@vibeorm/adapter-bun 1.3.0 → 2.0.0-alpha.10

package/dist/transaction-budget.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Transaction budgets — the total-deadline clock and the handle-closure gate.
+ *
+ * BYTE-IDENTICAL in all six adapter packages, exactly like `savepoint-gate.ts`:
+ * adapters depend on `@vibeorm/runtime` for TYPES only, so a shared value
+ * module there would invert the dependency direction, and `@vibeorm/schema` is
+ * the IR package, not a home for a transaction clock. Keep the six copies in
+ * lockstep — a divergence here is a silent per-engine behaviour difference.
+ *
+ * WHAT A DEADLINE IS, AND IS NOT
+ *
+ * `TransactionOptions.timeout` is unchanged: a PER-STATEMENT engine-side bound.
+ * `TransactionOptions.deadline` is new and different — a TOTAL wall-clock bound
+ * on one top-level transaction. Its clock starts immediately before `BEGIN` is
+ * sent, so connection acquisition (which has its own budget on the pooled
+ * adapters) is deliberately NOT counted.
+ *
+ * Enforcement is never `Promise.race` over a statement that keeps running:
+ *
+ * - `"between-statements"` (the default, and all six adapters can deliver it):
+ *   before every statement, every nested `transaction()` and the `COMMIT`, an
+ *   expired budget refuses. The statement is never sent and the transaction is
+ *   rolled back. A statement ALREADY IN FLIGHT is not interrupted.
+ * - `"cancel-running-statements"` (postgres servers only): additionally hands
+ *   the engine the remaining budget as `statement_timeout`, so the SERVER
+ *   cancels an over-long statement. An adapter that cannot do this refuses the
+ *   request outright rather than quietly delivering the weaker level.
+ *
+ * JavaScript cannot forcibly stop a running callback. A callback that keeps
+ * going past the deadline finds its later database calls refused; work it does
+ * outside the database (an HTTP call, an SMS) is not stopped and cannot be.
+ * There is no automatic retry: a deadline failure is terminal for that
+ * transaction, because external side effects may already have happened.
+ */
+import type { TransactionDeadlineEnforcement, TransactionDeadlineSupport, TransactionOptions } from "@vibeorm/runtime";
+import { VibeError } from "@vibeorm/schema";
+/** Where a budget check happened, reported as `meta.stage`. */
+export type BudgetStage = "statement" | "nested" | "commit";
+/**
+ * What is known about a finished transaction. `"unknown"` is a first-class
+ * outcome, not a failure to decide: when a rollback itself fails the commit
+ * state genuinely cannot be asserted, and claiming "rolled back" would be a lie.
+ */
+export type TransactionOutcome = "committed" | "rolled-back" | "unknown";
+/** Wall clock, injectable so tests are deterministic instead of sleep-timed. */
+export type DeadlineClock = () => number;
+/** The ambient clock, used whenever no seam is injected. */
+export declare const DEFAULT_DEADLINE_CLOCK: DeadlineClock;
+/**
+ * One top-level transaction's budget. Nested savepoint handles share this
+ * object BY REFERENCE — they never get an independent clock, connection or
+ * session setting.
+ */
+export type TransactionBudget = {
+    /** The enforcement level in force, or `null` when no deadline was requested. */
+    readonly enforcement: TransactionDeadlineEnforcement | null;
+    /** The requested total budget in milliseconds, or `null` when none was. */
+    readonly totalMs: number | null;
+    /** Existing per-statement limit, independent of the total deadline. Zero disables it. */
+    readonly statementTimeoutMs: number | null;
+    /** Milliseconds left (never negative), or `null` when no deadline is set. */
+    remainingMs(): number | null;
+    /** True only when a deadline is set and has passed. */
+    expired(): boolean;
+    /** Refuse a closed handle or an expired budget. Called BEFORE anything is sent. */
+    assertUsable(params: {
+        stage: BudgetStage;
+    }): void;
+    /** Record the terminal outcome; the first call wins and later ones are ignored. */
+    close(params: {
+        outcome: TransactionOutcome;
+    }): void;
+    /** The recorded outcome, or `null` while the transaction is still open. */
+    readonly outcome: TransactionOutcome | null;
+};
+/**
+ * Check `options.deadline` against what this adapter can honestly deliver.
+ * Called BEFORE `BEGIN` — a budget this engine cannot honour must never leave
+ * a transaction open behind it.
+ *
+ * @throws VibeError `VIBE_VALIDATION` when `totalMs` is not a positive integer.
+ * @throws VibeError `VIBE_UNSUPPORTED_CAPABILITY` when the requested
+ * `enforcement` is stronger than `support` — refused, never silently degraded.
+ */
+export declare function validateTransactionDeadline(params: {
+    options?: TransactionOptions;
+    support: TransactionDeadlineSupport;
+    provider: string;
+}): void;
+/**
+ * Start the clock for one top-level transaction. Call it immediately before
+ * `BEGIN`; {@link validateTransactionDeadline} must already have run.
+ */
+export declare function startTransactionBudget(params: {
+    options?: TransactionOptions;
+    provider: string;
+    clock?: DeadlineClock;
+}): TransactionBudget;
+/**
+ * The engine-side bound for the NEXT statement, or `null` when the caller did
+ * not buy `"cancel-running-statements"`. Floored at 1 ms: on postgres `0` means
+ * "no limit", so a spent budget must never be handed over as a zero.
+ */
+export declare function engineStatementBudgetMs(params: {
+    budget: TransactionBudget;
+}): number | null;
+/**
+ * The refusal an expired budget raises. `VIBE_TRANSACTION` with a stable
+ * `meta.reason` — no SQL text, no parameter values, no credentials.
+ */
+export declare function transactionDeadlineError(params: {
+    provider: string;
+    stage: BudgetStage;
+    totalMs: number;
+    overdueMs: number;
+}): VibeError;
+/**
+ * The refusal an ESCAPED transaction handle raises — a transactional adapter
+ * kept past the end of its transaction. Without this it would run on a
+ * connection that is back in the pool, outside any transaction.
+ */
+export declare function transactionClosedError(params: {
+    provider: string;
+    outcome: TransactionOutcome;
+    stage: BudgetStage;
+}): VibeError;
+/**
+ * The stable typed outcome for "the deadline expired and the rollback that was
+ * supposed to clean up failed too". Promising a rollback here would be false;
+ * promising a retry would be worse.
+ *
+ * `cause` is the CAUSAL error (the deadline refusal), so the reason the
+ * transaction was being abandoned survives. The rollback failure itself is
+ * reported only as `meta.rollbackFailed`: a raw driver failure can carry
+ * statement text, and this error is meant to be logged.
+ */
+export declare function transactionOutcomeUnknownError(params: {
+    provider: string;
+    totalMs: number;
+    cause: unknown;
+}): VibeError;
+/** Whether `error` is this module's deadline refusal (used to pick the cleanup path). */
+export declare function isTransactionDeadlineError(error: unknown): boolean;
+//# sourceMappingURL=transaction-budget.d.ts.map

