@coffre/db 0.1.9 → 0.1.11

package/dist/connect.d.ts

@@ -1,4 +1,4 @@
-import { t as Database } from "./database-CWpo5aF0.js";
+import { t as Database } from "./database-BhLco7OA.js";
 import { Engine } from "./dialect.js";
 import { ClientConfig } from "pg";
 //#region src/postgres.d.ts

package/dist/{database-CWpo5aF0.d.ts → database-BhLco7OA.d.ts}

@@ -23,6 +23,16 @@ type PoolLike = pg.Pool | {
     release: () => void;
   }>;
 };
+/**
+ * A query made on the database from inside one of its own transactions,
+ * rather than through the transaction. With one connection per call, as on
+ * Workers, it would wait for the transaction, which waits for it: a call
+ * Cloudflare cancels as hung, and nothing says why. So it is refused at
+ * once, with this, wherever the database runs.
+ */
+declare class QueryOutsideTransaction extends Error {
+  constructor();
+}
 declare function createDatabase(pool: PoolLike): Database;
 /**
  * The tables of the database's own dialect: the Postgres ones on Postgres,
@@ -36,4 +46,4 @@ declare function tablesOf(db: Queryable): typeof schema_d_exports;
  */
 declare function own<T extends Table>(db: Queryable, table: T): T;
 //#endregion
-export { createDatabase as a, Transaction as i, PoolLike as n, own as o, Queryable as r, tablesOf as s, Database as t };
+export { Transaction as a, tablesOf as c, Queryable as i, PoolLike as n, createDatabase as o, QueryOutsideTransaction as r, own as s, Database as t };

package/dist/dialect.d.ts

@@ -1,4 +1,4 @@
-import { r as Queryable } from "./database-CWpo5aF0.js";
+import { i as Queryable } from "./database-BhLco7OA.js";
 import { SQL } from "drizzle-orm";
 import { PgTable } from "drizzle-orm/pg-core";
 //#region src/dialect.d.ts

package/dist/hyperdrive.d.ts

@@ -1,4 +1,4 @@
-import { n as PoolLike } from "./database-CWpo5aF0.js";
+import { n as PoolLike } from "./database-BhLco7OA.js";
 import pg from "pg";
 //#region src/hyperdrive.d.ts
 /** Postgres through a Hyperdrive binding: `postgres(env.HYPERDRIVE)`. */
@@ -13,20 +13,36 @@ export declare function postgres(hyperdrive: {
   readonly connectionString: string;
 }): PostgresDatabase;
 /**
- * Request-scoped node-postgres adapter for Hyperdrive.
+ * node-postgres for one call on Workers, through Hyperdrive: one client,
+ * connected on the first query, which every query and transaction of the
+ * call takes its turn on.
  *
- * Hyperdrive owns the durable origin pool. The Worker creates edge clients
- * only inside one invocation, which prevents I/O objects from leaking across
- * Worker request contexts while keeping the Pool shape Drizzle expects. The
- * class name must end in `Pool`: that is how Drizzle knows to check out a
- * client for each transaction.
+ * Hyperdrive keeps the pool to the database; a Worker's connections belong
+ * to the call that opened them, so each call opens its own. One, not one per
+ * query: on Cloudflare, a call that opened several Hyperdrive connections at
+ * once was now and then cancelled as hung, with nothing left pending, and
+ * every connection costs a round trip before the query can be sent.
+ *
+ * The turns keep a transaction whole: queries go to the client in the order
+ * they are asked, a transaction holds it from BEGIN until it is released,
+ * and a query asked meanwhile waits until then, so nothing runs inside a
+ * transaction it is not part of. So code inside a transaction must query
+ * through the transaction: a query on the database there would wait for the
+ * transaction to end, which waits for it. Neither the vault nor the server
+ * does.
+ *
+ * The class name must end in `Pool`: that is how Drizzle knows to check out
+ * a client for each transaction.
  */
 export declare class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
   #private;
   constructor(connectionString: string);
   readonly query: pg.Pool['query'];
+  /** The client, for a transaction: held from now until `release`. */
   connect(): Promise<Pick<pg.PoolClient, 'query'> & {
     release: () => void;
   }>;
+  /** Close the client once nothing waits on it: what a Worker hands `waitUntil` when the call is done. */
+  end(): Promise<void>;
 }
 //#endregion

package/dist/hyperdrive.js

