tina4-nodejs 3.13.92 → 3.13.94

package/types/orm/src/adapters/mysql.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Tina4 MySQL Adapter — uses the `mysql2` package (optional peer dependency).
+ *
+ * Install: npm install mysql2
+ * URL format: mysql://user:pass@host:port/database
+ */
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface MysqlConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+}
+export declare class MysqlAdapter implements DatabaseAdapter {
+    private config;
+    private connection;
+    private _lastInsertId;
+    private _inTransaction;
+    constructor(config: MysqlConfig | string);
+    /** Connect to MySQL. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private ensureConnected;
+    private queryPromise;
+    /** Translate SQL for MySQL dialect. */
+    translateSql(sql: string): string;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    deleteAsync(table: string, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    startTransaction(): void;
+    startTransactionAsync(): Promise<void>;
+    commit(): void;
+    commitAsync(): Promise<void>;
+    rollback(): void;
+    rollbackAsync(): Promise<void>;
+    tables(): string[];
+    tablesAsync(): Promise<string[]>;
+    columns(table: string): ColumnInfo[];
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    lastInsertId(): number | bigint | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    tableExistsAsync(name: string): Promise<boolean>;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+}

package/types/orm/src/adapters/odbc.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Tina4 ODBC Adapter — uses the `odbc` package (optional peer dependency).
+ *
+ * Install: npm install odbc
+ * URL format: odbc:///DSN=MyDSN
+ *             odbc:///DRIVER={driver};SERVER=host;DATABASE=db
+ *
+ * The connection string after stripping the "odbc:///" prefix is passed
+ * directly to odbc.connect(), so any valid ODBC connection string works.
+ */
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface OdbcConfig {
+    /** Full ODBC connection string, e.g. "DSN=MyDSN" or "DRIVER={SQL Server};SERVER=host;DATABASE=db" */
+    connectionString: string;
+}
+export declare class OdbcAdapter implements DatabaseAdapter {
+    private config;
+    private connection;
+    private _lastInsertId;
+    private _inTransaction;
+    /**
+     * Accepts either an OdbcConfig object or a raw connection string.
+     * When created via Database.create("odbc:///DSN=MyDSN"), the "odbc:///"
+     * prefix is stripped by parseDatabaseUrl and the remainder is passed here.
+     */
+    constructor(config: OdbcConfig | string);
+    /** Extract the raw ODBC connection string from config. */
+    private getConnectionString;
+    /** Connect to the ODBC data source. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private ensureConnected;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    insert(table: string, data: Record<string, unknown>): DatabaseResult;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult;
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult;
+    startTransaction(): void;
+    commit(): void;
+    rollback(): void;
+    tables(): string[];
+    columns(table: string): ColumnInfo[];
+    tableExists(name: string): boolean;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    getTableColumns(name: string): Array<{
+        name: string;
+        type: string;
+    }>;
+    addColumn(table: string, colName: string, def: FieldDefinition): void;
+    /** Execute a write statement (INSERT, UPDATE, DELETE, DDL). */
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    /** Execute a statement with multiple parameter sets inside a single transaction. */
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    /** Run a SELECT and return all matching rows. */
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Run a SELECT with optional LIMIT/OFFSET pagination. */
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    /** Run a SELECT and return the first row or null. */
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    /** Insert a single row into a table. */
+    insertAsync(table: string, data: Record<string, unknown>): Promise<DatabaseResult>;
+    /** Update rows in a table matching filter. */
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    /** Delete rows from a table. */
+    deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): Promise<DatabaseResult>;
+    /** Begin a transaction. */
+    startTransactionAsync(): Promise<void>;
+    /** Commit the current transaction. */
+    commitAsync(): Promise<void>;
+    /** Rollback the current transaction. */
+    rollbackAsync(): Promise<void>;
+    /** List all user tables using ODBC catalog functions. */
+    tablesAsync(): Promise<string[]>;
+    /** Get column metadata for a table using ODBC catalog functions. */
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    /** Check whether a table exists. */
+    tableExistsAsync(name: string): Promise<boolean>;
+    /** Create a table from a FieldDefinition map. Uses generic SQL — works with most ODBC sources. */
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+    /** Get raw column name+type list for a table. */
+    getTableColumnsAsync(name: string): Promise<Array<{
+        name: string;
+        type: string;
+    }>>;
+    /** Add a column to an existing table. */
+    addColumnAsync(table: string, colName: string, def: FieldDefinition): Promise<void>;
+    lastInsertId(): number | bigint | null;
+    close(): void;
+}

