@nextlyhq/adapter-drizzle 0.0.2-alpha.65 → 0.0.2-alpha.67

package/dist/{adapter-C6ENLDau.d.cts → adapter-bUAaPzjV.d.cts}

@@ -1,9 +1,51 @@
 import { AnyRelations, SQL } from 'drizzle-orm';
-import { T as TransactionContext, S as SelectOptions, W as WhereClause, U as UpdateOptions, D as DeleteOptions, e as UpsertOptions, f as TransactionOptions, g as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, a as Migration, d as MigrationResult } from './migration-B6AmjCQ1.cjs';
+import { T as TransactionContext, S as SelectOptions, W as WhereClause, D as DeleteOptions, U as UpsertOptions, e as TransactionOptions, f as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, g as UpdateOptions, a as Migration, d as MigrationResult } from './migration-Bu0WLdX4.cjs';
 import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.cjs';
 import { T as TableDefinition, C as CreateTableOptions, D as DropTableOptions, A as AlterTableOperation, a as AlterTableOptions } from './schema-BDn8WfSL.cjs';
 import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.cjs';
 
+/**
+ * A pooled adapter's Drizzle transactions, each on a connection the adapter
+ * checks out and returns itself.
+ *
+ * Drizzle's own `transaction()` on a pool checks a connection out, but does
+ * not return it as carefully as the adapter's `transaction()` does: it sends
+ * BEGIN outside its `try`, so a failed BEGIN never gives the connection back;
+ * and when its ROLLBACK fails it hands the connection to the pool as if
+ * nothing had happened, possibly still inside the transaction, and throws the
+ * ROLLBACK's error in place of the work's. Core services open their
+ * transactions through that handle, so it gets the same care here: Drizzle
+ * runs the transaction on a connection this module owns, and this module
+ * decides how the connection goes back.
+ *
+ * @module pinned-transaction
+ */
+/**
+ * Drizzle's database handle, as far as running a transaction goes.
+ *
+ * The callback takes `unknown` and the options `never`, so every dialect's
+ * handle fits, whose callback receives its own transaction type and whose
+ * options are its own.
+ */
+interface DrizzleTransactor {
+    transaction<T>(work: (tx: unknown) => Promise<T>, config?: never): Promise<T>;
+}
+/** One connection a pooled adapter checked out for one transaction. */
+interface PinnedConnection {
+    /** Drizzle bound to this connection alone, with the handle's relations. */
+    drizzle: DrizzleTransactor;
+    /**
+     * Sends ROLLBACK on this connection. Harmless when no transaction is open
+     * on it: PostgreSQL answers with a warning, MySQL does nothing.
+     */
+    rollback(): Promise<unknown>;
+    /**
+     * Gives the connection back: to the pool, or, when `dirty`, closed and
+     * removed from it, because it may still be inside the transaction.
+     */
+    release(dirty: boolean): void;
+}
+
 /**
  * Transaction CRUD forwarder helper for database adapters.
  *
@@ -21,15 +63,20 @@ import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.cjs
 interface TransactionCrudDelegator {
     select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
     selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
-    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions, executor?: unknown): Promise<T[]>;
     updateCount(table: string, data: Record<string, unknown>, where: WhereClause, executor?: unknown): Promise<number>;
     delete(table: string, where: WhereClause, options?: DeleteOptions, executor?: unknown): Promise<number>;
     upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
 }
 /**
  * Transaction context CRUD methods provided by the forwarder.
+ *
+ * `update` is not among them. The pooled `update` goes through the Drizzle
+ * query builder, which writes the columns the runtime model declares; a
+ * transaction's update must reach the columns the physical table has, and
+ * each adapter binds the base class's `transactionUpdate` beside its
+ * transactional `insert`.
  */
