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

package/dist/store/internal/write-verify.js

@@ -1,71 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isRetryExhausted = isRetryExhausted;
-exports.rowIsAbsent = rowIsAbsent;
-exports.verifyWriteLanded = verifyWriteLanded;
-const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
-const retry_1 = require("../../shared/dynamodb/retry");
-/** True when `error` is a {@link RetryExhaustedError} — by name, not `instanceof` (banned repo-wide). */
-function isRetryExhausted(error) {
-    return error.name === 'RetryExhaustedError';
-}
-/**
- * True when the row is confirmed absent — used to resolve an ambiguous
- * retry-exhausted *delete*, where the delete may well have landed server-side
- * and only its acknowledgement was lost. Only the partition key is projected:
- * existence is the whole question. A failure reading this is not treated as
- * confirmation, which is fail-safe here: the caller only rethrows, and nothing
- * is deleted on the strength of a `false`.
- */
-async function rowIsAbsent(context, key) {
-    try {
-        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-            TableName: context.tableName,
-            Key: key,
-            ConsistentRead: true,
-            ProjectionExpression: '#pk',
-            ExpressionAttributeNames: { '#pk': 'PK' },
-        }), context.retry);
-        return result.Item === undefined;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Read `record`'s row back to establish what an ambiguous write actually did,
- * comparing the row's revision with the one this write carried. Every put
- * stamps a fresh per-call `rev`, so the comparison works for inline and
- * offloaded records alike.
- *
- * - `'landed'`: the row holds this write's `rev`, so it committed server-side
- *   and only its acknowledgement was lost.
- * - `'not-landed'`: the row was read and holds something else, or nothing —
- *   or the record carries no `rev` to compare — so this call's own upload, if
- *   any, is dead and safe to delete.
- * - `'unverified'`: the read itself failed, so nothing is established.
- *
- * The third answer used to be folded into the second as a plain `false`, which
- * made a partition that blocked both the put and this read delete the object a
- * possibly-live row points at — permanently breaking every later read of that
- * item. Only a *confirmed* non-commit may delete the new upload: leaking one
- * object (reclaimed by `ensureS3LifecycleRule`) is recoverable, stranding a
- * live row is not.
- */
-async function verifyWriteLanded(context, record) {
-    if (record.rev === undefined)
-        return 'not-landed';
-    try {
-        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-            TableName: context.tableName,
-            Key: { PK: record.PK, SK: record.SK },
-            ConsistentRead: true,
-            ProjectionExpression: '#r',
-            ExpressionAttributeNames: { '#r': conditional_put_1.REVISION_ATTRIBUTE },
-        }), context.retry);
-        return result.Item?.[conditional_put_1.REVISION_ATTRIBUTE] === record.rev ? 'landed' : 'not-landed';
-    }
-    catch {
-        return 'unverified';
-    }
-}

package/dist/store/store.d.ts

