@delali/narsil 0.1.15 → 0.2.1-next.25

package/dist/distribution.d.ts

@@ -1,122 +1,395 @@
-import { C as ClusterCoordinator, N as NodeRegistration, A as AllocationTable, a as NodeRole, b as NodeCapacity } from './types-DHX6zGeD.js';
-export { c as AllocationConstraints, d as AllocationEvent, e as NodeEvent, P as PartitionAssignment, f as PartitionState, S as SchemaEvent } from './types-DHX6zGeD.js';
-import { B as BatchResult, Q as QueryParams, u as QueryResult, N as NarsilConfig } from './config-CojEPOgS.js';
-import { I as IndexConfig, A as AnyDocument } from './schema-DCgkO1j4.js';
+import { N as NarsilConfig } from './config-CAjTHzkH.js';
+import { B as BatchResult, Q as QueryParams, q as QueryResult } from './search-CgQQIciB.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-Bo2JQg8b.js';
+import './adapters-CVqI5NBt.js';
 
+/**
+ * How much replication history a primary keeps, and how many replicas have to
+ * confirm a write before it is acknowledged.
+ *
+ * A replica that falls further behind than the retained log recovers from a
+ * whole snapshot instead of replaying entries, so a larger retention trades
+ * memory for cheaper recovery.
+ *
+ * @public
+ */
+interface ReplicationConfig {
+    /** A primary keeps this many bytes of replication log before it drops the oldest entries. */
+    logRetentionBytes: number;
+    /** This many replicas must acknowledge a write before the primary reports it as done. */
+    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>;
 }
 
-interface ControllerConfig {
-    nodeId: string;
-    coordinator: ClusterCoordinator;
-    transport: NodeTransport;
-    leaseTtlMs: number;
-    standbyRetryMs: number;
-    knownIndexNames: string[];
-    onError?: (indexName: string, error: unknown) => void;
-}
-interface ControllerNode {
-    readonly isActive: boolean;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    shutdown(): Promise<void>;
-}
-
-type DataNodeLifecycleStatus = 'stopped' | 'joining' | 'active' | 'leaving' | 'shutdown';
-interface NodeLifecycleConfig {
-    registration: NodeRegistration;
-    coordinator: ClusterCoordinator;
-    transport: NodeTransport;
-    knownIndexNames: string[];
-    bootstrapRetryBaseMs: number;
-    bootstrapRetryMaxMs: number;
-    bootstrapMaxRetries: number;
-    allocationDebounceMs: number;
-    onBootstrapPartition: (indexName: string, partitionId: number, primaryNodeId: string) => Promise<boolean>;
-    onRemovePartition?: (indexName: string, partitionId: number) => void;
-    onPrimaryDemotion?: (indexName: string, partitionId: number, newPrimaryNodeId: string) => void;
-    onError?: (error: unknown) => void;
-}
-interface DataNodeHandle {
-    readonly status: DataNodeLifecycleStatus;
-    readonly nodeId: string;
-    join(): Promise<void>;
-    leave(): Promise<void>;
-    shutdown(): Promise<void>;
-}
-
+/**
+ * Everything {@link createClusterNode} needs to join a node to a cluster.
+ *
+ * The coordinator and the transport are the two pieces you choose: the
+ * coordinator holds the cluster's shared state, and the transport carries
+ * messages between nodes.
+ *
+ * @public
+ */
 interface ClusterNodeConfig {
+    /** This node reads and writes the cluster's shared state here. Every node in a cluster must point at the same one. */
     coordinator: ClusterCoordinator;
+    /** This node reaches its peers through this transport. */
     transport: NodeTransport;
+    /** Peers reach this node at this address, as the transport writes it. */
     address: string;
+    /** This node holds these roles in the cluster, and holds data alone by default. */
     roles?: NodeRole[];
+    /** This identifies the node across the cluster. The package generates an id by default, which a restart changes. */
     nodeId?: string;
+    /** This node offers this much capacity, which the allocator weighs. It offers {@link DEFAULT_CAPACITY} by default. */
     capacity?: NodeCapacity;
+    /** These settings configure the engine this node runs locally, such as its persistence and durability. */
     engine?: NarsilConfig;
+    /** These replication settings override the engine's own, and anything you leave out keeps its value. */
+    replication?: Partial<ReplicationConfig>;
+    /** This receives the failures the node reports while running on its own, away from any call you made. */
     onError?: (error: Error) => void;
 }
+/**
+ * How an index is spread across the cluster when a node creates it.
+ *
+ * @public
+ */
 interface CreateIndexOptions {
+    /** The cluster splits the index into this many partitions, and into {@link DEFAULT_PARTITION_COUNT} by default. */
     partitionCount?: number;
+    /** The cluster keeps this many copies of each partition, and {@link DEFAULT_REPLICATION_FACTOR} by default. */
     replicationFactor?: number;
 }
