@iamjulianacosta/mobx-data 1.0.1

package/dist/schema/types.d.ts

@@ -0,0 +1,61 @@
+/** Shape of a single `@attr` decoration on a model class property. */
+export interface AttributeDef {
+    /** Property name on the model class. */
+    name: string;
+    /** Registered transform type (e.g. `'string'`, `'number'`), or `null` for pass-through. */
+    type: string | null;
+    /** Extra options passed by the decorator (default value, etc.). */
+    options: AttributeOptions;
+    /** Discriminant – always `true`; used to narrow union types. */
+    isAttribute: true;
+}
+/** Options accepted by the `@attr` decorator. */
+export interface AttributeOptions {
+    /** Static value or factory function called when the attribute has no server value. */
+    defaultValue?: unknown | (() => unknown);
+    /** Arbitrary custom options forwarded to the transform. */
+    [key: string]: unknown;
+}
+/** Identifies the direction of a relationship from the owning model's perspective. */
+export type RelationshipKind = 'belongsTo' | 'hasMany';
+/** Shape of a single `@belongsTo` / `@hasMany` decoration on a model class property. */
+export interface RelationshipDef {
+    /** Property name on the model class. */
+    name: string;
+    /** Direction from the owning model's perspective. */
+    kind: RelationshipKind;
+    /** `modelName` of the related model. */
+    type: string;
+    /** Normalised options (async, inverse, polymorphic, …). */
+    options: RelationshipOptions;
+    /** Discriminant – always `true`; used to narrow union types. */
+    isRelationship: true;
+}
+/** Options accepted by `@belongsTo` and `@hasMany` decorators. */
+export interface RelationshipOptions {
+    /**
+     * When `true` the relationship proxy returns an `AsyncBelongsTo` / `AsyncHasMany`
+     * that must be awaited before the related record(s) are available.
+     */
+    async?: boolean;
+    /**
+     * Name of the inverse property on the related model.
+     * Set to `null` to explicitly opt out of inverse tracking.
+     */
+    inverse?: string | null;
+    /** When `true` the relationship can point to records of multiple model types. */
+    polymorphic?: boolean;
+    /** Arbitrary custom options. */
+    [key: string]: unknown;
+}
+/** Attribute definitions keyed by property name. */
+export type AttributeDefinitionsMap = Map<string, AttributeDef>;
+/** Relationship definitions keyed by property name. */
+export type RelationshipDefinitionsMap = Map<string, RelationshipDef>;
+/** Reflect-metadata key used to store attribute definitions on a prototype. */
+export declare const ATTRIBUTES_META_KEY: unique symbol;
+/** Reflect-metadata key used to store relationship definitions on a prototype. */
+export declare const RELATIONSHIPS_META_KEY: unique symbol;
+/** Reflect-metadata key used to store the registered model name on a class. */
+export declare const MODEL_NAME_META_KEY: unique symbol;
+//# sourceMappingURL=types.d.ts.map

package/dist/schema/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,mEAAmE;IACnE,OAAO,EAAE,gBAAgB,CAAC;IAC1B,gEAAgE;IAChE,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,YAAY,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IACzC,2DAA2D;IAC3D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,CAAC;AAEvD,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,gBAAgB,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,mBAAmB,CAAC;IAC7B,gEAAgE;IAChE,cAAc,EAAE,IAAI,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iFAAiF;IACjF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gCAAgC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,MAAM,uBAAuB,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAChE,uDAAuD;AACvD,MAAM,MAAM,0BAA0B,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEtE,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,eAAiC,CAAC;AAClE,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,eAAoC,CAAC;AACxE,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,eAAgC,CAAC"}

