@iamjulianacosta/mobx-data 1.0.1

package/src/adapter/MemoryAdapter.ts

@@ -0,0 +1,216 @@
+/**
+ * In-memory adapter for testing and server-side rendering.
+ *
+ * `MemoryAdapter` stores records in plain `Map` structures with no network I/O.
+ * It implements the full adapter interface (findRecord, findAll, findMany, query,
+ * queryRecord, createRecord, updateRecord, deleteRecord) so it can serve as a
+ * drop-in replacement for `RestAdapter` in unit tests or SSR hydration scenarios.
+ *
+ * Use `seed()` to pre-populate data and `reset()` to clear all state between
+ * test cases.
+ */
+
+import { injectable } from 'tsyringe';
+import { Adapter, type AdapterSnapshot } from './Adapter.js';
+
+interface MemoryRecord {
+  id: string;
+  type: string;
+  attributes: Record<string, unknown>;
+}
+
+@injectable()
+export class MemoryAdapter extends Adapter {
+  private storage: Map<string, Map<string, MemoryRecord>> = new Map();
+
+  private nextId: Map<string, number> = new Map();
+
+  private getCollection(modelName: string): Map<string, MemoryRecord> {
+    let collection = this.storage.get(modelName);
+    if (!collection) {
+      collection = new Map();
+      this.storage.set(modelName, collection);
+    }
+    return collection;
+  }
+
+  private generateId(modelName: string): string {
+    const current = this.nextId.get(modelName) ?? 1;
+    this.nextId.set(modelName, current + 1);
+    return String(current);
+  }
+
+  /**
+   * Pre-populates the adapter with records for a given model type.
+   * Auto-increments the internal ID counter to avoid collisions with
+   * subsequently created records.
+   *
+   * @param modelName - The model type to seed.
+   * @param records - Array of plain objects; each must have an `id` key.
+   */
+  seed(modelName: string, records: Array<{ id: string; [key: string]: unknown }>): void {
+    const collection = this.getCollection(modelName);
+    for (const record of records) {
+      const { id, ...attributes } = record;
+      collection.set(id, { id, type: modelName, attributes });
+      const numId = Number(id);
+      if (!Number.isNaN(numId)) {
+        const current = this.nextId.get(modelName) ?? 1;
+        if (numId >= current) {
+          this.nextId.set(modelName, numId + 1);
+        }
+      }
+    }
+  }
+
+  /** Clears all stored records and resets ID counters. */
+  reset(): void {
+    this.storage.clear();
+    this.nextId.clear();
+  }
+
+  override async findRecord(
+    _store: unknown,
+    modelName: string,
+    id: string,
+  ): Promise<unknown> {
+    const collection = this.getCollection(modelName);
+    const record = collection.get(id);
+    if (!record) {
+      throw Object.assign(
+        new Error(`Record not found: ${modelName}:${id}`),
+        { status: 404 },
+      );
+    }
+    return { data: { id: record.id, type: record.type, attributes: { ...record.attributes } } };
+  }
+
+  override async findAll(
+    _store: unknown,
+    modelName: string,
+  ): Promise<unknown> {
+    const collection = this.getCollection(modelName);
+    const data = Array.from(collection.values()).map((record) => ({
+      id: record.id,
+      type: record.type,
+      attributes: { ...record.attributes },
+    }));
+    return { data };
+  }
+
+  override async findMany(
+    _store: unknown,
+    modelName: string,
+    ids: string[],
+  ): Promise<unknown> {
+    const collection = this.getCollection(modelName);
+    const data = ids
+      .map((id) => collection.get(id))
+      .filter((record): record is MemoryRecord => record !== undefined)
+      .map((record) => ({
+        id: record.id,
+        type: record.type,
+        attributes: { ...record.attributes },
+      }));
+    return { data };
+  }
+
+  /** Filters records by exact attribute match on all query keys. */
+  override async query(
+    _store: unknown,
+    modelName: string,
+    query: Record<string, unknown>,
+  ): Promise<unknown> {
+    const collection = this.getCollection(modelName);
+    const entries = Array.from(collection.values());
+    const filtered = entries.filter((record) => {
+      for (const [key, value] of Object.entries(query)) {
+        if (record.attributes[key] !== value) {
+          return false;
+        }
+      }
+      return true;
+    });
+    const data = filtered.map((record) => ({
+      id: record.id,
+      type: record.type,
+      attributes: { ...record.attributes },
+    }));
+    return { data };
+  }
+
+  /** Returns the first record matching the query, or `null`. */
+  override async queryRecord(
+    _store: unknown,
+    modelName: string,
+    query: Record<string, unknown>,
+  ): Promise<unknown> {
+    const result = await this.query(_store, modelName, query) as { data: unknown[] };
+    return { data: result.data[0] ?? null };
+  }
+
+  private static safeAssign(
+    target: Record<string, unknown>,
+    source: Record<string, unknown>,
+  ): void {
+    for (const [key, value] of Object.entries(source)) {
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+        continue;
+      }
+      target[key] = value;
+    }
+  }
+
+  override async createRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const id = this.generateId(modelName);
+    const attributes: Record<string, unknown> = {};
+    const record = snapshot.record as { _data?: Record<string, unknown> };
+    if (record._data) {
+      MemoryAdapter.safeAssign(attributes, record._data);
+    }
+    const entry: MemoryRecord = { id, type: modelName, attributes };
+    this.getCollection(modelName).set(id, entry);
+    return { data: { id, type: modelName, attributes: { ...attributes } } };
+  }
+
+  override async updateRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const { id } = snapshot;
+    if (!id) {
+      throw new Error('Cannot update a record without an id');
+    }
+    const collection = this.getCollection(modelName);
+    const existing = collection.get(id);
+    if (!existing) {
+      throw Object.assign(
+        new Error(`Record not found: ${modelName}:${id}`),
+        { status: 404 },
+      );
+    }
+    const record = snapshot.record as { _data?: Record<string, unknown> };
+    if (record._data) {
+      MemoryAdapter.safeAssign(existing.attributes, record._data);
+    }
+    return { data: { id, type: modelName, attributes: { ...existing.attributes } } };
+  }
+
+  override async deleteRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const { id } = snapshot;
+    if (!id) {
+      throw new Error('Cannot delete a record without an id');
+    }
+    this.getCollection(modelName).delete(id);
+    return null;
+  }
+}

