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

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

@@ -1,70 +1,340 @@
 "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;
-const descriptor_keys_1 = require("../codec/descriptor-keys");
-const orphans_1 = require("../codec/s3/orphans");
-const constants_1 = require("../constants");
+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");
-/** Delete the buffered keys, best-effort clean their S3 objects, then clear it. */
-async function flushBuffer(options, buffer, progress) {
-    if (buffer.keys.length === 0)
-        return;
-    const chunks = Math.ceil(buffer.keys.length / constants_1.BATCH_WRITE_MAX);
-    try {
-        await (0, batch_write_1.batchWriteAll)(options.client, options.tableName, buffer.keys.map((Key) => ({ DeleteRequest: { Key } })));
-    }
-    catch (error) {
-        /** batchWriteAll's only throw is a BatchWriteAllIncompleteError (see batch-write.ts). */
-        const failure = error;
-        throw new errors_1.BatchWriteAllIncompleteError(progress.succeededChunks + failure.succeededChunks, progress.totalChunks + failure.totalChunks, failure.failedChunks, progress.writes + failure.succeededCount);
+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);
     }
-    progress.writes += buffer.keys.length;
-    progress.succeededChunks += chunks;
-    progress.totalChunks += chunks;
-    if (options.offloader) {
-        await (0, orphans_1.cleanUpS3Orphans)(options.offloader, (0, descriptor_keys_1.collectS3Keys)(buffer.descriptors), options.operation, options.logger);
+    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);
     }
