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

package/src/types/orm-types.ts

@@ -0,0 +1,146 @@
+import type { AggregateProperty } from '../aggregates.js';
+
+export interface OrmDbConfig {
+  file: string;
+  schema: string;
+  mode: string;
+  directory: string;
+  autosave: string;
+  saveInterval: unknown;
+}
+
+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: unknown;
+  [key: string]: unknown;
+}
+
+export interface OrmRecord {
+  id: string | number | unknown;
+  __model?: { __name: string };
+  __data: Record<string, unknown> & { id?: unknown; __pendingSqlId?: boolean };
+  __relationships: Record<string, unknown>;
+  toJSON?(options?: { fields?: Set<string>; baseUrl?: string }): unknown;
+  [key: string]: unknown;
+}
+
+export interface ForeignKeyDef {
+  references: string;
+  column: 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>;
+  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>;
+  isView?: boolean;
+  viewName?: string;
+  source?: string;
+  viewQuery?: string;
+}

package/src/types/pg.d.ts

@@ -0,0 +1,28 @@
+declare module 'pg' {
+  interface PoolConfig {
+    host?: string;
+    user?: string;
+    password?: string;
+    database?: string;
+    port?: number;
+    [key: string]: unknown;
+  }
+
+  interface QueryResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    fields?: { name: string }[];
+  }
+
+  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,11 @@
+declare module '@stonyx/rest-server' {
+  export class Request {
+    constructor(...args: unknown[]);
+  }
+
+  export default class RestServer {
+    static instance: RestServer;
+    static close(): void;
+    mountRoute(RequestClass: unknown, options: { name: string; options?: unknown }): void;
+  }
+}

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

@@ -0,0 +1,33 @@
+declare module '@stonyx/utils/file' {
+  export function createFile(path: string, data: unknown, options?: { json?: boolean }): Promise<void>;
+  export function createDirectory(path: string): Promise<void>;
+  export function updateFile(path: string, data: unknown, options?: { json?: boolean }): Promise<void>;
+  export function readFile(path: string, options?: { json?: boolean; missingFileCallback?: () => Promise<unknown> }): Promise<unknown>;
+  export function fileExists(path: string): Promise<boolean>;
+  export function deleteDirectory(path: string): Promise<void>;
+  export function forEachFileImport(
+    path: string,
+    callback: (exported: unknown, meta: { name: string }) => 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: 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?: unknown): 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,16 @@
+import { pluralize as basePluralize } from '@stonyx/utils/string';
+
+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';
+}
+
+// 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 pluralizedLast = basePluralize(parts.pop()!);
+    return [...parts, pluralizedLast].join('-');
+  }
+
+  return basePluralize(word);
+}

package/src/{view-resolver.js → view-resolver.ts}

@@ -1,30 +1,41 @@
-import Orm, { createRecord, store } from '@stonyx/orm';
+import Orm, { store } from '@stonyx/orm';
+import { createRecord } from './manage-record.js';
 import { AggregateProperty } from './aggregates.js';
 import { get } from '@stonyx/utils/object';
