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

package/dist/shared/dynamodb/cancellation.js

@@ -1,8 +1,152 @@
 "use strict";
+/**
+ * Hides how a cancelled transaction says why it failed.
+ *
+ * A `TransactionCanceledException` carries one raw reason per item, in the
+ * order the items were sent, under codes that are not the exception names the
+ * same failures carry outside a transaction. Which reason is a guard
+ * rejection, which are transient or throttling, and which item failed its
+ * condition are read here and nowhere else, so the retry layer, the error
+ * classifier and the writers that act on a rejection cannot read one apart.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCancellationReasons = getCancellationReasons;
-/** Extract `CancellationReasons` from a transaction-cancellation error, if present. */
+exports.conditionalCheckFailure = conditionalCheckFailure;
+exports.transientCancellation = transientCancellation;
+exports.throttledCancellation = throttledCancellation;
+exports.conditionFailedAt = conditionFailedAt;
+/** The reason code an item that was not the cause carries. */
+const NOT_THE_CAUSE = 'None';
+/**
+ * The reason code a guard rejection arrives under inside a transaction. It is
+ * *not* the exception name the same rejection carries outside one
+ * (`ConditionalCheckFailedException`); the two strings are neither
+ * interchangeable nor prefixes to test for.
+ */
+const CONDITION_FAILED = 'ConditionalCheckFailed';
+/**
+ * The per-item reasons a `TransactWriteItems` cancellation carries.
+ *
+ * Accepts: `error` — any error; only a `TransactionCanceledException` carries
+ * the field.
+ *
+ * Its parameter is the weak {@link RejectionFields} rather than `Error`, which
+ * is a deliberate trade: `{}` and `{ name }` now compile where they did not,
+ * and in exchange this module stays the only place that dereferences
+ * `CancellationReasons`, so {@link conditionalCheckFailure}, the retry
+ * classifier and the two history readers cannot drift apart in how they read
+ * it. Every value that reaches it at runtime comes from a `catch`; the two
+ * call sites inside this package that pass it along rather than an `Error`
+ * ({@link conditionalCheckFailure} and `isConditionalCheckFailed`) received
+ * one from a `catch` themselves.
+ *
+ * Returns: one entry per transaction item, in the order the items were sent
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html),
+ * or `undefined` when the error carries none — which is what an older service
+ * response, a different failure, or a thrown value that is not an object at
+ * all looks like.
+ *
+ * Throws: **nothing**, for any value a `throw` can produce. Every value that
+ * reaches this came from a `catch`, and `null` is one a `catch` can bind: the
+ * property read raised a `TypeError` there, inside the classification the
+ * retry layer makes before it decides whether to try again.
+ */
 function getCancellationReasons(error) {
-    return error.CancellationReasons;
+    return error?.CancellationReasons;
+}
+/**
+ * The reason belonging to the one item a transaction's guard turned away.
+ *
+ * A cancellation names every item, so "was this write rejected by its
+ * condition?" is only answerable once the items that were merely along for the
+ * ride are set aside. What must remain is a single cause, and it must be the
+ * condition: a cancellation that also failed a second item for its own reason
+ * is not a guard rejection, and reporting one would hide the other failure.
+ *
+ * A reason carrying no `Code` counts as a cause here, while the retry
+ * classifier treats that same shape as transient. The disagreement is
+ * deliberate, because the two readers are conservative in opposite directions:
+ * for the classifier, an unreadable reason may be retried, which a request
+ * token makes harmless; here it must **not** be read as a clean rejection,
+ * since acting on one discards whatever else the transaction failed on. AWS
+ * populates `Code` for every item, so neither branch is reachable in practice.
+ *
+ * Accepts: `error` — any error; only a cancellation carries reasons.
+ *
+ * Returns: the sole `ConditionalCheckFailed` reason — with the rejected row
+ * attached when the item asked for it — or `undefined` for every other error,
+ * including a cancellation with no reasons, a different cause, or more than
+ * one.
+ *
+ * Throws: nothing.
+ */
+function conditionalCheckFailure(error) {
+    const reasons = getCancellationReasons(error) ?? [];
+    const causes = reasons.filter((reason) => reason.Code !== NOT_THE_CAUSE);
+    return causes.length === 1 && causes[0].Code === CONDITION_FAILED ? causes[0] : undefined;
+}
+/**
+ * Cancellation reason codes (from a `TransactionCanceledException`'s
+ * `CancellationReasons`) that are transient and safe to retry. `None` marks an
+ * item that was not the cause and is ignored.
+ */
+const TRANSIENT_CANCELLATION_REASONS = [
+    'None',
+    'TransactionConflict',
+    'ThrottlingError',
+    'ProvisionedThroughputExceeded',
+];
+/**
+ * Whether a cancelled transaction failed only for transient reasons.
+ *
+ * Accepts: `error` — any error; only a cancellation carries reasons.
+ *
+ * Returns: `undefined` when the error carries no reasons, so the caller's
+ * ordinary signal matching applies; otherwise whether every reason is
+ * transient. A cancellation carrying no reasons at all is not transient.
+ *
+ * Throws: nothing, for any value; see {@link getCancellationReasons}.
+ */
+function transientCancellation(error) {
+    const reasons = getCancellationReasons(error);
+    if (!reasons)
+        return undefined;
+    // `length > 0` is load-bearing: `.every()` is vacuously true on an empty
+    // array, which would make a reason-less cancellation retryable — the exact
+    // opposite of what this function documents. AWS populates one reason per
+    // `TransactItems` entry, so an empty array should not occur; if it ever
+    // does, the conservative answer is not to retry.
+    return (reasons.length > 0 &&
+        reasons.every((reason) => reason.Code === undefined || TRANSIENT_CANCELLATION_REASONS.includes(reason.Code)));
+}
+/** Cancellation reason codes that mean the request was throttled. */
+const THROTTLING_REASONS = ['ThrottlingError', 'ProvisionedThroughputExceeded'];
+/**
+ * Whether a cancelled transaction was throttled.
+ *
+ * Accepts: `error` — any error; only a cancellation carries reasons.
+ *
+ * Returns: true when any reason is a throttling reason. Meaningful only for a
+ * cancellation {@link transientCancellation} already found transient, which is
+ * the one place it is asked.
+ *
+ * Throws: nothing, for any value.
+ */
+function throttledCancellation(error) {
+    return (getCancellationReasons(error) ?? []).some((reason) => reason.Code !== undefined && THROTTLING_REASONS.includes(reason.Code));
+}
+/**
+ * Whether the item at `index` of a cancelled transaction failed its condition.
+ *
+ * Accepts: `error` — any error. `index` — the item's position in the
+ * `TransactItems` the caller sent; reasons come back in that order.
+ *
+ * Returns: true when that item's reason is `ConditionalCheckFailed`, whatever
+ * the other items' reasons are; false for anything that is not such a
+ * cancellation.
+ *
+ * Throws: nothing, for any value.
+ */
+function conditionFailedAt(error, index) {
+    return getCancellationReasons(error)?.[index]?.Code === CONDITION_FAILED;
 }
