@junejs/server 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -30,8 +30,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.16",
-    "@junejs/db": "0.0.16",
+    "@junejs/core": "0.0.18",
+    "@junejs/db": "0.0.18",
     "marked": "^18.0.5",
     "rolldown": "^1.1.0",
     "postcss": "^8.4.0",
@@ -40,10 +40,30 @@
   },
   "peerDependencies": {
     "react": "^19.2.0",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "pg": "^8.0.0",
+    "mysql2": "^3.0.0",
+    "@libsql/client": "^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/junebuild/june"
+  },
+  "devDependencies": {
+    "@libsql/client": "^0.17.3",
+    "@types/pg": "^8.20.0",
+    "mysql2": "^3.22.5",
+    "pg": "^8.21.0"
   }
 }

package/src/adapter.ts

@@ -136,47 +136,72 @@ export function workers(opts?: { name?: string; domain?: string }): JuneAdapter
 
 // Vercel target — emits the Build Output API v3 tree (.vercel/output/). June's
 // worker is already a Web-standard fetch handler, so this is packaging, not a
-// re-bundle: the same portable graph, built with edge-light conditions, becomes a
-// Vercel Edge Function. v1 scope: SSR + static + the full agent surface. No db
-// (D1 is Cloudflare-only) — declaring one fails fast; an HTTP-driver db backend
-// for Vercel is a planned follow-up.
+// re-bundle: the same portable graph (built with edge-light conditions, so
+// react-dom resolves to server.edge.js) packaged for the platform.
+//
+// Default runtime is "node" — a Vercel Function on Fluid compute. Vercel
+// deprecated the Edge Functions *product* and officially recommends the Node
+// runtime for performance + reliability, and Fluid compute (in-function
+// concurrency) closed the cold-start gap edge used to win on. Node also lifts
+// edge's limits (no 1–4MB code cap, full API). `vercel({ runtime: "edge" })` still
+// emits an Edge Function for latency-critical global cases — the runtime is not
+// removed, just discouraged. BOTH run the SAME bundle; only the .func packaging
+// (.vc-config.json + the export shape) differs.
+//
+// db: turso() works (libsql over HTTPS — the build bundles the web client, the
+// request opens it from env → ambient `import { db }`). sqlite()/d1() are
+// Cloudflare-only (a D1 binding); validate() rejects them with that guidance.
 //
 // Routing: only the hashed framework assets (/_june/*) are served statically by
 // the CDN (their exact-path URLs match June's scheme); every page + projection
-// (.md/.json/mcp/llms.txt) renders through the one edge function, so the
-// dual-audience surface is identical to Workers.
+// (.md/.json/mcp/llms.txt) renders through the one function, so the dual-audience
+// surface is identical to Workers.
 const VERCEL_FUNCTION = "__june"; // → /__june, the catch-all SSR function
 