+import type { SourceRecord } from './types/orm-types.js';
+
+interface ViewClass {
+  source?: string;
+  resolve?: Record<string, unknown>;
+  groupBy?: string;
+  new (viewName: string): Record<string, unknown>;
+}
 
 export default class ViewResolver {
-  constructor(viewName) {
+  viewName: string;
+
+  constructor(viewName: string) {
     this.viewName = viewName;
   }
 
-  async resolveAll() {
+  async resolveAll(): Promise<unknown[]> {
     const orm = Orm.instance;
-    const { modelClass: viewClass } = orm.getRecordClasses(this.viewName);
+    const { modelClass: viewClass } = orm.getRecordClasses(this.viewName) as { modelClass: ViewClass | undefined; serializerClass: unknown };
 
     if (!viewClass) return [];
 
     const source = viewClass.source;
     if (!source) return [];
 
-    const sourceRecords = await store.findAll(source);
+    const sourceRecords = await store.findAll(source) as SourceRecord[];
     if (!sourceRecords || sourceRecords.length === 0) {
       return [];
     }
 
     const resolveMap = viewClass.resolve || {};
     const viewInstance = new viewClass(this.viewName);
-    const aggregateFields = {};
-    const regularFields = {};
+    const aggregateFields: Record<string, AggregateProperty> = {};
+    const regularFields: Record<string, unknown> = {};
 
     // Categorize fields on the view instance
     for (const [key, value] of Object.entries(viewInstance)) {
@@ -48,16 +59,22 @@ export default class ViewResolver {
     return this._resolvePerRecord(sourceRecords, aggregateFields, regularFields, resolveMap, viewClass);
   }
 
-  _resolvePerRecord(sourceRecords, aggregateFields, regularFields, resolveMap, viewClass) {
-    const results = [];
+  private _resolvePerRecord(
+    sourceRecords: SourceRecord[],
+    aggregateFields: Record<string, AggregateProperty>,
+    regularFields: Record<string, unknown>,
+    resolveMap: Record<string, unknown>,
+    viewClass: ViewClass
+  ): unknown[] {
+    const results: unknown[] = [];
 
     for (const sourceRecord of sourceRecords) {
-      const rawData = { id: sourceRecord.id };
+      const rawData: Record<string, unknown> = { id: sourceRecord.id };
 
       // Compute aggregate fields from source record's relationships
       for (const [key, aggProp] of Object.entries(aggregateFields)) {
-        const relatedRecords = sourceRecord.__relationships?.[aggProp.relationship]
-          || sourceRecord[aggProp.relationship];
+        const relatedRecords = sourceRecord.__relationships?.[aggProp.relationship!]
+          || sourceRecord[aggProp.relationship!];
         const relArray = Array.isArray(relatedRecords) ? relatedRecords : [];
         rawData[key] = aggProp.compute(relArray);
       }
@@ -93,8 +110,8 @@ export default class ViewResolver {
 
       // Clear existing record from store to allow re-resolution
       const viewStore = store.get(this.viewName);
-      if (viewStore?.has(rawData.id)) {
-        viewStore.delete(rawData.id);
+      if (viewStore?.has(rawData.id as number | string)) {
+        viewStore.delete(rawData.id as number | string);
       }
 
       const record = createRecord(this.viewName, rawData, { isDbRecord: true });
@@ -104,21 +121,28 @@ export default class ViewResolver {
     return results;
   }
 
-  _resolveGroupBy(sourceRecords, groupByField, aggregateFields, regularFields, resolveMap, viewClass) {
+  private _resolveGroupBy(
+    sourceRecords: SourceRecord[],
+    groupByField: string,
+    aggregateFields: Record<string, AggregateProperty>,
+    regularFields: Record<string, unknown>,
+    resolveMap: Record<string, unknown>,
+    viewClass: ViewClass
+  ): unknown[] {
     // Group source records by the groupBy field value
-    const groups = new Map();
+    const groups = new Map<unknown, SourceRecord[]>();
     for (const record of sourceRecords) {
       const key = record.__data?.[groupByField] ?? record[groupByField];
       if (!groups.has(key)) {
         groups.set(key, []);
       }
-      groups.get(key).push(record);
+      groups.get(key)!.push(record);
     }
 
-    const results = [];
+    const results: unknown[] = [];
 
     for (const [groupKey, groupRecords] of groups) {
-      const rawData = { id: groupKey };
+      const rawData: Record<string, unknown> = { id: groupKey };
 
       // Compute aggregate fields
       for (const [key, aggProp] of Object.entries(aggregateFields)) {
@@ -127,15 +151,15 @@ export default class ViewResolver {
           rawData[key] = aggProp.compute(groupRecords);
         } else {
           // Relationship aggregate — flatten related records across all group members
-          const allRelated = [];
+          const allRelated: unknown[] = [];
           for (const record of groupRecords) {
-            const relatedRecords = record.__relationships?.[aggProp.relationship]
-              || record[aggProp.relationship];
+            const relatedRecords = record.__relationships?.[aggProp.relationship!]
+              || record[aggProp.relationship!];
             if (Array.isArray(relatedRecords)) {
               allRelated.push(...relatedRecords);
             }
           }
-          rawData[key] = aggProp.compute(allRelated);
+          rawData[key] = aggProp.compute(allRelated as { __data?: Record<string, unknown>; [key: string]: unknown }[]);
         }
       }
 
@@ -163,8 +187,8 @@ export default class ViewResolver {
 
       // Clear existing record from store to allow re-resolution
       const viewStore = store.get(this.viewName);
-      if (viewStore?.has(rawData.id)) {
-        viewStore.delete(rawData.id);
+      if (viewStore?.has(rawData.id as number | string)) {
+        viewStore.delete(rawData.id as number | string);
       }
 
       const record = createRecord(this.viewName, rawData, { isDbRecord: true });
@@ -174,10 +198,11 @@ export default class ViewResolver {
     return results;
   }
 
-  async resolveOne(id) {
+  async resolveOne(id: unknown): Promise<unknown> {
     const all = await this.resolveAll();
-    return all.find(record => {
-      return record.id === id || record.id == id;
+    return all.find((record: unknown) => {
+      const r = record as SourceRecord;
+      return r.id === id || r.id == id;
     });
   }
 }

package/src/view.ts

@@ -0,0 +1,22 @@
+import attr from './attr.js';
+
+export default class View {
+  static memory: boolean = false;
+  static readOnly: boolean = true;
+  static pluralName: string | undefined = undefined;
+  static source: string | undefined = undefined;
+  static groupBy: string | undefined = undefined;
+  static resolve: ((record: unknown) => unknown) | undefined = undefined;
+
+  id = attr('number');
+  __name: string;
+
+  constructor(name: string) {
+    this.__name = name;
+
+    // Enforce readOnly — cannot be overridden to false
+    if ((this.constructor as typeof View).readOnly !== true) {
+      throw new Error(`View '${name}' cannot override readOnly to false`);
+    }
+  }
+}

package/src/has-many.js

@@ -1,68 +0,0 @@
-import { createRecord, relationships, store } from '@stonyx/orm';
-import { getRelationships } from './relationships.js';
-import { getOrSet, makeArray } from '@stonyx/utils/object';
-import { dbKey } from './db.js';
-
-function queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, id) {
-  pendingRelationshipQueue.push({
-    pendingRelationship: getOrSet(pendingRelationships, modelName, new Map()),
-    id
-  });
-
-  return null;
-}
-
-export default function hasMany(modelName) {
-  const globalRelationships = relationships.get('global');
-  const pendingRelationships = relationships.get('pending');
-
-  const fn = (sourceRecord, rawData, options) => {
-    const { __name: sourceModelName } = sourceRecord.__model;
-    const relationshipId = sourceRecord.id;
-    const relationship = getRelationships('hasMany', sourceModelName, modelName, relationshipId);
-    const modelStore = store.get(modelName);
-    const pendingRelationshipQueue = [];
-
-    const output = !rawData ? [] : makeArray(rawData).map(elementData => {
-      let record;
-
-      if (typeof elementData !== 'object') {
-        if (!modelStore) {
-          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
-        }
-
-        record = modelStore.get(elementData);
-
-        if (!record) {
-          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
-        }
-      } else {
-        if (elementData !== Object(elementData)) {
-          return queuePendingRelationship(pendingRelationshipQueue, pendingRelationships, modelName, elementData);
-        }
-
-        record = createRecord(modelName, elementData, options);
-      }
-
-      // Populate belongTo side if the relationship is defined
-      const otherSide = relationships.get('belongsTo').get(modelName)?.get(sourceModelName)?.get(record.id);
-
-      if (otherSide) Object.assign(otherSide, sourceRecord);
-
-      return record;
-    }).filter(value => value);
-
-    relationship.set(relationshipId, output);
-        
-    // Assign global relationship
-    if (options.global || sourceModelName === dbKey) getOrSet(globalRelationships, modelName, []).push(output);
-
-    // Assign pending relationships
-    for (const { pendingRelationship, id } of pendingRelationshipQueue) getOrSet(pendingRelationship, id, []).push(output);
-
-    return output;
-  }
-
-  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
-  return fn;
-}

package/src/relationships.js

@@ -1,43 +0,0 @@
-import { relationships } from "@stonyx/orm";
-
-export default class Relationships {
-  constructor() {
-    if (Relationships.instance) return Relationships.instance;
-    Relationships.instance = this;
-
-    this.data = new Map();
-  }
-
-  get(key) {
-    return this.data.get(key);
-  }
-
-  set(key, value) {
-    this.data.set(key, value);
-  }
-}
-
-// TODO: Refactor mapping to remove a level of iteration
-export function getRelationships(type, sourceModel, targetModel, relationshipId) {
-  const allRelationships = relationships.get(type);
-  
-  // create relationship map for this type of it doesn't already exist
-  if (!allRelationships.has(sourceModel)) allRelationships.set(sourceModel, new Map());
-  
-  const modelRelationship = allRelationships.get(sourceModel);
-
-  if (!modelRelationship.has(targetModel)) modelRelationship.set(targetModel, new Map());
-
-  const relationship = modelRelationship.get(targetModel);
-
-  // TODO: Determine whether already having id should be handled differently
-  //if (relationship.has(relationshipId)) return;
-
-  return relationship;
-}
-
-export function getHasManyRelationships(sourceModel, targetModel) {
-  return relationships.get('hasMany').get(sourceModel)?.get(targetModel);
-}
-
-export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending'];

package/src/timescale/timescale-db.js

@@ -1,111 +0,0 @@
-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);
-  }
-}