@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/dist/orm-request.js

@@ -0,0 +1,475 @@
+import { Request } from '@stonyx/rest-server';
+import Orm, { store, createRecord, updateRecord } from '@stonyx/orm';
+import { camelCaseToKebabCase } from '@stonyx/utils/string';
+import { getPluralName } from './plural-registry.js';
+import { getBeforeHooks, getAfterHooks } from './hooks.js';
+import config from 'stonyx/config';
+import { isOrmRecord } from './utils.js';
+const methodAccessMap = {
+    GET: 'read',
+    POST: 'create',
+    DELETE: 'delete',
+    PATCH: 'update',
+};
+const WRITE_OPERATIONS = new Set(['create', 'update', 'delete']);
+// Helper to detect relationship type from function
+function getRelationshipInfo(property) {
+    if (typeof property !== 'function')
+        return null;
+    const relType = property.__relationshipType;
+    if (relType === 'belongsTo') {
+        return { type: 'belongsTo', isArray: false };
+    }
+    if (relType === 'hasMany') {
+        return { type: 'hasMany', isArray: true };
+    }
+    return null;
+}
+// Helper to introspect model relationships
+function getModelRelationships(modelName) {
+    const { modelClass } = Orm.instance.getRecordClasses(modelName);
+    if (!modelClass)
+        return {};
+    const model = new modelClass(modelName);
+    const relationships = {};
+    for (const [key, property] of Object.entries(model)) {
+        if (key.startsWith('__'))
+            continue;
+        const info = getRelationshipInfo(property);
+        if (info) {
+            relationships[key] = info;
+        }
+    }
+    return relationships;
+}
+// Helper to build base URL from request
+function getBaseUrl(request) {
+    const protocol = request.protocol || 'http';
+    const host = request.get('host');
+    return `${protocol}://${host}`;
+}
+function getId(params) {
+    const id = params.id;
+    if (!id)
+        return '';
+    if (isNaN(id))
+        return id;
+    return parseInt(id);
+}
+function buildResponse(data, includeParam, recordOrRecords, options = {}) {
+    const { links, baseUrl } = options;
+    const response = { data };
+    // Add top-level links
+    if (links) {
+        response.links = links;
+    }
+    if (!includeParam)
+        return response;
+    const includes = parseInclude(includeParam);
+    if (includes.length === 0)
+        return response;
+    const includedRecords = collectIncludedRecords(recordOrRecords, includes);
+    if (includedRecords.length > 0) {
+        response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
+    }
+    return response;
+}
+/**
+ * Recursively traverse an include path and collect related records
+ */
+function traverseIncludePath(currentRecords, includePath, depth, seen, included) {
+    if (depth >= includePath.length)
+        return; // Reached end of path
+    const relationshipName = includePath[depth];
+    const nextRecords = [];
+    for (const record of currentRecords) {
+        if (!record.__relationships)
+            continue;
+        if (!(relationshipName in record.__relationships))
+            continue;
+        const relatedRecords = record.__relationships[relationshipName];
+        if (!relatedRecords)
+            continue;
+        // Handle both belongsTo (single) and hasMany (array)
+        const recordsToProcess = Array.isArray(relatedRecords)
+            ? relatedRecords.filter(isOrmRecord)
+            : isOrmRecord(relatedRecords) ? [relatedRecords] : [];
+        for (const relatedRecord of recordsToProcess) {
+            if (!relatedRecord)
+                continue;
+            if (!relatedRecord.__model)
+                continue;
+            const type = relatedRecord.__model.__name;
+            const id = relatedRecord.id;
+            // Initialize Set for this type if needed
+            let seenIds = seen.get(type);
+            if (!seenIds) {
+                seenIds = new Set();
+                seen.set(type, seenIds);
+            }
+            // Check if we've already seen this type+id combination
+            if (!seenIds.has(id)) {
+                seenIds.add(id);
+                included.push(relatedRecord);
+                nextRecords.push(relatedRecord); // Prepare for next depth level
+            }
+            else if (depth < includePath.length - 1) {
+                // Even if we've seen this record, we might need it for deeper traversal
+                nextRecords.push(relatedRecord);
+            }
+        }
+    }
+    // If there are more segments in the path, recursively process
+    if (depth < includePath.length - 1 && nextRecords.length > 0) {
+        traverseIncludePath(nextRecords, includePath, depth + 1, seen, included);
+    }
+}
+function collectIncludedRecords(data, includes) {
+    if (!includes || includes.length === 0)
+        return [];
+    if (!data)
+        return [];
+    const seen = new Map(); // Map<type, Set<id>> for deduplication
+    const included = [];
+    // Normalize to array for consistent processing
+    const records = Array.isArray(data) ? data : [data];
+    // Process each include path
+    for (const includePath of includes) {
+        traverseIncludePath(records, includePath, 0, seen, included);
+    }
+    return included;
+}
+function parseInclude(includeParam) {
+    if (!includeParam || typeof includeParam !== 'string')
+        return [];
+    return includeParam
+        .split(',')
+        .map(rel => rel.trim())
+        .filter(rel => rel.length > 0)
+        .map(rel => rel.split('.')); // Parse nested paths: "owner.pets" -> ["owner", "pets"]
+}
+function parseFields(query) {
+    const fields = new Map();
+    if (!query)
+        return fields;
+    for (const [key, value] of Object.entries(query)) {
+        const match = key.match(/^fields\[(\w+)\]$/);
+        if (match && typeof value === 'string') {
+            const modelName = match[1];
+            const fieldNames = value.split(',').map(f => f.trim()).filter(f => f);
+            fields.set(modelName, new Set(fieldNames));
+        }
+    }
+    return fields;
+}
+function parseFilters(query) {
+    const filters = [];
+    if (!query)
+        return filters;
+    for (const [key, value] of Object.entries(query)) {
+        const match = key.match(/^filter\[(.+)\]$/);
+        if (match && typeof value === 'string') {
+            filters.push({ path: match[1].split('.'), value });
+        }
+    }
+    return filters;
+}
+function createFilterPredicate(filters) {
+    if (filters.length === 0)
+        return null;
+    return (record) => filters.every(({ path, value }) => {
+        let current = record;
+        for (const segment of path) {
+            if (current == null)
+                return false;
+            current = current[segment];
+        }
+        return String(current) === value;
+    });
+}
+export default class OrmRequest extends Request {
+    model;
+    access;
+    handlers;
+    constructor({ model, access }) {
+        super(...arguments);
+        this.model = model;
+        this.access = access;
+        const pluralizedModel = getPluralName(model);
+        const modelRelationships = getModelRelationships(model);
+        // Define raw handlers first
+        const getCollectionHandler = async (request, { filter: accessFilter }) => {
+            const allRecords = (await store.findAll(model)).filter(isOrmRecord);
+            const queryFilters = parseFilters(request.query);
+            const queryFilterPredicate = createFilterPredicate(queryFilters);
+            const fieldsMap = parseFields(request.query);
+            const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+            let recordsToReturn = allRecords;
+            if (accessFilter)
+                recordsToReturn = recordsToReturn.filter(accessFilter);
+            if (queryFilterPredicate)
+                recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
+            const baseUrl = getBaseUrl(request);
+            const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
+            return buildResponse(data, request.query?.include, recordsToReturn, {
+                links: { self: `${baseUrl}/${pluralizedModel}` },
+                baseUrl
+            });
+        };
+        const getSingleHandler = async (request) => {
+            const record = await store.find(model, getId(request.params));
+            if (!record)
+                return 404;
+            const fieldsMap = parseFields(request.query);
+            const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+            const baseUrl = getBaseUrl(request);
+            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
+                links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
+                baseUrl
+            });
+        };
+        const createHandler = async ({ body, query }) => {
+            const { type, id, attributes, relationships: rels } = (body?.data || {});
+            if (!type)
+                return 400; // Bad request
+            const fieldsMap = parseFields(query);
+            const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
+            // Check for duplicate ID
+            if (id !== undefined && await store.find(model, id))
+                return 409; // Conflict
+            const { id: _ignoredId, ...sanitizedAttributes } = attributes || {};
+            // Extract relationship IDs from JSON:API relationships object
+            if (rels) {
+                for (const [key, value] of Object.entries(rels)) {
+                    const relData = value?.data;
+                    if (relData && relData.id !== undefined) {
+                        sanitizedAttributes[key] = relData.id;
+                    }
+                }
+            }
+            const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
+            const created = createRecord(model, recordAttributes, { serialize: false });
+            const record = isOrmRecord(created) ? created : null;
+            if (!record)
+                return 500;
+            return { data: record.toJSON?.({ fields: modelFields }) };
+        };
+        const updateHandler = async ({ body, params }) => {
+            const found = await store.find(model, getId(params));
+            if (!found || !isOrmRecord(found))
+                return 404;
+            const record = found;
+            const { attributes, relationships: rels } = (body?.data || {});
+            if (!attributes && !rels)
+                return 400; // Bad request
+            // Apply attribute updates 1 by 1 to utilize built-in transform logic, ignore id key
+            if (attributes) {
+                for (const [key, value] of Object.entries(attributes)) {
+                    if (!Object.hasOwn(record, key))
+                        continue;
+                    if (key === 'id')
+                        continue;
+                    record[key] = value;
+                }
+                ;
+            }
+            // Apply relationship updates via updateRecord to properly resolve references
+            if (rels) {
+                const relUpdates = {};
+                for (const [key, value] of Object.entries(rels)) {
+                    const relData = value?.data;
+                    if (relData && relData.id !== undefined) {
+                        relUpdates[key] = relData.id;
+                    }
+                }
+                if (Object.keys(relUpdates).length > 0) {
+                    updateRecord(record, relUpdates);
+                }
+            }
+            return { data: record.toJSON?.() };
+        };
+        const deleteHandler = ({ params }) => {
+            store.remove(model, getId(params));
+            return 204;
+        };
+        // Wrap handlers with hooks
+        const isView = Orm.instance?.isView?.(model);
+        this.handlers = {
+            get: {
+                '/': this._withHooks('list', getCollectionHandler),
+                '/:id': this._withHooks('get', getSingleHandler),
+                ...this._generateRelationshipRoutes(model, pluralizedModel, modelRelationships)
+            },
+        };
+        // Views are read-only -- no write endpoints
+        if (!isView) {
+            this.handlers.patch = {
+                '/:id': this._withHooks('update', updateHandler)
+            };
+            this.handlers.post = {
+                '/': this._withHooks('create', createHandler)
+            };
+            this.handlers.delete = {
+                '/:id': this._withHooks('delete', deleteHandler)
+            };
+        }
+    }
+    // Wraps a handler with before/after hook execution
+    _withHooks(operation, handler) {
+        return async (request, state) => {
+            // Build context object for hooks
+            const context = {
+                model: this.model,
+                operation,
+                request,
+                params: request.params,
+                body: request.body,
+                query: request.query,
+                state,
+            };
+            // Capture old state for operations that modify data
+            if (operation === 'update' || operation === 'delete') {
+                const existingRecord = await store.find(this.model, getId(request.params));
+                if (existingRecord) {
+                    // Deep copy the record's data to preserve old state
+                    context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
+                }
+                if (operation === 'delete') {
+                    context.recordId = getId(request.params);
+                }
+            }
+            // Run before hooks sequentially (can halt by returning a value)
+            for (const hook of getBeforeHooks(operation, this.model)) {
+                const result = await hook(context);
+                if (result !== undefined) {
+                    // Hook returned a value - halt operation and return result
+                    return result;
+                }
+            }
+            // Execute main handler
+            const response = await handler(request, state);
+            // Persist to SQL database for write operations
+            const sqlDb = Orm.instance.sqlDb;
+            if (sqlDb && WRITE_OPERATIONS.has(operation)) {
+                await sqlDb.persist(operation, this.model, context, response);
+            }
+            // Add response and relevant records to context
+            context.response = response;
+            if (operation === 'get' && response?.data && !Array.isArray(response.data)) {
+                context.record = await store.find(this.model, getId(request.params));
+            }
+            else if (operation === 'list' && response?.data) {
+                context.records = await store.findAll(this.model);
+            }
+            else if (operation === 'create' && response?.data && (response.data.id)) {
+                // For create, get the record from store using the ID from the response
+                const responseData = response.data;
+                const recordId = isNaN(responseData.id) ? responseData.id : parseInt(responseData.id);
+                context.record = store.get(this.model, recordId);
+            }
+            else if (operation === 'update' && response?.data) {
+                context.record = store.get(this.model, getId(request.params));
+            }
+            else if (operation === 'delete') {
+                // For delete, the record may no longer exist, but we have oldState
+                context.recordId = getId(request.params);
+            }
+            // Run after hooks sequentially
+            for (const hook of getAfterHooks(operation, this.model)) {
+                await hook(context);
+            }
+            // Auto-save DB after write operations when configured
+            if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation)) {
+                await Orm.db.save();
+            }
+            return response;
+        };
+    }
+    _generateRelationshipRoutes(model, pluralizedModel, modelRelationships) {
+        const routes = {};
+        for (const [relationshipName, info] of Object.entries(modelRelationships)) {
+            // Dasherize the relationship name for URL paths (e.g., accessLinks -> access-links)
+            const dasherizedName = camelCaseToKebabCase(relationshipName);
+            // Related resource route: GET /:id/{relationship}
+            routes[`/:id/${dasherizedName}`] = async (request) => {
+                const record = await store.find(model, getId(request.params));
+                if (!record)
+                    return 404;
+                const relatedData = record.__relationships[relationshipName];
+                const baseUrl = getBaseUrl(request);
+                let data;
+                if (info.isArray) {
+                    // hasMany - return array
+                    const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
+                    data = related.map(r => r.toJSON?.({ baseUrl }));
+                }
+                else {
+                    // belongsTo - return single or null
+                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
+                }
+                return {
+                    links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}` },
+                    data
+                };
+            };
+            // Relationship linkage route: GET /:id/relationships/{relationship}
+            routes[`/:id/relationships/${dasherizedName}`] = async (request) => {
+                const record = await store.find(model, getId(request.params));
+                if (!record)
+                    return 404;
+                const relatedData = record.__relationships[relationshipName];
+                const baseUrl = getBaseUrl(request);
+                let data;
+                if (info.isArray) {
+                    // hasMany - return array of linkage objects
+                    const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
+                    data = related
+                        .filter((r) => Boolean(r.__model))
+                        .map(r => ({ type: r.__model.__name, id: r.id }));
+                }
+                else {
+                    // belongsTo - return single linkage or null
+                    if (isOrmRecord(relatedData) && relatedData.__model) {
+                        data = { type: relatedData.__model.__name, id: relatedData.id };
+                    }
+                    else {
+                        data = null;
+                    }
+                }
+                return {
+                    links: {
+                        self: `${baseUrl}/${pluralizedModel}/${request.params.id}/relationships/${dasherizedName}`,
+                        related: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}`
+                    },
+                    data
+                };
+            };
+        }
+        // Catch-all for invalid relationship names on related resource route
+        routes[`/:id/:relationship`] = async (request) => {
+            const record = await store.find(model, getId(request.params));
+            if (!record)
+                return 404;
+            // If we reach here, relationship doesn't exist (valid ones were registered above)
+            return 404;
+        };
+        // Catch-all for invalid relationship names on relationship linkage route
+        routes[`/:id/relationships/:relationship`] = async (request) => {
+            const record = await store.find(model, getId(request.params));
+            if (!record)
+                return 404;
+            return 404;
+        };
+        return routes;
+    }
+    auth(request, state) {
+        const access = this.access(request);
+        if (!access)
+            return 403;
+        if (Array.isArray(access) && !access.includes(methodAccessMap[request.method]))
+            return 403;
+        if (typeof access === 'function')
+            state.filter = access;
+        return undefined;
+    }
+}

