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

package/dist/shared/codec/s3/lifecycle.js

@@ -1,63 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureLifecycleRule = ensureLifecycleRule;
-const client_1 = require("./client");
-const config_1 = require("./config");
-async function readState(client, bucket) {
-    const { GetBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
-    try {
-        const existing = await client.send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
-        return {
-            rules: existing.Rules ?? [],
-            transitionDefaultMinimumObjectSize: existing.TransitionDefaultMinimumObjectSize,
-        };
-    }
-    catch (error) {
-        if (error.name === 'NoSuchLifecycleConfiguration')
-            return { rules: [] };
-        throw error;
-    }
-}
-function alreadyCorrect(rule, days) {
-    return (rule?.Status === 'Enabled' &&
-        rule.Expiration?.Days === days &&
-        rule.NoncurrentVersionExpiration?.NoncurrentDays === days);
-}
-/**
- * Idempotently ensure a `days`-day expiration lifecycle rule exists for
- * `prefix`. Reads existing rules, preserves user-defined ones and the
- * bucket-level `TransitionDefaultMinimumObjectSize` (a Put replaces the whole
- * configuration, so dropping it would reset the bucket to the default), and
- * only adds/updates the library's prefix-scoped rule.
- *
- * Noncurrent versions expire after the same number of days, so a versioned
- * bucket does not retain every superseded payload forever; the field is inert
- * on an unversioned bucket. The prefix is re-checked here because this rule is
- * the one place an unscoped prefix would destroy data outside this library's.
- */
-async function ensureLifecycleRule(client, bucket, prefix, days) {
-    (0, config_1.assertScopedKeyPrefix)(prefix);
-    const ruleId = (0, config_1.buildLifecycleRuleId)(prefix);
-    const state = await readState(client, bucket);
-    const existing = state.rules.find((rule) => rule.ID === ruleId);
-    if (alreadyCorrect(existing, days))
-        return;
-    const newRule = {
-        ID: ruleId,
-        Filter: { Prefix: prefix },
-        Status: 'Enabled',
-        Expiration: { Days: days },
-        NoncurrentVersionExpiration: { NoncurrentDays: days },
-    };
-    const merged = existing
-        ? state.rules.map((rule) => (rule.ID === ruleId ? newRule : rule))
-        : [...state.rules, newRule];
-    const { PutBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
-    await client.send(new PutBucketLifecycleConfigurationCommand({
-        Bucket: bucket,
-        LifecycleConfiguration: { Rules: merged },
-        ...(state.transitionDefaultMinimumObjectSize === undefined
-            ? {}
-            : { TransitionDefaultMinimumObjectSize: state.transitionDefaultMinimumObjectSize }),
-    }));
-}

package/dist/shared/codec/s3/offloader.d.ts

@@ -1,44 +0,0 @@
-import { S3OffloadConfig } from './config';
-/**
- * Thin holder composing the pure S3 functions. Owns config + the lazily-built
- * S3 client and delegates all real work; every method is a small delegation.
- */
-export declare class S3Offloader {
-    private clientPromise;
-    private resolvedClient;
-    private destroyed;
-    private readonly bucketName;
-    private readonly keyPrefix;
-    private readonly thresholdBytes;
-    private readonly sse;
-    private readonly sseKmsKeyId?;
-    private readonly maxDownloadBytes;
-    private readonly config;
-    constructor(config: S3OffloadConfig);
-    private getClient;
-    /** True when `data` is large enough to warrant S3 offload. */
-    shouldOffload(data: Uint8Array): boolean;
-    /** Build the S3 key for the given key parts. */
-    buildKey(parts: readonly string[]): string;
-    /** The configured key prefix. */
-    getKeyPrefix(): string;
-    /** True when `key` lies under this offloader's prefix and the `scope` parts' path. */
-    ownsKey(key: string, scope: readonly string[]): boolean;
-    /** Refuse a row-sourced key outside the row's own path (see {@link assertKeyInScope}). */
-    assertOwnedKey(key: string, scope: readonly string[]): void;
-    /** Upload `data` under `key`, returning the key. */
-    upload(key: string, data: Uint8Array): Promise<string>;
-    /** Download the bytes stored under `key`, refusing objects over `maxDownloadBytes`. */
-    download(key: string): Promise<Uint8Array>;
-    /** Delete `keys`, returning the keys S3 reported as failed. */
-    deleteBatch(keys: string[]): Promise<string[]>;
-    /** Ensure a `${ttlDays}`-day expiration lifecycle rule exists for the prefix. */
-    ensureLifecycleRule(ttlDays: number): Promise<void>;
-    /**
-     * Release the underlying S3 client. Safe at any point in the client's
-     * lifecycle: called before construction starts it does nothing, called
-     * mid-construction it marks the offloader destroyed so the client is
-     * released the moment it resolves, and called after it releases it directly.
-     */
-    destroy(): void;
-}

package/dist/shared/codec/s3/offloader.js

@@ -1,118 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.S3Offloader = void 0;
-const constants_1 = require("../../constants");
-const client_1 = require("./client");
-const config_1 = require("./config");
-const delete_1 = require("./delete");
-const key_scope_1 = require("./key-scope");
-const lifecycle_1 = require("./lifecycle");
-const read_write_1 = require("./read-write");
-/**
- * Thin holder composing the pure S3 functions. Owns config + the lazily-built
- * S3 client and delegates all real work; every method is a small delegation.
- */
-class S3Offloader {
-    clientPromise;
-    resolvedClient;
-    destroyed = false;
-    bucketName;
-    keyPrefix;
-    thresholdBytes;
-    sse;
-    sseKmsKeyId;
-    maxDownloadBytes;
-    config;
-    constructor(config) {
-        this.config = config;
-        this.bucketName = config.bucketName;
-        this.keyPrefix = config.keyPrefix ?? constants_1.DEFAULT_S3_KEY_PREFIX;
-        this.thresholdBytes = config.thresholdBytes ?? constants_1.DEFAULT_S3_THRESHOLD_BYTES;
-        this.sse = config.serverSideEncryption ?? constants_1.DEFAULT_S3_SSE;
-        this.sseKmsKeyId = config.sseKmsKeyId;
-        this.maxDownloadBytes = config.maxDownloadBytes ?? constants_1.DEFAULT_MAX_S3_DOWNLOAD_BYTES;
-        /**
-         * Warm the optional peer's import so a missing `@aws-sdk/client-s3`
-         * surfaces on the very first S3 operation, typed, rather than on the first
-         * oversize payload days later. The rejection is handled here; whichever
-         * operation runs first re-raises it through its own `loadS3Sdk()` call.
-         */
-        void (0, client_1.loadS3Sdk)().catch(() => undefined);
-    }
-    getClient() {
-        if (!this.clientPromise) {
-            const cfg = this.config.clientConfig ?? {};
-            /** The hook is typed structurally for consumers; the runtime modules use the real SDK client. */
-            this.clientPromise = (this.config.createS3Client
-                ? Promise.resolve(this.config.createS3Client({ maxAttempts: 1, ...cfg }))
-                : (0, client_1.createDefaultS3Client)(cfg)).then((client) => {
-                this.resolvedClient = client;
-                /**
-                 * `destroy()` may have run during this construction, when there was
-                 * no client yet to release. Release it now instead of leaking it.
-                 */
-                if (this.destroyed)
-                    client.destroy();
-                return client;
-            }, (error) => {
-                this.clientPromise = undefined;
-                throw error;
-            });
-        }
-        return this.clientPromise;
-    }
-    /** True when `data` is large enough to warrant S3 offload. */
-    shouldOffload(data) {
-        return data.length >= this.thresholdBytes;
-    }
-    /** Build the S3 key for the given key parts. */
-    buildKey(parts) {
-        return (0, config_1.buildS3Key)(this.keyPrefix, parts);
-    }
-    /** The configured key prefix. */
-    getKeyPrefix() {
-        return this.keyPrefix;
-    }
-    /** True when `key` lies under this offloader's prefix and the `scope` parts' path. */
-    ownsKey(key, scope) {
-        return (0, key_scope_1.isKeyInScope)(key, this.keyPrefix, scope);
-    }
-    /** Refuse a row-sourced key outside the row's own path (see {@link assertKeyInScope}). */
-    assertOwnedKey(key, scope) {
-        (0, key_scope_1.assertKeyInScope)(key, this.keyPrefix, scope);
-    }
-    /** Upload `data` under `key`, returning the key. */
-    async upload(key, data) {
-        await (0, read_write_1.uploadObject)(await this.getClient(), {
-            bucket: this.bucketName,
-            key,
-            data,
-            serverSideEncryption: this.sse,
-            sseKmsKeyId: this.sseKmsKeyId,
-        });
-        return key;
-    }
-    /** Download the bytes stored under `key`, refusing objects over `maxDownloadBytes`. */
-    async download(key) {
-        return (0, read_write_1.downloadObject)(await this.getClient(), this.bucketName, key, this.maxDownloadBytes);
-    }
-    /** Delete `keys`, returning the keys S3 reported as failed. */
-    async deleteBatch(keys) {
-        return (0, delete_1.deleteObjects)(await this.getClient(), this.bucketName, keys);
-    }
-    /** Ensure a `${ttlDays}`-day expiration lifecycle rule exists for the prefix. */
-    async ensureLifecycleRule(ttlDays) {
-        return (0, lifecycle_1.ensureLifecycleRule)(await this.getClient(), this.bucketName, this.keyPrefix, ttlDays);
-    }
-    /**
-     * Release the underlying S3 client. Safe at any point in the client's
-     * lifecycle: called before construction starts it does nothing, called
-     * mid-construction it marks the offloader destroyed so the client is
-     * released the moment it resolves, and called after it releases it directly.
-     */
-    destroy() {
-        this.destroyed = true;
-        this.resolvedClient?.destroy();
-    }
-}
-exports.S3Offloader = S3Offloader;

package/dist/shared/codec/s3/orphans.d.ts

@@ -1,23 +0,0 @@
-import type { Logger } from '../../logging/logger';
-import type { S3Offloader } from './offloader';
-/** Options for {@link cleanUpS3Orphans}. */
-export interface OrphanCleanupOptions {
-    rng?: () => number;
-    maxAttempts?: number;
-    signal?: AbortSignal;
-    /**
-     * The row's own leading key parts when `keys` were read back from a row.
-     * A key outside the path they produce is never deleted, only reported; own
-     * uploads (built by this call) pass no scope.
-     */
-    scope?: readonly string[];
-}
-/**
- * Best-effort delete of S3 objects orphaned by a failed DynamoDB write. Retries
- * transient errors with full-jitter backoff; on persistent failure or when S3
- * reports keys it could not delete, it logs at `warn` and never throws — the
- * sole non-throwing path in the library. There is no automatic backstop: an
- * S3 lifecycle rule sweeps the leftovers only if one was provisioned via
- * `ensureS3LifecycleRule()`, which is opt-in.
- */
-export declare function cleanUpS3Orphans(offloader: S3Offloader, keys: ReadonlyArray<string | undefined>, context: string, logger: Logger, options?: OrphanCleanupOptions): Promise<void>;

package/dist/shared/codec/s3/orphans.js

@@ -1,71 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.cleanUpS3Orphans = cleanUpS3Orphans;
-const backoff_1 = require("../../dynamodb/backoff");
-const retry_1 = require("./retry");
-const DEFAULT_MAX_ATTEMPTS = 3;
-const BASE_DELAY_MS = 100;
-/**
- * Wait out one backoff window, cancellable via `options.signal`. Resolves `true`
- * when the signal aborts the wait (so the caller stops retrying) and `false`
- * otherwise — never rejects, preserving the best-effort, non-throwing contract.
- */
-async function backoffSleep(delayMs, options) {
-    try {
-        await (0, backoff_1.sleep)((0, backoff_1.fullJitter)(delayMs, options.rng), options.signal);
-        return false;
-    }
-    catch {
-        return true;
-    }
-}
-/** Drop every key outside the row's scope, reporting each one. */
-function ownedOnly(offloader, keys, scope, context, logger) {
-    return keys.filter((key) => {
-        if (offloader.ownsKey(key, scope))
-            return true;
-        logger.warn(`${context}: refusing to delete an S3 object outside this row's scope`, { key });
-        return false;
-    });
-}
-/** The non-empty keys, restricted to the row's scope when one is given. */
-function selectOrphans(offloader, keys, context, logger, options) {
-    const present = keys.filter((key) => typeof key === 'string' && key.length > 0);
-    return options.scope ? ownedOnly(offloader, present, options.scope, context, logger) : present;
-}
-/**
- * Best-effort delete of S3 objects orphaned by a failed DynamoDB write. Retries
- * transient errors with full-jitter backoff; on persistent failure or when S3
- * reports keys it could not delete, it logs at `warn` and never throws — the
- * sole non-throwing path in the library. There is no automatic backstop: an
- * S3 lifecycle rule sweeps the leftovers only if one was provisioned via
- * `ensureS3LifecycleRule()`, which is opt-in.
- */
-async function cleanUpS3Orphans(offloader, keys, context, logger, options = {}) {
-    const orphans = selectOrphans(offloader, keys, context, logger, options);
-    if (orphans.length === 0)
-        return;
-    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-    let delay = BASE_DELAY_MS;
-    let lastError = new Error('S3 orphan cleanup did not run');
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        try {
-            const failed = await offloader.deleteBatch(orphans);
-            if (failed.length === 0)
-                return;
-            logger.warn(`Some orphaned S3 objects could not be deleted after ${context}; a lifecycle rule from ensureS3LifecycleRule() would sweep them, otherwise clean up manually`, { failedCount: failed.length });
-            return;
-        }
-        catch (error) {
-            lastError = error;
-            if (attempt >= maxAttempts || !(0, retry_1.isTransientS3Error)(lastError))
-                break;
-            if (await backoffSleep(delay, options))
-                break;
-            delay = (0, backoff_1.nextBackoffDelay)(delay);
-        }
-    }
-    logger.warn(`Failed to clean up orphaned S3 objects after ${context}; a lifecycle rule from ensureS3LifecycleRule() would sweep them, otherwise clean up manually`, {
-        message: lastError.message,
-    });
-}

package/dist/shared/codec/s3/read-write.d.ts

@@ -1,18 +0,0 @@
-import type { S3Client } from '@aws-sdk/client-s3';
-/** Parameters for {@link uploadObject}. */
-export interface UploadParams {
-    bucket: string;
-    key: string;
-    data: Uint8Array;
-    serverSideEncryption?: string;
-    sseKmsKeyId?: string;
-}
-/** Upload `data` to S3, wrapping failures as `S3_OFFLOAD_FAILED`. */
-export declare function uploadObject(client: S3Client, params: UploadParams): Promise<void>;
-/**
- * Download an object's bytes, wrapping failures/empty bodies as
- * `S3_OFFLOAD_FAILED`. An object over `maxBytes` is refused from its declared
- * `ContentLength` before the body is touched, or while streaming when the
- * length is unknown, so a replaced or hostile object can never exhaust memory.
- */
-export declare function downloadObject(client: S3Client, bucket: string, key: string, maxBytes: number): Promise<Uint8Array>;

package/dist/shared/codec/s3/read-write.js

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.uploadObject = uploadObject;
-exports.downloadObject = downloadObject;
-const retry_1 = require("../../dynamodb/retry");
-const base_error_1 = require("../../errors/base-error");
-const error_code_1 = require("../../errors/error-code");
-const bounded_body_1 = require("./bounded-body");
-const client_1 = require("./client");
-const retry_2 = require("./retry");
-/** Upload `data` to S3, wrapping failures as `S3_OFFLOAD_FAILED`. */
-async function uploadObject(client, params) {
-    const { PutObjectCommand } = await (0, client_1.loadS3Sdk)();
-    try {
-        await (0, retry_1.withRetry)(() => client.send(new PutObjectCommand({
-            Bucket: params.bucket,
-            Key: params.key,
-            Body: params.data,
-            ContentType: 'application/octet-stream',
-            ServerSideEncryption: params.serverSideEncryption,
-            ...(params.sseKmsKeyId ? { SSEKMSKeyId: params.sseKmsKeyId } : {}),
-        })), { maxAttempts: 3, isRetryable: retry_2.isTransientS3Error });
-    }
-    catch (error) {
-        throw new base_error_1.DynamoDBLangGraphError(error.message, error_code_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'upload', key: params.key }, error);
-    }
-}
-/**
- * Download an object's bytes, wrapping failures/empty bodies as
- * `S3_OFFLOAD_FAILED`. An object over `maxBytes` is refused from its declared
- * `ContentLength` before the body is touched, or while streaming when the
- * length is unknown, so a replaced or hostile object can never exhaust memory.
- */
-async function downloadObject(client, bucket, key, maxBytes) {
-    const { GetObjectCommand } = await (0, client_1.loadS3Sdk)();
-    try {
-        return await (0, retry_1.withRetry)(async () => {
-            const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
-            if (typeof response.ContentLength === 'number' && response.ContentLength > maxBytes) {
-                throw (0, bounded_body_1.oversizedObjectError)(key, response.ContentLength, maxBytes);
-            }
-            if (!response.Body) {
-                throw new Error(`S3 object body is empty for key: ${key}`);
-            }
-            return (0, bounded_body_1.readBodyBounded)(response.Body, key, maxBytes);
-        }, { maxAttempts: 3, isRetryable: retry_2.isTransientS3Error });
-    }
-    catch (error) {
-        throw new base_error_1.DynamoDBLangGraphError(error.message, error_code_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'download', key }, error);
-    }
-}

