weifuwu 0.27.2 → 0.27.4

package/dist/postgres/schema/columns.d.ts

@@ -0,0 +1,99 @@
+import { SQL } from './sql.ts';
+/** Reference to another table's column (foreign key). */
+export interface ColumnReference {
+    /** Referenced table name. */
+    table: string;
+    /** Referenced column name (default: `'id'`). */
+    column: string;
+    /** `ON DELETE` action (e.g. `'cascade'`, `'set null'`). */
+    onDelete?: string;
+}
+/**
+ * Fluent column builder for DDL generation.
+ *
+ * ```ts
+ * text('name').notNull().unique()
+ * integer('user_id').references('users')
+ * timestamptz('created_at').default(sql`NOW()`)
+ * ```
+ */
+export declare class ColumnBuilder<T> {
+    /** Column name. */
+    name: string;
+    /** SQL type string (e.g. `'TEXT'`, `'INTEGER'`). */
+    sqlType: string;
+    /** Whether this column is PRIMARY KEY. */
+    isPrimaryKey: boolean;
+    /** Whether this column allows NULL. */
+    isNullable: boolean;
+    /** Whether this column has a UNIQUE constraint. */
+    isUnique: boolean;
+    /** Whether the value is auto-generated (e.g. SERIAL, UUID defaults). */
+    isAutoGenerate: boolean;
+    /** DEFAULT expression as a raw SQL string. */
+    defaultExpr: string | null;
+    /** Foreign key reference, if any. */
+    ref: ColumnReference | null;
+    constructor(name: string, sqlType: string);
+    /** Mark as PRIMARY KEY (implies NOT NULL). */
+    primaryKey(): this;
+    /** Add NOT NULL constraint. */
+    notNull(): this;
+    /** Allow NULL values (default). */
+    nullable(): this;
+    /** Set a DEFAULT value. Accepts raw SQL, string, number, or boolean. */
+    default(expr: SQL | string | number | boolean): this;
+    /** Add UNIQUE constraint. */
+    unique(): this;
+    /** Add FOREIGN KEY reference to another table. */
+    references(table: string, column?: string, onDelete?: string): this;
+}
+/** Auto-incrementing integer primary key (`SERIAL`). */
+export declare function serial(name: string): ColumnBuilder<number>;
+/** UUID column. */
+export declare function uuid(name: string): ColumnBuilder<string>;
+/** TEXT column. */
+export declare function text(name: string): ColumnBuilder<string>;
+/** INTEGER column. */
+export declare function integer(name: string): ColumnBuilder<number>;
+/** BOOLEAN column (exported as `boolean`). */
+export declare function boolean_(name: string): ColumnBuilder<boolean>;
+export { boolean_ as boolean };
+/** TIMESTAMPTZ column (timestamp with time zone). */
+export declare function timestamptz(name: string): ColumnBuilder<string>;
+/** JSONB column (stores arbitrary JSON data). */
+export declare function jsonb<T = unknown>(name: string): ColumnBuilder<T>;
+/** TEXT[] column (PostgreSQL array of text). */
+export declare function textArray(name: string): ColumnBuilder<string[]>;
+/** Vector column for pgvector (embedding storage). Requires `dimensions`. */
+export declare function vector(name: string, dims: number): ColumnBuilder<number[]>;
+export interface PartitionByDef {
+    type: 'RANGE' | 'LIST' | 'HASH';
+    column: string;
+}
+export declare function partitionBy(type: 'range' | 'list' | 'hash', column: string): PartitionByDef;
+/**
+ * Create a pair of `created_at` / `updated_at` timestamp columns
+ * that default to `NOW()` and are NOT NULL.
+ *
+ * ```ts
+ * pgTable('users', {
+ *   id: serial('id').primaryKey(),
+ *   name: text('name'),
+ *   ...timestamps(),
+ * })
+ * ```
+ */
+export declare function timestamps(): {
+    readonly created_at: ColumnBuilder<string>;
+    readonly updated_at: ColumnBuilder<string>;
+};
+/**
+ * Convert a ColumnBuilder into a DDL column definition string.
+ *
+ * ```ts
+ * toDDL(text('name').notNull())
+ * // '"name" TEXT NOT NULL'
+ * ```
+ */
+export declare function toDDL(col: ColumnBuilder<unknown>): string;

package/dist/postgres/schema/index.d.ts

