@porulle/adapter-neon 0.10.4 → 0.10.6

package/README.md

@@ -7,11 +7,11 @@ porulle's first adopter (a live iPad POS on Cloudflare Workers + Neon):
 
 1. **Plain queries** go through `@neondatabase/serverless` HTTP — stateless,
    no socket-reuse races across Workers isolates.
-2. **`transaction()`** creates a fresh WebSocket `Pool` per call, runs the
-   transaction, then ends the pool. `drizzle-orm/neon-http` cannot run
-   transactions, and isolate-shared WebSocket pools flake when reused across
-   requests; a short-lived pool per transaction gives atomicity without the
-   flake.
+2. **`transaction()`** creates a fresh client per call and closes it before the
+   request completes. Direct Neon connections use a WebSocket `Pool`;
+   Hyperdrive connections use Postgres.js over Workers TCP. This distinction is
+   required because Neon WebSocket clients cannot speak to Hyperdrive's TCP
+   endpoint. `drizzle-orm/neon-http` cannot run interactive transactions.
 
 ## Usage
 
@@ -22,7 +22,7 @@ import { neonAdapter } from "@porulle/adapter-neon";
 export default defineConfig({
   databaseAdapter: neonAdapter({
     connectionString: env.DATABASE_URL, // direct Neon URL
-    // Optional: route per-transaction pools through Hyperdrive
+    // Optional: route transactions through Hyperdrive using Postgres.js
     hyperdrive: env.HYPERDRIVE,
   }),
   // ...
@@ -33,8 +33,9 @@ export default defineConfig({
   Used by the HTTP driver, and by transaction pools when no Hyperdrive
   binding is given.
 - `hyperdrive` — optional Cloudflare Hyperdrive binding (any object exposing
-  `connectionString`). When set, per-transaction pools connect through it;
-  plain queries keep using the Neon HTTP driver against `connectionString`.
+  `connectionString`). When set, transactions use a fresh Postgres.js client
+  over Hyperdrive; plain queries keep using Neon HTTP against
+  `connectionString`.
 
 `.execute()` results are normalized to the postgres-js shape (an array of
 rows), matching what `@porulle/core` and custom routes expect.

package/dist/index.d.ts

@@ -1,16 +1,18 @@
 import { type NeonHttpDatabase } from "drizzle-orm/neon-http";
 import { type NeonDatabase } from "drizzle-orm/neon-serverless";
+import { type PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { DatabaseAdapter } from "@porulle/core";
 type HttpClient = NeonHttpDatabase<Record<string, unknown>>;
 type WsClient = NeonDatabase<Record<string, unknown>>;
-type AnyDb = HttpClient | WsClient;
+type PgClient = PostgresJsDatabase<Record<string, never>>;
+type AnyDb = HttpClient | WsClient | PgClient;
 export interface NeonAdapterOptions {
     /** Direct Neon connection string (postgresql://...neon.tech/...). */
     connectionString: string;
     /**
      * Optional Cloudflare Hyperdrive binding (or any object exposing
-     * `connectionString`). When set, per-transaction pools connect through it;
-     * plain queries keep using the Neon HTTP driver against `connectionString`.
+     * `connectionString`). When set, transactions use a fresh Postgres.js TCP
+     * client through Hyperdrive; plain queries keep using Neon HTTP directly.
      */
     hyperdrive?: {
         connectionString: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAMrD,KAAK,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5D,KAAK,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AACtD,KAAK,KAAK,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEnC,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CACvD;AAED,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAsB/D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,mBAAmB,CAsC5E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACtF,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAExF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAMrD,KAAK,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5D,KAAK,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AACtD,KAAK,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAC1D,KAAK,KAAK,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CACvD;AAED,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAsB/D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,mBAAmB,CA0D5E"}

package/dist/index.js

@@ -7,20 +7,21 @@
  *   1. Plain queries (select / insert / update / delete / raw execute) go
  *      through `@neondatabase/serverless` HTTP — stateless, no socket-reuse
  *      races across Workers isolates.
- *   2. `transaction()` creates a FRESH WebSocket `Pool` per call, runs the
- *      transaction, then ends the pool. `drizzle-orm/neon-http` throws on
- *      `db.transaction()` ("No transactions support"), and isolate-shared
- *      WebSocket pools flake (~30% observed) when reused across requests —
- *      a short-lived pool per transaction gives atomicity without the flake.
+ *   2. `transaction()` creates a FRESH client per call. Direct Neon uses its
+ *      WebSocket `Pool`; Hyperdrive uses Postgres.js over Workers TCP. Both
+ *      clients are closed before the request completes. `drizzle-orm/neon-http`
+ *      throws on `db.transaction()` ("No transactions support").
  *
  * Hyperdrive-aware: pass the binding (`{ hyperdrive: env.HYPERDRIVE }`) and
- * its connection string is used for the per-transaction pools, keeping pool
- * setup on Cloudflare's fast path. The HTTP driver always speaks directly to
- * Neon, so a direct `connectionString` is still required alongside it.
+ * its TCP connection string is used by Postgres.js for transactions. A Neon
+ * WebSocket client cannot speak to Hyperdrive's TCP endpoint. The HTTP driver
+ * always speaks directly to Neon, so a direct `connectionString` is required.
  */
 import { Pool, neon, neonConfig } from "@neondatabase/serverless";
 import { drizzle as drizzleHttp } from "drizzle-orm/neon-http";
 import { drizzle as drizzleWs } from "drizzle-orm/neon-serverless";
+import { drizzle as drizzlePg } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
 if (typeof WebSocket !== "undefined") {
     neonConfig.webSocketConstructor = WebSocket;
 }
@@ -52,11 +53,10 @@ export function normalizeExecuteShape(db) {
 }
 export function neonAdapter(options) {
     const httpConnectionString = options.connectionString;
-    const poolConnectionString = options.hyperdrive?.connectionString ?? options.connectionString;
     const sql = neon(httpConnectionString);
     const httpDb = normalizeExecuteShape(drizzleHttp(sql));
-    const runInFreshPool = async (fn) => {
-        const pool = new Pool({ connectionString: poolConnectionString });
+    const runInFreshNeonPool = async (fn) => {
+        const pool = new Pool({ connectionString: options.connectionString });
         try {
             const wsDb = normalizeExecuteShape(drizzleWs(pool));
             return await wsDb.transaction(async (tx) => fn(normalizeExecuteShape(tx)));
@@ -67,13 +67,31 @@ export function neonAdapter(options) {
             await pool.end().catch(() => { });
         }
     };
+    const runInFreshHyperdriveClient = async (fn) => {
+        const client = postgres(options.hyperdrive.connectionString, {
+            max: 1,
+            prepare: false,
+            connect_timeout: 10,
+            idle_timeout: 5,
+        });
+        try {
+            const pgDb = normalizeExecuteShape(drizzlePg(client));
+            return await pgDb.transaction(async (tx) => fn(normalizeExecuteShape(tx)));
+        }
+        finally {
+            await client.end({ timeout: 1 }).catch(() => { });
+        }
+    };
+    const runTransaction = options.hyperdrive
+        ? runInFreshHyperdriveClient
+        : runInFreshNeonPool;
     // Some core paths call `kernel.database.db.transaction(...)` directly —
     // splice the pool-backed transaction onto the HTTP client so both entry
     // points behave identically.
     const dbWithTx = new Proxy(httpDb, {
         get(target, prop, receiver) {
             if (prop === "transaction") {
-                return runInFreshPool;
+                return runTransaction;
             }
             return Reflect.get(target, prop, receiver);
         },
@@ -82,7 +100,7 @@ export function neonAdapter(options) {
         provider: "postgresql",
         db: dbWithTx,
         async transaction(fn) {
-            return runInFreshPool(fn);
+            return runTransaction(fn);
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/adapter-neon",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -13,7 +13,8 @@
   "dependencies": {
     "@neondatabase/serverless": "^1.0.1",
     "drizzle-orm": "^0.45.1",
-    "@porulle/core": "0.10.4"
+    "postgres": "^3.4.7",
+    "@porulle/core": "0.10.6"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
@@ -31,7 +32,7 @@
     "dist",
     "README.md"
   ],
-  "description": "Workers-grade Neon DatabaseAdapter for @porulle/core: HTTP driver for plain queries, a fresh WebSocket Pool per transaction, Hyperdrive-aware.",
+  "description": "Workers-grade Neon DatabaseAdapter for @porulle/core: Neon HTTP queries with request-scoped Neon or Hyperdrive transactions.",
   "homepage": "https://porulle-docs.vercel.app",
   "bugs": {
     "url": "https://github.com/asyncdotengineering/porulle/issues"

package/src/index.ts

@@ -7,20 +7,21 @@
  *   1. Plain queries (select / insert / update / delete / raw execute) go
  *      through `@neondatabase/serverless` HTTP — stateless, no socket-reuse
  *      races across Workers isolates.
- *   2. `transaction()` creates a FRESH WebSocket `Pool` per call, runs the
- *      transaction, then ends the pool. `drizzle-orm/neon-http` throws on
- *      `db.transaction()` ("No transactions support"), and isolate-shared
- *      WebSocket pools flake (~30% observed) when reused across requests —
- *      a short-lived pool per transaction gives atomicity without the flake.
+ *   2. `transaction()` creates a FRESH client per call. Direct Neon uses its
+ *      WebSocket `Pool`; Hyperdrive uses Postgres.js over Workers TCP. Both
+ *      clients are closed before the request completes. `drizzle-orm/neon-http`
+ *      throws on `db.transaction()` ("No transactions support").
  *
  * Hyperdrive-aware: pass the binding (`{ hyperdrive: env.HYPERDRIVE }`) and
- * its connection string is used for the per-transaction pools, keeping pool
- * setup on Cloudflare's fast path. The HTTP driver always speaks directly to
- * Neon, so a direct `connectionString` is still required alongside it.
+ * its TCP connection string is used by Postgres.js for transactions. A Neon
+ * WebSocket client cannot speak to Hyperdrive's TCP endpoint. The HTTP driver
+ * always speaks directly to Neon, so a direct `connectionString` is required.
  */
 import { Pool, neon, neonConfig } from "@neondatabase/serverless";
 import { drizzle as drizzleHttp, type NeonHttpDatabase } from "drizzle-orm/neon-http";
 import { drizzle as drizzleWs, type NeonDatabase } from "drizzle-orm/neon-serverless";
+import { drizzle as drizzlePg, type PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
 import type { DatabaseAdapter } from "@porulle/core";
 
 if (typeof WebSocket !== "undefined") {
@@ -29,15 +30,16 @@ if (typeof WebSocket !== "undefined") {
 
 type HttpClient = NeonHttpDatabase<Record<string, unknown>>;
 type WsClient = NeonDatabase<Record<string, unknown>>;
-type AnyDb = HttpClient | WsClient;
+type PgClient = PostgresJsDatabase<Record<string, never>>;
+type AnyDb = HttpClient | WsClient | PgClient;
 
 export interface NeonAdapterOptions {
   /** Direct Neon connection string (postgresql://...neon.tech/...). */
   connectionString: string;
   /**
    * Optional Cloudflare Hyperdrive binding (or any object exposing
-   * `connectionString`). When set, per-transaction pools connect through it;
-   * plain queries keep using the Neon HTTP driver against `connectionString`.
+   * `connectionString`). When set, transactions use a fresh Postgres.js TCP
+   * client through Hyperdrive; plain queries keep using Neon HTTP directly.
    */
   hyperdrive?: { connectionString: string } | undefined;
 }
@@ -75,13 +77,12 @@ export function normalizeExecuteShape<T extends AnyDb>(db: T): T {
 
 export function neonAdapter(options: NeonAdapterOptions): NeonDatabaseAdapter {
   const httpConnectionString = options.connectionString;
-  const poolConnectionString = options.hyperdrive?.connectionString ?? options.connectionString;
 
   const sql = neon(httpConnectionString);
   const httpDb = normalizeExecuteShape(drizzleHttp(sql) as HttpClient);
 
-  const runInFreshPool = async (fn: (tx: unknown) => Promise<unknown>): Promise<unknown> => {
-    const pool = new Pool({ connectionString: poolConnectionString });
+  const runInFreshNeonPool = async (fn: (tx: unknown) => Promise<unknown>): Promise<unknown> => {
+    const pool = new Pool({ connectionString: options.connectionString });
     try {
       const wsDb = normalizeExecuteShape(drizzleWs(pool) as WsClient);
       return await wsDb.transaction(async (tx) => fn(normalizeExecuteShape(tx as WsClient)));
@@ -92,13 +93,34 @@ export function neonAdapter(options: NeonAdapterOptions): NeonDatabaseAdapter {
     }
   };
 
+  const runInFreshHyperdriveClient = async (
+    fn: (tx: unknown) => Promise<unknown>,
+  ): Promise<unknown> => {
+    const client = postgres(options.hyperdrive!.connectionString, {
+      max: 1,
+      prepare: false,
+      connect_timeout: 10,
+      idle_timeout: 5,
+    });
+    try {
+      const pgDb = normalizeExecuteShape(drizzlePg(client) as PgClient);
+      return await pgDb.transaction(async (tx) => fn(normalizeExecuteShape(tx as PgClient)));
+    } finally {
+      await client.end({ timeout: 1 }).catch(() => {});
+    }
+  };
+
+  const runTransaction = options.hyperdrive
+    ? runInFreshHyperdriveClient
+    : runInFreshNeonPool;
+
   // Some core paths call `kernel.database.db.transaction(...)` directly —
   // splice the pool-backed transaction onto the HTTP client so both entry
   // points behave identically.
   const dbWithTx = new Proxy(httpDb, {
     get(target, prop, receiver) {
       if (prop === "transaction") {
-        return runInFreshPool;
+        return runTransaction;
       }
       return Reflect.get(target, prop, receiver);
     },
@@ -108,7 +130,7 @@ export function neonAdapter(options: NeonAdapterOptions): NeonDatabaseAdapter {
     provider: "postgresql",
     db: dbWithTx,
     async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
-      return runInFreshPool(fn) as Promise<T>;
+      return runTransaction(fn) as Promise<T>;
     },
   };
 }