fundamentals

README

Fundamentals for Go

The Go counterpart of Cratis Fundamentals: shared domain-value primitives for Arc.Go and Chronicle.Go. Instead of each framework defining incompatible values and codecs, Fundamentals.Go provides one small, standard-library-only foundation. It must never import either framework.

Status

This documentation targets v0.3.0; the API remains experimental. See release status for publication details. Start with a UUID-backed domain value and a JSON round trip. You need only Go: no server, container or C# knowledge.

• Scalars and concepts: concepts supplies UUID, DateOnly, TimeOnly, TimeSpan, explicit domain codecs, Underlying and CheckJSON; concepts/conceptstypes adds compile-time recognition.
• Correlation context and naming policies: shared metadata and explicit casing, without choosing product policies.
• Optional dependency injection: exact typed bindings, a default container, constructor planning and test-only conformance suites. Plain constructors need none of it.
• Ecosystem recipes: compiled, unpublished examples in a separate module; the released root stays standard-library-only.

The documentation overview covers every public package. Beginning with v0.3.0, concepts.ParseDotNetGUID provides opt-in .NET 10.0.12 compatibility conversion; strict UUID defaults remain unchanged. The parity map records remaining C# gaps. Enum and dictionary-key contract fixtures are source-distributed evidence, not Go codecs, runtime or schema support.

Releases remain v0.x while the API is experimental; a minor version may contain breaking changes, with migration notes.

Installation

Requires Go 1.26 or later. Install the v0.3.0 compatibility release:

go get github.com/cratis/fundamentals.go@v0.3.0

Use the lowercase module path exactly as shown. CI checks Go 1.26 and 1.27 with GOWORK=off and GOTOOLCHAIN=local.

Development

From the repository root:

export GOWORK=off
export GOTOOLCHAIN=local
go build ./...
go vet ./...
go test -race -count=1 -timeout=3m ./...
golangci-lint run

The root commands exclude the nested, unpublished recipes/ module; run its gates separately as described in the contribution guide.

See the contribution guide for the full checks and release conventions, and the documentation overview for scope and limitations.

Community and security

• Cratis and the Cratis repositories
• Private vulnerability reporting

License

MIT.

Documentation

Overview

Package fundamentals is the root of the Go counterpart of Cratis Fundamentals.

Package concepts provides the shared UUID and temporal wire scalars and the typed concept contract; package correlation shares correlation IDs through context.Context; package dependencyinjection provides an optional dependency-injection contract and default container. Documentation/parity.md records the remaining gaps.

Example (CorrelationPropagation)

package main

import (
	"context"
	"fmt"

	"github.com/cratis/fundamentals.go/concepts"
	"github.com/cratis/fundamentals.go/correlation"
)

func main() {
	id, err := concepts.ParseUUID("00112233-4455-6677-8899-aabbccddeeff")
	if err != nil {
		panic(err)
	}
	operation, cancel := context.WithCancel(context.Background())
	defer cancel()
	ctx := correlation.WithID(operation, id)
	// Pass ctx to the next operation; the parent remains unchanged.
	fmt.Println("save author:", correlation.FromContext(ctx))
	fmt.Println("parent unset:", correlation.FromContext(operation).IsZero())
	cleared := correlation.WithID(ctx, correlation.ID{})
	fmt.Println("child unset:", correlation.FromContext(cleared).IsZero())
	cancel()
	fmt.Println("canceled:", cleared.Err() == context.Canceled)
}

Output:
save author: 00112233-4455-6677-8899-aabbccddeeff
parent unset: true
child unset: true
canceled: true

Example (DomainRoundTrip)

package main

import (
	"encoding/json"
	"fmt"

	"github.com/cratis/fundamentals.go/concepts"
)

// AuthorID identifies an author without making arbitrary UUIDs interchangeable.
type AuthorID concepts.UUID

func (id AuthorID) ConceptValue() concepts.UUID  { return concepts.UUID(id) }
func (id AuthorID) MarshalText() ([]byte, error) { return concepts.UUID(id).MarshalText() }
func (id AuthorID) MarshalJSON() ([]byte, error) { return concepts.UUID(id).MarshalJSON() }
func (id *AuthorID) UnmarshalText(data []byte) error {
	return (*concepts.UUID)(id).UnmarshalText(data)
}
func (id *AuthorID) UnmarshalJSON(data []byte) error {
	return (*concepts.UUID)(id).UnmarshalJSON(data)
}

func main() {
	id, err := concepts.ParseUUID("00112233-4455-6677-8899-AABBCCDDEEFF")
	if err != nil {
		panic(err)
	}
	type author struct {
		ID   AuthorID `json:"id"`
		Name string   `json:"name"`
	}
	original := author{ID: AuthorID(id), Name: "Ada"}
	data, err := json.Marshal(original)
	if err != nil {
		panic(err)
	}
	var restored author
	if err := json.Unmarshal(data, &restored); err != nil {
		panic(err)
	}
	fmt.Println(string(data))
	fmt.Println("same author:", restored == original)
}

Output:
{"id":"00112233-4455-6677-8899-aabbccddeeff","name":"Ada"}
same author: true