tina4-nodejs 3.10.76 → 3.10.84

package/packages/orm/src/baseModel.ts

@@ -2,6 +2,7 @@ import { getAdapter, getNamedAdapter, setAdapter, parseDatabaseUrl } from "./dat
 import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
+import { QueryCache } from "./sqlTranslation.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 
 /**
@@ -54,6 +55,7 @@ export class BaseModel {
   static hasMany?: RelationshipDefinition[];
   static belongsTo?: RelationshipDefinition[];
   static _db?: string;
+  static _queryCache?: QueryCache;
 
   /**
    * When true, auto-generates fieldMapping entries from camelCase field names
@@ -69,6 +71,12 @@ export class BaseModel {
    */
   static fieldMapping: Record<string, string> = {};
 
+  /**
+   * When true, auto-generates CRUD routes for this model.
+   * Models must explicitly opt-in by setting `static autoCrud = true;`.
+   */
+  static autoCrud: boolean = false;
+
   /** Instance data */
   [key: string]: unknown;
 
@@ -235,17 +243,95 @@ export class BaseModel {
     return instance;
   }
 
-  /** Alias for findById(). */
-  static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): T | null {
-    return (this as unknown as typeof BaseModel).findById.call(this, id, include) as T | null;
+  /**
+   * Find records by filter dict. Always returns an array.
+   *
+   * Usage:
+   *   User.find({ name: "Alice" })              → [User, ...]
+   *   User.find({ age: 18 }, 10)                → [User, ...] (limit 10)
+   *   User.find({}, 100, 0, "name ASC")         → [User, ...] (with orderBy)
+   *   User.find()                                → all records
+   *
+   * Use findById(id) for single-record primary key lookup.
+   */
+  static find<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    filter?: Record<string, unknown>,
+    limit = 100,
+    offset = 0,
+    orderBy?: string,
+    include?: string[],
+  ): T[] {
+    const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
+    const db = ModelClass.getDb();
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter) {
+      for (const [key, value] of Object.entries(filter)) {
+        const col = ModelClass.getDbColumn(key) ?? key;
+        conditions.push(`"${col}" = ?`);
+        params.push(value);
+      }
+    }
+
+    if (ModelClass.softDelete) {
+      conditions.push("is_deleted = 0");
+    }
+
+    let sql = `SELECT * FROM "${ModelClass.tableName}"`;
+    if (conditions.length > 0) {
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    if (orderBy) {
+      sql += ` ORDER BY ${orderBy}`;
+    }
+
+    const rows = db.fetch(sql, params, limit, offset);
+    const data = (rows as any)?.data ?? rows;
+    const instances = (Array.isArray(data) ? data : []).map((row: Record<string, unknown>) => {
+      const inst = new this(row) as T;
+      (inst as any)._exists = true;
+      return inst;
+    });
+
+    if (include) {
+      ModelClass._eagerLoad(instances as BaseModel[], include);
+    }
+
+    return instances;
   }
 
   /**
    * Load a record into this instance via selectOne.
    * Returns true if found and loaded, false otherwise.
    */
