@iamjulianacosta/mobx-data 1.0.1

package/src/odata/ODataAdapter.ts

@@ -0,0 +1,245 @@
+import { injectable } from 'tsyringe';
+import pluralize from 'pluralize';
+import { pascalCase } from 'change-case';
+import { RestAdapter } from '@mobx-data/adapter';
+import type { AdapterSnapshot } from '@mobx-data/adapter';
+
+/** All OData v4 system query option names (both bare and $-prefixed forms are checked). */
+const ODATA_SYSTEM_QUERY_OPTIONS = new Set([
+  '$filter',
+  '$select',
+  '$orderby',
+  '$top',
+  '$skip',
+  '$expand',
+  '$count',
+  '$search',
+  '$format',
+  '$skiptoken',
+]);
+
+/**
+ * OData v4 adapter.
+ *
+ * Extends `RestAdapter` with OData-specific conventions:
+ * - Entity-set names are PascalCase plural (`user` → `Users`).
+ * - Single-entity URLs use key-in-parentheses syntax (`Users(1)`, `Users('abc')`).
+ * - Mutations use PATCH instead of PUT.
+ * - Accept / Content-Type headers carry the `odata.metadata=minimal` parameter.
+ * - System query options (`$filter`, `$expand`, etc.) are passed through verbatim;
+ *   bare names are auto-prefixed (`filter` → `$filter`).
+ */
+@injectable()
+export class ODataAdapter extends RestAdapter {
+  /** OData protocol version sent in `OData-Version` and `OData-MaxVersion` headers. */
+  odataVersion: string = '4.0';
+
+  static isNumericKey(id: string): boolean {
+    return /^-?\d+(?:\.\d+)?$/.test(id);
+  }
+
+  static escapeODataString(value: string): string {
+    return value.replace(/'/g, "''");
+  }
+
+  override defaultHeaders(): Record<string, string> {
+    return {
+      Accept: 'application/json;odata.metadata=minimal',
+      'OData-Version': this.odataVersion,
+      'OData-MaxVersion': this.odataVersion,
+      ...this.headers,
+    };
+  }
+
+  override mutationHeaders(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json;odata.metadata=minimal',
+      ...this.defaultHeaders(),
+    };
+  }
+
+  /**
+   * Maps a camelCase/dasherized model name to a PascalCase plural entity-set name.
+   * @example `pathForType('orderItem')` → `'OrderItems'`
+   */
+  override pathForType(modelName: string): string {
+    return pascalCase(pluralize.plural(modelName));
+  }
+
+  /**
+   * Encodes a record id as an OData key literal.
+   * Numeric ids are returned bare (`1`); string ids are single-quoted with
+   * inner apostrophes escaped (`o'brien` → `'o''brien'`).
+   *
+   * Override this method when the service uses a non-default key format (e.g. GUIDs).
+   */
+  encodeKey(id: string): string {
+    if (ODataAdapter.isNumericKey(id)) {
+      return id;
+    }
+    return `'${ODataAdapter.escapeODataString(id)}'`;
+  }
+
+  override urlForFindRecord(
+    id: string,
+    modelName: string,
+    _snapshot: AdapterSnapshot,
+  ): string {
+    return this._composeURL(`${this.pathForType(modelName)}(${this.encodeKey(id)})`);
+  }
+
+  override urlForUpdateRecord(
+    id: string,
+    modelName: string,
+    _snapshot: AdapterSnapshot,
+  ): string {
+    return this._composeURL(`${this.pathForType(modelName)}(${this.encodeKey(id)})`);
+  }
+
+  override urlForDeleteRecord(
+    id: string,
+    modelName: string,
+    _snapshot: AdapterSnapshot,
+  ): string {
+    return this._composeURL(`${this.pathForType(modelName)}(${this.encodeKey(id)})`);
+  }
+
+  /**
+   * Fetches multiple records by id using a single request.
+   * Builds a `$filter=id eq X or id eq Y` expression so only one HTTP round-trip
+   * is needed regardless of how many ids are requested.
+   */
+  override async findMany(
+    _store: unknown,
+    modelName: string,
+    ids: string[],
+    snapshots: AdapterSnapshot[],
+  ): Promise<unknown> {
+    const base = this.buildURL(modelName, ids, snapshots, 'findMany');
+    const filter = ids.map((id) => `id eq ${this.encodeKey(id)}`).join(' or ');
+    const url = `${base}?${this._toQueryString({ $filter: filter })}`;
+    return this._fetchJSON(url, {
+      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 normalized = this._normalizeQuery(query);
+    const url = `${base}${this._appendQuery(normalized)}`;
+    return this._fetchJSON(url, {
+      method: 'GET',
+      headers: this.defaultHeaders(),
+    });
+  }
+
+  /**
+   * Queries for a single record by appending `$top=1` to whatever filter is provided.
+   * The caller is responsible for picking the first element from the returned `value` array.
+   */
+  override async queryRecord(
+    _store: unknown,
+    modelName: string,
+    query: Record<string, unknown>,
+  ): Promise<unknown> {
+    const base = this.buildURL(modelName, null, null, 'queryRecord', query);
+    const normalized = { ...this._normalizeQuery(query), $top: 1 };
+    const url = `${base}${this._appendQuery(normalized)}`;
+    return this._fetchJSON(url, {
+      method: 'GET',
+      headers: this.defaultHeaders(),
+    });
+  }
+
+  /** Sends a PATCH request (partial update) as required by the OData v4 spec. */
+  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._serializeSnapshot(snapshot)),
+    });
+  }
+
+  /** Sends a PATCH request with only the changed attributes (partial update). */
+  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),
+    });
+  }
+
+  /** Extracts the raw attribute map from the snapshot's internal record. */
+  protected _serializeSnapshot(snapshot: AdapterSnapshot): Record<string, unknown> {
+    const record = snapshot.record as { _data?: Record<string, unknown> };
+    const data = record._data;
+    const body: Record<string, unknown> = {};
+    if (data) {
+      Object.assign(body, data);
+    }
+    return body;
+  }
+
+  /**
+   * Normalises a query hash so every OData system option has its `$` prefix.
+   * Bare names (`filter`, `top`, `expand`) are prefixed automatically.
+   * Custom (non-system) keys are forwarded verbatim.
+   * `null` and `undefined` values are dropped.
+   */
+  protected _normalizeQuery(
+    query: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const normalized: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) {
+        continue;
+      }
+      if (ODATA_SYSTEM_QUERY_OPTIONS.has(key)) {
+        normalized[key] = value;
+      } else if (ODATA_SYSTEM_QUERY_OPTIONS.has(`$${key}`)) {
+        normalized[`$${key}`] = value;
+      } else {
+        normalized[key] = value;
+      }
+    }
+    return normalized;
+  }
+
+  /** Serialises a key→value map to a `key=value&…` query string (percent-encoded). */
+  protected _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.join('&');
+  }
+
+  /** Returns `?key=value&…` when the query is non-empty, or an empty string. */
+  protected _appendQuery(query: Record<string, unknown>): string {
+    const queryString = this._toQueryString(query);
+    return queryString ? `?${queryString}` : '';
+  }
+}