package/dist/serializer/EmbeddedRecordsMixin.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Mixin that adds support for embedded (nested) records in REST payloads.
+ *
+ * Apply with:
+ * ```ts
+ * class PostSerializer extends EmbeddedRecordsMixin(RestSerializer) {
+ *   attrs = {
+ *     comments: { embedded: 'always' },
+ *     author:   { embedded: 'always', serialize: 'records' },
+ *   };
+ * }
+ * ```
+ *
+ * ## How it works
+ *
+ * ### Deserialization
+ * When `embedded: 'always'` is set for a relationship, `normalize()` intercepts
+ * the raw payload before passing it to `super.normalize()`:
+ * - For `hasMany`: replaces the nested array with a plain id array and queues
+ *   each nested object as an `included` resource.
+ * - For `belongsTo`: replaces the nested object with the extracted id and
+ *   queues the nested object as an `included` resource.
+ *
+ * Queued resources are collected during `normalizeResponse()` and appended to
+ * `document.included` so the `Store` can push them into the identity map.
+ *
+ * ### Serialization
+ * When `serialize: 'records'` is set, `serializeHasMany` / `serializeBelongsTo`
+ * write the full related record(s) into the payload instead of just ids.
+ *
+ * ## Configuration
+ *
+ * Each entry in `attrs` is an `EmbeddedAttrConfig`:
+ * - `embedded: 'always'` — enable embedded deserialization.
+ * - `serialize: 'records'` — write full records on serialize.
+ * - `serialize: 'ids'` — write id array on serialize (default).
+ * - `serialize: false` — omit relationship from serialized payload.
+ * - `deserialize: 'records'` — same as `embedded: 'always'`.
+ * - `deserialize: false` — ignore this relationship during normalization.
+ */
+import type { RelationshipDef } from '@mobx-data/schema';
+import type { ModelClassMeta, NormalizeRequestType, NormalizedDocument, NormalizedResource, SerializerSnapshot } from './Serializer.js';
+/** Per-relationship embedding configuration. */
+export interface EmbeddedAttrConfig {
+    /** `'always'` to deserialize embedded records; `'never'` to skip. */
+    embedded?: 'always' | 'never';
+    /** `'records'` to serialize full objects; `'ids'` for ids only; `false` to omit. */
+    serialize?: 'records' | 'ids' | false;
+    /** `'records'` to deserialize embedded objects; `'ids'` for plain ids; `false` to skip. */
+    deserialize?: 'records' | 'ids' | false;
+}
+/** Map of relationship name → embedding config. */
+export interface EmbeddedRecordsAttrs {
+    [key: string]: EmbeddedAttrConfig;
+}
+/**
+ * The minimal serializer interface required by the mixin.
+ * Any class extending `JsonSerializer` satisfies this.
+ */
+export interface JsonSerializerLike {
+    attrs?: EmbeddedRecordsAttrs;
+    primaryKey: string;
+    normalize(store: unknown, modelClass: ModelClassMeta, payload: unknown, prop?: string): NormalizedResource | null;
+    normalizeResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    serialize(snapshot: SerializerSnapshot, options?: {
+        includeId?: boolean;
+    }): Record<string, unknown>;
+    serializeHasMany(snapshot: SerializerSnapshot, json: Record<string, unknown>, relationship: RelationshipDef): void;
+    serializeBelongsTo(snapshot: SerializerSnapshot, json: Record<string, unknown>, relationship: RelationshipDef): void;
+    keyForAttribute(key: string): string;
+    keyForRelationship(key: string): string;
+}
+type Constructor<T> = new (...args: any[]) => T;
+/**
+ * Returns a new class that extends `Base` with embedded-record support.
+ * `Base` must be (or extend) `JsonSerializer`.
+ */
+export declare function EmbeddedRecordsMixin<TBase extends Constructor<JsonSerializerLike>>(Base: TBase): TBase;
+export {};
+//# sourceMappingURL=EmbeddedRecordsMixin.d.ts.map

