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

package/dist/esm/history/internal/parse.js

@@ -0,0 +1,105 @@
+import { mapChatMessagesToStoredMessages, mapStoredMessagesToChatMessages, } from '@langchain/core/messages';
+import { KEY_SEPARATOR, MAX_PARTITION_ID_BYTES } from '../../shared/dynamodb/table-schema.js';
+import { validationError } from '../../shared/errors/errors.js';
+import { redactedMessage } from '../../shared/logging/secret-patterns.js';
+import { truncateForLog } from '../../shared/logging/truncate.js';
+import { ULID_TIME_RANGE_MS } from '../../shared/ulid.js';
+import { assertSignalLike } from '../../shared/validation/collaborators.js';
+import { assertShape } from '../../shared/validation/option-shape.js';
+import { parseIdentifier, parseInteger, parseLimit, parseString, } from '../../shared/validation/primitives.js';
+import { GET_MESSAGES_KEYS, LIST_SESSIONS_KEYS } from './setup.js';
+export function parseSessionId(value) {
+    return parseIdentifier(value, KEY_SEPARATOR, 'sessionId', MAX_PARTITION_ID_BYTES);
+}
+function toStoredMessages(messages) {
+    const stored = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        try {
+            stored.push(mapChatMessagesToStoredMessages([messages[index]])[0]);
+        }
+        catch (error) {
+            throw validationError(`messages[${index}] is not a LangChain message: ` + redactedMessage(error), 'messages');
+        }
+    }
+    return stored;
+}
+export function parseStoredMessages(stored) {
+    for (let index = 0; index < stored.length; index += 1) {
+        const message = stored[index];
+        if (message === undefined) {
+            throw validationError(`messages[${index}] is missing`, 'messages');
+        }
+        try {
+            mapStoredMessagesToChatMessages([message]);
+        }
+        catch (error) {
+            throw validationError(`messages[${index}] of type "${truncateForLog(message.type)}" cannot be stored: ` +
+                redactedMessage(error), 'messages');
+        }
+    }
+    return stored;
+}
+export function parseMessages(messages) {
+    if (!Array.isArray(messages)) {
+        throw validationError('messages must be an array', 'messages');
+    }
+    return parseStoredMessages(toStoredMessages(messages));
+}
+function windowBound(before) {
+    const hasGetTime = before !== null && typeof before.getTime === 'function';
+    const time = hasGetTime ? before.getTime() : Number.NaN;
+    if (!Number.isFinite(time))
+        throw validationError('before must be a valid Date', 'before');
+    if (time < 0 || time >= ULID_TIME_RANGE_MS) {
+        throw 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);
+}
+export function parseMessageWindow(window) {
+    const parsed = {};
+    if (window.limit !== undefined)
+        parsed.limit = parseLimit(window.limit, 1);
+    if (window.before !== undefined)
+        parsed.before = windowBound(window.before);
+    return parsed;
+}
+export function parseGetMessagesRequest(sessionId, options) {
+    assertShape(options, GET_MESSAGES_KEYS, 'options');
+    assertSignalLike(options.signal);
+    const parsedSessionId = parseSessionId(sessionId);
+    return {
+        sessionId: parsedSessionId,
+        window: parseMessageWindow(options),
+        signal: options.signal,
+    };
+}
+function scanCap(value, field) {
+    if (value === undefined || value === Infinity)
+        return value;
+    return parseInteger(value, field, { min: 1 });
+}
+function pageCursor(cursor, indexName) {
+    if (cursor === undefined)
+        return undefined;
+    if (indexName === undefined) {
+        throw 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 parseString(cursor, 'cursor');
+}
+export function parseListSessionsRequest(options, indexName) {
+    assertShape(options, LIST_SESSIONS_KEYS, 'options');
+    assertSignalLike(options.signal);
+    const limit = options.limit === undefined ? undefined : 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,
+    };
+}

