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

package/dist/shared/errors/errors.js

@@ -1,112 +1,239 @@
 "use strict";
+/**
+ * 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, and
+ * every AWS-classified code is wrapped once, by `wrapForeignError` in the
+ * error boundary, not per code here.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CompensationFailedError = exports.BatchWriteAllIncompleteError = exports.BatchWriteIncompleteError = exports.AbortError = exports.ResultTruncatedError = exports.RetryExhaustedError = exports.ConflictError = exports.ValidationError = void 0;
+exports.validationError = validationError;
+exports.conflictError = conflictError;
+exports.retryExhaustedError = retryExhaustedError;
+exports.resultTruncatedError = resultTruncatedError;
+exports.abortError = abortError;
+exports.batchWriteIncompleteError = batchWriteIncompleteError;
+exports.batchWriteAllIncompleteError = batchWriteAllIncompleteError;
+exports.compensationFailedError = compensationFailedError;
+const secret_patterns_1 = require("../logging/secret-patterns");
 const base_error_1 = require("./base-error");
 const error_code_1 = require("./error-code");
-/** Input failed a validation rule before any AWS call was made. */
-class ValidationError extends base_error_1.DynamoDbLangGraphError {
-    constructor(message, field) {
-        super(message, error_code_1.ErrorCode.VALIDATION, field === undefined ? {} : { operation: field });
-        this.name = 'ValidationError';
-    }
+/**
+ * Build one error, with the stack starting at the code that called `factory`
+ * rather than inside it: the top frame is the one a reader follows.
+ */
+function build(factory, spec) {
+    const error = new base_error_1.DynamoDBLangGraphError(spec.message, spec.code, spec.context, spec.cause, spec.details);
+    Error.captureStackTrace(error, factory);
+    return error;
 }
-exports.ValidationError = ValidationError;
-/** A conditional write failed because the precondition no longer holds. */
-class ConflictError extends base_error_1.DynamoDbLangGraphError {
-    constructor(message, cause) {
-        super(message, error_code_1.ErrorCode.CONDITION_CONFLICT, {}, cause);
-        this.name = 'ConflictError';
-    }
+/**
+ * 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.
+ */
+function validationError(message, field, cause) {
+    return build(validationError, {
+        message,
+        code: error_code_1.ErrorCode.VALIDATION,
+        context: field === undefined ? {} : { field },
+        cause,
+    });
 }
-exports.ConflictError = ConflictError;
-/** A retried operation exhausted its attempt budget. */
-class RetryExhaustedError extends base_error_1.DynamoDbLangGraphError {
-    constructor(message, attempts, cause) {
-        super(message, error_code_1.ErrorCode.RETRY_EXHAUSTED, attempts === undefined ? {} : { attempts }, cause);
-        this.name = 'RetryExhaustedError';
-    }
+/**
+ * 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.
+ */
+function conflictError(message, cause) {
+    return build(conflictError, { message, code: error_code_1.ErrorCode.CONDITION_CONFLICT, context: {}, cause });
+}
+/**
+ * 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.
+ *
+ * Returns: a `RETRY_EXHAUSTED` error, with `context.attempts` when `attempts`
+ * was given. 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.
+ */
+function retryExhaustedError(message, attempts, cause) {
+    return build(retryExhaustedError, {
+        message,
+        code: error_code_1.ErrorCode.RETRY_EXHAUSTED,
+        context: attempts === undefined ? {} : { attempts },
+        cause,
+    });
 }
-exports.RetryExhaustedError = RetryExhaustedError;
 /**
- * A paginated read 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.
+ * 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.
  */
-class ResultTruncatedError extends base_error_1.DynamoDbLangGraphError {
-    constructor(cap, limit) {
-        super(`paginated read truncated at the ${cap} cap (${limit}) with more data remaining`, error_code_1.ErrorCode.RESULT_TRUNCATED, { operation: cap });
-        this.name = 'ResultTruncatedError';
-    }
+function resultTruncatedError(cap, limit) {
+    return build(resultTruncatedError, {
+        message: `paginated read truncated at the ${cap} cap (${limit}) with more data remaining`,
+        code: error_code_1.ErrorCode.RESULT_TRUNCATED,
+        context: { field: cap },
+    });
 }
-exports.ResultTruncatedError = ResultTruncatedError;
-/** An operation was cancelled via its AbortSignal. */
-class AbortError extends base_error_1.DynamoDbLangGraphError {
-    constructor(message = 'Operation aborted') {
-        super(message, error_code_1.ErrorCode.ABORTED);
-        this.name = 'AbortError';
-    }
+/**
+ * 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.
+ */
+function abortError(message = 'Operation aborted', cause) {
+    return build(abortError, { message, code: error_code_1.ErrorCode.ABORTED, context: {}, cause });
 }
-exports.AbortError = AbortError;
 /**
- * A BatchWriteItem sequence could not drain its UnprocessedItems. Items NOT
- * listed in {@link unprocessed} were acked by DynamoDB and persist — there is
- * no rollback (drive reconciliation from `unprocessed`). `cause`, when given,
- * is the underlying failure that interrupted the drain (e.g. a thrown,
- * non-UnprocessedItems error from a retry round) rather than a clean exhaustion
- * of the UnprocessedItems retry budget.
+ * 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.
  */
-class BatchWriteIncompleteError extends base_error_1.DynamoDbLangGraphError {
-    succeededCount;
-    unprocessed;
-    constructor(succeededCount, unprocessed, retries, cause) {
-        super(`batchWrite did not drain after ${retries} UnprocessedItems retries: ` +
-            `${succeededCount} item(s) persisted, ${unprocessed.length} still un-acked.`, error_code_1.ErrorCode.BATCH_WRITE_INCOMPLETE, {}, cause);
-        this.name = 'BatchWriteIncompleteError';
-        this.succeededCount = succeededCount;
-        this.unprocessed = unprocessed;
-    }
+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_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause,
+        details: { kind: 'drain', succeededCount, unprocessed: items, retries },
+    });
 }
-exports.BatchWriteIncompleteError = BatchWriteIncompleteError;
 /**
- * batchWriteAll attempts every chunk rather than stopping at the first
- * failure — a mid-sequence chunk failing does not abandon the chunks after
- * it. `failedChunks` holds each failing chunk's own error (commonly a
- * {@link BatchWriteIncompleteError}); every chunk not represented there
- * drained successfully and its writes persist — there is no rollback.
- * `succeededCount` is the exact number of individual write requests
- * confirmed persisted across every chunk (full chunks plus any failed
- * chunk's own partial drain), more precise than `succeededChunks` alone
- * when a chunk partially drains before exhausting its retries.
+ * 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.
  */
-class BatchWriteAllIncompleteError extends base_error_1.DynamoDbLangGraphError {
-    succeededChunks;
-    totalChunks;
-    failedChunks;
-    succeededCount;
-    constructor(succeededChunks, totalChunks, failedChunks, succeededCount = 0) {
-        super(`batchWriteAll did not fully drain: ${succeededChunks}/${totalChunks} chunk(s) succeeded, ` +
-            `${failedChunks.length} chunk(s) failed. ${succeededCount} write(s) persisted before the failure.`, error_code_1.ErrorCode.BATCH_WRITE_INCOMPLETE, {}, failedChunks[0]);
-        this.name = 'BatchWriteAllIncompleteError';
-        this.succeededChunks = succeededChunks;
-        this.totalChunks = totalChunks;
-        this.failedChunks = failedChunks;
-        this.succeededCount = succeededCount;
-    }
+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_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause: failed[0],
+        details: {
+            kind: 'pass',
+            unit,
+            succeededChunks: succeeded,
+            totalChunks: total,
+            failedChunks: failed,
+            succeededCount,
+        },
+    });
 }
-exports.BatchWriteAllIncompleteError = BatchWriteAllIncompleteError;
 /**
- * A compensating rollback failed after an append-saga chunk error, so the
- * trigger error could not be cleanly undone. Carries the original trigger as
- * `cause` and the rollback failure as {@link rollbackError}; the session's
- * `messageCount` may have drifted — repair it with `reconcileMessageCount`.
+ * 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.
  */
-class CompensationFailedError extends base_error_1.DynamoDbLangGraphError {
-    rollbackError;
-    constructor(cause, rollbackError) {
-        super(`compensation failed after an append error: ${cause.message} (rollback: ${rollbackError.message})`, error_code_1.ErrorCode.COMPENSATION_FAILED, {}, cause);
-        this.name = 'CompensationFailedError';
-        this.rollbackError = rollbackError;
-    }
+function compensationFailedError(cause, rollbackError) {
+    const trigger = (0, base_error_1.toError)(cause);
+    const rollback = (0, base_error_1.toError)(rollbackError);
+    return build(compensationFailedError, {
+        message: `compensation failed after an append error: ${(0, secret_patterns_1.redactedMessage)(trigger)} ` +
+            `(rollback: ${(0, secret_patterns_1.redactedMessage)(rollback)})`,
+        code: error_code_1.ErrorCode.COMPENSATION_FAILED,
+        context: {},
+        cause: trigger,
+        details: { rollbackError: rollback },
+    });
 }
-exports.CompensationFailedError = CompensationFailedError;
-//# sourceMappingURL=errors.js.map

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

@@ -1,6 +1,25 @@
+/**
+ * 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. */
+/**
+ * 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;
@@ -9,6 +28,53 @@ export interface Logger {
 }
 /** Default logger: discards everything. Inject a real logger to enable output. */
 export declare const SILENT_LOGGER: Logger;
-/** Return the injected logger, or {@link SILENT_LOGGER} when none is given. */
+/**
+ * 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;
-//# sourceMappingURL=logger.d.ts.map

package/dist/shared/logging/logger.js

@@ -1,6 +1,16 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SILENT_LOGGER = void 0;
+exports.absorbLoggerFailure = absorbLoggerFailure;
 exports.resolveLogger = resolveLogger;
 /** Default logger: discards everything. Inject a real logger to enable output. */
 exports.SILENT_LOGGER = {
@@ -9,8 +19,92 @@ exports.SILENT_LOGGER = {
     error() { },
     debug() { },
 };
-/** Return the injected logger, or {@link SILENT_LOGGER} when none is given. */
+/**
+ * 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.
+ */
+function absorbLoggerFailure(emit) {
+    try {
+        emit();
+    }
+    catch {
+        // Nowhere left to say it: the reporting channel is the broken part.
+    }
+}
+/**
+ * `inner` with each level wrapped so a throw out of it stops at the log call.
+ *
+ * A `Logger` is an interface a consumer implements, so every log call this
+ * package makes runs foreign code, and almost every one of them is made from
+ * inside a `catch`: one that stringifies a circular object, whose transport
+ * has closed, or that asserts on a field it did not expect replaces the error
+ * the caller actually needs to see with its own. At the retry hook the damage
+ * is larger than a swap — `withRetry` calls `onRetry` synchronously and does
+ * not catch it, so a logger that throws ends an operation that was still
+ * succeeding, after its first transient failure.
+ *
+ * Wrapped once per adapter, here, rather than remembered at each of the three
+ * dozen call sites: a site that forgets is a site whose failure path reports
+ * the wrong error, and those sites are exactly the ones a test suite exercises
+ * least. `absorbLoggerFailure` stays for the places that promise,
+ * with no precondition on the logger they were handed, never to throw:
+ * `redactLogger`, which a caller may wrap any logger with, the S3 orphan
+ * cleanup, and the chat history's append compensation, whose announcement must
+ * not be able to stop the rollback it announces.
+ */
+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'),
+    };
+}
+/**
+ * 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.
+ */
 function resolveLogger(logger) {
-    return logger ?? exports.SILENT_LOGGER;
+    return logger === undefined ? exports.SILENT_LOGGER : containedLogger(logger);
 }
-//# sourceMappingURL=logger.js.map

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

@@ -1,5 +1,12 @@
-import type { Logger } from './logger';
-import { type Redactable } from './redaction-walk';
+/**
+ * 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';
 /**
  * Recursively clone `value`, replacing any value at a secret-looking key with
  * `[REDACTED]` and any recognised secret *shape* inside a string — including an
@@ -13,12 +20,35 @@ import { type Redactable } from './redaction-walk';
  * `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.
- * Does not mutate the input.
+ *
+ * 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.
+ *
+ * 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, 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: Redactable, patterns?: readonly string[], valuePatterns?: readonly RegExp[]): Redactable;
+export declare function redactSecrets(value: LogArgument | undefined, patterns?: readonly string[], valuePatterns?: readonly RegExp[]): Redactable;
 /** Options controlling {@link redactLogger}. */
 export interface RedactLoggerOptions {
-    /** Additional key names (matched case-insensitively as substrings) to redact. */
+    /**
+     * 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.
@@ -28,8 +58,62 @@ export interface RedactLoggerOptions {
     extraValuePatterns?: readonly RegExp[];
 }
 /**
- * Wrap a logger so object args are redacted before delegation. The message
- * string is passed through unchanged (never interpolate secrets into it).
+ * 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;
-//# sourceMappingURL=redaction.d.ts.map
+/** 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 {};