@@ -1,61 +0,0 @@
-import { BaseStore, type Operation, type OperationResults, type SearchItem, type SearchOperation } from '@langchain/langgraph-checkpoint';
-import type { CancelOptions } from '../shared/options';
-import { type VectorReconcileResult } from './actions/reconcile-vector-index';
-import type { DynamoDBStoreOptions } from './types';
-/**
- * DynamoDB-backed LangGraph store for long-term memory with optional semantic
- * search. A thin orchestrator: the base class's get/put/search/delete/
- * listNamespaces all funnel into {@link batch}, which dispatches each operation.
- */
-export declare class DynamoDBStore extends BaseStore {
-    private readonly context;
-    private readonly ownsClient;
-    private readonly ddbClient;
-    constructor(options: DynamoDBStoreOptions);
-    private dispatch;
-    /**
-     * Execute a batch of operations and return their results in operation
-     * order. Writes to one item stay ordered; writes to different items, and
-     * then all reads, run concurrently — so a get after a put to the same key
-     * in one batch observes the put, and a batch of ten gets costs about one
-     * round trip rather than ten (see `runBatch`). The library's error boundary
-     * for every `BaseStore` method (`get`/`put`/`delete`/`search`/
-     * `listNamespaces` all funnel through here): a raw AWS SDK error surfaces
-     * as an `UpstreamError`, and one failing operation rejects the whole batch.
-     * @throws ValidationError for a malformed namespace, key or value; UpstreamError; RetryExhaustedError; ResultTruncatedError from a listing over its cap.
-     */
-    batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
-    /**
-     * Search with optional cancellation. Overrides the base implementation, which
-     * routes through {@link batch} and therefore cannot carry a signal. A plain
-     * search stops reading once `offset + limit` matches are in hand; a `query`
-     * ranks in-process (up to `maxSearchCandidates`) or through the `vectorBackend`.
-     * @throws ValidationError when the candidate set exceeds `maxSearchCandidates`; AbortError; UpstreamError.
-     */
-    search(namespacePrefix: string[], options?: Pick<SearchOperation, 'filter' | 'limit' | 'offset' | 'query'> & CancelOptions): Promise<SearchItem[]>;
-    /**
-     * Repair the configured vector backend against the canonical items under
-     * `namespacePrefix`. A maintenance tool; see {@link reconcileVectorIndex}.
-     * @throws ValidationError without an `index` and `vectorBackend` or for an empty prefix; ResultTruncatedError past `maxScanItems`.
-     */
-    reconcileVectorIndex(namespacePrefix: string[], options?: CancelOptions): Promise<VectorReconcileResult>;
-    /**
-     * LangGraph's lifecycle hook. A host that manages stores through the
-     * upstream `BaseStore` interface calls `stop()`, so it releases the owned
-     * client exactly like {@link destroy}, which stays the explicit API. Both
-     * are idempotent.
-     */
-    stop(): void;
-    /** Release owned resources (the underlying client and any S3 client). */
-    destroy(): void;
-    /**
-     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
-     * offloaded objects don't outlive their DynamoDB item forever. No-ops when
-     * S3 offload or TTL isn't configured; throws when the bucket cannot be read
-     * or written. Requires the `s3:GetLifecycleConfiguration` /
-     * `s3:PutLifecycleConfiguration` bucket-level permissions (broader than the
-     * object-level CRUD the rest of S3 offload needs) — call this once during
-     * deployment/provisioning, not per-request.
-     */
-    ensureS3LifecycleRule(): Promise<void>;
-}

package/dist/store/store.js

