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

package/dist/history/internal/setup.js

@@ -1,106 +0,0 @@
-"use strict";
-/**
- * Hides which options the history and its methods accept, and how the history
- * is assembled from them.
- *
- * The exhaustive key list of every option bag — the constructor's,
- * `getMessages`', `listSessions`' — lives here, compiler-checked against its
- * type, beside the code that resolves the constructor's options into the
- * context every action receives.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_SESSIONS_KEYS = exports.GET_MESSAGES_KEYS = exports.HISTORY_KEYS = exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = void 0;
-exports.setUpHistory = setUpHistory;
-const adapter_1 = require("../../shared/adapter");
-const json_serde_1 = require("../../shared/codec/json-serde");
-const errors_1 = require("../../shared/errors/errors");
-const ulid_1 = require("../../shared/ulid");
-const option_shape_1 = require("../../shared/validation/option-shape");
-/**
- * Max attempts for the message-append transaction. It shares one session's
- * metadata row across every concurrent `addMessages` caller on that session,
- * so a burst of concurrent appends can collide repeatedly; combined with the
- * existing 100ms base / 5000ms cap backoff, this keeps worst-case retrying
- * within AWS's documented guidance to bound conflict retries to "around one
- * minute" (see DynamoDB's "Error retries and exponential backoff" guide).
- * This bound is exact for clients this library constructs, which disable the
- * AWS SDK's own internal retries (`maxAttempts: 1`, see
- * `resolveDynamoDBClient`). An injected client that keeps SDK retries stacks
- * them inside each attempt; construction warns about that.
- */
-exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
-/**
- * The keys of each chat-history option bag, exhaustive in both directions:
- * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
- * cannot rot away from the type it guards. They live with the feature because
- * the types they are checked against do; `shared/` knows no feature.
- */
-exports.HISTORY_KEYS = (0, option_shape_1.allKeysOf)({
-    tableName: 'tableName',
-    client: 'client',
-    clientConfig: 'clientConfig',
-    createClient: 'createClient',
-    ttl: 'ttl',
-    logger: 'logger',
-    retry: 'retry',
-    indexShards: 'indexShards',
-    indexName: 'indexName',
-    readConcurrency: 'readConcurrency',
-    compression: 'compression',
-    s3: 's3',
-    serde: 'serde',
-    onCorruptMessage: 'onCorruptMessage',
-});
-/** See {@link HISTORY_KEYS}. */
-exports.GET_MESSAGES_KEYS = (0, option_shape_1.allKeysOf)({
-    limit: 'limit',
-    before: 'before',
-    signal: 'signal',
-});
-/** See {@link HISTORY_KEYS}. */
-exports.LIST_SESSIONS_KEYS = (0, option_shape_1.allKeysOf)({
-    limit: 'limit',
-    cursor: 'cursor',
-    maxIterations: 'maxIterations',
-    maxItems: 'maxItems',
-    signal: 'signal',
-});
-const CORRUPT_MESSAGE_POLICIES = ['skip', 'throw'];
-/** Reject an `onCorruptMessage` outside its union; see {@link setUpHistory} for why. */
-function assertCorruptMessagePolicy(policy) {
-    if (policy !== undefined && !CORRUPT_MESSAGE_POLICIES.includes(policy)) {
-        throw (0, errors_1.validationError)(`onCorruptMessage must be one of ${CORRUPT_MESSAGE_POLICIES.join(' | ')}`, 'onCorruptMessage');
-    }
-}
-/**
- * Validate the options, then resolve the client, offloader and serializer.
- *
- * Accepts: `options` — validated first, so no half-built adapter exists when
- * one is wrong. `onCorruptMessage` is checked against its union here because a
- * JavaScript caller can pass a string the type never admits, and an
- * unrecognised policy would silently behave as `'skip'` — dropping messages a
- * caller asked to be told about.
- *
- * Returns: the context every action shares, and the shell that releases what
- * it holds — a client the caller passed in is never destroyed by `destroy()`.
- *
- * Throws: `VALIDATION` naming the offending option.
- *
- * Guarantees: constructing an adapter performs no I/O.
- */
-function setUpHistory(options) {
-    (0, option_shape_1.assertShape)(options, exports.HISTORY_KEYS, 'options');
-    const shell = (0, adapter_1.openAdapter)(options, 'history', {
-        options: () => assertCorruptMessagePolicy(options.onCorruptMessage),
-        attemptFloor: exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS,
-    });
-    return {
-        shell,
-        context: {
-            ...shell.core,
-            serde: options.serde ?? json_serde_1.JSON_SERDE,
-            ulid: (0, ulid_1.createUlidFactory)(),
-            onCorruptMessage: options.onCorruptMessage ?? 'skip',
-        },
-    };
-}

package/dist/history/types.js

