tina4-nodejs 3.13.92 → 3.13.94

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

@@ -0,0 +1,85 @@
+import type { DatabaseAdapter } 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 declare 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?;
+    private readonly _sql?;
+    private _columnInfoCache?;
+    [index: number]: Record<string, unknown> | undefined;
+    constructor(records?: Record<string, unknown>[], columns?: string[], count?: number, limit?: number, offset?: number, adapter?: DatabaseAdapter, sql?: string);
+    /** JSON string of records. */
+    toJson(): string;
+    /** CSV with header row. */
+    toCsv(): string;
+    /** Same as records — plain array of row objects. */
+    toArray(): Record<string, unknown>[];
+    /** Pagination envelope — accepts either (page, perPage) or (offset, limit) style.
+     *
+     * When called with two arguments both >= 0 and the first >= the second
+     * (i.e. offset-style), pass `{ offset, limit }` as the first argument.
+     * The simplest way is to always use the default (page, perPage) form and
+     * let the autoCRUD layer supply offset/limit from the query string.
+     *
+     * Returns a superset of keys for backwards-compatibility across all clients.
+     */
+    toPaginate(page?: number, perPage?: number): {
+        records: Record<string, unknown>[];
+        data: Record<string, unknown>[];
+        count: number;
+        total: number;
+        limit: number;
+        offset: number;
+        page: number;
+        per_page: number;
+        perPage: number;
+        totalPages: number;
+        total_pages: number;
+        has_next: boolean;
+        has_prev: boolean;
+    };
+    /** Iterable — for (const row of result) */
+    [Symbol.iterator](): Iterator<Record<string, unknown>>;
+    /** Total count — cross-framework parity with Python/Ruby. */
+    size(): number;
+    /** Number of records in this page. */
+    get length(): number;
+    /** Array-like indexed access with negative index support. */
+    at(index: number): Record<string, unknown> | undefined;
+    /** JSON.stringify support — serialises as the records array. */
+    toJSON(): Record<string, unknown>[];
+    /**
+     * 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[];
+    /** Extract table name from a SQL query using simple regex. */
+    private _extractTableFromSql;
+    /** Query the database adapter for column metadata. */
+    private _queryColumnMetadata;
+    /** Normalize adapter column info to standard format. */
+    private _normalizeColumns;
+    /** Parse size and decimals from a type string like VARCHAR(255) or NUMERIC(10,2). */
+    private _parseTypeSize;
+    /** Derive basic column info from record keys when no adapter is available. */
+    private _fallbackColumnInfo;
+}

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

