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

package/dist/history/actions/reconcile-count.d.ts

@@ -1,13 +1,45 @@
+/**
+ * Hides that repairing `messageCount` is the session row's own job.
+ *
+ * The public repair only parses the session id and hands it to the module
+ * that owns the count (record 22). The recount, the compare-and-swap on the
+ * value it read, and the retry when an append lands in between all live
+ * there, beside the append that keeps the count in step, so the repair and
+ * the append cannot come to disagree about what the count means.
+ */
 import type { HistoryContext } from '../internal/setup';
 /**
- * Recompute `messageCount` from the authoritative number of stored message items
- * and write it back, repairing any drift. A repair tool: the append path keeps
- * the count consistent transactionally, so this is only needed after external
- * corruption. Run it when the session is quiescent — it `SET`s the count, so a
- * concurrent append's increment could be clobbered. Requires the session to
- * already exist; reconciling a nonexistent session throws {@link ConflictError}
- * rather than creating a permanent, TTL-less metadata-only row. Returns the
- * reconciled count.
+ * Recompute `messageCount` from the number of stored message items and write it
+ * back, repairing drift. The append path keeps the count consistent
+ * transactionally, so this is only needed after external corruption.
+ *
+ * **Safe to run on a live session.** The count is written under a condition on
+ * the value the row held when the count was computed, so an append landing in
+ * between makes the write fail rather than clobber the increment; the tool then
+ * recounts and tries again. Writing it unconditionally — which is what this did
+ * — silently discarded concurrent appends on exactly the sessions an operator
+ * reaches for this tool to fix.
+ *
+ * Accepts: `sessionId` — validated, and an existing session: repairing one that
+ * does not exist would mean creating it. `signal` — aborts the reads.
+ *
+ * Returns: the count now stored, which is the number of messages a reader would
+ * see.
+ *
+ * Throws: `VALIDATION` naming `sessionId`; `CONDITION_CONFLICT` when the
+ * session does not exist — rather than creating a permanent, TTL-less
+ * metadata-only row — and when it stays too busy to settle within
+ * {@link OVERWRITE_CAS_MAX_ATTEMPTS} attempts; `FORMAT_UNSUPPORTED` for a
+ * message row a newer release wrote, and `VALIDATION` naming `message` for
+ * a row in the session's message key space that this adapter did not write,
+ * both of which `getMessages` refuses too — writing a count back for a session
+ * no read can open would repair nothing; whatever the reads and the write
+ * throw.
+ *
+ * Guarantees: safe on a live session. The write is pinned to the value the row
+ * held when the count was computed, so an append landing in between fails the
+ * write rather than clobbering its increment, and the tool recounts. Expired
+ * messages are not counted, so the repaired number agrees with what
+ * `getMessages` returns rather than with what the table still holds.
  */
-export declare function reconcileMessageCount(context: HistoryContext, sessionId: string): Promise<number>;
-//# sourceMappingURL=reconcile-count.d.ts.map
+export declare function reconcileMessageCount(context: HistoryContext, sessionId: string, signal?: AbortSignal): Promise<number>;

package/dist/history/actions/reconcile-count.js

@@ -1,51 +1,51 @@
 "use strict";
