@stonyx/orm 0.2.1-beta.9 → 0.2.1-beta.90

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

package/src/view-resolver.ts

@@ -0,0 +1,211 @@
+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 {
+  viewName: string;
+
+  constructor(viewName: string) {
+    this.viewName = viewName;
+  }
+
+  async resolveAll(): Promise<unknown[]> {
+    const orm = Orm.instance;
+    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) as SourceRecord[];
+    if (!sourceRecords || sourceRecords.length === 0) {
+      return [];
+    }
+
+    const resolveMap = viewClass.resolve || {};
+    const viewInstance = new viewClass(this.viewName);
+    const aggregateFields: Record<string, AggregateProperty> = {};
+    const regularFields: Record<string, unknown> = {};
+
+    // Categorize fields on the view instance
+    for (const [key, value] of Object.entries(viewInstance)) {
+      if (key.startsWith('__')) continue;
+      if (key === 'id') continue;
+
+      if (value instanceof AggregateProperty) {
+        aggregateFields[key] = value;
+      } else if (typeof value !== 'function') {
+        // Regular attr or direct value — not a relationship handler
+        regularFields[key] = value;
+      }
+    }
+
+    const groupByField = viewClass.groupBy;
+
+    if (groupByField) {
+      return this._resolveGroupBy(sourceRecords, groupByField, aggregateFields, regularFields, resolveMap, viewClass);
+    }
+
+    return this._resolvePerRecord(sourceRecords, aggregateFields, regularFields, resolveMap, viewClass);
+  }
+
+  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: Record<string, unknown> = { id: sourceRecord.id };
+
+      // Compute aggregate fields from source record's relationships
+      for (const [key, aggProp] of Object.entries(aggregateFields)) {
+        if (!aggProp.relationship) continue;
+        const relatedRecords = sourceRecord.__relationships?.[aggProp.relationship]
+          || sourceRecord[aggProp.relationship];
+        const relArray = Array.isArray(relatedRecords) ? relatedRecords : [];
+        rawData[key] = aggProp.compute(relArray);
+      }
+
+      // Apply resolve map entries
+      for (const [key, resolver] of Object.entries(resolveMap)) {
+        if (typeof resolver === 'function') {
+          rawData[key] = resolver(sourceRecord);
+        } else if (typeof resolver === 'string') {
+          rawData[key] = get(sourceRecord.__data || sourceRecord, resolver)
+            ?? get(sourceRecord, resolver);
+        }
+      }
+
+      // Map regular attr fields from source record if not already set
+      for (const key of Object.keys(regularFields)) {
+        if (rawData[key] !== undefined) continue;
+
+        const sourceValue = sourceRecord.__data?.[key] ?? sourceRecord[key];
+        if (sourceValue !== undefined) {
+          rawData[key] = sourceValue;
+        }
+      }
+
+      // Set belongsTo source relationship
+      const viewInstanceForRel = new viewClass(this.viewName);
+      for (const [key, value] of Object.entries(viewInstanceForRel)) {
+        if (typeof value === 'function' && key !== 'id') {
+          // This is a relationship handler — pass the source record id
+          rawData[key] = sourceRecord.id;
+        }
+      }
+
+      // Clear existing record from store to allow re-resolution
+      const viewStore = store.get(this.viewName);
+      if (viewStore?.has(rawData.id as number | string)) {
+        viewStore.delete(rawData.id as number | string);
+      }
+
+      const record = createRecord(this.viewName, rawData, { isDbRecord: true });
+      results.push(record);
+    }
+
+    return results;
+  }
+
+  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<unknown, SourceRecord[]>();
+    for (const record of sourceRecords) {
+      const key = record.__data?.[groupByField] ?? record[groupByField];
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      const group = groups.get(key);
+      if (group) group.push(record);
+    }
+
+    const results: unknown[] = [];
+
+    for (const [groupKey, groupRecords] of groups) {
+      const rawData: Record<string, unknown> = { id: groupKey };
+
+      // Compute aggregate fields
+      for (const [key, aggProp] of Object.entries(aggregateFields)) {
+        if (aggProp.relationship === undefined) {
+          // Field-level aggregate — compute over group records directly
+          rawData[key] = aggProp.compute(groupRecords);
+        } else {
+          // Relationship aggregate — flatten related records across all group members
+          if (!aggProp.relationship) continue;
+          const allRelated: unknown[] = [];
+          for (const record of groupRecords) {
+            const relatedRecords = record.__relationships?.[aggProp.relationship]
+              || record[aggProp.relationship];
+            if (Array.isArray(relatedRecords)) {
+              allRelated.push(...relatedRecords);
+            }
+          }
+          rawData[key] = aggProp.compute(allRelated as { __data?: Record<string, unknown>; [key: string]: unknown }[]);
+        }
+      }
+
+      // Apply resolve map entries — functions receive the group array
+      for (const [key, resolver] of Object.entries(resolveMap)) {
+        if (typeof resolver === 'function') {
+          rawData[key] = resolver(groupRecords);
+        } else if (typeof resolver === 'string') {
+          // String path — take value from first record in group
+          const first = groupRecords[0];
+          rawData[key] = get(first.__data || first, resolver)
+            ?? get(first, resolver);
+        }
+      }
+
+      // Map regular attr fields from first record if not already set
+      for (const key of Object.keys(regularFields)) {
+        if (rawData[key] !== undefined) continue;
+        const first = groupRecords[0];
+        const sourceValue = first.__data?.[key] ?? first[key];
+        if (sourceValue !== undefined) {
+          rawData[key] = sourceValue;
+        }
+      }
+
+      // Clear existing record from store to allow re-resolution
+      const viewStore = store.get(this.viewName);
+      if (viewStore?.has(rawData.id as number | string)) {
+        viewStore.delete(rawData.id as number | string);
+      }
+
+      const record = createRecord(this.viewName, rawData, { isDbRecord: true });
+      results.push(record);
+    }
+
+    return results;
+  }
+
+  async resolveOne(id: unknown): Promise<unknown> {
+    const all = await this.resolveAll();
+    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/.claude/code-style-rules.md

@@ -1,44 +0,0 @@
-# Stonyx Code Style Rules
-
-Strict prettier/eslint rules to apply across all Stonyx projects. These will be formalized into an ESLint/Prettier config once enough patterns are collected.
-
----
-
-## Rules
-
-### 1. Destructure config objects in function signatures
-
-When a function receives a config/options object and only uses specific properties, destructure them in the function signature rather than accessing them via dot notation in the body.
-
-**Bad:**
-```javascript
-export async function getPool(mysqlConfig) {
-  pool = mysql.createPool({
-    host: mysqlConfig.host,
-    port: mysqlConfig.port,
-    user: mysqlConfig.user,
-    password: mysqlConfig.password,
-    database: mysqlConfig.database,
-    connectionLimit: mysqlConfig.connectionLimit,
-    // ...
-  });
-}
-```
-
-**Good:**
-```javascript
-export async function getPool({ host, port, user, password, database, connectionLimit }) {
-  pool = mysql.createPool({
-    host,
-    port,
-    user,
-    password,
-    database,
-    connectionLimit,
-    // ...
-  });
-}
-```
-
-**Source:** PR #14, `src/mysql/connection.js`
-**ESLint rule (candidate):** `prefer-destructuring` (with custom config for function parameters)