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

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

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactSecrets = redactSecrets;
+exports.redactLogger = redactLogger;
+exports.walkObject = walkObject;
+const errors_js_1 = require("../errors/errors.js");
+const collaborators_js_1 = require("../validation/collaborators.js");
+const option_shape_js_1 = require("../validation/option-shape.js");
+const primitives_js_1 = require("../validation/primitives.js");
+const logger_js_1 = require("./logger.js");
+const secret_patterns_js_1 = require("./secret-patterns.js");
+const UNREDACTABLE = '[UNREDACTABLE]';
+function assertRegExpArray(value, field) {
+    if (!Array.isArray(value) || value.some((entry) => !(0, secret_patterns_js_1.isRegExp)(entry))) {
+        throw (0, errors_js_1.validationError)(`${field} must be an array of RegExp`, field);
+    }
+}
+function assertKeyPatterns(value, field) {
+    (0, primitives_js_1.assertStringArray)(value, field);
+    if (value.some((entry) => (0, secret_patterns_js_1.normaliseKey)(entry) === '')) {
+        throw (0, errors_js_1.validationError)(`${field} must name a letter or digit in every entry`, field);
+    }
+}
+function redactSecrets(value, patterns = secret_patterns_js_1.DEFAULT_SECRET_KEY_PATTERNS, valuePatterns = secret_patterns_js_1.DEFAULT_SECRET_VALUE_PATTERNS) {
+    assertKeyPatterns(patterns, 'patterns');
+    assertRegExpArray(valuePatterns, 'valuePatterns');
+    const keyPatterns = patterns.map(secret_patterns_js_1.normaliseKey);
+    const walking = new WeakSet();
+    const done = new WeakMap();
+    const walk = (current) => {
+        if (typeof current === 'string')
+            return (0, secret_patterns_js_1.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) {
+    (0, option_shape_js_1.assertObjectShape)(options, 'options');
+    if (options.extraKeys !== undefined)
+        assertKeyPatterns(options.extraKeys, 'extraKeys');
+    if (options.extraValuePatterns !== undefined) {
+        assertRegExpArray(options.extraValuePatterns, 'extraValuePatterns');
+    }
+}
+function redactLogger(inner, options = {}) {
+    (0, collaborators_js_1.assertMembers)(inner, collaborators_js_1.LOGGER_MEMBERS, 'logger');
+    assertRedactionOptions(options);
+    const patterns = options.extraKeys
+        ? [...secret_patterns_js_1.DEFAULT_SECRET_KEY_PATTERNS, ...options.extraKeys.map(secret_patterns_js_1.normaliseKey)]
+        : secret_patterns_js_1.DEFAULT_SECRET_KEY_PATTERNS;
+    const valuePatterns = options.extraValuePatterns
+        ? [...secret_patterns_js_1.DEFAULT_SECRET_VALUE_PATTERNS, ...options.extraValuePatterns]
+        : secret_patterns_js_1.DEFAULT_SECRET_VALUE_PATTERNS;
+    const deliver = (method) => (message, ...args) => (0, logger_js_1.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: (0, secret_patterns_js_1.isSecretKey)(key, keyPatterns) ? secret_patterns_js_1.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 = (0, secret_patterns_js_1.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;
+}
+function walkObject(current, deps) {
+    if (Array.isArray(current))
+        return current.map(deps.walk);
+    if (ArrayBuffer.isView(current))
+        return (0, secret_patterns_js_1.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 → cjs/shared}/logging/secret-patterns.d.ts

@@ -40,15 +40,23 @@ export declare function normaliseKey(key: string): string;
  *
  * 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,
@@ -62,6 +70,17 @@ export declare function normaliseKey(key: string): string;
  * 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.
  */
 export declare const DEFAULT_SECRET_VALUE_PATTERNS: readonly RegExp[];
 /**
@@ -199,6 +218,10 @@ export interface RedactedErrorText {
  * 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.
  */
 export declare function redactErrorText(error: Error, patterns: readonly RegExp[]): RedactedErrorText;

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

@@ -0,0 +1,93 @@
+"use strict";
+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_js_1 = require("../errors/base-error.js");
+const truncate_js_1 = require("./truncate.js");
+exports.REDACTED = '[REDACTED]';
+exports.DEFAULT_SECRET_KEY_PATTERNS = [
+    'accesskey',
+    'accesskeyid',
+    'secret',
+    'sessiontoken',
+    'securitytoken',
+    'authorization',
+    'password',
+    'passwd',
+    'passphrase',
+    'apikey',
+    'bearer',
+    'token',
+    'privatekey',
+    'secretkey',
+];
+function normaliseKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+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_]|-(?!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,
+];
+function isSecretKey(key, patterns) {
+    const normalised = normaliseKey(key);
+    return patterns.some((pattern) => normalised === pattern || normalised.endsWith(pattern));
+}
+function redactedMessage(error) {
+    return (0, truncate_js_1.truncateRelayedText)(redactText((0, base_error_js_1.toError)(error).message, exports.DEFAULT_SECRET_VALUE_PATTERNS));
+}
+function globalCopyOf(pattern) {
+    const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+    return new RegExp(pattern.source, flags);
+}
+function isRegExp(value) {
+    return Object.prototype.toString.call(value) === '[object RegExp]';
+}
+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);
+}
+function binaryLabel(value) {
+    return `[${value.constructor.name}(${value.byteLength})]`;
+}
+function redactErrorText(error, patterns) {
+    const described = (0, base_error_js_1.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/cjs/shared/logging/truncate.js

@@ -0,0 +1,31 @@
+"use strict";
+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;
+exports.MAX_LOGGED_VALUE_CHARS = 256;
+exports.MAX_LOGGED_LABELS = 8;
+exports.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})`;
+}
+function truncateForLog(value) {
+    return cutTo(value, exports.MAX_LOGGED_VALUE_CHARS);
+}
+function truncateRelayedText(value) {
+    return cutTo(value, exports.MAX_RELAYED_MESSAGE_CHARS);
+}
+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;
+}

package/dist/{shared → cjs/shared}/options.d.ts

@@ -8,12 +8,12 @@
  * 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';
-import type { S3OffloadConfig } from './codec/s3/config';
-import type { DynamoDBDocumentLike } from './dynamodb/client';
-import type { RetryPolicy } from './dynamodb/retry';
-import type { Logger } from './logging/logger';
-import type { TtlOption } from './validation/ttl';
+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`.
@@ -34,10 +34,14 @@ export interface BaseAdapterOptions {
     /**
      * Index partitions per adapter in the recency index (GSI1), default 8.
      *
-     * Rows carry the index attributes whether or not the table defines the
-     * index, so enabling it later needs no rewrite of new rows — only a backfill
-     * of the old ones. The value is fixed at table creation: changing it changes
-     * every row's shard, so an existing index must be backfilled again.
+     * 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.
@@ -54,6 +58,9 @@ export interface BaseAdapterOptions {
      * `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;
     /**
@@ -79,6 +86,15 @@ export interface CodecOptions {
 }
 /** Per-call cancellation for the long-running adapter methods. */
 export interface CancelOptions {
-    /** Aborting it rejects the call with an `ABORTED` error at the next wait. */
+    /**
+     * 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/cjs/shared/options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/shared/ulid.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ULID_TIME_RANGE_MS = void 0;
+exports.secureRng = secureRng;
+exports.ulidTimePrefix = ulidTimePrefix;
+exports.createUlidFactory = createUlidFactory;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("./errors/errors.js");
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const ENCODING_LEN = 32;
+const TIME_CHARS = 10;
+const RANDOM_CHARS = 16;
+exports.ULID_TIME_RANGE_MS = ENCODING_LEN ** TIME_CHARS;
+const RNG_POOL_BYTES = 256;
+function secureRng() {
+    let pool = Buffer.alloc(0);
+    let offset = 0;
+    return () => {
+        if (offset >= pool.length) {
+            pool = (0, node_crypto_1.randomBytes)(RNG_POOL_BYTES);
+            offset = 0;
+        }
+        const byte = pool[offset];
+        offset += 1;
+        return byte / 256;
+    };
+}
+function encodeTime(timeMs) {
+    let remaining = Math.floor(timeMs);
+    let out = '';
+    for (let i = 0; i < TIME_CHARS; i++) {
+        out = ENCODING[remaining % ENCODING_LEN] + out;
+        remaining = Math.floor(remaining / ENCODING_LEN);
+    }
+    return out;
+}
+function ulidTimePrefix(timeMs) {
+    if (!(timeMs >= 0 && timeMs < exports.ULID_TIME_RANGE_MS)) {
+        throw (0, errors_js_1.validationError)(`a ULID time prefix covers epoch milliseconds 0 to ${exports.ULID_TIME_RANGE_MS - 1} (the year ` +
+            `37648); ${timeMs} is outside it and has no ten-character encoding`);
+    }
+    return encodeTime(timeMs);
+}
+function randomDigits(rng) {
+    const digits = [];
+    for (let i = 0; i < RANDOM_CHARS; i++) {
+        digits.push(Math.floor(rng() * ENCODING_LEN));
+    }
+    return digits;
+}
+function incrementDigits(digits) {
+    const next = [...digits];
+    for (let i = RANDOM_CHARS - 1; i >= 0; i--) {
+        if (next[i] < ENCODING_LEN - 1) {
+            next[i] += 1;
+            return { digits: next, overflowed: false };
+        }
+        next[i] = 0;
+    }
+    return { digits: next, overflowed: true };
+}
+function createUlidFactory(now = Date.now, rng = secureRng()) {
+    let lastTime = -1;
+    let lastRandom = [];
+    return () => {
+        const time = now();
+        if (time > lastTime) {
+            lastTime = time;
+            lastRandom = randomDigits(rng);
+        }
+        else {
+            const result = incrementDigits(lastRandom);
+            if (result.overflowed) {
+                lastTime += 1;
+                lastRandom = randomDigits(rng);
+            }
+            else {
+                lastRandom = result.digits;
+            }
+        }
+        return encodeTime(lastTime) + lastRandom.map((digit) => ENCODING[digit]).join('');
+    };
+}

package/dist/{shared → cjs/shared}/validation/collaborators.d.ts

@@ -7,7 +7,7 @@
  * `AbortSignal` has, so a wrong object fails where it was passed and not at the
  * first call deep inside an operation.
  */
-import type { CancelOptions } from '../options';
+import type { CancelOptions } from '../options.js';
 /** The `DynamoDBDocument` methods this package calls on an injected `client`. */
 export declare const CLIENT_MEMBERS: readonly string[];
 /** The `Logger` methods every adapter calls. */
@@ -53,6 +53,23 @@ export declare const ABORT_SIGNAL_MEMBERS: Readonly<Record<string, 'boolean' | '
  * the value.
  */
 export declare function assertMembers(value: object, members: readonly string[], field: string): void;
+/**
+ * Refuse an injected client whose document translation changes what this
+ * package writes or reads back.
+ *
+ * Accepts: `client` — the injected document client, or any object standing in
+ * for one; one without `config.translateConfig` translates the default way.
+ *
+ * Returns: nothing: the client is kept under its declared type, and this checks it.
+ *
+ * Throws: `VALIDATION` naming `client` when its `unmarshallOptions.wrapNumbers`
+ * is set — every number this package reads back (a row's format version, a
+ * `ttl`, a message count) would arrive wrapped, so a newer row would read as
+ * version 0 and a session as malformed — or when its
+ * `marshallOptions.convertEmptyValues` is on, which stores the root checkpoint
+ * namespace, the empty string, as NULL.
+ */
+export declare function assertClientTranslation(client: object): void;
 /**
  * Validate the collaborators every adapter shares: `client`, `logger` and
  * `serde`. Pulled out of each `setUp*` as one call rather than three inline
@@ -67,7 +84,9 @@ export declare function assertMembers(value: object, members: readonly string[],
  * and this checks it. A collaborator the caller did not supply is left
  * untouched, so it still reaches its default.
  *
- * Throws: see {@link assertMembers}.
+ * Throws: see {@link assertMembers} for a collaborator missing a method, and
+ * {@link assertClientTranslation} for a `client` whose translation would
+ * change how a row reads back.
  */
 export declare function assertBaseCollaborators(options: {
     client?: object;

package/dist/cjs/shared/validation/collaborators.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANCEL_KEYS = exports.ABORT_SIGNAL_MEMBERS = exports.VECTOR_BACKEND_MEMBERS = exports.EMBEDDINGS_MEMBERS = exports.SERDE_MEMBERS = exports.LOGGER_MEMBERS = exports.CLIENT_MEMBERS = void 0;
+exports.assertMembers = assertMembers;
+exports.assertClientTranslation = assertClientTranslation;
+exports.assertBaseCollaborators = assertBaseCollaborators;
+exports.isAbortSignalLike = isAbortSignalLike;
+exports.assertSignalLike = assertSignalLike;
+exports.assertCancelOptions = assertCancelOptions;
+const errors_js_1 = require("../errors/errors.js");
+const option_shape_js_1 = require("./option-shape.js");
+exports.CLIENT_MEMBERS = [
+    'get',
+    'put',
+    'delete',
+    'update',
+    'query',
+    'scan',
+    'batchWrite',
+    'transactWrite',
+];
+exports.LOGGER_MEMBERS = ['debug', 'info', 'warn', 'error'];
+exports.SERDE_MEMBERS = ['dumpsTyped', 'loadsTyped'];
+exports.EMBEDDINGS_MEMBERS = ['embedQuery', 'embedDocuments'];
+exports.VECTOR_BACKEND_MEMBERS = ['upsert', 'query', 'delete'];
+exports.ABORT_SIGNAL_MEMBERS = {
+    aborted: 'boolean',
+    addEventListener: 'function',
+    removeEventListener: 'function',
+};
+function assertMembers(value, members, field) {
+    if (!(0, option_shape_js_1.isObjectShape)(value)) {
+        throw (0, errors_js_1.validationError)(`${field} must be an object`, field);
+    }
+    for (const member of members) {
+        if (typeof Reflect.get(value, member) !== 'function') {
+            throw (0, errors_js_1.validationError)(`${field}.${member} must be a function`, `${field}.${member}`);
+        }
+    }
+}
+function assertClientTranslation(client) {
+    const translate = client.config?.translateConfig;
+    if (translate?.unmarshallOptions?.wrapNumbers) {
+        throw (0, errors_js_1.validationError)('client reads numbers back wrapped (unmarshallOptions.wrapNumbers), where this package ' +
+            'reads a row version, a ttl and a count as numbers; inject a DynamoDBDocument built ' +
+            'without it', 'client');
+    }
+    if (translate?.marshallOptions?.convertEmptyValues === true) {
+        throw (0, errors_js_1.validationError)('client stores an empty string as NULL (marshallOptions.convertEmptyValues), which erases ' +
+            'the root checkpoint namespace; inject a DynamoDBDocument built without it', 'client');
+    }
+}
+function assertBaseCollaborators(options) {
+    if (options.client !== undefined) {
+        assertMembers(options.client, exports.CLIENT_MEMBERS, 'client');
+        assertClientTranslation(options.client);
+    }
+    if (options.logger !== undefined)
+        assertMembers(options.logger, exports.LOGGER_MEMBERS, 'logger');
+    if (options.serde !== undefined)
+        assertMembers(options.serde, exports.SERDE_MEMBERS, 'serde');
+}
+function isAbortSignalLike(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return Object.entries(exports.ABORT_SIGNAL_MEMBERS).every(([member, type]) => typeof Reflect.get(value, member) === type);
+}
+function assertSignalLike(value, field = 'signal') {
+    if (value !== undefined && !isAbortSignalLike(value)) {
+        throw (0, errors_js_1.validationError)(`${field} must be an AbortSignal`, field);
+    }
+}
+exports.CANCEL_KEYS = (0, option_shape_js_1.allKeysOf)({ signal: 'signal' });
+function assertCancelOptions(options) {
+    if (options === undefined)
+        return;
+    (0, option_shape_js_1.assertShape)(options, exports.CANCEL_KEYS, 'options');
+    assertSignalLike(options.signal);
+}

package/dist/{shared → cjs/shared}/validation/option-shape.d.ts

@@ -1,11 +1,13 @@
 /**
  * Hides how an option object is told apart from a misspelt one.
  *
- * An option type lists its keys once, checked by the compiler against the
- * type, and an object carrying any other key is refused naming that key. No
- * caller writes the plain-object test or the unknown-key walk itself, so the
- * message and the field a refusal names are the same for every option object
- * this package reads.
+ * An option type this package defines lists its keys once, checked by the
+ * compiler against the type, and an object carrying any other key is refused
+ * naming that key. An option object LangGraph defines is only held to being an
+ * object, since a key a later LangGraph adds must not refuse a call LangGraph
+ * makes (decision record 28). No caller writes the plain-object test or the
+ * unknown-key walk itself, so the message and the field a refusal names are the
+ * same for every option object this package reads.
  */
 /**
  * Every key of `T`, listed once.

package/dist/cjs/shared/validation/option-shape.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allKeysOf = allKeysOf;
+exports.isObjectShape = isObjectShape;
+exports.assertObjectShape = assertObjectShape;
+exports.assertShape = assertShape;
+exports.parseShape = parseShape;
+const errors_js_1 = require("../errors/errors.js");
+function allKeysOf(keys) {
+    return Object.keys(keys);
+}
+function isObjectShape(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertObjectShape(value, field) {
+    if (!isObjectShape(value)) {
+        throw (0, errors_js_1.validationError)(`${field} must be an object`, field);
+    }
+}
+function assertShape(value, allowed, field) {
+    assertObjectShape(value, field);
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            throw (0, errors_js_1.validationError)(`${field}.${key} is not an option this package reads; expected one of ${allowed.join(', ')}`, `${field}.${key}`);
+        }
+    }
+}
+function parseShape(value, allowed, field) {
+    assertShape(value, allowed, field);
+    return value;
+}