@iamjulianacosta/mobx-data 1.0.1

package/src/request/types.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared type definitions for the request pipeline.
+ *
+ * The request pipeline models each network call as a `StoreRequest` flowing
+ * through a chain of `Handler` instances.  Each handler can inspect, mutate,
+ * or short-circuit the request before passing it to `next`.
+ *
+ * Flow:
+ * ```
+ * RequestManager.request(StoreRequest)
+ *   → CacheHandler.request(context, next)
+ *     → FetchHandler.request(context, next)   ← terminal
+ * ```
+ */
+
+/** HTTP methods supported by the request pipeline. */
+export type HttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PATCH'
+  | 'PUT'
+  | 'DELETE'
+  | 'HEAD'
+  | 'OPTIONS';
+
+/** Store-level operation that triggered this request. */
+export type RequestOp =
+  | 'findRecord'
+  | 'findAll'
+  | 'findMany'
+  | 'query'
+  | 'queryRecord'
+  | 'createRecord'
+  | 'updateRecord'
+  | 'deleteRecord'
+  | 'custom';
+
+/** Stable identifier for a record — type + id pair. */
+export interface RecordIdentifier {
+  /** Model name. */
+  type: string;
+  /** Server-assigned id, or `null` for new records. */
+  id: string | null;
+  /** Optional local id for identity tracking before the server assigns an id. */
+  lid?: string;
+}
+
+/**
+ * A fully-described outgoing HTTP request.
+ *
+ * Passed to the first handler in the chain and forwarded (possibly mutated)
+ * to subsequent handlers via `next`.
+ */
+export interface StoreRequest {
+  /** HTTP method. */
+  method: HttpMethod;
+  /** Fully-qualified URL. */
+  url: string;
+  /** HTTP headers. */
+  headers?: Record<string, string>;
+  /** Request body.  `null` / `undefined` = no body. */
+  body?: string | FormData | Blob | ArrayBuffer | null;
+  /** Store operation that initiated this request. */
+  op?: RequestOp;
+  /** Records involved in this request (for cache invalidation, etc.). */
+  records?: RecordIdentifier[];
+  /** Store reference — passed through so handlers can access it if needed. */
+  store?: unknown;
+  /** Cache behavior overrides. */
+  cacheOptions?: {
+    /** When `true`, bypass the cache and always hit the network. */
+    reload?: boolean;
+    /** When `true`, return the cached value and refetch in the background. */
+    backgroundReload?: boolean;
+    /** Custom cache key.  Defaults to `"${method} ${url}"`. */
+    key?: string;
+  };
+  /** `AbortSignal` for request cancellation. */
+  signal?: AbortSignal;
+  /** Arbitrary additional metadata forwarded to handlers. */
+  [key: string]: unknown;
+}
+
+/** The response produced by the terminal handler and returned up the chain. */
+export interface StoreResponse<T = unknown> {
+  /** Parsed response body. */
+  content: T;
+  /** HTTP status code. */
+  status?: number;
+  /** Response headers. */
+  headers?: Record<string, string>;
+  /** The originating request. */
+  request?: StoreRequest;
+}
+
+/**
+ * Context object passed to each handler.
+ * Handlers read `request`, may call `setResponse` to stash an intermediate
+ * result, and call `next` to forward to the next handler.
+ */
+export interface RequestContext<T = unknown> {
+  /** The current request (may have been mutated by earlier handlers). */
+  request: StoreRequest;
+  /** Response set by a previous handler, if any. */
+  response?: StoreResponse<T>;
+  /** Allows a handler to record the response without ending the chain. */
+  setResponse(response: StoreResponse<T>): void;
+}
+
+/**
+ * Function passed to each handler that invokes the next handler in the chain.
+ * Handlers call `next(request)` to continue, or return a response directly to
+ * short-circuit remaining handlers.
+ */
+export type NextFn<T = unknown> = (
+  request: StoreRequest,
+) => Promise<StoreResponse<T>>;
+
+/**
+ * Interface that every request handler must implement.
+ *
+ * @example
+ * ```ts
+ * class LoggingHandler implements Handler {
+ *   async request(context, next) {
+ *     console.log('→', context.request.method, context.request.url);
+ *     const response = await next(context.request);
+ *     console.log('←', response.status);
+ *     return response;
+ *   }
+ * }
+ * ```
+ */
+export interface Handler<T = unknown> {
+  request(
+    context: RequestContext<T>,
+    next: NextFn<T>,
+  ): Promise<StoreResponse<T>> | StoreResponse<T>;
+}

