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

package/dist/cjs/store/actions/search.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchItems = searchItems;
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const semantic_search_js_1 = require("../internal/semantic-search.js");
+const table_search_js_1 = require("../internal/table-search.js");
+const vector_index_js_1 = require("../internal/vector-index.js");
+async function searchItems(context, search, signal) {
+    const { offset, limit } = search;
+    if (limit === 0)
+        return [];
+    if (search.query && (0, vector_index_js_1.hasVectorBackend)(context)) {
+        const ranked = await (0, vector_index_js_1.searchViaBackend)(context, search, signal);
+        return ranked.slice(offset, offset + limit);
+    }
+    if (!search.query || !context.index) {
+        const page = await (0, table_search_js_1.collectCandidates)(context, search, { kind: 'page', need: offset + limit }, signal);
+        return page.map(({ item }) => ({ ...item, score: undefined })).slice(offset, offset + limit);
+    }
+    const candidates = await (0, table_search_js_1.collectCandidates)(context, search, { kind: 'semantic', cap: context.maxSearchCandidates }, signal);
+    const queryVector = await context.index.embeddings.embedQuery(search.query);
+    (0, semantic_search_js_1.assertVectorDims)(context.index, queryVector, 'query');
+    const ranked = (0, table_search_js_1.rankInMemory)(candidates, queryVector, context.maxSearchCandidates, (count) => context.logger.warn('search: some candidates carry an embedding of a different dimension than the query and ' +
+        'were ranked unscored; re-embed them with reconcileVectorIndex or a re-put', { namespacePrefix: (0, truncate_js_1.truncateLabelsForLog)(search.namespacePrefix), count }));
+    return ranked.slice(offset, offset + limit);
+}

package/dist/cjs/store/internal/batch-plan.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Hides how a batch runs: every read first, against the state the batch found,
+ * then one write per item, concurrently within each phase.
+ *
+ * That is how the reference store evaluates a batch — a get, a search or a
+ * listing is answered as the batch found things, and the puts are applied
+ * afterwards, the last one per item winning — so a graph developed against it
+ * gets the same answers here, and two tasks of one superstep that touch the
+ * same item get answers that do not depend on which of them was enqueued
+ * first. The operations of one phase share the call's one decode budget,
+ * divided between them, so a batch of concurrent searches costs no more memory
+ * than a single one.
+ */
+import type { ParsedOperation } from './parse.js';
+/** The two phases of a batch: the indices of its reads, and of the one write kept per item. */
+export interface BatchPlan {
+    readonly reads: number[];
+    readonly writes: number[];
+}
+/**
+ * Split a batch into the reads it answers first and the writes it applies
+ * afterwards.
+ *
+ * Accepts: `operations` — in caller order.
+ *
+ * Returns: the indices of every get, search and listing, in caller order, and
+ * the index of the last put or delete addressing each item, in caller order.
+ * An earlier write to the same item is superseded before it is sent: the
+ * reference applies only the last put per key, and sending both would race
+ * two compare-and-swaps for an outcome the batch has already decided.
+ *
+ * Throws: nothing.
+ */
+export declare function planBatch(operations: readonly ParsedOperation[]): BatchPlan;
+/**
+ * Run a batch: its reads concurrently, at most `limit` in flight, then its
+ * writes the same way. Results come back in operation order.
+ *
+ * Accepts: `operations` — in caller order. `dispatch` — handed each operation
+ * and its share of the budget: `limit` divided by the operations its phase
+ * keeps in flight, and never less than one. `limit` — operations in flight
+ * within one phase.
+ *
+ * Returns: the results in operation order, not completion order; a write
+ * superseded by a later one to the same item answers `null`, as the write
+ * that was sent does, without having been sent.
+ *
+ * Throws: the first failure. Any failure rejects the whole batch: no operation
+ * in a later phase starts, the ones already in flight settle, and that first
+ * error is the one thrown.
+ *
+ * Guarantees: every read sees the state before any of the batch's writes, and
+ * the operations of one call decode at most `limit` payloads at once between
+ * them, which is what `readConcurrency`'s documented memory ceiling assumes.
+ */
+export declare function runBatch<R>(operations: readonly ParsedOperation[], dispatch: (operation: ParsedOperation, readConcurrency: number) => Promise<R>, limit?: number): Promise<(R | null)[]>;