@@ -0,0 +1,182 @@
+/**
+ * Tina4 DocStore - pymongo-style document storage with a zero-config SQLite (JSON1) fallback.
+ *
+ * A document store with the everyday MongoDB driver collection API, backed by
+ * SQLite's JSON1 extension when no MongoDB server is configured.
+ *
+ *     import { getCollection, ObjectId } from "@tina4/orm";
+ *
+ *     const orders = getCollection("orders");          // SqliteCollection when no Mongo configured
+ *     const { insertedId } = await orders.insertOne({ customer_id: 1, total: 9.99 });
+ *     for (const o of await orders.find({ customer_id: { $in: [1, 2] } }).sort("created_at", -1).limit(10).toArray()) {
+ *       // ...
+ *     }
+ *     await orders.updateOne({ _id: insertedId }, { $set: { status: "shipped" } });
+ *
+ * `getCollection(name)` returns a real MongoDB driver `Collection` when a Mongo
+ * URI is configured (TINA4_MONGO_URI, else TINA4_SESSION_MONGO_URI - the same
+ * names the queue/session Mongo backends read), and otherwise a SqliteCollection
+ * backed by a local SQLite file. This mirrors the file-based fallbacks the queue,
+ * cache, and session subsystems already provide: an app that talks to Mongo in
+ * production runs serverless in local dev with no code change - only the backend
+ * differs.
+ *
+ * Design (the SQLite backend):
+ *   - Each collection is a table `(_id TEXT PRIMARY KEY, doc TEXT)`; `doc` is JSON.
+ *   - Query filters are pushed down to SQL over `json_extract(doc, '$.field')`
+ *     (lazy, not a full in-memory scan), supporting equality, $in/$nin,
+ *     $gt/$gte/$lt/$lte, $ne, $exists, $regex, and implicit-AND / $or / $and.
+ *   - Updates: $set, $unset, $inc, and full-document replace.
+ *   - Cursors: sort / limit / skip / projection.
+ *   - IDs are a built-in 12-byte ObjectId (zero-dependency; interchangeable with
+ *     the driver's ObjectId as a 24-hex string).
+ *
+ * Type round-trip is by value, not by wrapper object, so json_extract stays
+ * queryable and sortable: a Date is stored as an ISO-8601 UTC string and an
+ * ObjectId as its 24-hex string, and reads rehydrate a strict-ISO string back to
+ * a Date and a 24-hex string back to an ObjectId. That keeps range queries and
+ * sorts working on date and id fields - the trade-off (a plain 24-hex / ISO
+ * string becomes an ObjectId / Date on read) is acceptable for the local dev store.
+ *
+ * Deliberate non-goals: aggregation pipeline, $elemMatch, geo. This is the
+ * everyday CRUD + filter subset, not full Mongo parity.
+ */
+import { DatabaseSync } from "node:sqlite";
+/** Raised when a value cannot be parsed as an ObjectId. */
+export declare class InvalidId extends Error {
+    constructor(message: string);
+}
+/**
+ * A 12-byte MongoDB-style ObjectId, with no external dependency.
+ *
+ * Layout: 4-byte big-endian seconds since epoch, 5-byte per-process random,
+ * 3-byte big-endian counter. Renders as a 24-char hex string, so it is
+ * interchangeable with the driver's ObjectId wherever the string form is used.
+ */
+export declare class ObjectId {
+    private static _counter;
+    private static _process;
+    private readonly _bytes;
+    constructor(oid?: ObjectId | Buffer | Uint8Array | string | null);
+    private static _generate;
+    static isValid(value: unknown): boolean;
+    get binary(): Buffer;
+    /** The timestamp embedded in the id (the first 4 bytes), as a Date. */
+    get generationTime(): Date;
+    toString(): string;
+    toJSON(): string;
+    equals(other: unknown): boolean;
+}
+/** Value -> JSON-serialisable, sortable scalar form (for storage/queries). */
+export declare function encodeValue(value: unknown): unknown;
+/** Stored JSON value -> rich value, rehydrating ObjectId (24-hex) and Date (ISO). */
+export declare function decodeValue(value: unknown): unknown;
+interface CompiledFilter {
+    where: string;
+    params: unknown[];
+}
+/**
+ * Compile a Mongo-style filter object into { where, params }.
+ *
+ * Returns { where: "1=1", params: [] } for an empty filter. Supports implicit
+ * AND across keys, $or / $and, and the per-field operator set.
+ */
+export declare function compileFilter(query?: Record<string, unknown> | null): CompiledFilter;
+export interface InsertOneResult {
+    acknowledged: boolean;
+    insertedId: unknown;
+}
+export interface InsertManyResult {
+    acknowledged: boolean;
+    insertedIds: unknown[];
+}
+export interface UpdateResult {
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedId: unknown | null;
+}
+export interface DeleteResult {
+    acknowledged: boolean;
+    deletedCount: number;
+}
+/** Lazy result cursor. Builds and runs SQL only when materialised (toArray). */
+export declare class Cursor {
+    private readonly collection;
+    private readonly where;
+    private readonly params;
+    private readonly projection?;
+    private _sort;
+    private _limit;
+    private _skip;
+    constructor(collection: SqliteCollection, where: string, params: unknown[], projection?: (Record<string, unknown> | null) | undefined);
+    sort(keyOrList: string | [string, number][], direction?: number): this;
+    limit(n: number): this;
+    skip(n: number): this;
+    private buildSql;
+    /** Materialise the cursor into an array of decoded documents. */
+    toArray(): Record<string, unknown>[];
+    /** Alias for toArray() (pymongo's to_list / driver's toArray). */
+    toList(length?: number): Record<string, unknown>[];
+    [Symbol.iterator](): Iterator<Record<string, unknown>>;
+}
+/** A SQLite-backed collection exposing the everyday MongoDB driver API. */
+export declare class SqliteCollection {
+    readonly connection: DatabaseSync;
+    private readonly name;
+    readonly quoted: string;
+    constructor(connection: DatabaseSync, name: string);
+    private dump;
+    /** Decode a stored JSON document (rehydrating ObjectId/Date), with optional projection. */
+    load(docText: string, projection?: Record<string, unknown> | null): Record<string, unknown>;
+    insertOne(document: Record<string, unknown>): InsertOneResult;
+    insertMany(documents: Record<string, unknown>[]): InsertManyResult;
+    find(filter?: Record<string, unknown> | null, projection?: Record<string, unknown> | null): Cursor;
+    findOne(filter?: Record<string, unknown> | null, projection?: Record<string, unknown> | null): Record<string, unknown> | null;
+    countDocuments(filter?: Record<string, unknown> | null): number;
+    estimatedDocumentCount(): number;
+    distinct(key: string, filter?: Record<string, unknown> | null): unknown[];
+    private matchingRows;
+    private firstMatch;
+    private writeBack;
+    private doUpsert;
+    updateOne(filter: Record<string, unknown> | null | undefined, update: Record<string, unknown>, options?: {
+        upsert?: boolean;
+    }): UpdateResult;
+    updateMany(filter: Record<string, unknown> | null | undefined, update: Record<string, unknown>, options?: {
+        upsert?: boolean;
+    }): UpdateResult;
+    replaceOne(filter: Record<string, unknown> | null | undefined, replacement: Record<string, unknown>, options?: {
+        upsert?: boolean;
+    }): UpdateResult;
+    deleteOne(filter?: Record<string, unknown> | null): DeleteResult;
+    deleteMany(filter?: Record<string, unknown> | null): DeleteResult;
+    drop(): void;
+}
+/** A SQLite-backed document database (a file of collection tables). */
+export declare class SqliteDatabase {
+    readonly path: string;
+    private readonly conn;
+    private readonly collections;
+    constructor(path?: string);
+    getCollection(name: string): SqliteCollection;
+    listCollectionNames(): string[];
+    close(): void;
+}
+/** True when no Mongo is configured, so the SQLite fallback is in effect. */
+export declare function isServerless(): boolean;
+/**
+ * Return a collection for `name`.
+ *
+ * A real MongoDB driver `Collection` when a Mongo URI is configured (and the
+ * `mongodb` driver is installed); otherwise a `SqliteCollection` backed by the
+ * local SQLite file. Same call sites either way - only the backend differs.
+ *
+ * The real-Mongo path is async (the driver connects lazily), so this returns a
+ * Promise when Mongo is configured. In serverless mode it returns a
+ * SqliteCollection synchronously (the common local-dev case).
+ */
+export declare function getCollection(name: string): SqliteCollection | Promise<unknown>;
+/** Drop the cached default SQLite store (test helper). */
+export declare function resetDefaultStore(): void;
+export {};

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

