@delali/narsil 0.2.0 → 0.2.1

package/dist/config-CAjTHzkH.d.ts

@@ -0,0 +1,256 @@
+import { b as PersistenceAdapter, I as InvalidationAdapter, E as EmbeddingAdapter } from './adapters-CVqI5NBt.js';
+import { Q as QueryParams, q as QueryResult } from './search-CgQQIciB.js';
+import { I as IndexConfig, A as AnyDocument } from './schema-CE6S_aAr.js';
+
+/**
+ * Hooks that run alongside the engine's own work, which is how you add
+ * validation, auditing, enrichment, or metrics without forking the engine.
+ *
+ * Every hook is optional. A `before` hook runs first and rejects the operation
+ * by throwing; an `after` hook runs once the operation succeeds. The engine
+ * awaits a hook that returns a promise, so slow work in one slows every write
+ * or search it covers.
+ *
+ * @public
+ */
+interface NarsilPlugin {
+    /** This name identifies the plugin in errors and in event payloads. */
+    name: string;
+    /** Runs before a document is indexed. Throw to reject the write. */
+    beforeInsert?(ctx: InsertContext): void | Promise<void>;
+    /** Runs once a document is indexed. */
+    afterInsert?(ctx: InsertContext): void | Promise<void>;
+    /** Runs before a document is removed. Throw to reject the removal. */
+    beforeRemove?(ctx: RemoveContext): void | Promise<void>;
+    /** Runs once a document is removed. */
+    afterRemove?(ctx: RemoveContext): void | Promise<void>;
+    /** Runs before a document is replaced. Throw to reject the update. */
+    beforeUpdate?(ctx: UpdateContext): void | Promise<void>;
+    /** Runs once a document is replaced. */
+    afterUpdate?(ctx: UpdateContext): void | Promise<void>;
+    /** Runs before a search executes. Throw to reject the query. */
+    beforeSearch?(ctx: SearchContext): void | Promise<void>;
+    /** Runs once a search returns, with the results on the context. */
+    afterSearch?(ctx: SearchContext): void | Promise<void>;
+    /** Runs once an index is created. */
+    onIndexCreate?(ctx: IndexContext): void | Promise<void>;
+    /** Runs once an index is dropped. */
+    onIndexDrop?(ctx: IndexContext): void | Promise<void>;
+    /** Runs once an index grows into another partition. */
+    onPartitionSplit?(ctx: PartitionContext): void | Promise<void>;
+    /** Runs once the engine moves its indexes onto worker threads. */
+    onWorkerPromote?(ctx: WorkerContext): void | Promise<void>;
+}
+/**
+ * What a plugin receives around an insert.
+ *
+ * @public
+ */
+interface InsertContext {
+    /** The engine writes the document to this index. */
+    indexName: string;
+    /** The document is stored under this id, which the engine resolves before the `before` hook runs. */
+    docId: string;
+    /** This is the document itself, and the engine indexes whatever a `before` hook leaves here. */
+    document: AnyDocument;
+}
+/**
+ * What a plugin receives around a removal.
+ *
+ * @public
+ */
+interface RemoveContext {
+    /** The engine removes the document from this index. */
+    indexName: string;
+    /** This document is being removed. */
+    docId: string;
+}
+/**
+ * What a plugin receives around an update.
+ *
+ * @public
+ */
+interface UpdateContext {
+    /** The document belongs to this index. */
+    indexName: string;
+    /** This document is being replaced. */
+    docId: string;
+    /** The index stored this document before the update. */
+    oldDocument: AnyDocument;
+    /** This document replaces it, and the engine indexes whatever a `before` hook leaves here. */
+    newDocument: AnyDocument;
+}
+/**
+ * What a plugin receives around a search.
+ *
+ * @public
+ */
+interface SearchContext {
+    /** The search runs against this index. */
+    indexName: string;
+    /** These are the parameters the query runs with, and a `before` hook that changes them rewrites the search. */
+    params: QueryParams;
+    /** These are the results, which an `after` hook alone receives. */
+    results?: QueryResult;
+}
+/**
+ * What a plugin receives when an index is created or dropped.
+ *
+ * @public
+ */
+interface IndexContext {
+    /** This index is being created or dropped. */
+    indexName: string;
+    /** The index was created with this configuration. */
+    config: IndexConfig;
+}
+/**
+ * What a plugin receives when an index grows into another partition.
+ *
+ * @public
+ */
+interface PartitionContext {
+    /** This index grew. */
+    indexName: string;
+    /** The index held this many partitions before. */
+    oldPartitionCount: number;
+    /** The index holds this many partitions now. */
+    newPartitionCount: number;
+}
+/**
+ * What a plugin receives when the engine moves onto worker threads.
+ *
+ * @public
+ */
+interface WorkerContext {
+    /** The pool started with this many workers. */
+    workerCount: number;
+    /** The engine promoted for this reason, such as the threshold the index passed. */
+    reason: string;
+}
+
+/**
+ * Everything {@link createNarsil} accepts when it builds an engine.
+ *
+ * Every field is optional, and an engine created without any of them keeps
+ * its indexes in memory alone. Add persistence to survive a restart, add
+ * invalidation to share a store with another process, and add durability to
+ * recover the writes made since the last snapshot.
+ *
+ * @public
+ */
+interface NarsilConfig {
+    /** This adapter writes partitions somewhere they outlive the process. */
+    persistence?: PersistenceAdapter;
+    /** This channel carries partition changes to other instances sharing the store. */
+    invalidation?: InvalidationAdapter;
+    /** These hooks observe or reject writes, searches, and lifecycle changes. */
+    plugins?: NarsilPlugin[];
+    /** This supplies the id for a document inserted without one. The engine generates a UUID v7 by default. */
+    idGenerator?: () => string;
+    /** These settings control when the engine moves its indexes onto worker threads, and how many it uses. */
+    workers?: WorkerConfig;
+    /** Every index uses this adapter unless its own config names another. */
+    embedding?: EmbeddingAdapter;
+    /** Named adapters; names persist in index metadata so recovery can rebind. */
+    embeddingAdapters?: Record<string, EmbeddingAdapter>;
+    /** These settings recover the writes made since the last snapshot. */
+    durability?: DurabilityConfig;
+    /** These settings control what the engine does when an index's stored analysis differs from its language module. */
+    analysis?: AnalysisConfig;
+}
+/**
+ * Describes an index whose stored terms came from an older analysis than the
+ * one its language module carries today.
+ *
+ * The engine hands this to {@link AnalysisConfig.onStaleAnalysis} together
+ * with the rebuild that fixes it, so you decide when the work runs.
+ *
+ * @public
+ */
+interface StaleAnalysis {
+    /** This index holds terms that are out of date. */
+    indexName: string;
+    /** The index was built with this language module. */
+    language: string;
+    /** The index recorded this revision when it was written, and `null` for an index written before revisions existed. */
+    storedRevision: string | null;
+    /** The language module carries this revision now. */
+    currentRevision: string;
+    /** The rebuild reindexes this many documents. */
+    documentCount: number;
+}
+/**
+ * What the engine does when an index's stored terms no longer match the
+ * analysis its language module produces.
+ *
+ * A stale index answers text queries from terms an older analysis wrote, and
+ * every such result reports `analysisStale`. Rebuilding fixes it, and this
+ * setting controls whether the engine starts that work itself.
+ *
+ * @public
+ */
+interface AnalysisConfig {
+    /** `auto` rebuilds a stale index in the background, and `manual` leaves it to you. The engine rebuilds automatically by default. */
+    rebuild?: 'auto' | 'manual';
+    /**
+     * Called once for each stale index the engine finds.
+     *
+     * @param index - The index that is stale, and how far behind it is.
+     * @param rebuild - Starts the rebuild and resolves once every partition
+     * carries current terms. Under `manual` nothing rebuilds until you call it.
+     */
+    onStaleAnalysis?(index: StaleAnalysis, rebuild: () => Promise<void>): void | Promise<void>;
+}
+/**
+ * Write-ahead logging and checkpointing, which recover the writes made since
+ * the last snapshot.
+ *
+ * The `wal` tier logs every mutation before applying it, so a crash costs
+ * nothing once the log replays. The `snapshot` tier writes whole partitions on
+ * an interval, which is cheaper to run and loses whatever arrived after the
+ * last write.
+ *
+ * @public
+ */
+interface DurabilityConfig {
+    /** `wal` logs every mutation, and `snapshot` writes whole partitions on an interval. */
+    tier?: 'wal' | 'snapshot';
+    /** The engine writes the log and its checkpoints into this directory. */
+    directory?: string;
+    /** `sync` flushes before a write resolves, and `async` flushes on the interval below. */
+    mode?: 'sync' | 'async';
+    /** In `async` mode the engine flushes this many milliseconds apart. */
+    flushIntervalMs?: number;
+    /** The log rolls over to a new segment once it reaches this size. */
+    segmentMaxBytes?: number;
+    /** The engine checkpoints this many milliseconds apart, which shortens the replay a restart has to do. */
+    checkpointIntervalMs?: number;
+    /** This many mutations trigger a checkpoint before the interval elapses. */
+    checkpointMutationThreshold?: number;
+    /** Compaction reclaims the log once this fraction of it is dead. */
+    compactionThreshold?: number;
+}
+/**
+ * When the engine moves its indexes onto worker threads, and how many it uses.
+ *
+ * An engine starts on the main thread, where a small index answers fastest.
+ * Once an index passes a threshold the engine promotes it to a worker pool, so
+ * that indexing and searching run off the calling thread.
+ *
+ * @public
+ */
+interface WorkerConfig {
+    /** Setting this allows promotion to worker threads. The engine promotes nothing while it is false. */
+    enabled?: boolean;
+    /** The pool runs this many workers. The engine derives a count from the host's cores by default. */
+    count?: number;
+    /** This many documents in one index trigger promotion. */
+    promotionThreshold?: number;
+    /** This many documents across every index trigger promotion. */
+    totalPromotionThreshold?: number;
+    /** Each worker imports this module on start-up, which is how a worker reaches a custom tokeniser or language. */
+    bootstrapModule?: string;
+}
+
+export type { AnalysisConfig as A, DurabilityConfig as D, IndexContext as I, NarsilConfig as N, PartitionContext as P, RemoveContext as R, SearchContext as S, UpdateContext as U, WorkerConfig as W, InsertContext as a, NarsilPlugin as b, StaleAnalysis as c, WorkerContext as d };

