tina4-nodejs 3.1.2 → 3.4.0

package/packages/orm/src/baseModel.ts

@@ -15,6 +15,7 @@ import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from ".
  *     static hasOne = [{ model: "Profile", foreignKey: "user_id" }];
  *     static hasMany = [{ model: "Post", foreignKey: "author_id" }];
  *     static _db = "secondary";
+ *     static fieldMapping = { firstName: "first_name", lastName: "last_name" };
  *   }
  */
 export class BaseModel {
@@ -27,6 +28,14 @@ export class BaseModel {
   static belongsTo?: RelationshipDefinition[];
   static _db?: string;
 
+  /**
+   * Maps JS property names to database column names.
+   * Example: { firstName: "first_name" } means the JS property `firstName`
+   * corresponds to the database column `first_name`.
+   * Properties not listed here use the property name as-is.
+   */
+  static fieldMapping: Record<string, string> = {};
+
   /** Instance data */
   [key: string]: unknown;
 
@@ -35,12 +44,52 @@ export class BaseModel {
 
   constructor(data?: Record<string, unknown>) {
     if (data) {
+      const ModelClass = this.constructor as typeof BaseModel;
+      const reverseMapping = ModelClass.getReverseMapping();
       for (const [key, value] of Object.entries(data)) {
-        this[key] = value;
+        // If this DB column has a mapping, use the JS property name instead
+        const jsProp = reverseMapping[key] ?? key;
+        this[jsProp] = value;
       }
     }
   }
 
+  /**
+   * Get the database column name for a JS property.
+   * Returns the mapped column name, or the property name if no mapping exists.
+   */
+  static getDbColumn(prop: string): string {
+    return this.fieldMapping[prop] ?? prop;
+  }
+
+  /**
+   * Get all instance data converted to database column names.
+   * Uses fieldMapping to translate JS property names to DB column names.
+   */
+  getDbData(): Record<string, unknown> {
+    const ModelClass = this.constructor as typeof BaseModel;
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(ModelClass.fields)) {
+      if (this[key] !== undefined) {
+        const dbCol = ModelClass.getDbColumn(key);
+        result[dbCol] = this[key];
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Get the reverse mapping (DB column → JS property).
+   * Flips fieldMapping so that { firstName: "first_name" } becomes { first_name: "firstName" }.
+   */
+  static getReverseMapping(): Record<string, string> {
+    const reverse: Record<string, string> = {};
+    for (const [jsProp, dbCol] of Object.entries(this.fieldMapping)) {
+      reverse[dbCol] = jsProp;
+    }
+    return reverse;
+  }
+
   /**
    * Get the database adapter for this model.
    */
@@ -52,12 +101,19 @@ export class BaseModel {
   }
 
   /**
-   * Get the primary key field name.
+   * Get the primary key field name (JS property name).
    */
   protected static getPkField(): string {
     return Object.entries(this.fields).find(([, def]) => def.primaryKey)?.[0] ?? "id";
   }
 
+  /**
+   * Get the primary key database column name (applies fieldMapping).
+   */
+  protected static getPkColumn(): string {
+    return this.getDbColumn(this.getPkField());
+  }
+
   /**
    * Find a record by primary key.
    * @param id Primary key value.
@@ -67,7 +123,8 @@ export class BaseModel {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
-    let sql = `SELECT * FROM "${ModelClass.tableName}" WHERE "${pk}" = ?`;
+    const pkCol = ModelClass.getPkColumn();
+    let sql = `SELECT * FROM "${ModelClass.tableName}" WHERE "${pkCol}" = ?`;
 
     if (ModelClass.softDelete) {
       sql += ` AND is_deleted = 0`;
@@ -129,6 +186,7 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
+    const pkCol = ModelClass.getPkColumn();
     const pkValue = this[pk];
     this._relCache = {}; // Clear relationship cache on save
 
@@ -139,17 +197,17 @@ export class BaseModel {
       );
       if (updateFields.length === 0) return;
 
-      const setClause = updateFields.map(([k]) => `"${k}" = ?`).join(", ");
+      const setClause = updateFields.map(([k]) => `"${ModelClass.getDbColumn(k)}" = ?`).join(", ");
       const values = [...updateFields.map(([k]) => this[k]), pkValue];
 
-      db.execute(`UPDATE "${ModelClass.tableName}" SET ${setClause} WHERE "${pk}" = ?`, values);
+      db.execute(`UPDATE "${ModelClass.tableName}" SET ${setClause} WHERE "${pkCol}" = ?`, values);
     } else {
       // Insert
       const insertFields = Object.entries(ModelClass.fields).filter(
         ([name, def]) => !(def.primaryKey && def.autoIncrement) && this[name] !== undefined,
       );
 
-      const columns = insertFields.map(([k]) => `"${k}"`).join(", ");
+      const columns = insertFields.map(([k]) => `"${ModelClass.getDbColumn(k)}"`).join(", ");
       const placeholders = insertFields.map(() => "?").join(", ");
       const values = insertFields.map(([k]) => this[k]);
 
@@ -171,6 +229,7 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
+    const pkCol = ModelClass.getPkColumn();
     const pkValue = this[pk];
 
     if (pkValue === undefined || pkValue === null) {
@@ -179,13 +238,13 @@ export class BaseModel {
 
     if (ModelClass.softDelete) {
       db.execute(
-        `UPDATE "${ModelClass.tableName}" SET is_deleted = 1 WHERE "${pk}" = ?`,
+        `UPDATE "${ModelClass.tableName}" SET is_deleted = 1 WHERE "${pkCol}" = ?`,
         [pkValue],
       );
       this.is_deleted = 1;
     } else {
       db.execute(
-        `DELETE FROM "${ModelClass.tableName}" WHERE "${pk}" = ?`,
+        `DELETE FROM "${ModelClass.tableName}" WHERE "${pkCol}" = ?`,
         [pkValue],
       );
     }
@@ -317,7 +376,13 @@ export class BaseModel {
     if (db.tableExists(this.tableName)) return;
 
     if (typeof db.createTable === "function") {
-      db.createTable(this.tableName, this.fields);
+      // Remap field keys to DB column names if fieldMapping is defined
+      const mappedFields: Record<string, FieldDefinition> = {};
+      for (const [fieldName, def] of Object.entries(this.fields)) {
+        const dbCol = this.getDbColumn(fieldName);
+        mappedFields[dbCol] = def;
+      }
+      db.createTable(this.tableName, mappedFields);
     } else {
       // Fallback: build SQL manually
       const typeMap: Record<string, string> = {
@@ -331,9 +396,10 @@ export class BaseModel {
       };
 
       const colDefs: string[] = [];
-      for (const [colName, def] of Object.entries(this.fields)) {
+      for (const [fieldName, def] of Object.entries(this.fields)) {
+        const dbCol = this.getDbColumn(fieldName);
         const sqlType = typeMap[def.type] || "TEXT";
-        const parts = [`"${colName}" ${sqlType}`];
+        const parts = [`"${dbCol}" ${sqlType}`];
         if (def.primaryKey) parts.push("PRIMARY KEY");
         if (def.autoIncrement) parts.push("AUTOINCREMENT");
         if (def.required && !def.primaryKey) parts.push("NOT NULL");
@@ -382,6 +448,7 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
+    const pkCol = ModelClass.getPkColumn();
     const pkValue = this[pk];
 
     if (pkValue === undefined || pkValue === null) {
@@ -389,7 +456,7 @@ export class BaseModel {
     }
 
     db.execute(
-      `DELETE FROM "${ModelClass.tableName}" WHERE "${pk}" = ?`,
+      `DELETE FROM "${ModelClass.tableName}" WHERE "${pkCol}" = ?`,
       [pkValue],
     );
   }
@@ -405,6 +472,7 @@ export class BaseModel {
 
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
+    const pkCol = ModelClass.getPkColumn();
     const pkValue = this[pk];
 
     if (pkValue === undefined || pkValue === null) {
@@ -412,7 +480,7 @@ export class BaseModel {
     }
 
     db.execute(
-      `UPDATE "${ModelClass.tableName}" SET is_deleted = 0 WHERE "${pk}" = ?`,
+      `UPDATE "${ModelClass.tableName}" SET is_deleted = 0 WHERE "${pkCol}" = ?`,
       [pkValue],
     );
     this.is_deleted = 0;
@@ -570,15 +638,19 @@ export class BaseModel {
     relatedClass: typeof BaseModel & (new (data?: Record<string, unknown>) => R),
     foreignKey: string,
   ): R | null {
-    const fkValue = this[foreignKey];
+    // foreignKey is a DB column name — resolve to JS property name on this model
+    const ModelClass = this.constructor as typeof BaseModel;
+    const reverseMap = ModelClass.getReverseMapping();
+    const fkProp = reverseMap[foreignKey] ?? foreignKey;
+    const fkValue = this[fkProp];
 
     if (fkValue === undefined || fkValue === null) {
       return null;
     }
 
     const db = relatedClass.getDb();
-    const relatedPk = relatedClass.getPkField();
-    let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${relatedPk}" = ?`;
+    const relatedPkCol = relatedClass.getPkColumn();
+    let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${relatedPkCol}" = ?`;
     if (relatedClass.softDelete) {
       sql += ` AND is_deleted = 0`;
     }
@@ -727,10 +799,12 @@ export class BaseModel {
           relatedClass._eagerLoad(related, nested);
         }
 
-        // Group by FK
+        // Group by FK — fk is a DB column name, resolve to JS property name on the related model
+        const relatedReverseMap = relatedClass.getReverseMapping();
+        const fkProp = relatedReverseMap[fk] ?? fk;
         const grouped: Record<string, BaseModel[]> = {};
         for (const record of related) {
-          const fkVal = String(record[fk]);
+          const fkVal = String(record[fkProp]);
           if (!grouped[fkVal]) grouped[fkVal] = [];
           grouped[fkVal].push(record);
         }
@@ -745,16 +819,20 @@ export class BaseModel {
           }
         }
       } else if (relType === "belongsTo") {
+        // fk is a DB column name on the current model — resolve to JS property name
+        const ownerReverseMap = ModelClass.getReverseMapping();
+        const fkProp = ownerReverseMap[fk] ?? fk;
         const fkValues = [...new Set(
           instances
-            .map((inst) => inst[fk])
+            .map((inst) => inst[fkProp])
             .filter((v) => v !== undefined && v !== null),
         )];
         if (fkValues.length === 0) continue;
 
         const relatedPk = relatedClass.getPkField();
+        const relatedPkCol = relatedClass.getPkColumn();
         const placeholders = fkValues.map(() => "?").join(",");
-        let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${relatedPk}" IN (${placeholders})`;
+        let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${relatedPkCol}" IN (${placeholders})`;
         if (relatedClass.softDelete) {
           sql += ` AND is_deleted = 0`;
         }
@@ -772,7 +850,7 @@ export class BaseModel {
         }
 
         for (const inst of instances) {
-          const fkVal = inst[fk];
+          const fkVal = inst[fkProp];
           inst._relCache[relName] = fkVal !== undefined && fkVal !== null
             ? lookup[String(fkVal)] ?? null
             : null;

package/packages/orm/src/database.ts

@@ -1,4 +1,5 @@
-import type { DatabaseAdapter } from "./types.js";
+import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult } from "./types.js";
+import { DatabaseResult } from "./databaseResult.js";
 
 let activeAdapter: DatabaseAdapter | null = null;
 const namedAdapters: Map<string, DatabaseAdapter> = new Map();
@@ -171,15 +172,201 @@ export function parseDatabaseUrl(url: string, username?: string, password?: stri
   return result;
 }
 
+/**
+ * A wrapper class around a DatabaseAdapter that provides a clean, high-level API.
+ *
+ * Mirrors the Database class in Python/Ruby Tina4 implementations.
+ *
+ * Usage:
+ *   const db = await Database.create("sqlite:///path/to/db.sqlite");
+ *   const rows = db.fetch("SELECT * FROM users WHERE active = ?", [true], 10, 0);
+ *   const user = db.fetchOne("SELECT * FROM users WHERE id = ?", [1]);
+ *   db.insert("users", { name: "Alice", email: "alice@example.com" });
+ *   db.update("users", { name: "Bob" }, { id: 1 });
+ *   db.delete("users", { id: 1 });
+ *   db.close();
+ */
+export class Database {
+  private adapter: DatabaseAdapter;
+
+  /**
+   * Create a Database wrapping an existing adapter.
+   * For creating a Database from a URL, use the async static factories:
+   *   Database.create(url) or Database.fromEnv()
+   */
+  constructor(adapter: DatabaseAdapter) {
+    this.adapter = adapter;
+  }
+
+  /**
+   * Async factory: creates a Database from a connection URL.
+   * Works with all adapter types (sqlite, postgres, mysql, mssql, firebird).
+   */
+  static async create(url: string, username?: string, password?: string): Promise<Database> {
+    const adapter = await createAdapterFromUrl(url, username, password);
+    setAdapter(adapter);
+    return new Database(adapter);
+  }
+
+  /**
+   * Create a Database from an environment variable.
+   * @param envKey - Name of the env var holding the connection URL. Defaults to "DATABASE_URL".
+   */
+  static async fromEnv(envKey = "DATABASE_URL"): Promise<Database> {
+    const url = process.env[envKey];
+    if (!url) {
+      throw new Error(`Environment variable "${envKey}" is not set.`);
+    }
+    return Database.create(url);
+  }
+
+  /** Get the underlying adapter (for advanced / escape-hatch usage). */
+  getAdapter(): DatabaseAdapter {
+    return this.adapter;
+  }
+
+  /** Query rows with optional pagination. Returns a DatabaseResult wrapper. */
+  fetch(sql: string, params?: unknown[], limit?: number, offset?: number): DatabaseResult {
+    const rows = this.adapter.fetch<Record<string, unknown>>(sql, params, limit, offset);
+    return new DatabaseResult(rows, undefined, undefined, limit, offset, this.adapter, sql);
+  }
+
+  /** Fetch a single row or null. */
+  fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null {
+    return this.adapter.fetchOne<T>(sql, params);
+  }
+
+  /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
+  execute(sql: string, params?: unknown[]): unknown {
+    return this.adapter.execute(sql, params);
+  }
+
+  /** Insert a row into a table. */
+  insert(table: string, data: Record<string, unknown>): DatabaseWriteResult {
+    return this.adapter.insert(table, data);
+  }
+
+  /** Update rows in a table matching filter. */
+  update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>): DatabaseWriteResult {
+    return this.adapter.update(table, data, filter ?? {});
+  }
+
+  /** Delete rows from a table matching filter. */
+  delete(table: string, filter?: Record<string, unknown>): DatabaseWriteResult {
+    return this.adapter.delete(table, filter ?? {});
+  }
+
+  /** Close the database connection. */
+  close(): void {
+    this.adapter.close();
+  }
+
+  /** Start a transaction. */
+  startTransaction(): void {
+    this.adapter.startTransaction();
+  }
+
+  /** Commit the current transaction. */
+  commit(): void {
+    this.adapter.commit();
+  }
+
+  /** Rollback the current transaction. */
+  rollback(): void {
+    this.adapter.rollback();
+  }
+
+  /** Check if a table exists. */
+  tableExists(name: string): boolean {
+    return this.adapter.tableExists(name);
+  }
+
+  /** List all tables in the database. */
+  getTables(): string[] {
+    return this.adapter.tables();
+  }
+
+  /** Get the last auto-increment id. */
+  getLastId(): string | number {
+    const id = this.adapter.lastInsertId();
+    if (id === null) return 0;
+    return typeof id === "bigint" ? id.toString() : id;
+  }
+}
+
+/**
+ * Internal helper: create a DatabaseAdapter from a parsed URL.
+ * Extracted from initDatabase so Database.create() can reuse it.
+ */
+async function createAdapterFromUrl(url: string, username?: string, password?: string): Promise<DatabaseAdapter> {
+  const parsed = parseDatabaseUrl(url, username, password);
+
+  switch (parsed.type) {
+    case "sqlite": {
+      const { SQLiteAdapter } = await import("./adapters/sqlite.js");
+      return new SQLiteAdapter(parsed.path ?? "./data/tina4.db");
+    }
+    case "postgres": {
+      const { PostgresAdapter } = await import("./adapters/postgres.js");
+      const adapter = new PostgresAdapter({
+        host: parsed.host,
+        port: parsed.port,
+        user: parsed.user,
+        password: parsed.password,
+        database: parsed.database,
+      });
+      await adapter.connect();
+      return adapter;
+    }
+    case "mysql": {
+      const { MysqlAdapter } = await import("./adapters/mysql.js");
+      const adapter = new MysqlAdapter({
+        host: parsed.host,
+        port: parsed.port,
+        user: parsed.user,
+        password: parsed.password,
+        database: parsed.database,
+      });
+      await adapter.connect();
+      return adapter;
+    }
+    case "mssql": {
+      const { MssqlAdapter } = await import("./adapters/mssql.js");
+      const adapter = new MssqlAdapter({
+        host: parsed.host,
+        port: parsed.port,
+        user: parsed.user,
+        password: parsed.password,
+        database: parsed.database,
+      });
+      await adapter.connect();
+      return adapter;
+    }
+    case "firebird": {
+      const { FirebirdAdapter } = await import("./adapters/firebird.js");
+      const adapter = new FirebirdAdapter({
+        host: parsed.host,
+        port: parsed.port,
+        user: parsed.user,
+        password: parsed.password,
+        database: parsed.database,
+      });
+      await adapter.connect();
+      return adapter;
+    }
+  }
+}
+
 /**
  * Initialize the database from a config object or DATABASE_URL env var.
+ * Now returns a Database wrapper instance.
  *
  * Priority:
  *   1. config.url (explicit URL)
  *   2. process.env.DATABASE_URL
  *   3. config.type + config.path (legacy)
  */
-export async function initDatabase(config?: DatabaseConfig): Promise<DatabaseAdapter> {
+export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
   // Resolve credentials: config.user > config.username > env DATABASE_USERNAME
   const resolvedUser = config?.user ?? config?.username ?? process.env.DATABASE_USERNAME;
   const resolvedPassword = config?.password ?? process.env.DATABASE_PASSWORD;
@@ -188,68 +375,9 @@ export async function initDatabase(config?: DatabaseConfig): Promise<DatabaseAda
   const url = config?.url ?? process.env.DATABASE_URL;
 
   if (url) {
-    const parsed = parseDatabaseUrl(url, resolvedUser, resolvedPassword);
-
-    switch (parsed.type) {
-      case "sqlite": {
-        const { SQLiteAdapter } = await import("./adapters/sqlite.js");
-        const adapter = new SQLiteAdapter(parsed.path ?? "./data/tina4.db");
-        setAdapter(adapter);
-        return adapter;
-      }
-      case "postgres": {
-        const { PostgresAdapter } = await import("./adapters/postgres.js");
-        const adapter = new PostgresAdapter({
-          host: parsed.host,
-          port: parsed.port,
-          user: parsed.user,
-          password: parsed.password,
-          database: parsed.database,
-        });
-        await adapter.connect();
-        setAdapter(adapter);
-        return adapter;
-      }
-      case "mysql": {
-        const { MysqlAdapter } = await import("./adapters/mysql.js");
-        const adapter = new MysqlAdapter({
-          host: parsed.host,
-          port: parsed.port,
-          user: parsed.user,
-          password: parsed.password,
-          database: parsed.database,
-        });
-        await adapter.connect();
-        setAdapter(adapter);
-        return adapter;
-      }
-      case "mssql": {
-        const { MssqlAdapter } = await import("./adapters/mssql.js");
-        const adapter = new MssqlAdapter({
-          host: parsed.host,
-          port: parsed.port,
-          user: parsed.user,
-          password: parsed.password,
-          database: parsed.database,
-        });
-        await adapter.connect();
-        setAdapter(adapter);
-        return adapter;
-      }
-      case "firebird": {
-        const { FirebirdAdapter } = await import("./adapters/firebird.js");
-        const adapter = new FirebirdAdapter({
-          host: parsed.host,
-          port: parsed.port,
-          user: parsed.user,
-          password: parsed.password,
-          database: parsed.database,
-        });
-        await adapter.connect();
-        setAdapter(adapter);
-        return adapter;
-      }
-    }
+    const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);
+    setAdapter(adapter);
+    return new Database(adapter);
   }
 
   // Legacy config path — normalize "sqlserver" to "mssql"
@@ -261,7 +389,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<DatabaseAda
       const { SQLiteAdapter } = await import("./adapters/sqlite.js");
       const adapter = new SQLiteAdapter(config?.path ?? "./data/tina4.db");
       setAdapter(adapter);
-      return adapter;
+      return new Database(adapter);
     }
     case "postgres": {
       const { PostgresAdapter } = await import("./adapters/postgres.js");
@@ -274,7 +402,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<DatabaseAda
       });
       await adapter.connect();
       setAdapter(adapter);
-      return adapter;
+      return new Database(adapter);
     }
     case "mysql": {
       const { MysqlAdapter } = await import("./adapters/mysql.js");
@@ -287,7 +415,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<DatabaseAda
       });
       await adapter.connect();
       setAdapter(adapter);
-      return adapter;
+      return new Database(adapter);
     }
     case "mssql": {
       const { MssqlAdapter } = await import("./adapters/mssql.js");
@@ -300,7 +428,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<DatabaseAda
       });
       await adapter.connect();
       setAdapter(adapter);
-      return adapter;
+      return new Database(adapter);
     }
     case "firebird": {
       const { FirebirdAdapter } = await import("./adapters/firebird.js");
@@ -313,7 +441,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<DatabaseAda
       });
       await adapter.connect();
       setAdapter(adapter);
-      return adapter;
+      return new Database(adapter);
     }
     default:
       throw new Error(`Unknown database type: ${type}`);