@iamjulianacosta/mobx-data 1.1.1 → 1.4.0

package/src/mdql/MdqlValidator.ts

@@ -0,0 +1,193 @@
+import type { SchemaService } from '@mobx-data/schema';
+import {
+  ALL_OPERATORS,
+  OPERATORS_FOR_TYPE,
+  type MdqlFilterNode,
+  type MdqlQueryObject,
+  type MdqlValidationError,
+} from './types.js';
+
+export class MdqlValidationException extends Error {
+  public readonly errors: MdqlValidationError[];
+
+  constructor(errors: MdqlValidationError[]) {
+    const messages = errors.map((error) => `${error.path}: ${error.message}`);
+    super(`MDQL validation failed: ${messages.join('; ')}`);
+    this.name = 'MdqlValidationException';
+    this.errors = errors;
+  }
+}
+
+export class MdqlValidator {
+  static validate(query: MdqlQueryObject, schema: SchemaService): void {
+    const errors = MdqlValidator.validateQuiet(query, schema);
+    if (errors.length > 0) {
+      throw new MdqlValidationException(errors);
+    }
+  }
+
+  static validateQuiet(
+    query: MdqlQueryObject,
+    schema: SchemaService,
+  ): MdqlValidationError[] {
+    const errors: MdqlValidationError[] = [];
+
+    if (!schema.doesTypeExist(query.modelName)) {
+      errors.push({
+        path: 'modelName',
+        message: `Unknown model type "${query.modelName}".`,
+      });
+      return errors;
+    }
+
+    const attributes = schema.attributesDefinitionFor(query.modelName);
+    const relationships = schema.relationshipsDefinitionFor(query.modelName);
+
+    MdqlValidator.validateFilterNode(
+      query.filters,
+      'filters',
+      errors,
+      schema,
+      query.modelName,
+    );
+
+    for (let index = 0; index < query.orderBy.length; index++) {
+      const clause = query.orderBy[index]!;
+      if (clause.field.includes('.')) {
+        const resolved = MdqlValidator.resolveFieldAttribute(clause.field, query.modelName, schema);
+        if (!resolved) {
+          errors.push({
+            path: `orderBy[${index}]`,
+            message: `Unknown attribute path "${clause.field}".`,
+          });
+        }
+      } else if (clause.field !== 'id' && !attributes.has(clause.field)) {
+        errors.push({
+          path: `orderBy[${index}]`,
+          message: `Unknown attribute "${clause.field}" on "${query.modelName}".`,
+        });
+      }
+    }
+
+    for (const include of query.includes) {
+      if (!relationships.has(include)) {
+        errors.push({
+          path: 'includes',
+          message: `Unknown relationship "${include}" on "${query.modelName}".`,
+        });
+      }
+    }
+
+    if (query.limit !== null) {
+      if (!Number.isInteger(query.limit) || query.limit < 1) {
+        errors.push({
+          path: 'limit',
+          message: 'Limit must be a positive integer.',
+        });
+      }
+    }
+
+    if (query.offset !== null) {
+      if (!Number.isInteger(query.offset) || query.offset < 0) {
+        errors.push({
+          path: 'offset',
+          message: 'Offset must be a non-negative integer.',
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  private static resolveFieldAttribute(
+    field: string,
+    modelName: string,
+    schema: SchemaService,
+  ): { name: string; type: string | null } | null {
+    const parts = field.split('.');
+    if (parts.length === 1) {
+      if (field === 'id') return { name: 'id', type: 'string' };
+      const attributes = schema.attributesDefinitionFor(modelName);
+      return attributes.get(field) ?? null;
+    }
+
+    let currentModel = modelName;
+    for (let index = 0; index < parts.length - 1; index++) {
+      const relationships = schema.relationshipsDefinitionFor(currentModel);
+      const rel = relationships.get(parts[index]!);
+      if (!rel) return null;
+      currentModel = rel.type;
+      if (!schema.doesTypeExist(currentModel)) return null;
+    }
+
+    const lastPart = parts[parts.length - 1]!;
+    if (lastPart === 'id') {
+      return { name: 'id', type: 'string' };
+    }
+    const finalAttributes = schema.attributesDefinitionFor(currentModel);
+    return finalAttributes.get(lastPart) ?? null;
+  }
+
+  private static validateFilterNode(
+    node: MdqlFilterNode,
+    path: string,
+    errors: MdqlValidationError[],
+    schema: SchemaService,
+    modelName: string,
+  ): void {
+    if (node.kind === 'condition') {
+      const attributeDefinition = MdqlValidator.resolveFieldAttribute(
+        node.field, modelName, schema,
+      );
+
+      if (!attributeDefinition) {
+        const message = node.field.includes('.')
+          ? `Unknown attribute path "${node.field}".`
+          : `Unknown attribute "${node.field}".`;
+        errors.push({ path, message });
+        return;
+      }
+
+      const allowedOperators = attributeDefinition.type
+        ? OPERATORS_FOR_TYPE[attributeDefinition.type] ?? ALL_OPERATORS
+        : ALL_OPERATORS;
+
+      if (!allowedOperators.has(node.operator)) {
+        errors.push({
+          path,
+          message: `Operator "${node.operator}" is not valid for type "${attributeDefinition.type}".`,
+        });
+      }
+
+      if (node.operator === 'between') {
+        if (!Array.isArray(node.value) || node.value.length !== 2) {
+          errors.push({
+            path,
+            message: 'Operator "between" requires a value of [min, max].',
+          });
+        }
+      }
+
+      if (node.operator === 'in' || node.operator === 'notIn') {
+        if (!Array.isArray(node.value)) {
+          errors.push({
+            path,
+            message: `Operator "${node.operator}" requires an array value.`,
+          });
+        }
+      }
+
+      return;
+    }
+
+    for (let index = 0; index < node.children.length; index++) {
+      MdqlValidator.validateFilterNode(
+        node.children[index]!,
+        `${path}.${node.kind}[${index}]`,
+        errors,
+        schema,
+        modelName,
+      );
+    }
+  }
+}

package/src/mdql/index.ts

@@ -0,0 +1,21 @@
+export { MdqlQueryBuilder } from './MdqlQueryBuilder.js';
+export { MdqlValidator, MdqlValidationException } from './MdqlValidator.js';
+export { MdqlMemoryExecutor } from './MdqlMemoryExecutor.js';
+export type {
+  MdqlQueryObject,
+  MdqlFilterNode,
+  MdqlCondition,
+  MdqlLogicalGroup,
+  MdqlOperator,
+  MdqlUnaryOperator,
+  MdqlSortDirection,
+  MdqlOrderByClause,
+  MdqlValidationError,
+  ModelFields,
+  MdqlOperatorFor,
+  MdqlValueFor,
+  MdqlStringOperator,
+  MdqlNumberOperator,
+  MdqlBooleanOperator,
+} from './types.js';
+export { ALL_OPERATORS, OPERATORS_FOR_TYPE } from './types.js';

package/src/mdql/types.ts

@@ -0,0 +1,107 @@
+export type MdqlOperator =
+  | 'equals'
+  | 'notEquals'
+  | 'in'
+  | 'notIn'
+  | 'isNull'
+  | 'isNotNull'
+  | 'contains'
+  | 'startsWith'
+  | 'endsWith'
+  | 'greaterThan'
+  | 'greaterThanOrEquals'
+  | 'lessThan'
+  | 'lessThanOrEquals'
+  | 'between';
+
+export type MdqlUnaryOperator = 'isNull' | 'isNotNull';
+
+export type MdqlSortDirection = 'asc' | 'desc';
+
+export interface MdqlCondition {
+  kind: 'condition';
+  field: string;
+  operator: MdqlOperator;
+  value: unknown;
+}
+
+export interface MdqlLogicalGroup {
+  kind: 'and' | 'or' | 'not';
+  children: MdqlFilterNode[];
+}
+
+export type MdqlFilterNode = MdqlCondition | MdqlLogicalGroup;
+
+export interface MdqlOrderByClause {
+  field: string;
+  direction: MdqlSortDirection;
+}
+
+export interface MdqlQueryObject {
+  modelName: string;
+  filters: MdqlLogicalGroup;
+  orderBy: MdqlOrderByClause[];
+  limit: number | null;
+  offset: number | null;
+  includes: string[];
+}
+
+export interface MdqlValidationError {
+  path: string;
+  message: string;
+}
+
+const COMPARABLE_OPERATORS: MdqlOperator[] = [
+  'equals', 'notEquals', 'in', 'notIn', 'isNull', 'isNotNull',
+];
+
+const STRING_OPERATORS: MdqlOperator[] = [
+  ...COMPARABLE_OPERATORS, 'contains', 'startsWith', 'endsWith',
+];
+
+const NUMERIC_OPERATORS: MdqlOperator[] = [
+  ...COMPARABLE_OPERATORS,
+  'greaterThan', 'greaterThanOrEquals', 'lessThan', 'lessThanOrEquals', 'between',
+];
+
+export const OPERATORS_FOR_TYPE: Record<string, ReadonlySet<MdqlOperator>> = {
+  string: new Set(STRING_OPERATORS),
+  number: new Set(NUMERIC_OPERATORS),
+  date: new Set(NUMERIC_OPERATORS),
+  boolean: new Set(['equals', 'notEquals', 'isNull', 'isNotNull']),
+};
+
+export const ALL_OPERATORS: ReadonlySet<MdqlOperator> = new Set<MdqlOperator>([
+  'equals', 'notEquals', 'in', 'notIn', 'isNull', 'isNotNull',
+  'contains', 'startsWith', 'endsWith',
+  'greaterThan', 'greaterThanOrEquals', 'lessThan', 'lessThanOrEquals', 'between',
+]);
+
+// --- Type-level operator & value inference ---
+
+import type { Model } from '@mobx-data/model';
+
+export type ModelFields<T extends Model> = Omit<T, keyof Model>;
+
+export type MdqlStringOperator =
+  | 'equals' | 'notEquals' | 'in' | 'notIn' | 'isNull' | 'isNotNull'
+  | 'contains' | 'startsWith' | 'endsWith';
+
+export type MdqlNumberOperator =
+  | 'equals' | 'notEquals' | 'in' | 'notIn' | 'isNull' | 'isNotNull'
+  | 'greaterThan' | 'greaterThanOrEquals' | 'lessThan' | 'lessThanOrEquals' | 'between';
+
+export type MdqlBooleanOperator = 'equals' | 'notEquals' | 'isNull' | 'isNotNull';
+
+export type MdqlOperatorFor<T> =
+  [T] extends [string] ? MdqlStringOperator :
+  [T] extends [number] ? MdqlNumberOperator :
+  [T] extends [boolean] ? MdqlBooleanOperator :
+  [T] extends [Date] ? MdqlNumberOperator :
+  MdqlOperator;
+
+export type MdqlValueFor<TField, TOp extends MdqlOperator> =
+  TOp extends 'isNull' | 'isNotNull' ? undefined :
+  TOp extends 'in' | 'notIn' ? TField[] :
+  TOp extends 'between' ? [TField, TField] :
+  TField;

package/src/model/Model.ts

@@ -45,6 +45,13 @@ import { Errors } from './Errors.js';
 import { StateMachine, type RecordState, type RecordEvent } from './StateMachine.js';
 import { Snapshot } from './Snapshot.js';
 
+let clientIdCounter = 0;
+
+function generateClientId(): string {
+  clientIdCounter += 1;
+  return `client-${clientIdCounter}`;
+}
+
 /**
  * Raw relationship reference stored on the record.
  * Contains either a single `{ type, id }` object (belongsTo),
@@ -238,6 +245,8 @@ export abstract class Model {
   protected _relationships: Map<string, RelationshipRef> = new Map();
   /** Server-assigned id, or `null` for new records. */
   protected _id: string | null = null;
+  /** Client-generated identifier for new records that don't yet have a server id. */
+  readonly _clientId: string = generateClientId();
   /** Internal lifecycle state machine. */
   protected _stateMachine: StateMachine;
 
@@ -287,6 +296,7 @@ export abstract class Model {
       _relationships: observable.shallow,
       _id: observable,
       id: computed,
+      uniqueId: computed,
       currentState: computed,
       isLoading: computed,
       isLoaded: computed,
@@ -318,6 +328,11 @@ export abstract class Model {
     });
   }
 
+  /** Returns a stable identifier: the server-assigned `id` if available, otherwise the client-generated `_clientId`. */
+  get uniqueId(): string {
+    return this._id ?? this._clientId;
+  }
+
   /** Returns the static `modelName` from the concrete subclass constructor. */
   get modelName(): string {
     return (this.constructor as typeof Model).modelName;

package/src/model/Snapshot.ts

@@ -62,6 +62,8 @@ function walk<V>(proto: object | null, key: symbol): Map<string, V> {
 export class Snapshot<T extends Model = Model> {
   /** Server-assigned id at snapshot time, or `null` for new records. */
   readonly id: string | null;
+  /** Client-generated identifier, always present. */
+  readonly clientId: string;
   /** `modelName` of the snapshotted record. */
   readonly modelName: string;
   /** Reference to the live record (read-only from adapter/serializer code). */
@@ -76,6 +78,7 @@ export class Snapshot<T extends Model = Model> {
   constructor(record: T) {
     this.record = record;
     this.id = record.id;
+    this.clientId = record._clientId;
     this.modelName = record.modelName;
 
     const internal = record as unknown as {

package/src/odata/ODataAdapter.ts

@@ -195,7 +195,10 @@ export class ODataAdapter extends RestAdapter {
     const data = record._data;
     const body: Record<string, unknown> = {};
     if (data) {
-      Object.assign(body, data);
+      for (const key of Object.keys(data)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+        body[key] = data[key];
+      }
     }
     return body;
   }

package/src/request/CacheHandler.ts

@@ -47,12 +47,8 @@ export class CacheHandler implements Handler {
 
   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;
-      }
+      const firstKey = this.cache.keys().next().value as string;
+      this.cache.delete(firstKey);
     }
   }
 

package/src/schema/SchemaService.ts

@@ -16,8 +16,11 @@ import { singleton } from 'tsyringe';
 import {
   ATTRIBUTES_META_KEY,
   RELATIONSHIPS_META_KEY,
+  MODEL_OPTIONS_META_KEY,
   type AttributeDef,
   type AttributeDefinitionsMap,
+  type DiscriminatorDef,
+  type ModelOptions,
   type RelationshipDef,
   type RelationshipDefinitionsMap,
 } from './types.js';
@@ -36,6 +39,14 @@ interface Entry {
   attributes: AttributeDefinitionsMap;
   /** Merged relationship definitions (ancestors → leaf, leaf wins). */
   relationships: RelationshipDefinitionsMap;
+  /** When `true`, the model is abstract and cannot be instantiated directly. */
+  abstract?: boolean;
+  /** Discriminator configuration for polymorphic hierarchies. */
+  discriminator?: DiscriminatorDef;
+  /** Model name of the polymorphic root when this is a concrete child. */
+  polymorphicRoot?: string;
+  /** When `true`, the client-generated id is sent to the server on create. */
+  clientGeneratedIds?: boolean;
 }
 
 /**
@@ -87,7 +98,46 @@ export class SchemaService {
       modelClass.prototype as object,
       RELATIONSHIPS_META_KEY,
     );
-    this.entries.set(modelName, { modelClass, attributes, relationships });
+    const entry: Entry = { modelClass, attributes, relationships };
+
+    const options = Reflect.getOwnMetadata(MODEL_OPTIONS_META_KEY, modelClass) as
+      | ModelOptions
+      | undefined;
+    if (options?.abstract) {
+      entry.abstract = true;
+    }
+    if (options?.discriminator) {
+      entry.discriminator = {
+        key: options.discriminator.key ?? 'type',
+        map: options.discriminator.map,
+      };
+    }
+    if (options?.clientGeneratedIds) {
+      entry.clientGeneratedIds = true;
+    }
+
+    this.entries.set(modelName, entry);
+    this.linkPolymorphicChild(modelName, modelClass);
+  }
+
+  /**
+   * After registering a model, checks whether any already-registered
+   * polymorphic parent lists this model in its discriminator map and, if so,
+   * stores the `polymorphicRoot` back-link.
+   */
+  private linkPolymorphicChild(childName: string, childClass: ModelClass): void {
+    for (const [parentName, parentEntry] of this.entries) {
+      if (!parentEntry.discriminator || parentName === childName) continue;
+      for (const factory of Object.values(parentEntry.discriminator.map)) {
+        if (factory() === childClass) {
+          const childEntry = this.entries.get(childName);
+          if (childEntry) {
+            childEntry.polymorphicRoot = parentName;
+          }
+          return;
+        }
+      }
+    }
   }
 
   /**
@@ -102,6 +152,11 @@ export class SchemaService {
     return entry.modelClass;
   }
 
+  /** Returns all registered model names. */
+  registeredNames(): string[] {
+    return Array.from(this.entries.keys());
+  }
+
   /** Returns `true` when a model class has been registered for `modelName`. */
   doesTypeExist(modelName: string): boolean {
     return this.entries.has(modelName);
@@ -158,4 +213,71 @@ export class SchemaService {
       callback(name, meta);
     }
   }
+
+  /**
+   * Returns the discriminator definition for `modelName`, or `undefined`
+   * when the model is not polymorphic.
+   */
+  discriminatorFor(modelName: string): DiscriminatorDef | undefined {
+    return this.entries.get(modelName)?.discriminator;
+  }
+
+  /**
+   * Returns the polymorphic root model name for a concrete child, or `null`
+   * when `modelName` is not part of a polymorphic hierarchy.
+   */
+  polymorphicRootFor(modelName: string): string | null {
+    return this.entries.get(modelName)?.polymorphicRoot ?? null;
+  }
+
+  /**
+   * Returns `true` when `modelName` is declared abstract.
+   */
+  isAbstract(modelName: string): boolean {
+    return this.entries.get(modelName)?.abstract === true;
+  }
+
+  /** Returns `true` when the model uses client-generated ids. */
+  hasClientGeneratedIds(modelName: string): boolean {
+    return this.entries.get(modelName)?.clientGeneratedIds === true;
+  }
+
+  /**
+   * Resolves the concrete model class for a polymorphic parent given a raw
+   * payload.  Reads the discriminator key from the payload and returns the
+   * resolved model name and class.
+   *
+   * @throws when the discriminator key is missing from the payload.
+   * @throws when the discriminator value is not in the map.
+   * @returns `null` when `modelName` has no discriminator (not polymorphic).
+   */
+  resolveConcreteModel(
+    modelName: string,
+    payload: Record<string, unknown>,
+  ): { modelName: string; modelClass: ModelClass } | null {
+    const entry = this.entries.get(modelName);
+    if (!entry?.discriminator) return null;
+
+    const { key, map } = entry.discriminator;
+    const discriminatorValue = payload[key];
+    if (discriminatorValue === undefined || discriminatorValue === null) {
+      throw new Error(
+        `Missing discriminator key "${key}" in payload for polymorphic model "${modelName}".`,
+      );
+    }
+
+    const valueString = String(discriminatorValue);
+    const factory = map[valueString];
+    if (!factory) {
+      const knownValues = Object.keys(map).join(', ');
+      throw new Error(
+        `Unknown discriminator value "${valueString}" for model "${modelName}" `
+        + `(key: "${key}"). Known values: ${knownValues}.`,
+      );
+    }
+
+    const concreteClass = factory() as ModelClass;
+    const concreteName = concreteClass.modelName ?? valueString;
+    return { modelName: concreteName, modelClass: concreteClass };
+  }
 }

package/src/schema/decorators.ts

@@ -14,8 +14,10 @@ import 'reflect-metadata';
 import {
   ATTRIBUTES_META_KEY,
   RELATIONSHIPS_META_KEY,
+  MODEL_OPTIONS_META_KEY,
   type AttributeDef,
   type AttributeOptions,
+  type ModelOptions,
   type RelationshipDef,
   type RelationshipOptions,
 } from './types.js';
@@ -160,3 +162,30 @@ export function hasMany(
 ): PropertyDecorator {
   return makeRelationship('hasMany', type, options);
 }
+
+/**
+ * Class decorator that attaches model options (name, abstract, discriminator)
+ * as reflect-metadata on the constructor.  `SchemaService.registerModel` reads
+ * this metadata at registration time.
+ *
+ * @example
+ * ```ts
+ * @model({
+ *   name: 'vehicle',
+ *   abstract: true,
+ *   discriminator: {
+ *     key: 'type',
+ *     map: { car: () => Car, motorcycle: () => Motorcycle },
+ *   },
+ * })
+ * abstract class Vehicle extends Model { … }
+ * ```
+ */
+export function model(options: ModelOptions = {}): ClassDecorator {
+  return (target) => {
+    if (options.name) {
+      (target as unknown as { modelName: string }).modelName = options.name;
+    }
+    Reflect.defineMetadata(MODEL_OPTIONS_META_KEY, options, target);
+  };
+}

package/src/schema/index.ts

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

package/src/schema/types.ts

@@ -58,9 +58,43 @@ export type AttributeDefinitionsMap = Map<string, AttributeDef>;
 /** Relationship definitions keyed by property name. */
 export type RelationshipDefinitionsMap = Map<string, RelationshipDef>;
 
+/** Constructor type accepted by the discriminator map. */
+export interface ModelConstructor {
+  new (...args: never[]): unknown;
+  modelName?: string;
+  prototype: unknown;
+}
+
+/** Discriminator configuration for polymorphic model hierarchies. */
+export interface DiscriminatorDef {
+  /** Payload field that identifies the concrete type (defaults to `"type"`). */
+  key: string;
+  /** Maps discriminator values to lazy model constructor references. */
+  map: Record<string, () => ModelConstructor>;
+}
+
+/** Options accepted by the `@model` class decorator. */
+export interface ModelOptions {
+  /** Registered model name. */
+  name?: string;
+  /** When `true`, the model cannot be instantiated directly. */
+  abstract?: boolean;
+  /** Discriminator configuration for selecting concrete subclass at deserialization. */
+  discriminator?: {
+    /** Payload field that identifies the concrete type (defaults to `"type"`). */
+    key?: string;
+    /** Maps discriminator values to lazy model constructor references. */
+    map: Record<string, () => ModelConstructor>;
+  };
+  /** When `true`, the client-generated `_clientId` is sent to the server as the record id on create. */
+  clientGeneratedIds?: boolean;
+}
+
 /** 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');
+/** Reflect-metadata key used to store `@model` options on a class constructor. */
+export const MODEL_OPTIONS_META_KEY = Symbol('mobx-data:modelOptions');