tina4-nodejs 3.13.92 → 3.13.95

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

@@ -0,0 +1,275 @@
+import type { DatabaseAdapter } from "./types.js";
+import type { DiscoveredModel } from "./model.js";
+/**
+ * Make CREATE TABLE idempotent on engines lacking IF NOT EXISTS.
+ *
+ * Firebird and MSSQL do not support `CREATE TABLE IF NOT EXISTS`, so a raw
+ * CREATE in a re-run migration raises "object already exists". When the target
+ * table already exists on those engines, return a skip reason so the statement
+ * is skipped (mirrors the Firebird ALTER-TABLE-ADD idempotency guard).
+ * SQLite/MySQL/PostgreSQL support IF NOT EXISTS and are left to the engine.
+ * Only a genuine already-exists is skipped — every other error still raises.
+ */
+export declare function shouldSkipCreateTable(db: DatabaseAdapter, stmt: string): Promise<string | null>;
+/**
+ * Sync model definitions to the database (create tables, add columns).
+ */
+export declare function syncModels(models: DiscoveredModel[]): Promise<void>;
+/**
+ * Ensure the migration tracking table exists in the canonical shape (creating
+ * it or upgrading an older one in place) on the global adapter.
+ */
+export declare function ensureMigrationTable(): Promise<void>;
+/**
+ * Get the current batch number (max batch + 1).
+ */
+export declare function getNextBatch(): Promise<number>;
+/**
+ * Check if a migration has already been applied (a row with passed = 1).
+ */
+export declare function isMigrationApplied(name: string): Promise<boolean>;
+/**
+ * Record a migration as applied (public API). Routes through recordApplied() so
+ * a leftover passed=0 row for the same migration_name is deleted before the
+ * fresh row is written (at most one row per migration_name).
+ */
+export declare function recordMigration(name: string, batch: number, passed?: number): Promise<void>;
+/**
+ * Apply a migration (run its up function and record it).
+ */
+export declare function applyMigration(name: string, up: () => void | Promise<void>, batch: number): Promise<void>;
+/**
+ * Get all migrations from the last batch.
+ */
+export declare function getLastBatchMigrations(): Promise<Array<{
+    id: number;
+    migration_name: string;
+    batch: number;
+}>>;
+/**
+ * Remove a migration record (used during rollback).
+ */
+export declare function removeMigrationRecord(name: string): Promise<void>;
+/**
+ * Rollback the last batch of migrations using .down.sql files.
+ *
+ * For each migration in the last batch (in reverse order):
+ * 1. Looks for a corresponding .down.sql file on disk
+ * 2. If found, reads and executes the SQL statements
+ * 3. If not found, logs a warning
+ * 4. Deletes the tracking record either way
+ *
+ * @param migrationsDir - Directory containing migration files (default: "migrations")
+ * @param delimiter - SQL statement delimiter (default: ";")
+ * @returns Array of the down-migration files that were run, e.g.
+ *   "000001_create_users.down.sql". (The legacy down-FUNCTION Map API returns the
+ *   bare migration name instead, since no .down.sql file is involved there.)
+ *
+ * NOTE on return form (intentional, cross-framework): migration return values reflect
+ * WHAT each method acted on, so the forms differ by method and that is by design (not
+ * unified). migrate()/getApplied()/getPending() return the up-migration filename
+ * ("name.sql"); rollback() returns the DOWN-migration filename it executed
+ * ("name.down.sql") — matching the Python master. So a caller diffing rollback()
+ * against getApplied() compares ".down.sql" vs ".sql": strip the suffixes (or compare
+ * the bare "name" stem) to relate them.
+ */
+export declare function rollback(migrationsDir?: string | Map<string, () => void | Promise<void>>, delimiter?: string): Promise<string[]>;
+/**
+ * Get all applied migrations.
+ */
+export declare function getAppliedMigrations(): Promise<Array<{
+    id: number;
+    migration_name: string;
+    description: string;
+    batch: number;
+    executed_at: string;
+    passed: number;
+}>>;
+/**
+ * Result returned by the `migrate()` function.
+ */
+export interface MigrationResult {
+    /** Filenames of successfully applied migrations. */
+    applied: string[];
+    /** Filenames that were already applied (skipped). */
+    skipped: string[];
+    /** Filenames that failed with error details. */
+    failed: string[];
+}
+/**
+ * Result returned by the `status()` function.
+ */
+export interface MigrationStatus {
+    /** Filenames of completed (already applied) migrations. */
+    completed: string[];
+    /** Filenames of pending (not yet applied) migrations. */
+    pending: string[];
+}
+/**
+ * Replace smart/curly quotes with straight ASCII quotes so migration SQL
+ * authored or pasted from an editor/doc actually runs (those code points are
+ * not valid SQL delimiters). Already-straight quotes and ordinary string
+ * content are returned byte-for-byte unchanged.
+ */
+export declare function normalizeQuotes(sql: string): string;
+/**
+ * Return the new terminator from a `SET TERM <new> <current>` directive.
+ *
+ * `SET TERM` is a script-level directive (recognised by isql and other
+ * InterBase/Firebird tooling, not run by the engine) that changes the
+ * terminator separating statements. Recognising it lets a statement whose own
+ * body contains the default `;` terminator — a trigger, stored procedure or
+ * `EXECUTE BLOCK` — be kept intact rather than split on those inner `;`. The
+ * terminator may be more than one character (e.g. `!!`).
+ *
+ * @param statement A single, already-trimmed statement.
+ * @returns The new terminator, or `null` when `statement` is not a `SET TERM`
+ *          directive.
+ */
+export declare function parseSetTerm(statement: string): string | null;
+/**
+ * Split SQL text into individual statements with a single-pass, quote- and
+ * comment-aware scanner. The split decision is made character by character so
+ * the delimiter only ever fires in real statement position.
+ *
+ * This is the fix for issue #54: the old implementation split on `delimiter`
+ * BEFORE stripping `-- …` line comments, so a `;` inside a line comment
+ * fragmented one statement into several broken pieces. A scanner that knows
+ * where it is (code / comment / string) cannot make that mistake.
+ *
+ * Handled, in priority order, only when NOT already inside a stored-proc block:
+ * - `$$ … $$` and `// … //` stored-proc blocks are kept intact (inner `;` never
+ *   splits). A `//` preceded by `:` is a URL scheme (`https://…`), not a delimiter.
+ * - `/* … *​/` block comments are stripped.
+ * - `-- …` line comments are stripped to end of line (the newline is kept).
+ * - `'…'` single-quoted strings and `"…"` double-quoted identifiers are copied
+ *   verbatim, honouring the SQL doubled-quote escape (`''` / `""`); a `;`, `--`
+ *   or `/*` inside a literal is data, not a delimiter or comment.
+ * - A `SET TERM <new> <current>` directive switches the active terminator and is
+ *   consumed (never emitted), so a statement whose own body contains the default
+ *   terminator — a Firebird trigger, stored procedure or `EXECUTE BLOCK` —
+ *   survives as one. Multi-character terminators (e.g. `!!`) are supported.
+ * Mirrors the tina4-python `_split_statements` / tina4-php / tina4-ruby scanner (parity).
+ */
+export declare function splitStatements(sql: string, delimiter?: string): string[];
+/**
+ * Sort migration filenames supporting both naming patterns:
+ * - Sequential: 000001_name.sql, 000002_name.sql
+ * - Timestamp: 20240315120000_name.sql (YYYYMMDDHHMMSS)
+ *
+ * Numeric-aware: a file with a leading numeric/timestamp prefix sorts first by
+ * that number (so `9_*` applies before `10_*` — a plain lexical sort misorders
+ * unpadded prefixes because "10" < "9"). Files with NO numeric prefix sort
+ * AFTER the numbered ones, then lexically. Mirrors Python's `_migration_sort_key`.
+ */
+export declare function sortMigrationFiles(files: string[]): string[];
+/**
+ * Run all pending SQL-file migrations.
+ *
+ * Supports both naming patterns:
+ * - Sequential: 000001_description.sql
+ * - Timestamp: YYYYMMDDHHMMSS_description.sql
+ *
+ * 1. Creates the `tina4_migration` tracking table if it doesn't exist.
+ * 2. Scans `migrationsDir` for `.sql` files (excluding `.down.sql`), sorted.
+ * 3. Skips files already recorded as applied.
+ * 4. Splits file content on `delimiter` and executes each statement.
+ * 5. On success records the migration with the current batch number.
+ * 6. On error logs and continues.
+ * 7. Returns a summary of applied / skipped / failed files.
+ *
+ * @param adapter - A DatabaseAdapter instance (or omit to use the global adapter).
+ * @param options - Optional configuration.
+ */
+export declare function migrate(adapter?: DatabaseAdapter, options?: {
+    migrationsDir?: string;
+    delimiter?: string;
+}): Promise<MigrationResult>;
+/**
+ * Get migration status: which migrations are completed and which are pending.
+ *
+ * @param adapter - A DatabaseAdapter instance (or omit to use the global adapter).
+ * @param options - Optional configuration.
+ * @returns Object with `completed` and `pending` arrays of filenames.
+ */
+export declare function status(adapter?: DatabaseAdapter, options?: {
+    migrationsDir?: string;
+}): Promise<MigrationStatus>;
+/**
+ * Create a new empty SQL migration file with a timestamp prefix.
+ *
+ * Creates BOTH the up migration (.sql) and the down migration (.down.sql).
+ *
+ * @param description - Human-readable description (used in filename).
+ * @param options - Optional configuration.
+ * @returns Object with paths to the created up and down files.
+ */
+export declare function createMigration(description: string, options?: {
+    migrationsDir?: string;
+    kind?: "sql" | "class";
+}): Promise<string | {
+    upPath: string;
+    downPath: string;
+}>;
+/**
+ * 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 declare function createClassMigration(description: string, options?: {
+    migrationsDir?: string;
+}): Promise<string>;
+/**
+ * Object-oriented Migration class — canonical Tina4 Migration API.
+ *
+ * Provides parity with Python, PHP, and Ruby:
+ *   - migrate()           Run all pending migrations
+ *   - rollback(steps=1)   Roll back last N batches
+ *   - status()            Show completed/pending
+ *   - create(description) Scaffold new .sql + .down.sql files
+ *   - getApplied()        List applied migrations
+ *   - getPending()        List pending migration filenames
+ *   - getFiles()          List all migration files on disk
+ *
+ * @example
+ *   const m = new Migration(db, { migrationsDir: "migrations" });
+ *   await m.migrate();
+ *   await m.rollback(2);
+ *   await m.status();
+ *   await m.create("add users table");
+ */
+export declare class Migration {
+    private db?;
+    private dir;
+    private delimiter;
+    constructor(db?: DatabaseAdapter, options?: {
+        migrationsDir?: string;
+        delimiter?: string;
+    });
+    /** Run all pending migrations. Returns applied/skipped/failed summary. */
+    migrate(): Promise<MigrationResult>;
+    /** Roll back the last N batches. Returns list of rolled-back migration names. */
+    rollback(steps?: number): Promise<string[]>;
+    /** Get migration status: which are completed and which are pending. */
+    status(): Promise<MigrationStatus>;
+    /**
+     * 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).
+     */
+    create(description: string, kind?: "sql" | "class"): Promise<string | {
+        upPath: string;
+        downPath: string;
+    }>;
+    /** Return list of completed (applied) migration filenames. */
+    getApplied(): Promise<string[]>;
+    /** Return list of pending migration filenames. */
+    getPending(): Promise<string[]>;
+    /** Return sorted list of all migration files on disk (excludes .down.sql). */
+    getFiles(): string[];
+}

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