@@ -0,0 +1,6 @@
+export { sql, SQL } from './sql.ts';
+export { ColumnBuilder, serial, uuid, text, integer, boolean as boolean, boolean_, timestamptz, jsonb, textArray, vector, toDDL, partitionBy, timestamps, } from './columns.ts';
+export type { PartitionByDef } from './columns.ts';
+export { pgTable, Table, BoundTable } from './table.ts';
+export type { IndexOptions, FindOptions, CreateOptions } from './table.ts';
+export { eq, ne, gt, gte, lt, lte, isNull, isNotNull, like, contains, in_, and, or, not, } from './where.ts';

package/dist/postgres/schema/sql.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A parameterized SQL fragment with template strings and bound values.
+ * Used internally by the schema builder and where helpers.
+ */
+export declare class SQL {
+    /** Template string parts (interleaved with values). */
+    strings: TemplateStringsArray;
+    /** Bound parameter values. */
+    values: unknown[];
+    constructor(strings: TemplateStringsArray, values: unknown[]);
+    /** Serialize to a raw SQL string (interpolating values inline for DDL use). */
+    toSQL(): string;
+}
+/**
+ * Tagged template helper for creating parameterized SQL fragments.
+ *
+ * ```ts
+ * sql`NOW()`
+ * sql`${column} ILIKE ${'%' + search + '%'}`
+ * ```
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SQL;

package/dist/postgres/schema/table.d.ts

@@ -0,0 +1,141 @@
+import type { SqlClient } from '../../types.ts';
+import { ColumnBuilder, type PartitionByDef } from './columns.ts';
+import { SQL } from './sql.ts';
+/** Options for table index creation. */
+export interface IndexOptions {
+    /** Whether the index should be UNIQUE. */
+    unique?: boolean;
+    /** Index type: btree (default), hnsw (pgvector), gin (JSONB). */
+    type?: 'btree' | 'hnsw' | 'gin';
+    /** Create index in DESC order. */
+    desc?: boolean;
+    /** Custom operator class (e.g. `vector_cosine_ops`). */
+    operator?: string;
+}
+/** Options for CREATE TABLE. */
+export interface CreateOptions {
+    /** Partition by clause (RANGE, LIST, or HASH). */
+    partitionBy?: PartitionByDef;
+}
+/** Options for find/read queries. */
+export interface FindOptions {
+    /** ORDER BY clause: `{ column: 'asc' | 'desc' }`. */
+    orderBy?: Record<string, 'asc' | 'desc'>;
+    /** LIMIT. */
+    limit?: number;
+    /** OFFSET. */
+    offset?: number;
+    /** Columns to SELECT (default: all). */
+    select?: string[];
+    /** Include soft-deleted rows (also sets `withDeleted` context). */
+    withDeleted?: boolean;
+}
+/**
+ * Type-safe table schema + CRUD operations.
+ *
+ * Create an instance with {@link pgTable}, then call `.bind(sql)` to get a
+ * `BoundTable` for running queries.
+ *
+ * ```ts
+ * const users = pgTable('users', {
+ *   id: serial('id').primaryKey(),
+ *   name: text('name').notNull(),
+ *   email: text('email').unique(),
+ * })
+ *
+ * const db = users.bind(sql)
+ * await db.create()
+ * await db.insert({ name: 'Alice', email: 'a@b.com' })
+ * const row = await db.findBy({ email: 'a@b.com' })
+ * ```
+ */
+export declare class Table<R extends Record<string, unknown>> {
+    /** Database table name. */
+    readonly tableName: string;
+    /** All column builders (order-preserving). */
+    readonly columns: ColumnBuilder<unknown>[];
+    /** Column builders keyed by property name. */
+    readonly builders: Record<string, ColumnBuilder<unknown>>;
+    private colEntries;
+    constructor(tableName: string, builders: Record<string, ColumnBuilder<unknown>>);
+    /** Check if the table has a column with the given DB name. */
+    hasColumn(dbName: string): boolean;
+    /**
+     * Bind this table schema to a SQL connection, returning a `BoundTable`
+     * that can run queries without passing `sql` to every call.
+     */
+    bind(sql: SqlClient): BoundTable<R>;
+    /** Returns the primary key column name (DB name), or 'id' as fallback. */
+    private get pkColumn();
+    /** Adds `deleted_at IS NULL` condition if the table has soft delete and not explicitly excluded. */
+    private _softDeleteFilter;
+    create(sql: SqlClient, opts?: CreateOptions): Promise<void>;
+    drop(sql: SqlClient, opts?: {
+        cascade?: boolean;
+    }): Promise<void>;
+    createIndex(sql: SqlClient, columns: string | string[], opts?: IndexOptions): Promise<void>;
+    createUniqueIndex(sql: SqlClient, columns: string | string[]): Promise<void>;
+    private _buildConditions;
+    private _buildSET;
+    insert(sql: SqlClient, data: Partial<R>): Promise<R>;
+    insertMany(sql: SqlClient, data: Partial<R>[]): Promise<R[]>;
+    read(sql: SqlClient, id: string | number, opts?: Pick<FindOptions, 'select' | 'withDeleted'>): Promise<R | undefined>;
+    readMany(sql: SqlClient, where?: Partial<R> | SQL | SQL[], opts?: FindOptions): Promise<{
+        count: number;
+        data: R[];
+    }>;
+    update(sql: SqlClient, id: string | number, data: Partial<R>): Promise<R | undefined>;
+    updateMany(sql: SqlClient, where: Partial<R> | SQL | SQL[], data: Partial<R>): Promise<number>;
+    delete(sql: SqlClient, id: string | number): Promise<R | undefined>;
+    hardDelete(sql: SqlClient, id: string | number): Promise<R | undefined>;
+    deleteMany(sql: SqlClient, where: Partial<R> | SQL | SQL[]): Promise<number>;
+    hardDeleteMany(sql: SqlClient, where: Partial<R> | SQL | SQL[]): Promise<number>;
+    upsert(sql: SqlClient, data: Partial<R>, conflict: string | string[]): Promise<R>;
+    count(sql: SqlClient, where?: Partial<R> | SQL | SQL[]): Promise<number>;
+}
+export declare class BoundTable<R extends Record<string, unknown>> {
+    private inner;
+    private sql;
+    /** The underlying table name. */
+    get tableName(): string;
+    constructor(sql: SqlClient, tableName: string, builders: Record<string, ColumnBuilder<unknown>>);
+    create(opts?: CreateOptions): Promise<void>;
+    drop(opts?: {
+        cascade?: boolean;
+    }): Promise<void>;
+    createIndex(columns: string | string[], opts?: IndexOptions): Promise<void>;
+    createUniqueIndex(columns: string | string[]): Promise<void>;
+    insert(data: Partial<R>): Promise<R>;
+    insertMany(data: Partial<R>[]): Promise<R[]>;
+    read(id: string | number, opts?: Pick<FindOptions, 'select' | 'withDeleted'>): Promise<R | undefined>;
+    readMany(where?: Partial<R> | SQL | SQL[], opts?: FindOptions): Promise<{
+        count: number;
+        data: R[];
+    }>;
+    update(id: string | number, data: Partial<R>): Promise<R | undefined>;
+    updateMany(where: Partial<R> | SQL | SQL[], data: Partial<R>): Promise<number>;
+    delete(id: string | number): Promise<R | undefined>;
+    hardDelete(id: string | number): Promise<R | undefined>;
+    deleteMany(where: Partial<R> | SQL | SQL[]): Promise<number>;
+    hardDeleteMany(where: Partial<R> | SQL | SQL[]): Promise<number>;
+    upsert(data: Partial<R>, conflict: string | string[]): Promise<R>;
+    count(where?: Partial<R> | SQL | SQL[]): Promise<number>;
+    withSql(sql: SqlClient): BoundTable<R>;
+}
+/**
+ * Define a type-safe table schema.
+ *
+ * ```ts
+ * const users = pgTable('users', {
+ *   id: serial('id').primaryKey(),
+ *   name: text('name').notNull(),
+ *   email: text('email').unique(),
+ * })
+ *
+ * // The generic type R preserves the column types:
+ * // Table<{ id: number; name: string; email: string }>
+ * ```
+ */
+export declare function pgTable<R extends Record<string, unknown>>(tableName: string, builders: {
+    [K in keyof R]: ColumnBuilder<R[K]>;
+}): Table<R>;

