@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/dist/db.js

@@ -0,0 +1,180 @@
+/*
+ * 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 Cron from '@stonyx/cron';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+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';
+function asDBRecord(value) {
+    if (typeof value !== 'object' || value === null || typeof value.format !== 'function') {
+        throw new Error('createRecord did not return a valid DBRecord');
+    }
+    return value;
+}
+export default class DB {
+    static instance;
+    record;
+    constructor() {
+        if (DB.instance)
+            return DB.instance;
+        DB.instance = this;
+    }
+    async getSchema() {
+        const { rootPath } = config;
+        const { file, schema } = config.orm.db;
+        if (!file)
+            throw new Error('Configuration Error: ORM DB file path must be defined.');
+        return (await import(`${rootPath}/${schema}`)).default;
+    }
+    getCollectionKeys() {
+        const SchemaClass = Orm.instance.models[`${dbKey}Model`];
+        const instance = new SchemaClass();
+        const keys = [];
+        for (const key of Object.keys(instance)) {
+            if (key === '__name' || key === 'id')
+                continue;
+            if (typeof instance[key] === 'function')
+                keys.push(key);
+        }
+        return keys;
+    }
+    getDirPath() {
+        const { rootPath } = config;
+        const { file, directory } = config.orm.db;
+        const dbDir = path.dirname(path.resolve(`${rootPath}/${file}`));
+        return path.join(dbDir, directory);
+    }
+    async validateMode() {
+        const { rootPath } = config;
+        const { file, mode } = config.orm.db;
+        const collectionKeys = this.getCollectionKeys();
+        const dirPath = this.getDirPath();
+        if (mode === 'directory') {
+            const dbFilePath = path.resolve(`${rootPath}/${file}`);
+            const exists = await fileExists(dbFilePath);
+            if (exists) {
+                const data = await readFile(dbFilePath, { json: true });
+                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`);
+                    process.exit(1);
+                }
+            }
+        }
+        else {
+            const dirExists = await fileExists(dirPath);
+            if (dirExists) {
+                const hasCollectionFiles = (await Promise.all(collectionKeys.map(key => fileExists(path.join(dirPath, `${key}.json`))))).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`);
+                    process.exit(1);
+                }
+            }
+        }
+    }
+    async init() {
+        const { autosave, saveInterval } = config.orm.db;
+        store.set(dbKey, new Map());
+        Orm.instance.models[`${dbKey}Model`] = await this.getSchema();
+        await this.validateMode();
+        this.record = await this.getRecord();
+        if (autosave !== 'true')
+            return;
+        new Cron().register('save', this.save.bind(this), saveInterval);
+    }
+    async create() {
+        const { rootPath } = config;
+        const { file, mode } = config.orm.db;
+        if (mode === 'directory') {
+            const dirPath = this.getDirPath();
+            const collectionKeys = this.getCollectionKeys();
+            await createDirectory(dirPath);
+            await Promise.all(collectionKeys.map(key => createFile(path.join(dirPath, `${key}.json`), [], { json: true })));
+            // Write empty-array skeleton to db.json
+            const skeleton = {};
+            for (const key of collectionKeys)
+                skeleton[key] = [];
+            await createFile(`${rootPath}/${file}`, skeleton, { json: true });
+            return skeleton;
+        }
+        createFile(`${rootPath}/${file}`, {}, { json: true });
+        return {};
+    }
+    async save() {
+        const { file, mode } = config.orm.db;
+        const jsonData = this.record.format();
+        delete jsonData.id; // Don't save id
+        if (mode === 'directory') {
+            const dirPath = this.getDirPath();
+            const collectionKeys = this.getCollectionKeys();
+            // Write each collection to its own file in parallel
+            // 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] || []);
+                if (exists)
+                    await updateFile(filePath, data, { json: true });
+                else
+                    await createFile(filePath, data, { json: true });
+            }));
+            // Write empty-array skeleton to db.json
+            const skeleton = {};
+            for (const key of collectionKeys)
+                skeleton[key] = [];
+            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`);
+            return;
+        }
+        await updateFile(`${config.rootPath}/${file}`, jsonData, { json: true });
+        log.db?.(`DB has been successfully saved to ${file}`);
+    }
+    async getRecord() {
+        const { mode } = config.orm.db;
+        if (mode === 'directory')
+            return this.getRecordFromDirectory();
+        return this.getRecordFromFile();
+    }
+    async getRecordFromFile() {
+        const { file } = config.orm.db;
+        const data = await readFile(file, { json: true, missingFileCallback: this.create.bind(this) });
+        return asDBRecord(createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false }));
+    }
+    async getRecordFromDirectory() {
+        const dirPath = this.getDirPath();
+        const collectionKeys = this.getCollectionKeys();
+        const dirExists = await fileExists(dirPath);
+        if (!dirExists) {
+            const data = await this.create();
+            return asDBRecord(createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false }));
+        }
+        const assembled = {};
+        await Promise.all(collectionKeys.map(async (key) => {
+            const filePath = path.join(dirPath, `${key}.json`);
+            const exists = await fileExists(filePath);
+            assembled[key] = exists ? await readFile(filePath, { json: true }) : [];
+        }));
+        return asDBRecord(createRecord(dbKey, assembled, { isDbRecord: true, serialize: false, transform: false }));
+    }
+}

package/dist/exports/db.d.ts

@@ -0,0 +1,7 @@
+declare const db: {
+    record: unknown;
+    save(): Promise<void>;
+};
+export default db;
+export declare const data: unknown;
+export declare const saveDB: () => Promise<void>;

package/{src → dist}/exports/db.js

@@ -1,7 +1,5 @@
 import Orm from '@stonyx/orm';
-
-const { db } = Orm;
-
+const db = Orm.db;
 export default db;
 export const data = db.record;
-export const saveDB = db.save.bind(db);
+export const saveDB = db.save.bind(db);

package/dist/has-many.d.ts

@@ -0,0 +1,11 @@
+import type { SourceRecord } from './types/orm-types.js';
+interface HasManyOptions {
+    global?: boolean;
+    [key: string]: unknown;
+}
+type RelationshipHandler = ((sourceRecord: SourceRecord, rawData: unknown, options: HasManyOptions) => unknown[]) & {
+    __relatedModelName: string;
+    __relationshipType: 'hasMany';
+};
+export default function hasMany(modelName: string): RelationshipHandler;
+export {};

package/dist/has-many.js

@@ -0,0 +1,58 @@
+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';
+function queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, id) {
+    pendingRelationshipQueue.push({
+        pendingRelationship: getOrSet(pendingRelationships, modelName, new Map()),
+        id
+    });
+    return null;
+}
+export default function hasMany(modelName) {
+    const globalRelationships = getGlobalRegistry();
+    const pendingRelationships = getPendingRegistry();
+    const fn = (sourceRecord, rawData, options) => {
+        const { __name: sourceModelName } = sourceRecord.__model;
+        const relationshipId = sourceRecord.id;
+        const relationship = getRelationships('hasMany', sourceModelName, modelName, relationshipId);
+        const modelStore = store.get(modelName);
+        const pendingRelationshipQueue = [];
+        const output = !rawData ? [] : makeArray(rawData).map((elementData) => {
+            let record;
+            if (typeof elementData !== 'object') {
+                if (!modelStore) {
+                    return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+                }
+                record = modelStore.get(elementData);
+                if (!record) {
+                    return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+                }
+            }
+            else {
+                if (elementData !== Object(elementData)) {
+                    return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
+                }
+                record = createRecord(modelName, elementData, options);
+            }
+            // Populate belongTo side if the relationship is defined
+            const recordWithId = typeof record === 'object' && record !== null && 'id' in record ? record : undefined;
+            const otherSide = recordWithId ? getBelongsToRegistry()
+                .get(modelName)?.get(sourceModelName)?.get(recordWithId.id) : undefined;
+            if (otherSide)
+                Object.assign(otherSide, sourceRecord);
+            return record;
+        }).filter((value) => 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' });
+    return fn;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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>;
+/**
+ * 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 declare function beforeHook(operation: string, model: string, handler: HookHandler): () => void;
+/**
+ * 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 declare function afterHook(operation: string, model: string, handler: HookHandler): () => void;
+/**
+ * Get all before hooks for an operation:model combination.
+ */
+export declare function getBeforeHooks(operation: string, model: string): HookHandler[];
+/**
+ * Get all after hooks for an operation:model combination.
+ */
+export declare function getAfterHooks(operation: string, model: string): HookHandler[];
+/**
+ * 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 declare function clearHook(operation: string, model: string, type?: 'before' | 'after'): void;
+/**
+ * Clear all hooks (useful for testing).
+ */
+export declare function clearAllHooks(): void;
+export {};

