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

package/dist/esm/shared/codec/json-serde.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Hides the JSON form: writing it, reading it, and recognising it.
+ *
+ * The default serde writes a value as JSON under the `json` type and reads
+ * back only that type; the codec also asks, when a serde refuses stored bytes,
+ * whether those bytes are still JSON at all, which tells a corrupt payload from
+ * a serde that would not reconstruct it.
+ */
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+/**
+ * A plain JSON serializer implementing LangGraph's `SerializerProtocol`:
+ * the default `serde` of `DynamoDBStore` and `DynamoDBChatMessageHistory`, and
+ * the alternative a `DynamoDBSaver` can be given in place of LangGraph's
+ * `JsonPlusSerializer`.
+ *
+ * It is exported so that choice is available. The checkpointer's default
+ * revives a stored `{"lc": …}` record by instantiating the class the record
+ * names, so the row selects which constructor runs on read; this serializer
+ * runs `JSON.parse` and nothing else, and reconstructs no class at all.
+ * Reading with it is the narrower trust boundary, and the price is stated
+ * below: it stores the JSON projection of a value, not the value.
+ *
+ * `dumpsTyped` accepts any value `JSON.stringify` can represent and refuses the
+ * rest. A value it cannot represent — `undefined`, a function, a symbol —
+ * stringifies to `undefined` and would be stored as **zero bytes**, which reads
+ * back as a parse error; a circular structure or a `BigInt` makes it throw. Both
+ * are reported as `VALIDATION` naming `value`, at the write, rather than
+ * as an unreadable row later — with the refusal attached as `cause` and never
+ * quoted into the message, which for a circular structure names the caller's
+ * own properties and classes.
+ *
+ * What it represents, it represents as JSON, which is lossy in ways nothing
+ * records: a `Map` or `Set` stores as `{}`, an object key whose value is
+ * `undefined` is dropped and an array element is stored as `null`, `NaN` and
+ * `Infinity` store as `null`, `-0` as `0`, a `Uint8Array` as an index-keyed
+ * object and a `Date` as an ISO string. The README's *Table schema* section
+ * holds the whole table, against the checkpointer default column by column.
+ *
+ * `loadsTyped` reads only the `json` form it writes, and says
+ * so before it looks at a byte. Any other declared form is a `VALIDATION` error
+ * naming `serde`, because it says what *this* reader may rebuild and not that
+ * the payload is damaged. Bytes of that form which do not parse are
+ * `PAYLOAD_CORRUPT`, because they can never be read and the caller should
+ * report rather than retry; a `data` that is not bytes at all is a
+ * `VALIDATION` naming `data`, because that is the caller's mistake and
+ * not a row's.
+ *
+ * Frozen for the reason {@link ErrorCode} is: one object, shared by every
+ * adapter in the process that did not pass a `serde` of its own, and
+ * reachable from the package root. An assignment to `dumpsTyped` by any one
+ * consumer would silently change how every other one writes.
+ */
+export declare const JSON_SERDE: SerializerProtocol;
+/**
+ * Whether stored bytes are still the form the row that holds them declares.
+ *
+ * This is the structural question behind the two ways a decode fails —
+ * `PAYLOAD_CORRUPT` for bytes no reader can decode, and the `serde` refusal for
+ * bytes *this* reader will not rebuild a value from — and it is the only one
+ * this package can answer on its own. `SerializerProtocol` offers no way to ask
+ * a serde whether it parsed the bytes before deciding not to reconstruct what
+ * they name, and the refusal it throws is a caller's object: its class, its
+ * fields and its prose are all whatever that caller chose. Classifying a
+ * payload by any of those would make the code mean "a third party said so",
+ * which is exactly what neither code may mean.
+ *
+ * Accepts: `serdeType` — the type stamped on the row, as the descriptor carries
+ * it. `bytes` — what the row stored, already decompressed.
+ *
+ * Returns: whether the bytes still parse as the declared form. A type this
+ * package has no grammar for is taken at its word and answers `true`, so its
+ * serde's refusal is reported rather than written off: dropping a payload this
+ * reader merely cannot check would lose data on nothing but its own ignorance.
+ *
+ * Throws: **nothing**, for any bytes. It is called from inside the `catch` that
+ * is classifying a decode failure, where a throw would replace the failure
+ * being reported — and the value it is handed came off a row, so it may be
+ * anything that row's writer stored.
+ */
+export declare function bytesHoldDeclaredForm(serdeType: string, bytes: Uint8Array): boolean;

