@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/dist/main.js

@@ -0,0 +1,181 @@
+/*
+ * 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';
+const defaultOptions = {
+    dbType: 'json'
+};
+export default class Orm {
+    static initialized = false;
+    static relationships = new Map();
+    static store = new Store();
+    static instance;
+    static ready;
+    models = {};
+    serializers = {};
+    views = {};
+    transforms = { ...baseTransforms };
+    warnings = new Set();
+    options;
+    sqlDb;
+    db;
+    constructor(options = {}) {
+        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() {
+        const { paths, restServer } = config.orm;
+        const promises = ['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, { name }) => {
+                // 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);
+                }
+                const collection = this[pluralize(lowerCaseType)];
+                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, { name }) => {
+                const alias = `${kebabCaseToPascalCase(name)}View`;
+                Orm.store.set(name, new Map());
+                registerPluralName(name, exported);
+                this.views[alias] = exported;
+            }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
+        }
+        // Setup event names for hooks after models are loaded
+        const eventNames = [];
+        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();
+            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();
+            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();
+            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) => {
+            const { modelClass } = this.getRecordClasses(modelName);
+            return modelClass?.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() {
+        if (this.sqlDb)
+            await this.sqlDb.startup();
+    }
+    async shutdown() {
+        if (this.sqlDb)
+            await this.sqlDb.shutdown();
+    }
+    static get db() {
+        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) {
+        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) {
+        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) {
+        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/dist/manage-record.d.ts

@@ -0,0 +1,13 @@
+import OrmRecord from './record.js';
+interface CreateRecordOptions {
+    isDbRecord?: boolean;
+    serialize?: boolean;
+    transform?: boolean;
+    update?: boolean;
+    [key: string]: unknown;
+}
+export declare function createRecord(modelName: string, rawData?: {
+    [key: string]: unknown;
+}, userOptions?: CreateRecordOptions): OrmRecord;
+export declare function updateRecord(record: OrmRecord, rawData: unknown, userOptions?: CreateRecordOptions): void;
+export {};

package/dist/manage-record.js

@@ -0,0 +1,123 @@
+import Orm, { store } from '@stonyx/orm';
+import OrmRecord from './record.js';
+import { getGlobalRegistry, getPendingRegistry, getPendingBelongsToRegistry, getBelongsToRegistry, getHasManyRegistry } from './relationships.js';
+import { isOrmRecord } from './utils.js';
+const defaultOptions = {
+    isDbRecord: false,
+    serialize: true,
+    transform: true
+};
+export function createRecord(modelName, rawData = {}, userOptions = {}) {
+    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);
+    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;
+    const serializerClass = recordClasses.serializerClass;
+    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, 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 : 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, rawData, userOptions = {}) {
+    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, rawData) {
+    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 + 1 : 1;
+}
+function isStringIdModel(modelName) {
+    const modelClass = Orm.instance.getRecordClasses(modelName).modelClass;
+    if (!modelClass)
+        return false;
+    const model = new modelClass(modelName);
+    return model.id?.type === 'string';
+}

package/dist/meta-request.d.ts

@@ -0,0 +1,6 @@
+import { Request } from '@stonyx/rest-server';
+export default class MetaRequest extends Request {
+    handlers: Record<string, unknown>;
+    constructor(...args: unknown[]);
+    auth(): number | undefined;
+}

package/dist/meta-request.js

@@ -0,0 +1,52 @@
+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 {
+    handlers;
+    constructor(...args) {
+        super(...args);
+        this.handlers = {
+            get: {
+                '/meta': () => {
+                    try {
+                        const { models } = Orm.instance;
+                        const metadata = {};
+                        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 = {};
+                            // Get regular properties and relationships
+                            for (const [key, property] of Object.entries(model)) {
+                                // Skip internal properties
+                                if (key.startsWith('__'))
+                                    continue;
+                                if (property instanceof ModelProperty) {
+                                    properties[key] = { type: property.type };
+                                }
+                                else if (typeof property === 'function') {
+                                    const isBelongsTo = property.__relationshipType === 'belongsTo';
+                                    const isHasMany = property.__relationshipType === 'hasMany';
+                                    if (isBelongsTo || isHasMany)
+                                        properties[key] = { [isBelongsTo ? 'belongsTo' : 'hasMany']: name };
+                                }
+                            }
+                            metadata[name] = properties;
+                        }
+                        return metadata;
+                    }
+                    catch (error) {
+                        return { error: error instanceof Error ? error.message : String(error) };
+                    }
+                },
+            },
+        };
+    }
+    auth() {
+        if (!config.orm.restServer.metaRoute)
+            return 403;
+    }
+}

package/dist/migrate.d.ts

@@ -0,0 +1,2 @@
+export declare function fileToDirectory(): Promise<void>;
+export declare function directoryToFile(): Promise<void>;

package/dist/migrate.js

@@ -0,0 +1,57 @@
+import config from 'stonyx/config';
+import Orm from '@stonyx/orm';
+import { createFile, createDirectory, readFile, updateFile, deleteDirectory } from '@stonyx/utils/file';
+import { dbKey } from './db.js';
+import path from 'path';
+function 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;
+}
+function getDirPath() {
+    const { rootPath } = config;
+    const { file, directory } = config.orm.db;
+    const dbDir = path.dirname(path.resolve(`${rootPath}/${file}`));
+    return path.join(dbDir, directory);
+}
+export async function fileToDirectory() {
+    const { rootPath } = config;
+    const { file } = config.orm.db;
+    const dbFilePath = path.resolve(`${rootPath}/${file}`);
+    const collectionKeys = getCollectionKeys();
+    const dirPath = getDirPath();
+    // Read full data from db.json
+    const data = await readFile(dbFilePath, { json: true });
+    // Create directory and write each collection
+    await createDirectory(dirPath);
+    await Promise.all(collectionKeys.map(key => createFile(path.join(dirPath, `${key}.json`), data[key] || [], { json: true })));
+    // Overwrite db.json with empty-array skeleton
+    const skeleton = {};
+    for (const key of collectionKeys)
+        skeleton[key] = [];
+    await updateFile(dbFilePath, skeleton, { json: true });
+}
+export async function directoryToFile() {
+    const { rootPath } = config;
+    const { file } = config.orm.db;
+    const dbFilePath = path.resolve(`${rootPath}/${file}`);
+    const collectionKeys = getCollectionKeys();
+    const dirPath = getDirPath();
+    // Read each collection from the directory
+    const assembled = {};
+    await Promise.all(collectionKeys.map(async (key) => {
+        const filePath = path.join(dirPath, `${key}.json`);
+        assembled[key] = await readFile(filePath, { json: true });
+    }));
+    // Overwrite db.json with full assembled data
+    await updateFile(dbFilePath, assembled, { json: true });
+    // Remove the directory
+    await deleteDirectory(dirPath);
+}

package/dist/model-property.d.ts

@@ -0,0 +1,9 @@
+export default class ModelProperty {
+    readonly __kind: "ModelProperty";
+    type: string;
+    private _value;
+    ignoreFirstTransform?: boolean;
+    constructor(type?: string, defaultValue?: unknown);
+    get value(): unknown;
+    set value(newValue: unknown);
+}

package/dist/model-property.js

@@ -0,0 +1,29 @@
+import Orm from '@stonyx/orm';
+function validType(type) {
+    return Object.keys(Orm.instance.transforms).includes(type);
+}
+export default class ModelProperty {
+    __kind = 'ModelProperty';
+    type;
+    _value;
+    ignoreFirstTransform;
+    constructor(type = 'passthrough', defaultValue) {
+        if (!validType(type))
+            throw new Error(`Invalid model property type: ${type}`);
+        this.type = type;
+        this.value = defaultValue;
+    }
+    get value() {
+        return this._value;
+    }
+    set value(newValue) {
+        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/dist/model.d.ts

@@ -0,0 +1,15 @@
+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;
+    static pluralName: string | undefined;
+    id: import("./model-property.js").default;
+    __name: string;
+    constructor(name: string);
+}

package/dist/model.js

@@ -0,0 +1,18 @@
+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 = false;
+    static pluralName = undefined;
+    id = attr('number');
+    __name;
+    constructor(name) {
+        this.__name = name;
+    }
+}

package/dist/mysql/connection.d.ts

@@ -0,0 +1,14 @@
+import type { Pool } from 'mysql2/promise';
+interface MysqlConfig {
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    database: string;
+    connectionLimit?: number;
+    migrationsTable?: string;
+    migrationsDir?: string;
+}
+export declare function getPool(mysqlConfig: MysqlConfig): Promise<Pool>;
+export declare function closePool(): Promise<void>;
+export type { MysqlConfig };

package/dist/mysql/connection.js

@@ -0,0 +1,24 @@
+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;
+}

package/dist/mysql/migration-generator.d.ts

@@ -0,0 +1,45 @@
+import type { ModelSchema, SnapshotEntry, ViewSnapshotEntry, ForeignKeyDef } from './schema-introspector.js';
+interface ColumnChange {
+    model: string;
+    column: string;
+    type: string;
+}
+interface ColumnTypeChange {
+    model: string;
+    column: string;
+    from: string;
+    to: string;
+}
+interface ForeignKeyChange {
+    model: string;
+    column: string;
+    references: ForeignKeyDef;
+}
+interface SnapshotDiff {
+    hasChanges: boolean;
+    addedModels: string[];
+    removedModels: string[];
+    addedColumns: ColumnChange[];
+    removedColumns: ColumnChange[];
+    changedColumns: ColumnTypeChange[];
+    addedForeignKeys: ForeignKeyChange[];
+    removedForeignKeys: ForeignKeyChange[];
+}
+interface ViewDiff {
+    hasChanges: boolean;
+    addedViews: string[];
+    removedViews: string[];
+    changedViews: string[];
+}
+interface GeneratedMigration {
+    filename: string;
+    content: string;
+    snapshot: Record<string, SnapshotEntry | ViewSnapshotEntry>;
+}
+export declare function generateMigration(description?: string): Promise<GeneratedMigration | null>;
+export declare function loadLatestSnapshot(migrationsPath: string): Promise<Record<string, unknown>>;
+export declare function diffSnapshots(previous: Record<string, SnapshotEntry>, current: Record<string, SnapshotEntry>): SnapshotDiff;
+export declare function detectSchemaDrift(schemas: Record<string, ModelSchema>, snapshot: Record<string, SnapshotEntry>): SnapshotDiff;
+export declare function extractViewsFromSnapshot(snapshot: Record<string, unknown>): Record<string, ViewSnapshotEntry>;
+export declare function diffViewSnapshots(previous: Record<string, ViewSnapshotEntry>, current: Record<string, ViewSnapshotEntry>): ViewDiff;
+export {};