@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/dist/schema-helpers.js

@@ -0,0 +1,48 @@
+/**
+ * Detect relationship type and target model from a model property function.
+ * Returns null if the property is not a relationship.
+ */
+export function getRelationshipInfo(property) {
+    if (typeof property !== 'function')
+        return null;
+    const relType = property.__relationshipType;
+    const modelName = property.__relatedModelName || null;
+    if (relType === 'belongsTo')
+        return { type: 'belongsTo', modelName };
+    if (relType === 'hasMany')
+        return { type: 'hasMany', modelName };
+    return null;
+}
+/**
+ * Sanitize a model/table name for use in SQL identifiers.
+ * Replaces hyphens and slashes with underscores.
+ */
+export function sanitizeTableName(name) {
+    return name.replace(/[-/]/g, '_');
+}
+/**
+ * Sort model schemas in dependency order (belongsTo targets before dependents).
+ * Uses depth-first traversal to ensure referenced tables are created first.
+ */
+export function getTopologicalOrder(schemas) {
+    const visited = new Set();
+    const order = [];
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        const schema = schemas[name];
+        if (!schema)
+            return;
+        // Visit dependencies (belongsTo targets) first
+        for (const targetModelName of Object.values(schema.relationships.belongsTo)) {
+            if (targetModelName)
+                visit(targetModelName);
+        }
+        order.push(name);
+    }
+    for (const name of Object.keys(schemas)) {
+        visit(name);
+    }
+    return order;
+}

package/dist/serializer.d.ts

@@ -0,0 +1,17 @@
+export default class Serializer {
+    map: Record<string, unknown>;
+    path: string;
+    model: Record<string, unknown>;
+    constructor(model: Record<string, unknown>);
+    /**
+     * 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;
+    /**
+     * OVERRIDE: This hook allows for data manipulation prior to serialization logic
+     */
+    normalize(data: unknown): unknown;
+}
+export declare function getComputedProperties(classInstance: Record<string, unknown>): [string, PropertyDescriptor['get']][];

package/dist/serializer.js