package/dist/plural-registry.d.ts

@@ -0,0 +1,4 @@
+export declare function registerPluralName(modelName: string, modelClass: {
+    pluralName?: string;
+}): void;
+export declare function getPluralName(modelName: string): string;

package/dist/plural-registry.js

@@ -0,0 +1,9 @@
+import { pluralize } from './utils.js';
+const registry = new Map();
+export function registerPluralName(modelName, modelClass) {
+    const plural = modelClass.pluralName || pluralize(modelName);
+    registry.set(modelName, plural);
+}
+export function getPluralName(modelName) {
+    return registry.get(modelName) || pluralize(modelName);
+}

package/dist/postgres/connection.d.ts

@@ -0,0 +1,15 @@
+import type { Pool as PgPool } from 'pg';
+interface PgConfig {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    connectionLimit: number;
+}
+/**
+ * Create or return the singleton pg Pool.
+ */
+export declare function getPool(pgConfig: PgConfig, extensions?: string[]): Promise<PgPool>;
+export declare function closePool(): Promise<void>;
+export {};

package/dist/postgres/connection.js

@@ -0,0 +1,32 @@
+import { validateIdentifier } from './query-builder.js';
+let pool = null;
+/**
+ * Create or return the singleton pg Pool.
+ */
+export async function getPool(pgConfig, extensions = ['vector']) {
+    if (pool)
+        return pool;
+    const { default: pg } = await import('pg');
+    pool = new pg.Pool({
+        host: pgConfig.host,
+        port: pgConfig.port,
+        user: pgConfig.user,
+        password: pgConfig.password,
+        database: pgConfig.database,
+        max: pgConfig.connectionLimit,
+        idleTimeoutMillis: 30000,
+        connectionTimeoutMillis: 10000,
+    });
+    // Enable requested PostgreSQL extensions
+    for (const ext of extensions) {
+        validateIdentifier(ext, 'extension name');
+        await pool.query(`CREATE EXTENSION IF NOT EXISTS "${ext}"`);
+    }
+    return pool;
+}
+export async function closePool() {
+    if (!pool)
+        return;
+    await pool.end();
+    pool = null;
+}

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

