tina4-nodejs 3.13.92 → 3.13.94

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

@@ -0,0 +1,173 @@
+/**
+ * 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";
+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 all matching rows.
+     *
+     * @returns Array of row objects.
+     */
+    get<T = Record<string, unknown>>(): Promise<T[]>;
+    /**
+     * 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";
+        };
+    };
+}

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

@@ -0,0 +1,24 @@
+import { type StorageBackend } from "./storage.js";
+export interface RealtimeOptions {
+    prefix?: string;
+    authorize?: (identity: string, channelId: number) => boolean | Promise<boolean>;
+    storage?: StorageBackend;
+    features?: string[];
+}
+interface IceServer {
+    urls: string[];
+    username?: string;
+    credential?: string;
+}
+/** Build the ICE server list from the environment (STUN always; ephemeral TURN when configured). */
+export declare function iceServers(): IceServer[];
+/**
+ * Mount the realtime surface and return the resolved path map (also served
+ * from the config endpoint so the client can discover it).
+ *
+ * Returns a Promise because the framework-owned chat tables are created via the
+ * async ORM (Node's DB layer is async) - `await realtime(...)` so the tables
+ * exist before the first request. Route registration itself is synchronous.
+ */
+export declare function realtime(options?: RealtimeOptions): Promise<Record<string, string>>;
+export {};

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

