thema

type Assignee any

type BindOption bindOption

type CUEWrapper interface {
	// Underlying returns the underlying cue.Value wrapped by the object.
	Underlying() cue.Value
}

type ConvergentLineage[T Assignee] interface {
	Lineage

	TypedSchema() TypedSchema[T]
}

type FieldRef struct {
	Path  string      `json:"path"`
	Value interface{} `json:"value"`
}

type ImperativeLens struct {
	To, From SyntacticVersion
	Mapper   func(inst *Instance, to Schema) (*Instance, error)
}

type Instance struct {
	// contains filtered or unexported fields
}

type Lacuna struct {
	// The field path(s) and their value(s) in the pre-translation instance
	// that are relevant to the lacuna.
	SourceFields []FieldRef `json:"sourceFields,omitempty"`

	// The field path(s) and their value(s) in the post-translation instance
	// that are relevant to the lacuna.
	TargetFields []FieldRef `json:"targetFields,omitempty"`
	Type         LacunaType `json:"type"`

	// A human-readable message describing the gap in translation.
	Message string `json:"message"`
}

type LacunaType uint16

type Lineage interface {
	CUEWrapper

	// Name returns the name of the object schematized by the lineage, as declared
	// in the lineage's `name` field.
	Name() string

	// ValidateAny checks that the provided data is valid with respect to at
	// least one of the schemas in the lineage. The oldest (smallest) schema against
	// which the data validates is chosen. A nil return indicates no validating
	// schema was found.
	//
	// While this method takes a cue.Value, this is only to avoid having to trigger
	// the translation internally; input values must be concrete. To use
	// incomplete CUE values with Thema schemas, prefer working directly in CUE,
	// or if you must, rely on Underlying().
	//
	// TODO should this instead be interface{} (ugh ugh wish Go had tagged unions) like FillPath?
	ValidateAny(data cue.Value) *Instance

	// Schema returns the schema identified by the provided version, if one exists.
	//
	// Only the [0, 0] schema is guaranteed to exist in all valid lineages.
	Schema(v SyntacticVersion) (Schema, error)

	// First returns the first Schema in the lineage (v0.0). Thema requires that all
	// valid lineages contain at least one schema, so this is guaranteed to exist.
	First() Schema

	// Latest returns the newest Schema in the lineage - largest minor version
	// within the largest major version.
	//
	// Thema requires that all valid lineages contain at least one schema, so schema
	// is is guaranteed to exist, even if it's the 0.0 version.
	//
	// EXERCISE CAUTION WITH THIS METHOD. Relying on Latest is appropriate and
	// necessary for some use cases, such as keeping Thema declarations and
	// generated code in sync within a single repository. But use in the wrong
	// context - usually cross repository, loosely coupled, dependency
	// management-like contexts - can completely undermine Thema's translatability
	// invariants.
	//
	// If you're not sure, ask yourself: when a breaking change to this lineage is
	// published, what would that break downstream, and will the users who experience
	// that breakage be expecting it to happen?
	//
	// If the user would be expecting the breakage, using Latest is probably appropriate.
	// Otherwise, it is probably preferable to pick an explicit version number.
	Latest() Schema

	// All returns all Schemas in the lineage. Thema requires that all valid lineages
	// contain at least one schema, so this is guaranteed to contain at least one element.
	All() []Schema

	// Runtime returns the thema.Runtime instance with which this lineage was built.
	Runtime() *Runtime
	// contains filtered or unexported methods
}

type Runtime struct {
	// contains filtered or unexported fields
}

type Schema interface {
	CUEWrapper

	// Validate checks that the provided data is valid with respect to the
	// schema. If valid, the data is wrapped in an [Instance] and returned.
	// Otherwise, a nil Instance is returned along with an error detailing the
	// validation failure.
	//
	// While Validate takes a cue.Value, this is only to avoid having to trigger
	// the translation internally; input values must be concrete. Behavior of
	// this method is undefined for incomplete values.
	//
	// The concreteness requirement may be loosened in future versions of Thema. To
	// use incomplete CUE values with Thema schemas, prefer working directly in CUE,
	// or call [Schema.Underlying] to work directly with the underlying CUE API.
	//
	// TODO should this instead be interface{} (ugh ugh wish Go had tagged unions) like FillPath?
	Validate(data cue.Value) (*Instance, error)

	// Successor returns the next schema in the lineage, or nil if it is the last schema.
	Successor() Schema

	// Predecessor returns the previous schema in the lineage, or nil if it is the first schema.
	Predecessor() Schema

	// LatestInMajor returns the Schema with the newest (largest) minor version
	// within this Schema's major version. If the receiver Schema is the latest, it
	// will return itself.
	LatestInMajor() Schema

	// Version returns the schema's version number.
	Version() SyntacticVersion

	// Lineage returns the lineage that contains this schema.
	Lineage() Lineage

	// Examples returns the set of examples of this schema defined in the original
	// lineage. The string key is the name given to the example.
	Examples() map[string]*Instance
	// contains filtered or unexported methods
}

type SyntacticVersion [2]uint

type TranslationLacunas interface {
	AsList() []Lacuna
}

type TypedInstance[T Assignee] struct {
	*Instance
	// contains filtered or unexported fields
}

type TypedSchema[T Assignee] interface {
	Schema

	// NewT returns a new instance of T, but with schema-specified defaults for its
	// field values instead of Go zero values. Fields without a schema-specified default
	// are populated with standard Go zero values.
	NewT() T

	// ValidateTyped performs validation identically to [Schema.Validate], but
	// returns a TypedInstance on success.
	ValidateTyped(data cue.Value) (*TypedInstance[T], error)

	// ConvergentLineage returns the ConvergentLineage that contains this schema.
	ConvergentLineage() ConvergentLineage[T]
}