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

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

@@ -0,0 +1,278 @@
+import { isAbortError } from '../../dynamodb/abort.js';
+import { fullJitter, INITIAL_BACKOFF_DELAY_MS, isTransientS3Error, nextBackoffDelay, sleep, withRetry, } from '../../dynamodb/retry.js';
+import { copyForCaller, DynamoDBLangGraphError, failureLabel } from '../../errors/base-error.js';
+import { awsDiagnostics, classifiableCause, classifyAwsError } from '../../errors/classify.js';
+import { ErrorCode } from '../../errors/error-code.js';
+import { validationError } from '../../errors/errors.js';
+import { absorbLoggerFailure, SILENT_LOGGER } from '../../logging/logger.js';
+import { redactedMessage } from '../../logging/secret-patterns.js';
+import { truncateForLog } from '../../logging/truncate.js';
+import { createDefaultS3Client, loadS3Sdk, withS3ClientDefaults } from './client.js';
+import { assertKeyInScope, buildS3Key, DEFAULT_S3_KEY_PREFIX, encodeKeyPart, isKeyInScope, } from './config.js';
+import { ensureLifecycleRule } from './lifecycle.js';
+export const DEFAULT_S3_THRESHOLD_BYTES = 350 * 1024;
+export const DEFAULT_S3_SSE = 'AES256';
+const S3_MAX_ATTEMPTS = 3;
+export const DEFAULT_MAX_S3_DOWNLOAD_BYTES = 50 * 1024 * 1024;
+export const S3_DELETE_BATCH_MAX = 1000;
+export class S3Offloader {
+    clientPromise;
+    resolvedClient;
+    destroyed = false;
+    bucketName;
+    keyPrefix;
+    thresholdBytes;
+    sse;
+    sseKmsKeyId;
+    maxDownloadBytes;
+    config;
+    logger;
+    constructor(config, logger = SILENT_LOGGER) {
+        this.config = config;
+        this.logger = logger;
+        this.bucketName = config.bucketName;
+        this.keyPrefix = config.keyPrefix ?? DEFAULT_S3_KEY_PREFIX;
+        this.thresholdBytes = config.thresholdBytes ?? DEFAULT_S3_THRESHOLD_BYTES;
+        this.sse = config.serverSideEncryption ?? DEFAULT_S3_SSE;
+        this.sseKmsKeyId = config.sseKmsKeyId;
+        this.maxDownloadBytes = config.maxDownloadBytes ?? DEFAULT_MAX_S3_DOWNLOAD_BYTES;
+        void loadS3Sdk().catch(() => undefined);
+    }
+    getClient() {
+        if (!this.clientPromise) {
+            const cfg = this.config.clientConfig ?? {};
+            this.clientPromise = (this.config.createS3Client
+                ? Promise.resolve(this.config.createS3Client(withS3ClientDefaults(cfg)))
+                : 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 copyForCaller(error);
+        });
+    }
+    shouldOffload(data) {
+        return data.length >= this.thresholdBytes;
+    }
+    buildKey(parts, objectId) {
+        return buildS3Key(this.keyPrefix, parts, objectId);
+    }
+    getKeyPrefix() {
+        return this.keyPrefix;
+    }
+    ownsKey(key, scope) {
+        return isKeyInScope(key, this.keyPrefix, scope);
+    }
+    assertOwnedKey(key, scope) {
+        assertKeyInScope(key, this.keyPrefix, scope);
+    }
+    retryReporter(operation) {
+        return ({ attempt, delayMs, error }) => absorbLoggerFailure(() => this.logger.debug('retrying after a transient error', {
+            attempt,
+            delayMs,
+            operation,
+            error: truncateForLog(failureLabel(error)),
+        }));
+    }
+    async upload(key, data, row, signal) {
+        if (data.length > this.maxDownloadBytes) {
+            throw 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 ensureLifecycleRule(await this.getClient(), { bucket: this.bucketName, prefix: this.keyPrefix, days: ttlDays }, logger);
+    }
+    destroy() {
+        this.destroyed = true;
+        this.resolvedClient?.destroy();
+    }
+}
+function rethrowIfCancelled(error) {
+    if (isAbortError(error))
+        throw error;
+}
+function alreadyStored(error) {
+    return classifyAwsError(error) === ErrorCode.CONDITION_CONFLICT;
+}
+export async function uploadObject(client, params) {
+    const { PutObjectCommand } = await loadS3Sdk();
+    try {
+        await 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: isTransientS3Error,
+            signal: params.signal,
+            onRetry: params.onRetry,
+        });
+    }
+    catch (error) {
+        if (alreadyStored(error))
+            return;
+        rethrowIfCancelled(error);
+        throw new DynamoDBLangGraphError(redactedMessage(error), ErrorCode.S3_OFFLOAD_FAILED, {
+            operation: 'upload',
+            key: params.key,
+            ...awsDiagnostics(classifiableCause(error)),
+        }, error);
+    }
+}
+export async function downloadObject(client, object, signal, onRetry) {
+    const { GetObjectCommand } = await loadS3Sdk();
+    const { bucket, key, maxBytes } = object;
+    try {
+        return await 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: ${truncateForLog(key)}`);
+            }
+            return readBodyBounded(response.Body, key, maxBytes);
+        }, { maxAttempts: S3_MAX_ATTEMPTS, isRetryable: isTransientS3Error, signal, onRetry });
+    }
+    catch (error) {
+        rethrowIfCancelled(error);
+        throw new DynamoDBLangGraphError(redactedMessage(error), ErrorCode.S3_OFFLOAD_FAILED, { operation: 'download', key, ...awsDiagnostics(classifiableCause(error)) }, error);
+    }
+}
+export function oversizedObjectError(key, bytes, maxBytes) {
+    return new DynamoDBLangGraphError(`S3 object ${truncateForLog(key)} exceeds the ${maxBytes}-byte maxDownloadBytes cap ` +
+        `(${bytes} bytes declared or read)`, 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;
+}
+export 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);
+}
+export async function deleteObjects(client, bucket, keys) {
+    if (keys.length === 0)
+        return [];
+    const { DeleteObjectsCommand } = await loadS3Sdk();
+    const failed = [];
+    for (let offset = 0; offset < keys.length; offset += S3_DELETE_BATCH_MAX) {
+        const chunk = keys.slice(offset, offset + 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';
+export function backlinkMetadata(row) {
+    return { [PK_FIELD]: encodeKeyPart(row.pk), [SK_FIELD]: encodeKeyPart(row.sk) };
+}
+async function backoffSleep(delayMs, release) {
+    try {
+        await sleep(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;
+        absorbLoggerFailure(() => release.logger.warn(`${release.operation}: refusing to delete an S3 object outside this row's scope`, {
+            key: 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;
+}
+export async function cleanUpS3Orphans(offloader, release) {
+    const orphans = selectOrphans(offloader, release);
+    if (orphans.length === 0)
+        return;
+    const maxAttempts = release.maxAttempts ?? S3_MAX_ATTEMPTS;
+    let delay = 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;
+            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 || !isTransientS3Error(lastError))
+                break;
+            if (await backoffSleep(delay, release))
+                break;
+            delay = nextBackoffDelay(delay);
+        }
+    }
+    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: truncateForLog(failureLabel(lastError)) }));
+}

package/dist/esm/shared/concurrency.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hides how many calls run at once, and which failure a fan-out reports.
+ *
+ * A caller maps over rows, shards or payloads and gets results in input order.
+ * The worker pool, the floor that turns a bad limit into sequential work
+ * rather than none, and the rule that the first rejection wins and stops new
+ * work are decided here, as is the default of eight in flight, so tuning it
+ * touches no reader.
+ */
+/**
+ * Offloaded payloads decoded at once by one read (`getTuple` pending writes,
+ * `search` candidates, `getMessages`). Each offloaded row costs one S3 GET, so
+ * a serial loop scaled latency linearly with the row count; eight in flight
+ * keeps the win without bursting a bucket. Also the recency-index shards one
+ * listing queries at once when the adapter names no `readConcurrency`.
+ */
+export declare const DEFAULT_READ_CONCURRENCY = 8;
+/**
+ * Map `items` through `fn` with at most `limit` calls in flight.
+ *
+ * Accepts: `items` — any length, including empty, which calls `fn` never.
+ * `limit` — calls in flight; anything that is not a whole number of at least 1
+ * degrades to sequential rather than stalling, and a value above `items.length`
+ * starts only as many workers as there are items. The floor is a *range* test
+ * rather than arithmetic on purpose: `Math.min(NaN, items.length)` is `NaN`,
+ * so a `NaN` limit asked for `Array.from({ length: NaN })` workers — none —
+ * and the call resolved to an empty array having invoked `fn` on nothing.
+ * `refillDryShards` loops while any shard is dry around exactly this call, so
+ * zero workers there was a busy-spin with no I/O and no way out; only the
+ * required `concurrency` field kept it off typed paths. `fn` — receives the
+ * item and its index.
+ *
+ * Returns: the results in **input** order, not completion order.
+ *
+ * Throws: the first rejection, whatever its value. No further item is started
+ * after it, the calls already in flight are allowed to settle, and that first
+ * error is the one thrown — a later failure never displaces it. Whether one
+ * has happened is tracked by a flag rather than by testing the value, because
+ * a rejection whose value is `undefined` is indistinguishable from no rejection
+ * at all: tested by value, it would be swallowed, and its slot in the results
+ * would stay a hole.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/esm/shared/concurrency.js

@@ -0,0 +1,27 @@
+export const DEFAULT_READ_CONCURRENCY = 8;
+export 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/esm/shared/dynamodb/abort.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Hides what an abort looks like.
+ *
+ * A signal may be aborted with this library's own `ABORTED` error, a
+ * `DOMException`, a string, any other error or nothing at all. Every one of
+ * them reaches a caller as a single `ABORTED` error that is never wrapped
+ * 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.js';
+import { ErrorCode } from '../errors/error-code.js';
+/**
+ * Whether `error` is a cancellation rather than a failure.
+ *
+ * Accepts: `error` — any error, from any layer, and equally any other value a
+ * `throw` can produce, since a `catch` is where this is called; `undefined`
+ * too, the `reason` a signal aborted without one can carry.
+ *
+ * Returns: whether it carries this library's brand and `code: 'ABORTED'`,
+ * which is the contract every cancellable method documents and the only thing
+ * a caller branches on, narrowed so it can be handed on as the abort it is.
+ * An unbranded object that merely carries `code: 'ABORTED'` is not an abort,
+ * because an error a wrapper caught that only looks like an abort must still
+ * be rebranded rather than re-thrown as it is.
+ *
+ * Throws: **nothing**, for any value. A value that cannot carry a property is
+ * not a cancellation, which is the answer an uncoded `Error` gets too.
+ */
+export declare function isAbortError(error: Error | undefined): error is DynamoDBLangGraphError<ErrorCode.ABORTED>;
+/**
+ * This library's error for an aborted `signal`.
+ *
+ * Accepts: `signal` — aborted; its `reason` may be this library's own
+ * `ABORTED` error, the `DOMException` a bare `controller.abort()` produces, a
+ * string, any other error, or `undefined`.
+ *
+ * Returns: the reason unchanged when it already is this library's own
+ * `ABORTED` error, so an error does not accumulate wrappers across layers;
+ * otherwise a fresh `ABORTED` error carrying the reason as `cause` (`undefined` reason carries
+ * none).
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: `code === 'ABORTED'` holds however the signal was aborted, so a
+ * caller branches on the code rather than on the reason's shape.
+ */
+export declare function abortErrorFrom(signal: AbortSignal): DynamoDBLangGraphError<ErrorCode.ABORTED>;

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

