@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/src/record.ts

@@ -0,0 +1,186 @@
+import { store } from '@stonyx/orm';
+import { getComputedProperties } from "./serializer.js";
+import { camelCaseToKebabCase } from '@stonyx/utils/string';
+import { getPluralName } from './plural-registry.js';
+import type Serializer from './serializer.js';
+
+interface ToJSONOptions {
+  fields?: Set<string>;
+  baseUrl?: string;
+}
+
+interface SerializeOptions {
+  update?: boolean;
+  serialize?: boolean;
+  transform?: boolean;
+  [key: string]: unknown;
+}
+
+interface UnloadOptions {
+  [key: string]: unknown;
+}
+
+interface RelationshipLinks {
+  self: string;
+  related: string;
+}
+
+interface RelationshipEntry {
+  data: { type: string; id: unknown } | { type: string; id: unknown }[] | null;
+  links?: RelationshipLinks;
+}
+
+interface JSONAPIResult {
+  attributes: { [key: string]: unknown };
+  relationships: { [key: string]: RelationshipEntry };
+  id: unknown;
+  type: string;
+  links?: { self: string };
+}
+
+export default class Record {
+  /** @private */
+  __data: { [key: string]: unknown } = {};
+  /** @private */
+  __relationships: { [key: string]: unknown } = {};
+  /** @private */
+  __serialized = false;
+  /** @private */
+  __model: { __name: string; [key: string]: unknown };
+  /** @private */
+  __serializer: Serializer;
+
+  [key: string]: unknown;
+
+  constructor(model: { __name: string; [key: string]: unknown }, serializer: Serializer) {
+    this.__model = model;
+    this.__serializer = serializer;
+  }
+
+  serialize(rawData?: unknown, options: SerializeOptions = {}): { [key: string]: unknown } {
+    const { __data: data } = this;
+
+    if (this.__serialized && !options.update) {
+      const relatedIds: { [key: string]: unknown } = {};
+
+      for (const [key, childRecord] of Object.entries(this.__relationships)) {
+        relatedIds[key] = Array.isArray(childRecord)
+          ? childRecord.map((r: Record) => r.id)
+          : (childRecord as Record)?.id ?? null;
+      }
+
+      return { ...data, ...relatedIds };
+    }
+
+    const normalizedData = this.__serializer.normalize(rawData);
+    this.__serializer.setProperties(normalizedData, this, options);
+
+    return data;
+  }
+
+  // Similar to serialize, but preserves top level relationship records
+  format(): { [key: string]: unknown } {
+    if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
+
+    const { __data: data } = this;
+    const records: { [key: string]: unknown } = {};
+
+    for (const [key, childRecord] of Object.entries(this.__relationships)) {
+      if (Array.isArray(childRecord)) {
+        // Deduplicate by record ID — keep last occurrence (latest data wins)
+        const seen = new Set<unknown>();
+        const unique: Record[] = [];
+
+        for (let i = childRecord.length - 1; i >= 0; i--) {
+          const r = childRecord[i] as Record;
+          if (!seen.has(r.id)) {
+            seen.add(r.id);
+            unique.push(r);
+          }
+        }
+
+        unique.reverse();
+        records[key] = unique.map((r: Record) => r.serialize());
+      } else {
+        records[key] = (childRecord as Record)?.serialize() ?? null;
+      }
+    }
+
+    return { ...data, ...records };
+  }
+
+  // Formats record for JSON API output
+  toJSON(options: ToJSONOptions = {}): JSONAPIResult {
+    if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
+
+    const { fields, baseUrl } = options;
+    const { __data: data } = this;
+    const modelName = this.__model.__name;
+    const pluralizedModelName = getPluralName(modelName);
+    const recordId = data.id;
+    const relationships: { [key: string]: RelationshipEntry } = {};
+    const attributes: { [key: string]: unknown } = {};
+
+    for (const [key, value] of Object.entries(data)) {
+      if (key === 'id') continue;
+      if (fields && !fields.has(key)) continue;
+      attributes[key] = value;
+    }
+
+    for (const [key, getter] of getComputedProperties(this.__model)) {
+      if (fields && !fields.has(key)) continue;
+      attributes[key] = (getter as () => unknown).call(this);
+    }
+
+    for (const [key, childRecord] of Object.entries(this.__relationships)) {
+      if (fields && !fields.has(key)) continue;
+
+      const relationshipData = Array.isArray(childRecord)
+        ? childRecord.map((r: Record) => ({ type: r.__model.__name, id: r.id }))
+        : childRecord ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
+
+      // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
+      const dasherizedKey = camelCaseToKebabCase(key);
+
+      relationships[dasherizedKey] = { data: relationshipData };
+
+      // Add links to relationship if baseUrl provided
+      if (baseUrl) {
+        relationships[dasherizedKey].links = {
+          self: `${baseUrl}/${pluralizedModelName}/${recordId}/relationships/${dasherizedKey}`,
+          related: `${baseUrl}/${pluralizedModelName}/${recordId}/${dasherizedKey}`
+        };
+      }
+    }
+
+    const result: JSONAPIResult = {
+      attributes,
+      relationships,
+      id: recordId,
+      type: modelName,
+    };
+
+    // Add resource links if baseUrl provided
+    if (baseUrl) {
+      result.links = {
+        self: `${baseUrl}/${pluralizedModelName}/${recordId}`
+      };
+    }
+
+    return result;
+  }
+
+  unload(options: UnloadOptions = {}): void {
+    store.unloadRecord(this.__model.__name, this.id, options);
+  }
+
+  clean(): void {
+    try {
+      for (const key of Object.keys(this)) {
+        delete this[key];
+      }
+    } catch {
+      // Ignore errors during cleanup, as some keys may not be deletable
+    }
+  }
+}