-export function vercel(opts?: { regions?: string[] }): JuneAdapter {
+export function vercel(opts?: { runtime?: "node" | "edge"; regions?: string[] }): JuneAdapter {
+  const isEdge = (opts?.runtime ?? "node") === "edge";
   return {
     name: "vercel",
-    capabilities: { runtime: "edge", persistentConnections: false, assets: "platform" },
-    // NO "worker"/"browser": react-dom's ./server exports map "worker" → the
-    // BROWSER SSR build (server.browser.js), listed BEFORE "edge-light", so
-    // requesting "worker" pulls the wrong renderer and the edge function crashes
-    // at invocation. "edge-light" → server.edge.js (the same build workerd gets
-    // via "workerd"). Mirrors workers()'s shape: <runtime>, edge, import, default.
+    capabilities: {
+      // Node on Fluid holds streamed/SSE connections; the edge variant keeps the
+      // conservative flag it shipped with.
+      runtime: isEdge ? "edge" : "node",
+      persistentConnections: !isEdge,
+      assets: "platform",
+    },
+    // The bundle is identical for both runtimes. NO "worker"/"browser": react-dom's
+    // ./server exports map "worker" → the BROWSER SSR build (server.browser.js),
+    // listed BEFORE "edge-light", so requesting "worker" pulls the wrong renderer.
+    // "edge-light" → server.edge.js, which uses Web Streams (renderToReadableStream)
+    // and runs on workerd AND Node alike. Mirrors workers()'s shape.
     conditions: ["edge-light", "edge", "import", "default"],
 
-    validate({ plan }) {
-      if (plan.db) {
+    validate({ config }) {
+      // turso() is libsql over HTTPS — it runs on Vercel (the build bundles the web
+      // client; the request opens it from env → ambient `import { db }`). sqlite()/
+      // d1() need a D1 binding, which is Cloudflare-only.
+      const kind = config.resources?.db?.kind;
+      if (kind && kind !== "turso") {
         throw new Error(
-          "vercel(): the Vercel adapter has no db backend yet (D1 is Cloudflare-only).\n" +
-            "  Remove the `db` resource from june.config.ts, or deploy to Workers.\n" +
-            "  An HTTP-driver db (Neon/Turso) for Vercel is planned.",
+          `vercel(): the '${kind}' db isn't supported on Vercel (D1 is Cloudflare-only).\n` +
+            "  Use turso() (libsql over HTTPS) for a Vercel db, or deploy to Workers.",
         );
       }
     },
 
     entry() {
       // No withAssets: the CDN serves /_june/*; this function renders everything
-      // else. Resources arrive via process.env (Vercel injects env vars into the
-      // edge runtime); there are no platform bindings.
+      // else. Resources arrive via process.env (Vercel injects env vars); there
+      // are no platform bindings. The Node runtime captures the `fetch` Web
+      // Standard export (an object with a fetch method); the Edge runtime takes a
+      // bare default function. Same pipeline call either way.
+      const env = `const __env = typeof process !== "undefined" && process.env ? process.env : {};\n`;
       return {
         imports: [],
         wrap: (pipelineVar) =>
-          `const __env = typeof process !== "undefined" && process.env ? process.env : {};\n` +
-          `export default (request) => ${pipelineVar}.fetch(request, __env);`,
+          isEdge
+            ? env + `export default (request) => ${pipelineVar}.fetch(request, __env);`
+            : env + `export default { fetch: (request) => ${pipelineVar}.fetch(request, __env) };`,
       };
     },
 
@@ -192,14 +217,28 @@ export function vercel(opts?: { regions?: string[] }): JuneAdapter {
       // function ("referencing unsupported modules"). assets/ is handled below.
       const jsFiles = (await readdir(outDir)).filter((f) => f.endsWith(".js"));
       for (const f of jsFiles) await copyFile(join(outDir, f), join(fnDir, f));
-      await writeFile(
-        join(fnDir, ".vc-config.json"),
-        JSON.stringify(
-          { runtime: "edge", entrypoint: "worker.js", ...(opts?.regions ? { regions: opts.regions } : {}) },
-          null,
-          2,
-        ) + "\n",
-      );
+
+      const regions = opts?.regions ? { regions: opts.regions } : {};
+      const vcConfig = isEdge
+        ? { runtime: "edge", entrypoint: "worker.js", ...regions }
+        : {
+            // A Vercel Function on Fluid compute. handler = the ESM bundle entry;
+            // launcherType Nodejs invokes its default `fetch` export.
+            // supportsResponseStreaming is REQUIRED or a streamed Response (our SSE
+            // live feed, streamed SSR) is buffered instead of flushed.
+            runtime: "nodejs22.x",
+            handler: "worker.js",
+            launcherType: "Nodejs",
+            supportsResponseStreaming: true,
+            ...regions,
+          };
+      await writeFile(join(fnDir, ".vc-config.json"), JSON.stringify(vcConfig, null, 2) + "\n");
+      // The bundle is ESM (worker.js + ./chunk-*.js all use `export`/`import`).
+      // The Node runtime loads the .func as CommonJS by default, so mark the whole
+      // function dir as ESM. (The edge runtime always treats sources as ESM.)
+      if (!isEdge) {
+        await writeFile(join(fnDir, "package.json"), JSON.stringify({ type: "module" }, null, 2) + "\n");
+      }
 
       // static: only the hashed framework assets under /_june/ (exact-path URLs)
       if (hasAssets) {

package/src/build.ts

@@ -378,12 +378,25 @@ export async function juneBuild(
     kv: !!resourcesCfg?.kv,
     blob: !!resourcesCfg?.blob,
   };
-  if (hasResources) {
+  // Two SQLite-dialect defaults, picked by the declared db's kind:
+  //   turso()         → libsql over HTTPS, connected from env (TURSO_*) via the
+  //                     bundled web client. Open the declared factory directly so it
+  //                     feeds the ambient `import { db }` scope (re-emitted by kind,
+  //                     not imported from the app config, to avoid the host barrel).
+  //   sqlite()/d1()   → a D1 binding from env (env.DB), via bindWorkerResources.
+  // (kv/blob on a turso deploy aren't wired yet — db-only.)
+  const tursoDb = resourcesCfg?.db?.kind === "turso";
+  if (tursoDb) {
+    imports.push(`import { turso } from "@junejs/server/db";`);
+    imports.push(`import { memoizeResources } from "@junejs/server/resources";`);
+  } else if (hasResources) {
     imports.push(`import { bindWorkerResources } from "@junejs/server/resources";`);
   }
-  const resourcesField = hasResources
-    ? `\n  resources: bindWorkerResources(${JSON.stringify(resourceFlags)}),`
-    : "";
+  const resourcesField = tursoDb
+    ? `\n  resources: memoizeResources({ db: turso() }),`
+    : hasResources
+      ? `\n  resources: bindWorkerResources(${JSON.stringify(resourceFlags)}),`
+      : "";
 
   // Opt-in Tier-3 data layer: import its installDataLayer from the declared module
   // and call it at worker boot — the prod twin of the dev host's dataLayer.install()
@@ -521,10 +534,12 @@ ${adapterEntry.wrap("pipeline")}
     ? (JSON.parse(await Bun.file(pkgPath).text()) as { name?: string }).name
     : undefined;
   const defaultName = (pkgName ?? basename(appRoot)).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
-  // A declared `db` → a D1 binding named DB (the name bindWorkerResources reads).
-  const plan: ResourcePlan = resourcesCfg?.db
-    ? { db: { binding: "DB", databaseName: `${defaultName}-db` } }
-    : {};
+  // A declared D1-backed db (sqlite/d1) → a D1 binding named DB (the name
+  // bindWorkerResources reads). turso() connects from env, not a binding — no plan.
+  const plan: ResourcePlan =
+    resourcesCfg?.db && resourcesCfg.db.kind !== "turso"
+      ? { db: { binding: "DB", databaseName: `${defaultName}-db` } }
+      : {};
   await adapter.emit({ appRoot, outDir, hasAssets, linkHeader, config: fullConfig, plan, defaultName });
   if (plan.db) {
     console.log(

package/src/d1.ts

@@ -26,6 +26,7 @@ export interface D1Database {
 // already-bound D1Database.
 export function d1(binding: D1Database): DbFactory {
   const db: JuneDb = {
+    dialect: "sqlite", // D1 *is* sqlite — same SQL, same Juno compiler
     async query<T>(sql: string, params: unknown[] = []) {
       return (await binding.prepare(sql).bind(...params).all<T>()).results;
     },

package/src/db.ts

@@ -1,33 +1,38 @@
 // `db` resource adapters — implementations of the @junejs/core JuneDb contract.
 // Declared in june.config.ts (`resources.db: sqlite(...)` / `d1(...)`), opened
-// by the host, injected onto RouteContext as `ctx.db`. The framework depends on
-// the JuneDb contract; these adapters (and Juno on top) are swappable.
+// by the host and made ambient (`import { db } from "@junejs/db"`, via
+// runInScope — NOT on ctx). The framework depends on the JuneDb contract; these
+// adapters (and Juno on top) are swappable.
 //
-// sqlite() is host-coupled (node:fs + ./host) and DEV-only. The edge-safe d1()
-// adapter lives in ./d1 so the generated worker can import it without dragging
-// this module's host imports into the workerd bundle; it is re-exported here so
-// `@junejs/server/db` stays the one place both db adapters are named.
-
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+// This module is HOST-FREE so the generated worker can import it (e.g. `turso`)
+// without dragging node:fs / the dev host into the bundle (reminder #4). The two
+// host-coupled adapters keep their host touch out of the static graph:
+//   - d1()    lives in ./d1 (edge-safe; env binding).
+//   - sqlite() is DEV-only and imports node:fs + ./host LAZILY, inside open().
+// All five (sqlite/d1/postgres/mysql/turso) are named from this one place.
 
 import type { DbFactory } from "@junejs/core/resources";
 
-import { host } from "./host";
-
 export { d1, type D1Database } from "./d1";
+export { postgres, pgJuneDb, type PgClientLike } from "./postgres-driver";
+export { mysql, mysqlJuneDb, type MysqlConnLike } from "./mysql-driver";
+export { turso, libsqlJuneDb, type LibsqlClientLike } from "./turso-driver";
 
 // Local SQLite — the zero-config dev default. A persistent FILE, not :memory:,
 // on purpose: `june dev` restarts the process on every save (the watch
 // supervisor), so an in-memory default would evaporate your dev data at each
 // edit. A file also makes the dev db inspectable with the sqlite3 every
 // machine already has (`sqlite3 .june/dev.sqlite`). Pass ":memory:" explicitly
-// for ephemerality.
+// for ephemerality. node:fs + ./host are imported lazily so this module stays
+// host-free (sqlite() only runs in dev, where the imports resolve).
 export function sqlite(opts: { path?: string } = {}): DbFactory {
   const path = opts.path ?? ".june/dev.sqlite";
   return {
     kind: "sqlite",
-    open: () => {
+    open: async () => {
+      const { mkdirSync } = await import("node:fs");
+      const { dirname } = await import("node:path");
+      const { host } = await import("./host");
       if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
       return host.openDb(path);
     },

package/src/host.ts

@@ -49,7 +49,7 @@ export interface JuneHost {
   // this with the in-isolate dual-graph loader; the seam stays for the fallback.
   spawnModule(entry: string, args: string[], opts: { conditions?: string[] }): SpawnedModule;
   // Open a LOCAL SQLite database — the internal primitive the `sqlite()` db
-  // adapter builds on (docs/data-layer-boundary.md: openDb is demoted from the
+  // adapter builds on (docs/data-layer.md: openDb is demoted from the
   // user-facing API to a host primitive; apps declare `resources.db` instead).
   openDb(path: string): Promise<JuneDb>;
 }

package/src/index.ts

@@ -11,7 +11,7 @@ export {
   type AdapterEmitContext,
 } from "./adapter";
 export { host, type JuneHost, type JuneDb, type RunResult, type ServeHandle, type SpawnedModule } from "./host";
-export { sqlite, d1, type D1Database } from "./db";
+export { sqlite, d1, postgres, mysql, turso, type D1Database } from "./db";
 export { memoryKv, redisKv } from "./kv";
 export { localBlob, r2, type R2Bucket } from "./blob";
 export {

package/src/kv.ts

@@ -1,4 +1,4 @@
-// `kv` resource adapters. The kv resource IS the cache (docs/data-layer-boundary
+// `kv` resource adapters. The kv resource IS the cache (docs/data-layer
 // .md: "reframe cache as the kv resource — it already is one"): these wrap
 // @junejs/core/cache's CacheStore (memory / redis) as the simpler JuneKv contract,
 // so there is ONE key-value system, surfaced both as cache() and as ambient kv.

package/src/mysql-driver.ts

@@ -0,0 +1,68 @@
+// MySQL `db` adapter — implements the @junejs/core JuneDb contract over `mysql2`.
+// Tags itself `dialect: "mysql"` so Juno compiles backtick / `?` / ON DUPLICATE KEY
+// SQL for it. `mysql2` is dynamically imported (a peer the app installs only when it
+// declares `mysql()`). Test/dev grade: ONE connection per open(); pooling / env
+// binding come later.
+
+import type { DbFactory, JuneDb, RunResult } from "@junejs/core/resources";
+
+// mysql2 returns [rows, fields]; a write yields a ResultSetHeader as the first element.
+interface OkHeader {
+  affectedRows?: number;
+  insertId?: number;
+}
+// The slice of mysql2/promise's Connection we depend on — so mysqlJuneDb is fakeable.
+export interface MysqlConnLike {
+  query(sql: string, params?: unknown[]): Promise<[unknown, unknown]>;
+  end(): Promise<void>;
+}
+
+// Wrap a mysql2 connection as a JuneDb. Exported for offline unit tests.
+export function mysqlJuneDb(conn: MysqlConnLike): JuneDb {
+  const self: JuneDb = {
+    dialect: "mysql",
+    async query<T>(sql: string, params: unknown[] = []) {
+      return (await conn.query(sql, params))[0] as T[];
+    },
+    async get<T>(sql: string, params: unknown[] = []) {
+      const rows = (await conn.query(sql, params))[0] as unknown[];
+      return (rows[0] ?? undefined) as T | undefined;
+    },
+    async run(sql: string, params: unknown[] = []): Promise<RunResult> {
+      const header = (await conn.query(sql, params))[0] as OkHeader;
+      return { changes: header.affectedRows ?? 0, lastInsertRowid: header.insertId ?? 0 };
+    },
+    async exec(sql: string) {
+      await conn.query(sql); // needs multipleStatements for a multi-statement script
+    },
+    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
+      await conn.query("begin");
+      try {
+        const out = await fn(self);
+        await conn.query("commit");
+        return out;
+      } catch (e) {
+        await conn.query("rollback");
+        throw e;
+      }
+    },
+    async close() {
+      await conn.end();
+    },
+  };
+  return self;
+}
+
+// `mysql({ url })` — multipleStatements is on so exec() can run a whole migration file.
+export function mysql(opts: { url: string }): DbFactory {
+  return {
+    kind: "mysql",
+    open: async () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const mod = (await import("mysql2/promise")) as any;
+      const create = (mod.default ?? mod).createConnection;
+      const conn = await create({ uri: opts.url, multipleStatements: true });
+      return mysqlJuneDb(conn);
+    },
+  };
+}

package/src/postgres-driver.ts

@@ -0,0 +1,67 @@
+// Postgres `db` adapter — implements the @junejs/core JuneDb contract over
+// node-postgres (`pg`). Tags itself `dialect: "postgres"` so Juno compiles `$n` /
+// double-quoted SQL for it (see @junejs/juno's dialectFor). `pg` is dynamically
+// imported, so it's a peer the app installs only when it declares `postgres()` — the
+// host never hard-depends on it. Test/dev grade: ONE connection per open(); pooling /
+// env binding / deploy adapters come in a later step.
+
+import type { DbFactory, JuneDb, RunResult } from "@junejs/core/resources";
+
+// The slice of `pg`'s Client we depend on — so pgJuneDb is unit-testable with a fake.
+export interface PgClientLike {
+  query(sql: string, params?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+  end(): Promise<void>;
+}
+
+// Wrap a connected pg client as a JuneDb. Exported (not just the factory) so the
+// mapping — rows, first-row, RunResult, transaction ordering — is testable offline.
+export function pgJuneDb(client: PgClientLike): JuneDb {
+  const self: JuneDb = {
+    dialect: "postgres",
+    async query<T>(sql: string, params: unknown[] = []) {
+      return (await client.query(sql, params)).rows as T[];
+    },
+    async get<T>(sql: string, params: unknown[] = []) {
+      return ((await client.query(sql, params)).rows[0] ?? undefined) as T | undefined;
+    },
+    async run(sql: string, params: unknown[] = []): Promise<RunResult> {
+      const r = await client.query(sql, params);
+      // Postgres has no autoincrement rowid — callers use `RETURNING id`. Report the
+      // affected-row count; lastInsertRowid is 0 (not meaningful on PG).
+      return { changes: r.rowCount ?? 0, lastInsertRowid: 0 };
+    },
+    async exec(sql: string) {
+      await client.query(sql); // DDL / multi-statement via the simple-query protocol
+    },
+    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
+      await client.query("begin");
+      try {
+        const out = await fn(self); // same connection
+        await client.query("commit");
+        return out;
+      } catch (e) {
+        await client.query("rollback");
+        throw e;
+      }
+    },
+    async close() {
+      await client.end();
+    },
+  };
+  return self;
+}
+
+// `postgres({ url })` — declared in june.config.ts; opened by the host.
+export function postgres(opts: { url: string }): DbFactory {
+  return {
+    kind: "postgres",
+    open: async () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const mod = (await import("pg")) as any;
+      const Client = (mod.default ?? mod).Client;
+      const client = new Client({ connectionString: opts.url });
+      await client.connect();
+      return pgJuneDb(client);
+    },
+  };
+}

package/src/resources.ts

@@ -1,7 +1,9 @@
 // Resource resolution — open the handles declared in june.config.ts `resources`
-// and hand them to the pipeline, which injects them onto RouteContext (ctx.db /
-// ctx.kv / ctx.blob). A resource not declared is never opened (and, for static
-// apps, tree-shaken out — the build freeze knows which routes touch resources).
+// and hand them to the pipeline, which runs each request inside runInScope() so
+// they resolve AMBIENTLY (`import { db } from "@junejs/db"`). ctx never carries
+// them — ctx is identity-only (see route.ts). A resource not declared is never
+// opened (and, for static apps, tree-shaken out — the build freeze knows which
+// routes touch resources).
 
 import type { ResourceConfig, Resources } from "@junejs/core/resources";
 
@@ -48,7 +50,7 @@ export type ResourceFlags = { db?: boolean; kv?: boolean; blob?: boolean };
 // from env (env.DB → D1) — the prod half of "sqlite dev → D1 prod, one
 // declaration": the same `resources: { db: sqlite() }` runs on D1 at the edge,
 // because D1 *is* SQLite (same SQL, same Juno tables). No env binding → the
-// handle is absent and the route degrades (ctx.db undefined), never a crash.
+// handle is absent and the route degrades (ambient `db` unavailable), never a crash.
 // Memoized per isolate (env is stable across requests in a workerd isolate).
 //
 // env is typed `unknown` (it arrives untyped from the runtime) and narrowed to

package/src/sqlite-driver.ts

@@ -51,6 +51,7 @@ function asyncSqlite(db: SyncSqlite): JuneDb {
     return s;
   };
   const self: JuneDb = {
+    dialect: "sqlite",
     async query<T>(sql: string, params: unknown[] = []) {
       return prep(sql).all(...params) as T[];
     },

package/src/turso-driver.ts

@@ -0,0 +1,96 @@
+// Turso / libsql `db` adapter — implements the @junejs/core JuneDb contract over
+// @libsql/client. Turso speaks libsql (SQLite over an HTTPS endpoint), so it tags
+// itself `dialect: "sqlite"`: Juno compiles the exact same `?`-placeholder SQLite
+// SQL it uses for the local sqlite() adapter, and the connection is a plain URL +
+// token (no TCP socket, no platform binding) — so it runs on the Vercel Node
+// runtime, on edge, and anywhere with fetch. `@libsql/client` is dynamically
+// imported: a peer the app installs only when it declares turso(); the host never
+// hard-depends on it. Host-free (no node:* / ./host) so it can enter a worker
+// bundle, unlike sqlite().
+
+import type { DbFactory, JuneDb, RunResult } from "@junejs/core/resources";
+
+// The slice of @libsql/client's Client we depend on — so libsqlJuneDb is
+// unit-testable with a fake (no network).
+export interface LibsqlResultSet {
+  rows: unknown[];
+  rowsAffected: number;
+  lastInsertRowid?: bigint | number;
+}
+export interface LibsqlClientLike {
+  execute(stmt: { sql: string; args?: unknown[] } | string): Promise<LibsqlResultSet>;
+  executeMultiple?(sql: string): Promise<void>;
+  close(): void | Promise<void>;
+}
+
+// Wrap a libsql client as a JuneDb. Exported (not just the factory) so the mapping
+// — rows, first-row, RunResult, transaction ordering — is testable offline.
+export function libsqlJuneDb(client: LibsqlClientLike): JuneDb {
+  const self: JuneDb = {
+    dialect: "sqlite", // libsql IS sqlite — same SQL + Juno tables as sqlite()/d1()
+    async query<T>(sql: string, params: unknown[] = []) {
+      return (await client.execute({ sql, args: params })).rows as T[];
+    },
+    async get<T>(sql: string, params: unknown[] = []) {
+      return ((await client.execute({ sql, args: params })).rows[0] ?? undefined) as T | undefined;
+    },
+    async run(sql: string, params: unknown[] = []): Promise<RunResult> {
+      const r = await client.execute({ sql, args: params });
+      // libsql returns lastInsertRowid as a bigint; RunResult is number-ish.
+      return { changes: r.rowsAffected ?? 0, lastInsertRowid: Number(r.lastInsertRowid ?? 0) };
+    },
+    async exec(sql: string) {
+      // DDL / migrations are multi-statement; executeMultiple splits on `;`.
+      if (client.executeMultiple) await client.executeMultiple(sql);
+      else await client.execute(sql);
+    },
+    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
+      // Test/dev grade, matching postgres()/mysql(): BEGIN/COMMIT on the one
+      // client. (For strict isolation over HTTP, libsql's interactive
+      // client.transaction() is the upgrade path.)
+      await client.execute("BEGIN");
+      try {
+        const out = await fn(self);
+        await client.execute("COMMIT");
+        return out;
+      } catch (e) {
+        await client.execute("ROLLBACK");
+        throw e;
+      }
+    },
+    async close() {
+      await client.close();
+    },
+  };
+  return self;
+}
+
+// `turso({ url, authToken })` — declared in june.config.ts, or omit both to read
+// the standard TURSO_DATABASE_URL / TURSO_AUTH_TOKEN env vars at open() time
+// (NOT at construction — so the build can evaluate the config without the secrets
+// present, and the deployed function reads them from its own environment).
+export function turso(opts: { url?: string; authToken?: string } = {}): DbFactory {
+  return {
+    kind: "turso",
+    open: async () => {
+      const url = opts.url ?? readEnv("TURSO_DATABASE_URL");
+      const authToken = opts.authToken ?? readEnv("TURSO_AUTH_TOKEN");
+      if (!url) {
+        throw new Error(
+          "turso(): no database url — pass { url } or set TURSO_DATABASE_URL in the environment.",
+        );
+      }
+      // The pure-fetch web client: works in dev (Bun) AND bundles into the one
+      // deployed function (the node client would pull native bindings). Turso is
+      // remote (libsql:// over HTTPS), which is exactly what the web client speaks.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const mod = (await import("@libsql/client/web")) as any;
+      const createClient = (mod.default ?? mod).createClient;
+      return libsqlJuneDb(createClient({ url, authToken }));
+    },
+  };
+}
+
+function readEnv(name: string): string | undefined {
+  return typeof process !== "undefined" && process.env ? process.env[name] : undefined;
+}