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

package/README.md

@@ -1,78 +1,91 @@
 # @vibeorm/adapter-bun
 
-Bun-native database adapter for VibeORM using Bun's built-in `bun:sql` driver.
+> Part of **[VibeORM](https://github.com/vibeorm/vibeorm)** — a type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
 
-## Installation
+This adapter runs VibeORM on Bun's built-in `bun:sql` PostgreSQL driver, including its internal connection pool. It has no external driver dependency and runs on Bun only.
 
 ```bash
-bun add @vibeorm/adapter-bun
+bun add @vibeorm/adapter-bun@alpha
 ```
 
-## Usage
+> **Pre-release.** `2.0.0-alpha.x`, published under the `alpha` dist-tag. `npm i vibeorm` still resolves to the stable v1 line.
 
-The generated client uses this adapter by default. You can also create one manually:
+## Usage
 
 ```ts
+import { VibeClient } from "./generated/vibeorm/index.js";
 import { bunAdapter } from "@vibeorm/adapter-bun";
 
-const adapter = bunAdapter({
-  url: "postgres://user:pass@localhost:5432/mydb",
-  max: 20,
-});
-```
+// url defaults to process.env.DATABASE_URL, then bun's PG* env vars
+const db = VibeClient({ adapter: bunAdapter({ url: process.env.DATABASE_URL, max: 10 }) });
 
-Then pass it to the client:
-
-```ts
-import { VibeClient } from "./generated/vibeorm/index.ts";
+const users = await db.user.findMany({ where: { email: { contains: "@example.com" } }, take: 10 });
 
-const db = VibeClient({
-  adapter: bunAdapter({ url: "postgres://..." }),
-});
+await db.$disconnect();
 ```
 
 ## Options
 
-```ts
-type BunAdapterOptions = {
-  url?: string;                // Connection string (defaults to DATABASE_URL env)
-  max?: number;                // Pool size (default: 10)
-  statementTimeout?: number;   // Default query timeout in ms (default: none)
-  connectionTimeout?: number;  // Max time to establish a connection in ms (default: none)
-  preparedStatements?: boolean; // Enable prepared statement caching (default: false)
-  stmtCacheMax?: number;       // Max cached prepared statements (default: 1000)
-  planCacheMode?: string;      // PostgreSQL plan_cache_mode (default: "force_custom_plan")
-};
-```
+`bunAdapter(options?: BunAdapterOptions)`:
 
-### Statement timeout
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `url` | `string` | `process.env.DATABASE_URL`, then bun's `PG*` env vars | PostgreSQL connection URL |
+| `max` | `number` | `10` | Maximum pooled connections |
+| `statementTimeout` | `number` (ms) | — | Pool-wide `statement_timeout`, sent as a startup parameter so every connection inherits it; a per-transaction `timeout` overrides it |
+| `connectionTimeout` | `number` (ms) | — | Wait for a connection to be established. bun:sql expects seconds; the adapter converts |
+| `preparedStatements` | `boolean` | `false` | Run ORM-path queries as tagged templates, creating named prepared statements. PostgreSQL may fall back to a generic plan after ~5 executions — leave off unless profiling says otherwise |
+| `stmtCacheMax` | `number` | `1000` | Maximum entries in the synthetic template cache (LRU) |
+| `planCacheMode` | `"auto" \| "force_custom_plan" \| "force_generic_plan"` | `"force_custom_plan"` | PostgreSQL `plan_cache_mode` for every connection |
 
-Set a default timeout for all queries. Any query exceeding this duration is cancelled by PostgreSQL (SQLSTATE `57014`), surfaced as a `VibeTransientError` with code `STATEMENT_TIMEOUT`.
+`planCacheMode` and `statementTimeout` travel in the `options` startup parameter appended to the connection URL, so they apply to every pooled connection without a per-query round trip. Client-side libpq options such as `connect_timeout` must never go in the URL — bun:sql forwards unrecognised URL parameters to the server, which rejects them.
 
-```ts
-const adapter = bunAdapter({
-  url: "postgres://...",
-  statementTimeout: 30000, // 30 seconds
-});
-```
+## Runtime support
 
-Injected as a PostgreSQL connection-level startup parameter (`-c statement_timeout=N`), so every query on every pooled connection inherits it automatically with zero per-query overhead.
+| Runtime | Supported |
+|---|---|
+| Bun ≥ 1.2 | yes |
+| Node | no — `bun:sql` is a Bun built-in |
 
-Transaction-level `timeout` (via `db.$transaction(fn, { timeout })`) overrides this default for that transaction using `SET LOCAL statement_timeout`.
+On Node, use [`@vibeorm/adapter-pg`](https://github.com/vibeorm/vibeorm/tree/master/packages/adapter-pg) instead; it speaks the same postgres dialect with the same semantics.
 
-### Connection timeout
+## Capabilities
 
-Limit how long initial TCP connection establishment can take:
+This is a postgres-dialect adapter, so the full capability set is available: `RETURNING`, scalar array columns, native enums, `ILIKE`, `DISTINCT ON`, partial indexes, transactional DDL, `createManyAndReturn`, a real JSON column type, native `NULLS FIRST`/`NULLS LAST`, and the `"join"` relation strategy (`LEFT JOIN LATERAL` plus JSON aggregation). The generated capability table lives in [docs/dialects.md](https://github.com/vibeorm/vibeorm/blob/master/docs/dialects.md).
 
-```ts
-const adapter = bunAdapter({
-  url: "postgres://...",
-  connectionTimeout: 5000, // 5 seconds
-});
-```
+## Transactions
+
+A top-level `transaction()` without options uses `sql.begin()` and lets bun:sql drive `BEGIN`/`COMMIT`. With `isolationLevel` or `timeout` the adapter reserves one connection and issues the statements itself, because `begin()` takes no such options.
+
+Nested transactions become savepoints, chosen by probing the handle:
+
+- Modern bun:sql exposes `savepoint(fn)` on the in-transaction handle, and the adapter uses it. `begin()` is never called inside a transaction — it throws there ("use savepoint() instead").
+- Reserved connections (and older bun:sql builds) expose no `savepoint` helper, so the adapter issues `SAVEPOINT` / `RELEASE SAVEPOINT` / `ROLLBACK TO SAVEPOINT` SQL by hand, with a name counter shared across the whole top-level transaction.
+
+Raw transaction control (`BEGIN` / `COMMIT` / `ROLLBACK` through the raw path, as `@vibeorm/migrate` does) reserves one connection for the duration: bun:sql refuses transaction control through `sql.unsafe()` on a pooled instance (`ERR_POSTGRES_UNSAFE_TRANSACTION`). Concurrent raw transactions on a single adapter are unsupported.
+
+## Error mapping
+
+Every driver failure becomes a `VibeError` with the driver error as `cause` and `meta` carrying `sqlstate` plus `constraint` / `table` / `column` when reported. bun:sql puts the SQLSTATE on `code` or on `errno` depending on the Bun version; both are read. A non-SQLSTATE `ERR_POSTGRES_*` identifier is kept as `meta.driverCode`. Table (`BUN_SQLSTATE_ERROR_CODES`, frozen and mirrored by tests):
+
+| SQLSTATE | Condition | VibeError code | `meta.reason` |
+|---|---|---|---|
+| `23505` | unique_violation | `VIBE_UNIQUE_VIOLATION` | |
+| `23503` | foreign_key_violation | `VIBE_FK_VIOLATION` | |
+| `23502` | not_null_violation | `VIBE_VALIDATION` | |
+| `23514` | check_violation | `VIBE_VALIDATION` | |
+| `22P02` | invalid_text_representation | `VIBE_VALIDATION` | |
+| `40001` | serialization_failure | `VIBE_TRANSACTION` | |
+| `40P01` | deadlock_detected | `VIBE_TRANSACTION` | |
+| `57014` | query_canceled (statement_timeout) | `VIBE_TRANSACTION` | `"timeout"` |
+| anything else, including every `ERR_POSTGRES_*` connection or auth failure | | `VIBE_ADAPTER` | |
 
-Injected as `connect_timeout` in the PostgreSQL connection URL (converted to seconds).
+A transaction callback's own error is rethrown untouched instead of being mapped as a driver failure.
 
-## License
+## Links
 
-[MIT](../../LICENSE)
+- [Documentation](https://github.com/vibeorm/vibeorm/tree/master/docs)
+- [Getting started](https://github.com/vibeorm/vibeorm/blob/master/docs/getting-started.md)
+- [Dialect capability tables](https://github.com/vibeorm/vibeorm/blob/master/docs/dialects.md)
+- [Repository and issues](https://github.com/vibeorm/vibeorm)
+- MIT licensed

package/dist/connection-url.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Connection-URL handling for bun:sql.
+ *
+ * Per-connection PostgreSQL settings (`plan_cache_mode`, `statement_timeout`)
+ * travel in the `options` startup parameter, which the server parses for
+ * `-c key=value` pairs — so every connection in bun's internal pool inherits
+ * them without a per-query round trip.
+ *
+ * v1 lesson (LEARNINGS.md): bun:sql forwards *unrecognised* URL parameters to
+ * the server as runtime configuration, so a libpq client-side option such as
+ * `connect_timeout` must never be put in the URL (PostgreSQL rejects it as an
+ * unrecognised configuration parameter). Connection timeouts use bun:sql's
+ * `connectionTimeout` constructor option instead.
+ */
+/**
+ * PostgreSQL plan-cache behaviour for the implicit prepared statements bun:sql
+ * creates. `force_custom_plan` replans with the real parameter values (≈0.1 ms
+ * per query) and keeps index selection optimal on range/LIKE/skewed filters —
+ * `auto` lets PostgreSQL switch to a generic plan after ~5 executions.
+ */
+export type PlanCacheMode = "auto" | "force_custom_plan" | "force_generic_plan";
+/**
+ * Build the `options` startup string, or `undefined` when nothing needs setting.
+ *
+ * @throws VibeError `VIBE_VALIDATION` when `statementTimeout` is not a
+ * non-negative integer — the value ends up inside the startup string verbatim.
+ */
+export declare function buildStartupOptions(params: {
+    planCacheMode: PlanCacheMode;
+    statementTimeout?: number;
+}): string | undefined;
+/** Append the `options` startup parameter to a connection URL. */
+export declare function applyStartupOptions(params: {
+    url: string;
+    startupOptions: string;
+}): string;
+//# sourceMappingURL=connection-url.d.ts.map

package/dist/connection-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-url.d.ts","sourceRoot":"","sources":["../src/connection-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,aAAa,EAAE,aAAa,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,GAAG,SAAS,CAerB;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAI3F"}

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Driver-error mapping for `bun:sql`.
+ *
+ * bun:sql raises `SQL.PostgresError` for server failures and for client-side
+ * problems alike. Server failures carry the PostgreSQL SQLSTATE — depending on
+ * the Bun version on `code` or on `errno` — while client-side failures use a
+ * `ERR_POSTGRES_*` identifier in `code`. Both shapes are read here, so the
+ * mapping is stable across Bun versions. Constitution rule 5: only `VibeError`
+ * escapes the adapter.
+ */
+import { VibeError, type VibeErrorCode } from "@vibeorm/schema";
+/**
+ * PostgreSQL SQLSTATE → stable VibeError code. Frozen and mirrored by tests;
+ * anything absent from this table (including every `ERR_POSTGRES_*` connection
+ * or auth failure) maps to `VIBE_ADAPTER`.
+ */
+export declare const BUN_SQLSTATE_ERROR_CODES: Readonly<Record<string, VibeErrorCode>>;
+/** SQLSTATEs that additionally explain themselves through `meta.reason`. */
+export declare const BUN_SQLSTATE_REASONS: Readonly<Record<string, string>>;
+/**
+ * Extract the SQLSTATE from a bun:sql error, accepting it on either `code` or
+ * `errno`. `ERR_POSTGRES_*` identifiers are not SQLSTATEs and yield `undefined`.
+ */
+export declare function bunErrorSqlstate(params: {
+    error: unknown;
+}): string | undefined;
+/**
+ * Map any error thrown by bun:sql onto a `VibeError`.
+ *
+ * A `VibeError` passes through unchanged, so an error raised deeper inside the
+ * ORM (or by a nested adapter call) is never re-wrapped.
+ */
+export declare function mapBunDriverError(params: {
+    error: unknown;
+}): VibeError;
+/** Run a driver call, mapping anything it throws onto a `VibeError`. */
+export declare function runMapped<T>(fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIhE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAqB3E,CAAC;AAEH,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEhE,CAAC;AAYH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAS/E;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CA8BvE;AAED,wEAAwE;AACxE,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMnE"}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @vibeorm/adapter-bun — bun:sql (PostgreSQL) adapter for VibeORM v2.
+ *
+ * Uses Bun's built-in SQL driver and its internal connection pool. Owns
+ * optional prepared statements (synthetic tagged templates), transactions
+ * (nested → savepoints), array-literal parameter formatting and driver-error
+ * mapping. Only `VibeError` ever escapes.
+ */
+import type { DatabaseAdapter } from "@vibeorm/runtime";
+import { type PlanCacheMode } from "./connection-url.ts";
+/** Options for {@link bunAdapter}. */
+export type BunAdapterOptions = {
+    /** PostgreSQL connection URL. Defaults to `process.env.DATABASE_URL`, then bun's `PG*` env vars. */
+    readonly url?: string;
+    /** Maximum pooled connections (default 10). */
+    readonly max?: number;
+    /**
+     * Pool-wide `statement_timeout` in milliseconds, sent as a startup parameter
+     * so every connection inherits it. A per-transaction `timeout` overrides it
+     * for that transaction.
+     */
+    readonly statementTimeout?: number;
+    /**
+     * Milliseconds to wait for a connection to be established. Passed to bun:sql
+     * as `connectionTimeout` (which expects **seconds**; converted here).
+     */
+    readonly connectionTimeout?: number;
+    /**
+     * Execute ORM-path queries as tagged templates, creating named prepared
+     * statements (default false). Saves planning time but lets PostgreSQL fall
+     * back to a generic plan after ~5 executions — leave off unless profiling
+     * says otherwise. bun:sql's `prepare: false` constructor option is never set
+     * (it triggers a known bun:sql performance regression).
+     */
+    readonly preparedStatements?: boolean;
+    /** Maximum entries in the synthetic template cache (default 1000, LRU). */
+    readonly stmtCacheMax?: number;
+    /** PostgreSQL `plan_cache_mode` for every connection (default `force_custom_plan`). */
+    readonly planCacheMode?: PlanCacheMode;
+};
+/**
+ * Create a VibeORM adapter backed by bun:sql.
+ *
+ * @example
+ * ```ts
+ * const adapter = bunAdapter({ url: process.env.DATABASE_URL, max: 10 });
+ * await adapter.connect();
+ * const rows = await adapter.execute({ text: 'SELECT * FROM "User" WHERE "id" = $1', values: [1] });
+ * ```
+ */
+export declare function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter;
+export { BUN_SQLSTATE_ERROR_CODES, BUN_SQLSTATE_REASONS, bunErrorSqlstate, mapBunDriverError, } from "./errors.ts";
+export { serializeParams, serializeParamsRaw, toPgArrayLiteral } from "./params.ts";
+export { applyStartupOptions, buildStartupOptions } from "./connection-url.ts";
+export type { PlanCacheMode } from "./connection-url.ts";
+export { createSavepointCounter, nextSavepointName } from "./savepoints.ts";
+export type { SavepointCounter } from "./savepoints.ts";
+export { createTemplateCache, templateChunks } from "./template-cache.ts";
+export type { TemplateCache } from "./template-cache.ts";
+export { ISOLATION_LEVEL_SQL, beginStatement, classifyRawTransactionControl, refuseNestedTransactionOptions, statementTimeoutStatement, } from "./transaction-sql.ts";
+export type { RawTransactionControl } from "./transaction-sql.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAiD,MAAM,kBAAkB,CAAC;AAEvG,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAwEnG,sCAAsC;AACtC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,oGAAoG;IACpG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC,CAAC;AAsBF;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,eAAe,CA2TvE;AAgBD,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,6BAA6B,EAC7B,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}