package/dist/postgres/schema/where.d.ts

@@ -0,0 +1,29 @@
+import { SQL } from './sql.ts';
+/** Column equals value: `col = val`. */
+export declare function eq(col: string, val: unknown): SQL;
+/** Column not equals value: `col != val`. */
+export declare function ne(col: string, val: unknown): SQL;
+/** Column greater than value: `col > val`. */
+export declare function gt(col: string, val: unknown): SQL;
+/** Column greater than or equal value: `col >= val`. */
+export declare function gte(col: string, val: unknown): SQL;
+/** Column less than value: `col < val`. */
+export declare function lt(col: string, val: unknown): SQL;
+/** Column less than or equal value: `col <= val`. */
+export declare function lte(col: string, val: unknown): SQL;
+/** Column IS NULL. */
+export declare function isNull(col: string): SQL;
+/** Column IS NOT NULL. */
+export declare function isNotNull(col: string): SQL;
+/** Column LIKE pattern. */
+export declare function like(col: string, pattern: string): SQL;
+/** Negate a condition: `NOT (condition)`. */
+export declare function not(condition: SQL): SQL;
+/** JSONB containment: `col @> val` (does `col` contain `val`?). */
+export declare function contains(col: string, val: Record<string, unknown>): SQL;
+/** Column value is in array: `col = ANY(val)`. */
+export declare function in_(col: string, val: unknown[]): SQL;
+/** Combine conditions with AND. */
+export declare function and(...conditions: SQL[]): SQL;
+/** Combine conditions with OR. */
+export declare function or(...conditions: SQL[]): SQL;

