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

package/dist/shared/codec/json-serde.d.ts

@@ -1,8 +1,80 @@
+/**
+ * Hides the JSON form: writing it, reading it, and recognising it.
+ *
+ * The default serde writes a value as JSON under the `json` type and reads
+ * back only that type; the codec also asks, when a serde refuses stored bytes,
+ * whether those bytes are still JSON at all, which tells a corrupt payload from
+ * a serde that would not reconstruct it.
+ */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
 /**
- * A minimal JSON serializer implementing LangGraph's {@link SerializerProtocol},
- * used by adapters (the store, history) that persist plain JSON values through
- * the shared payload codec.
+ * A plain JSON serializer implementing LangGraph's `SerializerProtocol`:
+ * the default `serde` of `DynamoDBStore` and `DynamoDBChatMessageHistory`, and
+ * the alternative a `DynamoDBSaver` can be given in place of LangGraph's
+ * `JsonPlusSerializer`.
+ *
+ * It is exported so that choice is available. The checkpointer's default
+ * revives a stored `{"lc": …}` record by instantiating the class the record
+ * names, so the row selects which constructor runs on read; this serializer
+ * runs `JSON.parse` and nothing else, and reconstructs no class at all.
+ * Reading with it is the narrower trust boundary, and the price is stated
+ * below: it stores the JSON projection of a value, not the value.
+ *
+ * `dumpsTyped` accepts any value `JSON.stringify` can represent and refuses the
+ * rest. A value it cannot represent — `undefined`, a function, a symbol —
+ * stringifies to `undefined` and would be stored as **zero bytes**, which reads
+ * back as a parse error; a circular structure or a `BigInt` makes it throw. Both
+ * are reported as `VALIDATION` naming `value`, at the write, rather than
+ * as an unreadable row later — with the refusal attached as `cause` and never
+ * quoted into the message, which for a circular structure names the caller's
+ * own properties and classes.
+ *
+ * What it represents, it represents as JSON, which is lossy in ways nothing
+ * records: a `Map` or `Set` stores as `{}`, an object key whose value is
+ * `undefined` is dropped and an array element is stored as `null`, `NaN` and
+ * `Infinity` store as `null`, `-0` as `0`, a `Uint8Array` as an index-keyed
+ * object and a `Date` as an ISO string. The README's *Table schema* section
+ * holds the whole table, against the checkpointer default column by column.
+ *
+ * `loadsTyped` reads only the `json` form it writes, and says
+ * so before it looks at a byte. Any other declared form is a `VALIDATION` error
+ * naming `serde`, because it says what *this* reader may rebuild and not that
+ * the payload is damaged. Bytes of that form which do not parse are
+ * `PAYLOAD_CORRUPT`, because they can never be read and the caller should
+ * report rather than retry; a `data` that is not bytes at all is a
+ * `VALIDATION` naming `data`, because that is the caller's mistake and
+ * not a row's.
+ *
+ * Frozen for the reason {@link ErrorCode} is: one object, shared by every
+ * adapter in the process that did not pass a `serde` of its own, and
+ * reachable from the package root. An assignment to `dumpsTyped` by any one
+ * consumer would silently change how every other one writes.
  */
 export declare const JSON_SERDE: SerializerProtocol;
-//# sourceMappingURL=json-serde.d.ts.map
+/**
+ * Whether stored bytes are still the form the row that holds them declares.
+ *
+ * This is the structural question behind the two ways a decode fails —
+ * `PAYLOAD_CORRUPT` for bytes no reader can decode, and the `serde` refusal for
+ * bytes *this* reader will not rebuild a value from — and it is the only one
+ * this package can answer on its own. `SerializerProtocol` offers no way to ask
+ * a serde whether it parsed the bytes before deciding not to reconstruct what
+ * they name, and the refusal it throws is a caller's object: its class, its
+ * fields and its prose are all whatever that caller chose. Classifying a
+ * payload by any of those would make the code mean "a third party said so",
+ * which is exactly what neither code may mean.
+ *
+ * Accepts: `serdeType` — the type stamped on the row, as the descriptor carries
+ * it. `bytes` — what the row stored, already decompressed.
+ *
+ * Returns: whether the bytes still parse as the declared form. A type this
+ * package has no grammar for is taken at its word and answers `true`, so its
+ * serde's refusal is reported rather than written off: dropping a payload this
+ * reader merely cannot check would lose data on nothing but its own ignorance.
+ *
+ * Throws: **nothing**, for any bytes. It is called from inside the `catch` that
+ * is classifying a decode failure, where a throw would replace the failure
+ * being reported — and the value it is handed came off a row, so it may be
+ * anything that row's writer stored.
+ */
+export declare function bytesHoldDeclaredForm(serdeType: string, bytes: Uint8Array): boolean;

