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

package/src/postgres/schema-introspector.js

@@ -0,0 +1,354 @@
+import Orm from '@stonyx/orm';
+import { getPgType, getVectorType } from './type-map.js';
+import { camelCaseToKebabCase } from '@stonyx/utils/string';
+import { getPluralName } from '../plural-registry.js';
+import { dbKey } from '../db.js';
+import { AggregateProperty } from '../aggregates.js';
+
+function getRelationshipInfo(property) {
+  if (typeof property !== 'function') return null;
+  const fnStr = property.toString();
+  const modelName = property.__relatedModelName || null;
+
+  if (fnStr.includes(`getRelationships('belongsTo',`)) return { type: 'belongsTo', modelName };
+  if (fnStr.includes(`getRelationships('hasMany',`)) return { type: 'hasMany', modelName };
+
+  return null;
+}
+
+function sanitizeTableName(name) {
+  return name.replace(/[-/]/g, '_');
+}
+
+export function introspectModels() {
+  const { models } = Orm.instance;
+  const schemas = {};
+
+  for (const [modelKey, modelClass] of Object.entries(models)) {
+    const name = camelCaseToKebabCase(modelKey.slice(0, -5));
+
+    if (name === dbKey) continue;
+
+    const model = new modelClass(modelKey);
+    const columns = {};
+    const foreignKeys = {};
+    const relationships = { belongsTo: {}, hasMany: {} };
+    const vectorColumns = {};
+    let idType = 'number';
+
+    const transforms = Orm.instance.transforms;
+
+    for (const [key, property] of Object.entries(model)) {
+      if (key.startsWith('__')) continue;
+
+      const relInfo = getRelationshipInfo(property);
+
+      if (relInfo?.type === 'belongsTo') {
+        relationships.belongsTo[key] = relInfo.modelName;
+      } else if (relInfo?.type === 'hasMany') {
+        relationships.hasMany[key] = relInfo.modelName;
+      } else if (property?.constructor?.name === 'ModelProperty') {
+        if (key === 'id') {
+          idType = property.type;
+        } else if (property.type === 'vector') {
+          const dimensions = property.dimensions || 1536;
+          columns[key] = getVectorType(dimensions);
+          vectorColumns[key] = dimensions;
+        } else {
+          columns[key] = getPgType(property.type, transforms[property.type]);
+        }
+      }
+    }
+
+    // Build foreign keys from belongsTo relationships
+    for (const [relName, targetModelName] of Object.entries(relationships.belongsTo)) {
+      const fkColumn = `${relName}_id`;
+      foreignKeys[fkColumn] = {
+        references: sanitizeTableName(getPluralName(targetModelName)),
+        column: 'id',
+      };
+    }
+
+    schemas[name] = {
+      table: sanitizeTableName(getPluralName(name)),
+      idType,
+      columns,
+      foreignKeys,
+      relationships,
+      vectorColumns,
+      memory: modelClass.memory === true,
+    };
+  }
+
+  return schemas;
+}
+
+export function buildTableDDL(name, schema, allSchemas = {}) {
+  const { idType, columns, foreignKeys } = schema;
+  const table = sanitizeTableName(schema.table);
+  const lines = [];
+
+  // Primary key
+  if (idType === 'string') {
+    lines.push('  "id" VARCHAR(255) PRIMARY KEY');
+  } else {
+    lines.push('  "id" INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY');
+  }
+
+  // Attribute columns
+  for (const [col, pgType] of Object.entries(columns)) {
+    lines.push(`  "${col}" ${pgType}`);
+  }
+
+  // Foreign key columns
+  for (const [fkCol, fkDef] of Object.entries(foreignKeys)) {
+    const refIdType = getReferencedIdType(fkDef.references, allSchemas);
+    lines.push(`  "${fkCol}" ${refIdType}`);
+  }
+
+  // Timestamps
+  lines.push('  "created_at" TIMESTAMPTZ DEFAULT NOW()');
+  lines.push('  "updated_at" TIMESTAMPTZ DEFAULT NOW()');
+
+  // Foreign key constraints
+  for (const [fkCol, fkDef] of Object.entries(foreignKeys)) {
+    const refTable = sanitizeTableName(fkDef.references);
+    lines.push(`  FOREIGN KEY ("${fkCol}") REFERENCES "${refTable}"("${fkDef.column}") ON DELETE SET NULL`);
+  }
+
+  return `CREATE TABLE IF NOT EXISTS "${table}" (\n${lines.join(',\n')}\n)`;
+}
+
+/**
+ * Build HNSW index DDL for vector columns on a model.
+ * @param {string} name - Model name
+ * @param {Object} schema - Model schema with vectorColumns
+ * @returns {string[]} Array of CREATE INDEX statements
+ */
+export function buildVectorIndexDDL(name, schema) {
+  const table = sanitizeTableName(schema.table);
+  const statements = [];
+
+  for (const [col] of Object.entries(schema.vectorColumns || {})) {
+    statements.push(
+      `CREATE INDEX IF NOT EXISTS "idx_${table}_${col}_hnsw" ON "${table}" USING hnsw ("${col}" vector_cosine_ops) WITH (m = 16, ef_construction = 200)`
+    );
+  }
+
+  return statements;
+}
+
+function getReferencedIdType(tableName, allSchemas) {
+  for (const schema of Object.values(allSchemas)) {
+    if (schema.table === tableName) {
+      return schema.idType === 'string' ? 'VARCHAR(255)' : 'INTEGER';
+    }
+  }
+
+  return 'INTEGER';
+}
+
+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)) {
+      visit(targetModelName);
+    }
+
+    order.push(name);
+  }
+
+  for (const name of Object.keys(schemas)) {
+    visit(name);
+  }
+
+  return order;
+}
+
+export function introspectViews() {
+  const orm = Orm.instance;
+  if (!orm.views) return {};
+
+  const schemas = {};
+
+  for (const [viewKey, viewClass] of Object.entries(orm.views)) {
+    const name = camelCaseToKebabCase(viewKey.slice(0, -4)); // Remove 'View' suffix
+
+    const source = viewClass.source;
+    if (!source) continue;
+
+    const model = new viewClass(name);
+    const columns = {};
+    const foreignKeys = {};
+    const aggregates = {};
+    const relationships = { belongsTo: {}, hasMany: {} };
+
+    for (const [key, property] of Object.entries(model)) {
+      if (key.startsWith('__')) continue;
+      if (key === 'id') continue;
+
+      if (property instanceof AggregateProperty) {
+        aggregates[key] = property;
+        continue;
+      }
+
+      const relInfo = getRelationshipInfo(property);
+
+      if (relInfo?.type === 'belongsTo') {
+        relationships.belongsTo[key] = relInfo.modelName;
+        const fkColumn = `${key}_id`;
+        foreignKeys[fkColumn] = {
+          references: sanitizeTableName(getPluralName(relInfo.modelName)),
+          column: 'id',
+        };
+      } else if (relInfo?.type === 'hasMany') {
+        relationships.hasMany[key] = relInfo.modelName;
+      } else if (property?.constructor?.name === 'ModelProperty') {
+        const transforms = Orm.instance.transforms;
+        columns[key] = getPgType(property.type, transforms[property.type]);
+      }
+    }
+
+    schemas[name] = {
+      viewName: sanitizeTableName(getPluralName(name)),
+      source,
+      groupBy: viewClass.groupBy || undefined,
+      columns,
+      foreignKeys,
+      aggregates,
+      relationships,
+      isView: true,
+      memory: viewClass.memory !== false ? false : false, // Views default to memory:false
+    };
+  }
+
+  return schemas;
+}
+
+export function buildViewDDL(name, viewSchema, modelSchemas = {}) {
+  if (!viewSchema.source) {
+    throw new Error(`View '${name}' must define a source model`);
+  }
+
+  const sourceModelName = viewSchema.source;
+  const sourceSchema = modelSchemas[sourceModelName];
+  const sourceTable = sanitizeTableName(sourceSchema
+    ? sourceSchema.table
+    : getPluralName(sourceModelName));
+
+  const selectColumns = [];
+  const joins = [];
+  const hasAggregates = Object.keys(viewSchema.aggregates || {}).length > 0;
+  const groupByField = viewSchema.groupBy;
+
+  // ID column: groupBy field or source table PK
+  if (groupByField) {
+    selectColumns.push(`"${sourceTable}"."${groupByField}" AS "id"`);
+  } else {
+    selectColumns.push(`"${sourceTable}"."id" AS "id"`);
+  }
+
+  // Aggregate columns
+  for (const [key, aggProp] of Object.entries(viewSchema.aggregates || {})) {
+    // Use pgFunction if available, fall back to mysqlFunction
+    const fn = aggProp.pgFunction || aggProp.mysqlFunction;
+
+    if (aggProp.relationship === undefined) {
+      // Field-level aggregate (groupBy views)
+      if (aggProp.aggregateType === 'count') {
+        selectColumns.push(`COUNT(*) AS "${key}"`);
+      } else {
+        selectColumns.push(`${fn}("${sourceTable}"."${aggProp.field}") AS "${key}"`);
+      }
+    } else {
+      // Relationship aggregate
+      const relName = aggProp.relationship;
+      const relTable = sanitizeTableName(getPluralName(relName));
+
+      if (aggProp.aggregateType === 'count') {
+        selectColumns.push(`${fn}("${relTable}"."id") AS "${key}"`);
+      } else {
+        const field = aggProp.field;
+        selectColumns.push(`${fn}("${relTable}"."${field}") AS "${key}"`);
+      }
+
+      // Add LEFT JOIN for the relationship if not already added
+      const joinKey = `${relTable}`;
+      if (!joins.find(j => j.table === joinKey)) {
+        const fkColumn = `${sourceModelName}_id`;
+        joins.push({
+          table: relTable,
+          condition: `"${relTable}"."${fkColumn}" = "${sourceTable}"."id"`
+        });
+      }
+    }
+  }
+
+  // Regular columns
+  for (const [key] of Object.entries(viewSchema.columns || {})) {
+    selectColumns.push(`"${sourceTable}"."${key}" AS "${key}"`);
+  }
+
+  // Build JOIN clauses
+  const joinClauses = joins.map(j =>
+    `LEFT JOIN "${j.table}" ON ${j.condition}`
+  ).join('\n  ');
+
+  // Build GROUP BY
+  let groupBy = '';
+  if (groupByField) {
+    groupBy = `\nGROUP BY "${sourceTable}"."${groupByField}"`;
+  } else if (hasAggregates) {
+    groupBy = `\nGROUP BY "${sourceTable}"."id"`;
+  }
+
+  const viewName = sanitizeTableName(viewSchema.viewName);
+  const sql = `CREATE OR REPLACE VIEW "${viewName}" AS\nSELECT\n  ${selectColumns.join(',\n  ')}\nFROM "${sourceTable}"${joinClauses ? '\n  ' + joinClauses : ''}${groupBy}`;
+
+  return sql;
+}
+
+export function viewSchemasToSnapshot(viewSchemas) {
+  const snapshot = {};
+
+  for (const [name, schema] of Object.entries(viewSchemas)) {
+    snapshot[name] = {
+      viewName: schema.viewName,
+      source: schema.source,
+      ...(schema.groupBy ? { groupBy: schema.groupBy } : {}),
+      columns: { ...schema.columns },
+      foreignKeys: { ...schema.foreignKeys },
+      isView: true,
+      viewQuery: buildViewDDL(name, schema),
+    };
+  }
+
+  return snapshot;
+}
+
+export function schemasToSnapshot(schemas) {
+  const snapshot = {};
+
+  for (const [name, schema] of Object.entries(schemas)) {
+    snapshot[name] = {
+      table: schema.table,
+      idType: schema.idType,
+      columns: { ...schema.columns },
+      foreignKeys: { ...schema.foreignKeys },
+      ...(schema.vectorColumns && Object.keys(schema.vectorColumns).length > 0
+        ? { vectorColumns: { ...schema.vectorColumns } }
+        : {}),
+    };
+  }
+
+  return snapshot;
+}

