@delali/narsil 0.2.2 → 0.2.3-next.33

package/dist/distribution.d.ts

@@ -1,10 +1,12 @@
-import { N as NarsilConfig } from './config-DXypXAfN.js';
-import { B as BatchResult, Q as QueryParams, q as QueryResult } from './search-DLBtiPdQ.js';
-import { I as IndexConfig, A as AnyDocument } from './schema-CE6S_aAr.js';
-import { A as AllocationTable, N as NodeRole, C as ClusterCoordinator, a as NodeCapacity } from './types-BV3nAKTL.js';
-export { b as AllocationConstraints, c as AllocationEvent, d as NodeEvent, e as NodeRegistration, P as PartitionAssignment, f as PartitionState, S as SchemaEvent } from './types-BV3nAKTL.js';
-export { createInMemoryCoordinator } from './distribution/coordinator/in-memory.js';
-import './adapters-CVqI5NBt.js';
+import { N as NarsilConfig } from './config-ChZ7lfqc.js';
+import { A as AllocationTable, N as NodeRole, C as ClusterCoordinator, a as NodeCapacity } from './types-Bfhhnh3G.js';
+export { b as AllocationConstraints, c as AllocationEvent, d as NodeEvent, e as NodeRegistration, P as PartitionAssignment, f as PartitionState, S as SchemaEvent } from './types-Bfhhnh3G.js';
+import { N as NodeTransport } from './types-D5OwhtsQ.js';
+export { L as ListenHandler, R as RespondFn, T as TransportConfig, a as TransportMessage } from './types-D5OwhtsQ.js';
+import { a as NarsilEventMap, N as Narsil } from './engine-DScGlT2Z.js';
+import { B as BatchResult, L as ListParams, g as ListResult, i as SuggestParams, j as SuggestResult, Q as QueryParams, h as PreflightResult, f as IndexStats, P as PartitionStatsResult, M as MemoryStats, e as QueryResult } from './search-CQ-9bKxo.js';
+import { I as IndexConfig, A as AnyDocument, a as InsertOptions } from './schema-emTQfEiX.js';
+import './adapters-79OIa4xm.js';
 
 /**
  * How much replication history a primary keeps, and how many replicas have to
@@ -23,83 +25,6 @@ interface ReplicationConfig {
     waitForActiveReplicas: number;
 }
 
-/**
- * One message on the wire between cluster nodes.
- *
- * The payload is opaque bytes, which is what lets a node written in another
- * language join the same cluster: only the header fields have to agree.
- *
- * @public
- */
-interface TransportMessage {
-    /** This says what the message is, such as a replication entry or a search request. */
-    type: string;
-    /** This node sent the message. */
-    sourceId: string;
-    /** This correlates a reply with its request. */
-    requestId: string;
-    /** This carries the encoded body, and the message type tells a reader how to decode it. */
-    payload: Uint8Array;
-}
-/**
- * How long a transport waits before giving up on each kind of exchange.
- *
- * Every value is in milliseconds. Replication and snapshot transfers carry
- * their own timeouts because they move far more than a search does.
- *
- * @public
- */
-interface TransportConfig {
-    /** Opening a connection to a peer may take this long. */
-    connectTimeout: number;
-    /** An ordinary request and its reply may take this long. */
-    requestTimeout: number;
-    /** A replication entry may take this long to reach a replica and come back acknowledged. */
-    replicationTimeout: number;
-    /** A whole snapshot transfer, which moves a partition between nodes, may take this long. */
-    snapshotTimeout: number;
-}
-/**
- * How one cluster node reaches the others.
- *
- * The package includes a TCP transport for real deployments and an in-process
- * one for tests, and this is the contract either satisfies. Write your own to
- * run a cluster over something else.
- *
- * @public
- */
-interface NodeTransport {
-    /**
-     * Sends one request to a peer and waits for its reply.
-     *
-     * @param target - Node id to send to.
-     * @param message - The request.
-     * @returns The peer's reply.
-     * @throws A `TransportError` when the peer is unreachable, the message is
-     * oversized, or the request times out.
-     */
-    send(target: string, message: TransportMessage): Promise<TransportMessage>;
-    /**
-     * Sends one request whose reply arrives in chunks, which is how a snapshot
-     * moves without being held in memory whole.
-     *
-     * @param target - Node id to send to.
-     * @param message - The request.
-     * @param handler - Called once per chunk, in order.
-     */
-    stream(target: string, message: TransportMessage, handler: (chunk: Uint8Array) => void): Promise<void>;
-    /**
-     * Starts accepting requests from peers.
-     *
-     * @param handler - Called for each request, with the function that returns
-     * the reply.
-     * @returns A function that ends the listener.
-     */
-    listen(handler: (message: TransportMessage, respond: (response: TransportMessage) => void) => void | Promise<void>): Promise<() => void>;
-    /** Closes every connection and releases the port or registration it held. */
-    shutdown(): Promise<void>;
-}
-
 /**
  * Everything {@link createClusterNode} needs to join a node to a cluster.
  *
@@ -181,6 +106,31 @@ interface ClusterNodeInfo {
     /** This says where the node stands, from joining through to shut down. */
     status: string;
 }
