tina4-nodejs 3.1.2 → 3.4.0

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";