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

package/dist/store/actions/reconcile-vector-index.d.ts

@@ -1,17 +1,38 @@
+/**
+ * Hides what a reconcile refuses before it touches the backend.
+ *
+ * A repair is scoped to one partition's items, so its prefix must be a
+ * non-empty namespace, and without an `index` and a `vectorBackend` there is
+ * nothing to repair; both are refused here, before any read. How the backend
+ * is then made to agree with the table belongs to the vector index, so the
+ * store's method knows neither half.
+ */
 import type { StoreContext } from '../internal/setup';
-/** Counts returned by {@link reconcileVectorIndex}. */
-export interface VectorReconcileResult {
-    upserted: number;
-    pruned: number;
-}
+import type { VectorReconcileResult } from '../types';
 /**
  * Repair the vector backend against the canonical DynamoDB items under
  * `namespacePrefix`: re-push every live embedding, and — when the backend
  * implements {@link VectorBackend.listKeys} — prune vectors with no canonical
  * item. A maintenance tool for backend drift; run it when the namespace is
- * idle. Re-embeds with the store's configured fields, so per-put `index` field
- * overrides are not reproduced. Requires a configured `index` and
- * `vectorBackend`; the prefix must be a non-empty namespace.
+ * idle.
+ *
+ * Accepts: `namespacePrefix` — a non-empty namespace, since the repair is
+ * scoped to one partition's items. `options.signal` — aborts between pages.
+ *
+ * Returns: how many vectors were upserted and how many pruned.
+ *
+ * Throws: `VALIDATION` naming `namespacePrefix` or `namespacePrefix element`
+ * for an empty or malformed prefix, as `search` names it, and `vectorBackend`
+ * when the store has no index or backend to reconcile;
+ * `RESULT_TRUNCATED` past `maxScanItems`, since repairing from a
+ * partial view would prune live vectors; whatever the reads, the embeddings
+ * model and the backend throw.
+ *
+ * Guarantees: re-embeds with the store's configured fields, so a per-put
+ * `index` field override is not reproduced — a reconcile makes the backend
+ * agree with the store's configuration, not with each item's write-time one.
+ * DynamoDB is never written: only the backend is repaired.
  */
-export declare function reconcileVectorIndex(context: StoreContext, namespacePrefix: string[]): Promise<VectorReconcileResult>;
-//# sourceMappingURL=reconcile-vector-index.d.ts.map
+export declare function reconcileVectorIndex(context: StoreContext, namespacePrefix: string[], options?: {
+    signal?: AbortSignal;
+}): Promise<VectorReconcileResult>;

package/dist/store/actions/reconcile-vector-index.js

@@ -1,27 +1,46 @@
 "use strict";
+/**
+ * Hides what a reconcile refuses before it touches the backend.
+ *
+ * A repair is scoped to one partition's items, so its prefix must be a
+ * non-empty namespace, and without an `index` and a `vectorBackend` there is
+ * nothing to repair; both are refused here, before any read. How the backend
+ * is then made to agree with the table belongs to the vector index, so the
+ * store's method knows neither half.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reconcileVectorIndex = reconcileVectorIndex;
 const errors_1 = require("../../shared/errors/errors");
-const index_reconcile_1 = require("../internal/index-reconcile");
-const validation_1 = require("../internal/validation");
+const parse_1 = require("../internal/parse");
+const vector_index_1 = require("../internal/vector-index");
 /**
  * Repair the vector backend against the canonical DynamoDB items under
  * `namespacePrefix`: re-push every live embedding, and — when the backend
  * implements {@link VectorBackend.listKeys} — prune vectors with no canonical
  * item. A maintenance tool for backend drift; run it when the namespace is
- * idle. Re-embeds with the store's configured fields, so per-put `index` field
- * overrides are not reproduced. Requires a configured `index` and
- * `vectorBackend`; the prefix must be a non-empty namespace.
+ * idle.
+ *
+ * Accepts: `namespacePrefix` — a non-empty namespace, since the repair is
+ * scoped to one partition's items. `options.signal` — aborts between pages.
+ *
+ * Returns: how many vectors were upserted and how many pruned.
+ *
+ * Throws: `VALIDATION` naming `namespacePrefix` or `namespacePrefix element`
+ * for an empty or malformed prefix, as `search` names it, and `vectorBackend`
+ * when the store has no index or backend to reconcile;
+ * `RESULT_TRUNCATED` past `maxScanItems`, since repairing from a
+ * partial view would prune live vectors; whatever the reads, the embeddings
+ * model and the backend throw.
+ *
+ * Guarantees: re-embeds with the store's configured fields, so a per-put
+ * `index` field override is not reproduced — a reconcile makes the backend
+ * agree with the store's configuration, not with each item's write-time one.
+ * DynamoDB is never written: only the backend is repaired.
  */
