@steve31415/baselib 2.2.1 → 2.3.0

package/dist/db.d.ts

@@ -1,11 +1,30 @@
 import pg from 'pg';
-import type { Logger } from './log-core.js';
+import { type Logger } from './log-core.js';
 export interface PoolOptions {
     /** Override the database name (default: env DB_NAME / DATABASE_URL path). */
     database?: string;
     max?: number;
+    /** Receives idle-client errors (see logPoolErrors). Without one they go to
+     *  stderr — on the Cloud Logging backstop, but not in Axiom. */
+    logger?: Logger;
 }
+/** pg-pool re-emits an idle client's socket error as its own 'error' event —
+ * in production "Connection terminated unexpectedly" when Cloud SQL closes an
+ * idle connection. Unhandled, that event throws and takes the process down
+ * (todo 2026-08-20, notes 2026-08-27 ×2). The failed client has already been
+ * removed from the pool and the next checkout opens a fresh connection, so
+ * the right response is to log it and carry on. createPool attaches this;
+ * exported for apps that build their own pg.Pool. */
+export declare function logPoolErrors(pool: pg.Pool, logger?: Logger): void;
 export declare function createPool(opts?: PoolOptions): Promise<pg.Pool>;
+/** End a pool and resolve only once every client's connection has actually
+ * closed. pg-pool's own `end()` resolves as soon as it has *asked* its idle
+ * clients to close — their sockets are still open — so a caller that then
+ * drops the database `with (force)` can kill a backend mid-goodbye, and the
+ * FATAL it sends back surfaces as an unhandled pool 'error' (it took down a
+ * todo2 deploy with every test green, 2026-08-20). pg-pool emits 'remove' for
+ * each client once its socket has closed; wait for all of them. */
+export declare function endPool(pool: pg.Pool): Promise<void>;
 export declare function migrate(pool: pg.Pool, migrationsDir: string, logger?: Logger): Promise<{
     applied: string[];
 }>;

package/dist/db.js

@@ -6,6 +6,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import pg from 'pg';
 import { requireEnv } from './config.js';
+import { serializeError } from './log-core.js';
 // DATE columns come back as 'YYYY-MM-DD' strings, not JS Dates: calendar
 // dates are timezone-free by meaning, and a Date object smears them across
 // zones (and JSON-serializes to a full ISO timestamp). Set here — on the
@@ -13,7 +14,27 @@ import { requireEnv } from './config.js';
 // own pg copy miss this one (file:-dependency installs resolve separate pg
 // instances).
 pg.types.setTypeParser(pg.types.builtins.DATE, (v) => v);
+/** pg-pool re-emits an idle client's socket error as its own 'error' event —
+ * in production "Connection terminated unexpectedly" when Cloud SQL closes an
+ * idle connection. Unhandled, that event throws and takes the process down
+ * (todo 2026-08-20, notes 2026-08-27 ×2). The failed client has already been
+ * removed from the pool and the next checkout opens a fresh connection, so
+ * the right response is to log it and carry on. createPool attaches this;
+ * exported for apps that build their own pg.Pool. */
+export function logPoolErrors(pool, logger) {
+    pool.on('error', (err) => {
+        if (logger)
+            logger.error('database pool: idle client error', { error: err });
+        else
+            console.error('database pool: idle client error', serializeError(err));
+    });
+}
 export async function createPool(opts = {}) {
+    const pool = await newPool(opts);
+    logPoolErrors(pool, opts.logger);
+    return pool;
+}
+async function newPool(opts) {
     const instance = process.env.CLOUD_SQL_INSTANCE;
     if (instance) {
         const { Connector, AuthTypes, IpAddressTypes } = await import('@google-cloud/cloud-sql-connector');
@@ -35,6 +56,26 @@ export async function createPool(opts = {}) {
         url.pathname = `/${opts.database}`;
     return new pg.Pool({ connectionString: url.toString(), max: opts.max ?? 5 });
 }
+/** End a pool and resolve only once every client's connection has actually
+ * closed. pg-pool's own `end()` resolves as soon as it has *asked* its idle
+ * clients to close — their sockets are still open — so a caller that then
+ * drops the database `with (force)` can kill a backend mid-goodbye, and the
+ * FATAL it sends back surfaces as an unhandled pool 'error' (it took down a
+ * todo2 deploy with every test green, 2026-08-20). pg-pool emits 'remove' for
+ * each client once its socket has closed; wait for all of them. */
+export async function endPool(pool) {
+    let open = pool.totalCount;
+    const allClosed = new Promise((resolve) => {
+        if (open === 0)
+            return resolve();
+        pool.on('remove', () => {
+            if (--open === 0)
+                resolve();
+        });
+    });
+    await pool.end();
+    await allClosed;
+}
 // Plain-SQL migrations: numbered files (001-*.sql, 002-*.sql, …) applied in
 // order, recorded in schema_migrations, each inside a transaction, guarded by
 // an advisory lock so concurrent boots can't race. Applied at service boot.

package/dist/log-core.d.ts

@@ -52,7 +52,8 @@ export interface ShipperOptions {
      *  fire at the next CPU window (next request or shutdown), not on the
      *  wall clock. */
     retryDelaysMs?: number[];
-    /** Per-attempt fetch timeout (default 3s). */
+    /** Per-attempt fetch timeout (default 10s; 3s aborted most of the fleet's
+     *  attempts in the two weeks to 2026-08-28). */
     attemptTimeoutMs?: number;
     /** Caps across ALL undelivered batches; overflow drops oldest with an
      *  onGiveUp('buffer-overflow'). Defaults 5000 events / 5 MB. */

package/dist/log-core.js

@@ -70,7 +70,7 @@ export class LogShipper {
         this.intervalMs = opts.intervalMs ?? 2000;
         this.maxAttempts = opts.maxAttempts ?? 4;
         this.retryDelaysMs = opts.retryDelaysMs ?? [5_000, 15_000, 40_000];
-        this.attemptTimeoutMs = opts.attemptTimeoutMs ?? 3_000;
+        this.attemptTimeoutMs = opts.attemptTimeoutMs ?? 10_000;
         this.maxBufferedEvents = opts.maxBufferedEvents ?? 5_000;
         this.maxBufferedBytes = opts.maxBufferedBytes ?? 5 * 1024 * 1024;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",