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 ¶
- func ComparePositions(fset *token.FileSet, a, b token.Pos) int
- func Nilable(t types.Type) bool
- func Nullable(t types.Type) bool
- type Builtin
- type Config
- type Diagnostic
- type Enum
- type EnumValue
- type Field
- type Project
- func (p *Project) CheckForeignConstants()
- func (p *Project) CheckMapKey(key types.Type, s Site) bool
- func (p *Project) Declares(obj *types.TypeName) bool
- func (p *Project) Diagnostics() []Diagnostic
- func (p *Project) Enum(obj *types.TypeName) *Enum
- func (p *Project) FieldDoc(v *types.Var) string
- func (p *Project) FieldSite(s Site, name string, f *types.Var) Site
- func (p *Project) Fields(st *types.Struct, s Site) []Field
- func (p *Project) FileSet() *token.FileSet
- func (p *Project) IsByteSlice(s *types.Slice) bool
- func (p *Project) MarshalMethod(t types.Type) string
- func (p *Project) Package(pkgPath string) *packages.Package
- func (p *Project) RelativeFile(file string) string
- func (p *Project) Report(s Site, format string, args ...any)
- func (p *Project) TextMethod(t types.Type) string
- func (p *Project) TypeDoc(obj *types.TypeName) string
- type Site
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComparePositions ¶
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.
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 )
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 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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
FileSet returns the file set the packages were loaded into, which the positions of their syntax and types resolve against.
func (*Project) IsByteSlice ¶
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 ¶
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 ¶
Package returns the project package at pkgPath, or nil for an import path that names no project package.
func (*Project) RelativeFile ¶
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 ¶
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 ¶
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.
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. |