@@ -0,0 +1,7 @@
+import type { ModelDefinition } from "./types.js";
+export interface DiscoveredModel {
+    definition: ModelDefinition;
+    filePath: string;
+    modelClass: any;
+}
+export declare function discoverModels(modelsDir: string): Promise<DiscoveredModel[]>;

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

@@ -0,0 +1,14 @@
+import type { QueryOptions } from "./types.js";
+export interface ParsedQuery {
+    where: string;
+    orderBy: string;
+    limit: number;
+    offset: number;
+    params: unknown[];
+}
+export declare function buildQuery(tableName: string, options: QueryOptions, extraConditions?: string[]): {
+    sql: string;
+    countSql: string;
+    params: unknown[];
+};
+export declare function parseQueryString(query: Record<string, string>): QueryOptions;

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

@@ -0,0 +1,193 @@
+/**
+ * QueryBuilder — Fluent SQL query builder for Tina4 Node.js.
+ *
+ * Usage:
+ *   // Standalone
+ *   const result = QueryBuilder.fromTable("users", db)
+ *     .select("id", "name")
+ *     .where("active = ?", [1])
+ *     .orderBy("name ASC")
+ *     .limit(10)
+ *     .get();
+ *
+ *   // From ORM model
+ *   const result = User.query()
+ *     .where("age > ?", [18])
+ *     .orderBy("name")
+ *     .get();
+ */
+import type { DatabaseAdapter } from "./types.js";
+import { DatabaseResult } from "./databaseResult.js";
+export declare class QueryBuilder {
+    private table;
+    private db;
+    private columns;
+    private wheres;
+    private params;
+    private joinClauses;
+    private groupByCols;
+    private havings;
+    private havingParams;
+    private orderByCols;
+    private limitVal;
+    private offsetVal;
+    /**
+     * Private constructor — use static factory methods.
+     */
+    private constructor();
+    /**
+     * Create a QueryBuilder for a table.
+     *
+     * @param tableName - Table name.
+     * @param db - Optional database adapter.
+     * @returns A new QueryBuilder instance.
+     */
+    static fromTable(tableName: string, db?: DatabaseAdapter): QueryBuilder;
+    /**
+     * Set the columns to select.
+     *
+     * @param cols - Column names.
+     * @returns this for chaining.
+     */
+    select(...cols: string[]): QueryBuilder;
+    /**
+     * Add a WHERE condition (AND).
+     *
+     * @param condition - SQL condition with ? placeholders.
+     * @param params - Parameter values.
+     * @returns this for chaining.
+     */
+    where(condition: string, params?: unknown[]): QueryBuilder;
+    /**
+     * Add a WHERE condition (OR).
+     *
+     * @param condition - SQL condition with ? placeholders.
+     * @param params - Parameter values.
+     * @returns this for chaining.
+     */
+    orWhere(condition: string, params?: unknown[]): QueryBuilder;
+    /**
+     * Add an INNER JOIN.
+     *
+     * @param table - Table to join.
+     * @param onClause - Join condition.
+     * @returns this for chaining.
+     */
+    join(table: string, onClause: string): QueryBuilder;
+    /**
+     * Add a LEFT JOIN.
+     *
+     * @param table - Table to join.
+     * @param onClause - Join condition.
+     * @returns this for chaining.
+     */
+    leftJoin(table: string, onClause: string): QueryBuilder;
+    /**
+     * Add a GROUP BY column.
+     *
+     * @param column - Column name.
+     * @returns this for chaining.
+     */
+    groupBy(column: string): QueryBuilder;
+    /**
+     * Add a HAVING clause.
+     *
+     * @param expression - HAVING expression with ? placeholders.
+     * @param params - Parameter values.
+     * @returns this for chaining.
+     */
+    having(expression: string, params?: unknown[]): QueryBuilder;
+    /**
+     * Add an ORDER BY clause.
+     *
+     * @param expression - Column and direction (e.g. "name ASC").
+     * @returns this for chaining.
+     */
+    orderBy(expression: string): QueryBuilder;
+    /**
+     * Set LIMIT and optional OFFSET.
+     *
+     * @param count - Maximum rows to return.
+     * @param offset - Number of rows to skip.
+     * @returns this for chaining.
+     */
+    limit(count: number, offset?: number): QueryBuilder;
+    /**
+     * Build and return the SQL string without executing.
+     *
+     * @returns The constructed SQL query.
+     */
+    toSql(): string;
+    /**
+     * Execute the query and return a DatabaseResult.
+     *
+     * BREAKING (3.13.95, parity): this returned a bare array of rows. The other
+     * three frameworks all return the DatabaseResult that `db.fetch()` produces:
+     *   Python  get() -> DatabaseResult   (orm/query_builder/__init__.py)
+     *   PHP     get(): mixed -> $this->db->fetch(...)
+     *   Ruby    get -> @db.fetch(...)
+     * Node was the odd one out, so the same builder chain returned a different
+     * TYPE per language and portable code could not read `.records`, `.count`,
+     * `.limit` or `.offset` off it.
+     *
+     * MIGRATION: read `.records` for the rows.
+     *   before: const rows = await qb.get();          rows.length
+     *   after:  const result = await qb.get();        result.records.length
+     * DatabaseResult is iterable, so `for (const row of result)` and
+     * `[...result]` work unchanged, and `response()`/`res.json()` already
+     * auto-serialize it to a JSON array.
+     *
+     * No default LIMIT is applied when `.limit()` was never called (v3.13.39) --
+     * a silent cap here was a data-loss-on-read footgun. That is unchanged.
+     *
+     * @returns DatabaseResult carrying `.records`, `.count`, `.limit`, `.offset`.
+     */
+    get(): Promise<DatabaseResult>;
+    /**
+     * Execute the query and return a single row.
+     *
+     * @returns A single row object, or null.
+     */
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    /**
+     * Execute the query and return the row count.
+     *
+     * @returns Number of matching rows.
+     */
+    count(): Promise<number>;
+    /**
+     * Check whether any matching rows exist.
+     *
+     * @returns True if at least one row matches.
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Convert the fluent builder state into a MongoDB-compatible query document.
+     *
+     * @returns An object with filter, projection, sort, limit, skip (only non-empty keys).
+     */
+    toMongo(): {
+        filter?: Record<string, unknown>;
+        projection?: Record<string, number>;
+        sort?: Record<string, 1 | -1>;
+        limit?: number;
+        skip?: number;
+    };
+    /**
+     * Parse a single SQL condition string into a MongoDB filter object.
+     */
+    private parseConditionToMongo;
+    /**
+     * Merge multiple single-field mongo condition objects into one.
+     * Uses $and if field keys conflict.
+     */
+    private mergeMongoConditions;
+    /**
+     * Build the WHERE clause from accumulated conditions.
+     */
+    private buildWhere;
+    /**
+     * Ensure a database adapter is available.
+     */
+    private ensureDb;
+}

