tina4-nodejs 3.0.0-rc.2 → 3.1.0

package/packages/orm/src/baseModel.ts

@@ -24,11 +24,15 @@ export class BaseModel {
   static tableFilter?: string;
   static hasOne?: RelationshipDefinition[];
   static hasMany?: RelationshipDefinition[];
+  static belongsTo?: RelationshipDefinition[];
   static _db?: string;
 
   /** Instance data */
   [key: string]: unknown;
 
+  /** Relationship cache for lazy loading */
+  private _relCache: Record<string, unknown> = {};
+
   constructor(data?: Record<string, unknown>) {
     if (data) {
       for (const [key, value] of Object.entries(data)) {
@@ -56,8 +60,10 @@ export class BaseModel {
 
   /**
    * Find a record by primary key.
+   * @param id Primary key value.
+   * @param include Optional array of relationship names to eager-load.
    */
-  static findById<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown): T | null {
+  static findById<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): T | null {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -72,16 +78,24 @@ export class BaseModel {
 
     const rows = db.query(sql, [id]);
     if (rows.length === 0) return null;
-    return new ModelClass(rows[0] as Record<string, unknown>) as T;
+    const instance = new ModelClass(rows[0] as Record<string, unknown>) as T;
+    if (include) {
+      ModelClass._eagerLoad([instance], include);
+    }
+    return instance;
   }
 
   /**
    * Find all records, optionally with a where clause.
+   * @param where Optional WHERE clause.
+   * @param params Optional query parameters.
+   * @param include Optional array of relationship names to eager-load.
    */
   static findAll<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
     where?: string,
     params?: unknown[],
+    include?: string[],
   ): T[] {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
@@ -101,7 +115,11 @@ export class BaseModel {
     const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}`;
 
     const rows = db.query(sql, params);
-    return rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+    const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+    if (include) {
+      ModelClass._eagerLoad(instances, include);
+    }
+    return instances;
   }
 
   /**
@@ -112,6 +130,7 @@ export class BaseModel {
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
     const pkValue = this[pk];
+    this._relCache = {}; // Clear relationship cache on save
 
     if (pkValue !== undefined && pkValue !== null) {
       // Update
@@ -174,8 +193,9 @@ export class BaseModel {
 
   /**
    * Convert to plain object (dictionary).
+   * @param include Optional array of relationship names to include (supports dot notation for nesting).
    */
-  toDict(): Record<string, unknown> {
+  toDict(include?: string[]): Record<string, unknown> {
     const ModelClass = this.constructor as typeof BaseModel;
     const result: Record<string, unknown> = {};
     for (const key of Object.keys(ModelClass.fields)) {
@@ -183,27 +203,66 @@ export class BaseModel {
         result[key] = this[key];
       }
     }
-    // Include relationship data
-    if (ModelClass.hasOne) {
-      for (const rel of ModelClass.hasOne) {
-        const relKey = rel.model.toLowerCase();
-        if (this[relKey] !== undefined) {
-          result[relKey] = this[relKey];
+    // Include soft delete field
+    if (ModelClass.softDelete && this.is_deleted !== undefined) {
+      result.is_deleted = this.is_deleted;
+    }
+
+    if (include) {
+      // Group includes: top-level and nested
+      const topLevel: Record<string, string[]> = {};
+      for (const inc of include) {
+        const parts = inc.split(".", 2);
+        const relName = parts[0];
+        if (!topLevel[relName]) {
+          topLevel[relName] = [];
+        }
+        if (parts.length > 1) {
+          topLevel[relName].push(parts[1]);
         }
       }
-    }
-    if (ModelClass.hasMany) {
-      for (const rel of ModelClass.hasMany) {
-        const relKey = rel.model.toLowerCase() + "s";
-        if (this[relKey] !== undefined) {
-          result[relKey] = this[relKey];
+
+      for (const [relName, nested] of Object.entries(topLevel)) {
+        const cached = this._relCache[relName];
+        if (cached === undefined) {
+          // Try lazy load via instance methods
+          const related = this._lazyLoadRelationship(relName);
+          if (related === undefined) continue;
+          this._relCache[relName] = related;
+        }
+        const data = this._relCache[relName];
+        if (data === null || data === undefined) {
+          result[relName] = null;
+        } else if (Array.isArray(data)) {
+          result[relName] = (data as BaseModel[]).map((r) =>
+            r.toDict(nested.length > 0 ? nested : undefined),
+          );
+        } else if (typeof (data as BaseModel).toDict === "function") {
+          result[relName] = (data as BaseModel).toDict(
+            nested.length > 0 ? nested : undefined,
+          );
+        }
+      }
+    } else {
+      // Legacy: include any relationship data already loaded on instance
+      if (ModelClass.hasOne) {
+        for (const rel of ModelClass.hasOne) {
+          const relKey = rel.model.toLowerCase();
+          if (this[relKey] !== undefined) {
+            result[relKey] = this[relKey];
+          }
+        }
+      }
+      if (ModelClass.hasMany) {
+        for (const rel of ModelClass.hasMany) {
+          const relKey = rel.model.toLowerCase() + "s";
+          if (this[relKey] !== undefined) {
+            result[relKey] = this[relKey];
+          }
         }
       }
     }
-    // Include soft delete field
-    if (ModelClass.softDelete && this.is_deleted !== undefined) {
-      result.is_deleted = this.is_deleted;
-    }
+
     return result;
   }
 
@@ -533,4 +592,199 @@ export class BaseModel {
     this[relKey] = related;
     return related;
   }
+
+  /**
+   * Register a model class for lookup by name (used by eager loading).
+   */
+  static _modelRegistry: Record<string, typeof BaseModel> = {};
+
+  static registerModel(name: string, modelClass: typeof BaseModel): void {
+    BaseModel._modelRegistry[name] = modelClass;
+  }
+
+  /**
+   * Resolve a model class by name from the registry.
+   */
+  private static _resolveModel(name: string): (typeof BaseModel) | null {
+    return BaseModel._modelRegistry[name] ?? null;
+  }
+
+  /**
+   * Lazy-load a single relationship by name (used by toDict with include).
+   */
+  private _lazyLoadRelationship(relName: string): unknown {
+    const ModelClass = this.constructor as typeof BaseModel;
+
+    // Check hasOne
+    if (ModelClass.hasOne) {
+      const rel = ModelClass.hasOne.find((r) => r.model.toLowerCase() === relName || r.model === relName);
+      if (rel) {
+        const relatedClass = BaseModel._modelRegistry[rel.model];
+        if (relatedClass) {
+          return this.hasOne(relatedClass as any, rel.foreignKey);
+        }
+      }
+    }
+
+    // Check hasMany
+    if (ModelClass.hasMany) {
+      const rel = ModelClass.hasMany.find((r) => {
+        const key = r.model.toLowerCase() + "s";
+        return key === relName || r.model.toLowerCase() === relName || r.model === relName;
+      });
+      if (rel) {
+        const relatedClass = BaseModel._modelRegistry[rel.model];
+        if (relatedClass) {
+          return this.hasMany(relatedClass as any, rel.foreignKey);
+        }
+      }
+    }
+
+    // Check belongsTo
+    if (ModelClass.belongsTo) {
+      const rel = ModelClass.belongsTo.find((r) => r.model.toLowerCase() === relName || r.model === relName);
+      if (rel) {
+        const relatedClass = BaseModel._modelRegistry[rel.model];
+        if (relatedClass) {
+          return this.belongsTo(relatedClass as any, rel.foreignKey);
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Eager load relationships for a collection of instances (prevents N+1).
+   * @param instances Array of model instances.
+   * @param include Array of relationship names (supports dot notation for nesting).
+   */
+  static _eagerLoad(instances: BaseModel[], include: string[]): void {
+    if (instances.length === 0) return;
+
+    const ModelClass = instances[0].constructor as typeof BaseModel;
+
+    // Group includes: top-level and nested
+    const topLevel: Record<string, string[]> = {};
+    for (const inc of include) {
+      const parts = inc.split(".", 2);
+      const relName = parts[0];
+      if (!topLevel[relName]) {
+        topLevel[relName] = [];
+      }
+      if (parts.length > 1) {
+        topLevel[relName].push(parts[1]);
+      }
+    }
+
+    for (const [relName, nested] of Object.entries(topLevel)) {
+      // Find the relationship definition
+      let relDef: RelationshipDefinition | undefined;
+      let relType: "hasOne" | "hasMany" | "belongsTo" | null = null;
+
+      if (ModelClass.hasOne) {
+        relDef = ModelClass.hasOne.find((r) => r.model.toLowerCase() === relName || r.model === relName);
+        if (relDef) relType = "hasOne";
+      }
+      if (!relDef && ModelClass.hasMany) {
+        relDef = ModelClass.hasMany.find((r) => {
+          const key = r.model.toLowerCase() + "s";
+          return key === relName || r.model.toLowerCase() === relName || r.model === relName;
+        });
+        if (relDef) relType = "hasMany";
+      }
+      if (!relDef && ModelClass.belongsTo) {
+        relDef = ModelClass.belongsTo.find((r) => r.model.toLowerCase() === relName || r.model === relName);
+        if (relDef) relType = "belongsTo";
+      }
+
+      if (!relDef || !relType) continue;
+
+      const relatedClass = BaseModel._modelRegistry[relDef.model];
+      if (!relatedClass) continue;
+
+      const db = relatedClass.getDb();
+      const fk = relDef.foreignKey;
+
+      if (relType === "hasOne" || relType === "hasMany") {
+        const pk = ModelClass.getPkField();
+        const pkValues = instances
+          .map((inst) => inst[pk])
+          .filter((v) => v !== undefined && v !== null);
+        if (pkValues.length === 0) continue;
+
+        const placeholders = pkValues.map(() => "?").join(",");
+        let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${fk}" IN (${placeholders})`;
+        if (relatedClass.softDelete) {
+          sql += ` AND is_deleted = 0`;
+        }
+
+        const rows = db.query(sql, pkValues);
+        const related = rows.map((row) => new relatedClass(row as Record<string, unknown>));
+
+        // Eager load nested
+        if (nested.length > 0 && related.length > 0) {
+          relatedClass._eagerLoad(related, nested);
+        }
+
+        // Group by FK
+        const grouped: Record<string, BaseModel[]> = {};
+        for (const record of related) {
+          const fkVal = String(record[fk]);
+          if (!grouped[fkVal]) grouped[fkVal] = [];
+          grouped[fkVal].push(record);
+        }
+
+        for (const inst of instances) {
+          const pkVal = String(inst[pk]);
+          const records = grouped[pkVal] || [];
+          if (relType === "hasOne") {
+            inst._relCache[relName] = records[0] ?? null;
+          } else {
+            inst._relCache[relName] = records;
+          }
+        }
+      } else if (relType === "belongsTo") {
+        const fkValues = [...new Set(
+          instances
+            .map((inst) => inst[fk])
+            .filter((v) => v !== undefined && v !== null),
+        )];
+        if (fkValues.length === 0) continue;
+
+        const relatedPk = relatedClass.getPkField();
+        const placeholders = fkValues.map(() => "?").join(",");
+        let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${relatedPk}" IN (${placeholders})`;
+        if (relatedClass.softDelete) {
+          sql += ` AND is_deleted = 0`;
+        }
+
+        const rows = db.query(sql, fkValues);
+        const related = rows.map((row) => new relatedClass(row as Record<string, unknown>));
+
+        if (nested.length > 0 && related.length > 0) {
+          relatedClass._eagerLoad(related, nested);
+        }
+
+        const lookup: Record<string, BaseModel> = {};
+        for (const record of related) {
+          lookup[String(record[relatedPk])] = record;
+        }
+
+        for (const inst of instances) {
+          const fkVal = inst[fk];
+          inst._relCache[relName] = fkVal !== undefined && fkVal !== null
+            ? lookup[String(fkVal)] ?? null
+            : null;
+        }
+      }
+    }
+  }
+
+  /**
+   * Clear the relationship cache.
+   */
+  clearRelCache(): void {
+    this._relCache = {};
+  }
 }

package/packages/orm/src/cachedDatabase.ts

@@ -0,0 +1,180 @@
+/**
+ * Tina4 Cached Database — Transparent query cache decorator for DatabaseAdapter.
+ *
+ * Wraps any DatabaseAdapter and caches SELECT results from fetch() and fetchOne().
+ * Write operations (insert, update, delete, execute) invalidate the entire cache.
+ *
+ * Opt-in via .env:
+ *   TINA4_DB_CACHE=true          # enable (default: false)
+ *   TINA4_DB_CACHE_TTL=30        # TTL in seconds (default: 30)
+ *
+ * Usage:
+ *   import { CachedDatabaseAdapter } from "@tina4/orm";
+ *   import { SQLiteAdapter } from "./adapters/sqlite.js";
+ *
+ *   const raw = new SQLiteAdapter("./data/app.db");
+ *   const db = new CachedDatabaseAdapter(raw);
+ *   db.fetch("SELECT * FROM users");   // cached on second call
+ *   db.cacheStats();                   // { enabled: true, hits: 1, ... }
+ */
+
+import { QueryCache } from "./sqlTranslation.js";
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "./types.js";
+
+function isTruthy(val: string | undefined): boolean {
+  return ["true", "1", "yes", "on"].includes((val ?? "").trim().toLowerCase());
+}
+
+export class CachedDatabaseAdapter implements DatabaseAdapter {
+  private adapter: DatabaseAdapter;
+  private cache: QueryCache;
+  private enabled: boolean;
+  private ttl: number;
+  private hits: number = 0;
+  private misses: number = 0;
+
+  constructor(adapter: DatabaseAdapter, enabled?: boolean, ttl?: number) {
+    this.adapter = adapter;
+    this.enabled = enabled ?? isTruthy(process.env.TINA4_DB_CACHE);
+    this.ttl = ttl ?? parseInt(process.env.TINA4_DB_CACHE_TTL ?? "30", 10);
+    this.cache = new QueryCache({ defaultTtl: this.ttl, maxSize: 10000 });
+  }
+
+  // ── Cache helpers ─────────────────────────────────────────
+
+  cacheStats(): { enabled: boolean; hits: number; misses: number; size: number; ttl: number } {
+    return {
+      enabled: this.enabled,
+      hits: this.hits,
+      misses: this.misses,
+      size: this.cache.size(),
+      ttl: this.ttl,
+    };
+  }
+
+  cacheClear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  private invalidate(): void {
+    this.cache.clear();
+  }
+
+  // ── DatabaseAdapter interface ─────────────────────────────
+
+  execute(sql: string, params?: unknown[]): unknown {
+    if (this.enabled) this.invalidate();
+    return this.adapter.execute(sql, params);
+  }
+
+  executeMany(sql: string, paramsList: unknown[][]): { totalAffected: number; lastInsertId?: number | bigint } {
+    if (this.enabled) this.invalidate();
+    return this.adapter.executeMany(sql, paramsList);
+  }
+
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[] {
+    return this.adapter.query(sql, params);
+  }
+
+  fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[] {
+    if (this.enabled) {
+      const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
+      const cached = this.cache.get<T[]>(key);
+      if (cached !== undefined) {
+        this.hits++;
+        return cached;
+      }
+      const result = this.adapter.fetch<T>(sql, params, limit, skip);
+      this.cache.set(key, result, this.ttl);
+      this.misses++;
+      return result;
+    }
+    return this.adapter.fetch(sql, params, limit, skip);
+  }
+
+  fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null {
+    if (this.enabled) {
+      const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
+      const cached = this.cache.get<T | null>(key);
+      if (cached !== undefined) {
+        this.hits++;
+        return cached;
+      }
+      const result = this.adapter.fetchOne<T>(sql, params);
+      this.cache.set(key, result, this.ttl);
+      this.misses++;
+      return result;
+    }
+    return this.adapter.fetchOne(sql, params);
+  }
+
+  insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult {
+    if (this.enabled) this.invalidate();
+    return this.adapter.insert(table, data);
+  }
+
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult {
+    if (this.enabled) this.invalidate();
+    return this.adapter.update(table, data, filter);
+  }
+
+  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult {
+    if (this.enabled) this.invalidate();
+    return this.adapter.delete(table, filter);
+  }
+
+  startTransaction(): void {
+    this.adapter.startTransaction();
+  }
+
+  commit(): void {
+    this.adapter.commit();
+  }
+
+  rollback(): void {
+    this.adapter.rollback();
+  }
+
+  tables(): string[] {
+    return this.adapter.tables();
+  }
+
+  columns(table: string): ColumnInfo[] {
+    return this.adapter.columns(table);
+  }
+
+  lastInsertId(): number | bigint | null {
+    return this.adapter.lastInsertId();
+  }
+
+  close(): void {
+    this.adapter.close();
+  }
+
+  tableExists(name: string): boolean {
+    return this.adapter.tableExists(name);
+  }
+
+  createTable(name: string, columns: Record<string, FieldDefinition>): void {
+    if (this.enabled) this.invalidate();
+    this.adapter.createTable(name, columns);
+  }
+
+  getTableColumns?(name: string): Array<{ name: string; type: string }> {
+    return this.adapter.getTableColumns?.(name) ?? [];
+  }
+
+  addColumn?(table: string, colName: string, def: FieldDefinition): void {
+    if (this.enabled) this.invalidate();
+    this.adapter.addColumn?.(table, colName, def);
+  }
+
+  /**
+   * Access the underlying adapter directly.
+   */
+  getAdapter(): DatabaseAdapter {
+    return this.adapter;
+  }
+}

package/packages/orm/src/index.ts

@@ -7,8 +7,11 @@ export type {
   ColumnInfo,
   QueryOptions,
   RelationshipDefinition,
+  PaginatedResult,
 } from "./types.js";
 
+export { FetchResult } from "./types.js";
+
 export { initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter } from "./database.js";
 export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
 export { discoverModels } from "./model.js";
@@ -34,6 +37,7 @@ export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";
 export { BaseModel } from "./baseModel.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslation.js";
+export { CachedDatabaseAdapter } from "./cachedDatabase.js";
 export { FakeData } from "./fakeData.js";
 export { seedTable, seedOrm } from "./seeder.js";
 

package/packages/orm/src/model.ts

@@ -43,6 +43,7 @@ export async function discoverModels(modelsDir: string): Promise<DiscoveredModel
         tableFilter: ModelClass.tableFilter,
         hasOne: ModelClass.hasOne as RelationshipDefinition[] | undefined,
         hasMany: ModelClass.hasMany as RelationshipDefinition[] | undefined,
+        belongsTo: ModelClass.belongsTo as RelationshipDefinition[] | undefined,
         dbName: ModelClass._db,
       };
 

