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

package/dist/cjs/shared/codec/compression.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Hides whether a stored payload's bytes are gzipped.
+ *
+ * When gzip is attempted, when its output is not worth keeping, and how a read
+ * refuses a gzip bomb or a stream that is not gzip are decided here. A caller
+ * carries only the flag this module returns, recorded beside the bytes, so
+ * compression is never guessed from the bytes and the thresholds can change
+ * without touching the codec that stores them.
+ */
+/** 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;
+/** Configuration for payload compression. */
+export interface CompressionConfig {
+    enabled: boolean;
+    minSizeBytes?: number;
+    level?: number;
+    maxDecompressedBytes?: number;
+}
+/** The bytes to store plus whether they were gzip-compressed. */
+export interface CompressionResult {
+    bytes: Uint8Array;
+    compressed: boolean;
+}
+/**
+ * The bytes to store for `data`, gzipped when that is worth doing.
+ *
+ * Accepts: `data` — any length, including empty. `config.enabled` — `false`
+ * returns the input untouched. `config.minSizeBytes` — the size below which
+ * gzip is not attempted, default {@link DEFAULT_COMPRESSION_MIN_BYTES}.
+ * `config.level` — zlib level 0–9, default {@link DEFAULT_COMPRESSION_LEVEL}.
+ * `config.maxDecompressedBytes` — a payload larger than it is stored
+ * uncompressed, since no reader configured like this writer would inflate it.
+ *
+ * Returns: `compressed: true` only when gzip beat the input by more than 10%;
+ * otherwise the input bytes and `compressed: false`. The flag is recorded in
+ * the payload descriptor, so compression is never inferred from the bytes on
+ * read.
+ *
+ * Throws: whatever `zlib.gzip` rejects with.
+ */
+export declare function compress(data: Uint8Array, config: CompressionConfig): Promise<CompressionResult>;
+/**
+ * The payload bytes `data` stands for, gunzipped when the row says so.
+ *
+ * Accepts: `data` — the bytes as stored. `compressed` — the descriptor's own
+ * flag; `false` returns `data` unchanged and inspects nothing. `maxBytes` — the
+ * decompressed-output cap, default {@link DEFAULT_MAX_DECOMPRESSED_BYTES}; a
+ * reader that configures no compression uses that default whatever the writer
+ * used.
+ *
+ * Returns: the decoded bytes.
+ *
+ * Throws: `COMPRESSION_LIMIT` when the output would exceed `maxBytes`, and
+ * `PAYLOAD_CORRUPT` when `compressed` is true but the bytes are not gzip.
+ * `PAYLOAD_CORRUPT` is permanent for that payload
+ * ({@link isPermanentPayloadLoss}). `COMPRESSION_LIMIT` is this reader's
+ * limit, not the payload's loss: a reader with a larger cap reads it. From
+ * this release on, `compress` never produces a payload past its writer's own
+ * cap; a payload an earlier release compressed — which did not check it —
+ * can still exceed a smaller `maxBytes` here.
+ */
+export declare function decompress(data: Uint8Array, compressed: boolean, maxBytes?: number): Promise<Uint8Array>;

package/dist/cjs/shared/codec/compression.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_DECOMPRESSED_BYTES = exports.DEFAULT_COMPRESSION_LEVEL = exports.DEFAULT_COMPRESSION_MIN_BYTES = void 0;
+exports.compress = compress;
+exports.decompress = decompress;
+const node_util_1 = require("node:util");
+const node_zlib_1 = require("node:zlib");
+const base_error_js_1 = require("../errors/base-error.js");
+const error_code_js_1 = require("../errors/error-code.js");
+const gzipAsync = (0, node_util_1.promisify)(node_zlib_1.gzip);
+const gunzipAsync = (0, node_util_1.promisify)(node_zlib_1.gunzip);
+const COMPRESSION_GAIN_RATIO = 0.9;
+exports.DEFAULT_COMPRESSION_MIN_BYTES = 1024;
+exports.DEFAULT_COMPRESSION_LEVEL = 6;
+exports.DEFAULT_MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
+async function compress(data, config) {
+    const minSize = config.minSizeBytes ?? exports.DEFAULT_COMPRESSION_MIN_BYTES;
+    const readable = config.maxDecompressedBytes ?? exports.DEFAULT_MAX_DECOMPRESSED_BYTES;
+    if (!config.enabled || data.length < minSize || data.length > readable) {
+        return { bytes: data, compressed: false };
+    }
+    const level = config.level ?? exports.DEFAULT_COMPRESSION_LEVEL;
+    const gzipped = new Uint8Array(await gzipAsync(data, { level }));
+    if (gzipped.length >= data.length * COMPRESSION_GAIN_RATIO) {
+        return { bytes: data, compressed: false };
+    }
+    return { bytes: gzipped, compressed: true };
+}
+function corruptPayload(cause) {
+    return new base_error_js_1.DynamoDBLangGraphError('the stored payload is marked compressed but is not valid gzip, so it cannot be decoded', error_code_js_1.ErrorCode.PAYLOAD_CORRUPT, {}, cause);
+}
+async function decompress(data, compressed, maxBytes = exports.DEFAULT_MAX_DECOMPRESSED_BYTES) {
+    if (!compressed)
+        return data;
+    try {
+        return new Uint8Array(await gunzipAsync(data, { maxOutputLength: maxBytes }));
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ERR_BUFFER_TOO_LARGE') {
+            throw new base_error_js_1.DynamoDBLangGraphError(`Refusing to decompress: output would exceed ${maxBytes} bytes`, error_code_js_1.ErrorCode.COMPRESSION_LIMIT, {}, error);
+        }
+        throw corruptPayload(error);
+    }
+}