@@ -1,12 +0,0 @@
-"use strict";
-/**
- * Hides the history's implementation from the types a caller names.
- *
- * Every option and result of the multi-session history's reads, writes and
- * listings is declared here, with no run-time code, so a caller can type
- * what it builds without importing an action, a parser or a row module. The
- * parsed forms the actions work from belong to the parser and the row
- * shapes to the modules that own them, so either can change without moving
- * a published type.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.js

@@ -1,51 +0,0 @@
-"use strict";
-/**
- * AWS DynamoDB implementation of LangGraph's checkpoint saver, memory store
- * and chat message history, in TypeScript.
- *
- * Hides where anything lives.
- *
- * This module re-exports and declares nothing of its own, so which module
- * holds an adapter, the factory, the error class, the serializer or a
- * collaborator type is free to change without moving anything a caller
- * imports. What appears here is the whole supported surface; the package's
- * exports map admits no deep import, so nothing else is reachable.
- *
- * @packageDocumentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.redactSecrets = exports.redactLogger = exports.ErrorCode = exports.isDynamoDBLangGraphError = exports.DynamoDBLangGraphError = exports.JSON_SERDE = exports.DynamoDBFactory = exports.backfillRecencyIndex = exports.DynamoDBSessionChatMessageHistory = exports.DynamoDBChatMessageHistory = exports.DynamoDBStore = exports.DynamoDBSaver = void 0;
-var saver_1 = require("./checkpointer/saver");
-Object.defineProperty(exports, "DynamoDBSaver", { enumerable: true, get: function () { return saver_1.DynamoDBSaver; } });
-var store_1 = require("./store/store");
-Object.defineProperty(exports, "DynamoDBStore", { enumerable: true, get: function () { return store_1.DynamoDBStore; } });
-var chat_message_history_1 = require("./history/chat-message-history");
-Object.defineProperty(exports, "DynamoDBChatMessageHistory", { enumerable: true, get: function () { return chat_message_history_1.DynamoDBChatMessageHistory; } });
-var session_adapter_1 = require("./history/session-adapter");
-Object.defineProperty(exports, "DynamoDBSessionChatMessageHistory", { enumerable: true, get: function () { return session_adapter_1.DynamoDBSessionChatMessageHistory; } });
-/**
- * Operator tool: give rows written before the recency index their index keys.
- * Run it before setting `indexName` on any adapter — see its own documentation
- * for why enabling the index first hides pre-existing rows from the listings.
- */
-var backfill_1 = require("./backfill/backfill");
-Object.defineProperty(exports, "backfillRecencyIndex", { enumerable: true, get: function () { return backfill_1.backfillRecencyIndex; } });
-var factory_1 = require("./factory/factory");
-Object.defineProperty(exports, "DynamoDBFactory", { enumerable: true, get: function () { return factory_1.DynamoDBFactory; } });
-/**
- * The plain JSON serializer the store and chat-history adapters use by
- * default, exported so a checkpointer can be given it in place of LangGraph's
- * `JsonPlusSerializer`, whose read path instantiates the class a stored
- * `{"lc": …}` record names. See the README's *Trust boundary* note and
- * `SECURITY.md`.
- */
-var json_serde_1 = require("./shared/codec/json-serde");
-Object.defineProperty(exports, "JSON_SERDE", { enumerable: true, get: function () { return json_serde_1.JSON_SERDE; } });
-var base_error_1 = require("./shared/errors/base-error");
-Object.defineProperty(exports, "DynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_1.DynamoDBLangGraphError; } });
-Object.defineProperty(exports, "isDynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_1.isDynamoDBLangGraphError; } });
-var error_code_1 = require("./shared/errors/error-code");
-Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return error_code_1.ErrorCode; } });
-var redaction_1 = require("./shared/logging/redaction");
-Object.defineProperty(exports, "redactLogger", { enumerable: true, get: function () { return redaction_1.redactLogger; } });
-Object.defineProperty(exports, "redactSecrets", { enumerable: true, get: function () { return redaction_1.redactSecrets; } });

package/dist/shared/adapter.js

