@coffre/db 0.1.9 → 0.1.10

package/dist/hyperdrive.d.ts

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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.10"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

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;
   }
 }