Documentation
¶
Overview ¶
Package typescript renders and publishes pure TypeScript clients from the shared manifest. Generated HTTP and realtime transports are injected.
Index ¶
Constants ¶
const MaxSurfaces = 64
MaxSurfaces bounds the client entries one export declares.
Variables ¶
This section is empty.
Functions ¶
func ExportCommand ¶
func ExportCommand(name cli.Name, api openapi.Options, sources Sources, surfaces ...Surface) (cli.Declaration, error)
ExportCommand declares an application command that builds the client contract from the running application's own registries and publishes the TypeScript SDK, manifest and OpenAPI into an existing directory:
app contracts:export --dir frontend/src/generated [--prefix contracts] [--check]
It replaces a hand-written manifest.Build/Generate command. The API title, version and servers come from api, and surfaces adds one client entry per portal. Check is read-only and fails on stale output. Building runs no handlers or external transports.
func Render ¶
Render returns one deterministic, dependency-free ES2022 TypeScript module with the runtime inlined. Generate publishes the same client as an entry module importing shared runtime modules. Runtime payload numbers never pass through JSON.parse. Wide integers and exact JSON numbers have decimal-string client values and exact numeric wire tokens; json,string continues to use the declared quoted wire format.
Types ¶
type Options ¶
type Options struct {
Dir string
Prefix string
Check bool
OpenAPI openapi.Options
// React and Vue emit optional subscription adapters as separate modules.
// They import their respective peer framework; the core SDK never does.
React bool
Vue bool
// Surfaces adds one client entry per declared surface beside the full one.
Surfaces []Surface
}
Options selects an existing output directory and stable file prefix. OpenAPI requires the application's title/version. Check is strictly read-only.
type Report ¶
type Report struct{ Written, Removed []string }
Report lists TypeScript output paths written and removed during generation.
func Generate ¶
Generate publishes the manifest, SDK and OpenAPI together. The SDK is the full entry <prefix>_foundry.gen.ts and one entry per surface, which import the shared runtime modules <prefix>_runtime_foundry.gen.ts and <prefix>_runtime_realtime_foundry.gen.ts. Obsolete owned artifacts are removed, edited/unowned files are refused, and an interrupted publication uses the same recovery journal as foundry generate.
type Sources ¶
Sources resolves the application's registered descriptors, such as its HTTP router and realtime description, when the export command runs.
type Surface ¶
type Surface struct {
Name string
Routes []foundryhttp.RouteID
Channels []websocket.ChannelID
Paths []string
Guards []auth.GuardName
Auth *SurfaceAuth
}
Surface declares one client entry, such as a portal, with the same API as the full SDK restricted to its operations and channels. Routes and Channels select IDs and their dotted namespaces, Paths selects routes below literal path prefixes such as "/api/admin", and Guards selects the channels declared for a guard (see manifest.Selection). It is published as <prefix>_<Name>_foundry.gen.ts, embedding only its projection of the manifest; the realtime runtime is imported only when it has channels.
type SurfaceAuth ¶ added in v0.3.0
type SurfaceAuth struct {
Guard auth.GuardName
Login foundryhttp.RouteID
Refresh foundryhttp.RouteID
Logout foundryhttp.RouteID
Profile foundryhttp.RouteID
Identifier string // Case-sensitive JSON property name of the login identifier (e.g. "email").
}
SurfaceAuth explicitly declares the routes and credentials of a portal's session guard. Every referenced route must be a valid registered endpoint. Identifier must exactly match a non-secret JSON property in the login body. Helpers supply only the login body: routes cannot require path/query inputs, signed URLs, idempotency keys, or bodies on refresh, logout and profile.
Source Files