@vibeorm/adapter-mysql 2.0.0-alpha.8 → 2.0.0

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.map

@@ -1 +1 @@
-{"version":3,"file":"transaction-sql.d.ts","sourceRoot":"","sources":["../src/transaction-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3E,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAIvE,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAAE,cAAc,EAAE,cAAc,CAAA;CAAE,GAAG,MAAM,CAE7F;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAU7E;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAmD,CAAC;AAI/F,+EAA+E;AAC/E,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAK5D;;;;;;;;;;;GAWG;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,CAkBP"}
+{"version":3,"file":"transaction-sql.d.ts","sourceRoot":"","sources":["../src/transaction-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3E,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAIvE,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAAE,cAAc,EAAE,cAAc,CAAA;CAAE,GAAG,MAAM,CAE7F;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAU7E;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAmD,CAAC;AAI/F,+EAA+E;AAC/E,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAK5D;;;;;;;;;;;GAWG;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,6 +1,6 @@
 {
   "name": "@vibeorm/adapter-mysql",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.0",
   "description": "mysql2 adapter for VibeORM v2",
   "keywords": [
     "orm",
@@ -42,8 +42,8 @@
     "bun": ">=1.2.0"
   },
   "dependencies": {
-    "@vibeorm/runtime": "2.0.0-alpha.8",
-    "@vibeorm/schema": "2.0.0-alpha.6",
+    "@vibeorm/runtime": "2.0.0",
+    "@vibeorm/schema": "2.0.0",
     "mysql2": "^3.15.0"
   },
   "publishConfig": {