package/types/orm/src/realtime/index.d.ts

@@ -0,0 +1,7 @@
+export { realtime, iceServers, type RealtimeOptions } from "./realtime.js";
+export { LocalStorage, S3Storage, selectStorage, storageKey, type StorageBackend, } from "./storage.js";
+export { default as Workspace } from "./models/workspace.js";
+export { default as Channel } from "./models/channel.js";
+export { default as ChannelMember } from "./models/channelMember.js";
+export { default as Message } from "./models/message.js";
+export { default as Attachment } from "./models/attachment.js";

package/types/orm/src/realtime/models/attachment.d.ts

@@ -0,0 +1,43 @@
+import { BaseModel } from "../../baseModel.js";
+/**
+ * Attachment - a file linked to a channel (and optionally a message).
+ * channel_id scopes the file for permission checks; message_id is null until
+ * the file is attached to a posted message. storage_key is the StorageBackend
+ * key; the row carries only metadata, never the blob.
+ */
+export default class Attachment extends BaseModel {
+    static tableName: string;
+    static fields: {
+        id: {
+            type: "integer";
+            primaryKey: boolean;
+            autoIncrement: boolean;
+        };
+        channel_id: {
+            type: "integer";
+        };
+        message_id: {
+            type: "integer";
+        };
+        storage_key: {
+            type: "string";
+            required: boolean;
+            maxLength: number;
+        };
+        filename: {
+            type: "string";
+            maxLength: number;
+        };
+        mime: {
+            type: "string";
+            maxLength: number;
+        };
+        size: {
+            type: "integer";
+        };
+        thumb_key: {
+            type: "string";
+            maxLength: number;
+        };
+    };
+}