@@ -0,0 +1,45 @@
+import type { ForeignKeyDef, SnapshotEntry } from '../types/orm-types.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 DiffResult {
+    hasChanges: boolean;
+    addedModels: string[];
+    removedModels: string[];
+    addedColumns: ColumnChange[];
+    removedColumns: ColumnChange[];
+    changedColumns: ColumnTypeChange[];
+    addedForeignKeys: ForeignKeyChange[];
+    removedForeignKeys: ForeignKeyChange[];
+}
+interface ViewDiffResult {
+    hasChanges: boolean;
+    addedViews: string[];
+    removedViews: string[];
+    changedViews: string[];
+}
+interface MigrationResult {
+    filename: string;
+    content: string;
+    snapshot: Record<string, unknown>;
+}
+export declare function generateMigration(description?: string, configKey?: string): Promise<MigrationResult | null>;
+export declare function loadLatestSnapshot(migrationsPath: string): Promise<Record<string, unknown>>;
+export declare function diffSnapshots(previous: Record<string, SnapshotEntry>, current: Record<string, SnapshotEntry>): DiffResult;
+export declare function detectSchemaDrift(schemas: Record<string, unknown>, snapshot: Record<string, SnapshotEntry>): DiffResult;
+export declare function extractViewsFromSnapshot(snapshot: Record<string, SnapshotEntry>): Record<string, SnapshotEntry>;
+export declare function diffViewSnapshots(previous: Record<string, SnapshotEntry>, current: Record<string, SnapshotEntry>): ViewDiffResult;
+export {};