@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/src/timescale/query-builder.ts

@@ -0,0 +1,174 @@
+// 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: string, context: string = 'interval'): string {
+  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: string, context: string = 'aggregate'): string {
+  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();
+}
+
+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;
+  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: 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(validateAggregate(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 ')}` : '';
+  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: 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;
+  validateInterval(bucketSize, 'bucket size');
+  aggregates.forEach(agg => validateAggregate(agg));
+
+  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');
+  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: 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,119 @@
+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;
+}
+
+interface TimescaleDeps {
+  buildCreateHypertable: typeof buildCreateHypertable;
+  buildTimeBucket: typeof buildTimeBucket;
+  buildContinuousAggregate: typeof buildContinuousAggregate;
+  buildEnableCompression: typeof buildEnableCompression;
+  buildCompressionPolicy: typeof buildCompressionPolicy;
+}
+
+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,
+    });
+  }
+
+  private get tsDeps(): TimescaleDeps {
+    return this.deps as unknown as TimescaleDeps;
+  }
+
+  /**
+   * 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.tsDeps.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.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: 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.tsDeps.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.tsDeps.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.tsDeps.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 as string | number | Date | undefined),
+  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,49 @@
+declare module 'mysql2/promise' {
+  interface PoolOptions {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    port?: number;
+    waitForConnections?: boolean;
+    connectionLimit?: number;
+    queueLimit?: number;
+    enableKeepAlive?: boolean;
+    keepAliveInitialDelay?: number;
+    [key: string]: string | number | boolean | undefined;
+  }
+
+  interface ExecuteResult {
+    insertId: number;
+    affectedRows: number;
+    changedRows: number;
+    fieldCount: number;
+    info: string;
+    serverStatus: number;
+    warningStatus: number;
+  }
+
+  interface FieldPacket {
+    name: string;
+    type: number;
+    length: number;
+  }
+
+  type RowDataPacket = Record<string, string | number | boolean | null>;
+
+  interface Pool {
+    execute(sql: string, params?: unknown[]): Promise<[RowDataPacket[] | ExecuteResult, FieldPacket[]]>;
+    query(sql: string, params?: unknown[]): Promise<[RowDataPacket[] | ExecuteResult, FieldPacket[]]>;
+    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;
+}

package/src/types/orm-types.ts

@@ -0,0 +1,158 @@
+import type { AggregateProperty } from '../aggregates.js';
+
+export interface OrmDbConfig {
+  file: string;
+  schema: string;
+  mode: string;
+  directory: string;
+  autosave: string;
+  saveInterval: string | number;
+}
+
+export interface OrmMysqlConfig {
+  host: string;
+  port?: number;
+  user: string;
+  password: string;
+  database: string;
+  connectionLimit?: number;
+  migrationsDir?: string;
+  migrationsTable?: string;
+  [key: string]: unknown;
+}
+
+export interface OrmPostgresConfig {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  connectionLimit?: number;
+  migrationsDir?: string;
+  migrationsTable?: string;
+  [key: string]: unknown;
+}
+
+export interface OrmPaths {
+  model: string;
+  serializer: string;
+  transform: string;
+  view?: string;
+  access?: string;
+  [key: string]: string | undefined;
+}
+
+export interface OrmRestServerConfig {
+  enabled: string;
+  route: string;
+  metaRoute: boolean;
+}
+
+export interface OrmSection {
+  db: OrmDbConfig;
+  paths: OrmPaths;
+  restServer: OrmRestServerConfig;
+  mysql?: OrmMysqlConfig;
+  postgres?: OrmPostgresConfig;
+  timescale?: OrmPostgresConfig;
+  [key: string]: unknown;
+}
+
+export interface OrmConfig {
+  rootPath: string;
+  orm: OrmSection;
+  [key: string]: unknown;
+}
+
+export interface SourceRecord {
+  __model: { __name: string; [key: string]: unknown };
+  __data?: Record<string, unknown>;
+  __relationships?: Record<string, unknown>;
+  id: string | number;
+  [key: string]: unknown;
+}
+
+export interface OrmRecord {
+  id: string | number;
+  __model?: { __name: string };
+  __data: Record<string, unknown> & { id?: string | number; __pendingSqlId?: boolean };
+  __relationships: Record<string, unknown>;
+  toJSON?(options?: { fields?: Set<string>; baseUrl?: string }): Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ForeignKeyDef {
+  references: string;
+  column: string;
+}
+
+export interface HypertableConfig {
+  timeColumn: string;
+  chunkInterval?: string;
+  compress?: {
+    segmentBy?: string;
+    orderBy?: string;
+    after?: string;
+  };
+}
+
+export interface ModelSchema {
+  table: string;
+  idType: string;
+  columns: Record<string, string>;
+  foreignKeys: Record<string, ForeignKeyDef>;
+  relationships: {
+    belongsTo: Record<string, string | null>;
+    hasMany: Record<string, string | null>;
+  };
+  vectorColumns?: Record<string, number>;
+  hypertable?: HypertableConfig;
+  memory: boolean;
+}
+
+export interface ViewSchema {
+  viewName: string;
+  source: string;
+  groupBy?: string;
+  columns: Record<string, string>;
+  foreignKeys: Record<string, ForeignKeyDef>;
+  aggregates: Record<string, AggregateProperty>;
+  relationships: {
+    belongsTo: Record<string, string | null>;
+    hasMany: Record<string, string | null>;
+  };
+  isView: boolean;
+  memory: boolean;
+}
+
+/**
+ * Typed relationship registry maps.
+ * Each key in Orm.relationships stores a different nested Map structure.
+ */
+/** Relationship registry map types — source → target → recordId → value */
+export type HasManyMap = Map<string, Map<string, Map<unknown, unknown[]>>>;
+export type BelongsToMap = Map<string, Map<string, Map<unknown, unknown>>>;
+export type GlobalMap = Map<string, unknown[][]>;
+export type PendingMap = Map<string, Map<unknown, unknown[][]>>;
+export type PendingBelongsToMap = Map<string, Map<unknown, unknown[]>>;
+
+export interface RelationshipMaps {
+  hasMany: HasManyMap;
+  belongsTo: BelongsToMap;
+  global: GlobalMap;
+  pending: PendingMap;
+  pendingBelongsTo: PendingBelongsToMap;
+}
+
+export interface SnapshotEntry {
+  table?: string;
+  idType?: string;
+  columns?: Record<string, string>;
+  foreignKeys?: Record<string, ForeignKeyDef>;
+  vectorColumns?: Record<string, number>;
+  hypertable?: HypertableConfig;
+  isView?: boolean;
+  viewName?: string;
+  source?: string;
+  viewQuery?: string;
+}

