lambda-pool 0.1.0

package/dist/application/diagnostics.js

@@ -0,0 +1,94 @@
+// Diagnostics: inspect a connection config and surface actionable warnings.
+//
+// Composes the pure modules (url, providers, budget) into a single advisory
+// report. Returns data — it never logs or throws — so callers decide how to
+// present it (CLI, startup log, test assertion). This is the "lint your DB
+// connection for serverless" feature.
+import { recommendPoolLimit } from "../core/budget.js";
+import { detectProvider, isPooledEndpoint } from "../core/providers.js";
+import { parseConnectionString, redactUrl, urlRequestsSsl } from "../core/url.js";
+const DEFAULT_EXPECTED_INSTANCES = 20;
+/**
+ * Analyze a connection config for serverless safety. Pure: returns a report,
+ * performs no I/O.
+ */
+export function diagnose(input) {
+    const diagnostics = [];
+    const safeUrl = redactUrl(input.url);
+    let parsed;
+    try {
+        parsed = parseConnectionString(input.url);
+    }
+    catch (e) {
+        diagnostics.push({
+            severity: "error",
+            code: "INVALID_URL",
+            message: e.message,
+        });
+        return { safeUrl, provider: "unknown", diagnostics, ok: false };
+    }
+    const preset = detectProvider(parsed.host);
+    const pooled = isPooledEndpoint(parsed.host);
+    const instances = input.expectedInstances ?? DEFAULT_EXPECTED_INSTANCES;
+    // 1) Pool size sanity against the provider's typical budget.
+    const budget = recommendPoolLimit({
+        maxConnections: preset.typicalMaxConnections,
+        expectedInstances: instances,
+    });
+    if (!pooled && input.poolLimit > budget.recommendedPoolLimit) {
+        diagnostics.push({
+            severity: "warning",
+            code: "POOL_TOO_LARGE",
+            message: `poolLimit ${input.poolLimit} may exceed ${preset.label}'s budget: ` +
+                `${budget.rationale} Lower poolLimit or use a pooler.`,
+        });
+    }
+    // 2) Provider has a pooler but you're on the direct host.
+    if (preset.hasPooledEndpoint && !pooled && input.poolLimit > 1) {
+        diagnostics.push({
+            severity: "info",
+            code: "POOLER_AVAILABLE",
+            message: `${preset.label} offers a pooled endpoint. ${preset.note}`,
+        });
+    }
+    // 3) SSL requested in the URL but no CA supplied → likely silent fallback.
+    if (urlRequestsSsl(input.url) && !input.hasCaCert) {
+        diagnostics.push({
+            severity: "warning",
+            code: "SSL_WITHOUT_CA",
+            message: "URL requests SSL but no CA cert was provided (DATABASE_SSL_CA_BASE64). " +
+                "mysql2/pg may not verify the server as you expect; pass the CA explicitly.",
+        });
+    }
+    // 4) A pool larger than 1 with no pooler on a tiny-budget provider.
+    if (!preset.hasPooledEndpoint &&
+        input.poolLimit > preset.safeDirectPoolLimit &&
+        preset.typicalMaxConnections <= 30) {
+        diagnostics.push({
+            severity: "warning",
+            code: "SMALL_MAX_CONNECTIONS",
+            message: `${preset.label} typically caps max_connections around ${preset.typicalMaxConnections}; ` +
+                `keep the per-instance pool at ${preset.safeDirectPoolLimit}.`,
+        });
+    }
+    // 5) Friendly confirmation when everything looks right.
+    if (diagnostics.length === 0) {
+        diagnostics.push({
+            severity: "info",
+            code: "OK",
+            message: `Configuration looks serverless-safe for ${preset.label}.`,
+        });
+    }
+    const ok = !diagnostics.some((d) => d.severity === "error");
+    return { safeUrl, provider: preset.id, diagnostics, ok };
+}
+/** Format a report as plain text lines (for CLI / startup logs). */
+export function formatReport(report) {
+    const head = `lambda-pool diagnostics for ${report.safeUrl} [${report.provider}]`;
+    const lines = report.diagnostics.map((d) => `  ${symbolFor(d.severity)} ${d.code}: ${d.message}`);
+    return [head, ...lines].join("\n");
+}
+function symbolFor(s) {
+    return s === "error" ? "✖" : s === "warning" ? "⚠" : "ℹ";
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/application/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/application/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/application/inspect.d.ts

@@ -0,0 +1,20 @@
+import { type DiagnoseReport } from "./diagnostics.ts";
+import { type Env } from "../core/env.ts";
+export interface InspectEnv extends Env {
+    DATABASE_URL?: string;
+    MYSQL_URL?: string;
+    POSTGRES_URL?: string;
+    PG_URL?: string;
+    DATABASE_POOL_LIMIT?: string;
+    DATABASE_SSL_CA_BASE64?: string;
+    /** Optional hint for the budget check (peak warm instances). */
+    EXPECTED_INSTANCES?: string;
+}
+/**
+ * Build a diagnostics report from environment variables.
+ *
+ * Throws only when no connection URL is present at all — everything else is
+ * surfaced as diagnostics, never thrown.
+ */
+export declare function inspectEnv(env: InspectEnv): DiagnoseReport;
+//# sourceMappingURL=inspect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/application/inspect.ts"],"names":[],"mappings":"AAMA,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAA8B,KAAK,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAEtE,MAAM,WAAW,UAAW,SAAQ,GAAG;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gEAAgE;IAChE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,cAAc,CA0B1D"}

package/dist/application/inspect.js

@@ -0,0 +1,31 @@
+// Convenience: run diagnostics straight from an env bag.
+//
+// Bridges the env-shaped world (process.env) to the pure `diagnose()` core, so
+// apps can do a one-line startup check without re-deriving the URL/pool/CA
+// values themselves. Kept separate from the builders so each module has one job.
+import { diagnose } from "./diagnostics.js";
+import { resolvePoolLimit, firstEnv } from "../core/env.js";
+/**
+ * Build a diagnostics report from environment variables.
+ *
+ * Throws only when no connection URL is present at all — everything else is
+ * surfaced as diagnostics, never thrown.
+ */
+export function inspectEnv(env) {
+    const url = firstEnv(env, "DATABASE_URL", "MYSQL_URL", "POSTGRES_URL", "PG_URL");
+    if (!url) {
+        throw new Error("lambda-pool: no connection URL in env (DATABASE_URL / MYSQL_URL / POSTGRES_URL / PG_URL).");
+    }
+    const expected = env.EXPECTED_INSTANCES
+        ? Number(env.EXPECTED_INSTANCES)
+        : undefined;
+    return diagnose({
+        url,
+        poolLimit: resolvePoolLimit(env.DATABASE_POOL_LIMIT),
+        hasCaCert: Boolean(env.DATABASE_SSL_CA_BASE64),
+        ...(expected && Number.isFinite(expected) && expected > 0
+            ? { expectedInstances: Math.floor(expected) }
+            : {}),
+    });
+}
+//# sourceMappingURL=inspect.js.map

package/dist/application/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/application/inspect.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,iFAAiF;AAEjF,OAAO,EAAE,QAAQ,EAAuB,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAY,MAAM,gBAAgB,CAAC;AAatE;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAe;IACxC,MAAM,GAAG,GAAG,QAAQ,CAClB,GAAG,EACH,cAAc,EACd,WAAW,EACX,cAAc,EACd,QAAQ,CACT,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,kBAAkB;QACrC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAChC,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO,QAAQ,CAAC;QACd,GAAG;QACH,SAAS,EAAE,gBAAgB,CAAC,GAAG,CAAC,mBAAmB,CAAC;QACpD,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;QAC9C,GAAG,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC;YACvD,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE;YAC7C,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;AACL,CAAC"}

package/dist/application/preflight.d.ts

@@ -0,0 +1,28 @@
+import { type Diagnostic, type DiagnoseReport } from "./diagnostics.ts";
+import { type Env } from "../core/env.ts";
+export interface PreflightOptions {
+    /**
+     * Optional live reachability probe. Return true if the DB answered. Inject
+     * the adapter's `isReachable(pool)` here when you want a real connection test;
+     * omit it for a static (no-I/O) preflight.
+     */
+    probe?: () => Promise<boolean>;
+    /** Peak warm instances, forwarded to the budget checks. */
+    expectedInstances?: number;
+}
+export interface PreflightResult {
+    /** Overall pass: no `error` diagnostics and (if probed) the DB was reachable. */
+    ok: boolean;
+    safeUrl: string;
+    report: DiagnoseReport;
+    /** Present only when a probe was supplied. */
+    reachable?: boolean;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Run a preflight check over the connection in `env`. Never throws for a
+ * reachability failure — the probe result is folded into `ok`. Throws only when
+ * `env` has no connection URL at all (a programming/config error).
+ */
+export declare function preflight(env: Env, options?: PreflightOptions): Promise<PreflightResult>;
+//# sourceMappingURL=preflight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/application/preflight.ts"],"names":[],"mappings":"AAUA,OAAO,EAAY,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,cAAc,CAAC;IACvB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAqC1B"}

package/dist/application/preflight.js

@@ -0,0 +1,49 @@
+// Preflight: a single startup gate combining config + diagnostics, with an
+// optional live reachability probe.
+//
+// Lives in the application layer: it composes core (config) and application
+// (diagnostics). The live probe is *injected* as a function rather than
+// imported from adapters, so this module keeps the dependency rule intact
+// (application must not import adapters) while still supporting a real check.
+import { loadPoolConfig } from "../core/config.js";
+import { redactUrl } from "../core/url.js";
+import { diagnose } from "./diagnostics.js";
+import {} from "../core/env.js";
+/**
+ * Run a preflight check over the connection in `env`. Never throws for a
+ * reachability failure — the probe result is folded into `ok`. Throws only when
+ * `env` has no connection URL at all (a programming/config error).
+ */
+export async function preflight(env, options = {}) {
+    const config = loadPoolConfig(env); // throws if no URL — intentional
+    const report = diagnose({
+        url: config.url,
+        poolLimit: config.poolLimit,
+        hasCaCert: config.hasTls,
+        ...(options.expectedInstances
+            ? { expectedInstances: options.expectedInstances }
+            : {}),
+    });
+    const diagnostics = [...report.diagnostics];
+    let reachable;
+    if (options.probe) {
+        reachable = await options.probe().catch(() => false);
+        if (!reachable) {
+            diagnostics.push({
+                severity: "error",
+                code: "UNREACHABLE",
+                message: "Database did not respond to the reachability probe.",
+            });
+        }
+    }
+    const ok = !diagnostics.some((d) => d.severity === "error") &&
+        (reachable ?? true);
+    return {
+        ok,
+        safeUrl: redactUrl(config.url),
+        report,
+        ...(reachable === undefined ? {} : { reachable }),
+        diagnostics,
+    };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/application/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/application/preflight.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,oCAAoC;AACpC,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAwC,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAY,MAAM,gBAAgB,CAAC;AAuB1C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAQ,EACR,UAA4B,EAAE;IAE9B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,iCAAiC;IAErE,MAAM,MAAM,GAAG,QAAQ,CAAC;QACtB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,MAAM;QACxB,GAAG,CAAC,OAAO,CAAC,iBAAiB;YAC3B,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE;YAClD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,SAA8B,CAAC;IAEnC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,SAAS,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,WAAW,CAAC,IAAI,CAAC;gBACf,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,qDAAqD;aAC/D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,EAAE,GACN,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC;QAChD,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;IAEtB,OAAO;QACL,EAAE;QACF,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC;QAC9B,MAAM;QACN,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;QACjD,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/application/recommend.d.ts

@@ -0,0 +1,22 @@
+import { type BudgetResult } from "../core/budget.ts";
+import { type ProviderId } from "../core/providers.ts";
+export interface RecommendInput {
+    /** Connection URI. */
+    url: string;
+    /** Peak warm serverless instances. Default 20. */
+    expectedInstances?: number;
+    /** Override the provider's assumed max_connections (e.g. you know your plan). */
+    maxConnections?: number;
+}
+export interface Recommendation extends BudgetResult {
+    provider: ProviderId;
+    /** True when the URL already targets the provider's pooled endpoint. */
+    usingPooledEndpoint: boolean;
+    /** True when a pooler is recommended (budget exceeded and one is available). */
+    poolerAdvised: boolean;
+    /** The max_connections value the recommendation was computed against. */
+    assumedMaxConnections: number;
+}
+/** Recommend a pool size for the database behind `url`. Pure. */
+export declare function recommendForUrl(input: RecommendInput): Recommendation;
+//# sourceMappingURL=recommend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recommend.d.ts","sourceRoot":"","sources":["../../src/application/recommend.ts"],"names":[],"mappings":"AAOA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGzF,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,QAAQ,EAAE,UAAU,CAAC;IACrB,wEAAwE;IACxE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gFAAgF;IAChF,aAAa,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAID,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,CAsBrE"}

package/dist/application/recommend.js

@@ -0,0 +1,30 @@
+// Use-case: end-to-end pool recommendation from a connection URL.
+//
+// Composes provider detection (core/providers) with the budget math
+// (core/budget): given just a URL and an expected instance count, identify the
+// provider, use its typical max_connections as the budget, and recommend a
+// per-instance pool size — plus whether a pooler is advisable. No I/O.
+import { recommendPoolLimit } from "../core/budget.js";
+import { detectProvider, isPooledEndpoint } from "../core/providers.js";
+import { parseConnectionString } from "../core/url.js";
+const DEFAULT_EXPECTED_INSTANCES = 20;
+/** Recommend a pool size for the database behind `url`. Pure. */
+export function recommendForUrl(input) {
+    const { host } = parseConnectionString(input.url);
+    const preset = detectProvider(host);
+    const usingPooledEndpoint = isPooledEndpoint(host);
+    const assumedMaxConnections = input.maxConnections ?? preset.typicalMaxConnections;
+    const expectedInstances = input.expectedInstances ?? DEFAULT_EXPECTED_INSTANCES;
+    const budget = recommendPoolLimit({
+        maxConnections: assumedMaxConnections,
+        expectedInstances,
+    });
+    return {
+        ...budget,
+        provider: preset.id,
+        usingPooledEndpoint,
+        assumedMaxConnections,
+        poolerAdvised: budget.exceedsBudget && preset.hasPooledEndpoint && !usingPooledEndpoint,
+    };
+}
+//# sourceMappingURL=recommend.js.map

package/dist/application/recommend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend.js","sourceRoot":"","sources":["../../src/application/recommend.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,oEAAoE;AACpE,+EAA+E;AAC/E,2EAA2E;AAC3E,uEAAuE;AAEvE,OAAO,EAAE,kBAAkB,EAAqB,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAmB,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAqBvD,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAEtC,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,KAAqB;IACnD,MAAM,EAAE,IAAI,EAAE,GAAG,qBAAqB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAEnD,MAAM,qBAAqB,GACzB,KAAK,CAAC,cAAc,IAAI,MAAM,CAAC,qBAAqB,CAAC;IACvD,MAAM,iBAAiB,GAAG,KAAK,CAAC,iBAAiB,IAAI,0BAA0B,CAAC;IAEhF,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,cAAc,EAAE,qBAAqB;QACrC,iBAAiB;KAClB,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,EAAE,MAAM,CAAC,EAAE;QACnB,mBAAmB;QACnB,qBAAqB;QACrB,aAAa,EACX,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,iBAAiB,IAAI,CAAC,mBAAmB;KAC3E,CAAC;AACJ,CAAC"}

package/dist/core/budget.d.ts

@@ -0,0 +1,35 @@
+export interface BudgetInput {
+    /** The database server's `max_connections`. */
+    maxConnections: number;
+    /** Peak number of warm instances the platform may run concurrently. */
+    expectedInstances: number;
+    /**
+     * Connections to hold back for migrations, admin tools, the DB's own
+     * superuser reserve, cron jobs, etc. Defaults to a sensible floor.
+     */
+    reserved?: number;
+    /** Other long-lived clients (a separate worker, a BI tool) using the DB. */
+    otherClients?: number;
+}
+export interface BudgetResult {
+    /** Recommended per-instance pool size (>= 1). */
+    recommendedPoolLimit: number;
+    /** Connections available to serverless instances after reserves. */
+    usableConnections: number;
+    /** Projected peak usage at the recommended pool size. */
+    projectedPeakUsage: number;
+    /** True when even a pool of 1 across all instances exceeds the budget. */
+    exceedsBudget: boolean;
+    /** Human-readable explanation of how the number was derived. */
+    rationale: string;
+}
+/**
+ * Recommend a per-instance pool size from a connection budget.
+ *
+ * Formula: `floor((maxConnections - reserved - otherClients) / expectedInstances)`,
+ * clamped to at least 1. When even 1×instances exceeds the usable budget, the
+ * result still recommends 1 but flags `exceedsBudget` so the caller can warn
+ * that a pooler is needed.
+ */
+export declare function recommendPoolLimit(input: BudgetInput): BudgetResult;
+//# sourceMappingURL=budget.d.ts.map

package/dist/core/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/core/budget.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAgCnE"}

package/dist/core/budget.js

@@ -0,0 +1,48 @@
+// Connection-budget math.
+//
+// The core insight of this package as a pure function: given the database's
+// `max_connections`, how many connections may a single warm instance safely
+// pool, accounting for the number of instances the platform may keep warm and a
+// reserve for migrations / admin / other clients?
+//
+// Pure and dependency-free. No env, no I/O — just arithmetic you can unit-test.
+/** Postgres reserves superuser slots; default reserve reflects that + admin. */
+const DEFAULT_RESERVED = 3;
+function asPositiveInt(n, name) {
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`lambda-pool: ${name} must be a positive number (got ${n}).`);
+    }
+    return Math.floor(n);
+}
+/**
+ * Recommend a per-instance pool size from a connection budget.
+ *
+ * Formula: `floor((maxConnections - reserved - otherClients) / expectedInstances)`,
+ * clamped to at least 1. When even 1×instances exceeds the usable budget, the
+ * result still recommends 1 but flags `exceedsBudget` so the caller can warn
+ * that a pooler is needed.
+ */
+export function recommendPoolLimit(input) {
+    const maxConnections = asPositiveInt(input.maxConnections, "maxConnections");
+    const expectedInstances = asPositiveInt(input.expectedInstances, "expectedInstances");
+    const reserved = Math.max(0, Math.floor(input.reserved ?? DEFAULT_RESERVED));
+    const otherClients = Math.max(0, Math.floor(input.otherClients ?? 0));
+    const usableConnections = Math.max(0, maxConnections - reserved - otherClients);
+    const raw = Math.floor(usableConnections / expectedInstances);
+    const recommendedPoolLimit = Math.max(1, raw);
+    const projectedPeakUsage = recommendedPoolLimit * expectedInstances;
+    const exceedsBudget = projectedPeakUsage > usableConnections;
+    const rationale = exceedsBudget
+        ? `Even 1 connection × ${expectedInstances} instances (${expectedInstances}) exceeds the ${usableConnections} usable connections ` +
+            `(${maxConnections} max − ${reserved} reserved − ${otherClients} other). Use a connection pooler (PgBouncer / RDS Proxy / Neon pooled endpoint).`
+        : `${usableConnections} usable connections (${maxConnections} max − ${reserved} reserved − ${otherClients} other) ` +
+            `÷ ${expectedInstances} instances → pool of ${recommendedPoolLimit} per instance (peak ${projectedPeakUsage}).`;
+    return {
+        recommendedPoolLimit,
+        usableConnections,
+        projectedPeakUsage,
+        exceedsBudget,
+        rationale,
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/core/budget.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,gFAAgF;AAChF,kDAAkD;AAClD,EAAE;AACF,gFAAgF;AA6BhF,gFAAgF;AAChF,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B,SAAS,aAAa,CAAC,CAAS,EAAE,IAAY;IAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,mCAAmC,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAkB;IACnD,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;IAC7E,MAAM,iBAAiB,GAAG,aAAa,CACrC,KAAK,CAAC,iBAAiB,EACvB,mBAAmB,CACpB,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,gBAAgB,CAAC,CAAC,CAAC;IAC7E,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtE,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAChC,CAAC,EACD,cAAc,GAAG,QAAQ,GAAG,YAAY,CACzC,CAAC;IAEF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,GAAG,iBAAiB,CAAC,CAAC;IAC9D,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9C,MAAM,kBAAkB,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;IACpE,MAAM,aAAa,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;IAE7D,MAAM,SAAS,GAAG,aAAa;QAC7B,CAAC,CAAC,uBAAuB,iBAAiB,eAAe,iBAAiB,iBAAiB,iBAAiB,sBAAsB;YAChI,IAAI,cAAc,UAAU,QAAQ,eAAe,YAAY,kFAAkF;QACnJ,CAAC,CAAC,GAAG,iBAAiB,wBAAwB,cAAc,UAAU,QAAQ,eAAe,YAAY,UAAU;YACjH,KAAK,iBAAiB,wBAAwB,oBAAoB,uBAAuB,kBAAkB,IAAI,CAAC;IAEpH,OAAO;QACL,oBAAoB;QACpB,iBAAiB;QACjB,kBAAkB;QAClB,aAAa;QACb,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/core/config.d.ts

@@ -0,0 +1,24 @@
+import { type Env } from "./env.ts";
+import { type Engine } from "./url.ts";
+export interface PoolConfig {
+    /** The resolved connection URI. */
+    url: string;
+    /** Engine inferred from the URI scheme. */
+    engine: Engine;
+    /** Host, for provider detection. */
+    host: string;
+    /** Per-instance pool size (default 1). */
+    poolLimit: number;
+    /** Decoded CA PEM, when DATABASE_SSL_CA_BASE64 was provided. */
+    caCert?: string;
+    /** Whether TLS material was supplied. */
+    hasTls: boolean;
+}
+/**
+ * Read and normalize pool configuration from an env bag.
+ *
+ * Throws a single clear error when no connection URL is present; everything
+ * else has a defined default.
+ */
+export declare function loadPoolConfig(env: Env): PoolConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAOA,OAAO,EAA8C,KAAK,GAAG,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,EAAyB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAmBnD"}

package/dist/core/config.js

@@ -0,0 +1,32 @@
+// Normalized pool configuration from an environment bag.
+//
+// One place that reads the (many) accepted env var names and produces a single
+// typed, engine-resolved config. The adapters and use-cases consume this
+// instead of re-deriving URL / pool-limit / CA from raw env each time (DRY,
+// Single Source of Truth). Pure: takes an env object, returns data.
+import { decodeCaBase64, firstEnv, resolvePoolLimit } from "./env.js";
+import { parseConnectionString } from "./url.js";
+const URL_KEYS = ["DATABASE_URL", "MYSQL_URL", "POSTGRES_URL", "PG_URL"];
+/**
+ * Read and normalize pool configuration from an env bag.
+ *
+ * Throws a single clear error when no connection URL is present; everything
+ * else has a defined default.
+ */
+export function loadPoolConfig(env) {
+    const url = firstEnv(env, ...URL_KEYS);
+    if (!url) {
+        throw new Error(`lambda-pool: no connection URL in env (one of: ${URL_KEYS.join(", ")}).`);
+    }
+    const { engine, host } = parseConnectionString(url);
+    const tls = decodeCaBase64(env.DATABASE_SSL_CA_BASE64);
+    return {
+        url,
+        engine,
+        host,
+        poolLimit: resolvePoolLimit(env.DATABASE_POOL_LIMIT),
+        ...(tls ? { caCert: tls.ca } : {}),
+        hasTls: Boolean(tls),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,+EAA+E;AAC/E,yEAAyE;AACzE,4EAA4E;AAC5E,oEAAoE;AAEpE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,gBAAgB,EAAY,MAAM,UAAU,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAe,MAAM,UAAU,CAAC;AAiB9D,MAAM,QAAQ,GAAG,CAAC,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,CAAU,CAAC;AAElF;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAQ;IACrC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,kDAAkD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC1E,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAEvD,OAAO;QACL,GAAG;QACH,MAAM;QACN,IAAI;QACJ,SAAS,EAAE,gBAAgB,CAAC,GAAG,CAAC,mBAAmB,CAAC;QACpD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC;KACrB,CAAC;AACJ,CAAC"}

package/dist/core/dsn.d.ts

@@ -0,0 +1,20 @@
+import { type Engine } from "./url.ts";
+export interface DsnParts {
+    engine: Engine;
+    host: string;
+    /** Defaults to the engine's standard port when omitted. */
+    port?: number;
+    user: string;
+    password?: string;
+    database: string;
+    /** Extra query params, e.g. `{ sslmode: "require" }`. */
+    params?: Record<string, string>;
+}
+/**
+ * Assemble a valid connection URI from typed parts.
+ *
+ * Throws when a required field (host, user, database) is missing, so a
+ * misconfigured environment fails loudly at build time rather than at connect.
+ */
+export declare function buildDsn(parts: DsnParts): string;
+//# sourceMappingURL=dsn.d.ts.map

package/dist/core/dsn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.d.ts","sourceRoot":"","sources":["../../src/core/dsn.ts"],"names":[],"mappings":"AAOA,OAAO,EAAe,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAOD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAkBhD"}

package/dist/core/dsn.js

@@ -0,0 +1,38 @@
+// Build a connection string from parts — the inverse of parseConnectionString.
+//
+// Useful when credentials arrive as discrete env vars (DB_HOST, DB_USER, …)
+// rather than a single URL, which is common on RDS / self-hosted setups. Pure
+// and dependency-free; encodes each component so special characters in a
+// password don't corrupt the URI.
+import { defaultPort } from "./url.js";
+const PROTOCOL = {
+    mysql: "mysql:",
+    postgres: "postgres:",
+};
+/**
+ * Assemble a valid connection URI from typed parts.
+ *
+ * Throws when a required field (host, user, database) is missing, so a
+ * misconfigured environment fails loudly at build time rather than at connect.
+ */
+export function buildDsn(parts) {
+    if (!parts.host)
+        throw new Error("lambda-pool: buildDsn requires a host.");
+    if (!parts.user)
+        throw new Error("lambda-pool: buildDsn requires a user.");
+    if (!parts.database) {
+        throw new Error("lambda-pool: buildDsn requires a database.");
+    }
+    const url = new URL(`${PROTOCOL[parts.engine]}//placeholder`);
+    url.hostname = parts.host;
+    url.port = String(parts.port ?? defaultPort(parts.engine));
+    url.username = encodeURIComponent(parts.user);
+    if (parts.password)
+        url.password = encodeURIComponent(parts.password);
+    url.pathname = `/${encodeURIComponent(parts.database)}`;
+    for (const [k, v] of Object.entries(parts.params ?? {})) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+//# sourceMappingURL=dsn.js.map

package/dist/core/dsn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.js","sourceRoot":"","sources":["../../src/core/dsn.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,yEAAyE;AACzE,kCAAkC;AAElC,OAAO,EAAE,WAAW,EAAe,MAAM,UAAU,CAAC;AAcpD,MAAM,QAAQ,GAA2B;IACvC,KAAK,EAAE,QAAQ;IACf,QAAQ,EAAE,WAAW;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAe;IACtC,IAAI,CAAC,KAAK,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC3E,IAAI,CAAC,KAAK,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC3E,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAC9D,GAAG,CAAC,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC;IAC1B,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3D,GAAG,CAAC,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,KAAK,CAAC,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtE,GAAG,CAAC,QAAQ,GAAG,IAAI,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC"}

package/dist/core/env.d.ts

@@ -0,0 +1,27 @@
+/** A bag of env vars (e.g. `process.env`). */
+export type Env = Record<string, string | undefined>;
+/** TLS material once decoded, ready to hand to a driver. */
+export interface DecodedTls {
+    ca: string;
+    rejectUnauthorized: boolean;
+}
+/**
+ * Resolve the per-instance pool size.
+ *
+ * Defaults to 1 (see file header). Any non-positive / non-finite override is
+ * ignored and falls back to the default so a bad env var can never widen the
+ * pool by accident.
+ */
+export declare function resolvePoolLimit(raw: string | undefined, fallback?: number): number;
+/**
+ * Decode a base64-encoded CA certificate into TLS options.
+ *
+ * Managed providers hand you a CA bundle but the connection URI's
+ * `?ssl-mode=REQUIRED` / `?sslmode=require` param is NOT understood by mysql2
+ * or pg in the way people expect, so we pass the CA explicitly and verify the
+ * server. Returns `undefined` when no CA is configured (driver defaults apply).
+ */
+export declare function decodeCaBase64(caBase64: string | undefined, rejectUnauthorized?: boolean): DecodedTls | undefined;
+/** Read the first defined value among the given env keys. */
+export declare function firstEnv(env: Env, ...keys: string[]): string | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/core/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/core/env.ts"],"names":[],"mappings":"AAcA,8CAA8C;AAC9C,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAErD,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,SAAI,GACX,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,kBAAkB,UAAO,GACxB,UAAU,GAAG,SAAS,CAMxB;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAMxE"}

package/dist/core/env.js

@@ -0,0 +1,52 @@
+// Shared, dependency-free helpers used by both the MySQL and Postgres adapters.
+//
+// Why this package exists
+// -----------------------
+// On Vercel/Lambda every *warm* function instance keeps its own connection
+// pool. If each pool opens N connections and the platform keeps M instances
+// warm, the database sees up to N*M connections. Managed Postgres/MySQL on
+// small plans (Aiven free, Neon, RDS micro, PlanetScale) cap `max_connections`
+// very low (often 10-25), so a seemingly innocent `connectionLimit: 10` will
+// throw `ER_CON_COUNT_ERROR` / `too many clients already` under modest traffic.
+//
+// The fix is counter-intuitive: make each pool TINY (default 1). The platform's
+// horizontal scaling becomes your concurrency; the database stops melting.
+/**
+ * Resolve the per-instance pool size.
+ *
+ * Defaults to 1 (see file header). Any non-positive / non-finite override is
+ * ignored and falls back to the default so a bad env var can never widen the
+ * pool by accident.
+ */
+export function resolvePoolLimit(raw, fallback = 1) {
+    if (raw == null || raw === "")
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+/**
+ * Decode a base64-encoded CA certificate into TLS options.
+ *
+ * Managed providers hand you a CA bundle but the connection URI's
+ * `?ssl-mode=REQUIRED` / `?sslmode=require` param is NOT understood by mysql2
+ * or pg in the way people expect, so we pass the CA explicitly and verify the
+ * server. Returns `undefined` when no CA is configured (driver defaults apply).
+ */
+export function decodeCaBase64(caBase64, rejectUnauthorized = true) {
+    if (!caBase64)
+        return undefined;
+    return {
+        ca: Buffer.from(caBase64, "base64").toString("utf8"),
+        rejectUnauthorized,
+    };
+}
+/** Read the first defined value among the given env keys. */
+export function firstEnv(env, ...keys) {
+    for (const k of keys) {
+        const v = env[k];
+        if (v != null && v !== "")
+            return v;
+    }
+    return undefined;
+}
+//# sourceMappingURL=env.js.map

package/dist/core/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/core/env.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,0BAA0B;AAC1B,0BAA0B;AAC1B,2EAA2E;AAC3E,4EAA4E;AAC5E,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAW3E;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAuB,EACvB,QAAQ,GAAG,CAAC;IAEZ,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC/C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,QAA4B,EAC5B,kBAAkB,GAAG,IAAI;IAEzB,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;QACpD,kBAAkB;KACnB,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,QAAQ,CAAC,GAAQ,EAAE,GAAG,IAAc;IAClD,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACjB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}