package/dist/{direct-executor-2FV3MEDD.mjs → direct-executor-3W4QRA4E.mjs}

@@ -1,5 +1,5 @@
-export { createDirectExecutor } from './chunk-S6IAXOBA.mjs';
+export { createDirectExecutor } from './chunk-ASI6AOW2.mjs';
 import './chunk-TGP5M5R7.mjs';
 import './chunk-S7RJJMHI.mjs';
 import './chunk-U2BKYEC7.mjs';
-import './chunk-M2EDG55Y.mjs';
+import './chunk-UNJZ7ZDB.mjs';

package/dist/distribution/coordinator/etcd.d.ts

@@ -1,16 +1,57 @@
-import { C as ClusterCoordinator } from '../../types-BRTcBgAp.js';
-import '../../schema-BnvLvjRp.js';
-import '../../adapters-Bo2JQg8b.js';
+import { C as ClusterCoordinator } from '../../types-BV3nAKTL.js';
+import '../../schema-CE6S_aAr.js';
+import '../../adapters-CVqI5NBt.js';
 
+/**
+ * How {@link createEtcdCoordinator} reaches etcd, and how long the leases it
+ * takes there survive.
+ *
+ * @public
+ */
 interface EtcdCoordinatorConfig {
+    /** The coordinator connects to these etcd endpoints. */
     endpoints: string[];
+    /** The coordinator writes every key under this prefix, which lets one etcd cluster hold several Narsil clusters. */
     keyPrefix: string;
+    /** A node's registration survives this many seconds without a heartbeat, after which peers treat the node as gone. */
     nodeHeartbeatTtlSeconds: number;
+    /** The controller lease survives this many seconds without renewal, which is how long a failover takes at worst. */
     leaseTtlSeconds: number;
 }
 