+/**
+ * The cluster-facing side of a node, which is where you look at the cluster
+ * rather than at the data.
+ *
+ * @public
+ */
 interface ClusterNamespace {
+    /**
+     * Reads how one index is spread across the cluster.
+     *
+     * @param indexName - The index to describe.
+     * @returns Its allocation, or `null` when the index has none yet.
+     */
     getAllocation(indexName: string): Promise<AllocationTable | null>;
+    /**
+     * Describes this node.
+     *
+     * @returns Its id, its roles, and where it stands.
+     */
     getNodeInfo(): ClusterNodeInfo;
+    /**
+     * Reports whether this node is the cluster's active controller, which is the
+     * one node making allocation decisions.
+     *
+     * @returns True while this node holds the controller lease.
+     */
     isControllerActive(): boolean;
 }
+/**
+ * What one node reports about itself.
+ *
+ * @public
+ */
 interface ClusterNodeInfo {
+    /** This identifies the node across the cluster. */
     nodeId: string;
+    /** The node holds these roles in the cluster. */
     roles: ReadonlyArray<NodeRole>;
+    /** This says where the node stands, from joining through to shut down. */
     status: string;
 }
+/**
+ * One node of a cluster, which routes each write to the partition's primary
+ * and gathers each search from every partition.
+ *
+ * The write and search methods mirror {@link Narsil}, so code moving from a
+ * single engine to a cluster keeps its shape. Build one with
+ * {@link createClusterNode}.
+ *
+ * @public
+ */
 interface ClusterNode {
+    /** This identifies the node across the cluster. */
     readonly nodeId: string;
+    /** The node holds these roles in the cluster. */
     readonly roles: ReadonlyArray<NodeRole>;
+    /**
+     * Creates an index across the cluster, publishing its schema and allocating
+     * its partitions to nodes.
+     *
+     * @param name - Every later call uses this name to reach the index.
+     * @param config - The schema, and the language, scoring, and vector
+     * settings, exactly as a single engine takes them.
+     * @param options - How the index is spread across the cluster.
+     */
     createIndex(name: string, config: IndexConfig, options?: CreateIndexOptions): Promise<void>;
+    /**
+     * Adds one document, routing it to the partition's primary.
+     *
+     * @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.
+     * @returns The id the document is stored under.
+     */
     insert(indexName: string, document: AnyDocument, docId?: string): 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.
+     * @returns The ids written, and each rejection with its error.
+     */
     insertBatch(indexName: string, documents: AnyDocument[]): Promise<BatchResult>;
+    /**
+     * Removes one document.
+     *
+     * @param indexName - The index holding the document.
+     * @param docId - The document to remove.
+     */
     remove(indexName: string, docId: string): Promise<void>;
+    /**
+     * Removes many documents and reports each one's outcome.
+     *
+     * @param indexName - The index holding the documents.
+     * @param docIds - The documents to remove.
+     * @returns The ids removed, and each failure with its error.
+     */
     removeBatch(indexName: string, docIds: string[]): Promise<BatchResult>;
+    /**
+     * Runs a search across every partition and merges the results into one
+     * ranking.
+     *
+     * The search skips a partition whose nodes are all unreachable instead of
+     * failing, so read the result's count against what you expect.
+     *
+     * @typeParam T - Shape of the stored documents.
+     * @param indexName - The index the search runs against.
+     * @param params - The same parameters a single engine takes.
+     * @returns The merged hits, the total count, and the elapsed time.
+     */
     query<T = AnyDocument>(indexName: string, params: QueryParams): Promise<QueryResult<T>>;
+    /** 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. */
     start(): Promise<void>;
+    /** 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.
+ *
+ * The node is idle until you call {@link ClusterNode.start}, which registers
+ * it, takes on the partitions the controller allocates to it, and starts
+ * answering. A node whose roles include `controller` stands for election and
+ * runs allocation for the whole cluster while it holds the lease.
+ *
+ * @param config - The coordinator, the transport, this node's address, and the
+ * settings for the engine it runs locally.
+ * @returns The node, ready for {@link ClusterNode.start}.
+ *
+ * @public
+ */
 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.
+ *
+ * @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;
 }
+/**
+ * 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`.
+ *
+ * @public
+ */
 declare function createInMemoryTransport(nodeId: string, network: InMemoryNetwork, config?: Partial<TransportConfig>): NodeTransport;
 
-export { AllocationTable, ClusterCoordinator, type ClusterNamespace, type ClusterNode, type ClusterNodeConfig, type ClusterNodeInfo, type ControllerConfig, type ControllerNode, type CreateIndexOptions, DEFAULT_CAPACITY, DEFAULT_PARTITION_COUNT, DEFAULT_REPLICATION_FACTOR, type DataNodeHandle, type InMemoryNetwork, type InMemoryTransportInternal, NodeCapacity, type NodeLifecycleConfig, NodeRegistration, NodeRole, type NodeTransport, type TransportConfig, createClusterNode, createInMemoryNetwork, createInMemoryTransport };
+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 };