package/dist/cjs/store/internal/batch-plan.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planBatch = planBatch;
+exports.runBatch = runBatch;
+const concurrency_js_1 = require("../../shared/concurrency.js");
+function itemOf(address) {
+    return JSON.stringify([address.namespace, address.key]);
+}
+function planBatch(operations) {
+    const reads = [];
+    const lastWrite = new Map();
+    operations.forEach((op, index) => {
+        if (op.kind === 'put' || op.kind === 'delete')
+            lastWrite.set(itemOf(op.address), index);
+        else
+            reads.push(index);
+    });
+    return { reads, writes: [...lastWrite.values()].sort((a, b) => a - b) };
+}
+async function runBatch(operations, dispatch, limit = concurrency_js_1.DEFAULT_READ_CONCURRENCY) {
+    const results = operations.map(() => null);
+    const { reads, writes } = planBatch(operations);
+    for (const phase of [reads, writes]) {
+        if (phase.length === 0)
+            continue;
+        const share = Math.max(1, Math.floor(limit / Math.min(limit, phase.length)));
+        await (0, concurrency_js_1.mapWithConcurrency)(phase, limit, async (index) => {
+            results[index] = await dispatch(operations[index], share);
+        });
+    }
+    return results;
+}

package/dist/{store → cjs/store}/internal/filter.d.ts

@@ -2,9 +2,9 @@
  * Hides the store's filter grammar.
  *
  * Which operators a search filter accepts, how each compares a stored field —
- * ordered comparisons only between like-typed values, an absent field matching
- * nothing — and whether an item passes a search's optional filter are decided
- * here, the same way whichever search path runs.
+ * ordered comparisons only between like-typed values, an absent field
+ * satisfying only `$ne` and `$nin` — and whether an item passes a search's
+ * optional filter are decided here, the same way whichever search path runs.
  */
 import type { Item } from '@langchain/langgraph-checkpoint';
 /** A JSON value stored in an item or supplied in a filter. */

package/dist/cjs/store/internal/filter.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesStoreFilter = matchesStoreFilter;
+exports.passesFilter = passesFilter;
+const node_util_1 = require("node:util");
+function orderOf(actual, expected) {
+    if (actual < expected)
+        return -1;
+    if (actual > expected)
+        return 1;
+    return actual === expected ? 0 : undefined;
+}
+function testOrder(order, test) {
+    return order !== undefined && test(order);
+}
+function compareOrdered(actual, expected, test) {
+    if (typeof actual === 'number' && typeof expected === 'number') {
+        return testOrder(orderOf(actual, expected), test);
+    }
+    if (typeof actual === 'string' && typeof expected === 'string') {
+        return testOrder(orderOf(actual, expected), test);
+    }
+    return false;
+}
+function equalValues(actual, expected) {
+    if (typeof actual === 'number' && typeof expected === 'number') {
+        return actual === expected || (Number.isNaN(actual) && Number.isNaN(expected));
+    }
+    return (0, node_util_1.isDeepStrictEqual)(actual, expected);
+}
+const COMPARATORS = {
+    $eq: (actual, expected) => equalValues(actual, expected),
+    $ne: (actual, expected) => !equalValues(actual, expected),
+    $gt: (actual, expected) => compareOrdered(actual, expected, (order) => order > 0),
+    $gte: (actual, expected) => compareOrdered(actual, expected, (order) => order >= 0),
+    $lt: (actual, expected) => compareOrdered(actual, expected, (order) => order < 0),
+    $lte: (actual, expected) => compareOrdered(actual, expected, (order) => order <= 0),
+    $in: (actual, expected) => Array.isArray(expected) ? expected.some((candidate) => equalValues(actual, candidate)) : false,
+    $nin: (actual, expected) => Array.isArray(expected) ? !expected.some((candidate) => equalValues(actual, candidate)) : true,
+};
+function isOperatorObject(condition) {
+    return (typeof condition === 'object' &&
+        condition !== null &&
+        !Array.isArray(condition) &&
+        Object.keys(condition).every((key) => Object.prototype.hasOwnProperty.call(COMPARATORS, key)));
+}
+function matchesCondition(actual, condition) {
+    if (!isOperatorObject(condition))
+        return equalValues(actual, condition);
+    return Object.entries(condition).every(([operator, expected]) => COMPARATORS[operator](actual, expected));
+}
+function ownField(item, field) {
+    if (item === null || typeof item !== 'object')
+        return undefined;
+    return Object.hasOwn(item, field) ? item[field] : undefined;
+}
+function matchesStoreFilter(value, filter) {
+    return Object.entries(filter).every(([field, condition]) => matchesCondition(ownField(value, field), condition));
+}
+function passesFilter(item, filter) {
+    if (!filter)
+        return true;
+    return matchesStoreFilter(item.value, filter);
+}