package/src/relationships.ts

@@ -0,0 +1,54 @@
+import { relationships } from '@stonyx/orm';
+import type { HasManyMap, BelongsToMap, GlobalMap, PendingMap, PendingBelongsToMap } from './types/orm-types.js';
+
+// TODO: Refactor mapping to remove a level of iteration
+export function getRelationships(type: string, sourceModel: string, targetModel: string, relationshipId?: string): Map<unknown, unknown> | undefined {
+  let allRelationships = relationships.get(type) as Map<string, Map<string, Map<unknown, unknown>>> | undefined;
+
+  if (!allRelationships) {
+    allRelationships = new Map();
+    relationships.set(type, allRelationships);
+  }
+
+  // create relationship map for this type of it doesn't already exist
+  if (!allRelationships.has(sourceModel)) allRelationships.set(sourceModel, new Map());
+
+  const modelRelationship = allRelationships.get(sourceModel) as Map<string, Map<unknown, unknown>> | undefined;
+  if (!modelRelationship) return undefined;
+
+  if (!modelRelationship.has(targetModel)) modelRelationship.set(targetModel, new Map());
+
+  const relationship = modelRelationship.get(targetModel) as Map<unknown, unknown> | undefined;
+
+  // TODO: Determine whether already having id should be handled differently
+  //if (relationship.has(relationshipId)) return;
+
+  return relationship;
+}
+
+export function getHasManyRelationships(sourceModel: string, targetModel: string): Map<unknown, unknown> | undefined {
+  return (relationships.get('hasMany') as HasManyMap | undefined)?.get(sourceModel)?.get(targetModel);
+}
+
+/** Typed accessors for the relationship registry */
+export function getHasManyRegistry(): HasManyMap {
+  return relationships.get('hasMany') as HasManyMap;
+}
+
+export function getBelongsToRegistry(): BelongsToMap {
+  return relationships.get('belongsTo') as BelongsToMap;
+}
+
+export function getGlobalRegistry(): GlobalMap {
+  return relationships.get('global') as GlobalMap;
+}
+
+export function getPendingRegistry(): PendingMap {
+  return relationships.get('pending') as PendingMap;
+}
+
+export function getPendingBelongsToRegistry(): PendingBelongsToMap {
+  return relationships.get('pendingBelongsTo') as PendingBelongsToMap;
+}
+
+export const TYPES: string[] = ['global', 'hasMany', 'belongsTo', 'pending'];

package/src/schema-helpers.ts