package/src/schema/SchemaService.ts

@@ -0,0 +1,161 @@
+/**
+ * Central registry for model classes and their schema metadata.
+ *
+ * `SchemaService` is a tsyringe singleton that acts as the authoritative
+ * source of truth for every model registered with the store.  At registration
+ * time it walks the full prototype chain (deepest ancestor first) and merges
+ * all `@attr` / `@belongsTo` / `@hasMany` definitions so subclasses
+ * transparently inherit parent schema.
+ *
+ * Consumers (Store, serializers, snapshot helpers) call `attributesDefinitionFor`
+ * and `relationshipsDefinitionFor` rather than reading reflect-metadata directly.
+ */
+
+import 'reflect-metadata';
+import { singleton } from 'tsyringe';
+import {
+  ATTRIBUTES_META_KEY,
+  RELATIONSHIPS_META_KEY,
+  type AttributeDef,
+  type AttributeDefinitionsMap,
+  type RelationshipDef,
+  type RelationshipDefinitionsMap,
+} from './types.js';
+
+/** Minimal shape of a model constructor that SchemaService can register. */
+export interface ModelClass {
+  modelName?: string;
+  prototype: unknown;
+  new (...args: never[]): unknown;
+}
+
+/** Internal entry stored per registered model name. */
+interface Entry {
+  modelClass: ModelClass;
+  /** Merged attribute definitions (ancestors → leaf, leaf wins). */
+  attributes: AttributeDefinitionsMap;
+  /** Merged relationship definitions (ancestors → leaf, leaf wins). */
+  relationships: RelationshipDefinitionsMap;
+}
+
+/**
+ * Walks the prototype chain from the class root down to the leaf, collecting
+ * own-metadata from each level and merging into a single Map.  Later entries
+ * (i.e. the subclass) override earlier ones so subclass declarations win.
+ */
+function walkPrototypeChain<V>(
+  prototype: object | null,
+  metadataKey: symbol,
+): Map<string, V> {
+  // Walk from Object root down to the leaf so subclass entries override parents.
+  const chain: object[] = [];
+  let current: object | null = prototype;
+  while (current && current !== Object.prototype) {
+    chain.push(current);
+    current = Object.getPrototypeOf(current);
+  }
+  const merged = new Map<string, V>();
+  for (const proto of chain.reverse()) {
+    const local = Reflect.getOwnMetadata(metadataKey, proto) as
+      | Map<string, V>
+      | undefined;
+    if (local) {
+      for (const [key, value] of local) {
+        merged.set(key, value);
+      }
+    }
+  }
+  return merged;
+}
+
+@singleton()
+export class SchemaService {
+  private entries = new Map<string, Entry>();
+
+  /**
+   * Registers a model class under `modelName`.
+   *
+   * Walks the prototype chain at registration time so lookups are O(1).
+   * Calling this a second time for the same `modelName` replaces the entry.
+   */
+  registerModel(modelName: string, modelClass: ModelClass): void {
+    const attributes = walkPrototypeChain<AttributeDef>(
+      modelClass.prototype as object,
+      ATTRIBUTES_META_KEY,
+    );
+    const relationships = walkPrototypeChain<RelationshipDef>(
+      modelClass.prototype as object,
+      RELATIONSHIPS_META_KEY,
+    );
+    this.entries.set(modelName, { modelClass, attributes, relationships });
+  }
+
+  /**
+   * Returns the constructor for the given `modelName`.
+   * @throws if the model has not been registered.
+   */
+  modelFor(modelName: string): ModelClass {
+    const entry = this.entries.get(modelName);
+    if (!entry) {
+      throw new Error(`No model registered for type "${modelName}"`);
+    }
+    return entry.modelClass;
+  }
+
+  /** Returns `true` when a model class has been registered for `modelName`. */
+  doesTypeExist(modelName: string): boolean {
+    return this.entries.has(modelName);
+  }
+
+  /**
+   * Returns the merged attribute definitions for `modelName`.
+   * @throws if the model has not been registered.
+   */
+  attributesDefinitionFor(modelName: string): AttributeDefinitionsMap {
+    const entry = this.entries.get(modelName);
+    if (!entry) {
+      throw new Error(`No model registered for type "${modelName}"`);
+    }
+    return entry.attributes;
+  }
+
+  /**
+   * Returns the merged relationship definitions for `modelName`.
+   * @throws if the model has not been registered.
+   */
+  relationshipsDefinitionFor(modelName: string): RelationshipDefinitionsMap {
+    const entry = this.entries.get(modelName);
+    if (!entry) {
+      throw new Error(`No model registered for type "${modelName}"`);
+    }
+    return entry.relationships;
+  }
+
+  /**
+   * Iterates over every attribute definition for `modelName`, invoking
+   * `callback` with the attribute name and its `AttributeDef`.
+   */
+  eachAttribute(
+    modelName: string,
+    callback: (name: string, meta: AttributeDef) => void,
+  ): void {
+    const attributes = this.attributesDefinitionFor(modelName);
+    for (const [name, meta] of attributes) {
+      callback(name, meta);
+    }
+  }
+
+  /**
+   * Iterates over every relationship definition for `modelName`, invoking
+   * `callback` with the relationship name and its `RelationshipDef`.
+   */
+  eachRelationship(
+    modelName: string,
+    callback: (name: string, meta: RelationshipDef) => void,
+  ): void {
+    const relationships = this.relationshipsDefinitionFor(modelName);
+    for (const [name, meta] of relationships) {
+      callback(name, meta);
+    }
+  }
+}

