tina4-nodejs 3.10.90 → 3.10.92

package/packages/orm/src/autoCrud.ts

@@ -4,6 +4,70 @@ import { getAdapter } from "./database.js";
 import { buildQuery, parseQueryString } from "./query.js";
 import { validate } from "./validation.js";
 
+/**
+ * Auto-CRUD — discovers ORM models and auto-generates REST endpoints.
+ *
+ * Generated endpoints per model:
+ *   GET    /api/{table}        — list with pagination, filtering, sorting
+ *   GET    /api/{table}/{id}   — get single record
+ *   POST   /api/{table}        — create record
+ *   PUT    /api/{table}/{id}   — update record
+ *   DELETE /api/{table}/{id}   — delete record
+ */
+export class AutoCrud {
+  private static registered: Map<string, DiscoveredModel> = new Map();
+
+  /**
+   * Register a model for auto-CRUD.
+   */
+  static register(model: DiscoveredModel, prefix: string = "/api"): void {
+    const tableName = model.definition.tableName;
+    if (!tableName) {
+      throw new Error(`AutoCrud: model has no tableName set.`);
+    }
+    AutoCrud.registered.set(tableName, model);
+  }
+
+  /**
+   * Discover models from the provided array and register them.
+   * (In Node.js, models are discovered by the server and passed in.)
+   */
+  static discover(discoveredModels: DiscoveredModel[], prefix: string = "/api"): string[] {
+    const names: string[] = [];
+    for (const model of discoveredModels) {
+      AutoCrud.register(model, prefix);
+      names.push(model.definition.tableName);
+    }
+    return names;
+  }
+
+  /**
+   * Return all registered models.
+   */
+  static models(): Map<string, DiscoveredModel> {
+    return new Map(AutoCrud.registered);
+  }
+
+  /**
+   * Clear all registered models (useful for testing).
+   */
+  static clear(): void {
+    AutoCrud.registered.clear();
+  }
+
+  /**
+   * Generate route definitions for all registered models.
+   */
+  static generateRoutes(): RouteDefinition[] {
+    const models = Array.from(AutoCrud.registered.values());
+    return generateCrudRoutes(models);
+  }
+}
+
+/**
+ * Generate CRUD route definitions for the given models.
+ * (Standalone function for backward compatibility.)
+ */
 export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[] {
   const routes: RouteDefinition[] = [];
 
@@ -38,33 +102,28 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
         const adapter = getAdapter();
-        const options = parseQueryString(req.query);
-        const { sql, countSql, params } = buildQuery(tableName, options, extraConditions);
 
-        const countParams = params.slice(0, -2); // Remove LIMIT and OFFSET
-        const items = adapter.query(sql, params);
-        const [{ total }] = adapter.query<{ total: number }>(countSql, countParams);
+        // Parse query params for filtering / sorting / pagination
+        const qp = parseQueryString(req.query ?? {});
+        const { sql, countSql, params } = buildQuery(tableName, qp, extraConditions);
+
+        // params includes limit and offset at the end; countSql doesn't need them
+        const countParams = params.slice(0, -2);
+        const rows = adapter.query(sql, params);
 
-        const limit = options.limit ?? 100;
-        const page = options.page ?? 1;
-        const offset = (page - 1) * limit;
-        const totalPages = Math.ceil(total / limit);
+        const countRow = adapter.query(countSql, countParams);
+        const total = Number(countRow[0]?.total ?? 0);
+        const limit = qp.limit ?? 100;
+        const page = qp.page ?? 1;
 
         res.json({
-          // Primary keys
-          records: items,
-          data: items,
-          count: total,
-          total,
-          limit,
-          offset,
-          page,
-          per_page: limit,
-          perPage: limit,
-          totalPages,
-          total_pages: totalPages,
-          // Legacy nested meta (kept for any clients that use it)
-          meta: { total, page, limit, totalPages },
+          data: rows,
+          meta: {
+            total,
+            page,
+            limit,
+            totalPages: Math.ceil(total / limit),
+          },
         });
       },
     });
