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

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

@@ -0,0 +1,195 @@
+/**
+ * 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';
+import type { AttributeMap } from '../../shared/dynamodb/client';
+import { type RowKey } from '../../shared/dynamodb/table-schema';
+import type { SessionId } from './parse';
+import type { HistoryContext } from './setup';
+/** 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 `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.
+ */
+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/history/internal/rows.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * 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.
+ */
+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}`;
+/** 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}`;
+/**
+ * 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.
+ */
+function historyPartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+/**
+ * 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.
+ */
+function sessionPartition(sessionId) {
+    return `${ADAPTER_PARTITION_PREFIX}${sessionId}`;
+}
+/**
+ * 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.
+ */
+function sessionRowKey(sessionId) {
+    return { PK: sessionPartition(sessionId), SK: exports.SESSION_SORT_KEY };
+}
+/**
+ * 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.
+ */
+function messageSortKey(ulid) {
+    return `${MESSAGE_PREFIX}${ulid}`;
+}
+/**
+ * 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.
+ */
+function isHistorySortKey(sortKey) {
+    return sortKey.startsWith(ADAPTER_PREFIX);
+}
+/**
+ * `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.
+ */
+function messageSortKeyPrefix() {
+    return MESSAGE_PREFIX;
+}
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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 `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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+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;
+}