package/src/odata/index.ts

@@ -0,0 +1 @@
+export { ODataAdapter } from './ODataAdapter.js';

package/src/request/CacheHandler.ts

@@ -0,0 +1,125 @@
+/**
+ * In-memory caching handler for the request pipeline.
+ *
+ * `CacheHandler` is registered via `RequestManager.useCache()` so it always
+ * runs first in the chain.  It caches `GET` responses and replays them on
+ * subsequent requests with the same key — unless `cacheOptions.reload: true`
+ * is set, in which case it bypasses the cache and stores the fresh response.
+ *
+ * Cache key: `cacheOptions.key` when provided, otherwise `"<METHOD> <URL>"`.
+ *
+ * Only `GET` requests are cached; mutations (POST, PUT, PATCH, DELETE) are
+ * always forwarded to `next` without touching the cache.
+ *
+ * Usage:
+ * ```ts
+ * const manager = new RequestManager()
+ *   .useCache(new CacheHandler())
+ *   .use(new FetchHandler());
+ * ```
+ */
+
+import { injectable } from 'tsyringe';
+import type {
+  Handler,
+  NextFn,
+  RequestContext,
+  StoreRequest,
+  StoreResponse,
+} from './types.js';
+
+interface CacheEntry {
+  response: StoreResponse;
+  cachedAt: number;
+}
+
+@injectable()
+export class CacheHandler implements Handler {
+  private cache = new Map<string, CacheEntry>();
+
+  maxSize: number = 256;
+
+  ttl: number = 300_000;
+
+  private isExpired(entry: CacheEntry): boolean {
+    return Date.now() - entry.cachedAt > this.ttl;
+  }
+
+  private evictLRU(): void {
+    while (this.cache.size > this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      } else {
+        break;
+      }
+    }
+  }
+
+  static keyFor(req: StoreRequest): string {
+    return req.cacheOptions?.key ?? `${req.method} ${req.url}`;
+  }
+
+  static isCacheable(req: StoreRequest): boolean {
+    return req.method === 'GET';
+  }
+
+  /**
+   * Handles a request by checking the in-memory cache before forwarding to
+   * the next handler.
+   *
+   * - Non-GET requests skip the cache entirely.
+   * - `cacheOptions.reload: true` forces a network request and refreshes the entry.
+   * - Cached entries expire after `ttl` milliseconds (default 5 minutes).
+   * - The cache uses LRU eviction when it exceeds `maxSize` entries (default 256).
+   */
+  async request<T = unknown>(
+    context: RequestContext<T>,
+    next: NextFn<T>,
+  ): Promise<StoreResponse<T>> {
+    const req = context.request;
+    if (!CacheHandler.isCacheable(req)) {
+      return next(req);
+    }
+
+    const key = CacheHandler.keyFor(req);
+    const reload = req.cacheOptions?.reload === true;
+
+    if (!reload) {
+      const hit = this.cache.get(key);
+      if (hit) {
+        if (this.isExpired(hit)) {
+          this.cache.delete(key);
+        } else {
+          // LRU promotion: delete and re-set to move to end
+          this.cache.delete(key);
+          this.cache.set(key, hit);
+          return hit.response as StoreResponse<T>;
+        }
+      }
+    }
+
+    const response = await next(req);
+    this.cache.set(key, { response: response as StoreResponse, cachedAt: Date.now() });
+    this.evictLRU();
+    return response;
+  }
+
+  /** Returns the number of entries currently in the cache. */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /** Removes all entries from the cache. */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Removes a single entry by key.
+   * @returns `true` when the entry existed and was deleted.
+   */
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+}

