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

package/dist/checkpointer/internal/parse.js

@@ -1,372 +0,0 @@
-"use strict";
-/**
- * Hides the rules a checkpointer's caller input is held to.
- *
- * Every config, option and identifier an action accepts is parsed here once
- * into a branded type only these parsers can build (record 21), so code
- * downstream asks for a `ThreadId` or a `PutWritesRequest` and never checks it
- * again. Which markers mean "no id", how the legacy `thread_ts` alias
- * resolves, which field a refusal names and in what order the checks run are
- * all settled here and nowhere else.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ROOT_NAMESPACE = void 0;
-exports.parseThreadId = parseThreadId;
-exports.parseCheckpointNs = parseCheckpointNs;
-exports.parseCheckpointId = parseCheckpointId;
-exports.parseTaskId = parseTaskId;
-exports.parseWriteChannel = parseWriteChannel;
-exports.parseConfig = parseConfig;
-exports.parseThreadConfig = parseThreadConfig;
-exports.parsePutRequest = parsePutRequest;
-exports.parsePutWritesRequest = parsePutWritesRequest;
-exports.parseListScope = parseListScope;
-exports.parseDeltaHistoryRequest = parseDeltaHistoryRequest;
-const table_schema_1 = require("../../shared/dynamodb/table-schema");
-const errors_1 = require("../../shared/errors/errors");
-const collaborators_1 = require("../../shared/validation/collaborators");
-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");
-/**
- * Parse a thread id.
- *
- * Accepts: `value` — anything; a thread id reaches the partition key, so it is
- * held to every identifier rule at {@link MAX_PARTITION_ID_BYTES}.
- *
- * Returns: `value` as a {@link ThreadId}.
- *
- * Throws: `VALIDATION` naming `thread_id`.
- */
-function parseThreadId(value) {
-    return (0, primitives_1.parseIdentifier)(value, table_schema_1.KEY_SEPARATOR, 'thread_id', table_schema_1.MAX_PARTITION_ID_BYTES);
-}
-/**
- * Parse a checkpoint namespace.
- *
- * Accepts: `value` — anything; `''` is legal, because it *is* the root
- * namespace, and every other identifier rule applies (see `parseKeySegment`).
- *
- * Returns: `value` as a {@link CheckpointNs}.
- *
- * Throws: `VALIDATION` naming `checkpoint_ns`.
- */
-function parseCheckpointNs(value) {
-    return (0, primitives_1.parseKeySegment)(value, table_schema_1.KEY_SEPARATOR, 'checkpoint_ns', table_schema_1.MAX_KEY_SEGMENT_BYTES);
-}
-/**
- * Parse a checkpoint id.
- *
- * Accepts: `value` — anything. `field` — the field the caller set:
- * `checkpoint_id` by default, `thread_ts` when the id was read from that legacy
- * alias, `before` for `list`'s bound, so the refusal names what the caller
- * actually wrote.
- *
- * Returns: `value` as a {@link CheckpointId}.
- *
- * Throws: `VALIDATION` naming `field`.
- */
-function parseCheckpointId(value, field = 'checkpoint_id') {
-    return (0, primitives_1.parseIdentifier)(value, table_schema_1.KEY_SEPARATOR, field, table_schema_1.MAX_KEY_SEGMENT_BYTES);
-}
-/**
- * Parse a task id. LangGraph's own are UUIDs; the rule is stated for whatever
- * else a caller passes.
- *
- * Accepts: `value` — anything.
- *
- * Returns: `value` as a {@link TaskId}.
- *
- * Throws: `VALIDATION` naming `taskId`.
- */
-function parseTaskId(value) {
-    return (0, primitives_1.parseIdentifier)(value, table_schema_1.KEY_SEPARATOR, 'taskId', table_schema_1.MAX_KEY_SEGMENT_BYTES);
-}
-/**
- * Parse a pending write's channel, the trailing segment of its WRITE sort key.
- *
- * Accepts: `value` — anything; LangGraph's own channel names never contain the
- * reserved separator.
- *
- * Returns: `value` as a {@link WriteChannel}.
- *
- * Throws: `VALIDATION` naming `channel`.
- */
-function parseWriteChannel(value) {
-    return (0, primitives_1.parseIdentifier)(value, table_schema_1.KEY_SEPARATOR, 'channel', table_schema_1.MAX_KEY_SEGMENT_BYTES);
-}
-/** The root namespace, which a config that names none addresses. */
-exports.ROOT_NAMESPACE = parseCheckpointNs('');
-/**
- * Whether `value` is one of the three markers a config treats as "no id here":
- * exactly `undefined`, `null` and `''`. Not JavaScript truthiness: `0`, `false`
- * and `NaN` are values to parse, and refuse, not absences.
- */
-function isAbsentId(value) {
-    return value === undefined || value === null || value === '';
-}
-/**
- * Refuse a config whose own shape this package cannot read, before any
- * identifier is read from it. A `null` or `undefined` config otherwise reached
- * a bare `TypeError`; a `configurable` that is not an object read as a config
- * naming no thread, so `list` scanned every thread in the table; a signal that
- * is not `AbortSignal`-shaped failed only inside a retry's wait.
- */
-function assertConfigShape(config) {
-    (0, option_shape_1.assertObjectShape)(config, 'config');
-    if (config.configurable !== undefined)
-        (0, option_shape_1.assertObjectShape)(config.configurable, 'configurable');
-    (0, collaborators_1.assertSignalLike)(config.signal);
-}
-/** A shape-checked config's `configurable`, `{}` when it has none. */
-function configurableOf(config) {
-    assertConfigShape(config);
-    return (config.configurable ?? {});
-}
-/** The namespace a `configurable` names, or `undefined` when it names none. */
-function namespaceOf(configurable) {
-    if (configurable.checkpoint_ns === undefined)
-        return undefined;
-    return parseCheckpointNs(configurable.checkpoint_ns ?? '');
-}
-/**
- * A config's checkpoint id, resolved the way the reference's `getCheckpointId`
- * does — `checkpoint_id || thread_ts || ''` (`@langchain/langgraph-checkpoint`
- * `dist/base.js:169-171`) — but against exactly the three absence markers of
- * {@link isAbsentId}, so `checkpoint_id: 0` is refused as the malformed id it
- * is rather than falling through to `thread_ts` or reading as "the newest".
- */
-function resolveCheckpointId(configurable) {
-    if (!isAbsentId(configurable.checkpoint_id))
-        return parseCheckpointId(configurable.checkpoint_id);
-    if (!isAbsentId(configurable.thread_ts)) {
-        return parseCheckpointId(configurable.thread_ts, 'thread_ts');
-    }
-    return undefined;
-}
-/**
- * Parse a config a read accepts, naming a thread or not.
- *
- * Accepts: `config` — an object; `configurable` absent or an object; `signal`
- * absent or `AbortSignal`-shaped. A config naming no thread is legal: the
- * identifiers it does give are still parsed, as the reference saver does
- * (`@langchain/langgraph-checkpoint@1.1.5` `dist/memory.js:86-92`).
- *
- * Returns: the thread, the namespace as given (`undefined` when not named), the
- * checkpoint id (`undefined` for "the newest"), and the signal.
- *
- * Throws: `VALIDATION` naming `config`, `configurable` or `signal` for a config
- * of the wrong shape, then `thread_id`, `checkpoint_ns`, `checkpoint_id` or
- * `thread_ts`, in that order.
- */
-function parseConfig(config) {
-    const configurable = configurableOf(config);
-    const threadId = configurable.thread_id === undefined ? undefined : parseThreadId(configurable.thread_id);
-    return {
-        threadId,
-        checkpointNs: namespaceOf(configurable),
-        checkpointId: resolveCheckpointId(configurable),
-        signal: config.signal,
-    };
-}
-/**
- * Parse a config a write needs: one that names a thread.
- *
- * Accepts: `config` — as {@link parseConfig}, with `thread_id` required.
- *
- * Returns: the address, its namespace defaulted to {@link ROOT_NAMESPACE}, and
- * the signal.
- *
- * Throws: as {@link parseConfig}; a missing `thread_id` is refused naming
- * `thread_id`, before the namespace is read.
- */
-function parseThreadConfig(config) {
-    const configurable = configurableOf(config);
-    const threadId = parseThreadId(configurable.thread_id);
-    return {
-        address: {
-            threadId,
-            checkpointNs: namespaceOf(configurable) ?? exports.ROOT_NAMESPACE,
-            checkpointId: resolveCheckpointId(configurable),
-        },
-        signal: config.signal,
-    };
-}
-/**
- * Parse the arguments of `put`.
- *
- * Accepts: `config` — as {@link parseThreadConfig}; its checkpoint id becomes
- * the parent. `checkpoint` — must be present; its `id` is parsed as the key
- * segment it becomes. `metadata` — stored as given.
- *
- * Returns: the request every later step of the put reads.
- *
- * Throws: as {@link parseThreadConfig}; then `VALIDATION` naming `checkpoint`
- * for a `null` or `undefined` checkpoint, or `checkpoint_id` for a malformed
- * `checkpoint.id`.
- */
-function parsePutRequest(config, checkpoint, metadata) {
-    const { address, signal } = parseThreadConfig(config);
-    if (checkpoint === null || checkpoint === undefined) {
-        throw (0, errors_1.validationError)('checkpoint must be an object', 'checkpoint');
-    }
-    const checkpointId = parseCheckpointId(checkpoint.id);
-    return {
-        address: { threadId: address.threadId, checkpointNs: address.checkpointNs, checkpointId },
-        parentCheckpointId: address.checkpointId,
-        checkpoint,
-        metadata,
-        signal,
-    };
-}
-/**
- * Refuse a `writes` argument that cannot be read as the tuples it is typed to
- * hold: a non-array, or an entry that is not itself an array. Every entry is
- * checked before any channel is, so a call with both faults names `writes`.
- *
- * Indexed by position rather than `Array.prototype.forEach`, which skips a
- * hole in a sparse array (`[, ['a', 1]]`) instead of visiting it: a skipped
- * hole read as `undefined` downstream, past every later `.map` this parser
- * runs over the same array, and reached the `WriteChannel` brand unparsed.
- */
-function assertWriteEntries(writes) {
-    if (!Array.isArray(writes)) {
-        throw (0, errors_1.validationError)('writes must be an array', 'writes');
-    }
-    for (let index = 0; index < writes.length; index += 1) {
-        if (!Array.isArray(writes[index])) {
-            throw (0, errors_1.validationError)(`writes[${index}] must be a [channel, value] tuple`, 'writes');
-        }
-    }
-}
-/**
- * Refuse a write whose composed WRITE sort key would pass DynamoDB's cap.
- * Every segment is capped on its own, and four capped segments together still
- * exceed it.
- */
-function assertWriteKeyFits(address, taskId, channel) {
-    const bytes = (0, rows_1.writeSortKeyBytes)({
-        checkpointNs: address.checkpointNs,
-        checkpointId: address.checkpointId,
-        taskId,
-        channel,
-    });
-    if (bytes > table_schema_1.MAX_SORT_KEY_BYTES) {
-        throw (0, errors_1.validationError)(`checkpoint_ns, checkpoint_id, taskId and channel compose a ${bytes}-byte sort key; ` +
-            `DynamoDB caps sort keys at ${table_schema_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
-    }
-}
-/**
- * Parse the arguments of `putWrites`.
- *
- * Accepts: `config` — as {@link parseThreadConfig}, and it must name a
- * checkpoint, since writes attach to one. `writes` — an array of
- * `[channel, value]` arrays; the value, and any element past the second, are
- * unconstrained, as upstream's type places no rule on them. `taskId` — parsed
- * as the key segment it becomes.
- *
- * Returns: the request, with a fresh array of fresh tuples, so a caller
- * changing its own array while the call awaits changes nothing that was
- * checked.
- *
- * Throws: `VALIDATION`, before anything is encoded or uploaded, in this order:
- * `taskId`; as {@link parseThreadConfig}; `checkpoint_id` when the config names
- * none; `writes` for a non-array or an entry that is not one; `channel` for any
- * malformed channel; `sortKey` for any write whose composed key passes the cap.
- */
-function parsePutWritesRequest(config, writes, taskId) {
-    const parsedTaskId = parseTaskId(taskId);
-    const { address, signal } = parseThreadConfig(config);
-    if (address.checkpointId === undefined) {
-        throw (0, errors_1.validationError)('checkpoint_id is required to store writes', 'checkpoint_id');
-    }
-    const target = {
-        threadId: address.threadId,
-        checkpointNs: address.checkpointNs,
-        checkpointId: address.checkpointId,
-    };
-    assertWriteEntries(writes);
-    const channels = writes.map(([channel]) => parseWriteChannel(channel));
-    for (const channel of channels)
-        assertWriteKeyFits(target, parsedTaskId, channel);
-    return {
-        address: target,
-        taskId: parsedTaskId,
-        writes: writes.map(([, value], index) => [channels[index], value]),
-        signal,
-    };
-}
-/**
- * `options.before`'s checkpoint id, parsed the way a config's is: exactly
- * `undefined`, `null` and `''` mean no bound, anything else is parsed as the
- * key segment it is compared with. Left unchecked, a non-string made every
- * row fail the comparison and the listing came back silently empty.
- */
-function beforeCheckpointId(before) {
-    if (before === undefined)
-        return undefined;
-    (0, option_shape_1.assertObjectShape)(before, 'before');
-    const checkpointId = before.configurable?.checkpoint_id;
-    if (isAbsentId(checkpointId))
-        return undefined;
-    return parseCheckpointId(checkpointId, 'before');
-}
-/**
- * Parse the arguments of `list`.
- *
- * Accepts: `config` — as {@link parseConfig}; `thread_id` omitted lists every
- * thread and `checkpoint_ns` omitted every namespace, as the reference savers
- * do. `options.limit` — an integer from 0 to the page ceiling; `0` asks for
- * nothing, and a negative value is refused rather than read as zero, since it
- * can only be a page size whose computation went wrong. `options.before` — an
- * object naming, at most, a `checkpoint_id`. `options.filter` — metadata
- * equality clauses; an object when given.
- *
- * Returns: the scope every later step of the listing reads instead of the raw
- * config.
- *
- * Throws: `VALIDATION`, config first: as {@link parseConfig}; then
- * `options.<key>` for a key this package does not read, `filter`, `limit`,
- * `before`.
- */
-function parseListScope(config, options) {
-    const { threadId, checkpointNs, checkpointId, signal } = parseConfig(config);
-    if (options !== undefined) {
-        (0, option_shape_1.assertShape)(options, setup_1.SAVER_LIST_KEYS, 'options');
-        if (options.filter !== undefined)
-            (0, option_shape_1.assertObjectShape)(options.filter, 'filter');
-    }
-    // Zero floor: `list` is an iterator a caller drains, so a zero page ends it
-    // immediately and visibly. Only a conversation window refuses zero.
-    const limit = options?.limit === undefined ? undefined : (0, primitives_1.parseLimit)(options.limit, 0);
-    return {
-        threadId,
-        checkpointNs,
-        checkpointId,
-        before: beforeCheckpointId(options?.before),
-        filter: options?.filter,
-        limit,
-        signal,
-    };
-}
-/**
- * Parse the options of `getDeltaChannelHistory` — their shape only. The
- * config's identifiers are parsed by the `getTuple` each hop of the walk calls,
- * and only once a channel is named: an empty `channels` reads nothing, so it
- * refuses nothing either.
- *
- * Accepts: `options` — an object naming exactly `config` and `channels`.
- * `options.config` — shaped as {@link parseConfig} requires. `options.channels`
- * — an array of strings; an empty one is a legitimate request.
- *
- * Returns: the config as given and a copy of the channels.
- *
- * Throws: `VALIDATION` naming `options`, `options.<key>`, `config`,
- * `configurable`, `signal` or `channels`.
- */
-function parseDeltaHistoryRequest(options) {
-    (0, option_shape_1.assertShape)(options, setup_1.DELTA_CHANNEL_HISTORY_KEYS, 'options');
-    assertConfigShape(options.config);
-    return { config: options.config, channels: (0, primitives_1.parseStringArray)(options.channels, 'channels') };
-}