@minnowdb/core 0.0.1 → 0.1.0

package/dist/engine/defaults.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Write-time default filling. For a default-bearing column (always non-nullable), a null or
+ * absent slot means "generate" and an explicit value passes through untouched. Pure defaults
+ * (now, literals) are filled here before validation; auto-increment slots stay null until the
+ * write path reserves a range from storage, keeping generation atomic across concurrent
+ * writers. Function defaults never reach the engine — the typed facade fills them before the
+ * batch crosses the boundary.
+ */
+import type { RowIdRange, TableColumnRecord, TableRecord } from "../storage/types.js";
+import type { BatchValue, ColumnarBatch } from "./batch.js";
+/** The deferred part of a fill: slots that need storage-reserved auto-increment values. */
+export interface AutoIncrementFill {
+    readonly column: TableColumnRecord;
+    /** Row indexes whose value must come from the reserved range, in row order. */
+    readonly missingIndexes: readonly number[];
+    /** One past the largest explicit value in the batch, so generated keys never collide with it. */
+    readonly atLeast: bigint;
+}
+export interface FilledBatch {
+    readonly batch: ColumnarBatch;
+    /** Full written vectors, input row order, for columns where at least one slot was generated. */
+    readonly generated: Map<string, BatchValue[]>;
+    /** Present whenever the table has an auto-increment column, even if every value is explicit —
+     * the counter still bumps past the explicit maximum in the same atomic step. */
+    readonly autoIncrement?: AutoIncrementFill;
+}
+export declare function fillColumnDefaults(table: TableRecord, input: ColumnarBatch, now: () => Date, knownRowCount?: number): FilledBatch;
+/**
+ * Writes the reserved range into the batch's null slots. The vector is the fresh array
+ * `fillColumnDefaults` created for this fill, never a caller-owned one.
+ */
+export declare function patchAutoIncrementValues(input: ColumnarBatch, fill: AutoIncrementFill, range: RowIdRange): void;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/engine/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/engine/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC9C;oFACgF;IAChF,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,MAAM,IAAI,EACf,aAAa,CAAC,EAAE,MAAM,GACrB,WAAW,CA8Db;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,UAAU,GAChB,IAAI,CASN"}

package/dist/engine/defaults.js

@@ -0,0 +1,87 @@
+/**
+ * Write-time default filling. For a default-bearing column (always non-nullable), a null or
+ * absent slot means "generate" and an explicit value passes through untouched. Pure defaults
+ * (now, literals) are filled here before validation; auto-increment slots stay null until the
+ * write path reserves a range from storage, keeping generation atomic across concurrent
+ * writers. Function defaults never reach the engine — the typed facade fills them before the
+ * batch crosses the boundary.
+ */
+export function fillColumnDefaults(table, input, now, knownRowCount) {
+    const defaultColumns = table.columns.filter((column) => column.defaultValue !== undefined);
+    if (defaultColumns.length === 0)
+        return { batch: input, generated: new Map() };
+    const rowCount = knownRowCount ?? Object.values(input.columns).find((values) => values.length > 0)?.length ?? 0;
+    if (rowCount === 0)
+        return { batch: input, generated: new Map() };
+    const columns = { ...input.columns };
+    const generated = new Map();
+    let autoIncrement;
+    let nowValue;
+    for (const column of defaultColumns) {
+        const defaultValue = column.defaultValue;
+        if (defaultValue === undefined)
+            continue;
+        const provided = input.columns[column.name];
+        if (defaultValue.kind === "autoincrement") {
+            const missingIndexes = [];
+            let maxExplicit = 0n;
+            for (let index = 0; index < rowCount; index += 1) {
+                const value = provided?.[index] ?? null;
+                if (value === null) {
+                    missingIndexes.push(index);
+                    continue;
+                }
+                if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+                    throw new TypeError(`${column.name}[${String(index)}] must be a whole number in the safe integer range`);
+                }
+                if (BigInt(value) > maxExplicit)
+                    maxExplicit = BigInt(value);
+            }
+            if (missingIndexes.length > 0) {
+                columns[column.name] =
+                    provided === undefined ? new Array(rowCount).fill(null) : [...provided];
+            }
+            autoIncrement = { column, missingIndexes, atLeast: maxExplicit + 1n };
+            continue;
+        }
+        const values = provided === undefined ? new Array(rowCount).fill(null) : [...provided];
+        let filled = false;
+        for (let index = 0; index < rowCount; index += 1) {
+            if ((values[index] ?? null) !== null)
+                continue;
+            filled = true;
+            switch (defaultValue.kind) {
+                case "now":
+                    values[index] = nowValue ??= now();
+                    break;
+                case "literal":
+                    values[index] = defaultValue.value;
+                    break;
+            }
+        }
+        if (filled) {
+            columns[column.name] = values;
+            generated.set(column.name, values);
+        }
+    }
+    return {
+        batch: { columns },
+        generated,
+        ...(autoIncrement === undefined ? {} : { autoIncrement }),
+    };
+}
+/**
+ * Writes the reserved range into the batch's null slots. The vector is the fresh array
+ * `fillColumnDefaults` created for this fill, never a caller-owned one.
+ */
+export function patchAutoIncrementValues(input, fill, range) {
+    const vector = input.columns[fill.column.name];
+    fill.missingIndexes.forEach((rowIndex, offset) => {
+        const value = range.start + BigInt(offset);
+        if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new RangeError(`Auto-increment exhausted the safe integer range: ${fill.column.name}`);
+        }
+        vector[rowIndex] = Number(value);
+    });
+}
+//# sourceMappingURL=defaults.js.map