package/dist/{history/internal/rows.js → esm/history/internal/rows.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides the history's key layout and how a message becomes a row and back.
  *
@@ -9,39 +8,15 @@
  * the SESSION row carries is `session.ts`'s decision; where it lives is this
  * module's.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_SORT_KEY = void 0;
-exports.historyPartitionPrefix = historyPartitionPrefix;
-exports.sessionPartition = sessionPartition;
-exports.sessionRowKey = sessionRowKey;
-exports.messageSortKey = messageSortKey;
-exports.isHistorySortKey = isHistorySortKey;
-exports.messageSortKeyPrefix = messageSortKeyPrefix;
-exports.sessionRowsQuery = sessionRowsQuery;
-exports.messageQuery = messageQuery;
-exports.buildMessageRow = buildMessageRow;
-exports.parseMessageRow = parseMessageRow;
-const codec_1 = require("../../shared/codec/codec");
-const table_schema_1 = require("../../shared/dynamodb/table-schema");
-/**
- * Row-kind tag distinguishing this adapter's sort keys from another
- * adapter's on a table shared via `DynamoDBFactory.createAll()` — matches the
- * pattern the checkpointer module already uses for its own META#/PAYLOAD#/
- * WRITE# keys. Without it, `SESSION_SORT_KEY` alone was a bare, common-word
- * literal a store caller could produce by accident (e.g.
- * `store.put([sessionId], 'SESSION', ...)`, since `sortKey` collapses a
- * single-element namespace down to just the key).
- */
-const ADAPTER_PREFIX = `HISTORY${table_schema_1.KEY_SEPARATOR}`;
+import type { QueryCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { StoredMessage } from '@langchain/core/messages';
+import { type PayloadDescriptor } from '../../shared/codec/codec.js';
+import type { AttributeMap } from '../../shared/dynamodb/client.js';
+import { type RowKey } from '../../shared/dynamodb/table-schema.js';
+import type { SessionId } from './parse.js';
+import type { HistoryContext } from './setup.js';
 /** Fixed sort key for the per-session metadata item. */
-exports.SESSION_SORT_KEY = `${ADAPTER_PREFIX}SESSION`;
-const MESSAGE_PREFIX = `${ADAPTER_PREFIX}MSG#`;
-/**
- * Adapter tag prefixed to every chat-history partition key — see the
- * equivalent in checkpointer/internal/rows.ts for why the three adapters'
- * partitions must not overlap on a shared table.
- */
-const ADAPTER_PARTITION_PREFIX = `${table_schema_1.ADAPTER_TAGS.history}${table_schema_1.KEY_SEPARATOR}`;
+export declare const SESSION_SORT_KEY = "HISTORY#SESSION";
 /**
  * The tag every chat-history partition key starts with.
  *
@@ -52,9 +27,7 @@ const ADAPTER_PARTITION_PREFIX = `${table_schema_1.ADAPTER_TAGS.history}${table_
  *
  * Throws: nothing.
  */
-function historyPartitionPrefix() {
-    return ADAPTER_PARTITION_PREFIX;
-}
+export declare function historyPartitionPrefix(): string;
 /**
  * Partition key for a chat session: the adapter tag plus the session id.
  *
@@ -66,9 +39,7 @@ function historyPartitionPrefix() {
  *
  * Throws: nothing.
  */
-function sessionPartition(sessionId) {
-    return `${ADAPTER_PARTITION_PREFIX}${sessionId}`;
-}
+export declare function sessionPartition(sessionId: string): string;
 /**
  * The key of a session's SESSION row.
  *
@@ -78,9 +49,7 @@ function sessionPartition(sessionId) {
  *
  * Throws: nothing.
  */
-function sessionRowKey(sessionId) {
-    return { PK: sessionPartition(sessionId), SK: exports.SESSION_SORT_KEY };
-}
+export declare function sessionRowKey(sessionId: string): RowKey;
 /**
  * Sort key for a single message item.
  *
@@ -92,9 +61,7 @@ function sessionRowKey(sessionId) {
  *
  * Throws: nothing.
  */
-function messageSortKey(ulid) {
-    return `${MESSAGE_PREFIX}${ulid}`;
-}
+export declare function messageSortKey(ulid: string): string;
 /**
  * Whether `sortKey` is one this adapter writes.
  *
@@ -106,9 +73,7 @@ function messageSortKey(ulid) {
  *
  * Throws: nothing.
  */
-function isHistorySortKey(sortKey) {
-    return sortKey.startsWith(ADAPTER_PREFIX);
-}
+export declare function isHistorySortKey(sortKey: string): boolean;
 /**
  * `begins_with` prefix selecting every message item in a session.
  *
@@ -120,8 +85,10 @@ function isHistorySortKey(sortKey) {
  *
  * Throws: nothing.
  */
-function messageSortKeyPrefix() {
-    return MESSAGE_PREFIX;
+export declare function messageSortKeyPrefix(): string;
+/** Options for {@link sessionRowsQuery}. */
+export interface SessionRowsQueryOptions {
+    consistent?: boolean;
 }
 /**
  * Query input selecting every row in a session's partition.
@@ -134,16 +101,20 @@ function messageSortKeyPrefix() {
  *
  * Throws: nothing.
  */
-function sessionRowsQuery(tableName, sessionId, options = {}) {
-    const params = {
-        TableName: tableName,
-        KeyConditionExpression: '#pk = :pk',
-        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE },
-        ExpressionAttributeValues: { ':pk': sessionPartition(sessionId) },
-    };
-    if (options.consistent)
-        params.ConsistentRead = true;
-    return params;
+export declare function sessionRowsQuery(tableName: string, sessionId: SessionId, options?: SessionRowsQueryOptions): QueryCommandInput;
+/** Options for {@link messageQuery}. */
+export interface MessageQueryOptions extends SessionRowsQueryOptions {
+    /** Walk the messages newest-first; the caller restores chronological order. */
+    descending?: boolean;
+    /** Cap the rows DynamoDB evaluates per page. */
+    limit?: number;
+    /**
+     * Exclusive upper sort-key bound. Expressed as `BETWEEN prefix AND bound`
+     * because a key condition allows one sort-key operator: the bound is the
+     * message prefix plus the ULID time characters of an instant, so every
+     * real message key from that millisecond onwards sorts strictly after it.
+     */
+    beforeSortKey?: string;
 }
 /**
  * Query input selecting a session's message items.
@@ -158,26 +129,25 @@ function sessionRowsQuery(tableName, sessionId, options = {}) {
  *
  * Throws: nothing.
  */
-function messageQuery(tableName, sessionId, options = {}) {
-    const params = {
-        TableName: tableName,
-        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
-        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_1.SORT_KEY_ATTRIBUTE },
-        ExpressionAttributeValues: {
-            ':pk': sessionPartition(sessionId),
-            ':skp': messageSortKeyPrefix(),
-        },
-        ScanIndexForward: !options.descending,
-    };
-    if (options.beforeSortKey !== undefined) {
-        params.KeyConditionExpression = '#pk = :pk AND #sk BETWEEN :skp AND :before';
-        params.ExpressionAttributeValues[':before'] = options.beforeSortKey;
-    }
-    if (options.limit !== undefined)
-        params.Limit = options.limit;
-    if (options.consistent)
-        params.ConsistentRead = true;
-    return params;
+export declare function messageQuery(tableName: string, sessionId: SessionId, options?: MessageQueryOptions): QueryCommandInput;
+/** A single stored chat message row (one per message, ordered by its ULID). */
+export interface MessageRow {
+    PK: string;
+    SK: string;
+    /** Row format version; absent on rows written before it existed (see `table-schema.ts`). */
+    v?: number;
+    sessionId: string;
+    message: PayloadDescriptor;
+    ttl?: number;
+}
+/** One message as the row it becomes. */
+export interface MessageRowSource {
+    readonly sessionId: SessionId;
+    /** The message's own ULID: its sort key and the id its offloaded object is written under. */
+    readonly messageId: string;
+    readonly message: StoredMessage;
+    /** When the row expires; absent when the adapter has no ttl. */
+    readonly ttlTimestamp?: number;
 }
 /**
  * Encode a single stored message into its DynamoDB row.
@@ -191,35 +161,17 @@ function messageQuery(tableName, sessionId, options = {}) {
  * than losing its oldest turns first. `signal` — cancels the upload an
  * offloaded message costs.
  *
- * Returns: the row, keyed by the session partition and a `MSG#<messageId>` sort
- * key, its payload inline or offloaded to
+ * Returns: the row, keyed by the session partition and a
+ * `HISTORY#MSG#<messageId>` sort key, its payload inline or offloaded to
  * `<keyPrefix><sessionId, base64url>/<messageId>.bin`.
  *
  * Throws: `VALIDATION` naming `value` for a message the serializer cannot
- * represent; `S3_OFFLOAD_FAILED` when an offloaded payload cannot be uploaded.
- * Encoding precedes the transaction, so a message that cannot be stored never
- * half-writes a turn.
+ * represent, or `payload` for one too large to store inline without `s3`,
+ * or, once offloaded, larger than `s3.maxDownloadBytes`; `S3_OFFLOAD_FAILED`
+ * when an offloaded payload cannot be uploaded. Encoding precedes the
+ * transaction, so a message that cannot be stored never half-writes a turn.
  */
-async function buildMessageRow(context, source, signal) {
-    const { sessionId, messageId, message, ttlTimestamp } = source;
-    const pk = sessionPartition(sessionId);
-    const sk = messageSortKey(messageId);
-    const descriptor = await (0, codec_1.encodePayload)(message, (0, codec_1.codecDepsOf)(context, signal), {
-        keyParts: [sessionId],
-        objectId: messageId,
-        row: { pk, sk },
-    });
-    const item = {
-        PK: pk,
-        SK: sk,
-        v: table_schema_1.ROW_FORMAT_VERSION,
-        sessionId,
-        message: descriptor,
-    };
-    if (ttlTimestamp !== undefined)
-        item.ttl = ttlTimestamp;
-    return item;
-}
+export declare function buildMessageRow(context: HistoryContext, source: MessageRowSource, signal?: AbortSignal): Promise<MessageRow>;
 /**
  * Narrow a raw row to a {@link MessageRow}.
  *
@@ -241,10 +193,4 @@ async function buildMessageRow(context, source, signal) {
  * Guarantees: a row's attributes are bound to the partition it lives in, so a
  * row planted under one session cannot claim to belong to another.
  */
-function parseMessageRow(raw) {
-    const shaped = typeof raw.sessionId === 'string' && typeof raw.message === 'object' && raw.message !== null;
-    if (!shaped)
-        return undefined;
-    const item = raw;
-    return item.PK === sessionPartition(item.sessionId) ? item : undefined;
-}
+export declare function parseMessageRow(raw: AttributeMap): MessageRow | undefined;

package/dist/esm/history/internal/rows.js

@@ -0,0 +1,83 @@
+import { codecDepsOf, encodePayload } from '../../shared/codec/codec.js';
+import { ADAPTER_TAGS, KEY_SEPARATOR, PARTITION_KEY_ATTRIBUTE, ROW_FORMAT_VERSION, SORT_KEY_ATTRIBUTE, } from '../../shared/dynamodb/table-schema.js';
+const ADAPTER_PREFIX = `HISTORY${KEY_SEPARATOR}`;
+export const SESSION_SORT_KEY = `${ADAPTER_PREFIX}SESSION`;
+const MESSAGE_PREFIX = `${ADAPTER_PREFIX}MSG${KEY_SEPARATOR}`;
+const ADAPTER_PARTITION_PREFIX = `${ADAPTER_TAGS.history}${KEY_SEPARATOR}`;
+export function historyPartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+export function sessionPartition(sessionId) {
+    return `${ADAPTER_PARTITION_PREFIX}${sessionId}`;
+}
+export function sessionRowKey(sessionId) {
+    return { PK: sessionPartition(sessionId), SK: SESSION_SORT_KEY };
+}
+export function messageSortKey(ulid) {
+    return `${MESSAGE_PREFIX}${ulid}`;
+}
+export function isHistorySortKey(sortKey) {
+    return sortKey.startsWith(ADAPTER_PREFIX);
+}
+export function messageSortKeyPrefix() {
+    return MESSAGE_PREFIX;
+}
+export function sessionRowsQuery(tableName, sessionId, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk',
+        ExpressionAttributeNames: { '#pk': PARTITION_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': sessionPartition(sessionId) },
+    };
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+export function messageQuery(tableName, sessionId, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
+        ExpressionAttributeNames: { '#pk': PARTITION_KEY_ATTRIBUTE, '#sk': SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: {
+            ':pk': sessionPartition(sessionId),
+            ':skp': messageSortKeyPrefix(),
+        },
+        ScanIndexForward: !options.descending,
+    };
+    if (options.beforeSortKey !== undefined) {
+        params.KeyConditionExpression = '#pk = :pk AND #sk BETWEEN :skp AND :before';
+        params.ExpressionAttributeValues[':before'] = options.beforeSortKey;
+    }
+    if (options.limit !== undefined)
+        params.Limit = options.limit;
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+export async function buildMessageRow(context, source, signal) {
+    const { sessionId, messageId, message, ttlTimestamp } = source;
+    const pk = sessionPartition(sessionId);
+    const sk = messageSortKey(messageId);
+    const descriptor = await encodePayload(message, codecDepsOf(context, signal), {
+        keyParts: [sessionId],
+        objectId: messageId,
+        row: { pk, sk },
+    });
+    const item = {
+        PK: pk,
+        SK: sk,
+        v: ROW_FORMAT_VERSION,
+        sessionId,
+        message: descriptor,
+    };
+    if (ttlTimestamp !== undefined)
+        item.ttl = ttlTimestamp;
+    return item;
+}
+export function parseMessageRow(raw) {
+    const shaped = typeof raw.sessionId === 'string' && typeof raw.message === 'object' && raw.message !== null;
+    if (!shaped)
+        return undefined;
+    const item = raw;
+    return item.PK === sessionPartition(item.sessionId) ? item : undefined;
+}