package/dist/esm/shared/codec/json-serde.js

@@ -0,0 +1,54 @@
+import { DynamoDBLangGraphError, toError } from '../errors/base-error.js';
+import { ErrorCode } from '../errors/error-code.js';
+import { validationError } from '../errors/errors.js';
+import { truncateForLog } from '../logging/truncate.js';
+export const JSON_SERDE = {
+    async dumpsTyped(value) {
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            throw validationError('value cannot be serialized as JSON — a circular structure, or a value JSON has no ' +
+                'encoding for such as a BigInt; the refusal itself is attached as `cause`', 'value', toError(error));
+        }
+        if (text === undefined) {
+            throw validationError('value has no JSON representation (undefined, a function or a symbol), so it cannot be ' +
+                'stored; store null instead to record an absent value', 'value');
+        }
+        return Promise.resolve([JSON_SERDE_TYPE, new TextEncoder().encode(text)]);
+    },
+    async loadsTyped(type, data) {
+        if (type !== JSON_SERDE_TYPE) {
+            throw validationError(`this serializer reads only the \`${JSON_SERDE_TYPE}\` form it writes, and this payload ` +
+                `declares ${truncateForLog(String(JSON.stringify(type)))}; read the row with the ` +
+                'serializer that wrote it, or rewrite the row', 'serde');
+        }
+        let text;
+        try {
+            text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+        }
+        catch (error) {
+            throw validationError('data must be the bytes or text this serializer wrote, as a Uint8Array or a string', 'data', error);
+        }
+        try {
+            return Promise.resolve(JSON.parse(text));
+        }
+        catch (error) {
+            throw new DynamoDBLangGraphError('the stored payload is not the JSON this serializer wrote, so it cannot be decoded', ErrorCode.PAYLOAD_CORRUPT, {}, error);
+        }
+    },
+};
+Object.freeze(JSON_SERDE);
+const JSON_SERDE_TYPE = 'json';
+export function bytesHoldDeclaredForm(serdeType, bytes) {
+    if (serdeType !== JSON_SERDE_TYPE)
+        return true;
+    try {
+        JSON.parse(new TextDecoder().decode(bytes));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/esm/shared/codec/s3/client-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Hides the S3 SDK's own types from this package's declarations.
+ *
+ * The S3 client, its config and a command are described by the members this
+ * package touches, so no shipped declaration imports the optional
+ * `@aws-sdk/client-s3` peer and a caller without it installed still compiles
+ * (record 1). A real `S3Client` or `S3ClientConfig` satisfies these shapes as
+ * it is, so a caller who has the SDK passes its own values unchanged.
+ */
+/** A region as the SDK accepts it: a string or a provider resolving to one. */
+export type S3RegionLike = string | (() => Promise<string>);
+/** A value an S3 client option can hold. */
+export type S3ClientOption = string | number | boolean | object | null | undefined;
+/**
+ * The S3 client options this library reads (`region`) or sets (`maxAttempts`),
+ * open to every other `S3ClientConfig` key.
+ */
+export interface S3ClientOptions {
+    region?: S3RegionLike;
+    maxAttempts?: number;
+    [option: string]: S3ClientOption;
+}
+/**
+ * Structural stand-in for `S3ClientConfig`, so the shipped declarations compile
+ * without the optional `@aws-sdk/client-s3` peer installed. A literal gets
+ * completion for the options the library uses; a typed `S3ClientConfig`
+ * variable is accepted as it is.
+ */
+export type S3ClientConfigLike = S3ClientOptions | object;
+/**
+ * The options of a config, read through the structural type.
+ *
+ * Accepts: a config as the caller gave it, or nothing.
+ *
+ * Returns: the same object seen as {@link S3ClientOptions} so `region` and
+ * `maxAttempts` can be read; an absent config reads as empty rather than
+ * needing a guard at every call site.
+ *
+ * Throws: nothing.
+ */
+export declare function s3ClientOptions(config: S3ClientConfigLike | undefined): S3ClientOptions;
+/** What every SDK command object carries: its `input`. */
+interface S3CommandLike {
+    input: object;
+}
+/**
+ * The S3 client surface this library calls, typed structurally for the same
+ * reason. `S3Client` from `@aws-sdk/client-s3` satisfies it.
+ */
+export interface S3ClientLike {
+    send(command: S3CommandLike, options?: object): Promise<object>;
+    destroy(): void;
+}
+export {};

package/dist/esm/shared/codec/s3/client-types.js

@@ -0,0 +1,3 @@
+export function s3ClientOptions(config) {
+    return (config ?? {});
+}

package/dist/esm/shared/codec/s3/client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Hides that the S3 SDK is loaded on first use, and how its client is set up.
+ *
+ * An adapter without offload never imports the optional peer; the first
+ * offload does, once, and a missing install surfaces as `VALIDATION` naming
+ * the remedy (record 1). The client built here defaults to no retries of its
+ * own — `maxAttempts: 1` — so this package's retry is the only layer unless a
+ * caller's own `maxAttempts` overrides it (record 14), and its idle timer
+ * bounds a stalled transfer without bounding a slow one.
+ */
+import type { S3Client } from '@aws-sdk/client-s3';
+import { type S3ClientConfigLike, type S3ClientOptions } from './client-types.js';
+type S3Sdk = typeof import('@aws-sdk/client-s3');
+/**
+ * The optional `@aws-sdk/client-s3` peer, imported on first use.
+ *
+ * Accepts: nothing. Concurrent callers share one import.
+ *
+ * Returns: the module, cached for every later call.
+ *
+ * Throws: `VALIDATION` naming `s3` when the package is not installed,
+ * carrying the install command; any other import failure — a broken build, a
+ * syntax error inside the package — passes through unchanged. A failure is not
+ * cached, so an install or a fixed bundle succeeds on a later call. Each
+ * concurrent caller of a failed import gets its own error instance
+ * (`copyForCaller`), so the public boundary stamping one's `context.operation`
+ * cannot leave it sitting in another caller's error too.
+ */
+export declare function loadS3Sdk(): Promise<S3Sdk>;
+/**
+ * `config` with the two defaults every S3 client of this library is built
+ * with, whichever constructor builds it.
+ *
+ * Accepts: `config` — the caller's `s3.clientConfig`, or an empty object.
+ *
+ * Returns: a copy whose `maxAttempts` and `requestHandler` are the caller's
+ * own where it gave one and the default where it did not. A key named with
+ * `undefined` — a config assembled from settings that were not all set — gave
+ * none, and keeps the default.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: `maxAttempts` defaults to 1, so the SDK performs no retries of
+ * its own and this library's retry, backoff and classification are the only
+ * retry layer — the same default `resolveDynamoDBClient` applies on the
+ * DynamoDB side. A default request handler bounds a transfer that has
+ * stalled, which `maxAttempts` alone does not; a `requestHandler` in `config`
+ * replaces it whole rather than merging with it.
+ */
+export declare function withS3ClientDefaults(config: S3ClientConfigLike): S3ClientOptions;
+/**
+ * An `S3Client` built from `config` with the lazily-loaded SDK.
+ *
+ * Accepts: `config` — any `S3ClientConfig`; an explicit `maxAttempts` or
+ * `requestHandler` wins over the defaults {@link withS3ClientDefaults} fills
+ * in.
+ *
+ * Returns: the client. The caller owns it and destroys it.
+ *
+ * Throws: whatever {@link loadS3Sdk} throws.
+ */
+export declare function createDefaultS3Client(config: S3ClientConfigLike): Promise<S3Client>;
+export {};

package/dist/esm/shared/codec/s3/client.js

@@ -0,0 +1,40 @@
+import { DEFAULT_SOCKET_TIMEOUT_MS } from '../../dynamodb/client.js';
+import { copyForCaller } from '../../errors/base-error.js';
+import { validationError } from '../../errors/errors.js';
+import { s3ClientOptions } from './client-types.js';
+const MISSING_MODULE_CODES = ['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'];
+let sdkPromise;
+function wrapMissingPeer(error) {
+    const code = error.code;
+    if (code !== undefined && MISSING_MODULE_CODES.includes(code)) {
+        throw validationError('S3 offload requires the optional peer @aws-sdk/client-s3 (npm install @aws-sdk/client-s3); ' +
+            'bundlers must keep it installed or external', 's3', error);
+    }
+    throw error;
+}
+export async function loadS3Sdk() {
+    if (!sdkPromise) {
+        sdkPromise = import('@aws-sdk/client-s3').catch((error) => {
+            sdkPromise = undefined;
+            return wrapMissingPeer(error);
+        });
+    }
+    try {
+        return await sdkPromise;
+    }
+    catch (error) {
+        throw copyForCaller(error);
+    }
+}
+export function withS3ClientDefaults(config) {
+    const options = s3ClientOptions(config);
+    return {
+        ...options,
+        maxAttempts: options.maxAttempts ?? 1,
+        requestHandler: options.requestHandler ?? { socketTimeout: DEFAULT_SOCKET_TIMEOUT_MS },
+    };
+}
+export async function createDefaultS3Client(config) {
+    const { S3Client: S3ClientCtor } = await loadS3Sdk();
+    return new S3ClientCtor(withS3ClientDefaults(config));
+}

package/dist/{shared/codec/s3/config.js → esm/shared/codec/s3/config.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides the S3 key layout: where a row's object lives, and which keys a row may touch.
  *
@@ -9,26 +8,41 @@
  * caller passes, its checks, the default prefix per adapter and the lifecycle
  * rule ids derived from a prefix are part of the same layout.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_S3_KEY_BYTES = exports.DEFAULT_S3_KEY_PREFIX = void 0;
-exports.encodeKeyPart = encodeKeyPart;
-exports.buildS3Key = buildS3Key;
-exports.assertScopedKeyPrefix = assertScopedKeyPrefix;
-exports.buildLifecycleRuleId = buildLifecycleRuleId;
-exports.buildMarkerRuleId = buildMarkerRuleId;
-exports.defaultAdapterKeyPrefix = defaultAdapterKeyPrefix;
-exports.s3KeyScope = s3KeyScope;
-exports.isKeyInScope = isKeyInScope;
-exports.assertKeyInScope = assertKeyInScope;
-exports.offloaderConfigFor = offloaderConfigFor;
-const errors_1 = require("../../errors/errors");
-const truncate_1 = require("../../logging/truncate");
-const primitives_1 = require("../../validation/primitives");
-const client_types_1 = require("./client-types");
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { type S3ClientConfigLike } from './client-types.js';
 /** Default S3 key prefix for offloaded payloads. */
-exports.DEFAULT_S3_KEY_PREFIX = 'langgraph-checkpoints/';
+export declare const DEFAULT_S3_KEY_PREFIX = "langgraph-checkpoints/";
 /** S3 cap on an object key, applied to the produced offload key. */
-exports.MAX_S3_KEY_BYTES = 1024;
+export declare const MAX_S3_KEY_BYTES = 1024;
+/** Configuration for offloading large payloads to S3. */
+export interface S3OffloadConfig {
+    bucketName: string;
+    keyPrefix?: string;
+    /**
+     * Serialized payloads at or above this size are offloaded (default 350 KB).
+     * Only the payload counts: the store's inline vectors live on the same item
+     * and are not part of it. The store embeds one vector per text its
+     * `index.fields` extract — a wildcard path yields one per element — each up
+     * to about 10 bytes per dimension, so three texts at 1024 dims cost roughly
+     * 30 KB. A row that payload and those vectors would take past DynamoDB's
+     * 400 KB item limit is refused with `VALIDATION` naming `index`.
+     */
+    thresholdBytes?: number;
+    serverSideEncryption?: string;
+    sseKmsKeyId?: string;
+    /**
+     * Largest object this adapter will buffer from S3 (default 50 MiB). An
+     * offloaded payload larger than it is refused at the write, and a value
+     * below `thresholdBytes` is refused at construction, so an adapter never
+     * stores an object it could not read back.
+     */
+    maxDownloadBytes?: number;
+    /**
+     * S3 client configuration (an `S3ClientConfig`). `region` defaults to the
+     * adapter's DynamoDB region.
+     */
+    clientConfig?: S3ClientConfigLike;
+}
 /**
  * One key part, base64url-encoded.
  *
@@ -40,9 +54,7 @@ exports.MAX_S3_KEY_BYTES = 1024;
  *
  * Throws: nothing.
  */
-function encodeKeyPart(part) {
-    return Buffer.from(part, 'utf8').toString('base64url');
-}
+export declare function encodeKeyPart(part: string): string;
 /**
  * Build a fully-qualified S3 key: `${prefix}${parts, each base64url-encoded,
  * joined with '/'}/${objectId}.bin`.
@@ -72,21 +84,7 @@ function encodeKeyPart(part) {
  * third, so identifiers that each pass their own length rule can still compose
  * a key S3 would reject with a raw error.
  */
-function buildS3Key(prefix, parts, objectId) {
-    if (parts.length === 0) {
-        throw (0, errors_1.validationError)('an offloaded object needs the identity of the row that points at it; parts was empty', 's3Key');
-    }
-    const encoded = [...parts.map(encodeKeyPart), objectId];
-    const key = `${prefix}${encoded.join('/')}.bin`;
-    const bytes = Buffer.byteLength(key, 'utf8');
-    if (bytes > exports.MAX_S3_KEY_BYTES) {
-        throw (0, errors_1.validationError)(`the offloaded S3 object key would be ${bytes} bytes; S3 caps keys at ` +
-            `${exports.MAX_S3_KEY_BYTES} — shorten the identifiers or the keyPrefix`, 's3Key');
-    }
-    return key;
-}
-/** A path segment that names something other than itself, or nothing at all. */
-const UNSCOPED_SEGMENTS = new Set(['', '.', '..']);
+export declare function buildS3Key(prefix: string, parts: readonly string[], objectId: string): string;
 /**
  * Refuse a key prefix that does not scope what it is used for.
  *
@@ -118,25 +116,7 @@ const UNSCOPED_SEGMENTS = new Set(['', '.', '..']);
  * outside the path the lifecycle rule sweeps, which is the whole job of a
  * prefix.
  */
-function assertScopedKeyPrefix(keyPrefix) {
-    if (typeof keyPrefix !== 'string' ||
-        keyPrefix === '' ||
-        keyPrefix === '/' ||
-        !keyPrefix.endsWith('/')) {
-        throw (0, errors_1.validationError)('s3.keyPrefix must be a non-empty path that ends with "/" (for example "langgraph/"): ' +
-            'it scopes both the offloaded objects and the S3 lifecycle rule', 's3.keyPrefix');
-    }
-    (0, primitives_1.assertNoControlChars)(keyPrefix, 's3.keyPrefix');
-    (0, primitives_1.assertWellFormed)(keyPrefix, 's3.keyPrefix');
-    if (keyPrefix
-        .slice(0, -1)
-        .split('/')
-        .some((segment) => UNSCOPED_SEGMENTS.has(segment))) {
-        throw (0, errors_1.validationError)('s3.keyPrefix must name a real path: no empty, "." or ".." segment (for example ' +
-            '"langgraph/", not "../langgraph/" or "/langgraph/"). Such a prefix addresses object ' +
-            'keys outside the path the IAM policy grants and the lifecycle rule sweeps', 's3.keyPrefix');
-    }
-}
+export declare function assertScopedKeyPrefix(keyPrefix: string): void;
 /**
  * The lifecycle rule id for `prefix`: `langgraph-ttl-` plus its slug.
  *
@@ -153,13 +133,7 @@ function assertScopedKeyPrefix(keyPrefix) {
  * and `ensureLifecycleRule` refuses rather than take over a rule that a
  * different prefix already holds.
  */
-function buildLifecycleRuleId(prefix) {
-    let trimmed = prefix;
-    while (trimmed.endsWith('/'))
-        trimmed = trimmed.slice(0, -1);
-    const slug = trimmed.replace(/[^a-zA-Z0-9-]/g, '-') || 'default';
-    return `langgraph-ttl-${slug}`;
-}
+export declare function buildLifecycleRuleId(prefix: string): string;
 /**
  * The id of the rule that reclaims this prefix's expired delete markers:
  * {@link buildLifecycleRuleId}'s id with a suffix of its own.
@@ -181,9 +155,7 @@ function buildLifecycleRuleId(prefix) {
  * over either id when a different prefix already holds it, and its refusal
  * names the suffix so the remedy fits the case.
  */
-function buildMarkerRuleId(prefix) {
-    return `${buildLifecycleRuleId(prefix)}-markers`;
-}
+export declare function buildMarkerRuleId(prefix: string): string;
 /**
  * An adapter's default S3 key prefix.
  *
@@ -196,9 +168,7 @@ function buildMarkerRuleId(prefix) {
  *
  * Throws: nothing.
  */
-function defaultAdapterKeyPrefix(base, adapter) {
-    return `${base}${adapter}/`;
-}
+export declare function defaultAdapterKeyPrefix(base: string, adapter: string): string;
 /**
  * The path every key built from `parts` shares.
  *
@@ -210,9 +180,7 @@ function defaultAdapterKeyPrefix(base, adapter) {
  *
  * Throws: nothing.
  */
-function s3KeyScope(prefix, parts) {
-    return `${prefix}${parts.map(encodeKeyPart).join('/')}`;
-}
+export declare function s3KeyScope(prefix: string, parts: readonly string[]): string;
 /**
  * Whether `key` lies inside the path `parts` produce.
  *
@@ -231,12 +199,7 @@ function s3KeyScope(prefix, parts) {
  * `t1`) never matches its scope — the parts are base64url-encoded and joined
  * by `/`, so the comparison is segment-wise, not textual.
  */
-function isKeyInScope(key, prefix, parts) {
-    const scope = s3KeyScope(prefix, parts);
-    if (parts.length === 0)
-        return key.startsWith(scope);
-    return key === `${scope}.bin` || key.startsWith(`${scope}/`);
-}
+export declare function isKeyInScope(key: string, prefix: string, parts: readonly string[]): boolean;
 /**
  * Refuse a row-sourced `s3Key` outside the path the row's own identifiers
  * produce.
@@ -271,13 +234,9 @@ function isKeyInScope(key, prefix, parts) {
  * at. A writer able to place one row in a partition cannot make this library
  * download or delete another tenant's object, nor make it quietly return less.
  */
-function assertKeyInScope(key, prefix, parts) {
-    if (isKeyInScope(key, prefix, parts))
-        return;
-    throw (0, errors_1.validationError)(`s3Key "${(0, truncate_1.truncateForLog)(key)}" lies outside the S3 path this row may reference ` +
-        `("${(0, truncate_1.truncateForLog)(s3KeyScope(prefix, parts))}"); refusing to touch an object the row ` +
-        'does not own', 's3Key');
-}
+export declare function assertKeyInScope(key: string, prefix: string, parts: readonly string[]): void;
+/** The adapters that share one bucket, each under its own default key prefix. */
+export type AdapterName = 'checkpointer' | 'store' | 'history';
 /**
  * An adapter's `s3` option resolved into the offloader's configuration.
  *
@@ -298,11 +257,4 @@ function assertKeyInScope(key, prefix, parts) {
  * region redirects, so such a bucket otherwise failed with an opaque
  * `PermanentRedirect` on the first offload.
  */
-function offloaderConfigFor(s3, adapter, clientConfig) {
-    const region = (0, client_types_1.s3ClientOptions)(s3.clientConfig).region ?? clientConfig?.region;
-    return {
-        ...s3,
-        keyPrefix: s3.keyPrefix ?? defaultAdapterKeyPrefix(exports.DEFAULT_S3_KEY_PREFIX, adapter),
-        ...(region === undefined ? {} : { clientConfig: { ...s3.clientConfig, region } }),
-    };
-}
+export declare function offloaderConfigFor(s3: S3OffloadConfig, adapter: AdapterName, clientConfig?: DynamoDBClientConfig): S3OffloadConfig;

package/dist/esm/shared/codec/s3/config.js

@@ -0,0 +1,79 @@
+import { validationError } from '../../errors/errors.js';
+import { truncateForLog } from '../../logging/truncate.js';
+import { assertNoControlChars, assertWellFormed } from '../../validation/primitives.js';
+import { s3ClientOptions } from './client-types.js';
+export const DEFAULT_S3_KEY_PREFIX = 'langgraph-checkpoints/';
+export const MAX_S3_KEY_BYTES = 1024;
+export function encodeKeyPart(part) {
+    return Buffer.from(part, 'utf8').toString('base64url');
+}
+export function buildS3Key(prefix, parts, objectId) {
+    if (parts.length === 0) {
+        throw validationError('an offloaded object needs the identity of the row that points at it; parts was empty', 's3Key');
+    }
+    const encoded = [...parts.map(encodeKeyPart), objectId];
+    const key = `${prefix}${encoded.join('/')}.bin`;
+    const bytes = Buffer.byteLength(key, 'utf8');
+    if (bytes > MAX_S3_KEY_BYTES) {
+        throw validationError(`the offloaded S3 object key would be ${bytes} bytes; S3 caps keys at ` +
+            `${MAX_S3_KEY_BYTES} — shorten the identifiers or the keyPrefix`, 's3Key');
+    }
+    return key;
+}
+const UNSCOPED_SEGMENTS = new Set(['', '.', '..']);
+export function assertScopedKeyPrefix(keyPrefix) {
+    if (typeof keyPrefix !== 'string' ||
+        keyPrefix === '' ||
+        keyPrefix === '/' ||
+        !keyPrefix.endsWith('/')) {
+        throw validationError('s3.keyPrefix must be a non-empty path that ends with "/" (for example "langgraph/"): ' +
+            'it scopes both the offloaded objects and the S3 lifecycle rule', 's3.keyPrefix');
+    }
+    assertNoControlChars(keyPrefix, 's3.keyPrefix');
+    assertWellFormed(keyPrefix, 's3.keyPrefix');
+    if (keyPrefix
+        .slice(0, -1)
+        .split('/')
+        .some((segment) => UNSCOPED_SEGMENTS.has(segment))) {
+        throw validationError('s3.keyPrefix must name a real path: no empty, "." or ".." segment (for example ' +
+            '"langgraph/", not "../langgraph/" or "/langgraph/"). Such a prefix addresses object ' +
+            'keys outside the path the IAM policy grants and the lifecycle rule sweeps', 's3.keyPrefix');
+    }
+}
+export function buildLifecycleRuleId(prefix) {
+    let trimmed = prefix;
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    const slug = trimmed.replace(/[^a-zA-Z0-9-]/g, '-') || 'default';
+    return `langgraph-ttl-${slug}`;
+}
+export function buildMarkerRuleId(prefix) {
+    return `${buildLifecycleRuleId(prefix)}-markers`;
+}
+export function defaultAdapterKeyPrefix(base, adapter) {
+    return `${base}${adapter}/`;
+}
+export function s3KeyScope(prefix, parts) {
+    return `${prefix}${parts.map(encodeKeyPart).join('/')}`;
+}
+export function isKeyInScope(key, prefix, parts) {
+    const scope = s3KeyScope(prefix, parts);
+    if (parts.length === 0)
+        return key.startsWith(scope);
+    return key === `${scope}.bin` || key.startsWith(`${scope}/`);
+}
+export function assertKeyInScope(key, prefix, parts) {
+    if (isKeyInScope(key, prefix, parts))
+        return;
+    throw validationError(`s3Key "${truncateForLog(key)}" lies outside the S3 path this row may reference ` +
+        `("${truncateForLog(s3KeyScope(prefix, parts))}"); refusing to touch an object the row ` +
+        'does not own', 's3Key');
+}
+export function offloaderConfigFor(s3, adapter, clientConfig) {
+    const region = s3ClientOptions(s3.clientConfig).region ?? clientConfig?.region;
+    return {
+        ...s3,
+        keyPrefix: s3.keyPrefix ?? defaultAdapterKeyPrefix(DEFAULT_S3_KEY_PREFIX, adapter),
+        ...(region === undefined ? {} : { clientConfig: { ...s3.clientConfig, region } }),
+    };
+}