@@ -0,0 +1,59 @@
+import type { ModelSchema } from './types/orm-types.js';
+
+export interface SchemaRelationshipInfo {
+  type: 'belongsTo' | 'hasMany';
+  modelName: string | null;
+}
+
+/**
+ * Detect relationship type and target model from a model property function.
+ * Returns null if the property is not a relationship.
+ */
+export function getRelationshipInfo(property: unknown): SchemaRelationshipInfo | null {
+  if (typeof property !== 'function') return null;
+  const relType = (property as { __relationshipType?: string }).__relationshipType;
+  const modelName = (property as { __relatedModelName?: string }).__relatedModelName || null;
+
+  if (relType === 'belongsTo') return { type: 'belongsTo', modelName };
+  if (relType === 'hasMany') return { type: 'hasMany', modelName };
+
+  return null;
+}
+
+/**
+ * Sanitize a model/table name for use in SQL identifiers.
+ * Replaces hyphens and slashes with underscores.
+ */
+export function sanitizeTableName(name: string): string {
+  return name.replace(/[-/]/g, '_');
+}
+
+/**
+ * Sort model schemas in dependency order (belongsTo targets before dependents).
+ * Uses depth-first traversal to ensure referenced tables are created first.
+ */
+export function getTopologicalOrder(schemas: Record<string, ModelSchema>): string[] {
+  const visited = new Set<string>();
+  const order: string[] = [];
+
+  function visit(name: string): void {
+    if (visited.has(name)) return;
+    visited.add(name);
+
+    const schema = schemas[name];
+    if (!schema) return;
+
+    // Visit dependencies (belongsTo targets) first
+    for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
+      if (targetModelName) visit(targetModelName);
+    }
+
+    order.push(name);
+  }
+
+  for (const name of Object.keys(schemas)) {
+    visit(name);
+  }
+
+  return order;
+}

package/src/serializer.ts

@@ -0,0 +1,161 @@
+import config from 'stonyx/config';
+import { get, makeArray } from '@stonyx/utils/object';
+import type { AggregateProperty } from './aggregates.js';
+import type ModelProperty from './model-property.js';
+
+const RESERVED_KEYS = ['__name'];
+
+function isAggregateProperty(v: unknown): v is AggregateProperty {
+  return typeof v === 'object' && v !== null && (v as { __kind?: string }).__kind === 'AggregateProperty';
+}
+
+function isModelProperty(v: unknown): v is ModelProperty {
+  return typeof v === 'object' && v !== null && (v as { __kind?: string }).__kind === 'ModelProperty';
+}
+
+function searchQuery(query: Record<string, unknown>, array: unknown, key?: string): unknown {
+  const result = makeArray(array).find((item: unknown) => {
+    for (const [prop, value] of Object.entries(query)) {
+      if ((item as Record<string, unknown>)[prop] !== value) return false;
+
+      return true;
+    }
+  });
+
+  if (!result) return null;
+  if (key) return (result as Record<string, unknown>)[key];
+
+  return result;
+}
+
+function query(rawData: unknown, pathPrefix: string, subPath: unknown): unknown {
+  if (!rawData) return null;
+
+  const [path, getter, pointer] = makeArray(subPath) as [string, unknown, string | undefined];
+  const fullPath = `${pathPrefix}${path}`;
+  const value = get(rawData as Record<string, unknown>, fullPath);
+
+  if (getter === undefined || getter === null) return value;
+
+  try {
+    switch (typeof getter) {
+      case 'object':
+        return searchQuery(getter as Record<string, unknown>, value, pointer);
+
+      case 'function':
+        return (getter as (v: unknown) => unknown)(value);
+
+      case 'number': {
+        const element = (value as unknown[])[getter];
+        return pointer ? (element as Record<string, unknown>)[pointer] : element;
+      }
+
+      default:
+        return (value as Record<string, unknown>)[getter as string];
+    }
+  } catch (error) {
+    if (config.debug) console.error(`Cannot parse value for ${fullPath}.`, { getter, query }, error);
+  }
+}
+
+export default class Serializer {
+  map: Record<string, unknown> = {};
+  path = '';
+  model: Record<string, unknown>;
+
+  constructor(model: Record<string, unknown>) {
+    this.model = model;
+  }
+
+  /**
+   * This method populates the record's instance with instances of
+   * the ModelProperty object, while setting parsed values to the record's
+   * __data property, which represents the serialized version of the data
+   */
+  setProperties(rawData: unknown, record: unknown, options: Record<string, unknown>): void {
+    const { path, model } = this;
+    const keys = Object.keys(model).filter(key => !RESERVED_KEYS.includes(key));
+    const pathPrefix = path ? `${path}.` : '';
+    const rec = record as Record<string, unknown>;
+    const parsedData = rec.__data as Record<string, unknown>;
+    const relatedRecords = rec.__relationships as Record<string, unknown>;
+
+    for (const key of keys) {
+      const subPath = options.serialize ? ((this.map as Record<string, unknown>)[key] || key) : key;
+      const handler = model[key];
+      const data = query(rawData, pathPrefix, subPath);
+
+      // Skip fields not present in the update payload (undefined = not provided)
+      if (data === undefined && options.update) continue;
+
+      // Relationship handling
+      if (typeof handler === 'function') {
+        // Pass relationship key name to handler for pending fulfillment
+        const handlerOptions = { ...options, _relationshipKey: key };
+        const childRecord = handler(record, data, handlerOptions);
+
+        rec[key] = childRecord;
+        relatedRecords[key] = childRecord;
+
+        continue;
+      }
+
+      // Aggregate property handling — use the rawData value, not the aggregate descriptor
+      if (isAggregateProperty(handler)) {
+        parsedData[key] = data;
+        rec[key] = data;
+        continue;
+      }
+
+      // Direct assignment handling
+      if (!isModelProperty(handler)) {
+        parsedData[key] = handler;
+        rec[key] = handler;
+        continue;
+      }
+
+      const prop = handler as { value: unknown; ignoreFirstTransform: boolean };
+
+      Object.defineProperty(record, key, {
+        enumerable: true,
+        configurable: true,
+        get: () => prop.value,
+        set(newValue: unknown) {
+          prop.ignoreFirstTransform = !options.transform;
+          prop.value = newValue;
+          parsedData[key] = prop.value;
+        }
+      });
+
+      rec[key] = data;
+    }
+
+    if (options.update) return;
+
+    // Serialize computed properties
+    for (const [key, getter] of getComputedProperties(this.model)) {
+      Object.defineProperty(record, key, {
+        enumerable: true,
+        get: () => (getter as () => unknown).call(record)
+      });
+    }
+
+    rec.__serialized = true;
+  }
+
+  /**
+   * OVERRIDE: This hook allows for data manipulation prior to serialization logic
+   */
+  normalize(data: unknown): unknown {
+    return data;
+  }
+}
+
+export function getComputedProperties(classInstance: Record<string, unknown>): [string, PropertyDescriptor['get']][] {
+  const proto = Object.getPrototypeOf(classInstance);
+  if (!proto || proto === Object.prototype) return [];
+
+  return Object.entries(Object.getOwnPropertyDescriptors(proto))
+    .filter(([key, descriptor]) => key !== 'constructor' && descriptor.get)
+    .map(([key, descriptor]) => [key, descriptor.get]);
+}