+/**
+ * Hides that repairing `messageCount` is the session row's own job.
+ *
+ * The public repair only parses the session id and hands it to the module
+ * that owns the count (record 22). The recount, the compare-and-swap on the
+ * value it read, and the retry when an append lands in between all live
+ * there, beside the append that keeps the count in step, so the repair and
+ * the append cannot come to disagree about what the count means.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reconcileMessageCount = reconcileMessageCount;
-const retry_1 = require("../../shared/dynamodb/retry");
-const errors_1 = require("../../shared/errors/errors");
-const keys_1 = require("../internal/keys");
-const query_1 = require("../internal/query");
-const validation_1 = require("../internal/validation");
-async function countMessages(context, sessionId) {
-    const base = (0, query_1.messageQuery)(context.tableName, sessionId);
-    let total = 0;
-    let startKey;
-    do {
-        const page = await (0, retry_1.withDynamoDBRetry)(() => context.client.query({ ...base, Select: 'COUNT', ExclusiveStartKey: startKey }));
-        total += page.Count ?? 0;
-        startKey = page.LastEvaluatedKey;
-    } while (startKey);
-    return total;
-}
+const parse_1 = require("../internal/parse");
+const session_1 = require("../internal/session");
 /**
- * Recompute `messageCount` from the authoritative number of stored message items
- * and write it back, repairing any drift. A repair tool: the append path keeps
- * the count consistent transactionally, so this is only needed after external
- * corruption. Run it when the session is quiescent — it `SET`s the count, so a
- * concurrent append's increment could be clobbered. Requires the session to
- * already exist; reconciling a nonexistent session throws {@link ConflictError}
- * rather than creating a permanent, TTL-less metadata-only row. Returns the
- * reconciled count.
+ * Recompute `messageCount` from the number of stored message items and write it
+ * back, repairing drift. The append path keeps the count consistent
+ * transactionally, so this is only needed after external corruption.
+ *
+ * **Safe to run on a live session.** The count is written under a condition on
+ * the value the row held when the count was computed, so an append landing in
+ * between makes the write fail rather than clobber the increment; the tool then
+ * recounts and tries again. Writing it unconditionally — which is what this did
+ * — silently discarded concurrent appends on exactly the sessions an operator
+ * reaches for this tool to fix.
+ *
+ * Accepts: `sessionId` — validated, and an existing session: repairing one that
+ * does not exist would mean creating it. `signal` — aborts the reads.
+ *
+ * Returns: the count now stored, which is the number of messages a reader would
+ * see.
+ *
+ * Throws: `VALIDATION` naming `sessionId`; `CONDITION_CONFLICT` when the
+ * session does not exist — rather than creating a permanent, TTL-less
+ * metadata-only row — and when it stays too busy to settle within
+ * {@link OVERWRITE_CAS_MAX_ATTEMPTS} attempts; `FORMAT_UNSUPPORTED` for a
+ * message row a newer release wrote, and `VALIDATION` naming `message` for
+ * a row in the session's message key space that this adapter did not write,
+ * both of which `getMessages` refuses too — writing a count back for a session
+ * no read can open would repair nothing; whatever the reads and the write
+ * throw.
+ *
+ * Guarantees: safe on a live session. The write is pinned to the value the row
+ * held when the count was computed, so an append landing in between fails the
+ * write rather than clobbering its increment, and the tool recounts. Expired
+ * messages are not counted, so the repaired number agrees with what
+ * `getMessages` returns rather than with what the table still holds.
  */
-async function reconcileMessageCount(context, sessionId) {
-    (0, validation_1.validateSessionId)(sessionId);
-    const count = await countMessages(context, sessionId);
-    try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.update({
-            TableName: context.tableName,
-            Key: { PK: (0, keys_1.sessionPartition)(sessionId), SK: keys_1.SESSION_SORT_KEY },
-            UpdateExpression: 'SET #count = :count',
-            ExpressionAttributeNames: { '#count': 'messageCount' },
-            ExpressionAttributeValues: { ':count': count },
-            ConditionExpression: 'attribute_exists(PK)',
-        }));
-    }
-    catch (error) {
-        if (error.name === 'ConditionalCheckFailedException') {
-            throw new errors_1.ConflictError(`Cannot reconcile messageCount: session "${sessionId}" does not exist`, error);
-        }
-        throw error;
-    }
-    return count;
+async function reconcileMessageCount(context, sessionId, signal) {
+    return (0, session_1.repairMessageCount)(context, (0, parse_1.parseSessionId)(sessionId), signal);
 }
-//# sourceMappingURL=reconcile-count.js.map

package/dist/history/chat-message-history.d.ts

@@ -1,48 +1,235 @@
+/**
+ * Hides that chat history is a set of actions behind one error boundary.
+ *
+ * The public class holds only what it resolved from its options and routes
+ * each read and write to the action that implements it, through
+ * `guardPublic`. Each asynchronous method is the error boundary, so no error
+ * but the library's own reaches a caller (record 13); the synchronous
+ * `destroy` and `forSession` are the exceptions — the latter is also the
+ * one route from it to LangChain's single-session history. Where an action
+ * lives, how it reads or writes, and which client or offloader it uses can
+ * change without touching this surface.
+ */
 import type { BaseMessage } from '@langchain/core/messages';
