lambda-pool 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owlCoder
+
+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,291 @@
+# lambda-pool
+
+[![npm version](https://img.shields.io/npm/v/lambda-pool.svg)](https://www.npmjs.com/package/lambda-pool)
+[![license](https://img.shields.io/npm/l/lambda-pool.svg)](./LICENSE)
+[![types](https://img.shields.io/npm/types/lambda-pool.svg)](https://www.npmjs.com/package/lambda-pool)
+[![zero deps](https://img.shields.io/badge/runtime%20deps-0-22c55e.svg)](#zero-runtime-dependencies)
+
+Serverless-safe **connection-pool options** for **MySQL** (`mysql2`) and **Postgres** (`pg`)
+on Vercel / AWS Lambda / Cloudflare-to-DB, where the database has a **small
+`max_connections`** budget (Aiven free tier, Neon, Supabase, RDS micro, PlanetScale).
+
+It returns a plain options object you pass to your own driver. **Zero runtime
+dependencies.** It does not open connections, wrap your driver, or pin a version.
+
+```bash
+npm install lambda-pool
+```
+
+## The bug this prevents
+
+On Vercel/Lambda every **warm** function instance keeps **its own** pool. If each
+pool opens `N` connections and the platform keeps `M` instances warm, your
+database sees up to **`N × M`** connections.
+
+Managed databases on small plans cap `max_connections` very low (often **10–25**).
+So a perfectly reasonable-looking `connectionLimit: 10` blows the budget under
+mild traffic and you get:
+
+- MySQL: `ER_CON_COUNT_ERROR: Too many connections`
+- Postgres: `sorry, too many clients already`
+
+…intermittently, only in production, only under load. The classic "works on my
+machine, dies on Black Friday" footgun.
+
+## The fix (and why it's counter-intuitive)
+
+Make each pool **tiny** — default **1 connection per instance**. The platform's
+horizontal scaling *is* your concurrency; the database stops melting. Idle
+instances release their slot so they don't sit on the budget.
+
+That's the whole idea. This package just encodes the right defaults so you don't
+have to rediscover them in an incident.
+
+## Usage
+
+### MySQL (`mysql2`)
+
+```ts
+import mysql from "mysql2/promise";
+import { buildMysqlPoolOptions } from "lambda-pool/mysql";
+
+const pool = mysql.createPool(buildMysqlPoolOptions(process.env));
+```
+
+### Postgres (`pg`)
+
+```ts
+import { Pool } from "pg";
+import { buildPgPoolOptions } from "lambda-pool/pg";
+
+const pool = new Pool(buildPgPoolOptions(process.env));
+```
+
+Both also re-exported from the root: `import { buildPgPoolOptions } from "lambda-pool"`.
+
+## Diagnostics — lint your connection for serverless
+
+Beyond building options, `lambda-pool` can **analyze** a connection config and
+tell you whether it will survive serverless fan-out. Pure function, no I/O:
+
+```ts
+import { inspectEnv, formatReport } from "lambda-pool";
+
+const report = inspectEnv(process.env);
+console.log(formatReport(report));
+// lambda-pool diagnostics for mysql://u:***@pg.aivencloud.com/db [aiven]
+//   ⚠ SMALL_MAX_CONNECTIONS: Aiven typically caps max_connections around 20; keep the per-instance pool at 1.
+```
+
+It recognizes the provider from the host (Aiven, Neon, Supabase, PlanetScale,
+RDS/Aurora, Railway, Render, Vercel Postgres) and warns about: pool sizes too
+large for the provider's budget, SSL requested in the URL with no CA supplied,
+and using a direct host when a pooled endpoint is available.
+
+## CLI
+
+```bash
+# Lint the connection in your env (exit 1 on any warning — good as a CI gate)
+DATABASE_URL=postgres://… npx lambda-pool inspect
+
+# Full preflight check (config + diagnostics) — strict gate, exit 1 on any issue
+DATABASE_URL=postgres://… npx lambda-pool doctor
+
+# Recommend a pool size straight from a connection URL (detects the provider)
+npx lambda-pool recommend "postgres://…@db.aivencloud.com/app" 10
+
+# Recommend from raw numbers: max_connections, instances, [reserved], [other]
+npx lambda-pool budget 100 20
+#   recommended pool limit: 4
+#   97 usable connections (100 max − 3 reserved − 0 other) ÷ 20 instances → pool of 4 per instance (peak 80).
+
+# List recognized providers
+npx lambda-pool providers
+```
+
+## Budget calculator (programmatic)
+
+```ts
+import { recommendPoolLimit } from "lambda-pool";
+
+const { recommendedPoolLimit, exceedsBudget, rationale } = recommendPoolLimit({
+  maxConnections: 20,   // your DB's max_connections
+  expectedInstances: 30, // peak warm serverless instances
+});
+// recommendedPoolLimit: 1, exceedsBudget: true → use a pooler
+```
+
+## Connection-string utilities
+
+```ts
+import { parseConnectionString, redactUrl } from "lambda-pool";
+
+redactUrl("postgres://u:secret@host/db"); // → "postgres://u:***@host/db"
+parseConnectionString("mysql://root@127.0.0.1/test").port; // → 3306
+```
+
+## Health checks
+
+Driver-agnostic readiness probe. Works with any pool that has a `query()`
+method (both `mysql2` and `pg` do), so `lambda-pool` stays dependency-free:
+
+```ts
+import { checkHealth } from "lambda-pool";
+
+const { healthy, latencyMs, error } = await checkHealth(pool, { timeoutMs: 2000 });
+// use in a /healthz endpoint — never throws
+```
+
+## Retry transient connect errors
+
+Cold starts and brief failovers cause transient connect errors. `withRetry`
+wraps an operation with jittered exponential backoff:
+
+```ts
+import { withRetry, isTransientDbError } from "lambda-pool";
+
+const client = await withRetry(() => pool.connect(), {
+  attempts: 4,
+  retryable: isTransientDbError, // don't retry auth failures
+});
+```
+
+## Preflight (startup gate)
+
+Run a single check at boot that combines config validation, diagnostics, and an
+optional live reachability probe. The probe is **injected**, so the check stays
+pure unless you opt into a real connection:
+
+```ts
+import { preflight } from "lambda-pool";
+import { isReachable } from "lambda-pool/health";
+
+const result = await preflight(process.env, {
+  probe: () => isReachable(pool), // optional live check
+});
+if (!result.ok) {
+  console.error(result.diagnostics);
+  process.exit(1);
+}
+```
+
+## Redact objects for logging
+
+`redactUrl` masks a connection string; `redact` masks whole objects (config
+dumps, error context) by key name, so secrets never reach your log aggregator:
+
+```ts
+import { redact } from "lambda-pool";
+
+redact({ host: "db", password: "p", nested: { token: "t" } });
+// → { host: "db", password: "***", nested: { token: "***" } }
+```
+
+## Build a connection string from parts
+
+```ts
+import { buildDsn } from "lambda-pool";
+
+buildDsn({ engine: "postgres", host: "db", user: "u", password: "p/w", database: "app" });
+// → "postgres://u:p%2Fw@db:5432/app"  (credentials safely encoded)
+```
+
+## Result type
+
+Non-throwing variants return a small `Result` you can branch on:
+
+```ts
+import { safeParseConnectionString } from "lambda-pool";
+
+const r = safeParseConnectionString(process.env.DATABASE_URL ?? "");
+if (!r.ok) { /* handle r.error */ } else { /* use r.value */ }
+```
+
+## API surface
+
+| Import | Exports |
+|---|---|
+| `lambda-pool/mysql` | `buildMysqlPoolOptions` |
+| `lambda-pool/pg` | `buildPgPoolOptions` |
+| `lambda-pool/url` | `parseConnectionString`, `safeParseConnectionString`, `redactUrl`, `urlRequestsSsl` |
+| `lambda-pool/providers` | `detectProvider`, `listProviders`, `isPooledEndpoint` |
+| `lambda-pool/budget` | `recommendPoolLimit` |
+| `lambda-pool/diagnostics` | `diagnose`, `formatReport` |
+| `lambda-pool/recommend` | `recommendForUrl` |
+| `lambda-pool/preflight` | `preflight` |
+| `lambda-pool/config` | `loadPoolConfig` |
+| `lambda-pool/dsn` | `buildDsn` |
+| `lambda-pool/redact` | `redact` |
+| `lambda-pool/health` | `checkHealth`, `isReachable` |
+| `lambda-pool/retry` | `withRetry`, `backoffDelay`, `isTransientDbError` |
+| `lambda-pool/result` | `Result`, `ok`, `err`, `attempt`, `unwrap` |
+
+All of the above are also re-exported from the package root.
+
+## Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `DATABASE_URL` | Connection URI. Aliases: `MYSQL_URL` / `POSTGRES_URL` / `PG_URL`. | **required** |
+| `DATABASE_POOL_LIMIT` | Per-instance pool size. Raise **only** behind a pooler (PgBouncer, Neon pooled endpoint) or on a bigger plan. | `1` |
+| `DATABASE_SSL_CA_BASE64` | Base64 of your provider's CA cert → enables strict TLS. | off |
+
+A non-positive or non-numeric `DATABASE_POOL_LIMIT` is ignored and falls back to
+the default, so a bad env var can never silently widen the pool.
+
+## What the defaults are
+
+**MySQL** (`mysql2` `PoolOptions`): `connectionLimit: 1`, `maxIdle: 1`,
+`idleTimeout: 30000`, `enableKeepAlive: true`, `waitForConnections: true`,
+`queueLimit: 0`.
+
+**Postgres** (`pg` `PoolConfig`): `max: 1`, `idleTimeoutMillis: 30000`,
+`connectionTimeoutMillis: 10000`, `maxUses: 7500`, `allowExitOnIdle: true`.
+
+Override the default size in code without an env var:
+
+```ts
+buildPgPoolOptions(process.env, { defaultPoolLimit: 2 }); // behind a pooler
+```
+
+### A note on TLS
+
+Managed providers hand you a CA bundle, but the URI's `?ssl-mode=REQUIRED` /
+`?sslmode=require` param is **not** interpreted by `mysql2` / `pg` the way people
+expect. Pass the CA explicitly via `DATABASE_SSL_CA_BASE64` and the server is
+verified (`rejectUnauthorized: true`).
+
+## Architecture
+
+The source is organized into strict clean-architecture layers
+(`core → application → adapters → presentation`) with the dependency rule
+enforced in CI. See [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## Zero runtime dependencies
+
+`lambda-pool` imports nothing at runtime. `mysql2` / `pg` are **your** dependency
+and only `devDependencies` here (for tests/types). You stay in control of the
+driver version.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test            # hermetic unit tests, no DB needed
+npm run build
+```
+
+Integration tests run the option objects against real `mysql2` / `pg` pools,
+using throwaway containers whose `max_connections` is pinned to 10 to mirror a
+free tier:
+
+```bash
+docker compose -f docker-compose.test.yml up -d
+RUN_DB_TESTS=1 npm run test:integration
+docker compose -f docker-compose.test.yml down -v
+```
+
+## License
+
+MIT

package/dist/adapters/health.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The minimal surface needed to run a trivial probe query. Both
+ * `mysql2`'s pool and `pg`'s pool structurally satisfy this.
+ */
+export interface Queryable {
+    query(sql: string): Promise<unknown>;
+}
+export interface HealthResult {
+    healthy: boolean;
+    /** Round-trip latency of the probe query, in milliseconds. */
+    latencyMs: number;
+    /** Present when the probe failed. */
+    error?: Error;
+}
+export interface HealthOptions {
+    /** SQL used to probe. Defaults to `SELECT 1`. */
+    probeSql?: string;
+    /** Fail the probe if it takes longer than this many ms. */
+    timeoutMs?: number;
+}
+/**
+ * Run a probe query against any `Queryable` and report health + latency.
+ *
+ * Never throws — failures are returned in the result so callers can use it
+ * directly in a readiness endpoint.
+ */
+export declare function checkHealth(db: Queryable, options?: HealthOptions): Promise<HealthResult>;
+/** Convenience: true/false readiness, swallowing the detail. */
+export declare function isReachable(db: Queryable, options?: HealthOptions): Promise<boolean>;
+//# sourceMappingURL=health.d.ts.map

package/dist/adapters/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/adapters/health.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,SAAS,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAwBvB;AAED,gEAAgE;AAChE,wBAAsB,WAAW,CAC/B,EAAE,EAAE,SAAS,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/adapters/health.js

@@ -0,0 +1,36 @@
+// Driver-agnostic health checks (Dependency Inversion + Interface Segregation).
+//
+// The package depends on a tiny `Queryable` port — the narrowest surface that
+// both `mysql2` pools and `pg` pools already satisfy — not on a concrete driver.
+// Adapters live next to the builders. This keeps `lambda-pool` dependency-free
+// while still offering a "is the DB reachable?" helper.
+function timeout(ms) {
+    return new Promise((_, reject) => setTimeout(() => reject(new Error(`lambda-pool: health probe timed out after ${ms}ms`)), ms));
+}
+/**
+ * Run a probe query against any `Queryable` and report health + latency.
+ *
+ * Never throws — failures are returned in the result so callers can use it
+ * directly in a readiness endpoint.
+ */
+export async function checkHealth(db, options = {}) {
+    const sql = options.probeSql ?? "SELECT 1";
+    const started = performance.now();
+    const probe = (async () => {
+        await db.query(sql);
+    })();
+    const race = options.timeoutMs
+        ? Promise.race([probe, timeout(options.timeoutMs)]).then(() => ({ ok: true, value: undefined }), (e) => ({ ok: false, error: e }))
+        : probe.then(() => ({ ok: true, value: undefined }), (e) => ({ ok: false, error: e }));
+    const outcome = await race;
+    const latencyMs = Math.round(performance.now() - started);
+    return outcome.ok
+        ? { healthy: true, latencyMs }
+        : { healthy: false, latencyMs, error: outcome.error };
+}
+/** Convenience: true/false readiness, swallowing the detail. */
+export async function isReachable(db, options) {
+    const r = await checkHealth(db, options);
+    return r.healthy;
+}
+//# sourceMappingURL=health.js.map

package/dist/adapters/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/adapters/health.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,iFAAiF;AACjF,+EAA+E;AAC/E,wDAAwD;AA2BxD,SAAS,OAAO,CAAC,EAAU;IACzB,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CACR,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,6CAA6C,EAAE,IAAI,CAAC,CAAC,EAC5E,EAAE,CACH,CACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAa,EACb,UAAyB,EAAE;IAE3B,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,IAAI,UAAU,CAAC;IAC3C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAElC,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE;QACxB,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC,CAAC,EAAE,CAAC;IAEL,MAAM,IAAI,GAAiC,OAAO,CAAC,SAAS;QAC1D,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CACpD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAa,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAC/C,CAAC,CAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAc,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CACjD;QACH,CAAC,CAAC,KAAK,CAAC,IAAI,CACR,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAa,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAC/C,CAAC,CAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAc,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CACjD,CAAC;IAEN,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC;IAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;IAE1D,OAAO,OAAO,CAAC,EAAE;QACf,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;QAC9B,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;AAC1D,CAAC;AAED,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAa,EACb,OAAuB;IAEvB,MAAM,CAAC,GAAG,MAAM,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACzC,OAAO,CAAC,CAAC,OAAO,CAAC;AACnB,CAAC"}

package/dist/adapters/mysql.d.ts

@@ -0,0 +1,40 @@
+import { type Env } from "../core/env.ts";
+export interface MysqlPoolEnv extends Env {
+    /** Connection URI (mysql://...). Alias: MYSQL_URL. */
+    DATABASE_URL?: string;
+    MYSQL_URL?: string;
+    /** Base64-encoded CA cert — when present, enables strict TLS. */
+    DATABASE_SSL_CA_BASE64?: string;
+    /** Per-instance pool size override; defaults to 1. */
+    DATABASE_POOL_LIMIT?: string;
+}
+/** Shape compatible with mysql2 `PoolOptions` (structural — no import needed). */
+export interface MysqlPoolOptions {
+    uri: string;
+    connectionLimit: number;
+    maxIdle: number;
+    idleTimeout: number;
+    enableKeepAlive: boolean;
+    waitForConnections: boolean;
+    queueLimit: number;
+    ssl?: {
+        ca: string;
+        rejectUnauthorized: boolean;
+    };
+}
+export interface BuildMysqlOptions {
+    /** Override the default pool size of 1. */
+    defaultPoolLimit?: number;
+}
+/**
+ * Build serverless-safe mysql2 pool options.
+ *
+ * - `connectionLimit` defaults to 1 (one connection per warm lambda). Raise it
+ *   only behind a connection pooler or on a plan with headroom, via
+ *   `DATABASE_POOL_LIMIT`.
+ * - `maxIdle: 1` + `idleTimeout` lets idle lambdas release their connection so
+ *   they don't sit on a slot of a tiny `max_connections` budget.
+ * - TLS is enabled with strict verification when `DATABASE_SSL_CA_BASE64` is set.
+ */
+export declare function buildMysqlPoolOptions(env: MysqlPoolEnv, opts?: BuildMysqlOptions): MysqlPoolOptions;
+//# sourceMappingURL=mysql.d.ts.map

package/dist/adapters/mysql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.d.ts","sourceRoot":"","sources":["../../src/adapters/mysql.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,GAAG,EAIT,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,YAAa,SAAQ,GAAG;IACvC,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,OAAO,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,EACjB,IAAI,GAAE,iBAAsB,GAC3B,gBAAgB,CAuBlB"}

package/dist/adapters/mysql.js

@@ -0,0 +1,34 @@
+// Serverless-safe pool options for mysql2.
+//
+// Returns a PLAIN options object — you pass it to your own
+// `mysql.createPool(...)`, so this module has zero runtime dependencies and is
+// not pinned to any mysql2 version.
+import { decodeCaBase64, firstEnv, resolvePoolLimit, } from "../core/env.js";
+/**
+ * Build serverless-safe mysql2 pool options.
+ *
+ * - `connectionLimit` defaults to 1 (one connection per warm lambda). Raise it
+ *   only behind a connection pooler or on a plan with headroom, via
+ *   `DATABASE_POOL_LIMIT`.
+ * - `maxIdle: 1` + `idleTimeout` lets idle lambdas release their connection so
+ *   they don't sit on a slot of a tiny `max_connections` budget.
+ * - TLS is enabled with strict verification when `DATABASE_SSL_CA_BASE64` is set.
+ */
+export function buildMysqlPoolOptions(env, opts = {}) {
+    const uri = firstEnv(env, "DATABASE_URL", "MYSQL_URL");
+    if (!uri) {
+        throw new Error("lambda-pool: DATABASE_URL (or MYSQL_URL) is not set — cannot build a MySQL pool.");
+    }
+    const ssl = decodeCaBase64(env.DATABASE_SSL_CA_BASE64);
+    return {
+        uri,
+        connectionLimit: resolvePoolLimit(env.DATABASE_POOL_LIMIT, opts.defaultPoolLimit ?? 1),
+        maxIdle: 1,
+        idleTimeout: 30_000,
+        enableKeepAlive: true,
+        waitForConnections: true,
+        queueLimit: 0,
+        ...(ssl ? { ssl } : {}),
+    };
+}
+//# sourceMappingURL=mysql.js.map

package/dist/adapters/mysql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.js","sourceRoot":"","sources":["../../src/adapters/mysql.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,2DAA2D;AAC3D,+EAA+E;AAC/E,oCAAoC;AAEpC,OAAO,EAEL,cAAc,EACd,QAAQ,EACR,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AA6BxB;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAiB,EACjB,OAA0B,EAAE;IAE5B,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IACvD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAEvD,OAAO;QACL,GAAG;QACH,eAAe,EAAE,gBAAgB,CAC/B,GAAG,CAAC,mBAAmB,EACvB,IAAI,CAAC,gBAAgB,IAAI,CAAC,CAC3B;QACD,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,MAAM;QACnB,eAAe,EAAE,IAAI;QACrB,kBAAkB,EAAE,IAAI;QACxB,UAAU,EAAE,CAAC;QACb,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxB,CAAC;AACJ,CAAC"}

package/dist/adapters/pg.d.ts

@@ -0,0 +1,46 @@
+import { type Env } from "../core/env.ts";
+export interface PgPoolEnv extends Env {
+    /** Connection URI (postgres://...). Aliases: POSTGRES_URL, PG_URL. */
+    DATABASE_URL?: string;
+    POSTGRES_URL?: string;
+    PG_URL?: string;
+    /** Base64-encoded CA cert — when present, enables strict TLS. */
+    DATABASE_SSL_CA_BASE64?: string;
+    /** Per-instance pool size override; defaults to 1. */
+    DATABASE_POOL_LIMIT?: string;
+}
+/** Shape compatible with pg `PoolConfig` (structural — no import needed). */
+export interface PgPoolOptions {
+    connectionString: string;
+    /** pg calls this `max` (mysql2 calls it `connectionLimit`). */
+    max: number;
+    /** Close a connection after it sits idle this long (ms). 0 disables. */
+    idleTimeoutMillis: number;
+    /** Fail fast instead of hanging when the DB has no free slots (ms). */
+    connectionTimeoutMillis: number;
+    /** Recycle a connection after this many uses (0 = never). */
+    maxUses: number;
+    /** Don't keep the event loop alive for idle clients. */
+    allowExitOnIdle: boolean;
+    ssl?: {
+        ca: string;
+        rejectUnauthorized: boolean;
+    };
+}
+export interface BuildPgOptions {
+    /** Override the default pool size of 1. */
+    defaultPoolLimit?: number;
+}
+/**
+ * Build serverless-safe `pg` pool options.
+ *
+ * - `max` defaults to 1 (one connection per warm lambda). Raise it only behind
+ *   a pooler (PgBouncer / Neon pooled endpoint) via `DATABASE_POOL_LIMIT`.
+ * - `idleTimeoutMillis` + `allowExitOnIdle` let an idle lambda release its slot
+ *   of a tiny `max_connections` budget and not pin the process open.
+ * - `connectionTimeoutMillis` makes "too many clients" surface as a fast error
+ *   rather than a hung request.
+ * - TLS is enabled with strict verification when `DATABASE_SSL_CA_BASE64` is set.
+ */
+export declare function buildPgPoolOptions(env: PgPoolEnv, opts?: BuildPgOptions): PgPoolOptions;
+//# sourceMappingURL=pg.d.ts.map

package/dist/adapters/pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.ts","sourceRoot":"","sources":["../../src/adapters/pg.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,GAAG,EAIT,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,SAAU,SAAQ,GAAG;IACpC,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,uBAAuB,EAAE,MAAM,CAAC;IAChC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,eAAe,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,OAAO,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,cAAmB,GACxB,aAAa,CAwBf"}

package/dist/adapters/pg.js

@@ -0,0 +1,34 @@
+// Serverless-safe pool options for node-postgres (`pg`).
+//
+// Returns a PLAIN options object — you pass it to your own `new pg.Pool(...)`,
+// so this module has zero runtime dependencies and is not pinned to any pg
+// version.
+import { decodeCaBase64, firstEnv, resolvePoolLimit, } from "../core/env.js";
+/**
+ * Build serverless-safe `pg` pool options.
+ *
+ * - `max` defaults to 1 (one connection per warm lambda). Raise it only behind
+ *   a pooler (PgBouncer / Neon pooled endpoint) via `DATABASE_POOL_LIMIT`.
+ * - `idleTimeoutMillis` + `allowExitOnIdle` let an idle lambda release its slot
+ *   of a tiny `max_connections` budget and not pin the process open.
+ * - `connectionTimeoutMillis` makes "too many clients" surface as a fast error
+ *   rather than a hung request.
+ * - TLS is enabled with strict verification when `DATABASE_SSL_CA_BASE64` is set.
+ */
+export function buildPgPoolOptions(env, opts = {}) {
+    const connectionString = firstEnv(env, "DATABASE_URL", "POSTGRES_URL", "PG_URL");
+    if (!connectionString) {
+        throw new Error("lambda-pool: DATABASE_URL (or POSTGRES_URL / PG_URL) is not set — cannot build a Postgres pool.");
+    }
+    const ssl = decodeCaBase64(env.DATABASE_SSL_CA_BASE64);
+    return {
+        connectionString,
+        max: resolvePoolLimit(env.DATABASE_POOL_LIMIT, opts.defaultPoolLimit ?? 1),
+        idleTimeoutMillis: 30_000,
+        connectionTimeoutMillis: 10_000,
+        maxUses: 7_500,
+        allowExitOnIdle: true,
+        ...(ssl ? { ssl } : {}),
+    };
+}
+//# sourceMappingURL=pg.js.map

package/dist/adapters/pg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.js","sourceRoot":"","sources":["../../src/adapters/pg.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,WAAW;AAEX,OAAO,EAEL,cAAc,EACd,QAAQ,EACR,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAkCxB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAc,EACd,OAAuB,EAAE;IAEzB,MAAM,gBAAgB,GAAG,QAAQ,CAC/B,GAAG,EACH,cAAc,EACd,cAAc,EACd,QAAQ,CACT,CAAC;IACF,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,iGAAiG,CAClG,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAEvD,OAAO;QACL,gBAAgB;QAChB,GAAG,EAAE,gBAAgB,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,CAAC,gBAAgB,IAAI,CAAC,CAAC;QAC1E,iBAAiB,EAAE,MAAM;QACzB,uBAAuB,EAAE,MAAM;QAC/B,OAAO,EAAE,KAAK;QACd,eAAe,EAAE,IAAI;QACrB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxB,CAAC;AACJ,CAAC"}

package/dist/application/diagnostics.d.ts

@@ -0,0 +1,33 @@
+import { type ProviderId } from "../core/providers.ts";
+export type Severity = "error" | "warning" | "info";
+export interface Diagnostic {
+    severity: Severity;
+    code: string;
+    message: string;
+}
+export interface DiagnoseInput {
+    /** The connection URI to analyze. */
+    url: string;
+    /** The pool size you intend to use (per warm instance). */
+    poolLimit: number;
+    /** Whether a CA cert was supplied out-of-band (DATABASE_SSL_CA_BASE64). */
+    hasCaCert?: boolean;
+    /** Peak warm instances, for budget checks. Defaults to a typical serverless fan-out. */
+    expectedInstances?: number;
+}
+export interface DiagnoseReport {
+    /** Password-redacted URL, safe to log alongside the report. */
+    safeUrl: string;
+    provider: ProviderId;
+    diagnostics: Diagnostic[];
+    /** True when no `error`-severity diagnostics are present. */
+    ok: boolean;
+}
+/**
+ * Analyze a connection config for serverless safety. Pure: returns a report,
+ * performs no I/O.
+ */
+export declare function diagnose(input: DiagnoseInput): DiagnoseReport;
+/** Format a report as plain text lines (for CLI / startup logs). */
+export declare function formatReport(report: DiagnoseReport): string;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/application/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/application/diagnostics.ts"],"names":[],"mappings":"AAQA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGzF,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,UAAU,CAAC;IACrB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,6DAA6D;IAC7D,EAAE,EAAE,OAAO,CAAC;CACb;AAID;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAiF7D;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAM3D"}