@farukada/aws-langgraph-dynamodb-ts 1.0.0-rc.1 → 1.0.0

package/dist/cjs/shared/errors/errors.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Hides what each of this library's errors carries, for the codes that have
+ * a factory here.
+ *
+ * A failure site with a factory below names it for its code and the facts it
+ * has. The message wording, which facts go into `context` or `details`,
+ * copying a list a caller reads from a `catch` long after the throw,
+ * redacting quoted cause text, and a stack that starts at the caller rather
+ * than inside the factory are decided here once per code, on the one error
+ * class (record 19). `FORMAT_UNSUPPORTED`, `PAYLOAD_CORRUPT`,
+ * `COMPRESSION_LIMIT`, `S3_OFFLOAD_FAILED` and `ANCESTOR_EXPIRED` are raised
+ * with `new DynamoDBLangGraphError` at their own call sites instead; so is
+ * `CONTENTION` when `ensureLifecycleRule` gives up on a lifecycle write that
+ * never stays, which is this package's own verdict rather than an AWS
+ * rejection. Every other occurrence of an AWS-classified code, `CONTENTION`
+ * included, is wrapped once, by `wrapForeignError` in the error boundary, not
+ * per code here.
+ */
+import type { WriteRequest } from '../dynamodb/client.js';
+import { DynamoDBLangGraphError } from './base-error.js';
+import { ErrorCode } from './error-code.js';
+/**
+ * The error for input that failed a check before any AWS call was made.
+ *
+ * Accepts: `message` — already redacted by whoever composed it. `field` — the
+ * option, argument or cap that failed, dotted for a nested one
+ * (`s3.bucketName`); omitted only where no single input is at fault. `cause` —
+ * the refusal beneath it.
+ *
+ * Returns: a `VALIDATION` error, with `context.field` set when a field was
+ * named — which is what a caller branches on to point at the offending input.
+ *
+ * Throws: nothing; building an error may not fail.
+ */
+export declare function validationError(message: string, field?: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.VALIDATION>;
+/**
+ * The error for a conditional write whose precondition no longer holds.
+ *
+ * Accepts: `message` — what precondition no longer held. `cause` — the
+ * rejection beneath it, when there is one.
+ *
+ * Returns: a `CONDITION_CONFLICT` error. A caller may retry the operation
+ * from a fresh read; nothing was written.
+ *
+ * Throws: nothing; building an error may not fail.
+ */
+export declare function conflictError(message: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.CONDITION_CONFLICT>;
+/**
+ * Record on `error` that an attempt of the budget it ended may still land.
+ *
+ * Accepts: `error` — the failure a retry budget is about to throw as it is: a
+ * refusal that is not retried, so it is thrown bare rather than wrapped in
+ * `RETRY_EXHAUSTED`, after an earlier attempt of the same budget got no
+ * answer. Credentials expiring mid-budget are the ordinary way there.
+ *
+ * Returns: `error`, carrying the record for {@link retryBudgetMayStillLand}.
+ * An error that cannot take a property — frozen, or not an object — is
+ * returned as it is, and then reads as answered, which is how every error
+ * read before this record existed.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function markMayStillLand<E extends Error>(error: E): E;
+/**
+ * The error for a retried operation that exhausted its attempt budget.
+ *
+ * Accepts: `attempts` — how many were made before the budget ran out.
+ * `cause` — the last failure, kept so a caller can classify what actually
+ * went wrong. `mayStillLand` — whether any attempt of the budget, not only the
+ * last, left DynamoDB free to apply it later; read back by
+ * {@link retryBudgetMayStillLand}. Defaults to false, which is what a caller
+ * outside `withRetry` — one built by an older release, or a test double — gets
+ * for not recording one.
+ *
+ * Returns: a `RETRY_EXHAUSTED` error, with `context.attempts` when `attempts`
+ * was given, and the `awsErrorName`, `httpStatusCode` and `requestId` of the
+ * last failure when that failure was AWS's, so a count by status needs no walk
+ * of `cause`. It says the attempts are spent, **not** that the operation did
+ * not happen: a write whose response was lost is reported this way too, which
+ * is why every caller that would delete something reads the row back first.
+ *
+ * Throws: nothing; building an error may not fail.
+ */
+export declare function retryExhaustedError(message: string, attempts?: number, cause?: Error, mayStillLand?: boolean): DynamoDBLangGraphError<ErrorCode.RETRY_EXHAUSTED>;
+/**
+ * Whether some attempt of the retry budget this error ended — recorded across
+ * every attempt `withRetry` made, not re-derived from the error, which is only
+ * the last one — left DynamoDB free to apply it later.
+ *
+ * Accepts: `error` — any error; one {@link retryExhaustedError} built, or one
+ * {@link markMayStillLand} marked, carries the record.
+ *
+ * Returns: the flag recorded on the error; false for any other error,
+ * including a `RETRY_EXHAUSTED` error built without passing one.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function retryBudgetMayStillLand(error: Error): boolean;
+/**
+ * The error for a paginated read that hit its runaway guard (item or
+ * iteration cap) while more data remained, so the result would have been
+ * silently truncated. Narrow the query (filter/prefix) or raise the cap rather
+ * than trusting a partial result.
+ *
+ * Accepts: `cap` — which cap was hit (`maxItems`, `maxIterations`). `limit` —
+ * its value, quoted in the message so the fix is obvious.
+ *
+ * Returns: a `RESULT_TRUNCATED` error, with `context.field` naming the cap.
+ * Raised only when data actually remained, so it never turns a complete
+ * result into a failure.
+ *
+ * Throws: nothing; building an error may not fail.
+ */
+export declare function resultTruncatedError(cap: string, limit: number): DynamoDBLangGraphError<ErrorCode.RESULT_TRUNCATED>;
+/**
+ * The error for an operation cancelled via its `AbortSignal`.
+ *
+ * Accepts: `message` — defaults to `Operation aborted`. `cause` — the
+ * `AbortSignal`'s own reason, when it carried one.
+ *
+ * Returns: an `ABORTED` error. Distinct from every failure code on purpose: a
+ * caller who cancelled did not encounter a fault, and treating the two alike
+ * reported an incomplete write for a deliberate stop.
+ *
+ * Throws: nothing; building an error may not fail.
+ */
+export declare function abortError(message?: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.ABORTED>;
+/**
+ * The error for a `BatchWriteItem` sequence that could not drain its
+ * `UnprocessedItems`.
+ *
+ * Accepts: `succeededCount` — writes DynamoDB acked. `unprocessed` — the
+ * requests it did not, verbatim, so they can be re-submitted. `retries` —
+ * rounds spent. `cause` — an error that interrupted the drain (a thrown,
+ * non-`UnprocessedItems` error from a retry round), rather than a clean
+ * exhaustion of the `UnprocessedItems` retry budget.
+ *
+ * Returns: a `BATCH_WRITE_INCOMPLETE` error whose `details` (`kind: 'drain'`)
+ * carry both counts and the list. Items *not* listed in `details.unprocessed`
+ * persist: there is no rollback, so reconciliation is driven from that list.
+ * That list is **copied**: it is read from a `catch` long after the throw, and
+ * a caller reusing its request buffer must not be able to rewrite it.
+ *
+ * Throws: nothing; building an error may not fail. Anything but an array of
+ * requests reads as an empty list rather than crashing the report.
+ */
+export declare function batchWriteIncompleteError(succeededCount: number, unprocessed: WriteRequest[], retries: number, cause?: Error): DynamoDBLangGraphError<ErrorCode.BATCH_WRITE_INCOMPLETE>;
+/** What a batch that could not finish reports. */
+export interface IncompleteBatch {
+    /** Chunks (or rows) that committed. */
+    readonly succeeded: number;
+    /** Chunks (or rows) the batch had. */
+    readonly total: number;
+    readonly failures: Error[];
+    /** Requests that committed, when a chunk is more than one request. */
+    readonly succeededCount?: number;
+    readonly unit?: 'row';
+}
+/**
+ * The error for a `batchWriteAll` pass — or a partition-wide delete — that did
+ * not fully drain. `batchWriteAll` attempts every chunk rather than stopping
+ * at the first failure, so a mid-sequence chunk failing does not abandon the
+ * chunks after it. A partition-wide delete reports through the same shape,
+ * because what it answers is the same question — how much of this call got
+ * through — but it sends one conditional request per row rather than a batch
+ * of twenty-five, so it counts rows where a batch counts chunks and says so in
+ * its message.
+ *
+ * Accepts: `batch.succeeded`/`batch.total` — the chunk tally. `batch.failures`
+ * — each failing chunk's own error, commonly a `BATCH_WRITE_INCOMPLETE` drain
+ * error. `batch.succeededCount` — individual writes confirmed persisted across
+ * every chunk (full chunks plus any failed chunk's own partial drain), which
+ * is more precise than the chunk tally when a chunk partially drains.
+ * `batch.unit` — what the first two counts count; omitting it reproduces the
+ * batch wording exactly.
+ *
+ * Returns: a `BATCH_WRITE_INCOMPLETE` error whose `details` (`kind: 'pass'`)
+ * carry the tally, with the first failing chunk's error as `cause`. Every
+ * chunk not represented in `details.failedChunks` drained successfully and its
+ * writes persist — there is no rollback. The list is **copied**, for the same
+ * reason a drain error copies its own.
+ *
+ * Throws: nothing; building an error may not fail. Anything but an array of
+ * errors reads as an empty list rather than crashing the report.
+ */
+export declare function batchWriteAllIncompleteError(batch: IncompleteBatch): DynamoDBLangGraphError<ErrorCode.BATCH_WRITE_INCOMPLETE>;
+/**
+ * The error for a compensating rollback that failed after an append-saga
+ * chunk error, so the trigger could not be cleanly undone.
+ *
+ * Accepts: `cause` — the failure that triggered the rollback. `rollbackError`
+ * — why the rollback itself could not finish. Both are built from a `catch`,
+ * so either may be whatever a `throw` produced rather than an `Error`.
+ *
+ * Returns: a `COMPENSATION_FAILED` error carrying the trigger as `cause` and
+ * the rollback failure as `details.rollbackError`, each normalised through
+ * `toError` so both are always error-shaped. The session's `messageCount` may
+ * have drifted, which `reconcileMessageCount` repairs; the quoted text of both
+ * errors is redacted before it is embedded.
+ *
+ * Throws: nothing; building an error may not fail. Reading `.message` off a
+ * thrown `null` or `undefined` would throw here, inside the `catch` reporting
+ * the rollback — which is why `toError` normalises both `cause` and
+ * `rollbackError` before anything reads off them.
+ */
+export declare function compensationFailedError(cause: Error, rollbackError: Error): DynamoDBLangGraphError<ErrorCode.COMPENSATION_FAILED>;
+/**
+ * The error for an append-saga chunk whose own outcome could not be
+ * established, raised once every chunk this call *could* confirm has already
+ * been undone — the rollback itself did not fail; this chunk alone could not
+ * be read back, or its write may still be applied after the read.
+ *
+ * Accepts: `cause` — the failing chunk's own failure. `unsettledBecause` —
+ * why its outcome is unknown: the read-back's own failure, or the write's
+ * own failure, when some attempt of it may still be applied. Both are built
+ * from a `catch`, so either may be whatever a `throw` produced rather than
+ * an `Error`.
+ *
+ * Returns: a `COMPENSATION_FAILED` error carrying `cause` as `cause` and
+ * `unsettledBecause` as `details.rollbackError`, each normalised through
+ * `toError` so both are always error-shaped. Its message says the chunk's
+ * own fate could not be established — never that a rollback failed, since
+ * every chunk this call could confirm was already rolled back before this is
+ * raised. The session's `messageCount` may have drifted, which
+ * `reconcileMessageCount` repairs; the quoted text of both errors is
+ * redacted before it is embedded.
+ *
+ * Throws: nothing; building an error may not fail. Reading `.message` off a
+ * thrown `null` or `undefined` would throw here, which is why `toError`
+ * normalises both `cause` and `unsettledBecause` before anything reads off
+ * them.
+ */
+export declare function unsettledAppendError(cause: Error, unsettledBecause: Error): DynamoDBLangGraphError<ErrorCode.COMPENSATION_FAILED>;

package/dist/cjs/shared/errors/errors.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validationError = validationError;
+exports.conflictError = conflictError;
+exports.markMayStillLand = markMayStillLand;
+exports.retryExhaustedError = retryExhaustedError;
+exports.retryBudgetMayStillLand = retryBudgetMayStillLand;
+exports.resultTruncatedError = resultTruncatedError;
+exports.abortError = abortError;
+exports.batchWriteIncompleteError = batchWriteIncompleteError;
+exports.batchWriteAllIncompleteError = batchWriteAllIncompleteError;
+exports.compensationFailedError = compensationFailedError;
+exports.unsettledAppendError = unsettledAppendError;
+const secret_patterns_js_1 = require("../logging/secret-patterns.js");
+const base_error_js_1 = require("./base-error.js");
+const classify_js_1 = require("./classify.js");
+const error_code_js_1 = require("./error-code.js");
+function build(factory, spec) {
+    const error = new base_error_js_1.DynamoDBLangGraphError(spec.message, spec.code, spec.context, spec.cause, spec.details);
+    Error.captureStackTrace(error, factory);
+    return error;
+}
+function validationError(message, field, cause) {
+    return build(validationError, {
+        message,
+        code: error_code_js_1.ErrorCode.VALIDATION,
+        context: field === undefined ? {} : { field },
+        cause,
+    });
+}
+function conflictError(message, cause) {
+    return build(conflictError, { message, code: error_code_js_1.ErrorCode.CONDITION_CONFLICT, context: {}, cause });
+}
+const MAY_STILL_LAND = Symbol('retryBudget.mayStillLand');
+function markMayStillLand(error) {
+    if (typeof error === 'object' && error !== null && Object.isExtensible(error)) {
+        Object.defineProperty(error, MAY_STILL_LAND, { value: true, enumerable: false });
+    }
+    return error;
+}
+function retryExhaustedError(message, attempts, cause, mayStillLand = false) {
+    const error = build(retryExhaustedError, {
+        message,
+        code: error_code_js_1.ErrorCode.RETRY_EXHAUSTED,
+        context: {
+            ...(attempts === undefined ? {} : { attempts }),
+            ...(cause === undefined ? {} : (0, classify_js_1.awsDiagnostics)(cause)),
+        },
+        cause,
+    });
+    Object.defineProperty(error, MAY_STILL_LAND, { value: mayStillLand, enumerable: false });
+    return error;
+}
+function retryBudgetMayStillLand(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    return error[MAY_STILL_LAND] === true;
+}
+function resultTruncatedError(cap, limit) {
+    return build(resultTruncatedError, {
+        message: `paginated read truncated at the ${cap} cap (${limit}) with more data remaining`,
+        code: error_code_js_1.ErrorCode.RESULT_TRUNCATED,
+        context: { field: cap },
+    });
+}
+function abortError(message = 'Operation aborted', cause) {
+    return build(abortError, { message, code: error_code_js_1.ErrorCode.ABORTED, context: {}, cause });
+}
+function batchWriteIncompleteError(succeededCount, unprocessed, retries, cause) {
+    const items = Array.isArray(unprocessed) ? [...unprocessed] : [];
+    return build(batchWriteIncompleteError, {
+        message: `batchWrite did not drain after ${retries} UnprocessedItems retries: ` +
+            `${succeededCount} item(s) persisted, ${items.length} still un-acked.`,
+        code: error_code_js_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause,
+        details: { kind: 'drain', succeededCount, unprocessed: items, retries },
+    });
+}
+function batchWriteAllIncompleteError(batch) {
+    const { succeeded, total, succeededCount = 0, unit = 'chunk' } = batch;
+    const failed = Array.isArray(batch.failures) ? [...batch.failures] : [];
+    return build(batchWriteAllIncompleteError, {
+        message: `${unit === 'chunk' ? 'batchWriteAll' : 'the partition delete'} did not fully drain: ` +
+            `${succeeded}/${total} ${unit}(s) succeeded, ` +
+            `${failed.length} ${unit}(s) failed. ${succeededCount} write(s) persisted before the failure.`,
+        code: error_code_js_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause: failed[0],
+        details: {
+            kind: 'pass',
+            unit,
+            succeededChunks: succeeded,
+            totalChunks: total,
+            failedChunks: failed,
+            succeededCount,
+        },
+    });
+}
+function compensationFailedError(cause, rollbackError) {
+    const trigger = (0, base_error_js_1.toError)(cause);
+    const rollback = (0, base_error_js_1.toError)(rollbackError);
+    return build(compensationFailedError, {
+        message: `compensation failed after an append error: ${(0, secret_patterns_js_1.redactedMessage)(trigger)} ` +
+            `(rollback: ${(0, secret_patterns_js_1.redactedMessage)(rollback)})`,
+        code: error_code_js_1.ErrorCode.COMPENSATION_FAILED,
+        context: {},
+        cause: trigger,
+        details: { rollbackError: rollback },
+    });
+}
+function unsettledAppendError(cause, unsettledBecause) {
+    const trigger = (0, base_error_js_1.toError)(cause);
+    const unsettled = (0, base_error_js_1.toError)(unsettledBecause);
+    return build(unsettledAppendError, {
+        message: `an append chunk could not be settled after ${(0, secret_patterns_js_1.redactedMessage)(trigger)} ` +
+            `(unsettled because: ${(0, secret_patterns_js_1.redactedMessage)(unsettled)})`,
+        code: error_code_js_1.ErrorCode.COMPENSATION_FAILED,
+        context: {},
+        cause: trigger,
+        details: { rollbackError: unsettled },
+    });
+}

package/dist/cjs/shared/logging/logger.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Hides that a caller's logger is foreign code that may throw.
+ *
+ * A caller supplies no logger or one of their own, and internal code receives
+ * a logger that is silent by default and whose four levels never throw. No
+ * `catch` block or retry hook therefore treats a log call as a failure path
+ * of its own, and where a throw is absorbed, and what becomes of the line it
+ * was writing, can change here without touching any call site.
+ */
+/** A value safe to pass as a structured log argument. */
+export type LogArgument = string | number | boolean | null | object;
+/**
+ * Pluggable logging interface — consumers supply their own implementation.
+ * `args` are structured fields, at most one plain object per call, so an
+ * adapter for a structured logger (pino, winston) can merge them into one
+ * record; the message is a fixed string and never carries a value.
+ *
+ * It is the one piece of foreign code every adapter of this package calls,
+ * almost always from a `catch` block, so an adapter wraps it: anything one of
+ * its methods throws is absorbed at the log call and never replaces the error
+ * being reported.
+ */
+export interface Logger {
+    info(message: string, ...args: LogArgument[]): void;
+    warn(message: string, ...args: LogArgument[]): void;
+    error(message: string, ...args: LogArgument[]): void;
+    debug(message: string, ...args: LogArgument[]): void;
+}
+/** Default logger: discards everything. Inject a real logger to enable output. */
+export declare const SILENT_LOGGER: Logger;
+/**
+ * Run one log call so that a failure of the caller's own logger cannot become
+ * the caller's problem.
+ *
+ * Shared rather than private to the file that first needed it: a `Logger` is
+ * an interface a consumer implements, so a log call is foreign code wherever
+ * it appears, and a guard each site has to remember is a guard most sites will
+ * not have.
+ *
+ * Swallowed rather than reported onward, because the only channel a report
+ * could use is the logger that just broke, and the alternative — writing to
+ * the host's console uninvited — is what {@link SILENT_LOGGER} exists to
+ * refuse. What the line was going to say is an observation about work that has
+ * either succeeded or is already failing for a reason of its own; the error it
+ * protects is the one that says what that reason was.
+ *
+ * Accepts: `emit` — the whole log call as a thunk, so the arguments are built
+ * inside the guard too: a formatter that throws while composing the line is
+ * the same failure as a transport that throws while writing it.
+ *
+ * Returns: nothing, and the same nothing whether the line was written or lost.
+ *
+ * Throws: **nothing**, ever. That is the entire job. The caller's next
+ * statement runs, so a path that says what it is about to do and then does it
+ * cannot be stopped between the two by the saying.
+ */
+export declare function absorbLoggerFailure(emit: () => void): void;
+/**
+ * Resolve an optional logger to a concrete one.
+ *
+ * Accepts: `logger` — the caller's, or nothing. Its members were validated
+ * where the options were.
+ *
+ * Returns: {@link SILENT_LOGGER} when nothing was given — silent rather than
+ * console by default: a library writing to a host's stdout uninvited is a
+ * nuisance, and every event it would have written is documented so an operator
+ * can opt in. Otherwise a **wrapper** around the caller's logger, not the
+ * object itself: the same four levels, delegating each call with its message
+ * and arguments unchanged, and absorbing anything the caller's method throws
+ * (see `absorbLoggerFailure`). Identity is therefore not preserved, and
+ * a caller comparing what it passed in against what an adapter holds would
+ * find two different objects; nothing observable about a log line changes.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: every logger this package hands to its own internals has methods
+ * that cannot throw, so no `catch` block, and no retry hook, has to treat a log
+ * call as a failure path of its own.
+ */
+export declare function resolveLogger(logger?: Logger): Logger;

package/dist/cjs/shared/logging/logger.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SILENT_LOGGER = void 0;
+exports.absorbLoggerFailure = absorbLoggerFailure;
+exports.resolveLogger = resolveLogger;
+exports.SILENT_LOGGER = {
+    info() { },
+    warn() { },
+    error() { },
+    debug() { },
+};
+function absorbLoggerFailure(emit) {
+    try {
+        emit();
+    }
+    catch {
+    }
+}
+function containedLogger(inner) {
+    const deliver = (level) => (message, ...args) => absorbLoggerFailure(() => inner[level](message, ...args));
+    return {
+        info: deliver('info'),
+        warn: deliver('warn'),
+        error: deliver('error'),
+        debug: deliver('debug'),
+    };
+}
+function resolveLogger(logger) {
+    return logger === undefined ? exports.SILENT_LOGGER : containedLogger(logger);
+}

package/dist/cjs/shared/logging/redaction.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Hides how a logger and a value are redacted.
+ *
+ * A redacting logger walks every argument of every line, bounded in depth and
+ * safe against cycles and hostile getters, and replaces the value of any key
+ * that looks like a secret and any text that looks like one; the same walk
+ * serves `redactSecrets` for a value a caller wants to log themselves.
+ */
+import { type LogArgument, type Logger } from './logger.js';
+/**
+ * Recursively clone `value`, replacing any value at a secret-looking key with
+ * `[REDACTED]` and any recognised secret *shape* inside a string — including an
+ * error's `message`/`stack` text, which key-name matching cannot reach — with
+ * the same marker. Cycles become `[Circular]`.
+ *
+ * An Error with no own enumerable properties whose text holds no secret is
+ * passed through by reference, so its identity and stack trace survive; one
+ * carrying own data (this library's error types all attach `code`/`context`
+ * this way) or a secret in its text is rebuilt instead, with `name`/`message`/
+ * `stack` redacted and every other own property recursed like a plain object.
+ * `Date`/`RegExp` keep their identity rather than collapsing to `{}`,
+ * `Set`/`Map` render as their contents, and binary views become a short label.
+ *
+ * Accepts: `value` — any log argument, including `undefined`, a primitive, a
+ * typed `Error`, a class instance or a `Record`, so callers never cast. A
+ * cyclic or shared graph is fine; each node is walked once. `patterns` and
+ * `valuePatterns` — the key names and value shapes to redact, an array of
+ * strings and an array of `RegExp` respectively; both default to this
+ * package's own lists, and an empty one turns that rule off. A key name is
+ * matched by its normalised form — lower-case, punctuation removed — against
+ * the end of each key's, so `'apiKey'` covers `x-api-key` and `API_KEY`.
+ *
+ * Returns: a redacted clone. The input is never mutated — a logger that
+ * scrubbed the caller's own object would corrupt the very data the application
+ * is working with.
+ *
+ * Throws: `VALIDATION` naming `patterns` or `valuePatterns` for a list this
+ * function could not apply — a non-array, a wrong entry, or a key name with
+ * no letter or digit in it, which would match every key — which is a mistake
+ * in the call itself and is raised before anything is walked. Nothing after
+ * that: a value whose
+ * redaction fails — a throwing getter, a structure deep enough to exhaust the
+ * stack — is replaced whole by `[UNREDACTABLE]`, since a logger that throws
+ * takes down the operation it was only observing. {@link redactLogger}
+ * redacts one argument per call, so there a single hostile argument is what is
+ * lost rather than the record around it.
+ */
+export declare function redactSecrets(value: LogArgument | undefined, patterns?: readonly string[], valuePatterns?: readonly RegExp[]): Redactable;
+/** Options controlling {@link redactLogger}. */
+export interface RedactLoggerOptions {
+    /**
+     * Additional key names to redact. Matched like the defaults: a key is
+     * redacted when its normalised form (lower-case, punctuation removed) equals
+     * or ends with the normalised name, so `'ssn'` covers `SSN` and `user_ssn`.
+     */
+    extraKeys?: readonly string[];
+    /**
+     * Additional secret shapes to redact wherever they appear inside a string.
+     * A pattern's first capture group, if it has one, is preserved verbatim and
+     * only the remainder of the match is replaced.
+     */
+    extraValuePatterns?: readonly RegExp[];
+}
+/**
+ * Wrap a logger so object args are redacted before delegation.
+ *
+ * Accepts: `inner` — the logger to delegate to; it must carry all four
+ * methods, because a missing one is a wiring mistake worth naming here rather
+ * than at the first log line. `options.extraKeys` — further key names to
+ * redact, matched like the defaults. `options.extraValuePatterns` — further
+ * secret shapes; each must be a `RegExp`, and it is applied globally whether or
+ * not it carries the `g` flag.
+ *
+ * Returns: a logger with the same four methods.
+ *
+ * Throws: `VALIDATION` naming `logger` or `logger.<method>` for a logger it
+ * could not delegate to, and `options`, `extraKeys` or `extraValuePatterns`
+ * for an option of the wrong type. Nothing at log time.
+ *
+ * Guarantees: the message string is passed through unchanged — never
+ * interpolate a secret into it — and every other argument is redacted before
+ * it reaches `inner`. Past the wrap call nothing escapes a log call: an
+ * argument whose redaction fails is replaced by a fixed marker, and a failure
+ * of `inner` itself is absorbed, because the
+ * operation that wrote the line was only observing itself and is commonly
+ * reporting some other failure already.
+ */
+export declare function redactLogger(inner: Logger, options?: RedactLoggerOptions): Logger;
+/** A value that {@link redactSecrets} can recurse through. */
+export type Redactable = string | number | boolean | null | undefined | Redactable[] | {
+    [key: string]: Redactable;
+};
+/** Any `Redactable` that is a non-null object — what the walk dispatches on. */
+export type RedactableObject = Redactable[] | {
+    [key: string]: Redactable;
+};
+/** One step of the recursive walk, threaded into the entry helpers. */
+type Walk = (value: Redactable) => Redactable;
+/** Collaborators threaded through the recursive walk. */
+export interface WalkDeps {
+    keyPatterns: readonly string[];
+    valuePatterns: readonly RegExp[];
+    walk: Walk;
+}
+/**
+ * Dispatch one non-null object by its shape.
+ *
+ * Accepts: `current` — any object. `deps.walk` — how to recurse, which carries
+ * the cycle and memo state this module deliberately does not own.
+ *
+ * Returns: the redacted form — arrays and plain objects recursed, binary views
+ * collapsed to a label, `Date`/`RegExp` passed through by reference so they do
+ * not become `{}`, `Set`/`Map` rendered as their contents, and an Error through
+ * the error path, which preserves the non-enumerable text a plain walk cannot
+ * see.
+ *
+ * Throws: whatever a property getter on the value throws. `redactSecrets`, the
+ * only caller, catches it and returns `[UNREDACTABLE]` in place of the whole
+ * value it was given, rather than raising a getter's error at a caller who
+ * asked only for a copy it could log.
+ */
+export declare function walkObject(current: RedactableObject, deps: WalkDeps): Redactable;
+export {};