+
+/**
+ * The cluster splits an index into this many partitions when
+ * {@link CreateIndexOptions} names no count.
+ *
+ * @public
+ */
+declare const DEFAULT_PARTITION_COUNT = 5;
+/**
+ * The cluster keeps this many copies of each partition when
+ * {@link CreateIndexOptions} names no factor. One copy means a lost node costs
+ * that partition, so raise it for anything you cannot rebuild.
+ *
+ * @public
+ */
+declare const DEFAULT_REPLICATION_FACTOR = 1;
+/**
+ * A node claims this much capacity when {@link ClusterNodeConfig} declares
+ * none. Measure your own hosts and set it, because these figures are a
+ * placeholder rather than a reading.
+ *
+ * @public
+ */
+declare const DEFAULT_CAPACITY: NodeCapacity;
+
 /**
  * One node of a cluster, which routes each write to the partition's primary
  * and gathers each search from every partition.
@@ -213,18 +163,25 @@ interface ClusterNode {
      * @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 - Setting `skipClone` stores the object you passed rather
+     * than a copy, and it applies only where this node is the partition's own
+     * primary, because a document sent to another node is encoded for the wire
+     * and decoded there.
      * @returns The id the document is stored under.
      */
-    insert(indexName: string, document: AnyDocument, docId?: string): Promise<string>;
+    insert(indexName: string, document: AnyDocument, docId?: string, options?: InsertOptions): Promise<string>;
     /**
      * Adds many documents, routing each to its own partition's primary, and
      * reports each one's outcome.
      *
      * @param indexName - The index that receives the documents.
      * @param documents - The documents to write.
+     * @param options - Setting `skipClone` stores the objects you passed rather
+     * than copies, and it applies only to the documents this node is primary
+     * for, because the rest are encoded for the wire.
      * @returns The ids written, and each rejection with its error.
      */
-    insertBatch(indexName: string, documents: AnyDocument[]): Promise<BatchResult>;
+    insertBatch(indexName: string, documents: AnyDocument[], options?: InsertOptions): Promise<BatchResult>;
     /**
      * Removes one document.
      *
@@ -240,6 +197,144 @@ interface ClusterNode {
      * @returns The ids removed, and each failure with its error.
      */
     removeBatch(indexName: string, docIds: string[]): Promise<BatchResult>;
