@stonyx/orm 0.2.1-beta.9 → 0.2.1-beta.90

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/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.js → setup-rest-server.ts}

@@ -5,21 +5,26 @@ import MetaRequest from './meta-request.js';
 import RestServer from '@stonyx/rest-server';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { dbKey } from './db.js';
-import { pluralize } from './utils.js';
+import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
 
-export default async function(route, accessPath, metaRoute) {
-  let accessFiles = {};
-  
+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 => {
-      const accessInstance = new accessClass();
+    await forEachFileImport(accessPath, (accessClass: unknown) => {
+      const accessInstance = new (accessClass as new () => AccessInstance)();
       const { models } = accessInstance;
 
-      if (!models) throw new Error(`Access class "${accessClass.name}" must define a "models" list`);
+      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.name}" must declare an "access" method`);
+      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());
 
@@ -32,8 +37,8 @@ export default async function(route, accessPath, metaRoute) {
       }
     });
   } catch (error) {
-    log.error(error.message);
-    log.warn('You must define a valid access configuration file in order to access ORM generated REST endpoints.');
+    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');
@@ -41,20 +46,17 @@ export default async function(route, accessPath, metaRoute) {
   // Remove "/" prefix and name mount point accordingly
   const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
 
-  // Configure endpoints for models with access configuration
+  // Configure endpoints for models and views with access configuration
   for (const [model, access] of Object.entries(accessFiles)) {
-    const pluralizedModel = pluralize(model);
+    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!');
+    log.warn?.('SECURITY RISK! - Meta route is enabled via metaRoute config. This feature is intended for development purposes only!');
 
     RestServer.instance.mountRoute(MetaRequest, { name });
   }
-
-  // Cleanup references
-  accessFiles = null;
 }

package/src/standalone-db.ts

@@ -0,0 +1,185 @@
+/**
+ * Standalone JSON database layer for CLI usage.
+ *
+ * Reads and writes directly to JSON files without requiring the Stonyx
+ * bootstrap, ORM init, or any framework dependencies. Supports both
+ * single-file and directory modes.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+interface StandaloneDBOptions {
+  dbPath?: string;
+  mode?: 'file' | 'directory';
+  directory?: string;
+}
+
+interface DBRecord {
+  id: string | number;
+  [key: string]: unknown;
+}
+
+export default class StandaloneDB {
+  readonly mode: 'file' | 'directory';
+  readonly dbPath: string;
+  readonly directory: string;
+
+  constructor(options: StandaloneDBOptions = {}) {
+    this.mode = options.mode || 'directory';
+    this.dbPath = options.dbPath || 'db.json';
+    this.directory = options.directory || 'db';
+  }
+
+  /**
+   * Resolve the directory path for directory mode.
+   */
+  getDirPath(): string {
+    const dbDir = path.dirname(path.resolve(this.dbPath));
+    return path.join(dbDir, this.directory);
+  }
+
+  /**
+   * List available collections by inspecting either the db.json keys
+   * or the files in the db directory.
+   */
+  async getCollections(): Promise<string[]> {
+    if (this.mode === 'directory') {
+      const dirPath = this.getDirPath();
+
+      try {
+        const files = await fs.readdir(dirPath);
+        return files
+          .filter(f => f.endsWith('.json'))
+          .map(f => f.replace('.json', ''));
+      } catch {
+        return [];
+      }
+    }
+
+    // File mode -- read db.json and return its top-level keys
+    try {
+      const data = await this._readJSON(this.dbPath) as Record<string, unknown>;
+      return Object.keys(data).filter(key => Array.isArray(data[key]));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Read all records for a collection.
+   */
+  async readCollection(collection: string): Promise<DBRecord[]> {
+    if (this.mode === 'directory') {
+      const filePath = path.join(this.getDirPath(), `${collection}.json`);
+      return this._readJSON(filePath) as Promise<DBRecord[]>;
+    }
+
+    const data = await this._readJSON(this.dbPath) as Record<string, DBRecord[]>;
+    return data[collection] || [];
+  }
+
+  /**
+   * Write all records for a collection.
+   */
+  async writeCollection(collection: string, records: DBRecord[]): Promise<void> {
+    if (this.mode === 'directory') {
+      const dirPath = this.getDirPath();
+      await fs.mkdir(dirPath, { recursive: true });
+
+      const filePath = path.join(dirPath, `${collection}.json`);
+      await this._writeJSON(filePath, records);
+      return;
+    }
+
+    // File mode -- read full db, update collection, write back
+    let data: Record<string, unknown>;
+
+    try {
+      data = await this._readJSON(this.dbPath) as Record<string, unknown>;
+    } catch {
+      data = {};
+    }
+
+    data[collection] = records;
+    await this._writeJSON(this.dbPath, data);
+  }
+
+  /**
+   * Get a single record by id.
+   */
+  async get(collection: string, id: string | number): Promise<DBRecord | null> {
+    const records = await this.readCollection(collection);
+    const numericId = Number(id);
+
+    return records.find(r =>
+      r.id === id || r.id === numericId
+    ) || null;
+  }
+
+  /**
+   * List all records in a collection.
+   */
+  async list(collection: string): Promise<DBRecord[]> {
+    return this.readCollection(collection);
+  }
+
+  /**
+   * Create a new record. Auto-assigns an integer id if none provided.
+   */
+  async create(collection: string, data: DBRecord): Promise<DBRecord> {
+    const records = await this.readCollection(collection);
+
+    if (!data.id) {
+      const maxId = records.reduce((max, r) => {
+        const rid = typeof r.id === 'number' ? r.id : 0;
+        return rid > max ? rid : max;
+      }, 0);
+
+      data.id = maxId + 1;
+    }
+
+    // Check for duplicate id
+    const existing = records.find(r => r.id === data.id);
+    if (existing) {
+      throw new Error(`Record with id ${data.id} already exists in '${collection}'`);
+    }
+
+    records.push(data);
+    await this.writeCollection(collection, records);
+
+    return data;
+  }
+
+  /**
+   * Delete a record by id.
+   */
+  async delete(collection: string, id: string | number): Promise<DBRecord> {
+    const records = await this.readCollection(collection);
+    const numericId = Number(id);
+
+    const index = records.findIndex(r =>
+      r.id === id || r.id === numericId
+    );
+
+    if (index === -1) {
+      throw new Error(`Record with id '${id}' not found in '${collection}'`);
+    }
+
+    const [removed] = records.splice(index, 1);
+    await this.writeCollection(collection, records);
+
+    return removed;
+  }
+
+  // -- Private helpers --
+
+  private async _readJSON(filePath: string): Promise<unknown> {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+  }
+
+  private async _writeJSON(filePath: string, data: unknown): Promise<void> {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  }
+}