Codegen: typed client, resource typings, and WarpDrive schema generation from the resource registry

[evoactivity]

Motivation

Real-world evidence from an app using this package alongside tuyau's generated client registry: tuyau's types are wrong or vacuous for every JSON:API endpoint, through no fault of its own — it lacks the information.

• Request bodies are actively wrong. Tuyau infers from vine validators, but the JSON:API pattern validates post-deserialization attributes (request.validateUsing(v, { data: input.attributes })). Tuyau therefore emits the flat internal shape with internal attribute names (e.g. { name, type }) while the endpoint requires the envelope with wire names ({ data: { type: 'libraries', attributes: { name, libraryType } } }).
• Responses are vacuous. Controller return types are the wide Document union; per-resource attribute shapes only exist at runtime in the registry, so every endpoint types identically and clients narrow by hand.
• Error shapes are wrong. Tuyau declares vine's { errors: SimpleError[] } for 422s, but renderJsonApiError emits JSON:API error documents.

This package is the source of truth for everything tuyau is missing: the resource registry (model ↔ resource ↔ type name), Lucid column metadata including serializeAs wire names, relationship definitions with cardinality, declared filters, route registration per resource, the deserializer (request contract), the document builder (response contract), and the error renderer (error contract). It can generate what tuyau structurally cannot.

Proposed artifacts (phased)

Phase 1: resource typings + document types

• Per-resource interfaces generated from the registry: attributes (wire names, TS types reflected type-level from the model via ModelAttributes-style indirection so generated code cannot drift), relationships with cardinality and related type names.
• Per-endpoint document types: SingleDocument<T> / CollectionDocument<T>, request documents for store/update (envelope-aware, wire names, to-one → linkage not FK), and the real error document type.
• Include-aware narrowing: valid include paths derived from exposed relationships as template-literal types ('plugins' | 'plugins.library' | ...), with included unions computed from the requested paths.
• Enabler: tighten JsonApiResource.pick to pick<K extends keyof Serialized>(names: K[]): Pick<Serialized, K> so ReturnType<resource['attributes']> is exact for customized resources; the default derivation is already deterministic from Lucid metadata. Conditional attributes (e.g. a create-only plaintext token) surface as optional fields; document annotating attributes() return types for these.

Phase 2: typed fetch client

• Tuyau-style generated client keyed by registered resources/actions: api.libraries.index({ include, filter, sort, page }) with filters typed from declared FilterHandlers, include paths compile-checked, responses narrowed by the include argument, and errorResponse as JSON:API error documents.
• Generation as an assembler hook (like tuyau's generateRegistry) or an ace command; needs the booted registry, not static analysis.

Phase 3: WarpDrive schema emission

• Registry → WarpDrive ResourceSchema modules: { identity, fields: [{ kind: 'attribute' | 'relationship', name, type, options }] }, cardinality mapped to relationship kinds, wire names respected.
• Paired Type-branded TS interfaces for SchemaRecord, so an Ember app registers generated schemas instead of hand-maintaining models that drift from the server.

Design notes

• Heterogeneous/mixed collections (multiple resource types in one document) need union document types.
• Non-JSON:API endpoints (auth token exchanges etc.) are explicitly out of scope; they are the one place tuyau-style validator inference is actually correct.
• Route-group awareness (e.g. /api/v1 vs /api/v2 mounting) should follow the same route-name namespacing the LinkBuilder already uses.
• Emission target: a configurable output directory the host app can re-export (the consuming monorepo currently exports .adonisjs/client artifacts to sibling apps; this would replace that role for JSON:API surfaces).

[evoactivity]

Amendment: user-selectable generation targets

Generation should be opt-in per artifact through config (e.g. a codegen block in config/jsonapi.ts), not all-or-nothing. Targets compose:

codegen: {
  outDir: './.adonisjs/jsonapi',
  targets: ['types', 'client'],          // or ['warpdrive']
}

types (the baseline). Types that map to the JSON:API document structure properly: per-resource attribute/relationship interfaces, resource objects, single/collection documents, request documents for create/update, error documents. No client, no framework assumptions — useful to any consumer on any stack.

client. A JS client that follows JSON:API conventions end to end, built on the types target: per-resource actions honouring the registered routes, include/fields/sort/page/filter params typed and serialized per spec, responses narrowed by include paths, relationship endpoints where registered.

warpdrive. Schemas and types only — a WarpDrive app brings its own request layer, so no client is generated. Two type variants per resource, matching WarpDrive's immutability model:

• a readonly variant typing the default immutable SchemaRecord (all fields readonly, relationships as readonly references)
• an editable variant typing the checkout()-ed working copy (mutable attributes; identity/type still readonly)

Both carry the Type brand so store.request(...) and checkout() resolve to the right shapes. Schema modules emit the ResourceSchema field arrays with wire names and relationship cardinality from the registry.

Targets share one internal model of the registry, so warpdrive and types agree on names and shapes when both are enabled.

[evoactivity]

Cross-reference: OpenAPI 3 / Scalar generation (ektotv/monorepo#70)

A spike in a consuming app (ektotv/monorepo#70, branch spike/openapi-scalar) landed on the same conclusion this issue is built around: the resource registry is the source of truth, and the JSON:API document / attribute / relationship / request / error shapes should be generated from it rather than hand-declared.

An OpenAPI (JSON Schema) emission target fits naturally alongside the types / client / warpdrive targets in the amendment's codegen.targets model, it is the same internal registry model, emitted as OpenAPI components.schemas instead of TS interfaces. Since the package also owns route registration, it could optionally emit the paths (operations plus filter[...] / include / sort / page[...] query params derived from the declared filters and exposed relationships) for the registered resources too.

Composition with non-JSON:API routes

Consuming apps have routes this package does not power (auth token exchanges, RPC command endpoints, health, etc.), which this issue already scopes out as the place vine inference is correct. That composes cleanly for OpenAPI:

• Documents merge, paths are disjoint and schema names namespaced, so the app assembles a union: library-generated schemas on the JSON:API operations, vine/decorator-derived schemas on the rest.
• Attribution is per-operation, not per-controller, so a mixed controller (REST actions + RPC actions on the same resource, e.g. a bindings controller with a sync action) works: each path+method draws from the right source.

So the library would own the JSON:API schemas (the hard, currently-wrong part), and the app owns discovery, the non-JSON:API endpoints, security, the application/vnd.api+json media type, the Scalar UI, and any app-only concerns like a role-aware client/admin attribute split (which is runtime and invisible to static generation).

Noting here so the openapi target is considered as part of the shared registry model rather than re-implemented per app.