tempest-db-js 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -18,12 +18,26 @@ interface OrderTerm {
     readonly column: string;
     readonly direction: SortDirection;
 }
+/** One aggregate expression in a grouped SELECT (`COUNT(*) AS "n"`). */
+interface AggregateTerm {
+    readonly fn: "count" | "sum" | "avg" | "min" | "max";
+    /** The column to aggregate, or `"*"` (only valid for `count`). */
+    readonly column: string | "*";
+    /** The result alias. */
+    readonly alias: string;
+}
 /** Serializable AST for a SELECT. Dialects (Phase 4) compile this to SQL. */
 interface SelectNode {
     readonly kind: "select";
     readonly table: string;
     /** Projected columns, or "*" for the whole row. */
     readonly columns: readonly string[] | "*";
+    /** Emit `SELECT DISTINCT` when true. */
+    readonly distinct: boolean;
+    /** Aggregate expressions; when non-empty, this is a grouped/aggregate query. */
+    readonly aggregates: readonly AggregateTerm[];
+    /** `GROUP BY` columns. */
+    readonly groupBy: readonly string[];
     readonly where: CondNode | undefined;
     readonly orderBy: readonly OrderTerm[];
     readonly limit: number | undefined;
@@ -83,6 +97,29 @@ type WhereInput<Row = Record<string, unknown>> = {
 declare const OPERATORS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "like", "ilike", "in", "notIn", "between", "isNull"];
 /** One supported operator name. */
 type Operator = (typeof OPERATORS)[number];
+/** An aggregate expression carrying its result type `T` as a phantom. */
+declare class Agg<T> {
+    readonly fn: AggregateTerm["fn"];
+    readonly column: string | "*";
+    readonly __t: T;
+    constructor(fn: AggregateTerm["fn"], column: string | "*");
+}
+/** `COUNT(*)` — the number of rows in the group (never null). */
+declare function count(): Agg<number>;
+/** `SUM(column)` — null when the group has no non-null values. */
+declare function sum(column: string): Agg<number | null>;
+/** `AVG(column)` — null when the group has no non-null values. */
+declare function avg(column: string): Agg<number | null>;
+/** `MIN(column)` — numeric columns; null on an empty group. */
+declare function min(column: string): Agg<number | null>;
+/** `MAX(column)` — numeric columns; null on an empty group. */
+declare function max(column: string): Agg<number | null>;
+/** Extract the phantom result type of an aggregate expression. */
+type AggResult<A> = A extends Agg<infer T> ? T : never;
+/** Flatten an intersection into a single object literal. */
+type SimplifyProj<T> = {
+    [K in keyof T]: T[K];
+} & {};
 /**
  * Immutable, chainable SELECT builder.
  *
@@ -101,6 +138,27 @@ declare class SelectBuilder<Full, Proj = Full> {
     private with;
     /** Add a WHERE filter: the object form (keys typed) or an `and`/`or`/`not`. */
     where(input: WhereInput<Full> | Condition): SelectBuilder<Full, Proj>;
+    /** Emit `SELECT DISTINCT` — drop duplicate rows. */
+    distinct(): SelectBuilder<Full, Proj>;
+    /**
+     * Group by columns and compute aggregates. The result row is the grouped
+     * columns (typed from the model) plus one field per aggregate alias.
+     *
+     * @param groupBy The columns to group by (checked against the model). Pass `[]`
+     *   for a whole-table aggregate.
+     * @param spec A map of result alias → aggregate expression ({@link count},
+     *   {@link sum}, {@link avg}, {@link min}, {@link max}).
+     * @returns A builder whose row is `Pick<Full, K> & { [alias]: aggResult }`.
+     *
+     * @example
+     * ```ts
+     * select(Order).aggregate(["status"], { n: count(), total: sum("amount") });
+     * // rows: { status: string; n: number; total: number | null }[]
+     * ```
+     */
+    aggregate<K extends keyof Full & string, S extends Record<string, Agg<unknown>>>(groupBy: readonly K[], spec: S): SelectBuilder<Full, SimplifyProj<Pick<Full, K> & {
+        [A in keyof S]: AggResult<S[A]>;
+    }>>;
     /** Order by a column of `Full`. */
     orderBy(column: keyof Full & string, direction?: SortDirection): SelectBuilder<Full, Proj>;
     /** Limit the number of rows. */
@@ -177,12 +235,23 @@ declare function not<Row = Record<string, unknown>>(input: WhereArg<NoInfer<Row>
 
 /** Columns to return from a mutation, or "*" for the whole row. */
 type Returning = readonly string[] | "*" | null;
+/**
+ * Conflict-resolution clause for an INSERT (`ON CONFLICT`). `target` is the
+ * conflicting column(s) (a unique/PK constraint); `update` is `"nothing"` for
+ * `DO NOTHING`, or the columns to overwrite for `DO UPDATE SET`.
+ */
+interface OnConflict {
+    readonly target: readonly string[];
+    readonly update: Record<string, unknown> | "nothing";
+}
 /** Serializable AST for an INSERT. */
 interface InsertNode {
     readonly kind: "insert";
     readonly table: string;
     readonly values: readonly Record<string, unknown>[];
     readonly returning: Returning;
+    /** Conflict handling (`ON CONFLICT ...`), or `undefined` for none. */
+    readonly onConflict?: OnConflict;
 }
 /**
  * INSERT builder.
@@ -202,6 +271,19 @@ declare class InsertBuilder<Full, Ins, Ret = number> {
     private with;
     /** Provide one row or many rows to insert, typed by the insert shape. */
     values(rows: Ins | readonly Ins[]): InsertBuilder<Full, Ins, Ret>;
+    /**
+     * On a unique/PK conflict on `target`, do nothing (skip the row).
+     *
+     * @param target The conflicting column(s) — a unique or primary key.
+     */
+    onConflictDoNothing(target: readonly (keyof Full & string)[]): InsertBuilder<Full, Ins, Ret>;
+    /**
+     * On a unique/PK conflict on `target`, overwrite the given columns (upsert).
+     *
+     * @param target The conflicting column(s) — a unique or primary key.
+     * @param set The columns to update with new values.
+     */
+    onConflictDoUpdate(target: readonly (keyof Full & string)[], set: Partial<Full>): InsertBuilder<Full, Ins, Ret>;
     /** Return the full inserted row(s). */
     returning(): InsertBuilder<Full, Ins, Full>;
     /** Return only the given columns of the inserted row(s). */
@@ -420,8 +502,20 @@ interface JoinSelection {
     readonly alias: string;
     readonly column: string;
 }
-/** `where` filter for a join: keys are `alias.column` refs (object form). */
-type JoinWhereInput = Record<string, unknown>;
+/** Collapse a union of object types into their intersection. */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * `where` filter for a join. Keys are `alias.column` refs; each value accepts a
+ * bare value (shorthand for `eq`) or an operator object restricted to the
+ * operators valid for that column's type — exactly like the single-table
+ * {@link WhereInput}, but qualified per source. `like` on a numeric join column,
+ * or `gt` on a string one, is a compile error.
+ */
+type JoinWhereInput<S extends Sources> = Partial<UnionToIntersection<{
+    [A in keyof S]: {
+        [C in keyof NonNullable<S[A]> & string as `${A & string}.${C}`]: NonNullable<S[A]>[C] | OperatorsFor<NonNullable<NonNullable<S[A]>[C]>>;
+    };
+}[keyof S]>>;
 /** Serializable AST for a multi-table SELECT. */
 interface JoinNode {
     readonly kind: "join_select";
@@ -476,7 +570,7 @@ declare class JoinBuilder<S extends Sources> {
         [K in A]: InferModel<C> | null;
     }>;
     /** Filter by `alias.column` references (object form) or an `and`/`or`/`not`. */
-    where(input: Partial<Record<ColRef<S>, unknown>> | Condition): JoinBuilder<S>;
+    where(input: JoinWhereInput<S> | Condition): JoinBuilder<S>;
     /** Order by an `alias.column` reference. */
     orderBy(ref: ColRef<S>, direction?: SortDirection): JoinBuilder<S>;
     limit(n: number): JoinBuilder<S>;
@@ -517,11 +611,26 @@ type QueryNode = SelectNode | InsertNode | UpdateNode | DeleteNode | JoinNode;
  */
 declare abstract class BaseDialect {
     abstract readonly name: "sqlite" | "postgresql";
+    /**
+     * INSERT SQL templates keyed by structure (dialect|table|columns|rowCount|
+     * returning). Shared across dialect instances — the key namespaces by dialect
+     * name, and the placeholder text is dialect-specific but structure-determined.
+     */
+    private static readonly insertTemplates;
+    /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
+    private static readonly quotedIds;
     /** Render the n-th (1-based) placeholder. */
     protected abstract placeholder(index: number): string;
     /** Render a case-insensitive LIKE for the active dialect. */
     protected abstract ilike(column: string, param: string): string;
-    /** Quote an identifier (column/table) for the active dialect. */
+    /**
+     * Quote an identifier (column/table) for the active dialect.
+     *
+     * Memoized: identifiers form a small, stable set (column/table names), but this
+     * runs for every identifier on every compile. Caching the quoted form removes a
+     * regex-replace + string allocation from the hot path. The standard double-quote
+     * form is identical across both dialects, so one shared cache is correct.
+     */
     protected quoteId(name: string): string;
     /** Compile any node to `{ sql, params }`. */
     compile(node: QueryNode): CompiledQuery;
@@ -529,6 +638,15 @@ declare abstract class BaseDialect {
     private qualify;
     private compileSelect;
     private compileInsert;
+    /**
+     * The INSERT SQL template for a given structure, cached across calls.
+     *
+     * The text depends only on (dialect, table, columns, row count, returning,
+     * conflict shape) — never on the bound values — and placeholder positions are
+     * deterministic from the counts (a fresh statement always starts binding at 1).
+     * So a per-row insert loop compiles the string once and reuses it every row.
+     */
+    private insertTemplate;
     private compileUpdate;
     private compileDelete;
     private compileJoin;
@@ -576,14 +694,35 @@ interface AsyncDriver {
     execute(sql: string, params: readonly unknown[]): Promise<DriverResult>;
     /** Lazily iterate rows (for `.stream()`), if the driver supports it. */
     iterate?(sql: string, params: readonly unknown[]): AsyncIterableIterator<Record<string, unknown>>;
+    /**
+     * Reserve a single pinned connection for the duration of a transaction.
+     * Pooled drivers (PostgreSQL) MUST implement this so `BEGIN`/`COMMIT` and the
+     * statements between them all run on the same connection. Single-connection
+     * drivers (SQLite) may omit it — `transaction` then runs on the shared handle.
+     */
+    reserve?(): Promise<ReservedAsyncDriver>;
     close(): Promise<void>;
 }
+/** An {@link AsyncDriver} pinned to one connection, used inside a transaction. */
+interface ReservedAsyncDriver extends AsyncDriver {
+    /** Return the pinned connection to the pool. */
+    release(): Promise<void>;
+}
 /** SQLite driver backed by Node's built-in `node:sqlite` (zero install). */
 declare class NodeSqliteDriver implements SyncDriver {
     private readonly db;
+    /**
+     * Prepared-statement cache keyed by SQL text. tempest-db-js always
+     * parameterizes, so a query shape maps to one stable SQL string — reusing the
+     * compiled statement avoids re-`prepare()` on every call (the dominant cost of
+     * per-row inserts and point lookups).
+     */
+    private readonly statements;
     constructor(database: any);
     /** Open a `node:sqlite` database at the given path (or `:memory:`). */
     static open(path: string): NodeSqliteDriver;
+    /** Return the cached prepared statement for `sql`, preparing it on first use. */
+    private prepare;
     execute(sql: string, params: readonly unknown[]): DriverResult;
     iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
     close(): void;
@@ -607,6 +746,34 @@ type RowOf<B> = B extends {
 declare class NoResultError extends Error {
     constructor(message: string);
 }
+/**
+ * Raised when the driver rejects a statement. Wraps the original driver error
+ * and attaches the offending SQL and its bound parameters, so a failure points
+ * at the exact query instead of an opaque driver message.
+ */
+declare class QueryExecutionError extends Error {
+    /** The original error thrown by the driver. */
+    readonly cause: unknown;
+    /** The SQL that failed. */
+    readonly sql: string;
+    /** The bound parameters, in order. */
+    readonly params: readonly unknown[];
+    constructor(
+    /** The original error thrown by the driver. */
+    cause: unknown, 
+    /** The SQL that failed. */
+    sql: string, 
+    /** The bound parameters, in order. */
+    params: readonly unknown[]);
+}
+/**
+ * A hook invoked for every statement a session runs (query logging / tracing).
+ * Errors thrown by the logger are ignored so logging never breaks execution.
+ */
+type QueryLogger = (event: {
+    readonly sql: string;
+    readonly params: readonly unknown[];
+}) => void;
 /** Synchronous result view over already-fetched rows. */
 declare class SyncResult<Row> {
     private readonly rows;
@@ -636,7 +803,13 @@ declare class AsyncResult<Row> {
 declare class SyncSession {
     private readonly driver;
     private readonly dialect;
-    constructor(driver: SyncDriver, dialect: BaseDialect);
+    /** Optional per-statement logger (query tracing). */
+    private readonly logger?;
+    constructor(driver: SyncDriver, dialect: BaseDialect, 
+    /** Optional per-statement logger (query tracing). */
+    logger?: QueryLogger | undefined);
+    /** Log, run, and error-wrap one raw statement. */
+    private exec;
     /** Compile, run, and coerce a builder into a result. */
     execute<B extends Executable>(builder: B): SyncResult<RowOf<B>>;
     /** Run `fn` inside a transaction: commit on success, rollback on throw. */
@@ -649,17 +822,27 @@ declare class SyncSession {
      */
     stream<B extends Executable>(builder: B): IterableIterator<RowOf<B>>;
     close(): void;
+    /** `using session = ...` closes the driver when the scope exits. */
+    [Symbol.dispose](): void;
 }
 /** An asynchronous unit of work. */
 declare class AsyncSession {
     private readonly driver;
     private readonly dialect;
-    constructor(driver: AsyncDriver, dialect: BaseDialect);
+    /** Optional per-statement logger (query tracing). */
+    private readonly logger?;
+    constructor(driver: AsyncDriver, dialect: BaseDialect, 
+    /** Optional per-statement logger (query tracing). */
+    logger?: QueryLogger | undefined);
+    /** Log, run, and error-wrap one raw statement. */
+    private exec;
     execute<B extends Executable>(builder: B): AsyncResult<RowOf<B>>;
     /** Lazily iterate result rows. Uses driver streaming when available. */
     stream<B extends Executable>(builder: B): AsyncIterableIterator<RowOf<B>>;
     transaction<T>(fn: (tx: AsyncSession) => Promise<T>): Promise<T>;
     close(): Promise<void>;
+    /** `await using session = ...` closes the driver when the scope exits. */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /** Connection-pool tuning (PostgreSQL; ignored by SQLite). */
 interface PoolOptions {
@@ -676,24 +859,35 @@ interface EngineOptions {
     readonly driver?: string;
     /** Connection-pool tuning (PostgreSQL only). */
     readonly pool?: PoolOptions;
+    /**
+     * Called for every statement a session runs — SQL + bound params. Use for
+     * query logging/tracing. Thrown errors are swallowed so it never breaks a query.
+     */
+    readonly onQuery?: QueryLogger;
 }
 /** A synchronous engine (SQLite only). */
 declare class SyncEngine {
     private readonly driver;
+    private readonly logger?;
     readonly dialect: Dialect;
-    constructor(driver: SyncDriver);
+    constructor(driver: SyncDriver, logger?: QueryLogger | undefined);
     session(): SyncSession;
     transaction<T>(fn: (tx: SyncSession) => T): T;
     close(): void;
+    /** `using engine = createSyncEngine(...)` closes the pool when the scope exits. */
+    [Symbol.dispose](): void;
 }
 /** An asynchronous engine. */
 declare class AsyncEngine {
     private readonly driver;
     readonly dialect: Dialect;
-    constructor(driver: AsyncDriver, dialect: Dialect);
+    private readonly logger?;
+    constructor(driver: AsyncDriver, dialect: Dialect, logger?: QueryLogger | undefined);
     session(): AsyncSession;
     transaction<T>(fn: (tx: AsyncSession) => Promise<T>): Promise<T>;
     close(): Promise<void>;
+    /** `await using engine = createEngine(...)` closes the pool when the scope exits. */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * Create a **synchronous** engine from a database URL. SQLite only — PostgreSQL
@@ -785,6 +979,91 @@ declare class BaseRepository<C extends ModelClass> {
     paginate(filter?: PaginationFilter<InferModel<C>>): Promise<PaginationResult<InferModel<C>>>;
 }
 
+/**
+ * tempest-db-js — opt-in active-record layer.
+ *
+ * The library's default return shape is a plain inferred object (a locked design
+ * decision — see the roadmap). This module adds an **opt-in** wrapper for code
+ * that prefers instance methods: `ActiveRecord` holds the plain row on `.data`
+ * and exposes `save` / `update` / `delete` / `reload` over an async session. It
+ * never replaces the default plain-object return — you reach for it explicitly.
+ */
+
+/**
+ * An opt-in active-record wrapper around a single row.
+ *
+ * The current field values live on {@link data} (a plain, typed row object).
+ * Mutating methods persist through the bound session and refresh `data`.
+ *
+ * @typeParam C - the model class.
+ */
+declare class ActiveRecord<C extends ModelClass> {
+    private readonly model;
+    private readonly session;
+    /** The current field values (a plain, typed row). */
+    data: InferModel<C>;
+    private readonly pk;
+    constructor(model: C, session: AsyncSession, 
+    /** The current field values (a plain, typed row). */
+    data: InferModel<C>);
+    /** The primary-key value of the wrapped row. */
+    private pkValue;
+    private pkFilter;
+    /**
+     * Persist the current `data` — insert if new, otherwise overwrite the existing
+     * row (upsert on the primary key). Refreshes `data` from the returned row.
+     *
+     * @returns This wrapper, for chaining.
+     */
+    save(): Promise<this>;
+    /**
+     * Update the given columns for this row and merge them into `data`.
+     *
+     * @param patch The columns to change.
+     * @returns This wrapper, for chaining.
+     */
+    update(patch: Partial<InferModel<C>>): Promise<this>;
+    /**
+     * Delete this row.
+     *
+     * @returns The number of rows affected (0 or 1).
+     */
+    delete(): Promise<number>;
+    /**
+     * Re-fetch this row by primary key and refresh `data`.
+     *
+     * @returns This wrapper, for chaining.
+     * @throws When the row no longer exists.
+     */
+    reload(): Promise<this>;
+}
+/** A small factory binding a model + session for producing {@link ActiveRecord}s. */
+interface ActiveRecordManager<C extends ModelClass> {
+    /** Wrap an existing row (already loaded) as an active record. */
+    wrap(row: InferModel<C>): ActiveRecord<C>;
+    /** Build an unsaved active record from insert data; call `.save()` to persist. */
+    create(data: InferInsert<C>): ActiveRecord<C>;
+    /** Fetch a row by primary key and wrap it, or `null` if absent. */
+    get(id: unknown): Promise<ActiveRecord<C> | null>;
+}
+/**
+ * Create an {@link ActiveRecordManager} for a model over a session.
+ *
+ * @param model The model class.
+ * @param session The async session to persist through.
+ * @returns A manager that wraps/fetches rows as active records.
+ *
+ * @example
+ * ```ts
+ * const users = activeRecord(User, engine.session());
+ * const u = users.create({ name: "Ana", age: 30 });
+ * await u.save();
+ * await u.update({ age: 31 });
+ * await u.delete();
+ * ```
+ */
+declare function activeRecord<C extends ModelClass>(model: C, session: AsyncSession): ActiveRecordManager<C>;
+
 /**
  * tempest-db-js — typed relations (hasMany / belongsTo) with eager loading.
  *
@@ -1031,8 +1310,12 @@ declare abstract class Model {
  * Instantiates the class once and collects every field that is a `Column`. Used
  * by the serialization layer and (Phase 6) the migration schema reflector.
  *
+ * The result is **memoized per class** — a model's columns never change at
+ * runtime, and this is called once per row on hot read paths (coercion, joins),
+ * so re-instantiating the class every time would dominate large result sets.
+ *
  * @param model The model class (subclass of `Model`).
- * @returns A record of column name → `Column` instance.
+ * @returns A record of column name → `Column` instance (do not mutate).
  */
 declare function columnsOf(model: ModelClass): Record<string, Column<unknown>>;
 /** Pull the static type out of a Column. */
@@ -1081,4 +1364,4 @@ type InferInsert<C extends ModelClass> = Simplify<{
     [K in Exclude<ColumnKeys<InstanceType<C>>, OptionalInsertKeys<InstanceType<C>>>]: ColValue<InstanceType<C>[K]>;
 }>;
 
-export { type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, Model, type ModelClass, NoResultError, NodeSqliteDriver, OPERATORS, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, type QueryNode, RecordNotFound, type Relation, type RelationValue, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, SqliteDialect, type SyncDriver, SyncEngine, SyncResult, SyncSession, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, and, belongsTo, column, columnsOf, createEngine, createSyncEngine, del, detectDialect, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, not, or, parse, parseDatabaseUrl, select, sql, stringify, toCondNode, toDict, toJSON, update };
+export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, Model, type ModelClass, NoResultError, NodeSqliteDriver, OPERATORS, type OnConflict, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, SqliteDialect, type SyncDriver, SyncEngine, SyncResult, SyncSession, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, update };