@vibeorm/runtime 2.6.0 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeORM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -26,7 +26,7 @@ Each `ModelDelegate` implements 16 methods:
 | Delete | `delete` · `deleteMany` |
 | Aggregate | `count` · `aggregate` · `groupBy` |
 
-The statement-building pieces are exported too, for tooling that needs SQL without executing it: `buildQuery`, `compileWhere`, `compileSelect`, `compileOrderBy`, `resolveResultShape`, and the runtime metadata builders `buildRuntimeMeta`, `getModelMeta`, `getFieldMeta`.
+The statement-building pieces are exported too, for tooling that needs SQL without executing it: `buildQuery`, `compileWhere`, `compileSelect`, `compileOrderBy`, `compileProjection`, `resolveResultShape`, and the runtime metadata builders `buildRuntimeMeta`, `getModelMeta`, `getFieldMeta`.
 
 ## The adapter contract
 
@@ -53,6 +53,7 @@ const adapter: DatabaseAdapter = {
 - `formatArrayParam` converts a JS array into the driver's preferred scalar-array representation; the ORM path binds arrays through it, the raw path does not.
 - The optional `wire` declaration (`WireFidelity`) tells the runtime what the driver already delivers for non-list scalars, so provably no-op decoders can be skipped.
 - The optional `rowChanges()` member reports the surviving direct row changes of the adapter's active transaction as a number or `"unknown"`; it backs `transactionRowChanges`. An adapter without it reports `"unknown"`. The kit's `statementRowChanges`, `observeRowChanges` and `readRowChanges` implement it for the shipped adapters.
+- The optional `transactionOutcome: "reported"` declaration says that a failed top-level `transaction()` records what happened beside the value it throws (commit outcome, whether `COMMIT` was sent, the cleanup `ROLLBACK`, the connection). An adapter reports through the kit's `settleFailedTransaction`, which applies the one commit-outcome rule; undeclared means no reports.
 
 `toSqlExecutor({ adapter })` bridges an adapter to the `SqlExecutor` shape `@vibeorm/migrate` runs on.
 
@@ -60,6 +61,7 @@ const adapter: DatabaseAdapter = {
 
 ## Helpers for frameworks
 
+- `transactionOutcomeOf({ error })` returns the facts of the failed top-level transaction that threw `error` (`commit`: `"not-committed"` or `"unknown"`, `commitSent`, `rollback`, `connection`), or `undefined` when there are none. The error itself is unchanged; branch on `adapter.transactionOutcome === "reported"`, never on an adapter name ([queries.md](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#when-a-transaction-fails-transactionoutcomeof)).
 - `transactionRowChanges({ db })` returns the direct row changes that survive in the transaction behind a handle, or `"unknown"` when some statement could not be observed ([queries.md](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#rows-changed-so-far-transactionrowchanges)).
 - `createDelegateMethodClassifier({ db })` returns `({ method, model? }) => "read" | "write" | undefined` for that handle's core and configured extension methods; `undefined` means denied ([queries.md](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#read-only-clients-readonly)).
 - `advisoryKeyOf({ text })` maps a string to a signed 64-bit `bigint` advisory-lock key (SHA-256 of the UTF-8 bytes, first eight bytes, big-endian). Different strings can map to the same key ([queries.md](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#advisory-locks-advisorylock-tryadvisorylock)).

package/dist/adapter-kit/adapter-lifecycle.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The terminal lifetime of a root adapter (EPIC A2): `disconnect()` ends an
+ * adapter for good. ONE copy, shared by all six first-party adapters.
+ *
+ * - `admit` registers a root operation (statement, transaction, session,
+ *   connect) synchronously, BEFORE it reaches its first await, and refuses
+ *   with `VIBE_ADAPTER_CLOSED` once `disconnect()` was called. Admitted
+ *   operations run independently: this is lifecycle accounting, not a queue —
+ *   server statements stay concurrent.
+ * - `inCallback` marks a transaction/session callback as running, so the
+ *   callback's own call of the root `disconnect()` refuses instead of waiting
+ *   for itself to finish.
+ * - `disconnect` seals admission synchronously, waits until every admitted
+ *   operation has settled (their callbacks may still issue child statements),
+ *   then runs the adapter's cleanup once. Every later or concurrent call gets
+ *   the same completion — success or failure — and admission never reopens.
+ *
+ * There is no timer, no cancellation and no scheduler: an unfinished admitted
+ * callback keeps `disconnect()` waiting. Stop producers and await pending work
+ * before closing.
+ */
+import { VibeError } from "@vibeorm/schema";
+/** The adapter a lifecycle gate belongs to; carried as `meta.driver` by its refusals. */
+export type AdapterLifecycleDriver = "pg" | "bun" | "mysql" | "pglite" | "sqlite" | "better-sqlite3";
+/** One root adapter's terminal lifetime. */
+export type AdapterLifecycleGate = {
+    /** Run a root operation, or refuse it with `VIBE_ADAPTER_CLOSED` once `disconnect()` was called. */
+    readonly admit: <T>(params: {
+        readonly run: () => Promise<T>;
+    }) => Promise<T>;
+    /** Run a transaction/session callback with this gate's active-callback marker set. */
+    readonly inCallback: <T>(params: {
+        readonly run: () => Promise<T>;
+    }) => Promise<T>;
+    /** Seal, drain admitted work, clean up once; every call shares the one completion. */
+    readonly disconnect: () => Promise<void>;
+};
+/** New root work on an adapter whose `disconnect()` was called. Fixed meta, never an address. */
+export declare function adapterClosedError(params: {
+    readonly driver: AdapterLifecycleDriver;
+    readonly state: "closing" | "closed";
+}): VibeError;
+/** The root `disconnect()` called from inside one of its own running callbacks. */
+export declare function disconnectInActiveCallbackError(params: {
+    readonly driver: AdapterLifecycleDriver;
+}): VibeError;
+/**
+ * `connect` / `disconnect` on a transaction handle (or `$connect` /
+ * `$disconnect` on a transaction client). The connection belongs to the
+ * transaction for its whole lifetime: reconnecting mid-transaction is
+ * meaningless and disconnecting would tear down an open transaction's own
+ * connection. The generated transaction type omits both; this refusal is the
+ * authority, because a type cannot stop a JavaScript caller.
+ */
+export declare function transactionLifecycleRefusal(params: {
+    readonly method: string;
+}): VibeError;
+/**
+ * Create the lifecycle gate of ONE root adapter. `cleanup` closes what the
+ * adapter owns (raw session, owned pool/instance/database) and is called at
+ * most once, after admitted work drained. `isConnectionReentrant` lets an
+ * embedded adapter report a running callback of the connection it shares with
+ * other wrappers; that callback's `disconnect()` refuses too.
+ */
+export declare function createAdapterLifecycleGate(params: {
+    readonly driver: AdapterLifecycleDriver;
+    readonly cleanup: () => Promise<void>;
+    readonly isConnectionReentrant?: () => boolean;
+}): AdapterLifecycleGate;
+/**
+ * The named shutdown-cleanup boundary of the adapters' `disconnect()`: run
+ * every step in order even when an earlier one failed (a failed raw-session
+ * rollback must still let the owned pool close), then reject with the FIRST
+ * failure, later failures attached as `meta.cleanupCause` evidence.
+ */
+export declare function runShutdownCleanup(params: {
+    readonly steps: readonly (() => Promise<void>)[];
+}): Promise<void>;
+//# sourceMappingURL=adapter-lifecycle.d.ts.map

package/dist/adapter-kit/deferred-control.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Deferred transaction control (round-trip EPIC 6, pipelining).
+ *
+ * The opening of a transaction (`BEGIN …`, the `timeout` option's `SET LOCAL`)
+ * and every `SAVEPOINT` need no answer before the next statement may be sent:
+ * nothing in JavaScript reads their replies except error handling. An adapter
+ * that can put several statements on the wire at once (adapter-pg's one-Sync
+ * batch, adapter-bun's pipelined extended queries) therefore keeps them here
+ * and sends them AHEAD OF the next statement, in the same burst.
+ *
+ * Bookkeeping only — this module sends nothing and knows no driver:
+ * - {@link DeferredControl.take} hands the pending texts to the statement that
+ *   is about to be sent; that statement carries them.
+ * - A transaction whose callback sends nothing never takes the opening, so the
+ *   adapter sends neither `BEGIN` nor `COMMIT`/`ROLLBACK`
+ *   ({@link DeferredControl.opened}).
+ * - A nested transaction whose body sends nothing never takes its `SAVEPOINT`,
+ *   so its `RELEASE SAVEPOINT` / `ROLLBACK TO SAVEPOINT` are elided as well
+ *   ({@link DeferredControl.routeSavepoint}). The savepoint gate's admission,
+ *   sibling order and abort tracking are untouched: only WHEN the text leaves
+ *   the client moves.
+ *
+ * ONE copy, shared by the postgres server adapters (constitution: adapter-kit).
+ */
+/** What the adapter does with one savepoint control text from the gate. */
+export type SavepointControlRoute = 
+/** `SAVEPOINT x` queued: it rides with the next statement. */
+"deferred"
+/** The matching `SAVEPOINT` never left the client: send nothing. */
+ | "elided"
+/** Send it now, as today. */
+ | "send";
+/** Pending control texts of ONE top-level transaction (one connection). */
+export type DeferredControl = {
+    /** True once the opening texts were handed out: the server has (or failed to open) the transaction. */
+    readonly opened: () => boolean;
+    /** Whether a control text waits to ride with the next statement. */
+    readonly hasPending: () => boolean;
+    /** Hand out every pending text in send order and empty the queue. */
+    readonly take: () => readonly string[];
+    /**
+     * Route a savepoint control text produced by `runNestedSavepoint`
+     * (`SAVEPOINT x`, `RELEASE SAVEPOINT x`, `ROLLBACK TO SAVEPOINT x`).
+     * Any other text routes to `"send"`.
+     */
+    readonly routeSavepoint: (params: {
+        readonly text: string;
+    }) => SavepointControlRoute;
+};
+/**
+ * Start the bookkeeping for one top-level transaction. `opening` holds the
+ * texts that open it, in order (for example `["BEGIN", "SET LOCAL
+ * statement_timeout = 5000"]`); they stay pending until the first statement.
+ */
+export declare function createDeferredControl(params: {
+    readonly opening: readonly string[];
+}): DeferredControl;
+//# sourceMappingURL=deferred-control.d.ts.map

package/dist/adapter-kit/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * @vibeorm/runtime/adapter-kit — the transaction-safety helpers every driver
  * adapter shares: savepoint naming, the savepoint lifetime gate (F14), the
- * transaction budget (EPIC 6) and the nested-option refusal.
+ * transaction budget (EPIC 6), the nested-option refusal and the terminal
+ * adapter lifetime (EPIC A2: `disconnect()` ends an adapter for good).
  *
  * ONE copy. Each adapter imports from this subpath and re-exports the helpers
  * it always offered, so a fix to the gate or the budget reaches every engine
@@ -15,10 +16,16 @@ export { createSavepointCounter, nextSavepointName } from "./savepoints.ts";
 export type { SavepointCounter } from "./savepoints.ts";
 export { abortTransactionOnServerFailure, createSavepointScope, isSavepointRollbackFailedError, isTransactionAbortedError, markTransactionAborted, markSavepointOpened, runNestedSavepoint, runRootScope, savepointRollbackFailedError, scopeTurn, transactionAbortedError, } from "./savepoint-gate.ts";
 export type { AbortedTransaction, SavepointScope, SavepointState } from "./savepoint-gate.ts";
-export { refuseNestedTransactionOptions } from "./nested-options.ts";
+export { readOnlyRequested, refuseNestedTransactionOptions } from "./nested-options.ts";
+export { createDeferredControl } from "./deferred-control.ts";
+export type { DeferredControl, SavepointControlRoute } from "./deferred-control.ts";
 export { DEFAULT_DEADLINE_CLOCK, engineStatementBudgetMs, isTransactionDeadlineError, startTransactionBudget, transactionClosedError, transactionDeadlineError, transactionOutcomeUnknownError, validateTransactionDeadline, } from "./transaction-budget.ts";
 export type { BudgetStage, DeadlineClock, TransactionBudget, TransactionOutcome } from "./transaction-budget.ts";
-export { dispatchSynchronousRowChanges, observeRowChanges, readRowChanges, statementRowChanges } from "./row-changes.ts";
+export { closeFailedTransactionBudget, failedCommitOutcome, recordTransactionOutcome, settleFailedTransaction, transactionOutcomeOf, } from "./transaction-outcome.ts";
+export type { CommitProgress, ConnectionOutcome, RollbackOutcome, FailedCommitOutcome, TransactionOutcomeReport, } from "./transaction-outcome.ts";
+export { ROW_CHANGES_COLUMN, dispatchSynchronousRowChanges, observeRowChanges, readRowChanges, statementRowChanges } from "./row-changes.ts";
 export { runPinnedSession } from "./session.ts";
+export { createAdapterLifecycleGate, runShutdownCleanup, transactionLifecycleRefusal } from "./adapter-lifecycle.ts";
+export type { AdapterLifecycleDriver, AdapterLifecycleGate } from "./adapter-lifecycle.ts";
 export { runSqliteSession } from "./sqlite-session.ts";
 //# sourceMappingURL=index.d.ts.map