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

package/dist/esm/shared/clock.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Hides where the current time comes from, and in which unit each reader
+ * takes it.
+ *
+ * Every timestamp, deadline and expiry this package computes through
+ * `nowIso`, `nowMs` or `nowSeconds` reads `Date.now` through here, so a test
+ * that freezes it freezes all of them at once, and under a skewed clock they
+ * agree with each other rather than disagreeing by a second. Two call sites
+ * take their own default instead of this seam — `calculateTtlTimestamp`'s
+ * `now` parameter and `createUlidFactory`'s `now` parameter, both defaulting
+ * to `Date.now` directly — so freezing this module's clock alone does not
+ * freeze them. That the ISO form sorts chronologically and that the TTL unit
+ * is floored seconds are settled here; a caller asks for the unit it needs.
+ */
+/**
+ * The current time as an ISO-8601 string.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: UTC, millisecond precision, `Z`-suffixed — the form whose byte order
+ * is its chronological order, which is why it can lead a sort key unparsed.
+ *
+ * Throws: nothing.
+ */
+export declare function nowIso(): string;
+/**
+ * The current time as epoch milliseconds.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: the millisecond, unrounded — the unit a whole-operation deadline is
+ * measured in, since a retry budget is bounded far below a second's
+ * granularity of error.
+ *
+ * Throws: nothing.
+ */
+export declare function nowMs(): number;
+/**
+ * The current time as whole epoch seconds, the unit DynamoDB's TTL uses.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: the second, floored — never a fraction, which DynamoDB would reject
+ * on the `ttl` attribute.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: every expiry stamp, expiry filter and ttl-anchor comparison in
+ * this package reads this one seam, so they agree with each other under a
+ * frozen or skewed clock rather than disagreeing by a second.
+ */
+export declare function nowSeconds(): number;

package/dist/esm/shared/clock.js

@@ -0,0 +1,9 @@
+export function nowIso() {
+    return new Date(Date.now()).toISOString();
+}
+export function nowMs() {
+    return Date.now();
+}
+export function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}

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