package/dist/shared/codec/json-serde.js

@@ -1,18 +1,191 @@
 "use strict";
+/**
+ * Hides the JSON form: writing it, reading it, and recognising it.
+ *
+ * The default serde writes a value as JSON under the `json` type and reads
+ * back only that type; the codec also asks, when a serde refuses stored bytes,
+ * whether those bytes are still JSON at all, which tells a corrupt payload from
+ * a serde that would not reconstruct it.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JSON_SERDE = void 0;
+exports.bytesHoldDeclaredForm = bytesHoldDeclaredForm;
+const base_error_1 = require("../errors/base-error");
+const error_code_1 = require("../errors/error-code");
+const errors_1 = require("../errors/errors");
+const truncate_1 = require("../logging/truncate");
 /**
- * A minimal JSON serializer implementing LangGraph's {@link SerializerProtocol},
- * used by adapters (the store, history) that persist plain JSON values through
- * the shared payload codec.
+ * A plain JSON serializer implementing LangGraph's `SerializerProtocol`:
+ * the default `serde` of `DynamoDBStore` and `DynamoDBChatMessageHistory`, and
+ * the alternative a `DynamoDBSaver` can be given in place of LangGraph's
+ * `JsonPlusSerializer`.
+ *
+ * It is exported so that choice is available. The checkpointer's default
+ * revives a stored `{"lc": …}` record by instantiating the class the record
+ * names, so the row selects which constructor runs on read; this serializer
+ * runs `JSON.parse` and nothing else, and reconstructs no class at all.
+ * Reading with it is the narrower trust boundary, and the price is stated
+ * below: it stores the JSON projection of a value, not the value.
+ *
+ * `dumpsTyped` accepts any value `JSON.stringify` can represent and refuses the
+ * rest. A value it cannot represent — `undefined`, a function, a symbol —
+ * stringifies to `undefined` and would be stored as **zero bytes**, which reads
+ * back as a parse error; a circular structure or a `BigInt` makes it throw. Both
+ * are reported as `VALIDATION` naming `value`, at the write, rather than
+ * as an unreadable row later — with the refusal attached as `cause` and never
+ * quoted into the message, which for a circular structure names the caller's
+ * own properties and classes.
+ *
+ * What it represents, it represents as JSON, which is lossy in ways nothing
+ * records: a `Map` or `Set` stores as `{}`, an object key whose value is
+ * `undefined` is dropped and an array element is stored as `null`, `NaN` and
+ * `Infinity` store as `null`, `-0` as `0`, a `Uint8Array` as an index-keyed
+ * object and a `Date` as an ISO string. The README's *Table schema* section
+ * holds the whole table, against the checkpointer default column by column.
+ *
+ * `loadsTyped` reads only the `json` form it writes, and says
+ * so before it looks at a byte. Any other declared form is a `VALIDATION` error
+ * naming `serde`, because it says what *this* reader may rebuild and not that
+ * the payload is damaged. Bytes of that form which do not parse are
+ * `PAYLOAD_CORRUPT`, because they can never be read and the caller should
+ * report rather than retry; a `data` that is not bytes at all is a
+ * `VALIDATION` naming `data`, because that is the caller's mistake and
+ * not a row's.
+ *
+ * Frozen for the reason {@link ErrorCode} is: one object, shared by every
+ * adapter in the process that did not pass a `serde` of its own, and
+ * reachable from the package root. An assignment to `dumpsTyped` by any one
+ * consumer would silently change how every other one writes.
  */
 exports.JSON_SERDE = {
     async dumpsTyped(value) {
-        return ['json', new TextEncoder().encode(JSON.stringify(value))];
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            // The refusal travels as `cause`, never as text. V8 writes the path it
+            // walked into the message it throws for a circular structure, quoting
+            // the caller's own property names and constructor names — and this
+            // package does not compose a public `err.message` out of a caller's
+            // identifiers, which an application may print, log or return in a
+            // response. `redactedMessage` removes credential shapes, not names, so
+            // it never covered this. A caller who wants the path reads `cause`.
+            throw (0, errors_1.validationError)('value cannot be serialized as JSON — a circular structure, or a value JSON has no ' +
+                'encoding for such as a BigInt; the refusal itself is attached as `cause`', 'value', (0, base_error_1.toError)(error));
+        }
+        if (text === undefined) {
+            throw (0, errors_1.validationError)('value has no JSON representation (undefined, a function or a symbol), so it cannot be ' +
+                'stored; store null instead to record an absent value', 'value');
+        }
+        // `dumpsTyped` stays `async` because the two throws above must reach a
+        // caller as a rejection even when it is called without `await` (a bare
+        // `.catch()`), which a plain synchronous throw would not do. Returning
+        // `Promise.resolve(...)` here — rather than the bare tuple — is what
+        // satisfies `require-await`: the rule accepts a `return` of a thenable
+        // value in place of an explicit `await`, and needs no `await` to do it.
+        return Promise.resolve([JSON_SERDE_TYPE, new TextEncoder().encode(text)]);
     },