package/src/types/pg.d.ts

@@ -0,0 +1,32 @@
+declare module 'pg' {
+  interface PoolConfig {
+    host?: string;
+    user?: string;
+    password?: string;
+    database?: string;
+    port?: number;
+    max?: number;
+    idleTimeoutMillis?: number;
+    connectionTimeoutMillis?: number;
+  }
+
+  type RowData = Record<string, string | number | boolean | null>;
+
+  interface QueryResult {
+    rows: RowData[];
+    rowCount: number;
+    fields?: { name: string; dataTypeID: number }[];
+  }
+
+  export class Pool {
+    constructor(config?: PoolConfig);
+    query(sql: string, params?: unknown[]): Promise<QueryResult>;
+    connect(): Promise<PoolClient>;
+    end(): Promise<void>;
+  }
+
+  export class PoolClient {
+    query(sql: string, params?: unknown[]): Promise<QueryResult>;
+    release(): void;
+  }
+}

package/src/types/stonyx-cron.d.ts

@@ -0,0 +1,5 @@
+declare module '@stonyx/cron' {
+  export default class Cron {
+    register(name: string, fn: () => void | Promise<void>, interval: unknown): void;
+  }
+}

package/src/types/stonyx-events.d.ts

@@ -0,0 +1,4 @@
+declare module '@stonyx/events' {
+  export function setup(events: string[]): void;
+  export function emit(event: string, ...args: unknown[]): Promise<void>;
+}