-//# sourceMappingURL=cancellation.js.map

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

@@ -1,21 +1,175 @@
+/**
+ * Hides the DynamoDB client: the part of the DocumentClient this package calls,
+ * the row shapes that part speaks, and how a client this package builds bounds
+ * each request.
+ *
+ * The structural type is what lets a caller inject any DocumentClient-shaped
+ * object, and it is public; the row shapes travel through every module that
+ * reads or writes a row; the construction is the one place a request timeout
+ * and a socket timeout are set, and the one place that knows whether the
+ * adapter owns the client it holds.
+ */
 import { DynamoDBClient, type DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
-import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+import { DynamoDBDocument, type NativeAttributeValue, type TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { Logger } from '../logging/logger';
+/**
+ * How long one request attempt may take on a client this library builds
+ * (10 seconds) before the SDK's request handler destroys it and rejects with a
+ * retryable `TimeoutError`. `MAX_WRITE_LIFETIME_MS`
+ * (`src/shared/dynamodb/retry.ts`) bounds how many attempts *start*; it is
+ * checked between them, so it can refuse to begin another wait and can never
+ * shorten the attempt already in flight. Without a handler timeout — every one
+ * of them defaults to 0 — a hung socket holds that attempt open forever and
+ * the write lifetime bounds nothing.
+ *
+ * Measured, not picked. Across the fan-out widths this package documents, the
+ * worst interval the handler itself saw — socket acquisition including the
+ * wait behind the agent's fifty sockets, connect, request write and
+ * time-to-first-response-header — was 0.92 s, at a thousand concurrent writes
+ * of 20 KB values, and ten seconds is roughly eleven times that. The asymmetry
+ * settles the close call: too large leaves one attempt hanging for at most ten
+ * seconds, which the write lifetime's own headroom absorbs, while too small
+ * turns a healthy wide fan-out into a retry storm.
+ */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+/**
+ * How long a socket may sit idle (5 seconds) on a client this library builds
+ * before the request handler destroys the request. Which error that surfaces
+ * as depends on when it fires: before response headers the handler's own
+ * rejection reaches the caller as a `TimeoutError`, while after them the call
+ * has already resolved and the destroy arrives through the response stream
+ * instead, as an `ECONNRESET` abort. Both are classified retryable, so either
+ * way a stalled transfer becomes a retry of this library's own. An idle timer
+ * rather than a deadline: activity in either direction resets it, so it bounds
+ * a transfer that has stalled and never one that is merely slow, and its clock
+ * starts at socket assignment rather than at request creation. What each
+ * client needs it *for* differs, so that belongs at each client's own call
+ * site rather than here.
+ *
+ * Not a tuning knob. The handler installs the socket listener immediately only
+ * below 6 000 ms; at or above that it defers registration by 3 000 ms and
+ * returns the deferral's timer id, which the handler's clear-on-resolve
+ * cancels when response headers arrive — so at 6 000 or more the field
+ * silently stops doing anything for every response that answers inside three
+ * seconds, which is the normal case. That is a fact about the request handler
+ * and about neither client. A unit assertion holds this value under that
+ * threshold so raising it fails loudly instead of disabling the only bound a
+ * stalled transfer has.
+ */
+export declare const DEFAULT_SOCKET_TIMEOUT_MS = 5000;
 /** A resolved DynamoDB client plus its ownership flag. */
 export interface ResolvedDynamoDBClient {
     ddbClient: DynamoDBClient | undefined;
-    client: DynamoDBDocument;
+    client: DynamoDBDocumentLike;
     ownsClient: boolean;
 }
 /** Options for {@link resolveDynamoDBClient}. */
 export interface ResolveClientOptions {
-    client?: DynamoDBDocument;
+    client?: DynamoDBDocumentLike;
     clientConfig?: DynamoDBClientConfig;
-    createClient?: (config: DynamoDBClientConfig) => DynamoDBClient;
 }
 /**
- * Resolve the DocumentClient for an adapter. An injected `client` is used as-is
- * and not owned; otherwise a client is built from `clientConfig` (via the
- * `createClient` seam) and owned, so the adapter destroys it on `destroy()`.
+ * The DocumentClient an adapter will use, and whether it owns it.
+ *
+ * Accepts: `client` — an injected DocumentClient, used as-is; `clientConfig` —
+ * what one is built from when no client is injected; `createClient` — the test
+ * seam that builds it. `assertBaseAdapterOptions` rejects an injected client
+ * given alongside either of the other two, so only one branch is ever taken.
+ *
+ * Returns: the document client, the raw client behind it when this call built
+ * one, and `ownsClient` — true only then. An injected client is never
+ * destroyed by `destroy()`; it may be shared with the caller's own code and
+ * with the other adapters.
+ *
+ * Throws: whatever the SDK constructor throws for an unusable config.
+ *
+ * Guarantees: a client this call builds gets `maxAttempts: 1` unless the config
+ * overrides it, so the SDK performs no retries of its own and this library's
+ * retry layer is the only one. It also gets a default request handler that
+ * bounds how long one attempt may run, which `maxAttempts` alone does not. A
+ * `requestHandler` in `clientConfig` replaces that default whole rather than
+ * merging with it — the documented escape hatch, and equally the documented
+ * way to give up the bound. An injected client keeps whatever it was built
+ * with — see {@link warnOnStackedRetries}.
  */
 export declare function resolveDynamoDBClient(options: ResolveClientOptions): ResolvedDynamoDBClient;
-//# sourceMappingURL=client.d.ts.map
+/**
+ * Warn once when an injected client keeps the SDK's own retries.
+ *
+ * Accepts: `client` — the caller's. A client that cannot report its setting —
+ * a stub, a mock, a future SDK shape — is left alone.
+ *
+ * Returns: nothing. Deliberately not awaited by its callers: it is a warning
+ * about a caller-supplied client, not a precondition for using it, so
+ * constructing an adapter stays free of I/O.
+ *
+ * Throws: nothing, ever. The SDK's own config resolution can reject, and a
+ * rejection here would surface as an unhandled rejection from a constructor
+ * that did nothing wrong.
+ *
+ * Guarantees: the SDK's retries run inside every attempt of this library's
+ * retry layer, so the budget the constants and README describe multiplies (5 ×
+ * 3 requests per operation at the SDK default) and a throttling event turns
+ * into a retry storm. Saying so once, at construction, is the only place the
+ * caller can act on it.
+ *
+ * The one gap a deadline cannot cover. A tokened write's budget is bounded by
+ * `MAX_WRITE_LIFETIME_MS`, but that bound is checked between attempts: it can
+ * refuse to start another wait, and it cannot shorten an attempt already in
+ * flight. An injected client that retries internally turns one of this
+ * library's attempts into several of its own, so the time spent inside a
+ * single attempt stops being bounded by anything this library sets — which is
+ * why the warning says to construct it with `maxAttempts: 1`.
+ *
+ * `maxAttempts: 1` is necessary but not sufficient. The per-attempt bound
+ * holds for an injected client only if it also carries its own request
+ * timeout: a client this library builds is given one
+ * ({@link resolveDynamoDBClient}), and an injected client is used exactly as
+ * handed over, so one without a handler timeout leaves a single attempt
+ * unbounded even with the SDK's retries switched off.
+ */
+export declare function warnOnStackedRetries(client: DynamoDBDocumentLike, logger: Logger): Promise<void>;
+/**
+ * A row, or a key, as the DocumentClient returns and takes it: attribute names
+ * mapped to values that nothing has checked yet. Each feature's row parser
+ * turns one into that feature's row type.
+ */
+export type AttributeMap = Record<string, NativeAttributeValue>;
+/** A BatchWriteItem PutRequest. */
+interface PutWriteRequest {
+    PutRequest: {
+        Item: AttributeMap;
+    };
+}
+/** A BatchWriteItem DeleteRequest. */
+interface DeleteWriteRequest {
+    DeleteRequest: {
+        Key: AttributeMap;
+    };
+}
+/** A single BatchWriteItem write request. */
+export type WriteRequest = PutWriteRequest | DeleteWriteRequest;
+/** One action of a `TransactWriteItems` request, as the document client takes it. */
+export type TransactAction = NonNullable<TransactWriteCommandInput['TransactItems']>[number];
+/**
+ * The DocumentClient surface this library uses, named by shape rather than by
+ * identity. A `DynamoDBDocument` satisfies it, and so does a client built from
+ * a different copy of `@aws-sdk/lib-dynamodb`.
+ *
+ * That second case is the reason it exists. A consumer pinned to an older SDK
+ * than this package depends on gets a second, newer copy nested under the
+ * package; naming `DynamoDBDocument` in an option type would name *that* copy,
+ * and the client the consumer built is then a different type with the same
+ * name — refused at compile time for a method this library never calls, on the
+ * injection path the documentation recommends. Injection always worked at
+ * runtime; only the compiler stood in the way.
+ *
+ * The members are the eight the runtime collaborator check already requires,
+ * pinned equal to that list by a test — a client this type accepts and the
+ * constructor then rejects, or the reverse, would be worse than either rule
+ * alone. Picking them off `DynamoDBDocument` keeps each signature the SDK's
+ * own, so the internals stay exactly as type-safe as they were and the
+ * signatures cannot drift from the SDK this package installs.
+ */
+export type DynamoDBDocumentLike = Pick<DynamoDBDocument, 'batchWrite' | 'delete' | 'get' | 'put' | 'query' | 'scan' | 'transactWrite' | 'update'>;
+export {};

package/dist/shared/dynamodb/client.js

@@ -1,19 +1,167 @@
 "use strict";
+/**
+ * Hides the DynamoDB client: the part of the DocumentClient this package calls,
+ * the row shapes that part speaks, and how a client this package builds bounds
+ * each request.
+ *
+ * The structural type is what lets a caller inject any DocumentClient-shaped
+ * object, and it is public; the row shapes travel through every module that
+ * reads or writes a row; the construction is the one place a request timeout
+ * and a socket timeout are set, and the one place that knows whether the
+ * adapter owns the client it holds.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SOCKET_TIMEOUT_MS = exports.DEFAULT_REQUEST_TIMEOUT_MS = void 0;
 exports.resolveDynamoDBClient = resolveDynamoDBClient;
+exports.warnOnStackedRetries = warnOnStackedRetries;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 /**
- * Resolve the DocumentClient for an adapter. An injected `client` is used as-is
- * and not owned; otherwise a client is built from `clientConfig` (via the
- * `createClient` seam) and owned, so the adapter destroys it on `destroy()`.
+ * How long one request attempt may take on a client this library builds
+ * (10 seconds) before the SDK's request handler destroys it and rejects with a
+ * retryable `TimeoutError`. `MAX_WRITE_LIFETIME_MS`
+ * (`src/shared/dynamodb/retry.ts`) bounds how many attempts *start*; it is
+ * checked between them, so it can refuse to begin another wait and can never
+ * shorten the attempt already in flight. Without a handler timeout — every one
+ * of them defaults to 0 — a hung socket holds that attempt open forever and
+ * the write lifetime bounds nothing.
+ *
+ * Measured, not picked. Across the fan-out widths this package documents, the
+ * worst interval the handler itself saw — socket acquisition including the
+ * wait behind the agent's fifty sockets, connect, request write and
+ * time-to-first-response-header — was 0.92 s, at a thousand concurrent writes
+ * of 20 KB values, and ten seconds is roughly eleven times that. The asymmetry
+ * settles the close call: too large leaves one attempt hanging for at most ten
+ * seconds, which the write lifetime's own headroom absorbs, while too small
+ * turns a healthy wide fan-out into a retry storm.
+ */
+exports.DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * How long a socket may sit idle (5 seconds) on a client this library builds
+ * before the request handler destroys the request. Which error that surfaces
+ * as depends on when it fires: before response headers the handler's own
+ * rejection reaches the caller as a `TimeoutError`, while after them the call
+ * has already resolved and the destroy arrives through the response stream
+ * instead, as an `ECONNRESET` abort. Both are classified retryable, so either
+ * way a stalled transfer becomes a retry of this library's own. An idle timer
+ * rather than a deadline: activity in either direction resets it, so it bounds
+ * a transfer that has stalled and never one that is merely slow, and its clock
+ * starts at socket assignment rather than at request creation. What each
+ * client needs it *for* differs, so that belongs at each client's own call
+ * site rather than here.
+ *
+ * Not a tuning knob. The handler installs the socket listener immediately only
+ * below 6 000 ms; at or above that it defers registration by 3 000 ms and
+ * returns the deferral's timer id, which the handler's clear-on-resolve
+ * cancels when response headers arrive — so at 6 000 or more the field
+ * silently stops doing anything for every response that answers inside three
+ * seconds, which is the normal case. That is a fact about the request handler
+ * and about neither client. A unit assertion holds this value under that
+ * threshold so raising it fails loudly instead of disabling the only bound a
+ * stalled transfer has.
+ */
+exports.DEFAULT_SOCKET_TIMEOUT_MS = 5_000;
+/**
+ * The DocumentClient an adapter will use, and whether it owns it.
+ *
+ * Accepts: `client` — an injected DocumentClient, used as-is; `clientConfig` —
+ * what one is built from when no client is injected; `createClient` — the test
+ * seam that builds it. `assertBaseAdapterOptions` rejects an injected client
+ * given alongside either of the other two, so only one branch is ever taken.
+ *
+ * Returns: the document client, the raw client behind it when this call built
+ * one, and `ownsClient` — true only then. An injected client is never
+ * destroyed by `destroy()`; it may be shared with the caller's own code and
+ * with the other adapters.
+ *
+ * Throws: whatever the SDK constructor throws for an unusable config.
+ *
+ * Guarantees: a client this call builds gets `maxAttempts: 1` unless the config
+ * overrides it, so the SDK performs no retries of its own and this library's
+ * retry layer is the only one. It also gets a default request handler that
+ * bounds how long one attempt may run, which `maxAttempts` alone does not. A
+ * `requestHandler` in `clientConfig` replaces that default whole rather than
+ * merging with it — the documented escape hatch, and equally the documented
+ * way to give up the bound. An injected client keeps whatever it was built
+ * with — see {@link warnOnStackedRetries}.
  */
 function resolveDynamoDBClient(options) {
     if (options.client) {
         return { ddbClient: undefined, client: options.client, ownsClient: false };
     }
     const createClient = options.createClient ?? ((config) => new client_dynamodb_1.DynamoDBClient(config));
-    const ddbClient = createClient({ maxAttempts: 1, ...options.clientConfig });
+    // `throwOnRequestTimeout` is what makes the request timeout a bound: without
+    // it the handler only logs a warning when the timeout is breached.
+    // `socketTimeout` is here because `requestTimeout` stops applying the moment
+    // response *headers* arrive — the handler resolves there and clears its
+    // timers — so it says nothing about a response body that then stalls
+    // mid-stream, and an idle timer does. No `connectionTimeout` is passed,
+    // deliberately — its timer starts when the request is created and is
+    // cleared only when the agent *assigns* a socket, so the time a request
+    // spends queued behind `maxSockets` counts against it. At the thousand-wide
+    // fan-out this package documents, any value short enough to be useful
+    // destroys healthy writes that this library then retries, and any value
+    // long enough to be safe bounds nothing the request timeout does not
+    // already bound.
+    const ddbClient = createClient({
+        maxAttempts: 1,
+        requestHandler: {
+            requestTimeout: exports.DEFAULT_REQUEST_TIMEOUT_MS,
+            socketTimeout: exports.DEFAULT_SOCKET_TIMEOUT_MS,
+            throwOnRequestTimeout: true,
+        },
+        ...options.clientConfig,
+    });
     return { ddbClient, client: lib_dynamodb_1.DynamoDBDocument.from(ddbClient), ownsClient: true };
 }
-//# sourceMappingURL=client.js.map
+/**
+ * Warn once when an injected client keeps the SDK's own retries.
+ *
+ * Accepts: `client` — the caller's. A client that cannot report its setting —
+ * a stub, a mock, a future SDK shape — is left alone.
+ *
+ * Returns: nothing. Deliberately not awaited by its callers: it is a warning
+ * about a caller-supplied client, not a precondition for using it, so
+ * constructing an adapter stays free of I/O.
+ *
+ * Throws: nothing, ever. The SDK's own config resolution can reject, and a
+ * rejection here would surface as an unhandled rejection from a constructor
+ * that did nothing wrong.
+ *
+ * Guarantees: the SDK's retries run inside every attempt of this library's
+ * retry layer, so the budget the constants and README describe multiplies (5 ×
+ * 3 requests per operation at the SDK default) and a throttling event turns
+ * into a retry storm. Saying so once, at construction, is the only place the
+ * caller can act on it.
+ *
+ * The one gap a deadline cannot cover. A tokened write's budget is bounded by
+ * `MAX_WRITE_LIFETIME_MS`, but that bound is checked between attempts: it can
+ * refuse to start another wait, and it cannot shorten an attempt already in
+ * flight. An injected client that retries internally turns one of this
+ * library's attempts into several of its own, so the time spent inside a
+ * single attempt stops being bounded by anything this library sets — which is
+ * why the warning says to construct it with `maxAttempts: 1`.
+ *
+ * `maxAttempts: 1` is necessary but not sufficient. The per-attempt bound
+ * holds for an injected client only if it also carries its own request
+ * timeout: a client this library builds is given one
+ * ({@link resolveDynamoDBClient}), and an injected client is used exactly as
+ * handed over, so one without a handler timeout leaves a single attempt
+ * unbounded even with the SDK's retries switched off.
+ */
+async function warnOnStackedRetries(client, logger) {
+    const report = client.config
+        ?.maxAttempts;
+    if (typeof report !== 'function')
+        return;
+    try {
+        const maxAttempts = await report();
+        if (maxAttempts > 1) {
+            logger.warn("injected DynamoDB client keeps the SDK's own retries; they stack inside this library's " +
+                'retry budget — construct it with maxAttempts: 1 unless that is intended', { maxAttempts });
+        }
+    }
+    catch {
+        // A client that cannot report its retry setting is left alone.
+    }
+}