package/types/orm/src/realtime/models/channel.d.ts

@@ -0,0 +1,32 @@
+import { BaseModel } from "../../baseModel.js";
+/**
+ * Channel - a conversation stream inside a workspace.
+ * kind is one of public | private | dm. workspace_id is a plain integer FK
+ * column (the realtime handlers query it directly).
+ */
+export default class Channel extends BaseModel {
+    static tableName: string;
+    static fields: {
+        id: {
+            type: "integer";
+            primaryKey: boolean;
+            autoIncrement: boolean;
+        };
+        workspace_id: {
+            type: "integer";
+        };
+        name: {
+            type: "string";
+            required: boolean;
+            maxLength: number;
+        };
+        kind: {
+            type: "string";
+            default: string;
+            maxLength: number;
+        };
+        created_at: {
+            type: "datetime";
+        };
+    };
+}

package/types/orm/src/realtime/models/channelMember.d.ts

@@ -0,0 +1,32 @@
+import { BaseModel } from "../../baseModel.js";
+/**
+ * ChannelMember - a user's membership of a channel plus their read cursor.
+ * user_id is a string so it holds any identity shape the app puts in the JWT
+ * (an integer id, a UUID, an email). last_read_at is the read-receipt cursor.
+ */
+export default class ChannelMember extends BaseModel {
+    static tableName: string;
+    static fields: {
+        id: {
+            type: "integer";
+            primaryKey: boolean;
+            autoIncrement: boolean;
+        };
+        channel_id: {
+            type: "integer";
+        };
+        user_id: {
+            type: "string";
+            required: boolean;
+            maxLength: number;
+        };
+        role: {
+            type: "string";
+            default: string;
+            maxLength: number;
+        };
+        last_read_at: {
+            type: "datetime";
+        };
+    };
+}