@@ -79,16 +138,19 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
         const adapter = getAdapter();
+
         const conditions = [`"${pkColumn}" = ?`, ...extraConditions];
-        const items = adapter.query(
+        const rows = adapter.query(
           `SELECT * FROM "${tableName}" WHERE ${conditions.join(" AND ")}`,
           [req.params.id],
         );
-        if (items.length === 0) {
+
+        if (rows.length === 0) {
           res.status(404).json({ error: "Not Found", statusCode: 404 });
           return;
         }
-        res.json({ data: items[0] });
+
+        res.json({ data: rows[0] });
       },
     });
 
@@ -101,47 +163,39 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
         tags: [tableName],
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
-        const body = req.body as Record<string, unknown> | undefined;
-        if (!body || typeof body !== "object") {
-          res.status(400).json({ error: "Request body is required", statusCode: 400 });
-          return;
-        }
+        const adapter = getAdapter();
+        const body = req.body as Record<string, unknown>;
 
-        const errors = validate(body, fields, false);
+        // Validate against field definitions
+        const errors = validate(body, fields);
         if (errors.length > 0) {
-          res.status(422).json({ error: "Validation failed", statusCode: 422, errors });
+          res.status(422).json({ error: "Validation failed", errors });
           return;
         }
 
-        const adapter = getAdapter();
-
-        // Filter to known fields, exclude auto-increment PKs
-        const insertFields = Object.entries(body).filter(([key]) => {
-          const def = fields[key];
-          return def && !(def.primaryKey && def.autoIncrement);
-        });
-
-        // Add is_deleted = 0 for soft delete models
-        if (softDelete) {
-          insertFields.push(["is_deleted", 0]);
+        // Map JS property names to DB column names
+        const dbBody: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(body)) {
+          dbBody[getDbCol(key)] = value;
         }
 
-        const columns = insertFields.map(([k]) => `"${getDbCol(k)}"`).join(", ");
-        const placeholders = insertFields.map(() => "?").join(", ");
-        const values = insertFields.map(([, v]) => v);
+        const columns = Object.keys(dbBody);
+        const values = Object.values(dbBody);
+        const placeholders = columns.map(() => "?").join(", ");
 
-        const result = adapter.execute(
-          `INSERT INTO "${tableName}" (${columns}) VALUES (${placeholders})`,
+        adapter.execute(
+          `INSERT INTO "${tableName}" (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${placeholders})`,
           values,
-        ) as { lastInsertRowid?: number };
+        );
 
-        const id = result.lastInsertRowid;
+        // Fetch the created record to include auto-generated fields (e.g. id)
+        const lastId = adapter.lastInsertId();
         const created = adapter.query(
           `SELECT * FROM "${tableName}" WHERE "${pkColumn}" = ?`,
-          [id],
+          [lastId],
         );
 
-        res.status(201).json({ data: created[0] });
+        res.status(201).json({ data: created[0] ?? { ...body, [pkField]: lastId } });
       },
     });
 
@@ -154,21 +208,9 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
         tags: [tableName],
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
-        const body = req.body as Record<string, unknown> | undefined;
-        if (!body || typeof body !== "object") {
-          res.status(400).json({ error: "Request body is required", statusCode: 400 });
-          return;
-        }
-
-        const errors = validate(body, fields, true);
-        if (errors.length > 0) {
-          res.status(422).json({ error: "Validation failed", statusCode: 422, errors });
-          return;
-        }
-
         const adapter = getAdapter();
+        const body = req.body as Record<string, unknown>;
 
-        // Check exists (respect soft delete)
         const conditions = [`"${pkColumn}" = ?`, ...extraConditions];
         const existing = adapter.query(
           `SELECT * FROM "${tableName}" WHERE ${conditions.join(" AND ")}`,
@@ -179,18 +221,19 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
           return;
         }
 