package/src/setup-rest-server.ts

@@ -0,0 +1,62 @@
+import { waitForModule } from 'stonyx';
+import { store } from '@stonyx/orm';
+import OrmRequest from './orm-request.js';
+import MetaRequest from './meta-request.js';
+import RestServer from '@stonyx/rest-server';
+import { forEachFileImport } from '@stonyx/utils/file';
+import { dbKey } from './db.js';
+import { getPluralName } from './plural-registry.js';
+import log from 'stonyx/log';
+
+interface AccessInstance {
+  models: string[] | '*';
+  access: (request: unknown) => unknown;
+}
+
+export default async function(route: string, accessPath: string, metaRoute: boolean): Promise<void> {
+  const accessFiles: Record<string, (request: unknown) => unknown> = {};
+
+  try {
+    await forEachFileImport(accessPath, (accessClass: unknown) => {
+      const accessInstance = new (accessClass as new () => AccessInstance)();
+      const { models } = accessInstance;
+
+      if (!models) throw new Error(`Access class "${(accessClass as { name: string }).name}" must define a "models" list`);
+
+      if (models.length === 0) return; // No models to assign access to
+      if (typeof accessInstance.access !== 'function') throw new Error(`Access class "${(accessClass as { name: string }).name}" must declare an "access" method`);
+
+      const availableModels = Array.from(store.data.keys());
+
+      for (const model of models === '*' ? availableModels : models) {
+        if (model === dbKey) continue;
+        if (!store.data.has(model)) throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
+        if (accessFiles![model]) throw new Error(`Access for model "${model}" has already been defined by another access class.`);
+
+        accessFiles![model] = accessInstance.access;
+      }
+    });
+  } catch (error) {
+    log.error?.(error instanceof Error ? error.message : String(error));
+    log.warn?.('You must define a valid access configuration file in order to access ORM generated REST endpoints.');
+  }
+
+  await waitForModule('rest-server');
+
+  // Remove "/" prefix and name mount point accordingly
+  const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
+
+  // Configure endpoints for models and views with access configuration
+  for (const [model, access] of Object.entries(accessFiles!)) {
+    const pluralizedModel = getPluralName(model);
+    const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
+    RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });
+  }
+
+  // Mount the meta route when metaRoute config is enabled
+  if (metaRoute) {
+    log.warn?.('SECURITY RISK! - Meta route is enabled via metaRoute config. This feature is intended for development purposes only!');
+
+    RestServer.instance.mountRoute(MetaRequest, { name });
+  }
+}