@haddowg/json-api-client 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,198 @@
+import { $ as SortQuery, A as DefaultActionTypes, At as RelationView, B as IncludePath, Bt as AtomicDescriptor, C as fetchTransport, Ct as mediaType, D as Collection, Dt as EdgeEnvelope, E as Client, Et as Edge, F as FieldsMap, Ft as ActionDescriptor, G as ReadResult, Gt as RelationDescriptor, H as LinkageRef, Ht as ClientIdPolicy, I as FilterKey, It as ActionInput, J as RelationshipAccessor, K as RelationName, Kt as RelationMutations, L as FilterQuery, Lt as ActionOutput, M as DefaultWriteAttributes, Mt as ResourceLinks, N as EdgeMembers, Nt as materialise, O as CountToken, Ot as MaterialiseContext, P as FieldSelectionMap, Pt as relatedPaginatorKind, Q as SingleReadQuery, R as HydratedMember, Rt as ActionScope, S as TransportResponse, St as ResourceIdentifier, T as AtomicResultOf, Tt as DocumentEnvelope, U as MemberName, Ut as CountableDescriptor, V as IncludedRelations, Vt as Cardinality, W as PivotInput, Wt as PaginatorKind, X as ResourceHandle, Y as ResourceAccessors, Z as ResourceObjectView, _ as HANDLE_RESERVED, _t as ATOMIC_EXT, a as Validator, at as WriteOptions, b as JsonApiTransport, bt as LocalIdentifier, c as resolveValidator, ct as AtomicDeleteHandle, d as JsonApiContext, dt as AtomicRef, et as SortToken, f as JsonApiRequest, ft as AtomicResult, g as ClientOptions, gt as runAtomic, h as serializeQuery, ht as AtomicUpdateInput, i as ValidationOption, it as UpdateInput, j as DefaultAttributes, jt as ResourceEnvelope, k as CreateInput, kt as Page, l as validateDocument, lt as AtomicHandle, m as execute, mt as AtomicUpdateHandle, n as SchemaMap, nt as TypeName, o as WireResource, ot as AtomicCreateHandle, p as ReadQuery, pt as AtomicResults, q as RelationReadQuery, qt as ResourceDescriptor, r as ValidationConfig, rt as TypedReadQuery, s as assertJsonApiDocument, st as AtomicCreateInput, t as ResolvedValidator, tt as TypeAccessor, u as Document, ut as AtomicRecorder, v as HeadersInit, vt as ATOMIC_MEDIA_TYPE, w as ActionsAccessor, wt as ArrayEnvelope, x as TransportRequest, xt as MediaTypeParams, y as createClient, yt as JSON_API_MEDIA_TYPE, z as IdentifierMember, zt as ApiDescriptor } from "./validate-BmyPbJCK.cjs";
+
+//#region src/errors.d.ts
+/** A single JSON:API error object (spec: error objects). */
+interface JsonApiErrorObject {
+  id?: string;
+  status?: string;
+  code?: string;
+  title?: string;
+  detail?: string;
+  source?: {
+    pointer?: string;
+    parameter?: string;
+    header?: string;
+  };
+  meta?: Record<string, unknown>;
+  /**
+   * The user-facing input path, remapped from `source.pointer` for write errors
+   * (e.g. `/data/attributes/title` -> `title`). Populated by the runtime, which
+   * built the envelope and therefore knows the inverse mapping. See CONTEXT.md.
+   */
+  path?: string;
+  /**
+   * The zero-based index of the failing operation within an atomic batch, parsed from a
+   * `source.pointer` carrying an `/atomic:operations/{n}` prefix. Populated only for atomic
+   * errors; `path` then holds the flat path within that operation's input.
+   */
+  opIndex?: number;
+}
+/**
+ * Thrown by the always-on light structural guards (ADR 0004) when a parsed response is not a
+ * JSON:API document, or a `data`/`included` member is not a resource object carrying `type`+`id`.
+ * Distinct from {@link JsonApiError} (a non-2xx server response): this signals the wire shape the
+ * runtime relies on was violated, not an application error the server reported. The opt-in
+ * per-field validator throws its engine's own error type, never this one.
+ */
+declare class StructuralGuardError extends Error {
+  constructor(message: string);
+}
+/**
+ * Thrown for any non-2xx JSON:API response. Carries the parsed error document plus
+ * expressive status matchers and pointer-grouping helpers.
+ */
+declare class JsonApiError extends Error {
+  readonly status: number;
+  readonly errors: JsonApiErrorObject[];
+  constructor(status: number, errors: JsonApiErrorObject[], message?: string);
+  hasStatus(status: number): boolean;
+  is4xx(): boolean;
+  is5xx(): boolean;
+  isBadRequest(): boolean;
+  isUnauthorized(): boolean;
+  isForbidden(): boolean;
+  isNotFound(): boolean;
+  isNotAcceptable(): boolean;
+  isConflict(): boolean;
+  isUnsupportedMediaType(): boolean;
+  isUnprocessable(): boolean;
+  /** Alias of {@link isUnprocessable} — the JSON:API validation status. */
+  isValidationError(): boolean;
+  isRateLimited(): boolean;
+  /**
+   * Group errors by user-facing input path (falls back to the raw pointer, then the
+   * query parameter). The payoff for form/validation UX — 422 `source.pointer`s are
+   * remapped to the flat shape the caller actually supplied.
+   */
+  byPath(): Record<string, JsonApiErrorObject[]>;
+}
+//#endregion
+//#region src/serialize-write.d.ts
+/**
+ * A JSON:API resource identifier in a write document: `{ type, id }` or — inside an atomic
+ * batch — `{ type, lid }` (a reference to a resource created earlier in the same transaction).
+ * May carry writable pivot meta on a to-many member.
+ */
+interface WriteIdentifier {
+  type: string;
+  id?: string;
+  lid?: string;
+  meta?: {
+    pivot: Record<string, unknown>;
+  } & Record<string, unknown>;
+}
+/** A relationship document: `{ data: <linkage> }`. */
+interface RelationshipDocument {
+  data: WriteIdentifier | WriteIdentifier[] | null;
+}
+/** The JSON:API write document {@link toDocument} produces. */
+interface WriteDocument {
+  data: {
+    type: string;
+    id?: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, RelationshipDocument>;
+  };
+}
+/** Options for {@link toDocument}. */
+interface ToDocumentOptions {
+  /**
+   * The resource id, supplied for an UPDATE (it comes from the handle, not the input). When
+   * present it is always written as `data.id`. Omit for a CREATE — then `input.id` is written
+   * only per the type's `clientId` policy.
+   */
+  id?: string;
+}
+/**
+ * Build a JSON:API write document from FLAT input. Each input key is routed via the
+ * descriptor: a declared relation -> `data.relationships[name] = { data: <linkage> }`;
+ * anything else -> `data.attributes[name]`. Relationship linkage is coerced by cardinality:
+ *
+ * - to-one accepts an identifier `{type,id}`, a materialised resource object (its `{type,id}`
+ *   are extracted), or `null` (-> `data: null`, clearing the relationship);
+ * - to-many accepts an array of those; a member may carry a `$pivot` object, rendered as the
+ *   member identifier's `meta.pivot` (writable pivot fields).
+ *
+ * `data.type` is always the accessor `type`. `data.id` is written from `opts.id` (an update),
+ * else from `input.id` only when the type's `clientId` policy allows it (omitted when
+ * `forbidden`, passed through when `optional`/`required`).
+ */
+declare function toDocument(descriptor: ApiDescriptor, type: string, input: Record<string, unknown>, opts?: ToDocumentOptions): WriteDocument;
+/**
+ * Build a relationship-mutation document `{ data: <linkage> }` for the
+ * `/{type}/{id}/relationships/{rel}` endpoints, coercing the caller's refs by cardinality:
+ *
+ * - to-one accepts an identifier `{type,id}`, a materialised resource object, or `null`
+ *   (-> `data: null`, clearing the relationship);
+ * - to-many accepts an array of those; a member may carry `$pivot`, rendered as the member
+ *   identifier's `meta.pivot`.
+ *
+ * The same {@link coerceLinkage} the whole-resource writer uses, so a relationship written
+ * standalone and one embedded in a resource serialise identically.
+ */
+declare function toRelationshipDocument(refs: unknown, cardinality: 'one' | 'many'): RelationshipDocument;
+/**
+ * Invert a write error's `source.pointer` to the caller's FLAT input path, descriptor-aware:
+ *
+ * - `/data/attributes/title`                                 -> `title`
+ * - `/data/relationships/artist/data`                        -> `artist`
+ * - `/data/id`                                               -> `id` (client-id create conflict)
+ * - `/data/attributes/releaseInfo/label`                     -> `releaseInfo.label` (nested map)
+ * - `/data/relationships/orderedTracks/data/0/meta/pivot/position` -> `orderedTracks[0].$pivot.position`
+ *
+ * Pivot values nest under a member's `meta.pivot` (symmetric with reads — see
+ * `JsonPointerBuilder::forLinkageMeta` / bundle ADR 0103), so a `meta/pivot/<field>` tail on
+ * a member of a pivot-bearing to-many is surfaced as `.$pivot.<field>`.
+ *
+ * A query-side pointer is left untouched (those are already user-facing — see
+ * {@link withRemappedPaths}). An unrecognised / non-write pointer is returned verbatim.
+ * `/data/type` and a bare `/data` are passed through (the client owns those; the caller
+ * never supplies them).
+ */
+declare function remapPointer(descriptor: ApiDescriptor, type: string, pointer: string): string;
+/**
+ * Invert a relationship-MUTATION error's `source.pointer` to the caller's flat path, for the
+ * `/{type}/{id}/relationships/{rel}` endpoints. Two pointer shapes reach here:
+ *
+ * - the LINKAGE document shape (validation on the linkage members), rooted at `data` — the
+ *   relation name is supplied by the route, not the wire:
+ *   - `/data`                             -> `<rel>`                  (to-one clear/set)
+ *   - `/data/meta/pivot/position`         -> `<rel>.$pivot.position`  (to-one pivot, rare)
+ *   - `/data/0/meta/pivot/position`       -> `<rel>[0].$pivot.position`
+ * - the RESOURCE-document shape that core's relationship prohibitions emit unchanged
+ *   (`FullReplacementProhibited`/`RemovalProhibited`/`AdditionProhibited`/
+ *   `RelationshipTypeInappropriate` all point at `/data/relationships/<name>`) — short-circuited
+ *   to the relation name (drop the `relationships/<name>` prefix) rather than treating
+ *   `relationships` as a linkage sub-segment.
+ *
+ * A non-`data` pointer is returned verbatim.
+ */
+declare function remapRelationshipPointer(rel: string, hasPivot: boolean, pointer: string): string;
+/**
+ * Return a {@link JsonApiError} with each error object's `path` populated by remapping its
+ * `source.pointer` (descriptor-aware) — so {@link JsonApiError.byPath} groups by the flat input
+ * shape. Errors with no write pointer (e.g. a `source.parameter` query-side error, or no
+ * source) are passed through unchanged. The original error is not mutated.
+ */
+declare function withRemappedPaths(error: JsonApiError, descriptor: ApiDescriptor, type: string): JsonApiError;
+/**
+ * The relationship-mutation twin of {@link withRemappedPaths}: remap each error's pointer
+ * keyed by the relation name from the route. Handles both the linkage-document shape (rooted
+ * at `data`) and the resource-document shape core's prohibition exceptions emit
+ * (`/data/relationships/<rel>`). `hasPivot` lets a member-level `meta` field surface as
+ * `$pivot`. The original error is not mutated.
+ */
+declare function withRemappedRelationshipPaths(error: JsonApiError, rel: string, hasPivot: boolean): JsonApiError;
+/**
+ * Invert an atomic-batch error's `source.pointer` to `(opIndex, flatPath)`: an atomic 422
+ * points at `/atomic:operations/{n}/data/...`, so strip the `atomic:operations/{n}` prefix to
+ * the op index, resolve that op's wire type (`typeForOp`), and delegate the remaining `/data`
+ * tail to the same {@link remapPointer} a standalone write uses (so the flat path is identical
+ * — `title`, `releaseInfo.label`, `artist`, …). A pointer without the atomic prefix is remapped
+ * verbatim under the (whole-batch) document at op index `undefined`. The original error is not
+ * mutated.
+ */
+declare function withRemappedAtomicPaths(error: JsonApiError, descriptor: ApiDescriptor, typeForOp: (opIndex: number) => string | undefined): JsonApiError;
+//#endregion
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, Page, PaginatorKind, PivotInput, ReadQuery, ReadResult, RelationDescriptor, RelationMutations, RelationName, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, materialise, mediaType, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts","../src/serialize-write.ts"],"mappings":";;;;UACiB,kBAAA;EACf,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,MAAA;IAAW,OAAA;IAAkB,SAAA;IAAoB,MAAA;EAAA;EACjD,IAAA,GAAO,MAAM;EADF;;;;;EAOX,IAAA;EAMA;;AAAO;AAUT;;EAVE,OAAA;AAAA;;;;;AAW2B;AAU7B;;cAXa,oBAAA,SAA6B,KAAK;cACjC,OAAA;AAAA;;;;;cAUD,YAAA,SAAqB,KAAA;EAAA,SACvB,MAAA;EAAA,SACA,MAAA,EAAQ,kBAAA;cAEL,MAAA,UAAgB,MAAA,EAAQ,kBAAA,IAAsB,OAAA;EAO1D,SAAA,CAAU,MAAA;EAIV,KAAA;EAIA,KAAA;EAIA,YAAA;EAIA,cAAA;EAIA,WAAA;EAIA,UAAA;EAIA,eAAA;EAIA,UAAA;EAIA,sBAAA;EAIA,eAAA;EAxBA;EA6BA,iBAAA;EAIA,aAAA;EArBA;;;;;EA8BA,MAAA,IAAU,MAAA,SAAe,kBAAA;AAAA;;;;;;;;UClFjB,eAAA;EACR,IAAA;EACA,EAAA;EACA,GAAA;EACA,IAAA;IAAS,KAAA,EAAO,MAAA;EAAA,IAA4B,MAAM;AAAA;;UAInC,oBAAA;EACf,IAAA,EAAM,eAAA,GAAkB,eAAe;AAAA;ADNZ;AAAA,UCUZ,aAAA;EACf,IAAA;IACE,IAAA;IACA,EAAA;IACA,UAAA,GAAa,MAAA;IACb,aAAA,GAAgB,MAAA,SAAe,oBAAA;EAAA;AAAA;;UAKlB,iBAAA;EDViB;;;;;ECgBhC,EAAE;AAAA;;;;;;;;;;;;;;;iBAiBY,UAAA,CACd,UAAA,EAAY,aAAA,EACZ,IAAA,UACA,KAAA,EAAO,MAAA,mBACP,IAAA,GAAO,iBAAA,GACN,aAAA;;;;;;AD+B0C;;;;AClGmB;;;iBAmHhD,sBAAA,CACd,IAAA,WACA,WAAA,mBACC,oBAAoB;;;;;;;;;AAlG6B;AAIpD;;;;;;;;AACyC;iBAwLzB,YAAA,CAAa,UAAA,EAAY,aAAa,EAAE,IAAA,UAAc,OAAA;;;;;;;;;;;;;;;;;AA/Kf;iBA+PvC,wBAAA,CAAyB,GAAA,UAAa,QAAA,WAAmB,OAAA;;;;AApPrE;AAiBJ;;iBAqPgB,iBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,IAAA,WACC,YAAA;;;;;;;;iBAWa,6BAAA,CACd,KAAA,EAAO,YAAA,EACP,GAAA,UACA,QAAA,YACC,YAAY;;;;;;;;AAnQC;AAgDhB;iBAgOgB,uBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,SAAA,GAAY,OAAA,kCACX,YAAA"}