@@ -0,0 +1,61 @@
+/**
+ * Pluggable file storage for the realtime "files" feature. StorageBackend is
+ * the interface; LocalStorage (default, zero-dependency, filesystem) and
+ * S3Storage (opt-in, S3-compatible via @aws-sdk/client-s3) are the shipped
+ * implementations. Selection mirrors the cache/session/queue backend pattern:
+ * TINA4_STORAGE_BACKEND (local default | s3) plus per-backend env vars, with a
+ * graceful fallback to local if an s3 backend cannot be constructed - a real
+ * persistent store, never a silent no-op. Parity with Python's storage.py.
+ */
+export interface StorageBackend {
+    put(key: string, data: Buffer | string, mime?: string): void | Promise<void>;
+    get(key: string): Buffer | null | Promise<Buffer | null>;
+    /** A directly-fetchable URL when the backend supports one, else null. */
+    url(key: string, ttl?: number): string | null | Promise<string | null>;
+    delete(key: string): void | Promise<void>;
+    exists(key: string): boolean | Promise<boolean>;
+}
+/**
+ * Generate an opaque, collision-free storage key, preserving the extension.
+ * The key carries no user-controlled path segment, so it can never traverse
+ * outside the storage root.
+ */
+export declare function storageKey(filename?: string): string;
+/** Zero-dependency filesystem store. The default backend. */
+export declare class LocalStorage implements StorageBackend {
+    private directory;
+    constructor(directory?: string);
+    private pathFor;
+    put(key: string, data: Buffer | string): void;
+    get(key: string): Buffer | null;
+    url(): string | null;
+    delete(key: string): void;
+    exists(key: string): boolean;
+}
+/**
+ * S3-compatible store (AWS S3, MinIO, ...). Opt-in; needs @aws-sdk/client-s3.
+ * Presigned GET URLs let clients fetch large blobs straight from object
+ * storage instead of streaming through the app.
+ */
+export declare class S3Storage implements StorageBackend {
+    private client;
+    private bucket;
+    constructor(opts?: {
+        endpoint?: string;
+        key?: string;
+        secret?: string;
+        bucket?: string;
+        region?: string;
+    });
+    put(key: string, data: Buffer | string, mime?: string): Promise<void>;
+    get(key: string): Promise<Buffer | null>;
+    url(key: string, ttl?: number): Promise<string | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+/**
+ * Resolve the storage backend from an explicit instance or the environment.
+ * Falls back to LocalStorage (logging why) when an s3 backend cannot be built
+ * (driver missing or config incomplete) - a real store, never a silent no-op.
+ */
+export declare function selectStorage(storage?: StorageBackend): StorageBackend;

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

@@ -0,0 +1,118 @@
+import { FakeData } from "./fakeData.js";
+import type { DatabaseAdapter, FieldDefinition } from "./types.js";
+/**
+ * Result of a seed run — `{ seeded, failed, errors }`.
+ *
+ * `errors` is a list of `{ row, message }` describing every skipped row
+ * (`row` is the 0-based index). Mirrors the Python `SeedSummary`; Node tests
+ * compare `.seeded` / `.failed` rather than the bare integer.
+ */
+export interface SeedSummary {
+    seeded: number;
+    failed: number;
+    errors: Array<{
+        row: number;
+        message: string;
+    }>;
+}
+/** Options shared by seedTable / seedOrm / seedModels. */
+export interface SeedOptions {
+    /** Static values applied to every row (overrides generated values). */
+    overrides?: Record<string, unknown>;
+    /** Delete every existing row in the target before seeding (P2). */
+    clear?: boolean;
+    /** PRNG seed for reproducible FakeData output (P3). */
+    seed?: number;
+    /** Re-raise on the first failed row instead of skipping it (P1). */
+    strict?: boolean;
+}
+/**
+ * Introspect `table`'s columns and build a column->generator field map for
+ * {@link seedTable}, skipping the auto-increment / `id` primary key (the engine
+ * assigns it). Mirrors the Python master's `auto_field_map`
+ * (tina4_python/seeder/__init__.py): the shared "seed a table I did not
+ * hand-write generators for" helper that both the dev-admin seed endpoint and
+ * the MCP `seed_table` dev tool use — `seedTable` itself stays explicit
+ * (no map = no rows), and this is how a caller opts into automatic generation.
+ *
+ * Reuses `FakeData.forField()` (column-name + type heuristics) so the generated
+ * data matches every other Tina4 seeding path. Returns an empty map when the
+ * table has no seedable columns, so `seedTable` then seeds nothing rather than
+ * crashing.
+ *
+ * @param db - A DatabaseAdapter instance (pass `getAdapter()`, NOT the Database
+ *             wrapper — the wrapper has no `columns()`).
+ * @param table - The table to introspect.
+ * @param fake - Optional shared FakeData (pass one seeded via `new FakeData(n)`
+ *               for reproducible output).
+ * @returns `{ column -> () => value }`, ready to hand to `seedTable`.
+ */
+export declare function autoFieldMap(db: DatabaseAdapter, table: string, fake?: FakeData): Promise<Record<string, () => unknown>>;
+/**
+ * Seed a database table with fake data using raw SQL inserts.
+ *
+ * Visible-but-resilient (P1): each row is wrapped. On a row failure the cause
+ * is logged (with the row index) and the row is skipped — unless `strict: true`,
+ * in which case the first failure RE-RAISES. At the end a one-line summary is
+ * logged ("seeded N, M failed").
+ *
+ * @param db - A DatabaseAdapter instance
+ * @param tableName - The table to insert into
+ * @param count - Number of rows to insert (default 10)
+ * @param fieldMap - Dict of column_name -> callable that generates a value
+ *                   (or a static value). If not provided, no rows are inserted.
+ * @param overrides - (legacy positional) Static values applied to every row.
+ *                   Prefer `opts.overrides`.
+ * @param opts - Seed options: `{ overrides, clear, seed, strict }`.
+ * @returns A SeedSummary `{ seeded, failed, errors }`.
+ *
+ * @example
+ *   const fake = new FakeData();
+ *   await seedTable(db, "users", 50, {
+ *     name: () => fake.name(),
+ *     email: () => fake.email(),
+ *   }, undefined, { clear: true });
+ */
+export declare function seedTable(db: DatabaseAdapter, tableName: string, count?: number, fieldMap?: Record<string, (() => unknown) | unknown>, overrides?: Record<string, unknown>, opts?: SeedOptions): Promise<SeedSummary>;
+/** A model-like shape the seeder can drive (real BaseModel subclass or mock). */
+interface SeedableModel {
+    tableName: string;
+    fields: Record<string, FieldDefinition>;
+    _db?: string;
+    getDb?: () => DatabaseAdapter;
+    name?: string;
+}
+/**
+ * Seed an ORM model class with auto-generated fake data, based on field
+ * definitions. Visible-but-resilient (P1): each row is wrapped, failures are
+ * logged + counted + skipped (or re-raised under `strict`).
+ *
+ * @param ormClass - A model with static `tableName`, `fields`, and optionally
+ *   `getDb`/`_db`.
+ * @param count - Number of rows to insert (default 10)
+ * @param overrides - (legacy positional) Static field overrides.
+ * @param seed - (legacy positional) PRNG seed for deterministic output.
+ * @param opts - Seed options `{ overrides, clear, seed, strict }`. Options
+ *   supersede the legacy positional args when both are supplied.
+ * @param fkPools - (internal) pre-resolved FK value pools from seedModels.
+ * @returns A SeedSummary `{ seeded, failed, errors }`.
+ */
+export declare function seedOrm(ormClass: SeedableModel, count?: number, overrides?: Record<string, unknown>, seed?: number, opts?: SeedOptions, fkPools?: Record<string, unknown[]>): Promise<SeedSummary>;
+/**
+ * Batch-seed several ORM models, ordering by their foreignKey dependency graph
+ * (P4a). Parent tables seed before children (topological sort); when
+ * `clear: true` the clear runs in REVERSE order so children are removed before
+ * parents — no FK violations regardless of the order the caller lists models.
+ * FK columns are resolved to real parent PKs so child rows reference an
+ * existing parent. Mirrors Python `seed_models`.
+ *
+ * @param ormClasses - List of model classes to seed.
+ * @param count - Rows per model (default 10).
+ * @param opts - Seed options. `overrides` may be a flat dict applied to every
+ *   model, or a Map/record keyed by model to apply per-model overrides.
+ * @returns `{ [modelName]: SeedSummary }` for each model seeded.
+ */
+export declare function seedModels(ormClasses: SeedableModel[], count?: number, opts?: SeedOptions & {
+    overrides?: Record<string, unknown> | Map<SeedableModel, Record<string, unknown>>;
+}): Promise<Record<string, SeedSummary>>;
+export {};