-import { DynamoDBSessionChatMessageHistory } from './session-adapter';
-import type { DynamoDBChatMessageHistoryOptions, SessionMetadata } from './types';
+import type { CancelOptions } from '../shared/options';
+import { type AdapterWindow, DynamoDBSessionChatMessageHistory } from './session-adapter';
+import type { DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionPage } from './types';
 /**
- * DynamoDB-backed multi-session chat history. Each message is its own item
- * (ordered by a monotonic ULID, compressed / S3-offloaded as needed) alongside a
- * per-session metadata item; every message in a session shares one uniform TTL.
- * Appends are O(1) and lock-free. Use {@link forSession} to get a single-session
- * LangChain adapter.
+ * DynamoDB-backed multi-session chat history. Each message is its own row,
+ * ordered by when it was appended, beside one metadata row per session, and
+ * every message in a session shares one TTL. An append costs the same however
+ * long the session is and takes no lock. Use {@link forSession} to get a
+ * single-session LangChain adapter. Every public method rejects only with this
+ * library's error.
  */
 export declare class DynamoDBChatMessageHistory {
     private readonly context;
-    private readonly ownsClient;
-    private readonly ddbClient;
+    private readonly shell;
+    /**
+     * Accepts: `options` — validated here, so a misconfiguration surfaces at
+     * construction rather than on the first request.
+     *
+     * Returns: an adapter that owns the client it built, or borrows the one it
+     * was given.
+     *
+     * Throws: `VALIDATION` naming the offending option.
+     *
+     * Guarantees: no I/O. Constructing the adapter issues no request.
+     */
     constructor(options: DynamoDBChatMessageHistoryOptions);
-    /** Get a session's messages in order. */
-    getMessages(sessionId: string): Promise<BaseMessage[]>;
-    /** Append messages to a session. */
-    addMessages(sessionId: string, messages: BaseMessage[]): Promise<void>;
-    /** Append a single message to a session. */
-    addMessage(sessionId: string, message: BaseMessage): Promise<void>;
-    /** Delete a session and any offloaded payload. */
-    clear(sessionId: string): Promise<void>;
-    /** List all sessions as metadata summaries. */
-    listSessions(options?: {
-        maxIterations?: number;
-        maxItems?: number;
-    }): Promise<SessionMetadata[]>;
+    /**
+     * Get a session's messages in chronological order.
+     *
+     * Accepts: `sessionId` — validated. `options.limit` — an integer from 1 to
+     * `MAX_PAGE_LIMIT` (10,000); only the newest that many messages. `0` is
+     * refused rather than answered with an empty conversation, which is the one
+     * place this package refuses a `limit` of zero. `options.before` — a valid
+     * `Date`; only messages appended before that instant. Neither given reads
+     * the whole session. `options.signal` — aborts the reads.
+     *
+     * Returns: the messages, oldest first. A session that does not exist and one
+     * whose messages have all expired both return nothing.
+     *
+     * Throws: `VALIDATION` for a malformed session id or window, an invalid
+     * `signal`, or naming `options.<key>` for a key this package does not read;
+     * `VALIDATION` naming `s3Key` for a row addressing an object outside the
+     * session's own path, and naming `message` for a row in this session's
+     * message key space that this adapter did not write, both whatever the
+     * corruption policy;
+     * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer release wrote;
+     * a classified AWS failure;
+     * `ABORTED`; and, under `onCorruptMessage: 'throw'`, the decode error of a
+     * corrupt row.
+     *
+     * Guarantees: strongly consistent, so the turn just appended is visible.
+     * Expired messages are filtered on read, so the history is never stale.
+     * @remarks One query page plus one S3 download per offloaded message.
+     */
+    getMessages(sessionId: string, options?: GetMessagesOptions): Promise<BaseMessage[]>;
+    /**
+     * Append messages to a session.
+     *
+     * Accepts: `sessionId` — validated. `messages` — LangChain messages; an empty
+     * list writes nothing and is not an error. `options.signal` — aborts between
+     * chunks.
+     *
+     * Returns: nothing, and only once every message has landed.
+     *
+     * Throws: `VALIDATION` naming `messages`, for a value that is not itself
+     * an array, or, with the offending index, for an element that is not a
+     * message or one that could never be read back; or naming `signal` or
+     * `options.<key>` for a key this package does not read;
+     * `COMPENSATION_FAILED` when a later chunk fails and the rollback fails
+     * too; `RETRY_EXHAUSTED` after 18 contended attempts; a classified AWS failure;
+     * `ABORTED`.
+     *
+     * Guarantees: a caller observes all messages or none. One transaction per
+     * chunk of up to 99 keeps `messageCount` exact. Lock-free and safe under
+     * concurrent appends to one session; every message shares the session's TTL
+     * when one is configured.
+     */
+    addMessages(sessionId: string, messages: BaseMessage[], options?: CancelOptions): Promise<void>;
+    /**
+     * Append one message.
+     *
+     * Accepts: as {@link addMessages}, for a single message.
+     *
+     * Returns: nothing.
+     *
+     * Throws: as {@link addMessages}.
+     */
+    addMessage(sessionId: string, message: BaseMessage, options?: CancelOptions): Promise<void>;
+    /**
+     * Delete a session's messages, metadata and offloaded objects.
+     *
+     * Accepts: `sessionId` — validated. `options.signal` — aborts between pages.
+     *
+     * Returns: nothing. Clearing a session that does not exist is not an error.
+     *
+     * Throws: `VALIDATION` for a malformed session id, an invalid `signal`,
+     * or an `options.<key>` this package does not read;
+     * `BATCH_WRITE_INCOMPLETE` when a row's delete fails, counting rows
+     * rather than batches; a classified AWS failure; `ABORTED` when the signal fires,
+     * which is what a cancel surfaces as rather than an incomplete delete, even
+     * when it fires part-way through the pass. A row refused because it
+     * was rewritten after the partition read raises nothing: it is left in place,
+     * reported at `warn`, and counted as skipped.
+     *
+     * Guarantees: a row this adapter did not write is left in place and logged,
+     * and neither is a row rewritten since the read — an append landing during
+     * the call moves the session row's own write id, so that row survives with
+     * the session it belongs to instead of being removed under a live
+     * conversation. Single pass: call it when the session is quiescent, since a
+     * message appended while it runs may survive it, and the surviving session
+     * row then over-counts until `reconcileMessageCount` repairs it.
+     */
+    clear(sessionId: string, options?: CancelOptions): Promise<void>;
+    /**
+     * List every session as a metadata summary, most recently updated first.
+     * With a configured `indexName` this reads each index shard newest-first,
+     * merges the shards and pages by the opaque `nextCursor`. Without one it
+     * falls back to a filtered table scan — cross-tenant by construction,
+     * bounded by `maxItems` / `maxIterations`, and returning the newest `limit`
+     * sessions, or every session when no limit is given, with no cursor.
+     *
+     * Accepts: `options.limit` — an integer from 0 to `MAX_PAGE_LIMIT` (10,000);
+     * the page size with the index, the newest N without it, and `0` an empty
+     * page read from neither. `options.cursor` — from a previous page,
+     * and only with a configured `indexName`. `options.maxItems` /
+     * `maxIterations` — caps on the scan path. `options.signal` — aborts the
+     * reads.
+     *
+     * Returns: the page and, while rows may remain, a `nextCursor`. A page may
+     * come back shorter than `limit` while more rows remain: expired and foreign
+     * rows are dropped after the read. A cursor does not promise more rows:
+     * DynamoDB can end a shard's page at its last row and still return a key to
+     * continue from, and the page after such a cursor can come back empty. Stop
+     * when `nextCursor` is absent, never when a page looks short.
+     *
+     * Throws: `VALIDATION` naming `limit`, `cursor`, `maxItems`,
+     * `maxIterations`, `signal`, or `options.<key>` for a key this package does
+     * not read; `RESULT_TRUNCATED` past either cap on the scan path, or for an
+     * index shard whose pages do not end; `FORMAT_UNSUPPORTED` for a session row
+     * a newer release wrote; a classified AWS failure; `ABORTED`.
+     *
+     * Guarantees: with a configured `indexName` each shard is read one DynamoDB
+     * page at a time, and its next page whenever it has no row buffered and the
+     * page still needs one, so a shard can cost a query whose rows the page never
+     * takes; at most `readConcurrency` shards are queried at once. Memory is the
+     * page being built, up to `limit` rows and so bounded by
+     * `MAX_PAGE_LIMIT` (10,000), plus at most one DynamoDB page per shard,
+     * whatever the table holds.
+     */
+    listSessions(options?: ListSessionsOptions): Promise<SessionPage>;
     /**
      * Recompute and repair a session's `messageCount` from the stored messages.
      * A maintenance tool for external corruption; run it when the session is idle.
+     *
+     * Accepts: `sessionId` — validated, and an existing session.
+     * `options.signal` — aborts the reads.
+     *
+     * Returns: the count now stored, which is the number of messages a reader
+     * would see.
+     *
+     * Throws: `VALIDATION` for a malformed session id, an invalid `signal`,
+     * or an `options.<key>` this package does not read; `CONDITION_CONFLICT` when the
+     * session does not exist or stayed busy through every attempt;
+     * `FORMAT_UNSUPPORTED` for a message row a newer release wrote, and
+     * `VALIDATION` naming `message` for a row in the session's message key
+     * space that this adapter did not write, both of which `getMessages` refuses
+     * too — a count is a repair only while it agrees with the read;
+     * a classified AWS failure; `ABORTED`.
+     *
+     * Guarantees: safe on a live session — the write is pinned to the value the
+     * row held when the count was computed, so a concurrent append makes it
+     * recount instead of clobbering the increment.
+     */
+    reconcileMessageCount(sessionId: string, options?: CancelOptions): Promise<number>;
+    /**
+     * Get a single-session LangChain adapter for `sessionId`.
+     *
+     * Accepts: `sessionId` — validated by the adapter's own constructor, the
+     * same rule every other method applies. `window.limit` — bounds what the
+     * adapter feeds the chain to the newest that many messages; validated the
+     * same way.
+     *
+     * Returns: an adapter implementing `BaseListChatMessageHistory`, which is
+     * what `RunnableWithMessageHistory` takes.
+     *
+     * Throws: `VALIDATION` naming `sessionId`, `window` for a window that is
+     * not an object, `window.<key>` for a key the adapter does not declare, or
+     * `limit` — raised by the constructed adapter, so a bad id or window fails
+     * here rather than on first use.
+     */
+    forSession(sessionId: string, window?: AdapterWindow): DynamoDBSessionChatMessageHistory;
+    /**
+     * Release owned resources.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Idempotent, and a no-op for a client the caller injected
+     * — that one is theirs to close.
+     *
+     * Throws: whatever a resource's own `destroy` raises — but only after every
+     * other one has been released, so a client that fails to close never strands
+     * the one behind it.
      */
-    reconcileMessageCount(sessionId: string): Promise<number>;
-    /** Get a single-session LangChain adapter for `sessionId`. */
-    forSession(sessionId: string): DynamoDBSessionChatMessageHistory;
-    /** Release owned resources (the underlying client and any S3 client). */
     destroy(): void;
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever.
+     *
+     * Accepts: nothing; the rule follows the configured `s3` and `ttl`. A no-op
+     * without both.
+     *
+     * Returns: nothing. Installing a rule that is already there is a no-op too.
+     *
+     * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
+     * a classified AWS failure when the bucket's lifecycle cannot be read or written.
+     * @remarks Requires the bucket-level `s3:GetLifecycleConfiguration` /
+     * `s3:PutLifecycleConfiguration` permissions, broader than the object-level
+     * CRUD the rest of S3 offload needs — call it once during provisioning, not
+     * per request.
      */
     ensureS3LifecycleRule(): Promise<void>;
 }
-//# sourceMappingURL=chat-message-history.d.ts.map