package/dist/postgres/types.d.ts

@@ -0,0 +1,49 @@
+import type { SqlClient, Context, Middleware, Closeable } from '../types.ts';
+import type { ColumnBuilder, BoundTable, Table } from './schema/index.ts';
+declare module '../types.ts' {
+    interface Context {
+        sql: SqlClient;
+    }
+}
+export interface PostgresInjected {
+    sql: SqlClient;
+}
+export interface PostgresOptions {
+    connection?: string | Record<string, unknown>;
+    signal?: AbortSignal;
+    closeTimeout?: number;
+    max?: number;
+    ssl?: boolean | Record<string, unknown>;
+    idle_timeout?: number;
+    connect_timeout?: number;
+    /** Per-statement timeout in ms. Set to 0 to disable. Default: 30_000. */
+    statementTimeout?: number;
+    /** Called after every query completes. Receives query text, duration in ms, and row count. */
+    onQuery?: (query: string, durationMs: number, rowCount: number) => void;
+}
+export interface PostgresClient extends Middleware<Context, Context & PostgresInjected>, Closeable {
+    sql: SqlClient;
+    /** Creates the migration tracking table (_weifuwu_migrations). Called once at startup. */
+    migrate: () => Promise<void>;
+    /** Record that a module's migration has been applied (idempotent). */
+    markMigrated: (moduleName: string) => Promise<void>;
+    /** Check whether a module has already been migrated. */
+    isMigrated: (moduleName: string) => Promise<boolean>;
+    table: {
+        <R extends Record<string, unknown>>(tableName: string, builders: {
+            [K in keyof R]: ColumnBuilder<R[K]>;
+        }): BoundTable<R>;
+        <R extends Record<string, unknown>>(schema: Table<R>): BoundTable<R>;
+    };
+    transaction: <T>(fn: (sql: any) => Promise<T>, retryOpts?: {
+        maxRetries?: number;
+    }) => Promise<T>;
+    /** Snapshot of connection pool state: active, idle, waiting, max connections. */
+    poolStats: () => {
+        active: number;
+        idle: number;
+        waiting: number;
+        max: number;
+    };
+    close: () => Promise<void>;
+}

package/dist/queue/cron.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Cron expression parsing utilities (moved from cron-utils.ts).
+ * Used internally by queue for scheduled job execution.
+ *
+ * All functions operate in local timezone.
+ */
+export declare function parsePattern(pattern: string): Set<number>[];
+export declare function matches(fields: Set<number>[], date: Date): boolean;
+export declare function cronNext(expr: string, from?: Date): number;

package/dist/queue/index.d.ts

@@ -0,0 +1,2 @@
+import type { Queue, QueueOptions } from './types.ts';
+export declare function queue(opts?: QueueOptions): Queue;

package/dist/queue/types.d.ts