package/dist/cjs/store/internal/get-item.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Hides what a single read counts as absent, and how it outlives an overwrite.
+ *
+ * A get reads its row strongly consistently and answers `null` alike for a
+ * missing row, an expired one and a row this adapter does not own. When the
+ * object an offloaded row names is deleted between the row read and the
+ * download, one re-read settles whether the item was replaced, removed or
+ * truly lost. A caller gets an item or `null` and never sees the race.
+ */
+import type { Item } from '@langchain/langgraph-checkpoint';
+import type { StoreAddress } from './parse.js';
+import { type StoreItemRow } from './rows.js';
+import type { StoreContext } from './setup.js';
+/** A row and the item it decodes to, read together so a caller can use the row's own fields. */
+export interface ReadCandidate {
+    readonly row: StoreItemRow;
+    readonly item: Item;
+}
+/**
+ * The item a row denotes, recovering from a concurrent overwrite of that row.
+ *
+ * An offloaded item can lose a race with a concurrent overwrite: between the
+ * row read and the S3 download the writer commits a new descriptor and deletes
+ * the object this read was about to fetch. That surfaces as `NoSuchKey` — or
+ * as a 403 `AccessDenied` for a role without `s3:ListBucket`, which S3 answers
+ * for a missing key instead — and one strongly-consistent re-read settles it —
+ * the row now points at the new object (that is the answer), is gone, or
+ * still points at the same missing object (a genuine loss, rethrown) — and a
+ * refused download on an unchanged row is rethrown the same way, since it is
+ * then a real permission failure. A row the overwrite left with no descriptor
+ * at all is a replacement like any other: it is decoded, and refused by its
+ * own coded error. Any other download failure propagates.
+ *
+ * Every reader that downloads a row it read earlier takes this route: `get`,
+ * whose window is one read; a search, which reads a whole page before it
+ * downloads anything; and a reconcile, which reads a whole namespace. A
+ * search that failed on it failed for an item that is live and readable a
+ * moment later.
+ *
+ * Accepts: `record` — a row read moments ago, whose object may since have been
+ * released. `signal` — aborts the download and the re-read.
+ *
+ * Returns: the row that was finally decoded and its item — the one given, or
+ * the one the overwrite left — or `undefined` when the re-read finds the row
+ * gone or expired.
+ *
+ * Throws: as {@link readStoreItem}, for the row finally decoded; the
+ * download's own failure when the re-read finds the same row.
+ */
+export declare function readCandidate(context: StoreContext, record: StoreItemRow, signal?: AbortSignal): Promise<ReadCandidate | undefined>;
+/**
+ * Retrieve a single item by namespace and key (strongly consistent), or null.
+ *
+ * A download that finds its object released by a concurrent overwrite is
+ * settled by {@link readCandidate}.
+ *
+ * Accepts: `address` — parsed; no check is repeated here. `signal` — aborts
+ * the reads.
+ *
+ * Returns: the item, or `null` for one that does not exist, has expired, or
+ * whose key holds a row this adapter does not own — which includes a row whose
+ * `createdAt` or `updatedAt` is not the string this package writes there, since
+ * an item is reported with both. The answers are one on purpose: a caller
+ * cannot act on the difference, and reporting a foreign row would leak that a
+ * shared table holds one.
+ *
+ * Throws: `VALIDATION` naming — for a row whose descriptor is not one —
+ * `descriptor`; `FORMAT_UNSUPPORTED` for
+ * a row, or a payload, written by a newer version, which is *not* reported as
+ * absent — hiding an item that exists is worse than failing; `PAYLOAD_CORRUPT`
+ * or the download's own error for a payload that cannot be read; `ABORTED`
+ * when the signal fires.
+ *
+ * Guarantees: strongly consistent — an item just written is always seen, and
+ * the ttl is honoured here rather than waited for.
+ */
+export declare function getItem(context: StoreContext, address: StoreAddress, signal?: AbortSignal): Promise<Item | null>;

