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

package/dist/history/internal/message-read.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Hides how a session's message key space is read.
+ *
+ * A read admits only rows this package wrote as a message of this session,
+ * refusing any other row in the key space rather than skipping it, treats an
+ * expired row as absent however long the sweep lags, walks newest-first when
+ * it wants the latest few and restores chronological order, and counts the
+ * rows the same way it reads them, so a repaired count is the number a read
+ * returns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWindow = readWindow;
+exports.countLiveMessages = countLiveMessages;
+const clock_1 = require("../../shared/clock");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const errors_1 = require("../../shared/errors/errors");
+const truncate_1 = require("../../shared/logging/truncate");
+const ulid_1 = require("../../shared/ulid");
+const rows_1 = require("./rows");
+/**
+ * The row as one of this adapter's messages, or a refusal naming it.
+ *
+ * The version is checked first, so a row a newer release wrote is reported as
+ * newer rather than judged against attribute types it may no longer use. What
+ * survives that is narrowed rather than cast: a shared table's message key
+ * space is this adapter's, and a row in it is not necessarily.
+ *
+ * Reported and never dropped, whatever `onCorruptMessage` says. That policy
+ * exists for a payload no reader could recover, and a row this adapter cannot
+ * account for is not one — skipping it handed the caller a shorter
+ * conversation that `RunnableWithMessageHistory` then re-persists as the whole
+ * truth. The `warn` carries the sort key, cut like every other row-sourced
+ * one, because the error can only say that such a row exists and an operator
+ * has to go and look at it.
+ */
+function parseSessionMessageRow(context, sessionId, raw) {
+    (0, table_schema_1.assertReadableRow)(raw, 'message');
+    const item = (0, rows_1.parseMessageRow)(raw);
+    if (item)
+        return item;
+    context.logger.warn('getMessages: refused a row that is not a chat message item', {
+        sessionId,
+        sortKey: (0, truncate_1.truncateForLog)(raw.SK),
+    });
+    throw (0, errors_1.validationError)('a row in the message key space of this session is not a chat message item this package ' +
+        'wrote: its `sessionId` or `message` attribute is absent, is of the wrong type, or names ' +
+        'another session. The `warn` logged alongside this names the row', 'message');
+}
+/**
+ * Read the live message items a window selects, in chronological order.
+ *
+ * Without `limit` the query walks the session oldest-first. With it the query
+ * walks newest-first with a matching page cap and stops as soon as `limit`
+ * live items are in hand — rows past their TTL are skipped here, so a page can
+ * come back short and the walk simply continues — and the tail is then
+ * reversed back into chronological order. `before` becomes an exclusive upper
+ * sort-key bound: the message prefix plus the ULID time characters of that
+ * instant, which every message id from that millisecond onwards sorts after.
+ *
+ * Accepts: `window.limit` — absent asks for the whole session, which is what
+ * `getMessages()` with no arguments means; otherwise at least 1, which is why
+ * no zero case is handled below. `parseMessageWindow` refuses `0` for its
+ * own reason, and that refusal is also what keeps `Limit: 0` — which DynamoDB
+ * rejects outright with a raw `ValidationException` — out of the query built
+ * here. `window.before` — already parsed as a real date. `signal` — aborts
+ * between pages.
+ *
+ * Returns: the live messages in chronological order, oldest first, whichever
+ * direction the query walked.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer version wrote — checked before
+ * the row's ttl, so the answer does not depend on the reading machine's clock;
+ * `VALIDATION` naming `message` for a row in this session's message key
+ * space that this adapter did not write, checked before the ttl for the same
+ * reason; `ABORTED`; whatever the query throws.
+ *
+ * Guarantees: strongly consistent, so the turn just appended is visible to the
+ * very next read. An unlimited window is deliberately uncapped — silently
+ * truncating a conversation is worse than a slow read, and a caller that wants
+ * a bound passes `limit` — so past {@link LIST_SCAN_WARN_THRESHOLD} messages
+ * the read still succeeds and an operator is told the session is unusually
+ * large.
+ */
+async function readWindow(context, sessionId, window, signal) {
+    const now = (0, clock_1.nowSeconds)();
+    const limit = window.limit ?? Number.POSITIVE_INFINITY;
+    const items = [];
+    for await (const raw of (0, paginate_1.paginateQuery)({
+        retry: (0, retry_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, rows_1.messageQuery)(context.tableName, sessionId, {
+            consistent: true,
+            descending: window.limit !== undefined,
+            limit: window.limit,
+            beforeSortKey: window.before && (0, rows_1.messageSortKey)((0, ulid_1.ulidTimePrefix)(window.before.getTime())),
+        }),
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        // A message newer than this version reads, and a row that is not one of
+        // this adapter's at all, both fail loudly rather than vanishing from the
+        // window.
+        const item = parseSessionMessageRow(context, sessionId, raw);
+        if ((0, table_schema_1.isExpiredRow)(item, now))
+            continue;
+        items.push(item);
+        if (items.length >= limit)
+            break;
+    }
+    if (items.length >= paginate_1.LIST_SCAN_WARN_THRESHOLD) {
+        context.logger.warn('getMessages: a session holds very many messages; the read is complete but slow. Pass a ' +
+            '`limit` to read only the newest turns', { sessionId, messages: items.length });
+    }
+    return window.limit === undefined ? items : items.reverse();
+}
+/**
+ * The row as one of this session's messages, or a refusal naming it — the same
+ * test the read makes, on the same order: the version first, so a row a newer
+ * release wrote is reported as newer rather than judged against attribute
+ * types it may no longer use.
+ *
+ * The count is a definition rather than a tally, and the definition is "what
+ * `getMessages` would return". A row in the message key space that this
+ * adapter did not write makes that read refuse the whole session, so counting
+ * it would write a repaired `messageCount` back onto a session no reader can
+ * open — a number that is not merely stale but describes nothing. The repair
+ * refuses instead, and the read's own `warn` is what names the row.
+ */
+function parseCountableRow(raw, sessionId) {
+    (0, table_schema_1.assertReadableRow)(raw, 'message');
+    const item = (0, rows_1.parseMessageRow)(raw);
+    if (item)
+        return item;
+    throw (0, errors_1.validationError)(`session "${sessionId}" holds a row in its message key space that is not a chat message ` +
+        'item this package wrote, so its messages cannot be counted: a read of the session ' +
+        'reports the same row and names it. Remove or repair the row, then reconcile again', 'message');
+}
+/**
+ * The number of message rows a session holds, counted the way the read path
+ * counts them.
+ *
+ * Only rows `getMessages` would return are counted: an expired message that
+ * DynamoDB's TTL sweep has not yet removed is invisible to every reader, so
+ * counting it would "repair" `messageCount` to a number nobody ever sees. The
+ * count is therefore a definition, not an implementation detail — it is what
+ * makes the repaired value agree with what the session returns. For the same
+ * reason a message a newer release wrote, and a row in the message key space
+ * that this adapter did not write, are both refused rather than counted:
+ * `getMessages` refuses them.
+ *
+ * Accepts: `sessionId` — validated by the caller. `signal` — aborts the reads.
+ *
+ * Returns: how many messages a reader would actually see right now.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a message row a newer release wrote, checked
+ * before the row's ttl as `getMessages` checks it; `VALIDATION` naming
+ * `message` for a row in the message key space that is not one of this
+ * adapter's, which `getMessages` refuses too; whatever the query throws
+ * after retries; `ABORTED`.
+ *
+ * Guarantees: each row comes back projected to its identity, its format
+ * version and its ttl, so no message payload is transferred however large the
+ * session is — the descriptor is projected by the one nested path
+ * `message.location` that every descriptor this package has written carries,
+ * which proves the attribute is there and a map without reading the bytes it
+ * holds. Every check runs here rather than in a filter, because a filter would
+ * drop an expired row before its version could be checked. The pages are
+ * walked by the shared paginator with both of its caps lifted: a partial count
+ * is not a repair, it is a new and wrong number, so the count either completes
+ * or fails.
+ */
+async function countLiveMessages(context, sessionId, signal) {
+    const now = (0, clock_1.nowSeconds)();
+    const query = (0, rows_1.messageQuery)(context.tableName, sessionId);
+    let total = 0;
+    for await (const raw of (0, paginate_1.paginateQuery)({
+        retry: (0, retry_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: {
+            ...query,
+            ProjectionExpression: '#pk, #sid, #msg.#loc, #v, #ttl',
+            ExpressionAttributeNames: {
+                ...query.ExpressionAttributeNames,
+                '#sid': 'sessionId',
+                '#msg': 'message',
+                '#loc': 'location',
+                '#v': 'v',
+                '#ttl': 'ttl',
+            },
+        },
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        const row = parseCountableRow(raw, sessionId);
+        if (!(0, table_schema_1.isExpiredRow)(row, now))
+            total += 1;
+    }
+    return total;
+}

package/dist/history/internal/parse.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Hides the rules chat-history input must meet before anything reads it.
+ *
+ * A session id, an append's messages, a read window and the listing options
+ * are each parsed once into a type only this module can build (record 21), so
+ * an action that holds one never checks it again. Which messages may be
+ * stored is decided by the read side's own rebuild, so write and read agree
+ * by construction, and which instants a `before` may name follows from the
+ * range a message id can express.
+ */
+import { type BaseMessage, type StoredMessage } from '@langchain/core/messages';
+import { type PageLimit } from '../../shared/validation/primitives';
+import type { GetMessagesOptions, ListSessionsOptions, MessageWindow } from '../types';
+declare const sessionIdBrand: unique symbol;
+declare const storableMessagesBrand: unique symbol;
+declare const parsedWindowBrand: unique symbol;
+/**
+ * A session id checked as the partition key it becomes. {@link parseSessionId}
+ * is the only way to obtain one, so an internal function that asks for a
+ * `SessionId` cannot be handed one nobody checked, and does not check it again.
+ * Each of the four history actions that take one — add, clear, get and
+ * reconcile — parses it on every call, and the session adapter parses the id
+ * it is bound to when it is built. The brand is phantom: at run time it is the
+ * caller's string.
+ */
+export type SessionId = string & {
+    readonly [sessionIdBrand]: true;
+};
+/**
+ * Messages in their stored form, each one proven to rebuild on the read side.
+ * Built only by {@link parseStoredMessages}; the array is the one
+ * {@link parseMessages} made, which no caller holds.
+ */
+export type StorableMessages = StoredMessage[] & {
+    readonly [storableMessagesBrand]: true;
+};
+/**
+ * A conversation window checked against the page rule and the range a message
+ * id can express, holding only the keys the caller gave. Built only by
+ * {@link parseMessageWindow}; its `before` is a copy, so a caller moving its own
+ * `Date` afterwards moves nothing this package reads.
+ */
+export type ParsedWindow = {
+    readonly limit?: PageLimit;
+    readonly before?: Date;
+} & {
+    readonly [parsedWindowBrand]: true;
+};
+/**
+ * Parse a session id.
+ *
+ * Accepts: `value` — anything; a session id reaches the partition key, so it is
+ * held to every identifier rule at {@link MAX_PARTITION_ID_BYTES}.
+ *
+ * Returns: `value` as a {@link SessionId}.
+ *
+ * Throws: `VALIDATION` naming `sessionId`.
+ */
+export declare function parseSessionId(value: unknown): SessionId;
+/**
+ * Parse stored messages: prove each one rebuilds on the read side.
+ *
+ * Accepts: `stored` — the stored form of one call's messages. The check *is*
+ * the read side's own rebuild (`mapStoredMessagesToChatMessages`), so write and
+ * read agree by construction rather than by two lists of types kept in step by
+ * hand.
+ *
+ * Returns: `stored`, as {@link StorableMessages}.
+ *
+ * Throws: `VALIDATION` naming `messages`, carrying the offending index and
+ * type. The type comes off the caller's own object and nothing length-checked
+ * it, so the message names it bounded by {@link truncateForLog}, and so is
+ * what LangChain says about it — that text renders the same unchecked value
+ * into itself, so bounding only the type bounds nothing. The two take
+ * different caps because they are different things: the type is an identifier,
+ * while what LangChain threw is prose, cut once by `redactedMessage` and not
+ * again here. `context` still names `messages`, which is what a caller
+ * branches on. A `RemoveMessage`, or a tool, function or generic message
+ * missing its required field, is refused here instead of being persisted and
+ * then skipped or thrown by `getMessages`. A hole in a sparse array is refused
+ * as missing, naming its index: the array is walked by index, where
+ * `Array.prototype.forEach` would skip the hole and let it through.
+ */
+export declare function parseStoredMessages(stored: StoredMessage[]): StorableMessages;
+/**
+ * Parse the messages of one append, in two passes: to the stored form, then
+ * proof that each rebuilds.
+ *
+ * Accepts: `messages` — declared `BaseMessage[]`; a non-array is refused, and
+ * so is an entry LangChain cannot serialize.
+ *
+ * Returns: a fresh array of stored messages, as {@link StorableMessages}.
+ *
+ * Throws: `VALIDATION` naming `messages`, with the offending index for an
+ * entry.
+ */
+export declare function parseMessages(messages: BaseMessage[]): StorableMessages;
+/**
+ * Parse a conversation window.
+ *
+ * Accepts: `window.limit` — an integer from 1 to the page ceiling; the only
+ * floor of 1 in the package, because a window feeds a model, and an empty
+ * conversation is not a visibly empty answer but an invented one.
+ * `window.before` — a valid `Date` inside the range a message id can express.
+ *
+ * Returns: a fresh window holding only the keys the caller gave, as a
+ * {@link ParsedWindow}.
+ *
+ * Throws: `VALIDATION` naming `limit` or `before`.
+ */
+export declare function parseMessageWindow(window: MessageWindow): ParsedWindow;
+/** The arguments of `getMessages`, parsed. */
+export interface GetMessagesRequest {
+    readonly sessionId: SessionId;
+    readonly window: ParsedWindow;
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Parse the arguments of `getMessages`.
+ *
+ * Accepts: `sessionId` — as {@link parseSessionId}. `options` — an object with
+ * only `limit`, `before` and `signal`; the window as {@link parseMessageWindow}.
+ *
+ * Returns: the request the read works from.
+ *
+ * Throws: `VALIDATION`, in this order: `options.<key>`, `signal`, `sessionId`,
+ * `limit`, `before`.
+ */
+export declare function parseGetMessagesRequest(sessionId: string, options: GetMessagesOptions): GetMessagesRequest;
+/** The options of `listSessions`, parsed. */
+export interface ListSessionsRequest {
+    readonly limit: PageLimit | undefined;
+    readonly maxItems: number | undefined;
+    readonly maxIterations: number | undefined;
+    readonly cursor: string | undefined;
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Parse the options of `listSessions`.
+ *
+ * Accepts: `options` — only `limit`, `cursor`, `maxIterations`, `maxItems` and
+ * `signal`. `limit` — 0 to the page ceiling; `0` is answered with an empty page.
+ * `maxItems`, `maxIterations` — an integer of at least 1, or `Infinity`.
+ * `cursor` — a string, and only with `indexName`. `indexName` — the adapter's
+ * configured recency index, if any.
+ *
+ * Returns: the request the listing works from.
+ *
+ * Throws: `VALIDATION`, in this order: `options.<key>`, `signal`, `limit`,
+ * `maxItems`, `maxIterations`, `cursor`.
+ */
+export declare function parseListSessionsRequest(options: ListSessionsOptions, indexName: string | undefined): ListSessionsRequest;
+export {};

package/dist/history/internal/parse.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * Hides the rules chat-history input must meet before anything reads it.
+ *
+ * A session id, an append's messages, a read window and the listing options
+ * are each parsed once into a type only this module can build (record 21), so
+ * an action that holds one never checks it again. Which messages may be
+ * stored is decided by the read side's own rebuild, so write and read agree
+ * by construction, and which instants a `before` may name follows from the
+ * range a message id can express.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSessionId = parseSessionId;
+exports.parseStoredMessages = parseStoredMessages;
+exports.parseMessages = parseMessages;
+exports.parseMessageWindow = parseMessageWindow;
+exports.parseGetMessagesRequest = parseGetMessagesRequest;
+exports.parseListSessionsRequest = parseListSessionsRequest;
+const messages_1 = require("@langchain/core/messages");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const errors_1 = require("../../shared/errors/errors");
+const secret_patterns_1 = require("../../shared/logging/secret-patterns");
+const truncate_1 = require("../../shared/logging/truncate");
+const ulid_1 = require("../../shared/ulid");
+const collaborators_1 = require("../../shared/validation/collaborators");
+const option_shape_1 = require("../../shared/validation/option-shape");
+const primitives_1 = require("../../shared/validation/primitives");
+const setup_1 = require("./setup");
+/**
+ * Parse a session id.
+ *
+ * Accepts: `value` — anything; a session id reaches the partition key, so it is
+ * held to every identifier rule at {@link MAX_PARTITION_ID_BYTES}.
+ *
+ * Returns: `value` as a {@link SessionId}.
+ *
+ * Throws: `VALIDATION` naming `sessionId`.
+ */
+function parseSessionId(value) {
+    return (0, primitives_1.parseIdentifier)(value, table_schema_1.KEY_SEPARATOR, 'sessionId', table_schema_1.MAX_PARTITION_ID_BYTES);
+}
+/**
+ * Serialize the caller's messages, reporting a value that is not a message.
+ *
+ * Accepts: `messages` — LangChain messages. The type says so; this runs for the
+ * JavaScript caller it does not bind, and for the `any` that reaches an
+ * `addMessages` through a chain. Empty is empty.
+ *
+ * Returns: the messages in their stored form, in order.
+ *
+ * Throws: `VALIDATION` naming `messages` and the offending index. Serializing
+ * one message at a time is what makes that index knowable: mapping the array in
+ * one call failed with `TypeError: message.toDict is not a function` from inside
+ * LangChain, naming neither the message nor this library. What LangChain says
+ * is quoted bounded: that text renders the offending value into itself, so it
+ * is exactly as long as the caller's own object makes it, and bounding the
+ * index while relaying it whole would bound nothing at all. The bound is
+ * `redactedMessage`'s own and is not applied again here — a second cut would
+ * mark the length of the first cut's output instead of the length the caller's
+ * text really had, which is the one thing the mark exists to state.
+ *
+ * Walked by index rather than with `Array.prototype.map`, which keeps a hole
+ * in a sparse array without visiting it: a hole is read as the `undefined` it
+ * is and refused like any other value that is not a message.
+ */
+function toStoredMessages(messages) {
+    const stored = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        try {
+            stored.push((0, messages_1.mapChatMessagesToStoredMessages)([messages[index]])[0]);
+        }
+        catch (error) {
+            throw (0, errors_1.validationError)(`messages[${index}] is not a LangChain message: ` + (0, secret_patterns_1.redactedMessage)(error), 'messages');
+        }
+    }
+    return stored;
+}
+/**
+ * Parse stored messages: prove each one rebuilds on the read side.
+ *
+ * Accepts: `stored` — the stored form of one call's messages. The check *is*
+ * the read side's own rebuild (`mapStoredMessagesToChatMessages`), so write and
+ * read agree by construction rather than by two lists of types kept in step by
+ * hand.
+ *
+ * Returns: `stored`, as {@link StorableMessages}.
+ *
+ * Throws: `VALIDATION` naming `messages`, carrying the offending index and
+ * type. The type comes off the caller's own object and nothing length-checked
+ * it, so the message names it bounded by {@link truncateForLog}, and so is
+ * what LangChain says about it — that text renders the same unchecked value
+ * into itself, so bounding only the type bounds nothing. The two take
+ * different caps because they are different things: the type is an identifier,
+ * while what LangChain threw is prose, cut once by `redactedMessage` and not
+ * again here. `context` still names `messages`, which is what a caller
+ * branches on. A `RemoveMessage`, or a tool, function or generic message
+ * missing its required field, is refused here instead of being persisted and
+ * then skipped or thrown by `getMessages`. A hole in a sparse array is refused
+ * as missing, naming its index: the array is walked by index, where
+ * `Array.prototype.forEach` would skip the hole and let it through.
+ */
+function parseStoredMessages(stored) {
+    for (let index = 0; index < stored.length; index += 1) {
+        const message = stored[index];
+        if (message === undefined) {
+            throw (0, errors_1.validationError)(`messages[${index}] is missing`, 'messages');
+        }
+        try {
+            (0, messages_1.mapStoredMessagesToChatMessages)([message]);
+        }
+        catch (error) {
+            throw (0, errors_1.validationError)(`messages[${index}] of type "${(0, truncate_1.truncateForLog)(message.type)}" cannot be stored: ` +
+                (0, secret_patterns_1.redactedMessage)(error), 'messages');
+        }
+    }
+    return stored;
+}
+/**
+ * Parse the messages of one append, in two passes: to the stored form, then
+ * proof that each rebuilds.
+ *
+ * Accepts: `messages` — declared `BaseMessage[]`; a non-array is refused, and
+ * so is an entry LangChain cannot serialize.
+ *
+ * Returns: a fresh array of stored messages, as {@link StorableMessages}.
+ *
+ * Throws: `VALIDATION` naming `messages`, with the offending index for an
+ * entry.
+ */
+function parseMessages(messages) {
+    if (!Array.isArray(messages)) {
+        throw (0, errors_1.validationError)('messages must be an array', 'messages');
+    }
+    return parseStoredMessages(toStoredMessages(messages));
+}
+/**
+ * A window's `before`, as a copy, when a message id can express it: the bound
+ * is the message id of that instant, and a message id holds its millisecond in
+ * ten base-32 characters.
+ *
+ * `null` is refused, naming `before`, rather than read as "up to now". A
+ * `Date` is duck-typed, since one from another realm is still a date.
+ * Unchecked, `before: null` would reach `null.getTime`, a property access the
+ * boundary brands `UNEXPECTED_ERROR` instead of naming the caller's mistake;
+ * an invalid `Date` would otherwise derive a NaN sort key that matches nothing
+ * and read as an empty conversation. A pre-epoch `Date` would be worse than
+ * either: the bound built from it sorts above every real id, so the window
+ * would come back holding the entire conversation the caller asked to exclude.
+ * Past the range the bound would wrap to the lowest prefix and the window would
+ * come back empty.
+ */
+function windowBound(before) {
+    const hasGetTime = before !== null && typeof before.getTime === 'function';
+    const time = hasGetTime ? before.getTime() : Number.NaN;
+    if (!Number.isFinite(time))
+        throw (0, errors_1.validationError)('before must be a valid Date', 'before');
+    if (time < 0 || time >= ulid_1.ULID_TIME_RANGE_MS) {
+        throw (0, errors_1.validationError)('before must be a Date from the epoch onwards and before the year 37648: the bound is ' +
+            'the message id of that instant, and a message id encodes its millisecond in ten ' +
+            'base-32 characters, which hold no instant outside that range', 'before');
+    }
+    return new Date(time);
+}
+/**
+ * Parse a conversation window.
+ *
+ * Accepts: `window.limit` — an integer from 1 to the page ceiling; the only
+ * floor of 1 in the package, because a window feeds a model, and an empty
+ * conversation is not a visibly empty answer but an invented one.
+ * `window.before` — a valid `Date` inside the range a message id can express.
+ *
+ * Returns: a fresh window holding only the keys the caller gave, as a
+ * {@link ParsedWindow}.
+ *
+ * Throws: `VALIDATION` naming `limit` or `before`.
+ */
+function parseMessageWindow(window) {
+    const parsed = {};
+    if (window.limit !== undefined)
+        parsed.limit = (0, primitives_1.parseLimit)(window.limit, 1);
+    if (window.before !== undefined)
+        parsed.before = windowBound(window.before);
+    return parsed;
+}
+/**
+ * Parse the arguments of `getMessages`.
+ *
+ * Accepts: `sessionId` — as {@link parseSessionId}. `options` — an object with
+ * only `limit`, `before` and `signal`; the window as {@link parseMessageWindow}.
+ *
+ * Returns: the request the read works from.
+ *
+ * Throws: `VALIDATION`, in this order: `options.<key>`, `signal`, `sessionId`,
+ * `limit`, `before`.
+ */
+function parseGetMessagesRequest(sessionId, options) {
+    (0, option_shape_1.assertShape)(options, setup_1.GET_MESSAGES_KEYS, 'options');
+    (0, collaborators_1.assertSignalLike)(options.signal);
+    const parsedSessionId = parseSessionId(sessionId);
+    return {
+        sessionId: parsedSessionId,
+        window: parseMessageWindow(options),
+        signal: options.signal,
+    };
+}
+/** A scan cap: absent and `Infinity` both mean none; anything else is an integer of at least 1. */
+function scanCap(value, field) {
+    if (value === undefined || value === Infinity)
+        return value;
+    return (0, primitives_1.parseInteger)(value, field, { min: 1 });
+}
+/**
+ * The paging cursor, which only the recency index can honour: without it a
+ * listing is one table scan, which has no position to resume from.
+ */
+function pageCursor(cursor, indexName) {
+    if (cursor === undefined)
+        return undefined;
+    if (indexName === undefined) {
+        throw (0, errors_1.validationError)('paging by cursor needs a configured `indexName`: without the recency index a listing is ' +
+            'one table scan, which has no position to resume from', 'cursor');
+    }
+    return (0, primitives_1.parseString)(cursor, 'cursor');
+}
+/**
+ * Parse the options of `listSessions`.
+ *
+ * Accepts: `options` — only `limit`, `cursor`, `maxIterations`, `maxItems` and
+ * `signal`. `limit` — 0 to the page ceiling; `0` is answered with an empty page.
+ * `maxItems`, `maxIterations` — an integer of at least 1, or `Infinity`.
+ * `cursor` — a string, and only with `indexName`. `indexName` — the adapter's
+ * configured recency index, if any.
+ *
+ * Returns: the request the listing works from.
+ *
+ * Throws: `VALIDATION`, in this order: `options.<key>`, `signal`, `limit`,
+ * `maxItems`, `maxIterations`, `cursor`.
+ */
+function parseListSessionsRequest(options, indexName) {
+    (0, option_shape_1.assertShape)(options, setup_1.LIST_SESSIONS_KEYS, 'options');
+    (0, collaborators_1.assertSignalLike)(options.signal);
+    const limit = options.limit === undefined ? undefined : (0, primitives_1.parseLimit)(options.limit, 0);
+    const maxItems = scanCap(options.maxItems, 'maxItems');
+    const maxIterations = scanCap(options.maxIterations, 'maxIterations');
+    return {
+        limit,
+        maxItems,
+        maxIterations,
+        cursor: pageCursor(options.cursor, indexName),
+        signal: options.signal,
+    };
+}