-    async loadsTyped(_type, data) {
-        const text = typeof data === 'string' ? data : new TextDecoder().decode(data);
-        return JSON.parse(text);
+    async loadsTyped(type, data) {
+        // The declared form is honoured, and honoured first. Ignoring it left this
+        // serializer answering for forms it has no grammar for: a row stamped
+        // `bytes` by the checkpointer's default — what that serializer writes for a
+        // raw `Uint8Array` — parsed here as JSON and returned a *different value*
+        // whenever those bytes happened to be valid JSON, and returned this
+        // serializer's own `PAYLOAD_CORRUPT` when they were not. The second reading
+        // is the one that cost data: the codec passes an already-branded refusal
+        // through untouched, so `bytesHoldDeclaredForm` never ran, the row was
+        // filed as permanent loss, and history's default `onCorruptMessage: 'skip'`
+        // dropped the message. The same row read through the checkpointer's own
+        // default was reported as a refusal instead, so which serde an adapter
+        // carried decided whether a turn survived the read.
+        //
+        // A form this serializer cannot rebuild a value from is a statement about
+        // this reader, not about the payload, so it names `serde` — the same brand
+        // the codec puts on `JsonPlusSerializer`'s `Unknown serialization type`,
+        // which is what makes the two agree. The type is quoted from the row, so it
+        // is bounded, for the reason `truncateForLog` states.
+        if (type !== JSON_SERDE_TYPE) {
+            throw (0, errors_1.validationError)(`this serializer reads only the \`${JSON_SERDE_TYPE}\` form it writes, and this payload ` +
+                `declares ${(0, truncate_1.truncateForLog)(String(JSON.stringify(type)))}; read the row with the ` +
+                'serializer that wrote it, or rewrite the row', 'serde');
+        }
+        let text;
+        // The decode is inside a guard of its own because it fails for a different
+        // reason than the parse does, and names it separately. UTF-8 decoding is
+        // lenient — a malformed byte becomes U+FFFD rather than an error — so the
+        // only way `TextDecoder` refuses is a `data` that is not bytes at all,
+        // which is the caller's mistake and not a corrupt row. The codec always
+        // passes a `Uint8Array`; a direct caller passing anything else would
+        // otherwise get a bare `TypeError` from Node naming an argument called
+        // "list".
+        try {
+            text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+        }
+        catch (error) {
+            throw (0, errors_1.validationError)('data must be the bytes or text this serializer wrote, as a Uint8Array or a string', 'data', error);
+        }
+        try {
+            // Same reasoning as `dumpsTyped`'s final return: see its comment.
+            return Promise.resolve(JSON.parse(text));
+        }
+        catch (error) {
+            throw new base_error_1.DynamoDBLangGraphError('the stored payload is not the JSON this serializer wrote, so it cannot be decoded', error_code_1.ErrorCode.PAYLOAD_CORRUPT, {}, error);
+        }
     },
 };
