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

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

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteStoreItem = deleteStoreItem;
+exports.assertRowFits = assertRowFits;
+exports.persistRow = persistRow;
+exports.putWithRevisionSwap = putWithRevisionSwap;
+exports.isRetryExhausted = isRetryExhausted;
+exports.verifyWriteLanded = verifyWriteLanded;
+const codec_js_1 = require("../../shared/codec/codec.js");
+const offloader_js_1 = require("../../shared/codec/s3/offloader.js");
+const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const row_size_js_1 = require("../../shared/dynamodb/row-size.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const base_error_js_1 = require("../../shared/errors/base-error.js");
+const error_code_js_1 = require("../../shared/errors/error-code.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const rows_js_1 = require("./rows.js");
+const vector_index_js_1 = require("./vector-index.js");
+async function repinOrResolve(context, key, error) {
+    if ((0, idempotent_write_js_1.isConditionalCheckFailed)(error)) {
+        const rejected = (0, idempotent_write_js_1.rejectedRow)(error);
+        return rejected === undefined ? undefined : (0, rows_js_1.existingFrom)(rejected);
+    }
+    if (isRetryExhausted(error) && (await (0, idempotent_write_js_1.isRowAbsent)(context, key)))
+        return undefined;
+    throw error;
+}
+async function removeObservedRow(context, key, existing) {
+    let observed = existing;
+    for (let attempt = 1; attempt <= idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        try {
+            await (0, idempotent_write_js_1.deleteIdempotently)(context, key, (0, idempotent_write_js_1.revisionGuard)(rows_js_1.REVISION_ATTRIBUTE, observed));
+            return observed;
+        }
+        catch (error) {
+            const repinned = await repinOrResolve(context, key, error);
+            if (repinned === undefined)
+                return observed;
+            observed = repinned;
+        }
+    }
+    return undefined;
+}
+async function deleteStoreItem(context, address) {
+    const key = (0, rows_js_1.itemRowKey)(address);
+    const existing = await (0, rows_js_1.readExisting)(context, key);
+    const released = existing.exists ? await removeObservedRow(context, key, existing) : existing;
+    if (released === undefined) {
+        context.logger.warn('store.delete: compare-and-swap exhausted; the item was not deleted', {
+            namespace: address.namespace,
+            key: address.key,
+            attempts: idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS,
+        });
+    }
+    await (0, vector_index_js_1.dropVectorWhenGone)(context, address);
+    if (context.offloader && released?.value) {
+        await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+            keys: (0, codec_js_1.collectS3Keys)([released.value]),
+            operation: 'store.delete',
+            logger: context.logger,
+            scope: [...address.namespace, address.key],
+        });
+    }
+}
+async function cleanUp(context, release, label, scope) {
+    if (!context.offloader || !release)
+        return;
+    await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+        keys: (0, codec_js_1.collectS3Keys)([release]),
+        operation: label,
+        logger: context.logger,
+        ...(scope === undefined ? {} : { scope }),
+    });
+}
+function assertRowFits(record) {
+    const bytes = (0, row_size_js_1.rowSizeBytes)(record);
+    if (bytes <= row_size_js_1.MAX_ROW_BYTES)
+        return;
+    const { embeddings, ...bare } = record;
+    const vectorsOverflow = embeddings !== undefined && (0, row_size_js_1.rowSizeBytes)(bare) <= row_size_js_1.MAX_ROW_BYTES;
+    throw (0, errors_js_1.validationError)(vectorsOverflow
+        ? `the item's ${embeddings.length} inline vectors make its row ${bytes} bytes, over ` +
+            `DynamoDB's ${row_size_js_1.MAX_ROW_BYTES}-byte item limit; index fewer fields, embed with fewer ` +
+            'dimensions, or configure a vectorBackend'
+        : `the item's row would be ${bytes} bytes, over DynamoDB's ${row_size_js_1.MAX_ROW_BYTES}-byte item ` +
+            'limit; configure s3 offloading or store a smaller value', vectorsOverflow ? 'index' : 'value');
+}
+async function persistRow(context, record, existing) {
+    try {
+        assertRowFits(record);
+    }
+    catch (error) {
+        await cleanUp(context, record.value, 'store.put');
+        throw error;
+    }
+    let superseded;
+    if (context.offloader) {
+        const swap = await putWithRevisionSwap(context, record, existing);
+        superseded = swap.ok
+            ? swap.superseded
+            : await settleFailedPut(context, record, swap.reason, swap.pinned);
+    }
+    else {
+        try {
+            await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.put({ TableName: context.tableName, Item: record }, request), context.retry);
+            superseded = existing;
+        }
+        catch (error) {
+            superseded = await settleFailedPut(context, record, error, existing);
+        }
+    }
+    await cleanUp(context, superseded.value, 'store.put.overwrite', [
+        ...record.namespace,
+        record.key,
+    ]);
+}
+async function settleFailedPut(context, record, error, pinned) {
+    const verdict = (0, idempotent_write_js_1.settledVerdict)(await verifyWriteLanded(context, record), error);
+    if (verdict === 'landed')
+        return pinned;
+    if (verdict === 'not-landed')
+        await cleanUp(context, record.value, 'store.put');
+    throw error;
+}
+async function put(context, record, observed) {
+    const guard = observed ? (0, idempotent_write_js_1.revisionGuard)(rows_js_1.REVISION_ATTRIBUTE, observed) : undefined;
+    await (0, idempotent_write_js_1.commitRow)(context, record, record.value, { guard });
+}
+async function putWithRevisionSwap(context, record, existing) {
+    let observed = existing;
+    for (let attempt = 1; attempt <= idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        const attempted = observed;
+        try {
+            await put(context, record, attempted);
+            return { ok: true, superseded: attempted };
+        }
+        catch (error) {
+            const rejection = error;
+            if (!(0, idempotent_write_js_1.isConditionalCheckFailed)(rejection)) {
+                return { ok: false, reason: rejection, pinned: attempted };
+            }
+            try {
+                const rejected = (0, idempotent_write_js_1.rejectedRow)(rejection);
+                observed = rejected
+                    ? (0, rows_js_1.existingFrom)(rejected)
+                    : await (0, rows_js_1.readExisting)(context, (0, table_schema_js_1.rowKeyOf)(record));
+            }
+            catch (readError) {
+                return { ok: false, reason: readError, pinned: attempted };
+            }
+            if (record.rev !== undefined && observed.revision === record.rev) {
+                return { ok: true, superseded: attempted };
+            }
+            record.createdAt = (0, rows_js_1.isLiveRow)(observed)
+                ? (observed.createdAt ?? record.createdAt)
+                : record.updatedAt;
+        }
+    }
+    context.logger.warn('store.put: compare-and-swap exhausted; overwriting unconditionally, which can orphan one ' +
+        'S3 object under a concurrent put (reclaimed by ensureS3LifecycleRule)', { namespace: record.namespace, key: record.key, attempts: idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS });
+    try {
+        await put(context, record);
+        return { ok: true, superseded: observed };
+    }
+    catch (error) {
+        return { ok: false, reason: error, pinned: observed };
+    }
+}
+function isRetryExhausted(error) {
+    return (0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.RETRY_EXHAUSTED);
+}
+async function verifyWriteLanded(context, record) {
+    const { verdict } = await (0, idempotent_write_js_1.verifyRow)(context, {
+        key: (0, table_schema_js_1.rowKeyOf)(record),
+        kind: 'attribute',
+        attribute: rows_js_1.REVISION_ATTRIBUTE,
+        expected: record.rev,
+    });
+    return verdict;
+}