package/dist/serializer/EmbeddedRecordsMixin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddedRecordsMixin.d.ts","sourceRoot":"","sources":["../../src/serializer/EmbeddedRecordsMixin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AAEzB,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC9B,oFAAoF;IACpF,SAAS,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;IACtC,2FAA2F;IAC3F,WAAW,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;CACzC;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CACP,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,MAAM,GACZ,kBAAkB,GAAG,IAAI,CAAC;IAC7B,iBAAiB,CACf,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,MAAM,GAAG,IAAI,EACjB,WAAW,EAAE,oBAAoB,GAChC,kBAAkB,CAAC;IACtB,SAAS,CACP,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3B,gBAAgB,CACd,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,YAAY,EAAE,eAAe,GAC5B,IAAI,CAAC;IACR,kBAAkB,CAChB,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,YAAY,EAAE,eAAe,GAC5B,IAAI,CAAC;IACR,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACzC;AAGD,KAAK,WAAW,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,SAAS,WAAW,CAAC,kBAAkB,CAAC,EAC7C,IAAI,EAAE,KAAK,GAAG,KAAK,CAgJpB"}

package/dist/serializer/JsonSerializer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Flat-JSON serializer for simple REST APIs.
+ *
+ * `JsonSerializer` expects payloads to be plain JSON objects or arrays with
+ * no root-key wrapping.  It is the lowest-level concrete serializer and the
+ * base that `RestSerializer` extends.
+ *
+ * Normalization:
+ * - Array payload → `{ data: [NormalizedResource, …] }`
+ * - Object payload → `{ data: NormalizedResource }`
+ * - `null` / `undefined` → `{ data: null }`
+ *
+ * Serialization:
+ * - Iterates `@attr` → writes via `serializeAttribute`
+ * - Iterates `@belongsTo` / `@hasMany` → writes via `serializeBelongsTo` /
+ *   `serializeHasMany`
+ *
+ * `normalizeResponse` automatically dispatches to the correct per-operation
+ * hook (`normalizeFindRecordResponse`, etc.) when a subclass overrides them.
+ * If no override exists it falls through to `_buildDocument`.
+ */
+import { Serializer, type ModelClassMeta, type NormalizeRequestType, type NormalizedDocument, type NormalizedResource, type SerializerSnapshot } from './Serializer.js';
+export declare class JsonSerializer extends Serializer {
+    static dispatchMethodName(requestType: NormalizeRequestType): keyof Serializer | null;
+    /**
+     * Normalizes a single flat JSON object into a `NormalizedResource`.
+     * Returns `null` for absent or non-object payloads.
+     */
+    normalize(_store: unknown, modelClass: ModelClassMeta, payload: unknown, _prop?: string): NormalizedResource | null;
+    /**
+     * Entry point for normalization.
+     *
+     * Checks whether a subclass has overridden the relevant per-operation hook
+     * (e.g. `normalizeFindRecordResponse`).  If so, calls it; otherwise falls
+     * through to `_buildDocument`.
+     */
+    normalizeResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /**
+     * Builds a `NormalizedDocument` from a raw payload.
+     * Arrays are normalized item by item; plain objects are normalized as a
+     * single resource.
+     */
+    protected _buildDocument(store: unknown, modelClass: ModelClassMeta, payload: unknown, _id: string | null, _requestType: NormalizeRequestType): NormalizedDocument;
+    /**
+     * Serializes a snapshot to a flat JSON object.
+     * Includes `id` when `options.includeId` is `true`.
+     */
+    serialize(snapshot: SerializerSnapshot, options?: {
+        includeId?: boolean;
+    }): Record<string, unknown>;
+}
+//# sourceMappingURL=JsonSerializer.d.ts.map

package/dist/serializer/JsonSerializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonSerializer.d.ts","sourceRoot":"","sources":["../../src/serializer/JsonSerializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAC;AAEzB,qBACa,cAAe,SAAQ,UAAU;IAC5C,MAAM,CAAC,kBAAkB,CACvB,WAAW,EAAE,oBAAoB,GAChC,MAAM,UAAU,GAAG,IAAI;IAqB1B;;;OAGG;IACM,SAAS,CAChB,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,OAAO,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,kBAAkB,GAAG,IAAI;IAuB5B;;;;;;OAMG;IACM,iBAAiB,CACxB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,MAAM,GAAG,IAAI,EACjB,WAAW,EAAE,oBAAoB,GAChC,kBAAkB;IAqBrB;;;;OAIG;IACH,SAAS,CAAC,cAAc,CACtB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,YAAY,EAAE,oBAAoB,GACjC,kBAAkB;IAcrB;;;OAGG;IACM,SAAS,CAChB,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAiB3B"}

