@delali/narsil 0.2.4-next.48 → 0.2.4-next.50

package/dist/{engine-Cjr1uBLa.d.ts → engine-9PtFY50q.d.ts}

@@ -1,6 +1,6 @@
 import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { I as IndexInfo, f as IndexStats, P as PartitionStatsResult, B as BatchResult, L as ListParams, g as ListResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult, M as MemoryStats, V as VectorMaintenanceResult } from './search-DDHjfXhJ.js';
-import { I as IndexConfig, A as AnyDocument, b as InsertOptions, P as PartitionConfig } from './schema-B7juWg8Q.js';
+import { B as BatchResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, L as ListParams, g as ListResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult, M as MemoryStats, V as VectorMaintenanceResult } from './memory-Bzd5xcEW.js';
+import { A as AnyDocument, b as InsertOptions, W as WriteOptions, I as IndexConfig, P as PartitionConfig } from './schema-BqRx9t4E.js';
 
 /**
  * Every event the engine emits, with the payload each one carries.
@@ -16,8 +16,12 @@ type NarsilEventMap = {
     /**
      * A worker thread died. The pool drops it and fails its outstanding requests
      * with `WORKER_CRASHED`, while the remaining workers keep answering because
-     * each holds a full worker copy of every promoted index. Once no worker is
-     * left, queries fall back to the main thread, which holds every document.
+     * each holds a full worker copy of every promoted index. After a delay the
+     * engine spawns a replacement, loads every copy onto it, and puts it back
+     * into rotation. Once no worker is left, queries fall back to the main
+     * thread, which holds every document, and the next request after the delay
+     * starts a new pool. The delay starts at one second and doubles up to a
+     * minute while replacements keep failing.
      */
     workerCrash: {
         /** This worker died. */
@@ -27,16 +31,16 @@ type NarsilEventMap = {
         /** This ended the worker. */
         error: Error;
     };
-    /** The engine moved its indexes onto worker threads. */
+    /** An index gained worker copies, whether it reached the copy threshold or loaded its copies again after an idle spell. */
     workerPromote: {
-        /** The pool started with this many workers. */
+        /** The pool holds this many workers. */
         workerCount: number;
-        /** The engine promoted for this reason, such as the threshold the index passed. */
+        /** The index gained its copies for this reason, such as the copy threshold it reached. */
         reason: string;
     };
-    /** The engine tried to move onto worker threads and could not. Indexes keep answering on the main thread. */
+    /** An index could not gain worker copies. It keeps answering on the main thread. */
     workerPromoteFailure: {
-        /** The engine tried to promote for this reason. */
+        /** The engine tried to load the copies for this reason. */
         reason: string;
         /** This stopped it. */
         error: Error;
@@ -63,6 +67,24 @@ type NarsilEventMap = {
         /** The index holds this many partitions. */
         partitionCount: number;
     };
+    /**
+     * The process heap crossed nine tenths of its limit during a write or a
+     * load, so the next large index may end the process with an out-of-memory
+     * error. The engine emits the event once per crossing and arms it again
+     * once the heap falls below eight tenths of the limit. Raise the limit with
+     * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
+     * idle index; see {@link ProcessMemoryReport.heapLimit}.
+     */
+    heapPressure: {
+        /** The heap crossed nine tenths of its limit during a write to this index or a load of it. */
+        indexName: string;
+        /** The process is using this much heap, in bytes. */
+        heapUsed: number;
+        /** The heap may grow to this many bytes. */
+        heapLimit: number;
+        /** The engine estimates that the index holds this many bytes. */
+        estimatedMemoryBytes: number;
+    };
     /** A rebuild is bringing an index's terms up to its language module's current analysis. */
     analysisRebuild: {
         /** This index is being rebuilt. */
@@ -111,73 +133,31 @@ interface IndexLifecycleOperations {
 }
 
 /**
- * The search engine, and everything you do with it.
+ * Adds, replaces, and removes documents, and waits for the worker copies to
+ * catch up with those writes.
  *
- * One instance holds every index you create, so an application usually keeps a
- * single engine for its lifetime and reaches each index by name. Build one
- * with {@link createNarsil}.
+ * A write returns once the main copy holds it, and the worker copies apply
+ * it afterwards, so a query that a copy answers can come back without a write
+ * that returned before it. Every write takes a `wait` option for the cases
+ * where the next query has to see it.
  *
  * @public
  */
-interface Narsil extends IndexLifecycleOperations {
-    /**
-     * Creates an index you can insert documents into and query.
-     *
-     * The schema sets the type of each field, marks which fields you can
-     * filter and sort on, and controls how the engine tokenises text. The
-     * `language` option picks the analyser that stems those text fields.
-     *
-     * @param name - Every later call uses this name to reach the index.
-     * @param config - This carries the schema, and the language, partitioning,
-     * and scoring settings.
-     */
-    createIndex(name: string, config: IndexConfig): Promise<void>;
-    /** Registers an adapter under a name that index configs can reference and
-     * durability metadata can persist; re-registering rebinds referencing indexes. */
-    registerEmbeddingAdapter(name: string, adapter: EmbeddingAdapter): void;
-    /**
-     * Removes an index and everything it holds, including whatever persistence
-     * wrote for it. The documents do not come back.
-     *
-     * @param name - The index to drop.
-     */
-    dropIndex(name: string): Promise<void>;
-    /**
-     * Lists every index this engine holds, with its size and its language.
-     *
-     * @returns One entry per index, in creation order.
-     */
-    listIndexes(): IndexInfo[];
-    /**
-     * Returns one index's document count, partition count, memory estimate,
-     * language, and schema.
-     *
-     * @param indexName - The index to describe.
-     * @returns The index's current figures.
-     * @throws A `NarsilError` with `INDEX_NOT_FOUND` for an unknown name.
-     */
-    getStats(indexName: string): IndexStats;
-    /**
-     * Returns per-partition figures for one index, which is where you look when
-     * an index grows unevenly or a rebalance is worth running.
-     *
-     * @param indexName - The index to describe.
-     * @returns One entry per open partition, in partition order, or an empty list while the index is closed.
-     */
-    getPartitionStats(indexName: string): PartitionStatsResult[];
+interface DocumentWriteOperations {
     /**
      * Adds one document to an index and returns the id it is stored under.
      *
      * The id comes from the `docId` argument when you pass one, otherwise from
      * the document's own `id` field, and otherwise the engine generates it. Use
-     * {@link Narsil.insertBatch} for a large load, so that one bad document
-     * cannot abandon the rest.
+     * {@link DocumentWriteOperations.insertBatch} for a large load, so that one
+     * bad document cannot abandon the rest.
      *
      * @param indexName - The index that receives the document.
      * @param document - Its fields must match the types the schema declares.
      * @param docId - Pass an id to control it yourself, or omit it and read the
      * returned value.
-     * @param options - Per-write settings, such as skipping the defensive copy.
+     * @param options - Per-write settings, such as skipping the defensive copy
+     * or waiting for every worker copy to apply the write.
      * @returns The id the document is stored under.
      */
     insert(indexName: string, document: AnyDocument, docId?: string, options?: InsertOptions): Promise<string>;
@@ -200,41 +180,117 @@ interface Narsil extends IndexLifecycleOperations {
      *
      * @param indexName - The index holding the document.
      * @param docId - The document to remove.
+     * @param options - Per-write settings, such as waiting for every worker
+     * copy to apply the removal.
      * @throws A `NarsilError` with `DOC_NOT_FOUND` when the index holds no such
      * document.
      */
-    remove(indexName: string, docId: string): Promise<void>;
+    remove(indexName: string, docId: string, options?: WriteOptions): Promise<void>;
     /**
      * Removes many documents in one pass and reports each one's outcome.
      *
      * @param indexName - The index holding the documents.
      * @param docIds - The documents to remove.
+     * @param options - Per-write settings applied to the whole batch.
      * @returns The ids removed, and each failure with its error.
      */
-    removeBatch(indexName: string, docIds: string[]): Promise<BatchResult>;
+    removeBatch(indexName: string, docIds: string[], options?: WriteOptions): Promise<BatchResult>;
     /**
      * Replaces a stored document with the one you pass.
      *
      * The engine removes the old document and indexes the new one, so the
-     * document you supply has to be complete rather than a set of changed
-     * fields.
+     * document you supply has to be complete, with every field it should hold
+     * afterwards.
      *
      * @param indexName - The index holding the document.
      * @param docId - The document to replace.
      * @param document - The complete replacement.
+     * @param options - Per-write settings, such as waiting for every worker
+     * copy to apply the replacement.
      */
-    update(indexName: string, docId: string, document: AnyDocument): Promise<void>;
+    update(indexName: string, docId: string, document: AnyDocument, options?: WriteOptions): Promise<void>;
     /**
      * Replaces many documents in one pass and reports each one's outcome.
      *
      * @param indexName - The index holding the documents.
      * @param updates - Each id with the complete document that replaces it.
+     * @param options - Per-write settings applied to the whole batch.
      * @returns The ids replaced, and each failure with its error.
      */
     updateBatch(indexName: string, updates: Array<{
         docId: string;
         document: AnyDocument;
-    }>): Promise<BatchResult>;
+    }>, options?: WriteOptions): Promise<BatchResult>;
+    /**
+     * Resolves once every worker copy of an index has applied every write that
+     * returned before the call.
+     *
+     * Call this after a run of writes, or pass `wait: true` on one write,
+     * before a query that has to see them. An index that holds no copies
+     * resolves at once.
+     *
+     * @param indexName - The index whose copies have to catch up.
+     */
+    waitForWrites(indexName: string): Promise<void>;
+}
+
+/**
+ * The search engine, and everything you do with it.
+ *
+ * One instance holds every index you create, so an application usually keeps a
+ * single engine for its lifetime and reaches each index by name. Build one
+ * with {@link createNarsil}. The write methods come from
+ * {@link DocumentWriteOperations} and the open and close methods from
+ * {@link IndexLifecycleOperations}.
+ *
+ * @public
+ */
+interface Narsil extends IndexLifecycleOperations, DocumentWriteOperations {
+    /**
+     * Creates an index you can insert documents into and query.
+     *
+     * The schema sets the type of each field, marks which fields you can
+     * filter and sort on, and controls how the engine tokenises text. The
+     * `language` option picks the analyser that stems those text fields.
+     *
+     * @param name - Every later call uses this name to reach the index.
+     * @param config - This carries the schema, and the language, partitioning,
+     * and scoring settings.
+     */
+    createIndex(name: string, config: IndexConfig): Promise<void>;
+    /** Registers an adapter under a name that index configs can reference and
+     * durability metadata can persist; re-registering rebinds referencing indexes. */
+    registerEmbeddingAdapter(name: string, adapter: EmbeddingAdapter): void;
+    /**
+     * Removes an index and everything it holds, including whatever persistence
+     * wrote for it. The documents do not come back.
+     *
+     * @param name - The index to drop.
+     */
+    dropIndex(name: string): Promise<void>;
+    /**
+     * Lists every index this engine holds, with its size and its language.
+     *
+     * @returns One entry per index, in creation order.
+     */
+    listIndexes(): IndexInfo[];
+    /**
+     * Returns one index's document count, partition count, memory estimate,
+     * language, and schema.
+     *
+     * @param indexName - The index to describe.
+     * @returns The index's current figures.
+     * @throws A `NarsilError` with `INDEX_NOT_FOUND` for an unknown name.
+     */
+    getStats(indexName: string): IndexStats;
+    /**
+     * Returns per-partition figures for one index, which is where you look when
+     * an index grows unevenly or a rebalance is worth running.
+     *
+     * @param indexName - The index to describe.
+     * @returns One entry per open partition, in partition order, or an empty list while the index is closed.
+     */
+    getPartitionStats(indexName: string): PartitionStatsResult[];
     /**
      * Fetches one stored document by id, without searching.
      *
@@ -478,4 +534,4 @@ interface Narsil extends IndexLifecycleOperations {
     shutdown(): Promise<void>;
 }
 
-export type { IndexLifecycleOperations as I, NarsilEventMap as N, Narsil as a };
+export type { DocumentWriteOperations as D, IndexLifecycleOperations as I, NarsilEventMap as N, Narsil as a };