@@ -0,0 +1,136 @@
+import config from 'stonyx/config';
+import { get, makeArray } from '@stonyx/utils/object';
+const RESERVED_KEYS = ['__name'];
+function isAggregateProperty(v) {
+    return typeof v === 'object' && v !== null && v.__kind === 'AggregateProperty';
+}
+function isModelProperty(v) {
+    return typeof v === 'object' && v !== null && v.__kind === 'ModelProperty';
+}
+function searchQuery(query, array, key) {
+    const result = makeArray(array).find((item) => {
+        for (const [prop, value] of Object.entries(query)) {
+            if (item[prop] !== value)
+                return false;
+            return true;
+        }
+    });
+    if (!result)
+        return null;
+    if (key)
+        return result[key];
+    return result;
+}
+function query(rawData, pathPrefix, subPath) {
+    if (!rawData)
+        return null;
+    const [path, getter, pointer] = makeArray(subPath);
+    const fullPath = `${pathPrefix}${path}`;
+    const value = get(rawData, fullPath);
+    if (getter === undefined || getter === null)
+        return value;
+    try {
+        switch (typeof getter) {
+            case 'object':
+                return searchQuery(getter, value, pointer);
+            case 'function':
+                return getter(value);
+            case 'number': {
+                const element = value[getter];
+                return pointer ? element[pointer] : element;
+            }
+            default:
+                return value[getter];
+        }
+    }
+    catch (error) {
+        if (config.debug)
+            console.error(`Cannot parse value for ${fullPath}.`, { getter, query }, error);
+    }
+}
+export default class Serializer {
+    map = {};
+    path = '';
+    model;
+    constructor(model) {
+        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, record, options) {
+        const { path, model } = this;
+        const keys = Object.keys(model).filter(key => !RESERVED_KEYS.includes(key));
+        const pathPrefix = path ? `${path}.` : '';
+        const rec = record;
+        const parsedData = rec.__data;
+        const relatedRecords = rec.__relationships;
+        for (const key of keys) {
+            const subPath = options.serialize ? (this.map[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;
+            Object.defineProperty(record, key, {
+                enumerable: true,
+                configurable: true,
+                get: () => prop.value,
+                set(newValue) {
+                    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.call(record)
+            });
+        }
+        rec.__serialized = true;
+    }
+    /**
+     * OVERRIDE: This hook allows for data manipulation prior to serialization logic
+     */
+    normalize(data) {
+        return data;
+    }
+}
+export function getComputedProperties(classInstance) {
+    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/dist/setup-rest-server.d.ts

@@ -0,0 +1 @@
+export default function (route: string, accessPath: string, metaRoute: boolean): Promise<void>;

package/dist/setup-rest-server.js

@@ -0,0 +1,52 @@
+import { waitForModule } from 'stonyx';
+import { store } from '@stonyx/orm';
+import OrmRequest from './orm-request.js';
+import MetaRequest from './meta-request.js';
+import RestServer from '@stonyx/rest-server';
+import { forEachFileImport } from '@stonyx/utils/file';
+import { dbKey } from './db.js';
+import { getPluralName } from './plural-registry.js';
+import log from 'stonyx/log';
+export default async function (route, accessPath, metaRoute) {
+    const accessFiles = {};
+    try {
+        await forEachFileImport(accessPath, (accessClass) => {
+            const accessInstance = new accessClass();
+            const { models } = accessInstance;
+            if (!models)
+                throw new Error(`Access class "${accessClass.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`);
+            const availableModels = Array.from(store.data.keys());
+            for (const model of models === '*' ? availableModels : models) {
+                if (model === dbKey)
+                    continue;
+                if (!store.data.has(model))
+                    throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
+                if (accessFiles[model])
+                    throw new Error(`Access for model "${model}" has already been defined by another access class.`);
+                accessFiles[model] = accessInstance.access;
+            }
+        });
+    }
+    catch (error) {
+        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');
+    // Remove "/" prefix and name mount point accordingly
+    const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
+    // Configure endpoints for models and views with access configuration
+    for (const [model, access] of Object.entries(accessFiles)) {
+        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!');
+        RestServer.instance.mountRoute(MetaRequest, { name });
+    }
+}

package/dist/standalone-db.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+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);
+    /**
+     * Resolve the directory path for directory mode.
+     */
+    getDirPath(): string;
+    /**
+     * List available collections by inspecting either the db.json keys
+     * or the files in the db directory.
+     */
+    getCollections(): Promise<string[]>;
+    /**
+     * Read all records for a collection.
+     */
+    readCollection(collection: string): Promise<DBRecord[]>;
+    /**
+     * Write all records for a collection.
+     */
+    writeCollection(collection: string, records: DBRecord[]): Promise<void>;
+    /**
+     * Get a single record by id.
+     */
+    get(collection: string, id: string | number): Promise<DBRecord | null>;
+    /**
+     * List all records in a collection.
+     */
+    list(collection: string): Promise<DBRecord[]>;
+    /**
+     * Create a new record. Auto-assigns an integer id if none provided.
+     */
+    create(collection: string, data: DBRecord): Promise<DBRecord>;
+    /**
+     * Delete a record by id.
+     */
+    delete(collection: string, id: string | number): Promise<DBRecord>;
+    private _readJSON;
+    private _writeJSON;
+}
+export {};

package/dist/standalone-db.js

@@ -0,0 +1,142 @@
+/**
+ * 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';
+export default class StandaloneDB {
+    mode;
+    dbPath;
+    directory;
+    constructor(options = {}) {
+        this.mode = options.mode || 'directory';
+        this.dbPath = options.dbPath || 'db.json';
+        this.directory = options.directory || 'db';
+    }
+    /**
+     * Resolve the directory path for directory mode.
+     */
+    getDirPath() {
+        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() {
+        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);
+            return Object.keys(data).filter(key => Array.isArray(data[key]));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Read all records for a collection.
+     */
+    async readCollection(collection) {
+        if (this.mode === 'directory') {
+            const filePath = path.join(this.getDirPath(), `${collection}.json`);
+            return this._readJSON(filePath);
+        }
+        const data = await this._readJSON(this.dbPath);
+        return data[collection] || [];
+    }
+    /**
+     * Write all records for a collection.
+     */
+    async writeCollection(collection, records) {
+        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;
+        try {
+            data = await this._readJSON(this.dbPath);
+        }
+        catch {
+            data = {};
+        }
+        data[collection] = records;
+        await this._writeJSON(this.dbPath, data);
+    }
+    /**
+     * Get a single record by id.
+     */
+    async get(collection, id) {
+        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) {
+        return this.readCollection(collection);
+    }
+    /**
+     * Create a new record. Auto-assigns an integer id if none provided.
+     */
+    async create(collection, data) {
+        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, id) {
+        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 --
+    async _readJSON(filePath) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    async _writeJSON(filePath, data) {
+        await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,62 @@
+interface UnloadOptions {
+    includeChildren?: boolean;
+    [key: string]: unknown;
+}
+export default class Store {
+    static instance: Store | undefined;
+    data: Map<string, Map<number | string, unknown>>;
+    /**
+     * Set by Orm during init — resolves memory flag for a model name.
+     */
+    _memoryResolver: ((modelName: string) => boolean) | null;
+    /**
+     * Set by Orm during init — reference to the SQL adapter instance for on-demand queries.
+     */
+    _sqlDb: {
+        findRecord(modelName: string, id: unknown): Promise<unknown>;
+        findAll(modelName: string, conditions?: Record<string, unknown>): Promise<unknown[]>;
+    } | null;
+    constructor();
+    /**
+     * Synchronous memory-only access.
+     * Returns the record if it exists in the in-memory store, undefined otherwise.
+     * Does NOT query the database. For memory:false models, use find() instead.
+     */
+    get(key: string): Map<number | string, unknown> | undefined;
+    get(key: string, id: number | string): unknown;
+    /**
+     * Async authoritative read. Always queries the SQL database for memory: false models.
+     * For memory: true models, returns from store (already loaded on boot).
+     */
+    find(modelName: string, id: number | string): Promise<unknown>;
+    /**
+     * Async read for all records of a model. Always queries MySQL for memory: false models.
+     * For memory: true models, returns from store.
+     */
+    findAll(modelName: string, conditions?: Record<string, unknown>): Promise<unknown[]>;
+    /**
+     * Async query — always hits MySQL, never reads from memory cache.
+     * Use for complex queries, aggregations, or when you need guaranteed freshness.
+     */
+    query(modelName: string, conditions?: Record<string, unknown>): Promise<unknown[]>;
+    /**
+     * Check if a model is configured for in-memory storage.
+     * @private
+     */
+    private _isMemoryModel;
+    set(key: string, value: Map<number | string, unknown>): void;
+    remove(key: string, id?: number | string): void;
+    unloadRecord(model: string, id: unknown, options?: UnloadOptions): void;
+    unloadAllRecords(model: string, options?: UnloadOptions): void;
+    private _removeFromHasManyArrays;
+    private _nullifyBelongsToReferences;
+    private _cleanupRelationshipRegistries;
+    /**
+     * Extracts hasMany and non-bidirectional belongsTo children from a record
+     * @private
+     */
+    private _getChildren;
+    private _isBidirectionalRelationship;
+    private _buildUnloadQueue;
+}
+export {};