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

package/dist/cjs/shared/codec/s3/offloader.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Offloader = exports.S3_DELETE_BATCH_MAX = exports.DEFAULT_MAX_S3_DOWNLOAD_BYTES = exports.DEFAULT_S3_SSE = exports.DEFAULT_S3_THRESHOLD_BYTES = void 0;
+exports.uploadObject = uploadObject;
+exports.downloadObject = downloadObject;
+exports.oversizedObjectError = oversizedObjectError;
+exports.readBodyBounded = readBodyBounded;
+exports.deleteObjects = deleteObjects;
+exports.backlinkMetadata = backlinkMetadata;
+exports.cleanUpS3Orphans = cleanUpS3Orphans;
+const abort_js_1 = require("../../dynamodb/abort.js");
+const retry_js_1 = require("../../dynamodb/retry.js");
+const base_error_js_1 = require("../../errors/base-error.js");
+const classify_js_1 = require("../../errors/classify.js");
+const error_code_js_1 = require("../../errors/error-code.js");
+const errors_js_1 = require("../../errors/errors.js");
+const logger_js_1 = require("../../logging/logger.js");
+const secret_patterns_js_1 = require("../../logging/secret-patterns.js");
+const truncate_js_1 = require("../../logging/truncate.js");
+const client_js_1 = require("./client.js");
+const config_js_1 = require("./config.js");
+const lifecycle_js_1 = require("./lifecycle.js");
+exports.DEFAULT_S3_THRESHOLD_BYTES = 350 * 1024;
+exports.DEFAULT_S3_SSE = 'AES256';
+const S3_MAX_ATTEMPTS = 3;
+exports.DEFAULT_MAX_S3_DOWNLOAD_BYTES = 50 * 1024 * 1024;
+exports.S3_DELETE_BATCH_MAX = 1000;
+class S3Offloader {
+    clientPromise;
+    resolvedClient;
+    destroyed = false;
+    bucketName;
+    keyPrefix;
+    thresholdBytes;
+    sse;
+    sseKmsKeyId;
+    maxDownloadBytes;
+    config;
+    logger;
+    constructor(config, logger = logger_js_1.SILENT_LOGGER) {
+        this.config = config;
+        this.logger = logger;
+        this.bucketName = config.bucketName;
+        this.keyPrefix = config.keyPrefix ?? config_js_1.DEFAULT_S3_KEY_PREFIX;
+        this.thresholdBytes = config.thresholdBytes ?? exports.DEFAULT_S3_THRESHOLD_BYTES;
+        this.sse = config.serverSideEncryption ?? exports.DEFAULT_S3_SSE;
+        this.sseKmsKeyId = config.sseKmsKeyId;
+        this.maxDownloadBytes = config.maxDownloadBytes ?? exports.DEFAULT_MAX_S3_DOWNLOAD_BYTES;
+        void (0, client_js_1.loadS3Sdk)().catch(() => undefined);
+    }
+    getClient() {
+        if (!this.clientPromise) {
+            const cfg = this.config.clientConfig ?? {};
+            this.clientPromise = (this.config.createS3Client
+                ? Promise.resolve(this.config.createS3Client((0, client_js_1.withS3ClientDefaults)(cfg)))
+                : (0, client_js_1.createDefaultS3Client)(cfg)).then((client) => {
+                this.resolvedClient = client;
+                if (this.destroyed)
+                    client.destroy();
+                return client;
+            }, (error) => {
+                this.clientPromise = undefined;
+                throw error;
+            });
+        }
+        return this.clientPromise.catch((error) => {
+            throw (0, base_error_js_1.copyForCaller)(error);
+        });
+    }
+    shouldOffload(data) {
+        return data.length >= this.thresholdBytes;
+    }
+    buildKey(parts, objectId) {
+        return (0, config_js_1.buildS3Key)(this.keyPrefix, parts, objectId);
+    }
+    getKeyPrefix() {
+        return this.keyPrefix;
+    }
+    ownsKey(key, scope) {
+        return (0, config_js_1.isKeyInScope)(key, this.keyPrefix, scope);
+    }
+    assertOwnedKey(key, scope) {
+        (0, config_js_1.assertKeyInScope)(key, this.keyPrefix, scope);
+    }
+    retryReporter(operation) {
+        return ({ attempt, delayMs, error }) => (0, logger_js_1.absorbLoggerFailure)(() => this.logger.debug('retrying after a transient error', {
+            attempt,
+            delayMs,
+            operation,
+            error: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(error)),
+        }));
+    }
+    async upload(key, data, row, signal) {
+        if (data.length > this.maxDownloadBytes) {
+            throw (0, errors_js_1.validationError)(`payload of ${data.length} bytes exceeds s3.maxDownloadBytes (${this.maxDownloadBytes}), ` +
+                'so no reader configured like this adapter could download it; raise ' +
+                's3.maxDownloadBytes or store a smaller value', 'payload');
+        }
+        await uploadObject(await this.getClient(), {
+            bucket: this.bucketName,
+            key,
+            data,
+            serverSideEncryption: this.sse,
+            sseKmsKeyId: this.sseKmsKeyId,
+            metadata: backlinkMetadata(row),
+            signal,
+            onRetry: this.retryReporter('upload'),
+        });
+        return key;
+    }
+    async download(key, signal) {
+        return downloadObject(await this.getClient(), { bucket: this.bucketName, key, maxBytes: this.maxDownloadBytes }, signal, this.retryReporter('download'));
+    }
+    async deleteBatch(keys) {
+        return deleteObjects(await this.getClient(), this.bucketName, keys);
+    }
+    async ensureLifecycleRule(ttlDays, logger) {
+        return (0, lifecycle_js_1.ensureLifecycleRule)(await this.getClient(), { bucket: this.bucketName, prefix: this.keyPrefix, days: ttlDays }, logger);
+    }
+    destroy() {
+        this.destroyed = true;
+        this.resolvedClient?.destroy();
+    }
+}
+exports.S3Offloader = S3Offloader;
+function rethrowIfCancelled(error) {
+    if ((0, abort_js_1.isAbortError)(error))
+        throw error;
+}
+function alreadyStored(error) {
+    return (0, classify_js_1.classifyAwsError)(error) === error_code_js_1.ErrorCode.CONDITION_CONFLICT;
+}
+async function uploadObject(client, params) {
+    const { PutObjectCommand } = await (0, client_js_1.loadS3Sdk)();
+    try {
+        await (0, retry_js_1.withRetry)((request) => client.send(new PutObjectCommand({
+            Bucket: params.bucket,
+            Key: params.key,
+            Body: params.data,
+            ContentType: 'application/octet-stream',
+            IfNoneMatch: '*',
+            ServerSideEncryption: params.serverSideEncryption,
+            ...(params.sseKmsKeyId ? { SSEKMSKeyId: params.sseKmsKeyId } : {}),
+            ...(params.metadata ? { Metadata: params.metadata } : {}),
+        }), request), {
+            maxAttempts: S3_MAX_ATTEMPTS,
+            isRetryable: retry_js_1.isTransientS3Error,
+            signal: params.signal,
+            onRetry: params.onRetry,
+        });
+    }
+    catch (error) {
+        if (alreadyStored(error))
+            return;
+        rethrowIfCancelled(error);
+        throw new base_error_js_1.DynamoDBLangGraphError((0, secret_patterns_js_1.redactedMessage)(error), error_code_js_1.ErrorCode.S3_OFFLOAD_FAILED, {
+            operation: 'upload',
+            key: params.key,
+            ...(0, classify_js_1.awsDiagnostics)((0, classify_js_1.classifiableCause)(error)),
+        }, error);
+    }
+}
+async function downloadObject(client, object, signal, onRetry) {
+    const { GetObjectCommand } = await (0, client_js_1.loadS3Sdk)();
+    const { bucket, key, maxBytes } = object;
+    try {
+        return await (0, retry_js_1.withRetry)(async (request) => {
+            const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }), request);
+            if (typeof response.ContentLength === 'number' && response.ContentLength > maxBytes) {
+                response.Body?.destroy?.();
+                throw oversizedObjectError(key, response.ContentLength, maxBytes);
+            }
+            if (!response.Body) {
+                throw new Error(`S3 object body is empty for key: ${(0, truncate_js_1.truncateForLog)(key)}`);
+            }
+            return readBodyBounded(response.Body, key, maxBytes);
+        }, { maxAttempts: S3_MAX_ATTEMPTS, isRetryable: retry_js_1.isTransientS3Error, signal, onRetry });
+    }
+    catch (error) {
+        rethrowIfCancelled(error);
+        throw new base_error_js_1.DynamoDBLangGraphError((0, secret_patterns_js_1.redactedMessage)(error), error_code_js_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'download', key, ...(0, classify_js_1.awsDiagnostics)((0, classify_js_1.classifiableCause)(error)) }, error);
+    }
+}
+function oversizedObjectError(key, bytes, maxBytes) {
+    return new base_error_js_1.DynamoDBLangGraphError(`S3 object ${(0, truncate_js_1.truncateForLog)(key)} exceeds the ${maxBytes}-byte maxDownloadBytes cap ` +
+        `(${bytes} bytes declared or read)`, error_code_js_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'download', key });
+}
+function concat(chunks, total) {
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+async function readBodyBounded(body, key, maxBytes) {
+    const streaming = body;
+    const iterate = streaming[Symbol.asyncIterator];
+    if (typeof iterate !== 'function') {
+        const whole = new Uint8Array(await body.transformToByteArray());
+        if (whole.length > maxBytes)
+            throw oversizedObjectError(key, whole.length, maxBytes);
+        return whole;
+    }
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of { [Symbol.asyncIterator]: iterate.bind(streaming) }) {
+        total += chunk.length;
+        if (total > maxBytes) {
+            streaming.destroy?.();
+            throw oversizedObjectError(key, total, maxBytes);
+        }
+        chunks.push(chunk);
+    }
+    return concat(chunks, total);
+}
+async function deleteObjects(client, bucket, keys) {
+    if (keys.length === 0)
+        return [];
+    const { DeleteObjectsCommand } = await (0, client_js_1.loadS3Sdk)();
+    const failed = [];
+    for (let offset = 0; offset < keys.length; offset += exports.S3_DELETE_BATCH_MAX) {
+        const chunk = keys.slice(offset, offset + exports.S3_DELETE_BATCH_MAX);
+        const response = await client.send(new DeleteObjectsCommand({
+            Bucket: bucket,
+            Delete: { Objects: chunk.map((key) => ({ Key: key })), Quiet: true },
+        }));
+        for (const error of response.Errors ?? []) {
+            if (error.Key)
+                failed.push(error.Key);
+        }
+    }
+    return failed;
+}
+const PK_FIELD = 'dynamodb-pk-b64';
+const SK_FIELD = 'dynamodb-sk-b64';
+function backlinkMetadata(row) {
+    return { [PK_FIELD]: (0, config_js_1.encodeKeyPart)(row.pk), [SK_FIELD]: (0, config_js_1.encodeKeyPart)(row.sk) };
+}
+async function backoffSleep(delayMs, release) {
+    try {
+        await (0, retry_js_1.sleep)((0, retry_js_1.fullJitter)(delayMs, release.rng), release.signal);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function ownedOnly(offloader, keys, release, scope) {
+    return keys.filter((key) => {
+        if (offloader.ownsKey(key, scope))
+            return true;
+        (0, logger_js_1.absorbLoggerFailure)(() => release.logger.warn(`${release.operation}: refusing to delete an S3 object outside this row's scope`, {
+            key: (0, truncate_js_1.truncateForLog)(key),
+        }));
+        return false;
+    });
+}
+function selectOrphans(offloader, release) {
+    const present = release.keys.filter((key) => typeof key === 'string' && key.length > 0);
+    return release.scope ? ownedOnly(offloader, present, release, release.scope) : present;
+}
+async function cleanUpS3Orphans(offloader, release) {
+    const orphans = selectOrphans(offloader, release);
+    if (orphans.length === 0)
+        return;
+    const maxAttempts = release.maxAttempts ?? S3_MAX_ATTEMPTS;
+    let delay = retry_js_1.INITIAL_BACKOFF_DELAY_MS;
+    let lastError = new Error('S3 orphan cleanup did not run');
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const failed = await offloader.deleteBatch(orphans);
+            if (failed.length === 0)
+                return;
+            (0, logger_js_1.absorbLoggerFailure)(() => release.logger.warn(`Some orphaned S3 objects could not be deleted after ${release.operation}; a lifecycle rule from ensureS3LifecycleRule() would sweep them, otherwise clean up manually`, { failedCount: failed.length }));
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxAttempts || !(0, retry_js_1.isTransientS3Error)(lastError))
+                break;
+            if (await backoffSleep(delay, release))
+                break;
+            delay = (0, retry_js_1.nextBackoffDelay)(delay);
+        }
+    }
+    (0, logger_js_1.absorbLoggerFailure)(() => release.logger.warn(`Failed to clean up orphaned S3 objects after ${release.operation}; a lifecycle rule from ensureS3LifecycleRule() would sweep them, otherwise clean up manually`, { reason: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(lastError)) }));
+}

