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

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

@@ -1,173 +0,0 @@
-"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;
-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 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 `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.
- */
-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;
-            // 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 (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);
-}

package/dist/shared/dynamodb/paginate.js

@@ -1,188 +0,0 @@
-"use strict";
-/**
- * Hides that a Query or a Scan is many pages.
- *
- * A read receives rows one at a time and never sees a page boundary. How many
- * rows and pages it may collect before it refuses with `RESULT_TRUNCATED`
- * rather than truncating silently, how a read that stopped exactly at its row
- * cap probes whether anything remained, and where cancellation is checked
- * between pages are decided here, the same way for a Query and a Scan.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_SCAN_WARN_THRESHOLD = exports.MAX_TOTAL_ROWS_IN_MEMORY = exports.MAX_LOOP_ITERATIONS = void 0;
-exports.paginateQuery = paginateQuery;
-exports.paginatePages = paginatePages;
-exports.paginateScan = paginateScan;
-const errors_1 = require("../errors/errors");
-const abort_1 = require("./abort");
-const retry_1 = require("./retry");
-/** Hard cap on query-pagination loop iterations (runaway-loop guard). */
-exports.MAX_LOOP_ITERATIONS = 1000;
-/** Hard cap on rows collected into memory across a paginated query. */
-exports.MAX_TOTAL_ROWS_IN_MEMORY = 10000;
-/**
- * Raw rows a single `listCheckpoints` call may pull before it warns. The read
- * itself is deliberately unbounded: capping it would count raw rows rather
- * than filter-matched ones, so a caller asking for a handful of rare matches
- * over a large thread would get a hard error instead of the true answer. The
- * warning gives the operational signal without that wrong error.
- *
- * Its own literal, deliberately: this is the point at which a scan is worth
- * telling an operator about, which is independent of
- * {@link MAX_TOTAL_ROWS_IN_MEMORY}'s hard collection cap. Aliasing the two —
- * so one reused the other's literal — would let retuning the memory cap
- * silently move the warning threshold too, for constants that answer
- * unrelated questions, and would make knip report the pair as a duplicate
- * export.
- */
-exports.LIST_SCAN_WARN_THRESHOLD = 10000;
-/**
- * Every row a Query returns, across all its pages.
- *
- * Accepts: `params` — the Query input; `ExclusiveStartKey` is set per page and
- * anything the caller put there is replaced. `retry` and `signal` are applied
- * to each page read, `maxItems` / `maxIterations` to the walk (see
- * {@link paginatePages}).
- *
- * Returns: an async generator over the rows, following `LastEvaluatedKey`
- * until it is absent. A page carrying no `Items` is an empty page, not the end.
- *
- * Throws: whatever the page read throws, plus the caps and abort behaviour of
- * {@link paginatePages}.
- */
-function paginateQuery(options) {
-    return paginatePages(async (startKey) => {
-        const page = await (0, retry_1.withDynamoDBRetry)((request) => options.client.query({ ...options.params, ExclusiveStartKey: startKey }, request), { ...options.retry, signal: options.signal });
-        return {
-            items: page.Items ?? [],
-            lastKey: page.LastEvaluatedKey,
-        };
-    }, options);
-}
-/** Read the next page, honouring the abort signal and the iteration cap first. */
-async function readPage(reader, startKey) {
-    if (reader.iterations >= reader.maxIterations) {
-        throw (0, errors_1.resultTruncatedError)('maxIterations', reader.maxIterations);
-    }
-    if (reader.signal?.aborted)
-        throw (0, abort_1.abortErrorFrom)(reader.signal);
-    reader.iterations += 1;
-    return reader.fetchPage(startKey);
-}
-/**
- * Yield one page's rows, counting toward the shared `state.yielded` budget.
- * Reaching the cap with unyielded rows still on the page is a truncation;
- * reaching it on the last row is reported as `capped` for the caller to settle.
- *
- * Synchronous and private: nothing here awaits, and `paginatePages` delegates
- * to it with `yield*` from inside its own `async function*`, so the rows it
- * yields still reach callers through the same async-generator protocol.
- */
-function* yieldPageRows(page, state, maxItems) {
-    for (let index = 0; index < page.items.length; index++) {
-        yield page.items[index];
-        state.yielded += 1;
-        if (state.yielded >= maxItems) {
-            if (index < page.items.length - 1)
-                throw (0, errors_1.resultTruncatedError)('maxItems', maxItems);
-            return 'capped';
-        }
-    }
-    return 'exhausted';
-}
-/**
- * Whether anything remains past `startKey`. DynamoDB returns a
- * `LastEvaluatedKey` whenever it stopped *evaluating* at the 1 MB boundary,
- * whether or not a later item passes the filter, so a trailing key alone proves
- * nothing: the keys are followed until a page carries an item (truncated) or
- * they run out (the result was complete). The probe is charged against the same
- * iteration budget and honours the same signal as the read itself.
- */
-async function dataRemains(reader, startKey) {
-    let key = startKey;
-    while (key !== undefined) {
-        const page = await readPage(reader, key);
-        if (page.items.length > 0)
-            return true;
-        key = page.lastKey;
-    }
-    return false;
-}
-/** Reject a cap that admits nothing; `Infinity` is the way to ask for no cap. */
-function assertPositiveCap(value, field) {
-    if (!(value >= 1)) {
-        throw (0, errors_1.validationError)(`${field} must be at least 1 (pass Infinity to read to completion)`, field);
-    }
-    return value;
-}
-/**
- * Drive a paged DynamoDB read to completion, yielding each item.
- *
- * Accepts: `fetchPage` — performs one page read from a start key.
- * `options.maxItems` — how many items may be yielded, default
- * {@link MAX_TOTAL_ROWS_IN_MEMORY}. `options.maxIterations` — how many page
- * reads may be issued, default {@link MAX_LOOP_ITERATIONS}; the probe below is
- * charged against it too. Both accept `Infinity` to read to true completion
- * (deletes do), and both must otherwise be at least 1 — an accepted cap of 0
- * would yield one item before noticing. `options.signal` — checked before every
- * fetch. `options.retry` is the page reader's own concern.
- *
- * Returns: an async generator over the items, continuing past empty pages.
- *
- * Throws: `VALIDATION` naming `maxItems` or `maxIterations` for a cap below
- * 1; `ABORTED` when the signal is already aborted at a page boundary; and
- * `RESULT_TRUNCATED` when a cap is reached while data actually
- * remains — a partial result is never returned silently.
- *
- * Guarantees: reaching `maxItems` on the last item of a page is not by itself a
- * truncation. DynamoDB returns a `LastEvaluatedKey` whenever it stopped
- * *evaluating* at the 1 MB boundary, whether or not a later item passes the
- * filter, so the remaining keys are followed until one carries an item
- * (truncated) or they run out (the result was complete).
- */
-async function* paginatePages(fetchPage, options = {}) {
-    const maxItems = assertPositiveCap(options.maxItems ?? exports.MAX_TOTAL_ROWS_IN_MEMORY, 'maxItems');
-    const reader = {
-        fetchPage,
-        maxIterations: assertPositiveCap(options.maxIterations ?? exports.MAX_LOOP_ITERATIONS, 'maxIterations'),
-        iterations: 0,
-        signal: options.signal,
-    };
-    const state = { yielded: 0 };
-    let startKey;
-    for (;;) {
-        const page = await readPage(reader, startKey);
-        const outcome = yield* yieldPageRows(page, state, maxItems);
-        if (outcome === 'capped') {
-            if (await dataRemains(reader, page.lastKey))
-                throw (0, errors_1.resultTruncatedError)('maxItems', maxItems);
-            return;
-        }
-        startKey = page.lastKey;
-        if (startKey === undefined)
-            return;
-    }
-}
-/**
- * Every item a Scan returns, across all its pages.
- *
- * Accepts: as {@link paginateQuery}; only the request differs.
- *
- * Returns: as {@link paginateQuery} — an async generator over the items, which
- * a consumer may abandon early to stop reading.
- *
- * Throws: as {@link paginateQuery}.
- *
- * A `Scan` reads every row of the table before filtering, so the four reads
- * allowed to call this are fixed and guarded; `test/static/guards/scan-sites.ts`
- * lists them and states the rule they follow.
- */
-function paginateScan(options) {
-    return paginatePages(async (startKey) => {
-        const page = await (0, retry_1.withDynamoDBRetry)((request) => options.client.scan({ ...options.params, ExclusiveStartKey: startKey }, request), { ...options.retry, signal: options.signal });
-        return {
-            items: page.Items ?? [],
-            lastKey: page.LastEvaluatedKey,
-        };
-    }, options);
-}