package/src/postgres/type-map.js

@@ -0,0 +1,53 @@
+const typeMap = {
+  string: 'VARCHAR(255)',
+  number: 'INTEGER',
+  float: 'REAL',
+  boolean: 'BOOLEAN',
+  date: 'TIMESTAMPTZ',
+  timestamp: 'BIGINT',
+  passthrough: 'TEXT',
+  trim: 'VARCHAR(255)',
+  uppercase: 'VARCHAR(255)',
+  ceil: 'INTEGER',
+  floor: 'INTEGER',
+  round: 'INTEGER',
+};
+
+/**
+ * Resolves a Stonyx ORM attribute type to a PostgreSQL column type.
+ *
+ * For built-in types, returns the mapped PostgreSQL type directly.
+ *
+ * For custom transforms (e.g. an `animal` transform that maps strings to ints):
+ *   - If the transform function exports a `pgType` property, that value is used.
+ *   - Otherwise, if `mysqlType` is defined, it is mapped to a PG equivalent.
+ *   - Otherwise, defaults to JSONB. Values are JSON-stringified on write and
+ *     JSON-parsed on read by PostgreSQL natively.
+ */
+export function getPgType(attrType, transformFn) {
+  if (typeMap[attrType]) return typeMap[attrType];
+  if (transformFn?.pgType) return transformFn.pgType;
+  if (transformFn?.mysqlType) return mysqlTypeToPg(transformFn.mysqlType);
+
+  return 'JSONB';
+}
+
+/**
+ * Returns a vector column type for the given dimensions.
+ * @param {number} dimensions - Vector dimensionality (e.g. 768, 1536)
+ * @returns {string}
+ */
+export function getVectorType(dimensions) {
+  return `vector(${dimensions})`;
+}
+
+function mysqlTypeToPg(mysqlType) {
+  const upper = mysqlType.toUpperCase();
+  if (upper === 'TINYINT(1)') return 'BOOLEAN';
+  if (upper === 'INT' || upper === 'INT AUTO_INCREMENT') return 'INTEGER';
+  if (upper === 'DATETIME') return 'TIMESTAMPTZ';
+  if (upper === 'JSON') return 'JSONB';
+  return mysqlType;
+}
+
+export default typeMap;

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);
+  }
+}