jsonshape

package
v0.0.0-...-779303e Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package jsonshape reads what the types of a gst project look like on the wire: the JSON encoding/json writes for them, which is the codec of the framework's response envelope and request binding. Every generator that describes the API in another language reads the shape from here -- the TypeScript declarations do -- so all of them describe one and the same shape.

Load type-checks the project packages the API's types are declared in, from source, and indexes their syntax for the doc comments and constants a description carries over. The Project it returns then answers, for any type reached from those packages, which keys a struct encodes to (Fields), which types decide their encoding through methods of their own (MarshalMethod), which named types are enums (Enum), and which values may be null or absent (Nullable, Nilable). A shape that cannot be read off a declaration is reported on the Project as a Diagnostic, at the position the project declares the subject.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComparePositions

func ComparePositions(fset *token.FileSet, a, b token.Pos) int

ComparePositions orders two positions of fset by file name and offset. Pos values alone do not order positions of different files: the loader adds files to the file set in whatever order it parses them.

func Nilable

func Nilable(t types.Type) bool

Nilable reports whether a value of t can be nil: a pointer, slice, map or interface, such as *string, []string or any, but not string. A request may leave such a field out, and a nil value reaches the client as null or not at all.

func Nullable

func Nullable(t types.Type) bool

Nullable reports whether a value of t may encode as null, as a *string, []string or map value may. Raw JSON and interface values are left out: their shape admits null already.

Types

type Builtin

type Builtin int

Builtin is the JSON shape of a type from outside the project whose encoding methods produce a known shape.

const (
	BuiltinString         Builtin = iota + 1 // a JSON string
	BuiltinNumber                            // a JSON number
	BuiltinAny                               // raw JSON of any shape, null included
	BuiltinObject                            // an object, or null for a nil map
	BuiltinNullableString                    // a string, or null when unset
	BuiltinWrapper                           // the encoding of the single type argument
)

func BuiltinOf

func BuiltinOf(n *types.Named) (Builtin, bool)

BuiltinOf reports the builtin shape of n, if it has one: BuiltinString for time.Time, and BuiltinWrapper for datatypes.JSONType[*Options] as for any other instantiation of datatypes.JSONType.

type Config

type Config struct {
	// Dir is the directory the Go packages are loaded from, normally the root
	// of the project module. Diagnostic file names are relative to it.
	Dir string
	// ModulePath is the import path prefix of the project packages: the ones
	// type-checked from source, whose types get descriptions of their own.
	ModulePath string
	// Roots are the import paths of the packages declaring the types the API
	// sends and receives. The project packages they reach are loaded.
	Roots []string
	// Overlay maps file paths, absolute or relative to Dir, to the contents
	// the load reads in place of the files on disk, the way a go build
	// overlay does: the generated files a run is about to rewrite, see
	// columns.InspectionOverlay.
	Overlay map[string][]byte
}

Config describes one load.

type Diagnostic

type Diagnostic struct {
	// Pos is where the project declares the subject, or uses the type from
	// outside the project a field belongs to. It is invalid for a subject
	// without a place of its own, such as a whole package.
	Pos token.Position
	// Subject is the Go path of the type or field, such as
	// example.com/app/model/sample.Sample.status.
	Subject string
	// Message tells why the subject cannot be described, and what to change.
	Message string
}

Diagnostic reports a Go type or field whose JSON shape cannot be described.

func (Diagnostic) String

func (d Diagnostic) String() string

String renders the diagnostic as "file:line: subject: message", as in

model/sample/sample.go:12: example.com/app/model/sample.class: class is reserved in TypeScript and cannot name a type; rename the Go type

or as "subject: message" for a diagnostic without a position.

type Enum

type Enum struct {
	// Values are the constants, one per distinct value, in source order.
	Values []EnumValue
	// Bitwise marks a bit set: a constant built with a bitwise operator means
	// any combination of the constants may appear, so the type is a number.
	Bitwise bool
	// CoversZero reports whether one of the constants has the zero value of
	// the type; otherwise a variable never assigned a constant holds a value
	// the constants do not list.
	CoversZero bool
}

Enum describes a named string or integer type of the project whose package declares constants of it. Its JSON values are those constants, and the zero value of a variable never assigned one.

type EnumValue

type EnumValue struct {
	Const *types.Const
	Doc   string
}

EnumValue is one constant of an enum type.

type Field

type Field struct {
	// Key is the JSON key.
	Key string
	// Var is the struct field the key comes from.
	Var *types.Var
	// Omit is set by the omitempty or omitzero tag option.
	Omit bool
	// Quoted is set by the string tag option on a field it applies to: the
	// value travels as a JSON string.
	Quoted bool
	// ViaPointer marks a key promoted through an embedded pointer, which a nil
	// pointer drops together with every other key of the embedded struct.
	ViaPointer bool
	// Tag is the struct tag of the field as written, for the options other
	// descriptions read off it, such as the pb tag numbering protobuf fields.
	Tag string
	// contains filtered or unexported fields
}

Field is one key of the JSON object a struct encodes to.

type Project

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

Project is a loaded project: its type-checked packages, the doc comments and constants read off their syntax, and the diagnostics of one description run over them. It serves that one run: the diagnostics it collects are the run's, and a generator reads them once its run is over.

func Load

func Load(cfg Config) (*Project, error)

Load type-checks the project packages the roots reach (see load) and indexes their syntax (see newSourceIndex).

func (*Project) CheckForeignConstants

func (p *Project) CheckForeignConstants()

CheckForeignConstants reports constants of an enum type declared outside the type's package, for every enum Enum described so far. The description of the type lists the constants of its own package only, so such a constant could send a value the description refuses.