-type TransactionCrudForwarders = Pick<TransactionContext, "select" | "selectOne" | "update" | "updateCount" | "delete" | "upsert" | "getDrizzle">;
+type TransactionCrudForwarders = Pick<TransactionContext, "select" | "selectOne" | "updateCount" | "delete" | "upsert" | "getDrizzle">;
 
 /**
  * Base database adapter abstract class.
@@ -112,6 +159,122 @@ declare abstract class DrizzleAdapter {
      * @throws The callback's own error, unchanged, when it carries that brand
      */
     abstract transaction<T>(callback: (ctx: TransactionContext) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Whether a `transaction()` call made from the current async context would
+     * join a transaction already open on this adapter, as a savepoint, rather
+     * than open one of its own.
+     *
+     * A caller about to do something no rollback can undo — removing a stored
+     * file, say — asks this first: work that joins an enclosing transaction is
+     * undone with it, while the effect it performs after its own savepoint
+     * releases is not.
+     *
+     * False here. Concrete rather than abstract so existing adapters keep
+     * working unchanged, and false is right for a pooled adapter: a call made
+     * inside another transaction's work opens its own transaction on its own
+     * connection, which commits independently.
+     *
+     * @returns True when the call would nest in an open transaction
+     */
+    inTransaction(): boolean;
+    /**
+     * The transaction each async flow is inside, kept per flow rather than per
+     * connection: on SQLite every request shares the one connection, and
+     * another request's open transaction says nothing about this one.
+     */
+    private readonly flowTransactions;
+    /**
+     * Whether the calling async flow is inside a transaction on this adapter
+     * that has not finished: its own, or one it was started from inside.
+     *
+     * A write that must outlive any rollback — a count of a failed attempt, the
+     * spend of a single-use secret — asks this before running in a transaction
+     * of its own. Made inside an open transaction on SQLite, it joins that
+     * transaction as a savepoint and is undone with it. On PostgreSQL and MySQL
+     * it would commit on a connection of its own, so refusing it there too
+     * keeps code that passes on one dialect from failing on another. Unlike
+     * {@link inTransaction}, which asks whether a call would nest and is always
+     * false on a pooled adapter, this answers alike on every dialect, and
+     * another flow's open transaction never answers true.
+     *
+     * Covers transactions opened through {@link transaction} and through the
+     * Drizzle handle's own `transaction` on the dialects whose handle takes
+     * async work. A dialect that keeps scopes of its own judges from those
+     * instead; an adapter that does neither answers false.
+     *
+     * @experimental
+     * @returns True while a transaction the calling flow is inside is open
+     */
+    transactionOpenInFlow(): boolean;
+    /**
+     * Run a whole transaction, from its BEGIN until its COMMIT or ROLLBACK has
+     * run, as the calling flow's open transaction, for
+     * {@link transactionOpenInFlow}. A dialect's `transaction` runs through
+     * this unless it judges the flow from scopes of its own.
+     *
+     * The transaction counts as open for its work and for anything the work
+     * starts, awaited or not, until it has finished. Something the work starts
+     * that outlives it then sees it closed, or the one enclosing it still open.
+     *
+     * @param run - The transaction, BEGIN to COMMIT or ROLLBACK
+     * @returns What `run` resolves to
+     */
+    protected runInFlowTransaction<T>(run: () => Promise<T>): Promise<T>;
+    /**
+     * Run each of a pool-bound Drizzle handle's transactions on a connection
+     * `checkout` hands it, and return that connection as the adapter's own
+     * `transaction()` does: closed rather than pooled when no ROLLBACK can be
+     * confirmed on it, and never leaked by a failed BEGIN (`pinTransactions`).
+     *
+     * For PostgreSQL's and MySQL's handles. Apply it before
+     * {@link trackFlowTransactions}, which wraps whatever `transaction` the
+     * handle has at that point.
+     *
+     * @param db - A Drizzle handle on this adapter's pool
+     * @param checkout - Checks out a connection for one transaction
+     * @returns The same handle, its `transaction` replaced
+     */
+    protected pinDrizzleTransactions<D extends DrizzleTransactor>(db: D, checkout: () => Promise<PinnedConnection>): D;
+    /**
+     * Make a Drizzle handle's own `transaction` count for
+     * {@link transactionOpenInFlow}, as the adapter's does.
+     *
+     * Core's services run their transactions through the handle on PostgreSQL
+     * and MySQL; without this, a call made inside one would be refused on
+     * SQLite, where they go through the adapter, and let through on the
+     * others. Not for SQLite's handle: its `transaction` takes only
+     * synchronous work, which no async flow can be inside.
+     *
+     * @param db - A Drizzle handle this adapter created
+     * @returns The same handle, its `transaction` tracked
+     */
+    protected trackFlowTransactions<D extends DrizzleTransactor>(db: D): D;
+    /**
+     * Run `effect` once the write made from the current async context has
+     * committed: an event, a hook, a cache flush, anything outside the database
+     * that must not happen for a change that is rolled back.
+     *
+     * A caller invokes this after its own transaction has resolved. Where that
+     * transaction was nested in an enclosing one, as a savepoint, the change is
+     * not durable yet, and an adapter that nests (see {@link inTransaction})
+     * holds `effect` until the outermost transaction commits, and drops it when
+     * that transaction, or the savepoint it was registered in, rolls back. A
+     * held effect runs after the commit, before the outermost `transaction()`
+     * call resolves, in registration order; one that then throws or rejects is
+     * handed to `onDeferredFailure` rather than failing a transaction that has
+     * committed.
+     *
+     * Here `effect` runs now and the returned promise settles with it, its
+     * failure included. Concrete rather than abstract, as `inTransaction` is,
+     * and right for a pooled adapter: each transaction has its own connection
+     * and has committed by the time its caller continues.
+     *
+     * @experimental
+     * @param effect - What to run once the change is durable
+     * @param onDeferredFailure - Receives the error of a held effect that fails
+     * @returns Settles once `effect` has run, or once it has been held
+     */
+    afterCommit(effect: () => unknown, _onDeferredFailure?: (error: unknown) => void): Promise<void>;
     /**
      * Get database capabilities.
      *
@@ -122,6 +285,23 @@ declare abstract class DrizzleAdapter {
      * @returns Database capability flags
      */
     abstract getCapabilities(): DatabaseCapabilities;
+    /**
+     * The schema this adapter's connections resolve unqualified names in.
+     *
+     * @remarks
+     * Read-only, and optional because only PostgreSQL has a schema namespace:
+     * MySQL's "schema" is its database and SQLite has one file. An adapter that
+     * sets no `search_path` of its own answers `undefined`, meaning the server's
+     * default applies.
+     *
+     * Exposed so the caller that built its own adapter can be held to the same
+     * schema the rest of the application assumes. The value lives in the
+     * adapter's config, and a mismatch is not an error anywhere below: every
+     * query succeeds, in a namespace nothing else is looking at.
+     *
+     * @returns The configured schema name, or `undefined` when none is set
+     */
+    getConfiguredSchema?(): string | undefined;
     /**
      * Get the raw Drizzle ORM instance for direct queries.
      *
@@ -633,7 +813,8 @@ declare abstract class DrizzleAdapter {
      * @remarks
      * Default implementation uses dialect-specific ON CONFLICT syntax.
      * PostgreSQL/SQLite: ON CONFLICT ... DO UPDATE
-     * MySQL: ON DUPLICATE KEY UPDATE
+     * MySQL: the MySQL adapter overrides this, resolving the conflict by the
+     * conflict columns (see its `upsert`)
      *
      * @param table - Table name
      * @param data - Record data
@@ -806,6 +987,128 @@ declare abstract class DrizzleAdapter {
      * @protected
      */
     protected createTransactionForwarders(txDb: () => unknown): TransactionCrudForwarders;
+    /**
+     * The Drizzle handles one transaction hands out; see
+     * `transactionDrizzleHandles`. `build` makes an instance on the
+     * transaction's own connection, with the relations config when given one.
+     *
+     * @protected
+     */
+    protected transactionDrizzleHandles<TBare>(build: (relations?: AnyRelations) => TBare): {
+        bare: () => TBare;
+        withRelations: <T = unknown>(relations: AnyRelations) => T;
+    };
+    /**
+     * A transaction context's `update`, for each adapter to bind.
+     *
+     * Not forwarded to the pooled `update` the way `select` and `delete` are:
+     * that one goes through the Drizzle query builder, which writes the columns
+     * the runtime MODEL declares, and a transaction's update must reach the
+     * columns the physical TABLE has — the localization transition window
+     * writes a column the model has already moved to a companion table that
+     * does not exist yet. The INSERT half of every transaction context already
+     * builds its own statement for that reason; `update-statement.ts` is the
+     * UPDATE half, spelled once for the three adapters, and this runs it: on
+     * the transaction executor, classified with the operation and table named
+     * as the pooled `update` classifies its failures, and read back through
+     * `select` on the same executor when the caller asked for rows.
+     *
+     * That read is by the rows' IDENTITY where the dialect can report it: on
+     * PostgreSQL and SQLite the statement carries `RETURNING <primary key>`, and
+     * the read-back asks for exactly those rows — so a row another transaction
+     * adds under the same predicate meanwhile is not among them, and an update
+     * whose own write falsifies its predicate still reads its rows back. MySQL
+     * has no RETURNING, so there the read re-runs the predicate, as the pooled
+     * `update` always has on that dialect; a table with no primary key in its
+     * model reads back the same way.
+     *
+     * @param txDb - thunk returning the transaction-bound Drizzle instance
+     * @param run - how this dialect runs a statement on that instance, and the
+     *   rows it returns when the statement carries RETURNING: better-sqlite3
+     *   answers synchronously, the pooled drivers do not
+     * @param bindUnmodeled - how a value binds when the model declares no
+     *   column for it; a declared column binds through its own encoder
+     * @returns the context's `update` method
+     */
+    protected transactionUpdate(txDb: () => unknown, run: (statement: SQL, returnsRows: boolean) => Promise<Record<string, unknown>[] | undefined> | Record<string, unknown>[] | undefined, bindUnmodeled: (value: unknown) => unknown): TransactionContext["update"];
+    /**
+     * The columns that identify a row of this table, under both spellings: the
+     * SQL name RETURNING reports and the Drizzle property name the query
+     * builder's WHERE is addressed by. Columns flagged primary first; failing
+     * that, the table-level primary key the dialect's table config carries
+     * (`primaryKey({ columns })` leaves each column's flag false), which each
+     * adapter reads through its own dialect. Empty when the model declares
+     * neither, and the read-back falls back to the caller's predicate.
+     */
+    protected identityColumns(tableObj: Record<string, unknown>): Array<{
+        jsName: string;
+        sqlName: string;
+    }>;
+    /**
+     * How a value binds to a column the model does not declare, on a driver
+     * that binds scalars, dates and binary natively: a structured value goes
+     * as JSON text, since what node-postgres and mysql2 make of a bare object
+     * or array is not JSON. For the adapters to hand `transactionUpdate`.
+     */
+    protected bindUnmodeledStructuredAsJson(value: unknown): unknown;
+    /**
+     * Refuse an upsert target every dialect would not answer alike: a conflict
+     * column named twice, which SQLite rejects as no constraint's target and
+     * MySQL would accept; and, when nothing is to be updated, a conflict column
+     * left for the database to fill, since the row that stands is then read
+     * back by a value the caller never gave. Shared with the dialects that
+     * override `upsert`, so the refusals are one rule.
+     */
+    protected assertUpsertTarget(table: string, data: Record<string, unknown>, options: UpsertOptions, keepExisting: boolean): void;
+    /**
+     * The columns of a table-level `primaryKey({ columns })`, as the dialect's
+     * table config reports them. The base class cannot read that config without
+     * naming a dialect, so each adapter answers for its own; a dialect that does
+     * not answer reports none.
+     */
+    protected compositePrimaryKey(_tableObj: Record<string, unknown>): object[];
+    /** The registered table object, or the error every CRUD method throws without one. */
+    private resolvedTableObject;
+    /**
+     * The statement `transactionUpdate` runs.
+     *
+     * @throws when nothing would be written — every key `undefined`, or none at
+     *   all. The query builder refused that too ("No values to set"), and a
+     *   patch that names nothing is a caller's mistake rather than a write of
+     *   nothing.
+     */
+    private buildTransactionUpdate;
+    /**
+     * Whether a transaction's `update` reads the rows it changed back: the
+     * caller named columns, or `*`. An empty list, like no option at all, asks
+     * for nothing and `update` answers `[]`, as it always has. The rows come
+     * from a read of the update's own WHERE on its own transaction, so they are
+     * the model's view of the row, decoded as every read is decoded — which is
+     * what the query-builder update returned for them, and why the named list
+     * selects nothing narrower.
+     */
+    private updateReturnsRows;
+    /**
+     * The driver's own error inside `error`: the first in its `cause` chain that
+     * `isDriverError` recognises, or `error` itself when none does.
+     *
+     * A query that runs through Drizzle fails with Drizzle's `DrizzleQueryError`,
+     * whose message is the SQL statement and which carries no driver code; the
+     * driver's error, the only object that knows what actually went wrong, is
+     * its `cause`. A dialect's {@link classifyError} classifies from what this
+     * returns, so a failure reads the same whether or not Drizzle wrapped it.
+     *
+     * The walk is bounded, because an error chain can be made cyclic and a
+     * classifier that can hang is worse than one that gives up. Falling back to
+     * `error` keeps an error that carries no code anywhere classified as before.
+     *
+     * @param error - The error as it was caught
+     * @param isDriverError - Whether a link in the chain is the driver's error
+     * @returns The driver's error, or `error` when no link is
+     */
+    protected driverErrorIn<T extends {
+        cause?: unknown;
+    }>(error: unknown, isDriverError: (candidate: T) => boolean): T;
     /**
      * Classify an error into a DatabaseError.
      *