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 GeneratePageSchema(pageFile, moduleRoot, modulePath string) ([]byte, error)
- func GenerateRouteSchema(route Route, packageName string, options Options) ([]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
- type Kind
- type Options
- type Prefetch
- type PrefetchImage
- type Route
- type Value
Constants ¶
const APIVersionV1Alpha1 = "gobeyond.contract/v1alpha1"
Variables ¶
This section is empty.
Functions ¶
func DecodeJSON ¶
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 ¶
Generate returns deterministic, go/format-formatted generated files keyed by slash-separated project-relative path. Generate never writes to disk.
func GeneratePageSchema ¶
GeneratePageSchema projects the authored Go Props type into the TypeScript contract consumed by the portable React compiler. The Go page package is the source of truth; the returned page.schema.ts is generated and must not be edited by application teams.
Imported application structs are followed when their import path is below modulePath. This deliberately refuses arbitrary external types: a page payload must have a visible, JSON-safe shape at the Go/browser boundary.
func GenerateRouteSchema ¶
GenerateRouteSchema projects one route contract into the route's authored Go package. The returned source is intended for page.schema.go: it gives route authors local Props and cache metadata without importing generated internals.
func TrustStaticSafeHTML ¶
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 ¶
Validate checks a programmatically constructed document using the same semantic restrictions as Decode.
func ValidateEncodedValue ¶
ValidateEncodedValue marshals a typed Go value and validates the JSON that would be delivered to the browser against schema.
func ValidateJSON ¶
ValidateJSON validates exactly one JSON value against schema. Object properties are closed: unknown properties are rejected at every depth.
Types ¶
type 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 generated/contracts.
OutputDir string
// SafeHTMLImportPath supplies the package containing SafeHTML. It defaults
// to the GoBeyond renderplan package.
SafeHTMLImportPath string
}
type Prefetch ¶
type Prefetch struct {
Data bool
Images []PrefetchImage
}
type Route ¶
type Route struct {
RouteID string
Props Value
// Revalidate is the origin props-ISR window declared by
// definePage({ revalidate }), in whole seconds. Zero means the route opted
// out. It is route metadata, not an HTTP cache directive: the edge
// Cache-Control for a response stays whatever gb.CachePolicy the loader
// returned.
Revalidate int
// Tags are the invalidation handles declared by definePage({ tags }).
Tags []string
Prefetch *Prefetch
}
Source Files