@@ -10,44 +10,115 @@ function postgres(hyperdrive) {
 	};
 }
 /**
-* Request-scoped node-postgres adapter for Hyperdrive.
+* node-postgres for one call on Workers, through Hyperdrive: one client,
+* connected on the first query, which every query and transaction of the
+* call takes its turn on.
 *
-* Hyperdrive owns the durable origin pool. The Worker creates edge clients
-* only inside one invocation, which prevents I/O objects from leaking across
-* Worker request contexts while keeping the Pool shape Drizzle expects. The
-* class name must end in `Pool`: that is how Drizzle knows to check out a
-* client for each transaction.
+* Hyperdrive keeps the pool to the database; a Worker's connections belong
+* to the call that opened them, so each call opens its own. One, not one per
+* query: on Cloudflare, a call that opened several Hyperdrive connections at
+* once was now and then cancelled as hung, with nothing left pending, and
+* every connection costs a round trip before the query can be sent.
+*
+* The turns keep a transaction whole: queries go to the client in the order
+* they are asked, a transaction holds it from BEGIN until it is released,
+* and a query asked meanwhile waits until then, so nothing runs inside a
+* transaction it is not part of. So code inside a transaction must query
+* through the transaction: a query on the database there would wait for the
+* transaction to end, which waits for it. Neither the vault nor the server
+* does.
+*
+* The class name must end in `Pool`: that is how Drizzle knows to check out
+* a client for each transaction.
 */
 var HyperdrivePool = class {
 	#connectionString;
+	/** The client, connecting or connected; null before the first query, and once it has failed. */
+	#client = null;
+	/** Whether a transaction holds the client. */
+	#held = false;
+	/** What waits for its turn, in the order it asked. */
+	#waiting = [];
+	/** Queries and transactions asked and not done: waiting for the client, their turn, or an answer. */
+	#busy = 0;
+	/** What waits for the client to be idle: `end`. */
+	#idle = [];
 	constructor(connectionString) {
 		if (connectionString.trim().length === 0) throw new Error("Hyperdrive returned an empty connection string");
 		this.#connectionString = connectionString;
 	}
 	query = (async (...args) => {
-		const client = await this.#connectClient();
+		this.#busy += 1;
 		try {
-			return await client.query(...args);
+			const client = await this.#connected();
+			return await new Promise((resolve, reject) => {
+				this.#turn(() => client.query(...args).then(resolve, reject));
+			});
 		} finally {
-			await client.end();
+			this.#done();
 		}
 	});
+	/** The client, for a transaction: held from now until `release`. */
 	async connect() {
-		const client = await this.#connectClient();
+		this.#busy += 1;
+		let client;
+		try {
+			client = await this.#connected();
+		} catch (error) {
+			this.#done();
+			throw error;
+		}
+		await new Promise((resolve) => this.#turn(() => {
+			this.#held = true;
+			resolve();
+		}));
 		let released = false;
 		return {
 			query: client.query.bind(client),
 			release: () => {
 				if (released) return;
 				released = true;
-				client.end().catch(() => {});
+				this.#held = false;
+				this.#next();
+				this.#done();
 			}
 		};
 	}