+    /**
+     * Replaces a stored document, routing the replacement to the partition's
+     * primary, which replicates the complete new document to every in-sync copy.
+     *
+     * @param indexName - The index holding the document.
+     * @param docId - The document to replace.
+     * @param document - The complete replacement, because the primary replicates
+     * whole documents rather than changed fields.
+     */
+    update(indexName: string, docId: string, document: AnyDocument): Promise<void>;
+    /**
+     * Replaces many documents, routing each to its own partition's primary, and
+     * reports each one's outcome. Replacements bound for one remote primary
+     * travel together in one message.
+     *
+     * @param indexName - The index holding the documents.
+     * @param updates - Each id with the complete document that replaces it.
+     * @returns The ids replaced, and each failure with its error.
+     */
+    updateBatch(indexName: string, updates: Array<{
+        docId: string;
+        document: AnyDocument;
+    }>): Promise<BatchResult>;
+    /**
+     * Removes an index from the whole cluster: its schema, its allocation, and
+     * every node's local copy. The documents do not come back.
+     *
+     * The controller drives the teardown, so nodes drop their partitions a
+     * moment after this resolves rather than atomically with it.
+     *
+     * @param name - The index to drop.
+     */
+    dropIndex(name: string): Promise<void>;
+    /**
+     * Removes every document from an index across the cluster and keeps the
+     * index itself, along with its schema and allocation.
+     *
+     * Each removal runs through the replication log the way a single remove
+     * does, so a large index takes many round trips to empty.
+     *
+     * @param indexName - The index to empty.
+     */
+    clear(indexName: string): Promise<void>;
+    /**
+     * Counts the documents an index holds across the cluster, reading each
+     * partition's count from one copy.
+     *
+     * The count fails with `QUERY_NO_ACTIVE_REPLICA` rather than answer with a
+     * partition missing, because a partial count would read as a smaller index.
+     *
+     * @param indexName - The index to count.
+     * @returns The document count across every partition.
+     */
+    countDocuments(indexName: string): Promise<number>;
+    /**
+     * Reads one page of stored documents from across the cluster, in
+     * document-id order by default and in the caller's sort order when they
+     * name one. Pass the returned cursor back for the next page.
+     *
+     * @typeParam T - Shape of the stored documents.
+     * @param indexName - The index to walk.
+     * @param params - These set the cursor, the page size, the filter, the
+     * sort, and how much of each document comes back.
+     * @returns The page, the cursor for the next page, and how many documents
+     * the listing covers in total.
+     */
+    listDocuments<T = AnyDocument>(indexName: string, params?: ListParams): Promise<ListResult<T>>;
+    /**
+     * Returns the indexed terms that complete a prefix, merged from every
+     * partition with their document frequencies summed.
+     *
+     * Each node reports its most frequent completions alone, so a term that
+     * ranks low on every node can be undercounted, exactly as distributed
+     * facet counts can.
+     *
+     * @param indexName - The index to draw completions from.
+     * @param params - The prefix typed so far, and how many completions to return.
+     * @returns The completions, most widely used first.
+     */
+    suggest(indexName: string, params: SuggestParams): Promise<SuggestResult>;
+    /**
+     * Counts what a query would match across the cluster without building a
+     * single hit.
+     *
+     * @param indexName - The index the query would run against.
+     * @param params - The same parameters {@link ClusterNode.query} takes.
+     * @returns The match count and the time the count took.
+     */
+    preflight(indexName: string, params: QueryParams): Promise<PreflightResult>;
+    /**
+     * Describes one index across the cluster: its document count and memory
+     * estimate summed over every partition, its partition count, its language,
+     * and its schema.
+     *
+     * @param indexName - The index to describe.
+     * @returns The index's current figures, gathered from one copy of each partition.
+     */
+    getStats(indexName: string): Promise<IndexStats>;
+    /**
+     * Returns per-partition figures for one index, each read from one copy of
+     * that partition.
+     *
+     * @param indexName - The index to describe.
+     * @returns One entry per partition, in partition order.
+     */
+    getPartitionStats(indexName: string): Promise<PartitionStatsResult[]>;
+    /**
+     * Writes this node's local engine state to its durability directory, so a
+     * restart of this node replays less of the log. Other nodes checkpoint
+     * themselves.
+     *
+     * @param indexName - The index to checkpoint on this node.
+     */
+    checkpoint(indexName: string): Promise<void>;
+    /**
+     * Reports what this node's engine and process are using. Memory is a
+     * per-node fact, so ask each node for its own.
+     *
+     * @returns Process heap figures and this node's engine estimate.
+     */
+    getMemoryStats(): Promise<MemoryStats>;
+    /**
+     * Starts delivering one kind of engine event from this node's local engine
+     * to your listener.
+     *
+     * @typeParam K - The event name, which fixes the payload the listener gets.
+     * @param event - Which event to listen for.
+     * @param handler - Called once per event on this node.
+     */
+    on<K extends keyof NarsilEventMap>(event: K, handler: (payload: NarsilEventMap[K]) => void): void;
+    /**
+     * Removes a listener {@link ClusterNode.on} registered.
+     *
+     * @typeParam K - The event name.
+     * @param event - The event the listener was registered for.
+     * @param handler - The same function reference that was registered.
+     */
+    off<K extends keyof NarsilEventMap>(event: K, handler: (payload: NarsilEventMap[K]) => void): void;
     /**
      * Runs a search across every partition and merges the results into one
      * ranking.
@@ -253,6 +348,41 @@ interface ClusterNode {
      * @returns The merged hits, the total count, and the elapsed time.
      */
     query<T = AnyDocument>(indexName: string, params: QueryParams): Promise<QueryResult<T>>;
