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

package/dist/{store/internal/rows.js → esm/store/internal/rows.d.ts}

@@ -1,49 +1,25 @@
-"use strict";
 /**
  * Hides the store's key layout and how an item becomes a row and back.
  *
  * An item's namespace root is its partition and the rest of its namespace,
  * with its key, is its sort key, so a prefix search is a key-range query. How
  * those keys are composed, which attributes a row carries — its revision token,
- * timestamps, embeddings, recency-index keys — how a value is encoded into one
- * and decoded out, and which rows a read admits as this adapter's items are
- * decided here.
+ * timestamps, embeddings — how a value is encoded into one and decoded out,
+ * and which rows a read admits as this adapter's items are decided here.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.REVISION_ATTRIBUTE = void 0;
-exports.storePartitionPrefix = storePartitionPrefix;
-exports.partitionKey = partitionKey;
-exports.sortKey = sortKey;
-exports.sortKeyPrefix = sortKeyPrefix;
-exports.namespaceMatchesPrefix = namespaceMatchesPrefix;
-exports.itemRowKey = itemRowKey;
-exports.scopedQuery = scopedQuery;
-exports.storeScan = storeScan;
-exports.projectKeys = projectKeys;
-exports.readExisting = readExisting;
-exports.existingFrom = existingFrom;
-exports.parseStoreRow = parseStoreRow;
-exports.parseWholeStoreRow = parseWholeStoreRow;
-exports.buildStoreRow = buildStoreRow;
-exports.readStoreItem = readStoreItem;
-exports.storeIndexTarget = storeIndexTarget;
-const node_crypto_1 = require("node:crypto");
-const codec_1 = require("../../shared/codec/codec");
-const recency_index_1 = require("../../shared/dynamodb/recency-index");
-const retry_1 = require("../../shared/dynamodb/retry");
-const table_schema_1 = require("../../shared/dynamodb/table-schema");
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { Item } from '@langchain/langgraph-checkpoint';
+import { type DescriptorRef, type PayloadDescriptor } from '../../shared/codec/codec.js';
+import type { AttributeMap } from '../../shared/dynamodb/client.js';
+import { type RowKey } from '../../shared/dynamodb/table-schema.js';
+import type { JsonValue } from './filter.js';
+import type { StoreContext } from './setup.js';
 /**
  * The attribute an item row carries its revision token in, rewritten on every
  * put. A put's compare-and-swap and a delete's pin both hold the row to the
  * token they observed.
  */
-exports.REVISION_ATTRIBUTE = 'rev';
-/**
- * Adapter tag prefixed to every store partition key — see the equivalent in
- * checkpointer/internal/rows.ts for why the three adapters' partitions must
- * not overlap on a shared table.
- */
-const ADAPTER_PARTITION_PREFIX = `${table_schema_1.ADAPTER_TAGS.store}${table_schema_1.KEY_SEPARATOR}`;
+export declare const REVISION_ATTRIBUTE = "rev";
 /**
  * The tag every store partition key starts with.
  *
@@ -54,9 +30,7 @@ const ADAPTER_PARTITION_PREFIX = `${table_schema_1.ADAPTER_TAGS.store}${table_sc
  *
  * Throws: nothing.
  */
-function storePartitionPrefix() {
-    return ADAPTER_PARTITION_PREFIX;
-}
+export declare function storePartitionPrefix(): string;
 /**
  * Partition key for an item: the adapter tag plus the scope-root element.
  *
@@ -71,9 +45,7 @@ function storePartitionPrefix() {
  *
  * Throws: nothing.
  */
-function partitionKey(namespace) {
-    return `${ADAPTER_PARTITION_PREFIX}${namespace[0]}`;
-}
+export declare function partitionKey(namespace: string[]): string;
 /**
  * Sort key: the rest of the namespace plus the key, separator-joined.
  *
@@ -85,9 +57,7 @@ function partitionKey(namespace) {
  *
  * Throws: nothing.
  */