-  load(sql: string, params?: unknown[], include?: string[]): boolean {
+  /**
+   * Load a record into this instance.
+   *
+   * Usage:
+   *   orm.id = 1; orm.load()          — uses PK already set
+   *   orm.load("id = ?", [1])         — filter with params
+   *   orm.load("id = 1")              — filter string
+   *
+   * Returns true if found, false otherwise.
+   */
+  load(filter?: string, params?: unknown[], include?: string[]): boolean {
     const ModelClass = this.constructor as typeof BaseModel & (new (data?: Record<string, unknown>) => BaseModel);
+    const table = (ModelClass as any).tableName ?? (this as any).tableName;
+
+    let sql: string;
+    if (filter === undefined || filter === null) {
+      // No args — use PK already set
+      const pk = (ModelClass as any).primaryKey ?? (this as any).primaryKey ?? "id";
+      const pkValue = (this as any)[pk];
+      if (pkValue === undefined || pkValue === null) return false;
+      sql = `SELECT * FROM ${table} WHERE ${pk} = ?`;
+      params = [pkValue];
+    } else {
+      sql = `SELECT * FROM ${table} WHERE ${filter}`;
+    }
+
     const result = ModelClass.selectOne(sql, params, include);
     if (!result) return false;
     const data = (result as any).toJSON ? (result as any).toJSON() : result;
@@ -338,7 +424,7 @@ export class BaseModel {
    * Save this instance (insert or update).
    * Returns this on success (fluent), null on failure.
    */
-  save(): this | null {
+  save(): this | false {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -381,7 +467,7 @@ export class BaseModel {
       db.commit();
     } catch (e) {
       db.rollback();
-      return null;
+      return false;
     }
     (this as any)._exists = true;
     return this;
@@ -390,7 +476,7 @@ export class BaseModel {
   /**
    * Delete this instance. Uses soft delete if configured.
    */
-  delete(): void {
+  delete(): boolean {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -420,6 +506,7 @@ export class BaseModel {
       db.rollback();
       throw e;
     }
+    return true;
   }
 
   /**
@@ -552,9 +639,9 @@ export class BaseModel {
    * Generate and execute CREATE TABLE DDL from the model's field definitions.
    * Uses the adapter's createTable method if available, otherwise builds SQL directly.
    */
-  static createTable(): void {
+  static createTable(): boolean {
     const db = this.getDb();
-    if (db.tableExists(this.tableName)) return;
+    if (db.tableExists(this.tableName)) return true;
 
     if (typeof db.createTable === "function") {
       // Remap field keys to DB column names if fieldMapping is defined
@@ -601,6 +688,7 @@ export class BaseModel {
         throw e;
       }
     }
+    return true;
   }
 
   /**
@@ -615,6 +703,45 @@ export class BaseModel {
     return result;
   }
 
+  /**
+   * Return true if a record with the given primary key exists.
+   */
+  static exists(id: unknown): boolean {
+    const ModelClass = this as unknown as typeof BaseModel;
+    return ModelClass.findById(id) !== null;
+  }
+
+  /**
+   * Run a raw SQL query with results cached by TTL. Cache is per-model-class.
+   */
+  static cached<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    sql: string,
+    params?: unknown[],
+    ttl = 60,
+  ): T[] {
+    const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
+    if (!ModelClass._queryCache) {
+      ModelClass._queryCache = new QueryCache({ defaultTtl: ttl, maxSize: 500 });
+    }
+    const key = QueryCache.queryKey(`${ModelClass.tableName}:${sql}`, params ?? []);
+    const hit = ModelClass._queryCache.get(key) as T[] | undefined;
+    if (hit !== undefined) return hit;
+    const results = ModelClass.select<T>(sql, params);
+    ModelClass._queryCache.set(key, results, ttl);
+    return results;
+  }
+
+  /**
+   * Clear the per-model query cache.
+   */
+  static clearCache(): void {
+    const ModelClass = this as unknown as typeof BaseModel;
+    if (ModelClass._queryCache) {
+      ModelClass._queryCache.clear();
+    }
+  }
+
   /**
    * Execute a raw SQL SELECT and return results as model instances.
    */
@@ -647,7 +774,7 @@ export class BaseModel {
   /**
    * Permanently delete this instance, bypassing soft delete.
    */
-  forceDelete(): void {
+  forceDelete(): boolean {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -669,12 +796,13 @@ export class BaseModel {
       db.rollback();
       throw e;
     }
+    return true;
   }
 
   /**
    * Restore a soft-deleted record.
    */
-  restore(): void {
+  restore(): boolean {
     const ModelClass = this.constructor as typeof BaseModel;
     if (!ModelClass.softDelete) {
       throw new Error("restore() is only available on models with softDelete enabled");
@@ -701,6 +829,7 @@ export class BaseModel {
       throw e;
     }
     this.is_deleted = 0;
+    return true;
   }
 
   /**

package/packages/orm/src/index.ts

@@ -32,6 +32,7 @@ export {
   migrate,
   createMigration,
   status,
+  Migration,
 } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { generateCrudRoutes } from "./autoCrud.js";

package/packages/orm/src/migration.ts

@@ -745,3 +745,84 @@ export async function createMigration(
 
   return { upPath, downPath };
 }
+
+/**
+ * Object-oriented Migration class — canonical Tina4 Migration API.
+ *
+ * Provides parity with Python, PHP, and Ruby:
+ *   - migrate()           Run all pending migrations
+ *   - rollback(steps=1)   Roll back last N batches
+ *   - status()            Show completed/pending
+ *   - create(description) Scaffold new .sql + .down.sql files
+ *   - getApplied()        List applied migrations
+ *   - getPending()        List pending migration filenames
+ *   - getFiles()          List all migration files on disk
+ *
+ * @example
+ *   const m = new Migration(db, { migrationsDir: "migrations" });
+ *   await m.migrate();
+ *   await m.rollback(2);
+ *   await m.status();
+ *   await m.create("add users table");
+ */
+export class Migration {
+  private db?: DatabaseAdapter;
+  private dir: string;
+  private delimiter: string;
+
+  constructor(db?: DatabaseAdapter, options?: { migrationsDir?: string; delimiter?: string }) {
+    this.db = db;
+    this.dir = options?.migrationsDir ?? "migrations";
+    this.delimiter = options?.delimiter ?? ";";
+  }
+
+  /** Run all pending migrations. Returns applied/skipped/failed summary. */
+  async migrate(): Promise<MigrationResult> {
+    return migrate(this.db, { migrationsDir: this.dir, delimiter: this.delimiter });
+  }
+
+  /** Roll back the last N batches. Returns list of rolled-back migration names. */
+  async rollback(steps = 1): Promise<string[]> {
+    const db = this.db ?? (await import("./database.js")).getAdapter();
+    // If tracking table doesn't exist yet there's nothing to roll back
+    if (!db.tableExists(MIGRATION_TABLE)) return [];
+    const rolled: string[] = [];
+    for (let i = 0; i < steps; i++) {
+      const batch = rollback(this.dir, this.delimiter);
+      if (batch.length === 0) break;
+      rolled.push(...batch);
+    }
+    return rolled;
+  }
+
+  /** Get migration status: which are completed and which are pending. */
+  async status(): Promise<MigrationStatus> {
+    return status(this.db, { migrationsDir: this.dir });
+  }
+
+  /** Scaffold a new .sql + .down.sql migration file. Returns created paths. */
+  async create(description: string): Promise<{ upPath: string; downPath: string }> {
+    return createMigration(description, { migrationsDir: this.dir });
+  }
+
+  /** Return list of completed (applied) migration filenames. */
+  async getApplied(): Promise<string[]> {
+    const s = await this.status();
+    return s.completed;
+  }
+
+  /** Return list of pending migration filenames. */
+  async getPending(): Promise<string[]> {
+    const s = await this.status();
+    return s.pending;
+  }
+
+  /** Return sorted list of all migration files on disk (excludes .down.sql). */
+  getFiles(): string[] {
+    const dir = resolve(this.dir);
+    if (!existsSync(dir)) return [];
+    return sortMigrationFiles(
+      readdirSync(dir).filter((f) => f.endsWith(".sql") && !f.endsWith(".down.sql")),
+    );
+  }
+}