package/packages/orm/src/types.ts

@@ -25,6 +25,7 @@ export interface ModelDefinition {
   tableFilter?: string;
   hasOne?: RelationshipDefinition[];
   hasMany?: RelationshipDefinition[];
+  belongsTo?: RelationshipDefinition[];
   dbName?: string;
 }
 
@@ -102,6 +103,80 @@ export interface DatabaseAdapter {
   addColumn?(table: string, colName: string, def: FieldDefinition): void;
 }
 
+export interface PaginatedResult<T = Record<string, unknown>> {
+  data: T[];
+  page: number;
+  perPage: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+/**
+ * Wraps an array of fetched rows with convenience methods.
+ *
+ * Mirrors Python's `DatabaseResult` and Ruby's `Tina4::DatabaseResult`.
+ */
+export class FetchResult<T = Record<string, unknown>> {
+  readonly records: T[];
+  readonly count: number;
+  readonly sql: string;
+
+  constructor(records: T[], sql = "") {
+    this.records = records;
+    this.count = records.length;
+    this.sql = sql;
+  }
+
+  /** Paginate the in-memory result set. */
+  toPaginate(page = 1, perPage = 20): PaginatedResult<T> {
+    const total = this.count;
+    const totalPages = Math.max(1, Math.ceil(total / perPage));
+    const offset = (page - 1) * perPage;
+    const data = this.records.slice(offset, offset + perPage);
+    return {
+      data,
+      page,
+      perPage,
+      total,
+      totalPages,
+      hasNext: page < totalPages,
+      hasPrev: page > 1,
+    };
+  }
+
+  /** Return the first record or null. */
+  first(): T | null {
+    return this.records[0] ?? null;
+  }
+
+  /** Return the last record or null. */
+  last(): T | null {
+    return this.records[this.records.length - 1] ?? null;
+  }
+
+  /** Check if result is empty. */
+  isEmpty(): boolean {
+    return this.records.length === 0;
+  }
+
+  /** Convert to plain array. */
+  toArray(): T[] {
+    return [...this.records];
+  }
+
+  /** Convert to JSON string. */
+  toJSON(): string {
+    return JSON.stringify(this.records);
+  }
+
+  /** Iterate over records. */
+  [Symbol.iterator](): Iterator<T> {
+    return this.records[Symbol.iterator]();
+  }
+}
+
 export interface QueryOptions {
   filter?: Record<string, unknown>;
   sort?: string;