package/dist/cjs/store/internal/get-item.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCandidate = readCandidate;
+exports.getItem = getItem;
+const clock_js_1 = require("../../shared/clock.js");
+const codec_js_1 = require("../../shared/codec/codec.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const rows_js_1 = require("./rows.js");
+async function readRow(context, namespace, key, signal) {
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_js_1.itemRowKey)({ namespace, key }),
+        ConsistentRead: true,
+    }, request), (0, retry_js_1.retryFor)(context, signal));
+    if (!result.Item)
+        return undefined;
+    const record = (0, rows_js_1.parseWholeStoreRow)(result.Item);
+    if (!record) {
+        context.logger.warn('store.get: ignored a row that is not a store item', {
+            partitionKey: (0, rows_js_1.partitionKey)(namespace),
+            sortKey: (0, rows_js_1.sortKey)(namespace, key),
+        });
+        return undefined;
+    }
+    return (0, table_schema_js_1.isExpiredRow)(record, (0, clock_js_1.nowSeconds)()) ? undefined : record;
+}
+function sameObject(read, reread) {
+    const fresh = reread.value;
+    if (!fresh)
+        return false;
+    return (read.value.location === codec_js_1.PayloadLocation.S3 &&
+        fresh.location === codec_js_1.PayloadLocation.S3 &&
+        read.value.s3Key === fresh.s3Key);
+}
+async function readCandidate(context, record, signal) {
+    try {
+        return { row: record, item: await (0, rows_js_1.readStoreItem)(context, record, signal) };
+    }
+    catch (error) {
+        if (!(0, codec_js_1.isMissingObjectError)(error) && !(0, codec_js_1.isRefusedObjectError)(error))
+            throw error;
+        const fresh = await readRow(context, record.namespace, record.key, signal);
+        if (!fresh)
+            return undefined;
+        if (sameObject(record, fresh))
+            throw error;
+        return { row: fresh, item: await (0, rows_js_1.readStoreItem)(context, fresh, signal) };
+    }
+}
+async function getItem(context, address, signal) {
+    const { namespace, key } = address;
+    const record = await readRow(context, namespace, key, signal);
+    if (!record)
+        return null;
+    const read = await readCandidate(context, record, signal);
+    return read === undefined ? null : read.item;
+}

package/dist/{store → cjs/store}/internal/item-write.d.ts

@@ -10,10 +10,11 @@
  * anything is released. Without an offloader there is no object to protect,
  * and a put is a plain write.
  */
-import { type WriteVerdict } from '../../shared/dynamodb/idempotent-write';
-import type { StoreAddress } from './parse';
-import { type ExistingRowMeta, type StoreItemRow } from './rows';
-import type { StoreContext } from './setup';
+import { type WriteVerdict } from '../../shared/dynamodb/idempotent-write.js';
+import { type RowKey } from '../../shared/dynamodb/table-schema.js';
+import type { StoreAddress } from './parse.js';
+import { type ExistingRowMeta, type StoreItemRow } from './rows.js';
+import type { StoreContext } from './setup.js';
 /**
  * Delete the item and, when a vector backend is configured, drop its vector.
  *
@@ -99,6 +100,20 @@ import type { StoreContext } from './setup';
  * comes back unnoticed.
  */
 export declare function deleteStoreItem(context: StoreContext, address: StoreAddress): Promise<void>;