-function sortKey(namespace, key) {
-    return [...namespace.slice(1), key].join(table_schema_1.KEY_SEPARATOR);
-}
+export declare function sortKey(namespace: string[], key: string): string;
 /**
  * `begins_with` prefix selecting a scoped subtree within `prefix[0]`'s
  * partition.
@@ -101,10 +71,7 @@ function sortKey(namespace, key) {
  *
  * Throws: nothing.
  */
-function sortKeyPrefix(prefix) {
-    const rest = prefix.slice(1);
-    return rest.length === 0 ? '' : `${rest.join(table_schema_1.KEY_SEPARATOR)}${table_schema_1.KEY_SEPARATOR}`;
-}
+export declare function sortKeyPrefix(prefix: string[]): string;
 /**
  * Whether `namespace` starts with `prefix`, element by element.
  *
@@ -117,11 +84,7 @@ function sortKeyPrefix(prefix) {
  *
  * Throws: nothing.
  */
-function namespaceMatchesPrefix(namespace, prefix) {
-    if (prefix.length > namespace.length)
-        return false;
-    return prefix.every((element, index) => namespace[index] === element);
-}
+export declare function namespaceMatchesPrefix(namespace: string[], prefix: string[]): boolean;
 /**
  * The key of an item's row.
  *
@@ -132,9 +95,10 @@ function namespaceMatchesPrefix(namespace, prefix) {
  *
  * Throws: nothing.
  */
-function itemRowKey(address) {
-    return { PK: partitionKey(address.namespace), SK: sortKey(address.namespace, address.key) };
-}
+export declare function itemRowKey(address: {
+    namespace: string[];
+    key: string;
+}): RowKey;
 /**
  * Query input for a scoped prefix.
  *
@@ -148,23 +112,7 @@ function itemRowKey(address) {
  *
  * Throws: nothing.
  */
-function scopedQuery(tableName, prefix) {
-    const skPrefix = sortKeyPrefix(prefix);
-    if (skPrefix.length === 0) {
-        return {
-            TableName: tableName,
-            KeyConditionExpression: '#pk = :pk',
-            ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE },
-            ExpressionAttributeValues: { ':pk': partitionKey(prefix) },
-        };
-    }
-    return {
-        TableName: tableName,
-        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
-        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_1.SORT_KEY_ATTRIBUTE },
-        ExpressionAttributeValues: { ':pk': partitionKey(prefix), ':skp': skPrefix },
-    };
-}
+export declare function scopedQuery(tableName: string, prefix: string[]): QueryCommandInput;
 /**
  * Scan input for the rootless case, filtered to store items only.
  *
@@ -194,14 +142,7 @@ function scopedQuery(tableName, prefix) {
  *
  * Throws: nothing.
  */
-function storeScan(tableName) {
-    return {
-        TableName: tableName,
-        FilterExpression: 'begins_with(#pk, :pkp) AND attribute_exists(#ns)',
-        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#ns': 'namespace' },
-        ExpressionAttributeValues: { ':pkp': storePartitionPrefix() },
-    };
-}
+export declare function storeScan(tableName: string): ScanCommandInput;
 /**
  * Restrict a Query/Scan to the attributes `parseStoreRow` needs, leaving the
  * payload behind: a namespace listing never reads a value.
@@ -220,24 +161,39 @@ function storeScan(tableName) {
  * Guarantees: RCU is billed on the stored size regardless, so the saving is
  * transfer and unmarshalling, not cost.
  */
