@delali/narsil 0.2.0 → 0.2.1-next.25

package/dist/server.d.ts

@@ -1,38 +1,72 @@
-import { N as Narsil } from './narsil-CMZRPDlQ.js';
-import { E as EmbeddingAdapter } from './adapters-Bo2JQg8b.js';
-import './schema-BnvLvjRp.js';
-import './config-P27AtSn4.js';
+import { N as Narsil } from './engine-CCrlfLyq.js';
+import { E as EmbeddingAdapter } from './adapters-CVqI5NBt.js';
+import './search-CgQQIciB.js';
+import './schema-CE6S_aAr.js';
 
 /**
  * Context handed to {@link OnRequestHook} for every inbound request, captured
  * synchronously before any body is read. `remoteAddress` is the peer address
  * decoded from the socket; behind a proxy it is the proxy's address, so trust
  * forwarded headers only when the proxy is trusted.
+ *
+ * @public
  */
 interface RequestContext {
+    /** The request used this HTTP method, in upper case. */
     method: string;
+    /** The request asked for this path, without the query string. */
     path: string;
+    /** These are the request headers, keyed by lower-case name. */
     headers: Record<string, string>;
+    /** The server decoded this peer address from the socket. */
     remoteAddress: string;
 }
 /**
  * Returned by an {@link OnRequestHook} to reject a request. The `status` is sent
  * verbatim as the HTTP status; `code` and `message` populate the error envelope.
+ *
+ * @public
  */
 interface RequestDenial {
+    /** The server answers with this status. */
     status: number;
+    /** The error envelope carries this machine-readable code. */
     code: string;
+    /** The error envelope carries this description. */
     message: string;
 }
+/**
+ * Runs before every routed request, which is where authentication, rate
+ * limiting, and any other admission rule goes.
+ *
+ * @param ctx - The request's method, path, headers, and peer address.
+ * @returns A {@link RequestDenial} to reject the request, or `undefined` to
+ * let it through.
+ *
+ * @public
+ */
 type OnRequestHook = (ctx: RequestContext) => undefined | RequestDenial | Promise<undefined | RequestDenial>;