package/src/adapter/RestAdapter.ts

@@ -0,0 +1,248 @@
+/**
+ * HTTP/REST adapter that communicates with a JSON REST API.
+ *
+ * `RestAdapter` is the default concrete adapter.  It uses the Fetch API and
+ * maps each store operation to a conventional HTTP verb:
+ *
+ * | Operation      | Method |
+ * |----------------|--------|
+ * | findRecord     | GET    |
+ * | findAll        | GET    |
+ * | findMany       | GET    |
+ * | query          | GET    |
+ * | queryRecord    | GET    |
+ * | createRecord   | POST   |
+ * | updateRecord   | PUT    |
+ * | deleteRecord   | DELETE |
+ *
+ * Subclasses (e.g. `JsonApiAdapter`, `ODataAdapter`) override individual
+ * methods to adjust headers, HTTP verbs, or body serialization without
+ * reimplementing the full adapter.
+ */
+
+import { injectable } from 'tsyringe';
+import { Adapter, type AdapterSnapshot } from './Adapter.js';
+
+@injectable()
+export class RestAdapter extends Adapter {
+  static serializeSnapshotToObject(
+    snapshot: AdapterSnapshot,
+  ): Record<string, unknown> {
+    const body: Record<string, unknown> = {};
+    const record = snapshot.record as { _data?: Record<string, unknown> };
+    const data = record._data;
+    if (data) {
+      for (const [key, value] of Object.entries(data)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+          continue;
+        }
+        body[key] = value;
+      }
+    }
+    return body;
+  }
+
+  static toQueryString(query: Record<string, unknown>): string {
+    const parts: string[] = [];
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) {
+        continue;
+      }
+      parts.push(
+        `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`,
+      );
+    }
+    return parts.length > 0 ? `?${parts.join('&')}` : '';
+  }
+
+  /** Headers sent with every read (GET) request. */
+  defaultHeaders(): Record<string, string> {
+    return {
+      Accept: 'application/json',
+      ...this.headers,
+    };
+  }
+
+  /** Headers sent with every write (POST / PUT / DELETE) request. */
+  mutationHeaders(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      ...this.defaultHeaders(),
+    };
+  }
+
+  /**
+   * Low-level fetch wrapper used by all operation methods.
+   *
+   * - Throws an enriched `Error` (with `status` and `body` properties) for
+   *   any non-2xx response.
+   * - Returns `null` for 204 No Content responses.
+   * - Attempts JSON parsing; falls back to the raw text string on failure.
+   */
+  async _fetchJSON(
+    url: string,
+    init: RequestInit,
+  ): Promise<unknown> {
+    const response = await fetch(url, init);
+    if (!response.ok) {
+      let body: unknown = null;
+      try {
+        body = await response.json();
+      } catch {
+        /* ignore */
+      }
+      const error = Object.assign(
+        new Error(`Request failed: ${response.status}`),
+        { status: response.status, body },
+      );
+      throw error;
+    }
+    if (response.status === 204) {
+      return null;
+    }
+    const text = await response.text();
+    if (!text) {
+      return null;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  override async findRecord(
+    _store: unknown,
+    modelName: string,
+    id: string,
+    snapshot: AdapterSnapshot,
+    options?: { include?: string },
+  ): Promise<unknown> {
+    let url = this.buildURL(modelName, id, snapshot, 'findRecord');
+    if (options?.include) {
+      url += `${url.includes('?') ? '&' : '?'}include=${encodeURIComponent(options.include)}`;
+    }
+    return this._fetchJSON(url, {
+      method: 'GET',
+      headers: this.defaultHeaders(),
+    });
+  }
+
+  override async findAll(
+    _store: unknown,
+    modelName: string,
+    _sinceToken: string | null,
+    snapshotArray: AdapterSnapshot[],
+    options?: { include?: string },
+  ): Promise<unknown> {
+    let url = this.buildURL(modelName, null, snapshotArray, 'findAll');
+    if (options?.include) {
+      url += `${url.includes('?') ? '&' : '?'}include=${encodeURIComponent(options.include)}`;
+    }
+    return this._fetchJSON(url, {
+      method: 'GET',
+      headers: this.defaultHeaders(),
+    });
+  }
+
+  /**
+   * Fetches multiple records by appending an `ids` query parameter.
+   * e.g. `/posts?ids=1,2,3`
+   */
+  override async findMany(
+    _store: unknown,
+    modelName: string,
+    ids: string[],
+    snapshots: AdapterSnapshot[],
+  ): Promise<unknown> {
+    const url = this.buildURL(modelName, ids, snapshots, 'findMany');
+    const separator = url.includes('?') ? '&' : '?';
+    const fullUrl = `${url}${separator}ids=${ids.map(encodeURIComponent).join(',')}`;
+    return this._fetchJSON(fullUrl, {
+      method: 'GET',
+      headers: this.defaultHeaders(),
+    });
+  }
+
+  override async query(
+    _store: unknown,
+    modelName: string,
+    query: Record<string, unknown>,
+  ): Promise<unknown> {
+    const base = this.buildURL(modelName, null, null, 'query', query);
+    const url = `${base}${RestAdapter.toQueryString(query)}`;
+    return this._fetchJSON(url, {
+      method: 'GET',
+      headers: this.defaultHeaders(),
+    });
+  }
+
+  override async queryRecord(
+    _store: unknown,
+    modelName: string,
+    query: Record<string, unknown>,
+  ): Promise<unknown> {
+    const base = this.buildURL(modelName, null, null, 'queryRecord', query);
+    const url = `${base}${RestAdapter.toQueryString(query)}`;
+    return this._fetchJSON(url, {
+      method: 'GET',
+      headers: this.defaultHeaders(),
+    });
+  }
+
+  override async createRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const url = this.buildURL(modelName, null, snapshot, 'createRecord');
+    return this._fetchJSON(url, {
+      method: 'POST',
+      headers: this.mutationHeaders(),
+      body: JSON.stringify(RestAdapter.serializeSnapshotToObject(snapshot)),
+    });
+  }
+
+  override async updateRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const url = this.buildURL(modelName, snapshot.id, snapshot, 'updateRecord');
+    return this._fetchJSON(url, {
+      method: 'PUT',
+      headers: this.mutationHeaders(),
+      body: JSON.stringify(RestAdapter.serializeSnapshotToObject(snapshot)),
+    });
+  }
+
+  override async patchRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const url = this.buildURL(modelName, snapshot.id, snapshot, 'updateRecord');
+    const changed = snapshot.changedAttributes();
+    const partial: Record<string, unknown> = {};
+    for (const [key, [, current]] of Object.entries(changed)) {
+      partial[key] = current;
+    }
+    return this._fetchJSON(url, {
+      method: 'PATCH',
+      headers: this.mutationHeaders(),
+      body: JSON.stringify(partial),
+    });
+  }
+
+  override async deleteRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const url = this.buildURL(modelName, snapshot.id, snapshot, 'deleteRecord');
+    return this._fetchJSON(url, {
+      method: 'DELETE',
+      headers: this.defaultHeaders(),
+    });
+  }
+}

