@stonyx/orm 0.2.1-beta.82 → 0.2.1-beta.84

package/src/{store.js → store.ts}

@@ -1,8 +1,50 @@
 import Orm, { relationships } from '@stonyx/orm';
-import { TYPES } from './relationships.js';
+import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry } from './relationships.js';
 import ViewResolver from './view-resolver.js';
 
+interface UnloadOptions {
+  includeChildren?: boolean;
+  [key: string]: unknown;
+}
+
+interface UnloadQueueItem {
+  record: StoreRecord;
+  modelName: string;
+  recordId: unknown;
+  isRoot?: boolean;
+  depth?: number;
+}
+
+interface ChildInfo {
+  childRecord: StoreRecord;
+  relationshipKey: string;
+  type: string;
+}
+
+interface StoreRecord {
+  __model: { __name: string; [key: string]: unknown };
+  __data: Record<string, unknown>;
+  __relationships: Record<string, unknown>;
+  id: unknown;
+  clean(): void;
+  [key: string]: unknown;
+}
+
 export default class Store {
+  static instance: Store | undefined;
+
+  data: Map<string, Map<number | string, unknown>> = new Map();
+
+  /**
+   * Set by Orm during init — resolves memory flag for a model name.
+   */
+  _memoryResolver: ((modelName: string) => boolean) | null = 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 = null;
+
   constructor() {
     if (Store.instance) return Store.instance;
     Store.instance = this;
@@ -15,7 +57,9 @@ export default class Store {
    * 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, id) {
+  get(key: string): Map<number | string, unknown> | undefined;
+  get(key: string, id: number | string): unknown;
+  get(key: string, id?: number | string): Map<number | string, unknown> | unknown | undefined {
     if (!id) return this.data.get(key);
 
     return this.data.get(key)?.get(id);
@@ -24,11 +68,8 @@ export default class Store {
   /**
    * Async authoritative read. Always queries the SQL database for memory: false models.
    * For memory: true models, returns from store (already loaded on boot).
-   * @param {string} modelName - The model name
-   * @param {string|number} id - The record ID
-   * @returns {Promise<Record|undefined>}
    */
-  async find(modelName, id) {
+  async find(modelName: string, id: number | string): Promise<unknown> {
     // For views in non-SQL mode, use view resolver
     if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
       const resolver = new ViewResolver(modelName);
@@ -52,11 +93,8 @@ export default class Store {
   /**
    * Async read for all records of a model. Always queries MySQL for memory: false models.
    * For memory: true models, returns from store.
-   * @param {string} modelName - The model name
-   * @param {Object} [conditions] - Optional WHERE conditions
-   * @returns {Promise<Record[]>}
    */
-  async findAll(modelName, conditions) {
+  async findAll(modelName: string, conditions?: Record<string, unknown>): Promise<unknown[]> {
     // For views in non-SQL mode, use view resolver
     if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
       const resolver = new ViewResolver(modelName);
@@ -64,8 +102,8 @@ export default class Store {
 
       if (!conditions || Object.keys(conditions).length === 0) return records;
 
-      return records.filter(record =>
-        Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+      return records.filter((record: unknown) =>
+        Object.entries(conditions).every(([key, value]) => (record as StoreRecord).__data[key] === value)
       );
     }
 
@@ -88,19 +126,16 @@ export default class Store {
 
     if (!conditions || Object.keys(conditions).length === 0) return records;
 
-    return records.filter(record =>
-      Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+    return records.filter((record: unknown) =>
+      Object.entries(conditions).every(([key, value]) => (record as StoreRecord).__data[key] === value)
     );
   }
 
   /**
    * Async query — always hits MySQL, never reads from memory cache.
    * Use for complex queries, aggregations, or when you need guaranteed freshness.
-   * @param {string} modelName - The model name
-   * @param {Object} conditions - WHERE conditions
-   * @returns {Promise<Record[]>}
    */
-  async query(modelName, conditions = {}) {
+  async query(modelName: string, conditions: Record<string, unknown> = {}): Promise<unknown[]> {
     if (this._sqlDb) {
       return this._sqlDb.findAll(modelName, conditions);
     }
@@ -113,37 +148,25 @@ export default class Store {
 
     if (Object.keys(conditions).length === 0) return records;
 
-    return records.filter(record =>
-      Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+    return records.filter((record: unknown) =>
+      Object.entries(conditions).every(([key, value]) => (record as StoreRecord).__data[key] === value)
     );
   }
 
-  /**
-   * Set by Orm during init — resolves memory flag for a model name.
-   * @type {Function|null}
-   */
-  _memoryResolver = null;
-
-  /**
-   * Set by Orm during init — reference to the SQL adapter instance for on-demand queries.
-   * @type {object|null}
-   */
-  _sqlDb = null;
-
   /**
    * Check if a model is configured for in-memory storage.
    * @private
    */
-  _isMemoryModel(modelName) {
+  private _isMemoryModel(modelName: string): boolean {
     if (this._memoryResolver) return this._memoryResolver(modelName);
     return false; // default to non-memory if resolver not set yet
   }
 
-  set(key, value) {
+  set(key: string, value: Map<number | string, unknown>): void {
     this.data.set(key, value);
   }
 
-  remove(key, id) {
+  remove(key: string, id?: number | string): void {
     // Guard: read-only views cannot have records removed
     if (Orm.instance?.isView?.(key)) {
       throw new Error(`Cannot remove records from read-only view '${key}'`);
@@ -154,7 +177,7 @@ export default class Store {
     this.unloadAllRecords(key);
   }
 
-  unloadRecord(model, id, options={}) {
+  unloadRecord(model: string, id: unknown, options: UnloadOptions = {}): void {
     const modelStore = this.data.get(model);
 
     if (!modelStore) {
@@ -162,7 +185,7 @@ export default class Store {
       return;
     }
 
-    const record = modelStore.get(id);
+    const record = modelStore.get(id as string | number) as StoreRecord | undefined;
 
     if (!record) {
       console.warn(`[Store] Cannot unload record: ${model}:${id} not found in store`);
@@ -171,7 +194,7 @@ export default class Store {
 
     const { toUnload, visited } = options.includeChildren
       ? this._buildUnloadQueue(record, options)
-      : { toUnload: [{ record, modelName: model, recordId: id }], visited: new Set([`${model}:${id}`]) };
+      : { toUnload: [{ record, modelName: model, recordId: id }] as UnloadQueueItem[], visited: new Set([`${model}:${id}`]) };
 
     for (const item of toUnload.reverse()) {
       const { record: recordToUnload, modelName, recordId } = item;
@@ -181,11 +204,11 @@ export default class Store {
       this._cleanupRelationshipRegistries(modelName, recordId);
       recordToUnload.clean();
 
-      this.data.get(modelName).delete(recordId);
+      this.data.get(modelName)!.delete(recordId as string | number);
     }
   }
 
-  unloadAllRecords(model, options={}) {
+  unloadAllRecords(model: string, options: UnloadOptions = {}): void {
     const modelStore = this.data.get(model);
 
     if (!modelStore) {
@@ -201,11 +224,11 @@ export default class Store {
       }
     }
 
-    for (const relationshipType of TYPES) relationships.get(relationshipType).delete(model);
+    for (const relationshipType of TYPES) (relationships.get(relationshipType) as Map<string, unknown>).delete(model);
   }
 
-  _removeFromHasManyArrays(modelName, recordId, visited) {
-    const hasManyRegistry = relationships.get('hasMany');
+  private _removeFromHasManyArrays(modelName: string, recordId: unknown, visited: Set<string>): void {
+    const hasManyRegistry = getHasManyRegistry();
 
     for (const [sourceModel, targetModels] of hasManyRegistry) {
       const targetModelMap = targetModels.get(modelName);
@@ -217,30 +240,30 @@ export default class Store {
         // Don't modify arrays of records being deleted
         if (visited.has(sourceKey)) continue;
 
-        const index = hasManyArray.findIndex(r => r && r.id === recordId);
+        const index = hasManyArray.findIndex(r => r && (r as StoreRecord).id === recordId);
         if (index !== -1) hasManyArray.splice(index, 1);
       }
     }
   }
 
-  _nullifyBelongsToReferences(modelName, recordId, visited) {
-    const belongsToRegistry = relationships.get('belongsTo');
+  private _nullifyBelongsToReferences(modelName: string, recordId: unknown, visited: Set<string>): void {
+    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 && belongsToRecord.id === recordId) {
+        if (belongsToRecord && (belongsToRecord as StoreRecord).id === recordId) {
           const sourceKey = `${sourceModel}:${sourceRecordId}`;
 
           if (visited.has(sourceKey)) continue;
           targetModelMap.set(sourceRecordId, null);
 
-          const sourceRecord = this.get(sourceModel, sourceRecordId);
+          const sourceRecord = this.get(sourceModel, sourceRecordId as string | number) as StoreRecord | undefined;
           if (sourceRecord && sourceRecord.__relationships) {
             for (const [key, value] of Object.entries(sourceRecord.__relationships)) {
-              if (value && value.id === recordId) {
+              if (value && (value as StoreRecord).id === recordId) {
                 sourceRecord.__relationships[key] = null;
               }
             }
@@ -250,18 +273,18 @@ export default class Store {
     }
   }
 
-  _cleanupRelationshipRegistries(modelName, recordId) {
-    const hasManyMap = relationships.get('hasMany').get(modelName);
+  private _cleanupRelationshipRegistries(modelName: string, recordId: unknown): void {
+    const hasManyMap = getHasManyRegistry().get(modelName);
     if (hasManyMap) {
       for (const [, recordMap] of hasManyMap) recordMap.delete(recordId);
     }
 
-    const belongsToMap = relationships.get('belongsTo').get(modelName);
+    const belongsToMap = getBelongsToRegistry().get(modelName);
     if (belongsToMap) {
       for (const [, recordMap] of belongsToMap) recordMap.delete(recordId);
     }
 
-    const pendingMap = relationships.get('pending').get(modelName);
+    const pendingMap = getPendingRegistry().get(modelName);
     if (pendingMap) pendingMap.delete(recordId);
   }
 
@@ -269,8 +292,8 @@ export default class Store {
    * Extracts hasMany and non-bidirectional belongsTo children from a record
    * @private
    */
-  _getChildren(record) {
-    const children = [];
+  private _getChildren(record: StoreRecord): ChildInfo[] {
+    const children: ChildInfo[] = [];
 
     if (!record.__relationships) return children;
 
@@ -278,30 +301,29 @@ export default class Store {
       // hasMany children - always include
       if (Array.isArray(value)) {
         for (const childRecord of value) {
-          if (childRecord) children.push({ childRecord, relationshipKey: key, type: 'hasMany' });
+          if (childRecord) children.push({ childRecord: childRecord as StoreRecord, relationshipKey: key, type: 'hasMany' });
         }
       } else if (value && !this._isBidirectionalRelationship(
         record.__model.__name,
-        value.__model.__name
+        (value as StoreRecord).__model.__name
       )) {
-        children.push({ childRecord: value, relationshipKey: key, type: 'belongsTo' });
+        children.push({ childRecord: value as StoreRecord, relationshipKey: key, type: 'belongsTo' });
       }
     }
 
     return children;
   }
 
-  _isBidirectionalRelationship(sourceModel, targetModel) {
-    const hasManyRegistry = relationships.get('hasMany');
-    const inverseMap = hasManyRegistry.get(targetModel)?.get(sourceModel);
+  private _isBidirectionalRelationship(sourceModel: string, targetModel: string): boolean {
+    const inverseMap = getHasManyRegistry().get(targetModel)?.get(sourceModel);
 
-    return inverseMap && inverseMap.size > 0;
+    return !!inverseMap && inverseMap.size > 0;
   }
 
-  _buildUnloadQueue(record, options) {
-    const visited = new Set();
-    const toUnload = [];
-    const queue = [{
+  private _buildUnloadQueue(record: StoreRecord, options: UnloadOptions): { toUnload: UnloadQueueItem[]; visited: Set<string> } {
+    const visited = new Set<string>();
+    const toUnload: UnloadQueueItem[] = [];
+    const queue: UnloadQueueItem[] = [{
       record,
       modelName: record.__model.__name,
       recordId: record.id,
@@ -310,7 +332,7 @@ export default class Store {
     }];
 
     while (queue.length > 0) {
-      const item = queue.shift();
+      const item = queue.shift()!;
       const key = `${item.modelName}:${item.recordId}`;
 
       if (visited.has(key)) continue;
@@ -328,7 +350,7 @@ export default class Store {
               modelName: childRecord.__model.__name,
               recordId: childRecord.id,
               isRoot: false,
-              depth: item.depth + 1
+              depth: (item.depth ?? 0) + 1
             });
           }
         }

package/src/timescale/query-builder.ts

@@ -0,0 +1,137 @@
+// 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';
+
+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 function buildCreateHypertable(table: string, timeColumn: string, options: HypertableOptions = {}): QueryResult {
+  validateIdentifier(table, 'table name');
+  validateIdentifier(timeColumn, 'column name');
+
+  const { chunkInterval = '7 days' } = options;
+
+  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: string, timeColumn: string, bucketSize: string, options: TimeBucketOptions = {}): QueryResult {
+  validateIdentifier(table, 'table name');
+  validateIdentifier(timeColumn, 'column name');
+
+  const { aggregates = [], where, orderBy = 'bucket', limit } = options;
+  const values: unknown[] = [];
+  let paramIndex = 1;
+
+  const selectCols: string[] = [`time_bucket($${paramIndex++}, "${timeColumn}") AS bucket`];
+  values.push(bucketSize);
+
+  for (const agg of aggregates) {
+    selectCols.push(agg);
+  }
+
+  const whereClauses: string[] = [];
+  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 ')}` : '';
+  const orderStr = orderBy ? ` ORDER BY ${orderBy}` : '';
+  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: string, table: string, timeColumn: string, bucketSize: string, aggregates: string[], options: ContinuousAggregateOptions = {}): SqlResult {
+  validateIdentifier(viewName, 'view name');
+  validateIdentifier(table, 'table name');
+  validateIdentifier(timeColumn, 'column name');
+
+  const { withNoData = false } = options;
+
+  const selectCols: string[] = [
+    `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: string, compressAfter: string): SqlResult {
+  validateIdentifier(table, 'table name');
+
+  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: string, segmentBy?: string, orderBy?: string): SqlResult {
+  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/src/timescale/timescale-db.ts

@@ -0,0 +1,107 @@
+import PostgresDB from '../postgres/postgres-db.js';
+import { isDbError } from '../utils.js';
+import { buildCreateHypertable, buildTimeBucket, buildContinuousAggregate, buildCompressionPolicy, buildEnableCompression } from './query-builder.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 override extensions: string[] = ['timescaledb'];
+  static override configKey: string = 'timescale';
+
+  constructor(deps: Record<string, unknown> = {}) {
+    super({
+      ...deps,
+      buildCreateHypertable,
+      buildTimeBucket,
+      buildContinuousAggregate,
+      buildCompressionPolicy,
+      buildEnableCompression,
+    });
+  }
+
+  /**
+   * Convert a table to a TimescaleDB hypertable.
+   * Should be called after the table is created (e.g. after initial migration).
+   */
+  async createHypertable(modelName: string, timeColumn: string, options: HypertableOptions = {}): Promise<void> {
+    const schemas = this.deps.introspectModels();
+    const schema = schemas[modelName];
+    if (!schema) throw new Error(`Model '${modelName}' not found`);
+
+    const { sql } = (this.deps as unknown as { buildCreateHypertable: typeof buildCreateHypertable }).buildCreateHypertable(schema.table, timeColumn, options);
+    await this.requirePool().query(sql);
+  }
+
+  /**
+   * Query time-bucketed aggregations on a hypertable.
+   */
+  async timeBucket(modelName: string, timeColumn: string, bucketSize: string, options: TimeBucketOptions = {}): Promise<Record<string, unknown>[]> {
+    const schemas = this.deps.introspectModels();
+    const schema = schemas[modelName];
+    if (!schema) return [];
+
+    const { sql, values } = (this.deps as unknown as { buildTimeBucket: typeof buildTimeBucket }).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: string, modelName: string, timeColumn: string, bucketSize: string, aggregates: string[], options: ContinuousAggregateOptions = {}): Promise<void> {
+    const schemas = this.deps.introspectModels();
+    const schema = schemas[modelName];
+    if (!schema) throw new Error(`Model '${modelName}' not found`);
+
+    const { sql } = (this.deps as unknown as { buildContinuousAggregate: typeof buildContinuousAggregate }).buildContinuousAggregate(viewName, schema.table, timeColumn, bucketSize, aggregates, options);
+    await this.requirePool().query(sql);
+  }
+
+  /**
+   * Enable compression on a hypertable.
+   */
+  async enableCompression(modelName: string, options: CompressionOptions = {}): Promise<void> {
+    const schemas = this.deps.introspectModels();
+    const schema = schemas[modelName];
+    if (!schema) throw new Error(`Model '${modelName}' not found`);
+
+    const { sql } = (this.deps as unknown as { buildEnableCompression: typeof buildEnableCompression }).buildEnableCompression(schema.table, options.segmentBy, options.orderBy);
+    await this.requirePool().query(sql);
+  }
+
+  /**
+   * Add a compression policy to a hypertable.
+   */
+  async addCompressionPolicy(modelName: string, compressAfter: string): Promise<void> {
+    const schemas = this.deps.introspectModels();
+    const schema = schemas[modelName];
+    if (!schema) throw new Error(`Model '${modelName}' not found`);
+
+    const { sql } = (this.deps as unknown as { buildCompressionPolicy: typeof buildCompressionPolicy }).buildCompressionPolicy(schema.table, compressAfter);
+    await this.requirePool().query(sql);
+  }
+}

package/src/transforms.ts

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

package/src/types/mysql2.d.ts

@@ -0,0 +1,30 @@
+declare module 'mysql2/promise' {
+  interface PoolOptions {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    port?: number;
+    [key: string]: unknown;
+  }
+
+  interface QueryResult {
+    [index: number]: unknown;
+  }
+
+  interface Pool {
+    execute(sql: string, params?: unknown[]): Promise<[unknown[], unknown]>;
+    query(sql: string, params?: unknown[]): Promise<[unknown[], unknown]>;
+    end(): Promise<void>;
+    getConnection(): Promise<PoolConnection>;
+  }
+
+  interface PoolConnection extends Pool {
+    release(): void;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+  }
+
+  export function createPool(options: PoolOptions): Pool;
+}