-    buffer.keys = [];
-    buffer.descriptors = [];
+    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);
 }
 /**
- * Delete every row in a partition that belongs to the calling adapter,
- * best-effort deleting any offloaded S3 objects. Streams the partition with
- * unbounded pagination and flushes in batches, so a partition of any size is
- * deleted to completion with bounded memory — never silently truncated at the
- * in-memory page caps, and never discarding already-flushed progress if a
- * later batch fails. Returns the number of rows deleted.
+ * 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 buffer = { keys: [], descriptors: [] };
-    const progress = { writes: 0, succeededChunks: 0, totalChunks: 0 };
-    let skipped = 0;
+    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) {
-        if (!options.ownsSortKey(row.SK)) {
-            skipped += 1;
+        const sortKey = row.SK;
+        if (!options.ownsSortKey(sortKey)) {
+            state.skipped += 1;
             options.logger.warn(`${options.operation}: left a foreign row in place`, {
-                sortKey: row.SK,
+                sortKey: (0, truncate_1.truncateForLog)(sortKey),
             });
             continue;
         }
-        buffer.keys.push({ PK: row.PK, SK: row.SK });
-        for (const descriptor of options.descriptorsOf(row)) {
-            if (descriptor)
-                buffer.descriptors.push(descriptor);
+        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;
         }
-        if (buffer.keys.length >= constants_1.BATCH_WRITE_MAX)
-            await flushBuffer(options, buffer, progress);
+        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,
+        });
     }
-    await flushBuffer(options, buffer, progress);
-    options.logger.info(`${options.operation}: deleted rows`, { deleted: progress.writes, skipped });
-    return progress.writes;
+    return tally;
 }
-//# sourceMappingURL=partition-delete.js.map

package/dist/shared/dynamodb/recency-index.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Hides the recency index (record 8).
+ *
+ * A row that a cross-partition listing reaches carries two index keys: a
+ * partition that hashes its identity onto one of a fixed number of shards, and
+ * a sort key that orders it by time. A listing reads every shard at once,
+ * merges them newest first, and hands out an opaque cursor that resumes the
+ * merge. The shard function, the key format and the merge are decided here.
+ */
+import { type PageLimit } from '../validation/primitives';
+import type { AttributeMap, DynamoDBDocumentLike } from './client';
+import { type RetryOptions } from './retry';
+/** One page of a recency listing, and where the next one resumes. */
+export interface IndexPage {
+    items: AttributeMap[];
+    /** Absent when the page is the last one. */
+    nextCursor?: string;
+}
+/**
+ * Read one page of a recency listing from the index, newest first.
+ *
+ * Each shard is read one DynamoDB page at a time and the pages are merged row
+ * by row: the newest buffered row goes onto the page, and a shard whose buffer
+ * runs dry reads its next page before another row is chosen. That is correct
+ * because each shard is already sorted and no row is chosen while a shard that
+ * may hold a newer one is unread. It is also what bounds memory: a listing
+ * holds the page it is building, up to `limit` rows, plus at most one DynamoDB
+ * page per shard, and a shard none of whose buffered rows the page takes is
+ * never followed. The price is that a dry shard is read again whenever the page
+ * still needs a row, even when every row still to come is another shard's,
+ * which can cost a query per shard per page whose rows the page never takes.
+ * The alternative — one query over an unsharded index — would make every
+ * listing hit one partition, which is what the sharding exists to avoid.
+ *
+ * This replaces a full-table `Scan` with a `FilterExpression`, which consumed
+ * read capacity for every row *evaluated*, collected the whole table in memory
+ * and sorted it there.
+ *
+ * Accepts: `limit` — a `PageLimit`, already checked against the package-wide
+ * page rule by the caller's parser. `0` returns an empty page with no cursor
+ * and issues no query — and is answered here rather than left to the merge,
+ * where an empty page with shards still unread would have read
+ * `items[items.length - 1]` off an empty array to build the cursor. `cursor`
+ * — from a previous page, or none to start at the newest. `shards` — must
+ * match what the writers used. `concurrency` — how many shards are queried at
+ * once.
+ *
+ * Returns: the page, newest first, and a `nextCursor` exactly while rows may
+ * remain: a shard still buffers a row the page did not take, or has not
+ * reported its end. A cursor is never withheld while rows remain, and none is
+ * issued once every shard has reported its end, even for a page filled
+ * exactly. DynamoDB can still report a `LastEvaluatedKey` on a page that ends
+ * at a shard's last row, so the page after such a cursor may come back empty.
+ *
+ * Throws: `VALIDATION` naming `cursor`; `RESULT_TRUNCATED`
+ * for a shard whose pages do not end within `MAX_LOOP_ITERATIONS`; whatever
+ * the queries throw, including an `ABORTED` error.
+ *
+ * Guarantees: at most `concurrency` shards are queried at once; each shard is
+ * followed across DynamoDB's 1 MB page boundary, but its next page is read only
+ * when its buffer is empty and the page still needs a row, so besides the page
+ * being built, up to `limit` rows, no more than one DynamoDB page per shard is
+ * held at a time.
+ */
+export declare function queryRecencyIndex(options: IndexQueryOptions): Promise<IndexPage>;
+/**
+ * Every row of one adapter's recency index, newest first, page by page.
+ *
+ * The streaming counterpart of {@link queryRecencyIndex}, for a caller that
+ * consumes rows until it has what it needs and then stops. It replaces a
+ * full-table `Scan` whose cost scaled with the table rather than with the
+ * answer.
+ *
+ * Accepts: as {@link queryRecencyIndex}, without `limit` and `cursor` — this
+ * walks the whole index, paging internally.
+ *
+ * Returns: an async generator over every row, newest first. An early `break`
+ * fetches no further page, so a caller that needs ten rows of a large index
+ * pays for one page.
+ *
+ * Throws: as {@link queryRecencyIndex}.
+ */
+export declare function iterateRecencyIndex(options: Omit<IndexQueryOptions, 'limit' | 'cursor'>): AsyncGenerator<AttributeMap>;
+/** The adapter tags that scope GSI1, matching the partition-key tags. */
+export type IndexTag = 'CHKPT' | 'STORE' | 'SESS';
+/** How a row appears in the recency index: its adapter's tag, its identity, and its time. */
+export interface IndexTarget {
+    tag: IndexTag;
+    id: string;
+    at: string;
+}
+/** The time a row that recorded none is indexed at, older than anything indexed since. */
+export declare const BACKFILLED_AT = "1970-01-01T00:00:00.000Z";
+/**
+ * The time a backfilled row is indexed at.
+ *
+ * Accepts: `recorded` — the row's own time attribute, whatever it holds.
+ *
+ * Returns: that time when it is a string, else {@link BACKFILLED_AT}.
+ *
+ * Throws: nothing.
+ */
+export declare function backfilledAt(recorded: AttributeMap[string]): string;
+/** The two attributes a row carries to appear in GSI1. */
+export interface IndexKeys {
+    gsi1pk: string;
+    gsi1sk: string;
+}
+/** Default number of index partitions per adapter. */
+export declare const DEFAULT_INDEX_SHARDS = 8;
+/**
+ * The most shards a recency index may have. The indexed read builds every
+ * shard's partition key and issues at least one query per shard, so an
+ * unbounded value turns a config typo into an unbounded stream of requests and
+ * an out-of-memory crash. How many of those queries run at once is
+ * `readConcurrency`.
+ */
+export declare const MAX_INDEX_SHARDS = 1024;
+/**
+ * The GSI1 keys for a row that takes part in cross-partition listing.
+ *
+ * The partition key is the adapter tag plus a shard, because an index keyed by
+ * the tag alone is one partition per adapter — a single hot partition, which is
+ * worse than the table scan it replaces. AWS names the sharding requirement
+ * directly: mapping one identifier onto one partition key "will quickly create
+ * partition hot spots", and the answer is a secondary sharding model
+ * (https://docs.aws.amazon.com/whitepapers/latest/multi-tenant-saas-storage-strategies/multitenancy-on-dynamodb.html).
+ *
+ * The sort key leads with an ISO-8601 timestamp, used unparsed: its byte order
+ * already is its chronological order, so a recency listing is a key condition
+ * rather than an in-memory sort. The row's own id follows it, which makes the
+ * key total — two rows written in the same millisecond still order, so a cursor
+ * can never loop.
+ *
+ * Accepts: `tag` — the adapter's. `id` — the row's own identifier, which
+ * decides its shard and breaks ties in the sort key. `at` — an ISO-8601
+ * instant. `shards` — index partitions per adapter, at least 1; fixed at table
+ * creation, since changing it changes every row's shard and requires a
+ * backfill.
+ *
+ * Returns: the two index attributes.
+ *
+ * Throws: `VALIDATION` naming `indexShards` for a count below 1 — the read
+ * side built an empty partition list from such a value and reported an empty
+ * table full of rows.
+ *
+ * Guarantees: the same row always lands on the same shard, so a listing that
+ * queries every shard sees every row exactly once.
+ */
+export declare function indexKeys(tag: IndexTag, id: string, at: string, shards: number): IndexKeys;
+/**
+ * Every index partition of one adapter.
+ *
+ * Accepts: `shards` — the same count the rows were written with; validated
+ * here as it is in {@link indexKeys}, because a listing that silently queried
+ * an empty partition list would return nothing for a table full of rows.
+ *
+ * Returns: one partition key per shard, which a recency listing queries in
+ * parallel and merges.
+ *
+ * Throws: `VALIDATION` naming `indexShards`.
+ */
+export declare function indexPartitions(tag: IndexTag, shards: number): string[];
+/** What a recency listing needs to read one page. */
+export interface IndexQueryOptions {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    indexName: string;
+    tag: IndexTag;
+    shards: number;
+    /** Shards queried at once: the adapter's `readConcurrency`. */
+    concurrency: number;
+    /** Rows per page, checked by the caller's parser, so the query does not check it again. */
+    limit: PageLimit;
+    /** Opaque, from a previous page. */
+    cursor?: string;
+    retry?: RetryOptions;
+    signal?: AbortSignal;
+}
+/** Where one shard stands while a listing builds a page. */
+export interface ShardReader {
+    partition: string;
+    /**
+     * The rows of the shard's last DynamoDB page that are not on the listing's
+     * page yet, oldest first, so the newest is the last element and leaves with
+     * `pop()`. Never more than one page.
+     */
+    buffer: AttributeMap[];
+    /** Where the shard's next page starts; absent before its first page. */
+    startKey: AttributeMap | undefined;
+    /** True once DynamoDB reported no data past the last page read. */
+    exhausted: boolean;
+    /** DynamoDB pages read from this shard so far. */
+    pages: number;
+}
+/**
+ * A reader placed before a shard's first page.
+ *
+ * Accepts: `partition` — the shard's index partition key.
+ *
+ * Returns: a reader with an empty buffer that is not exhausted, so a listing
+ * reads its first page before choosing any row.
+ *
+ * Throws: nothing.
+ */
+export declare function shardReader(partition: string): ShardReader;
+/**
+ * Read a shard's next DynamoDB page into its buffer.
+ *
+ * `Limit` bounds the items a `Query` *evaluates*, and a page also stops at
+ * 1 MB, so a shard of large rows answers with fewer than `limit` items and a
+ * `LastEvaluatedKey`. Taking that short page as the whole shard would drop
+ * rows and report the listing complete. The key is kept here
+ * instead, and the listing reads the next page once the shard's buffer is empty
+ * and its page still needs a row. One page at a time is what bounds a listing's
+ * memory to at most one DynamoDB page per shard, besides the page it is
+ * building.
+ *
+ * Accepts: `reader` — its buffer empty and the shard not exhausted. `before` —
+ * the sort key to read below, or none for the newest. `limit` — the rows the
+ * listing's page still needs, at least 1; the shard cannot contribute more.
+ *
+ * Returns: nothing. The reader's buffer holds the page's rows, and its key,
+ * `exhausted` and page count describe what is left.
+ *
+ * Throws: `RESULT_TRUNCATED` naming `maxIterations`, without issuing
+ * a query, when the shard has already read {@link MAX_LOOP_ITERATIONS} pages —
+ * a listing fails rather than hand back a partial shard; whatever the query
+ * throws, including an `ABORTED` error.
+ */
+export declare function readShardPage(options: IndexQueryOptions, reader: ShardReader, before: string | undefined, limit: number): Promise<void>;