+/**
+ * Which cross-origin requests the server accepts.
+ *
+ * Passing `true` for `cors` instead of this object accepts any origin, which
+ * suits local development and little else.
+ *
+ * @public
+ */
 interface CorsOptions {
+    /** The server allows these origins, given as one origin or a list. */
     origin?: string | string[];
+    /** The server allows these methods on a cross-origin request. */
     methods?: string[];
+    /** A browser may send these request headers cross-origin. */
     headers?: string[];
 }
 /**
  * Byte and batch ceilings the server enforces before handing work to the
  * engine. Every field has a safe default; override only to fit a deployment.
+ *
+ * @public
  */
 interface ServerLimits {
     /** Cap for JSON request bodies (single doc, batch, search). Excess → 413. */
@@ -54,9 +88,20 @@ interface ServerLimits {
      * Defaults to 10000. */
     maxFetchDocuments?: number;
 }
+/**
+ * Everything {@link createServer} accepts.
+ *
+ * Every field is optional, and a server created without any of them binds to
+ * loopback with the default limits and no authentication.
+ *
+ * @public
+ */
 interface ServerOptions {
+    /** The server binds to this address, and to loopback by default. Any other address needs an authentication hook. */
     host?: string;
+    /** The server binds to this port. Pass 0 to let the operating system choose one, then read {@link NarsilServer.listeningPort}. */
     port?: number;
+    /** These settings control which cross-origin requests the server accepts, and `true` accepts any origin. */
     cors?: boolean | CorsOptions;
     /** Authentication or admission gate run before every routed request. */
     onRequest?: OnRequestHook;
@@ -77,6 +122,7 @@ interface ServerOptions {
      * needs query-time or ingest-time embedding names a server-registered adapter.
      */
     embeddingAdapters?: Record<string, EmbeddingAdapter>;
+    /** These ceilings apply before the server hands any work to the engine. */
     limits?: ServerLimits;
     /**
      * Backing store for long-running task records. Defaults to an in-memory store
@@ -93,52 +139,127 @@ interface ServerOptions {
      */
     instanceId?: string;
     /**
-     * Allows binding to a non-loopback address without an {@link onRequest} auth
-     * hook. The server otherwise refuses to start in that configuration because it
-     * exposes destructive admin endpoints. Set this only when the address is on a
-     * trusted private network where access is controlled elsewhere.
+     * Allows binding to a non-loopback address without an
+     * {@link ServerOptions.onRequest} auth hook. The server otherwise refuses to
+     * start in that configuration because it exposes destructive admin endpoints.
+     * Set this only when the address is on a trusted private network where access
+     * is controlled elsewhere.
      */
     allowInsecure?: boolean;
 }
 /**
  * Pluggable backing store for task records. Every method is async so any
- * backend works — an in-memory map, Redis, an HTTP key-value service, or a
+ * backend works: an in-memory map, Redis, an HTTP key-value service, or a
  * database. `set` upserts by `record.id`; `get` returns null for an unknown id.
  * `ttlMs`, when honored by the backend, expires the record so terminal tasks do
  * not accumulate. The server never calls a method that mutates a record it did
  * not construct, so a backend may treat records as immutable snapshots.
+ *
+ * @public
  */
 interface TaskStore {
+    /**
+     * Stores a record, replacing whatever its id already held.
+     *
+     * @param record - The record to store.
+     * @param ttlMs - Milliseconds after which the backend may drop it, which
+     * keeps finished tasks from accumulating. Ignore it in a backend without
+     * expiry.
+     */
     set(record: TaskRecord, ttlMs?: number): Promise<void>;
+    /**
+     * Reads one record back.
+     *
+     * @param id - The task to read.
+     * @returns The record, or `null` when the store holds no such id.
+     */
     get(id: string): Promise<TaskRecord | null>;
+    /**
+     * Lists every record the store holds.
+     *
+     * @returns Each record the backend still has.
+     */
     list(): Promise<TaskRecord[]>;
+    /**
+     * Removes one record. An id the store never held is not an error.
+     *
+     * @param id - The task to remove.
+     */
     delete(id: string): Promise<void>;
+    /** Releases whatever the backend holds open, such as a connection pool. */
     shutdown?(): Promise<void>;
 }
+/**
+ * The running HTTP server, as {@link createServer} returns it.
+ *
+ * @public
+ */
 interface NarsilServer {
+    /**
+     * Binds the socket and starts answering requests.
+     *
+     * @throws An error when the address is already in use, or when a non-loopback
+     * address is configured without an authentication hook.
+     */
     listen(): Promise<void>;
+    /** Closes the socket and ends the server. The engine keeps running. */
     close(): Promise<void>;
+    /** The server bound to this port, which is what you read after binding to port 0. */
     readonly listeningPort: number;
 }
+/**
+ * The body every failed response carries, which is what an HTTP client parses
+ * on a non-2xx status.
+ *
+ * @public
+ */
 interface ErrorEnvelope {
+    /** This describes the failure. */
     error: {
+        /** This code comes from either {@link ServerErrorCodes} or {@link ErrorCodes}. */
         code: string;
+        /** This describes the failure, for a log or a person. */
         message: string;
+        /** These values are behind the failure, such as the field or limit involved. */
         details?: Record<string, unknown>;
     };
 }
+/**
+ * Which long-running operation a task record tracks.
+ *
+ * @public
+ */
 type TaskType = 'optimizeVectors' | 'rebalance' | 'restore';
+/**
+ * Where a long-running operation stands.
+ *
+ * @public
+ */
 type TaskStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+/**
+ * One long-running operation, which the server answers with straight away and
+ * you then poll.
+ *
+ * @public
+ */
 interface TaskRecord {
+    /** This identifies the task, and is what you poll by. */
     id: string;
+    /** This says which operation the task runs. */
     type: TaskType;
+    /** The operation runs against this index. */
     indexName: string;
+    /** This says where the operation stands. */
     status: TaskStatus;
     /** Identifier of the server instance running this task; see ServerOptions.instanceId. */
     owner: string;
+    /** The server accepted the task at this many milliseconds since the epoch. */
     createdAt: number;
+    /** Work started at this many milliseconds since the epoch, and a queued task omits it. */
     startedAt?: number;
+    /** Work ended at this many milliseconds since the epoch, and a task omits it until it succeeds or fails. */
     completedAt?: number;
+    /** This says why the task failed, and a failed task alone carries it. */
     error?: {
         code: string;
         message: string;
@@ -148,34 +269,70 @@ interface TaskRecord {
 /** Declarative index configuration accepted over HTTP. Function-valued engine
  * options (custom tokenizer, stopWords-as-function, group reducer, embedding
  * adapter object) are not representable here; the embedding adapter is named
- * instead via {@link CreateIndexEmbedding}. */
+ * instead via {@link CreateIndexEmbedding}.
+ *
+ * @public */
 interface CreateIndexRequest {
+    /** The server creates the index under this name. */
     name: string;
+    /** This carries the schema and settings, in the subset JSON can express. */
     config: HttpIndexConfig;
 }
+/**
+ * How a JSON `createIndex` request connects an index to an embedding adapter.
+ *
+ * An adapter is a function and cannot cross JSON, so the request names one the
+ * server registered instead of carrying it.
+ *
+ * @public
+ */
 interface CreateIndexEmbedding {
+    /** This names an adapter the server registered under `embeddingAdapters`. */
     adapter?: string;
+    /** This maps each vector field to the text field, or fields, the server embeds into it. */
     fields: Record<string, string | string[]>;
 }
+/**
+ * The index settings a JSON request can carry, which is {@link IndexConfig}
+ * minus everything that is a function.
+ *
+ * A custom tokeniser, a stop-word function, and an embedding adapter object
+ * have no JSON form, so an HTTP client names a registered one or supplies a
+ * plain list instead.
+ *
+ * @public
+ */
 interface HttpIndexConfig {
+    /** This layout gives each value as either a field type or a nested schema. */
     schema: Record<string, unknown>;
+    /** The server tokenises and stems text fields with the language module registered under this name. */
     language?: string;
+    /** These settings control how the index splits documents across partitions as it grows. */
     partitions?: {
         maxDocsPerPartition?: number;
         maxPartitions?: number;
         watermark?: number;
     };
+    /** A query scores this way unless it asks for another mode. */
     defaultScoring?: 'local' | 'dfs' | 'broadcast';
+    /** These parameters tune BM25 for this index. */
     bm25?: {
         k1?: number;
         b?: number;
     };
+    /** This list replaces the language's stop words. */
     stopWords?: string[];
+    /** Setting this records term positions, which phrase queries and highlighting need. */
     trackPositions?: boolean;
+    /** Setting this returns the words users typed from suggestions and prefix expansion, instead of index stems. */
     surfaceForms?: boolean;
+    /** These settings control when vector fields move to an HNSW graph, and how that graph is built. */
     vectorPromotion?: Record<string, unknown>;
+    /** Setting this rejects a document carrying a field the schema does not declare. */
     strict?: boolean;
+    /** This names a server-registered embedding adapter and the fields it embeds. */
     embedding?: CreateIndexEmbedding;
+    /** The server rejects a document that omits any of these fields. */
     required?: string[];
 }
 
@@ -184,12 +341,21 @@ interface HttpIndexConfig {
  * (durability, embedding, workers) and hands the live instance in; the server
  * shares it across requests and never constructs or shuts it down. Start with
  * `.listen()` and stop with `.close()`; the engine is shut down separately.
+ *
+ * @param engine - The live engine every request runs against.
+ * @param options - Address, CORS, request limits, the authentication hook, and
+ * the task store. Omit it to bind to loopback with the default limits.
+ * @returns The server, ready for {@link NarsilServer.listen}.
+ *
+ * @public
  */
 declare function createServer(engine: Narsil, options?: ServerOptions): NarsilServer;
 
 /** HTTP-layer error codes for failures that arise before or around the engine
  * call (parsing, limits, routing). Engine failures carry their own
- * {@link NarsilError} codes, mapped by {@link httpStatusForNarsilError}. */
+ * {@link NarsilError} codes, mapped by {@link httpStatusForNarsilError}.
+ *
+ * @public */
 declare const ServerErrorCodes: {
     readonly INVALID_REQUEST: "INVALID_REQUEST";
     readonly INVALID_JSON: "INVALID_JSON";
@@ -204,7 +370,12 @@ declare const ServerErrorCodes: {
     readonly REQUEST_ABORTED: "REQUEST_ABORTED";
 };
 /** Maps a {@link NarsilError} code to an HTTP status. Unknown or cluster-only
- * codes fall through to 500 so an internal fault never leaks as a client error. */
+ * codes fall through to 500 so an internal fault never leaks as a client error.
+ *
+ * @param code - The code a {@link NarsilError} carried.
+ * @returns The status the server answers with.
+ *
+ * @public */
 declare function httpStatusForNarsilError(code: string): number;
 
 /**
@@ -213,14 +384,44 @@ declare function httpStatusForNarsilError(code: string): number;
  * terminal records first, so a long-lived server cannot accumulate task state
  * without bound. `ttlMs` is ignored here; the cap plays that role. Records are
  * copied in and out so a caller cannot mutate stored state by reference.
+ *
+ * @public
  */
 declare class InMemoryTaskStore implements TaskStore {
     private readonly maxRetained;
     private readonly records;
+    /**
+     * Builds a store that keeps task records in this process alone.
+     *
+     * @param maxRetained - Records to keep before the oldest finished ones are
+     * dropped. Defaults to 1000.
+     */
     constructor(maxRetained?: number);
+    /**
+     * Stores a record, replacing whatever its id already held.
+     *
+     * @param record - The record to store. A copy is kept, so changing the
+     * object afterwards leaves the store untouched.
+     */
     set(record: TaskRecord): Promise<void>;
+    /**
+     * Reads one record back.
+     *
+     * @param id - The task to read.
+     * @returns A copy of the record, or `null` when the store holds no such id.
+     */
     get(id: string): Promise<TaskRecord | null>;
+    /**
+     * Lists every record the store holds.
+     *
+     * @returns A copy of each record, oldest first.
+     */
     list(): Promise<TaskRecord[]>;
+    /**
+     * Removes one record. An id the store never held is not an error.
+     *
+     * @param id - The task to remove.
+     */
     delete(id: string): Promise<void>;
     private prune;
 }

package/dist/server.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from './chunk-M2EDG55Y.mjs';
+import { NarsilError, ErrorCodes } from './chunk-UNJZ7ZDB.mjs';
 import { randomUUID } from 'crypto';
 
 // src/server/cors.ts
@@ -1015,21 +1015,49 @@ async function loadUWebSockets() {
 // src/server/task-store.ts
 var DEFAULT_MAX_RETAINED = 1e3;
 var InMemoryTaskStore = class {
+  /**
+   * Builds a store that keeps task records in this process alone.
+   *
+   * @param maxRetained - Records to keep before the oldest finished ones are
+   * dropped. Defaults to 1000.
+   */
   constructor(maxRetained = DEFAULT_MAX_RETAINED) {
     this.maxRetained = maxRetained;
   }
   records = /* @__PURE__ */ new Map();
+  /**
+   * Stores a record, replacing whatever its id already held.
+   *
+   * @param record - The record to store. A copy is kept, so changing the
+   * object afterwards leaves the store untouched.
+   */
   async set(record) {
     this.records.set(record.id, { ...record });
     this.prune();
   }
+  /**
+   * Reads one record back.
+   *
+   * @param id - The task to read.
+   * @returns A copy of the record, or `null` when the store holds no such id.
+   */
   async get(id) {
     const record = this.records.get(id);
     return record ? { ...record } : null;
   }
+  /**
+   * Lists every record the store holds.
+   *
+   * @returns A copy of each record, oldest first.
+   */
   async list() {
     return [...this.records.values()].map((record) => ({ ...record }));
   }
+  /**
+   * Removes one record. An id the store never held is not an error.
+   *
+   * @param id - The task to remove.
+   */
   async delete(id) {
     this.records.delete(id);
   }