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

package/src/main.ts

@@ -0,0 +1,229 @@
+/*
+ * 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.
+ */
+
+import DB from './db.js';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { forEachFileImport } from '@stonyx/utils/file';
+import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
+import { registerPluralName } from './plural-registry.js';
+import setupRestServer from './setup-rest-server.js';
+import baseTransforms from './transforms.js';
+import Store from './store.js';
+import Serializer from './serializer.js';
+import { setup } from '@stonyx/events';
+
+interface OrmOptions {
+  dbType?: string;
+}
+
+export interface SqlDb {
+  init(): Promise<unknown>;
+  startup(): Promise<void>;
+  shutdown(): Promise<void>;
+  persist(operation: string, model: string, context: unknown, response: unknown): Promise<void>;
+  findRecord(modelName: string, id: unknown): Promise<unknown>;
+  findAll(modelName: string, conditions?: Record<string, unknown>): Promise<unknown[]>;
+}
+
+export interface OrmDB {
+  record: unknown;
+  save(): Promise<void>;
+  init(): Promise<void>;
+}
+
+const defaultOptions: OrmOptions = {
+  dbType: 'json'
+}
+
+export default class Orm {
+  static initialized: boolean = false;
+  static relationships: Map<string, Map<string, unknown>> = new Map();
+  static store: Store = new Store();
+  static instance: Orm;
+  static ready: unknown[];
+
+  models: Record<string, unknown> = {};
+  serializers: Record<string, unknown> = {};
+  views: Record<string, unknown> = {};
+  transforms: Record<string, (value: unknown) => unknown> = { ...baseTransforms };
+  warnings: Set<string> = new Set();
+  options!: OrmOptions;
+  sqlDb?: SqlDb;
+  db?: OrmDB | SqlDb;
+
+  constructor(options: OrmOptions = {}) {
+    if (Orm.instance) return Orm.instance;
+
+    const { relationships } = Orm;
+
+    // Declare relationship maps
+    for (const key of ['hasMany', 'belongsTo', 'global', 'pending', 'pendingBelongsTo']) {
+      relationships.set(key, new Map());
+    }
+
+    this.options = { ...defaultOptions, ...options };
+
+    Orm.instance = this;
+  }
+
+  async init(): Promise<void> {
+    const { paths, restServer } = config.orm;
+
+    const promises: Promise<unknown>[] = ['Model', 'Serializer', 'Transform'].map(type => {
+      const lowerCaseType = type.toLowerCase();
+      const path = paths[lowerCaseType];
+
+      if (!path) throw new Error(`Configuration Error: ORM path for "${type}" must be defined.`);
+
+      return forEachFileImport(path, (exported: unknown, { name }: { name: string }) => {
+        // Transforms keep their original name, everything else gets converted to PascalCase with the type suffix
+        const alias = type === 'Transform' ? name : `${kebabCaseToPascalCase(name)}${type}`;
+
+        if (type === 'Model') {
+          Orm.store.set(name, new Map());
+          registerPluralName(name, exported as { pluralName?: string });
+        }
+
+        const collection = this[pluralize(lowerCaseType) as keyof this] as Record<string, unknown>;
+        return collection[alias] = exported;
+      }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
+    });
+
+    // Wait for imports before db & rest server setup
+    await Promise.all(promises);
+
+    // Discover views from paths.view (separate from model/serializer/transform)
+    if (paths.view) {
+      await forEachFileImport(paths.view, (exported: unknown, { name }: { name: string }) => {
+        const alias = `${kebabCaseToPascalCase(name)}View`;
+        Orm.store.set(name, new Map());
+        registerPluralName(name, exported as { pluralName?: string });
+        this.views[alias] = exported;
+      }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
+    }
+
+    // Setup event names for hooks after models are loaded
+    const eventNames: string[] = [];
+    const operations = ['list', 'get', 'create', 'update', 'delete'];
+    const viewOperations = ['list', 'get'];
+    const timings = ['before', 'after'];
+
+    for (const modelName of Orm.store.data.keys()) {
+      const isView = this.isView(modelName);
+      const ops = isView ? viewOperations : operations;
+
+      for (const timing of timings) {
+        for (const operation of ops) {
+          eventNames.push(`${timing}:${operation}:${modelName}`);
+        }
+      }
+    }
+
+    setup(eventNames);
+
+    if (config.orm.timescale) {
+      const { default: TimescaleDB } = await import('./timescale/timescale-db.js');
+      this.sqlDb = new TimescaleDB() as SqlDb;
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
+    } else if (config.orm.postgres) {
+      const { default: PostgresDB } = await import('./postgres/postgres-db.js');
+      this.sqlDb = new PostgresDB() as SqlDb;
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
+    } else if (config.orm.mysql) {
+      const { default: MysqlDB } = await import('./mysql/mysql-db.js');
+      this.sqlDb = new MysqlDB() as SqlDb;
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
+    } else if (this.options.dbType !== 'none') {
+      const db = new DB();
+      this.db = db;
+
+      promises.push(db.init());
+    }
+
+    if (restServer.enabled === 'true') {
+      promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
+    }
+
+    // Wire up memory resolver so store.find() can check model memory flags
+    Orm.store._memoryResolver = (modelName: string): boolean => {
+      const { modelClass } = this.getRecordClasses(modelName);
+      return (modelClass as { memory?: boolean })?.memory === true;
+    };
+
+    // Wire up SQL adapter reference for on-demand queries from store.find()/findAll()
+    if (this.sqlDb) {
+      Orm.store._sqlDb = this.sqlDb;
+    }
+
+    Orm.ready = await Promise.all(promises);
+    Orm.initialized = true;
+  }
+
+  async startup(): Promise<void> {
+    if (this.sqlDb) await this.sqlDb.startup();
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.sqlDb) await this.sqlDb.shutdown();
+  }
+
+  static get db(): OrmDB | SqlDb {
+    if (!Orm.initialized) throw new Error('ORM has not been initialized yet');
+
+    if (!Orm.instance.db) throw new Error('ORM database has not been initialized');
+    return Orm.instance.db;
+  }
+
+  getRecordClasses(modelName: string): { modelClass: unknown; serializerClass: unknown } {
+    const modelClassPrefix = kebabCaseToPascalCase(modelName);
+
+    // Check views first, then models
+    const viewClass = this.views[`${modelClassPrefix}View`];
+    if (viewClass) {
+      return {
+        modelClass: viewClass,
+        serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || Serializer
+      };
+    }
+
+    return {
+      modelClass: this.models[`${modelClassPrefix}Model`],
+      serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || Serializer
+    };
+  }
+
+  isView(modelName: string): boolean {
+    const modelClassPrefix = kebabCaseToPascalCase(modelName);
+    return !!this.views[`${modelClassPrefix}View`];
+  }
+
+  // Queue warnings to avoid the same error from being logged in the same iteration
+  warn(message: string): void {
+    this.warnings.add(message);
+
+    setTimeout(() => {
+      this.warnings.forEach(warning => log.warn?.(warning));
+      this.warnings.clear();
+    }, 0);
+  }
+}
+
+export const store = Orm.store;
+export const relationships = Orm.relationships;

package/src/manage-record.ts

@@ -0,0 +1,161 @@
+import Orm, { store } from '@stonyx/orm';
+import OrmRecord from './record.js';
+import { getGlobalRegistry, getPendingRegistry, getPendingBelongsToRegistry, getBelongsToRegistry, getHasManyRegistry } from './relationships.js';
+import type Serializer from './serializer.js';
+import { isOrmRecord } from './utils.js';
+
+interface CreateRecordOptions {
+  isDbRecord?: boolean;
+  serialize?: boolean;
+  transform?: boolean;
+  update?: boolean;
+  [key: string]: unknown;
+}
+
+interface PendingBelongsToEntry {
+  sourceRecord: OrmRecord;
+  sourceModelName: string;
+  relationshipKey: string;
+  relationshipId: unknown;
+}
+
+const defaultOptions: CreateRecordOptions = {
+  isDbRecord: false,
+  serialize: true,
+  transform: true
+};
+
+export function createRecord(modelName: string, rawData: { [key: string]: unknown } = {}, userOptions: CreateRecordOptions = {}): OrmRecord {
+  const orm = Orm.instance;
+  const { initialized } = Orm;
+  const options = { ...defaultOptions, ...userOptions };
+
+  if (!initialized && !options.isDbRecord) throw new Error('ORM is not ready');
+
+  // Guard: read-only views cannot have records created directly
+  if (orm?.isView?.(modelName) && !options.isDbRecord) {
+    throw new Error(`Cannot create records for read-only view '${modelName}'`);
+  }
+
+  const modelStore = store.get(modelName);
+  const globalRelationships = getGlobalRegistry();
+  const pendingRelationships = getPendingRegistry();
+
+  if (!modelStore) throw new Error(`Model store for '${modelName}' is not registered. Ensure the model is defined before creating records.`);
+
+  assignRecordId(modelName, rawData);
+  const existingRecord = modelStore.get(rawData.id as number | string);
+
+  if (existingRecord instanceof OrmRecord) {
+    // Update the existing record with new data so the last entry wins
+    updateRecord(existingRecord, rawData, { ...options, update: true });
+    return existingRecord;
+  }
+
+  const recordClasses = orm.getRecordClasses(modelName);
+  const modelClass = recordClasses.modelClass as (new (name: string) => { __name: string; [key: string]: unknown }) | undefined;
+  const serializerClass = recordClasses.serializerClass as new (model: { [key: string]: unknown }) => Serializer;
+
+  if (!modelClass) throw new Error(`A model named '${modelName}' does not exist`);
+
+  const model = new modelClass(modelName);
+  const serializer = new serializerClass(model);
+  const record = new OrmRecord(model, serializer);
+
+  record.serialize(rawData, options);
+  modelStore.set(record.id as number | string, record);
+
+  // populate global hasMany relationships
+  const globalHasMany = globalRelationships.get(modelName);
+  if (globalHasMany) for (const relationship of globalHasMany) relationship.push(record);
+
+  // populate pending hasMany relationships and clear the queue
+  const pendingHasMany = pendingRelationships.get(modelName)?.get(record.id);
+  if (pendingHasMany) {
+    for (const relationship of pendingHasMany) relationship.push(record);
+    pendingHasMany.splice(0);
+  }
+
+  // Fulfill pending belongsTo relationships
+  const pendingBelongsToQueue = getPendingBelongsToRegistry();
+  const pendingBelongsToRaw = pendingBelongsToQueue.get(modelName)?.get(record.id);
+  const pendingBelongsTo = Array.isArray(pendingBelongsToRaw) ? pendingBelongsToRaw as PendingBelongsToEntry[] : undefined;
+
+  if (pendingBelongsTo) {
+    const belongsToReg = getBelongsToRegistry();
+    const hasManyReg = getHasManyRegistry();
+
+    for (const { sourceRecord, sourceModelName, relationshipKey, relationshipId } of pendingBelongsTo) {
+      // Update the belongsTo relationship on the source record
+      sourceRecord.__relationships[relationshipKey] = record;
+      sourceRecord[relationshipKey] = record; // Also update the direct property
+
+      // Update the belongsTo relationship registry
+      const sourceModelReg = belongsToReg.get(sourceModelName);
+      if (sourceModelReg) {
+        const targetModelReg = sourceModelReg.get(modelName);
+        if (targetModelReg) {
+          targetModelReg.set(relationshipId, record);
+        }
+      }
+
+      // Wire inverse hasMany if it exists
+      const inverseHasMany = hasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
+
+      if (inverseHasMany && !inverseHasMany.includes(sourceRecord)) {
+        inverseHasMany.push(sourceRecord);
+      }
+    }
+
+    // Clear the pending queue
+    pendingBelongsTo.length = 0;
+  }
+
+  return record;
+}
+
+export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions = {}): void {
+  if (!rawData) throw new Error('rawData must be passed in to updateRecord call');
+
+  // Guard: read-only views cannot be updated
+  const modelName = record?.__model?.__name;
+  if (modelName && Orm.instance?.isView?.(modelName)) {
+    throw new Error(`Cannot update records for read-only view '${modelName}'`);
+  }
+
+  const options = { ...defaultOptions, ...userOptions, update: true };
+
+  record.serialize(rawData, options);
+}
+
+/**
+ * gets the next available id based on last record entry.
+ *
+ * In MySQL mode with numeric IDs, assigns a temporary pending ID.
+ * MySQL's AUTO_INCREMENT provides the real ID after INSERT.
+ */
+function assignRecordId(modelName: string, rawData: { [key: string]: unknown }): void {
+  if (rawData.id) return;
+
+  // In SQL mode with numeric IDs, defer to database auto-increment
+  if (Orm.instance?.sqlDb && !isStringIdModel(modelName)) {
+    rawData.id = `__pending_${Date.now()}_${Math.random()}`;
+    rawData.__pendingSqlId = true;
+    return;
+  }
+
+  const storeMap = store.get(modelName);
+  if (!storeMap) throw new Error(`Cannot assign record ID: model "${modelName}" not found in store`);
+  const modelStore = Array.from(storeMap.values()).filter(isOrmRecord);
+  const lastRecord = modelStore.at(-1);
+  rawData.id = lastRecord ? (lastRecord.id as number) + 1 : 1;
+}
+
+function isStringIdModel(modelName: string): boolean {
+  const modelClass = Orm.instance.getRecordClasses(modelName).modelClass as (new (name: string) => { [key: string]: unknown }) | undefined;
+  if (!modelClass) return false;
+
+  const model = new modelClass(modelName);
+
+  return (model.id as { type?: string } | undefined)?.type === 'string';
+}