package/types/orm/src/adapters/postgres.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tina4 PostgreSQL Adapter — uses the `pg` package (optional peer dependency).
+ *
+ * Install: npm install pg @types/pg
+ * URL format: postgresql://user:pass@host:port/database
+ */
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface PostgresConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+}
+export declare class PostgresAdapter implements DatabaseAdapter {
+    private config;
+    private client;
+    private _lastInsertId;
+    private _inTransaction;
+    constructor(config: PostgresConfig | string);
+    /** Connect to PostgreSQL. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private ensureConnected;
+    /** Convert ? placeholders to $1, $2, ... for pg. */
+    /** Ensure bytea columns are Buffer (already the case with pg). No-op guard. */
+    private decodeBlobs;
+    private convertPlaceholders;
+    /**
+     * Normalise an `id` column value (typed `unknown` because pg row values are
+     * `unknown`) into the shape `_lastInsertId` / `DatabaseResult.lastId`
+     * expect. At runtime PG returns numeric PKs as number/bigint (the int8/numeric
+     * type parsers above coerce them to Number); a numeric string is coerced to a
+     * number so the SERIAL path always returns the integer id.
+     *
+     * A non-numeric string id — the UUID PK case (`id uuid PRIMARY KEY DEFAULT
+     * gen_random_uuid()`) returned via RETURNING — is preserved as-is so the
+     * insert surfaces the actual id instead of null (#256). null/undefined/empty
+     * still become null.
+     */
+    private normalizeId;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    /** Async executeMany for real usage. */
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    /** Async execute for real usage. */
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    /** Async query for real usage. */
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    deleteAsync(table: string, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    startTransaction(): void;
+    startTransactionAsync(): Promise<void>;
+    commit(): void;
+    commitAsync(): Promise<void>;
+    rollback(): void;
+    rollbackAsync(): Promise<void>;
+    tables(): string[];
+    tablesAsync(): Promise<string[]>;
+    columns(table: string): ColumnInfo[];
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    lastInsertId(): number | bigint | string | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    tableExistsAsync(name: string): Promise<boolean>;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+    /** Translate SQL for PostgreSQL dialect. */
+    translateSql(sql: string): string;
+}

package/types/orm/src/adapters/sqlite.d.ts

@@ -0,0 +1,56 @@
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export declare class SQLiteAdapter implements DatabaseAdapter {
+    private db;
+    private _lastInsertId;
+    constructor(dbPath: string);
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
+    private _inTransaction;
+    startTransaction(): void;
+    commit(): void;
+    rollback(): void;
+    tables(): string[];
+    columns(table: string): ColumnInfo[];
+    lastInsertId(): number | bigint | null;
+    close(): void;
+    /**
+     * Atomically increment and return the next value of a tina4_sequences row.
+     *
+     * DB-contract B (no duplicate primary keys under concurrency): the old
+     * read-increment-read path in Database.sequenceNext() yields at every `await`
+     * between the read and the write, so two concurrent async callers can read the
+     * same `current_value` and return the same id. This method runs the WHOLE
+     * operation — ensure-table, seed-if-absent, and the increment-and-return — as
+     * ONE synchronous burst on the single shared `node:sqlite` connection. Because
+     * `node:sqlite` is synchronous and JavaScript is single-threaded, no other
+     * async task can interleave between the statements (there is no `await`
+     * inside), so the increment is atomic and every caller gets a distinct id.
+     * This is the Node analog of the Python master holding SQLiteAdapter._write_lock
+     * across the whole op.
+     *
+     * On SQLite >= 3.35 a single `UPDATE ... SET current_value = current_value + 1
+     * ... RETURNING current_value` is itself atomic and returns the new value in
+     * one statement (read via prepare().all() — stmt.run() does not surface
+     * RETURNING rows). Older SQLite does `UPDATE ... + 1` then `SELECT`, still
+     * race-safe because both run in the same synchronous burst.
+     *
+     * @throws if the sequence row vanishes mid-increment (never silently returns 1).
+     */
+    sequenceNextSqlite(seqName: string, seedValue: number): number;
+    tableExists(name: string): boolean;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    getTableColumns(name: string): Array<{
+        name: string;
+        type: string;
+    }>;
+    addColumn(table: string, colName: string, def: FieldDefinition): void;
+}

package/types/orm/src/autoCrud.d.ts

@@ -0,0 +1,73 @@
+import type { RouteDefinition } from "../../core/src/index.js";
+import type { DiscoveredModel } from "./model.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
+ */
+/**
+ * Options accepted by the AutoCrud registration API.
+ *
+ * `public` is the cross-backend escape hatch (parity with python's `public=True`
+ * and php's `bool $public`). Write routes (POST/PUT/DELETE) are secure-by-default
+ * — the router gates them unless a def sets `secure: false`. Set `public: true`
+ * to open the generated write routes explicitly. Reads (GET) are always public.
+ */
+export interface AutoCrudOptions {
+    /** When true, the generated write routes (POST/PUT/DELETE) are OPEN (secure:false). Default false → secure. */
+    public?: boolean;
+}
+export declare class AutoCrud {
+    private static registered;
+    /** tableName -> public-writes flag (default secure); mirrors php's `$this->public`. */
+    private static publicWrites;
+    /**
+     * Register a model for auto-CRUD.
+     *
+     * @param options.public If true, the generated write routes are OPEN (no auth).
+     *   Default (false) keeps them secure-by-default, matching the framework's write gate.
+     */
+    static register(model: DiscoveredModel, prefix?: string, options?: AutoCrudOptions): void;
+    /**
+     * 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, options?: AutoCrudOptions): string[];
+    /**
+     * Return all registered models.
+     */
+    static models(): Map<string, DiscoveredModel>;
+    /**
+     * Clear all registered models (useful for testing).
+     */
+    static clear(): void;
+    /**
+     * Generate route definitions for all registered models, honouring each
+     * model's per-table `public` flag (set at register/discover time).
+     */
+    static generateRoutes(): RouteDefinition[];
+}
+/**
+ * Filter discovered models down to those that explicitly opted into auto-CRUD via
+ * `static autoCrud = true` (the documented opt-in gate; default false). The server
+ * passes only these to generateCrudRoutes, so a model without the flag gets no CRUD
+ * endpoints. Exported so the opt-in gate is locked in by a test rather than
+ * re-implemented at each call site.
+ */
+export declare function crudEligibleModels(models: DiscoveredModel[]): DiscoveredModel[];
+/**
+ * Generate CRUD route definitions for the given models.
+ * (Standalone function for backward compatibility.)
+ *
+ * @param options.public When true, the generated write routes (POST/PUT/DELETE)
+ *   opt OUT of the router's secure-by-default write gate (`secure: false`) — the
+ *   cross-backend escape hatch (parity with python `public=True` / php `$public`).
+ *   Default (false) leaves `secure` unset so the router gates writes (secure:true).
+ *   GET routes are unaffected (reads are already public).
+ */
+export declare function generateCrudRoutes(models: DiscoveredModel[], options?: AutoCrudOptions): RouteDefinition[];