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

package/dist/shared/dynamodb/partition-delete.js

@@ -1,340 +0,0 @@
-"use strict";
-/**
- * Hides deleting exactly the rows of a partition that a read observed.
- *
- * A partition on a shared table can hold another adapter's rows, and a row can
- * be rewritten between the read and the delete. A foreign row is left in place,
- * each delete is pinned to the write id the read saw so a rewritten row
- * survives, the rows of a unit are skipped once one of them is refused, and an
- * object is released only once the row naming it is confirmed gone.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DELETE_CONCURRENCY = void 0;
-exports.namedDescriptor = namedDescriptor;
-exports.deletePartitionRows = deletePartitionRows;
-exports.flushPendingDeletes = flushPendingDeletes;
-const codec_1 = require("../codec/codec");
-const offloader_1 = require("../codec/s3/offloader");
-const concurrency_1 = require("../concurrency");
-const errors_1 = require("../errors/errors");
-const truncate_1 = require("../logging/truncate");
-const abort_1 = require("./abort");
-const batch_write_1 = require("./batch-write");
-const idempotent_write_1 = require("./idempotent-write");
-const paginate_1 = require("./paginate");
-const retry_1 = require("./retry");
-const table_schema_1 = require("./table-schema");
-/**
- * Conditional row deletes a partition-wide delete keeps in flight. Pinning a
- * row on the write that produced it costs one request per row where a batch
- * carried twenty-five, so issuing them one at a time would have paid a round
- * trip per row; eight at once gives most of that back while keeping a
- * partition of any size from opening a socket per row. A fixed value rather
- * than a caller option: this is a maintenance path, and it has no other knob.
- *
- * Its own literal at the same value as `DEFAULT_READ_CONCURRENCY`
- * (`src/shared/concurrency.ts`), not an alias of it — aliasing two limits
- * would move one whenever the other is retuned (see
- * `LIST_SCAN_WARN_THRESHOLD` (`src/shared/dynamodb/paginate.ts`)).
- */
-exports.DELETE_CONCURRENCY = 8;
-/**
- * One row attribute read as a named descriptor, which is the only way this
- * library fills a {@link NamedDescriptor}.
- *
- * Accepts: `row` — a row the partition read returned, whose attributes this
- * library did not necessarily write. `attribute` — the name the payload would
- * be held under.
- *
- * Returns: the named descriptor, or nothing when the row carries no usable one
- * there. An absent attribute and one holding `null` are the same answer,
- * because neither names a payload: the row contributes no id to pin on and no
- * object to release. Narrowing here rather than at each caller is what keeps
- * `descriptor` the non-null thing the type claims — a `null` cast into the
- * array by a caller reached `pinFor`, which reads a write id off it.
- *
- * Throws: nothing.
- */
-function namedDescriptor(row, attribute) {
-    const descriptor = row[attribute];
-    if (descriptor === null || descriptor === undefined)
-        return undefined;
-    return { attribute, descriptor };
-}
-/**
- * The condition the read's own observation supports: the top-level id when the
- * row carries one, else the id on the first descriptor that has one. A row
- * observed with neither gets none and is deleted unconditionally — every row
- * written before the id existed is such a row, and refusing those would leave a
- * table upgraded in place impossible to empty.
- */
-function pinFor(idAttribute, row, named) {
-    if (idAttribute !== undefined) {
-        const observed = row[idAttribute];
-        if (typeof observed === 'string')
-            return (0, idempotent_write_1.writeIdGuard)(idAttribute, observed);
-    }
-    for (const entry of named) {
-        const { writeId } = entry.descriptor;
-        if (writeId !== undefined)
-            return (0, idempotent_write_1.writeIdGuard)(entry.attribute, writeId, idempotent_write_1.WRITE_ID_ATTRIBUTE);
-    }
-    return undefined;
-}
-/** The row as a buffered delete: its key, its pin, its objects and its unit. */
-function pendingDelete(options, row) {
-    const named = options.descriptorsOf(row);
-    return {
-        key: (0, table_schema_1.rowKeyOf)(row),
-        guard: pinFor(options.idAttribute, row, named),
-        descriptors: named.map((entry) => entry.descriptor),
-        unit: options.unitOf?.(row),
-    };
-}
-/** Whether an earlier kind's refusal already settled this row's unit. */
-function unitRefused(options, row, state) {
-    const unit = options.unitOf?.(row);
-    return unit !== undefined && state.units.has(unit);
-}
-/**
- * The cancel among a flush's failures, when the caller's signal fired. A row
- * whose delete was cancelled is neither deleted nor failed, so reporting the
- * pass as an incomplete delete told a caller branching on `ABORTED` that its
- * own stop was a fault.
- */
-function cancelAmong(failures) {
-    return failures.find(abort_1.isAbortError);
-}
-/** Delete the buffered rows, fold what they settled into the pass, and empty the buffer. */
-async function flushBuffer(options, state) {
-    if (state.buffer.length === 0)
-        return;
-    const tally = await flushPendingDeletes(options, state.buffer.splice(0));
-    state.deleted += tally.deleted;
-    state.skipped += tally.refused;
-    // Refusals are deliberately out of this total. They are not rows the pass
-    // failed to delete; they are rows it was never entitled to delete, already
-    // counted as `skipped` and reported on their own line. Counting them here
-    // would make the error read `1/3 row(s) succeeded, 1 row(s) failed` and leave
-    // the reader to guess at the third.
-    state.attempted += tally.deleted + tally.failures.length;
-    for (const unit of tally.refusedUnits)
-        state.units.add(unit);
-    if (tally.failures.length === 0)
-        return;
-    const cancelled = cancelAmong(tally.failures);
-    if (cancelled !== undefined)
-        throw cancelled;
-    const { deleted, attempted } = state;
-    throw (0, errors_1.batchWriteAllIncompleteError)({
-        succeeded: deleted,
-        total: attempted,
-        failures: tally.failures,
-        succeededCount: deleted,
-        unit: 'row',
-    });
-}
-/**
- * Delete exactly the rows of one partition that this adapter's read observed.
- *
- * Accepts: `params` — the partition query, which carries no sort-key
- * condition. `ownsSortKey` — decides per row; a row it rejects is left in
- * place and reported at `warn`, which is what keeps a shared table's other
- * adapters intact. `descriptorsOf` — the offloaded payloads a row references,
- * each named by the attribute holding it. `idAttribute`, `unitOf` and `kindOf`
- * — the per-write id, the unit and the kind boundary, for an adapter whose
- * rows have them. `scope` — the partition's own leading S3 key parts; an object
- * outside their path is never deleted. `signal` — stops the read between pages.
- *
- * Returns: how many rows were deleted, not counting the ones left in place.
- *
- * Throws: `ABORTED` when the signal fires, whether between pages or during
- * a row's delete, unwrapped and with no further row issued — a cancel is not a
- * delete that half-landed. Otherwise `BATCH_WRITE_INCOMPLETE` when
- * a row's delete fails, carrying what did succeed across every earlier flush.
- * S3 cleanup never throws, whatever it finds.
- *
- * Guarantees: every delete is pinned on the per-write id the read observed, so
- * a row rewritten after that read is left in place and reported rather than
- * erased with the object it names. A row observed carrying no id is deleted
- * unconditionally, as it was before the pin existed. The read is deliberately
- * uncapped (`maxItems` and `maxIterations` are `Infinity`), so a partition of
- * any size is deleted to completion rather than truncated at the in-memory page
- * caps — memory stays bounded because rows are flushed in batches of
- * {@link BATCH_WRITE_MAX} and never accumulated. The carry-forward depends on
- * the scan being **ascending**, which is the default the partition queries rely
- * on: a kind's rows are settled before the next kind's are issued, so a refusal
- * suppresses the rest of its unit. A failure part-way keeps the rows already
- * deleted; this is a single pass over a quiescent partition, not a transaction.
- */
-async function deletePartitionRows(options) {
-    const state = { buffer: [], deleted: 0, attempted: 0, skipped: 0, units: new Set() };
-    let kind;
-    const pages = (0, paginate_1.paginateQuery)({
-        client: options.client,
-        params: options.params,
-        retry: options.retry,
-        signal: options.signal,
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
-    });
-    for await (const row of pages) {
-        const sortKey = row.SK;
-        if (!options.ownsSortKey(sortKey)) {
-            state.skipped += 1;
-            options.logger.warn(`${options.operation}: left a foreign row in place`, {
-                sortKey: (0, truncate_1.truncateForLog)(sortKey),
-            });
-            continue;
-        }
-        const rowKind = options.kindOf?.(row);
-        if (rowKind !== kind) {
-            await flushBuffer(options, state);
-            kind = rowKind;
-        }
-        if (unitRefused(options, row, state)) {
-            state.skipped += 1;
-            options.logger.warn(`${options.operation}: skipped a row whose unit was refused`, {
-                sortKey: (0, truncate_1.truncateForLog)(sortKey),
-            });
-            continue;
-        }
-        state.buffer.push(pendingDelete(options, row));
-        if (state.buffer.length >= batch_write_1.BATCH_WRITE_MAX)
-            await flushBuffer(options, state);
-    }
-    await flushBuffer(options, state);
-    const { deleted, skipped } = state;
-    options.logger.info(`${options.operation}: deleted rows`, { deleted, skipped });
-    return deleted;
-}
-/**
- * Record a row the pin turned away: left in place, nothing released, reported.
- *
- * Reported *before* it is counted, deliberately. The report calls the caller's
- * own `Logger`, and a `Logger` that throws makes this row's handling
- * incomplete; {@link deleteRow} then files it as a failure. Counting it first
- * would leave the same row counted as a refusal the pass also reports as a
- * failure. One row, one outcome.
- */
-function recordRefusal(deps, row, tally) {
-    deps.logger.warn(`${deps.operation}: left a row rewritten since the read`, {
-        sortKey: (0, truncate_1.truncateForLog)(row.key.SK),
-    });
-    tally.refused += 1;
-    if (row.unit !== undefined)
-        tally.refusedUnits.push(row.unit);
-}
-/**
- * Settle one row, turning a lost pin into an outcome rather than a rejection.
- *
- * A rejection carrying the row means it was rewritten after the read: the row
- * stays, its objects stay, and the pass reports it. A rejection carrying no row
- * means it is already gone — a racing delete, or this pass's own earlier
- * attempt whose acknowledgement was lost — which is the outcome the caller
- * asked for, so it counts as deleted and its objects are released. Anything
- * else is a genuine failure and is rethrown, so the pass ends rather than
- * reporting a delete it did not make.
- */
-async function settleRow(deps, row, tally) {
-    try {
-        await (0, retry_1.withDynamoDBRetry)((request) => deps.client.delete({
-            TableName: deps.tableName,
-            Key: row.key,
-            ...row.guard,
-        }, request), deps.retry);
-    }
-    catch (error) {
-        const rejection = error;
-        if (!(0, idempotent_write_1.isConditionalCheckFailed)(rejection))
-            throw rejection;
-        if ((0, idempotent_write_1.rejectedRow)(rejection) !== undefined) {
-            recordRefusal(deps, row, tally);
-            return;
-        }
-    }
-    tally.deleted += 1;
-    tally.released.push(...row.descriptors);
-}
-/**
- * Delete one row, recording whatever stops it before letting the flush end.
- *
- * The recording wraps the whole of {@link settleRow} rather than sitting in the
- * one branch that first needed it, because the delete's own rejection is not
- * the only thing in there that can throw. Reading the row a rejection carries
- * is a decode, and it fails on an `Item` that arrives already unmarshalled —
- * which the stock document client does not produce, but a client wrapped
- * through the documented injection seam can. Reporting a refusal is a call into
- * the caller's own `Logger`, which is consumer code. Recorded only in that one
- * branch, neither would reach `tally.failures`, and an empty `failures` is
- * exactly what the pass reads as "nothing went wrong": one such throw would
- * abandon the rest of the buffer and the pass would still resolve, reporting a
- * thread deleted that was mostly still there.
- */
-async function deleteRow(deps, row, tally) {
-    try {
-        await settleRow(deps, row, tally);
-    }
-    catch (error) {
-        tally.failures.push(error);
-        throw error;
-    }
-}
-/**
- * Delete a buffer of rows, each pinned on what the read observed of it, then
- * release the objects of the rows that are confirmed gone.
- *
- * Accepts: `deps` — the client, the table, and the logging, retry and offload
- * collaborators of the pass this flush belongs to. `rows` — the buffer,
- * each row carrying its key, its pin and the objects it names.
- *
- * Returns: the tally — rows deleted, rows refused and the units they belonged
- * to, the failures, and the descriptors released.
- *
- * Throws: nothing. Every failure stops the flush from starting further rows and
- * is handed back in `failures` for the caller to end the pass with — the
- * delete's own rejection, and equally a throw from decoding a rejection's
- * attached row or from the caller's logger, neither of which is this pass's to
- * absorb. A refusal never stops anything. S3 cleanup never throws either
- * ({@link cleanUpS3Orphans}).
- *
- * Guarantees: an empty `failures` means every row of the buffer was settled.
- * The flush cannot both lose a failure and hand back a clean tally, which is
- * what let a pass log a deleted thread over a partition it had mostly left
- * alone. At most {@link DELETE_CONCURRENCY} requests are in flight. There
- * is one request per row - that is the price of a condition, which a batch
- * write silently ignores - but they cost a bounded number of sequential rounds
- * rather than one per row, and a partition of any size cannot open a socket
- * per row. A row the pin
- * turned away is left exactly as the racing writer left it, and nothing it
- * names is released — a live row still names those objects.
- */
-async function flushPendingDeletes(deps, rows) {
-    const tally = {
-        deleted: 0,
-        refused: 0,
-        refusedUnits: [],
-        failures: [],
-        released: [],
-    };
-    try {
-        await (0, concurrency_1.mapWithConcurrency)(rows, exports.DELETE_CONCURRENCY, (row) => deleteRow(deps, row, tally));
-    }
-    catch {
-        // The only thing that reaches here is {@link deleteRow}'s own rethrow, and
-        // it records every failure it rethrows — the delete's rejection, the decode
-        // of a rejection's attached row, and the caller's logger alike. So what is
-        // dropped here is a second reference to something already in
-        // `tally.failures`, never the only record of it, and the throw's remaining
-        // job was to stop further rows from being started.
-    }
-    if (deps.offloader) {
-        await (0, offloader_1.cleanUpS3Orphans)(deps.offloader, {
-            keys: (0, codec_1.collectS3Keys)(tally.released),
-            operation: deps.operation,
-            logger: deps.logger,
-            scope: deps.scope,
-        });
-    }
-    return tally;
-}