package/dist/shared/codec/s3/retry.d.ts

@@ -1,5 +0,0 @@
-/**
- * True when `error` looks like a transient S3 failure worth retrying — the one
- * classifier for uploads, downloads and orphan cleanup.
- */
-export declare function isTransientS3Error(error: Error): boolean;

package/dist/shared/codec/s3/retry.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isTransientS3Error = isTransientS3Error;
-const retry_classifier_1 = require("../../dynamodb/retry-classifier");
-/**
- * Transient S3 signals: everything the DynamoDB classifier already treats as
- * transient (the SDK transport `TimeoutError`, socket errors, `RequestTimeout`,
- * `ServiceUnavailable`, …) plus the two names only S3 uses. HTTP 429/5xx and
- * the `$retryable` trait are recognised by the shared classifier itself.
- */
-const RETRYABLE_S3_SIGNALS = [
-    ...retry_classifier_1.DEFAULT_RETRYABLE_ERRORS,
-    'SlowDown',
-    'InternalError',
-];
-/**
- * True when `error` looks like a transient S3 failure worth retrying — the one
- * classifier for uploads, downloads and orphan cleanup.
- */
-function isTransientS3Error(error) {
-    return (0, retry_classifier_1.isRetryableError)(error, RETRYABLE_S3_SIGNALS);
-}