@@ -0,0 +1,336 @@
+/**
+ * Hides how a value becomes a stored payload and back.
+ *
+ * A value is serialized by the configured serde, gzipped when that pays, and
+ * kept inline in its row or offloaded to S3 under a key its row can be traced
+ * from, behind a versioned descriptor the row stores. Reading reverses that,
+ * and a failure that means the payload can never be read again — a corrupt
+ * body, a missing object, a descriptor no reader understands — is told apart
+ * here from one a retry might cure.
+ */
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import { type CompressionConfig } from './compression.js';
+import type { S3Offloader } from './s3/offloader.js';
+/**
+ * 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;
+/** Where an encoded payload lives. */
+export declare enum PayloadLocation {
+    INLINE = "INLINE",
+    S3 = "S3"
+}
+/**
+ * Version of the persisted descriptor shape. Absent on rows written before it
+ * existed, which read as version 1; a higher value marks a row written by a
+ * newer library and is refused rather than misread.
+ */
+export declare const DESCRIPTOR_SCHEMA_VERSION = 1;
+/** Fields every descriptor carries, whatever its location. */
+interface DescriptorBase {
+    schemaVersion?: number;
+    serdeType: string;
+    compressed: boolean;
+    /**
+     * The id of the write that produced this descriptor — the `objectId` its
+     * encode was given, and the identity a delete pins on to tell the row it
+     * observed from one another write replaced since. Optional because a row
+     * written before the field existed carries none, and a row observed without
+     * one is deleted unconditionally rather than pinned on nothing.
+     */
+    writeId?: string;
+}
+/** A payload stored inline as bytes in the DynamoDB item. */
+interface InlinePayloadDescriptor extends DescriptorBase {
+    location: PayloadLocation.INLINE;
+    bytes: Uint8Array;
+}
+/** A payload offloaded to S3, referenced by key. */
+interface S3PayloadDescriptor extends DescriptorBase {
+    location: PayloadLocation.S3;
+    s3Key: string;
+}
+/** The result of encoding a payload. */
+export type PayloadDescriptor = InlinePayloadDescriptor | S3PayloadDescriptor;
+/** Collaborators for the codec. */
+export interface CodecDeps {
+    serde: SerializerProtocol;
+    compression?: CompressionConfig;
+    offloader?: S3Offloader;
+    /**
+     * The caller's cancellation, carried into the S3 upload or download a
+     * payload costs. It belongs here rather than on a parameter of its own for
+     * the same reason `RetryOptions.signal` does: the deps object is built per
+     * call at every use site, so "these options carry a signal" is already how
+     * this package decides what a cancel may interrupt — and a path that must
+     * not be interrupted keeps building its deps without one.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * The codec collaborators an adapter context carries, with a call's signal.
+ *
+ * Accepts: `source` — the adapter's serde, compression and offloader.
+ * `signal` — the call's cancellation, carried into the S3 request a payload
+ * needs.
+ *
+ * Returns: the collaborators the codec takes.
+ *
+ * Throws: nothing.
+ */
+export declare function codecDepsOf(source: Pick<CodecDeps, 'serde' | 'compression' | 'offloader'>, signal?: AbortSignal): CodecDeps;
+/**
+ * The payload bytes a descriptor stands for: downloaded when offloaded, then
+ * decompressed. Infrastructure only, no deserialization — a caller that needs
+ * to tell a transport or permission failure from bad data does this step and
+ * {@link loadPayloadValue} separately (see
+ * `src/history/actions/get-messages.ts`).
+ *
+ * Accepts: `descriptor` — as written by {@link encodePayload}; a
+ * `schemaVersion` above this release's, or a `location` it does not know, is
+ * refused rather than guessed at. `deps.offloader` — required only for an `S3`
+ * descriptor. `scope` — the row's own leading key parts (`[threadId]`,
+ * `[...namespace, key]`, `[sessionId]`); `[]` degrades the check to the
+ * configured prefix. `deps.signal` — cancels the download of an offloaded
+ * payload, request and all; an inline one reads no bytes and ignores it.
+ *
+ * Returns: the decoded bytes.
+ *
+ * Throws: `VALIDATION` naming `descriptor` for a shape no reader could
+ * make sense of and `s3` for an offloaded row with no offloader configured;
+ * `FORMAT_UNSUPPORTED` naming `schemaVersion` for a payload a newer release
+ * wrote, which a newer reader reads fine; `VALIDATION` naming `s3Key` when
+ * the key lies outside `scope`; `ABORTED` when the signal fires during the
+ * download; `S3_OFFLOAD_FAILED` from the download; `COMPRESSION_LIMIT` or
+ * `PAYLOAD_CORRUPT` from decompression.
+ *
+ * Guarantees: an offloaded object is downloaded only when its key lies under
+ * the path `scope` produces, so a row can never point this adapter at an
+ * object it does not own.
+ */
+export declare function readPayloadBytes(descriptor: PayloadDescriptor, deps: CodecDeps, scope: readonly string[]): Promise<Uint8Array>;
+/**
+ * The value stored bytes hold, with a serde that refuses them branded rather
+ * than left bare.
+ *
+ * Accepts: `serdeType` — the row's own, handed to the serde unchanged, and the
+ * declared form {@link bytesHoldDeclaredForm} checks the bytes against.
+ * `bytes` — what {@link readPayloadBytes} returned. `deps.serde` — the
+ * serializer the adapter was configured with, which may be the caller's.
+ *
+ * Returns: whatever the serde reconstructs, typed as the caller declares.
+ *
+ * Throws: the serde's own error whenever it is already one of this library's,
+ * so `PAYLOAD_CORRUPT` from `JSON_SERDE` stays exactly what it was — as does
+ * its refusal of a `serdeType` it has no grammar for, which it brands the same
+ * `VALIDATION` naming `serde` that the classifier below reaches for on the
+ * identical row under any other serde; `PAYLOAD_CORRUPT` when the bytes are no
+ * longer the form the row declares, on whatever serde raised it; anything else
+ * as a `VALIDATION` error naming `serde`, carrying the refusal as `cause`.
+ *
+ * Guarantees: no error leaves a decode unbranded, and which serde the adapter
+ * was configured with never decides *which* brand. A rotted row read through
+ * `JSON_SERDE` reported `PAYLOAD_CORRUPT` while the identical row read through
+ * the checkpointer's own default reported the refusal below, so a caller
+ * quarantining on `PAYLOAD_CORRUPT` never matched and `history.getMessages`
+ * lost a whole conversation where it promises one dropped message. A row
+ * declaring a form neither serde writes ran the same divergence the other way,
+ * and reached further: `JSON_SERDE` ignored the declared type, so its own
+ * `JSON.parse` failure arrived here already branded and the classifier was
+ * never consulted. The serializer honours the declared form now, which is what
+ * keeps this the one place the distinction is drawn.
+ *
+ * The refusal is what remains once the bytes are known to be intact: the
+ * serializer would not reconstruct the value they name. A stored `lc`
+ * constructor record naming a class outside LangChain's allow-list is refused
+ * by `load()` with a plain `Error`, which a public boundary could only rebrand
+ * as an `UNEXPECTED_ERROR` — reporting a row's own content to the caller as an AWS
+ * failure. It is deliberately *not* classified as payload loss, for
+ * `assertKeyInScope`'s reason rather than `PAYLOAD_CORRUPT`'s: the bytes are
+ * undamaged and parse, and which classes revive is a property of **this**
+ * reader — the serde it was given, and what that serde's allow-list carries —
+ * not of the payload. A refusal that says only "this reader may not
+ * reconstruct that" is a misconfigured serde or a planted row, both of which an
+ * operator must see; writing it off would let `history.getMessages` answer with
+ * a silently shorter conversation for the one row shape most worth noticing.
+ */
+export declare function loadPayloadValue<T>(serdeType: string, bytes: Uint8Array, deps: CodecDeps): Promise<T>;
+/**
+ * The value a descriptor stands for: {@link readPayloadBytes} followed by
+ * {@link loadPayloadValue}.
+ *
+ * Accepts: as {@link readPayloadBytes}; `scope` has the same meaning.
+ *
+ * Returns: whatever the serde reconstructs, typed as the caller declares.
+ *
+ * Throws: everything {@link readPayloadBytes} throws, plus everything
+ * {@link loadPayloadValue} throws for bytes the serde will not accept —
+ * `PAYLOAD_CORRUPT` for bytes that are no longer the form the row declares,
+ * whichever serde is configured, `VALIDATION` naming `serde` for a refusal
+ * of bytes that are still intact.
+ *
+ * Guarantees: the bytes are read first, in a statement of their own. Passing
+ * `descriptor.serdeType` and the awaited read as two arguments to one call read
+ * the property *before* the guard ran, since arguments evaluate left to right —
+ * so a row whose payload is `null` raised a bare `TypeError` carrying no code,
+ * which a public boundary can only rebrand as an `UNEXPECTED_ERROR`. Every read
+ * path now answers such a row with the `VALIDATION` error naming `descriptor` that
+ * the history adapter, which reads its bytes separately, already produced.
+ */
+export declare function decodePayload<T>(descriptor: PayloadDescriptor, deps: CodecDeps, scope: readonly string[]): Promise<T>;
+/** The DynamoDB key of the row that will hold the descriptor being built. */
+interface RowKey {
+    pk: string;
+    sk: string;
+}
+/** Options controlling where an offloaded payload's S3 key is built from. */
+export interface EncodeOptions {
+    /**
+     * The identity of the row this payload belongs to, as the path segments
+     * above {@link EncodeOptions.objectId}. A reader refuses an object that lies
+     * outside the path its row's leading identifiers produce.
+     */
+    keyParts: readonly string[];
+    /**
+     * The id of the write this payload belongs to, and the key's last segment.
+     * The caller draws a fresh UUID or ULID for each write — each store put, each
+     * checkpoint put, each `putWrites` call, each history message — and passes the
+     * same one for every payload of that write, whose `keyParts` already differ.
+     * No other write uses that id, so no row another write commits names the
+     * object.
+     */
+    objectId: string;
+    /**
+     * The row's DynamoDB key, stored on the object as the backlink AWS
+     * recommends for exactly this layout: "Store the primary key value of the
+     * item as Amazon S3 metadata of the object" (*Best practices for storing
+     * large items and attributes in DynamoDB*). Nothing in this package reads it
+     * back; it exists so an out-of-band sweeper can ask DynamoDB whether an
+     * object's parent row still exists without parsing object keys.
+     */
+    row: RowKey;
+}
+/**
+ * The descriptor recording how to read `value` back: serialized, compressed if
+ * configured, and offloaded to S3 if large enough.
+ *
+ * Accepts: `value` — anything the serde can represent as at least one byte;
+ * what it cannot represent is the serde's own error, and what it represents as
+ * nothing is refused here (see {@link assertSerialisedToBytes}), whichever
+ * serde is configured. `deps.compression` — absent or `enabled: false` stores the
+ * serialized bytes as they are. `deps.offloader` — absent stores every payload
+ * inline. `deps.signal` — cancels the upload of an offloaded payload; an
+ * inline one is never sent anywhere and ignores it. `options` — the row's
+ * identity, the write's object id and the row's DynamoDB key (see
+ * {@link EncodeOptions}).
+ *
+ * Returns: an `S3` descriptor when an offloader is configured and
+ * `shouldOffload` accepts the compressed size, otherwise an `INLINE`
+ * descriptor carrying the bytes. Both record `serdeType` and `compressed`, so
+ * neither is ever inferred from the bytes on read.
+ *
+ * Throws: whatever `serde.dumpsTyped` throws; `ABORTED` when the signal
+ * fires during the upload; `S3_OFFLOAD_FAILED` from the upload; and two
+ * distinguishable `VALIDATION` errors. One names `payload`, raised either
+ * way a payload can turn out unstorable: with **no** offloader, the bytes
+ * exceed `MAX_INLINE_PAYLOAD_BYTES`; with one, `s3.thresholdBytes` is itself
+ * capped at that limit (`src/shared/validation/options.ts`, `assertS3`), so
+ * bytes too large to store inline are always at or above the threshold and
+ * offload instead — where they are refused if they exceed
+ * `s3.maxDownloadBytes`, before the upload ({@link S3Offloader.upload}). The
+ * other names `value` — it serialises to nothing (see
+ * {@link assertSerialisedToBytes}) — and is raised for an offloaded payload
+ * and an inline one alike, before either is stored.
+ */
+export declare function encodePayload<T>(value: T, deps: CodecDeps, options: EncodeOptions): Promise<PayloadDescriptor>;
+/**
+ * The part of a descriptor cleanup needs: where the payload lives and, for S3,
+ * its key. A full `PayloadDescriptor` satisfies it, and so does the projection
+ * a pre-write read returns without the inline bytes.
+ */
+export interface DescriptorRef {
+    location: PayloadLocation;
+    s3Key?: string;
+}
+/**
+ * The S3 keys of whichever descriptors are offloaded.
+ *
+ * Accepts: `descriptors` — any mix of inline and offloaded, including a
+ * projection that carries only `location` and `s3Key`, and including none. An
+ * offloaded descriptor missing its key is skipped rather than deleted blindly,
+ * and so is an entry that is not a descriptor at all: several callers read
+ * these straight off a row, and a row this library did not write can hold
+ * `null` where the descriptor belongs, or omit the attribute entirely. Widening
+ * the parameter rather than making each caller filter is what lets the `Throws`
+ * clause below hold for every caller instead of only the careful ones.
+ *
+ * Returns: the keys, in the order given; an inline payload contributes none,
+ * and neither does an absent one.
+ *
+ * Throws: nothing — this feeds cleanup, which must not fail the operation it
+ * follows.
+ */
+export declare function collectS3Keys(descriptors: readonly (DescriptorRef | null | undefined)[]): string[];
+/**
+ * True when an offloaded object no longer exists.
+ *
+ * Accepts: `error` — any error; only `S3_OFFLOAD_FAILED` carrying a `NoSuchKey`
+ * cause matches. An error with no `cause`, or one whose cause names another
+ * S3 failure, is not a missing object. Anything else a `throw` can produce —
+ * `null`, `undefined`, a primitive — carries no code and is not one either.
+ *
+ * Returns: whether the object is gone — a lifecycle sweep removed it, or a
+ * competing overwrite deleted it between a row read and the download.
+ *
+ * Throws: **nothing**, for any value. A caught value that cannot carry a
+ * property answers `false`, as `isDynamoDBLangGraphError` does, rather than
+ * raising a `TypeError` inside the `catch` that is reporting the download
+ * failure this test exists to classify.
+ */
+export declare function isMissingObjectError(error: Error): boolean;
+/**
+ * True when S3 refused to answer a download rather than answering it.
+ *
+ * Accepts: `error` — any error; only `S3_OFFLOAD_FAILED` whose cause the
+ * classifier codes `ACCESS_DENIED` matches.
+ *
+ * Returns: whether S3 declined to say anything about the object. Without
+ * `s3:ListBucket` on the bucket, S3 answers a GET of a key that does not exist
+ * with 403 rather than 404, so this is what a released object looks like to
+ * such a role — and equally what a missing `s3:GetObject` looks like. A caller
+ * settles which by other means before treating it as either.
+ *
+ * Throws: **nothing**, for any value.
+ */
+export declare function isRefusedObjectError(error: Error): boolean;
+/**
+ * True when a payload can never be read again, as opposed to a failure that may
+ * succeed on retry or after a configuration fix (throttling, network,
+ * permissions).
+ *
+ * Accepts: `error` — any error. Permanent are: its object is gone
+ * ({@link isMissingObjectError}), its bytes are not the form the row declares
+ * (`PAYLOAD_CORRUPT`), or the row's own descriptor is unreadable
+ * ({@link isUnreadableDescriptor}). Everything else is false, including an
+ * error that carries no code at all, and including four refusals that look
+ * like loss and are not. The `s3Key` scope refusal: a row pointing outside
+ * its own path is a configuration or tenancy fault to report, not a payload
+ * to write off. The `serde` refusal, on the same reasoning (see
+ * `loadPayloadValue`). `FORMAT_UNSUPPORTED`, on a row or on a payload: newer
+ * is not lost. And `COMPRESSION_LIMIT`: a payload larger than this reader
+ * inflates is intact, and a reader with a larger cap reads it. From this
+ * release on, this package never compresses a payload past its writer's own
+ * cap; a payload an earlier release compressed — which did not check it —
+ * can still trip a smaller one here.
+ *
+ * Returns: whether a caller should report rather than retry.
+ *
+ * Throws: **nothing**, for any value a `throw` can produce. One that cannot
+ * carry a code is not permanent loss, which is the same answer an uncoded
+ * `Error` gets.
+ */
+export declare function isPermanentPayloadLoss(error: Error): boolean;
+export {};

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

@@ -0,0 +1,150 @@
+import { DynamoDBLangGraphError, hasErrorCode, isDynamoDBLangGraphError, toError, } from '../errors/base-error.js';
+import { classifyAwsError, isMissingObject } from '../errors/classify.js';
+import { ErrorCode } from '../errors/error-code.js';
+import { validationError } from '../errors/errors.js';
+import { truncateForLog } from '../logging/truncate.js';
+import { compress, decompress, } from './compression.js';
+import { bytesHoldDeclaredForm } from './json-serde.js';
+export const MAX_INLINE_PAYLOAD_BYTES = 400 * 1024 - 8 * 1024;
+export var PayloadLocation;
+(function (PayloadLocation) {
+    PayloadLocation["INLINE"] = "INLINE";
+    PayloadLocation["S3"] = "S3";
+})(PayloadLocation || (PayloadLocation = {}));
+export const DESCRIPTOR_SCHEMA_VERSION = 1;
+export function codecDepsOf(source, signal) {
+    return {
+        serde: source.serde,
+        compression: source.compression,
+        offloader: source.offloader,
+        signal,
+    };
+}
+function configuredOffloader(deps) {
+    if (!deps.offloader) {
+        throw validationError("this row's payload is offloaded to S3 but the adapter has no `s3` configuration; " +
+            'configure the bucket the writer used', 's3');
+    }
+    return deps.offloader;
+}
+function assertReadableDescriptor(descriptor) {
+    if (descriptor === null || typeof descriptor !== 'object') {
+        throw validationError(`payload descriptor is ${descriptor === null ? 'null' : typeof descriptor}, not a descriptor ` +
+            'this library wrote', 'descriptor');
+    }
+    const version = descriptor.schemaVersion ?? DESCRIPTOR_SCHEMA_VERSION;
+    if (version > DESCRIPTOR_SCHEMA_VERSION) {
+        const written = truncateForLog(String(version));
+        throw new DynamoDBLangGraphError(`this payload was written in descriptor schema version ${written}; this version of the ` +
+            `library reads up to ${DESCRIPTOR_SCHEMA_VERSION} — upgrade to read it`, ErrorCode.FORMAT_UNSUPPORTED, { field: 'schemaVersion' });
+    }
+    const locations = Object.values(PayloadLocation);
+    if (!locations.includes(descriptor.location)) {
+        const location = truncateForLog(String(JSON.stringify(descriptor.location)));
+        throw validationError(`payload descriptor has an unknown location ${location}`, 'descriptor');
+    }
+    if (descriptor.location === PayloadLocation.S3 && typeof descriptor.s3Key !== 'string') {
+        throw validationError('payload descriptor is offloaded but names no object key', 'descriptor');
+    }
+    if (descriptor.location === PayloadLocation.INLINE && !ArrayBuffer.isView(descriptor.bytes)) {
+        throw validationError('payload descriptor is inline but carries no bytes', 'descriptor');
+    }
+}
+export async function readPayloadBytes(descriptor, deps, scope) {
+    assertReadableDescriptor(descriptor);
+    let raw;
+    if (descriptor.location === PayloadLocation.S3) {
+        const offloader = configuredOffloader(deps);
+        offloader.assertOwnedKey(descriptor.s3Key, scope);
+        raw = await offloader.download(descriptor.s3Key, deps.signal);
+    }
+    else {
+        raw = descriptor.bytes;
+    }
+    return decompress(raw, descriptor.compressed, deps.compression?.maxDecompressedBytes);
+}
+export async function loadPayloadValue(serdeType, bytes, deps) {
+    try {
+        return (await deps.serde.loadsTyped(serdeType, bytes));
+    }
+    catch (error) {
+        const refusal = toError(error);
+        if (isDynamoDBLangGraphError(refusal))
+            throw refusal;
+        if (!bytesHoldDeclaredForm(serdeType, bytes)) {
+            throw new DynamoDBLangGraphError('the stored payload is no longer the form this row declares, so no serde could decode ' +
+                'it; the refusal that proved it is attached as `cause`', ErrorCode.PAYLOAD_CORRUPT, {}, refusal);
+        }
+        throw validationError('the configured serde refused the payload stored in this row: the bytes parse, but the ' +
+            'serializer would not reconstruct the value they name — a stored `lc` constructor record ' +
+            'naming a class outside its allow-list reads this way, as does a serde that did not ' +
+            'write these bytes. The refusal itself is attached as `cause`', 'serde', refusal);
+    }
+}
+export async function decodePayload(descriptor, deps, scope) {
+    const bytes = await readPayloadBytes(descriptor, deps, scope);
+    return loadPayloadValue(descriptor.serdeType, bytes, deps);
+}
+function assertInlinePayloadFits(bytes, deps) {
+    if (bytes.length <= MAX_INLINE_PAYLOAD_BYTES)
+        return;
+    const hint = deps.compression?.enabled
+        ? ''
+        : ', or enable compression if the data compresses well';
+    throw validationError(`payload of ${bytes.length} bytes exceeds the ${MAX_INLINE_PAYLOAD_BYTES}-byte inline limit ` +
+        `(DynamoDB items are capped at 400 KB); configure s3 offloading${hint}`, 'payload');
+}
+function assertSerialisedToBytes(raw) {
+    if (raw.length > 0)
+        return;
+    throw validationError('value serialises to zero bytes, which no reader can parse back: a function, a symbol ' +
+        'or any value the configured serde drops encodes to nothing. Store a value the serde ' +
+        'can represent, or configure one that refuses it.', 'value');
+}
+export async function encodePayload(value, deps, options) {
+    const [serdeType, raw] = await deps.serde.dumpsTyped(value);
+    assertSerialisedToBytes(raw);
+    const { bytes, compressed } = deps.compression
+        ? await compress(raw, deps.compression)
+        : { bytes: raw, compressed: false };
+    const base = {
+        schemaVersion: DESCRIPTOR_SCHEMA_VERSION,
+        serdeType,
+        compressed,
+        writeId: options.objectId,
+    };
+    if (deps.offloader && deps.offloader.shouldOffload(bytes)) {
+        const s3Key = deps.offloader.buildKey(options.keyParts, options.objectId);
+        await deps.offloader.upload(s3Key, bytes, options.row, deps.signal);
+        return { ...base, location: PayloadLocation.S3, s3Key };
+    }
+    if (!deps.offloader)
+        assertInlinePayloadFits(bytes, deps);
+    return { ...base, location: PayloadLocation.INLINE, bytes };
+}
+export function collectS3Keys(descriptors) {
+    const keys = [];
+    for (const descriptor of descriptors) {
+        if (descriptor?.location === PayloadLocation.S3 && descriptor.s3Key !== undefined) {
+            keys.push(descriptor.s3Key);
+        }
+    }
+    return keys;
+}
+export function isMissingObjectError(error) {
+    return (hasErrorCode(error, ErrorCode.S3_OFFLOAD_FAILED) &&
+        error.cause !== undefined &&
+        isMissingObject(error.cause));
+}
+export function isRefusedObjectError(error) {
+    return (hasErrorCode(error, ErrorCode.S3_OFFLOAD_FAILED) &&
+        classifyAwsError(error.cause) === ErrorCode.ACCESS_DENIED);
+}
+function isUnreadableDescriptor(error) {
+    return hasErrorCode(error, ErrorCode.VALIDATION) && error.context.field === 'descriptor';
+}
+export function isPermanentPayloadLoss(error) {
+    return (hasErrorCode(error, ErrorCode.PAYLOAD_CORRUPT) ||
+        isMissingObjectError(error) ||
+        isUnreadableDescriptor(error));
+}

package/dist/esm/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/esm/shared/codec/compression.js

@@ -0,0 +1,40 @@
+import { promisify } from 'node:util';
+import { gunzip, gzip } from 'node:zlib';
+import { DynamoDBLangGraphError } from '../errors/base-error.js';
+import { ErrorCode } from '../errors/error-code.js';
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+const COMPRESSION_GAIN_RATIO = 0.9;
+export const DEFAULT_COMPRESSION_MIN_BYTES = 1024;
+export const DEFAULT_COMPRESSION_LEVEL = 6;
+export const DEFAULT_MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
+export async function compress(data, config) {
+    const minSize = config.minSizeBytes ?? DEFAULT_COMPRESSION_MIN_BYTES;
+    const readable = config.maxDecompressedBytes ?? DEFAULT_MAX_DECOMPRESSED_BYTES;
+    if (!config.enabled || data.length < minSize || data.length > readable) {
+        return { bytes: data, compressed: false };
+    }
+    const level = config.level ?? 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 DynamoDBLangGraphError('the stored payload is marked compressed but is not valid gzip, so it cannot be decoded', ErrorCode.PAYLOAD_CORRUPT, {}, cause);
+}
+export async function decompress(data, compressed, maxBytes = 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 DynamoDBLangGraphError(`Refusing to decompress: output would exceed ${maxBytes} bytes`, ErrorCode.COMPRESSION_LIMIT, {}, error);
+        }
+        throw corruptPayload(error);
+    }
+}