@iamjulianacosta/mobx-data 1.0.1

package/src/serializer/EmbeddedRecordsMixin.ts

@@ -0,0 +1,257 @@
+/**
+ * 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;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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 function EmbeddedRecordsMixin<
+  TBase extends Constructor<JsonSerializerLike>,
+>(Base: TBase): TBase {
+  class WithEmbeddedRecords extends Base {
+    override attrs?: EmbeddedRecordsAttrs;
+
+    /** Accumulates extracted embedded resources during a `normalizeResponse` call. */
+    private pendingIncluded: NormalizedResource[] = [];
+
+    /**
+     * Intercepts raw payload hashes to extract embedded records.
+     *
+     * For each relationship configured with `embedded: 'always'`:
+     * - Recursively normalizes the embedded object(s) and adds them to
+     *   `pendingIncluded`.
+     * - Replaces the embedded value in the hash with the extracted id(s) so
+     *   `super.normalize` treats it as a plain id reference.
+     */
+    override normalize(
+      store: unknown,
+      modelClass: ModelClassMeta,
+      payload: unknown,
+      prop?: string,
+    ): NormalizedResource | null {
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        return super.normalize(store, modelClass, payload, prop);
+      }
+      const src = payload as Record<string, unknown>;
+      const attrs = this.attrs ?? {};
+      const hash: Record<string, unknown> = { ...src };
+
+      for (const [name, rel] of modelClass.relationships) {
+        const cfg = attrs[name];
+        if (!cfg || cfg.embedded !== 'always') {
+          continue;
+        }
+        const raw = hash[name];
+        if (raw === undefined || raw === null) {
+          continue;
+        }
+
+        if (rel.kind === 'hasMany' && Array.isArray(raw)) {
+          const ids: string[] = [];
+          for (const item of raw) {
+            const extracted = this.extractEmbeddedResource(store, rel, item);
+            if (extracted && extracted.id !== null) {
+              ids.push(extracted.id);
+              this.pendingIncluded.push(extracted);
+            }
+          }
+          hash[name] = ids;
+        } else if (
+          rel.kind === 'belongsTo'
+          && typeof raw === 'object'
+          && !Array.isArray(raw)
+        ) {
+          const extracted = this.extractEmbeddedResource(store, rel, raw);
+          if (extracted && extracted.id !== null) {
+            this.pendingIncluded.push(extracted);
+            hash[name] = extracted.id;
+          }
+        }
+      }
+
+      return super.normalize(store, modelClass, hash, prop);
+    }
+
+    /**
+     * Resets `pendingIncluded`, delegates to `super.normalizeResponse`, then
+     * appends any extracted embedded resources to `document.included`.
+     */
+    override normalizeResponse(
+      store: unknown,
+      modelClass: ModelClassMeta,
+      payload: unknown,
+      id: string | null,
+      requestType: NormalizeRequestType,
+    ): NormalizedDocument {
+      this.pendingIncluded = [];
+      const doc = super.normalizeResponse(store, modelClass, payload, id, requestType);
+      if (this.pendingIncluded.length > 0) {
+        const included = doc.included ? [...doc.included] : [];
+        included.push(...this.pendingIncluded);
+        doc.included = included;
+        this.pendingIncluded = [];
+      }
+      return doc;
+    }
+
+    /**
+     * When `serialize: 'records'` is configured, writes the full related
+     * record objects instead of just ids.
+     */
+    override serializeHasMany(
+      snapshot: SerializerSnapshot,
+      json: Record<string, unknown>,
+      relationship: RelationshipDef,
+    ): void {
+      const cfg = this.attrs?.[relationship.name];
+      if (cfg?.serialize === 'records') {
+        const records = snapshot.hasMany(relationship.name) as unknown[];
+        json[this.keyForRelationship(relationship.name)] = records ?? [];
+        return;
+      }
+      super.serializeHasMany(snapshot, json, relationship);
+    }
+
+    /**
+     * When `serialize: 'records'` is configured, writes the full related
+     * record object instead of just the id.
+     */
+    override serializeBelongsTo(
+      snapshot: SerializerSnapshot,
+      json: Record<string, unknown>,
+      relationship: RelationshipDef,
+    ): void {
+      const cfg = this.attrs?.[relationship.name];
+      if (cfg?.serialize === 'records') {
+        const record = snapshot.belongsTo(relationship.name);
+        json[this.keyForRelationship(relationship.name)] = record ?? null;
+        return;
+      }
+      super.serializeBelongsTo(snapshot, json, relationship);
+    }
+
+    /**
+     * Normalizes a single embedded resource object using the related model's
+     * type as a placeholder `ModelClassMeta`.
+     */
+    private extractEmbeddedResource(
+      store: unknown,
+      rel: RelationshipDef,
+      item: unknown,
+    ): NormalizedResource | null {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) {
+        return null;
+      }
+      const embeddedClass: ModelClassMeta = {
+        modelName: rel.type,
+        attributes: new Map(),
+        relationships: new Map(),
+      };
+      return this.normalize(store, embeddedClass, item);
+    }
+  }
+  return WithEmbeddedRecords as unknown as TBase;
+}

