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

package/dist/shared/dynamodb/recency-index.js

@@ -0,0 +1,377 @@
+"use strict";
+/**
+ * Hides the recency index (record 8).
+ *
+ * A row that a cross-partition listing reaches carries two index keys: a
+ * partition that hashes its identity onto one of a fixed number of shards, and
+ * a sort key that orders it by time. A listing reads every shard at once,
+ * merges them newest first, and hands out an opaque cursor that resumes the
+ * merge. The shard function, the key format and the merge are decided here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INDEX_SHARDS = exports.DEFAULT_INDEX_SHARDS = exports.BACKFILLED_AT = void 0;
+exports.queryRecencyIndex = queryRecencyIndex;
+exports.iterateRecencyIndex = iterateRecencyIndex;
+exports.backfilledAt = backfilledAt;
+exports.indexKeys = indexKeys;
+exports.indexPartitions = indexPartitions;
+exports.shardReader = shardReader;
+exports.readShardPage = readShardPage;
+const concurrency_1 = require("../concurrency");
+const errors_1 = require("../errors/errors");
+const primitives_1 = require("../validation/primitives");
+const paginate_1 = require("./paginate");
+const retry_1 = require("./retry");
+const table_schema_1 = require("./table-schema");
+/**
+ * A cursor is the sort key of the last row handed out.
+ *
+ * That is all it needs to be: `gsi1sk` is `<timestamp>#<id>`, which is unique
+ * and totally ordered, so the next page is simply "everything below this". It
+ * is also why the cursor is not a `LastEvaluatedKey` — one per shard would have
+ * to be carried, and a shard count change would silently invalidate them.
+ * Opaque to the caller all the same: its shape is not a promise.
+ *
+ * The key handed here is always the last row {@link takeNewest} chose, and
+ * that is the only reason the cursor is sound: the merge hands rows out in
+ * descending {@link compareSortKeys} order, so the last one is the smallest
+ * key on the page in the server's own order, which is exactly what
+ * `#sk < :before` resumes below. There is no second comparison to keep in step
+ * — one comparator decides the order, and the cursor is a row it chose.
+ */
+function encodeCursor(sortKey) {
+    return Buffer.from(sortKey, 'utf8').toString('base64url');
+}
+/**
+ * The sort key a cursor encodes.
+ *
+ * Accepts: `cursor` — as a previous page returned it.
+ *
+ * Returns: the `gsi1sk` to resume below.
+ *
+ * Throws: `VALIDATION` naming `cursor` when the decoded value carries no
+ * `#`. `gsi1sk` is `<timestamp>#<id>`, so such a value was issued by something
+ * else — a scan cursor, a page token from another API — and using it as a bound
+ * would quietly return the wrong page rather than say so. A value that carries
+ * a `#` is not checked further.
+ */
+function decodeCursor(cursor) {
+    const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+    if (!decoded.includes('#')) {
+        throw (0, errors_1.validationError)('cursor is not one this adapter issued', 'cursor');
+    }
+    return decoded;
+}
+/** A shard with no row to offer that may still hold one. */
+function isDry(reader) {
+    return reader.buffer.length === 0 && !reader.exhausted;
+}
+/**
+ * Read the next page of every dry shard, at most `concurrency` at once, until
+ * no shard is dry. A page can hold no rows and still carry a key, and a shard
+ * in that state may hold the newest row of all, so choosing a row before it is
+ * read again could put an older row on the page first.
+ *
+ * The loop carries no iteration cap of its own, and that is a decision rather
+ * than an omission. Every pass calls {@link readShardPage} on every dry shard,
+ * and that call either advances the shard or, once the shard has read
+ * `MAX_LOOP_ITERATIONS` pages, throws `RESULT_TRUNCATED` without issuing a
+ * query — so a shard that answers with empty pages forever ends the listing
+ * there. A second cap here could only ever fire after that one, which makes it
+ * a branch no test could reach: {@link mapWithConcurrency}'s own floor (in
+ * `shared/concurrency.ts`) never starts zero workers, even for a
+ * non-integer or zero `concurrency`, so a pass here always advances at least
+ * one dry shard or reads nothing because none is dry. A collaborator that
+ * could silently spin without reading anything belongs fixed at that floor,
+ * not papered over by a cap here.
+ */
+async function refillDryShards(options, readers, before, needed) {
+    for (let dry = readers.filter(isDry); dry.length > 0; dry = readers.filter(isDry)) {
+        await (0, concurrency_1.mapWithConcurrency)(dry, options.concurrency, (reader) => readShardPage(options, reader, before, needed));
+    }
+}
+/**
+ * Move the newest buffered row off its shard; undefined when every buffer is
+ * empty.
+ *
+ * "Newest" is {@link compareSortKeys}, not `>`: the row this picks is the one
+ * the resumed `#sk < :before` query will agree is newest, and the two orders
+ * part company at an astral id. `''` is a safe starting bound because a
+ * DynamoDB key attribute is never the empty string, so no row can lose to it.
+ */
+function takeNewest(readers) {
+    let newest;
+    let newestKey = '';
+    for (const reader of readers) {
+        const head = reader.buffer[reader.buffer.length - 1];
+        if (head !== undefined && (0, table_schema_1.compareSortKeys)(head.gsi1sk, newestKey) > 0) {
+            newest = reader;
+            newestKey = head.gsi1sk;
+        }
+    }
+    return newest?.buffer.pop();
+}
+/**
+ * Read one page of a recency listing from the index, newest first.
+ *
+ * Each shard is read one DynamoDB page at a time and the pages are merged row
+ * by row: the newest buffered row goes onto the page, and a shard whose buffer
+ * runs dry reads its next page before another row is chosen. That is correct
+ * because each shard is already sorted and no row is chosen while a shard that
+ * may hold a newer one is unread. It is also what bounds memory: a listing
+ * holds the page it is building, up to `limit` rows, plus at most one DynamoDB
+ * page per shard, and a shard none of whose buffered rows the page takes is
+ * never followed. The price is that a dry shard is read again whenever the page
+ * still needs a row, even when every row still to come is another shard's,
+ * which can cost a query per shard per page whose rows the page never takes.
+ * The alternative — one query over an unsharded index — would make every
+ * listing hit one partition, which is what the sharding exists to avoid.
+ *
+ * This replaces a full-table `Scan` with a `FilterExpression`, which consumed
+ * read capacity for every row *evaluated*, collected the whole table in memory
+ * and sorted it there.
+ *
+ * Accepts: `limit` — a `PageLimit`, already checked against the package-wide
+ * page rule by the caller's parser. `0` returns an empty page with no cursor
+ * and issues no query — and is answered here rather than left to the merge,
+ * where an empty page with shards still unread would have read
+ * `items[items.length - 1]` off an empty array to build the cursor. `cursor`
+ * — from a previous page, or none to start at the newest. `shards` — must
+ * match what the writers used. `concurrency` — how many shards are queried at
+ * once.
+ *
+ * Returns: the page, newest first, and a `nextCursor` exactly while rows may
+ * remain: a shard still buffers a row the page did not take, or has not
+ * reported its end. A cursor is never withheld while rows remain, and none is
+ * issued once every shard has reported its end, even for a page filled
+ * exactly. DynamoDB can still report a `LastEvaluatedKey` on a page that ends
+ * at a shard's last row, so the page after such a cursor may come back empty.
+ *
+ * Throws: `VALIDATION` naming `cursor`; `RESULT_TRUNCATED`
+ * for a shard whose pages do not end within `MAX_LOOP_ITERATIONS`; whatever
+ * the queries throw, including an `ABORTED` error.
+ *
+ * Guarantees: at most `concurrency` shards are queried at once; each shard is
+ * followed across DynamoDB's 1 MB page boundary, but its next page is read only
+ * when its buffer is empty and the page still needs a row, so besides the page
+ * being built, up to `limit` rows, no more than one DynamoDB page per shard is
+ * held at a time.
+ */
+async function queryRecencyIndex(options) {
+    if (options.limit === 0)
+        return { items: [] };
+    const before = options.cursor === undefined ? undefined : decodeCursor(options.cursor);
+    const readers = indexPartitions(options.tag, options.shards).map((partition) => shardReader(partition));
+    const items = [];
+    while (items.length < options.limit) {
+        await refillDryShards(options, readers, before, options.limit - items.length);
+        const row = takeNewest(readers);
+        if (row === undefined)
+            break;
+        items.push(row);
+    }
+    // Rows remain when a shard still buffers a row or has not reported its end.
+    // Either way the loop stopped on a full page, so the page is non-empty and
+    // its last row is the right place to resume.
+    const remain = readers.some((reader) => reader.buffer.length > 0 || !reader.exhausted);
+    return {
+        items,
+        ...(remain ? { nextCursor: encodeCursor(items[items.length - 1].gsi1sk) } : {}),
+    };
+}
+/** Rows per page when a caller streams the whole index rather than paging it. */
+const STREAM_PAGE_SIZE = (0, primitives_1.parseLimit)(100, 0);
+/**
+ * Every row of one adapter's recency index, newest first, page by page.
+ *
+ * The streaming counterpart of {@link queryRecencyIndex}, for a caller that
+ * consumes rows until it has what it needs and then stops. It replaces a
+ * full-table `Scan` whose cost scaled with the table rather than with the
+ * answer.
+ *
+ * Accepts: as {@link queryRecencyIndex}, without `limit` and `cursor` — this
+ * walks the whole index, paging internally.
+ *
+ * Returns: an async generator over every row, newest first. An early `break`
+ * fetches no further page, so a caller that needs ten rows of a large index
+ * pays for one page.
+ *
+ * Throws: as {@link queryRecencyIndex}.
+ */
+async function* iterateRecencyIndex(options) {
+    let cursor;
+    do {
+        const page = await queryRecencyIndex({ ...options, limit: STREAM_PAGE_SIZE, cursor });
+        for (const item of page.items)
+            yield item;
+        cursor = page.nextCursor;
+    } while (cursor !== undefined);
+}
+/** The time a row that recorded none is indexed at, older than anything indexed since. */
+exports.BACKFILLED_AT = '1970-01-01T00:00:00.000Z';
+/**
+ * The time a backfilled row is indexed at.
+ *
+ * Accepts: `recorded` — the row's own time attribute, whatever it holds.
+ *
+ * Returns: that time when it is a string, else {@link BACKFILLED_AT}.
+ *
+ * Throws: nothing.
+ */
+function backfilledAt(recorded) {
+    return typeof recorded === 'string' ? recorded : exports.BACKFILLED_AT;
+}
+/** Default number of index partitions per adapter. */
+exports.DEFAULT_INDEX_SHARDS = 8;
+/**
+ * The most shards a recency index may have. The indexed read builds every
+ * shard's partition key and issues at least one query per shard, so an
+ * unbounded value turns a config typo into an unbounded stream of requests and
+ * an out-of-memory crash. How many of those queries run at once is
+ * `readConcurrency`.
+ */
+exports.MAX_INDEX_SHARDS = 1024;
+/**
+ * A stable 32-bit FNV-1a hash of `value`.
+ *
+ * Deterministic and dependency-free, which is what a shard assignment needs: a
+ * row's index entry must be findable and deletable without a scan, so the same
+ * id must always map to the same shard — across processes, releases and
+ * machines. A cryptographic hash would cost more per write for a property
+ * nothing here depends on.
+ */
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+/** Refuse a shard count that would make the index unusable in either direction. */
+function assertShardCount(shards) {
+    if (!Number.isInteger(shards) || shards < 1) {
+        throw (0, errors_1.validationError)(`indexShards must be a positive integer (received ${shards}); a non-positive value would ` +
+            'make every row share one index partition or produce an unusable key', 'indexShards');
+    }
+}
+/**
+ * The GSI1 keys for a row that takes part in cross-partition listing.
+ *
+ * The partition key is the adapter tag plus a shard, because an index keyed by
+ * the tag alone is one partition per adapter — a single hot partition, which is
+ * worse than the table scan it replaces. AWS names the sharding requirement
+ * directly: mapping one identifier onto one partition key "will quickly create
+ * partition hot spots", and the answer is a secondary sharding model
+ * (https://docs.aws.amazon.com/whitepapers/latest/multi-tenant-saas-storage-strategies/multitenancy-on-dynamodb.html).
+ *
+ * The sort key leads with an ISO-8601 timestamp, used unparsed: its byte order
+ * already is its chronological order, so a recency listing is a key condition
+ * rather than an in-memory sort. The row's own id follows it, which makes the
+ * key total — two rows written in the same millisecond still order, so a cursor
+ * can never loop.
+ *
+ * Accepts: `tag` — the adapter's. `id` — the row's own identifier, which
+ * decides its shard and breaks ties in the sort key. `at` — an ISO-8601
+ * instant. `shards` — index partitions per adapter, at least 1; fixed at table
+ * creation, since changing it changes every row's shard and requires a
+ * backfill.
+ *
+ * Returns: the two index attributes.
+ *
+ * Throws: `VALIDATION` naming `indexShards` for a count below 1 — the read
+ * side built an empty partition list from such a value and reported an empty
+ * table full of rows.
+ *
+ * Guarantees: the same row always lands on the same shard, so a listing that
+ * queries every shard sees every row exactly once.
+ */
+function indexKeys(tag, id, at, shards) {
+    assertShardCount(shards);
+    return {
+        gsi1pk: `${tag}#${fnv1a(id) % shards}`,
+        gsi1sk: `${at}#${id}`,
+    };
+}
+/**
+ * Every index partition of one adapter.
+ *
+ * Accepts: `shards` — the same count the rows were written with; validated
+ * here as it is in {@link indexKeys}, because a listing that silently queried
+ * an empty partition list would return nothing for a table full of rows.
+ *
+ * Returns: one partition key per shard, which a recency listing queries in
+ * parallel and merges.
+ *
+ * Throws: `VALIDATION` naming `indexShards`.
+ */
+function indexPartitions(tag, shards) {
+    assertShardCount(shards);
+    return Array.from({ length: shards }, (_unused, shard) => `${tag}#${shard}`);
+}
+/**
+ * A reader placed before a shard's first page.
+ *
+ * Accepts: `partition` — the shard's index partition key.
+ *
+ * Returns: a reader with an empty buffer that is not exhausted, so a listing
+ * reads its first page before choosing any row.
+ *
+ * Throws: nothing.
+ */
+function shardReader(partition) {
+    return { partition, buffer: [], startKey: undefined, exhausted: false, pages: 0 };
+}
+/** The `Query` for one page of one shard. */
+function shardQuery(options, reader, before, limit) {
+    return {
+        TableName: options.tableName,
+        IndexName: options.indexName,
+        KeyConditionExpression: before === undefined ? '#pk = :pk' : '#pk = :pk AND #sk < :before',
+        ExpressionAttributeNames: {
+            '#pk': 'gsi1pk',
+            ...(before === undefined ? {} : { '#sk': 'gsi1sk' }),
+        },
+        ExpressionAttributeValues: {
+            ':pk': reader.partition,
+            ...(before === undefined ? {} : { ':before': before }),
+        },
+        ScanIndexForward: false,
+        Limit: limit,
+        ...(reader.startKey === undefined ? {} : { ExclusiveStartKey: reader.startKey }),
+    };
+}
+/**
+ * Read a shard's next DynamoDB page into its buffer.
+ *
+ * `Limit` bounds the items a `Query` *evaluates*, and a page also stops at
+ * 1 MB, so a shard of large rows answers with fewer than `limit` items and a
+ * `LastEvaluatedKey`. Taking that short page as the whole shard would drop
+ * rows and report the listing complete. The key is kept here
+ * instead, and the listing reads the next page once the shard's buffer is empty
+ * and its page still needs a row. One page at a time is what bounds a listing's
+ * memory to at most one DynamoDB page per shard, besides the page it is
+ * building.
+ *
+ * Accepts: `reader` — its buffer empty and the shard not exhausted. `before` —
+ * the sort key to read below, or none for the newest. `limit` — the rows the
+ * listing's page still needs, at least 1; the shard cannot contribute more.
+ *
+ * Returns: nothing. The reader's buffer holds the page's rows, and its key,
+ * `exhausted` and page count describe what is left.
+ *
+ * Throws: `RESULT_TRUNCATED` naming `maxIterations`, without issuing
+ * a query, when the shard has already read {@link MAX_LOOP_ITERATIONS} pages —
+ * a listing fails rather than hand back a partial shard; whatever the query
+ * throws, including an `ABORTED` error.
+ */
+async function readShardPage(options, reader, before, limit) {
+    if (reader.pages >= paginate_1.MAX_LOOP_ITERATIONS) {
+        throw (0, errors_1.resultTruncatedError)('maxIterations', paginate_1.MAX_LOOP_ITERATIONS);
+    }
+    const result = await (0, retry_1.withDynamoDBRetry)((request) => options.client.query(shardQuery(options, reader, before, limit), request), { ...options.retry, signal: options.signal });
+    reader.pages += 1;
+    reader.buffer = (result.Items ?? []).slice().reverse();
+    reader.startKey = result.LastEvaluatedKey;
+    reader.exhausted = reader.startKey === undefined;
+}

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

@@ -1,18 +1,286 @@
-/** Options controlling {@link withRetry}. */
+/**
+ * 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';
+/** 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;
 }
 /**
- * Run `fn`, retrying retryable transient errors with full-jitter exponential
- * backoff. Non-retryable errors are re-thrown unchanged; exhaustion throws
- * {@link RetryExhaustedError}; an aborted signal throws {@link AbortError}.
+ * 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. `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.
+ *
+ * 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 least once and at most `maxAttempts` times. 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;
+ * 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). */
+    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 withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
-/** {@link withRetry} preset for DynamoDB operations. */
-export declare function withDynamoDBRetry<T>(fn: () => Promise<T>, overrides?: Partial<RetryOptions>): Promise<T>;
-//# sourceMappingURL=retry.d.ts.map
+export declare function isTransientS3Error(error: Error): boolean;