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

package/src/{db.js → db.ts}

@@ -17,20 +17,36 @@
 import Cron from '@stonyx/cron';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
-import Orm, { createRecord, store } from '@stonyx/orm';
+import Orm, { store } from '@stonyx/orm';
+import { createRecord } from './manage-record.js';
 import { createFile, createDirectory, updateFile, readFile, fileExists } from '@stonyx/utils/file';
 import path from 'path';
 
 export const dbKey = '__db';
 
+interface DBRecord {
+  format(): Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+function asDBRecord(value: unknown): DBRecord {
+  if (typeof value !== 'object' || value === null || typeof (value as DBRecord).format !== 'function') {
+    throw new Error('createRecord did not return a valid DBRecord');
+  }
+  return value as DBRecord;
+}
+
 export default class DB {
+  static instance: DB;
+  record!: DBRecord;
+
   constructor() {
     if (DB.instance) return DB.instance;
 
     DB.instance = this;
   }
 
-  async getSchema() {
+  async getSchema(): Promise<unknown> {
     const { rootPath } = config;
     const { file, schema } = config.orm.db;
 
@@ -39,10 +55,10 @@ export default class DB {
     return (await import(`${rootPath}/${schema}`)).default;
   }
 
-  getCollectionKeys() {
-    const SchemaClass = Orm.instance.models[`${dbKey}Model`];
+  getCollectionKeys(): string[] {
+    const SchemaClass = Orm.instance.models[`${dbKey}Model`] as new () => Record<string, unknown>;
     const instance = new SchemaClass();
-    const keys = [];
+    const keys: string[] = [];
 
     for (const key of Object.keys(instance)) {
       if (key === '__name' || key === 'id') continue;
@@ -52,7 +68,7 @@ export default class DB {
     return keys;
   }
 
-  getDirPath() {
+  getDirPath(): string {
     const { rootPath } = config;
     const { file, directory } = config.orm.db;
     const dbDir = path.dirname(path.resolve(`${rootPath}/${file}`));
@@ -60,7 +76,7 @@ export default class DB {
     return path.join(dbDir, directory);
   }
 
-  async validateMode() {
+  async validateMode(): Promise<void> {
     const { rootPath } = config;
     const { file, mode } = config.orm.db;
     const collectionKeys = this.getCollectionKeys();
@@ -71,11 +87,11 @@ export default class DB {
       const exists = await fileExists(dbFilePath);
 
       if (exists) {
-        const data = await readFile(dbFilePath, { json: true });
+        const data = await readFile(dbFilePath, { json: true }) as Record<string, unknown[]>;
         const hasData = collectionKeys.some(key => Array.isArray(data[key]) && data[key].length > 0);
 
         if (hasData) {
-          log.error(`DB mode mismatch: db.json contains data but mode is set to 'directory'. Run migration first:\n\n  stonyx db:migrate-to-directory\n`);
+          log.error?.(`DB mode mismatch: db.json contains data but mode is set to 'directory'. Run migration first:\n\n  stonyx db:migrate-to-directory\n`);
           process.exit(1);
         }
       }
@@ -88,14 +104,14 @@ export default class DB {
         )).some(Boolean);
 
         if (hasCollectionFiles) {
-          log.error(`DB mode mismatch: directory '${config.orm.db.directory}/' contains collection files but mode is set to 'file'. Run migration first:\n\n  stonyx db:migrate-to-file\n`);
+          log.error?.(`DB mode mismatch: directory '${config.orm.db.directory}/' contains collection files but mode is set to 'file'. Run migration first:\n\n  stonyx db:migrate-to-file\n`);
           process.exit(1);
         }
       }
     }
   }
 
-  async init() {
+  async init(): Promise<void> {
     const { autosave, saveInterval } = config.orm.db;
 
     store.set(dbKey, new Map());
@@ -109,7 +125,7 @@ export default class DB {
     new Cron().register('save', this.save.bind(this), saveInterval);
   }
 
-  async create() {
+  async create(): Promise<Record<string, unknown>> {
     const { rootPath } = config;
     const { file, mode } = config.orm.db;
 
@@ -124,7 +140,7 @@ export default class DB {
       ));
 
       // Write empty-array skeleton to db.json
-      const skeleton = {};
+      const skeleton: Record<string, unknown[]> = {};
       for (const key of collectionKeys) skeleton[key] = [];
 
       await createFile(`${rootPath}/${file}`, skeleton, { json: true });
@@ -137,9 +153,9 @@ export default class DB {
     return {};
   }
 
-  async save() {
+  async save(): Promise<void> {
     const { file, mode } = config.orm.db;
-    const jsonData = this.record.format();
+    const jsonData = this.record.format() as Record<string, unknown>;
     delete jsonData.id; // Don't save id
 
     if (mode === 'directory') {
@@ -147,26 +163,36 @@ export default class DB {
       const collectionKeys = this.getCollectionKeys();
 
       // Write each collection to its own file in parallel
-      await Promise.all(collectionKeys.map(key =>
-        updateFile(path.join(dirPath, `${key}.json`), jsonData[key] || [], { json: true })
-      ));
+      // Use createFile for new files, updateFile for existing ones
+      await Promise.all(collectionKeys.map(async key => {
+        const filePath = path.join(dirPath, `${key}.json`);
+        const exists = await fileExists(filePath);
+        const data = (jsonData[key] || []) as Record<string, unknown> | unknown[];
+
+        if (exists) await updateFile(filePath, data, { json: true });
+        else await createFile(filePath, data, { json: true });
+      }));
 
       // Write empty-array skeleton to db.json
-      const skeleton = {};
+      const skeleton: Record<string, unknown[]> = {};
       for (const key of collectionKeys) skeleton[key] = [];
 
-      await updateFile(`${config.rootPath}/${file}`, skeleton, { json: true });
+      const dbFilePath = `${config.rootPath}/${file}`;
+      const dbFileExists = await fileExists(dbFilePath);
+
+      if (dbFileExists) await updateFile(dbFilePath, skeleton, { json: true });
+      else await createFile(dbFilePath, skeleton, { json: true });
 
-      log.db(`DB has been successfully saved to ${config.orm.db.directory}/ directory`);
+      log.db?.(`DB has been successfully saved to ${config.orm.db.directory}/ directory`);
       return;
     }
 
     await updateFile(`${config.rootPath}/${file}`, jsonData, { json: true });
 
-    log.db(`DB has been successfully saved to ${file}`);
+    log.db?.(`DB has been successfully saved to ${file}`);
   }
 
-  async getRecord() {
+  async getRecord(): Promise<DBRecord> {
     const { mode } = config.orm.db;
 
     if (mode === 'directory') return this.getRecordFromDirectory();
@@ -174,25 +200,25 @@ export default class DB {
     return this.getRecordFromFile();
   }
 
-  async getRecordFromFile() {
+  async getRecordFromFile(): Promise<DBRecord> {
     const { file } = config.orm.db;
 
     const data = await readFile(file, { json: true, missingFileCallback: this.create.bind(this) });
 
-    return createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false });
+    return asDBRecord(createRecord(dbKey, data as Record<string, unknown>, { isDbRecord: true, serialize: false, transform: false }));
   }
 
-  async getRecordFromDirectory() {
+  async getRecordFromDirectory(): Promise<DBRecord> {
     const dirPath = this.getDirPath();
     const collectionKeys = this.getCollectionKeys();
     const dirExists = await fileExists(dirPath);
 
     if (!dirExists) {
       const data = await this.create();
-      return createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false });
+      return asDBRecord(createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false }));
     }
 
-    const assembled = {};
+    const assembled: Record<string, unknown> = {};
 
     await Promise.all(collectionKeys.map(async key => {
       const filePath = path.join(dirPath, `${key}.json`);
@@ -201,6 +227,6 @@ export default class DB {
       assembled[key] = exists ? await readFile(filePath, { json: true }) : [];
     }));
 
-    return createRecord(dbKey, assembled, { isDbRecord: true, serialize: false, transform: false });
+    return asDBRecord(createRecord(dbKey, assembled, { isDbRecord: true, serialize: false, transform: false }));
   }
 }

package/src/exports/db.ts

@@ -0,0 +1,7 @@
+import Orm from '@stonyx/orm';
+
+const db = Orm.db as { record: unknown; save(): Promise<void> };
+
+export default db;
+export const data = db.record;
+export const saveDB = db.save.bind(db);

package/src/has-many.ts

@@ -0,0 +1,92 @@
+import { createRecord, store } from '@stonyx/orm';
+import { getRelationships, getGlobalRegistry, getPendingRegistry, getBelongsToRegistry } from './relationships.js';
+import { getOrSet, makeArray } from '@stonyx/utils/object';
+import { dbKey } from './db.js';
+import type { SourceRecord } from './types/orm-types.js';
+
+interface HasManyOptions {
+  global?: boolean;
+  [key: string]: unknown;
+}
+
+interface PendingItem {
+  pendingRelationship: Map<unknown, unknown[][]>;
+  id: unknown;
+}
+
+type RelationshipHandler = ((sourceRecord: SourceRecord, rawData: unknown, options: HasManyOptions) => unknown[]) & {
+  __relatedModelName: string;
+  __relationshipType: 'hasMany';
+};
+
+function queuePendingRelationship(
+  pendingRelationshipQueue: PendingItem[],
+  pendingRelationships: Map<string, Map<unknown, unknown[][]>>,
+  modelName: string,
+  id: unknown
+): null {
+  pendingRelationshipQueue.push({
+    pendingRelationship: getOrSet(pendingRelationships, modelName, new Map()),
+    id
+  });
+
+  return null;
+}
+
+export default function hasMany(modelName: string): RelationshipHandler {
+  const globalRelationships = getGlobalRegistry();
+  const pendingRelationships = getPendingRegistry();
+
+  const fn = (sourceRecord: SourceRecord, rawData: unknown, options: HasManyOptions): unknown[] => {
+    const { __name: sourceModelName } = sourceRecord.__model;
+    const relationshipId = sourceRecord.id;
+    const relationship = getRelationships('hasMany', sourceModelName, modelName, relationshipId as string) as Map<unknown, unknown[]>;
+    const modelStore = store.get(modelName);
+    const pendingRelationshipQueue: PendingItem[] = [];
+
+    const output: unknown[] = !rawData ? [] : makeArray(rawData).map((elementData: unknown) => {
+      let record: unknown;
+
+      if (typeof elementData !== 'object') {
+        if (!modelStore) {
+          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+        }
+
+        record = modelStore.get(elementData as number | string);
+
+        if (!record) {
+          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+        }
+      } else {
+        if (elementData !== Object(elementData)) {
+          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+        }
+
+        record = createRecord(modelName, elementData as Record<string, unknown>, options);
+      }
+
+      // Populate belongTo side if the relationship is defined
+      const recordWithId = typeof record === 'object' && record !== null && 'id' in record ? record as SourceRecord : undefined;
+      const otherSide = recordWithId ? getBelongsToRegistry()
+        .get(modelName)?.get(sourceModelName)?.get(recordWithId.id) : undefined;
+
+      if (otherSide) Object.assign(otherSide, sourceRecord);
+
+      return record;
+    }).filter((value: unknown) => value);
+
+    relationship.set(relationshipId, output);
+
+    // Assign global relationship
+    if (options.global || sourceModelName === dbKey) getOrSet(globalRelationships, modelName, []).push(output);
+
+    // Assign pending relationships
+    for (const { pendingRelationship, id } of pendingRelationshipQueue) getOrSet(pendingRelationship, id, []).push(output);
+
+    return output;
+  };
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  Object.defineProperty(fn, '__relationshipType', { value: 'hasMany' as const });
+  return fn as RelationshipHandler;
+}

package/src/hooks.ts

@@ -0,0 +1,151 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Middleware-based hooks registry for ORM operations.
+ * Unlike event-based hooks, middleware hooks run sequentially and can halt operations.
+ */
+
+/** Context object passed to before/after hook handlers. */
+export interface HookContext {
+  /** Model name (e.g. 'user', 'animal'). */
+  model: string;
+  /** Operation name: 'create', 'update', 'delete', 'get', or 'list'. */
+  operation: string;
+  /** The incoming HTTP request object. */
+  request?: unknown;
+  /** URL route parameters (e.g. { id: '42' }). */
+  params?: Record<string, string>;
+  /** Parsed request body for create/update operations. */
+  body?: Record<string, unknown>;
+  /** URL query string parameters. */
+  query?: Record<string, string>;
+  /** Mutable state bag shared across hooks within a single request. */
+  state?: Record<string, unknown>;
+  /** Previous record state (available in update hooks). */
+  oldState?: unknown;
+  /** Target record ID for single-record operations. */
+  recordId?: string | number;
+  /** Response data (available in after hooks). */
+  response?: unknown;
+  /** The affected record (available in after hooks for create/update/delete). */
+  record?: unknown;
+  /** The affected records (available in after hooks for list operations). */
+  records?: unknown[];
+  [key: string]: unknown;
+}
+
+type HookHandler = (context: HookContext) => unknown | Promise<unknown>;
+
+// Map of "operation:model" -> handler[]
+const beforeHooks: Map<string, HookHandler[]> = new Map();
+const afterHooks: Map<string, HookHandler[]> = new Map();
+
+/**
+ * Register a before hook middleware that runs before the operation executes.
+ *
+ * @param operation - Operation name: 'create', 'update', 'delete', 'get', or 'list'
+ * @param model - Model name (e.g., 'user', 'animal')
+ * @param handler - Middleware function (context) => any
+ *   - Return undefined to continue to next hook/handler
+ *   - Return any value to halt operation (integer = HTTP status, object = response body)
+ * @returns Unsubscribe function
+ */
+export function beforeHook(operation: string, model: string, handler: HookHandler): () => void {
+  const key = `${operation}:${model}`;
+  if (!beforeHooks.has(key)) {
+    beforeHooks.set(key, []);
+  }
+  const hooks = beforeHooks.get(key);
+  if (hooks) hooks.push(handler);
+
+  // Return unsubscribe function
+  return () => {
+    const hooks = beforeHooks.get(key);
+    if (hooks) {
+      const index = hooks.indexOf(handler);
+      if (index > -1) hooks.splice(index, 1);
+    }
+  };
+}
+
+/**
+ * Register an after hook middleware that runs after the operation completes.
+ * After hooks cannot halt operations (they run after completion).
+ *
+ * @param operation - Operation name
+ * @param model - Model name
+ * @param handler - Middleware function (context) => void
+ * @returns Unsubscribe function
+ */
+export function afterHook(operation: string, model: string, handler: HookHandler): () => void {
+  const key = `${operation}:${model}`;
+  if (!afterHooks.has(key)) {
+    afterHooks.set(key, []);
+  }
+  const hooks = afterHooks.get(key);
+  if (hooks) hooks.push(handler);
+
+  // Return unsubscribe function
+  return () => {
+    const hooks = afterHooks.get(key);
+    if (hooks) {
+      const index = hooks.indexOf(handler);
+      if (index > -1) hooks.splice(index, 1);
+    }
+  };
+}
+
+/**
+ * Get all before hooks for an operation:model combination.
+ */
+export function getBeforeHooks(operation: string, model: string): HookHandler[] {
+  const key = `${operation}:${model}`;
+  return beforeHooks.get(key) || [];
+}
+
+/**
+ * Get all after hooks for an operation:model combination.
+ */
+export function getAfterHooks(operation: string, model: string): HookHandler[] {
+  const key = `${operation}:${model}`;
+  return afterHooks.get(key) || [];
+}
+
+/**
+ * Clear registered hooks for a specific operation:model.
+ *
+ * @param operation - Operation name
+ * @param model - Model name
+ * @param type - 'before' or 'after' (if omitted, clears both)
+ */
+export function clearHook(operation: string, model: string, type?: 'before' | 'after'): void {
+  const key = `${operation}:${model}`;
+  if (!type || type === 'before') {
+    beforeHooks.set(key, []);
+  }
+  if (!type || type === 'after') {
+    afterHooks.set(key, []);
+  }
+}
+
+/**
+ * Clear all hooks (useful for testing).
+ */
+export function clearAllHooks(): void {
+  beforeHooks.clear();
+  afterHooks.clear();
+}

package/src/{index.js → index.ts}

@@ -15,15 +15,24 @@
  */
 
 import Model from './model.js';
+import View from './view.js';
 import Serializer from './serializer.js';
 
 import attr from './attr.js';
 import belongsTo from './belongs-to.js';
 import hasMany from './has-many.js';
 import { createRecord, updateRecord } from './manage-record.js';
+import { count, avg, sum, min, max } from './aggregates.js';
 
 export { default } from './main.js';
 export { store, relationships } from './main.js';
-export { Model, Serializer }; // base classes
+export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
-export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+export { count, avg, sum, min, max }; // aggregate helpers
+export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+
+// Store API:
+// store.get(model, id)   -- sync, memory-only
+// store.find(model, id)  -- async, MySQL for memory:false models
+// store.findAll(model)   -- async, all records
+// store.query(model, conditions) -- async, always hits MySQL