codegen

package

v0.1.0-alpha.1 Latest Latest Go to latest Published: Jul 23, 2026 License: MIT Imports: 15 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Origens-Dev/gobeyond

Links

Open Source Insights

Documentation ¶

Overview ¶

Package codegen decodes GoBeyond value-contract documents and generates the Go types shared by page loaders and actions.

Generated object fields are emitted in lexical JSON-name order. Optional and nullable values use pointers. A schema marked both optional and nullable has the same Go representation as either flag alone, so absence and JSON null are intentionally collapsed in the MVP wire model.

The MVP supports unions only when every variant is a string literal or a string enum. Such unions become named string types with constants. Structural and mixed unions are rejected because encoding/json cannot decode them into a safe, unambiguous generated representation without an explicit discriminator contract.

Index ¶

Constants
func DecodeJSON(schema Value, data []byte, target any) error
func Generate(document Document, options Options) (map[string][]byte, error)
func TrustStaticSafeHTML(document Document, routeID string, props any) (any, error)
func Validate(document Document) error
func ValidateEncodedValue(schema Value, value any) error
func ValidateJSON(schema Value, data []byte) error
type Action
type Document
- func Decode(reader io.Reader) (Document, error)
- func Parse(data []byte) (Document, error)
type Kind
type Options
type Route
type Value

Constants ¶

View Source

const APIVersionV1Alpha1 = "gobeyond.contract/v1alpha1"

Variables ¶

This section is empty.

Functions ¶

func DecodeJSON ¶

func DecodeJSON(schema Value, data []byte, target any) error

DecodeJSON validates one JSON value against a generated value contract and then decodes it into target. Validation is schema-driven rather than based on Go reflection, so missing required properties and invalid enum values do not collapse into otherwise-valid Go zero values.

func Generate ¶

func Generate(document Document, options Options) (map[string][]byte, error)

Generate returns deterministic, go/format-formatted generated files keyed by slash-separated project-relative path. Generate never writes to disk.

func TrustStaticSafeHTML ¶

func TrustStaticSafeHTML(document Document, routeID string, props any) (any, error)

TrustStaticSafeHTML restores SafeHTML trust markers after build props have crossed the compiler's JSON protocol. The build artifact is trusted only after it has passed the frozen value contract.

func Validate ¶

func Validate(document Document) error

Validate checks a programmatically constructed document using the same semantic restrictions as Decode.

func ValidateEncodedValue ¶

func ValidateEncodedValue(schema Value, value any) error

ValidateEncodedValue marshals a typed Go value and validates the JSON that would be delivered to the browser against schema.

func ValidateJSON ¶

func ValidateJSON(schema Value, data []byte) error

ValidateJSON validates exactly one JSON value against schema. Object properties are closed: unknown properties are rejected at every depth.

Types ¶

type Action ¶

type Action struct {
	ActionID string
	Input    Value
	Output   Value
}

type Document ¶

type Document struct {
	APIVersion string
	Routes     []Route
	Actions    []Action
}

func Decode ¶

func Decode(reader io.Reader) (Document, error)

Decode strictly decodes and validates one value-contract JSON document. Unknown fields, trailing JSON, invalid kind-specific fields, duplicate IDs, and schemas that cannot be represented safely by the MVP generator fail.

func Parse ¶

func Parse(data []byte) (Document, error)

Parse strictly decodes one value-contract JSON document.

type Kind ¶

type Kind string

const (
	KindString   Kind = "string"
	KindNumber   Kind = "number"
	KindInteger  Kind = "integer"
	KindBoolean  Kind = "boolean"
	KindDateTime Kind = "datetime"
	KindBytes    Kind = "bytes"
	KindSafeHTML Kind = "safeHtml"
	KindLiteral  Kind = "literal"
	KindEnum     Kind = "enum"
	KindArray    Kind = "array"
	KindObject   Kind = "object"
	KindUnion    Kind = "union"
)

type Options ¶

type Options struct {
	// OutputDir is the slash-separated relative directory used as the root of
	// returned paths. It defaults to internal/gobeyondgen/contracts.
	OutputDir string
	// SafeHTMLImportPath supplies the package containing SafeHTML. It defaults
	// to the GoBeyond renderplan package.
	SafeHTMLImportPath string
}

type Route ¶

type Route struct {
	RouteID string
	Props   Value
}

type Value ¶

type Value struct {
	Kind     Kind
	Optional bool
	Nullable bool
	Literal  any
	Values   []string
	Items    *Value
	Shape    map[string]Value
	Variants []Value
}

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL