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

package/dist/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/shared/concurrency.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_READ_CONCURRENCY = void 0;
+exports.mapWithConcurrency = mapWithConcurrency;
+/**
+ * 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`.
+ */
+exports.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.
+ */
+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));
+    // `failure` is stored `Error | undefined` only because that is as far as a
+    // `catch` binding's value can be named without `unknown`, which is banned
+    // in src; the JSDoc above states the real contract — whatever `fn` rejected
+    // with, unchanged, and that can be `undefined` itself. The assertion below
+    // changes nothing at runtime; it only lets `only-throw-error` see the type
+    // this throw already had before that rule existed.
+    if (failed)
+        throw failure;
+    return results;
+}

package/dist/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';
+import { ErrorCode } from '../errors/error-code';
+/**
+ * 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/shared/dynamodb/abort.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAbortError = isAbortError;
+exports.abortErrorFrom = abortErrorFrom;
+const base_error_1 = require("../errors/base-error");
+const error_code_1 = require("../errors/error-code");
+const errors_1 = require("../errors/errors");
+/**
+ * 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.
+ */
+function isAbortError(error) {
+    return error !== undefined && (0, base_error_1.hasErrorCode)(error, error_code_1.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.
+ */
+function abortErrorFrom(signal) {
+    const reason = signal.reason;
+    if (isAbortError(reason))
+        return reason;
+    return (0, errors_1.abortError)('Operation aborted', reason === undefined ? undefined : (0, base_error_1.toError)(reason));
+}

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

@@ -1,23 +1,86 @@
-import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
-import { DrainOptions } from './drain-unprocessed';
-import type { WriteRequest } from './types';
+/**
+ * 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';
+import { type RetryOptions } from './retry';
+/**
+ * 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 {@link BatchWriteAllIncompleteError} reporting exactly how many
+ * 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.
  *
- * This is this function's ONLY throw site. Two callers —
- * checkpointer/internal/special-write-cleanup.ts and
- * history/internal/append-saga.ts — type-assert a caught error straight to
- * {@link BatchWriteAllIncompleteError} on that guarantee (not `instanceof`,
- * banned repo-wide) instead of narrowing it, since this project enforces
- * 100% branch coverage and a defensive else-branch here would be
- * unreachable, hence untestable. Adding another throw path to this function
- * requires updating both call sites.
+ * 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 batchWriteAll(client: DynamoDBDocument, tableName: string, requests: WriteRequest[], options?: DrainOptions): Promise<void>;
-//# sourceMappingURL=batch-write.d.ts.map
+export declare function drainUnprocessedWrites(client: DynamoDBDocumentLike, tableName: string, requests: WriteRequest[], options?: DrainOptions): Promise<void>;

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

@@ -1,54 +1,173 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_UNPROCESSED_RETRIES = exports.BATCH_WRITE_MAX = void 0;
 exports.batchWriteAll = batchWriteAll;
-const constants_1 = require("../constants");
+exports.drainUnprocessedWrites = drainUnprocessedWrites;
+const base_error_1 = require("../errors/base-error");
+const error_code_1 = require("../errors/error-code");
 const errors_1 = require("../errors/errors");
-const drain_unprocessed_1 = require("./drain-unprocessed");
+const abort_1 = require("./abort");
+const retry_1 = require("./retry");
+/**
+ * DynamoDB BatchWriteItem maximum requests per call.
+ *
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html
+ */
+exports.BATCH_WRITE_MAX = 25;
+/** Maximum retries draining UnprocessedItems / UnprocessedKeys. */
+exports.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 {@link BatchWriteAllIncompleteError} reporting exactly how many
+ * 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.
  *
- * This is this function's ONLY throw site. Two callers —
- * checkpointer/internal/special-write-cleanup.ts and
- * history/internal/append-saga.ts — type-assert a caught error straight to
- * {@link BatchWriteAllIncompleteError} on that guarantee (not `instanceof`,
- * banned repo-wide) instead of narrowing it, since this project enforces
- * 100% branch coverage and a defensive else-branch here would be
- * unreachable, hence untestable. Adding another throw path to this function
- * requires updating both call sites.
+ * 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.
  */
 async function batchWriteAll(client, tableName, requests, options = {}) {
-    const totalChunks = Math.ceil(requests.length / constants_1.BATCH_WRITE_MAX);
+    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 += constants_1.BATCH_WRITE_MAX) {
-        const chunk = requests.slice(offset, offset + constants_1.BATCH_WRITE_MAX);
+    for (let offset = 0; offset < requests.length; offset += exports.BATCH_WRITE_MAX) {
+        const chunk = requests.slice(offset, offset + exports.BATCH_WRITE_MAX);
         try {
-            await (0, drain_unprocessed_1.drainUnprocessedWrites)(client, tableName, chunk, options);
+            await drainUnprocessedWrites(client, tableName, chunk, options);
             succeededChunks += 1;
             succeededCount += chunk.length;
         }
         catch (error) {
-            /**
-             * drainUnprocessedWrites has exactly three throw sites and every one
-             * constructs a BatchWriteIncompleteError with an accurate
-             * succeededCount — asserted, not name-checked, since the false case is
-             * unreachable and this project enforces 100% branch coverage with no
-             * exceptions (see drain-unprocessed.ts).
-             */
-            const err = error;
-            failedChunks.push(err);
-            succeededCount += err.succeededCount;
+            const failure = error;
+            // Anything but an incomplete batch is the drain's other documented
+            // throw, a cancel, and it leaves the loop at once. Reading the brand and
+            // code rather than the class is the same realm-safe test the rest of
+            // this package makes, and it is what keeps a count this function cannot
+            // know out of the total: adding an absent `succeededCount` made it
+            // `NaN`.
+            if (!(0, base_error_1.hasErrorCode)(failure, error_code_1.ErrorCode.BATCH_WRITE_INCOMPLETE))
+                throw failure;
+            failedChunks.push(failure);
+            succeededCount += failure.details.succeededCount;
         }
     }
     if (failedChunks.length > 0) {
-        throw new errors_1.BatchWriteAllIncompleteError(succeededChunks, totalChunks, failedChunks, succeededCount);
+        throw (0, errors_1.batchWriteAllIncompleteError)({
+            succeeded: succeededChunks,
+            total: totalChunks,
+            failures: failedChunks,
+            succeededCount,
+        });
+    }
+}
+/**
+ * The backoff window between rounds: the adapter's configured policy, never
+ * module constants — reading the constants here instead would leave a caller
+ * who raises `baseDelayMs` still waiting the module's default 100 ms on this
+ * one path, breaking the documented "one policy governs every wait".
+ */
+function drainBackoff(retry) {
+    return {
+        base: retry?.baseDelayMs ?? retry_1.INITIAL_BACKOFF_DELAY_MS,
+        max: retry?.maxDelayMs ?? retry_1.MAX_BACKOFF_DELAY_MS,
+    };
+}
+/**
+ * The error a failed round raises.
+ *
+ * An `ABORTED` error passes through unchanged: a caller who cancelled did not get
+ * an incomplete batch write, and wrapping it reported
+ * `BATCH_WRITE_INCOMPLETE` for an aborted `deleteThread`, contradicting the
+ * `ABORTED` every cancellable method documents. Anything else becomes a
+ * `BATCH_WRITE_INCOMPLETE` error carrying what did persist.
+ */
+function drainFailure(error, succeededCount, pending, retries) {
+    if ((0, abort_1.isAbortError)(error))
+        return error;
+    return (0, errors_1.batchWriteIncompleteError)(succeededCount, pending, retries, error);
+}
+/**
+ * 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.
+ */
+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_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_1.sleep)((0, retry_1.fullJitter)(delay, options.rng), options.signal);
+            delay = (0, retry_1.nextBackoffDelay)(delay, maxDelay);
+        }
+        catch (error) {
+            throw drainFailure(error, initialCount - pending.length, pending, retries);
+        }
     }
+    throw (0, errors_1.batchWriteIncompleteError)(initialCount - pending.length, pending, maxRetries);
 }
-//# sourceMappingURL=batch-write.js.map

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

@@ -1,7 +1,124 @@
-/** One entry of a TransactWriteItems/TransactionCanceledException's CancellationReasons. */
+/**
+ * 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.
+ */
+import type { AttributeValue } from '@aws-sdk/client-dynamodb';
+/**
+ * One entry of a TransactWriteItems/TransactionCanceledException's
+ * CancellationReasons. `Item` is the row the service attached to the item whose
+ * condition failed, in raw AttributeValue form — an error payload is not
+ * unmarshalled by the document client the way a response is.
+ */
 export interface CancellationReason {
     Code?: string;
+    Item?: Record<string, AttributeValue>;
 }
-/** Extract `CancellationReasons` from a transaction-cancellation error, if present. */
-export declare function getCancellationReasons(error: Error): CancellationReason[] | undefined;
-//# sourceMappingURL=cancellation.d.ts.map
+/**
+ * The fields a write's rejection can arrive in: the exception's own name, and
+ * the per-item reasons a cancelled transaction carries instead. Both are
+ * optional because this is an arbitrary error seen through a reader's eyes — a
+ * rejection outside a transaction names itself and carries no reasons, one
+ * inside a transaction carries reasons under a name of its own.
+ */
+export interface RejectionFields {
+    name?: string;
+    CancellationReasons?: CancellationReason[];
+}
+/**
+ * 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.
+ */
+export declare function getCancellationReasons(error: RejectionFields): CancellationReason[] | undefined;
+/**
+ * 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.
+ */
+export declare function conditionalCheckFailure(error: RejectionFields): CancellationReason | undefined;
+/**
+ * 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}.
+ */
+export declare function transientCancellation(error: RejectionFields): boolean | undefined;
+/**
+ * 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.
+ */
+export declare function throttledCancellation(error: RejectionFields): boolean;
+/**
+ * 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.
+ */
+export declare function conditionFailedAt(error: RejectionFields, index: number): boolean;