-async function reconcileVectorIndex(context, namespacePrefix) {
-    (0, validation_1.validateNamespace)(namespacePrefix);
-    if (!context.index || !context.vectorBackend) {
-        throw new errors_1.ValidationError('reconcileVectorIndex requires a configured index and vectorBackend');
+async function reconcileVectorIndex(context, namespacePrefix, options = {}) {
+    const prefix = (0, parse_1.parseNamespace)(namespacePrefix, 'namespacePrefix');
+    if (!(0, vector_index_1.hasVectorBackend)(context)) {
+        throw (0, errors_1.validationError)('reconcileVectorIndex requires a configured index and vectorBackend', 'vectorBackend');
     }
-    const backend = context.vectorBackend;
-    const targets = await (0, index_reconcile_1.collectReconcileTargets)(context, namespacePrefix);
-    const upserted = await (0, index_reconcile_1.pushEmbeddings)(backend, targets);
-    const pruned = await (0, index_reconcile_1.pruneOrphans)(context, backend, namespacePrefix, targets);
-    return { upserted, pruned };
+    return (0, vector_index_1.reconcileVectors)(context, prefix, options.signal);
 }
-//# sourceMappingURL=reconcile-vector-index.js.map

package/dist/store/actions/search.d.ts

@@ -1,10 +1,38 @@
-import type { SearchItem, SearchOperation } from '@langchain/langgraph-checkpoint';
+/**
+ * Hides which of three paths serves a search.
+ *
+ * A query with a `vectorBackend` is answered by the backend; no query, or no
+ * `index` to embed one with, is a page read from the table that stops once
+ * full; anything else is ranked in memory over at most `maxSearchCandidates`.
+ * A page of zero is answered before any of them. A caller gets the same shape
+ * of page whichever path ran, scored exactly when a query could be ranked.
+ */
+import type { SearchItem } from '@langchain/langgraph-checkpoint';
+import type { ParsedSearch } from '../internal/parse';
 import type { StoreContext } from '../internal/setup';
 /**
  * Search items under a namespace prefix: metadata filtering plus optional
- * semantic ranking. A non-empty prefix uses a native Query; an empty prefix
- * falls back to a (filtered) Scan. Semantic ranking uses the configured
- * VectorBackend when present, else an in-memory cosine ranking (capped).
+ * semantic ranking.
+ *
+ * Accepts: `search` — already parsed, so `namespacePrefix`, `offset` and
+ * `limit` are resolved; `search.query` absent or empty
+ * (which is absent: there is no query to embed) ranks nothing and returns the
+ * page as read, which is what the reference store does
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/store/memory.js:70-80`, where a
+ * falsy query takes the unscored path). A query without a configured `index`
+ * does the same, since there is nothing to embed it with.
+ *
+ * Returns: at most `limit` items from `offset`. With a query and an index every
+ * item carries a `score`; without one none does. Scores rank best-first; an item
+ * that cannot be scored ranks last rather than being dropped.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` or `index.dims`; whatever
+ * the reads, decodes and the embeddings model throw.
+ *
+ * Guarantees: a page of zero costs no request at all, and otherwise only the
+ * page's own items are decoded on the unranked path — the
+ * read stops as soon as it is full. A semantic search must read every candidate
+ * to rank it, which is why it is capped and why a large corpus belongs in a
+ * `vectorBackend`.
  */
-export declare function searchItems(context: StoreContext, op: SearchOperation): Promise<SearchItem[]>;
-//# sourceMappingURL=search.d.ts.map
+export declare function searchItems(context: StoreContext, search: ParsedSearch, signal?: AbortSignal): Promise<SearchItem[]>;

package/dist/store/actions/search.js

@@ -1,61 +1,66 @@
 "use strict";
+/**
+ * Hides which of three paths serves a search.
+ *
+ * A query with a `vectorBackend` is answered by the backend; no query, or no
+ * `index` to embed one with, is a page read from the table that stops once
+ * full; anything else is ranked in memory over at most `maxSearchCandidates`.
+ * A page of zero is answered before any of them. A caller gets the same shape
+ * of page whichever path ran, scored exactly when a query could be ranked.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchItems = searchItems;
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const scan_1 = require("../../shared/dynamodb/scan");
-const backend_search_1 = require("../internal/backend-search");
-const item_mapper_1 = require("../internal/item-mapper");
-const keys_1 = require("../internal/keys");
-const query_1 = require("../internal/query");
-const ranker_1 = require("../internal/ranker");
-const search_filter_1 = require("../internal/search-filter");
-const validation_1 = require("../internal/validation");
-const DEFAULT_LIMIT = 10;
-async function collectCandidates(context, op) {
-    const source = op.namespacePrefix.length > 0
-        ? (0, paginate_1.paginateQuery)({
-            client: context.client,
-            params: (0, query_1.scopedQuery)(context.tableName, op.namespacePrefix),
-            maxItems: context.maxScanItems,
-        })
-        : (0, scan_1.paginateScan)({
-            client: context.client,
-            params: (0, query_1.storeScan)(context.tableName),
-            maxItems: context.maxScanItems,
-        });
-    const candidates = [];
-    for await (const raw of source) {
-        const record = (0, item_mapper_1.narrowStoreRecord)(raw);
-        if (!record)
-            continue;
-        if (!(0, keys_1.namespaceMatchesPrefix)(record.namespace, op.namespacePrefix))
-            continue;
-        const item = await (0, item_mapper_1.readStoreItem)(context, record);
-        if (!(0, search_filter_1.passesFilter)(item, op))
-            continue;
-        candidates.push({ item, embedding: record.embedding });
-    }
-    return candidates;
-}
+const truncate_1 = require("../../shared/logging/truncate");
+const semantic_search_1 = require("../internal/semantic-search");
+const table_search_1 = require("../internal/table-search");
+const vector_index_1 = require("../internal/vector-index");
 /**
  * Search items under a namespace prefix: metadata filtering plus optional
- * semantic ranking. A non-empty prefix uses a native Query; an empty prefix
- * falls back to a (filtered) Scan. Semantic ranking uses the configured
- * VectorBackend when present, else an in-memory cosine ranking (capped).
+ * semantic ranking.
+ *
+ * Accepts: `search` — already parsed, so `namespacePrefix`, `offset` and
+ * `limit` are resolved; `search.query` absent or empty
+ * (which is absent: there is no query to embed) ranks nothing and returns the
+ * page as read, which is what the reference store does
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/store/memory.js:70-80`, where a
+ * falsy query takes the unscored path). A query without a configured `index`
+ * does the same, since there is nothing to embed it with.
+ *
+ * Returns: at most `limit` items from `offset`. With a query and an index every
+ * item carries a `score`; without one none does. Scores rank best-first; an item
+ * that cannot be scored ranks last rather than being dropped.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` or `index.dims`; whatever
+ * the reads, decodes and the embeddings model throw.
+ *
+ * Guarantees: a page of zero costs no request at all, and otherwise only the
+ * page's own items are decoded on the unranked path — the
+ * read stops as soon as it is full. A semantic search must read every candidate
+ * to rank it, which is why it is capped and why a large corpus belongs in a
+ * `vectorBackend`.
  */
-async function searchItems(context, op) {
-    const offset = op.offset ?? 0;
-    const limit = op.limit ?? DEFAULT_LIMIT;
-    (0, validation_1.validatePaging)(offset, limit);
-    if (op.query && context.index && context.vectorBackend) {
-        const ranked = await (0, backend_search_1.searchViaBackend)(context, context.vectorBackend, context.index, op, offset, limit);
+async function searchItems(context, search, signal) {
+    const { offset, limit } = search;
+    // A zero page is answered here, ahead of all three paths below, because each
+    // of them pays for it: `collectCandidates` pulls the first row out of the
+    // paginator before it tests its `offset + limit` bound, so even a page that
+    // needs nothing costs one Query or Scan, and the two ranked paths embed the
+    // query as well. Slicing the result to nothing afterwards hid the cost
+    // rather than avoiding it.
+    if (limit === 0)
+        return [];
+    if (search.query && (0, vector_index_1.hasVectorBackend)(context)) {
+        const ranked = await (0, vector_index_1.searchViaBackend)(context, search, signal);
         return ranked.slice(offset, offset + limit);
     }
-    const candidates = await collectCandidates(context, op);
-    if (!op.query || !context.index) {
-        return candidates.map(({ item }) => ({ ...item })).slice(offset, offset + limit);
+    if (!search.query || !context.index) {
+        const page = await (0, table_search_1.collectCandidates)(context, search, { kind: 'page', need: offset + limit }, signal);
+        return page.map(({ item }) => ({ ...item })).slice(offset, offset + limit);
     }
-    const queryVector = await context.index.embeddings.embedQuery(op.query);
-    return (0, ranker_1.rankInMemory)(candidates, queryVector, context.maxSearchCandidates).slice(offset, offset + limit);
+    const candidates = await (0, table_search_1.collectCandidates)(context, search, { kind: 'semantic', cap: context.maxSearchCandidates }, signal);
+    const queryVector = await context.index.embeddings.embedQuery(search.query);
+    (0, semantic_search_1.assertVectorDims)(context.index, queryVector, 'query');
+    const ranked = (0, table_search_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_1.truncateLabelsForLog)(search.namespacePrefix), count }));
+    return ranked.slice(offset, offset + limit);
 }
-//# sourceMappingURL=search.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Hides how a batch runs concurrently and still in the order it was written.
+ *
+ * Operations on different items, and reads of the same item, share a run and
+ * go in flight together; anything that could observe or overwrite an earlier
+ * operation's effect starts the next run. A caller sees the order it wrote —
+ * a `get` after a `put` of the same item sees it, a `search` sees every write
+ * before it — and how independence is judged can change without the store.
+ */
+import type { ParsedOperation } from './parse';
+/**
+ * Run a batch: each run of independent operations concurrently, at most
+ * `limit` in flight, and the runs themselves in
+ * order. Results come back in operation order.
+ *
+ * Accepts: `operations` — in caller order, which is the order they are
+ * observed in; empty returns empty. `limit` — operations in flight within one
+ * run.
+ *
+ * Returns: the results in operation order, not completion order.
+ *
+ * Throws: the first failure. Any failure rejects the whole batch: no operation
+ * in a later run starts, the ones already in flight settle, and that first
+ * error is the one thrown.
+ */
+export declare function runBatch<R>(operations: readonly ParsedOperation[], dispatch: (operation: ParsedOperation) => Promise<R>, limit?: number): Promise<R[]>;

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

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Hides how a batch runs concurrently and still in the order it was written.
+ *
+ * Operations on different items, and reads of the same item, share a run and
+ * go in flight together; anything that could observe or overwrite an earlier
+ * operation's effect starts the next run. A caller sees the order it wrote —
+ * a `get` after a `put` of the same item sees it, a `search` sees every write
+ * before it — and how independence is judged can change without the store.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBatch = runBatch;
+const concurrency_1 = require("../../shared/concurrency");
+function itemOf(address) {
+    return JSON.stringify([address.namespace, address.key]);
+}
+/** What `op` touches, decided by the kind the parser already assigned — the only place that asks. */
+function touchOf(op) {
+    switch (op.kind) {
+        case 'put':
+        case 'delete':
+            return { kind: 'write', item: itemOf(op.address) };
+        case 'get':
+            return { kind: 'get', item: itemOf(op.address) };
+        default:
+            return { kind: 'broad' };
+    }
+}
+/**
+ * True when `touch` may not join `segment` — because some operation already in
+ * it addresses the same item, or because a write and a whole-store read would
+ * then be unordered with respect to each other.
+ */
+function conflicts(segment, touch) {
+    if (touch.kind === 'broad')
+        return segment.hasWrite;
+    if (touch.kind === 'get')
+        return segment.written.has(touch.item);
+    return segment.written.has(touch.item) || segment.read.has(touch.item) || segment.hasBroad;
+}
+function admit(segment, index, touch) {
+    segment.indices.push(index);
+    if (touch.kind === 'broad')
+        segment.hasBroad = true;
+    if (touch.kind === 'get')
+        segment.read.add(touch.item);
+    if (touch.kind === 'write') {
+        segment.written.add(touch.item);
+        segment.hasWrite = true;
+    }
+}
+function emptySegment() {
+    return { indices: [], written: new Set(), read: new Set(), hasWrite: false, hasBroad: false };
+}
+/**
+ * Split a batch into runs of mutually independent operations, in caller order.
+ *
+ * Operations that address different items, and reads that address the same
+ * item, are independent of each other and share a run. Anything that could
+ * observe or overwrite an earlier operation's effect starts a new one, so the
+ * order the caller wrote is the order the caller observes: a `get` after a
+ * `put` of the same item sees it, a `get` before one does not, and a `search`
+ * sees every write that precedes it and none that follow.
+ *
+ * Running every write before every read — the earlier behaviour — made a
+ * `[delete, get]` batch return nothing where the reference store returns the
+ * value, and a `[get, put]` batch return the new value where the reference
+ * returns null. `AsyncBatchedStore` coalesces everything enqueued in one tick
+ * into a single `batch()`, so that difference is reachable from ordinary code.
+ */
+function planBatch(operations) {
+    const runs = [];
+    let segment = emptySegment();
+    operations.forEach((op, index) => {
+        const touch = touchOf(op);
+        if (segment.indices.length > 0 && conflicts(segment, touch)) {
+            runs.push(segment.indices);
+            segment = emptySegment();
+        }
+        admit(segment, index, touch);
+    });
+    if (segment.indices.length > 0)
+        runs.push(segment.indices);
+    return runs;
+}
+/**
+ * Run a batch: each run of independent operations concurrently, at most
+ * `limit` in flight, and the runs themselves in
+ * order. Results come back in operation order.
+ *
+ * Accepts: `operations` — in caller order, which is the order they are
+ * observed in; empty returns empty. `limit` — operations in flight within one
+ * run.
+ *
+ * Returns: the results in operation order, not completion order.
+ *
+ * Throws: the first failure. Any failure rejects the whole batch: no operation
+ * in a later run starts, the ones already in flight settle, and that first
+ * error is the one thrown.
+ */
+async function runBatch(operations, dispatch, limit = concurrency_1.DEFAULT_READ_CONCURRENCY) {
+    const results = [];
+    for (const run of planBatch(operations)) {
+        await (0, concurrency_1.mapWithConcurrency)(run, limit, async (index) => {
+            results[index] = await dispatch(operations[index]);
+        });
+    }
+    return results;
+}

package/dist/store/internal/filter.d.ts

@@ -1,10 +1,43 @@
+/**
+ * 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.
+ */
+import type { Item } from '@langchain/langgraph-checkpoint';
 /** A JSON value stored in an item or supplied in a filter. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 /**
- * True when `value` satisfies every field condition in `filter`. A plain value
- * is exact-match ($eq); an operator object ({ $gt: 4 }) applies comparisons.
+ * Whether `value` satisfies every field condition in `filter`.
+ *
+ * Accepts: `value` — a stored item's decoded value. Declared as a record, but a
+ * row holds whatever its writer stored, including `null` and a scalar; such a
+ * value has no own properties and so satisfies no condition. `filter` — a plain
+ * value per field is exact match, an operator object (`{ $gt: 4 }`) applies
+ * comparisons, and `{}` constrains nothing.
+ *
+ * Returns: whether every condition holds.
+ *
+ * Throws: nothing. `search` walks every candidate row, so one row whose value
+ * is not an object must not fail the search.
+ *
+ * Guarantees: own properties only — `value['toString']` would otherwise resolve
+ * up the prototype chain and be compared as if it were stored data.
  */
 export declare function matchesStoreFilter(value: Record<string, JsonValue>, filter: Record<string, JsonValue>): boolean;
-//# sourceMappingURL=filter.d.ts.map
+/**
+ * Whether `item` satisfies a search's optional metadata filter.
+ *
+ * Accepts: `filter` — a parsed search's filter; absent passes every item.
+ * `item.value` — whatever the item's writer stored; a value that is not
+ * an object satisfies no condition (see `matchesStoreFilter`).
+ *
+ * Returns: whether the item belongs in the result.
+ *
+ * Throws: nothing, so one unusual row cannot fail a search over many.
+ */
+export declare function passesFilter(item: Item, filter: Record<string, JsonValue> | undefined): boolean;

package/dist/store/internal/filter.js

@@ -1,6 +1,15 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchesStoreFilter = matchesStoreFilter;
+exports.passesFilter = passesFilter;
 const node_util_1 = require("node:util");
 /**
  * Three-way order for a like-typed pair, or `undefined` when the pair is
@@ -24,8 +33,8 @@ function testOrder(order, test) {
  * Ordered comparison over like-typed values only: numbers compare numerically,
  * strings lexicographically, and a mismatched or unordered pair never matches.
  *
- * Deliberately stricter than both what this used to do and what upstream does.
- * Native `>` coerces, so a stored `'10'` satisfied `{ $gt: 5 }` — inclusion
+ * Deliberately stricter than both native comparison and what upstream does.
+ * Native `>` coerces, so a stored `'10'` would satisfy `{ $gt: 5 }` — inclusion
  * decided by JS coercion rather than by the stored type. Upstream instead
  * reduces both sides with `Number()`, which makes two ISO-8601 date strings
  * `NaN` and every comparison between them false. Comparing like types
@@ -55,17 +64,28 @@ const COMPARATORS = {
         : true,
 };
 /**
- * True only when every key is one of the exact known operator names — matches
- * the official `@langchain/langgraph-checkpoint` InMemoryStore's own detection
- * exactly, so a stored value that merely has `$`-prefixed keys (e.g. a JSON
- * Schema document) is compared as a literal value instead of misread as a
- * filter operator.
+ * True when every key is one of the exact known operator names, which matches
+ * the reference store's own detection (`@langchain/langgraph-checkpoint@1.1.5`
+ * `dist/store/utils.js:61`): a stored value that merely has `$`-prefixed keys —
+ * a JSON Schema document, say — is compared as a literal instead of misread as
+ * a filter.
+ *
+ * An empty condition qualifies, and therefore imposes no constraint: `every`
+ * over no operators is true, exactly as it is upstream, so `{ field: {} }`
+ * matches every item — including one that does not hold the field at all, for
+ * which there is likewise no operator to fail. Requiring at least one key
+ * inverted that answer and made the same filter match nothing.
+ *
+ * Arrays are excluded where the reference does not. Upstream an empty array
+ * reaches `Object.keys([]).every(...)` and is likewise vacuously true, so `[]`
+ * as a condition matches everything there; treating a stored array as a literal
+ * to compare is the answer a caller means, and the difference is recorded
+ * rather than copied.
  */
 function isOperatorObject(condition) {
     return (typeof condition === 'object' &&
         condition !== null &&
         !Array.isArray(condition) &&
-        Object.keys(condition).length > 0 &&
         Object.keys(condition).every((key) => Object.prototype.hasOwnProperty.call(COMPARATORS, key)));
 }
 function matchesCondition(actual, condition) {
@@ -73,14 +93,45 @@ function matchesCondition(actual, condition) {
         return (0, node_util_1.isDeepStrictEqual)(actual, condition);
     return Object.entries(condition).every(([operator, expected]) => COMPARATORS[operator](actual, expected));
 }
+/** The value `item` holds at `field`, or undefined when it holds no such own property. */
+function ownField(item, field) {
+    if (item === null || typeof item !== 'object')
+        return undefined;
+    return Object.hasOwn(item, field) ? item[field] : undefined;
+}
 /**
- * True when `value` satisfies every field condition in `filter`. A plain value
- * is exact-match ($eq); an operator object ({ $gt: 4 }) applies comparisons.
+ * Whether `value` satisfies every field condition in `filter`.
+ *
+ * Accepts: `value` — a stored item's decoded value. Declared as a record, but a
+ * row holds whatever its writer stored, including `null` and a scalar; such a
+ * value has no own properties and so satisfies no condition. `filter` — a plain
+ * value per field is exact match, an operator object (`{ $gt: 4 }`) applies
+ * comparisons, and `{}` constrains nothing.
+ *
+ * Returns: whether every condition holds.
+ *
+ * Throws: nothing. `search` walks every candidate row, so one row whose value
+ * is not an object must not fail the search.
+ *
+ * Guarantees: own properties only — `value['toString']` would otherwise resolve
+ * up the prototype chain and be compared as if it were stored data.
  */
 function matchesStoreFilter(value, filter) {
-    return Object.entries(filter).every(([field, condition]) => 
-    /** Own properties only: `value['toString']` would otherwise resolve up the
-     *  prototype chain and be compared as if it were stored data. */
-    matchesCondition(Object.hasOwn(value, field) ? value[field] : undefined, condition));
+    return Object.entries(filter).every(([field, condition]) => matchesCondition(ownField(value, field), condition));
+}
+/**
+ * Whether `item` satisfies a search's optional metadata filter.
+ *
+ * Accepts: `filter` — a parsed search's filter; absent passes every item.
+ * `item.value` — whatever the item's writer stored; a value that is not
+ * an object satisfies no condition (see `matchesStoreFilter`).
+ *
+ * Returns: whether the item belongs in the result.
+ *
+ * Throws: nothing, so one unusual row cannot fail a search over many.
+ */
+function passesFilter(item, filter) {
+    if (!filter)
+        return true;
+    return matchesStoreFilter(item.value, filter);
 }
-//# sourceMappingURL=filter.js.map

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

@@ -0,0 +1,45 @@
+/**
+ * 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';
+import type { StoreContext } from './setup';
+/**
+ * Retrieve a single item by namespace and key (strongly consistent), or null.
+ *
+ * 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`, and
+ * one strongly-consistent re-read settles it — the row now points at the new
+ * object (return that), is gone (null), or still points at the same missing
+ * object (a genuine loss, rethrown). 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.
+ *
+ * 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>;