@@ -1,143 +0,0 @@
-"use strict";
-/**
- * Hides what an adapter owns for its lifetime, and how it lets go of it.
- *
- * Every adapter resolves the same things from its options — a DynamoDB client
- * it either built, and so must destroy, or was handed, and so must not; an S3
- * offloader when it offloads; a logger; a retry policy; the recency index's
- * settings — releases them the same way, and provisions the same lifecycle
- * rule from its ttl. Whether an adapter owns its client is decided in
- * `dynamodb/client.ts`; this module only reads that decision, to release a
- * client it built and leave an injected one alone.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.releaseOwned = releaseOwned;
-exports.ensureLifecycleFor = ensureLifecycleFor;
-exports.openAdapter = openAdapter;
-const config_1 = require("./codec/s3/config");
-const offloader_1 = require("./codec/s3/offloader");
-const concurrency_1 = require("./concurrency");
-const client_1 = require("./dynamodb/client");
-const recency_index_1 = require("./dynamodb/recency-index");
-const retry_1 = require("./dynamodb/retry");
-const base_error_1 = require("./errors/base-error");
-const logger_1 = require("./logging/logger");
-const collaborators_1 = require("./validation/collaborators");
-const options_1 = require("./validation/options");
-const ttl_1 = require("./validation/ttl");
-/**
- * Release every resource, whatever any one of them does.
- *
- * The hazard is the one `DynamoDBFactory`'s own `release` names: a teardown
- * written as a sequence of statements stops at the first throw, so everything
- * after it is stranded with no reference left to reach it by. Each adapter's
- * `destroy` was exactly that sequence — the S3 offloader, then the DynamoDB
- * client it built — and an S3 client whose sockets are already gone throws from
- * its own `destroy`, so the DynamoDB client leaked for the life of the process.
- *
- * Accepts: `resources` — in the order they should be released; an absent one
- * (an adapter with no offloader, a client the caller injected and therefore
- * owns) is skipped rather than guarded at each call site.
- *
- * Returns: nothing.
- *
- * Throws: the **first** failure, and only after every resource has been
- * offered its release, so nothing is stranded behind it. Raised rather than
- * logged because the default logger discards everything: a caller who never
- * configured one would otherwise be told nowhere at all that a client of theirs
- * is still holding sockets. A later failure is dropped, because a caller can
- * act on one report and the first one names the resource that actually broke.
- * A `throw` that produced something other than an `Error` is normalised, so a
- * caller's `catch` is handed the same shape whatever a client raised.
- */
-function releaseOwned(resources) {
-    let first;
-    for (const resource of resources) {
-        try {
-            resource?.destroy();
-        }
-        catch (error) {
-            first ??= (0, base_error_1.toError)(error);
-        }
-    }
-    if (first !== undefined)
-        throw first;
-}
-/**
- * Provision the S3 lifecycle rule that expires what an adapter offloads, on its
- * ttl, so an offloaded payload does not outlive the DynamoDB item that points
- * at it.
- *
- * The rule is expressed in whole days because that is the only granularity S3
- * lifecycle expiration accepts, while the DynamoDB TTL is in seconds; see
- * `lifecycleExpirationDays` for the rounding, which is always up.
- *
- * Accepts: `core` — the adapter's offloader, ttl and logger.
- *
- * Returns: nothing. Without an offloader there is nothing to rule over, and
- * without a ttl no item expires, so any rule would delete a payload a live row
- * still needs: either absence does nothing. Installing a rule that is already
- * there is a no-op too, so calling this on every deploy is safe.
- *
- * Throws: whatever reading or writing the bucket's lifecycle configuration
- * throws, and `VALIDATION` naming `s3.keyPrefix` when the rule id this
- * prefix would take is already held by a different prefix.
- *
- * Guarantees: needs the bucket-level `s3:GetLifecycleConfiguration` /
- * `s3:PutLifecycleConfiguration` permissions, which are broader than the
- * object-level CRUD the rest of offload uses — so this is a provisioning call,
- * not a per-request one.
- */
-async function ensureLifecycleFor(core) {
-    if (!core.offloader || !core.ttl)
-        return;
-    await core.offloader.ensureLifecycleRule((0, ttl_1.lifecycleExpirationDays)(core.ttl), core.logger);
-}
-/**
- * Check an adapter's options and resolve what it will own.
- *
- * Accepts: `options` — the adapter's, already held to its own key list, and
- * checked first, so no half-built adapter exists when one is wrong.
- * `adapter` — which adapter, which names its default S3 key prefix. `checks` —
- * the adapter's own option and collaborator checks, and its retry floor.
- *
- * Returns: the shell: the core every operation reads, with every shared
- * default filled in here and nowhere else, and the adapter's two lifetime
- * operations. A client the caller passed in is never destroyed by `release`.
- *
- * Throws: `VALIDATION` for an option or a collaborator that fails a shared
- * check or one of `checks`, in that order.
- *
- * Guarantees: no I/O. The stacked-retry check is deliberately not awaited: it
- * is a warning about a caller-supplied client, not a precondition.
- */
-function openAdapter(options, adapter, checks = {}) {
-    (0, options_1.assertBaseAdapterOptions)(options);
-    checks.options?.();
-    (0, collaborators_1.assertBaseCollaborators)(options);
-    checks.collaborators?.();
-    const logger = (0, logger_1.resolveLogger)(options.logger);
-    const resolved = (0, client_1.resolveDynamoDBClient)(options);
-    if (!resolved.ownsClient)
-        void (0, client_1.warnOnStackedRetries)(resolved.client, logger);
-    const offloader = options.s3
-        ? new offloader_1.S3Offloader((0, config_1.offloaderConfigFor)(options.s3, adapter, options.clientConfig))
-        : undefined;
-    const core = {
-        client: resolved.client,
-        tableName: options.tableName,
-        compression: options.compression,
-        offloader,
-        ttl: options.ttl,
-        logger,
-        retry: (0, retry_1.resolveRetryPolicy)(options.retry, logger, checks.attemptFloor),
-        indexShards: options.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS,
-        readConcurrency: options.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY,
-        indexName: options.indexName,
-    };
-    return {
-        core,
-        ensureLifecycleRule: () => ensureLifecycleFor(core),
-        release: () => releaseOwned([offloader, resolved.ownsClient ? resolved.ddbClient : undefined]),
-    };
-}