package/types/orm/src/realtime/models/message.d.ts

@@ -0,0 +1,36 @@
+import { BaseModel } from "../../baseModel.js";
+/**
+ * Message - one posted message in a channel.
+ * thread_id is null for a top-level message, or the id of the parent message
+ * for a threaded reply. edited_at is null until an edit.
+ */
+export default class Message extends BaseModel {
+    static tableName: string;
+    static fields: {
+        id: {
+            type: "integer";
+            primaryKey: boolean;
+            autoIncrement: boolean;
+        };
+        channel_id: {
+            type: "integer";
+        };
+        user_id: {
+            type: "string";
+            required: boolean;
+            maxLength: number;
+        };
+        body: {
+            type: "text";
+        };
+        thread_id: {
+            type: "integer";
+        };
+        created_at: {
+            type: "datetime";
+        };
+        edited_at: {
+            type: "datetime";
+        };
+    };
+}

package/types/orm/src/realtime/models/workspace.d.ts

@@ -0,0 +1,26 @@
+import { BaseModel } from "../../baseModel.js";
+/**
+ * Workspace - the top-level container for channels (a "team" / "org").
+ * Framework-owned table: the tina4_rt_ prefix keeps it clear of an app's own
+ * domain tables (mirrors tina4_migration / tina4_sequences + the Python
+ * master's tina4_rt_* tables). Field keys are snake_case so the columns and
+ * JSON keys stay byte-identical to the master (no camelCase mapping needed).
+ */
+export default class Workspace extends BaseModel {
+    static tableName: string;
+    static fields: {
+        id: {
+            type: "integer";
+            primaryKey: boolean;
+            autoIncrement: boolean;
+        };
+        name: {
+            type: "string";
+            required: boolean;
+            maxLength: number;
+        };
+        created_at: {
+            type: "datetime";
+        };
+    };
+}