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

package/dist/cjs/shared/dynamodb/retry.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Hides when and how a failed request is retried (record 14).
+ *
+ * Which failures are transient — read from an error's whole cause chain, its
+ * HTTP status and its retryable trait, and from a cancelled transaction's
+ * reasons — the full-jitter backoff schedule, the attempt budget and the
+ * deadline that can cut it short, and the policy an adapter resolves from its
+ * options at construction are one decision. Every DynamoDB call goes through
+ * it, and so does an S3 object upload and download; the bucket lifecycle calls
+ * (`maxAttempts: 1` on the S3 client) and orphan release, which retries on its
+ * own loop, do not.
+ */
+import type { Logger } from '../logging/logger.js';
+/** Starting delay for UnprocessedItems / UnprocessedKeys backoff loops. */
+export declare const INITIAL_BACKOFF_DELAY_MS = 100;
+/** Maximum backoff delay for retry loops. */
+export declare const MAX_BACKOFF_DELAY_MS = 5000;
+/** Default maximum attempts for transient-error retries. */
+export declare const DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+/**
+ * How long DynamoDB treats a repeated client request token as the same request
+ * rather than a new one, so re-sending a tokened write is deduplicated instead
+ * of applied twice (10 minutes). Recorded as its own constant so the margin
+ * {@link MAX_WRITE_LIFETIME_MS} keeps under it is legible.
+ */
+export declare const TOKEN_IDEMPOTENCY_WINDOW_MS = 600000;
+/**
+ * Longest one token-carrying write may keep retrying (5 minutes): half of
+ * {@link TOKEN_IDEMPOTENCY_WINDOW_MS}. The other half absorbs the attempt
+ * still in flight when the budget ends, clock skew between this client's own
+ * clock and DynamoDB's timer, and SDK-internal queueing, so a write that
+ * retries to the end still finishes well inside the window its token is
+ * honoured for. Its own literal rather than a division of the window:
+ * aliasing them would move one whenever the other is retuned (see
+ * `LIST_SCAN_WARN_THRESHOLD` (`src/shared/dynamodb/paginate.ts`)).
+ */
+export declare const MAX_WRITE_LIFETIME_MS = 300000;
+/**
+ * The per-request options one attempt hands to the SDK call it makes.
+ *
+ * It is the AWS SDK's own second argument (`HttpHandlerOptions` from
+ * `@smithy/types`) narrowed to the single field this library sets, so a call
+ * site forwards the value it was given instead of assembling one — the
+ * difference between `client.get(params, request)` at every site and thirty
+ * chances to write `{ signal }` where the SDK reads `abortSignal`.
+ *
+ * `DynamoDBDocumentLike` picks its members off the real `DynamoDBDocument`, so
+ * every method already accepts this as its optional second argument and no
+ * type had to move to make room for it.
+ */
+export interface SdkRequestOptions {
+    abortSignal?: AbortSignal;
+}
+/** What {@link RetryOptions.onRetry} learns before each backoff sleep. */
+export interface RetryAttemptInfo {
+    attempt: number;
+    delayMs: number;
+    error: Error;
+}
+/**
+ * How a failed request is retried: how many attempts, how long each wait, and
+ * which failures qualify.
+ */
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    retryableErrors?: readonly string[];
+    /**
+     * Decides retryability instead of `retryableErrors`: called with each failed
+     * attempt's error, it retries when it returns `true`.
+     */
+    isRetryable?: (error: Error) => boolean;
+    /** Called before every backoff sleep, so retries are visible before the budget is exhausted. */
+    onRetry?: (info: RetryAttemptInfo) => void;
+    signal?: AbortSignal;
+    rng?: () => number;
+}
+/**
+ * The cap a backoff schedule runs under.
+ *
+ * Accepts: `baseDelayMs` — the schedule's first delay, already defaulted.
+ * `maxDelayMs` — the cap the caller named, if it named one.
+ *
+ * Returns: the named cap; without one, {@link MAX_BACKOFF_DELAY_MS} raised to
+ * a base above it.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: a base delay given without a cap is the delay the schedule
+ * starts from. Held under the default cap it would be cut to five seconds on
+ * every sleep: an option accepted and then ignored.
+ */
+export declare function backoffCapMs(baseDelayMs: number, maxDelayMs: number | undefined): number;
+/**
+ * Run `fn`, retrying transient failures with full-jitter exponential backoff.
+ *
+ * Accepts: `fn` — given the {@link SdkRequestOptions} for the attempt, to pass
+ * as the second argument of the SDK call it makes. That argument is what
+ * carries `options.signal` into the request, and it is the only way a call
+ * site can: `fn` closes over its own parameters, so nothing else reaches it.
+ * An `fn` that makes no cancellable call ignores the parameter and is written
+ * exactly as it was, since a zero-argument function still satisfies the type.
+ *
+ * Accepts: `options.maxAttempts` — total attempts including the first, default
+ * {@link DEFAULT_RETRY_MAX_ATTEMPTS}; at least 1, which `assertRetryPolicy`
+ * enforces for every caller-supplied policy. `options.baseDelayMs` /
+ * `maxDelayMs` — the backoff schedule, its cap defaulted by
+ * {@link backoffCapMs}. `options.isRetryable` — replaces
+ * `retryableErrors` entirely, so a call site can share one classifier with
+ * paths that do not go through here. `options.signal` — checked before the
+ * first attempt, handed to every attempt as `abortSignal` so the request in
+ * flight is cancelled rather than merely awaited, checked again when an
+ * attempt fails, and honoured during every backoff wait. `options.onRetry` —
+ * called synchronously before each wait; an exception from it is not caught
+ * and ends the operation. `options.deadlineAt` — an internal bound on the
+ * whole budget rather than on one attempt: the wait that would carry the
+ * operation past it is never started, and the budget ends there instead.
+ * Without it the schedule, the attempt count and every error are unchanged.
+ *
+ * Returns: whatever `fn` resolves to, from the first attempt that succeeds.
+ *
+ * Throws: the error itself, unchanged, when it is not retryable — a
+ * `ValidationException` or a permission failure is never retried;
+ * `ABORTED` when the signal fires, including during a wait and
+ * including while a request is in flight — the SDK rejects the cancelled
+ * request with an error of its own, and a failed attempt whose signal has
+ * fired is reported as the cancel it is rather than being classified, retried
+ * or wrapped; `RETRY_EXHAUSTED` once the budget ends, carrying the attempt
+ * actually reached — not the attempts configured — and the last error as
+ * `cause`. Its message quotes the last error **redacted**, because it reaches
+ * `err.message`, which an application may print without a redacting logger.
+ * That error also records, for `mayStillLand` to read back
+ * (`retryBudgetMayStillLand`), whether *any* attempt of the budget — not only
+ * the last — left DynamoDB free to apply it later: one that ended on this
+ * side before an answer, one DynamoDB answered `TransactionInProgressException`
+ * to (its own earlier attempt under the same token still being processed), or
+ * one it answered with a server error (see `mayStillBeInFlight`). An attempt
+ * answered some other way settles nothing by itself, whatever attempt beside
+ * it did.
+ *
+ * A deadline that ends the budget is reported exactly as a spent one, by the
+ * same error with the same code: a caller cannot tell the two apart, and
+ * nothing needs to, since the handling of both is identical — read the row
+ * back, and release only what is confirmed not to have landed.
+ *
+ * A cancelled wait is also an abort no longer observed. The signal is read
+ * before the first attempt, after every failed one, and inside each wait, so
+ * ending the budget in place of a wait drops only that last observation point:
+ * a signal that fires *after* the deadline has already refused the wait, in
+ * the window where the wait would have been running, surfaces as
+ * `RETRY_EXHAUSTED` rather than `ABORTED`. One already set
+ * at entry, fired during an attempt, or fired during an earlier wait, is still
+ * caught.
+ *
+ * Guarantees: `fn` is called at most `maxAttempts` times, and at least once
+ * unless the signal was already aborted at entry, when it is not called at
+ * all. A thrown non-`Error` is wrapped, so what a caller catches is always an
+ * `Error`.
+ */
+export declare function withRetry<T>(fn: (request: SdkRequestOptions) => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * {@link withRetry} with this package's DynamoDB defaults.
+ *
+ * Accepts: `overrides` — merged over `maxAttempts:`
+ * {@link DEFAULT_RETRY_MAX_ATTEMPTS}, so an adapter's resolved policy wins.
+ *
+ * Returns: as {@link withRetry}.
+ *
+ * Throws: as {@link withRetry}.
+ */
+export declare function withDynamoDBRetry<T>(fn: (request: SdkRequestOptions) => Promise<T>, overrides?: Partial<RetryOptions>): Promise<T>;
+/**
+ * Whether `error`, or any cause in its chain, is transient.
+ *
+ * Accepts: `error` — an `Error`; its `cause` chain is walked to
+ * {@link MAX_CAUSE_DEPTH}, and a cycle in it terminates the walk rather than
+ * looping. Anything else a `throw` can produce carries no node to walk and is
+ * not retryable. `retryableErrors` — the signal tokens to match; an empty list
+ * still admits the trait and status rules below.
+ *
+ * Returns: true when any of these holds, in this order —
+ * 1. the error is a transaction cancellation and **every** reason it carries is
+ *    transient. This verdict is final either way: a permanent reason arrives
+ *    with the same HTTP status as a transient one, so the later rules cannot be
+ *    allowed to overturn it. A cancellation carrying no reasons is not retried.
+ * 2. any node carries the SDK's `$retryable` trait, or is a signing failure
+ *    the SDK corrected its clock for or reports expired (`isCorrectedClockSkew`);
+ * 3. any node's HTTP status is in {@link TRANSIENT_HTTP_STATUSES} — which is
+ *    what classifies a failure the SDK could not map to a modeled exception,
+ *    arriving as `name: 'Unknown'` with only a status;
+ * 4. any node's `name`, `code`, `errno` or `syscall` equals a token in
+ *    `retryableErrors`.
+ *
+ * The token match is exact, never substring: these fields are whole tokens, and
+ * a substring rule would let an unrelated name that merely contains one ride
+ * along.
+ *
+ * Throws: **nothing**, for any value a `throw` can produce — see
+ * {@link transientCancellation}, which the first rule reads through.
+ */
+export declare function isRetryableError(error: Error, retryableErrors: readonly string[]): boolean;
+/**
+ * Caller-facing retry tunables for every DynamoDB call an adapter makes. The
+ * schedule is full-jitter exponential backoff: `baseDelayMs` doubling per
+ * attempt, capped at `maxDelayMs`, for `maxAttempts` attempts. The
+ * message-append path never goes below its own contention floor.
+ */
+export interface RetryPolicy {
+    /** Attempts per call before `RETRY_EXHAUSTED` (default 5). */
+    maxAttempts?: number;
+    /** First backoff delay in milliseconds (default 100). */
+    baseDelayMs?: number;
+    /**
+     * Cap on a single backoff delay in milliseconds (default 5000, or
+     * `baseDelayMs` when that is given above it).
+     */
+    maxDelayMs?: number;
+}
+/**
+ * Resolve an adapter's retry policy once, at construction.
+ *
+ * Accepts: `policy` — the caller's, already validated, or nothing. `logger` —
+ * the adapter's resolved logger.
+ *
+ * Returns: the options every DynamoDB call of that adapter uses, with each
+ * field defaulted and the logger attached, so every retry is visible at `debug`
+ * (the attempt, the delay about to be slept, the error's name) instead of only
+ * surfacing once the budget is exhausted.
+ *
+ * Accepts: `attemptFloor` — the lowest attempt count this adapter will actually
+ * use, when it raises a caller's below its own. The budget is warned about at
+ * that number rather than at the caller's, because it is the one the writes
+ * will really spend; an adapter that honours the caller's count passes none.
+ *
+ * Throws: nothing; the policy was validated where it was given. A policy whose
+ * nominal budget outlives {@link MAX_WRITE_LIFETIME_MS} is warned about rather
+ * than refused, once per adapter constructed — three adapters built from one
+ * long policy each say so for themselves — see
+ * {@link warnIfOutlivesWriteLifetime}. The defaults are far inside it and say
+ * nothing.
+ */
+export declare function resolveRetryPolicy(policy: RetryPolicy | undefined, logger: Logger, attemptFloor?: number): RetryOptions;
+/**
+ * The context's retry options plus a per-call cancellation signal.
+ *
+ * Accepts: `context.retry` — the adapter's resolved policy. `signal` — the
+ * caller's, when the call takes one.
+ *
+ * Returns: the adapter's options untouched when there is no signal — the same
+ * object, so no per-call allocation on the common path — and a copy carrying it
+ * when there is.
+ *
+ * Throws: nothing.
+ */
+export declare function retryFor(context: {
+    retry?: RetryOptions;
+}, signal?: AbortSignal): RetryOptions | undefined;
+/**
+ * Wait `ms` milliseconds, cancellable.
+ *
+ * Accepts: `ms` — the delay. `signal` — omitted waits uninterruptibly; already
+ * aborted rejects before any timer is set; aborting while pending rejects at
+ * that moment and clears the timer.
+ *
+ * Returns: a promise resolving when the delay elapses.
+ *
+ * Throws: an `ABORTED` error however the signal was aborted —
+ * with a `DOMException`, a string or a custom reason (see
+ * {@link abortErrorFrom}).
+ *
+ * Guarantees: exactly one of resolve and reject runs, and neither the timer nor
+ * the abort listener outlives the call. The listener is attached before the
+ * timer is armed, so a signal whose `addEventListener` throws rejects the wait
+ * with nothing left behind — armed first, the timer outlived that rejection
+ * and later called `removeEventListener` outside any promise. A listener that
+ * runs while it is being attached settles the wait before any timer exists.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * The next exponential-backoff delay.
+ *
+ * Accepts: `currentMs` — the delay just used; at least 1, since doubling 0
+ * never grows. `maxMs` — the ceiling, default {@link MAX_BACKOFF_DELAY_MS}.
+ *
+ * Returns: `min(currentMs * 2, maxMs)`.
+ *
+ * Throws: nothing.
+ */
+export declare function nextBackoffDelay(currentMs: number, maxMs?: number): number;
+/**
+ * AWS's full jitter over a backoff delay.
+ *
+ * Accepts: `delayMs` — the unjittered delay. `rng` — a seam returning
+ * `[0, 1)`, default `Math.random`; tests inject a fixed one.
+ *
+ * Returns: a value in `[0, delayMs)`, so two clients retrying the same failure
+ * do not retry together
+ * (https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/).
+ *
+ * Throws: nothing.
+ */
+export declare function fullJitter(delayMs: number, rng?: () => number): number;
+/**
+ * Whether `error` is a transient S3 failure worth retrying.
+ *
+ * Accepts: `error` — any error, including one carrying no name or code, and
+ * equally anything else a `throw` can produce.
+ *
+ * Returns: {@link isRetryableError} over the shared default tokens, which hold
+ * S3's own transient names (`SlowDown`, `InternalError`,
+ * `ConditionalRequestConflict`) alongside DynamoDB's — one list, so the two
+ * services cannot drift apart on what is transient.
+ *
+ * Throws: **nothing**, for any value; {@link isRetryableError} is total.
+ */
+export declare function isTransientS3Error(error: Error): boolean;

package/dist/cjs/shared/dynamodb/retry.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WRITE_LIFETIME_MS = exports.TOKEN_IDEMPOTENCY_WINDOW_MS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.MAX_BACKOFF_DELAY_MS = exports.INITIAL_BACKOFF_DELAY_MS = void 0;
+exports.backoffCapMs = backoffCapMs;
+exports.withRetry = withRetry;
+exports.withDynamoDBRetry = withDynamoDBRetry;
+exports.isRetryableError = isRetryableError;
+exports.resolveRetryPolicy = resolveRetryPolicy;
+exports.retryFor = retryFor;
+exports.sleep = sleep;
+exports.nextBackoffDelay = nextBackoffDelay;
+exports.fullJitter = fullJitter;
+exports.isTransientS3Error = isTransientS3Error;
+const clock_js_1 = require("../clock.js");
+const base_error_js_1 = require("../errors/base-error.js");
+const classify_js_1 = require("../errors/classify.js");
+const errors_js_1 = require("../errors/errors.js");
+const secret_patterns_js_1 = require("../logging/secret-patterns.js");
+const truncate_js_1 = require("../logging/truncate.js");
+const abort_js_1 = require("./abort.js");
+const cancellation_js_1 = require("./cancellation.js");
+exports.INITIAL_BACKOFF_DELAY_MS = 100;
+exports.MAX_BACKOFF_DELAY_MS = 5000;
+exports.DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+exports.TOKEN_IDEMPOTENCY_WINDOW_MS = 600_000;
+exports.MAX_WRITE_LIFETIME_MS = 300_000;
+function crossesDeadline(deadlineAt, delayMs) {
+    return deadlineAt !== undefined && (0, clock_js_1.nowMs)() + delayMs >= deadlineAt;
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted)
+        throw (0, abort_js_1.abortErrorFrom)(signal);
+}
+function delayForAttempt(attempt, base, max, rng) {
+    const exponential = base * 2 ** (attempt - 1);
+    return fullJitter(Math.min(exponential, max), rng);
+}
+function backoffCapMs(baseDelayMs, maxDelayMs) {
+    return maxDelayMs ?? Math.max(exports.MAX_BACKOFF_DELAY_MS, baseDelayMs);
+}
+function resolveRetryOptions(options) {
+    const baseDelayMs = options.baseDelayMs ?? exports.INITIAL_BACKOFF_DELAY_MS;
+    return {
+        maxAttempts: options.maxAttempts ?? exports.DEFAULT_RETRY_MAX_ATTEMPTS,
+        baseDelayMs,
+        maxDelayMs: backoffCapMs(baseDelayMs, options.maxDelayMs),
+        isRetryable: options.isRetryable ??
+            ((error) => isRetryableError(error, options.retryableErrors ?? classify_js_1.DEFAULT_RETRYABLE_ERRORS)),
+        rng: options.rng ?? Math.random,
+    };
+}
+async function withRetry(fn, options = {}) {
+    const { maxAttempts, baseDelayMs, maxDelayMs, isRetryable, rng } = resolveRetryOptions(options);
+    assertNotAborted(options.signal);
+    const request = { abortSignal: options.signal };
+    let lastError = new Error('Retry failed without error');
+    let attempts = 0;
+    let mayStillLand = false;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        attempts = attempt;
+        try {
+            return await fn(request);
+        }
+        catch (error) {
+            assertNotAborted(options.signal);
+            lastError = (0, base_error_js_1.toError)(error);
+            if ((0, classify_js_1.mayStillBeInFlight)(lastError))
+                mayStillLand = true;
+            if (!isRetryable(lastError))
+                throw mayStillLand ? (0, errors_js_1.markMayStillLand)(lastError) : lastError;
+            if (attempt === maxAttempts)
+                break;
+            const delayMs = delayForAttempt(attempt, baseDelayMs, maxDelayMs, rng);
+            if (crossesDeadline(options.deadlineAt, delayMs))
+                break;
+            options.onRetry?.({ attempt, delayMs, error: lastError });
+            await sleep(delayMs, options.signal);
+        }
+    }
+    throw (0, errors_js_1.retryExhaustedError)(`Operation failed after ${attempts} attempts: ${(0, secret_patterns_js_1.redactedMessage)(lastError)}`, attempts, lastError, mayStillLand);
+}
+async function withDynamoDBRetry(fn, overrides) {
+    return withRetry(fn, { maxAttempts: exports.DEFAULT_RETRY_MAX_ATTEMPTS, ...overrides });
+}
+function recordNode(fields, evidence) {
+    for (const value of [fields.name, fields.code, fields.errno, fields.syscall]) {
+        if (typeof value === 'string')
+            evidence.signals.push(value);
+    }
+    if (typeof fields.$metadata?.httpStatusCode === 'number') {
+        evidence.statuses.push(fields.$metadata.httpStatusCode);
+    }
+    const byTrait = fields.$retryable !== undefined && fields.$retryable !== null;
+    if (byTrait || (0, classify_js_1.isCorrectedClockSkew)(fields))
+        evidence.retryableByTrait = true;
+}
+function collectEvidence(error) {
+    const seen = new WeakSet();
+    const evidence = { signals: [], statuses: [], retryableByTrait: false };
+    const walk = (node, depth) => {
+        if (depth > classify_js_1.MAX_CAUSE_DEPTH || node === null || typeof node !== 'object' || seen.has(node)) {
+            return;
+        }
+        seen.add(node);
+        const fields = node;
+        recordNode(fields, evidence);
+        if (fields.cause)
+            walk(fields.cause, depth + 1);
+    };
+    walk(error, 0);
+    return evidence;
+}
+function isRetryableError(error, retryableErrors) {
+    const cancellation = (0, cancellation_js_1.transientCancellation)(error);
+    if (cancellation !== undefined)
+        return cancellation;
+    const evidence = collectEvidence(error);
+    if (evidence.retryableByTrait)
+        return true;
+    if (evidence.statuses.some((status) => classify_js_1.TRANSIENT_HTTP_STATUSES.includes(status)))
+        return true;
+    return evidence.signals.some((signal) => retryableErrors.includes(signal));
+}
+function nominalBudgetMs(policy) {
+    let total = 0;
+    for (let sleep = 1; sleep < policy.maxAttempts; sleep++) {
+        total += Math.min(policy.baseDelayMs * 2 ** (sleep - 1), policy.maxDelayMs);
+    }
+    return total;
+}
+function warnIfOutlivesWriteLifetime(policy, logger) {
+    const budgetMs = nominalBudgetMs(policy);
+    if (budgetMs <= exports.MAX_WRITE_LIFETIME_MS)
+        return;
+    logger.warn('retry policy outlives the write lifetime; the budget will be cut short', {
+        budgetMs,
+        maxWriteLifetimeMs: exports.MAX_WRITE_LIFETIME_MS,
+    });
+}
+function resolveRetryPolicy(policy, logger, attemptFloor = 0) {
+    const baseDelayMs = policy?.baseDelayMs ?? exports.INITIAL_BACKOFF_DELAY_MS;
+    const resolved = {
+        maxAttempts: policy?.maxAttempts ?? exports.DEFAULT_RETRY_MAX_ATTEMPTS,
+        baseDelayMs,
+        maxDelayMs: backoffCapMs(baseDelayMs, policy?.maxDelayMs),
+    };
+    warnIfOutlivesWriteLifetime({ ...resolved, maxAttempts: Math.max(resolved.maxAttempts, attemptFloor) }, logger);
+    return {
+        ...resolved,
+        onRetry: ({ attempt, delayMs, error }) => logger.debug('retrying after a transient error', {
+            attempt,
+            delayMs,
+            error: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(error)),
+        }),
+    };
+}
+function retryFor(context, signal) {
+    return signal === undefined ? context.retry : { ...context.retry, signal };
+}
+function sleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject((0, abort_js_1.abortErrorFrom)(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const wait = { settled: false };
+        const onAbort = () => {
+            if (wait.settled)
+                return;
+            wait.settled = true;
+            clearTimeout(wait.timer);
+            reject((0, abort_js_1.abortErrorFrom)(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (wait.settled)
+            return;
+        wait.timer = setTimeout(() => {
+            if (wait.settled)
+                return;
+            wait.settled = true;
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+    });
+}
+function nextBackoffDelay(currentMs, maxMs = exports.MAX_BACKOFF_DELAY_MS) {
+    return Math.min(currentMs * 2, maxMs);
+}
+function fullJitter(delayMs, rng = Math.random) {
+    return rng() * delayMs;
+}
+function isTransientS3Error(error) {
+    return isRetryableError(error, classify_js_1.DEFAULT_RETRYABLE_ERRORS);
+}

package/dist/cjs/shared/dynamodb/row-size.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hides how DynamoDB measures a row against its 400 KB item limit.
+ *
+ * DynamoDB does not measure a row by its JSON length: every attribute name
+ * counts, a number costs a byte per two significant digits and one more,
+ * binary counts its raw bytes, and a list or a map adds three bytes and one
+ * per element. A write that would cross the limit is refused here, by those
+ * rules, before anything is sent, so the caller learns which input made the
+ * row too large instead of reading an `AWS_REJECTED` error after the work that
+ * built the row — an embedding, an upload — was already done.
+ */
+import type { AttributeMap } from './client.js';
+/** DynamoDB's cap on one item, 400 KB, in the binary kilobytes its documentation counts in. */
+export declare const MAX_ROW_BYTES: number;
+/**
+ * The size DynamoDB counts a row at against its item limit.
+ *
+ * Accepts: `row` — a row this package is about to write, as the document
+ * client would marshall it: strings, numbers, booleans, `null`, binary,
+ * arrays and plain objects, nested to any depth. An `undefined` attribute is
+ * counted as one byte although the client drops it, which only errs high.
+ *
+ * Returns: the sum, over every attribute, of its name's UTF-8 bytes and its
+ * value's size: a string's UTF-8 bytes; a number's significant digits halved
+ * and rounded up, plus one; binary's raw bytes; one byte for a boolean or a
+ * null; and for a list or a map three bytes, plus each element's size and one
+ * byte per element, a map's element also paying its name. The rules are
+ * AWS's own
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html).
+ *
+ * Throws: nothing.
+ */
+export declare function rowSizeBytes(row: AttributeMap): number;

package/dist/cjs/shared/dynamodb/row-size.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ROW_BYTES = void 0;
+exports.rowSizeBytes = rowSizeBytes;
+exports.MAX_ROW_BYTES = 400 * 1024;
+function nameBytes(name) {
+    return Buffer.byteLength(name, 'utf8');
+}
+function significantDigits(value) {
+    const mantissa = String(Math.abs(value)).split(/e/i)[0].replace('.', '');
+    const trimmed = mantissa.replace(/^0+/, '').replace(/0+$/, '');
+    return Math.max(trimmed.length, 1);
+}
+function valueBytes(value) {
+    if (typeof value === 'string')
+        return Buffer.byteLength(value, 'utf8');
+    if (typeof value === 'number')
+        return Math.ceil(significantDigits(value) / 2) + 1;
+    if (typeof value === 'boolean' || value === null || value === undefined)
+        return 1;
+    if (ArrayBuffer.isView(value))
+        return value.byteLength;
+    if (Array.isArray(value)) {
+        return value.reduce((sum, element) => sum + valueBytes(element) + 1, 3);
+    }
+    return Object.entries(value).reduce((sum, [name, element]) => sum + nameBytes(name) + valueBytes(element) + 1, 3);
+}
+function rowSizeBytes(row) {
+    return Object.entries(row).reduce((sum, [name, value]) => sum + nameBytes(name) + valueBytes(value), 0);
+}