package/src/{meta-request.js → meta-request.ts}

@@ -1,37 +1,40 @@
 import { Request } from '@stonyx/rest-server';
+import ModelProperty from './model-property.js';
 import Orm from '@stonyx/orm';
 import config from 'stonyx/config';
 import { dbKey } from './db.js';
 
 export default class MetaRequest extends Request {
-  constructor() {
-    super(...arguments);
-    
+  handlers: Record<string, unknown>;
+
+  constructor(...args: unknown[]) {
+    super(...args);
+
     this.handlers = {
       get: {
         '/meta': () => {
           try {
-            const { models } = Orm.instance;
-            const metadata = {};
+            const { models } = Orm.instance as Orm;
+            const metadata: Record<string, Record<string, unknown>> = {};
 
             for (const [modelName, modelClass] of Object.entries(models)) {
               const name = modelName.slice(0, -5).toLowerCase();
 
               if (name === dbKey) continue;
 
-              const model = new modelClass(modelName);
-              const properties = {};
+              const model = new (modelClass as new (name: string) => Record<string, unknown>)(modelName);
+              const properties: Record<string, unknown> = {};
 
               // Get regular properties and relationships
               for (const [key, property] of Object.entries(model)) {
                 // Skip internal properties
                 if (key.startsWith('__')) continue;
 
-                if (property?.constructor?.name === 'ModelProperty') {
-                  properties[key] = { type: property.type };
+                if (property instanceof ModelProperty) {
+                  properties[key] = { type: (property as { type: string }).type };
                 } else if (typeof property === 'function') {
-                  const isBelongsTo = property.toString().includes(`getRelationships('belongsTo',`);
-                  const isHasMany = property.toString().includes(`getRelationships('hasMany',`);
+                  const isBelongsTo = (property as { __relationshipType?: string }).__relationshipType === 'belongsTo';
+                  const isHasMany = (property as { __relationshipType?: string }).__relationshipType === 'hasMany';
 
                   if (isBelongsTo || isHasMany) properties[key] = { [isBelongsTo ? 'belongsTo' : 'hasMany']: name };
                 }
@@ -40,16 +43,16 @@ export default class MetaRequest extends Request {
               metadata[name] = properties;
             }
 
-            return metadata;            
+            return metadata;
           } catch (error) {
-            return { error: error.message };
+            return { error: error instanceof Error ? error.message : String(error) };
           }
         },
       },
     }
   }
 
-  auth() {
+  auth(): number | undefined {
     if (!config.orm.restServer.metaRoute) return 403;
   }
 }

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

@@ -4,10 +4,10 @@ import { createFile, createDirectory, readFile, updateFile, deleteDirectory } fr
 import { dbKey } from './db.js';
 import path from 'path';
 
-function getCollectionKeys() {
-  const SchemaClass = Orm.instance.models[`${dbKey}Model`];
+function getCollectionKeys(): string[] {
+  const SchemaClass = (Orm.instance as Orm).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;
@@ -17,7 +17,7 @@ function getCollectionKeys() {
   return keys;
 }
 
-function getDirPath() {
+function getDirPath(): string {
   const { rootPath } = config;
   const { file, directory } = config.orm.db;
   const dbDir = path.dirname(path.resolve(`${rootPath}/${file}`));
@@ -25,7 +25,7 @@ function getDirPath() {
   return path.join(dbDir, directory);
 }
 
-export async function fileToDirectory() {
+export async function fileToDirectory(): Promise<void> {
   const { rootPath } = config;
   const { file } = config.orm.db;
   const dbFilePath = path.resolve(`${rootPath}/${file}`);
@@ -33,7 +33,7 @@ export async function fileToDirectory() {
   const dirPath = getDirPath();
 
   // Read full data from db.json
-  const data = await readFile(dbFilePath, { json: true });
+  const data = await readFile(dbFilePath, { json: true }) as Record<string, unknown[]>;
 
   // Create directory and write each collection
   await createDirectory(dirPath);
@@ -43,13 +43,13 @@ export async function fileToDirectory() {
   ));
 
   // Overwrite db.json with empty-array skeleton
-  const skeleton = {};
+  const skeleton: Record<string, unknown[]> = {};
   for (const key of collectionKeys) skeleton[key] = [];
 
   await updateFile(dbFilePath, skeleton, { json: true });
 }
 
-export async function directoryToFile() {
+export async function directoryToFile(): Promise<void> {
   const { rootPath } = config;
   const { file } = config.orm.db;
   const dbFilePath = path.resolve(`${rootPath}/${file}`);
@@ -57,7 +57,7 @@ export async function directoryToFile() {
   const dirPath = getDirPath();
 
   // Read each collection from the directory
-  const assembled = {};
+  const assembled: Record<string, unknown> = {};
 
   await Promise.all(collectionKeys.map(async key => {
     const filePath = path.join(dirPath, `${key}.json`);

package/src/model-property.ts

@@ -0,0 +1,35 @@
+import Orm from '@stonyx/orm';
+
+function validType(type: string): boolean {
+  return Object.keys(Orm.instance.transforms).includes(type);
+}
+
+export default class ModelProperty {
+  readonly __kind = 'ModelProperty' as const;
+  type: string;
+  private _value: unknown;
+  ignoreFirstTransform?: boolean;
+
+  constructor(type: string = 'passthrough', defaultValue?: unknown) {
+    if (!validType(type)) throw new Error(`Invalid model property type: ${type}`);
+
+    this.type = type;
+    this.value = defaultValue;
+  }
+
+  get value(): unknown {
+    return this._value;
+  }
+
+  set value(newValue: unknown) {
+    if (this.ignoreFirstTransform) {
+      delete this.ignoreFirstTransform;
+      this._value = newValue;
+      return;
+    }
+
+    if (newValue === undefined) return;
+
+    this._value = newValue === null ? null : Orm.instance.transforms[this.type](newValue);
+  }
+}

package/src/model.ts

@@ -0,0 +1,21 @@
+import attr from './attr.js';
+
+export default class Model {
+  /**
+   * Controls whether records of this model are loaded into memory on startup.
+   *
+   * - true  → loaded on boot, kept in store
+   * - false → never cached; find() always queries MySQL (default)
+   *
+   * Override in subclass: static memory = true;
+   */
+  static memory: boolean = false;
+  static pluralName: string | undefined = undefined;
+
+  id = attr('number');
+  __name: string;
+
+  constructor(name: string) {
+    this.__name = name;
+  }
+}

package/src/mysql/{connection.js → connection.ts}

@@ -1,28 +1,43 @@
-let pool = null;
-
-export async function getPool(mysqlConfig) {
-  if (pool) return pool;
-
-  const mysql = await import('mysql2/promise');
-
-  pool = mysql.createPool({
-    host: mysqlConfig.host,
-    port: mysqlConfig.port,
-    user: mysqlConfig.user,
-    password: mysqlConfig.password,
-    database: mysqlConfig.database,
-    connectionLimit: mysqlConfig.connectionLimit,
-    waitForConnections: true,
-    enableKeepAlive: true,
-    keepAliveInitialDelay: 10000,
-  });
-
-  return pool;
-}
-
-export async function closePool() {
-  if (!pool) return;
-
-  await pool.end();
-  pool = null;
-}
+import type { Pool } from 'mysql2/promise';
+
+interface MysqlConfig {
+  host: string;
+  port?: number;
+  user: string;
+  password: string;
+  database: string;
+  connectionLimit?: number;
+  migrationsTable?: string;
+  migrationsDir?: string;
+}
+
+let pool: Pool | null = null;
+
+export async function getPool(mysqlConfig: MysqlConfig): Promise<Pool> {
+  if (pool) return pool;
+
+  const mysql = await import('mysql2/promise');
+
+  pool = mysql.createPool({
+    host: mysqlConfig.host,
+    port: mysqlConfig.port,
+    user: mysqlConfig.user,
+    password: mysqlConfig.password,
+    database: mysqlConfig.database,
+    connectionLimit: mysqlConfig.connectionLimit,
+    waitForConnections: true,
+    enableKeepAlive: true,
+    keepAliveInitialDelay: 10000,
+  });
+
+  return pool;
+}
+
+export async function closePool(): Promise<void> {
+  if (!pool) return;
+
+  await pool.end();
+  pool = null;
+}
+
+export type { MysqlConfig };