Help us shape the future of Go! Take the 2026 Go Developer Survey

schema

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package schema models the payload types that normalisers and protocols share. Types are declared in TypeScript, so scripts and the host use one definition.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ProgramFiles added in v0.19.0

func ProgramFiles(sources map[string]string) map[string]string

ProgramFiles places sources where FromProgram and TypeName expect them.

func PropertyName added in v0.21.0

func PropertyName(name string) (property string)

PropertyName renders a JSON key as a TypeScript property name, quoting it unless it is an identifier.

func ReadSources added in v0.19.0

func ReadSources(declarations fs.FS) (map[string]string, error)

ReadSources reads every .ts file in declarations, keyed by slash-separated name. Symlinks are rejected because fs.FS has no portable root-confined open operation.

Types

type Config added in v0.12.0

type Config struct {
	// SchemaDir holds TypeScript declaration files, each declaring ambient modules.
	SchemaDir string `` /* 217-byte string literal not displayed */
}

Config selects the TypeScript declarations that make up the schema.

func NewConfig added in v0.12.0

func NewConfig() Config

NewConfig returns the default schema configuration.

func (Config) Validate added in v0.19.0

func (c Config) Validate() error

Validate checks that the schema configuration is usable.

type Field added in v0.19.0

type Field struct {
	// Name is the JSON key.
	Name string
	// Optional means the key may be absent. A present key never holds null.
	Optional bool
	// Value is the member's type.
	Value Value
}

Field is one member of an object type.

type Kind added in v0.19.0

type Kind string

Kind is the JSON shape of a value.

const (
	// KindString is a JSON string.
	KindString Kind = "string"
	// KindNumber is a JSON number, or one of its literals.
	KindNumber Kind = "number"
	// KindBoolean is a JSON boolean.
	KindBoolean Kind = "boolean"
	// KindEnum is a union of string literals.
	KindEnum Kind = "enum"
	// KindObject is a reference to a named object type.
	KindObject Kind = "object"
	// KindList is an array, written T[].
	KindList Kind = "list"
	// KindMap is an object with arbitrary string keys, written Record<string, T>.
	KindMap Kind = "map"
)

Kinds of the TypeScript type expressions in the supported subset.

type Operation added in v0.19.0

type Operation struct {
	// Name is the service's type name followed by the method name.
	Name string
	// Request names the request object type.
	Request TypeRef
	// Response names the response object type.
	Response TypeRef
}

Operation is one unary RPC method declared on a service interface.

type Schema

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

Schema indexes types and operations whose references all resolve. Treat types and their fields as immutable after construction, as comparison plans share them.

func FromProgram added in v0.19.0

func FromProgram(program *ts.Program, sources map[string]string) (*Schema, error)

FromProgram reads the schema sources declare in a checked program built from ProgramFiles(sources). A type's name is its module name and namespace path.

func New

func New(types []*Type, operations []Operation) (*Schema, error)

New takes ownership of types and validates their references. It rejects duplicate names and references to undeclared types.

func Parse added in v0.19.0

func Parse(ctx context.Context, declarations fs.FS) (*Schema, error)

Parse type-checks every .ts file in declarations and reads the schema they declare.

func ParseSources added in v0.19.0

func ParseSources(ctx context.Context, sources map[string]string) (*Schema, error)

ParseSources type-checks named sources on their own and reads the schema they declare.

func (*Schema) Operation added in v0.19.0

func (s *Schema) Operation(name string) (Operation, error)

Operation returns the named RPC method.

func (*Schema) Operations added in v0.19.0

func (s *Schema) Operations() []Operation

Operations returns every operation, sorted by name.

func (*Schema) Type added in v0.19.0

func (s *Schema) Type(name TypeRef) (*Type, error)

Type returns the named object type.

func (*Schema) Types added in v0.7.0

func (s *Schema) Types() []*Type

Types returns every object type, sorted by name.

func (*Schema) Validate added in v0.19.0

func (s *Schema) Validate(name TypeRef, value any) error

Validate checks that a decoded JSON value is an instance of the named type. It rejects unknown keys and nulls, so a valid payload holds only declared data.

type Type added in v0.19.0

type Type struct {
	// Name is the declaring module's name followed by the type's namespace path.
	Name TypeRef
	// Fields are in declaration order.
	Fields []Field
}

Type is a named object type, declared as an interface or an object type alias.

func (*Type) Field added in v0.19.0

func (t *Type) Field(name string) (field Field, found bool)

Field returns the member with the given JSON key.

type TypeRef added in v0.25.0

type TypeRef string

TypeRef names a schema type, e.g. "weather.service.GetWeatherRequest".

func TypeName added in v0.19.0

func TypeName(t *ts.Type) (TypeRef, error)

TypeName returns the schema name of a named object type, which is how scripts and the host refer to it. Types declared outside a schema module have no name.

type Value added in v0.19.0

type Value struct {
	// Kind is the value's JSON shape.
	Kind Kind
	// Literals are an enum's permitted strings, or strings a number also accepts, as
	// in ProtoJSON's non-finite floats and open enums. Their order is not significant.
	Literals []string
	// Element is the element type of a list or the value type of a map, and None otherwise.
	Element Option[*Value]
	// Type names an object's type, or the alias a literal union was declared with, if any.
	Type TypeRef
}

Value is one TypeScript type expression in the supported subset.

func (Value) Equal added in v0.19.0

func (v Value) Equal(other Value) bool

Equal reports whether two values accept the same JSON. Enum alias names are ignored, but object types must have the same name.

func (Value) Format added in v0.19.0

func (v Value) Format(reference func(name TypeRef) string) string

Format renders the value as TypeScript, naming each referenced type with reference.

func (Value) String added in v0.19.0

func (v Value) String() string

String renders the value as TypeScript, naming referenced types as they are stored.

Jump to

Keyboard shortcuts

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