func (*Project) CheckMapKey

func (p *Project) CheckMapKey(key types.Type, s Site) bool

CheckMapKey reports a map key type without a stable JSON encoding, and returns whether it did. Keys of string and integer types encode as strings; a key type with text marshal methods is keyed differently with and without the JSON v2 experiment.

func (*Project) Declares

func (p *Project) Declares(obj *types.TypeName) bool

Declares reports whether obj gets a description of its own: a type declared at package scope in a project package.

func (*Project) Diagnostics

func (p *Project) Diagnostics() []Diagnostic

Diagnostics returns the diagnostics reported so far, ordered by position, then by subject and message.

func (*Project) Enum

func (p *Project) Enum(obj *types.TypeName) *Enum

Enum returns the enum description of obj, or nil when obj is no enum type: an alias, a type from outside the project, a type that is not a string or integer, one with an encoding method of its own, or one whose package declares no constant of it.

func (*Project) FieldDoc

func (p *Project) FieldDoc(v *types.Var) string

FieldDoc returns the doc comment of a project struct field, or its trailing comment when it has none. A field of a type from outside the project has none.

func (*Project) FieldSite

func (p *Project) FieldSite(s Site, name string, f *types.Var) Site

FieldSite locates a field of the type at s. The field's own position is used when the project declares it; a field of a type from outside the project is reported where the project uses that type.

func (*Project) Fields

func (p *Project) Fields(st *types.Struct, s Site) []Field

Fields resolves the keys of the JSON object st encodes to, the way encoding/json resolves them: the fields of embedded structs are promoted breadth first; a key defined at several depths belongs to the shallowest field; a tie at one depth goes to the only tagged field and otherwise drops the key; keys keep the order of the fields they come from. So a model embedding model.Base first encodes to id, created_by, updated_by, created_at and updated_at, then to the keys of its own fields. A json tag that encoding/json and the JSON v2 experiment read differently is reported at the field's site (see FieldSite), and so is an unexported struct embedded through a pointer, which a request carrying its keys fails to decode into.

func (*Project) FileSet

func (p *Project) FileSet() *token.FileSet

FileSet returns the file set the packages were loaded into, which the positions of their syntax and types resolve against.

func (*Project) IsByteSlice

func (p *Project) IsByteSlice(s *types.Slice) bool

IsByteSlice reports whether encoding/json encodes s as a base64 string: a slice of bytes whose element type has no marshal methods.

func (*Project) MarshalMethod

func (p *Project) MarshalMethod(t types.Type) string

MarshalMethod returns the method through which t writes its own JSON (see jsonMarshalMethods), or "" when t encodes by its structure or as text (see TextMethod).

func (*Project) Package

func (p *Project) Package(pkgPath string) *packages.Package

Package returns the project package at pkgPath, or nil for an import path that names no project package.

func (*Project) RelativeFile

func (p *Project) RelativeFile(file string) string

RelativeFile returns the name of file relative to the directory the packages were loaded from, or file itself when it lies outside. File names come from the loader, with symbolic links resolved on both sides.

func (*Project) Report

func (p *Project) Report(s Site, format string, args ...any)

Report records a diagnostic at s, once: a second report of the same text is dropped. The file name of the position is made relative to the directory the packages were loaded from.

func (*Project) TextMethod

func (p *Project) TextMethod(t types.Type) string

TextMethod returns the method through which t writes the text it encodes to as a JSON string, MarshalText or AppendText, when it declares no JSON method, or "" otherwise: a netip.Addr encodes to "10.0.0.1", which a generator describes as a string, and a type with a JSON method encodes whatever that method writes.

func (*Project) TypeDoc

func (p *Project) TypeDoc(obj *types.TypeName) string

TypeDoc returns the doc comment of a project type, picked the way the OpenAPI document picks it: the type's own comment, or that of its declaration group. A type from outside the project has none.

type Site

type Site struct {
	// Subject is the Go path of the type or field, such as
	// example.com/app/model/sample.Sample.status.
	Subject string
	// Pos is where the project declares the subject, or uses the type from
	// outside the project a field belongs to. It is invalid for a subject
	// without a place of its own, such as a whole package.
	Pos token.Pos
}

Site locates the subject of a diagnostic.

Directories

Path Synopsis
fixture
a-b
Package ab lives in a directory whose name maps to the same TypeScript import name as the a_b fixture package.
Package ab lives in a directory whose name maps to the same TypeScript import name as the a_b fixture package.
a_b
Package ab lives in a directory whose name maps to the same TypeScript import name as the a-b fixture package.
Package ab lives in a directory whose name maps to the same TypeScript import name as the a-b fixture package.
gst
Package gst sits where its output file would be gst.ts, the name of the framework prelude.
Package gst sits where its output file would be gst.ts, the name of the framework prelude.
mode
Package mode declares an enum type another fixture package declares a further constant of.
Package mode declares an enum type another fixture package declares a further constant of.
model/record
Package record declares fixture types the sample fixture refers to from another package.
Package record declares fixture types the sample fixture refers to from another package.
model/sample
Package sample declares the fixture types the TypeScript generator tests start from.
Package sample declares the fixture types the TypeScript generator tests start from.
pkg/notifier
Package notifier declares a fixture type a model refers to from outside the model directory.
Package notifier declares a fixture type a model refers to from outside the model directory.
unsupported
Package unsupported declares fixture types whose JSON shape the TypeScript generator cannot describe.
Package unsupported declares fixture types whose JSON shape the TypeScript generator cannot describe.

Jump to

Keyboard shortcuts

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