-	async #connectClient() {
+	/** Close the client once nothing waits on it: what a Worker hands `waitUntil` when the call is done. */
+	async end() {
+		while (this.#busy > 0) await new Promise((resolve) => this.#idle.push(resolve));
+		const client = this.#client;
+		this.#client = null;
+		if (client === null) return;
+		await client.then((connected) => connected.end()).catch(() => {});
+	}
+	/** Run `go` now if nothing holds the client or waits before it, otherwise at its turn. */
+	#turn(go) {
+		if (!this.#held && this.#waiting.length === 0) go();
+		else this.#waiting.push(go);
+	}
+	/** Give the next turns: queries until one is a transaction, which holds the client. */
+	#next() {
+		while (!this.#held && this.#waiting.length > 0) this.#waiting.shift()();
+	}
+	/** One query or transaction done: once none is left, what waits for the client to be idle goes on. */
+	#done() {
+		this.#busy -= 1;
+		if (this.#busy === 0) for (const resolve of this.#idle.splice(0)) resolve();
+	}
+	/** The call's client, connecting it the first time. One that fails is dropped: the next query connects again. */
+	#connected() {
+		if (this.#client !== null) return this.#client;
 		const client = new pg.Client(postgresConnection(this.#connectionString));
-		await client.connect();
-		return client;
+		const connecting = client.connect().then(() => client);
+		const drop = () => {
+			if (this.#client === connecting) this.#client = null;
+		};
+		client.on("error", drop);
+		client.on("end", drop);
+		connecting.catch(drop);
+		this.#client = connecting;
+		return connecting;
 	}
 };
 //#endregion

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import { l as schema_d_exports } from "./schema-Cd4WOnB5.js";
-import { a as createDatabase, i as Transaction, n as PoolLike, o as own, r as Queryable, s as tablesOf, t as Database } from "./database-CWpo5aF0.js";
-export { Database, PoolLike, Queryable, Transaction, createDatabase, own, schema_d_exports as schema, tablesOf };
+import { a as Transaction, c as tablesOf, i as Queryable, n as PoolLike, o as createDatabase, r as QueryOutsideTransaction, s as own, t as Database } from "./database-BhLco7OA.js";
+export { Database, PoolLike, QueryOutsideTransaction, Queryable, Transaction, createDatabase, own, schema_d_exports as schema, tablesOf };

package/dist/index.js

@@ -1,10 +1,62 @@
 import { n as trackCommits } from "./commits-BuW-NL3n.js";
 import { t as schema_exports } from "./schema.js";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Table, getTableName, is } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/node-postgres";
 //#region src/database.ts
+/**
+* A query made on the database from inside one of its own transactions,
+* rather than through the transaction. With one connection per call, as on
+* Workers, it would wait for the transaction, which waits for it: a call
+* Cloudflare cancels as hung, and nothing says why. So it is refused at
+* once, with this, wherever the database runs.
+*/
+var QueryOutsideTransaction = class extends Error {
+	constructor() {
+		super("query outside its transaction: use tx. A query on the database inside one of its own transactions waits for that transaction, which waits for it");
+		this.name = "QueryOutsideTransaction";
+	}
+};
+/** The transaction a flow of work runs inside, with the pool it holds, while it is open. */
+const inside = new AsyncLocalStorage();
+/**
+* `pool`, refusing a query or a transaction asked from inside a transaction
+* it is already running. Work from any other flow, a concurrent request's,
+* or what the transaction left running after it ended, goes on as before.
+*/
+function guarded(pool) {
+	return new Proxy(pool, { get(target, key) {
+		const value = Reflect.get(target, key, target);
+		if (typeof value !== "function") return value;
+		if (key !== "query" && key !== "connect") return value.bind(target);
+		return (...args) => {
+			const open = inside.getStore();
+			if (open?.open === true && open.pool === target) throw new QueryOutsideTransaction();
+			return value.apply(target, args);
+		};
+	} });
+}
+/** The refusal `error` is, or was caused by. */
+function brokenRule(error) {
+	for (let cause = error; cause instanceof Error; cause = cause.cause) if (cause instanceof QueryOutsideTransaction) return cause;
+}
 function createDatabase(pool) {
-	return trackCommits(drizzle(pool, { schema: schema_exports }));
+	const db = drizzle(guarded(pool), { schema: schema_exports });
+	const run = db.transaction.bind(db);
+	db.transaction = (async (work, config) => {
+		const open = {
+			pool,
+			open: true
+		};
+		try {
+			return await run((tx) => inside.run(open, () => work(tx)), config);
+		} catch (error) {
+			throw brokenRule(error) ?? error;
+		} finally {
+			open.open = false;
+		}
+	});
+	return trackCommits(db);
 }
 /**
 * The tables of the database's own dialect: the Postgres ones on Postgres,
@@ -31,4 +83,4 @@ function own(db, table) {
 	return found;
 }
 //#endregion
-export { createDatabase, own, schema_exports as schema, tablesOf };
+export { QueryOutsideTransaction, createDatabase, own, schema_exports as schema, tablesOf };

package/dist/log.d.ts

@@ -1,4 +1,4 @@
-import { i as Transaction } from "./database-CWpo5aF0.js";
+import { a as Transaction } from "./database-BhLco7OA.js";
 import { LogKey } from "@coffre/core/audit";
 //#region src/log.d.ts
 /**

package/dist/portable.d.ts

@@ -1,5 +1,5 @@
 import { l as schema_d_exports } from "./schema-Cd4WOnB5.js";
-import { t as Database } from "./database-CWpo5aF0.js";
+import { t as Database } from "./database-BhLco7OA.js";
 import { t as schema_sqlite_d_exports } from "./schema-sqlite.js";
 import { LibSQLDatabase } from "drizzle-orm/libsql";
 //#region src/portable.d.ts

package/dist/schema-version.d.ts

@@ -1,4 +1,4 @@
-import { r as Queryable } from "./database-CWpo5aF0.js";
+import { i as Queryable } from "./database-BhLco7OA.js";
 import { Engine } from "./dialect.js";
 //#region src/schema-version.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -74,7 +74,7 @@
     "drizzle-orm": "0.45.2",
     "pg": "8.16.3",
     "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.1.9"
+    "@coffre/core": "0.1.11"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/database.ts

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
 import { getTableName, is, Table } from 'drizzle-orm';
 import { drizzle, type NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type pg from 'pg';
@@ -27,8 +29,67 @@ export type PoolLike = pg.Pool | {
   connect: () => Promise<Pick<pg.PoolClient, 'query'> & { release: () => void }>;
 };
 
+/**
+ * A query made on the database from inside one of its own transactions,
+ * rather than through the transaction. With one connection per call, as on
+ * Workers, it would wait for the transaction, which waits for it: a call
+ * Cloudflare cancels as hung, and nothing says why. So it is refused at
+ * once, with this, wherever the database runs.
+ */
+export class QueryOutsideTransaction extends Error {
+  constructor() {
+    super('query outside its transaction: use tx. A query on the database inside one of its own transactions waits for that transaction, which waits for it');
+    this.name = 'QueryOutsideTransaction';
+  }
+}
+
+/** The transaction a flow of work runs inside, with the pool it holds, while it is open. */
+const inside = new AsyncLocalStorage<{ pool: PoolLike; open: boolean }>();
+
+/**
+ * `pool`, refusing a query or a transaction asked from inside a transaction
+ * it is already running. Work from any other flow, a concurrent request's,
+ * or what the transaction left running after it ended, goes on as before.
+ */
+function guarded(pool: PoolLike): PoolLike {
+  return new Proxy(pool, {
+    get(target, key) {
+      const value: unknown = Reflect.get(target, key, target);
+      if (typeof value !== 'function') return value;
+      if (key !== 'query' && key !== 'connect') return value.bind(target);
+      return (...args: unknown[]) => {
+        const open = inside.getStore();
+        if (open?.open === true && open.pool === target) throw new QueryOutsideTransaction();
+        return (value as (...args: unknown[]) => unknown).apply(target, args);
+      };
+    },
+  });
+}
+
+/** The refusal `error` is, or was caused by. */
+function brokenRule(error: unknown): QueryOutsideTransaction | undefined {
+  for (let cause = error; cause instanceof Error; cause = cause.cause) {
+    if (cause instanceof QueryOutsideTransaction) return cause;
+  }
+  return undefined;
+}
+
 export function createDatabase(pool: PoolLike): Database {
-  return trackCommits(drizzle(pool as pg.Pool, { schema }));
+  const db = drizzle(guarded(pool) as pg.Pool, { schema });
+  // Each transaction's work runs knowing which one it is in, until the transaction ends.
+  const run = db.transaction.bind(db);
+  db.transaction = (async (work, config) => {
+    const open = { pool, open: true };
+    try {
+      return await run((tx) => inside.run(open, () => work(tx)), config);
+    } catch (error) {
+      // Drizzle wraps what a query throws: the rule broken is what to say.
+      throw brokenRule(error) ?? error;
+    } finally {
+      open.open = false;
+    }
+  }) as Database['transaction'];
+  return trackCommits(db);
 }
 
 /**

package/src/hyperdrive.ts

@@ -15,16 +15,39 @@ export function postgres(hyperdrive: { readonly connectionString: string }): Pos
 }
 
 /**
- * Request-scoped node-postgres adapter for Hyperdrive.
+ * node-postgres for one call on Workers, through Hyperdrive: one client,
+ * connected on the first query, which every query and transaction of the
+ * call takes its turn on.
  *
- * Hyperdrive owns the durable origin pool. The Worker creates edge clients
- * only inside one invocation, which prevents I/O objects from leaking across
- * Worker request contexts while keeping the Pool shape Drizzle expects. The
- * class name must end in `Pool`: that is how Drizzle knows to check out a
- * client for each transaction.
+ * Hyperdrive keeps the pool to the database; a Worker's connections belong
+ * to the call that opened them, so each call opens its own. One, not one per
+ * query: on Cloudflare, a call that opened several Hyperdrive connections at
+ * once was now and then cancelled as hung, with nothing left pending, and
+ * every connection costs a round trip before the query can be sent.
+ *
+ * The turns keep a transaction whole: queries go to the client in the order
+ * they are asked, a transaction holds it from BEGIN until it is released,
+ * and a query asked meanwhile waits until then, so nothing runs inside a
+ * transaction it is not part of. So code inside a transaction must query
+ * through the transaction: a query on the database there would wait for the
+ * transaction to end, which waits for it. Neither the vault nor the server
+ * does.
+ *
+ * The class name must end in `Pool`: that is how Drizzle knows to check out
+ * a client for each transaction.
  */
 export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
   readonly #connectionString: string;
+  /** The client, connecting or connected; null before the first query, and once it has failed. */
+  #client: Promise<pg.Client> | null = null;
+  /** Whether a transaction holds the client. */
+  #held = false;
+  /** What waits for its turn, in the order it asked. */
+  readonly #waiting: (() => void)[] = [];
+  /** Queries and transactions asked and not done: waiting for the client, their turn, or an answer. */
+  #busy = 0;
+  /** What waits for the client to be idle: `end`. */
+  readonly #idle: (() => void)[] = [];
 
   constructor(connectionString: string) {
     if (connectionString.trim().length === 0) {
@@ -34,30 +57,88 @@ export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
   }
 
   readonly query: pg.Pool['query'] = (async (...args: unknown[]) => {
-    const client = await this.#connectClient();
+    this.#busy += 1;
     try {
-      return await (client.query as (...queryArgs: unknown[]) => Promise<unknown>)(...args);
+      const client = await this.#connected();
+      return await new Promise((resolve, reject) => {
+        // Sent at its turn, at once: pg answers its queries in the order they are sent.
+        this.#turn(() => (client.query as (...queryArgs: unknown[]) => Promise<unknown>)(...args).then(resolve, reject));
+      });
     } finally {
-      await client.end();
+      this.#done();
     }
   }) as pg.Pool['query'];
 
+  /** The client, for a transaction: held from now until `release`. */
   async connect(): Promise<Pick<pg.PoolClient, 'query'> & { release: () => void }> {
-    const client = await this.#connectClient();
+    this.#busy += 1;
+    let client: pg.Client;
+    try {
+      client = await this.#connected();
+    } catch (error) {
+      this.#done();
+      throw error;
+    }
+    await new Promise<void>((resolve) =>
+      this.#turn(() => {
+        this.#held = true;
+        resolve();
+      }),
+    );
     let released = false;
     return {
       query: client.query.bind(client) as pg.PoolClient['query'],
       release: () => {
         if (released) return;
         released = true;
-        client.end().catch(() => {});
+        this.#held = false;
+        this.#next();
+        this.#done();
       },
     };
   }
 
-  async #connectClient(): Promise<pg.Client> {
+  /** Close the client once nothing waits on it: what a Worker hands `waitUntil` when the call is done. */
+  async end(): Promise<void> {
+    while (this.#busy > 0) {
+      await new Promise<void>((resolve) => this.#idle.push(resolve));
+    }
+    const client = this.#client;
+    this.#client = null;
+    if (client === null) return;
+    await client.then((connected) => connected.end()).catch(() => {});
+  }
+
+  /** Run `go` now if nothing holds the client or waits before it, otherwise at its turn. */
+  #turn(go: () => void): void {
+    if (!this.#held && this.#waiting.length === 0) go();
+    else this.#waiting.push(go);
+  }
+
+  /** Give the next turns: queries until one is a transaction, which holds the client. */
+  #next(): void {
+    while (!this.#held && this.#waiting.length > 0) this.#waiting.shift()!();
+  }
+
+  /** One query or transaction done: once none is left, what waits for the client to be idle goes on. */
+  #done(): void {
+    this.#busy -= 1;
+    if (this.#busy === 0) for (const resolve of this.#idle.splice(0)) resolve();
+  }
+
+  /** The call's client, connecting it the first time. One that fails is dropped: the next query connects again. */
+  #connected(): Promise<pg.Client> {
+    if (this.#client !== null) return this.#client;
     const client = new pg.Client(postgresConnection(this.#connectionString));
-    await client.connect();
-    return client;
+    const connecting: Promise<pg.Client> = client.connect().then(() => client);
+    const drop = () => {
+      if (this.#client === connecting) this.#client = null;
+    };
+    // A connection lost between queries: pg fails what was waiting on it, and the next query connects again.
+    client.on('error', drop);
+    client.on('end', drop);
+    connecting.catch(drop);
+    this.#client = connecting;
+    return connecting;
   }
 }