package/src/request/FetchHandler.ts

@@ -0,0 +1,119 @@
+/**
+ * Terminal request handler that executes HTTP calls via the browser / Node
+ * `fetch` API.
+ *
+ * `FetchHandler` is designed to sit at the end of the `RequestManager` chain.
+ * It does not call `next` — it issues the network request and returns the
+ * parsed response directly.
+ *
+ * Response body parsing:
+ * - `204 No Content` or `Content-Length: 0` → `null`
+ * - `application/json` or `application/vnd.api+json` → parsed JSON (falls
+ *   back to raw text if parsing fails)
+ * - Everything else → raw text string
+ *
+ * Error handling:
+ * - Non-2xx responses throw a `FetchError` that includes `status`, `content`,
+ *   and `headers` for downstream error handling.
+ */
+
+import { injectable } from 'tsyringe';
+import type {
+  Handler,
+  NextFn,
+  RequestContext,
+  StoreResponse,
+} from './types.js';
+
+/**
+ * Error thrown by `FetchHandler` for non-2xx HTTP responses.
+ * Carries the status code, parsed body content, and response headers.
+ */
+export class FetchError extends Error {
+  readonly status: number;
+  readonly content: unknown;
+  readonly headers: Record<string, string>;
+  constructor(
+    status: number,
+    content: unknown,
+    headers: Record<string, string>,
+    message?: string,
+  ) {
+    super(message ?? `Request failed with status ${status}`);
+    this.status = status;
+    this.content = content;
+    this.headers = headers;
+  }
+}
+
+@injectable()
+export class FetchHandler implements Handler {
+  static headersToObject(headers: Headers): Record<string, string> {
+    const out: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      out[key] = value;
+    });
+    return out;
+  }
+
+  static async parseBody(response: Response): Promise<unknown> {
+    const contentType = response.headers.get('Content-Type') ?? '';
+    if (
+      response.status === 204
+      || response.headers.get('Content-Length') === '0'
+    ) {
+      return null;
+    }
+    const isJson = contentType.includes('application/json')
+      || contentType.includes('application/vnd.api+json');
+    if (isJson) {
+      const text = await response.text();
+      if (!text) {
+        return null;
+      }
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+    return response.text();
+  }
+
+  /**
+   * Issues the HTTP request and returns a `StoreResponse`.
+   * This is a terminal handler — it never calls `next`.
+   *
+   * @throws `FetchError` on non-2xx responses.
+   */
+  async request<T = unknown>(
+    context: RequestContext<T>,
+    _next: NextFn<T>,
+  ): Promise<StoreResponse<T>> {
+    const req = context.request;
+    const init: RequestInit = {
+      method: req.method,
+      headers: req.headers,
+    };
+    if (req.body !== undefined && req.body !== null) {
+      init.body = req.body;
+    }
+    if (req.signal) {
+      init.signal = req.signal;
+    }
+
+    const response = await fetch(req.url, init);
+    const content = await FetchHandler.parseBody(response);
+    const headers = FetchHandler.headersToObject(response.headers);
+
+    if (!response.ok) {
+      throw new FetchError(response.status, content, headers);
+    }
+    return {
+      content: content as T,
+      status: response.status,
+      headers,
+      request: req,
+    };
+  }
+}