+/**
+ * Refuse a row DynamoDB would refuse for its size.
+ *
+ * Accepts: `record` — the fully built row, its payload encoded and its inline
+ * vectors attached.
+ *
+ * Returns: nothing: the row is kept under its declared type, and this checks it.
+ *
+ * Throws: `VALIDATION` when the row would pass DynamoDB's 400 KB item limit —
+ * naming `index` when the row fits without its vectors, since the vectors are
+ * what pushed it over (index fewer fields, embed with fewer dimensions, or
+ * configure a `vectorBackend`), and `value` otherwise.
+ */
+export declare function assertRowFits(record: StoreItemRow): void;
 /**
  * Put the record and clean up whichever side is now dead.
  *
@@ -109,19 +124,25 @@ export declare function deleteStoreItem(context: StoreContext, address: StoreAdd
  * delete exactly the payload it superseded rather than a descriptor a racer may
  * already have replaced.
  *
- * Every failure reaching the catch arrives after at least one put was issued —
- * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
- * them proves a non-commit on its own: a put can commit server-side and lose
- * its response, and a `ConditionalCheckFailedException` is as consistent with
+ * Every failed put arrives after at least one write was issued —
+ * `putWithRevisionSwap` only re-reads after a rejection — so none of them
+ * proves a non-commit on its own: a put can commit server-side and lose its
+ * response, and a `ConditionalCheckFailedException` is as consistent with
  * hitting the row this call just wrote as with a competitor's win. The row is
- * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
- * confirmed `'not-landed'` deletes this record's own object; a confirmed
- * `'landed'` cleans up the previous object like the success path and swallows
- * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
- * one object at worst rather than stranding a live row pointing at a deleted
- * one. The verification compares the per-call `rev`, so an inline record is
- * verified too: otherwise a lost acknowledgement of an inline overwrite would be
- * reported as a failure while the previous offloaded object was never cleaned.
+ * therefore read back ({@link settleFailedPut}) before anything is deleted.
+ * Only a confirmed `'not-landed'` deletes this record's own object; a confirmed
+ * `'landed'` cleans up what the landed write replaced — the observation the
+ * attempt in flight was pinned to, which after a re-pin is a competitor's, not
+ * what this call first read — and swallows the error; an `'unverified'` read
+ * deletes nothing and rethrows, leaking one object at worst rather than
+ * stranding a live row pointing at a deleted one. So does a read that finds
+ * nothing, or finds another revision, after a write that DynamoDB may still
+ * apply: any attempt of the budget that got no answer, that DynamoDB answered
+ * as still in progress (`TransactionInProgressException`) or that failed with a
+ * server error (5xx). The verification compares the per-call `rev`, so an
+ * inline record is verified too: otherwise a lost acknowledgement of an inline
+ * overwrite would be reported as a failure while the previous offloaded object
+ * was never cleaned.
  *
  * Neither release reads the row again first. The record's object is uploaded
  * under the record's own `rev`, which no other put uses, so no row another put
@@ -134,9 +155,11 @@ export declare function deleteStoreItem(context: StoreContext, address: StoreAdd
  * Returns: nothing. The row is committed and exactly one side's object, at
  * most, has been released.
  *
- * Throws: whatever the write throws, unless the verification proves the write
- * landed after all — in which case the error is swallowed and the cleanup runs
- * as on the success path.
+ * Throws: `VALIDATION` naming `index` or `value` for a row over DynamoDB's
+ * item limit, before any write and after releasing this put's own upload;
+ * whatever the write, or the swap's re-read after a rejection, throws, unless
+ * the verification proves the write landed after all — in which case the error
+ * is swallowed and the cleanup runs as on the success path.
  *
  * Guarantees: this record's own object is released only after a read proves
  * the write did not land, and a superseded object only after this record is
@@ -146,9 +169,22 @@ export declare function deleteStoreItem(context: StoreContext, address: StoreAdd
  * deletes.
  */
 export declare function persistRow(context: StoreContext, record: StoreItemRow, existing: ExistingRowMeta): Promise<void>;