package/src/serializer/JsonSerializer.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 { injectable } from 'tsyringe';
+import {
+  Serializer,
+  type ModelClassMeta,
+  type NormalizeRequestType,
+  type NormalizedDocument,
+  type NormalizedResource,
+  type SerializerSnapshot,
+} from './Serializer.js';
+
+@injectable()
+export class JsonSerializer extends Serializer {
+  static dispatchMethodName(
+    requestType: NormalizeRequestType,
+  ): keyof Serializer | null {
+    switch (requestType) {
+      case 'findRecord':
+        return 'normalizeFindRecordResponse';
+      case 'findAll':
+        return 'normalizeFindAllResponse';
+      case 'query':
+        return 'normalizeQueryResponse';
+      case 'queryRecord':
+        return 'normalizeQueryRecordResponse';
+      case 'createRecord':
+        return 'normalizeCreateRecordResponse';
+      case 'updateRecord':
+        return 'normalizeUpdateRecordResponse';
+      case 'deleteRecord':
+        return 'normalizeDeleteRecordResponse';
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Normalizes a single flat JSON object into a `NormalizedResource`.
+   * Returns `null` for absent or non-object payloads.
+   */
+  override normalize(
+    _store: unknown,
+    modelClass: ModelClassMeta,
+    payload: unknown,
+    _prop?: string,
+  ): NormalizedResource | null {
+    if (payload === null || payload === undefined) {
+      return null;
+    }
+    if (typeof payload !== 'object') {
+      return null;
+    }
+    const hash = payload as Record<string, unknown>;
+    const id = this.extractId(modelClass, hash);
+    const attributes = this.extractAttributes(modelClass, hash);
+    const relationships = this.extractRelationships(modelClass, hash);
+
+    const resource: NormalizedResource = {
+      type: modelClass.modelName,
+      id,
+      attributes,
+    };
+    if (relationships && Object.keys(relationships).length > 0) {
+      resource.relationships = relationships;
+    }
+    return resource;
+  }
+
+  /**
+   * 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`.
+   */
+  override normalizeResponse(
+    store: unknown,
+    modelClass: ModelClassMeta,
+    payload: unknown,
+    id: string | null,
+    requestType: NormalizeRequestType,
+  ): NormalizedDocument {
+    const methodName = JsonSerializer.dispatchMethodName(requestType);
+    if (methodName) {
+      const override = (this as unknown as Record<string, unknown>)[methodName];
+      const baseImpl = (Serializer.prototype as unknown as Record<string, unknown>)[
+        methodName
+      ];
+      if (typeof override === 'function' && override !== baseImpl) {
+        return (override as (...args: unknown[]) => NormalizedDocument).call(
+          this,
+          store,
+          modelClass,
+          payload,
+          id,
+          requestType,
+        );
+      }
+    }
+    return this._buildDocument(store, modelClass, payload, id, requestType);
+  }
+
+  /**
+   * 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 {
+    if (payload === null || payload === undefined) {
+      return { data: null };
+    }
+    if (Array.isArray(payload)) {
+      const data = payload
+        .map((p) => this.normalize(store, modelClass, p))
+        .filter((r): r is NormalizedResource => r !== null);
+      return { data };
+    }
+    const data = this.normalize(store, modelClass, payload);
+    return { data };
+  }
+
+  /**
+   * Serializes a snapshot to a flat JSON object.
+   * Includes `id` when `options.includeId` is `true`.
+   */
+  override serialize(
+    snapshot: SerializerSnapshot,
+    options?: { includeId?: boolean },
+  ): Record<string, unknown> {
+    const json: Record<string, unknown> = {};
+    if (options?.includeId && snapshot.id !== null) {
+      json[this.primaryKey] = snapshot.id;
+    }
+    snapshot.eachAttribute((key, meta) => {
+      this.serializeAttribute(snapshot, json, key, meta);
+    });
+    snapshot.eachRelationship((_key, rel) => {
+      if (rel.kind === 'belongsTo') {
+        this.serializeBelongsTo(snapshot, json, rel);
+      } else {
+        this.serializeHasMany(snapshot, json, rel);
+      }
+    });
+    return json;
+  }
+}

package/src/serializer/RestSerializer.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 { injectable } from 'tsyringe';
+import pluralize from 'pluralize';
+import {
+  type ModelClassMeta,
+  type NormalizeRequestType,
+  type NormalizedDocument,
+  type NormalizedResource,
+} from './Serializer.js';
+import { JsonSerializer } from './JsonSerializer.js';
+
+@injectable()
+export class RestSerializer extends JsonSerializer {
+  /**
+   * Returns the plural payload key for a model name.
+   * e.g. `'post'` → `'posts'`
+   */
+  payloadKeyFromModelName(modelName: string): string {
+    return pluralize.plural(modelName);
+  }
+
+  /**
+   * Returns the model name for a payload root key.
+   * e.g. `'posts'` → `'post'`
+   */
+  modelNameFromPayloadKey(key: string): string {
+    return pluralize.singular(key);
+  }
+
+  /**
+   * 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 override _buildDocument(
+    store: unknown,
+    modelClass: ModelClassMeta,
+    payload: unknown,
+    _id: string | null,
+    _requestType: NormalizeRequestType,
+  ): NormalizedDocument {
+    if (payload === null || payload === undefined || typeof payload !== 'object') {
+      return { data: null };
+    }
+    const hash = payload as Record<string, unknown>;
+    const singular = modelClass.modelName;
+    const plural = this.payloadKeyFromModelName(singular);
+
+    let data: NormalizedResource | NormalizedResource[] | null = null;
+    const primaryKeys = new Set<string>();
+
+    if (singular in hash) {
+      primaryKeys.add(singular);
+      const raw = hash[singular];
+      if (Array.isArray(raw)) {
+        data = raw
+          .map((entry) => this.normalize(store, modelClass, entry))
+          .filter((resource): resource is NormalizedResource => resource !== null);
+      } else {
+        data = this.normalize(store, modelClass, raw);
+      }
+    } else if (plural in hash) {
+      primaryKeys.add(plural);
+      const raw = hash[plural];
+      if (Array.isArray(raw)) {
+        data = raw
+          .map((entry) => this.normalize(store, modelClass, entry))
+          .filter((resource): resource is NormalizedResource => resource !== null);
+      } else {
+        data = this.normalize(store, modelClass, raw);
+      }
+    }
+
+    // Collect sideloaded records from all remaining root keys.
+    const included: NormalizedResource[] = [];
+    for (const [key, value] of Object.entries(hash)) {
+      if (primaryKeys.has(key)) {
+        continue;
+      }
+      if (key === 'meta' || key === 'links') {
+        continue;
+      }
+      const sideloadType = this.modelNameFromPayloadKey(key);
+      const sideloadClass: ModelClassMeta = {
+        modelName: sideloadType,
+        attributes: new Map(),
+        relationships: new Map(),
+      };
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          const normalized = this.normalize(store, sideloadClass, item);
+          if (normalized) {
+            included.push(normalized);
+          }
+        }
+      } else if (value && typeof value === 'object') {
+        const normalized = this.normalize(store, sideloadClass, value);
+        if (normalized) {
+          included.push(normalized);
+        }
+      }
+    }
+
+    const doc: NormalizedDocument = { data };
+    if (included.length > 0) {
+      doc.included = included;
+    }
+    if (hash.meta && typeof hash.meta === 'object') {
+      doc.meta = hash.meta as Record<string, unknown>;
+    }
+    if (hash.links && typeof hash.links === 'object') {
+      doc.links = hash.links as Record<string, string>;
+    }
+    return doc;
+  }
+}