package/dist/shared/concurrency.d.ts

@@ -1,6 +0,0 @@
-/**
- * Map `items` through `fn` with at most `limit` calls in flight, preserving
- * input order in the result. The first rejection wins: no further item is
- * started, the calls already in flight settle, and that error propagates.
- */
-export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/shared/constants.d.ts

@@ -1,112 +0,0 @@
-/** Maximum TTL expressed in days (5 years). */
-export declare const MAX_TTL_DAYS: number;
-/** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
-export declare const MAX_TTL_SECONDS: number;
-/** Hard cap on query-pagination loop iterations (runaway-loop guard). */
-export declare const MAX_LOOP_ITERATIONS = 1000;
-/** Hard cap on items collected into memory across a paginated query. */
-export declare const MAX_TOTAL_ITEMS_IN_MEMORY = 10000;
-/** DynamoDB BatchWriteItem maximum requests per call. */
-export declare const BATCH_WRITE_MAX = 25;
-/** DynamoDB BatchGetItem maximum keys per call. */
-export declare const BATCH_GET_MAX = 100;
-/** Maximum retries draining UnprocessedItems / UnprocessedKeys. */
-export declare const MAX_UNPROCESSED_RETRIES = 10;
-/** Starting delay for UnprocessedItems / UnprocessedKeys backoff loops. */
-export declare const INITIAL_BACKOFF_DELAY_MS = 100;
-/** Maximum backoff delay for retry loops. */
-export declare const MAX_BACKOFF_DELAY_MS = 5000;
-/** S3 DeleteObjects maximum keys per request. */
-export declare const S3_DELETE_BATCH_MAX = 1000;
-/** Default payload size that triggers S3 offload (350 KB; 50 KB under the DDB 400 KB cap). */
-export declare const DEFAULT_S3_THRESHOLD_BYTES: number;
-/**
- * Largest serialized payload stored inline when no S3 offloader is configured:
- * DynamoDB's 400 KB item cap less 8 KB of headroom for the item's keys,
- * attribute names and descriptor fields. Exceeding it fails before the write
- * with a typed error instead of a raw `ValidationException` after it.
- */
-export declare const MAX_INLINE_PAYLOAD_BYTES: number;
-/** Default S3 key prefix for offloaded payloads. */
-export declare const DEFAULT_S3_KEY_PREFIX = "langgraph-checkpoints/";
-/** Default S3 server-side encryption algorithm. */
-export declare const DEFAULT_S3_SSE = "AES256";
-/** Default minimum payload size before gzip compression is attempted. */
-export declare const DEFAULT_COMPRESSION_MIN_BYTES = 1024;
-/** Default gzip compression level (balanced speed/ratio). */
-export declare const DEFAULT_COMPRESSION_LEVEL = 6;
-/** Default gzip-bomb guard: maximum decompressed output (50 MiB). */
-export declare const DEFAULT_MAX_DECOMPRESSED_BYTES: number;
-/**
- * Default cap on an offloaded object buffered from S3 (50 MiB), checked against
- * `ContentLength` before the body is read and enforced while streaming when
- * the length is unknown. Together with {@link DEFAULT_MAX_DECOMPRESSED_BYTES}
- * it bounds the memory any single payload can claim.
- */
-export declare const DEFAULT_MAX_S3_DOWNLOAD_BYTES: number;
-/** Default maximum attempts for transient-error retries. */
-export declare const DEFAULT_RETRY_MAX_ATTEMPTS = 5;
-/** Largest `retry.maxAttempts` an adapter accepts; beyond it a retry loop is a hang, not a policy. */
-export declare const MAX_RETRY_ATTEMPTS = 100;
-/**
- * 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.
- */
-export declare const MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
-/**
- * Offloaded payloads decoded at once by one read (`getTuple` pending writes,
- * `search` candidates, `getMessages`). Each offloaded row costs one S3 GET, so
- * a serial loop scaled latency linearly with the row count; eight in flight
- * keeps the win without bursting a bucket.
- */
-export declare const DEFAULT_READ_CONCURRENCY = 8;
-/** Default cap on candidates the in-DB semantic ranker will score. */
-export declare const DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
-/**
- * Raw rows a single `listCheckpoints` call may pull before it warns. The read
- * itself is deliberately unbounded — capping it counted raw rows rather than
- * filter-matched ones, which turned a caller asking for a handful of rare
- * matches over a large thread into a hard error instead of the true answer.
- * The warning restores the operational signal without restoring the wrong
- * error.
- *
- * Its own literal, deliberately: this is the point at which a scan is worth
- * telling an operator about, which is independent of
- * {@link MAX_TOTAL_ITEMS_IN_MEMORY}'s hard collection cap. Aliasing the two
- * meant retuning the memory cap silently moved the warning as well, and it
- * left the pair reported as a duplicate export.
- */
-export declare const LIST_SCAN_WARN_THRESHOLD = 10000;
-/**
- * Byte caps on caller-supplied identifiers, measured as UTF-8. DynamoDB caps a
- * partition key at 2048 bytes and a sort key at 1024; S3 caps an object key at
- * 1024. These leave room for the adapter prefixes and separators that compose
- * the stored keys, so a value that passes validation fails as a typed error
- * here rather than as a raw AWS ValidationException on the write.
- *
- * Partition-key identifiers: `thread_id` and `sessionId`.
- */
-export declare const MAX_PARTITION_ID_BYTES = 1024;
-/**
- * Sort-key segments: `checkpoint_ns`, `checkpoint_id`, `taskId`, a pending-write
- * channel, a store namespace element and a store `key`.
- */
-export declare const MAX_KEY_SEGMENT_BYTES = 256;
-/** DynamoDB cap on a whole sort key; composed keys are checked against it too. */
-export declare const MAX_SORT_KEY_BYTES = 1024;
-/** S3 cap on an object key, applied to the produced offload key. */
-export declare const MAX_S3_KEY_BYTES = 1024;
-/**
- * Extra days an S3 lifecycle rule adds over the TTL it backs. DynamoDB's TTL
- * sweep can lag up to ~48 h past the `ttl` timestamp; the offloaded object
- * must outlive its row, never the other way round.
- */
-export declare const S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;