-        // Filter to known fields
-        const updateFields = Object.entries(body).filter(([key]) => fields[key] && !fields[key].primaryKey);
-        if (updateFields.length === 0) {
-          res.json({ data: existing[0] });
-          return;
+        // Map JS property names to DB column names
+        const dbBody: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(body)) {
+          dbBody[getDbCol(key)] = value;
         }
 
-        const setClause = updateFields.map(([k]) => `"${getDbCol(k)}" = ?`).join(", ");
-        const values = [...updateFields.map(([, v]) => v), req.params.id];
+        const setClauses = Object.keys(dbBody)
+          .map((col) => `"${col}" = ?`)
+          .join(", ");
+        const values = [...Object.values(dbBody), req.params.id];
 
         adapter.execute(
-          `UPDATE "${tableName}" SET ${setClause} WHERE "${pkColumn}" = ?`,
+          `UPDATE "${tableName}" SET ${setClauses} WHERE "${pkColumn}" = ?`,
           values,
         );
 

package/packages/orm/src/baseModel.ts

@@ -201,7 +201,7 @@ export class BaseModel {
    * @returns A QueryBuilder instance bound to this model's table and database.
    */
   static query(): QueryBuilder {
-    return QueryBuilder.from(this.tableName, this.getDb());
+    return QueryBuilder.fromTable(this.tableName, this.getDb());
   }
 
   /**
@@ -285,7 +285,7 @@ export class BaseModel {
    */
   static create<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
-    data: Record<string, unknown>,
+    data: Record<string, unknown> = {},
   ): T {
     const instance = new this(data) as T;
     instance.save();
@@ -403,6 +403,7 @@ export class BaseModel {
     where?: string,
     params?: unknown[],
     include?: string[],
+    orderBy?: string,
   ): T[] {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
@@ -419,7 +420,8 @@ export class BaseModel {
     }
 
     const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
-    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}`;
+    const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
+    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`;
 
     const rows = db.query(sql, params);
     const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
@@ -755,28 +757,46 @@ export class BaseModel {
   /**
    * Return true if a record with the given primary key exists.
    */
-  static exists(id: unknown): boolean {
+  static exists(pkValue: unknown): boolean {
     const ModelClass = this as unknown as typeof BaseModel;
-    return ModelClass.findById(id) !== null;
+    return ModelClass.findById(pkValue) !== null;
   }
 
   /**
    * Run a raw SQL query with results cached by TTL. Cache is per-model-class.
+   *
+   * @param sql     SQL query string.
+   * @param params  Bind parameters.
+   * @param ttl     Cache TTL in seconds (default 60).
+   * @param limit   Max records to return (default 20).
+   * @param offset  Records to skip (default 0).
+   * @param include Relationship names to eager-load on cache miss.
    */
   static cached<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
     sql: string,
     params?: unknown[],
     ttl = 60,
+    limit = 20,
+    offset = 0,
+    include?: string[],
   ): 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 cacheKey = `${ModelClass.tableName}:${sql}:${limit}:${offset}`;
+    const key = QueryCache.queryKey(cacheKey, params ?? []);
     const hit = ModelClass._queryCache.get(key) as T[] | undefined;
     if (hit !== undefined) return hit;
-    const results = ModelClass.select<T>(sql, params);
+
+    const db = ModelClass.getDb();
+    const querySql = `${sql} LIMIT ${limit} OFFSET ${offset}`;
+    const rows = db.query(querySql, params);
+    const results = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+    if (include && results.length > 0) {
+      ModelClass._eagerLoad(results as BaseModel[], include);
+    }
     ModelClass._queryCache.set(key, results, ttl);
     return results;
   }
@@ -1260,6 +1280,23 @@ export class BaseModel {
     }
   }
 