@@ -0,0 +1,12 @@
+import { hasErrorCode, toError } from '../errors/base-error.js';
+import { ErrorCode } from '../errors/error-code.js';
+import { abortError } from '../errors/errors.js';
+export function isAbortError(error) {
+    return error !== undefined && hasErrorCode(error, ErrorCode.ABORTED);
+}
+export function abortErrorFrom(signal) {
+    const reason = signal.reason;
+    if (isAbortError(reason))
+        return reason;
+    return abortError('Operation aborted', reason === undefined ? undefined : toError(reason));
+}

package/dist/esm/shared/dynamodb/batch-write.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Hides BatchWriteItem.
+ *
+ * A call carries at most twenty-five requests, and the service may hand some
+ * 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.js';
+import { type RetryOptions } from './retry.js';
+/**
+ * DynamoDB BatchWriteItem maximum requests per call.
+ *
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html
+ */
+export declare const BATCH_WRITE_MAX = 25;
+/** Maximum retries draining UnprocessedItems / UnprocessedKeys. */
+export declare const MAX_UNPROCESSED_RETRIES = 10;
+/**
+ * Write an arbitrary number of requests, chunked into batches of 25 (the
+ * BatchWriteItem limit). Every chunk is attempted regardless of an earlier
+ * chunk's failure — order-independent writes (deletes/puts) should never
+ * lose "later" chunks just because an earlier one failed. If any chunk fails,
+ * throws `BATCH_WRITE_INCOMPLETE` reporting exactly how many
+ * chunks succeeded vs. failed, and exactly how many individual writes
+ * persisted, once every chunk has been attempted.
+ *
+ * Accepts: `requests` — any number, in any order, of writes that do not depend
+ * on each other; none is a no-op. `options` — the drain's retry budget and
+ * signal.
+ *
+ * Returns: nothing, and only when every request persisted.
+ *
+ * Throws: `ABORTED` the moment a chunk reports one, unwrapped and with no
+ * further chunk attempted — a caller who cancelled did not encounter a fault,
+ * and spending the remaining requests on a cancelled call is the opposite of
+ * what the cancel asked for. Otherwise `BATCH_WRITE_INCOMPLETE`,
+ * once every chunk has been attempted, reporting how many chunks succeeded and
+ * how many individual writes persisted. Its one caller — the rollback in
+ * history/internal/append.ts — type-asserts a caught error straight to
+ * its code's details (not `instanceof`, banned repo-wide) instead of
+ * narrowing it, on the narrower guarantee that it passes no signal, so the
+ * abort path cannot arise there; a call site that does pass one must narrow
+ * instead.
+ *
+ * Guarantees: every chunk is attempted regardless of an earlier chunk's
+ * failure — these writes are order-independent, so losing the later ones to an
+ * earlier failure would delete less than the caller asked and report no more
+ * for it. A cancel is the one exception, because it is not a failure. The
+ * count the error carries is exact, which is what lets a compensating caller
+ * revert precisely what landed, and it never counts a chunk whose error
+ * carried no count of its own.
+ */
+export declare function batchWriteAll(client: DynamoDBDocumentLike, tableName: string, requests: WriteRequest[], options?: DrainOptions): Promise<void>;
+/** Backoff/abort options shared by the drain helpers. */
+export interface DrainOptions {
+    /** The adapter's retry options, applied to every BatchWriteItem round. */
+    retry?: RetryOptions;
+    signal?: AbortSignal;
+    rng?: () => number;
+    maxRetries?: number;
+}
+/**
+ * Write `requests` with `BatchWriteItem`, re-submitting what DynamoDB returns
+ * as `UnprocessedItems` until the batch drains.
+ *
+ * Accepts: `requests` — any length, including empty, which issues no request.
+ * `options.maxRetries` — re-submission rounds, default
+ * {@link MAX_UNPROCESSED_RETRIES}. `options.retry` — the adapter's policy, whose
+ * `baseDelayMs` and `maxDelayMs` set the backoff between rounds, so one policy
+ * governs every wait this package performs. `options.signal` — aborts a wait.
+ *
+ * Returns: nothing; success means every request persisted.
+ *
+ * Throws: `BATCH_WRITE_INCOMPLETE` when the batch does not drain
+ * within the rounds allowed, or when a round's write call fails outright — its
+ * `succeededCount` is every earlier round's confirmed persists and the
+ * triggering error is the `cause`. An `ABORTED` error passes through unchanged: a
+ * caller who cancelled did not get an incomplete batch write, and every
+ * cancellable method documents `ABORTED`.
+ *
+ * Guarantees: **every** error this function throws is one of those two — a
+ * `BATCH_WRITE_INCOMPLETE` error carrying an accurate `succeededCount`, or an
+ * `ABORTED` error. {@link batchWriteAll} adds up those counts across chunks and
+ * depends on it.
+ */
+export declare function drainUnprocessedWrites(client: DynamoDBDocumentLike, tableName: string, requests: WriteRequest[], options?: DrainOptions): Promise<void>;

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