-function projectKeys(params) {
-    return {
-        ...params,
-        ProjectionExpression: `${table_schema_1.PARTITION_KEY_ATTRIBUTE}, ${table_schema_1.SORT_KEY_ATTRIBUTE}, #ns, #key, #v`,
-        ExpressionAttributeNames: {
-            ...params.ExpressionAttributeNames,
-            '#ns': 'namespace',
-            '#key': 'key',
-            '#v': 'v',
-        },
-    };
+export declare function projectKeys<T extends QueryCommandInput | ScanCommandInput>(params: T): T;
+/** The previous row's createdAt, expiry, payload descriptor and revision. */
+export interface ExistingRowMeta {
+    exists: boolean;
+    createdAt?: string;
+    /** The row's expiry stamp in epoch seconds, when it carries one. */
+    ttl?: number;
+    value?: DescriptorRef;
+    revision?: string;
 }
+/**
+ * Whether a row a put is about to replace is an item to its readers.
+ *
+ * A row past its `ttl` is hidden from `get`, from every search and from every
+ * listing until DynamoDB's sweep removes it, which can lag for days; a put over
+ * one is a creation, not an update. The row's revision and descriptor still
+ * count — the swap must pin the row that is physically there and release the
+ * object it names — so this is asked only of what the put inherits.
+ *
+ * Accepts: `existing` — what {@link readExisting} or {@link existingFrom} read.
+ *
+ * Returns: true when there is a row and it has not expired.
+ *
+ * Throws: nothing.
+ */
+export declare function isLiveRow(existing: ExistingRowMeta): boolean;
 /**
  * Read the fields a put needs from the row it is about to replace, in one
- * strongly-consistent projection: `createdAt` to preserve, the descriptor's
- * location and S3 key to clean up afterwards (never its inline bytes, which
- * can be hundreds of kilobytes the write would only discard), and the
- * revision the compare-and-swap pins.
+ * strongly-consistent projection: `createdAt` to preserve and the `ttl` that
+ * decides whether it is preserved, the descriptor's location and S3 key to
+ * clean up afterwards (never its inline bytes, which can be hundreds of
+ * kilobytes the write would only discard), and the revision the
+ * compare-and-swap pins.
  *
  * Lives apart from `actions/put.ts` so `item-write.ts` can re-read on a lost swap
  * without importing its own caller.
@@ -254,22 +210,7 @@ function projectKeys(params) {
  * Guarantees: strongly consistent — a put must supersede the row that is really
  * there, not one a replica still shows.
  */
-async function readExisting(context, key) {
-    const existing = await (0, retry_1.withDynamoDBRetry)((request) => context.client.get({
-        TableName: context.tableName,
-        Key: key,
-        ConsistentRead: true,
-        ProjectionExpression: '#c, #r, #v.#loc, #v.#s3k',
-        ExpressionAttributeNames: {
-            '#c': 'createdAt',
-            '#r': exports.REVISION_ATTRIBUTE,
-            '#v': 'value',
-            '#loc': 'location',
-            '#s3k': 's3Key',
-        },
-    }, request), context.retry);
-    return existingFrom(existing.Item);
-}
+export declare function readExisting(context: StoreContext, key: RowKey): Promise<ExistingRowMeta>;
 /**
  * Project a raw row onto {@link ExistingRowMeta}.
  *
@@ -281,13 +222,37 @@ async function readExisting(context, key) {
  *
  * Throws: nothing.
  */
-function existingFrom(item) {
-    return {
-        exists: item !== undefined,
-        createdAt: item?.createdAt,
-        value: item?.value,
-        revision: item?.[exports.REVISION_ATTRIBUTE],
-    };
+export declare function existingFrom(item: AttributeMap | undefined): ExistingRowMeta;
+/** The DynamoDB item backing a single stored value. */
+export interface StoreItemRow {
+    PK: string;
+    SK: string;
+    /** Row format version; absent on rows written before it existed (see `table-schema.ts`). */
+    v?: number;
+    namespace: string[];
+    key: string;
+    value: PayloadDescriptor;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * One vector per extracted path, scored by best match on read. Absent when
+     * the value has no indexable text, or when a `vectorBackend` holds the
+     * vectors instead.
+     */
+    embeddings?: number[][];
+    /**
+     * The single joined vector rows carried before the store embedded each path
+     * separately. Never written now; still read, and scored as a one-element
+     * list, so rows written by an earlier version rank exactly as they did.
+     */
+    embedding?: number[];
+    ttl?: number;
+    /**
+     * Revision token, rewritten on every put. Pins the compare-and-swap that
+     * keeps two concurrent overwrites from both deleting the same superseded S3
+     * object. Optional: rows written before 0.9.0 carry none.
+     */
+    rev?: string;
 }
 /**
  * Narrow a raw scanned row to a {@link StoreItemRow}, or `undefined` for a
@@ -311,18 +276,7 @@ function existingFrom(item) {
  * attribute names it may no longer use. Skipping it would hide an item that
  * exists.
  */
-function parseStoreRow(raw) {
-    // The version first. A later format may compose the row's key from
-    // attributes this one does not know, so testing the shape first reads such a
-    // row as foreign and hides an item that is there.
-    (0, table_schema_1.assertReadableRow)(raw, 'store item');
-    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
-        return undefined;
-    const record = raw;
-    const consistent = record.PK === partitionKey(record.namespace) &&
-        record.SK === sortKey(record.namespace, record.key);
-    return consistent ? record : undefined;
-}
+export declare function parseStoreRow(raw: AttributeMap): StoreItemRow | undefined;
 /**
  * The same narrowing for a call site that needs the *whole* row, not just its
  * identity: {@link readStoreItem} reads the timestamps as well as the payload,
@@ -345,12 +299,21 @@ function parseStoreRow(raw) {
  *
  * Throws: as {@link parseStoreRow}.
  */
-function parseWholeStoreRow(raw) {
-    const record = parseStoreRow(raw);
-    if (record === undefined)
-        return undefined;
-    const stamped = typeof record.createdAt === 'string' && typeof record.updatedAt === 'string';
-    return stamped ? record : undefined;
+export declare function parseWholeStoreRow(raw: AttributeMap): StoreItemRow | undefined;
+/** Fields controlling a stored item's timestamps, embeddings, ttl and revision token. */
+export interface BuildRowOptions {
+    createdAt: string;
+    updatedAt: string;
+    embeddings?: number[][];
+    ttlTimestamp?: number;
+    /**
+     * The row's revision token, unique per `put` call. It is the value a
+     * concurrent overwrite pins with a compare-and-swap, so each writer can tell
+     * whether the row it read is still the row it is replacing, and it is the
+     * object id an offloaded value is uploaded under. A fresh UUID is drawn when
+     * it is absent.
+     */
+    rev?: string;
 }
 /**
  * Encode a value into the DynamoDB record for a stored item.
@@ -362,44 +325,20 @@ function parseWholeStoreRow(raw) {
  * reads back, and an offloaded value's key ends in; absent, a fresh UUID is
  * drawn, before the value is encoded.
  *
- * Returns: the complete row, including the recency-index attributes: a store
- * item is listed across partitions by a rootless search, so it is indexed.
+ * Returns: the complete row. It carries no recency-index keys: no store read
+ * uses that index.
  *
  * Throws: `VALIDATION` naming `value` for a value with no JSON
- * representation; `S3_OFFLOAD_FAILED` when an offloaded payload cannot be
- * uploaded. Encoding happens before any write, so a value that cannot be stored
- * never half-writes a row.
+ * representation, or `payload` for one too large to store inline without
+ * `s3`, or, once offloaded, larger than `s3.maxDownloadBytes`;
+ * `S3_OFFLOAD_FAILED` when an offloaded payload cannot be uploaded. Encoding
+ * happens before any write, so a value that cannot be stored never
+ * half-writes a row.
  */
-async function buildStoreRow(context, address, value, options) {
-    const { namespace, key } = address;
-    const pk = partitionKey(namespace);
-    const sk = sortKey(namespace, key);
-    const rev = options.rev ?? (0, node_crypto_1.randomUUID)();
-    const descriptor = await (0, codec_1.encodePayload)(value, (0, codec_1.codecDepsOf)(context), {
-        keyParts: [...namespace, key],
-        objectId: rev,
-        row: { pk, sk },
-    });
-    // Store items are listed across partitions by a rootless search, so they are indexed.
-    const index = (0, recency_index_1.indexKeys)('STORE', sk, options.updatedAt, context.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS);
-    const record = {
-        PK: pk,
-        SK: sk,
-        v: table_schema_1.ROW_FORMAT_VERSION,
-        ...index,
-        namespace,
-        key,
-        value: descriptor,
-        createdAt: options.createdAt,
-        updatedAt: options.updatedAt,
-        rev,
-    };
-    if (options.embeddings)
-        record.embeddings = options.embeddings;
-    if (options.ttlTimestamp !== undefined)
-        record.ttl = options.ttlTimestamp;
-    return record;
-}
+export declare function buildStoreRow(context: StoreContext, address: {
+    namespace: string[];
+    key: string;
+}, value: Record<string, JsonValue>, options: BuildRowOptions): Promise<StoreItemRow>;
 /**
  * Decode a DynamoDB record back into a store {@link Item}.
  *
@@ -417,31 +356,4 @@ async function buildStoreRow(context, address, value, options) {
  * including the missing-object error `getItem` resolves against a concurrent
  * overwrite.
  */
-async function readStoreItem(context, record, signal) {
-    const value = await (0, codec_1.decodePayload)(record.value, (0, codec_1.codecDepsOf)(context, signal), [...record.namespace, record.key]);
-    return {
-        namespace: record.namespace,
-        key: record.key,
-        value,
-        createdAt: new Date(record.createdAt),
-        updatedAt: new Date(record.updatedAt),
-    };
-}
-/**
- * Where a store row sits in the recency index, for a row written before the
- * index existed.
- *
- * Accepts: `row` — any row of the table.
- *
- * Returns: an item row's identity — its sort key, at its own `updatedAt` — or
- * `undefined` for a row of another adapter.
- *
- * Throws: nothing.
- */
-function storeIndexTarget(row) {
-    const pk = typeof row.PK === 'string' ? row.PK : '';
-    const sk = typeof row.SK === 'string' ? row.SK : '';
-    if (!pk.startsWith(storePartitionPrefix()))
-        return undefined;
-    return { tag: 'STORE', id: sk, at: (0, recency_index_1.backfilledAt)(row.updatedAt) };
-}
+export declare function readStoreItem(context: StoreContext, record: StoreItemRow, signal?: AbortSignal): Promise<Item>;

package/dist/esm/store/internal/rows.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { nowSeconds } from '../../shared/clock.js';
+import { codecDepsOf, decodePayload, encodePayload, } from '../../shared/codec/codec.js';
+import { withDynamoDBRetry } from '../../shared/dynamodb/retry.js';
+import { ADAPTER_TAGS, assertReadableRow, isExpiredRow, KEY_SEPARATOR, PARTITION_KEY_ATTRIBUTE, ROW_FORMAT_VERSION, SORT_KEY_ATTRIBUTE, } from '../../shared/dynamodb/table-schema.js';
+export const REVISION_ATTRIBUTE = 'rev';
+const ADAPTER_PARTITION_PREFIX = `${ADAPTER_TAGS.store}${KEY_SEPARATOR}`;
+export function storePartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+export function partitionKey(namespace) {
+    return `${ADAPTER_PARTITION_PREFIX}${namespace[0]}`;
+}
+export function sortKey(namespace, key) {
+    return [...namespace.slice(1), key].join(KEY_SEPARATOR);
+}
+export function sortKeyPrefix(prefix) {
+    const rest = prefix.slice(1);
+    return rest.length === 0 ? '' : `${rest.join(KEY_SEPARATOR)}${KEY_SEPARATOR}`;
+}
+export function namespaceMatchesPrefix(namespace, prefix) {
+    if (prefix.length > namespace.length)
+        return false;
+    return prefix.every((element, index) => namespace[index] === element);
+}
+export function itemRowKey(address) {
+    return { PK: partitionKey(address.namespace), SK: sortKey(address.namespace, address.key) };
+}
+export function scopedQuery(tableName, prefix) {
+    const skPrefix = sortKeyPrefix(prefix);
+    if (skPrefix.length === 0) {
+        return {
+            TableName: tableName,
+            KeyConditionExpression: '#pk = :pk',
+            ExpressionAttributeNames: { '#pk': PARTITION_KEY_ATTRIBUTE },
+            ExpressionAttributeValues: { ':pk': partitionKey(prefix) },
+        };
+    }
+    return {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
+        ExpressionAttributeNames: { '#pk': PARTITION_KEY_ATTRIBUTE, '#sk': SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': partitionKey(prefix), ':skp': skPrefix },
+    };
+}
+export function storeScan(tableName) {
+    return {
+        TableName: tableName,
+        FilterExpression: 'begins_with(#pk, :pkp) AND attribute_exists(#ns)',
+        ExpressionAttributeNames: { '#pk': PARTITION_KEY_ATTRIBUTE, '#ns': 'namespace' },
+        ExpressionAttributeValues: { ':pkp': storePartitionPrefix() },
+    };
+}
+export function projectKeys(params) {
+    return {
+        ...params,
+        ProjectionExpression: `${PARTITION_KEY_ATTRIBUTE}, ${SORT_KEY_ATTRIBUTE}, #ns, #key, #v`,
+        ExpressionAttributeNames: {
+            ...params.ExpressionAttributeNames,
+            '#ns': 'namespace',
+            '#key': 'key',
+            '#v': 'v',
+        },
+    };
+}
+export function isLiveRow(existing) {
+    return existing.exists && !isExpiredRow(existing, nowSeconds());
+}
+export async function readExisting(context, key) {
+    const existing = await withDynamoDBRetry((request) => context.client.get({
+        TableName: context.tableName,
+        Key: key,
+        ConsistentRead: true,
+        ProjectionExpression: '#c, #r, #ttl, #v.#loc, #v.#s3k',
+        ExpressionAttributeNames: {
+            '#c': 'createdAt',
+            '#r': REVISION_ATTRIBUTE,
+            '#ttl': 'ttl',
+            '#v': 'value',
+            '#loc': 'location',
+            '#s3k': 's3Key',
+        },
+    }, request), context.retry);
+    return existingFrom(existing.Item);
+}
+export function existingFrom(item) {
+    return {
+        exists: item !== undefined,
+        createdAt: item?.createdAt,
+        ttl: item?.ttl,
+        value: item?.value,
+        revision: item?.[REVISION_ATTRIBUTE],
+    };
+}
+export function parseStoreRow(raw) {
+    assertReadableRow(raw, 'store item');
+    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
+        return undefined;
+    const record = raw;
+    const consistent = record.PK === partitionKey(record.namespace) &&
+        record.SK === sortKey(record.namespace, record.key);
+    return consistent ? record : undefined;
+}
+export function parseWholeStoreRow(raw) {
+    const record = parseStoreRow(raw);
+    if (record === undefined)
+        return undefined;
+    const stamped = typeof record.createdAt === 'string' && typeof record.updatedAt === 'string';
+    return stamped ? record : undefined;
+}
+export async function buildStoreRow(context, address, value, options) {
+    const { namespace, key } = address;
+    const pk = partitionKey(namespace);
+    const sk = sortKey(namespace, key);
+    const rev = options.rev ?? randomUUID();
+    const descriptor = await encodePayload(value, codecDepsOf(context), {
+        keyParts: [...namespace, key],
+        objectId: rev,
+        row: { pk, sk },
+    });
+    const record = {
+        PK: pk,
+        SK: sk,
+        v: ROW_FORMAT_VERSION,
+        namespace,
+        key,
+        value: descriptor,
+        createdAt: options.createdAt,
+        updatedAt: options.updatedAt,
+        rev,
+    };
+    if (options.embeddings)
+        record.embeddings = options.embeddings;
+    if (options.ttlTimestamp !== undefined)
+        record.ttl = options.ttlTimestamp;
+    return record;
+}
+export async function readStoreItem(context, record, signal) {
+    const value = await decodePayload(record.value, codecDepsOf(context, signal), [...record.namespace, record.key]);
+    return {
+        namespace: record.namespace,
+        key: record.key,
+        value,
+        createdAt: new Date(record.createdAt),
+        updatedAt: new Date(record.updatedAt),
+    };
+}