package/dist/hooks.js

@@ -0,0 +1,110 @@
+/*
+ * 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.
+ */
+// Map of "operation:model" -> handler[]
+const beforeHooks = new Map();
+const afterHooks = 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, model, handler) {
+    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, model, handler) {
+    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, model) {
+    const key = `${operation}:${model}`;
+    return beforeHooks.get(key) || [];
+}
+/**
+ * Get all after hooks for an operation:model combination.
+ */
+export function getAfterHooks(operation, model) {
+    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, model, type) {
+    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() {
+    beforeHooks.clear();
+    afterHooks.clear();
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+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, View, Serializer };
+export { attr, belongsTo, hasMany, createRecord, updateRecord };
+export { count, avg, sum, min, max };
+export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js';

package/dist/index.js

@@ -0,0 +1,34 @@
+/*
+ * 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 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, View, Serializer }; // base classes
+export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
+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

package/dist/main.d.ts

@@ -0,0 +1,46 @@
+import Store from './store.js';
+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>;
+}
+export default class Orm {
+    static initialized: boolean;
+    static relationships: Map<string, Map<string, unknown>>;
+    static store: 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>;
+    warnings: Set<string>;
+    options: OrmOptions;
+    sqlDb?: SqlDb;
+    db?: OrmDB | SqlDb;
+    constructor(options?: OrmOptions);
+    init(): Promise<void>;
+    startup(): Promise<void>;
+    shutdown(): Promise<void>;
+    static get db(): OrmDB | SqlDb;
+    getRecordClasses(modelName: string): {
+        modelClass: unknown;
+        serializerClass: unknown;
+    };
+    isView(modelName: string): boolean;
+    warn(message: string): void;
+}
+export declare const store: Store;
+export declare const relationships: Map<string, Map<string, unknown>>;
+export {};