package/src/schema/decorators.ts

@@ -0,0 +1,162 @@
+/**
+ * Property decorators for declaring model attributes and relationships.
+ *
+ * `@attr` marks a property as a data attribute that is serialized to/from the
+ * server payload.  `@belongsTo` and `@hasMany` declare the two supported
+ * association directions.
+ *
+ * All decorators write their metadata onto the class prototype via
+ * `reflect-metadata` so `SchemaService` can walk the prototype chain and
+ * merge inherited definitions.
+ */
+
+import 'reflect-metadata';
+import {
+  ATTRIBUTES_META_KEY,
+  RELATIONSHIPS_META_KEY,
+  type AttributeDef,
+  type AttributeOptions,
+  type RelationshipDef,
+  type RelationshipOptions,
+} from './types.js';
+
+/**
+ * Returns the own-prototype attribute map for `target`, creating one if it
+ * doesn't exist yet.  We deliberately avoid inheriting the parent map so each
+ * class level stores only its own declarations; `SchemaService.walkPrototypeChain`
+ * handles merging.
+ */
+function getOwnAttrMap(target: object): Map<string, AttributeDef> {
+  let map = Reflect.getOwnMetadata(ATTRIBUTES_META_KEY, target) as
+    | Map<string, AttributeDef>
+    | undefined;
+  if (!map) {
+    map = new Map();
+    Reflect.defineMetadata(ATTRIBUTES_META_KEY, map, target);
+  }
+  return map;
+}
+
+/**
+ * Returns the own-prototype relationship map for `target`, creating one if
+ * it doesn't exist yet.
+ */
+function getOwnRelMap(target: object): Map<string, RelationshipDef> {
+  let map = Reflect.getOwnMetadata(RELATIONSHIPS_META_KEY, target) as
+    | Map<string, RelationshipDef>
+    | undefined;
+  if (!map) {
+    map = new Map();
+    Reflect.defineMetadata(RELATIONSHIPS_META_KEY, map, target);
+  }
+  return map;
+}
+
+/**
+ * Marks a class property as a serializable attribute.
+ *
+ * @example
+ * ```ts
+ * @attr('string') name!: string;
+ * @attr('number', { defaultValue: 0 }) age!: number;
+ * @attr({ defaultValue: () => [] }) tags!: string[];
+ * ```
+ */
+export function attr(
+  type?: string | null,
+  options?: AttributeOptions,
+): PropertyDecorator;
+export function attr(options: AttributeOptions): PropertyDecorator;
+export function attr(
+  typeOrOptions?: string | null | AttributeOptions,
+  options?: AttributeOptions,
+): PropertyDecorator {
+  let resolvedType: string | null = null;
+  let resolvedOptions: AttributeOptions = {};
+
+  if (typeof typeOrOptions === 'string') {
+    resolvedType = typeOrOptions;
+    resolvedOptions = options ?? {};
+  } else if (typeOrOptions === null) {
+    resolvedType = null;
+    resolvedOptions = options ?? {};
+  } else if (typeof typeOrOptions === 'object' && typeOrOptions !== null) {
+    resolvedOptions = typeOrOptions;
+  }
+
+  return (target, propertyKey) => {
+    const map = getOwnAttrMap(target as object);
+    map.set(propertyKey as string, {
+      name: propertyKey as string,
+      type: resolvedType,
+      options: resolvedOptions,
+      isAttribute: true,
+    });
+  };
+}
+
+/**
+ * Builds and returns a `PropertyDecorator` that registers a relationship
+ * definition on the class prototype.  Shared by `@belongsTo` and `@hasMany`.
+ *
+ * Options are normalised with sensible defaults so consumers can rely on
+ * `async`, `inverse`, and `polymorphic` always being present.
+ */
+function makeRelationship(
+  kind: 'belongsTo' | 'hasMany',
+  type: string,
+  options: RelationshipOptions = {},
+): PropertyDecorator {
+  const normalized: RelationshipOptions = {
+    async: options.async ?? false,
+    inverse: options.inverse === undefined ? null : options.inverse,
+    polymorphic: options.polymorphic ?? false,
+    ...options,
+  };
+  return (target, propertyKey) => {
+    const map = getOwnRelMap(target as object);
+    map.set(propertyKey as string, {
+      name: propertyKey as string,
+      kind,
+      type,
+      options: normalized,
+      isRelationship: true,
+    });
+  };
+}
+
+/**
+ * Declares a `belongsTo` (many-to-one) association.
+ *
+ * @param type    - `modelName` of the related model.
+ * @param options - Optional relationship options (async, inverse, …).
+ *
+ * @example
+ * ```ts
+ * @belongsTo('user') author!: User;
+ * ```
+ */
+export function belongsTo(
+  type: string,
+  options: RelationshipOptions = {},
+): PropertyDecorator {
+  return makeRelationship('belongsTo', type, options);
+}
+
+/**
+ * Declares a `hasMany` (one-to-many) association.
+ *
+ * @param type    - `modelName` of the related model.
+ * @param options - Optional relationship options (async, inverse, …).
+ *
+ * @example
+ * ```ts
+ * @hasMany('comment') comments!: Comment[];
+ * ```
+ */
+export function hasMany(
+  type: string,
+  options: RelationshipOptions = {},
+): PropertyDecorator {
+  return makeRelationship('hasMany', type, options);
+}

package/src/schema/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export { attr, belongsTo, hasMany } from './decorators.js';
+export { SchemaService, type ModelClass } from './SchemaService.js';

package/src/schema/types.ts

@@ -0,0 +1,66 @@
+/** 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 const ATTRIBUTES_META_KEY = Symbol('mobx-data:attributes');
+/** Reflect-metadata key used to store relationship definitions on a prototype. */
+export const RELATIONSHIPS_META_KEY = Symbol('mobx-data:relationships');
+/** Reflect-metadata key used to store the registered model name on a class. */
+export const MODEL_NAME_META_KEY = Symbol('mobx-data:modelName');