@@ -0,0 +1,22 @@
+import { FakeData as CoreFakeData } from "../../core/src/fakeData.js";
+import type { FieldDefinition } from "./types.js";
+/**
+ * ORM-aware FakeData — wraps the core FakeData and adds forField()
+ * which generates appropriate fake data based on an ORM FieldDefinition.
+ */
+export declare class FakeData extends CoreFakeData {
+    constructor(seed?: number);
+    /**
+     * Generate a Date object within a year range.
+     * Matches the Python API's datetime() method.
+     */
+    datetime(startYear?: number, endYear?: number): Date;
+    /**
+     * Generate a fake value appropriate for an ORM field definition.
+     * Respects min/max, minLength/maxLength, and type constraints.
+     *
+     * @param fieldDef - An ORM FieldDefinition object
+     * @param columnName - Optional column name for heuristic matching (e.g. "email", "phone")
+     */
+    forField(fieldDef: FieldDefinition, columnName?: string): unknown;
+}

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

@@ -0,0 +1,40 @@
+export type { FieldType, FieldDefinition, ModelDefinition, DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, QueryOptions, RelationshipDefinition, PaginatedResult, } from "./types.js";
+export { FetchResult } from "./types.js";
+export { DatabaseResult } from "./databaseResult.js";
+export type { ColumnInfoResult } from "./databaseResult.js";
+export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
+export { adapterFetch, adapterQuery, adapterFetchOne, adapterExecute, adapterStartTransaction, adapterCommit, adapterRollback, adapterTableExists, adapterTables, adapterColumns, adapterCreateTable, extractLastInsertId, } from "./database.js";
+export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
+export { discoverModels } from "./model.js";
+export type { DiscoveredModel } from "./model.js";
+export { syncModels, ensureMigrationTable, getNextBatch, isMigrationApplied, recordMigration, applyMigration, rollback, getAppliedMigrations, getLastBatchMigrations, removeMigrationRecord, migrate, createMigration, status, Migration, splitStatements, parseSetTerm, normalizeQuotes, sortMigrationFiles, shouldSkipCreateTable, } from "./migration.js";
+export type { MigrationResult, MigrationStatus } from "./migration.js";
+export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
+export type { AutoCrudOptions } from "./autoCrud.js";
+export { buildQuery, parseQueryString } from "./query.js";
+export { validate } from "./validation.js";
+export type { ValidationError } from "./validation.js";
+export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
+export { QueryBuilder } from "./queryBuilder.js";
+export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
+export { CachedDatabaseAdapter } from "./cachedDatabase.js";
+export type { CachedAdapterOptions } from "./cachedDatabase.js";
+export { FakeData } from "./fakeData.js";
+export { seedTable, seedOrm, seedModels, autoFieldMap } from "./seeder.js";
+export type { SeedSummary, SeedOptions } from "./seeder.js";
+export { ObjectId, InvalidId, SqliteDatabase, SqliteCollection, Cursor, getCollection, isServerless, resetDefaultStore, encodeValue, decodeValue, compileFilter, } from "./docstore.js";
+export type { InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, } from "./docstore.js";
+export { SQLiteAdapter } from "./adapters/sqlite.js";
+export { PostgresAdapter } from "./adapters/postgres.js";
+export type { PostgresConfig } from "./adapters/postgres.js";
+export { MysqlAdapter } from "./adapters/mysql.js";
+export type { MysqlConfig } from "./adapters/mysql.js";
+export { MssqlAdapter } from "./adapters/mssql.js";
+export type { MssqlConfig } from "./adapters/mssql.js";
+export { FirebirdAdapter, normalizeFirebirdDbIdentifier, resolveFirebirdCharset } from "./adapters/firebird.js";
+export type { FirebirdConfig } from "./adapters/firebird.js";
+export { MongodbAdapter } from "./adapters/mongodb.js";
+export type { MongoConfig } from "./adapters/mongodb.js";
+export { OdbcAdapter } from "./adapters/odbc.js";
+export type { OdbcConfig } from "./adapters/odbc.js";
+export { realtime, iceServers, type RealtimeOptions, LocalStorage, S3Storage, selectStorage, storageKey, type StorageBackend, Workspace as RealtimeWorkspace, Channel as RealtimeChannel, ChannelMember as RealtimeChannelMember, Message as RealtimeMessage, Attachment as RealtimeAttachment, } from "./realtime/index.js";

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;