package/dist/serializer/RestSerializer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * REST serializer for root-key payloads with optional sideloading.
+ *
+ * `RestSerializer` expects the primary data to be wrapped under a root key
+ * that matches either the singular or plural model name:
+ *
+ * ```json
+ * { "post": { "id": "1", "title": "Hello" } }
+ * { "posts": [{ "id": "1", … }, { "id": "2", … }] }
+ * ```
+ *
+ * Any additional keys in the payload are treated as sideloaded (compound)
+ * data.  `meta` and `links` keys are reserved and forwarded to the document.
+ *
+ * Sideloaded types are inferred from the payload key via `modelNameFromPayloadKey`
+ * (default: singularization).
+ *
+ * Extends `JsonSerializer` so it inherits flat `normalize` and `serialize`
+ * behaviour and only overrides document-level parsing via `_buildDocument`.
+ */
+import { type ModelClassMeta, type NormalizeRequestType, type NormalizedDocument } from './Serializer.js';
+import { JsonSerializer } from './JsonSerializer.js';
+export declare class RestSerializer extends JsonSerializer {
+    /**
+     * Returns the plural payload key for a model name.
+     * e.g. `'post'` → `'posts'`
+     */
+    payloadKeyFromModelName(modelName: string): string;
+    /**
+     * Returns the model name for a payload root key.
+     * e.g. `'posts'` → `'post'`
+     */
+    modelNameFromPayloadKey(key: string): string;
+    /**
+     * Builds a `NormalizedDocument` from a root-key REST payload.
+     *
+     * - Looks for the model data under the singular or plural root key.
+     * - Treats every other non-reserved key as a sideloaded type.
+     * - Preserves `meta` and `links` from the root.
+     */
+    protected _buildDocument(store: unknown, modelClass: ModelClassMeta, payload: unknown, _id: string | null, _requestType: NormalizeRequestType): NormalizedDocument;
+}
+//# sourceMappingURL=RestSerializer.d.ts.map

package/dist/serializer/RestSerializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RestSerializer.d.ts","sourceRoot":"","sources":["../../src/serializer/RestSerializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,qBACa,cAAe,SAAQ,cAAc;IAChD;;;OAGG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIlD;;;OAGG;IACH,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI5C;;;;;;OAMG;cACgB,cAAc,CAC/B,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,YAAY,EAAE,oBAAoB,GACjC,kBAAkB;CA2EtB"}

