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

package/dist/store/internal/parse.js

@@ -1,350 +0,0 @@
-"use strict";
-/**
- * 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.
- */
-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_1 = require("../../shared/dynamodb/table-schema");
-const errors_1 = require("../../shared/errors/errors");
-const option_shape_1 = require("../../shared/validation/option-shape");
-const primitives_1 = require("../../shared/validation/primitives");
-const rows_1 = require("./rows");
-const setup_1 = require("./setup");
-/**
- * The root label upstream `BaseStore.put` refuses
- * (`@langchain/langgraph-checkpoint@1.1.5` `dist/store/base.js:23`).
- */
-const RESERVED_ROOT = 'langgraph';
-/** The page `search` reads when the caller names none. */
-const DEFAULT_SEARCH_LIMIT = (0, primitives_1.parseLimit)(10, 0);
-/** The page `listNamespaces` reads when the caller names none. */
-const DEFAULT_LIST_LIMIT = 100;
-/**
- * Every label of `value`, each a well-formed identifier, as a copy. Iterated
- * with `for…of`, so a hole in a sparse array is checked as the `undefined` it
- * reads as rather than skipped.
- *
- * These are this package's own rules, and only those: `#` is this package's
- * separator, so a `.` costs nothing here, and a listing's `'*'` wildcard
- * satisfies every one of these rules, so it needs no exemption. Upstream
- * `BaseStore.put` refuses a `.` in a label and a `"langgraph"` root too, but
- * only in that one method — see {@link assertUpstreamPutNamespace}.
- */
-function parseLabels(value, field) {
-    if (!Array.isArray(value)) {
-        throw (0, errors_1.validationError)(`${field} must be an array of labels`, field);
-    }
-    const labels = [];
-    for (const label of value) {
-        labels.push((0, primitives_1.parseIdentifier)(label, table_schema_1.KEY_SEPARATOR, `${field} element`, table_schema_1.MAX_KEY_SEGMENT_BYTES));
-    }
-    return labels;
-}
-/**
- * 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.
- *
- * Throws: `VALIDATION` naming `field` for a non-array, or `<field> element` for
- * a malformed label.
- */
-function parseNamespacePrefix(value, field) {
-    return parseLabels(value, field);
-}
-/**
- * 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.
- */
-function parseNamespace(value, field = 'namespace') {
-    if (!Array.isArray(value) || value.length === 0) {
-        throw (0, errors_1.validationError)(`${field} must be a non-empty array`, field);
-    }
-    return parseLabels(value, field);
-}
-/**
- * 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.
- */
-function parseStoreAddress(namespace, key) {
-    const parsedNamespace = parseNamespace(namespace);
-    const parsedKey = (0, primitives_1.parseIdentifier)(key, table_schema_1.KEY_SEPARATOR, 'key', table_schema_1.MAX_KEY_SEGMENT_BYTES);
-    const bytes = Buffer.byteLength((0, rows_1.sortKey)(parsedNamespace, parsedKey), 'utf8');
-    if (bytes > table_schema_1.MAX_SORT_KEY_BYTES) {
-        throw (0, errors_1.validationError)(`namespace and key compose a ${bytes}-byte sort key; DynamoDB caps sort keys at ` +
-            `${table_schema_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
-    }
-    return { namespace: parsedNamespace, key: parsedKey };
-}
-/** A put's `index`: absent and `false` as given, a field list as a copy. */
-function parseIndex(index) {
-    if (index === undefined || index === false)
-        return index;
-    return (0, primitives_1.parseStringArray)(index, 'index');
-}
-/**
- * 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.
- */
-function parseSearch(namespacePrefix, op) {
-    if (op.filter !== undefined)
-        (0, option_shape_1.assertObjectShape)(op.filter, 'filter');
-    const query = op.query === undefined ? undefined : (0, primitives_1.parseString)(op.query, 'query');
-    const offset = (0, primitives_1.parseInteger)(op.offset === undefined ? 0 : op.offset, 'offset', { min: 0 });
-    const limit = op.limit === undefined ? DEFAULT_SEARCH_LIMIT : (0, primitives_1.parseLimit)(op.limit, 0);
-    return {
-        kind: 'search',
-        namespacePrefix,
-        filter: op.filter,
-        query,
-        offset,
-        limit,
-    };
-}
-/**
- * One match condition: an object, a known match type, a well-formed path.
- * `matchType` is refused rather than resolved when it is neither `'prefix'`
- * nor `'suffix'`: `matchNamespace`'s own branch on `matchType` (see
- * `actions/list-namespaces.ts`) otherwise takes an unrecognised type as a
- * suffix match and answers as if the caller had asked for one. The refusal echoes a string
- * `matchType` in the message and describes anything else by its type, since
- * `JSON.stringify` itself throws on a bigint.
- */
-function parseMatchCondition(condition) {
-    (0, option_shape_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_1.validationError)(`matchType must be "prefix" or "suffix" (received ${received})`, 'matchConditions');
-    }
-    return { matchType, path: parseNamespacePrefix(path, matchType) };
-}
-/** The match conditions of a listing, absent when none are given. */
-function parseMatchConditions(conditions) {
-    if (conditions === undefined)
-        return undefined;
-    if (!Array.isArray(conditions)) {
-        throw (0, errors_1.validationError)('matchConditions must be an array', 'matchConditions');
-    }
-    const parsed = [];
-    for (const condition of conditions)
-        parsed.push(parseMatchCondition(condition));
-    return parsed;
-}
-/**
- * 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.
- */
-function parseListOperation(op) {
-    const offset = (0, primitives_1.parseInteger)(op.offset, 'offset', { min: 0 });
-    const limit = (0, primitives_1.parseLimit)(op.limit, 0);
-    const maxDepth = op.maxDepth === undefined ? undefined : (0, primitives_1.parseInteger)(op.maxDepth, 'maxDepth', { min: 1 });
-    return {
-        kind: 'list',
-        matchConditions: parseMatchConditions(op.matchConditions),
-        maxDepth,
-        offset,
-        limit,
-    };
-}
-/**
- * Parse the options of `listNamespaces`.
- *
- * Accepts: `options` — only `prefix`, `suffix`, `maxDepth`, `limit` and
- * `offset`; `limit` defaults to 100 and `offset` to 0.
- *
- * Returns: the listing the options describe.
- *
- * Throws: `VALIDATION` naming `options.<key>` for a key this package does not
- * read, then as {@link parseListOperation}.
- */
-function parseListNamespacesOptions(options) {
-    (0, option_shape_1.assertShape)(options, setup_1.STORE_LIST_NAMESPACES_KEYS, '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,
-    });
-}
-/**
- * Refuse what upstream `BaseStore.put` refuses and this store's own key rules
- * allow: no `.` in a label, and no `"langgraph"` root
- * (`@langchain/langgraph-checkpoint@1.1.5` `dist/store/base.js:16-24`). These
- * two rules belong to that one method only: the reference `InMemoryStore.batch`
- * checks neither, and LangGraph's runtime reaches a store only through
- * `batch()`, so a namespace such as `['memories', 'jane.doe@example.com']`
- * written there must stay readable, searchable and deletable here. Only
- * `put()` applies it, as upstream does; `batch()` does not.
- */
-function assertUpstreamPutNamespace(namespace) {
-    if (namespace.some((label) => label.includes('.'))) {
-        throw (0, errors_1.validationError)('namespace element must not contain "."; put() refuses it, as upstream BaseStore.put does', 'namespace element');
-    }
-    if (namespace[0] === RESERVED_ROOT) {
-        throw (0, errors_1.validationError)(`namespace must not start with "${RESERVED_ROOT}", the root label LangGraph reserves`, 'namespace');
-    }
-}
-/**
- * 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.
- */
-function parsePutArguments(namespace, key, value, index) {
-    const address = parseStoreAddress(namespace, key);
-    assertUpstreamPutNamespace(address.namespace);
-    if (value === null) {
-        throw (0, errors_1.validationError)('value must be an object; delete() removes an item', 'value');
-    }
-    (0, option_shape_1.assertObjectShape)(value, 'value');
-    return {
-        kind: 'put',
-        address,
-        value: value,
-        index: parseIndex(index),
-    };
-}
-/**
- * A batch put, or the delete a `null` value asks for. The index is parsed
- * either way, as it always was for a put with a `null` value.
- */
-function parsePutOperation(op) {
-    const address = parseStoreAddress(op.namespace, op.key);
-    if (op.value !== null)
-        (0, option_shape_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 };
-}
-/**
- * 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.
- */
-function parseOperation(operation) {
-    if (typeof operation !== 'object' || operation === null || Array.isArray(operation)) {
-        throw (0, errors_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);
-}
-/**
- * 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.
- */
-function parseOperations(operations) {
-    if (!Array.isArray(operations)) {
-        throw (0, errors_1.validationError)('operations must be an array', 'operations');
-    }
-    const parsed = [];
-    for (const operation of operations)
-        parsed.push(parseOperation(operation));
-    return parsed;
-}