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

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

@@ -1,23 +1,56 @@
+/**
+ * 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 { CompressionConfig } from './compression';
+import { type CompressionConfig } from './compression';
 import type { S3Offloader } from './s3/offloader';
+/**
+ * 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"
 }
-/** A payload stored inline as bytes in the DynamoDB item. */
-interface InlinePayloadDescriptor {
-    location: PayloadLocation.INLINE;
+/**
+ * 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 {
+interface S3PayloadDescriptor extends DescriptorBase {
     location: PayloadLocation.S3;
-    serdeType: string;
-    compressed: boolean;
     s3Key: string;
 }
 /** The result of encoding a payload. */
@@ -27,18 +60,260 @@ 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;
 }
 /**
- * Encode `value`: serialize via serde, compress (if configured), then offload
- * to S3 when the compressed bytes exceed the offloader's threshold. Returns a
- * descriptor recording how to read it back.
+ * 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` — the bytes are too
+ * large to store inline — and is raised only when there is **no** offloader
+ * and they exceed `MAX_INLINE_PAYLOAD_BYTES`. With an offloader that
+ * cell cannot arise: `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.
+ * 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>;
-/** Decode a {@link PayloadDescriptor} produced by {@link encodePayload}. */
-export declare function decodePayload<T>(descriptor: PayloadDescriptor, deps: CodecDeps): Promise<T>;
+/**
+ * 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 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`), it trips the decompression guard (`COMPRESSION_LIMIT`),
+ * 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 three 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: the bytes are checked against the form the row declares before
+ * that code is chosen, so reaching it means they are undamaged and a serializer
+ * declining to reconstruct the class they name says what *this* reader may do,
+ * not what the payload is (see `loadPayloadValue`). And `FORMAT_UNSUPPORTED`,
+ * on a row or on a payload: newer is not lost.
+ *
+ * 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 {};
-//# sourceMappingURL=codec.d.ts.map