@dudousxd/nestjs-agent-rag 0.14.0 → 0.14.2

package/dist/index.d.cts

@@ -279,14 +279,15 @@ interface LexicalVectorStore extends VectorStore {
     searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
 }
 /**
- * An **optional** capability: swap all of a document's chunks atomically, so no search or crash ever
- * sees it half-replaced. Optional because atomicity is exactly what not every backend can promise over
- * its client; {@link replaceDocumentChunks} falls back to `remove` plus `upsert` for the others.
+ * An **optional** capability: swap all of a document's chunks safely under concurrent calls, so two
+ * writers can't leave a mix of versions behind. Postgres also makes the swap atomic for searches and
+ * crashes; Redis can't, and only guarantees the end state. {@link replaceDocumentChunks} falls back to
+ * `remove` plus `upsert` for the others.
  */
 interface AtomicReplaceVectorStore extends VectorStore {
     replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
 }
-/** Replaces a document's chunks, atomically where the store can. */
+/** Replaces a document's chunks through the store's safe swap, where it has one. */
 declare function replaceDocumentChunks(store: VectorStore, documentId: string, records: VectorRecord[]): Promise<void>;
 /**
  * Does this store carry the optional {@link LexicalVectorStore} capability? Lets a consumer pick the
@@ -406,8 +407,9 @@ declare function describeSharedSource(legs: readonly unknown[]): Omit<RetrievalD
  * (`removeWhere` refusing an empty filter, an empty-array filter deleting nothing) are behavioural,
  * not incidental to Redis.
  */
-declare class MemoryVectorStore implements VectorStore {
+declare class MemoryVectorStore implements AtomicReplaceVectorStore {
     private readonly records;
+    private readonly replacing;
     /**
      * Telemetry self-description. No `collection`: there is no namespace to name — the corpus IS this
      * instance, and two `MemoryVectorStore`s in one process are two corpora with nothing to tell them
@@ -415,6 +417,8 @@ declare class MemoryVectorStore implements VectorStore {
      */
     describeRetrieval(): RetrievalDescriptor;
     upsert(records: VectorRecord[]): Promise<void>;
+    /** Replaces take turns per document. A `remove` during one isn't queued, and may be undone by it. */
+    replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
     remove(documentId: string): Promise<void>;
     /**
      * Merge `patch` into every chunk of `documentId`, leaving `text` and `embedding` untouched. The
@@ -671,6 +675,10 @@ declare class PgVectorStore implements AtomicReplaceVectorStore {
     /**
      * Swaps a document's chunks in one transaction, so a crash can't lose it and a search sees the old
      * version or the new one. A client without `transaction` falls back to two statements.
+     *
+     * Concurrent swaps of one document take turns on an advisory lock. Without it the second `DELETE`
+     * can't see the rows the first just committed, so the first's tail survives next to the second's
+     * chunks, and overlapping writes can deadlock.
      */
     replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
     private upsertWith;
@@ -770,12 +778,6 @@ declare class PgLexicalVectorStore extends PgVectorStore implements LexicalVecto
     private tsvector;
 }
 
-/**
- * The minimal Redis surface {@link RedisVectorStore} needs: send a raw command and get the reply.
- * Both `node-redis` (`client.sendCommand(args)`) and `ioredis` (wrap `redis.call`) satisfy it — so
- * this package pulls in NO Redis driver (bring your own, like the other adapters). Requires the
- * RediSearch module (Redis Stack / Redis 8+).
- */
 interface RedisSearchClient {
     sendCommand(args: (string | Buffer)[]): Promise<unknown>;
 }
@@ -837,7 +839,7 @@ interface RedisVectorStoreOptions {
  * {@link LexicalVectorStore}: {@link RedisVectorStore.searchText} is BM25 over that same index —
  * the lexical half of hybrid search with no second index to build, feed, or invalidate.
  */
-declare class RedisVectorStore implements LexicalVectorStore {
+declare class RedisVectorStore implements LexicalVectorStore, AtomicReplaceVectorStore {
     private readonly client;
     private readonly index;
     private readonly prefix;
@@ -879,6 +881,18 @@ declare class RedisVectorStore implements LexicalVectorStore {
     private reconcileSchema;
     private createIndex;
     upsert(records: VectorRecord[]): Promise<void>;
+    /**
+     * Replaces a document's chunks, one writer at a time per document. Redis can't swap them in one step
+     * without scanning the keyspace inside a script, so a search may briefly see old and new chunks
+     * together, but concurrent calls can't leave them mixed. The new chunks go in before the old ones
+     * come out, so a crash leaves the document searchable and the next call repairs it.
+     */
+    replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
+    /**
+     * A lease, so a crashed writer can't block the document forever. It is renewed while the work runs,
+     * which keeps a large document from outliving it.
+     */
+    private withDocumentLock;
     /**
      * Single-document deletion, by `SCAN … MATCH`.
      *
@@ -1700,8 +1714,9 @@ declare class RagIndex<Row, Scope extends RagScopeDefinition<Row>> {
     search(query: string, options: RagSearchOptions<Scope>): Promise<Passage[]>;
     /**
      * Replaces the row's chunks and returns how many were written. Embeddings come first: if the
-     * provider fails, the previous chunks are still there. The swap is one transaction on Postgres; on a
-     * store without `replaceDocument` a crash mid-swap loses the document until the next `index`.
+     * provider fails, the previous chunks are still there. The swap is one transaction on Postgres. Redis
+     * adds the new chunks before dropping the old, so a search can briefly see both. On a store without
+     * `replaceDocument`, a crash mid-swap loses the document until the next `index`.
      */
     index(row: Row): Promise<number>;
     /** Takes the id itself once the row is gone. */

package/dist/index.d.ts

@@ -279,14 +279,15 @@ interface LexicalVectorStore extends VectorStore {
     searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
 }
 /**
- * An **optional** capability: swap all of a document's chunks atomically, so no search or crash ever
- * sees it half-replaced. Optional because atomicity is exactly what not every backend can promise over
- * its client; {@link replaceDocumentChunks} falls back to `remove` plus `upsert` for the others.
+ * An **optional** capability: swap all of a document's chunks safely under concurrent calls, so two
+ * writers can't leave a mix of versions behind. Postgres also makes the swap atomic for searches and
+ * crashes; Redis can't, and only guarantees the end state. {@link replaceDocumentChunks} falls back to
+ * `remove` plus `upsert` for the others.
  */
 interface AtomicReplaceVectorStore extends VectorStore {
     replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
 }
-/** Replaces a document's chunks, atomically where the store can. */
+/** Replaces a document's chunks through the store's safe swap, where it has one. */
 declare function replaceDocumentChunks(store: VectorStore, documentId: string, records: VectorRecord[]): Promise<void>;
 /**
  * Does this store carry the optional {@link LexicalVectorStore} capability? Lets a consumer pick the
@@ -406,8 +407,9 @@ declare function describeSharedSource(legs: readonly unknown[]): Omit<RetrievalD
  * (`removeWhere` refusing an empty filter, an empty-array filter deleting nothing) are behavioural,
  * not incidental to Redis.
  */
-declare class MemoryVectorStore implements VectorStore {
+declare class MemoryVectorStore implements AtomicReplaceVectorStore {
     private readonly records;
+    private readonly replacing;
     /**
      * Telemetry self-description. No `collection`: there is no namespace to name — the corpus IS this
      * instance, and two `MemoryVectorStore`s in one process are two corpora with nothing to tell them
@@ -415,6 +417,8 @@ declare class MemoryVectorStore implements VectorStore {
      */
     describeRetrieval(): RetrievalDescriptor;
     upsert(records: VectorRecord[]): Promise<void>;
+    /** Replaces take turns per document. A `remove` during one isn't queued, and may be undone by it. */
+    replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
     remove(documentId: string): Promise<void>;
     /**
      * Merge `patch` into every chunk of `documentId`, leaving `text` and `embedding` untouched. The
@@ -671,6 +675,10 @@ declare class PgVectorStore implements AtomicReplaceVectorStore {
     /**
      * Swaps a document's chunks in one transaction, so a crash can't lose it and a search sees the old
      * version or the new one. A client without `transaction` falls back to two statements.
+     *
+     * Concurrent swaps of one document take turns on an advisory lock. Without it the second `DELETE`
+     * can't see the rows the first just committed, so the first's tail survives next to the second's
+     * chunks, and overlapping writes can deadlock.
      */
     replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
     private upsertWith;
@@ -770,12 +778,6 @@ declare class PgLexicalVectorStore extends PgVectorStore implements LexicalVecto
     private tsvector;
 }
 
-/**
- * The minimal Redis surface {@link RedisVectorStore} needs: send a raw command and get the reply.
- * Both `node-redis` (`client.sendCommand(args)`) and `ioredis` (wrap `redis.call`) satisfy it — so
- * this package pulls in NO Redis driver (bring your own, like the other adapters). Requires the
- * RediSearch module (Redis Stack / Redis 8+).
- */
 interface RedisSearchClient {
     sendCommand(args: (string | Buffer)[]): Promise<unknown>;
 }
@@ -837,7 +839,7 @@ interface RedisVectorStoreOptions {
  * {@link LexicalVectorStore}: {@link RedisVectorStore.searchText} is BM25 over that same index —
  * the lexical half of hybrid search with no second index to build, feed, or invalidate.
  */
-declare class RedisVectorStore implements LexicalVectorStore {
+declare class RedisVectorStore implements LexicalVectorStore, AtomicReplaceVectorStore {
     private readonly client;
     private readonly index;
     private readonly prefix;
@@ -879,6 +881,18 @@ declare class RedisVectorStore implements LexicalVectorStore {
     private reconcileSchema;
     private createIndex;
     upsert(records: VectorRecord[]): Promise<void>;
+    /**
+     * Replaces a document's chunks, one writer at a time per document. Redis can't swap them in one step
+     * without scanning the keyspace inside a script, so a search may briefly see old and new chunks
+     * together, but concurrent calls can't leave them mixed. The new chunks go in before the old ones
+     * come out, so a crash leaves the document searchable and the next call repairs it.
+     */
+    replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
+    /**
+     * A lease, so a crashed writer can't block the document forever. It is renewed while the work runs,
+     * which keeps a large document from outliving it.
+     */
+    private withDocumentLock;
     /**
      * Single-document deletion, by `SCAN … MATCH`.
      *
@@ -1700,8 +1714,9 @@ declare class RagIndex<Row, Scope extends RagScopeDefinition<Row>> {
     search(query: string, options: RagSearchOptions<Scope>): Promise<Passage[]>;
     /**
      * Replaces the row's chunks and returns how many were written. Embeddings come first: if the
-     * provider fails, the previous chunks are still there. The swap is one transaction on Postgres; on a
-     * store without `replaceDocument` a crash mid-swap loses the document until the next `index`.
+     * provider fails, the previous chunks are still there. The swap is one transaction on Postgres. Redis
+     * adds the new chunks before dropping the old, so a search can briefly see both. On a store without
+     * `replaceDocument`, a crash mid-swap loses the document until the next `index`.
      */
     index(row: Row): Promise<number>;
     /** Takes the id itself once the row is gone. */

package/dist/index.js

@@ -191,6 +191,7 @@ var MemoryVectorStore = class {
     __name(this, "MemoryVectorStore");
   }
   records = /* @__PURE__ */ new Map();
+  replacing = /* @__PURE__ */ new Map();
   /**
   * Telemetry self-description. No `collection`: there is no namespace to name — the corpus IS this
   * instance, and two `MemoryVectorStore`s in one process are two corpora with nothing to tell them
@@ -206,6 +207,23 @@ var MemoryVectorStore = class {
       this.records.set(record.id, record);
     }
   }
+  /** Replaces take turns per document. A `remove` during one isn't queued, and may be undone by it. */
+  async replaceDocument(documentId, records) {
+    const previous = this.replacing.get(documentId) ?? Promise.resolve();
+    const run = previous.catch(() => {
+    }).then(async () => {
+      await this.remove(documentId);
+      await this.upsert(records);
+    });
+    this.replacing.set(documentId, run);
+    try {
+      await run;
+    } finally {
+      if (this.replacing.get(documentId) === run) {
+        this.replacing.delete(documentId);
+      }
+    }
+  }
   async remove(documentId) {
     for (const id of this.records.keys()) {
       if (documentIdOf(id) === documentId) {
@@ -679,6 +697,10 @@ var PgVectorStore = class {
   /**
   * Swaps a document's chunks in one transaction, so a crash can't lose it and a search sees the old
   * version or the new one. A client without `transaction` falls back to two statements.
+  *
+  * Concurrent swaps of one document take turns on an advisory lock. Without it the second `DELETE`
+  * can't see the rows the first just committed, so the first's tail survives next to the second's
+  * chunks, and overlapping writes can deadlock.
   */
   async replaceDocument(documentId, records) {
     const swap = /* @__PURE__ */ __name(async (client) => {
@@ -688,7 +710,16 @@ var PgVectorStore = class {
       await this.upsertWith(client, records);
     }, "swap");
     const transaction = this.client.transaction?.bind(this.client);
-    await (transaction === void 0 ? swap(this.client) : transaction(swap));
+    if (transaction === void 0) {
+      await swap(this.client);
+      return;
+    }
+    await transaction(async (client) => {
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
+        `${this.table}:${stripNulBytes(documentId)}`
+      ]);
+      await swap(client);
+    });
   }
   async upsertWith(client, records) {
     const byId = /* @__PURE__ */ new Map();
@@ -1103,6 +1134,11 @@ function toVectorLiteral(embedding) {
 __name(toVectorLiteral, "toVectorLiteral");
 
 // src/redis-vector-store.ts
+import { randomUUID } from "crypto";
+var REPLACE_LOCK_TTL_MS = 3e4;
+var REPLACE_LOCK_WAIT_MS = 12e4;
+var RENEW_LOCK_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end return 0";
+var RELEASE_LOCK_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0";
 var RedisVectorSchemaMismatchError = class extends Error {
   static {
     __name(this, "RedisVectorSchemaMismatchError");
@@ -1264,6 +1300,92 @@ var RedisVectorStore = class {
     }
   }
   /**
+  * Replaces a document's chunks, one writer at a time per document. Redis can't swap them in one step
+  * without scanning the keyspace inside a script, so a search may briefly see old and new chunks
+  * together, but concurrent calls can't leave them mixed. The new chunks go in before the old ones
+  * come out, so a crash leaves the document searchable and the next call repairs it.
+  */
+  async replaceDocument(documentId, records) {
+    await this.withDocumentLock(documentId, async (assertHeld) => {
+      await this.upsert(records);
+      assertHeld();
+      const current = new Set(records.map((record) => `${this.prefix}${record.id}`));
+      const stale = (await this.chunkKeys(documentId)).filter((key) => !current.has(key));
+      assertHeld();
+      if (stale.length > 0) {
+        await this.client.sendCommand([
+          "DEL",
+          ...stale
+        ]);
+      }
+    });
+  }
+  /**
+  * A lease, so a crashed writer can't block the document forever. It is renewed while the work runs,
+  * which keeps a large document from outliving it.
+  */
+  async withDocumentLock(documentId, work) {
+    const key = `${this.index}:replace-lock:${documentId}`;
+    const token = randomUUID();
+    const deadline = Date.now() + REPLACE_LOCK_WAIT_MS;
+    let delay = 10;
+    while (await this.client.sendCommand([
+      "SET",
+      key,
+      token,
+      "NX",
+      "PX",
+      String(REPLACE_LOCK_TTL_MS)
+    ]) === null) {
+      if (Date.now() >= deadline) {
+        throw new Error(`RedisVectorStore: timed out after ${REPLACE_LOCK_WAIT_MS}ms waiting to change document "${documentId}"`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      delay = Math.min(delay * 2, 250);
+    }
+    let lost = false;
+    const assertHeld = /* @__PURE__ */ __name(() => {
+      if (lost) {
+        throw new Error(`RedisVectorStore: lost the lock while changing document "${documentId}"; call again to repair it`);
+      }
+    }, "assertHeld");
+    const renewal = setInterval(() => {
+      void Promise.resolve(this.client.sendCommand([
+        "EVAL",
+        RENEW_LOCK_SCRIPT,
+        "1",
+        key,
+        token,
+        String(REPLACE_LOCK_TTL_MS)
+      ])).then(
+        (renewed) => {
+          if (Number(renewed) === 0) {
+            lost = true;
+          }
+        },
+        // A failed renewal isn't a lost lock yet: the lease may still have time left.
+        () => {
+        }
+      );
+    }, REPLACE_LOCK_TTL_MS / 3);
+    renewal.unref?.();
+    try {
+      const result = await work(assertHeld);
+      assertHeld();
+      return result;
+    } finally {
+      clearInterval(renewal);
+      await Promise.resolve(this.client.sendCommand([
+        "EVAL",
+        RELEASE_LOCK_SCRIPT,
+        "1",
+        key,
+        token
+      ])).catch(() => {
+      });
+    }
+  }
+  /**
   * Single-document deletion, by `SCAN … MATCH`.
   *
   * This deliberately stays a keyspace scan even though the rest of this class no longer needs one.
@@ -1284,13 +1406,15 @@ var RedisVectorStore = class {
   * than N scans). Neither depends on a field that older chunks lack, so neither has a migration.
   */
   async remove(documentId) {
-    const keys = await this.chunkKeys(documentId);
-    if (keys.length > 0) {
-      await this.client.sendCommand([
-        "DEL",
-        ...keys
-      ]);
-    }
+    await this.withDocumentLock(documentId, async () => {
+      const keys = await this.chunkKeys(documentId);
+      if (keys.length > 0) {
+        await this.client.sendCommand([
+          "DEL",
+          ...keys
+        ]);
+      }
+    });
   }
   /**
   * Rewrite the metadata of every chunk of `documentId` in place, leaving `text` and `embedding`
@@ -2817,8 +2941,9 @@ var RagIndex = class {
   }
   /**
   * Replaces the row's chunks and returns how many were written. Embeddings come first: if the
-  * provider fails, the previous chunks are still there. The swap is one transaction on Postgres; on a
-  * store without `replaceDocument` a crash mid-swap loses the document until the next `index`.
+  * provider fails, the previous chunks are still there. The swap is one transaction on Postgres. Redis
+  * adds the new chunks before dropping the old, so a search can briefly see both. On a store without
+  * `replaceDocument`, a crash mid-swap loses the document until the next `index`.
   */
   async index(row) {
     const { definition, deps } = this;