@@ -0,0 +1,74 @@
+import { hasErrorCode } from '../errors/base-error.js';
+import { ErrorCode } from '../errors/error-code.js';
+import { batchWriteAllIncompleteError, batchWriteIncompleteError } from '../errors/errors.js';
+import { isAbortError } from './abort.js';
+import { backoffCapMs, fullJitter, INITIAL_BACKOFF_DELAY_MS, nextBackoffDelay, sleep, withDynamoDBRetry, } from './retry.js';
+export const BATCH_WRITE_MAX = 25;
+export const MAX_UNPROCESSED_RETRIES = 10;
+export async function batchWriteAll(client, tableName, requests, options = {}) {
+    const totalChunks = Math.ceil(requests.length / BATCH_WRITE_MAX);
+    let succeededChunks = 0;
+    let succeededCount = 0;
+    const failedChunks = [];
+    for (let offset = 0; offset < requests.length; offset += BATCH_WRITE_MAX) {
+        const chunk = requests.slice(offset, offset + BATCH_WRITE_MAX);
+        try {
+            await drainUnprocessedWrites(client, tableName, chunk, options);
+            succeededChunks += 1;
+            succeededCount += chunk.length;
+        }
+        catch (error) {
+            const failure = error;
+            if (!hasErrorCode(failure, ErrorCode.BATCH_WRITE_INCOMPLETE))
+                throw failure;
+            failedChunks.push(failure);
+            succeededCount += failure.details.succeededCount;
+        }
+    }
+    if (failedChunks.length > 0) {
+        throw batchWriteAllIncompleteError({
+            succeeded: succeededChunks,
+            total: totalChunks,
+            failures: failedChunks,
+            succeededCount,
+        });
+    }
+}
+function drainBackoff(retry) {
+    const base = retry?.baseDelayMs ?? INITIAL_BACKOFF_DELAY_MS;
+    const max = backoffCapMs(base, retry?.maxDelayMs);
+    return { base: Math.min(base, max), max };
+}
+function drainFailure(error, succeededCount, pending, retries) {
+    if (isAbortError(error))
+        return error;
+    return batchWriteIncompleteError(succeededCount, pending, retries, error);
+}
+export async function drainUnprocessedWrites(client, tableName, requests, options = {}) {
+    if (requests.length === 0)
+        return;
+    const maxRetries = options.maxRetries ?? 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 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 sleep(fullJitter(delay, options.rng), options.signal);
+            delay = nextBackoffDelay(delay, maxDelay);
+        }
+        catch (error) {
+            throw drainFailure(error, initialCount - pending.length, pending, retries);
+        }
+    }
+    throw batchWriteIncompleteError(initialCount - pending.length, pending, maxRetries);
+}