@@ -0,0 +1,61 @@
+import type { Redis, Context, Middleware, Closeable } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        queue: Queue;
+    }
+}
+export interface QueueJob<T = unknown> {
+    id: string;
+    type: string;
+    payload: T;
+    createdAt: number;
+    runAt: number;
+    schedule?: string;
+}
+export interface QueueOptions {
+    /** Backend store. Default: 'memory'. */
+    store?: 'memory' | 'pg' | 'redis';
+    redis?: Redis;
+    url?: string;
+    prefix?: string;
+    pollInterval?: number;
+    /** PostgreSQL client (required when store: 'pg'). */
+    pg?: {
+        sql: import('../types.ts').SqlClient;
+    };
+}
+export interface QueueInjected {
+    queue: Queue;
+}
+export interface QueueJobWithError<T = unknown> extends QueueJob<T> {
+    error: string;
+    failedAt: number;
+}
+export interface Queue extends Middleware<Context, Context & QueueInjected>, Closeable {
+    /** Register a cron job. Uses queue's backend (memory/pg/redis) for execution. */
+    cron(pattern: string, handler: () => void | Promise<void>): {
+        stop: () => void;
+    };
+    add<T>(type: string, payload: T, opts?: {
+        delay?: number;
+        schedule?: string;
+    }): Promise<string>;
+    process<T>(type: string, handler: (job: QueueJob<T>) => Promise<void>): void;
+    run(): Promise<void>;
+    stats(): {
+        running: boolean;
+        inflight: number;
+        processed: number;
+        failed: number;
+        handlers: number;
+        maxConcurrent: number;
+    };
+    jobs(limit?: number): Promise<QueueJob[]>;
+    failedJobs(limit?: number): Promise<QueueJobWithError[]>;
+    retryFailed(jobId: string): Promise<boolean>;
+    retryAllFailed(type?: string): Promise<number>;
+    dashboard(): import('../core/router.ts').Router;
+    /** Create the jobs table (PG mode only; safe to call multiple times). */
+    migrate?(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/redis/client.d.ts

@@ -0,0 +1,2 @@
+import type { RedisOptions, RedisClient } from './types.ts';
+export declare function redis(opts?: string | RedisOptions): RedisClient;

package/{redis/index.ts → dist/redis/index.d.ts}

@@ -1,2 +1,2 @@
-export { redis } from './client.ts'
-export type { RedisOptions, RedisClient, RedisInjected } from './types.ts'
+export { redis } from './client.ts';
+export type { RedisOptions, RedisClient, RedisInjected } from './types.ts';

package/dist/redis/types.d.ts

@@ -0,0 +1,17 @@
+import type { Redis, RedisOptions as IORedisOptions, Context, Middleware, Closeable } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        redis: Redis;
+    }
+}
+export type { Redis };
+export type RedisOptions = IORedisOptions & {
+    url?: string;
+};
+export interface RedisInjected {
+    redis: Redis;
+}
+export interface RedisClient extends Middleware<Context, Context & RedisInjected>, Closeable {
+    redis: Redis;
+    close: () => Promise<void>;
+}

package/dist/test/test-utils.d.ts

