tina4-nodejs 3.2.1 → 3.5.0

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}`);

package/packages/orm/src/databaseResult.ts

@@ -0,0 +1,207 @@
+import type { DatabaseAdapter, ColumnInfo } from "./types.js";
+
+/** Column metadata returned by columnInfo(). */
+export interface ColumnInfoResult {
+  name: string;
+  type: string;
+  size: number | null;
+  decimals: number | null;
+  nullable: boolean;
+  primary_key: boolean;
+}
+
+/**
+ * DatabaseResult — wraps fetched rows with convenience methods.
+ *
+ * Mirrors Python's `DatabaseResult` dataclass from tina4_python.database.adapter.
+ * Provides iteration, JSON/CSV export, pagination metadata, and array-like access.
+ */
+export class DatabaseResult implements Iterable<Record<string, unknown>> {
+  readonly records: Record<string, unknown>[];
+  readonly columns: string[];
+  readonly count: number;
+  readonly limit: number;
+  readonly offset: number;
+  private readonly _adapter?: DatabaseAdapter;
+  private readonly _sql?: string;
+  private _columnInfoCache?: ColumnInfoResult[];
+
+  constructor(
+    records?: Record<string, unknown>[],
+    columns?: string[],
+    count?: number,
+    limit?: number,
+    offset?: number,
+    adapter?: DatabaseAdapter,
+    sql?: string,
+  ) {
+    this.records = records ?? [];
+    this.columns =
+      columns ?? (this.records.length > 0 ? Object.keys(this.records[0]) : []);
+    this.count = count ?? this.records.length;
+    this.limit = limit ?? this.records.length;
+    this.offset = offset ?? 0;
+    this._adapter = adapter;
+    this._sql = sql;
+  }
+
+  /** JSON string of records. */
+  toJson(): string {
+    return JSON.stringify(this.records);
+  }
+
+  /** CSV with header row. */
+  toCsv(): string {
+    if (this.columns.length === 0) return "";
+    const escape = (val: unknown): string => {
+      if (val === null || val === undefined) return "";
+      const str = String(val);
+      if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+        return `"${str.replace(/"/g, '""')}"`;
+      }
+      return str;
+    };
+    const header = this.columns.map(escape).join(",");
+    const rows = this.records.map((row) =>
+      this.columns.map((col) => escape(row[col])).join(","),
+    );
+    return [header, ...rows].join("\n");
+  }
+
+  /** Same as records — plain array of row objects. */
+  toArray(): Record<string, unknown>[] {
+    return this.records;
+  }
+
+  /** Pagination envelope. */
+  toPaginate(): {
+    records: Record<string, unknown>[];
+    count: number;
+    limit: number;
+    offset: number;
+  } {
+    return {
+      records: this.records,
+      count: this.count,
+      limit: this.limit,
+      offset: this.offset,
+    };
+  }
+
+  /** Iterable — for (const row of result) */
+  [Symbol.iterator](): Iterator<Record<string, unknown>> {
+    return this.records[Symbol.iterator]();
+  }
+
+  /** Number of records in this page. */
+  get length(): number {
+    return this.records.length;
+  }
+
+  /** Array-like indexed access with negative index support. */
+  at(index: number): Record<string, unknown> | undefined {
+    if (index < 0) {
+      index = this.records.length + index;
+    }
+    return this.records[index];
+  }
+
+  /** JSON.stringify support — serialises as the records array. */
+  toJSON(): Record<string, unknown>[] {
+    return this.records;
+  }
+
+  /**
+   * Return column metadata for the query's table.
+   *
+   * Lazy — only queries the database when explicitly called. Caches the
+   * result so subsequent calls return immediately without re-querying.
+   */
+  columnInfo(): ColumnInfoResult[] {
+    if (this._columnInfoCache !== undefined) {
+      return this._columnInfoCache;
+    }
+
+    const table = this._extractTableFromSql();
+
+    if (this._adapter && table) {
+      try {
+        this._columnInfoCache = this._queryColumnMetadata(table);
+        return this._columnInfoCache;
+      } catch {
+        // Fall through to fallback
+      }
+    }
+
+    this._columnInfoCache = this._fallbackColumnInfo();
+    return this._columnInfoCache;
+  }
+
+  /** Extract table name from a SQL query using simple regex. */
+  private _extractTableFromSql(): string | null {
+    if (!this._sql) return null;
+
+    let m = this._sql.match(/\bFROM\s+["']?(\w+)["']?/i);
+    if (m) return m[1];
+
+    m = this._sql.match(/\bINSERT\s+INTO\s+["']?(\w+)["']?/i);
+    if (m) return m[1];
+
+    m = this._sql.match(/\bUPDATE\s+["']?(\w+)["']?/i);
+    if (m) return m[1];
+
+    return null;
+  }
+
+  /** Query the database adapter for column metadata. */
+  private _queryColumnMetadata(table: string): ColumnInfoResult[] {
+    if (!this._adapter) return this._fallbackColumnInfo();
+
+    try {
+      const rawCols: ColumnInfo[] = this._adapter.columns(table);
+      return this._normalizeColumns(rawCols);
+    } catch {
+      return this._fallbackColumnInfo();
+    }
+  }
+
+  /** Normalize adapter column info to standard format. */
+  private _normalizeColumns(rawCols: ColumnInfo[]): ColumnInfoResult[] {
+    return rawCols.map((col) => {
+      const colType = (col.type ?? "UNKNOWN").toUpperCase();
+      const [size, decimals] = this._parseTypeSize(colType);
+      return {
+        name: col.name,
+        type: colType.replace(/\(.*\)/, ""),
+        size,
+        decimals,
+        nullable: col.nullable ?? true,
+        primary_key: col.primaryKey ?? false,
+      };
+    });
+  }
+
+  /** Parse size and decimals from a type string like VARCHAR(255) or NUMERIC(10,2). */
+  private _parseTypeSize(typeStr: string): [number | null, number | null] {
+    const m = typeStr.match(/\((\d+)(?:\s*,\s*(\d+))?\)/);
+    if (m) {
+      const size = parseInt(m[1], 10);
+      const decimals = m[2] ? parseInt(m[2], 10) : null;
+      return [size, decimals];
+    }
+    return [null, null];
+  }
+
+  /** Derive basic column info from record keys when no adapter is available. */
+  private _fallbackColumnInfo(): ColumnInfoResult[] {
+    if (this.columns.length === 0) return [];
+    return this.columns.map((name) => ({
+      name,
+      type: "UNKNOWN",
+      size: null,
+      decimals: null,
+      nullable: true,
+      primary_key: false,
+    }));
+  }
+}

package/packages/orm/src/index.ts

@@ -3,7 +3,7 @@ export type {
   FieldDefinition,
   ModelDefinition,
   DatabaseAdapter,
-  DatabaseResult,
+  DatabaseResult as DatabaseWriteResult,
   ColumnInfo,
   QueryOptions,
   RelationshipDefinition,
@@ -12,7 +12,9 @@ export type {
 
 export { FetchResult } from "./types.js";
 
-export { initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter } from "./database.js";
+export { DatabaseResult } from "./databaseResult.js";
+export type { ColumnInfoResult } from "./databaseResult.js";
+export { Database, initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter } from "./database.js";
 export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
 export { discoverModels } from "./model.js";
 export type { DiscoveredModel } from "./model.js";
@@ -29,8 +31,9 @@ export {
   removeMigrationRecord,
   migrate,
   createMigration,
+  status,
 } from "./migration.js";
-export type { MigrationResult } from "./migration.js";
+export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { generateCrudRoutes } from "./autoCrud.js";
 export { buildQuery, parseQueryString } from "./query.js";
 export { validate } from "./validation.js";