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

package/dist/esm/shared/logging/redaction.js

@@ -0,0 +1,140 @@
+import { validationError } from '../errors/errors.js';
+import { assertMembers, LOGGER_MEMBERS } from '../validation/collaborators.js';
+import { assertObjectShape } from '../validation/option-shape.js';
+import { assertStringArray } from '../validation/primitives.js';
+import { absorbLoggerFailure } from './logger.js';
+import { binaryLabel, DEFAULT_SECRET_KEY_PATTERNS, DEFAULT_SECRET_VALUE_PATTERNS, isRegExp, isSecretKey, normaliseKey, REDACTED, redactErrorText, redactText, } from './secret-patterns.js';
+const UNREDACTABLE = '[UNREDACTABLE]';
+function assertRegExpArray(value, field) {
+    if (!Array.isArray(value) || value.some((entry) => !isRegExp(entry))) {
+        throw validationError(`${field} must be an array of RegExp`, field);
+    }
+}
+function assertKeyPatterns(value, field) {
+    assertStringArray(value, field);
+    if (value.some((entry) => normaliseKey(entry) === '')) {
+        throw validationError(`${field} must name a letter or digit in every entry`, field);
+    }
+}
+export function redactSecrets(value, patterns = DEFAULT_SECRET_KEY_PATTERNS, valuePatterns = DEFAULT_SECRET_VALUE_PATTERNS) {
+    assertKeyPatterns(patterns, 'patterns');
+    assertRegExpArray(valuePatterns, 'valuePatterns');
+    const keyPatterns = patterns.map(normaliseKey);
+    const walking = new WeakSet();
+    const done = new WeakMap();
+    const walk = (current) => {
+        if (typeof current === 'string')
+            return redactText(current, valuePatterns);
+        if (current === null || typeof current !== 'object')
+            return current;
+        if (done.has(current))
+            return done.get(current);
+        if (walking.has(current))
+            return '[Circular]';
+        walking.add(current);
+        try {
+            const redacted = walkObject(current, { keyPatterns, valuePatterns, walk });
+            done.set(current, redacted);
+            return redacted;
+        }
+        finally {
+            walking.delete(current);
+        }
+    };
+    try {
+        return walk(value);
+    }
+    catch {
+        return UNREDACTABLE;
+    }
+}
+function assertRedactionOptions(options) {
+    assertObjectShape(options, 'options');
+    if (options.extraKeys !== undefined)
+        assertKeyPatterns(options.extraKeys, 'extraKeys');
+    if (options.extraValuePatterns !== undefined) {
+        assertRegExpArray(options.extraValuePatterns, 'extraValuePatterns');
+    }
+}
+export function redactLogger(inner, options = {}) {
+    assertMembers(inner, LOGGER_MEMBERS, 'logger');
+    assertRedactionOptions(options);
+    const patterns = options.extraKeys
+        ? [...DEFAULT_SECRET_KEY_PATTERNS, ...options.extraKeys.map(normaliseKey)]
+        : DEFAULT_SECRET_KEY_PATTERNS;
+    const valuePatterns = options.extraValuePatterns
+        ? [...DEFAULT_SECRET_VALUE_PATTERNS, ...options.extraValuePatterns]
+        : DEFAULT_SECRET_VALUE_PATTERNS;
+    const deliver = (method) => (message, ...args) => absorbLoggerFailure(() => inner[method](message, ...args.map((arg) => redactSecrets(arg, patterns, valuePatterns))));
+    return {
+        info: deliver('info'),
+        warn: deliver('warn'),
+        error: deliver('error'),
+        debug: deliver('debug'),
+    };
+}
+function isSetValue(value) {
+    return Object.prototype.toString.call(value) === '[object Set]';
+}
+function isMapValue(value) {
+    return Object.prototype.toString.call(value) === '[object Map]';
+}
+function isErrorValue(value) {
+    const tag = Object.prototype.toString.call(value);
+    return tag === '[object Error]' || tag === '[object DOMException]';
+}
+function isOpaqueValue(value) {
+    const tag = Object.prototype.toString.call(value);
+    return tag === '[object Date]' || tag === '[object RegExp]';
+}
+function redactEntries(entries, keyPatterns, walk) {
+    const out = {};
+    for (const [key, value] of entries) {
+        Object.defineProperty(out, key, {
+            value: isSecretKey(key, keyPatterns) ? REDACTED : walk(value),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return out;
+}
+function redactMap(value, deps) {
+    const entries = [...value].map(([key, entry]) => {
+        const keyText = key;
+        return [String(keyText), entry];
+    });
+    return redactEntries(entries, deps.keyPatterns, deps.walk);
+}
+function redactError(current, entries, deps) {
+    const text = redactErrorText(current, deps.valuePatterns);
+    const aggregated = current.errors;
+    const bare = entries.length === 0 && current.cause === undefined && aggregated === undefined;
+    if (bare && !text.changed)
+        return current;
+    const out = redactEntries(entries, deps.keyPatterns, deps.walk);
+    out.name = text.name;
+    out.message = text.message;
+    out.stack = text.stack;
+    if (current.cause !== undefined)
+        out.cause = deps.walk(current.cause);
+    if (Array.isArray(aggregated))
+        out.errors = deps.walk(aggregated);
+    return out;
+}
+export function walkObject(current, deps) {
+    if (Array.isArray(current))
+        return current.map(deps.walk);
+    if (ArrayBuffer.isView(current))
+        return binaryLabel(current);
+    if (isOpaqueValue(current))
+        return current;
+    if (isSetValue(current))
+        return [...current].map(deps.walk);
+    if (isMapValue(current))
+        return redactMap(current, deps);
+    const entries = Object.entries(current);
+    if (isErrorValue(current))
+        return redactError(current, entries, deps);
+    return redactEntries(entries, deps.keyPatterns, deps.walk);
+}

package/dist/{shared/logging/secret-patterns.js → esm/shared/logging/secret-patterns.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides what a secret looks like.
  *
@@ -8,19 +7,8 @@
  * quotes it are decided here. The redacting logger and every error that
  * quotes its cause share these rules, so a new credential shape is one edit.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SECRET_VALUE_PATTERNS = exports.DEFAULT_SECRET_KEY_PATTERNS = exports.REDACTED = void 0;
-exports.normaliseKey = normaliseKey;
-exports.isSecretKey = isSecretKey;
-exports.redactedMessage = redactedMessage;
-exports.isRegExp = isRegExp;
-exports.redactText = redactText;
-exports.binaryLabel = binaryLabel;
-exports.redactErrorText = redactErrorText;
-const base_error_1 = require("../errors/base-error");
-const truncate_1 = require("./truncate");
 /** Marker substituted for anything recognised as secret. */
-exports.REDACTED = '[REDACTED]';
+export declare const REDACTED = "[REDACTED]";
 /**
  * Key names whose value is a secret. Each entry is a *normalised* name — see
  * {@link normaliseKey} — and matches a key whose normalised form equals it or
@@ -30,21 +18,7 @@ exports.REDACTED = '[REDACTED]';
  * `secretary` — a bare substring match would redact all four for merely
  * containing `token` or `secret`.
  */
-exports.DEFAULT_SECRET_KEY_PATTERNS = [
-    'accesskey',
-    'accesskeyid',
-    'secret',
-    'sessiontoken',
-    'securitytoken',
-    'authorization',
-    'password',
-    'passwd',
-    'passphrase',
-    'apikey',
-    'bearer',
-    'token',
-    'privatekey',
-];
+export declare const DEFAULT_SECRET_KEY_PATTERNS: readonly string[];
 /**
  * Canonical form of a key name for matching.
  *
@@ -56,9 +30,7 @@ exports.DEFAULT_SECRET_KEY_PATTERNS = [
  *
  * Throws: nothing.
  */
-function normaliseKey(key) {
-    return key.toLowerCase().replace(/[^a-z0-9]/g, '');
-}
+export declare function normaliseKey(key: string): string;
 /**
  * Secret shapes recognisable in free text, where key-name matching cannot
  * reach: an error's `message`/`stack`, or any other string value. Deliberately
@@ -68,15 +40,23 @@ function normaliseKey(key) {
  *
  * The credential-pair pattern (last) tolerates a **closing quote after the
  * keyword**, because that is what `JSON.stringify` produces
- * (`{"password":"…"}`) and requiring the separator to follow the bare keyword
- * matched nothing at all there — a silent, complete bypass on the single most
- * common shape a downstream HTTP error arrives in. Its group 1 is the keyword
- * and separator, preserved by {@link redactText}.
- *
- * Its value side tries three shapes, and their order is load-bearing:
+ * (`{"password":"…"}`), and a backslash before that quote, because a JSON body
+ * quoted inside another JSON string — the shape a logged HTTP error carries —
+ * reads `{\"password\":\"…\"}`; requiring the separator to follow the bare
+ * keyword would match nothing in either, a silent, complete bypass on the
+ * most common shapes a downstream error arrives in. Its keywords include the
+ * hyphenated and spaced spellings of an API key (`x-api-key`, `api key`), a
+ * secret key and a client secret. Its group 1 is the keyword and separator,
+ * preserved by {@link redactText}.
+ *
+ * Its value side tries four shapes, and their order is load-bearing:
  * 1. a fully-quoted span that consumes escapes, so `{"password":"a\"b"}` is
  *    redacted whole. Ending the span at the escaped quote stopped the
  *    redaction short and printed the rest of the secret verbatim.
+ * 1b. a span quoted with escaped quotes, `\"…\"`, the doubly encoded form of
+ *    the first; it ends at the next quote, so a quote inside such a secret
+ *    leaves its tail in the clear, and the sibling fields after it stay
+ *    intact where the line-end fallback would take them too.
  * 2. an unquoted JSON scalar — number, `true`, `false`, `null` — required to
  *    end at a real delimiter — `,`, `}`, `]` or end of input, optionally
  *    preceded by whitespace. Without this alternative,
@@ -90,13 +70,19 @@ function normaliseKey(key) {
  * 3. the rest of the line, so a multi-word secret is redacted whole instead of
  *    up to its first space. Trying the two precise shapes first is what keeps
  *    this fallback from over-redacting sibling JSON fields.
+ *
+ * The JWT pattern (third) must scan in linear time, because these patterns
+ * run on text a caller controls — anything passed to `redactSecrets` or
+ * `redactLogger`, and an error's whole message before `redactedMessage` cuts
+ * it. A token's header segment is therefore not allowed to run across a `-`
+ * that opens another `eyJ`: written as `eyJ[A-Za-z0-9_-]+`, every `-eyJ` in a
+ * long run of token characters started a fresh scan to the end of the run, so
+ * 400 KB of `-eyJ` held the event loop for about 13 seconds. The only output
+ * this changes is a token whose header segment itself contains `-eyJ`: it is
+ * redacted from that point on, which can leave part of the header — never the
+ * payload or the signature — in the clear.
  */
-exports.DEFAULT_SECRET_VALUE_PATTERNS = [
-    /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
-    /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi,
-    /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
-    /((?:aws_)?(?:secret_access_key|secretaccesskey|password|passwd|api_?key|token)["']?\s*[=:]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)(?=\s*[,}\]]|\s*$)|[^\r\n]+)/gi,
-];
+export declare const DEFAULT_SECRET_VALUE_PATTERNS: readonly RegExp[];
 /**
  * Whether a key name says its value is a secret.
  *
@@ -109,10 +95,7 @@ exports.DEFAULT_SECRET_VALUE_PATTERNS = [
  *
  * Throws: nothing.
  */
-function isSecretKey(key, patterns) {
-    const normalised = normaliseKey(key);
-    return patterns.some((pattern) => normalised === pattern || normalised.endsWith(pattern));
-}
+export declare function isSecretKey(key: string, patterns: readonly string[]): boolean;
 /**
  * An error's message with recognised credential shapes redacted.
  *
@@ -146,22 +129,7 @@ function isSecretKey(key, patterns) {
  * blocks into. Its promise has to hold for what a `catch` actually binds, or
  * the guard concentrates every site into a function that is not safe.
  */
-function redactedMessage(error) {
-    return (0, truncate_1.truncateRelayedText)(redactText((0, base_error_1.toError)(error).message, exports.DEFAULT_SECRET_VALUE_PATTERNS));
-}
-/**
- * A fresh, global copy of `pattern`.
- *
- * Rebuilt per call so a `g` flag's `lastIndex` never leaks between
- * invocations, and **forced** global: `String.prototype.replace` without `g`
- * substitutes only the first match, so a caller-supplied pattern written
- * without the flag would redact the first occurrence of a secret and print
- * every later one verbatim.
- */
-function globalCopyOf(pattern) {
-    const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
-    return new RegExp(pattern.source, flags);
-}
+export declare function redactedMessage(error: Error): string;
 /**
  * Whether `value` is a regular expression.
  *
@@ -173,9 +141,7 @@ function globalCopyOf(pattern) {
  *
  * Throws: nothing.
  */
-function isRegExp(value) {
-    return Object.prototype.toString.call(value) === '[object RegExp]';
-}
+export declare function isRegExp(value: RegExp): boolean;
 /**
  * Replace every recognised secret shape inside `value` with {@link REDACTED},
  * leaving the surrounding text intact so a redacted message stays readable.
@@ -204,13 +170,7 @@ function isRegExp(value) {
  * neither a missing `g` flag nor a leftover `lastIndex` can leave a later
  * occurrence in the clear.
  */
-function redactText(value, patterns) {
-    return patterns.reduce((text, pattern) => {
-        if (!isRegExp(pattern))
-            return text;
-        return text.replace(globalCopyOf(pattern), (_match, prefix) => typeof prefix === 'string' ? `${prefix}${exports.REDACTED}` : exports.REDACTED);
-    }, value);
-}
+export declare function redactText(value: string, patterns: readonly RegExp[]): string;
 /**
  * A short label for a binary view.
  *
@@ -223,8 +183,13 @@ function redactText(value, patterns) {
  *
  * Throws: nothing.
  */
-function binaryLabel(value) {
-    return `[${value.constructor.name}(${value.byteLength})]`;
+export declare function binaryLabel(value: ArrayBufferView): string;
+/** An Error's redacted non-enumerable text, plus whether redaction changed it. */
+export interface RedactedErrorText {
+    name: string;
+    message: string;
+    stack: string | undefined;
+    changed: boolean;
 }
 /**
  * Redact an Error's `name`, `message` and `stack`.
@@ -253,16 +218,10 @@ function binaryLabel(value) {
  * for truncation. A consumer who wants a bound has their own transport to put
  * one in.
  *
- * Throws: **nothing**, for any value.
+ * Throws: **nothing**, for any value: a `name` or `stack` that cannot be read
+ * — a getter of the consumer's own that throws, a `name` whose `toString`
+ * throws — is reported as `[unreadable name]` or `[unreadable stack]`, since
+ * the one thing this must not do on the way to the consumer's transport is
+ * fail.
  */
-function redactErrorText(error, patterns) {
-    const described = (0, base_error_1.toError)(error);
-    const message = redactText(described.message, patterns);
-    const stack = described.stack === undefined ? undefined : redactText(described.stack, patterns);
-    return {
-        name: described.name,
-        message,
-        stack,
-        changed: message !== described.message || stack !== described.stack,
-    };
-}
+export declare function redactErrorText(error: Error, patterns: readonly RegExp[]): RedactedErrorText;

package/dist/esm/shared/logging/secret-patterns.js

@@ -0,0 +1,83 @@
+import { toError } from '../errors/base-error.js';
+import { truncateRelayedText } from './truncate.js';
+export const REDACTED = '[REDACTED]';
+export const DEFAULT_SECRET_KEY_PATTERNS = [
+    'accesskey',
+    'accesskeyid',
+    'secret',
+    'sessiontoken',
+    'securitytoken',
+    'authorization',
+    'password',
+    'passwd',
+    'passphrase',
+    'apikey',
+    'bearer',
+    'token',
+    'privatekey',
+    'secretkey',
+];
+export function normaliseKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+export const DEFAULT_SECRET_VALUE_PATTERNS = [
+    /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+    /\beyJ(?:[A-Za-z0-9_]|-(?!eyJ))+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+    /((?:aws_)?(?:secret_access_key|secretaccesskey|secret_?key|client_?secret|password|passwd|api[-_ ]?key|token)(?:\\?["'])?\s*[=:]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\\"[^"\r\n]*\\"|\\'[^'\r\n]*\\'|(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)(?=\s*[,}\]]|\s*$)|[^\r\n]+)/gi,
+];
+export function isSecretKey(key, patterns) {
+    const normalised = normaliseKey(key);
+    return patterns.some((pattern) => normalised === pattern || normalised.endsWith(pattern));
+}
+export function redactedMessage(error) {
+    return truncateRelayedText(redactText(toError(error).message, DEFAULT_SECRET_VALUE_PATTERNS));
+}
+function globalCopyOf(pattern) {
+    const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+    return new RegExp(pattern.source, flags);
+}
+export function isRegExp(value) {
+    return Object.prototype.toString.call(value) === '[object RegExp]';
+}
+export function redactText(value, patterns) {
+    return patterns.reduce((text, pattern) => {
+        if (!isRegExp(pattern))
+            return text;
+        return text.replace(globalCopyOf(pattern), (_match, prefix) => typeof prefix === 'string' ? `${prefix}${REDACTED}` : REDACTED);
+    }, value);
+}
+export function binaryLabel(value) {
+    return `[${value.constructor.name}(${value.byteLength})]`;
+}
+export function redactErrorText(error, patterns) {
+    const described = toError(error);
+    const rawName = nameOf(described);
+    const rawStack = stackOf(described);
+    const name = redactText(rawName, patterns);
+    const message = redactText(described.message, patterns);
+    const stack = rawStack === undefined ? undefined : redactText(rawStack, patterns);
+    return {
+        name,
+        message,
+        stack,
+        changed: name !== rawName || message !== described.message || stack !== rawStack,
+    };
+}
+function nameOf(error) {
+    try {
+        return String(error.name);
+    }
+    catch {
+        return '[unreadable name]';
+    }
+}
+function stackOf(error) {
+    try {
+        const { stack } = error;
+        return stack === undefined ? undefined : String(stack);
+    }
+    catch {
+        return '[unreadable stack]';
+    }
+}

package/dist/{shared/logging/truncate.js → esm/shared/logging/truncate.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides how much of an unchecked string a line may quote.
  *
@@ -8,11 +7,6 @@
  * cut value's real length, are chosen here, so a call site says what kind of
  * value it quotes and never how many characters it keeps.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_RELAYED_MESSAGE_CHARS = exports.MAX_LOGGED_LABELS = exports.MAX_LOGGED_VALUE_CHARS = void 0;
-exports.truncateForLog = truncateForLog;
-exports.truncateRelayedText = truncateRelayedText;
-exports.truncateLabelsForLog = truncateLabelsForLog;
 /**
  * Characters of an unchecked string one log line or one public error message
  * carries, past which it is cut and marked with its real length.
@@ -33,7 +27,7 @@ exports.truncateLabelsForLog = truncateLabelsForLog;
  * cases these lines report — is cut. Nothing is lost by cutting: the line's
  * job is to say which row to go and look at, and the row holds the rest.
  */
-exports.MAX_LOGGED_VALUE_CHARS = 256;
+export declare const MAX_LOGGED_VALUE_CHARS = 256;
 /**
  * Labels of an unchecked `string[]` one log line or one public error message
  * carries, past which the rest are dropped and the real depth is stated.
@@ -57,7 +51,7 @@ exports.MAX_LOGGED_VALUE_CHARS = 256;
  * a key — so its depth is unchecked however carefully each label was checked,
  * and a backend's own answer is unchecked in both.
  */
-exports.MAX_LOGGED_LABELS = 8;
+export declare const MAX_LOGGED_LABELS = 8;
 /**
  * Characters of a relayed *cause's* text one public error message or one log
  * line carries, past which it is cut and marked with its real length.
@@ -94,26 +88,7 @@ exports.MAX_LOGGED_LABELS = 8;
  * records: aliasing two caps would move one whenever the other is retuned,
  * and these three answer unrelated questions.
  */
-exports.MAX_RELAYED_MESSAGE_CHARS = 1024;
-/** True for the high half of a surrogate pair, whose low half follows it. */
-function isHighSurrogate(unit) {
-    return unit >= 0xd800 && unit <= 0xdbff;
-}
-/**
- * The cut itself, shared by both caps so one value can never be marked twice
- * with two different lengths.
- *
- * `max` is a character count. A value at or under it comes back identical; a
- * longer one comes back as `max` characters — one fewer when that would split
- * a surrogate pair — followed by `…(len N)` giving the length it really had.
- */
-function cutTo(value, max) {
-    if (typeof value !== 'string' || value.length <= max)
-        return value;
-    const last = value.charCodeAt(max - 1);
-    const kept = isHighSurrogate(last) ? max - 1 : max;
-    return `${value.slice(0, kept)}…(len ${value.length})`;
-}
+export declare const MAX_RELAYED_MESSAGE_CHARS = 1024;
 /**
  * Bound a string this package did not length-check.
  *
@@ -157,9 +132,7 @@ function cutTo(value, max) {
  * `assertWellFormed` exists to keep out of this package's strings, and a JSON
  * log transport rewrites one to U+FFFD without saying so.
  */
-function truncateForLog(value) {
-    return cutTo(value, exports.MAX_LOGGED_VALUE_CHARS);
-}
+export declare function truncateForLog(value: string): string;
 /**
  * Bound the **prose** of a relayed cause, which takes its own cap.
  *
@@ -185,9 +158,7 @@ function truncateForLog(value) {
  *
  * Throws: nothing.
  */
-function truncateRelayedText(value) {
-    return cutTo(value, exports.MAX_RELAYED_MESSAGE_CHARS);
-}
+export declare function truncateRelayedText(value: string): string;
 /**
  * Bound a list of labels — a store `namespace`, a list of channel names — the
  * same rule reaches.
@@ -223,9 +194,4 @@ function truncateRelayedText(value) {
  *
  * Throws: nothing.
  */
-function truncateLabelsForLog(labels) {
-    if (!Array.isArray(labels))
-        return labels;
-    const kept = labels.slice(0, exports.MAX_LOGGED_LABELS).map((label) => truncateForLog(label));
-    return labels.length > exports.MAX_LOGGED_LABELS ? [...kept, `…(len ${labels.length})`] : kept;
-}
+export declare function truncateLabelsForLog(labels: string[]): string[];

package/dist/esm/shared/logging/truncate.js

@@ -0,0 +1,25 @@
+export const MAX_LOGGED_VALUE_CHARS = 256;
+export const MAX_LOGGED_LABELS = 8;
+export const MAX_RELAYED_MESSAGE_CHARS = 1024;
+function isHighSurrogate(unit) {
+    return unit >= 0xd800 && unit <= 0xdbff;
+}
+function cutTo(value, max) {
+    if (typeof value !== 'string' || value.length <= max)
+        return value;
+    const last = value.charCodeAt(max - 1);
+    const kept = isHighSurrogate(last) ? max - 1 : max;
+    return `${value.slice(0, kept)}…(len ${value.length})`;
+}
+export function truncateForLog(value) {
+    return cutTo(value, MAX_LOGGED_VALUE_CHARS);
+}
+export function truncateRelayedText(value) {
+    return cutTo(value, MAX_RELAYED_MESSAGE_CHARS);
+}
+export function truncateLabelsForLog(labels) {
+    if (!Array.isArray(labels))
+        return labels;
+    const kept = labels.slice(0, MAX_LOGGED_LABELS).map((label) => truncateForLog(label));
+    return labels.length > MAX_LOGGED_LABELS ? [...kept, `…(len ${labels.length})`] : kept;
+}

package/dist/esm/shared/options.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Hides which options every adapter shares.
+ *
+ * The table, the client, the ttl, the logger, the retry policy, the recency
+ * index, the read concurrency, the codec options and per-call cancellation are
+ * declared once here, so the checkpointer, the store and the history accept
+ * the same keys with the same meaning, and an adapter-wide option is added in
+ * one place. This module holds their types only; checking them is elsewhere.
+ */
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import type { CompressionConfig } from './codec/compression.js';
+import type { S3OffloadConfig } from './codec/s3/config.js';
+import type { DynamoDBDocumentLike } from './dynamodb/client.js';
+import type { RetryPolicy } from './dynamodb/retry.js';
+import type { Logger } from './logging/logger.js';
+import type { TtlOption } from './validation/ttl.js';
+/**
+ * Options common to every adapter (the unified options shape). An adapter
+ * either reuses an injected `client` or builds one from `clientConfig`.
+ */
+export interface BaseAdapterOptions {
+    /** DynamoDB table name. */
+    tableName: string;
+    /** Pre-built DocumentClient to reuse; when set, the adapter does not own it. */
+    client?: DynamoDBDocumentLike;
+    /** The config a client is built from when `client` is not provided. */
+    clientConfig?: DynamoDBClientConfig;
+    /** Optional time-to-live applied to written items. */
+    ttl?: TtlOption;
+    /** Optional per-instance logger (defaults to a silent logger). */
+    logger?: Logger;
+    /** Retry budget and backoff for every DynamoDB call (see the README "Retries and backoff"). */
+    retry?: RetryPolicy;
+    /**
+     * Index partitions per adapter in the recency index (GSI1), default 8.
+     *
+     * Checkpoint and session rows carry the index attributes whether or not the
+     * table defines the index, so enabling it later needs only a backfill of the
+     * rows written before. The value is fixed for the table's life. Every row
+     * keeps the shard it was written with, and `backfillRecencyIndex` writes
+     * keys only to rows that have none, so it cannot move a row. Raising the
+     * count is safe: the old shards stay among the ones a listing queries.
+     * Lowering it hides every row on a dropped shard from the listings. The
+     * store takes no `indexShards`.
+     *
+     * A single index partition per adapter would concentrate every listing on
+     * one partition, which is worse than the table scan it replaces.
+     */
+    indexShards?: number;
+    /**
+     * Name of the recency index (a GSI on `gsi1pk`/`gsi1sk`) on this table.
+     *
+     * Opt-in on purpose: whether the table carries the index is deployment
+     * configuration the operator knows, and probing for it would spend a failed
+     * request per process to find out. Naming it switches two listings that
+     * would otherwise scan the whole table onto a read of the index, newest
+     * first: `history.listSessions`, which pages it by cursor, and a
+     * `saver.list` without a `thread_id`, which streams it and takes no cursor.
+     * Leaving it unset keeps both on the table scan, so the index can be created
+     * and backfilled before any adapter reads it.
+     *
+     * The store takes no `indexName`: its rootless search and its namespace
+     * listing stay table scans.
+     */
+    indexName?: string;
+    /**
+     * How many payloads a single call decodes at once, default 8.
+     *
+     * It is the multiplier on this package's memory ceiling, which is
+     * `readConcurrency × (s3.maxDownloadBytes + compression.maxDecompressedBytes)`
+     * — a downloaded object and its decompressed form are both resident while a
+     * payload is decoded, and that much can be in flight for each concurrent
+     * decode. Lower it on a small container; raising it trades memory for
+     * latency on reads that fetch many offloaded payloads.
+     *
+     * It also bounds how many recency-index shards one listing queries at once.
+     */
+    readConcurrency?: number;
+}
+/** Options enabling payload compression and/or S3 offloading. */
+export interface CodecOptions {
+    /** Gzip compression configuration. */
+    compression?: CompressionConfig;
+    /** S3 offload configuration for payloads over DynamoDB's item limit. */
+    s3?: S3OffloadConfig;
+}
+/** Per-call cancellation for the long-running adapter methods. */
+export interface CancelOptions {
+    /**
+     * Aborting it rejects the call with an `ABORTED` error — carrying the abort
+     * reason as `cause` — whether the signal was already aborted (nothing is
+     * sent), aborts while the call waits between requests, or aborts while a
+     * request is in flight: the signal reaches the AWS SDK on every DynamoDB
+     * request and S3 transfer the call makes for you, so the request itself
+     * ends. The verification reads and the cleanup that follow a failure run to
+     * completion regardless. A value that is not `AbortSignal`-shaped is refused
+     * with `VALIDATION` naming `signal` before anything is sent.
+     */
+    signal?: AbortSignal;
+}

package/dist/esm/shared/options.js

@@ -0,0 +1 @@
+export {};