@@ -0,0 +1,193 @@
+import type { Context, Handler, SqlClient } from '../types.ts';
+import { Router } from '../core/router.ts';
+import { WebSocket as WSWebSocket } from 'ws';
+export interface TestResponse {
+    readonly status: number;
+    readonly headers: Headers;
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+}
+export declare class TestRequest {
+    private headers;
+    private ctxMixin;
+    private bodyData;
+    private app;
+    private method;
+    private path;
+    constructor(app: TestApp, method: string, path: string);
+    /** Set a request header */
+    header(name: string, value: string): this;
+    /** Mix properties into ctx (simulating middleware injection) */
+    with(mixin: Partial<Context>): this;
+    /** Shortcut: set ctx.user */
+    withUser(user: unknown): this;
+    /** Shortcut: set ctx.tenant */
+    withTenant(tenant: {
+        id: string;
+        name: string;
+        role: string;
+    }): this;
+    /** Set JSON request body */
+    body(data: unknown): this;
+    /** Set raw text body */
+    rawBody(data: string): this;
+    /** Send the request and return the response */
+    send(): Promise<TestResponse>;
+}
+export declare class TestApp {
+    private router;
+    private wsServer;
+    private wsConnections;
+    constructor();
+    /**
+     * Register a WebSocket handler.
+     */
+    ws(path: string, handler: import('../core/router.ts').WebSocketHandler): this;
+    /** Get the raw Router (for advanced use). */
+    get _router(): Router;
+    /** Add global middleware */
+    use(mw: any): this;
+    /** Register a GET route — supports route-level middleware via spread args. */
+    get(path: string, ...args: any[]): this;
+    /** Register a POST route. */
+    post(path: string, ...args: any[]): this;
+    /** Register a PUT route. */
+    put(path: string, ...args: any[]): this;
+    /** Register a PATCH route. */
+    patch(path: string, ...args: any[]): this;
+    /** Register a DELETE route. */
+    delete(path: string, ...args: any[]): this;
+    /** Start building a GET request */
+    getReq(path: string): TestRequest;
+    /** Start building a POST request */
+    postReq(path: string): TestRequest;
+    /** Start building a PUT request */
+    putReq(path: string): TestRequest;
+    /** Start building a PATCH request */
+    patchReq(path: string): TestRequest;
+    /** Start building a DELETE request */
+    deleteReq(path: string): TestRequest;
+    /** Get the underlying handler (for advanced usage) */
+    handler(): Handler;
+    /** Start building a WebSocket connection to the given path. */
+    wsReq(path: string): TestWSRequest;
+    /**
+     * Internal: ensure HTTP server is running for WebSocket connections.
+     * Starts on a random port.
+     */
+    _ensureServer(): Promise<string>;
+    /**
+     * Internal: register a WS connection for cleanup.
+     */
+    _trackConnection(conn: TestWSConnection): void;
+    /**
+     * Cleanup all WebSocket connections and stop the server.
+     */
+    close(): Promise<void>;
+}
+/** Start building a WebSocket test connection. */
+export declare class TestWSRequest {
+    private app;
+    private path;
+    private _timeout;
+    constructor(app: TestApp, path: string);
+    /** Set the timeout for operations (default: 5000ms). */
+    timeout(ms: number): this;
+    /**
+     * Connect to the WebSocket endpoint.
+     * Starts a real HTTP server (random port) if not already running.
+     */
+    connect(): Promise<TestWSConnection>;
+}
+/**
+ * A connected WebSocket for testing.
+ *
+ * ```ts
+ * const conn = await app.wsReq('/echo').connect()
+ * conn.send('hello')
+ * const msg = await conn.receive()
+ * assert.equal(msg, 'hello')
+ * conn.close()
+ * ```
+ */
+export declare class TestWSConnection {
+    private ws;
+    private _timeout;
+    private messageQueue;
+    private resolveQueue;
+    private _closed;
+    constructor(ws: WSWebSocket, timeout?: number);
+    /** Send a text message. */
+    send(data: string): void;
+    /** Send a JSON message. */
+    json(data: unknown): void;
+    /**
+     * Wait for the next message. Returns the raw text.
+     * Throws on timeout or if the connection is closed.
+     */
+    receive(timeout?: number): Promise<string>;
+    /** Wait for the next message and parse as JSON. */
+    receiveJson<T = unknown>(): Promise<T>;
+    /**
+     * Assert that no message is received within the given silence period.
+     * Useful for verifying that something did NOT happen.
+     */
+    expectSilent(ms: number): Promise<void>;
+    /** Close the connection. */
+    close(): void;
+    /** Whether the connection is closed. */
+    get closed(): boolean;
+}
+/** Create a new test app */
+export declare function testApp(): TestApp;
+/**
+ * Result of createTestDb().
+ */
+export interface TestDb {
+    /** Tagged-template SQL client connected to the test database. */
+    sql: SqlClient;
+    /** Connection URL of the test database. */
+    url: string;
+    /** Schema name used for this test session. */
+    schema: string;
+    /** Destroy the test database (drop schema). */
+    destroy: () => Promise<void>;
+}
+/**
+ * Create an isolated test database schema for integration testing.
+ *
+ * Uses PostgreSQL schemas for isolation — no separate database needed.
+ * Each call creates a unique schema under the same database.
+ *
+ * ```ts
+ * const db = await createTestDb()
+ * await db.sql`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`
+ * // ... run tests ...
+ * await db.destroy()  // drops the schema
+ * ```
+ *
+ * Uses `TEST_DATABASE_URL` or `DATABASE_URL` env var.
+ */
+export declare function createTestDb(options?: {
+    /** Database URL. Default: TEST_DATABASE_URL or DATABASE_URL. */
+    url?: string;
+    /** Schema name. Default: auto-generated 'test_<timestamp>_<random>'. */
+    schema?: string;
+}): Promise<TestDb>;
+/**
+ * Run a test callback within an isolated transaction that is rolled back
+ * after completion. This provides the fastest isolation — no cleanup needed.
+ *
+ * ```ts
+ * await withTestDb(async (sql) => {
+ *   await sql`INSERT INTO users ...`
+ *   // All changes are rolled back after this callback returns
+ * })
+ * ```
+ *
+ * @param optionsOrFn Either a URL string or options object, or the callback directly.
+ * @param fn Async callback receiving a tagged-template sql client.
+ */
+export declare function withTestDb(optionsOrFn: string | {
+    url?: string;
+} | ((sql: SqlClient) => Promise<void>), fn?: (sql: SqlClient) => Promise<void>): Promise<void>;