package/dist/cjs/store/internal/parse.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Hides what a well-formed store operation is (record 21).
+ *
+ * Every namespace, key, address, search, listing and batch is checked here,
+ * once, into branded types only these parsers build, and each operation's
+ * kind is decided from its shape here and nowhere else. Which of upstream's
+ * own rules apply — no `.` in a label and no `"langgraph"` root, for `put()`
+ * alone — and every default a caller may leave out are settled here too, so
+ * no later step checks again.
+ */
+import type { BaseStore, ListNamespacesOperation, Operation, PutOperation, SearchOperation } from '@langchain/langgraph-checkpoint';
+import { type PageLimit } from '../../shared/validation/primitives.js';
+import type { ListNamespacesOptions } from '../types.js';
+import type { JsonValue } from './filter.js';
+declare const namespaceBrand: unique symbol;
+declare const namespacePrefixBrand: unique symbol;
+declare const storeAddressBrand: unique symbol;
+/**
+ * A namespace checked as the partition and sort-key segments it becomes:
+ * non-empty, every label a well-formed identifier. Built only by
+ * {@link parseNamespace}, as a copy no caller holds. Mutable in type only so it
+ * still satisfies the public `VectorBackend` signatures; nothing writes to it.
+ */
+export type Namespace = string[] & {
+    readonly [namespaceBrand]: true;
+};
+/** A namespace prefix: like a {@link Namespace}, but possibly empty. Built only by {@link parseNamespacePrefix}. */
+export type NamespacePrefix = string[] & {
+    readonly [namespacePrefixBrand]: true;
+};
+/**
+ * An item's address — namespace and key — checked together, because the
+ * DynamoDB sort-key cap is a property of the pair. Built only by
+ * {@link parseStoreAddress}.
+ */
+export type StoreAddress = {
+    readonly namespace: Namespace;
+    readonly key: string;
+} & {
+    readonly [storeAddressBrand]: true;
+};
+/**
+ * Parse a namespace prefix.
+ *
+ * Accepts: `value` — anything; an array of labels a namespace can hold,
+ * possibly empty, which spans every namespace. `field` — the argument the
+ * caller set (`namespacePrefix`, or `prefix`/`suffix` for a match condition's
+ * path), named on a refusal.
+ *
+ * Returns: a copy of the labels, as a {@link NamespacePrefix}. A prefix no
+ * stored namespace could ever match is refused rather than answered with a
+ * silent empty page: a malformed label, or labels past the first that compose
+ * more sort key than DynamoDB allows a row to carry before any key — every
+ * label legal on its own, and still no item under it.
+ *
+ * Throws: `VALIDATION` naming `field` for a non-array or a path too wide for
+ * any sort key, or `<field> element` for a malformed label.
+ */
+export declare function parseNamespacePrefix(value: unknown, field: string): NamespacePrefix;
+/**
+ * Parse a namespace.
+ *
+ * Accepts: `value` — anything; a non-empty array of labels. `field` — defaults
+ * to `namespace`; `reconcileVectorIndex` passes `namespacePrefix`, whose prefix
+ * must not be empty.
+ *
+ * Returns: a copy of the labels, as a {@link Namespace}.
+ *
+ * Throws: `VALIDATION` naming `field` for a non-array or an empty one, or
+ * `<field> element` for a malformed label.
+ */
+export declare function parseNamespace(value: unknown, field?: string): Namespace;
+/**
+ * Parse an item's address: the namespace and key together, because the
+ * DynamoDB sort-key cap is a property of the pair. A deep namespace of legal
+ * segments can still compose an illegal sort key, which is why the
+ * composition is checked and not just the parts.
+ *
+ * Accepts: `namespace` — as {@link parseNamespace}. `key` — a well-formed
+ * identifier.
+ *
+ * Returns: the address, as a {@link StoreAddress}.
+ *
+ * Throws: `VALIDATION` naming `namespace` (or `namespace element`), then `key`,
+ * then `sortKey` when the two compose a sort key over DynamoDB's cap.
+ */
+export declare function parseStoreAddress(namespace: unknown, key: unknown): StoreAddress;
+/** Read one item. */
+export interface ParsedGet {
+    readonly kind: 'get';
+    readonly address: StoreAddress;
+}
+/** Store one item. */
+export interface ParsedPut {
+    readonly kind: 'put';
+    readonly address: StoreAddress;
+    readonly value: Record<string, JsonValue>;
+    /** `false` indexes nothing, a list the fields named, `undefined` the configured fields. */
+    readonly index: false | string[] | undefined;
+}
+/** Delete one item: a put whose value is `null`. */
+export interface ParsedDelete {
+    readonly kind: 'delete';
+    readonly address: StoreAddress;
+}
+/** Search under a prefix, its page and its defaults resolved. */
+export interface ParsedSearch {
+    readonly kind: 'search';
+    readonly namespacePrefix: NamespacePrefix;
+    readonly filter: Record<string, JsonValue> | undefined;
+    readonly query: string | undefined;
+    readonly offset: number;
+    readonly limit: PageLimit;
+}
+/** One match condition of a namespace listing. */
+export interface ParsedMatchCondition {
+    readonly matchType: 'prefix' | 'suffix';
+    readonly path: NamespacePrefix;
+}
+/** List namespaces. */
+export interface ParsedList {
+    readonly kind: 'list';
+    readonly matchConditions: ParsedMatchCondition[] | undefined;
+    readonly maxDepth: number | undefined;
+    readonly offset: number;
+    readonly limit: PageLimit;
+}
+/**
+ * One store operation, parsed. The kind is decided here, once, from the shape
+ * upstream's `Operation` union gives it — every other step switches on `kind`
+ * instead of asking the shape again.
+ */
+export type ParsedOperation = ParsedGet | ParsedPut | ParsedDelete | ParsedSearch | ParsedList;
+/**
+ * Parse a search's options against a prefix already parsed.
+ *
+ * Accepts: `namespacePrefix` — parsed by {@link parseNamespacePrefix}, which
+ * `store.search` does first so a malformed prefix is named before a malformed
+ * option. `op.filter` — an object when given. `op.query` — a string when given.
+ * `op.offset` — an integer of at least 0, `0` when absent; it carries no
+ * ceiling of its own, since it selects where a page starts rather than how
+ * much one holds, and what it can make a read walk is already bounded by
+ * `maxScanItems`. `op.limit` — 0 to the page ceiling, 10 when absent; `null` is
+ * not absent, so `limit: null` is refused rather than read as the default.
+ * `0` asks for no items and is answered as such, not refused — a page, not a
+ * conversation window, which is the one place this package refuses zero.
+ *
+ * Returns: the search, its defaults applied.
+ *
+ * Throws: `VALIDATION` naming `filter`, `query`, `offset` or `limit`, in that
+ * order.
+ */
+export declare function parseSearch(namespacePrefix: NamespacePrefix, op: Pick<SearchOperation, 'filter' | 'limit' | 'offset' | 'query'>): ParsedSearch;
+/**
+ * Parse a namespace-listing operation.
+ *
+ * Accepts: `op.offset` — an integer of at least 0. `op.limit` — 0 to the page
+ * ceiling. `op.maxDepth` — an integer of at least 1 when given: left
+ * unchecked, a negative value inverts truncation via `Array.prototype.slice(0,
+ * -n)`, which drops the *last* n elements rather than erroring, and 0
+ * truncates every namespace to the same empty one. `op.matchConditions` — an
+ * array of `{ matchType: 'prefix' | 'suffix', path }` when given; `*` is a
+ * legal label in a path.
+ *
+ * Returns: the listing.
+ *
+ * Throws: `VALIDATION` naming `offset`, `limit`, `maxDepth`, `matchConditions`
+ * or `<matchType> element`, in that order.
+ */
+export declare function parseListOperation(op: ListNamespacesOperation): ParsedList;
+/**
+ * Parse the options of `listNamespaces`.
+ *
+ * Accepts: `options` — an object; `prefix`, `suffix`, `maxDepth`, `limit` and
+ * `offset` are read, `limit` defaulting to 100 and `offset` to 0. Any other key
+ * is ignored rather than refused: `BaseStore.listNamespaces` declares these
+ * options, so a key a later LangGraph adds must not refuse the call (decision
+ * record 28).
+ *
+ * Returns: the listing the options describe.
+ *
+ * Throws: `VALIDATION` naming `options` for options that are not an object,
+ * then as {@link parseListOperation}.
+ */
+export declare function parseListNamespacesOptions(options: ListNamespacesOptions): ParsedList;
+/**
+ * Parse the arguments of `put()`.
+ *
+ * Accepts: `namespace`, `key` — as {@link parseStoreAddress}, plus the
+ * namespace rules upstream `put()` adds. `value` — an object; `null` is refused,
+ * because `delete()` is how an item is removed. `index` — `false`, a list of
+ * field paths, or absent.
+ *
+ * Returns: the put.
+ *
+ * Throws: `VALIDATION` naming `namespace`, `namespace element`, `key`,
+ * `sortKey`, `value` or `index`, in that order.
+ */
+export declare function parsePutArguments(namespace: string[], key: string, value: Parameters<BaseStore['put']>[2], index: PutOperation['index']): ParsedPut;
+/**
+ * Parse one operation of a batch, deciding its kind from its shape — the only
+ * place that asks.
+ *
+ * Accepts: `operation` — an object; a `namespacePrefix` makes it a search, a
+ * `value` a put (a delete when `null`), a `key` a get, anything else a listing.
+ *
+ * Returns: the parsed operation.
+ *
+ * Throws: `VALIDATION` naming `operations` for a non-object, else as the
+ * parser of its kind.
+ */
+export declare function parseOperation(operation: Operation): ParsedOperation;
+/**
+ * Parse every operation of a batch before any of them runs, so a malformed
+ * last operation cannot leave the first ones applied. That matters most
+ * inside a graph: LangGraph reaches a store only through `batch()`, via
+ * `AsyncBatchedStore`, which coalesces every call made in one tick into a
+ * single batch and rejects them all together (`@langchain/langgraph`
+ * `dist/pregel/loop.js:311`, `@langchain/langgraph-checkpoint@1.1.5`
+ * `dist/store/batch.js:85-105`).
+ *
+ * Accepts: `operations` — an array of operations.
+ *
+ * Returns: the parsed operations, in order.
+ *
+ * Throws: `VALIDATION` naming `operations` for a non-array, else as
+ * {@link parseOperation} for the first malformed one.
+ */
+export declare function parseOperations(operations: Operation[]): ParsedOperation[];
+export {};

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

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNamespacePrefix = parseNamespacePrefix;
+exports.parseNamespace = parseNamespace;
+exports.parseStoreAddress = parseStoreAddress;
+exports.parseSearch = parseSearch;
+exports.parseListOperation = parseListOperation;
+exports.parseListNamespacesOptions = parseListNamespacesOptions;
+exports.parsePutArguments = parsePutArguments;
+exports.parseOperation = parseOperation;
+exports.parseOperations = parseOperations;
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+const primitives_js_1 = require("../../shared/validation/primitives.js");
+const rows_js_1 = require("./rows.js");
+const RESERVED_ROOT = 'langgraph';
+const DEFAULT_SEARCH_LIMIT = (0, primitives_js_1.parseLimit)(10, 0);
+const DEFAULT_LIST_LIMIT = 100;
+function parseLabels(value, field) {
+    if (!Array.isArray(value)) {
+        throw (0, errors_js_1.validationError)(`${field} must be an array of labels`, field);
+    }
+    const labels = [];
+    for (const label of value) {
+        labels.push((0, primitives_js_1.parseIdentifier)(label, table_schema_js_1.KEY_SEPARATOR, `${field} element`, table_schema_js_1.MAX_KEY_SEGMENT_BYTES));
+    }
+    return labels;
+}
+function parseNamespacePrefix(value, field) {
+    const labels = parseLabels(value, field);
+    const bytes = Buffer.byteLength((0, rows_js_1.sortKeyPrefix)(labels), 'utf8');
+    if (bytes >= table_schema_js_1.MAX_SORT_KEY_BYTES) {
+        throw (0, errors_js_1.validationError)(`${field} leads a sort key with ${bytes} bytes before any key; DynamoDB caps sort keys at ` +
+            `${table_schema_js_1.MAX_SORT_KEY_BYTES} bytes, so no stored namespace can match it`, field);
+    }
+    return labels;
+}
+function parseNamespace(value, field = 'namespace') {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw (0, errors_js_1.validationError)(`${field} must be a non-empty array`, field);
+    }
+    return parseLabels(value, field);
+}
+function parseStoreAddress(namespace, key) {
+    const parsedNamespace = parseNamespace(namespace);
+    const parsedKey = (0, primitives_js_1.parseIdentifier)(key, table_schema_js_1.KEY_SEPARATOR, 'key', table_schema_js_1.MAX_KEY_SEGMENT_BYTES);
+    const bytes = Buffer.byteLength((0, rows_js_1.sortKey)(parsedNamespace, parsedKey), 'utf8');
+    if (bytes > table_schema_js_1.MAX_SORT_KEY_BYTES) {
+        throw (0, errors_js_1.validationError)(`namespace and key compose a ${bytes}-byte sort key; DynamoDB caps sort keys at ` +
+            `${table_schema_js_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
+    }
+    return { namespace: parsedNamespace, key: parsedKey };
+}
+function parseIndex(index) {
+    if (index === undefined || index === false)
+        return index;
+    return (0, primitives_js_1.parseStringArray)(index, 'index');
+}
+function parseSearch(namespacePrefix, op) {
+    if (op.filter !== undefined)
+        (0, option_shape_js_1.assertObjectShape)(op.filter, 'filter');
+    const query = op.query === undefined ? undefined : (0, primitives_js_1.parseString)(op.query, 'query');
+    const offset = (0, primitives_js_1.parseInteger)(op.offset === undefined ? 0 : op.offset, 'offset', { min: 0 });
+    const limit = op.limit === undefined ? DEFAULT_SEARCH_LIMIT : (0, primitives_js_1.parseLimit)(op.limit, 0);
+    return {
+        kind: 'search',
+        namespacePrefix,
+        filter: op.filter,
+        query,
+        offset,
+        limit,
+    };
+}
+function parseMatchCondition(condition) {
+    (0, option_shape_js_1.assertObjectShape)(condition, 'matchConditions');
+    const { matchType, path } = condition;
+    if (matchType !== 'prefix' && matchType !== 'suffix') {
+        const received = typeof matchType === 'string' ? JSON.stringify(matchType) : typeof matchType;
+        throw (0, errors_js_1.validationError)(`matchType must be "prefix" or "suffix" (received ${received})`, 'matchConditions');
+    }
+    return { matchType, path: parseNamespacePrefix(path, matchType) };
+}
+function parseMatchConditions(conditions) {
+    if (conditions === undefined)
+        return undefined;
+    if (!Array.isArray(conditions)) {
+        throw (0, errors_js_1.validationError)('matchConditions must be an array', 'matchConditions');
+    }
+    const parsed = [];
+    for (const condition of conditions)
+        parsed.push(parseMatchCondition(condition));
+    return parsed;
+}
+function parseListOperation(op) {
+    const offset = (0, primitives_js_1.parseInteger)(op.offset, 'offset', { min: 0 });
+    const limit = (0, primitives_js_1.parseLimit)(op.limit, 0);
+    const maxDepth = op.maxDepth === undefined ? undefined : (0, primitives_js_1.parseInteger)(op.maxDepth, 'maxDepth', { min: 1 });
+    return {
+        kind: 'list',
+        matchConditions: parseMatchConditions(op.matchConditions),
+        maxDepth,
+        offset,
+        limit,
+    };
+}
+function parseListNamespacesOptions(options) {
+    (0, option_shape_js_1.assertObjectShape)(options, 'options');
+    const { prefix, suffix, maxDepth, limit = DEFAULT_LIST_LIMIT, offset = 0 } = options;
+    const matchConditions = [];
+    if (prefix !== undefined)
+        matchConditions.push({ matchType: 'prefix', path: prefix });
+    if (suffix !== undefined)
+        matchConditions.push({ matchType: 'suffix', path: suffix });
+    return parseListOperation({
+        matchConditions: matchConditions.length > 0 ? matchConditions : undefined,
+        maxDepth,
+        limit,
+        offset,
+    });
+}
+function assertNoPeriodLabel(namespace) {
+    if (namespace.some((label) => label.includes('.'))) {
+        throw (0, errors_js_1.validationError)('namespace element must not contain "."; upstream refuses it on every write', 'namespace element');
+    }
+}
+function assertUpstreamPutNamespace(namespace) {
+    assertNoPeriodLabel(namespace);
+    if (namespace[0] === RESERVED_ROOT) {
+        throw (0, errors_js_1.validationError)(`namespace must not start with "${RESERVED_ROOT}", the root label LangGraph reserves`, 'namespace');
+    }
+}
+function parsePutArguments(namespace, key, value, index) {
+    const address = parseStoreAddress(namespace, key);
+    assertUpstreamPutNamespace(address.namespace);
+    if (value === null) {
+        throw (0, errors_js_1.validationError)('value must be an object; delete() removes an item', 'value');
+    }
+    (0, option_shape_js_1.assertObjectShape)(value, 'value');
+    return {
+        kind: 'put',
+        address,
+        value: value,
+        index: parseIndex(index),
+    };
+}
+function parsePutOperation(op) {
+    const address = parseStoreAddress(op.namespace, op.key);
+    if (op.value !== null)
+        assertNoPeriodLabel(address.namespace);
+    if (op.value !== null)
+        (0, option_shape_js_1.assertObjectShape)(op.value, 'value');
+    const index = parseIndex(op.index);
+    if (op.value === null)
+        return { kind: 'delete', address };
+    return { kind: 'put', address, value: op.value, index };
+}
+function parseOperation(operation) {
+    if (typeof operation !== 'object' || operation === null || Array.isArray(operation)) {
+        throw (0, errors_js_1.validationError)('every operation in operations must be an object', 'operations');
+    }
+    if ('namespacePrefix' in operation) {
+        return parseSearch(parseNamespacePrefix(operation.namespacePrefix, 'namespacePrefix'), operation);
+    }
+    if ('value' in operation)
+        return parsePutOperation(operation);
+    if ('key' in operation) {
+        return { kind: 'get', address: parseStoreAddress(operation.namespace, operation.key) };
+    }
+    return parseListOperation(operation);
+}
+function parseOperations(operations) {
+    if (!Array.isArray(operations)) {
+        throw (0, errors_js_1.validationError)('operations must be an array', 'operations');
+    }
+    const parsed = [];
+    for (const operation of operations)
+        parsed.push(parseOperation(operation));
+    return parsed;
+}