+  /**
+   * Public alias for _eagerLoad. Eagerly loads relationships for a list of instances,
+   * preventing N+1 queries.
+   *
+   * Usage:
+   *   const users = User.all();
+   *   await User.eagerLoad(users, ["posts", "profile"]);
+   *
+   * @param instances  Array of model instances to load relationships onto.
+   * @param includeList Array of relationship names (supports dot notation for nesting).
+   */
+  static eagerLoad(instances: BaseModel[], includeList: string[]): Promise<void> {
+    const ModelClass = this as unknown as typeof BaseModel;
+    ModelClass._eagerLoad(instances, includeList);
+    return Promise.resolve();
+  }
+
   /**
    * Clear the relationship cache.
    */

package/packages/orm/src/database.ts

@@ -95,7 +95,12 @@ export function parseDatabaseUrl(url: string, username?: string, password?: stri
   // Handle sqlite:// separately because URL class mangles the path
   if (url.startsWith("sqlite:///")) {
     // sqlite:///absolute/path — three slashes means absolute
-    const path = url.slice("sqlite://".length);
+    let path = url.slice("sqlite://".length);
+    // Windows: sqlite:///C:/Users/app.db → /C:/Users/app.db after slicing.
+    // The leading / before the drive letter must be removed.
+    if (/^\/[A-Za-z]:/.test(path)) {
+      path = path.slice(1);
+    }
     result = { type: "sqlite", path };
   } else if (url.startsWith("sqlite://")) {
     // sqlite://./relative or sqlite://relative
@@ -223,7 +228,7 @@ export class Database {
   private pool: (DatabaseAdapter | null)[] = [];
 
   /** Pool size (0 = single connection) */
-  private poolSize: number = 0;
+  private _poolSize: number = 0;
 
   /** Round-robin index */
   private poolIndex: number = 0;
@@ -270,7 +275,7 @@ export class Database {
       setAdapter(adapters[0]);
 
       const db = new Database(adapters[0]);
-      db.poolSize = pool;
+      db._poolSize = pool;
       db.pool = adapters;
       db.poolIndex = 0;
       db.adapter = null;  // Don't use single-adapter path
@@ -304,9 +309,9 @@ export class Database {
    * Get the next adapter — from pool (round-robin) or single connection.
    */
   private getNextAdapter(): DatabaseAdapter {
-    if (this.poolSize > 0) {
+    if (this._poolSize > 0) {
       const idx = this.poolIndex;
-      this.poolIndex = (this.poolIndex + 1) % this.poolSize;
+      this.poolIndex = (this.poolIndex + 1) % this._poolSize;
       return this.pool[idx] as DatabaseAdapter;
     }
 
@@ -319,16 +324,46 @@ export class Database {
   }
 
   /** Get the pool size (0 = single connection mode). */
-  getPoolSize(): number {
-    return this.poolSize;
+  poolSize(): number {
+    return this._poolSize;
+  }
+
+  /** Alias for poolSize() — returns total pool size (0 = single connection mode). */
+  size(): number {
+    return this._poolSize;
   }
 
   /** Get the number of active (created) connections in the pool. */
-  getActivePoolCount(): number {
-    if (this.poolSize === 0) return this.adapter ? 1 : 0;
+  activeCount(): number {
+    if (this._poolSize === 0) return this.adapter ? 1 : 0;
     return this.pool.filter(a => a !== null).length;
   }
 
+  /**
+   * Borrow a connection from the pool (or the single adapter).
+   * The caller is responsible for returning it via checkin().
+   */
+  checkout(): DatabaseAdapter {
+    return this.getNextAdapter();
+  }
+
+  /**
+   * Return a borrowed connection to the pool.
+   * For round-robin pools this is a no-op (connections stay in the pool array),
+   * but the method exists for API parity and future pooling strategies.
+   */
+  checkin(_adapter: DatabaseAdapter): void {
+    // No-op for round-robin pool — connections are not removed on checkout.
+  }
+
+  /**
+   * Close all pooled connections and clear the pool.
+   * Equivalent to close() but named for explicit pool teardown.
+   */
+  closeAll(): void {
+    this.close();
+  }
+
   /** Query rows with optional pagination. Returns a DatabaseResult wrapper. */
   fetch(sql: string, params?: unknown[], limit?: number, offset?: number): DatabaseResult {
     const adapter = this.getNextAdapter();
@@ -376,9 +411,9 @@ export class Database {
   }
 
   /** Update rows in a table matching filter. */
-  update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>): DatabaseWriteResult {
+  update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>, params?: unknown[]): DatabaseWriteResult {
     const adapter = this.getNextAdapter();
-    const result = adapter.update(table, data, filter ?? {});
+    const result = adapter.update(table, data, filter ?? {}, params);
     if (this.autoCommit) {
       try { adapter.commit(); } catch { /* no active transaction */ }
     }
@@ -386,9 +421,9 @@ export class Database {
   }
 
   /** Delete rows from a table matching filter. */
-  delete(table: string, filter?: Record<string, unknown>): DatabaseWriteResult {
+  delete(table: string, filter?: Record<string, unknown>, params?: unknown[]): DatabaseWriteResult {
     const adapter = this.getNextAdapter();
-    const result = adapter.delete(table, filter ?? {});
+    const result = adapter.delete(table, filter ?? {}, params);
     if (this.autoCommit) {
       try { adapter.commit(); } catch { /* no active transaction */ }
     }
@@ -397,7 +432,7 @@ export class Database {
 
   /** Close all database connections (pool or single). */
   close(): void {
-    if (this.poolSize > 0) {
+    if (this._poolSize > 0) {
       for (let i = 0; i < this.pool.length; i++) {
         if (this.pool[i] !== null) {
           this.pool[i]!.close();
@@ -454,7 +489,7 @@ export class Database {
    * @param paramSets - Array of parameter arrays, one per execution.
    * @returns Array of results from each execution.
    */
-  executeMany(sql: string, paramSets: unknown[][]): unknown[] {
+  executeMany(sql: string, paramSets: unknown[][] = []): unknown[] {
     const adapter = this.getNextAdapter();
     const results: unknown[] = [];
 
@@ -486,6 +521,14 @@ export class Database {
     };
   }
 
+  /** Clear the query result cache. */
+  cacheClear(): void {
+    // Node database layer does not maintain an internal query cache at this
+    // level (caching lives in the SQLTranslation layer). This method exists
+    // for API parity with PHP, Python, and Ruby.
+    // To clear the SQLTranslation query cache use: QueryCache.clear()
+  }
+
   /** Get the last auto-increment id. */
   getLastId(): string | number {
     const id = this.getNextAdapter().lastInsertId();

package/packages/orm/src/databaseResult.ts

@@ -122,6 +122,11 @@ export class DatabaseResult implements Iterable<Record<string, unknown>> {
     return this.records[Symbol.iterator]();
   }
 
+  /** Total count — cross-framework parity with Python/Ruby. */
+  size(): number {
+    return this.count;
+  }
+
   /** Number of records in this page. */
   get length(): number {
     return this.records.length;

package/packages/orm/src/fakeData.ts

@@ -14,16 +14,6 @@ export class FakeData extends CoreFakeData {
     super(seed);
   }
 
-  /** Alias for fullName() to match the Python API. */
-  name(): string {
-    return this.fullName();
-  }
-
-  /** Alias for float() to match the Python API. */
-  numeric(min = 0, max = 1000, decimals = 2): number {
-    return this.float(min, max, decimals);
-  }
-
   /**
    * Generate a Date object within a year range.
    * Matches the Python API's datetime() method.
@@ -69,7 +59,7 @@ export class FakeData extends CoreFakeData {
     if (col.includes("company") || col.includes("org")) return this.company();
     if (col.includes("job") || col.includes("title") || col.includes("position")) return this.jobTitle();
     if (col.includes("url") || col.includes("website") || col.includes("link")) return this.url();
-    if (col.includes("color") || col.includes("colour")) return this.hexColor();
+    if (col.includes("color") || col.includes("colour")) return this.colorHex();
     if (col.includes("uuid") || col === "guid") return this.uuid();
     if (col === "ip" || col === "ip_address" || col === "ipaddress") return this.ipAddress();
     if (col.includes("currency")) return this.currency();

package/packages/orm/src/index.ts

@@ -35,7 +35,7 @@ export {
   Migration,
 } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
-export { generateCrudRoutes } from "./autoCrud.js";
+export { AutoCrud, generateCrudRoutes } from "./autoCrud.js";
 export { buildQuery, parseQueryString } from "./query.js";
 export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";

package/packages/orm/src/migration.ts

@@ -191,7 +191,7 @@ export function isMigrationApplied(name: string): boolean {
 /**
  * Record a migration as applied.
  */
-export function recordMigration(name: string, batch: number): void {
+export function recordMigration(name: string, batch: number, passed: number = 1): void {
   const adapter = getAdapter();
   if (isFirebirdAdapter(adapter)) {
     // Firebird: generate ID from sequence
@@ -706,8 +706,11 @@ export async function status(
  */
 export async function createMigration(
   description: string,
-  options?: { migrationsDir?: string },
-): Promise<{ upPath: string; downPath: string }> {
+  options?: { migrationsDir?: string; kind?: "sql" | "class" },
+): Promise<string | { upPath: string; downPath: string }> {
+  if (options?.kind === "class") {
+    return createClassMigration(description, options);
+  }
   const dir = resolve(options?.migrationsDir ?? "migrations");
 
   // Ensure directory exists
@@ -746,6 +749,66 @@ export async function createMigration(
   return { upPath, downPath };
 }
 
+/**
+ * Create a new TypeScript class-based migration file with a timestamp prefix.
+ *
+ * @param description - Human-readable description (used in filename and class name).
+ * @param options - Optional configuration.
+ * @returns Path to the created file.
+ */
+export async function createClassMigration(
+  description: string,
+  options?: { migrationsDir?: string },
+): Promise<string> {
+  const dir = resolve(options?.migrationsDir ?? "migrations");
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const safeName = description
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+
+  // Derive PascalCase class name
+  const className = description
+    .replace(/[^a-zA-Z0-9 ]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+    .join("");
+
+  const now = new Date();
+  const timestamp = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0"),
+    String(now.getHours()).padStart(2, "0"),
+    String(now.getMinutes()).padStart(2, "0"),
+    String(now.getSeconds()).padStart(2, "0"),
+  ].join("");
+
+  const fileName = `${timestamp}_${safeName}.ts`;
+  const filePath = join(dir, fileName);
+
+  const content =
+    `// Migration: ${description}\n` +
+    `// Created: ${now.toISOString()}\n\n` +
+    `import type { DatabaseAdapter } from "@tina4/orm";\n\n` +
+    `export class ${className} {\n` +
+    `  async up(db: DatabaseAdapter): Promise<void> {\n` +
+    `    // db.execute("CREATE TABLE ...");\n` +
+    `  }\n\n` +
+    `  async down(db: DatabaseAdapter): Promise<void> {\n` +
+    `    // db.execute("DROP TABLE IF EXISTS ...");\n` +
+    `  }\n` +
+    `}\n`;
+
+  writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
 /**
  * Object-oriented Migration class — canonical Tina4 Migration API.
  *
@@ -800,8 +863,18 @@ export class Migration {
     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 }> {
+  /**
+   * Scaffold a new migration file.
+   *
+   * kind="sql"   — creates {timestamp}_{description}.sql + .down.sql (default)
+   * kind="class" — creates {timestamp}_{description}.ts with a TypeScript class template
+   *
+   * Returns the path to the created up file (or class file).
+   */
+  async create(description: string, kind: "sql" | "class" = "sql"): Promise<string | { upPath: string; downPath: string }> {
+    if (kind === "class") {
+      return createClassMigration(description, { migrationsDir: this.dir });
+    }
     return createMigration(description, { migrationsDir: this.dir });
   }