@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/dist/store.js

@@ -0,0 +1,286 @@
+import Orm, { relationships } from '@stonyx/orm';
+import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry } from './relationships.js';
+import ViewResolver from './view-resolver.js';
+function isStoreRecord(value) {
+    return typeof value === 'object' && value !== null && '__data' in value;
+}
+export default class Store {
+    static instance;
+    data = new Map();
+    /**
+     * Set by Orm during init — resolves memory flag for a model name.
+     */
+    _memoryResolver = null;
+    /**
+     * Set by Orm during init — reference to the SQL adapter instance for on-demand queries.
+     */
+    _sqlDb = null;
+    constructor() {
+        if (Store.instance)
+            return Store.instance;
+        Store.instance = this;
+        this.data = new Map();
+    }
+    get(key, id) {
+        if (!id)
+            return this.data.get(key);
+        return this.data.get(key)?.get(id);
+    }
+    /**
+     * Async authoritative read. Always queries the SQL database for memory: false models.
+     * For memory: true models, returns from store (already loaded on boot).
+     */
+    async find(modelName, id) {
+        // For views in non-SQL mode, use view resolver
+        if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
+            const resolver = new ViewResolver(modelName);
+            return resolver.resolveOne(id);
+        }
+        // For memory: true models, the store is authoritative
+        if (this._isMemoryModel(modelName)) {
+            return this.get(modelName, id);
+        }
+        // For memory: false models, always query the SQL database
+        if (this._sqlDb) {
+            return this._sqlDb.findRecord(modelName, id);
+        }
+        // Fallback to store (JSON mode or no SQL adapter)
+        return this.get(modelName, id);
+    }
+    /**
+     * Async read for all records of a model. Always queries MySQL for memory: false models.
+     * For memory: true models, returns from store.
+     */
+    async findAll(modelName, conditions) {
+        // For views in non-SQL mode, use view resolver
+        if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
+            const resolver = new ViewResolver(modelName);
+            const records = await resolver.resolveAll();
+            if (!conditions || Object.keys(conditions).length === 0)
+                return records;
+            return records.filter((record) => Object.entries(conditions).every(([key, value]) => isStoreRecord(record) && record.__data[key] === value));
+        }
+        // For memory: true models without conditions, return from store
+        if (this._isMemoryModel(modelName) && !conditions) {
+            const modelStore = this.get(modelName);
+            return modelStore ? Array.from(modelStore.values()) : [];
+        }
+        // For memory: false models (or filtered queries), always query the SQL database
+        if (this._sqlDb) {
+            return this._sqlDb.findAll(modelName, conditions);
+        }
+        // Fallback to store (JSON mode) — apply conditions in-memory if provided
+        const modelStore = this.get(modelName);
+        if (!modelStore)
+            return [];
+        const records = Array.from(modelStore.values());
+        if (!conditions || Object.keys(conditions).length === 0)
+            return records;
+        return records.filter((record) => Object.entries(conditions).every(([key, value]) => isStoreRecord(record) && record.__data[key] === value));
+    }
+    /**
+     * Async query — always hits MySQL, never reads from memory cache.
+     * Use for complex queries, aggregations, or when you need guaranteed freshness.
+     */
+    async query(modelName, conditions = {}) {
+        if (this._sqlDb) {
+            return this._sqlDb.findAll(modelName, conditions);
+        }
+        // Fallback: filter in-memory store
+        const modelStore = this.get(modelName);
+        if (!modelStore)
+            return [];
+        const records = Array.from(modelStore.values());
+        if (Object.keys(conditions).length === 0)
+            return records;
+        return records.filter((record) => Object.entries(conditions).every(([key, value]) => isStoreRecord(record) && record.__data[key] === value));
+    }
+    /**
+     * Check if a model is configured for in-memory storage.
+     * @private
+     */
+    _isMemoryModel(modelName) {
+        if (this._memoryResolver)
+            return this._memoryResolver(modelName);
+        return false; // default to non-memory if resolver not set yet
+    }
+    set(key, value) {
+        this.data.set(key, value);
+    }
+    remove(key, id) {
+        // Guard: read-only views cannot have records removed
+        if (Orm.instance?.isView?.(key)) {
+            throw new Error(`Cannot remove records from read-only view '${key}'`);
+        }
+        if (id)
+            return this.unloadRecord(key, id);
+        this.unloadAllRecords(key);
+    }
+    unloadRecord(model, id, options = {}) {
+        const modelStore = this.data.get(model);
+        if (!modelStore) {
+            console.warn(`[Store] Cannot unload record: model "${model}" not found in store — ensure the model is registered before unloading`);
+            return;
+        }
+        if (typeof id !== 'string' && typeof id !== 'number')
+            return;
+        const raw = modelStore.get(id);
+        if (!raw || !isStoreRecord(raw)) {
+            console.warn(`[Store] Cannot unload record: ${model}:${id} not found in store — it may have already been unloaded`);
+            return;
+        }
+        const record = raw;
+        const { toUnload, visited } = options.includeChildren
+            ? this._buildUnloadQueue(record, options)
+            : { toUnload: [{ record, modelName: model, recordId: id }], visited: new Set([`${model}:${id}`]) };
+        for (const item of toUnload.reverse()) {
+            const { record: recordToUnload, modelName, recordId } = item;
+            this._removeFromHasManyArrays(modelName, recordId, visited);
+            this._nullifyBelongsToReferences(modelName, recordId, visited);
+            this._cleanupRelationshipRegistries(modelName, recordId);
+            recordToUnload.clean();
+            this.data.get(modelName)?.delete(recordId);
+        }
+    }
+    unloadAllRecords(model, options = {}) {
+        const modelStore = this.data.get(model);
+        if (!modelStore) {
+            console.warn(`[Store] Cannot unload all records: model "${model}" not found in store — ensure the model is registered before unloading`);
+            return;
+        }
+        const recordIds = Array.from(modelStore.keys());
+        for (const id of recordIds) {
+            if (modelStore.has(id)) {
+                this.unloadRecord(model, id, options);
+            }
+        }
+        for (const relationshipType of TYPES) {
+            const reg = relationships.get(relationshipType);
+            if (reg instanceof Map)
+                reg.delete(model);
+        }
+    }
+    _removeFromHasManyArrays(modelName, recordId, visited) {
+        const hasManyRegistry = getHasManyRegistry();
+        for (const [sourceModel, targetModels] of hasManyRegistry) {
+            const targetModelMap = targetModels.get(modelName);
+            if (!targetModelMap)
+                continue;
+            for (const [sourceRecordId, hasManyArray] of targetModelMap) {
+                const sourceKey = `${sourceModel}:${sourceRecordId}`;
+                // Don't modify arrays of records being deleted
+                if (visited.has(sourceKey))
+                    continue;
+                const index = hasManyArray.findIndex(r => r && isStoreRecord(r) && r.id === recordId);
+                if (index !== -1)
+                    hasManyArray.splice(index, 1);
+            }
+        }
+    }
+    _nullifyBelongsToReferences(modelName, recordId, visited) {
+        const belongsToRegistry = getBelongsToRegistry();
+        for (const [sourceModel, targetModels] of belongsToRegistry) {
+            const targetModelMap = targetModels.get(modelName);
+            if (!targetModelMap)
+                continue;
+            for (const [sourceRecordId, belongsToRecord] of targetModelMap) {
+                if (belongsToRecord && isStoreRecord(belongsToRecord) && belongsToRecord.id === recordId) {
+                    const sourceKey = `${sourceModel}:${sourceRecordId}`;
+                    if (visited.has(sourceKey))
+                        continue;
+                    targetModelMap.set(sourceRecordId, null);
+                    if (typeof sourceRecordId !== 'string' && typeof sourceRecordId !== 'number')
+                        continue;
+                    const sourceRaw = this.get(sourceModel, sourceRecordId);
+                    if (!sourceRaw || !isStoreRecord(sourceRaw))
+                        continue;
+                    if (sourceRaw.__relationships) {
+                        for (const [key, value] of Object.entries(sourceRaw.__relationships)) {
+                            if (value && isStoreRecord(value) && value.id === recordId) {
+                                sourceRaw.__relationships[key] = null;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    _cleanupRelationshipRegistries(modelName, recordId) {
+        const hasManyMap = getHasManyRegistry().get(modelName);
+        if (hasManyMap) {
+            for (const [, recordMap] of hasManyMap)
+                recordMap.delete(recordId);
+        }
+        const belongsToMap = getBelongsToRegistry().get(modelName);
+        if (belongsToMap) {
+            for (const [, recordMap] of belongsToMap)
+                recordMap.delete(recordId);
+        }
+        const pendingMap = getPendingRegistry().get(modelName);
+        if (pendingMap)
+            pendingMap.delete(recordId);
+    }
+    /**
+     * Extracts hasMany and non-bidirectional belongsTo children from a record
+     * @private
+     */
+    _getChildren(record) {
+        const children = [];
+        if (!record.__relationships)
+            return children;
+        for (const [key, value] of Object.entries(record.__relationships)) {
+            // hasMany children - always include
+            if (Array.isArray(value)) {
+                for (const childRecord of value) {
+                    if (childRecord && isStoreRecord(childRecord))
+                        children.push({ childRecord, relationshipKey: key, type: 'hasMany' });
+                }
+            }
+            else if (value && isStoreRecord(value) && value.__model && !this._isBidirectionalRelationship(record.__model.__name, value.__model.__name)) {
+                children.push({ childRecord: value, relationshipKey: key, type: 'belongsTo' });
+            }
+        }
+        return children;
+    }
+    _isBidirectionalRelationship(sourceModel, targetModel) {
+        const inverseMap = getHasManyRegistry().get(targetModel)?.get(sourceModel);
+        return !!inverseMap && inverseMap.size > 0;
+    }
+    _buildUnloadQueue(record, options) {
+        const visited = new Set();
+        const toUnload = [];
+        const queue = [{
+                record,
+                modelName: record.__model.__name,
+                recordId: record.id,
+                isRoot: true,
+                depth: 0
+            }];
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (!item)
+                break;
+            const key = `${item.modelName}:${item.recordId}`;
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+            toUnload.push(item);
+            // Add children to queue if includeChildren is enabled
+            if (options.includeChildren) {
+                const children = this._getChildren(item.record);
+                for (const { childRecord } of children) {
+                    if (childRecord) {
+                        queue.push({
+                            record: childRecord,
+                            modelName: childRecord.__model.__name,
+                            recordId: childRecord.id,
+                            isRoot: false,
+                            depth: (item.depth ?? 0) + 1
+                        });
+                    }
+                }
+            }
+        }
+        return { toUnload, visited };
+    }
+}

package/dist/timescale/query-builder.d.ts

@@ -0,0 +1,43 @@
+export { validateIdentifier, buildInsert, buildUpdate, buildDelete, buildSelect } from '../postgres/query-builder.js';
+export declare function validateInterval(interval: string, context?: string): string;
+export declare function validateAggregate(expr: string, context?: string): string;
+interface QueryResult {
+    sql: string;
+    values: unknown[];
+}
+interface SqlResult {
+    sql: string;
+}
+interface HypertableOptions {
+    chunkInterval?: string;
+}
+interface TimeBucketOptions {
+    aggregates?: string[];
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    limit?: number;
+}
+interface ContinuousAggregateOptions {
+    withNoData?: boolean;
+}
+/**
+ * Build a CREATE TABLE + hypertable conversion statement.
+ * TimescaleDB hypertables are regular tables converted via create_hypertable().
+ */
+export declare function buildCreateHypertable(table: string, timeColumn: string, options?: HypertableOptions): QueryResult;
+/**
+ * Build a time_bucket aggregation query.
+ */
+export declare function buildTimeBucket(table: string, timeColumn: string, bucketSize: string, options?: TimeBucketOptions): QueryResult;
+/**
+ * Build a continuous aggregate creation statement.
+ */
+export declare function buildContinuousAggregate(viewName: string, table: string, timeColumn: string, bucketSize: string, aggregates: string[], options?: ContinuousAggregateOptions): SqlResult;
+/**
+ * Build an ADD compression policy statement.
+ */
+export declare function buildCompressionPolicy(table: string, compressAfter: string): SqlResult;
+/**
+ * Build an ALTER TABLE to enable compression on a hypertable.
+ */
+export declare function buildEnableCompression(table: string, segmentBy?: string, orderBy?: string): SqlResult;

package/dist/timescale/query-builder.js

@@ -0,0 +1,115 @@
+// Re-export all base PostgreSQL query builders
+export { validateIdentifier, buildInsert, buildUpdate, buildDelete, buildSelect } from '../postgres/query-builder.js';
+import { validateIdentifier } from '../postgres/query-builder.js';
+const SAFE_INTERVAL = /^\d+\s+(microsecond|millisecond|second|minute|hour|day|week|month|year)s?$/i;
+export function validateInterval(interval, context = 'interval') {
+    if (!interval || typeof interval !== 'string' || !SAFE_INTERVAL.test(interval.trim())) {
+        throw new Error(`Invalid SQL ${context}: "${interval}". Intervals must match pattern like "7 days", "1 hour", "30 minutes".`);
+    }
+    return interval.trim();
+}
+const SAFE_AGGREGATE = /^(COUNT|SUM|AVG|MIN|MAX|FIRST|LAST)\s*\(\s*("?[a-zA-Z_][a-zA-Z0-9_]*"?|\*)\s*\)\s*(AS\s+"?[a-zA-Z_][a-zA-Z0-9_]*"?)?$/i;
+export function validateAggregate(expr, context = 'aggregate') {
+    if (!expr || typeof expr !== 'string' || !SAFE_AGGREGATE.test(expr.trim())) {
+        throw new Error(`Invalid SQL ${context}: "${expr}". Aggregates must be simple function calls like "AVG(value) AS avg_value".`);
+    }
+    return expr.trim();
+}
+/**
+ * Build a CREATE TABLE + hypertable conversion statement.
+ * TimescaleDB hypertables are regular tables converted via create_hypertable().
+ */
+export function buildCreateHypertable(table, timeColumn, options = {}) {
+    validateIdentifier(table, 'table name');
+    validateIdentifier(timeColumn, 'column name');
+    const { chunkInterval = '7 days' } = options;
+    validateInterval(chunkInterval, 'chunk interval');
+    const sql = `SELECT create_hypertable('"${table}"', '${timeColumn}', chunk_time_interval => INTERVAL '${chunkInterval}', if_not_exists => TRUE)`;
+    return { sql, values: [] };
+}
+/**
+ * Build a time_bucket aggregation query.
+ */
+export function buildTimeBucket(table, timeColumn, bucketSize, options = {}) {
+    validateIdentifier(table, 'table name');
+    validateIdentifier(timeColumn, 'column name');
+    const { aggregates = [], where, orderBy = 'bucket', limit } = options;
+    const values = [];
+    let paramIndex = 1;
+    const selectCols = [`time_bucket($${paramIndex++}, "${timeColumn}") AS bucket`];
+    values.push(bucketSize);
+    for (const agg of aggregates) {
+        selectCols.push(validateAggregate(agg));
+    }
+    const whereClauses = [];
+    if (where) {
+        for (const [k, v] of Object.entries(where)) {
+            validateIdentifier(k, 'column name');
+            whereClauses.push(`"${k}" = $${paramIndex++}`);
+            values.push(v);
+        }
+    }
+    const whereStr = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
+    let orderStr = '';
+    if (orderBy) {
+        const parts = orderBy.trim().split(/\s+/);
+        const col = parts[0];
+        const dir = parts[1]?.toUpperCase();
+        validateIdentifier(col, 'ORDER BY column');
+        if (dir && dir !== 'ASC' && dir !== 'DESC') {
+            throw new Error(`Invalid ORDER BY direction: "${dir}". Must be ASC or DESC.`);
+        }
+        orderStr = ` ORDER BY "${col}"${dir ? ` ${dir}` : ''}`;
+    }
+    let limitStr = '';
+    if (limit != null) {
+        limitStr = ` LIMIT $${paramIndex++}`;
+        values.push(limit);
+    }
+    const sql = `SELECT ${selectCols.join(', ')} FROM "${table}"${whereStr} GROUP BY bucket${orderStr}${limitStr}`;
+    return { sql, values };
+}
+/**
+ * Build a continuous aggregate creation statement.
+ */
+export function buildContinuousAggregate(viewName, table, timeColumn, bucketSize, aggregates, options = {}) {
+    validateIdentifier(viewName, 'view name');
+    validateIdentifier(table, 'table name');
+    validateIdentifier(timeColumn, 'column name');
+    const { withNoData = false } = options;
+    validateInterval(bucketSize, 'bucket size');
+    aggregates.forEach(agg => validateAggregate(agg));
+    const selectCols = [
+        `time_bucket('${bucketSize}', "${timeColumn}") AS bucket`,
+        ...aggregates,
+    ];
+    const withClause = withNoData ? ' WITH NO DATA' : '';
+    const sql = `CREATE MATERIALIZED VIEW "${viewName}" WITH (timescaledb.continuous) AS SELECT ${selectCols.join(', ')} FROM "${table}" GROUP BY bucket${withClause}`;
+    return { sql };
+}
+/**
+ * Build an ADD compression policy statement.
+ */
+export function buildCompressionPolicy(table, compressAfter) {
+    validateIdentifier(table, 'table name');
+    validateInterval(compressAfter, 'compress after interval');
+    const sql = `SELECT add_compression_policy('"${table}"', INTERVAL '${compressAfter}', if_not_exists => TRUE)`;
+    return { sql };
+}
+/**
+ * Build an ALTER TABLE to enable compression on a hypertable.
+ */
+export function buildEnableCompression(table, segmentBy, orderBy) {
+    validateIdentifier(table, 'table name');
+    let opts = `timescaledb.compress`;
+    if (segmentBy) {
+        validateIdentifier(segmentBy, 'column name');
+        opts += `, timescaledb.compress_segmentby = '"${segmentBy}"'`;
+    }
+    if (orderBy) {
+        validateIdentifier(orderBy, 'column name');
+        opts += `, timescaledb.compress_orderby = '"${orderBy}"'`;
+    }
+    const sql = `ALTER TABLE "${table}" SET (${opts})`;
+    return { sql };
+}

package/dist/timescale/timescale-db.d.ts

@@ -0,0 +1,45 @@
+import PostgresDB from '../postgres/postgres-db.js';
+interface HypertableOptions {
+    chunkInterval?: string;
+}
+interface TimeBucketOptions {
+    aggregates?: string[];
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    limit?: number;
+}
+interface ContinuousAggregateOptions {
+    withNoData?: boolean;
+}
+interface CompressionOptions {
+    segmentBy?: string;
+    orderBy?: string;
+}
+export default class TimescaleDB extends PostgresDB {
+    static extensions: string[];
+    static configKey: string;
+    constructor(deps?: Record<string, unknown>);
+    private get tsDeps();
+    /**
+     * Convert a table to a TimescaleDB hypertable.
+     * Should be called after the table is created (e.g. after initial migration).
+     */
+    createHypertable(modelName: string, timeColumn: string, options?: HypertableOptions): Promise<void>;
+    /**
+     * Query time-bucketed aggregations on a hypertable.
+     */
+    timeBucket(modelName: string, timeColumn: string, bucketSize: string, options?: TimeBucketOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Create a continuous aggregate view on a hypertable.
+     */
+    createContinuousAggregate(viewName: string, modelName: string, timeColumn: string, bucketSize: string, aggregates: string[], options?: ContinuousAggregateOptions): Promise<void>;
+    /**
+     * Enable compression on a hypertable.
+     */
+    enableCompression(modelName: string, options?: CompressionOptions): Promise<void>;
+    /**
+     * Add a compression policy to a hypertable.
+     */
+    addCompressionPolicy(modelName: string, compressAfter: string): Promise<void>;
+}
+export {};

package/dist/timescale/timescale-db.js

@@ -0,0 +1,84 @@
+import PostgresDB from '../postgres/postgres-db.js';
+import { isDbError } from '../utils.js';
+import { buildCreateHypertable, buildTimeBucket, buildContinuousAggregate, buildCompressionPolicy, buildEnableCompression } from './query-builder.js';
+export default class TimescaleDB extends PostgresDB {
+    static extensions = ['timescaledb'];
+    static configKey = 'timescale';
+    constructor(deps = {}) {
+        super({
+            ...deps,
+            buildCreateHypertable,
+            buildTimeBucket,
+            buildContinuousAggregate,
+            buildCompressionPolicy,
+            buildEnableCompression,
+        });
+    }
+    get tsDeps() {
+        return this.deps;
+    }
+    /**
+     * Convert a table to a TimescaleDB hypertable.
+     * Should be called after the table is created (e.g. after initial migration).
+     */
+    async createHypertable(modelName, timeColumn, options = {}) {
+        const schemas = this.deps.introspectModels();
+        const schema = schemas[modelName];
+        if (!schema)
+            throw new Error(`Model '${modelName}' not found`);
+        const { sql } = this.tsDeps.buildCreateHypertable(schema.table, timeColumn, options);
+        await this.requirePool().query(sql);
+    }
+    /**
+     * Query time-bucketed aggregations on a hypertable.
+     */
+    async timeBucket(modelName, timeColumn, bucketSize, options = {}) {
+        const schemas = this.deps.introspectModels();
+        const schema = schemas[modelName];
+        if (!schema)
+            return [];
+        const { sql, values } = this.tsDeps.buildTimeBucket(schema.table, timeColumn, bucketSize, options);
+        try {
+            const result = await this.requirePool().query(sql, values);
+            return result.rows;
+        }
+        catch (error) {
+            if (isDbError(error) && error.code === '42P01')
+                return [];
+            throw error;
+        }
+    }
+    /**
+     * Create a continuous aggregate view on a hypertable.
+     */
+    async createContinuousAggregate(viewName, modelName, timeColumn, bucketSize, aggregates, options = {}) {
+        const schemas = this.deps.introspectModels();
+        const schema = schemas[modelName];
+        if (!schema)
+            throw new Error(`Model '${modelName}' not found`);
+        const { sql } = this.tsDeps.buildContinuousAggregate(viewName, schema.table, timeColumn, bucketSize, aggregates, options);
+        await this.requirePool().query(sql);
+    }
+    /**
+     * Enable compression on a hypertable.
+     */
+    async enableCompression(modelName, options = {}) {
+        const schemas = this.deps.introspectModels();
+        const schema = schemas[modelName];
+        if (!schema)
+            throw new Error(`Model '${modelName}' not found`);
+        const { sql } = this.tsDeps.buildEnableCompression(schema.table, options.segmentBy, options.orderBy);
+        await this.requirePool().query(sql);
+    }
+    /**
+     * Add a compression policy to a hypertable.
+     */
+    async addCompressionPolicy(modelName, compressAfter) {
+        const schemas = this.deps.introspectModels();
+        const schema = schemas[modelName];
+        if (!schema)
+            throw new Error(`Model '${modelName}' not found`);
+        const { sql } = this.tsDeps.buildCompressionPolicy(schema.table, compressAfter);
+        await this.requirePool().query(sql);
+    }
+}

package/dist/transforms.d.ts

@@ -0,0 +1,2 @@
+declare const transforms: Record<string, (value: unknown) => unknown>;
+export default transforms;

package/dist/transforms.js

@@ -0,0 +1,17 @@
+import { getTimestamp } from "@stonyx/utils/date";
+const transforms = {
+    boolean: (value) => typeof value === 'string' ? value.trim().toLowerCase() === 'true' : !!value,
+    date: (value) => value ? new Date(value) : null,
+    float: (value) => parseFloat(value),
+    number: (value) => parseInt(value),
+    passthrough: (value) => value,
+    string: (value) => String(value),
+    timestamp: (value) => getTimestamp(value),
+    trim: (value) => value?.trim(),
+    uppercase: (value) => value?.toUpperCase(),
+};
+// Math Proxies
+['ceil', 'floor', 'round'].forEach(method => {
+    transforms[method] = (value) => Math[method](value);
+});
+export default transforms;