-//# sourceMappingURL=json-serde.js.map
+Object.freeze(exports.JSON_SERDE);
+/**
+ * The one `serdeType` whose grammar this package can check for itself: the type
+ * `JSON_SERDE` stamps on everything it writes, and the one LangGraph's
+ * own `JsonPlusSerializer` stamps on every value but a raw `Uint8Array`, which
+ * it stamps `bytes`.
+ *
+ * The one constant is shared by the serializer that writes this form and the
+ * check that re-derives it, within this module. They had each decided
+ * separately what they understood: the check took any other type at its
+ * word, while `JSON_SERDE` ignored the declared type and ran `JSON.parse` on
+ * whatever it was handed. A row declaring a form neither of them writes was
+ * therefore classified one way through one serializer and the opposite way
+ * through the other — and a row declaring `bytes`, which the checkpointer's
+ * default writes for a raw `Uint8Array`, decoded to a *different value*
+ * rather than failing at all when its bytes happened to parse as JSON.
+ */
+const JSON_SERDE_TYPE = 'json';
+/**
+ * Whether stored bytes are still the form the row that holds them declares.
+ *
+ * This is the structural question behind the two ways a decode fails —
+ * `PAYLOAD_CORRUPT` for bytes no reader can decode, and the `serde` refusal for
+ * bytes *this* reader will not rebuild a value from — and it is the only one
+ * this package can answer on its own. `SerializerProtocol` offers no way to ask
+ * a serde whether it parsed the bytes before deciding not to reconstruct what
+ * they name, and the refusal it throws is a caller's object: its class, its
+ * fields and its prose are all whatever that caller chose. Classifying a
+ * payload by any of those would make the code mean "a third party said so",
+ * which is exactly what neither code may mean.
+ *
+ * Accepts: `serdeType` — the type stamped on the row, as the descriptor carries
+ * it. `bytes` — what the row stored, already decompressed.
+ *
+ * Returns: whether the bytes still parse as the declared form. A type this
+ * package has no grammar for is taken at its word and answers `true`, so its
+ * serde's refusal is reported rather than written off: dropping a payload this
+ * reader merely cannot check would lose data on nothing but its own ignorance.
+ *
+ * Throws: **nothing**, for any bytes. It is called from inside the `catch` that
+ * is classifying a decode failure, where a throw would replace the failure
+ * being reported — and the value it is handed came off a row, so it may be
+ * anything that row's writer stored.
+ */
+function bytesHoldDeclaredForm(serdeType, bytes) {
+    if (serdeType !== JSON_SERDE_TYPE)
+        return true;
+    try {
+        JSON.parse(new TextDecoder().decode(bytes));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/shared/codec/s3/client-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Hides the S3 SDK's own types from this package's declarations.
+ *
+ * The S3 client, its config and a command are described by the members this
+ * package touches, so no shipped declaration imports the optional
+ * `@aws-sdk/client-s3` peer and a caller without it installed still compiles
+ * (record 1). A real `S3Client` or `S3ClientConfig` satisfies these shapes as
+ * it is, so a caller who has the SDK passes its own values unchanged.
+ */
+/** A region as the SDK accepts it: a string or a provider resolving to one. */
+export type S3RegionLike = string | (() => Promise<string>);
+/** A value an S3 client option can hold. */
+export type S3ClientOption = string | number | boolean | object | null | undefined;
+/**
+ * The S3 client options this library reads (`region`) or sets (`maxAttempts`),
+ * open to every other `S3ClientConfig` key.
+ */
+export interface S3ClientOptions {
+    region?: S3RegionLike;
+    maxAttempts?: number;
+    [option: string]: S3ClientOption;
+}
+/**
+ * Structural stand-in for `S3ClientConfig`, so the shipped declarations compile
+ * without the optional `@aws-sdk/client-s3` peer installed. A literal gets
+ * completion for the options the library uses; a typed `S3ClientConfig`
+ * variable is accepted as it is.
+ */
+export type S3ClientConfigLike = S3ClientOptions | object;
+/**
+ * The options of a config, read through the structural type.
+ *
+ * Accepts: a config as the caller gave it, or nothing.
+ *
+ * Returns: the same object seen as {@link S3ClientOptions} so `region` and
+ * `maxAttempts` can be read; an absent config reads as empty rather than
+ * needing a guard at every call site.
+ *
+ * Throws: nothing.
+ */
+export declare function s3ClientOptions(config: S3ClientConfigLike | undefined): S3ClientOptions;
+/** What every SDK command object carries: its `input`. */
+export interface S3CommandLike {
+    input: object;
+}
+/**
+ * The S3 client surface this library calls, typed structurally for the same
+ * reason. `S3Client` from `@aws-sdk/client-s3` satisfies it.
+ */
+export interface S3ClientLike {
+    send(command: S3CommandLike, options?: object): Promise<object>;
+    destroy(): void;
+}

package/dist/shared/codec/s3/client-types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Hides the S3 SDK's own types from this package's declarations.
+ *
+ * The S3 client, its config and a command are described by the members this
+ * package touches, so no shipped declaration imports the optional
+ * `@aws-sdk/client-s3` peer and a caller without it installed still compiles
+ * (record 1). A real `S3Client` or `S3ClientConfig` satisfies these shapes as
+ * it is, so a caller who has the SDK passes its own values unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.s3ClientOptions = s3ClientOptions;
+/**
+ * The options of a config, read through the structural type.
+ *
+ * Accepts: a config as the caller gave it, or nothing.
+ *
+ * Returns: the same object seen as {@link S3ClientOptions} so `region` and
+ * `maxAttempts` can be read; an absent config reads as empty rather than
+ * needing a guard at every call site.
+ *
+ * Throws: nothing.
+ */
+function s3ClientOptions(config) {
+    return (config ?? {});
+}

package/dist/shared/codec/s3/client.d.ts

@@ -1,12 +1,45 @@
-import type { S3Client, S3ClientConfig } from '@aws-sdk/client-s3';
-/** Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. */
-export declare function loadS3Sdk(): Promise<typeof import('@aws-sdk/client-s3')>;
 /**
- * Construct an `S3Client` from `config` using the lazily-loaded SDK. Defaults
- * `maxAttempts: 1` so the SDK's own internal retries are disabled and this
- * library's retry/backoff/classification system is the sole retry layer,
- * matching {@link resolveDynamoDBClient}'s equivalent default; an explicit
- * `maxAttempts` in `config` still wins.
+ * Hides that the S3 SDK is loaded on first use, and how its client is set up.
+ *
+ * An adapter without offload never imports the optional peer; the first
+ * offload does, once, and a missing install surfaces as `VALIDATION` naming
+ * the remedy (record 1). The client built here defaults to no retries of its
+ * own — `maxAttempts: 1` — so this package's retry is the only layer unless a
+ * caller's own `maxAttempts` overrides it (record 14), and its idle timer
+ * bounds a stalled transfer without bounding a slow one.
  */
-export declare function createDefaultS3Client(config: S3ClientConfig): Promise<S3Client>;
-//# sourceMappingURL=client.d.ts.map
+import type { S3Client } from '@aws-sdk/client-s3';
+import type { S3ClientConfigLike } from './client-types';
+type S3Sdk = typeof import('@aws-sdk/client-s3');
+/**
+ * The optional `@aws-sdk/client-s3` peer, imported on first use.
+ *
+ * Accepts: nothing. Concurrent callers share one import.
+ *
+ * Returns: the module, cached for every later call.
+ *
+ * Throws: `VALIDATION` naming `s3` when the package is not installed,
+ * carrying the install command; any other import failure — a broken build, a
+ * syntax error inside the package — passes through unchanged. A failure is not
+ * cached, so an install or a fixed bundle succeeds on a later call.
+ */
+export declare function loadS3Sdk(): Promise<S3Sdk>;
+/**
+ * An `S3Client` built from `config` with the lazily-loaded SDK.
+ *
+ * Accepts: `config` — any `S3ClientConfig`; an explicit `maxAttempts` or
+ * `requestHandler` wins over the defaults below.
+ *
+ * Returns: the client. The caller owns it and destroys it.
+ *
+ * Throws: whatever {@link loadS3Sdk} throws.
+ *
+ * Guarantees: `maxAttempts` defaults to 1, so the SDK performs no retries of
+ * its own and this library's retry, backoff and classification are the only
+ * retry layer — the same default `resolveDynamoDBClient` applies on the
+ * DynamoDB side. A default request handler bounds a transfer that has
+ * stalled, which `maxAttempts` alone does not; a `requestHandler` in `config`
+ * replaces it whole rather than merging with it.
+ */
+export declare function createDefaultS3Client(config: S3ClientConfigLike): Promise<S3Client>;
+export {};

package/dist/shared/codec/s3/client.js

@@ -1,24 +1,97 @@
 "use strict";
+/**
+ * Hides that the S3 SDK is loaded on first use, and how its client is set up.
+ *
+ * An adapter without offload never imports the optional peer; the first
+ * offload does, once, and a missing install surfaces as `VALIDATION` naming
+ * the remedy (record 1). The client built here defaults to no retries of its
+ * own — `maxAttempts: 1` — so this package's retry is the only layer unless a
+ * caller's own `maxAttempts` overrides it (record 14), and its idle timer
+ * bounds a stalled transfer without bounding a slow one.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadS3Sdk = loadS3Sdk;
 exports.createDefaultS3Client = createDefaultS3Client;
+const client_1 = require("../../dynamodb/client");
+const errors_1 = require("../../errors/errors");
+/** Codes Node and bundlers use for an import that cannot be resolved. */
+const MISSING_MODULE_CODES = ['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'];
 let sdkPromise;
-/** Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. */
+/**
+ * Convert a failed import of the optional peer into a typed error that names
+ * the remedy. Any other failure (a broken build, a syntax error inside the
+ * package) passes through unchanged.
+ */
+function wrapMissingPeer(error) {
+    const code = error.code;
+    if (code !== undefined && MISSING_MODULE_CODES.includes(code)) {
+        throw (0, errors_1.validationError)('S3 offload requires the optional peer @aws-sdk/client-s3 (npm install @aws-sdk/client-s3); ' +
+            'bundlers must keep it installed or external', 's3', error);
+    }
+    throw error;
+}
+/**
+ * The optional `@aws-sdk/client-s3` peer, imported on first use.
+ *
+ * Accepts: nothing. Concurrent callers share one import.
+ *
+ * Returns: the module, cached for every later call.
+ *
+ * Throws: `VALIDATION` naming `s3` when the package is not installed,
+ * carrying the install command; any other import failure — a broken build, a
+ * syntax error inside the package — passes through unchanged. A failure is not
+ * cached, so an install or a fixed bundle succeeds on a later call.
+ */
 async function loadS3Sdk() {
     if (!sdkPromise) {
-        sdkPromise = import('@aws-sdk/client-s3');
+        sdkPromise = import('@aws-sdk/client-s3').catch((error) => {
+            sdkPromise = undefined;
+            return wrapMissingPeer(error);
+        });
     }
     return sdkPromise;
 }
 /**
- * Construct an `S3Client` from `config` using the lazily-loaded SDK. Defaults
- * `maxAttempts: 1` so the SDK's own internal retries are disabled and this
- * library's retry/backoff/classification system is the sole retry layer,
- * matching {@link resolveDynamoDBClient}'s equivalent default; an explicit
- * `maxAttempts` in `config` still wins.
+ * An `S3Client` built from `config` with the lazily-loaded SDK.
+ *
+ * Accepts: `config` — any `S3ClientConfig`; an explicit `maxAttempts` or
+ * `requestHandler` wins over the defaults below.
+ *
+ * Returns: the client. The caller owns it and destroys it.
+ *
+ * Throws: whatever {@link loadS3Sdk} throws.
+ *
+ * Guarantees: `maxAttempts` defaults to 1, so the SDK performs no retries of
+ * its own and this library's retry, backoff and classification are the only
+ * retry layer — the same default `resolveDynamoDBClient` applies on the
+ * DynamoDB side. A default request handler bounds a transfer that has
+ * stalled, which `maxAttempts` alone does not; a `requestHandler` in `config`
+ * replaces it whole rather than merging with it.
  */
 async function createDefaultS3Client(config) {
     const { S3Client: S3ClientCtor } = await loadS3Sdk();
-    return new S3ClientCtor({ maxAttempts: 1, ...config });
+    // One field, where the DynamoDB client gets three, and the asymmetry is
+    // deliberate. `requestTimeout` bounds request creation until response
+    // *headers* arrive, and a `PutObject`'s headers arrive only once the whole
+    // body has been uploaded — so here it would be a bound on upload duration,
+    // over payloads running from the offload threshold to the download cap, and
+    // a legitimate large upload on a slow link would be destroyed for being
+    // slow. `socketTimeout` is an idle timer that any activity in either
+    // direction resets, so it separates a stalled transfer from a slow one.
+    // `throwOnRequestTimeout` is absent because without a request timeout it has
+    // nothing to act on, and `connectionTimeout` because its timer counts the
+    // wait behind the agent's sockets, which this path fans out across.
+    //
+    // What this bounds is a transfer stalled after its socket was assigned, not
+    // the whole attempt: nothing here bounds the time a request spends queued
+    // for a socket, and an idle timer is not a deadline, so a large upload's
+    // total duration stays unbounded. At or above 2 MiB the SDK sends
+    // `Expect: 100-continue` and the handler then waits six seconds for the
+    // continue on a throwaway agent, so the five-second idle timer is what
+    // fires first — the one place the two timers race.
+    return new S3ClientCtor({
+        maxAttempts: 1,
+        requestHandler: { socketTimeout: client_1.DEFAULT_SOCKET_TIMEOUT_MS },
+        ...config,
+    });
 }
-//# sourceMappingURL=client.js.map