@haddowg/json-api-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gregory Haddow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# @haddowg/json-api-client
+
+> **Part of the [jsonapi.rest](https://jsonapi.rest) suite** — a complete, spec-compliant
+> JSON:API 1.1 stack: a framework-agnostic PHP [core](https://github.com/haddowg/json-api), a
+> [Symfony bundle](https://github.com/haddowg/json-api-symfony), a
+> [Laravel package](https://github.com/haddowg/json-api-laravel), and this **typed TypeScript
+> client**, bound together by one conformance-tested OpenAPI 3.1 contract.
+> Full documentation: **[haddowg.github.io/json-api-ts](https://haddowg.github.io/json-api-ts/)**.
+
+The generic, framework-agnostic runtime for a typesafe JSON:API client. Parameterised by a
+descriptor emitted by [`@haddowg/json-api-codegen`](../codegen) — the codegen reads your API's
+OpenAPI document; this package does the de/serialisation, hydration, and the fluent surface.
+
+Works standalone (`await client.albums.list()` needs no framework). For TanStack Query caching +
+normalization, add [`@haddowg/json-api-query`](../query).
+
+## Install
+
+```bash
+pnpm add @haddowg/json-api-client
+```
+
+You generally don't construct the client from this package directly — the generated module
+re-exports a descriptor-bound `createClient`. The snippets below assume that generated
+`createClient` (see the [codegen docs](../codegen)).
+
+## Creating a client
+
+```ts
+import { createClient } from './api/music.gen'
+
+const client = createClient({
+  baseUrl: 'https://music.example',
+  // transport?: defaults to the global `fetch` adapter when omitted
+  // headers?: per-request header provider (e.g. bearer auth); may be async
+  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+})
+```
+
+`ClientOptions`:
+
+| Option      | Type                                        | Notes                                                        |
+| ----------- | ------------------------------------------- | ------------------------------------------------------------ |
+| `baseUrl`   | `string`                                    | Base URL the generated path templates resolve against.       |
+| `transport` | `(req) => Promise<res>`                     | The transport seam; defaults to a `fetch` adapter.           |
+| `headers`   | `() => HeadersInit \| Promise<HeadersInit>` | Per-request header provider (bearer auth, etc.).             |
+| `atomic`    | `AtomicDescriptor \| null`                  | Atomic endpoint; the generated `createClient` threads it in. |
+| `validate`  | `ValidationOption`                          | Opt-in per-field validation seam (off by default).           |
+
+## Reads
+
+A resource read returns a **materialised** value: attributes and `type`/`id` are flat, enumerable
+props (clean to spread / `JSON.stringify`); the envelope hangs off non-enumerable `$`-accessors.
+
+### List a collection — filter / sort / include / fields / page
+
+```ts
+const albums = await client.albums.list({
+  filter: { status: 'released' },
+  sort: '-releasedAt',
+  include: ['artist'], // widens `artist` to a hydrated resource in the result type
+  fields: { albums: ['title', 'status', 'artist'] }, // sparse — other attrs are statically absent
+  page: { number: 1 },
+})
+
+albums[0]!.title // string
+albums[0]!.artist?.name // hydrated artist resource (its attributes are typed)
+albums.$page.kind // 'page' | 'offset' | 'cursor' | 'none'
+albums.$meta?.['page'] // raw top-level meta
+```
+
+> A relation kept in `include` must also stay in the `fields` set for that type, or it is narrowed
+> off the result type.
+
+### Get one — with a hydrated compound document
+
+```ts
+const ok = await client.albums.get('1', { include: ['artist', 'tracks'] })
+
+ok.title // string
+ok.$self // resource-level self link (non-enumerable)
+ok.tracks // the to-many `tracks` is a hydrated augmented array of track resources
+```
+
+### Resource-level `$`-accessors
+
+A materialised resource carries (all non-enumerable):
+
+- `$meta` — resource-level meta
+- `$links` / `$self` — resource-level links (`$self` is the `self` link shorthand)
+- `$document` — the shared, trimmed top-level `{ jsonapi, meta, links }`
+- `$raw` — the original JSON:API resource object (escape hatch)
+- `$rel(name)` — `{ data, links, meta }` for a relation (links-only relations + introspection)
+
+### Follow a relationship
+
+```ts
+// The related RESOURCES (full objects): GET /albums/1/tracks
+const tracks = await client.albums
+  .id('1')
+  .rel('tracks')
+  .related({ page: { size: 2 } })
+tracks.map((t) => t.title)
+tracks.$page.kind
+
+// The LINKAGE (resource identifiers): GET /albums/1/relationships/tracks
+const linkage = await client.albums.id('1').rel('tracks').get()
+```
+
+### Pivot data on a many-to-many edge
+
+Each member of a `belongsToMany` to-many carries its per-edge pivot under `$pivot` (typed sugar
+over `meta.pivot`); the same resource in another parent carries a different pivot.
+
+```ts
+const ordered = await client.playlists.id(playlistId).rel('orderedTracks').related()
+ordered[0]!.$pivot?.['position'] // edge-local pivot data
+```
+
+### `withCount` (the Countable profile)
+
+`withCount` is constrained to the type's count tokens and only available on `list` / related
+reads (no single-`get` endpoint advertises it). The client negotiates the Countable profile in
+`Accept` automatically when `withCount` is present.
+
+```ts
+const albums = await client.albums.list({ withCount: ['tracks'] })
+```
+
+### Pagination & cursor
+
+All three collection surfaces (top-level lists, related collections, to-many relationship arrays)
+expose the same `$page` + `$next()` / `$prev()`. Navigation is **count-free-safe** — driven by
+link presence, not a total. Cursor pagination is just a paginator `kind`; page with
+`page[cursor]` / `page[size]` query params and walk it with `$next()`:
+
+```ts
+let page = await client.tracks.list({ page: { size: 50 } })
+while (page) {
+  for (const track of page) {
+    /* … */
+  }
+  page = await page.$next() // undefined when there is no next link
+}
+```
+
+## Writes
+
+Flat ergonomic input — the client builds the JSON:API document. Create / update return the
+materialised resource; delete resolves `void`.
+
+```ts
+// POST /albums — `id` is required/optional/forbidden per the spec's per-type policy.
+const created = await client.albums.create({ title: 'Kid A', status: 'released' })
+
+// PATCH /albums/1 — a partial patch.
+const updated = await client.albums.id('1').update({ title: 'OK Computer (Remaster)' })
+
+// DELETE /albums/1 — resolves void (a 204).
+await client.albums.id('1').delete()
+```
+
+Create / update accept an optional second arg `{ include?, fields? }` to shape the materialised
+response, exactly like a read.
+
+### Relationship mutation
+
+A to-many relation exposes `add` / `remove` / `replace`; a to-one exposes `set(ref | null)`. A
+verb is present only when the relation's endpoint advertises it (the descriptor's per-relation
+`mutations` flags, derived from the bundle's `cannotAdd` / `cannotRemove` / `cannotReplace` +
+endpoint exposure) — a forbidden verb is a compile error, not a runtime surprise.
+
+```ts
+// to-many: POST / DELETE / PATCH .../relationships/tracks
+await client.albums
+  .id('1')
+  .rel('tracks')
+  .add([{ type: 'tracks', id: '4' }])
+await client.albums
+  .id('1')
+  .rel('tracks')
+  .remove([{ type: 'tracks', id: '4' }])
+await client.albums
+  .id('1')
+  .rel('tracks')
+  .replace([
+    { type: 'tracks', id: '1' },
+    { type: 'tracks', id: '3' },
+  ])
+
+// to-one: PATCH .../relationships/artist
+await client.albums.id('1').rel('artist').set({ type: 'artists', id: '2' })
+await client.albums.id('1').rel('artist').set(null) // clear
+```
+
+> **Verb / relation collision:** relations are reachable via `.rel('name')` (and, for the common
+> case, by name directly off the handle). A relation named like a reserved verb (`get`, `update`,
+> `delete`, `actions`, …) is shadowed — the codegen warns at build time and you reach it via
+> `.rel('name')`.
+
+## Custom actions
+
+Actions are reached via `.actions.<name>`: collection-scoped off the type accessor, resource-scoped
+off a handle (`.id(id)`). The body shape follows the action's declared `input`
+(`none` / `document` / `raw`); a `document` output is materialised, a `none` output resolves
+`undefined`.
+
+```ts
+// Resource-scoped, document in / document out.
+const reissued = await client.albums.id('1').actions.reissue({
+  data: { type: 'albums', attributes: { title: 'OK Computer' } },
+})
+
+// Collection-scoped, no input.
+const summary = await client.albums.actions.summary()
+```
+
+## Atomic operations
+
+`client.atomic(tx => …)` records ops in order and posts them as one all-or-nothing batch (the
+atomic ext media type). A `tx.create(...)` handle **doubles as a `lid` ref**, so a just-created
+resource wires into later ops without a server id. Results are typed positionally by op index.
+
+```ts
+const [artist, geogaddi] = await client.atomic((tx) => {
+  const newArtist = tx.create({ type: 'artists', name: 'Boards of Canada' })
+  const newAlbum = tx.create({ type: 'albums', title: 'Geogaddi', artist: newArtist })
+  return [newArtist, newAlbum] as const
+})
+
+artist.data.id // '99'
+geogaddi.data.title // 'Geogaddi'
+```
+
+`tx` also exposes `tx.update({ type, id, …fields })` and `tx.delete({ type, id } | ref)`. Calling
+`client.atomic` on a server that exposes no atomic endpoint throws.
+
+## Errors
+
+A non-2xx throws a typed `JsonApiError` carrying `status` + `errors: JsonApiErrorObject[]`, with
+expressive status matchers and pointer grouping:
+
+```ts
+import type { JsonApiError } from '@haddowg/json-api-client'
+
+try {
+  await client.albums.create({ title: '' })
+} catch (e) {
+  const error = e as JsonApiError
+  error.isUnprocessable() // 422 (alias: isValidationError())
+  // Server pointers (`/data/attributes/title`) are remapped to your FLAT input path (`title`).
+  error.byPath()['title']?.[0]?.detail // 'must not be blank'
+}
+```
+
+Status matchers: `hasStatus(n)`, `is4xx()`, `is5xx()`, `isBadRequest()` /400,
+`isUnauthorized()` /401, `isForbidden()` /403, `isNotFound()` /404, `isNotAcceptable()` /406,
+`isConflict()` /409, `isUnsupportedMediaType()` /415, `isUnprocessable()` /
+`isValidationError()` /422, `isRateLimited()` /429.
+
+`byPath()` groups errors by the flat input path (falling back to the raw pointer, then the query
+`parameter`) — the payoff for form/validation UX. Each error keeps its raw `source.pointer` as an
+escape hatch; atomic errors also carry an `opIndex`.
+
+> A response that parses but violates the JSON:API envelope shape (not a document, a member
+> missing `type`/`id`) throws a `StructuralGuardError` — distinct from a server-reported
+> `JsonApiError`. These light structural guards are always on; full per-field validation is opt-in
+> (below).
+
+## Transport
+
+The transport is a tiny `fetch`-shaped function, so any impl (native `fetch`, undici, an axios
+adapter, or a test mock) drops in:
+
+```ts
+import type {
+  JsonApiTransport,
+  TransportRequest,
+  TransportResponse,
+} from '@haddowg/json-api-client'
+
+const transport: JsonApiTransport = async (req: TransportRequest): Promise<TransportResponse> => {
+  const res = await myHttpLib(req.method, req.url, { headers: req.headers, body: req.body })
+  return { status: res.status, headers: res.headers, body: res.text }
+}
+
+const client = createClient({ baseUrl: 'https://music.example', transport })
+```
+
+Retries are deliberately out of scope here — the transport (or the TanStack layer) owns them.
+
+## Opt-in validation
+
+The core runtime trusts the wire (you own both ends; the envelope is invariant) and only runs the
+light structural guards. Full per-field validation is **opt-in** via the `validate?` option, fed by
+the codegen-emitted per-type `schemas` map. The validation engine is brought by you, never in the
+core dep tree.
+
+### With the bundled ajv adapter
+
+`ajv` is an optional peer dependency; the adapter lives at the `@haddowg/json-api-client/ajv`
+sub-path, so importing the main entry never pulls ajv in.
+
+```bash
+pnpm add ajv
+```
+
+```ts
+import Ajv2020 from 'ajv/dist/2020'
+import { createClient } from './api/music.gen'
+import { createAjvValidator } from '@haddowg/json-api-client/ajv'
+import { schemas } from './api/music.schemas.gen' // the codegen's `--schemas` output
+
+// The bundle emits JSON Schema 2020-12, so use `Ajv2020`. `strict: false` tolerates the
+// schemas' `x-enum-*` annotations; `allErrors` aggregates every failing field.
+const ajv = new Ajv2020({ allErrors: true, strict: false, validateFormats: false })
+
+const client = createClient({
+  baseUrl: 'https://music.example',
+  validate: createAjvValidator(ajv, schemas),
+})
+```
+
+Every wire resource is now validated against `schemas[type]`; a type the bundle does not cover is
+skipped (graceful partial coverage). A failure throws an `AjvValidationError` carrying every
+failing `{ type, id?, pointer, keyword, message }`.
+
+### With your own engine
+
+`validate` also accepts the schema-driven config `{ schemas, validator }` or a bare
+`(resource, schema) => void` validator that owns its own schema lookup:
+
+```ts
+const client = createClient({
+  baseUrl: 'https://music.example',
+  validate: (resource) => {
+    // throw on an invalid resource; return for a valid one
+  },
+})
+```
+
+## License
+
+MIT

package/dist/ajv.cjs

@@ -0,0 +1,62 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/ajv.ts
+/**
+* Thrown by the ajv adapter when a wire resource fails its per-type schema. Aggregates every
+* ajv error into {@link AjvValidationFailure}s (one per failing field) and renders a message
+* listing the failing pointers, so a caller can both read the summary and walk `failures`.
+*/
+var AjvValidationError = class extends Error {
+	/** Every failing field across the resource (ajv runs with `allErrors`-aware reporting if enabled). */
+	failures;
+	/** The JSON:API type of the resource that failed. */
+	type;
+	/** The id of the resource that failed, when present. */
+	resourceId;
+	constructor(type, id, failures) {
+		const at = id === void 0 ? type : `${type}:${id}`;
+		const pointers = failures.map((f) => `${f.pointer || "/"} ${f.message}`).join("; ");
+		super(`Resource ${at} failed schema validation: ${pointers}`);
+		this.name = "AjvValidationError";
+		this.type = type;
+		if (id !== void 0) this.resourceId = id;
+		this.failures = failures;
+	}
+};
+/** Map ajv's raw `ErrorObject`s for one resource to the adapter's typed failures. */
+function toFailures(type, id, errors) {
+	return errors.map((e) => {
+		const failure = {
+			type,
+			pointer: e.instancePath,
+			keyword: e.keyword,
+			message: e.message ?? "is invalid"
+		};
+		if (id !== void 0) failure.id = id;
+		return failure;
+	});
+}
+/**
+* Build the client's {@link Validator} from a user-brought ajv instance and the codegen's per-type
+* `schemas` map. Each schema is compiled ONCE up front (keyed by JSON:API type) with the instance's
+* configured dialect — pass `new Ajv2020()` for the 2020-12 dialect the bundle emits. The returned
+* function is the bare-`Validator` seam form: it looks the compiled validator up by `resource.type`,
+* skips a type the bundle does not cover (graceful partial coverage), and on a failing resource
+* throws an aggregated {@link AjvValidationError} listing the failing pointers.
+*
+* @param ajv   A configured ajv instance ({@link AjvLike}) — typically `new Ajv2020({ allErrors: true })`.
+* @param schemas The codegen-emitted `schemas` map (type -> resource-object JSON Schema 2020-12 doc).
+*/
+function createAjvValidator(ajv, schemas) {
+	const compiled = /* @__PURE__ */ new Map();
+	for (const [type, schema] of Object.entries(schemas)) compiled.set(type, ajv.compile(schema));
+	const validator = (resource) => {
+		const { type, id } = resource;
+		const validate = compiled.get(type);
+		if (validate === void 0) return;
+		if (!validate(resource)) throw new AjvValidationError(type, id, toFailures(type, id, validate.errors ?? []));
+	};
+	return validator;
+}
+//#endregion
+exports.AjvValidationError = AjvValidationError;
+exports.createAjvValidator = createAjvValidator;

package/dist/ajv.d.cts

@@ -0,0 +1,55 @@
+import { a as Validator, n as SchemaMap } from "./validate-BmyPbJCK.cjs";
+import { ValidateFunction } from "ajv";
+
+//#region src/ajv.d.ts
+/**
+ * The minimal ajv surface the adapter uses: `compile(schema)` -> a validate function. Any
+ * ajv-core instance satisfies it — typically `new Ajv2020()` (the JSON Schema 2020-12 dialect
+ * the bundle emits), but a base `Ajv` with the 2020 meta-schema added works too. Typed
+ * structurally so the adapter binds to the capability, not a specific ajv subclass.
+ */
+interface AjvLike {
+  compile(schema: unknown): ValidateFunction;
+}
+/** One failing field: the resource it came from plus ajv's pointer, keyword, and message. */
+interface AjvValidationFailure {
+  /** The JSON:API type of the resource that failed (`schemas[type]` was applied). */
+  type: string;
+  /** The resource id, when present (a bare identifier or a full resource object both carry one). */
+  id?: string;
+  /** ajv's `instancePath` into the resource (e.g. `/attributes/title`); empty string for the root. */
+  pointer: string;
+  /** The failing ajv keyword (e.g. `type`, `maxLength`, `enum`). */
+  keyword: string;
+  /** ajv's human-readable message (e.g. `must be string`). */
+  message: string;
+}
+/**
+ * Thrown by the ajv adapter when a wire resource fails its per-type schema. Aggregates every
+ * ajv error into {@link AjvValidationFailure}s (one per failing field) and renders a message
+ * listing the failing pointers, so a caller can both read the summary and walk `failures`.
+ */
+declare class AjvValidationError extends Error {
+  /** Every failing field across the resource (ajv runs with `allErrors`-aware reporting if enabled). */
+  readonly failures: readonly AjvValidationFailure[];
+  /** The JSON:API type of the resource that failed. */
+  readonly type: string;
+  /** The id of the resource that failed, when present. */
+  readonly resourceId?: string;
+  constructor(type: string, id: string | undefined, failures: readonly AjvValidationFailure[]);
+}
+/**
+ * Build the client's {@link Validator} from a user-brought ajv instance and the codegen's per-type
+ * `schemas` map. Each schema is compiled ONCE up front (keyed by JSON:API type) with the instance's
+ * configured dialect — pass `new Ajv2020()` for the 2020-12 dialect the bundle emits. The returned
+ * function is the bare-`Validator` seam form: it looks the compiled validator up by `resource.type`,
+ * skips a type the bundle does not cover (graceful partial coverage), and on a failing resource
+ * throws an aggregated {@link AjvValidationError} listing the failing pointers.
+ *
+ * @param ajv   A configured ajv instance ({@link AjvLike}) — typically `new Ajv2020({ allErrors: true })`.
+ * @param schemas The codegen-emitted `schemas` map (type -> resource-object JSON Schema 2020-12 doc).
+ */
+declare function createAjvValidator(ajv: AjvLike, schemas: SchemaMap): Validator;
+//#endregion
+export { AjvLike, AjvValidationError, AjvValidationFailure, createAjvValidator };
+//# sourceMappingURL=ajv.d.cts.map

package/dist/ajv.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv.d.cts","names":[],"sources":["../src/ajv.ts"],"mappings":";;;;;;;;;;UA2CiB,OAAA;EACf,OAAA,CAAQ,MAAA,YAAkB,gBAAgB;AAAA;;UAI3B,oBAAA;EAsEuB;EApEtC,IAAA;EAoEoE;EAlEpE,EAAA;EAkE6E;EAhE7E,OAAA;EAgEiC;EA9DjC,OAAA;EA8D+C;EA5D/C,OAAA;AAAA;AA4D6E;;;;;AAAA,cApDlE,kBAAA,SAA2B,KAAA;;WAE7B,QAAA,WAAmB,oBAAA;;WAEnB,IAAA;;WAEA,UAAA;cAEG,IAAA,UAAc,EAAA,sBAAwB,QAAA,WAAmB,oBAAA;AAAA;;;;;;;;;;;;iBA4CvD,kBAAA,CAAmB,GAAA,EAAK,OAAA,EAAS,OAAA,EAAS,SAAA,GAAY,SAAA"}

package/dist/ajv.d.mts

@@ -0,0 +1,55 @@
+import { a as Validator, n as SchemaMap } from "./validate-BmyPbJCK.mjs";
+import { ValidateFunction } from "ajv";
+
+//#region src/ajv.d.ts
+/**
+ * The minimal ajv surface the adapter uses: `compile(schema)` -> a validate function. Any
+ * ajv-core instance satisfies it — typically `new Ajv2020()` (the JSON Schema 2020-12 dialect
+ * the bundle emits), but a base `Ajv` with the 2020 meta-schema added works too. Typed
+ * structurally so the adapter binds to the capability, not a specific ajv subclass.
+ */
+interface AjvLike {
+  compile(schema: unknown): ValidateFunction;
+}
+/** One failing field: the resource it came from plus ajv's pointer, keyword, and message. */
+interface AjvValidationFailure {
+  /** The JSON:API type of the resource that failed (`schemas[type]` was applied). */
+  type: string;
+  /** The resource id, when present (a bare identifier or a full resource object both carry one). */
+  id?: string;
+  /** ajv's `instancePath` into the resource (e.g. `/attributes/title`); empty string for the root. */
+  pointer: string;
+  /** The failing ajv keyword (e.g. `type`, `maxLength`, `enum`). */
+  keyword: string;
+  /** ajv's human-readable message (e.g. `must be string`). */
+  message: string;
+}
+/**
+ * Thrown by the ajv adapter when a wire resource fails its per-type schema. Aggregates every
+ * ajv error into {@link AjvValidationFailure}s (one per failing field) and renders a message
+ * listing the failing pointers, so a caller can both read the summary and walk `failures`.
+ */
+declare class AjvValidationError extends Error {
+  /** Every failing field across the resource (ajv runs with `allErrors`-aware reporting if enabled). */
+  readonly failures: readonly AjvValidationFailure[];
+  /** The JSON:API type of the resource that failed. */
+  readonly type: string;
+  /** The id of the resource that failed, when present. */
+  readonly resourceId?: string;
+  constructor(type: string, id: string | undefined, failures: readonly AjvValidationFailure[]);
+}
+/**
+ * Build the client's {@link Validator} from a user-brought ajv instance and the codegen's per-type
+ * `schemas` map. Each schema is compiled ONCE up front (keyed by JSON:API type) with the instance's
+ * configured dialect — pass `new Ajv2020()` for the 2020-12 dialect the bundle emits. The returned
+ * function is the bare-`Validator` seam form: it looks the compiled validator up by `resource.type`,
+ * skips a type the bundle does not cover (graceful partial coverage), and on a failing resource
+ * throws an aggregated {@link AjvValidationError} listing the failing pointers.
+ *
+ * @param ajv   A configured ajv instance ({@link AjvLike}) — typically `new Ajv2020({ allErrors: true })`.
+ * @param schemas The codegen-emitted `schemas` map (type -> resource-object JSON Schema 2020-12 doc).
+ */
+declare function createAjvValidator(ajv: AjvLike, schemas: SchemaMap): Validator;
+//#endregion
+export { AjvLike, AjvValidationError, AjvValidationFailure, createAjvValidator };
+//# sourceMappingURL=ajv.d.mts.map

package/dist/ajv.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv.d.mts","names":[],"sources":["../src/ajv.ts"],"mappings":";;;;;;;;;;UA2CiB,OAAA;EACf,OAAA,CAAQ,MAAA,YAAkB,gBAAgB;AAAA;;UAI3B,oBAAA;EAsEuB;EApEtC,IAAA;EAoEoE;EAlEpE,EAAA;EAkE6E;EAhE7E,OAAA;EAgEiC;EA9DjC,OAAA;EA8D+C;EA5D/C,OAAA;AAAA;AA4D6E;;;;;AAAA,cApDlE,kBAAA,SAA2B,KAAA;;WAE7B,QAAA,WAAmB,oBAAA;;WAEnB,IAAA;;WAEA,UAAA;cAEG,IAAA,UAAc,EAAA,sBAAwB,QAAA,WAAmB,oBAAA;AAAA;;;;;;;;;;;;iBA4CvD,kBAAA,CAAmB,GAAA,EAAK,OAAA,EAAS,OAAA,EAAS,SAAA,GAAY,SAAA"}

package/dist/ajv.mjs

@@ -0,0 +1,62 @@
+//#region src/ajv.ts
+/**
+* Thrown by the ajv adapter when a wire resource fails its per-type schema. Aggregates every
+* ajv error into {@link AjvValidationFailure}s (one per failing field) and renders a message
+* listing the failing pointers, so a caller can both read the summary and walk `failures`.
+*/
+var AjvValidationError = class extends Error {
+	/** Every failing field across the resource (ajv runs with `allErrors`-aware reporting if enabled). */
+	failures;
+	/** The JSON:API type of the resource that failed. */
+	type;
+	/** The id of the resource that failed, when present. */
+	resourceId;
+	constructor(type, id, failures) {
+		const at = id === void 0 ? type : `${type}:${id}`;
+		const pointers = failures.map((f) => `${f.pointer || "/"} ${f.message}`).join("; ");
+		super(`Resource ${at} failed schema validation: ${pointers}`);
+		this.name = "AjvValidationError";
+		this.type = type;
+		if (id !== void 0) this.resourceId = id;
+		this.failures = failures;
+	}
+};
+/** Map ajv's raw `ErrorObject`s for one resource to the adapter's typed failures. */
+function toFailures(type, id, errors) {
+	return errors.map((e) => {
+		const failure = {
+			type,
+			pointer: e.instancePath,
+			keyword: e.keyword,
+			message: e.message ?? "is invalid"
+		};
+		if (id !== void 0) failure.id = id;
+		return failure;
+	});
+}
+/**
+* Build the client's {@link Validator} from a user-brought ajv instance and the codegen's per-type
+* `schemas` map. Each schema is compiled ONCE up front (keyed by JSON:API type) with the instance's
+* configured dialect — pass `new Ajv2020()` for the 2020-12 dialect the bundle emits. The returned
+* function is the bare-`Validator` seam form: it looks the compiled validator up by `resource.type`,
+* skips a type the bundle does not cover (graceful partial coverage), and on a failing resource
+* throws an aggregated {@link AjvValidationError} listing the failing pointers.
+*
+* @param ajv   A configured ajv instance ({@link AjvLike}) — typically `new Ajv2020({ allErrors: true })`.
+* @param schemas The codegen-emitted `schemas` map (type -> resource-object JSON Schema 2020-12 doc).
+*/
+function createAjvValidator(ajv, schemas) {
+	const compiled = /* @__PURE__ */ new Map();
+	for (const [type, schema] of Object.entries(schemas)) compiled.set(type, ajv.compile(schema));
+	const validator = (resource) => {
+		const { type, id } = resource;
+		const validate = compiled.get(type);
+		if (validate === void 0) return;
+		if (!validate(resource)) throw new AjvValidationError(type, id, toFailures(type, id, validate.errors ?? []));
+	};
+	return validator;
+}
+//#endregion
+export { AjvValidationError, createAjvValidator };
+
+//# sourceMappingURL=ajv.mjs.map

package/dist/ajv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv.mjs","names":[],"sources":["../src/ajv.ts"],"sourcesContent":["/**\n * @haddowg/json-api-client/ajv — an optional ajv adapter for the validation seam.\n *\n * Turns a user-brought ajv instance + the codegen-emitted `schemas` map into the\n * {@link Validator} the client's `validate?` option accepts, so opting into per-field\n * validation is a few lines:\n *\n * ```ts\n * import Ajv2020 from 'ajv/dist/2020'\n * import { createClient } from '@haddowg/json-api-client'\n * import { createAjvValidator } from '@haddowg/json-api-client/ajv'\n * import { schemas } from './japi.gen' // the codegen's `schemas` constant\n *\n * // The bundle emits the JSON Schema 2020-12 dialect, so use `Ajv2020`. `strict: false`\n * // tolerates the schemas' `x-enum-*` annotations; `allErrors` aggregates every failing field.\n * const ajv = new Ajv2020({ strict: false, allErrors: true })\n * const client = createClient(descriptor, {\n *   baseUrl: 'https://music.example',\n *   validate: createAjvValidator(ajv, schemas),\n * })\n * ```\n *\n * The schemas also carry `format` annotations (`date-time`, `date`, `uuid`, `time`, `uri`). ajv\n * ignores unknown formats by default; to ENFORCE them attach `ajv-formats`\n * (`import addFormats from 'ajv-formats'; addFormats(ajv)`). Note the wire's `time` is a\n * duration-style value the strict `time` format rejects — pass `{ mode: 'fast' }` or omit `time`\n * if you hit that, since formats are advisory and the client's posture is to validate structure\n * and types, trusting the wire on format minutiae.\n *\n * `ajv` is an OPTIONAL peer dependency of this package — it is imported here as a TYPE\n * only (`import type`), so the engine is brought by the caller and never enters the core\n * client's runtime dependency tree. This module is its own sub-path export\n * (`@haddowg/json-api-client/ajv`); importing the main entry never pulls ajv in.\n */\nimport type { ErrorObject, ValidateFunction } from 'ajv'\nimport type { SchemaMap, Validator, WireResource } from './validate'\n\n/**\n * The minimal ajv surface the adapter uses: `compile(schema)` -> a validate function. Any\n * ajv-core instance satisfies it — typically `new Ajv2020()` (the JSON Schema 2020-12 dialect\n * the bundle emits), but a base `Ajv` with the 2020 meta-schema added works too. Typed\n * structurally so the adapter binds to the capability, not a specific ajv subclass.\n */\nexport interface AjvLike {\n  compile(schema: unknown): ValidateFunction\n}\n\n/** One failing field: the resource it came from plus ajv's pointer, keyword, and message. */\nexport interface AjvValidationFailure {\n  /** The JSON:API type of the resource that failed (`schemas[type]` was applied). */\n  type: string\n  /** The resource id, when present (a bare identifier or a full resource object both carry one). */\n  id?: string\n  /** ajv's `instancePath` into the resource (e.g. `/attributes/title`); empty string for the root. */\n  pointer: string\n  /** The failing ajv keyword (e.g. `type`, `maxLength`, `enum`). */\n  keyword: string\n  /** ajv's human-readable message (e.g. `must be string`). */\n  message: string\n}\n\n/**\n * Thrown by the ajv adapter when a wire resource fails its per-type schema. Aggregates every\n * ajv error into {@link AjvValidationFailure}s (one per failing field) and renders a message\n * listing the failing pointers, so a caller can both read the summary and walk `failures`.\n */\nexport class AjvValidationError extends Error {\n  /** Every failing field across the resource (ajv runs with `allErrors`-aware reporting if enabled). */\n  readonly failures: readonly AjvValidationFailure[]\n  /** The JSON:API type of the resource that failed. */\n  readonly type: string\n  /** The id of the resource that failed, when present. */\n  readonly resourceId?: string\n\n  constructor(type: string, id: string | undefined, failures: readonly AjvValidationFailure[]) {\n    const at = id === undefined ? type : `${type}:${id}`\n    const pointers = failures.map((f) => `${f.pointer || '/'} ${f.message}`).join('; ')\n    super(`Resource ${at} failed schema validation: ${pointers}`)\n    this.name = 'AjvValidationError'\n    this.type = type\n    if (id !== undefined) {\n      this.resourceId = id\n    }\n    this.failures = failures\n  }\n}\n\n/** Map ajv's raw `ErrorObject`s for one resource to the adapter's typed failures. */\nfunction toFailures(\n  type: string,\n  id: string | undefined,\n  errors: ErrorObject[],\n): AjvValidationFailure[] {\n  return errors.map((e) => {\n    const failure: AjvValidationFailure = {\n      type,\n      pointer: e.instancePath,\n      keyword: e.keyword,\n      message: e.message ?? 'is invalid',\n    }\n    if (id !== undefined) {\n      failure.id = id\n    }\n    return failure\n  })\n}\n\n/**\n * Build the client's {@link Validator} from a user-brought ajv instance and the codegen's per-type\n * `schemas` map. Each schema is compiled ONCE up front (keyed by JSON:API type) with the instance's\n * configured dialect — pass `new Ajv2020()` for the 2020-12 dialect the bundle emits. The returned\n * function is the bare-`Validator` seam form: it looks the compiled validator up by `resource.type`,\n * skips a type the bundle does not cover (graceful partial coverage), and on a failing resource\n * throws an aggregated {@link AjvValidationError} listing the failing pointers.\n *\n * @param ajv   A configured ajv instance ({@link AjvLike}) — typically `new Ajv2020({ allErrors: true })`.\n * @param schemas The codegen-emitted `schemas` map (type -> resource-object JSON Schema 2020-12 doc).\n */\nexport function createAjvValidator(ajv: AjvLike, schemas: SchemaMap): Validator {\n  // Compile every per-type schema once, keyed by type. ajv key-collision (a duplicate `$id`) is the\n  // engine's concern; we compile each schema independently so one bad type does not block the rest.\n  const compiled = new Map<string, ValidateFunction>()\n  for (const [type, schema] of Object.entries(schemas)) {\n    compiled.set(type, ajv.compile(schema))\n  }\n\n  // The bare-`Validator` seam form: `(resource, schema) => void`. The adapter owns its own compiled\n  // lookup (by `resource.type`), so the seam's `schema` argument is unused (the runtime passes\n  // `undefined` for a bare validator); it is accepted only to satisfy the {@link Validator} signature.\n  const validator: Validator = (resource: WireResource): void => {\n    // Read `type`/`id` up front: ajv's `ValidateFunction` is a type guard, so calling it narrows\n    // `resource` in the failing branch and the props would no longer be reachable off it.\n    const { type, id } = resource\n    const validate = compiled.get(type)\n    // A type the bundle does not cover is skipped, not failed — matches the seam's graceful posture.\n    if (validate === undefined) {\n      return\n    }\n    if (!validate(resource)) {\n      const errors = validate.errors ?? []\n      throw new AjvValidationError(type, id, toFailures(type, id, errors))\n    }\n  }\n  return validator\n}\n"],"mappings":";;;;;;AAkEA,IAAa,qBAAb,cAAwC,MAAM;;CAE5C;;CAEA;;CAEA;CAEA,YAAY,MAAc,IAAwB,UAA2C;EAC3F,MAAM,KAAK,OAAO,KAAA,IAAY,OAAO,GAAG,KAAK,GAAG;EAChD,MAAM,WAAW,SAAS,KAAK,MAAM,GAAG,EAAE,WAAW,IAAI,GAAG,EAAE,SAAS,CAAC,CAAC,KAAK,IAAI;EAClF,MAAM,YAAY,GAAG,6BAA6B,UAAU;EAC5D,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,IAAI,OAAO,KAAA,GACT,KAAK,aAAa;EAEpB,KAAK,WAAW;CAClB;AACF;;AAGA,SAAS,WACP,MACA,IACA,QACwB;CACxB,OAAO,OAAO,KAAK,MAAM;EACvB,MAAM,UAAgC;GACpC;GACA,SAAS,EAAE;GACX,SAAS,EAAE;GACX,SAAS,EAAE,WAAW;EACxB;EACA,IAAI,OAAO,KAAA,GACT,QAAQ,KAAK;EAEf,OAAO;CACT,CAAC;AACH;;;;;;;;;;;;AAaA,SAAgB,mBAAmB,KAAc,SAA+B;CAG9E,MAAM,2BAAW,IAAI,IAA8B;CACnD,KAAK,MAAM,CAAC,MAAM,WAAW,OAAO,QAAQ,OAAO,GACjD,SAAS,IAAI,MAAM,IAAI,QAAQ,MAAM,CAAC;CAMxC,MAAM,aAAwB,aAAiC;EAG7D,MAAM,EAAE,MAAM,OAAO;EACrB,MAAM,WAAW,SAAS,IAAI,IAAI;EAElC,IAAI,aAAa,KAAA,GACf;EAEF,IAAI,CAAC,SAAS,QAAQ,GAEpB,MAAM,IAAI,mBAAmB,MAAM,IAAI,WAAW,MAAM,IADzC,SAAS,UAAU,CAAC,CAC+B,CAAC;CAEvE;CACA,OAAO;AACT"}