package/src/types/stonyx-rest-server.d.ts

@@ -0,0 +1,16 @@
+declare module '@stonyx/rest-server' {
+  export class Request {
+    constructor(...args: unknown[]);
+  }
+
+  interface RouteOptions {
+    name: string;
+    options?: { model: string; access: (request: unknown) => unknown } | Record<string, unknown>;
+  }
+
+  export default class RestServer {
+    static instance: RestServer;
+    static close(): void;
+    mountRoute(RequestClass: typeof Request, options: RouteOptions): void;
+  }
+}

package/src/types/stonyx-utils.d.ts

@@ -0,0 +1,33 @@
+declare module '@stonyx/utils/file' {
+  export function createFile(path: string, data: string | Record<string, unknown> | unknown[], options?: { json?: boolean }): Promise<void>;
+  export function createDirectory(path: string): Promise<void>;
+  export function updateFile(path: string, data: string | Record<string, unknown> | unknown[], options?: { json?: boolean }): Promise<void>;
+  export function readFile(path: string, options?: { json?: boolean; missingFileCallback?: () => Promise<Record<string, unknown>> }): Promise<string | Record<string, unknown> | unknown[]>;
+  export function fileExists(path: string): Promise<boolean>;
+  export function deleteDirectory(path: string): Promise<void>;
+  export function forEachFileImport(
+    path: string,
+    callback: (exported: Function | Record<string, unknown>, meta: { name: string }) => void | unknown,
+    options?: { ignoreAccessFailure?: boolean; rawName?: boolean; recursive?: boolean; recursiveNaming?: boolean }
+  ): Promise<void>;
+}
+
+declare module '@stonyx/utils/string' {
+  export function pluralize(word: string): string;
+  export function kebabCaseToPascalCase(str: string): string;
+  export function camelCaseToKebabCase(str: string): string;
+}
+
+declare module '@stonyx/utils/object' {
+  export function get(obj: Record<string, unknown>, path: string): unknown;
+  export function getOrSet<T>(map: Map<unknown, T>, key: unknown, defaultValue: T): T;
+  export function makeArray<T>(value: T | T[]): T[];
+}
+
+declare module '@stonyx/utils/date' {
+  export function getTimestamp(value?: string | number | Date): number;
+}
+
+declare module '@stonyx/utils/prompt' {
+  export function confirm(message: string): Promise<boolean>;
+}

package/src/types/stonyx.d.ts

@@ -0,0 +1,21 @@
+declare module 'stonyx/config' {
+  import type { OrmConfig } from './orm-types.js';
+  const config: OrmConfig;
+  export default config;
+}
+
+declare module 'stonyx/log' {
+  const log: Record<string, ((...args: unknown[]) => void) | undefined>;
+  export default log;
+}
+
+declare module 'stonyx' {
+  export function waitForModule(name: string): Promise<void>;
+}
+
+declare module 'stonyx/test-helpers' {
+  export function setupIntegrationTests(hooks: {
+    before(fn: () => void | Promise<void>): void;
+    after(fn: () => void | Promise<void>): void;
+  }): void;
+}

package/src/utils.ts

@@ -0,0 +1,22 @@
+import { pluralize as basePluralize } from '@stonyx/utils/string';
+import type { OrmRecord } from './types/orm-types.js';
+
+export function isDbError(error: unknown): error is { code: string; message: string } {
+  return typeof error === 'object' && error !== null && 'code' in error && typeof (error as Record<string, unknown>).code === 'string' && 'message' in error && typeof (error as Record<string, unknown>).message === 'string';
+}
+
+export function isOrmRecord(value: unknown): value is OrmRecord {
+  return typeof value === 'object' && value !== null && '__data' in value && '__relationships' in value;
+}
+
+// Wrapper to handle dasherized model names (e.g., "access-link" → "access-links")
+export function pluralize(word: string): string {
+  if (word.includes('-')) {
+    const parts = word.split('-');
+    const last = parts.pop() as string;
+    const pluralizedLast = basePluralize(last);
+    return [...parts, pluralizedLast].join('-');
+  }
+
+  return basePluralize(word);
+}