package/dist/engine/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/engine/defaults.ts"],"names":[],"mappings":"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"}

package/dist/engine/dsl/db.d.ts

@@ -0,0 +1,137 @@
+import { type CompiledQuery, type CompiledStatement, type QueryResult, type QueryRow, type QueryValue } from "../query.js";
+import { type AnyTable, type SchemaDefinition } from "../schema.js";
+import { type LiveSubscriptionHandle } from "./live-query.js";
+import { DeleteQueryBuilder, InsertQueryBuilder, UpdateQueryBuilder } from "./mutations.js";
+import { SelectQueryBuilder, type AliasedSelectQuery, type CteDefinition } from "./select-query-builder.js";
+import { type AnyRow, type ContextWithTable, type InferDatabase, type TableExpression } from "./types.js";
+/**
+ * The Kysely-style facade. `Minnow<DB>` wraps either the in-worker `MinnowDatabase` or the
+ * main-thread `MinnowDatabaseClient` (both satisfy `DslDriver` structurally) and hands out
+ * typed builders: `selectFrom`, `insertInto`, `updateTable`, `deleteFrom`, `with`, and live
+ * queries through the builders' `.live()`. `DB` is derived from the runtime schema with
+ * `InferDatabase<typeof appSchema>`; migrations stay on the driver (`driver.migrate(schema)`).
+ */
+export interface DriverLiveSet {
+    subscribe(query: string | {
+        kind: "typed-query";
+        plan: CompiledQuery;
+    }, options: {
+        onChange(result: QueryResult): void;
+        onError?(error: unknown): void;
+        onComplete?(): void;
+    }): Promise<LiveSubscriptionHandle>;
+    close(): void | Promise<void>;
+}
+export interface DslLiveOptions {
+    /** BroadcastChannel name for cross-tab commit hints (worker client). */
+    channelName?: string;
+    pollIntervalMs?: number;
+}
+/** The slice of MinnowDatabase / MinnowDatabaseClient the facade drives. */
+export interface DslDriver {
+    run<TRow>(query: {
+        kind: "typed-query";
+        plan: CompiledQuery;
+        __row?: TRow;
+    }): Promise<TRow[]>;
+    insertBatch(tableName: string, rows: ReadonlyArray<Readonly<Record<string, QueryValue>>>): Promise<{
+        rowCount: number;
+        generatedColumns?: Record<string, QueryValue[]>;
+    }>;
+    upsertBatch(tableName: string, rows: ReadonlyArray<Readonly<Record<string, QueryValue>>>): Promise<{
+        rowCount: number;
+        generatedColumns?: Record<string, QueryValue[]>;
+    }>;
+    runStatement(statement: CompiledStatement, options?: {
+        returning?: readonly string[] | "*";
+    }): Promise<{
+        kind: string;
+        rowCount?: number;
+        returnedRows?: QueryRow[];
+    }>;
+    execute(sql: string, params?: readonly QueryValue[]): Promise<{
+        kind: string;
+        result?: {
+            rows: QueryRow[];
+        };
+    }>;
+    liveQueries(options?: DslLiveOptions): DriverLiveSet;
+}
+export interface MinnowOptions {
+    /**
+     * The runtime schema the database was migrated with. Inserts then pad omitted nullable
+     * columns with null (the engine's batch API takes every column); without it, an insert must
+     * list every column itself.
+     */
+    schema?: SchemaDefinition<readonly AnyTable[]>;
+    /** Options for the shared live-query set behind `.live()`; created lazily on first use. */
+    live?: DslLiveOptions;
+}
+type EmptyContext = Record<never, AnyRow>;
+/**
+ * Creates the typed facade. The recommended form names the database type once, so every hover,
+ * error, and emitted declaration prints `Minnow<DB>` instead of the fully expanded schema —
+ * which matters as soon as the schema has more than a table or two:
+ *
+ * ```ts
+ * interface DB extends InferDatabase<typeof appSchema> {}
+ * const db = createMinnow<DB>(database, { schema: appSchema });
+ * ```
+ *
+ * Without the type argument, `DB` is inferred from the runtime schema value — fine for
+ * scratch code and small scripts, at the cost of expanded types in tooling:
+ *
+ * ```ts
+ * const db = createMinnow(database, { schema: appSchema });
+ * ```
+ */
+export declare function createMinnow<TTables extends readonly AnyTable[]>(driver: DslDriver, options: Omit<MinnowOptions, "schema"> & {
+    schema: SchemaDefinition<TTables>;
+}): Minnow<InferDatabase<SchemaDefinition<TTables>>>;
+export declare function createMinnow<DB>(driver: DslDriver, options?: MinnowOptions): Minnow<DB>;
+interface SharedLiveSet {
+    set?: DriverLiveSet | undefined;
+}
+/** One db.search hit: the owning table, the row (without the score alias), and its BM25 score. */
+export interface SearchHit<DB> {
+    table: keyof DB & string;
+    row: Record<string, QueryValue>;
+    score: number;
+}
+export declare class Minnow<in out DB> {
+    #private;
+    constructor(driver: DslDriver, options?: MinnowOptions, ctes?: readonly CteDefinition[], liveBox?: SharedLiveSet);
+    /**
+     * The driver this facade was created with — the `MinnowDatabase` or `MinnowDatabaseClient`
+     * behind it. Tools handed only the facade (devtools, inspectors, schema browsers) reach the
+     * catalog and the raw SQL entry points through here; application code should keep its own
+     * reference to the driver rather than reaching back through the facade.
+     */
+    get driver(): DslDriver;
+    selectFrom<TE extends TableExpression<DB>>(table: TE): SelectQueryBuilder<DB, ContextWithTable<DB, EmptyContext, TE>, EmptyContext>;
+    selectFrom<TDerivedRow extends AnyRow, TAlias extends string>(derived: AliasedSelectQuery<TDerivedRow, TAlias>): SelectQueryBuilder<DB, Record<TAlias, TDerivedRow>, EmptyContext>;
+    insertInto<TTable extends keyof DB & string>(table: TTable): InsertQueryBuilder<DB, TTable>;
+    updateTable<TTable extends keyof DB & string>(table: TTable): UpdateQueryBuilder<DB, TTable>;
+    deleteFrom<TTable extends keyof DB & string>(table: TTable): DeleteQueryBuilder<DB, TTable>;
+    /**
+     * Declares a common table expression usable in `selectFrom`/joins of queries created from the
+     * returned facade, exactly as SQL `WITH name AS (...)`.
+     */
+    with<TName extends string, TCteCtx, TCteRow extends AnyRow>(name: TName, factory: (creator: Minnow<DB>) => SelectQueryBuilder<DB, TCteCtx, TCteRow>): Minnow<DB & Record<TName, TCteRow>>;
+    /**
+     * Zero-ceremony document search across tables: every searched table (all schema tables by
+     * default; `options.tables` narrows the set) runs a MATCH(*)-filtered, BM25-ordered scan,
+     * and the per-table hits merge into one relevance-ranked list. The facade must be created
+     * with `{ schema }` — the per-table column lists come from it.
+     */
+    search(query: string, options?: {
+        tables?: ReadonlyArray<keyof DB & string>;
+        limit?: number;
+    }): Promise<Array<SearchHit<DB>>>;
+    /** @internal Raw-SQL escape hatch used by the `sql` template tag. */
+    $executeRaw(sqlText: string, params?: readonly QueryValue[]): Promise<QueryRow[]>;
+    /** Closes the shared live-query set, if one was created. */
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=db.d.ts.map

package/dist/engine/dsl/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../../src/engine/dsl/db.ts"],"names":[],"mappings":"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"}

package/dist/engine/dsl/db.js

@@ -0,0 +1,161 @@
+import { DeleteQueryBuilder, InsertQueryBuilder, UpdateQueryBuilder, } from "./mutations.js";
+import { isAliasedSelectQuery, parseTableExpression, SelectQueryBuilder, } from "./select-query-builder.js";
+export function createMinnow(driver, options = {}) {
+    return new Minnow(driver, options);
+}
+export class Minnow {
+    #driver;
+    #options;
+    #ctes;
+    #liveBox;
+    constructor(driver, options = {}, ctes = [], liveBox = {}) {
+        this.#driver = driver;
+        this.#options = options;
+        this.#ctes = ctes;
+        this.#liveBox = liveBox;
+    }
+    /**
+     * The driver this facade was created with — the `MinnowDatabase` or `MinnowDatabaseClient`
+     * behind it. Tools handed only the facade (devtools, inspectors, schema browsers) reach the
+     * catalog and the raw SQL entry points through here; application code should keep its own
+     * reference to the driver rather than reaching back through the facade.
+     */
+    get driver() {
+        return this.#driver;
+    }
+    #liveServices() {
+        return {
+            subscribe: async (query, handlers) => {
+                this.#liveBox.set ??= this.#driver.liveQueries(this.#options.live ?? {});
+                return this.#liveBox.set.subscribe(query, handlers);
+            },
+        };
+    }
+    #services() {
+        return {
+            run: (query) => this.#driver.run(query),
+            live: this.#liveServices(),
+        };
+    }
+    /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return --
+       the implementation signature erases the context; the overloads above carry precise types. */
+    selectFrom(table) {
+        if (isAliasedSelectQuery(table)) {
+            return SelectQueryBuilder.create({ kind: "derived", builder: table.builder, alias: table.alias }, this.#ctes, this.#services());
+        }
+        const { table: name, alias } = parseTableExpression(table);
+        return SelectQueryBuilder.create({ kind: "table", table: name, alias }, this.#ctes, this.#services());
+    }
+    /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return */
+    #mutationServices() {
+        const schemaTables = this.#options.schema?.tables;
+        return {
+            insertBatch: (tableName, rows) => this.#driver.insertBatch(tableName, rows),
+            upsertBatch: (tableName, rows) => this.#driver.upsertBatch(tableName, rows),
+            runStatement: (statement, options) => this.#driver.runStatement(statement, options),
+            tableColumns: (tableName) => {
+                const definition = schemaTables?.find(({ name }) => name === tableName);
+                return definition === undefined ? undefined : Object.keys(definition.columns);
+            },
+            columnDefaultFns: (tableName) => {
+                const definition = schemaTables?.find(({ name }) => name === tableName);
+                if (definition === undefined)
+                    return undefined;
+                let fns;
+                for (const [name, columnDefinition] of Object.entries(definition.columns)) {
+                    const fill = columnDefinition.defaultFn;
+                    if (fill !== undefined)
+                        (fns ??= {})[name] = fill;
+                }
+                return fns;
+            },
+        };
+    }
+    insertInto(table) {
+        return new InsertQueryBuilder(this.#mutationServices(), table);
+    }
+    updateTable(table) {
+        return new UpdateQueryBuilder(this.#mutationServices(), table);
+    }
+    deleteFrom(table) {
+        return new DeleteQueryBuilder(this.#mutationServices(), table);
+    }
+    /**
+     * Declares a common table expression usable in `selectFrom`/joins of queries created from the
+     * returned facade, exactly as SQL `WITH name AS (...)`.
+     */
+    with(name, factory) {
+        const builder = factory(this);
+        return new Minnow(this.#driver, this.#options, [...this.#ctes, { name, builder }], this.#liveBox);
+    }
+    /**
+     * Zero-ceremony document search across tables: every searched table (all schema tables by
+     * default; `options.tables` narrows the set) runs a MATCH(*)-filtered, BM25-ordered scan,
+     * and the per-table hits merge into one relevance-ranked list. The facade must be created
+     * with `{ schema }` — the per-table column lists come from it.
+     */
+    async search(query, options = {}) {
+        const schemaTables = this.#options.schema?.tables;
+        if (schemaTables === undefined) {
+            throw new TypeError("search() needs the table columns: create the facade with { schema }");
+        }
+        const tableNames = options.tables ?? schemaTables.map(({ name }) => name);
+        const limit = options.limit ?? 10;
+        const perTable = await Promise.all(tableNames.map(async (tableName) => {
+            const definition = schemaTables.find(({ name }) => name === tableName);
+            if (definition === undefined) {
+                throw new TypeError(`search() needs the table's schema: ${tableName}`);
+            }
+            /* eslint-disable-next-line @typescript-eslint/no-explicit-any --
+               per-table column lists are only known at runtime; hits erase the row type anyway. */
+            const builder = this.selectFrom(tableName);
+            // The score is selected under an internal alias so hits can rank across tables, then
+            // stripped from the row; user-facing rows never carry a synthetic column. The alias
+            // grows parentheses until it collides with no real column name.
+            const columnNames = Object.keys(definition.columns);
+            let scoreAlias = "(search score)";
+            while (columnNames.includes(scoreAlias))
+                scoreAlias = `(${scoreAlias})`;
+            let rows;
+            try {
+                rows = await builder
+                    .select((eb) => [...columnNames, eb.fn.bm25("*", query).as(scoreAlias)])
+                    .search(query)
+                    .limit(limit)
+                    .execute();
+            }
+            catch (error) {
+                // A schema can list tables that don't exist yet or hold nothing searchable; those
+                // tables simply contribute no hits. Anything else is a real failure.
+                const message = error instanceof Error ? error.message : "";
+                if (message.startsWith("Table not found:") ||
+                    message.startsWith("Unknown table:") ||
+                    message.includes("no searchable columns")) {
+                    return [];
+                }
+                throw error;
+            }
+            return rows.map((row) => {
+                const { [scoreAlias]: score, ...rest } = row;
+                return { table: tableName, row: rest, score: typeof score === "number" ? score : 0 };
+            });
+        }));
+        return perTable
+            .flat()
+            .sort((left, right) => right.score - left.score)
+            .slice(0, limit);
+    }
+    /** @internal Raw-SQL escape hatch used by the `sql` template tag. */
+    async $executeRaw(sqlText, params) {
+        const result = await this.#driver.execute(sqlText, params);
+        return result.result?.rows ?? [];
+    }
+    /** Closes the shared live-query set, if one was created. */
+    async close() {
+        const set = this.#liveBox.set;
+        this.#liveBox.set = undefined;
+        if (set !== undefined)
+            await set.close();
+    }
+}
+//# sourceMappingURL=db.js.map

package/dist/engine/dsl/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../../src/engine/dsl/db.ts"],"names":[],"mappings":"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"}

package/dist/engine/dsl/expression.d.ts

@@ -0,0 +1,172 @@
+import { type AggregateName, type Expression, type QueryValue, type WindowFunctionName } from "../query.js";
+import { type AliasedExpression, type BlockCompilable, type ColumnReference, type ColumnReferenceOf, type ContextWithTable, type ExpressionSource, type ReferencedValue, type TableExpression } from "./types.js";
+import type { SelectQueryBuilder } from "./select-query-builder.js";
+/**
+ * Kysely-style expression building. `eb(lhs, op, rhs)` plus `eb.and/or/not/fn/case/exists/...`
+ * assemble the same Expression trees the SQL parser produces — string left-hand sides are column
+ * references, right-hand sides are values (use `eb.ref` to compare columns). Everything holds an
+ * ExpressionSource so subqueries compile under the enclosing query's shared derived-source
+ * sequence, keeping builder plans byte-identical to parsed SQL.
+ */
+export type SqlBool = boolean;
+export type ComparisonOperatorToken = "=" | "!=" | "<>" | ">" | ">=" | "<" | "<=";
+export type LikeOperatorToken = "like" | "not like";
+export type InOperatorToken = "in" | "not in";
+export type IsOperatorToken = "is" | "is not";
+export type ArithmeticOperatorToken = "+" | "-" | "*" | "/";
+export type BinaryOperatorToken = ComparisonOperatorToken | LikeOperatorToken | InOperatorToken | IsOperatorToken | ArithmeticOperatorToken;
+export declare class ExpressionWrapper<out TValue> {
+    readonly source: ExpressionSource;
+    readonly kind: "dsl-expression";
+    constructor(source: ExpressionSource);
+    /** Names this expression's output column, as SQL `AS alias` does. */
+    as<TAlias extends string>(alias: TAlias): AliasedExpression<TValue, TAlias>;
+}
+export declare function isExpressionWrapper(value: unknown): value is ExpressionWrapper<unknown>;
+/**
+ * A subquery usable where a scalar `TValue` is expected: its row must be a single column whose
+ * value fits. Only the value side is checked structurally — the builder's `DB`/context do not
+ * matter here, hence the `any`s.
+ */
+export type ScalarSubquery<TValue> = SelectQueryBuilder<any, any, Record<string, TValue | null>>;
+/** A value operand: a literal, a wrapped expression, or a scalar subquery of the same type. */
+export type ValueOperand<TValue> = TValue | null | ExpressionWrapper<TValue | null> | ScalarSubquery<TValue>;
+type ArithmeticOperand<TCtx> = ColumnReferenceOf<TCtx, number> | number | ExpressionWrapper<number | null>;
+export declare function literalExpression(value: unknown): Expression;
+/** Shared with the query builders: `lhs op rhs` where lhs is a reference and rhs a value. */
+export declare function buildBinaryCondition(lhs: unknown, operator: string, rhs: unknown): ExpressionSource;
+interface OverClauseState {
+    partitionBy: ExpressionSource[];
+    orderBy: Array<{
+        source: ExpressionSource;
+        direction: "asc" | "desc";
+    }>;
+}
+export declare class OverBuilder<in out TCtx> {
+    private readonly state;
+    constructor(state?: OverClauseState);
+    partitionBy(...references: ReadonlyArray<ColumnReference<TCtx> | ExpressionWrapper<unknown>>): OverBuilder<TCtx>;
+    orderBy(reference: ColumnReference<TCtx> | ExpressionWrapper<unknown>, direction?: "asc" | "desc"): OverBuilder<TCtx>;
+    /** @internal */
+    get clause(): OverClauseState;
+}
+type OverConfigure<TCtx> = (over: OverBuilder<TCtx>) => OverBuilder<TCtx>;
+/** A ranking window function; SQL requires OVER, so only `.over()` yields an expression. */
+export declare class WindowFunctionBuilder<in out TCtx> {
+    private readonly name;
+    constructor(name: WindowFunctionName);
+    over(configure?: OverConfigure<TCtx>): ExpressionWrapper<number>;
+}
+export declare class AggregateExpressionWrapper<in out TCtx, out TValue> extends ExpressionWrapper<TValue> {
+    private readonly name;
+    private readonly argument;
+    private readonly isDistinct;
+    constructor(name: AggregateName, argument: ExpressionSource, isDistinct?: boolean);
+    /** COUNT(DISTINCT e); the engine restricts DISTINCT to COUNT over one scalar argument. */
+    distinct(): AggregateExpressionWrapper<TCtx, TValue>;
+    /** Turns the aggregate into a window over the given partition and ordering. */
+    over(configure?: OverConfigure<TCtx>): ExpressionWrapper<TValue>;
+}
+/** A COALESCE argument: a column reference or any wrapped expression. */
+type CoalesceArg<TCtx> = ColumnReference<TCtx> | ExpressionWrapper<unknown>;
+type CoalesceArgValue<TCtx, TArg> = TArg extends ExpressionWrapper<infer TValue> ? TValue : TArg extends string ? ReferencedValue<TCtx, TArg> : never;
+/**
+ * The union of the operand value types; null stays only when the final fallback is itself
+ * nullable, matching COALESCE's first-non-null semantics.
+ */
+type CoalesceValue<TCtx, TArgs extends readonly unknown[]> = TArgs extends readonly [
+    ...unknown[],
+    infer TLast
+] ? Exclude<CoalesceArgValue<TCtx, TArgs[number]>, null> | Extract<CoalesceArgValue<TCtx, TLast>, null> : CoalesceArgValue<TCtx, TArgs[number]>;
+export interface FunctionModule<in out TCtx> {
+    /** COUNT(argument); counts non-null values. */
+    count(reference: ColumnReference<TCtx> | ExpressionWrapper<unknown>): AggregateExpressionWrapper<TCtx, number>;
+    /** COUNT(*). */
+    countAll(): AggregateExpressionWrapper<TCtx, number>;
+    sum(reference: ColumnReferenceOf<TCtx, number> | ExpressionWrapper<number | null>): AggregateExpressionWrapper<TCtx, number | null>;
+    avg(reference: ColumnReferenceOf<TCtx, number> | ExpressionWrapper<number | null>): AggregateExpressionWrapper<TCtx, number | null>;
+    min<TRef extends ColumnReference<TCtx>>(reference: TRef): AggregateExpressionWrapper<TCtx, ReferencedValue<TCtx, TRef & string> | null>;
+    min<TValue>(expression: ExpressionWrapper<TValue>): AggregateExpressionWrapper<TCtx, TValue | null>;
+    max<TRef extends ColumnReference<TCtx>>(reference: TRef): AggregateExpressionWrapper<TCtx, ReferencedValue<TCtx, TRef & string> | null>;
+    max<TValue>(expression: ExpressionWrapper<TValue>): AggregateExpressionWrapper<TCtx, TValue | null>;
+    round(value: ArithmeticOperand<TCtx>, digits?: number): ExpressionWrapper<number | null>;
+    coalesce<TArgs extends readonly [CoalesceArg<TCtx>, ...Array<CoalesceArg<TCtx>>]>(...values: TArgs): ExpressionWrapper<CoalesceValue<TCtx, TArgs>>;
+    dateTrunc(unit: "year" | "month" | "day" | "hour" | "minute" | "second", value: ColumnReferenceOf<TCtx, Date> | Date | ExpressionWrapper<Date | null>): ExpressionWrapper<Date | null>;
+    /**
+     * Document-level BM25 relevance of the query against the listed columns ("*" = every
+     * non-boolean column of the scanned table), compiling to the same node as SQL
+     * `BM25(col, ...) AGAINST 'query'`. 0 when no term matches; null when every column is null.
+     */
+    bm25(columns: "*" | ReadonlyArray<ColumnReferenceOf<TCtx, string | number | Date> & string>, query: string): ExpressionWrapper<number | null>;
+}
+/** Shared by eb.match and fn.bm25: validates and assembles the full-text plan node. */
+export declare function buildFtsExpression(op: "match" | "bm25", columns: "*" | readonly string[], query: string): Expression;
+interface CaseBranch {
+    when: ExpressionSource;
+    then: ExpressionSource;
+}
+export declare class CaseThenBuilder<in out TCtx, out TValue> {
+    private readonly branches;
+    private readonly pendingWhen;
+    constructor(branches: readonly CaseBranch[], pendingWhen: ExpressionSource);
+    then<TNext extends QueryValue>(value: TNext | ExpressionWrapper<TNext>): CaseBuilder<TCtx, TValue | TNext>;
+}
+export declare class CaseBuilder<in out TCtx, out TValue = never> {
+    private readonly branches;
+    constructor(branches?: readonly CaseBranch[]);
+    when(condition: ExpressionWrapper<SqlBool>): CaseThenBuilder<TCtx, TValue>;
+    when<TRef extends ColumnReference<TCtx>>(lhs: TRef, operator: ComparisonOperatorToken | LikeOperatorToken, rhs: ValueOperand<ReferencedValue<TCtx, TRef & string>>): CaseThenBuilder<TCtx, TValue>;
+    else<TNext extends QueryValue>(value: TNext | ExpressionWrapper<TNext>): CaseEndBuilder<TValue | TNext>;
+    end(): ExpressionWrapper<TValue | null>;
+}
+export declare class CaseEndBuilder<out TValue> {
+    private readonly branches;
+    private readonly otherwise;
+    constructor(branches: readonly CaseBranch[], otherwise: ExpressionSource);
+    end(): ExpressionWrapper<TValue>;
+}
+export interface ExpressionBuilder<in out DB, in out TCtx> {
+    /** Compares a column (or expression) to a value; string left-hand sides are references. */
+    <TRef extends ColumnReference<TCtx> & string>(lhs: TRef, operator: ComparisonOperatorToken, rhs: ValueOperand<ReferencedValue<TCtx, TRef>>): ExpressionWrapper<SqlBool>;
+    (lhs: ExpressionWrapper<unknown>, operator: ComparisonOperatorToken, rhs: QueryValue | ExpressionWrapper<unknown> | ScalarSubquery<unknown>): ExpressionWrapper<SqlBool>;
+    (lhs: ColumnReference<TCtx> | ExpressionWrapper<string | null>, operator: LikeOperatorToken, rhs: string | ExpressionWrapper<string | null>): ExpressionWrapper<SqlBool>;
+    <TRef extends ColumnReference<TCtx> & string>(lhs: TRef, operator: InOperatorToken, rhs: ReadonlyArray<ReferencedValue<TCtx, TRef> | ExpressionWrapper<unknown>> | ScalarSubquery<ReferencedValue<TCtx, TRef>>): ExpressionWrapper<SqlBool>;
+    (lhs: ColumnReference<TCtx> | ExpressionWrapper<unknown>, operator: IsOperatorToken, rhs: null): ExpressionWrapper<SqlBool>;
+    (lhs: ArithmeticOperand<TCtx>, operator: ArithmeticOperatorToken, rhs: ArithmeticOperand<TCtx>): ExpressionWrapper<number>;
+    /** ANDs conditions left to right. */
+    and(conditions: ReadonlyArray<ExpressionWrapper<SqlBool>>): ExpressionWrapper<SqlBool>;
+    /** ORs conditions left to right. */
+    or(conditions: ReadonlyArray<ExpressionWrapper<SqlBool>>): ExpressionWrapper<SqlBool>;
+    not(condition: ExpressionWrapper<SqlBool>): ExpressionWrapper<SqlBool>;
+    /** `lhs BETWEEN lower AND upper`, desugared exactly as the parser does. */
+    between<TRef extends ColumnReference<TCtx>>(reference: TRef | ExpressionWrapper<unknown>, lower: ValueOperand<ReferencedValue<TCtx, TRef & string>>, upper: ValueOperand<ReferencedValue<TCtx, TRef & string>>): ExpressionWrapper<SqlBool>;
+    notBetween<TRef extends ColumnReference<TCtx>>(reference: TRef | ExpressionWrapper<unknown>, lower: ValueOperand<ReferencedValue<TCtx, TRef & string>>, upper: ValueOperand<ReferencedValue<TCtx, TRef & string>>): ExpressionWrapper<SqlBool>;
+    exists(subquery: BlockCompilable): ExpressionWrapper<SqlBool>;
+    /**
+     * Document-level full-text MATCH, compiling to the same node as SQL
+     * `MATCH(col, ...) AGAINST 'query'`: every query term must appear in some listed column
+     * ("*" searches every non-boolean column of the scanned table); a term ending in `*`
+     * matches prefixes. Rows whose listed columns are all null are unknown, like LIKE on null.
+     */
+    match(columns: "*" | ReadonlyArray<ColumnReferenceOf<TCtx, string | number | Date> & string>, query: string): ExpressionWrapper<SqlBool>;
+    /** A column reference as an expression, for the rare value-position column comparison. */
+    ref<TRef extends ColumnReference<TCtx>>(reference: TRef): ExpressionWrapper<ReferencedValue<TCtx, TRef & string>>;
+    /** A literal value as an expression. */
+    val<TValue extends QueryValue>(value: TValue): ExpressionWrapper<TValue>;
+    /** Arithmetic negation. */
+    neg(value: ArithmeticOperand<TCtx>): ExpressionWrapper<number>;
+    case(): CaseBuilder<TCtx>;
+    rowNumber(): WindowFunctionBuilder<TCtx>;
+    rank(): WindowFunctionBuilder<TCtx>;
+    denseRank(): WindowFunctionBuilder<TCtx>;
+    /** Starts a correlated or uncorrelated subquery over the database plus the outer scope. */
+    selectFrom<TE extends TableExpression<DB>>(table: TE): SelectQueryBuilder<DB, ContextWithTable<DB, TCtx, TE>, Record<never, unknown>>;
+    fn: FunctionModule<TCtx>;
+}
+/**
+ * Creates the callable expression builder. The subquery factory is injected by the select
+ * builder module, which owns both sides of that recursion.
+ */
+export declare function createExpressionBuilder<DB, TCtx>(createSubquery: (table: string) => unknown): ExpressionBuilder<DB, TCtx>;
+export {};
+//# sourceMappingURL=expression.d.ts.map