@lostgradient/weft 0.2.1 → 0.3.0

package/dist/storage/neon.d.ts

@@ -0,0 +1,108 @@
+import { type DeleteRangeOptions } from './delete-range.ts';
+import { type BatchOperation, type ConditionalBatchCondition, type ScanOptions, type Storage, type StorageCapabilities } from './interface.ts';
+import { type NeonQueryResult } from './neon-value-mapping.ts';
+/**
+ * A connection that can run a single interactive transaction. Obtained from
+ * {@link NeonPool.connect}; `release()` returns it to the pool. Both
+ * `batch()` and `conditionalBatch()` drive `BEGIN`/`COMMIT`/`ROLLBACK` over one
+ * of these so every statement in a transaction lands on the same connection —
+ * `pool.query()` alone may scatter statements across pooled connections, which
+ * would make a multi-statement batch non-atomic.
+ */
+export type NeonPoolClient = {
+    query(sql: string, parameters?: unknown[]): Promise<NeonQueryResult>;
+    release(): void;
+};
+/**
+ * Minimal structural view of a node-postgres `Pool`. The real Neon serverless
+ * `Pool` satisfies this; the PGlite test backend is wrapped to satisfy it too.
+ * `query()` runs a single statement on a pooled connection (used for the
+ * single-statement hot paths); `connect()` pins a connection for an interactive
+ * transaction; `end()` tears the pool down.
+ */
+export type NeonPool = {
+    query(sql: string, parameters?: unknown[]): Promise<NeonQueryResult>;
+    connect(): Promise<NeonPoolClient>;
+    end(): Promise<void>;
+};
+/**
+ * Configuration for connecting to a Neon (or any Postgres) database.
+ *
+ * @example
+ * ```ts
+ * import { NeonStorage, type NeonStorageOptions } from '@lostgradient/weft/storage/neon';
+ *
+ * const options: NeonStorageOptions = {
+ *   url: 'postgresql://user:password@ep-cool-name.us-east-2.aws.neon.tech/weft?sslmode=require',
+ * };
+ * await using storage = new NeonStorage(options);
+ * ```
+ */
+export type NeonStorageOptions = {
+    /** Postgres connection string for the primary endpoint. */
+    url: string;
+    /**
+     * Optional pre-built pool. Pass this to reuse a pool you manage (for example a
+     * test backend such as PGlite, or a shared application pool), instead of having
+     * the adapter construct its own from `url`. When supplied, `url` is ignored and
+     * **ownership stays with the caller**: disposing the `NeonStorage` does NOT
+     * close an injected pool, so it can be shared across adapters and the caller
+     * remains responsible for ending it. A pool the adapter constructs itself (from
+     * `url`) IS closed on disposal.
+     */
+    pool?: NeonPool;
+};
+/**
+ * Storage adapter backed by Neon serverless Postgres for durable, remote
+ * deployments. Implements the same `Storage` interface as the SQLite adapters
+ * over a single `kv(key TEXT COLLATE "C", value BYTEA)` table, so switching from
+ * a local SQLite store to Neon is a configuration change, not a code change.
+ *
+ * **Endpoint assumption.** `capabilities()` reports `readAfterWrite:
+ * 'linearizable'`, which holds for the **primary** Neon endpoint. A read-replica
+ * connection string would violate that guarantee — point this adapter at the
+ * primary.
+ *
+ * **WebSocket runtime.** The Neon serverless driver connects over WebSocket. Bun
+ * and Node 22+ provide a global `WebSocket`, so no extra wiring is needed there.
+ * On Node ≤21 the driver needs `neonConfig.webSocketConstructor` set to the `ws`
+ * package before first use; install `ws` and configure it in that runtime.
+ *
+ * @example
+ * ```ts
+ * import { NeonStorage } from '@lostgradient/weft/storage/neon';
+ * import { Engine } from '@lostgradient/weft';
+ *
+ * await using storage = new NeonStorage({
+ *   url: process.env['NEON_DATABASE_URL']!,
+ * });
+ * await using engine = new Engine({ storage });
+ * ```
+ */
+export declare class NeonStorage implements Storage {
+    #private;
+    /**
+     * @param options Connection configuration ({@link NeonStorageOptions}).
+     * @param poolFactory Internal seam for constructing the owned pool from `url`.
+     *   Defaults to the real driver `Pool`; tests inject a fake (for example one
+     *   whose `end()` rejects) to exercise owned-pool teardown without a network.
+     *   Used only when no `pool` is supplied; an injected `pool` stays caller-owned.
+     */
+    constructor(options: NeonStorageOptions, poolFactory?: (url: string) => NeonPool);
+    capabilities(): StorageCapabilities;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    deletePrefix(prefix: string): Promise<number>;
+    deleteRange(prefix: string, options: DeleteRangeOptions): Promise<number>;
+    scan(prefix: string, options?: ScanOptions): AsyncIterable<[string, Uint8Array]>;
+    keys(prefix: string, options?: ScanOptions): AsyncIterable<string>;
+    count(prefix: string): Promise<number>;
+    scoped(prefix: string): Storage;
+    batch(operations: BatchOperation[]): Promise<void>;
+    conditionalBatch(conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+    query<T>(sql: string, parameters?: unknown[]): Promise<T[]>;
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/storage/neon.js

@@ -0,0 +1,10 @@
+// @bun
+var $W=Object.defineProperty;var YW=(W)=>W;function jW(W,E){this[W]=YW.bind(null,E)}var zW=(W,E)=>{for(var F in E)$W(W,F,{get:E[F],enumerable:!0,configurable:!0,set:jW.bind(E,F)})};var j=(W,E)=>()=>(W&&(E=W(W=0)),E);function N(W,E,F){if(!W.capabilities()[E])throw Error(`Feature "${F}" requires storage capability "${E}", but this storage backend does not provide it.`)}function MW(W){let E=W.capabilities(),F=[];if(E.persistence!=="local"&&E.persistence!=="remote")F.push(`persistence must be "local" or "remote" (got "${E.persistence}")`);if(E.readAfterWrite!=="linearizable")F.push(`readAfterWrite must be "linearizable" (got "${E.readAfterWrite}")`);if(E.scanConsistency!=="snapshot")F.push(`scanConsistency must be "snapshot" (got "${E.scanConsistency}")`);if(!E.atomicBatch)F.push("atomicBatch must be true");if(!E.conditionalBatch)F.push("conditionalBatch must be true");if(F.length>0)throw Error(`Storage is not durable enough for recovery: ${F.join("; ")}.`)}var L="default";async function h(W,E){return await W.get(E)!==null}async function*U(W,E,F){for await(let[X]of W.scan(E,F))yield X}async function b(W,E){let F=0;for await(let X of U(W,E))F++;return F}async function C(W,E){let F=[];for await(let X of U(W,E))F.push({type:"delete",key:X});if(F.length===0)return 0;return await W.batch(F),F.length}async function K(W,E,F){let X=[];for await(let J of U(W,E,F))X.push({type:"delete",key:J});if(X.length===0)return 0;return await W.batch(X),X.length}var UW;var S=j(()=>{UW=["actrec:","archive:","async-act:","attr:","audit:bulk:","blob:","budget:","budget-charged:","ev:","idx:","liveness:","offload:","op:","review:","schedule:","schedule-due:","schedule-run:","sig:","sigres:","sigseq:","start-idem:","state:","tag:","tool-effect:","upd:","upk:","upr:","wf:","wf-cleanup:","wf-cleanup-needed:","wf-deadline:","wf-delayed:","wf-has-services:","wf-headers:","wf-idx-","wf-terminal:"]});function I(W){return W.length>0?W.slice(0,-1)+String.fromCharCode(W.charCodeAt(W.length-1)+1):"\xFF"}function IW(W,E={}){if(E.gt!==void 0&&W<=E.gt)return!1;if(E.gte!==void 0&&W<E.gte)return!1;if(E.lt!==void 0&&W>=E.lt)return!1;if(E.lte!==void 0&&W>E.lte)return!1;return!0}function x(W,E){if(W===null||E===null)return W===E;if(W.byteLength!==E.byteLength)return!1;for(let F=0;F<W.byteLength;F++)if(W[F]!==E[F])return!1;return!0}async function u(W,E){if(W.has)return W.has(E);return h(W,E)}function k(W,E,F){if(W.keys)return W.keys(E,F);return U(W,E,F)}async function c(W,E){if(W.count)return W.count(E);return b(W,E)}async function w(W,E){if(W.deletePrefix)return W.deletePrefix(E);return C(W,E)}async function y(W,E,F){if(N(W,"conditionalBatch","storageConditionalBatch"),!W.conditionalBatch)throw Error("This storage backend reports conditionalBatch capability but does not implement the conditionalBatch() method.");return W.conditionalBatch(E,F)}function _(W){return encodeURIComponent(W)}function xW(W){return decodeURIComponent(W)}function uW(W){try{return decodeURIComponent(W)}catch{return null}}var Y=(W)=>String(W).padStart(16,"0"),kW;var H=j(()=>{S();kW={workflow:(W)=>`wf:${_(W)}`,checkpoint:(W)=>`wf:${_(W)}:ckpt`,checkpointHistory:(W,E)=>`wf:${_(W)}:ckpt:${String(E).padStart(10,"0")}`,timelinePrefix:(W)=>`wf:${_(W)}:timeline:`,timeline:(W,E)=>`wf:${_(W)}:timeline:${String(E).padStart(10,"0")}`,schedule:(W)=>`schedule:${_(W)}`,scheduleTick:(W,E)=>`schedule-due:${String(W).padStart(16,"0")}:${_(E)}`,scheduleRun:(W)=>`schedule-run:${_(W)}`,operation:(W,E,F)=>`op:${W}:${Y(E)}:${F}`,operationInflight:(W)=>`op:inflight:${W}`,operationQueued:(W)=>`op:queued:${W}`,operationResolved:(W)=>`op:resolved:${W}`,bulkOperationAuditPrefix:()=>"audit:bulk:",bulkOperationAudit:(W,E,F)=>`audit:bulk:${Y(W)}:${_(E)}:${_(F)}`,operationResolvedByTimePrefix:()=>"op:resolved-by-time:",operationResolvedByTime:(W,E)=>`op:resolved-by-time:${Y(W)}:${_(E)}`,asyncActivity:(W,E)=>`async-act:v1:${_(W)}:${_(E)}`,activityReconciliationPrefix:(W)=>`actrec:v1:${_(W)}:`,activityReconciliation:(W,E,F)=>`actrec:v1:${_(W)}:${_(E)}:${F}`,eventPrefix:(W)=>`ev:${_(W)}:`,event:(W,E)=>`ev:${_(W)}:${String(E).padStart(10,"0")}`,eventHead:(W)=>`ev:${_(W)}:head`,eventWatermark:(W)=>`ev:${_(W)}:watermark`,signal:(W,E,F)=>`sig:${_(W)}:${E}:${_(F)}`,signalSequence:(W)=>`sigseq:v1:${_(W)}`,signalAcceptedResponsePrefix:(W)=>`sigres:v1:${_(W)}:`,signalAcceptedResponse:(W,E,F)=>`sigres:v1:${_(W)}:${_(E)}:${_(F)}`,deadline:(W,E)=>`wf-deadline:${Y(W)}:${_(E)}`,terminalCleanup:(W,E)=>`wf-cleanup:${Y(W)}:${_(E)}`,delayedStart:(W,E)=>`wf-delayed:${Y(W)}:${_(E)}`,terminalWorkflowPrefix:()=>"wf-terminal:",terminalWorkflow:(W,E)=>`wf-terminal:${Y(W)}:${_(E)}`,attribute:(W)=>`attr:${_(W)}`,attributeIndex:(W,E,F)=>`idx:${W}:${E}:${_(F)}`,tagIndex:(W,E)=>`tag:${_(W)}:${_(E)}`,updatePrefix:(W)=>`upd:${_(W)}:`,update:(W,E)=>`upd:${_(W)}:${E}`,updateResponse:(W)=>`upr:${W}`,updateIdempotency:(W,E)=>`upk:${_(W)}:${E}`,startIdempotency:(W)=>`start-idem:${_(W)}`,startIdempotencySignalId:(W)=>`start-idem:${W}`,livenessPrefix:()=>"liveness:",liveness:(W)=>`liveness:${_(W)}`,budget:(W,E,F)=>`budget:${W}:${E}:${F}`,review:(W,E)=>`review:${_(W)}:${E}`,workflowHeaders:(W)=>`wf-headers:${_(W)}`,terminalCleanupNeeded:(W)=>`wf-cleanup-needed:${_(W)}`,workflowHasServices:(W)=>`wf-has-services:${_(W)}`,offload:(W,E)=>`offload:${_(W)}:${E}`,archive:(W,E)=>`archive:${_(W)}:${E}`,stateExecution:(W,E)=>`state:execution:${_(W)}:${_(E)}`,stateWorkflow:(W,E)=>`state:workflow-scope:${L}:${_(W)}:${_(E)}`,streamChunkPrefix:(W,E)=>`blob:${_(W)}:${E}:chunk:`,streamChunk:(W,E,F)=>`blob:${_(W)}:${E}:chunk:${String(F).padStart(10,"0")}`,streamMetadata:(W,E)=>`blob:${_(W)}:${E}:meta`,budgetCharged:(W)=>`budget-charged:${W}`,toolEffect:(W,E,F)=>`tool-effect:${_(W)}:${E}:${F}`,workflowVisibilityStatus:(W,E)=>`wf-idx-status:${_(W)}:${_(E)}`,workflowVisibilityType:(W,E)=>`wf-idx-type:${_(W)}:${_(E)}`,workflowVisibilityCreated:(W,E)=>`wf-idx-created:${Y(W)}:${_(E)}`,workflowVisibilityUpdated:(W,E)=>`wf-idx-updated:${Y(W)}:${_(E)}`,workflowVisibilityDeadline:(W,E)=>`wf-idx-deadline:${Y(W)}:${_(E)}`,workflowVisibilityManifest:(W)=>`wf-idx-manifest:${_(W)}`,workflowVisibilityMetaVersion:()=>"wf-idx-meta:version",workflowVisibilityMetaBuiltAt:()=>"wf-idx-meta:built-at",workflowVisibilityMetaCursor:()=>"wf-idx-meta:cursor"}});function VW(W){if(W===void 0)return;if(typeof W!=="number"||!Number.isInteger(W)||W<0)throw Error("deleteRange limit must be a finite non-negative integer");return W===0?0:W}function V(W){let E={},F=!1;for(let J of["gt","gte","lt","lte"]){let Q=W[J];if(Q===void 0)continue;if(typeof Q!=="string")throw Error("deleteRange bounds must be strings");E[J]=Q,F=!0}if(!F)throw Error("deleteRange requires at least one of gt/gte/lt/lte; use deletePrefix to delete a whole prefix");let X=VW(W.limit);if(X!==void 0)E.limit=X;return E}async function f(W,E,F){let X=V(F);if(W.deleteRange)return W.deleteRange(E,X);return K(W,E,X)}var B=()=>{};function R(W){return W.replaceAll(/:+$/g,"")}function HW(W,E){let F=R(W),X=R(E);if(F.length===0)return X;if(X.length===0)return F;return`${F}:${X}`}function m(W,E){return new A(W,E)}var A;var g=j(()=>{B();H();A=class A{#W;#_;constructor(W,E){this.#W=W,this.#_=R(E)}#E(W){if(this.#_.length===0)return W;return W.length===0?`${this.#_}:`:`${this.#_}:${W}`}#X(W){if(this.#_.length===0)return W;return W.slice(this.#_.length+1)}#F(W={}){let E={};if(W.limit!==void 0)E.limit=W.limit;if(W.reverse!==void 0)E.reverse=W.reverse;if(W.gt!==void 0)E.gt=this.#E(W.gt);if(W.gte!==void 0)E.gte=this.#E(W.gte);if(W.lt!==void 0)E.lt=this.#E(W.lt);if(W.lte!==void 0)E.lte=this.#E(W.lte);return E}#J(W){let E={};if(W.limit!==void 0)E.limit=W.limit;if(W.gt!==void 0)E.gt=this.#E(W.gt);if(W.gte!==void 0)E.gte=this.#E(W.gte);if(W.lt!==void 0)E.lt=this.#E(W.lt);if(W.lte!==void 0)E.lte=this.#E(W.lte);return E}capabilities(){return this.#W.capabilities()}scoped(W){return new A(this.#W,HW(this.#_,W))}async get(W){return this.#W.get(this.#E(W))}async put(W,E){await this.#W.put(this.#E(W),E)}async delete(W){await this.#W.delete(this.#E(W))}async*scan(W,E){for await(let[F,X]of this.#W.scan(this.#E(W),this.#F(E)))yield[this.#X(F),X]}async batch(W){await this.#W.batch(W.map((E)=>{if(E.type==="put")return{type:"put",key:this.#E(E.key),value:E.value};return{type:"delete",key:this.#E(E.key)}}))}async conditionalBatch(W,E){return y(this.#W,W.map((F)=>({key:this.#E(F.key),expectedValue:F.expectedValue})),E.map((F)=>{if(F.type==="put")return{type:"put",key:this.#E(F.key),value:F.value};return{type:"delete",key:this.#E(F.key)}}))}async has(W){return u(this.#W,this.#E(W))}async deletePrefix(W){return w(this.#W,this.#E(W))}async deleteRange(W,E){let F=this.#J(V(E));return f(this.#W,this.#E(W),F)}async*keys(W,E){for await(let F of k(this.#W,this.#E(W),this.#F(E)))yield this.#X(F)}async count(W){return c(this.#W,this.#E(W))}[Symbol.dispose](){this.#W[Symbol.dispose]()}}});function LW(W){return W.trim().replace(/;+\s*$/u,"").trim()}function BW(W){return DW.test(W)}function _W(W){let E=LW(W);if(E.length===0)throw Error("Storage query must not be empty.");if(E.includes(";"))throw Error("Storage query must contain exactly one read-only statement.");if(NW.test(E))return;if(GW.test(E)&&BW(E))return;throw Error("Storage query only supports read-only SELECT and PRAGMA statements.")}var GW,DW,NW;var XW=j(()=>{GW=/^PRAGMA\b/iu,DW=/^PRAGMA\s+(?:[A-Z_][A-Z0-9_]*\.)?[A-Z_][A-Z0-9_]*\s*$/iu,NW=/^SELECT\b/iu});B();H();import{Pool as RW}from"@neondatabase/serverless";function O(W){return W.rowCount??W.affectedRows??W.rows.length}function G(W){if(W instanceof Uint8Array)return new Uint8Array(W);return new Uint8Array(W)}function q(W){return Buffer.from(W)}H();var d=`CREATE TABLE IF NOT EXISTS kv (
+  key TEXT COLLATE "C" PRIMARY KEY,
+  value BYTEA NOT NULL
+)`,l=`
+  SELECT COALESCE(co.collname, 'default') AS collation
+  FROM pg_attribute a
+  LEFT JOIN pg_collation co ON co.oid = a.attcollation
+  WHERE a.attrelid = to_regclass('kv') AND a.attname = 'key' AND a.attnum > 0
+`,p="BEGIN ISOLATION LEVEL SERIALIZABLE",s="BEGIN ISOLATION LEVEL READ COMMITTED",a="BEGIN READ ONLY",i="COMMIT",z="ROLLBACK",T="SELECT value FROM kv WHERE key = $1",v="INSERT INTO kv (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value",P="DELETE FROM kv WHERE key = $1",n="SELECT 1 AS present FROM kv WHERE key = $1 LIMIT 1",r="SELECT COUNT(*) AS count FROM kv WHERE key >= $1 AND key < $2",t="DELETE FROM kv WHERE key >= $1 AND key < $2";function D(W){return[W,I(W)]}function o(W,E){let{gt:F,gte:X,lt:J,lte:Q}=E,Z=D(W),$=["key >= $1 AND key < $2"];if(F!==void 0)Z.push(F),$.push(`key > $${Z.length}`);if(X!==void 0)Z.push(X),$.push(`key >= $${Z.length}`);if(J!==void 0)Z.push(J),$.push(`key < $${Z.length}`);if(Q!==void 0)Z.push(Q),$.push(`key <= $${Z.length}`);return{conditions:$,parameters:Z}}function e(W,E={}){let{limit:F,reverse:X}=E,{conditions:J,parameters:Q}=o(W,E),Z=X?"DESC":"ASC",$="";if(F!==void 0)Q.push(F),$=` LIMIT $${Q.length}`;return{parameters:Q,whereOrderLimit:`WHERE ${J.join(" AND ")} ORDER BY key ${Z}${$}`}}function WW(W,E={}){let{parameters:F,whereOrderLimit:X}=e(W,E);return{parameters:F,sql:`SELECT key, value FROM kv ${X}`}}function EW(W,E={}){let{parameters:F,whereOrderLimit:X}=e(W,E);return{parameters:F,sql:`SELECT key FROM kv ${X}`}}function FW(W,E){let{conditions:F,parameters:X}=o(W,E),J=F.join(" AND ");if(E.limit===void 0)return{parameters:X,sql:`DELETE FROM kv WHERE ${J}`};return X.push(E.limit),{parameters:X,sql:`DELETE FROM kv WHERE key IN (SELECT key FROM kv WHERE ${J} ORDER BY key ASC LIMIT $${X.length})`}}XW();g();var AW=new Set(["40001","40P01"]),JW=5;function OW(W){if(typeof W!=="object"||W===null||!("code"in W))return!1;let E=W.code;return typeof E==="string"&&AW.has(E)}class qW{#W;#_;#E;#X;constructor(W,E=(F)=>new RW({connectionString:F})){this.#E=W.pool===void 0,this.#W=W.pool??E(W.url)}capabilities(){return{persistence:"remote",readAfterWrite:"linearizable",scanConsistency:"snapshot",atomicBatch:!0,conditionalBatch:!0,boundedRangeDelete:!0}}#F(){return this.#_??=this.#J().catch((W)=>{throw this.#_=void 0,W}),this.#_}async#J(){await this.#W.query(d),await this.#$()}async#$(){let E=(await this.#W.query(l)).rows[0]?.collation;if(E==="C")return;let F=E===void 0?"no kv table":typeof E==="string"?`"${E}"`:"an unexpected collation value";throw Error(`NeonStorage requires the "kv" table's "key" column to use COLLATE "C" (found ${F}). A "kv" table created without COLLATE "C" sorts keys by the database locale, which breaks Weft's lexicographic prefix scans. Use a fresh database, or recreate the table as: CREATE TABLE kv (key TEXT COLLATE "C" PRIMARY KEY, value BYTEA NOT NULL).`)}async get(W){await this.#F();let F=(await this.#W.query(T,[W])).rows[0];if(F===void 0)return null;let X=F.value;if(X===null||X===void 0)return null;return G(X)}async put(W,E){await this.#F(),await this.#W.query(v,[W,q(E)])}async delete(W){await this.#F(),await this.#W.query(P,[W])}async has(W){return await this.#F(),(await this.#W.query(n,[W])).rows.length>0}async deletePrefix(W){await this.#F();let[E,F]=D(W),X=await this.#W.query(t,[E,F]);return O(X)}async deleteRange(W,E){await this.#F();let F=V(E),{parameters:X,sql:J}=FW(W,F),Q=await this.#W.query(J,X);return O(Q)}async*scan(W,E={}){await this.#F();let{parameters:F,sql:X}=WW(W,E),J=await this.#W.query(X,F);for(let Q of J.rows)yield[Q.key,G(Q.value)]}async*keys(W,E={}){await this.#F();let{parameters:F,sql:X}=EW(W,E),J=await this.#W.query(X,F);for(let Q of J.rows)yield Q.key}async count(W){await this.#F();let[E,F]=D(W),X=await this.#W.query(r,[E,F]);return Number(X.rows[0]?.count??0)}scoped(W){return m(this,W)}async#Q(W,E,F=()=>!0){let X=await this.#W.connect();try{await X.query(W);try{let J=await E(X);return await X.query(F(J)?i:z),J}catch(J){throw await X.query(z).catch(()=>{}),J}}finally{X.release()}}async batch(W){if(W.length===0)return;await this.#F(),await this.#Q(s,async(E)=>{await QW(E,W)})}async conditionalBatch(W,E){await this.#F();let F;for(let X=0;X<JW;X+=1)try{return await this.#Q(p,async(J)=>{for(let Q of W){let $=(await J.query(T,[Q.key])).rows[0]?.value,ZW=$===null||$===void 0?null:G($);if(!x(ZW,Q.expectedValue))return!1}return await QW(J,E),!0},(J)=>J)}catch(J){if(!OW(J))throw J;F=J}throw Error(`conditionalBatch exhausted ${JW} retries after retryable transaction failures`,{cause:F})}async query(W,E){return await this.#F(),_W(W),this.#Q(a,async(F)=>{return(await F.query(W,E??[])).rows})}#Z(){if(!this.#E)return Promise.resolve();return this.#X??=this.#W.end(),this.#X}[Symbol.dispose](){this.#Z().catch(()=>{})}async[Symbol.asyncDispose](){await this.#Z()}}async function QW(W,E){for(let F of E)if(F.type==="put")await W.query(v,[F.key,q(F.value)]);else await W.query(P,[F.key])}export{qW as NeonStorage};

package/dist/storage/node-sqlite-loader.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Lazy loader for the optional `better-sqlite3` peer dependency used by
+ * {@link NodeSQLiteStorage}. Kept in its own module — and deliberately NOT in the
+ * package `exports` map — so the test-only injection seam
+ * ({@link loadBetterSqlite3ForTest}) never becomes part of the documented public
+ * surface. `node-sqlite.ts` imports `loadBetterSqlite3` (production path);
+ * `node-sqlite.test.ts` imports the test entry directly from here.
+ *
+ * @module storage/node-sqlite-loader
+ */
+/**
+ * Minimal `better-sqlite3` `Database` surface this adapter uses. Defined here so
+ * both the loader and the storage module compile without the package installed.
+ */
+export type BetterSqliteStatement = {
+    run(...parameters: unknown[]): unknown;
+    get(...parameters: unknown[]): Record<string, unknown> | undefined;
+    all(...parameters: unknown[]): Record<string, unknown>[];
+};
+export type BetterSqliteTransaction = (...args: unknown[]) => unknown;
+export type BetterSqliteDatabase = {
+    pragma(source: string): unknown;
+    exec(source: string): void;
+    prepare(source: string): BetterSqliteStatement;
+    transaction(fn: (...args: unknown[]) => unknown): BetterSqliteTransaction;
+    close(): void;
+};
+export type BetterSqliteConstructor = new (path: string) => BetterSqliteDatabase;
+/**
+ * Build the actionable error thrown when `better-sqlite3` cannot be loaded —
+ * either because the optional dependency is absent or its native binding fails
+ * to dlopen.
+ */
+export declare function createMissingBetterSqlite3Error(cause: unknown): Error;
+/**
+ * Whether `error` is a recognizable `better-sqlite3` load failure (missing
+ * package or native-binding dlopen failure) worth reshaping into the actionable
+ * peer-dependency error rather than re-throwing raw.
+ */
+export declare function isBetterSqlite3LoadFailure(error: unknown): boolean;
+/**
+ * Resolve the `better-sqlite3` module via a CommonJS require. This package is
+ * ESM (`type: module`), so the global `require` is not defined — `createRequire`
+ * from `node:module` builds a CommonJS require for loading the native binding.
+ *
+ * Extracted as a standalone function so tests can inject a throwing resolver
+ * (see {@link loadBetterSqlite3ForTest}) to exercise the missing/failed-dependency
+ * paths WITHOUT `mock.module('node:module', ...)`. That mock is irreversible in
+ * Bun: it patches the CJS loader process-wide and `mock.restore()` does not undo
+ * it, which poisons `require()` for every later test in the same process
+ * (notably any WASM module that requires a core module during boot).
+ */
+declare function resolveBetterSqlite3Module(): {
+    default?: BetterSqliteConstructor;
+} & BetterSqliteConstructor;
+/** Resolver for the `better-sqlite3` module. Injectable for tests. */
+type BetterSqlite3ModuleResolver = typeof resolveBetterSqlite3Module;
+/**
+ * Load (and cache) the `better-sqlite3` constructor. Reshapes a recognized load
+ * failure into the actionable peer-dependency error.
+ */
+export declare function loadBetterSqlite3(resolveModule?: BetterSqlite3ModuleResolver): BetterSqliteConstructor;
+/**
+ * Test-only entry that exercises {@link loadBetterSqlite3}'s module-resolution
+ * and error-shaping with an injected resolver, bypassing the cached constructor
+ * so the missing/failed-dependency paths run every call. This lets those paths be
+ * tested without mocking the global `node:module` loader. Lives in this
+ * non-exported module so it never reaches the public package surface.
+ */
+export declare function loadBetterSqlite3ForTest(resolveModule: BetterSqlite3ModuleResolver): BetterSqliteConstructor;
+export {};

package/dist/storage/node-sqlite-loader.js

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+let DatabaseConstructor;
+export function createMissingBetterSqlite3Error(cause) {
+  return Error('NodeSQLiteStorage requires the optional peer dependency "better-sqlite3". Install it in your application with: bun add better-sqlite3 (or npm install better-sqlite3).', { cause });
+}
+export function isBetterSqlite3LoadFailure(error) {
+  if (!(error instanceof Error))
+    return !1;
+  const errorCode = error.code;
+  if (errorCode === "MODULE_NOT_FOUND")
+    return error.message.includes("'better-sqlite3'") || error.message.includes('"better-sqlite3"') || error.message.includes("'bindings'") || error.message.includes('"bindings"');
+  if (errorCode === "ERR_DLOPEN_FAILED")
+    return error.message.includes("better-sqlite3");
+  return !1;
+}
+function resolveBetterSqlite3Module() {
+  return createRequire(import.meta.url)("better-sqlite3");
+}
+export function loadBetterSqlite3(resolveModule = resolveBetterSqlite3Module) {
+  if (DatabaseConstructor)
+    return DatabaseConstructor;
+  let mod;
+  try {
+    mod = resolveModule();
+  } catch (error) {
+    if (isBetterSqlite3LoadFailure(error))
+      throw createMissingBetterSqlite3Error(error);
+    throw error;
+  }
+  DatabaseConstructor = typeof mod.default === "function" ? mod.default : mod;
+  return DatabaseConstructor;
+}
+export function loadBetterSqlite3ForTest(resolveModule) {
+  const previous = DatabaseConstructor;
+  DatabaseConstructor = void 0;
+  try {
+    return loadBetterSqlite3(resolveModule);
+  } finally {
+    DatabaseConstructor = previous;
+  }
+}

package/dist/storage/node-sqlite.d.ts

@@ -11,25 +11,7 @@
  * @module storage/node-sqlite
  */
 import type { BatchOperation, ConditionalBatchCondition, ScanOptions, Storage, StorageCapabilities } from './interface.ts';
-/**
- * Minimal subset of the `better-sqlite3` API surface that this adapter uses.
- * Defined here so the module compiles without the package installed — the
- * actual dependency is resolved lazily at construction time.
- */
-type BetterSqliteStatement = {
-    run(...parameters: unknown[]): unknown;
-    get(...parameters: unknown[]): Record<string, unknown> | undefined;
-    all(...parameters: unknown[]): Record<string, unknown>[];
-};
-type BetterSqliteTransaction = (...args: unknown[]) => unknown;
-type BetterSqliteDatabase = {
-    pragma(source: string): unknown;
-    exec(source: string): void;
-    prepare(source: string): BetterSqliteStatement;
-    transaction(fn: (...args: unknown[]) => unknown): BetterSqliteTransaction;
-    close(): void;
-};
-type BetterSqliteConstructor = new (path: string) => BetterSqliteDatabase;
+import { type BetterSqliteConstructor } from './node-sqlite-loader.ts';
 /**
  * Runtime-neutral alias for the Node SQLite adapter. Consumers that import
  * from `@lostgradient/weft/storage/sqlite` get this class under Node.

package/dist/storage/node-sqlite.js

@@ -1,7 +1,4 @@
 // @bun
-// src/storage/node-sqlite.ts
-import { createRequire } from "module";
-
 // src/storage/capabilities.ts
 function requireStorageCapability(storage, capability, featureName) {
   if (!storage.capabilities()[capability]) {
@@ -98,6 +95,44 @@ async function storageConditionalBatch(storage, conditions, operations) {
   return storage.conditionalBatch(conditions, operations);
 }
 
+// src/storage/node-sqlite-loader.ts
+import { createRequire } from "module";
+var DatabaseConstructor;
+function createMissingBetterSqlite3Error(cause) {
+  return new Error('NodeSQLiteStorage requires the optional peer dependency "better-sqlite3". ' + "Install it in your application with: bun add better-sqlite3 (or npm install better-sqlite3).", { cause });
+}
+function isBetterSqlite3LoadFailure(error) {
+  if (!(error instanceof Error))
+    return false;
+  const errorCode = error.code;
+  if (errorCode === "MODULE_NOT_FOUND") {
+    return error.message.includes("'better-sqlite3'") || error.message.includes('"better-sqlite3"') || error.message.includes("'bindings'") || error.message.includes('"bindings"');
+  }
+  if (errorCode === "ERR_DLOPEN_FAILED") {
+    return error.message.includes("better-sqlite3");
+  }
+  return false;
+}
+function resolveBetterSqlite3Module() {
+  const requireFromHere = createRequire(import.meta.url);
+  return requireFromHere("better-sqlite3");
+}
+function loadBetterSqlite3(resolveModule = resolveBetterSqlite3Module) {
+  if (DatabaseConstructor)
+    return DatabaseConstructor;
+  let mod;
+  try {
+    mod = resolveModule();
+  } catch (error) {
+    if (isBetterSqlite3LoadFailure(error)) {
+      throw createMissingBetterSqlite3Error(error);
+    }
+    throw error;
+  }
+  DatabaseConstructor = typeof mod.default === "function" ? mod.default : mod;
+  return DatabaseConstructor;
+}
+
 // src/storage/sqlite-key-value-queries.ts
 var SQLITE_CREATE_KEY_VALUE_TABLE = `CREATE TABLE IF NOT EXISTS kv (
   key TEXT PRIMARY KEY,
@@ -178,35 +213,6 @@ function buildSqliteKeyRangeSelect(prefix, options = {}) {
 }
 
 // src/storage/node-sqlite.ts
-var DatabaseConstructor;
-function createMissingBetterSqlite3Error(cause) {
-  return new Error('NodeSQLiteStorage requires the optional peer dependency "better-sqlite3". ' + "Install it in your application with: bun add better-sqlite3 (or npm install better-sqlite3).", { cause });
-}
-function isBetterSqlite3LoadFailure(error) {
-  if (!(error instanceof Error))
-    return false;
-  const errorCode = error.code;
-  if (errorCode === "MODULE_NOT_FOUND") {
-    return error.message.includes("'better-sqlite3'") || error.message.includes('"better-sqlite3"') || error.message.includes("'bindings'") || error.message.includes('"bindings"');
-  }
-  if (errorCode === "ERR_DLOPEN_FAILED") {
-    return error.message.includes("better-sqlite3");
-  }
-  return false;
-}
-function loadBetterSqlite3() {
-  if (DatabaseConstructor)
-    return DatabaseConstructor;
-  const requireFromHere = createRequire(import.meta.url);
-  let mod;
-  try {
-    mod = requireFromHere("better-sqlite3");
-  } catch (error) {
-    throw createMissingBetterSqlite3Error(error);
-  }
-  DatabaseConstructor = typeof mod.default === "function" ? mod.default : mod;
-  return DatabaseConstructor;
-}
 class NodeSQLiteStorage {
   #database;
   #persistence;

package/dist/storage/postgres-key-value-queries.d.ts

@@ -0,0 +1,79 @@
+import type { NormalizedDeleteRangeOptions } from './delete-range.ts';
+import { type ScanOptions } from './interface.ts';
+/**
+ * The Postgres counterpart of `sqlite-key-value-queries.ts`. The schema is the
+ * same single `kv(key, value)` table, but two Postgres specifics differ from the
+ * SQLite builders and force a separate module:
+ *
+ * - **Numbered placeholders.** Postgres binds parameters as `$1`, `$2`, … in
+ *   statement order, not the positional `?` SQLite uses. A builder that appends
+ *   bounds dynamically must therefore track the next placeholder index.
+ * - **`COLLATE "C"` on the key.** Postgres `TEXT` sorts by the database locale,
+ *   which reorders punctuation and would silently corrupt every prefix-range
+ *   scan and `ORDER BY key` the engine relies on. Pinning the primary-key column
+ *   to the `C` collation restores byte-wise (codepoint) ordering, matching
+ *   SQLite's default `BINARY` collation and the engine's key-layout assumptions.
+ *
+ * @module storage/postgres-key-value-queries
+ */
+export declare const PG_CREATE_KEY_VALUE_TABLE = "CREATE TABLE IF NOT EXISTS kv (\n  key TEXT COLLATE \"C\" PRIMARY KEY,\n  value BYTEA NOT NULL\n)";
+/**
+ * Introspect the collation of the `key` column on the `kv` table the adapter's
+ * own unqualified queries resolve to. Returns one row with a `collation` field:
+ * the named collation (`C` for a correctly-created table) or `default` when the
+ * column inherits the database default collation. Returns zero rows when no `kv`
+ * table is visible on the search path.
+ *
+ * `to_regclass('kv')` resolves the same search-path-visible relation that
+ * unqualified DDL/DML hits, so a `kv` table in another schema cannot be inspected
+ * by mistake (which would falsely pass a mis-collated active table or falsely
+ * reject a valid one). Detects a pre-existing `kv` whose key collation would break
+ * lexicographic prefix scans — a `CREATE TABLE IF NOT EXISTS` would otherwise
+ * silently adopt it.
+ */
+export declare const PG_SELECT_KEY_COLLATION = "\n  SELECT COALESCE(co.collname, 'default') AS collation\n  FROM pg_attribute a\n  LEFT JOIN pg_collation co ON co.oid = a.attcollation\n  WHERE a.attrelid = to_regclass('kv') AND a.attname = 'key' AND a.attnum > 0\n";
+/** Begin a transaction at SERIALIZABLE isolation (conditionalBatch's CAS path). */
+export declare const PG_BEGIN_SERIALIZABLE = "BEGIN ISOLATION LEVEL SERIALIZABLE";
+/** Begin a transaction at READ COMMITTED isolation (the atomic batch() path). */
+export declare const PG_BEGIN_READ_COMMITTED = "BEGIN ISOLATION LEVEL READ COMMITTED";
+/**
+ * Begin a READ ONLY transaction for the `query()` passthrough. Postgres enforces
+ * this at the database level — a writing statement (including a data-modifying
+ * CTE that a textual SELECT check would miss) errors instead of mutating.
+ */
+export declare const PG_BEGIN_READ_ONLY = "BEGIN READ ONLY";
+/** Commit the current transaction. */
+export declare const PG_COMMIT = "COMMIT";
+/** Roll back the current transaction. */
+export declare const PG_ROLLBACK = "ROLLBACK";
+export declare const PG_SELECT_VALUE_BY_KEY = "SELECT value FROM kv WHERE key = $1";
+export declare const PG_UPSERT_VALUE_BY_KEY = "INSERT INTO kv (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value";
+export declare const PG_DELETE_VALUE_BY_KEY = "DELETE FROM kv WHERE key = $1";
+export declare const PG_SELECT_KEY_PRESENCE = "SELECT 1 AS present FROM kv WHERE key = $1 LIMIT 1";
+export declare const PG_COUNT_KEYS_BY_PREFIX = "SELECT COUNT(*) AS count FROM kv WHERE key >= $1 AND key < $2";
+export declare const PG_DELETE_KEYS_BY_PREFIX = "DELETE FROM kv WHERE key >= $1 AND key < $2";
+export type PostgresKeyRangeQueryParameter = string | number;
+/** A fully-built SQL statement and its bound parameters (SELECT or DELETE). */
+export type PostgresBuiltQuery = {
+    parameters: PostgresKeyRangeQueryParameter[];
+    sql: string;
+};
+export declare function buildPostgresPrefixRangeParameters(prefix: string): [string, string];
+export declare function buildPostgresKeyValueRangeSelect(prefix: string, options?: ScanOptions): PostgresBuiltQuery;
+export declare function buildPostgresKeyRangeSelect(prefix: string, options?: ScanOptions): PostgresBuiltQuery;
+/**
+ * Build a bounded-range `DELETE` for the `kv` table from already-validated
+ * delete options.
+ *
+ * Without `limit`, emits `DELETE FROM kv WHERE <conditions>` — no ordering, since
+ * order is meaningless when deleting the whole matched range. With `limit`, emits
+ * a subquery form so the lowest (ascending) keys are deleted first:
+ * `DELETE FROM kv WHERE key IN (SELECT key FROM kv WHERE <conditions> ORDER BY key
+ * ASC LIMIT $n)`. Postgres does not support `DELETE ... ORDER BY ... LIMIT`
+ * directly, so the subquery is the portable form.
+ *
+ * Requires {@link NormalizedDeleteRangeOptions}: the type guarantees at least one
+ * bound is present and the prefix range is always the leading condition, so this
+ * builder can never produce a whole-table wipe.
+ */
+export declare function buildPostgresKeyRangeDelete(prefix: string, options: NormalizedDeleteRangeOptions): PostgresBuiltQuery;

package/dist/storage/postgres-key-value-queries.js

@@ -0,0 +1,63 @@
+import { resolvePrefixRangeEnd } from "./interface.js";
+export const PG_CREATE_KEY_VALUE_TABLE = `CREATE TABLE IF NOT EXISTS kv (
+  key TEXT COLLATE "C" PRIMARY KEY,
+  value BYTEA NOT NULL
+)`, PG_SELECT_KEY_COLLATION = `
+  SELECT COALESCE(co.collname, 'default') AS collation
+  FROM pg_attribute a
+  LEFT JOIN pg_collation co ON co.oid = a.attcollation
+  WHERE a.attrelid = to_regclass('kv') AND a.attname = 'key' AND a.attnum > 0
+`, PG_BEGIN_SERIALIZABLE = "BEGIN ISOLATION LEVEL SERIALIZABLE", PG_BEGIN_READ_COMMITTED = "BEGIN ISOLATION LEVEL READ COMMITTED", PG_BEGIN_READ_ONLY = "BEGIN READ ONLY", PG_COMMIT = "COMMIT", PG_ROLLBACK = "ROLLBACK", PG_SELECT_VALUE_BY_KEY = "SELECT value FROM kv WHERE key = $1", PG_UPSERT_VALUE_BY_KEY = "INSERT INTO kv (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value", PG_DELETE_VALUE_BY_KEY = "DELETE FROM kv WHERE key = $1", PG_SELECT_KEY_PRESENCE = "SELECT 1 AS present FROM kv WHERE key = $1 LIMIT 1", PG_COUNT_KEYS_BY_PREFIX = "SELECT COUNT(*) AS count FROM kv WHERE key >= $1 AND key < $2", PG_DELETE_KEYS_BY_PREFIX = "DELETE FROM kv WHERE key >= $1 AND key < $2";
+export function buildPostgresPrefixRangeParameters(prefix) {
+  return [prefix, resolvePrefixRangeEnd(prefix)];
+}
+function buildPostgresKeyRangeConditions(prefix, bounds) {
+  const { gt, gte, lt, lte } = bounds, parameters = buildPostgresPrefixRangeParameters(prefix), conditions = ["key >= $1 AND key < $2"];
+  if (gt !== void 0) {
+    parameters.push(gt);
+    conditions.push(`key > $${parameters.length}`);
+  }
+  if (gte !== void 0) {
+    parameters.push(gte);
+    conditions.push(`key >= $${parameters.length}`);
+  }
+  if (lt !== void 0) {
+    parameters.push(lt);
+    conditions.push(`key < $${parameters.length}`);
+  }
+  if (lte !== void 0) {
+    parameters.push(lte);
+    conditions.push(`key <= $${parameters.length}`);
+  }
+  return { conditions, parameters };
+}
+function buildPostgresKeyRangeQuery(prefix, options = {}) {
+  const { limit, reverse } = options, { conditions, parameters } = buildPostgresKeyRangeConditions(prefix, options), direction = reverse ? "DESC" : "ASC";
+  let limitClause = "";
+  if (limit !== void 0) {
+    parameters.push(limit);
+    limitClause = ` LIMIT $${parameters.length}`;
+  }
+  return {
+    parameters,
+    whereOrderLimit: `WHERE ${conditions.join(" AND ")} ORDER BY key ${direction}${limitClause}`
+  };
+}
+export function buildPostgresKeyValueRangeSelect(prefix, options = {}) {
+  const { parameters, whereOrderLimit } = buildPostgresKeyRangeQuery(prefix, options);
+  return { parameters, sql: `SELECT key, value FROM kv ${whereOrderLimit}` };
+}
+export function buildPostgresKeyRangeSelect(prefix, options = {}) {
+  const { parameters, whereOrderLimit } = buildPostgresKeyRangeQuery(prefix, options);
+  return { parameters, sql: `SELECT key FROM kv ${whereOrderLimit}` };
+}
+export function buildPostgresKeyRangeDelete(prefix, options) {
+  const { conditions, parameters } = buildPostgresKeyRangeConditions(prefix, options), whereClause = conditions.join(" AND ");
+  if (options.limit === void 0)
+    return { parameters, sql: `DELETE FROM kv WHERE ${whereClause}` };
+  parameters.push(options.limit);
+  return {
+    parameters,
+    sql: `DELETE FROM kv WHERE key IN (SELECT key FROM kv WHERE ${whereClause} ORDER BY key ASC LIMIT $${parameters.length})`
+  };
+}