package/dist/serializer/Serializer.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Abstract base class for all serializers.
+ *
+ * A serializer translates between the raw wire format returned by an adapter
+ * and the normalized document format consumed by the `Store`.  It also
+ * converts a record `Snapshot` back into a wire-format payload for create /
+ * update requests.
+ *
+ * ## Normalization pipeline
+ *
+ * ```
+ * raw payload
+ *   → normalizeResponse()  (dispatches to the per-operation override)
+ *     → normalizeFindRecordResponse() / normalizeQueryResponse() / …
+ *       → normalize()       (normalizes a single resource hash)
+ *         → extractId()
+ *         → extractAttributes()
+ *         → extractRelationships()
+ * → NormalizedDocument
+ * ```
+ *
+ * ## Serialization pipeline
+ *
+ * ```
+ * Snapshot
+ *   → serialize()
+ *     → serializeAttribute()    (for each @attr)
+ *     → serializeBelongsTo()    (for each @belongsTo)
+ *     → serializeHasMany()      (for each @hasMany)
+ * → wire payload object
+ * ```
+ *
+ * Subclasses (`JsonSerializer`, `RestSerializer`, `JsonApiSerializer`) override
+ * selected methods to handle their specific wire formats.
+ */
+import type { AttributeDef, RelationshipDef } from '@mobx-data/schema';
+/** Union of all request types that trigger a normalization call. */
+export type NormalizeRequestType = 'findRecord' | 'findAll' | 'findBelongsTo' | 'findHasMany' | 'findMany' | 'query' | 'queryRecord' | 'createRecord' | 'updateRecord' | 'deleteRecord';
+/**
+ * Normalized representation of a single server resource.
+ * This is the internal format understood by the `Store`.
+ */
+export interface NormalizedResource {
+    /** Model name. */
+    type: string;
+    /** Server-assigned id, or `null` for new records. */
+    id: string | null;
+    /** Flat attribute map keyed by property name. */
+    attributes?: Record<string, unknown>;
+    /**
+     * Relationship references keyed by property name.
+     * Each value contains `data` — a single `{ type, id }` or an array of them.
+     */
+    relationships?: Record<string, {
+        data: {
+            type: string;
+            id: string;
+        } | Array<{
+            type: string;
+            id: string;
+        }> | null;
+    }>;
+}
+/**
+ * Top-level normalized document returned by `normalizeResponse`.
+ * Mirrors the JSON:API document structure but is also used for REST payloads.
+ */
+export interface NormalizedDocument {
+    /** Primary resource(s), or `null` for empty responses. */
+    data: NormalizedResource | NormalizedResource[] | null;
+    /** Side-loaded or compound-document secondary resources. */
+    included?: NormalizedResource[];
+    /** Server-side metadata (pagination, total counts, etc.). */
+    meta?: Record<string, unknown>;
+    /** Pagination or related links. */
+    links?: Record<string, string>;
+}
+/**
+ * Snapshot-like interface consumed by `serialize` and the `serialize*` helpers.
+ * Serializers only read from snapshots; they never mutate records.
+ */
+export interface SerializerSnapshot {
+    /** Server-assigned id, or `null` for new records. */
+    id: string | null;
+    /** Model name. */
+    modelName: string;
+    /** Returns the snapshot-time value for an attribute key. */
+    attr(key: string): unknown;
+    /** Returns the `belongsTo` reference (or just the id when `{ id: true }`). */
+    belongsTo(key: string, options?: {
+        id: boolean;
+    }): unknown;
+    /** Returns the `hasMany` references (or just ids when `{ ids: true }`). */
+    hasMany(key: string, options?: {
+        ids: boolean;
+    }): unknown;
+    /** Returns `{ [key]: [original, current] }` pairs for dirty attributes. */
+    changedAttributes(): Record<string, [unknown, unknown]>;
+    /** Iterates over all attribute definitions. */
+    eachAttribute(fn: (key: string, meta: AttributeDef) => void): void;
+    /** Iterates over all relationship definitions. */
+    eachRelationship(fn: (key: string, meta: RelationshipDef) => void): void;
+    /** Live record reference (treated as read-only in serializer context). */
+    record: unknown;
+}
+/** Minimal model class descriptor passed to serializer methods. */
+export interface ModelClassMeta {
+    /** Registered model name. */
+    modelName: string;
+    /** Merged attribute definitions. */
+    attributes: Map<string, AttributeDef>;
+    /** Merged relationship definitions. */
+    relationships: Map<string, RelationshipDef>;
+}
+export declare abstract class Serializer {
+    /** Name of the field used as the primary key in raw payloads.  Default: `'id'`. */
+    primaryKey: string;
+    /**
+     * Normalizes a single raw resource hash into a `NormalizedResource`.
+     * Returns `null` for absent or non-object payloads.
+     */
+    abstract normalize(store: unknown, modelClass: ModelClassMeta, payload: unknown, prop?: string): NormalizedResource | null;
+    /**
+     * Entry point for normalization.  Dispatches to the appropriate
+     * `normalize*Response` method based on `requestType`, then builds the full
+     * `NormalizedDocument`.
+     */
+    abstract normalizeResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /**
+     * Serializes a record snapshot into a plain object suitable for a create
+     * or update request body.
+     */
+    abstract serialize(snapshot: SerializerSnapshot, options?: {
+        includeId?: boolean;
+    }): Record<string, unknown>;
+    /** Called when normalizing a `findRecord` response. */
+    normalizeFindRecordResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /** Called when normalizing a `findAll` response. */
+    normalizeFindAllResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /** Called when normalizing a `query` response. */
+    normalizeQueryResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /** Called when normalizing a `queryRecord` response. */
+    normalizeQueryRecordResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /** Called when normalizing a `createRecord` response. */
+    normalizeCreateRecordResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /** Called when normalizing an `updateRecord` response. */
+    normalizeUpdateRecordResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /** Called when normalizing a `deleteRecord` response. */
+    normalizeDeleteRecordResponse(store: unknown, modelClass: ModelClassMeta, payload: unknown, id: string | null, requestType: NormalizeRequestType): NormalizedDocument;
+    /**
+     * Writes a single attribute value into `json`.
+     * Default: writes `snapshot.attr(key)` under the key returned by `keyForAttribute`.
+     */
+    serializeAttribute(snapshot: SerializerSnapshot, json: Record<string, unknown>, key: string, _attribute: AttributeDef): void;
+    /**
+     * Writes a `belongsTo` relationship id into `json`.
+     * Default: writes the related record's id (or `null`) under `keyForRelationship`.
+     */
+    serializeBelongsTo(snapshot: SerializerSnapshot, json: Record<string, unknown>, relationship: RelationshipDef): void;
+    /**
+     * Writes a `hasMany` relationship id array into `json`.
+     * Default: writes the array of related ids under `keyForRelationship`.
+     */
+    serializeHasMany(snapshot: SerializerSnapshot, json: Record<string, unknown>, relationship: RelationshipDef): void;
+    /**
+     * Extracts attribute values from a raw resource hash.
+     * Returns a map of `{ propertyName: value }` using `keyForAttribute` to
+     * locate the payload key.
+     */
+    extractAttributes(modelClass: ModelClassMeta, resourceHash: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Extracts relationship references from a raw resource hash.
+     *
+     * - `belongsTo`: raw id (string or number) → `{ data: { type, id } }`
+     * - `hasMany`: array of raw ids → `{ data: [{ type, id }, …] }`
+     *
+     * Returns only the relationships whose payload keys are present in `resourceHash`.
+     */
+    extractRelationships(modelClass: ModelClassMeta, resourceHash: Record<string, unknown>): NormalizedResource['relationships'];
+    /**
+     * Extracts the primary key from a raw resource hash.
+     * Returns `null` when the key is absent.
+     */
+    extractId(_modelClass: ModelClassMeta, resourceHash: Record<string, unknown>): string | null;
+    /**
+     * Extracts field-level validation errors from a server error payload.
+     * Default: looks for `{ errors: { field: string | string[] } }`.
+     * Returns an empty object when no recognisable error structure is found.
+     */
+    extractErrors(_store: unknown, _modelClass: ModelClassMeta, payload: unknown, _id: string | null): Record<string, string[]>;
+    /**
+     * Maps a camelCase property name to the payload key used by this format.
+     * Default: identity (no transformation).
+     */
+    keyForAttribute(key: string): string;
+    /**
+     * Maps a camelCase relationship name to the payload key used by this format.
+     * Default: identity (no transformation).
+     */
+    keyForRelationship(key: string): string;
+}
+//# sourceMappingURL=Serializer.d.ts.map

package/dist/serializer/Serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.d.ts","sourceRoot":"","sources":["../../src/serializer/Serializer.ts"],"names":[],"mappings":"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"}

package/dist/serializer/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("../Serializer-95gi5edy.cjs"),e=require("../EmbeddedRecordsMixin-CBvqNdgC.cjs");exports.Serializer=r.Serializer;exports.EmbeddedRecordsMixin=e.EmbeddedRecordsMixin;Object.defineProperty(exports,"JsonSerializer",{enumerable:!0,get:()=>e.JsonSerializer});Object.defineProperty(exports,"RestSerializer",{enumerable:!0,get:()=>e.RestSerializer});
+//# sourceMappingURL=index.cjs.map

package/dist/serializer/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/serializer/index.d.ts

@@ -0,0 +1,5 @@
+export { Serializer, type NormalizedDocument, type NormalizedResource, type NormalizeRequestType, type SerializerSnapshot, type ModelClassMeta, } from './Serializer.js';
+export { RestSerializer } from './RestSerializer.js';
+export { JsonSerializer } from './JsonSerializer.js';
+export { EmbeddedRecordsMixin, type EmbeddedAttrConfig, type EmbeddedRecordsAttrs, } from './EmbeddedRecordsMixin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/serializer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/serializer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,2BAA2B,CAAC"}

package/dist/serializer/index.js

@@ -0,0 +1,9 @@
+import { S as i } from "../Serializer-FxJbsZ50.js";
+import { E as s, J as o, R as d } from "../EmbeddedRecordsMixin-VoHluHCT.js";
+export {
+  s as EmbeddedRecordsMixin,
+  o as JsonSerializer,
+  d as RestSerializer,
+  i as Serializer
+};
+//# sourceMappingURL=index.js.map

package/dist/serializer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/store/IdentityMap.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Two-level observable map that serves as the store's record cache.
+ *
+ * Records are stored in per-type buckets:
+ * ```
+ * buckets: Map<modelName, Map<id, Model>>
+ * ```
+ *
+ * The outer map is MobX-observable (shallow) so derived views like `peekAll`
+ * react when new type buckets are added.  Each inner bucket is an observable
+ * map so computed properties that iterate records within a type react to
+ * additions and deletions.
+ *
+ * All mutating methods (`set`, `delete`, `clear`) are MobX `action`s so they
+ * batch observable updates correctly.
+ */
+import type { Model } from '@mobx-data/model';
+export declare class IdentityMap {
+    /** @internal */
+    readonly _buckets: Map<string, Map<string, Model>>;
+    constructor();
+    /**
+     * Returns the bucket for `modelName`, optionally creating it when absent.
+     * Internal helper — not part of the public API.
+     */
+    private bucket;
+    /** Adds or replaces the record with the given `id` under `modelName`. */
+    set(modelName: string, id: string, record: Model): void;
+    /**
+     * Returns the record for `modelName` + `id`, or `null` when not found.
+     */
+    get(modelName: string, id: string): Model | null;
+    /** Returns `true` when a record exists for `modelName` + `id`. */
+    has(modelName: string, id: string): boolean;
+    /**
+     * Removes the record for `modelName` + `id`.
+     * @returns `true` when the record existed and was deleted.
+     */
+    delete(modelName: string, id: string): boolean;
+    /** Returns all records stored under `modelName` as an array. */
+    all(modelName: string): Model[];
+    /**
+     * Clears all records for `modelName`, or all records across all types when
+     * `modelName` is omitted.
+     */
+    clear(modelName?: string): void;
+    /**
+     * Returns the number of records stored for `modelName`, or the total across
+     * all types when `modelName` is omitted.
+     */
+    size(modelName?: string): number;
+}
+//# sourceMappingURL=IdentityMap.d.ts.map

package/dist/store/IdentityMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdentityMap.d.ts","sourceRoot":"","sources":["../../src/store/IdentityMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,qBAAa,WAAW;IACtB,gBAAgB;IAChB,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAa;;IAW/D;;;OAGG;IACH,OAAO,CAAC,MAAM;IASd,yEAAyE;IACzE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAG,IAAI;IAKvD;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAIhD,kEAAkE;IAClE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAI3C;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAI9C,gEAAgE;IAChE,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,EAAE;IAQ/B;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAU/B;;;OAGG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;CAUjC"}