package/dist/cjs/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/cjs/shared/codec/json-serde.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSON_SERDE = void 0;
+exports.bytesHoldDeclaredForm = bytesHoldDeclaredForm;
+const base_error_js_1 = require("../errors/base-error.js");
+const error_code_js_1 = require("../errors/error-code.js");
+const errors_js_1 = require("../errors/errors.js");
+const truncate_js_1 = require("../logging/truncate.js");
+exports.JSON_SERDE = {
+    async dumpsTyped(value) {
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            throw (0, errors_js_1.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', (0, base_error_js_1.toError)(error));
+        }
+        if (text === undefined) {
+            throw (0, errors_js_1.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 (0, errors_js_1.validationError)(`this serializer reads only the \`${JSON_SERDE_TYPE}\` form it writes, and this payload ` +
+                `declares ${(0, truncate_js_1.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 (0, errors_js_1.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 base_error_js_1.DynamoDBLangGraphError('the stored payload is not the JSON this serializer wrote, so it cannot be decoded', error_code_js_1.ErrorCode.PAYLOAD_CORRUPT, {}, error);
+        }
+    },
+};
+Object.freeze(exports.JSON_SERDE);
+const JSON_SERDE_TYPE = 'json';
+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/{shared → cjs/shared}/codec/s3/client-types.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 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. */
@@ -18,10 +27,20 @@ export interface S3ClientOptions {
  * variable is accepted as it is.
  */
 export type S3ClientConfigLike = S3ClientOptions | object;
-/** The options of a config, read through the structural type. */
+/**
+ * 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`. */
-export interface S3CommandLike {
+interface S3CommandLike {
     input: object;
 }
 /**
@@ -32,3 +51,4 @@ export interface S3ClientLike {
     send(command: S3CommandLike, options?: object): Promise<object>;
     destroy(): void;
 }
+export {};

package/dist/{shared → cjs/shared}/codec/s3/client-types.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.s3ClientOptions = s3ClientOptions;
-/** The options of a config, read through the structural type. */
 function s3ClientOptions(config) {
     return (config ?? {});
 }

package/dist/cjs/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/cjs/shared/codec/s3/client.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadS3Sdk = loadS3Sdk;
+exports.withS3ClientDefaults = withS3ClientDefaults;
+exports.createDefaultS3Client = createDefaultS3Client;
+const client_js_1 = require("../../dynamodb/client.js");
+const base_error_js_1 = require("../../errors/base-error.js");
+const errors_js_1 = require("../../errors/errors.js");
+const client_types_js_1 = require("./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 (0, errors_js_1.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;
+}
+async function loadS3Sdk() {
+    if (!sdkPromise) {
+        sdkPromise = Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3'))).catch((error) => {
+            sdkPromise = undefined;
+            return wrapMissingPeer(error);
+        });
+    }
+    try {
+        return await sdkPromise;
+    }
+    catch (error) {
+        throw (0, base_error_js_1.copyForCaller)(error);
+    }
+}
+function withS3ClientDefaults(config) {
+    const options = (0, client_types_js_1.s3ClientOptions)(config);
+    return {
+        ...options,
+        maxAttempts: options.maxAttempts ?? 1,
+        requestHandler: options.requestHandler ?? { socketTimeout: client_js_1.DEFAULT_SOCKET_TIMEOUT_MS },
+    };
+}
+async function createDefaultS3Client(config) {
+    const { S3Client: S3ClientCtor } = await loadS3Sdk();
+    return new S3ClientCtor(withS3ClientDefaults(config));
+}