package/dist/cjs/shared/concurrency.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_READ_CONCURRENCY = void 0;
+exports.mapWithConcurrency = mapWithConcurrency;
+exports.DEFAULT_READ_CONCURRENCY = 8;
+async function mapWithConcurrency(items, limit, fn) {
+    const results = [];
+    let next = 0;
+    let failed = false;
+    let failure;
+    const worker = async () => {
+        while (!failed && next < items.length) {
+            const index = next;
+            next += 1;
+            try {
+                results[index] = await fn(items[index], index);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+    };
+    const workers = Math.min(limit >= 1 ? Math.floor(limit) : 1, Math.max(items.length, 1));
+    await Promise.all(Array.from({ length: workers }, worker));
+    if (failed)
+        throw failure;
+    return results;
+}

package/dist/{shared → cjs/shared}/dynamodb/abort.d.ts

@@ -7,8 +7,8 @@
  * twice, and one test on the library's brand and that code is what tells a
  * cancellation from a failure, so no call site inspects a reason's shape.
  */
-import { DynamoDBLangGraphError } from '../errors/base-error';
-import { ErrorCode } from '../errors/error-code';
+import { DynamoDBLangGraphError } from '../errors/base-error.js';
+import { ErrorCode } from '../errors/error-code.js';
 /**
  * Whether `error` is a cancellation rather than a failure.
  *

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

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAbortError = isAbortError;
+exports.abortErrorFrom = abortErrorFrom;
+const base_error_js_1 = require("../errors/base-error.js");
+const error_code_js_1 = require("../errors/error-code.js");
+const errors_js_1 = require("../errors/errors.js");
+function isAbortError(error) {
+    return error !== undefined && (0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.ABORTED);
+}
+function abortErrorFrom(signal) {
+    const reason = signal.reason;
+    if (isAbortError(reason))
+        return reason;
+    return (0, errors_js_1.abortError)('Operation aborted', reason === undefined ? undefined : (0, base_error_js_1.toError)(reason));
+}

package/dist/{shared → cjs/shared}/dynamodb/batch-write.d.ts

@@ -5,8 +5,8 @@
  * back unprocessed; they are re-sent with backoff until a bound, and a batch
  * that still cannot finish is reported with how much of it did.
  */
-import type { DynamoDBDocumentLike, WriteRequest } from './client';
-import { type RetryOptions } from './retry';
+import type { DynamoDBDocumentLike, WriteRequest } from './client.js';
+import { type RetryOptions } from './retry.js';
 /**
  * DynamoDB BatchWriteItem maximum requests per call.
  *

package/dist/cjs/shared/dynamodb/batch-write.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_UNPROCESSED_RETRIES = exports.BATCH_WRITE_MAX = void 0;
+exports.batchWriteAll = batchWriteAll;
+exports.drainUnprocessedWrites = drainUnprocessedWrites;
+const base_error_js_1 = require("../errors/base-error.js");
+const error_code_js_1 = require("../errors/error-code.js");
+const errors_js_1 = require("../errors/errors.js");
+const abort_js_1 = require("./abort.js");
+const retry_js_1 = require("./retry.js");
+exports.BATCH_WRITE_MAX = 25;
+exports.MAX_UNPROCESSED_RETRIES = 10;
+async function batchWriteAll(client, tableName, requests, options = {}) {
+    const totalChunks = Math.ceil(requests.length / exports.BATCH_WRITE_MAX);
+    let succeededChunks = 0;
+    let succeededCount = 0;
+    const failedChunks = [];
+    for (let offset = 0; offset < requests.length; offset += exports.BATCH_WRITE_MAX) {
+        const chunk = requests.slice(offset, offset + exports.BATCH_WRITE_MAX);
+        try {
+            await drainUnprocessedWrites(client, tableName, chunk, options);
+            succeededChunks += 1;
+            succeededCount += chunk.length;
+        }
+        catch (error) {
+            const failure = error;
+            if (!(0, base_error_js_1.hasErrorCode)(failure, error_code_js_1.ErrorCode.BATCH_WRITE_INCOMPLETE))
+                throw failure;
+            failedChunks.push(failure);
+            succeededCount += failure.details.succeededCount;
+        }
+    }
+    if (failedChunks.length > 0) {
+        throw (0, errors_js_1.batchWriteAllIncompleteError)({
+            succeeded: succeededChunks,
+            total: totalChunks,
+            failures: failedChunks,
+            succeededCount,
+        });
+    }
+}
+function drainBackoff(retry) {
+    const base = retry?.baseDelayMs ?? retry_js_1.INITIAL_BACKOFF_DELAY_MS;
+    const max = (0, retry_js_1.backoffCapMs)(base, retry?.maxDelayMs);
+    return { base: Math.min(base, max), max };
+}
+function drainFailure(error, succeededCount, pending, retries) {
+    if ((0, abort_js_1.isAbortError)(error))
+        return error;
+    return (0, errors_js_1.batchWriteIncompleteError)(succeededCount, pending, retries, error);
+}
+async function drainUnprocessedWrites(client, tableName, requests, options = {}) {
+    if (requests.length === 0)
+        return;
+    const maxRetries = options.maxRetries ?? exports.MAX_UNPROCESSED_RETRIES;
+    const initialCount = requests.length;
+    const { base: baseDelay, max: maxDelay } = drainBackoff(options.retry);
+    let pending = requests;
+    let delay = baseDelay;
+    let retries = 0;
+    while (pending.length > 0) {
+        try {
+            const result = await (0, retry_js_1.withDynamoDBRetry)((request) => client.batchWrite({ RequestItems: { [tableName]: pending } }, request), { ...options.retry, signal: options.signal });
+            const leftover = result.UnprocessedItems?.[tableName] ?? [];
+            if (leftover.length === 0)
+                return;
+            pending = leftover;
+            retries += 1;
+            if (retries > maxRetries)
+                break;
+            await (0, retry_js_1.sleep)((0, retry_js_1.fullJitter)(delay, options.rng), options.signal);
+            delay = (0, retry_js_1.nextBackoffDelay)(delay, maxDelay);
+        }
+        catch (error) {
+            throw drainFailure(error, initialCount - pending.length, pending, retries);
+        }
+    }
+    throw (0, errors_js_1.batchWriteIncompleteError)(initialCount - pending.length, pending, maxRetries);
+}

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

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCancellationReasons = getCancellationReasons;
+exports.conditionalCheckFailure = conditionalCheckFailure;
+exports.transientCancellation = transientCancellation;
+exports.throttledCancellation = throttledCancellation;
+exports.conditionFailedAt = conditionFailedAt;
+const NOT_THE_CAUSE = 'None';
+const CONDITION_FAILED = 'ConditionalCheckFailed';
+function getCancellationReasons(error) {
+    return error?.CancellationReasons;
+}
+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;
+}
+const TRANSIENT_CANCELLATION_REASONS = [
+    'None',
+    'TransactionConflict',
+    'ThrottlingError',
+    'ProvisionedThroughputExceeded',
+];
+function transientCancellation(error) {
+    const reasons = getCancellationReasons(error);
+    if (!reasons)
+        return undefined;
+    return (reasons.length > 0 &&
+        reasons.every((reason) => reason.Code === undefined || TRANSIENT_CANCELLATION_REASONS.includes(reason.Code)));
+}
+const THROTTLING_REASONS = ['ThrottlingError', 'ProvisionedThroughputExceeded'];
+function throttledCancellation(error) {
+    return (getCancellationReasons(error) ?? []).some((reason) => reason.Code !== undefined && THROTTLING_REASONS.includes(reason.Code));
+}
+function conditionFailedAt(error, index) {
+    return getCancellationReasons(error)?.[index]?.Code === CONDITION_FAILED;
+}

package/dist/{shared → cjs/shared}/dynamodb/client.d.ts

@@ -11,7 +11,7 @@
  */
 import { DynamoDBClient, type DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocument, type NativeAttributeValue, type TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
-import type { Logger } from '../logging/logger';
+import type { Logger } from '../logging/logger.js';
 /**
  * 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
@@ -22,14 +22,15 @@ import type { Logger } from '../logging/logger';
  * 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.
+ * Measured, not picked. At a thousand concurrent writes of 20 KB values —
+ * wider than one call's own fan-out now runs, but within reach of several
+ * calls sharing one client — 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, 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;
 /**
@@ -89,8 +90,9 @@ export interface ResolveClientOptions {
  * 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}.
+ * way to give up the bound. Either key named with `undefined` overrides
+ * nothing and keeps its default. An injected client keeps whatever it was
+ * built with — see {@link warnOnStackedRetries}.
  */
 export declare function resolveDynamoDBClient(options: ResolveClientOptions): ResolvedDynamoDBClient;
 /**
@@ -135,20 +137,21 @@ export declare function warnOnStackedRetries(client: DynamoDBDocumentLike, logge
  * turns one into that feature's row type.
  */
 export type AttributeMap = Record<string, NativeAttributeValue>;
-/** A BatchWriteItem PutRequest. */
-interface PutWriteRequest {
+/**
+ * A single `BatchWriteItem` write request, as the document client takes it —
+ * a `PutRequest` carrying the item, or a `DeleteRequest` carrying the key:
+ * the shape of each entry a `BATCH_WRITE_INCOMPLETE` error's
+ * `details.unprocessed` carries, verbatim, so a caller can re-submit it.
+ */
+export type WriteRequest = {
     PutRequest: {
-        Item: AttributeMap;
+        Item: Record<string, NativeAttributeValue>;
     };
-}
-/** A BatchWriteItem DeleteRequest. */
-interface DeleteWriteRequest {
+} | {
     DeleteRequest: {
-        Key: AttributeMap;
+        Key: Record<string, NativeAttributeValue>;
     };
-}
-/** 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];
 /**
@@ -172,4 +175,3 @@ export type TransactAction = NonNullable<TransactWriteCommandInput['TransactItem
  * 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/cjs/shared/dynamodb/client.js

@@ -0,0 +1,40 @@
+"use strict";
+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");
+exports.DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+exports.DEFAULT_SOCKET_TIMEOUT_MS = 5_000;
+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({
+        ...options.clientConfig,
+        maxAttempts: options.clientConfig?.maxAttempts ?? 1,
+        requestHandler: options.clientConfig?.requestHandler ?? {
+            requestTimeout: exports.DEFAULT_REQUEST_TIMEOUT_MS,
+            socketTimeout: exports.DEFAULT_SOCKET_TIMEOUT_MS,
+            throwOnRequestTimeout: true,
+        },
+    });
+    return { ddbClient, client: lib_dynamodb_1.DynamoDBDocument.from(ddbClient), ownsClient: true };
+}
+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 {
+    }
+}