+/**
+ * Checks that a node id is safe to use as part of an etcd key.
+ *
+ * The coordinator builds each key from the node id, so an id carrying a
+ * separator or a traversal sequence would reach another node's keys. Call it
+ * when you generate ids yourself, and the coordinator calls it on every
+ * registration regardless.
+ *
+ * @param nodeId - The id to check.
+ * @throws A `NarsilError` with `CONFIG_INVALID` when the id is empty, longer
+ * than 255 characters, or carries a slash, a backslash, `..`, or a null byte.
+ *
+ * @public
+ */
 declare function validateNodeId(nodeId: string): void;
 
+/**
+ * Builds a coordinator backed by etcd, which is what holds a cluster's shared
+ * state across hosts and restarts.
+ *
+ * etcd gives the coordinator what a cluster depends on: leases that expire once
+ * a node misses its heartbeats, and compare-and-set writes that keep two
+ * controllers from disagreeing. Install `etcd3` alongside this package,
+ * because it is an optional peer dependency this call loads on demand.
+ *
+ * @param config - Endpoints, key prefix, and lease lifetimes to override.
+ * Anything you leave out keeps its default.
+ * @returns A coordinator you pass as a cluster node's `coordinator`.
+ * @throws A `NarsilError` with `COORDINATOR_DEPENDENCY_MISSING` when `etcd3`
+ * is not installed.
+ *
+ * @public
+ */
 declare function createEtcdCoordinator(config?: Partial<EtcdCoordinatorConfig>): Promise<ClusterCoordinator>;
 
 export { type EtcdCoordinatorConfig, createEtcdCoordinator, validateNodeId };

package/dist/distribution/coordinator/etcd.mjs

@@ -1,2 +1,2 @@
-export { createEtcdCoordinator, validateNodeId } from '../../chunk-AUMKFYTG.mjs';
-import '../../chunk-M2EDG55Y.mjs';
+export { createEtcdCoordinator, validateNodeId } from '../../chunk-FKK76OR7.mjs';
+import '../../chunk-UNJZ7ZDB.mjs';

package/dist/distribution/coordinator/in-memory.d.ts

@@ -1,7 +1,18 @@
-import { C as ClusterCoordinator } from '../../types-BRTcBgAp.js';
-import '../../schema-BnvLvjRp.js';
-import '../../adapters-Bo2JQg8b.js';
+import { C as ClusterCoordinator } from '../../types-BV3nAKTL.js';
+import '../../schema-CE6S_aAr.js';
+import '../../adapters-CVqI5NBt.js';
 
+/**
+ * Builds a coordinator that holds the cluster's shared state in one process's
+ * memory, which is what runs a whole cluster inside a test.
+ *
+ * Every node has to share the same instance, and nothing survives the process,
+ * so use {@link createEtcdCoordinator} for a cluster that spans hosts.
+ *
+ * @returns A coordinator you pass as a cluster node's `coordinator`.
+ *
+ * @public
+ */
 declare function createInMemoryCoordinator(): ClusterCoordinator;
 
 export { createInMemoryCoordinator };