package/dist/shared/constants.js

@@ -1,115 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.S3_LIFECYCLE_SWEEP_MARGIN_DAYS = exports.MAX_S3_KEY_BYTES = exports.MAX_SORT_KEY_BYTES = exports.MAX_KEY_SEGMENT_BYTES = exports.MAX_PARTITION_ID_BYTES = exports.LIST_SCAN_WARN_THRESHOLD = exports.DEFAULT_MAX_SEARCH_CANDIDATES = exports.DEFAULT_READ_CONCURRENCY = exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = exports.MAX_RETRY_ATTEMPTS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.DEFAULT_MAX_S3_DOWNLOAD_BYTES = exports.DEFAULT_MAX_DECOMPRESSED_BYTES = exports.DEFAULT_COMPRESSION_LEVEL = exports.DEFAULT_COMPRESSION_MIN_BYTES = exports.DEFAULT_S3_SSE = exports.DEFAULT_S3_KEY_PREFIX = exports.MAX_INLINE_PAYLOAD_BYTES = exports.DEFAULT_S3_THRESHOLD_BYTES = exports.S3_DELETE_BATCH_MAX = exports.MAX_BACKOFF_DELAY_MS = exports.INITIAL_BACKOFF_DELAY_MS = exports.MAX_UNPROCESSED_RETRIES = exports.BATCH_GET_MAX = exports.BATCH_WRITE_MAX = exports.MAX_TOTAL_ITEMS_IN_MEMORY = exports.MAX_LOOP_ITERATIONS = exports.MAX_TTL_SECONDS = exports.MAX_TTL_DAYS = void 0;
-/** Maximum TTL expressed in days (5 years). */
-exports.MAX_TTL_DAYS = 365 * 5;
-/** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
-exports.MAX_TTL_SECONDS = exports.MAX_TTL_DAYS * 24 * 60 * 60;
-/** Hard cap on query-pagination loop iterations (runaway-loop guard). */
-exports.MAX_LOOP_ITERATIONS = 1000;
-/** Hard cap on items collected into memory across a paginated query. */
-exports.MAX_TOTAL_ITEMS_IN_MEMORY = 10000;
-/** DynamoDB BatchWriteItem maximum requests per call. */
-exports.BATCH_WRITE_MAX = 25;
-/** DynamoDB BatchGetItem maximum keys per call. */
-exports.BATCH_GET_MAX = 100;
-/** Maximum retries draining UnprocessedItems / UnprocessedKeys. */
-exports.MAX_UNPROCESSED_RETRIES = 10;
-/** Starting delay for UnprocessedItems / UnprocessedKeys backoff loops. */
-exports.INITIAL_BACKOFF_DELAY_MS = 100;
-/** Maximum backoff delay for retry loops. */
-exports.MAX_BACKOFF_DELAY_MS = 5000;
-/** S3 DeleteObjects maximum keys per request. */
-exports.S3_DELETE_BATCH_MAX = 1000;
-/** Default payload size that triggers S3 offload (350 KB; 50 KB under the DDB 400 KB cap). */
-exports.DEFAULT_S3_THRESHOLD_BYTES = 350 * 1024;
-/**
- * Largest serialized payload stored inline when no S3 offloader is configured:
- * DynamoDB's 400 KB item cap less 8 KB of headroom for the item's keys,
- * attribute names and descriptor fields. Exceeding it fails before the write
- * with a typed error instead of a raw `ValidationException` after it.
- */
-exports.MAX_INLINE_PAYLOAD_BYTES = 400 * 1024 - 8 * 1024;
-/** Default S3 key prefix for offloaded payloads. */
-exports.DEFAULT_S3_KEY_PREFIX = 'langgraph-checkpoints/';
-/** Default S3 server-side encryption algorithm. */
-exports.DEFAULT_S3_SSE = 'AES256';
-/** Default minimum payload size before gzip compression is attempted. */
-exports.DEFAULT_COMPRESSION_MIN_BYTES = 1024;
-/** Default gzip compression level (balanced speed/ratio). */
-exports.DEFAULT_COMPRESSION_LEVEL = 6;
-/** Default gzip-bomb guard: maximum decompressed output (50 MiB). */
-exports.DEFAULT_MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
-/**
- * Default cap on an offloaded object buffered from S3 (50 MiB), checked against
- * `ContentLength` before the body is read and enforced while streaming when
- * the length is unknown. Together with {@link DEFAULT_MAX_DECOMPRESSED_BYTES}
- * it bounds the memory any single payload can claim.
- */
-exports.DEFAULT_MAX_S3_DOWNLOAD_BYTES = 50 * 1024 * 1024;
-/** Default maximum attempts for transient-error retries. */
-exports.DEFAULT_RETRY_MAX_ATTEMPTS = 5;
-/** Largest `retry.maxAttempts` an adapter accepts; beyond it a retry loop is a hang, not a policy. */
-exports.MAX_RETRY_ATTEMPTS = 100;
-/**
- * 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;
-/**
- * Offloaded payloads decoded at once by one read (`getTuple` pending writes,
- * `search` candidates, `getMessages`). Each offloaded row costs one S3 GET, so
- * a serial loop scaled latency linearly with the row count; eight in flight
- * keeps the win without bursting a bucket.
- */
-exports.DEFAULT_READ_CONCURRENCY = 8;
-/** Default cap on candidates the in-DB semantic ranker will score. */
-exports.DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
-/**
- * Raw rows a single `listCheckpoints` call may pull before it warns. The read
- * itself is deliberately unbounded — capping it counted raw rows rather than
- * filter-matched ones, which turned a caller asking for a handful of rare
- * matches over a large thread into a hard error instead of the true answer.
- * The warning restores the operational signal without restoring the wrong
- * error.
- *
- * Its own literal, deliberately: this is the point at which a scan is worth
- * telling an operator about, which is independent of
- * {@link MAX_TOTAL_ITEMS_IN_MEMORY}'s hard collection cap. Aliasing the two
- * meant retuning the memory cap silently moved the warning as well, and it
- * left the pair reported as a duplicate export.
- */
-exports.LIST_SCAN_WARN_THRESHOLD = 10000;
-/**
- * Byte caps on caller-supplied identifiers, measured as UTF-8. DynamoDB caps a
- * partition key at 2048 bytes and a sort key at 1024; S3 caps an object key at
- * 1024. These leave room for the adapter prefixes and separators that compose
- * the stored keys, so a value that passes validation fails as a typed error
- * here rather than as a raw AWS ValidationException on the write.
- *
- * Partition-key identifiers: `thread_id` and `sessionId`.
- */
-exports.MAX_PARTITION_ID_BYTES = 1024;
-/**
- * Sort-key segments: `checkpoint_ns`, `checkpoint_id`, `taskId`, a pending-write
- * channel, a store namespace element and a store `key`.
- */
-exports.MAX_KEY_SEGMENT_BYTES = 256;
-/** DynamoDB cap on a whole sort key; composed keys are checked against it too. */
-exports.MAX_SORT_KEY_BYTES = 1024;
-/** S3 cap on an object key, applied to the produced offload key. */
-exports.MAX_S3_KEY_BYTES = 1024;
-/**
- * Extra days an S3 lifecycle rule adds over the TTL it backs. DynamoDB's TTL
- * sweep can lag up to ~48 h past the `ttl` timestamp; the offloaded object
- * must outlive its row, never the other way round.
- */
-exports.S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;