+    /**
+     * Reads one document, from this node when it holds the partition and from a
+     * node that does otherwise.
+     *
+     * A read fails with `QUERY_NO_ACTIVE_REPLICA` when no reachable node serves
+     * the document's partition, rather than reporting the document missing.
+     *
+     * @param indexName - The index holding the document.
+     * @param docId - The document to read.
+     * @returns The document, or `undefined` when the partition holds no
+     * document under this id.
+     */
+    get(indexName: string, docId: string): Promise<AnyDocument | undefined>;
+    /**
+     * Reads many documents, grouping the ids by the node that serves each
+     * partition and fetching every group in one round trip.
+     *
+     * The read fails with `QUERY_NO_ACTIVE_REPLICA` when no reachable node
+     * serves some document's partition, rather than leaving that document out.
+     *
+     * @param indexName - The index holding the documents.
+     * @param docIds - The documents to read.
+     * @returns The documents found, keyed by id; an id nothing is stored under
+     * is absent.
+     */
+    getMultiple(indexName: string, docIds: string[]): Promise<Map<string, AnyDocument>>;
+    /**
+     * Reports whether a document exists, reading through the same routing as
+     * {@link ClusterNode.get}.
+     *
+     * @param indexName - The index to check.
+     * @param docId - The document id to check.
+     * @returns True when a node serving the partition holds the document.
+     */
+    has(indexName: string, docId: string): Promise<boolean>;
     /** This reaches the cluster-facing side of the node. */
     cluster: ClusterNamespace;
     /** Joins the cluster: the node registers, takes on its allocated partitions, and starts serving. */
@@ -260,29 +390,6 @@ interface ClusterNode {
     /** Leaves the cluster: the node hands its partitions on, deregisters, and closes the engine it ran. */
     shutdown(): Promise<void>;
 }
-/**
- * The cluster splits an index into this many partitions when
- * {@link CreateIndexOptions} names no count.
- *
- * @public
- */
-declare const DEFAULT_PARTITION_COUNT = 5;
-/**
- * The cluster keeps this many copies of each partition when
- * {@link CreateIndexOptions} names no factor. One copy means a lost node costs
- * that partition, so raise it for anything you cannot rebuild.
- *
- * @public
- */
-declare const DEFAULT_REPLICATION_FACTOR = 1;
-/**
- * A node claims this much capacity when {@link ClusterNodeConfig} declares
- * none. Measure your own hosts and set it, because these figures are a
- * placeholder rather than a reading.
- *
- * @public
- */
-declare const DEFAULT_CAPACITY: NodeCapacity;
 
 /**
  * Builds one node of a cluster, ready to join.
@@ -301,95 +408,37 @@ declare const DEFAULT_CAPACITY: NodeCapacity;
 declare function createClusterNode(config: ClusterNodeConfig): Promise<ClusterNode>;
 
 /**
- * Receives the chunks a streamed response carries, in order.
- *
- * @param chunks - Every chunk the responder produced.
- *
- * @public
- */
-type StreamResponder = (chunks: Uint8Array[]) => void;
-/**
- * The delivery side of an in-memory transport, which the network calls to hand
- * a peer its message.
- *
- * You reach this through {@link InMemoryNetwork} rather than building one, so
- * treat it as the connection between two in-process nodes.
- *
- * @public
- */
-interface InMemoryTransportInternal extends NodeTransport {
-    /**
-     * Delivers one request to this node's listener.
-     *
-     * @param message - The request the sender posted.
-     * @param respond - Hands the reply back to the sender.
-     */
-    deliverMessage(message: TransportMessage, respond: (response: TransportMessage) => void): void;
-    /**
-     * Delivers one streamed request to this node's listener.
-     *
-     * @param message - The request the sender posted.
-     * @param responder - Hands the chunks back to the sender.
-     */
-    deliverStream(message: TransportMessage, responder: StreamResponder): void;
-}
-/**
- * The switchboard that connects in-process cluster nodes to each other.
- *
- * Every node registers its transport under its own id, and a message addressed
- * to a node is handed straight to the transport registered under that id. This
- * runs a whole cluster inside one process, which is what tests and local
- * development use in place of TCP.
+ * How {@link clusterNodeEngine} shapes the operations it forwards.
  *
  * @public
  */
