@vibeorm/adapter-bun 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# @vibeorm/adapter-bun
+
+Bun-native database adapter for VibeORM using Bun's built-in `bun:sql` driver.
+
+## Installation
+
+```bash
+bun add @vibeorm/adapter-bun
+```
+
+## Usage
+
+The generated client uses this adapter by default. You can also create one manually:
+
+```ts
+import { bunAdapter } from "@vibeorm/adapter-bun";
+
+const adapter = bunAdapter({
+  url: "postgres://user:pass@localhost:5432/mydb",
+  max: 20,
+});
+```
+
+Then pass it to the client:
+
+```ts
+import { VibeClient } from "./generated/vibeorm/index.ts";
+
+const db = VibeClient({
+  adapter: bunAdapter({ url: "postgres://..." }),
+});
+```
+
+## Options
+
+```ts
+type BunAdapterOptions = {
+  url?: string;               // Connection string (defaults to DATABASE_URL env)
+  max?: number;               // Pool size (default: 20)
+  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")
+};
+```
+
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vibeorm/adapter-bun",
+  "version": "1.0.0",
+  "description": "Bun-native database adapter for VibeORM using bun:sql",
+  "license": "MIT",
+  "keywords": [
+    "orm",
+    "adapter",
+    "bun",
+    "postgresql",
+    "typescript"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "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"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "dependencies": {
+    "@vibeorm/runtime": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,308 @@
+/**
+ * @vibeorm/adapter-bun — Bun's native SQL adapter for VibeORM.
+ *
+ * Uses Bun's built-in `bun:sql` driver for high-performance PostgreSQL
+ * connections. Supports optional prepared statement caching via synthetic
+ * tagged templates.
+ */
+
+import type { DatabaseAdapter, QueryResult } from "@vibeorm/runtime";
+
+export type BunAdapterOptions = {
+  /** PostgreSQL connection URL. Falls back to DATABASE_URL env var if not provided. */
+  url?: string;
+  /** Maximum number of connections in the pool (default: 10). */
+  max?: number;
+  /**
+   * Whether to use named prepared statements for read queries (default: false).
+   *
+   * When `true`, the adapter caches SQL texts as synthetic tagged templates,
+   * creating named prepared statements that PostgreSQL caches execution plans for.
+   * This saves ~0.1ms of planning time per query but can cause PostgreSQL to
+   * switch to a "generic plan" after 5 executions, which may choose a worse
+   * index for queries with range filters or skewed data distributions.
+   *
+   * When `false` (default), the adapter uses `sql.unsafe()` which bypasses
+   * bun:sql's tagged template / named statement path. PostgreSQL replans each
+   * execution using the actual parameter values, always choosing the optimal index.
+   *
+   * Note: The bun:sql `prepare` constructor option is always left at its default
+   * (`true`). Setting `prepare: false` on the constructor triggers a bun:sql
+   * performance regression (~28ms per query on remote databases). Instead, we
+   * only control the execution path: `sql.unsafe()` vs tagged templates.
+   *
+   * Recommendation: Leave as `false` unless profiling shows planning overhead
+   * is a bottleneck (rare — typically only for sub-millisecond queries at
+   * very high throughput).
+   */
+  preparedStatements?: boolean;
+  /**
+   * Maximum number of entries in the prepared statement cache (default: 1000).
+   * Only used when `preparedStatements: true`.
+   * Prevents unbounded memory growth in long-running processes.
+   * Each unique SQL text consumes one slot. LRU eviction when full.
+   */
+  stmtCacheMax?: number;
+  /**
+   * Controls PostgreSQL's plan caching behavior for prepared statements
+   * (default: `"force_custom_plan"`).
+   *
+   * bun:sql uses the extended query protocol, which creates implicit prepared
+   * statements internally. After ~5 executions of the same query text,
+   * PostgreSQL may switch to a "generic plan" that ignores actual parameter
+   * values. This causes significant performance regressions for queries with
+   * range filters (`>=`, `<=`, `BETWEEN`), pattern matching (`LIKE`), or
+   * skewed data distributions — the planner picks sequential scans instead
+   * of index scans because it can't estimate selectivity without real values.
+   *
+   * - `"force_custom_plan"` (default): Always generates plans using actual
+   *   parameter values. Costs ~0.1 ms extra planning per query but always
+   *   picks the optimal index. Recommended for most workloads.
+   * - `"auto"`: PostgreSQL's default — switches to generic plans after ~5
+   *   executions if the estimated cost is similar. Can cause 2-4× regressions
+   *   on filtered COUNT / aggregate queries.
+   * - `"force_generic_plan"`: Always uses generic plans (not recommended).
+   *
+   * Injected via the PostgreSQL `options` startup parameter so it applies to
+   * every connection in the pool automatically. Requires PostgreSQL 12+.
+   */
+  planCacheMode?: "auto" | "force_custom_plan" | "force_generic_plan";
+};
+
+// ─── Internal bun:sql types ───────────────────────────────────────
+
+type SqlReserved = {
+  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
+  release(): void;
+};
+
+type SqlInstance = {
+  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
+  unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
+  begin<T>(fn: (tx: SqlInstance) => Promise<T>): Promise<T>;
+  reserve(): Promise<SqlReserved>;
+  close(): Promise<void>;
+};
+
+/**
+ * Create a VibeORM database adapter using Bun's built-in SQL driver.
+ *
+ * @example
+ * ```ts
+ * import { bunAdapter } from "@vibeorm/adapter-bun";
+ * import { VibeClient } from "./generated/vibeorm";
+ *
+ * const db = VibeClient({
+ *   adapter: bunAdapter({ url: "postgres://...", max: 10 }),
+ * });
+ *
+ * // With prepared statements enabled (for high-throughput local scenarios)
+ * const db2 = VibeClient({
+ *   adapter: bunAdapter({ url: "postgres://...", preparedStatements: true }),
+ * });
+ * ```
+ */
+export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
+  const USE_PREPARED = options?.preparedStatements ?? false;
+  const STMT_CACHE_MAX = options?.stmtCacheMax ?? 1000;
+  const PLAN_CACHE_MODE = options?.planCacheMode ?? "force_custom_plan";
+  const stmtCache = new Map<string, TemplateStringsArray>();
+
+  let sqlInstance: SqlInstance | null = null;
+
+  /**
+   * Append a PostgreSQL `options` startup parameter to a connection URL.
+   * The `options` parameter is sent during connection establishment, so it
+   * applies to every connection created by bun:sql's internal pool.
+   */
+  function appendStartupOption(params: { url: string; option: string }): string {
+    const { url, option } = params;
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}options=${encodeURIComponent(option)}`;
+  }
+
+  /**
+   * Resolve the connection URL, injecting plan_cache_mode if needed.
+   * Falls back to DATABASE_URL env var when no explicit URL is provided.
+   */
+  function resolveConnectionUrl(): string | undefined {
+    if (PLAN_CACHE_MODE === "auto") return options?.url;
+
+    const baseUrl = options?.url ?? process.env.DATABASE_URL;
+    if (!baseUrl) return undefined;
+
+    return appendStartupOption({
+      url: baseUrl,
+      option: `-c plan_cache_mode=${PLAN_CACHE_MODE}`,
+    });
+  }
+
+  function getSql(): SqlInstance {
+    if (sqlInstance) return sqlInstance;
+
+    // Import Bun's SQL
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { SQL } = require("bun");
+
+    const sqlOptions: Record<string, unknown> = {
+      max: options?.max ?? 10,
+      // Note: We intentionally do NOT set `prepare: false` here.
+      // Setting prepare=false on the bun:sql constructor triggers a performance
+      // regression (~28ms per query on remote/SSL databases) due to a bun:sql
+      // internal behavior change. Instead, we control prepared statement usage
+      // at the execution level: sql.unsafe() for the default path (no named stmts)
+      // vs tagged templates for the preparedStatements=true path.
+      // See: https://github.com/oven-sh/bun/issues/20294
+    };
+
+    const connectionUrl = resolveConnectionUrl();
+    if (connectionUrl) {
+      sqlInstance = new SQL(connectionUrl, sqlOptions) as unknown as SqlInstance;
+    } else if (options?.url) {
+      // URL provided but planCacheMode is "auto" — use URL as-is
+      sqlInstance = new SQL(options.url, sqlOptions) as unknown as SqlInstance;
+    } else {
+      // No URL — bun:sql will use PG* env vars. plan_cache_mode cannot be
+      // injected via startup options in this case (would need SET on connect).
+      sqlInstance = new SQL(sqlOptions) as unknown as SqlInstance;
+    }
+
+    return sqlInstance;
+  }
+
+  /**
+   * LRU-bounded synthetic tagged template cache for prepared statement reuse.
+   * bun:sql tagged templates create named prepared statements that PostgreSQL
+   * caches execution plans for. By converting dynamic SQL into synthetic tagged
+   * templates with stable references, we get the same caching behavior.
+   *
+   * Only used when `preparedStatements: true`.
+   */
+  function getOrCreateTemplate(params: { text: string }): TemplateStringsArray {
+    const { text } = params;
+    let strings = stmtCache.get(text);
+    if (strings) {
+      // Move to end (most recently used) by re-inserting
+      stmtCache.delete(text);
+      stmtCache.set(text, strings);
+      return strings;
+    }
+    const parts = text.split(/\$\d+/);
+    strings = Object.assign(parts, { raw: parts }) as unknown as TemplateStringsArray;
+    // Evict oldest entry if at capacity
+    if (stmtCache.size >= STMT_CACHE_MAX) {
+      const oldestKey = stmtCache.keys().next().value;
+      if (oldestKey !== undefined) stmtCache.delete(oldestKey);
+    }
+    stmtCache.set(text, strings);
+    return strings;
+  }
+
+  /**
+   * Convert a JS array to a PostgreSQL array literal string `{val1,val2,...}`.
+   * bun:sql's extended query protocol sends values as strings, so PostgreSQL
+   * needs array parameters in its native array literal format.
+   */
+  function toPgArrayLiteral(arr: unknown[]): string {
+    const escaped = arr.map((v) => {
+      if (v === null || v === undefined) return "NULL";
+      if (typeof v === "number" || typeof v === "bigint" || typeof v === "boolean") return String(v);
+      const str = String(v);
+      return `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    });
+    return `{${escaped.join(",")}}`;
+  }
+
+  /**
+   * Execute a query using the configured strategy.
+   * - preparedStatements=true: uses synthetic tagged templates (named prepared stmts)
+   * - preparedStatements=false: uses sql.unsafe() (replanned each time)
+   */
+  async function executeQuery(sql: SqlInstance, params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
+    if (USE_PREPARED) {
+      const strings = getOrCreateTemplate({ text: params.text });
+      const result = await sql(strings, ...params.values);
+      return result as Record<string, unknown>[];
+    }
+    const result = await sql.unsafe(params.text, params.values);
+    return result as Record<string, unknown>[];
+  }
+
+  function createAdapter(sql: SqlInstance): DatabaseAdapter {
+    return {
+      async execute(params) {
+        return executeQuery(sql, params);
+      },
+
+      async executeUnsafe(params) {
+        const result = await sql.unsafe(params.text, params.values);
+        const resultAny = result as unknown as Record<string, unknown>;
+        let affectedRows: number;
+        if (typeof resultAny.count === "number") {
+          affectedRows = resultAny.count;
+        } else if (typeof resultAny.affectedRows === "number") {
+          affectedRows = resultAny.affectedRows;
+        } else {
+          affectedRows = (result as unknown[]).length;
+        }
+        return {
+          rows: result as Record<string, unknown>[],
+          affectedRows,
+        };
+      },
+
+      async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T> {
+        return sql.begin(async (txSql: SqlInstance) => {
+          const txAdapter = createAdapter(txSql);
+          return fn(txAdapter);
+        });
+      },
+
+      async connect() {
+        const reserved = await sql.reserve();
+        reserved.release();
+      },
+
+      async disconnect() {
+        await sql.close();
+        sqlInstance = null;
+      },
+
+      formatArrayParam(values: unknown[]): unknown {
+        return toPgArrayLiteral(values);
+      },
+    };
+  }
+
+  // Create a lazy adapter that initializes the SQL connection on first use
+  const adapter: DatabaseAdapter = {
+    async execute(params) {
+      return createAdapter(getSql()).execute(params);
+    },
+
+    async executeUnsafe(params) {
+      return createAdapter(getSql()).executeUnsafe(params);
+    },
+
+    async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T> {
+      return createAdapter(getSql()).transaction(fn);
+    },
+
+    async connect() {
+      return createAdapter(getSql()).connect();
+    },
+
+    async disconnect() {
+      if (sqlInstance) {
+        await sqlInstance.close();
+        sqlInstance = null;
+      }
+    },
+
+    formatArrayParam(values: unknown[]): unknown {
+      return toPgArrayLiteral(values);
+    },
+  };
+
+  return adapter;
+}