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

package/config/environment.js

@@ -26,6 +26,13 @@ const {
   PG_DATABASE,
   PG_CONNECTION_LIMIT,
   PG_MIGRATIONS_DIR,
+  TIMESCALE_HOST,
+  TIMESCALE_PORT,
+  TIMESCALE_USER,
+  TIMESCALE_PASSWORD,
+  TIMESCALE_DATABASE,
+  TIMESCALE_CONNECTION_LIMIT,
+  TIMESCALE_MIGRATIONS_DIR,
 } = process.env;
 
 export default {
@@ -67,6 +74,16 @@ export default {
     migrationsDir: PG_MIGRATIONS_DIR ?? 'migrations',
     migrationsTable: '__migrations',
   } : undefined,
+  timescale: TIMESCALE_HOST ? {
+    host: TIMESCALE_HOST ?? 'localhost',
+    port: parseInt(TIMESCALE_PORT ?? '5432'),
+    user: TIMESCALE_USER ?? 'postgres',
+    password: TIMESCALE_PASSWORD ?? '',
+    database: TIMESCALE_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(TIMESCALE_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+  } : undefined,
   restServer: {
     enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
     route: ORM_REST_ROUTE ?? '/',

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.82",
+  "version": "0.2.1-beta.83",
   "description": "",
   "main": "src/main.js",
   "type": "module",

package/src/main.js

@@ -109,7 +109,12 @@ export default class Orm {
 
     setup(eventNames);
 
-    if (config.orm.postgres) {
+    if (config.orm.timescale) {
+      const { default: TimescaleDB } = await import('./timescale/timescale-db.js');
+      this.sqlDb = new TimescaleDB();
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
+    } else if (config.orm.postgres) {
       const { default: PostgresDB } = await import('./postgres/postgres-db.js');
       this.sqlDb = new PostgresDB();
       this.db = this.sqlDb;

package/src/postgres/connection.js

@@ -1,6 +1,11 @@
 let pool = null;
 
-export async function getPool(pgConfig) {
+/**
+ * Create or return the singleton pg Pool.
+ * @param {Object} pgConfig - Connection config (host, port, user, password, database, connectionLimit)
+ * @param {string[]} [extensions=['vector']] - PostgreSQL extensions to enable on init
+ */
+export async function getPool(pgConfig, extensions = ['vector']) {
   if (pool) return pool;
 
   const { default: pg } = await import('pg');
@@ -16,8 +21,10 @@ export async function getPool(pgConfig) {
     connectionTimeoutMillis: 10000,
   });
 
-  // Enable pgvector extension
-  await pool.query('CREATE EXTENSION IF NOT EXISTS vector');
+  // Enable requested PostgreSQL extensions
+  for (const ext of extensions) {
+    await pool.query(`CREATE EXTENSION IF NOT EXISTS ${ext}`);
+  }
 
   return pool;
 }

package/src/postgres/migration-generator.js

@@ -4,8 +4,8 @@ import path from 'path';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 
-export async function generateMigration(description = 'migration') {
-  const { migrationsDir } = config.orm.postgres;
+export async function generateMigration(description = 'migration', configKey = 'postgres') {
+  const { migrationsDir } = config.orm[configKey];
   const rootPath = config.rootPath;
   const migrationsPath = path.resolve(rootPath, migrationsDir);
 

package/src/postgres/postgres-db.js

@@ -21,17 +21,24 @@ const defaultDeps = {
 };
 
 export default class PostgresDB {
+  /** @type {string[]} PostgreSQL extensions to enable on pool init. Subclasses can override. */
+  static extensions = ['vector'];
+
+  /** @type {string} Config key under config.orm for this adapter. Subclasses can override. */
+  static configKey = 'postgres';
+
   constructor(deps = {}) {
-    if (PostgresDB.instance) return PostgresDB.instance;
-    PostgresDB.instance = this;
+    const Ctor = this.constructor;
+    if (Ctor.instance) return Ctor.instance;
+    Ctor.instance = this;
 
     this.deps = { ...defaultDeps, ...deps };
     this.pool = null;
-    this.pgConfig = this.deps.config.orm.postgres;
+    this.pgConfig = this.deps.config.orm[Ctor.configKey];
   }
 
   async init() {
-    this.pool = await this.deps.getPool(this.pgConfig);
+    this.pool = await this.deps.getPool(this.pgConfig, this.constructor.extensions);
     await this.deps.ensureMigrationsTable(this.pool, this.pgConfig.migrationsTable);
     await this.loadMemoryRecords();
   }

package/src/timescale/query-builder.js

@@ -0,0 +1,142 @@
+// 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';
+
+/**
+ * Build a CREATE TABLE + hypertable conversion statement.
+ * TimescaleDB hypertables are regular tables converted via create_hypertable().
+ * @param {string} table - Table name
+ * @param {string} timeColumn - The time-partitioning column (must be a timestamp type)
+ * @param {Object} [options]
+ * @param {string} [options.chunkInterval='7 days'] - Chunk time interval
+ * @returns {{ sql: string, values: any[] }}
+ */
+export function buildCreateHypertable(table, timeColumn, options = {}) {
+  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.
+ * @param {string} table - Table name
+ * @param {string} timeColumn - Timestamp column to bucket
+ * @param {string} bucketSize - Bucket interval (e.g. '1 hour', '5 minutes', '1 day')
+ * @param {Object} [options]
+ * @param {string[]} [options.aggregates] - Aggregate expressions (e.g. ['AVG("value") AS avg_value'])
+ * @param {Object} [options.where] - WHERE conditions
+ * @param {string} [options.orderBy='bucket'] - ORDER BY clause
+ * @param {number} [options.limit] - LIMIT
+ * @returns {{ sql: string, values: any[] }}
+ */
+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(agg);
+  }
+
+  let 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 ')}` : '';
+  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.
+ * @param {string} viewName - Name for the continuous aggregate view
+ * @param {string} table - Source hypertable
+ * @param {string} timeColumn - Timestamp column
+ * @param {string} bucketSize - Bucket interval
+ * @param {string[]} aggregates - Aggregate expressions
+ * @param {Object} [options]
+ * @param {boolean} [options.withNoData=false] - Create without materializing data initially
+ * @returns {{ sql: string }}
+ */
+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;
+
+  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.
+ * @param {string} table - Hypertable name
+ * @param {string} compressAfter - Interval after which to compress (e.g. '7 days')
+ * @returns {{ sql: string }}
+ */
+export function buildCompressionPolicy(table, compressAfter) {
+  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.
+ * @param {string} table - Hypertable name
+ * @param {string} segmentBy - Column to segment by (usually the non-time dimension)
+ * @param {string} orderBy - Column to order compressed data by (usually the time column)
+ * @returns {{ sql: string }}
+ */
+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/src/timescale/timescale-db.js

@@ -0,0 +1,111 @@
+import PostgresDB from '../postgres/postgres-db.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,
+    });
+  }
+
+  /**
+   * Convert a table to a TimescaleDB hypertable.
+   * Should be called after the table is created (e.g. after initial migration).
+   * @param {string} modelName
+   * @param {string} timeColumn - The time-partitioning column
+   * @param {Object} [options]
+   * @param {string} [options.chunkInterval='7 days']
+   */
+  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.deps.buildCreateHypertable(schema.table, timeColumn, options);
+    await this.pool.query(sql);
+  }
+
+  /**
+   * Query time-bucketed aggregations on a hypertable.
+   * @param {string} modelName
+   * @param {string} timeColumn - Timestamp column to bucket
+   * @param {string} bucketSize - Bucket interval (e.g. '1 hour', '5 minutes')
+   * @param {Object} [options]
+   * @param {string[]} [options.aggregates] - Aggregate expressions
+   * @param {Object} [options.where] - WHERE conditions
+   * @param {number} [options.limit]
+   * @returns {Promise<Object[]>} Rows with bucket + aggregate columns
+   */
+  async timeBucket(modelName, timeColumn, bucketSize, options = {}) {
+    const schemas = this.deps.introspectModels();
+    const schema = schemas[modelName];
+    if (!schema) return [];
+
+    const { sql, values } = this.deps.buildTimeBucket(schema.table, timeColumn, bucketSize, options);
+
+    try {
+      const result = await this.pool.query(sql, values);
+      return result.rows;
+    } catch (error) {
+      if (error.code === '42P01') return [];
+      throw error;
+    }
+  }
+
+  /**
+   * Create a continuous aggregate view on a hypertable.
+   * @param {string} viewName - Name for the materialized view
+   * @param {string} modelName - Source hypertable model
+   * @param {string} timeColumn - Timestamp column
+   * @param {string} bucketSize - Bucket interval
+   * @param {string[]} aggregates - Aggregate expressions
+   * @param {Object} [options]
+   * @param {boolean} [options.withNoData=false]
+   */
+  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.deps.buildContinuousAggregate(viewName, schema.table, timeColumn, bucketSize, aggregates, options);
+    await this.pool.query(sql);
+  }
+
+  /**
+   * Enable compression on a hypertable.
+   * @param {string} modelName
+   * @param {Object} [options]
+   * @param {string} [options.segmentBy] - Column to segment by
+   * @param {string} [options.orderBy] - Column to order by
+   */
+  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.deps.buildEnableCompression(schema.table, options.segmentBy, options.orderBy);
+    await this.pool.query(sql);
+  }
+
+  /**
+   * Add a compression policy to a hypertable.
+   * @param {string} modelName
+   * @param {string} compressAfter - Interval after which to compress (e.g. '7 days')
+   */
+  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.deps.buildCompressionPolicy(schema.table, compressAfter);
+    await this.pool.query(sql);
+  }
+}