@@ -1,107 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamoDBStore = void 0;
-const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
-const boundary_1 = require("../shared/errors/boundary");
-const ttl_1 = require("../shared/validation/ttl");
-const get_1 = require("./actions/get");
-const list_namespaces_1 = require("./actions/list-namespaces");
-const put_1 = require("./actions/put");
-const reconcile_vector_index_1 = require("./actions/reconcile-vector-index");
-const search_1 = require("./actions/search");
-const batch_plan_1 = require("./internal/batch-plan");
-const setup_1 = require("./internal/setup");
-/**
- * DynamoDB-backed LangGraph store for long-term memory with optional semantic
- * search. A thin orchestrator: the base class's get/put/search/delete/
- * listNamespaces all funnel into {@link batch}, which dispatches each operation.
- */
-class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
-    context;
-    ownsClient;
-    ddbClient;
-    constructor(options) {
-        super();
-        const setup = (0, setup_1.setUpStore)(options);
-        this.context = setup.context;
-        this.ownsClient = setup.ownsClient;
-        this.ddbClient = setup.ddbClient;
-    }
-    dispatch(operation) {
-        if ('namespacePrefix' in operation)
-            return (0, search_1.searchItems)(this.context, operation);
-        if ('value' in operation)
-            return (0, put_1.putItem)(this.context, operation);
-        if ('key' in operation)
-            return (0, get_1.getItem)(this.context, operation.namespace, operation.key);
-        return (0, list_namespaces_1.listNamespaces)(this.context, operation);
-    }
-    /**
-     * Execute a batch of operations and return their results in operation
-     * order. Writes to one item stay ordered; writes to different items, and
-     * then all reads, run concurrently — so a get after a put to the same key
-     * in one batch observes the put, and a batch of ten gets costs about one
-     * round trip rather than ten (see `runBatch`). The library's error boundary
-     * for every `BaseStore` method (`get`/`put`/`delete`/`search`/
-     * `listNamespaces` all funnel through here): a raw AWS SDK error surfaces
-     * as an `UpstreamError`, and one failing operation rejects the whole batch.
-     * @throws ValidationError for a malformed namespace, key or value; UpstreamError; RetryExhaustedError; ResultTruncatedError from a listing over its cap.
-     */
-    async batch(operations) {
-        return (0, boundary_1.guardPublic)('store.batch', async () => {
-            const results = await (0, batch_plan_1.runBatch)(operations, (operation) => this.dispatch(operation));
-            return results;
-        });
-    }
-    /**
-     * Search with optional cancellation. Overrides the base implementation, which
-     * routes through {@link batch} and therefore cannot carry a signal. A plain
-     * search stops reading once `offset + limit` matches are in hand; a `query`
-     * ranks in-process (up to `maxSearchCandidates`) or through the `vectorBackend`.
-     * @throws ValidationError when the candidate set exceeds `maxSearchCandidates`; AbortError; UpstreamError.
-     */
-    async search(namespacePrefix, options = {}) {
-        const { signal, ...rest } = options;
-        return (0, boundary_1.guardPublic)('store.search', () => (0, search_1.searchItems)(this.context, { namespacePrefix, ...rest }, signal));
-    }
-    /**
-     * Repair the configured vector backend against the canonical items under
-     * `namespacePrefix`. A maintenance tool; see {@link reconcileVectorIndex}.
-     * @throws ValidationError without an `index` and `vectorBackend` or for an empty prefix; ResultTruncatedError past `maxScanItems`.
-     */
-    reconcileVectorIndex(namespacePrefix, options) {
-        return (0, boundary_1.guardPublic)('store.reconcileVectorIndex', () => (0, reconcile_vector_index_1.reconcileVectorIndex)(this.context, namespacePrefix, options));
-    }
-    /**
-     * LangGraph's lifecycle hook. A host that manages stores through the
-     * upstream `BaseStore` interface calls `stop()`, so it releases the owned
-     * client exactly like {@link destroy}, which stays the explicit API. Both
-     * are idempotent.
-     */
-    stop() {
-        this.destroy();
-    }
-    /** Release owned resources (the underlying client and any S3 client). */
-    destroy() {
-        this.context.offloader?.destroy();
-        if (this.ownsClient)
-            this.ddbClient?.destroy();
-    }
-    /**
-     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
-     * offloaded objects don't outlive their DynamoDB item forever. No-ops when
-     * S3 offload or TTL isn't configured; throws when the bucket cannot be read
-     * or written. Requires the `s3:GetLifecycleConfiguration` /
-     * `s3:PutLifecycleConfiguration` bucket-level permissions (broader than the
-     * object-level CRUD the rest of S3 offload needs) — call this once during
-     * deployment/provisioning, not per-request.
-     */
-    async ensureS3LifecycleRule() {
-        return (0, boundary_1.guardPublic)('store.ensureS3LifecycleRule', async () => {
-            if (!this.context.offloader || !this.context.ttl)
-                return;
-            await this.context.offloader.ensureLifecycleRule((0, ttl_1.lifecycleExpirationDays)(this.context.ttl));
-        });
-    }
-}
-exports.DynamoDBStore = DynamoDBStore;

package/dist/store/types.d.ts

