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

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

@@ -0,0 +1,113 @@
+"use strict";
+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_js_1 = require("../../shared/dynamodb/table-schema.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const secret_patterns_js_1 = require("../../shared/logging/secret-patterns.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const ulid_js_1 = require("../../shared/ulid.js");
+const collaborators_js_1 = require("../../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+const primitives_js_1 = require("../../shared/validation/primitives.js");
+const setup_js_1 = require("./setup.js");
+function parseSessionId(value) {
+    return (0, primitives_js_1.parseIdentifier)(value, table_schema_js_1.KEY_SEPARATOR, 'sessionId', table_schema_js_1.MAX_PARTITION_ID_BYTES);
+}
+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_js_1.validationError)(`messages[${index}] is not a LangChain message: ` + (0, secret_patterns_js_1.redactedMessage)(error), 'messages');
+        }
+    }
+    return stored;
+}
+function parseStoredMessages(stored) {
+    for (let index = 0; index < stored.length; index += 1) {
+        const message = stored[index];
+        if (message === undefined) {
+            throw (0, errors_js_1.validationError)(`messages[${index}] is missing`, 'messages');
+        }
+        try {
+            (0, messages_1.mapStoredMessagesToChatMessages)([message]);
+        }
+        catch (error) {
+            throw (0, errors_js_1.validationError)(`messages[${index}] of type "${(0, truncate_js_1.truncateForLog)(message.type)}" cannot be stored: ` +
+                (0, secret_patterns_js_1.redactedMessage)(error), 'messages');
+        }
+    }
+    return stored;
+}
+function parseMessages(messages) {
+    if (!Array.isArray(messages)) {
+        throw (0, errors_js_1.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 (0, errors_js_1.validationError)('before must be a valid Date', 'before');
+    if (time < 0 || time >= ulid_js_1.ULID_TIME_RANGE_MS) {
+        throw (0, errors_js_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);
+}
+function parseMessageWindow(window) {
+    const parsed = {};
+    if (window.limit !== undefined)
+        parsed.limit = (0, primitives_js_1.parseLimit)(window.limit, 1);
+    if (window.before !== undefined)
+        parsed.before = windowBound(window.before);
+    return parsed;
+}
+function parseGetMessagesRequest(sessionId, options) {
+    (0, option_shape_js_1.assertShape)(options, setup_js_1.GET_MESSAGES_KEYS, 'options');
+    (0, collaborators_js_1.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 (0, primitives_js_1.parseInteger)(value, field, { min: 1 });
+}
+function pageCursor(cursor, indexName) {
+    if (cursor === undefined)
+        return undefined;
+    if (indexName === undefined) {
+        throw (0, errors_js_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_js_1.parseString)(cursor, 'cursor');
+}
+function parseListSessionsRequest(options, indexName) {
+    (0, option_shape_js_1.assertShape)(options, setup_js_1.LIST_SESSIONS_KEYS, 'options');
+    (0, collaborators_js_1.assertSignalLike)(options.signal);
+    const limit = options.limit === undefined ? undefined : (0, primitives_js_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,
+    };
+}

package/dist/cjs/history/internal/rows.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Hides the history's key layout and how a message becomes a row and back.
+ *
+ * A session is one partition: a SESSION row with a fixed sort key, and one
+ * message row per message, sorted by its ULID so a range query reads a window
+ * in order. How those keys are composed, how a session's rows are queried, and
+ * which rows a read admits as this adapter's messages are decided here. What
+ * the SESSION row carries is `session.ts`'s decision; where it lives is this
+ * module's.
+ */
+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. */
+export declare const SESSION_SORT_KEY = "HISTORY#SESSION";
+/**
+ * The tag every chat-history partition key starts with.
+ *
+ * Accepts: nothing — the tag is fixed, and the function exists so no caller
+ * composes it by hand.
+ *
+ * Returns: the tag, for a table-wide `begins_with` over this adapter's rows.
+ *
+ * Throws: nothing.
+ */
+export declare function historyPartitionPrefix(): string;
+/**
+ * Partition key for a chat session: the adapter tag plus the session id.
+ *
+ * Accepts: `sessionId` — normally validated, so it cannot contain the
+ * separator and the key is unambiguous.
+ *
+ * Returns: the partition key. A whole session lives in one partition, which is
+ * what makes a session read one Query and a session delete one partition walk.
+ *
+ * Throws: nothing.
+ */
+export declare function sessionPartition(sessionId: string): string;
+/**
+ * The key of a session's SESSION row.
+ *
+ * Accepts: `sessionId` — the session's id, parsed, or read off the row.
+ *
+ * Returns: the row's partition and its fixed sort key.
+ *
+ * Throws: nothing.
+ */
+export declare function sessionRowKey(sessionId: string): RowKey;
+/**
+ * Sort key for a single message item.
+ *
+ * Accepts: `ulid` — a monotonic ULID, or the time-prefix of one when the caller
+ * is building a range bound rather than a key.
+ *
+ * Returns: the sort key. ULIDs sort lexicographically in time order, so the
+ * sort key *is* the chronological order; nothing re-sorts messages on read.
+ *
+ * Throws: nothing.
+ */
+export declare function messageSortKey(ulid: string): string;
+/**
+ * Whether `sortKey` is one this adapter writes.
+ *
+ * Accepts: any sort key read from the session's partition.
+ *
+ * Returns: whether this adapter owns the row. A partition query carries no
+ * sort-key condition, so a partition-wide delete uses this to leave a row it
+ * does not own in place rather than deleting the whole partition blindly.
+ *
+ * Throws: nothing.
+ */
+export declare function isHistorySortKey(sortKey: string): boolean;
+/**
+ * `begins_with` prefix selecting every message item in a session.
+ *
+ * Accepts: nothing — the prefix is the same for every session, because the
+ * session is already the partition.
+ *
+ * Returns: the prefix, which excludes the SESSION metadata row: that row shares
+ * the partition but is not a message.
+ *
+ * Throws: nothing.
+ */
+export declare function messageSortKeyPrefix(): string;
+/** Options for {@link sessionRowsQuery}. */
+export interface SessionRowsQueryOptions {
+    consistent?: boolean;
+}
+/**
+ * Query input selecting every row in a session's partition.
+ *
+ * Accepts: `options.consistent` — for a read whose answer a write depends on.
+ *
+ * Returns: the Query input, with no sort-key condition: it selects the
+ * messages, the SESSION metadata row, and any row another adapter left in this
+ * partition — which is why every caller filters with `isHistorySortKey`.
+ *
+ * Throws: nothing.
+ */
+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.
+ *
+ * Accepts: `options.descending` — newest-first, which is how a tail window is
+ * read. `options.limit` — the rows DynamoDB evaluates per page, not a total.
+ * `options.beforeSortKey` — an upper bound, expressed as `BETWEEN prefix AND
+ * bound` because a key condition allows one sort-key operator.
+ *
+ * Returns: the Query input, selecting messages only — the SESSION row does not
+ * carry the message prefix.
+ *
+ * Throws: nothing.
+ */
+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.
+ *
+ * Accepts: `source.sessionId` — the session the message belongs to.
+ * `source.messageId` — the message's own id, which orders it and names its
+ * offloaded object; the caller allocates one per message from a monotonic
+ * factory. `source.message` — the message in its stored form.
+ * `source.ttlTimestamp` — the uniform whole-conversation expiry every
+ * message in the session shares, so a conversation expires as one thing rather
+ * than losing its oldest turns first. `signal` — cancels the upload an
+ * offloaded message costs.
+ *
+ * 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, 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.
+ */
+export declare function buildMessageRow(context: HistoryContext, source: MessageRowSource, signal?: AbortSignal): Promise<MessageRow>;
+/**
+ * Narrow a raw row to a {@link MessageRow}.
+ *
+ * Accepts: `raw` — any row read from a session's partition under the message
+ * sort-key prefix, which on a shared table another writer can produce too.
+ *
+ * Returns: the item, or undefined for a row that merely shares the prefix —
+ * one carrying no `sessionId`, no `message` descriptor, or a `sessionId` that
+ * disagrees with the partition it was found in. The test is on the attributes
+ * a message must have, not on a cast: this is the one boundary where a row may
+ * not have been written by this adapter, so the key it was found at is not
+ * trusted on its own. A `message` of `null` is refused here, as
+ * `parseMetaRow` refuses a `metadata` of `null`.
+ *
+ * Throws: nothing; a row a newer release wrote is the caller's to refuse,
+ * before the shape is judged against attribute types that release may no
+ * longer use.
+ *
+ * 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.
+ */
+export declare function parseMessageRow(raw: AttributeMap): MessageRow | undefined;

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

@@ -0,0 +1,96 @@
+"use strict";
+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_js_1 = require("../../shared/codec/codec.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const ADAPTER_PREFIX = `HISTORY${table_schema_js_1.KEY_SEPARATOR}`;
+exports.SESSION_SORT_KEY = `${ADAPTER_PREFIX}SESSION`;
+const MESSAGE_PREFIX = `${ADAPTER_PREFIX}MSG${table_schema_js_1.KEY_SEPARATOR}`;
+const ADAPTER_PARTITION_PREFIX = `${table_schema_js_1.ADAPTER_TAGS.history}${table_schema_js_1.KEY_SEPARATOR}`;
+function historyPartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+function sessionPartition(sessionId) {
+    return `${ADAPTER_PARTITION_PREFIX}${sessionId}`;
+}
+function sessionRowKey(sessionId) {
+    return { PK: sessionPartition(sessionId), SK: exports.SESSION_SORT_KEY };
+}
+function messageSortKey(ulid) {
+    return `${MESSAGE_PREFIX}${ulid}`;
+}
+function isHistorySortKey(sortKey) {
+    return sortKey.startsWith(ADAPTER_PREFIX);
+}
+function messageSortKeyPrefix() {
+    return MESSAGE_PREFIX;
+}
+function sessionRowsQuery(tableName, sessionId, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': sessionPartition(sessionId) },
+    };
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+function messageQuery(tableName, sessionId, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_js_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;
+}
+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_js_1.encodePayload)(message, (0, codec_js_1.codecDepsOf)(context, signal), {
+        keyParts: [sessionId],
+        objectId: messageId,
+        row: { pk, sk },
+    });
+    const item = {
+        PK: pk,
+        SK: sk,
+        v: table_schema_js_1.ROW_FORMAT_VERSION,
+        sessionId,
+        message: descriptor,
+    };
+    if (ttlTimestamp !== undefined)
+        item.ttl = ttlTimestamp;
+    return item;
+}
+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;
+}