package/dist/transaction-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-budget.d.ts","sourceRoot":"","sources":["../src/transaction-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EACV,8BAA8B,EAC9B,0BAA0B,EAC1B,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAEzE,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC;AAEzC,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,EAAE,aAAwC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC5D,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,6EAA6E;IAC7E,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;IAC7B,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC;IACnB,mFAAmF;IACnF,YAAY,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAAC;IACnD,mFAAmF;IACnF,KAAK,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,kBAAkB,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC7C,CAAC;AAIF;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,0BAA0B,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAgCP;AAID;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,GAAG,iBAAiB,CAyCpB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAQ5F;AAID;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,SAAS,CAaZ;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC;CACpB,GAAG,SAAS,CAUZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,SAAS,CAiBZ;AAED,yFAAyF;AACzF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGlE"}

package/dist/transaction-sql.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Transaction-control SQL text (postgres dialect, bun:sql flavour).
+ *
+ * Used by the reserved-connection path, which issues `BEGIN` itself so that
+ * isolation level and statement timeout can be applied — bun:sql's
+ * `sql.begin(fn)` fast path takes no such options.
+ */
+import type { IsolationLevel, TransactionOptions } from "@vibeorm/runtime";
+/** VibeORM isolation level → PostgreSQL isolation level keyword. */
+export declare const ISOLATION_LEVEL_SQL: Readonly<Record<IsolationLevel, string>>;
+/** `BEGIN`, with an `ISOLATION LEVEL` clause when the caller asked for one. */
+export declare function beginStatement(params: {
+    isolationLevel?: IsolationLevel;
+}): string;
+/**
+ * `SET LOCAL statement_timeout = <ms>` — transaction-scoped, so PostgreSQL
+ * cancels an over-long statement with SQLSTATE 57014 (mapped to
+ * `VIBE_TRANSACTION` with `meta.reason = "timeout"`).
+ *
+ * @throws VibeError `VIBE_VALIDATION` when the timeout is not a non-negative
+ * integer — the value is interpolated into SQL, so it is never trusted blindly.
+ */
+export declare function statementTimeoutStatement(params: {
+    timeout: number;
+}): string;
+/** How a raw statement steers the adapter's session-affine raw transaction. */
+export type RawTransactionControl = "open" | "close" | null;
+/**
+ * Classify a raw statement as transaction control.
+ *
+ * @vibeorm/migrate drives transactional DDL by sending literal `BEGIN` /
+ * `COMMIT` / `ROLLBACK` through its stateless `SqlExecutor` — sound only when
+ * every statement in between rides the SAME connection. The adapter uses this
+ * to pin one connection for the whole raw transaction ("open" reserves,
+ * "close" releases). On a pooled bun:sql instance an unpinned `BEGIN` is
+ * refused outright by the driver (`ERR_POSTGRES_UNSAFE_TRANSACTION`); other
+ * pool drivers would only work by checkout luck.
+ *
+ * Deliberately strict: only PURE single-statement control text matches
+ * (`BEGIN`, `BEGIN ISOLATION LEVEL …;`, `COMMIT`, `ROLLBACK WORK`, `END`,
+ * `ABORT`). Compound scripts, `ROLLBACK TO SAVEPOINT`, two-phase
+ * `COMMIT PREPARED` and `COMMIT AND CHAIN` (which keeps a transaction open)
+ * never engage the pinning.
+ */
+export declare function classifyRawTransactionControl(params: {
+    text: string;
+}): RawTransactionControl;
+/**
+ * Refuse options on a NESTED `transaction()` call — the same contract on every
+ * adapter (see the `DatabaseAdapter.transaction` JSDoc in @vibeorm/runtime):
+ * a nested transaction is a SAVEPOINT, and a savepoint can neither change the
+ * isolation level of the transaction it joins nor enforce its own timeout.
+ * Silently dropping the option (the pre-#3 behaviour) hid exactly that.
+ *
+ * @throws VibeError `VIBE_VALIDATION` when `isolationLevel` or `timeout` is
+ * present (an `undefined` or empty options object is accepted).
+ */
+export declare function refuseNestedTransactionOptions(params: {
+    options?: TransactionOptions;
+    provider: string;
+}): void;
+//# sourceMappingURL=transaction-sql.d.ts.map

