turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/connection-guard.d.ts

@@ -58,6 +58,19 @@ export interface CheckoutGuard extends ConnectionGuard {
  * event (an engine shim) is left alone.
  */
 export declare function absorbCheckedOutErrors(pool: unknown): void;
+export interface CheckoutWatch {
+    /** Connections currently checked out of the pool, in checkout order. */
+    readonly checkedOut: ReadonlySet<object>;
+}
+/**
+ * Track which connections of a pool Turbine owns are checked out, from
+ * pg-pool's public `acquire` / `release` / `remove` events, and call `onLost`
+ * once per connection that fails WHILE checked out (an idle connection's
+ * failure is pg-pool's own `'error'` event). Used for the client's
+ * `connectionLost` event and for force-closing what `disconnect({ timeoutMs })`
+ * is still waiting on. A pool without those events is left alone.
+ */
+export declare function watchCheckouts(pool: unknown, onLost?: (err: Error) => void): CheckoutWatch;
 /**
  * Guard a connection for as long as the caller holds it. Use {@link guardCheckout}
  * for a pooled checkout; this form is for a client whose whole lifetime the

package/dist/cjs/connection-guard.js

@@ -32,6 +32,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LONG_IDLE_SETTLE_MS = void 0;
 exports.absorbCheckedOutErrors = absorbCheckedOutErrors;
+exports.watchCheckouts = watchCheckouts;
 exports.guardConnection = guardConnection;
 exports.guardCheckout = guardCheckout;
 exports.settleEventLoop = settleEventLoop;
@@ -54,6 +55,33 @@ function absorbCheckedOutErrors(pool) {
         client.on?.('error', () => { });
     });
 }
+/**
+ * Track which connections of a pool Turbine owns are checked out, from
+ * pg-pool's public `acquire` / `release` / `remove` events, and call `onLost`
+ * once per connection that fails WHILE checked out (an idle connection's
+ * failure is pg-pool's own `'error'` event). Used for the client's
+ * `connectionLost` event and for force-closing what `disconnect({ timeoutMs })`
+ * is still waiting on. A pool without those events is left alone.
+ */
+function watchCheckouts(pool, onLost) {
+    const checkedOut = new Set();
+    const emitter = pool;
+    if (typeof emitter.on !== 'function')
+        return { checkedOut };
+    const reported = new WeakSet();
+    emitter.on('acquire', (client) => checkedOut.add(client));
+    emitter.on('release', (_err, client) => checkedOut.delete(client));
+    emitter.on('remove', (client) => checkedOut.delete(client));
+    emitter.on('connect', (client) => {
+        client.on?.('error', (err) => {
+            if (!checkedOut.has(client) || reported.has(client))
+                return;
+            reported.add(client);
+            onLost?.(err);
+        });
+    });
+    return { checkedOut };
+}
 /**
  * Guard a connection for as long as the caller holds it. Use {@link guardCheckout}
  * for a pooled checkout; this form is for a client whose whole lifetime the

package/dist/cjs/connection-url.d.ts

@@ -107,12 +107,33 @@ export interface PoolerDetection {
  * blocks a legitimate database, so precision wins and the caller is expected to
  * offer an override.
  */
-export declare function detectPooler(connectionString: string): PoolerDetection;
+export declare function detectPooler(connectionString: string, environment?: PgEnvironmentTarget): PoolerDetection;
+/**
+ * The `PGHOST` / `PGPORT` values a connection target falls back to. node-postgres
+ * reads a field from the connection string or the config first and the
+ * environment only when that leaves it unset, so a string that names no port (or
+ * no host) is still connecting to wherever these point.
+ */
+export interface PgEnvironmentTarget {
+    readonly host?: string | undefined;
+    readonly port?: string | undefined;
+}
+/** `target` with the host and port it leaves unset taken from `environment`, the way node-postgres does. */
+export declare function fillTargetFromEnvironment(target: ConnectionTarget, environment: PgEnvironmentTarget): ConnectionTarget;
+/** {@link detectPooler} for a target that is already parsed. */
+export declare function detectPoolerTarget(target: ConnectionTarget): PoolerDetection;
 export interface PoolerRefusalOptions {
     /** The command being refused, e.g. `turbine doctor`. */
     command: string;
     /** The flag that overrides the refusal, e.g. `--allow-pooler`. */
     allowFlag: string;
+    /**
+     * Why THIS command cannot use a pooler, in place of the default paragraph
+     * (written for `doctor`: session state, session-scoped views, the read bound).
+     * Lines are printed as given, between the endpoint and the advice to use the
+     * direct endpoint.
+     */
+    explanation?: readonly string[];
 }
 /**
  * The lines a command prints when it refuses a pooler endpoint.
@@ -158,6 +179,30 @@ export interface ConnectionOptionsConfig {
  * a value that can carry a space can carry a second `-c`.
  */
 export declare function withStatementTimeoutOption(config: ConnectionOptionsConfig, statementTimeoutMs: number): ConnectionOptionsConfig;
+/**
+ * The `-c statement_timeout=<ms>` startup setting, or `null` when the value is
+ * not a non-negative safe integer (see the injection note on
+ * {@link withStatementTimeoutOption}). No unit suffix: the GUC's default unit
+ * is milliseconds.
+ */
+export declare function statementTimeoutSetting(statementTimeoutMs: number): string | null;
+/**
+ * `config` with one `-c name=value` startup setting appended to its libpq
+ * `options`, in whichever place pg will read them from: an `options` query
+ * parameter already on the connection string wins over the `options` field,
+ * and the field falls back to `PGOPTIONS` only while it is unset, so both are
+ * read first and appended to rather than replaced.
+ *
+ * `setting` is emitted verbatim. The caller must have built it from a closed
+ * set or a narrowed number: the `options` string is split on whitespace, so a
+ * caller-controlled value could carry a second `-c`.
+ */
+export declare function withStartupSetting<T extends {
+    connectionString?: string;
+    options?: string;
+}>(config: T, setting: string): T & {
+    options?: string;
+};
 /**
  * `connectionString` with `setting` appended to an existing `options` query
  * parameter, or `null` when it carries none (in which case the caller uses the
@@ -170,22 +215,12 @@ export declare function withStatementTimeoutOption(config: ConnectionOptionsConf
  * password is not parseable by pg either, so there is no shape this handles
  * differently from the driver.
  *
- * Shared with `client.ts`, which needs the identical merge for
- * `plan_cache_mode`. It was duplicated there until 2026-08-16, and the reason
- * is worth keeping because it was wrong in an instructive way: importing it
- * from `client.ts` adds an import edge from a module ~100 test processes load,
- * and this file's merged coverage read 40% while measuring 100% in isolation,
- * which moved the aggregate gate 75.48% -> 75.03% against a 75% floor. The
- * conclusion drawn was that the refactor cost the gate's headroom.
- *
- * The 40% was a c8 merge defect, not an import cost: c8's V8-level merge is not
- * monotonic, and once the report merges at the istanbul level instead this file
- * reads 100% with the edge in place (see `//merge-bug` in .c8rc.json). So the
- * duplication was paying for an artifact, and the two copies are now one.
+ * Used by {@link withStartupSetting} (the client's pool configuration) and
+ * {@link withSearchPathOption}.
  *
- * Keep this module import-free regardless. That part was never about coverage:
- * `query/` and `cli/` both reach it, and an edge back to `client.ts` would be
- * the cycle `scripts/check-import-cycles.mjs` exists to refuse.
+ * Keep this module import-free: `query/` and `cli/` both reach it, and an
+ * edge back to `client.ts` would be the cycle `scripts/check-import-cycles.mjs`
+ * exists to refuse.
  */
 export declare function mergeConnectionStringOptions(connectionString: string, setting: string): string | null;
 /**

package/dist/cjs/connection-url.js

@@ -37,8 +37,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SEARCH_PATH_SCHEMA_PATTERN = exports.POOLER_PORTS = exports.POOLER_HOST_TOKENS = void 0;
 exports.parseConnectionTarget = parseConnectionTarget;
 exports.detectPooler = detectPooler;
+exports.fillTargetFromEnvironment = fillTargetFromEnvironment;
+exports.detectPoolerTarget = detectPoolerTarget;
 exports.poolerRefusalMessage = poolerRefusalMessage;
 exports.withStatementTimeoutOption = withStatementTimeoutOption;
+exports.statementTimeoutSetting = statementTimeoutSetting;
+exports.withStartupSetting = withStartupSetting;
 exports.mergeConnectionStringOptions = mergeConnectionStringOptions;
 exports.isPlainSchemaIdentifier = isPlainSchemaIdentifier;
 exports.parseSearchPathValue = parseSearchPathValue;
@@ -117,8 +121,22 @@ function noPooler(target) {
  * blocks a legitimate database, so precision wins and the caller is expected to
  * offer an override.
  */
-function detectPooler(connectionString) {
-    const target = parseConnectionTarget(connectionString);
+function detectPooler(connectionString, environment) {
+    const parsed = parseConnectionTarget(connectionString);
+    return detectPoolerTarget(environment === undefined ? parsed : fillTargetFromEnvironment(parsed, environment));
+}
+/** `target` with the host and port it leaves unset taken from `environment`, the way node-postgres does. */
+function fillTargetFromEnvironment(target, environment) {
+    const host = target.host ?? (environment.host ? environment.host.trim().toLowerCase() || null : null);
+    let port = target.port;
+    if (port === null && environment.port) {
+        const parsed = Number.parseInt(environment.port, 10);
+        port = Number.isInteger(parsed) ? parsed : null;
+    }
+    return { host, port };
+}
+/** {@link detectPooler} for a target that is already parsed. */
+function detectPoolerTarget(target) {
     if (target.host !== null) {
         for (const label of target.host.split('.')) {
             for (const token of label.split(/[-_]/)) {
@@ -171,6 +189,21 @@ function deriveDirectHost(host, token) {
     });
     return changed ? rewritten.join('.') : null;
 }
+/** Why `turbine doctor` refuses a pooler; the paragraph {@link poolerRefusalMessage} prints by default. */
+const DEFAULT_POOLER_EXPLANATION = [
+    'A transaction pooler (PgBouncer, a Neon "-pooler" endpoint, Supabase\'s pooler) does not',
+    'give a client its own server backend. It multiplexes many clients onto a few shared',
+    'backends and reuses one as soon as a transaction ends, so:',
+    '',
+    '  1. Session state is not private. Anything this command sets on the session can be left',
+    '     behind for another client, and whatever an earlier client left behind can be in',
+    '     force for this one. That is how a "read-only guardrail" becomes an outage.',
+    '  2. Session-scoped views describe the wrong session. pg_prepared_statements, which this',
+    '     report tells you to read to confirm a cached plan, belongs to whichever backend',
+    '     answered, not to your application.',
+    '  3. The read bounds may not apply. This command asks for its statement_timeout as a',
+    '     connection parameter, and a pooler is free to drop or reject one.',
+];
 /**
  * The lines a command prints when it refuses a pooler endpoint.
  *
@@ -188,18 +221,7 @@ function poolerRefusalMessage(detection, options) {
         `  Endpoint: ${where}${detection.port === null ? '' : `:${detection.port}`}`,
         `  Detected: ${what}`,
         '',
-        'A transaction pooler (PgBouncer, a Neon "-pooler" endpoint, Supabase\'s pooler) does not',
-        'give a client its own server backend. It multiplexes many clients onto a few shared',
-        'backends and reuses one as soon as a transaction ends, so:',
-        '',
-        '  1. Session state is not private. Anything this command sets on the session can be left',
-        '     behind for another client, and whatever an earlier client left behind can be in',
-        '     force for this one. That is how a "read-only guardrail" becomes an outage.',
-        '  2. Session-scoped views describe the wrong session. pg_prepared_statements, which this',
-        '     report tells you to read to confirm a cached plan, belongs to whichever backend',
-        '     answered, not to your application.',
-        '  3. The read bounds may not apply. This command asks for its statement_timeout as a',
-        '     connection parameter, and a pooler is free to drop or reject one.',
+        ...(options.explanation ?? DEFAULT_POOLER_EXPLANATION),
         '',
         'Use the DIRECT (non-pooled) endpoint for the same database instead.',
     ];
@@ -244,12 +266,33 @@ function poolerRefusalMessage(detection, options) {
  * a value that can carry a space can carry a second `-c`.
  */
 function withStatementTimeoutOption(config, statementTimeoutMs) {
+    const setting = statementTimeoutSetting(statementTimeoutMs);
+    return setting === null ? config : withStartupSetting(config, setting);
+}
+/**
+ * The `-c statement_timeout=<ms>` startup setting, or `null` when the value is
+ * not a non-negative safe integer (see the injection note on
+ * {@link withStatementTimeoutOption}). No unit suffix: the GUC's default unit
+ * is milliseconds.
+ */
+function statementTimeoutSetting(statementTimeoutMs) {
     if (!Number.isSafeInteger(statementTimeoutMs) || statementTimeoutMs < 0)
-        return config;
-    // No unit suffix: statement_timeout's default unit IS milliseconds, which is
-    // what `SET statement_timeout = <n>` meant before this replaced it.
-    const setting = `-c statement_timeout=${statementTimeoutMs}`;
-    const merged = mergeConnectionStringOptions(config.connectionString, setting);
+        return null;
+    return `-c statement_timeout=${statementTimeoutMs}`;
+}
+/**
+ * `config` with one `-c name=value` startup setting appended to its libpq
+ * `options`, in whichever place pg will read them from: an `options` query
+ * parameter already on the connection string wins over the `options` field,
+ * and the field falls back to `PGOPTIONS` only while it is unset, so both are
+ * read first and appended to rather than replaced.
+ *
+ * `setting` is emitted verbatim. The caller must have built it from a closed
+ * set or a narrowed number: the `options` string is split on whitespace, so a
+ * caller-controlled value could carry a second `-c`.
+ */
+function withStartupSetting(config, setting) {
+    const merged = config.connectionString ? mergeConnectionStringOptions(config.connectionString, setting) : null;
     if (merged !== null)
         return { ...config, connectionString: merged };
     const existing = config.options || (typeof process !== 'undefined' ? process.env?.PGOPTIONS : undefined);
@@ -267,22 +310,12 @@ function withStatementTimeoutOption(config, statementTimeoutMs) {
  * password is not parseable by pg either, so there is no shape this handles
  * differently from the driver.
  *
- * Shared with `client.ts`, which needs the identical merge for
- * `plan_cache_mode`. It was duplicated there until 2026-08-16, and the reason
- * is worth keeping because it was wrong in an instructive way: importing it
- * from `client.ts` adds an import edge from a module ~100 test processes load,
- * and this file's merged coverage read 40% while measuring 100% in isolation,
- * which moved the aggregate gate 75.48% -> 75.03% against a 75% floor. The
- * conclusion drawn was that the refactor cost the gate's headroom.
- *
- * The 40% was a c8 merge defect, not an import cost: c8's V8-level merge is not
- * monotonic, and once the report merges at the istanbul level instead this file
- * reads 100% with the edge in place (see `//merge-bug` in .c8rc.json). So the
- * duplication was paying for an artifact, and the two copies are now one.
+ * Used by {@link withStartupSetting} (the client's pool configuration) and
+ * {@link withSearchPathOption}.
  *
- * Keep this module import-free regardless. That part was never about coverage:
- * `query/` and `cli/` both reach it, and an edge back to `client.ts` would be
- * the cycle `scripts/check-import-cycles.mjs` exists to refuse.
+ * Keep this module import-free: `query/` and `cli/` both reach it, and an
+ * edge back to `client.ts` would be the cycle `scripts/check-import-cycles.mjs`
+ * exists to refuse.
  */
 function mergeConnectionStringOptions(connectionString, setting) {
     const q = connectionString.indexOf('?');

package/dist/cjs/diagnostics.d.ts

@@ -0,0 +1,81 @@
+/**
+ * turbine-orm, the `diagnostics` switch.
+ *
+ * One client option decides what Turbine checks and says about itself at run
+ * time: per-query advice (unknown options, unordered pages, deep `with`,
+ * strategy notes, missing FK indexes, redundant sort terms) and the SQL-cache
+ * self-check. It is resolved ONCE, when a client is constructed, and travels to
+ * every query interface the client builds, so no hot path reads `process.env`.
+ *
+ * This module is the only place in the library (outside `cli/`) that reads
+ * `NODE_ENV` or the two `TURBINE_*` cache-check variables; a source scan
+ * (`fleet-diagnostics-env-scan.test.ts`) fails the build on a second reader.
+ *
+ * Zero imports besides errors.ts, so client.ts, query/ and the engines can all
+ * depend on it without a new cycle.
+ */
+/** `'development'`: advice on, cache self-check on every hit. `'production'`: both off. */
+export type DiagnosticsMode = 'development' | 'production';
+/** The SQL-cache self-check: rebuild on every cache hit, a sampled fraction of hits, or never. */
+export type CacheCheckMode = 'every-hit' | 'off' | {
+    readonly sample: number;
+};
+/** Per-part overrides for {@link DiagnosticsConfig}. Unset parts follow the mode. */
+export interface DiagnosticsOptions {
+    /**
+     * Per-query advice: unknown query options, unordered pages, deep `with`
+     * trees, relation-strategy notes, missing FK indexes, redundant sort terms.
+     * Default: on in development, off in production.
+     */
+    advice?: boolean | undefined;
+    /**
+     * SQL-cache self-check. `'every-hit'` rebuilds the SQL on each cache hit
+     * and compares; `{ sample }` compares that fraction of hits, in `(0, 1]`;
+     * `'off'` never compares. Default: `'every-hit'` in development, `'off'` in
+     * production. A mismatch means Turbine has a bug, and throws.
+     */
+    cacheCheck?: CacheCheckMode | undefined;
+}
+/**
+ * The `diagnostics` client option: a mode, or per-part overrides on top of
+ * one. When no mode is given it comes from `NODE_ENV`, read once when the
+ * client is constructed: `'production'` when `NODE_ENV` is `'production'` (or
+ * when there is no `process` at all, as on an edge runtime), else
+ * `'development'`.
+ */
+export type DiagnosticsConfig = DiagnosticsMode | (DiagnosticsOptions & {
+    mode?: DiagnosticsMode | undefined;
+});
+/** What a client actually runs with. Frozen; built only by {@link resolveDiagnostics}. */
+export interface ResolvedDiagnostics {
+    readonly mode: DiagnosticsMode;
+    /** Whether per-query advice is emitted. */
+    readonly advice: boolean;
+    readonly cacheCheck: CacheCheckMode;
+}
+/**
+ * The environment variables this module reads. `null` in their place means
+ * there is no `process` to read (an edge runtime), which resolves to
+ * production.
+ */
+export interface DiagnosticsEnv {
+    NODE_ENV?: string | undefined;
+    TURBINE_DISABLE_CACHE_CHECK?: string | undefined;
+    TURBINE_CACHE_CHECK_SAMPLE?: string | undefined;
+}
+/**
+ * Resolve the `diagnostics` option, once, at client construction.
+ *
+ * Precedence for each part: the explicit option, then (for `cacheCheck` only)
+ * the legacy `TURBINE_DISABLE_CACHE_CHECK` / `TURBINE_CACHE_CHECK_SAMPLE`
+ * variables, then the mode's default. The mode itself is the option's, else
+ * `NODE_ENV`'s.
+ *
+ * Throws `ValidationError` (E003) for an unknown mode, an unknown key, a
+ * non-boolean `advice`, or a `sample` outside `(0, 1]`. A value this function
+ * returned is handed back by reference.
+ *
+ * @param env - The environment to read; defaults to `process.env`. Tests pass
+ *   one explicitly; `null` stands for a runtime with no `process`.
+ */
+export declare function resolveDiagnostics(config?: unknown, env?: DiagnosticsEnv | null): ResolvedDiagnostics;

package/dist/cjs/diagnostics.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * turbine-orm, the `diagnostics` switch.
+ *
+ * One client option decides what Turbine checks and says about itself at run
+ * time: per-query advice (unknown options, unordered pages, deep `with`,
+ * strategy notes, missing FK indexes, redundant sort terms) and the SQL-cache
+ * self-check. It is resolved ONCE, when a client is constructed, and travels to
+ * every query interface the client builds, so no hot path reads `process.env`.
+ *
+ * This module is the only place in the library (outside `cli/`) that reads
+ * `NODE_ENV` or the two `TURBINE_*` cache-check variables; a source scan
+ * (`fleet-diagnostics-env-scan.test.ts`) fails the build on a second reader.
+ *
+ * Zero imports besides errors.ts, so client.ts, query/ and the engines can all
+ * depend on it without a new cycle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDiagnostics = resolveDiagnostics;
+const errors_js_1 = require("./errors.js");
+const MODES = ['development', 'production'];
+const OPTION_KEYS = new Set(['mode', 'advice', 'cacheCheck']);
+/**
+ * Marks objects {@link resolveDiagnostics} built, so resolving a resolved value
+ * hands it back by reference. A `TransactionClient` builds a query interface
+ * per table per transaction from the client's options; re-resolving there would
+ * put the environment reads back on a per-transaction path.
+ */
+const resolvedSet = new WeakSet();
+/**
+ * Read the variables once. Every read is guarded: no `process` (edge runtimes)
+ * and no `process.env` (some sandboxes) both mean "no environment".
+ */
+function readEnv() {
+    if (typeof process === 'undefined' || process.env === undefined)
+        return null;
+    const env = process.env;
+    return {
+        NODE_ENV: env.NODE_ENV,
+        TURBINE_DISABLE_CACHE_CHECK: env.TURBINE_DISABLE_CACHE_CHECK,
+        TURBINE_CACHE_CHECK_SAMPLE: env.TURBINE_CACHE_CHECK_SAMPLE,
+    };
+}
+function invalid(detail) {
+    return new errors_js_1.ValidationError(`Invalid diagnostics option: ${detail}. Expected 'development', 'production', or ` +
+        "{ mode?, advice?: boolean, cacheCheck?: 'every-hit' | 'off' | { sample: number in (0, 1] } }.");
+}
+function checkSample(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
+        throw invalid(`cacheCheck.sample must be a number in (0, 1], got ${describe(value)}`);
+    }
+    return value;
+}
+function describe(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null || value === undefined) {
+        return String(value);
+    }
+    return Array.isArray(value) ? 'an array' : `a ${typeof value}`;
+}
+function resolveCacheCheck(value) {
+    if (value === 'every-hit' || value === 'off')
+        return value;
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        const keys = Object.keys(value);
+        if (keys.length !== 1 || keys[0] !== 'sample') {
+            throw invalid(`cacheCheck object takes exactly one key, sample; got { ${keys.join(', ')} }`);
+        }
+        return Object.freeze({ sample: checkSample(value.sample) });
+    }
+    throw invalid(`cacheCheck ${describe(value)}`);
+}
+/**
+ * The legacy cache-check variables, under an explicit `cacheCheck`.
+ * `TURBINE_DISABLE_CACHE_CHECK=1` turns the check off in any mode. In
+ * production mode, `TURBINE_CACHE_CHECK_SAMPLE` sets a sample rate: a rate of
+ * 1 or more checks every hit, and 0, a negative or an unparseable value leaves
+ * the check off, as these variables always behaved. Development mode already
+ * checks every hit, so the sample variable is not read there.
+ */
+function legacyCacheCheck(mode, env) {
+    if (env === null)
+        return undefined;
+    if (env.TURBINE_DISABLE_CACHE_CHECK === '1')
+        return 'off';
+    if (mode !== 'production' || env.TURBINE_CACHE_CHECK_SAMPLE === undefined)
+        return undefined;
+    const rate = Number.parseFloat(env.TURBINE_CACHE_CHECK_SAMPLE);
+    if (!Number.isFinite(rate) || rate <= 0)
+        return 'off';
+    return Object.freeze({ sample: Math.min(rate, 1) });
+}
+/**
+ * Resolve the `diagnostics` option, once, at client construction.
+ *
+ * Precedence for each part: the explicit option, then (for `cacheCheck` only)
+ * the legacy `TURBINE_DISABLE_CACHE_CHECK` / `TURBINE_CACHE_CHECK_SAMPLE`
+ * variables, then the mode's default. The mode itself is the option's, else
+ * `NODE_ENV`'s.
+ *
+ * Throws `ValidationError` (E003) for an unknown mode, an unknown key, a
+ * non-boolean `advice`, or a `sample` outside `(0, 1]`. A value this function
+ * returned is handed back by reference.
+ *
+ * @param env - The environment to read; defaults to `process.env`. Tests pass
+ *   one explicitly; `null` stands for a runtime with no `process`.
+ */
+function resolveDiagnostics(config, env = readEnv()) {
+    if (typeof config === 'object' && config !== null && resolvedSet.has(config)) {
+        return config;
+    }
+    let options = {};
+    if (typeof config === 'string') {
+        if (!MODES.includes(config))
+            throw invalid(`unknown mode ${describe(config)}`);
+        options = { mode: config };
+    }
+    else if (typeof config === 'object' && config !== null && !Array.isArray(config)) {
+        for (const key of Object.keys(config)) {
+            if (!OPTION_KEYS.has(key))
+                throw invalid(`unknown key "${key}"`);
+        }
+        options = config;
+        if (options.mode !== undefined && !MODES.includes(options.mode)) {
+            throw invalid(`unknown mode ${describe(options.mode)}`);
+        }
+        if (options.advice !== undefined && typeof options.advice !== 'boolean') {
+            throw invalid(`advice must be a boolean, got ${describe(options.advice)}`);
+        }
+    }
+    else if (config !== undefined && config !== null) {
+        throw invalid(describe(config));
+    }
+    const mode = options.mode ??
+        (env === null || env.NODE_ENV === 'production' ? 'production' : 'development');
+    const cacheCheck = options.cacheCheck !== undefined
+        ? resolveCacheCheck(options.cacheCheck)
+        : (legacyCacheCheck(mode, env) ?? (mode === 'production' ? 'off' : 'every-hit'));
+    const resolved = Object.freeze({
+        mode,
+        advice: options.advice ?? mode === 'development',
+        cacheCheck,
+    });
+    resolvedSet.add(resolved);
+    return resolved;
+}