package/src/request/RequestManager.ts

@@ -0,0 +1,112 @@
+/**
+ * Middleware-style manager that runs a `StoreRequest` through an ordered chain
+ * of `Handler` instances.
+ *
+ * Handlers are invoked in registration order.  Each handler receives a
+ * `RequestContext` and a `next` function; it may:
+ * - Call `next(request)` to pass control to the next handler.
+ * - Return a `StoreResponse` directly to short-circuit the chain.
+ * - Wrap `next` to inspect or transform the response (e.g. logging).
+ *
+ * An optional *cache handler* registered via `useCache()` is always prepended
+ * to the chain so it runs before every other handler.
+ *
+ * Usage:
+ * ```ts
+ * const manager = new RequestManager()
+ *   .useCache(new CacheHandler())
+ *   .use([new AuthHandler(), new FetchHandler()]);
+ *
+ * const response = await manager.request({ method: 'GET', url: '/posts' });
+ * ```
+ */
+
+import { injectable } from 'tsyringe';
+import type {
+  Handler,
+  NextFn,
+  RequestContext,
+  StoreRequest,
+  StoreResponse,
+} from './types.js';
+
+@injectable()
+export class RequestManager {
+  private _handlers: Handler[] = [];
+  private _cache: Handler | null = null;
+
+  /**
+   * Appends one or more handlers to the pipeline.
+   * Returns `this` for chaining.
+   */
+  use(handlers: Handler[] | Handler): this {
+    if (Array.isArray(handlers)) {
+      this._handlers.push(...handlers);
+    } else {
+      this._handlers.push(handlers);
+    }
+    return this;
+  }
+
+  /**
+   * Registers the cache handler.  It is always inserted at the front of
+   * the chain so it can intercept requests before any other handler sees them.
+   * Returns `this` for chaining.
+   */
+  useCache(handler: Handler): this {
+    this._cache = handler;
+    return this;
+  }
+
+  /** All non-cache handlers in registration order. */
+  get handlers(): readonly Handler[] {
+    return this._handlers;
+  }
+
+  /** The registered cache handler, or `null`. */
+  get cacheHandler(): Handler | null {
+    return this._cache;
+  }
+
+  /**
+   * Executes `request` through the full handler chain and returns the final
+   * `StoreResponse`.
+   *
+   * @throws when no handlers have been registered.
+   * @throws when the chain ends without any handler returning a response
+   *         (i.e. no terminal handler such as `FetchHandler`).
+   */
+  async request<T = unknown>(request: StoreRequest): Promise<StoreResponse<T>> {
+    const chain: Handler[] = this._cache
+      ? [this._cache, ...this._handlers]
+      : [...this._handlers];
+
+    if (chain.length === 0) {
+      throw new Error(
+        'RequestManager has no handlers registered — cannot complete request',
+      );
+    }
+
+    let index = 0;
+    const invoke = async (req: StoreRequest): Promise<StoreResponse<T>> => {
+      const handler = chain[index];
+      if (!handler) {
+        throw new Error(
+          'Handler chain ended without producing a response (no terminal handler)',
+        );
+      }
+      index++;
+      const context: RequestContext<T> = {
+        request: req,
+        response: undefined,
+        setResponse(r) {
+          this.response = r;
+        },
+      };
+      const next: NextFn<T> = (nextRequest) => invoke(nextRequest);
+      return handler.request(context, next) as Promise<StoreResponse<T>>;
+    };
+
+    return invoke(request);
+  }
+}

package/src/request/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { RequestManager } from './RequestManager.js';
+export { FetchHandler } from './FetchHandler.js';
+export { CacheHandler } from './CacheHandler.js';