package/dist/index.d.mts

@@ -0,0 +1,198 @@
+import { $ as SortQuery, A as DefaultActionTypes, At as RelationView, B as IncludePath, Bt as AtomicDescriptor, C as fetchTransport, Ct as mediaType, D as Collection, Dt as EdgeEnvelope, E as Client, Et as Edge, F as FieldsMap, Ft as ActionDescriptor, G as ReadResult, Gt as RelationDescriptor, H as LinkageRef, Ht as ClientIdPolicy, I as FilterKey, It as ActionInput, J as RelationshipAccessor, K as RelationName, Kt as RelationMutations, L as FilterQuery, Lt as ActionOutput, M as DefaultWriteAttributes, Mt as ResourceLinks, N as EdgeMembers, Nt as materialise, O as CountToken, Ot as MaterialiseContext, P as FieldSelectionMap, Pt as relatedPaginatorKind, Q as SingleReadQuery, R as HydratedMember, Rt as ActionScope, S as TransportResponse, St as ResourceIdentifier, T as AtomicResultOf, Tt as DocumentEnvelope, U as MemberName, Ut as CountableDescriptor, V as IncludedRelations, Vt as Cardinality, W as PivotInput, Wt as PaginatorKind, X as ResourceHandle, Y as ResourceAccessors, Z as ResourceObjectView, _ as HANDLE_RESERVED, _t as ATOMIC_EXT, a as Validator, at as WriteOptions, b as JsonApiTransport, bt as LocalIdentifier, c as resolveValidator, ct as AtomicDeleteHandle, d as JsonApiContext, dt as AtomicRef, et as SortToken, f as JsonApiRequest, ft as AtomicResult, g as ClientOptions, gt as runAtomic, h as serializeQuery, ht as AtomicUpdateInput, i as ValidationOption, it as UpdateInput, j as DefaultAttributes, jt as ResourceEnvelope, k as CreateInput, kt as Page, l as validateDocument, lt as AtomicHandle, m as execute, mt as AtomicUpdateHandle, n as SchemaMap, nt as TypeName, o as WireResource, ot as AtomicCreateHandle, p as ReadQuery, pt as AtomicResults, q as RelationReadQuery, qt as ResourceDescriptor, r as ValidationConfig, rt as TypedReadQuery, s as assertJsonApiDocument, st as AtomicCreateInput, t as ResolvedValidator, tt as TypeAccessor, u as Document, ut as AtomicRecorder, v as HeadersInit, vt as ATOMIC_MEDIA_TYPE, w as ActionsAccessor, wt as ArrayEnvelope, x as TransportRequest, xt as MediaTypeParams, y as createClient, yt as JSON_API_MEDIA_TYPE, z as IdentifierMember, zt as ApiDescriptor } from "./validate-BmyPbJCK.mjs";
+
+//#region src/errors.d.ts
+/** A single JSON:API error object (spec: error objects). */
+interface JsonApiErrorObject {
+  id?: string;
+  status?: string;
+  code?: string;
+  title?: string;
+  detail?: string;
+  source?: {
+    pointer?: string;
+    parameter?: string;
+    header?: string;
+  };
+  meta?: Record<string, unknown>;
+  /**
+   * The user-facing input path, remapped from `source.pointer` for write errors
+   * (e.g. `/data/attributes/title` -> `title`). Populated by the runtime, which
+   * built the envelope and therefore knows the inverse mapping. See CONTEXT.md.
+   */
+  path?: string;
+  /**
+   * The zero-based index of the failing operation within an atomic batch, parsed from a
+   * `source.pointer` carrying an `/atomic:operations/{n}` prefix. Populated only for atomic
+   * errors; `path` then holds the flat path within that operation's input.
+   */
+  opIndex?: number;
+}
+/**
+ * Thrown by the always-on light structural guards (ADR 0004) when a parsed response is not a
+ * JSON:API document, or a `data`/`included` member is not a resource object carrying `type`+`id`.
+ * Distinct from {@link JsonApiError} (a non-2xx server response): this signals the wire shape the
+ * runtime relies on was violated, not an application error the server reported. The opt-in
+ * per-field validator throws its engine's own error type, never this one.
+ */
+declare class StructuralGuardError extends Error {
+  constructor(message: string);
+}
+/**
+ * Thrown for any non-2xx JSON:API response. Carries the parsed error document plus
+ * expressive status matchers and pointer-grouping helpers.
+ */
+declare class JsonApiError extends Error {
+  readonly status: number;
+  readonly errors: JsonApiErrorObject[];
+  constructor(status: number, errors: JsonApiErrorObject[], message?: string);
+  hasStatus(status: number): boolean;
+  is4xx(): boolean;
+  is5xx(): boolean;
+  isBadRequest(): boolean;
+  isUnauthorized(): boolean;
+  isForbidden(): boolean;
+  isNotFound(): boolean;
+  isNotAcceptable(): boolean;
+  isConflict(): boolean;
+  isUnsupportedMediaType(): boolean;
+  isUnprocessable(): boolean;
+  /** Alias of {@link isUnprocessable} — the JSON:API validation status. */
+  isValidationError(): boolean;
+  isRateLimited(): boolean;
+  /**
+   * Group errors by user-facing input path (falls back to the raw pointer, then the
+   * query parameter). The payoff for form/validation UX — 422 `source.pointer`s are
+   * remapped to the flat shape the caller actually supplied.
+   */
+  byPath(): Record<string, JsonApiErrorObject[]>;
+}
+//#endregion
+//#region src/serialize-write.d.ts
+/**
+ * A JSON:API resource identifier in a write document: `{ type, id }` or — inside an atomic
+ * batch — `{ type, lid }` (a reference to a resource created earlier in the same transaction).
+ * May carry writable pivot meta on a to-many member.
+ */
+interface WriteIdentifier {
+  type: string;
+  id?: string;
+  lid?: string;
+  meta?: {
+    pivot: Record<string, unknown>;
+  } & Record<string, unknown>;
+}
+/** A relationship document: `{ data: <linkage> }`. */
+interface RelationshipDocument {
+  data: WriteIdentifier | WriteIdentifier[] | null;
+}
+/** The JSON:API write document {@link toDocument} produces. */
+interface WriteDocument {
+  data: {
+    type: string;
+    id?: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, RelationshipDocument>;
+  };
+}
+/** Options for {@link toDocument}. */
+interface ToDocumentOptions {
+  /**
+   * The resource id, supplied for an UPDATE (it comes from the handle, not the input). When
+   * present it is always written as `data.id`. Omit for a CREATE — then `input.id` is written
+   * only per the type's `clientId` policy.
+   */
+  id?: string;
+}
+/**
+ * Build a JSON:API write document from FLAT input. Each input key is routed via the
+ * descriptor: a declared relation -> `data.relationships[name] = { data: <linkage> }`;
+ * anything else -> `data.attributes[name]`. Relationship linkage is coerced by cardinality:
+ *
+ * - to-one accepts an identifier `{type,id}`, a materialised resource object (its `{type,id}`
+ *   are extracted), or `null` (-> `data: null`, clearing the relationship);
+ * - to-many accepts an array of those; a member may carry a `$pivot` object, rendered as the
+ *   member identifier's `meta.pivot` (writable pivot fields).
+ *
+ * `data.type` is always the accessor `type`. `data.id` is written from `opts.id` (an update),
+ * else from `input.id` only when the type's `clientId` policy allows it (omitted when
+ * `forbidden`, passed through when `optional`/`required`).
+ */
+declare function toDocument(descriptor: ApiDescriptor, type: string, input: Record<string, unknown>, opts?: ToDocumentOptions): WriteDocument;
+/**
+ * Build a relationship-mutation document `{ data: <linkage> }` for the
+ * `/{type}/{id}/relationships/{rel}` endpoints, coercing the caller's refs by cardinality:
+ *
+ * - to-one accepts an identifier `{type,id}`, a materialised resource object, or `null`
+ *   (-> `data: null`, clearing the relationship);
+ * - to-many accepts an array of those; a member may carry `$pivot`, rendered as the member
+ *   identifier's `meta.pivot`.
+ *
+ * The same {@link coerceLinkage} the whole-resource writer uses, so a relationship written
+ * standalone and one embedded in a resource serialise identically.
+ */
+declare function toRelationshipDocument(refs: unknown, cardinality: 'one' | 'many'): RelationshipDocument;
+/**
+ * Invert a write error's `source.pointer` to the caller's FLAT input path, descriptor-aware:
+ *
+ * - `/data/attributes/title`                                 -> `title`
+ * - `/data/relationships/artist/data`                        -> `artist`
+ * - `/data/id`                                               -> `id` (client-id create conflict)
+ * - `/data/attributes/releaseInfo/label`                     -> `releaseInfo.label` (nested map)
+ * - `/data/relationships/orderedTracks/data/0/meta/pivot/position` -> `orderedTracks[0].$pivot.position`
+ *
+ * Pivot values nest under a member's `meta.pivot` (symmetric with reads — see
+ * `JsonPointerBuilder::forLinkageMeta` / bundle ADR 0103), so a `meta/pivot/<field>` tail on
+ * a member of a pivot-bearing to-many is surfaced as `.$pivot.<field>`.
+ *
+ * A query-side pointer is left untouched (those are already user-facing — see
+ * {@link withRemappedPaths}). An unrecognised / non-write pointer is returned verbatim.
+ * `/data/type` and a bare `/data` are passed through (the client owns those; the caller
+ * never supplies them).
+ */
+declare function remapPointer(descriptor: ApiDescriptor, type: string, pointer: string): string;
+/**
+ * Invert a relationship-MUTATION error's `source.pointer` to the caller's flat path, for the
+ * `/{type}/{id}/relationships/{rel}` endpoints. Two pointer shapes reach here:
+ *
+ * - the LINKAGE document shape (validation on the linkage members), rooted at `data` — the
+ *   relation name is supplied by the route, not the wire:
+ *   - `/data`                             -> `<rel>`                  (to-one clear/set)
+ *   - `/data/meta/pivot/position`         -> `<rel>.$pivot.position`  (to-one pivot, rare)
+ *   - `/data/0/meta/pivot/position`       -> `<rel>[0].$pivot.position`
+ * - the RESOURCE-document shape that core's relationship prohibitions emit unchanged
+ *   (`FullReplacementProhibited`/`RemovalProhibited`/`AdditionProhibited`/
+ *   `RelationshipTypeInappropriate` all point at `/data/relationships/<name>`) — short-circuited
+ *   to the relation name (drop the `relationships/<name>` prefix) rather than treating
+ *   `relationships` as a linkage sub-segment.
+ *
+ * A non-`data` pointer is returned verbatim.
+ */
+declare function remapRelationshipPointer(rel: string, hasPivot: boolean, pointer: string): string;
+/**
+ * Return a {@link JsonApiError} with each error object's `path` populated by remapping its
+ * `source.pointer` (descriptor-aware) — so {@link JsonApiError.byPath} groups by the flat input
+ * shape. Errors with no write pointer (e.g. a `source.parameter` query-side error, or no
+ * source) are passed through unchanged. The original error is not mutated.
+ */
+declare function withRemappedPaths(error: JsonApiError, descriptor: ApiDescriptor, type: string): JsonApiError;
+/**
+ * The relationship-mutation twin of {@link withRemappedPaths}: remap each error's pointer
+ * keyed by the relation name from the route. Handles both the linkage-document shape (rooted
+ * at `data`) and the resource-document shape core's prohibition exceptions emit
+ * (`/data/relationships/<rel>`). `hasPivot` lets a member-level `meta` field surface as
+ * `$pivot`. The original error is not mutated.
+ */
+declare function withRemappedRelationshipPaths(error: JsonApiError, rel: string, hasPivot: boolean): JsonApiError;
+/**
+ * Invert an atomic-batch error's `source.pointer` to `(opIndex, flatPath)`: an atomic 422
+ * points at `/atomic:operations/{n}/data/...`, so strip the `atomic:operations/{n}` prefix to
+ * the op index, resolve that op's wire type (`typeForOp`), and delegate the remaining `/data`
+ * tail to the same {@link remapPointer} a standalone write uses (so the flat path is identical
+ * — `title`, `releaseInfo.label`, `artist`, …). A pointer without the atomic prefix is remapped
+ * verbatim under the (whole-batch) document at op index `undefined`. The original error is not
+ * mutated.
+ */
+declare function withRemappedAtomicPaths(error: JsonApiError, descriptor: ApiDescriptor, typeForOp: (opIndex: number) => string | undefined): JsonApiError;
+//#endregion
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, Page, PaginatorKind, PivotInput, ReadQuery, ReadResult, RelationDescriptor, RelationMutations, RelationName, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, materialise, mediaType, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/serialize-write.ts"],"mappings":";;;;UACiB,kBAAA;EACf,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,MAAA;IAAW,OAAA;IAAkB,SAAA;IAAoB,MAAA;EAAA;EACjD,IAAA,GAAO,MAAM;EADF;;;;;EAOX,IAAA;EAMA;;AAAO;AAUT;;EAVE,OAAA;AAAA;;;;;AAW2B;AAU7B;;cAXa,oBAAA,SAA6B,KAAK;cACjC,OAAA;AAAA;;;;;cAUD,YAAA,SAAqB,KAAA;EAAA,SACvB,MAAA;EAAA,SACA,MAAA,EAAQ,kBAAA;cAEL,MAAA,UAAgB,MAAA,EAAQ,kBAAA,IAAsB,OAAA;EAO1D,SAAA,CAAU,MAAA;EAIV,KAAA;EAIA,KAAA;EAIA,YAAA;EAIA,cAAA;EAIA,WAAA;EAIA,UAAA;EAIA,eAAA;EAIA,UAAA;EAIA,sBAAA;EAIA,eAAA;EAxBA;EA6BA,iBAAA;EAIA,aAAA;EArBA;;;;;EA8BA,MAAA,IAAU,MAAA,SAAe,kBAAA;AAAA;;;;;;;;UClFjB,eAAA;EACR,IAAA;EACA,EAAA;EACA,GAAA;EACA,IAAA;IAAS,KAAA,EAAO,MAAA;EAAA,IAA4B,MAAM;AAAA;;UAInC,oBAAA;EACf,IAAA,EAAM,eAAA,GAAkB,eAAe;AAAA;ADNZ;AAAA,UCUZ,aAAA;EACf,IAAA;IACE,IAAA;IACA,EAAA;IACA,UAAA,GAAa,MAAA;IACb,aAAA,GAAgB,MAAA,SAAe,oBAAA;EAAA;AAAA;;UAKlB,iBAAA;EDViB;;;;;ECgBhC,EAAE;AAAA;;;;;;;;;;;;;;;iBAiBY,UAAA,CACd,UAAA,EAAY,aAAA,EACZ,IAAA,UACA,KAAA,EAAO,MAAA,mBACP,IAAA,GAAO,iBAAA,GACN,aAAA;;;;;;AD+B0C;;;;AClGmB;;;iBAmHhD,sBAAA,CACd,IAAA,WACA,WAAA,mBACC,oBAAoB;;;;;;;;;AAlG6B;AAIpD;;;;;;;;AACyC;iBAwLzB,YAAA,CAAa,UAAA,EAAY,aAAa,EAAE,IAAA,UAAc,OAAA;;;;;;;;;;;;;;;;;AA/Kf;iBA+PvC,wBAAA,CAAyB,GAAA,UAAa,QAAA,WAAmB,OAAA;;;;AApPrE;AAiBJ;;iBAqPgB,iBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,IAAA,WACC,YAAA;;;;;;;;iBAWa,6BAAA,CACd,KAAA,EAAO,YAAA,EACP,GAAA,UACA,QAAA,YACC,YAAY;;;;;;;;AAnQC;AAgDhB;iBAgOgB,uBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,SAAA,GAAY,OAAA,kCACX,YAAA"}