package/dist/transaction-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-sql.d.ts","sourceRoot":"","sources":["../src/transaction-sql.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3E,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAIvE,CAAC;AAEH,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,EAAE;IAAE,cAAc,CAAC,EAAE,cAAc,CAAA;CAAE,GAAG,MAAM,CAKlF;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAU7E;AAID,+EAA+E;AAC/E,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAK5D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,qBAAqB,CAI7F;AAID;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAoBP"}

package/package.json

@@ -1,39 +1,49 @@
 {
   "name": "@vibeorm/adapter-bun",
-  "version": "1.3.0",
-  "description": "Bun-native database adapter for VibeORM using bun:sql",
-  "license": "MIT",
+  "version": "2.0.0-alpha.10",
+  "description": "bun:sql (Postgres) adapter for VibeORM v2",
   "keywords": [
     "orm",
-    "adapter",
+    "typescript",
+    "sql",
+    "database",
     "bun",
+    "type-safe",
+    "postgres",
     "postgresql",
-    "typescript"
+    "bun-sql",
+    "adapter",
+    "driver"
   ],
-  "type": "module",
-  "exports": {
-    ".": {
-      "default": "./src/index.ts",
-      "types": "./src/index.ts"
-    }
+  "homepage": "https://github.com/vibeorm/vibeorm/tree/master/packages/adapter-bun#readme",
+  "bugs": {
+    "url": "https://github.com/vibeorm/vibeorm/issues"
   },
-  "files": [
-    "src"
-  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/vibeorm/vibeorm.git",
     "directory": "packages/adapter-bun"
   },
-  "homepage": "https://github.com/vibeorm/vibeorm/tree/master/packages/adapter-bun",
-  "bugs": {
-    "url": "https://github.com/vibeorm/vibeorm/issues"
+  "license": "MIT",
+  "author": "VibeORM contributors",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "engines": {
-    "bun": ">=1.1.0"
+    "bun": ">=1.2.0"
   },
   "dependencies": {
-    "@vibeorm/runtime": "1.3.0"
+    "@vibeorm/runtime": "2.0.0-alpha.10",
+    "@vibeorm/schema": "2.0.0-alpha.8",
+    "@vibeorm/sql": "2.0.0-alpha.8"
   },
   "publishConfig": {
     "access": "public"