@@ -1,50 +0,0 @@
-import type { IndexConfig, SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { PayloadDescriptor } from '../shared/codec/codec';
-import type { BaseAdapterOptions, CodecOptions } from '../shared/options';
-import type { VectorScoreDirection } from './internal/score-direction';
-import type { VectorBackend } from './vector-backend';
-/** Options for {@link DynamoDBStore}. */
-export type DynamoDBStoreOptions = BaseAdapterOptions & CodecOptions & {
-    /**
-     * Optional semantic-search index configuration (embeddings + fields). The
-     * embedding is stored inline on the item (about 10 bytes per dimension) and
-     * is not counted toward `s3.thresholdBytes`; see that option's note on the
-     * 400 KB item limit.
-     */
-    index?: IndexConfig;
-    /** Optional serializer override (defaults to the JSON serializer). */
-    serde?: SerializerProtocol;
-    /** Optional external vector index; when set, similarity search delegates to it. */
-    vectorBackend?: VectorBackend;
-    /** Max candidates the in-DB ranker will score before erroring (default 1000). */
-    maxSearchCandidates?: number;
-    /** Cap on items scanned into memory during a plain (non-semantic) search before ResultTruncatedError. Defaults to MAX_TOTAL_ITEMS_IN_MEMORY. */
-    maxScanItems?: number;
-    /**
-     * Direction of the score a `vectorBackend` returns. `'relevance'` (the
-     * default) forwards it unchanged; `'distance'` negates and re-sorts, so a
-     * distance-native backend (S3 Vectors, FAISS L2, pgvector `<->`) satisfies
-     * the higher-is-better contract without the caller wrapping it. Any other
-     * value is rejected at construction with a `ValidationError` rather than
-     * silently ranking one direction as the other.
-     */
-    vectorScoreDirection?: VectorScoreDirection;
-};
-/** The DynamoDB item backing a single stored value. */
-export interface StoreItemRecord {
-    PK: string;
-    SK: string;
-    namespace: string[];
-    key: string;
-    value: PayloadDescriptor;
-    createdAt: string;
-    updatedAt: string;
-    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;
-}

package/dist/store/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/store/vector-backend.d.ts

@@ -1,43 +0,0 @@
-/** A vector-similarity match returned by an external {@link VectorBackend}. */
-export interface VectorMatch {
-    namespace: string[];
-    key: string;
-    /**
-     * Relevance, where **higher means a better match** — the same direction as
-     * upstream `SearchItem.score`, which this value is forwarded to verbatim.
-     *
-     * A backend whose native output is a *distance* (S3 Vectors, FAISS L2,
-     * pgvector's `<->`) has two options: convert before returning, or declare
-     * `vectorScoreDirection: 'distance'` on the store, which negates and
-     * re-sorts for you. Forwarding an unconverted distance without declaring it
-     * yields results ordered correctly but scored backwards, which silently
-     * breaks any caller that thresholds or displays the number; that case is
-     * warned about but never reordered.
-     */
-    score: number;
-}
-/** A stored vector's location, returned by {@link VectorBackend.listKeys}. */
-export interface VectorRef {
-    namespace: string[];
-    key: string;
-}
-/**
- * Pluggable vector index. When provided to the store, embeddings live here and
- * similarity search is delegated to it; DynamoDB still holds the canonical item.
- */
-export interface VectorBackend {
-    upsert(namespace: string[], key: string, vector: number[]): Promise<void>;
-    /**
-     * Return up to `topK` matches under `namespacePrefix`, best first. Each
-     * match's `score` must be a relevance, not a distance — see
-     * {@link VectorMatch.score}.
-     */
-    query(namespacePrefix: string[], queryVector: number[], topK: number): Promise<VectorMatch[]>;
-    delete(namespace: string[], key: string): Promise<void>;
-    /**
-     * Optionally enumerate every stored vector under `namespacePrefix`. Enables
-     * `reconcileVectorIndex` to prune vectors orphaned by a lost delete. Omit it
-     * when the backend cannot enumerate — reconciliation then re-pushes only.
-     */
-    listKeys?(namespacePrefix: string[]): Promise<VectorRef[]>;
-}

package/dist/store/vector-backend.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });