@farukada/aws-langgraph-dynamodb-ts 0.7.0 → 0.8.0

package/dist/store/internal/validation.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validatePaging = validatePaging;
 exports.validateNamespace = validateNamespace;
 exports.validateKey = validateKey;
+exports.validateMaxDepth = validateMaxDepth;
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
 /** Validate search/listNamespaces paging is non-negative integers. */
@@ -10,17 +11,25 @@ function validatePaging(offset, limit) {
     (0, primitives_1.validateInteger)(offset, 'offset', { min: 0 });
     (0, primitives_1.validateInteger)(limit, 'limit', { min: 0 });
 }
-/** Validate the namespace is non-empty and each element is separator-free. */
+/** Validate the namespace is non-empty and each element is a valid identifier. */
 function validateNamespace(namespace) {
     (0, primitives_1.validateNonEmptyArray)(namespace, 'namespace');
     for (const element of namespace) {
-        (0, primitives_1.validateNonEmptyString)(element, 'namespace element');
-        (0, primitives_1.assertNoSeparator)(element, keys_1.NAMESPACE_SEPARATOR, 'namespace element');
+        (0, primitives_1.validateIdentifier)(element, keys_1.NAMESPACE_SEPARATOR, 'namespace element');
     }
 }
-/** Validate an item key is a non-empty, separator-free string. */
+/** Validate an item key is a non-empty, separator- and control-char-free string. */
 function validateKey(key) {
-    (0, primitives_1.validateNonEmptyString)(key, 'key');
-    (0, primitives_1.assertNoSeparator)(key, keys_1.NAMESPACE_SEPARATOR, 'key');
+    (0, primitives_1.validateIdentifier)(key, keys_1.NAMESPACE_SEPARATOR, 'key');
+}
+/**
+ * Validate an optional namespace depth cap. Left unchecked, a negative value
+ * silently inverted truncation via `Array.prototype.slice(0, -n)`, which drops
+ * the *last* n elements rather than erroring.
+ */
+function validateMaxDepth(maxDepth) {
+    if (maxDepth === undefined)
+        return;
+    (0, primitives_1.validateInteger)(maxDepth, 'maxDepth', { min: 1 });
 }
 //# sourceMappingURL=validation.js.map

package/dist/store/internal/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/store/internal/validation.ts"],"names":[],"mappings":";;;;;AAAA,mEAK4C;AAC5C,iCAA6C;AAE7C,sEAAsE;AACtE,wBAA+B,MAAc,EAAE,KAAa;IAC1D,IAAA,4BAAe,EAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,IAAA,4BAAe,EAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,8EAA8E;AAC9E,2BAAkC,SAAmB;IACnD,IAAA,kCAAqB,EAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC9C,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QAChC,IAAA,mCAAsB,EAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;QACrD,IAAA,8BAAiB,EAAC,OAAO,EAAE,0BAAmB,EAAE,mBAAmB,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,qBAA4B,GAAW;IACrC,IAAA,mCAAsB,EAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,IAAA,8BAAiB,EAAC,GAAG,EAAE,0BAAmB,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/store/internal/validation.ts"],"names":[],"mappings":";;;;;;AAAA,mEAI4C;AAC5C,iCAA6C;AAE7C,sEAAsE;AACtE,wBAA+B,MAAc,EAAE,KAAa;IAC1D,IAAA,4BAAe,EAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,IAAA,4BAAe,EAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,kFAAkF;AAClF,2BAAkC,SAAmB;IACnD,IAAA,kCAAqB,EAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC9C,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QAChC,IAAA,+BAAkB,EAAC,OAAO,EAAE,0BAAmB,EAAE,mBAAmB,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,qBAA4B,GAAW;IACrC,IAAA,+BAAkB,EAAC,GAAG,EAAE,0BAAmB,EAAE,KAAK,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,0BAAiC,QAAiB;IAChD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO;IACnC,IAAA,4BAAe,EAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AACpD,CAAC"}

package/dist/store/internal/write-verify.d.ts

@@ -1,4 +1,16 @@
 import type { StoreContext } from './setup';
+/** True when `error` is a {@link RetryExhaustedError} — by name, not `instanceof` (banned repo-wide). */
+export declare function isRetryExhausted(error: Error): boolean;
+/**
+ * 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. A failure reading this is not treated
+ * as confirmation (fail safe), matching {@link writeLandedAt}.
+ */
+export declare function rowIsAbsent(context: StoreContext, key: {
+    PK: string;
+    SK: string;
+}): Promise<boolean>;
 /**
  * True when `record`'s row already holds the S3 key `expectedS3Key` — i.e. an
  * ambiguous retry-exhaustion write actually landed server-side and only its

package/dist/store/internal/write-verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-verify.d.ts","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAClC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC,CAgBlB"}
+{"version":3,"file":"write-verify.d.ts","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAEtD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAClC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC,CAgBlB"}

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

@@ -1,8 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryExhausted = isRetryExhausted;
+exports.rowIsAbsent = rowIsAbsent;
 exports.writeLandedAt = writeLandedAt;
 const codec_1 = require("../../shared/codec/codec");
 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. A failure reading this is not treated
+ * as confirmation (fail safe), matching {@link writeLandedAt}.
+ */
+async function rowIsAbsent(context, key) {
+    try {
+        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+            TableName: context.tableName,
+            Key: key,
+            ConsistentRead: true,
+            ProjectionExpression: '#v',
+            ExpressionAttributeNames: { '#v': 'value' },
+        }));
+        return result.Item === undefined;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * True when `record`'s row already holds the S3 key `expectedS3Key` — i.e. an
  * ambiguous retry-exhaustion write actually landed server-side and only its

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

@@ -1 +1 @@
-{"version":3,"file":"write-verify.js","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":";;;AAAA,oDAAmF;AACnF,uDAAgE;AAGhE;;;;;GAKG;AACI,KAAK,wBACV,OAAqB,EACrB,MAAkC,EAClC,aAAqB;IAErB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;YACrC,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,KAAsC,CAAC;QAClE,OAAO,KAAK,EAAE,QAAQ,KAAK,uBAAe,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"write-verify.js","sourceRoot":"","sources":["../../../src/store/internal/write-verify.ts"],"names":[],"mappings":";;;;;AAAA,oDAAmF;AACnF,uDAAgE;AAGhE,yGAAyG;AACzG,0BAAiC,KAAY;IAC3C,OAAO,KAAK,CAAC,IAAI,KAAK,qBAAqB,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACI,KAAK,sBACV,OAAqB,EACrB,GAA+B;IAE/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,GAAG;YACR,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACI,KAAK,wBACV,OAAqB,EACrB,MAAkC,EAClC,aAAqB;IAErB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;YACrC,cAAc,EAAE,IAAI;YACpB,oBAAoB,EAAE,IAAI;YAC1B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,KAAsC,CAAC;QAClE,OAAO,KAAK,EAAE,QAAQ,KAAK,uBAAe,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

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

@@ -2,6 +2,18 @@
 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 `<->`) must convert before returning: a distance ranks the
+     * other way, so forwarding one unconverted yields results that are ordered
+     * correctly but scored backwards, which silently breaks any caller that
+     * thresholds or displays the number. This package cannot tell the two apart
+     * and never reorders what a backend returns; it only warns when the scores
+     * it sees are not non-increasing.
+     */
     score: number;
 }
 /** A stored vector's location, returned by {@link VectorBackend.listKeys}. */
@@ -15,6 +27,11 @@ export interface VectorRef {
  */
 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>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"vector-backend.d.ts","sourceRoot":"","sources":["../../src/store/vector-backend.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,KAAK,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9F,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"vector-backend.d.ts","sourceRoot":"","sources":["../../src/store/vector-backend.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E;;;;OAIG;IACH,KAAK,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9F,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CAC5D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farukada/aws-langgraph-dynamodb-ts",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "description": "AWS DynamoDB implementation for LangGraph Memory Store and Checkpoint Saver in TypeScript",
   "keywords": [