package/src/adapter/index.ts

@@ -0,0 +1,7 @@
+export {
+  Adapter,
+  type AdapterRequestType,
+  type AdapterSnapshot,
+} from './Adapter.js';
+export { RestAdapter } from './RestAdapter.js';
+export { MemoryAdapter } from './MemoryAdapter.js';

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from './schema/index.js';
+export * from './model/index.js';
+export {
+  Store,
+  type AdapterLike,
+  type SerializerLike,
+  type FindOptions,
+  IdentityMap,
+  RecordArray,
+  AdapterPopulatedRecordArray,
+} from './store/index.js';
+export * from './adapter/index.js';
+export * from './serializer/index.js';
+export * from './transforms/index.js';
+export * from './request/index.js';
+export * from './json-api/index.js';
+export * from './odata/index.js';

package/src/json-api/JsonApiAdapter.ts

@@ -0,0 +1,93 @@
+/**
+ * Adapter that implements the [JSON:API](https://jsonapi.org) specification.
+ *
+ * Extends `RestAdapter` with the following differences:
+ *
+ * - **MIME types** — `Accept` and `Content-Type` headers are set to
+ *   `application/vnd.api+json` as required by the spec.
+ * - **PATCH for updates** — `updateRecord` uses `PATCH` instead of `PUT`.
+ * - **`coalesceFindRequests: true`** — the store coalesces separate
+ *   `findRecord` calls into a single `findMany` request.
+ *
+ * URL construction is inherited from `RestAdapter` / `Adapter` unchanged;
+ * override `pathForType` or `urlFor*` methods to customize.
+ */
+
+import { injectable } from 'tsyringe';
+import { RestAdapter, type AdapterSnapshot } from '@mobx-data/adapter';
+
+@injectable()
+export class JsonApiAdapter extends RestAdapter {
+  /** Always coalesce `findRecord` calls into a single `findMany` request. */
+  override coalesceFindRequests = true;
+
+  /** Returns JSON:API `Accept` header alongside any custom headers. */
+  override defaultHeaders(): Record<string, string> {
+    return {
+      Accept: 'application/vnd.api+json',
+      ...this.headers,
+    };
+  }
+
+  /** Returns JSON:API `Content-Type` header for mutation requests. */
+  override mutationHeaders(): Record<string, string> {
+    return {
+      'Content-Type': 'application/vnd.api+json',
+      ...this.defaultHeaders(),
+    };
+  }
+
+  /**
+   * Sends a PATCH request to update a record (JSON:API mandates PATCH, not PUT).
+   */
+  override async updateRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const url = this.buildURL(modelName, snapshot.id, snapshot, 'updateRecord');
+    return this._fetchJSON(url, {
+      method: 'PATCH',
+      headers: this.mutationHeaders(),
+      body: JSON.stringify(this._serializeForUpdate(snapshot)),
+    });
+  }
+
+  /**
+   * Sends a PATCH request with only the changed attributes (partial update).
+   * Produces a JSON:API document with only the dirty attribute keys.
+   */
+  override async patchRecord(
+    _store: unknown,
+    modelName: string,
+    snapshot: AdapterSnapshot,
+  ): Promise<unknown> {
+    const url = this.buildURL(modelName, snapshot.id, snapshot, 'updateRecord');
+    const changed = snapshot.changedAttributes();
+    const attributes: Record<string, unknown> = {};
+    for (const [key, [, current]] of Object.entries(changed)) {
+      attributes[key] = current;
+    }
+    const body = {
+      data: {
+        type: modelName,
+        id: snapshot.id,
+        attributes,
+      },
+    };
+    return this._fetchJSON(url, {
+      method: 'PATCH',
+      headers: this.mutationHeaders(),
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Extracts the raw data object from the snapshot for use as the PATCH body.
+   * Subclasses may override this to produce a full JSON:API `{ data: … }` document.
+   */
+  protected _serializeForUpdate(snapshot: AdapterSnapshot): Record<string, unknown> {
+    const rec = snapshot.record as { _data?: Record<string, unknown> };
+    return rec._data ? { ...rec._data } : {};
+  }
+}