@porulle/adapter-neon 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unified-commerce-engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @porulle/adapter-neon
+
+Workers-grade Neon `DatabaseAdapter` for `@porulle/core`.
+
+Two transports, picked by query type — the design proven in production by
+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.
+
+## Usage
+
+```ts
+import { defineConfig } from "@porulle/core";
+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
+    hyperdrive: env.HYPERDRIVE,
+  }),
+  // ...
+});
+```
+
+- `connectionString` — direct Neon URL (`postgresql://...neon.tech/...`).
+  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`.
+
+`.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

@@ -0,0 +1,28 @@
+import { type NeonHttpDatabase } from "drizzle-orm/neon-http";
+import { type NeonDatabase } from "drizzle-orm/neon-serverless";
+import type { DatabaseAdapter } from "@porulle/core";
+type HttpClient = NeonHttpDatabase<Record<string, unknown>>;
+type WsClient = NeonDatabase<Record<string, unknown>>;
+type AnyDb = HttpClient | WsClient;
+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`.
+     */
+    hyperdrive?: {
+        connectionString: string;
+    } | undefined;
+}
+export type NeonDatabaseAdapter = DatabaseAdapter<HttpClient, unknown>;
+/**
+ * Normalizes `.execute()` to the postgres-js shape (array of rows). Core and
+ * custom routes iterate `.execute()` results directly; the raw neon drivers
+ * return `{ rows, command, rowCount }`, which breaks that contract.
+ */
+export declare function normalizeExecuteShape<T extends AnyDb>(db: T): T;
+export declare function neonAdapter(options: NeonAdapterOptions): NeonDatabaseAdapter;
+export {};
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * Workers-grade Neon DatabaseAdapter for @porulle/core (issue #55).
+ *
+ * Two transports, picked by query type — the design proven in production by
+ * porulle's first adopter (ordereka-fashion-pos, live on Cloudflare Workers):
+ *
+ *   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.
+ *
+ * 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.
+ */
+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";
+if (typeof WebSocket !== "undefined") {
+    neonConfig.webSocketConstructor = WebSocket;
+}
+/**
+ * Normalizes `.execute()` to the postgres-js shape (array of rows). Core and
+ * custom routes iterate `.execute()` results directly; the raw neon drivers
+ * return `{ rows, command, rowCount }`, which breaks that contract.
+ */
+export function normalizeExecuteShape(db) {
+    const handler = {
+        get(target, prop, receiver) {
+            const orig = Reflect.get(target, prop, receiver);
+            if (prop === "execute" && typeof orig === "function") {
+                return async (...args) => {
+                    const result = await orig.apply(target, args);
+                    if (result &&
+                        typeof result === "object" &&
+                        "rows" in result &&
+                        Array.isArray(result.rows)) {
+                        return result.rows;
+                    }
+                    return result;
+                };
+            }
+            return orig;
+        },
+    };
+    return new Proxy(db, handler);
+}
+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 });
+        try {
+            const wsDb = normalizeExecuteShape(drizzleWs(pool));
+            return await wsDb.transaction(async (tx) => fn(normalizeExecuteShape(tx)));
+        }
+        finally {
+            // Best-effort: Pool.end() over WebSocket in Workers can be a no-op but
+            // never throws into the transaction result.
+            await pool.end().catch(() => { });
+        }
+    };
+    // 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 Reflect.get(target, prop, receiver);
+        },
+    });
+    return {
+        provider: "postgresql",
+        db: dbWithTx,
+        async transaction(fn) {
+            return runInFreshPool(fn);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@porulle/adapter-neon",
+  "version": "0.8.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@neondatabase/serverless": "^1.0.1",
+    "drizzle-orm": "^0.45.1",
+    "@porulle/core": "0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4",
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "Workers-grade Neon DatabaseAdapter for @porulle/core: HTTP driver for plain queries, a fresh WebSocket Pool per transaction, Hyperdrive-aware.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/adapters/adapter-neon"
+  },
+  "author": "Porulle contributors",
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+/**
+ * Workers-grade Neon DatabaseAdapter for @porulle/core (issue #55).
+ *
+ * Two transports, picked by query type — the design proven in production by
+ * porulle's first adopter (ordereka-fashion-pos, live on Cloudflare Workers):
+ *
+ *   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.
+ *
+ * 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.
+ */
+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 type { DatabaseAdapter } from "@porulle/core";
+
+if (typeof WebSocket !== "undefined") {
+  neonConfig.webSocketConstructor = WebSocket as unknown as typeof neonConfig.webSocketConstructor;
+}
+
+type HttpClient = NeonHttpDatabase<Record<string, unknown>>;
+type WsClient = NeonDatabase<Record<string, unknown>>;
+type AnyDb = HttpClient | WsClient;
+
+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`.
+   */
+  hyperdrive?: { connectionString: string } | undefined;
+}
+
+export type NeonDatabaseAdapter = DatabaseAdapter<HttpClient, unknown>;
+
+/**
+ * Normalizes `.execute()` to the postgres-js shape (array of rows). Core and
+ * custom routes iterate `.execute()` results directly; the raw neon drivers
+ * return `{ rows, command, rowCount }`, which breaks that contract.
+ */
+export function normalizeExecuteShape<T extends AnyDb>(db: T): T {
+  const handler: ProxyHandler<T> = {
+    get(target, prop, receiver) {
+      const orig = Reflect.get(target, prop, receiver);
+      if (prop === "execute" && typeof orig === "function") {
+        return async (...args: unknown[]) => {
+          const result = await (orig as (...a: unknown[]) => Promise<unknown>).apply(target, args);
+          if (
+            result &&
+            typeof result === "object" &&
+            "rows" in result &&
+            Array.isArray((result as { rows: unknown[] }).rows)
+          ) {
+            return (result as { rows: unknown[] }).rows;
+          }
+          return result;
+        };
+      }
+      return orig;
+    },
+  };
+  return new Proxy(db, handler);
+}
+
+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 });
+    try {
+      const wsDb = normalizeExecuteShape(drizzleWs(pool) as WsClient);
+      return await wsDb.transaction(async (tx) => fn(normalizeExecuteShape(tx as WsClient)));
+    } finally {
+      // Best-effort: Pool.end() over WebSocket in Workers can be a no-op but
+      // never throws into the transaction result.
+      await pool.end().catch(() => {});
+    }
+  };
+
+  // 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 Reflect.get(target, prop, receiver);
+    },
+  }) as HttpClient;
+
+  return {
+    provider: "postgresql",
+    db: dbWithTx,
+    async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+      return runInFreshPool(fn) as Promise<T>;
+    },
+  };
+}