-interface InMemoryNetwork {
-    /**
-     * Makes a node reachable under its id.
-     *
-     * @param nodeId - The id peers address this node by.
-     * @param transport - The transport that receives its messages.
-     */
-    register(nodeId: string, transport: InMemoryTransportInternal): void;
-    /**
-     * Makes a node unreachable, so a message addressed to it fails.
-     *
-     * @param nodeId - The node to remove.
-     */
-    unregister(nodeId: string): void;
-    /**
-     * Looks a node's transport up.
-     *
-     * @param nodeId - The node to find.
-     * @returns Its transport, or `undefined` when no node holds that id.
-     */
-    getTransport(nodeId: string): InMemoryTransportInternal | undefined;
+interface ClusterEngineOptions {
+    /** Every index created through the adapter is spread with these settings, and with the cluster defaults otherwise. */
+    createIndex?: CreateIndexOptions;
 }
 /**
- * Builds the switchboard that connects in-process cluster nodes.
- *
- * Create one network, then create a transport per node against it, which is
- * how a whole cluster runs inside a single process.
- *
- * @returns An empty network, ready for nodes to register against.
- *
- * @public
- */
-declare function createInMemoryNetwork(): InMemoryNetwork;
-/**
- * Builds one node's transport and registers it on an in-process network.
- *
- * The network hands each message straight to the addressed node with no socket
- * in between, so a cluster built this way behaves like a real one without any
- * ports to open.
- *
- * @param nodeId - The id peers address this node by.
- * @param network - The network this node joins.
- * @param config - The timeouts to override. Omit it to accept the defaults.
- * @returns The transport you pass as a cluster node's `transport`.
+ * Adapts a cluster node to the {@link Narsil} interface, so
+ * `createServer` from `@delali/narsil/server` serves the cluster the way it
+ * serves a single engine.
+ *
+ * Writes, updates, searches, suggestions, listings, counts, index creation,
+ * index removal, and document reads route through the cluster. Checkpointing,
+ * memory statistics, and engine events reach this node's local engine, because
+ * each covers a per-node fact. Every other operation fails with
+ * `CLUSTER_OPERATION_UNSUPPORTED`, which the HTTP server answers with status
+ * 501, so a caller learns the operation is missing rather than reading a
+ * wrong answer. That covers `getStats`, `getPartitionStats`, and
+ * `listIndexes` as well, because {@link Narsil} declares them synchronous and
+ * a cluster answer needs a round trip; call them on the
+ * {@link ClusterNode} itself, where they are asynchronous.
+ *
+ * @param node - The cluster node the adapter serves.
+ * @param options - How the forwarded operations are shaped, such as the
+ * partition count and replication factor of created indexes.
+ * @returns The node behind the {@link Narsil} interface.
  *
  * @public
  */
-declare function createInMemoryTransport(nodeId: string, network: InMemoryNetwork, config?: Partial<TransportConfig>): NodeTransport;
+declare function clusterNodeEngine(node: ClusterNode, options?: ClusterEngineOptions): Narsil;
 
-export { AllocationTable, ClusterCoordinator, type ClusterNamespace, type ClusterNode, type ClusterNodeConfig, type ClusterNodeInfo, type CreateIndexOptions, DEFAULT_CAPACITY, DEFAULT_PARTITION_COUNT, DEFAULT_REPLICATION_FACTOR, type InMemoryNetwork, type InMemoryTransportInternal, NodeCapacity, NodeRole, type NodeTransport, type ReplicationConfig, type StreamResponder, type TransportConfig, type TransportMessage, createClusterNode, createInMemoryNetwork, createInMemoryTransport };
+export { AllocationTable, ClusterCoordinator, type ClusterEngineOptions, type ClusterNamespace, type ClusterNode, type ClusterNodeConfig, type ClusterNodeInfo, type CreateIndexOptions, DEFAULT_CAPACITY, DEFAULT_PARTITION_COUNT, DEFAULT_REPLICATION_FACTOR, NodeCapacity, NodeRole, NodeTransport, type ReplicationConfig, clusterNodeEngine, createClusterNode };