+/**
+ * How a revision swap ended, settled rather than thrown: what its committed
+ * write superseded, or the failure together with the observation the attempt in
+ * flight was pinned to — what that write replaced, if it landed after all.
+ */
+type SwapOutcome = {
+    ok: true;
+    superseded: ExistingRowMeta;
+} | {
+    ok: false;
+    reason: Error;
+    pinned: ExistingRowMeta;
+};
 /**
  * Commit `record`, re-reading and retrying while another writer holds the row,
- * and return the state this write actually superseded — the only descriptor
+ * and report the state this write actually superseded — the only descriptor
  * safe to delete afterwards.
  *
  * Without the swap both racers read the same previous descriptor, both commit,
@@ -169,27 +205,32 @@ export declare function persistRow(context: StoreContext, record: StoreItemRow,
  * and claim a race it never entered.
  *
  * On exhaustion the write proceeds unconditionally and warns. That is
- * deliberate: the fallback is precisely the pre-0.9.0 behaviour — one possible
- * orphan, reclaimed by a lifecycle rule — so pathological contention degrades
- * instead of turning a working put into an error. `createdAt` is refreshed from
+ * deliberate: the fallback costs at most one orphaned object, reclaimed by a
+ * lifecycle rule, so pathological contention degrades instead of turning a
+ * working put into an error. `createdAt` is refreshed from
  * each re-read so a row created by whoever won keeps its true creation time.
  *
  * Accepts: `record` — the row to commit, carrying this call's own `rev`.
  * `existing` — what the caller read before encoding, used as the first pin; an
  * `exists: false` observation pins "no row", so a creation races correctly too.
  *
- * Returns: the state this write actually superseded — the descriptor safe to
- * delete — which is the last observation the winning put was pinned to, never
- * this record's own value.
+ * Returns: on success, the state this write actually superseded — the
+ * descriptor safe to delete — which is the last observation the winning put
+ * was pinned to, never this record's own value. On failure — a put failing
+ * other than on its guard, or a re-read failing after a rejection — the error,
+ * with the observation the failed attempt was pinned to. After a re-pin that is
+ * a competitor's row, not `existing`: the competitor already replaced and
+ * released `existing`, so a write that landed without an answer superseded the
+ * competitor's object, and only this observation names it.
  *
- * Throws: whatever the put throws other than a conditional-check failure; those
- * are the swap's own business.
+ * Throws: nothing; a failure is reported in the outcome, because only the
+ * swap knows which observation the failed attempt was pinned to.
  *
  * Guarantees: at most {@link OVERWRITE_CAS_MAX_ATTEMPTS} conditional puts, and
  * a re-read only when the rejection did not already carry the row that caused
  * it.
  */
-export declare function putWithRevisionSwap(context: StoreContext, record: StoreItemRow, existing: ExistingRowMeta): Promise<ExistingRowMeta>;
+export declare function putWithRevisionSwap(context: StoreContext, record: StoreItemRow, existing: ExistingRowMeta): Promise<SwapOutcome>;
 /**
  * Whether `error` is a spent retry budget.
  *
@@ -223,8 +264,7 @@ export declare function isRetryExhausted(error: Error): boolean;
  * Throws: nothing — a failed verification is `'unverified'`, which is an
  * answer, not an error.
  */
-export declare function verifyWriteLanded(context: StoreContext, record: {
-    PK: string;
-    SK: string;
+export declare function verifyWriteLanded(context: StoreContext, record: RowKey & {
     rev?: string;
 }): Promise<WriteVerdict>;
+export {};