@delali/narsil 0.2.2 → 0.2.3-next.32

package/dist/{schema-CE6S_aAr.d.ts → schema-emTQfEiX.d.ts}

@@ -1,4 +1,4 @@
-import { E as EmbeddingAdapter } from './adapters-CVqI5NBt.js';
+import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
 
 /**
  * A document as the engine stores it: any set of fields, with an optional `id`.
@@ -19,9 +19,13 @@ type AnyDocument = Record<string, unknown> & {
  * and `vector[N]` holds an N-dimensional embedding. Each array form indexes
  * every element of the field.
  *
+ * `string:sortable` is a `string` in every respect, and a sort may name it.
+ * Ordering text costs far more memory per document than ordering a number, so
+ * a sort naming a plain `string` field raises `SEARCH_INVALID_FIELD`.
+ *
  * @public
  */
-type FieldType = 'string' | 'number' | 'boolean' | 'enum' | 'geopoint' | `vector[${number}]` | 'string[]' | 'number[]' | 'boolean[]' | 'enum[]';
+type FieldType = 'string' | 'string:sortable' | 'number' | 'boolean' | 'enum' | 'geopoint' | `vector[${number}]` | 'string[]' | 'number[]' | 'boolean[]' | 'enum[]';
 /**
  * The field layout of an index, written as a plain object.
  *
@@ -123,8 +127,10 @@ interface IndexConfig {
     /** The engine rejects a document that omits any of these fields. */
     required?: string[];
     /**
-     * Return the words users typed from suggest() and prefix expansion
-     * instead of index stems, at an insert-throughput cost. Default false.
+     * Setting this to false stops the index recording the spellings a stemmer
+     * changed, so {@link Narsil.suggest} and prefix completions fall back to
+     * index stems such as `qualiti`. It defaults to true, which costs a little
+     * insert throughput and one entry per changed spelling.
      */
     surfaceForms?: boolean;
 }
@@ -137,9 +143,17 @@ interface IndexConfig {
  * @public
  */
 interface BM25Params {
-    /** This saturates term frequency, so a higher value lets a repeated term keep raising a score. It defaults to 1.2. */
+    /**
+     * This saturates term frequency, so a higher value lets a repeated term
+     * keep raising a score. It defaults to 1.2, and it must be a finite number
+     * at or above 0 or index creation fails with `CONFIG_INVALID`.
+     */
     k1?: number;
-    /** This normalises by field length, from 0 for none to 1 for full. It defaults to 0.75. */
+    /**
+     * This normalises by field length, from 0 for none to 1 for full. It
+     * defaults to 0.75, and it must lie between 0 and 1 or index creation
+     * fails with `CONFIG_INVALID`.
+     */
     b?: number;
 }
 /**
@@ -205,4 +219,4 @@ interface InsertOptions {
     skipClone?: boolean;
 }
 
-export type { AnyDocument as A, BM25Params as B, CustomTokenizer as C, EmbeddingFieldConfig as E, FieldType as F, IndexConfig as I, PartitionConfig as P, StopWordOverride as S, VectorIndexConfig as V, InsertOptions as a, SchemaDefinition as b, ScoringMode as c, VectorQuantizationMode as d };
+export type { AnyDocument as A, BM25Params as B, CustomTokenizer as C, EmbeddingFieldConfig as E, FieldType as F, IndexConfig as I, PartitionConfig as P, SchemaDefinition as S, VectorIndexConfig as V, InsertOptions as a, ScoringMode as b, StopWordOverride as c, VectorQuantizationMode as d };

package/dist/{search-DLBtiPdQ.d.ts → search-CQ-9bKxo.d.ts}

@@ -1,4 +1,4 @@
-import { A as AnyDocument, b as SchemaDefinition, c as ScoringMode } from './schema-CE6S_aAr.js';
+import { A as AnyDocument, S as SchemaDefinition, b as ScoringMode } from './schema-emTQfEiX.js';
 
 /**
  * Every code a {@link NarsilError} carries, grouped by the part of the engine
@@ -21,6 +21,7 @@ declare const ErrorCodes: {
     readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
     readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
     readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
+    readonly INDEX_ORPHANED: "INDEX_ORPHANED";
     readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
     readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
     readonly WORKER_CRASHED: "WORKER_CRASHED";
@@ -38,6 +39,7 @@ declare const ErrorCodes: {
     readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
     readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
     readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
+    readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
     readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
     readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
     readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
@@ -52,6 +54,7 @@ declare const ErrorCodes: {
     readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
     readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
     readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
+    readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
     readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
     readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
     readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
@@ -62,6 +65,7 @@ declare const ErrorCodes: {
     readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
     readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
     readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
+    readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
     readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
     readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
     readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
@@ -102,11 +106,76 @@ declare const ErrorCodes: {
 };
 /**
  * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
- * when you branch on a failure.
+ * when you branch on a failure the engine raised.
  *
  * @public
  */
 type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Every code the HTTP layer raises for a failure that arises before or around
+ * the engine call, such as parsing the body, enforcing a limit, or routing.
+ *
+ * The engine raises none of these, so a failure carrying one of them says the
+ * request never reached the engine.
+ *
+ * @public
+ */
+declare const ServerErrorCodes: {
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly INVALID_JSON: "INVALID_JSON";
+    readonly EMPTY_BODY: "EMPTY_BODY";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
+    readonly TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE";
+    readonly TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE";
+    readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
+    readonly HOOK_ERROR: "HOOK_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+/**
+ * Any one of the codes in {@link ServerErrorCodes}.
+ *
+ * @public
+ */
+type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
+/**
+ * Every code the HTTP client raises when a request never reaches a server, or
+ * when the client cannot read the answer.
+ *
+ * No server sends one of these, so a failure under one of them means the
+ * exchange broke before the operation ran. `STATUS_BY_CODE` in
+ * `src/server/errors.ts` therefore maps none of them, because no request can
+ * arrive under one and no HTTP status belongs to one.
+ *
+ * @public
+ */
+declare const ClientErrorCodes: {
+    readonly CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED";
+    readonly CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT";
+    readonly CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED";
+    readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
+    readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
+    readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
+};
+/**
+ * Any one of the codes in {@link ClientErrorCodes}.
+ *
+ * @public
+ */
+type ClientErrorCode = (typeof ClientErrorCodes)[keyof typeof ClientErrorCodes];
+/**
+ * Every code a {@link NarsilError} can carry: one the engine raised, one the
+ * HTTP layer raised, one the client raised, or any other string.
+ *
+ * The last arm exists for a server's `onRequest` hook, which rejects a request
+ * under a code of its own, such as `UNAUTHORIZED`, and the client then passes
+ * that code through unchanged. An editor still completes every code Narsil
+ * defines.
+ *
+ * @public
+ */
+type NarsilErrorCode = ErrorCode | ServerErrorCode | ClientErrorCode | (string & {});
 /**
  * The error every part of the engine throws.
  *
@@ -119,18 +188,21 @@ type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
  */
 declare class NarsilError extends Error {
     /** This says which failure it is. */
-    readonly code: ErrorCode;
+    readonly code: NarsilErrorCode;
     /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
     readonly details: Record<string, unknown>;
     /**
      * Builds an error carrying a code the caller can branch on.
      *
-     * @param code - The failure this error reports.
+     * @param code - The failure this error reports, from {@link ErrorCodes} for
+     * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
+     * or {@link ClientErrorCodes} for one that stopped a request from reaching a
+     * server.
      * @param message - Plain description, for a log or a person.
      * @param details - Values behind the failure, which reach
      * {@link NarsilError.details}.
      */
-    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
+    constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
 }
 
 /**
@@ -143,7 +215,7 @@ declare class NarsilError extends Error {
  * @public
  */
 interface QueryResult<T = AnyDocument> {
-    /** These documents matched, best score first, cut to the query's `limit`. */
+    /** These documents matched, cut to the query's `limit`, best score first or in the query's sort order. */
     hits: Array<Hit<T>>;
     /** This many documents matched in total, before `limit` and `offset` applied. */
     count: number;
@@ -168,8 +240,12 @@ interface QueryResult<T = AnyDocument> {
 interface Hit<T = AnyDocument> {
     /** The document is stored under this id. */
     id: string;
-    /** This score ranked the hit. Scores compare within one result set, never across searches. */
-    score: number;
+    /**
+     * This score ranked the hit. Scores compare within one result set, never
+     * across searches. A sorted query ranks by sort values instead and carries
+     * no score unless it sets `includeScores`.
+     */
+    score?: number;
     /** This is the stored document. */
     document: T;
     /** These are the parts the score was built from, which arrive when the query asked for them. */
@@ -215,6 +291,13 @@ interface FacetResult {
     values: Record<string, number>;
     /** The field held this many distinct values across the matching documents. */
     count: number;
+    /**
+     * No value's count is short by more than this. Counting runs per partition
+     * and each one reports only its own top values, so a value that is common
+     * overall but ranks low on a partition loses that partition's share. A bound
+     * of 0 means every count here is exact.
+     */
+    errorBound: number;
 }
 /**
  * One group of hits, produced by a query that grouped its results.
@@ -415,6 +498,37 @@ interface VectorMaintenanceResult {
     /** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
     estimatedOptimizeMs: number;
 }
+/**
+ * One stored document, as {@link Narsil.listDocuments} returns it.
+ *
+ * @typeParam T - Shape of the stored document.
+ *
+ * @public
+ */
+interface ListedDocument<T = AnyDocument> {
+    /** The document is stored under this id. */
+    id: string;
+    /** This holds the stored document, cut down to what the projection kept. */
+    document: T;
+}
+/**
+ * What {@link Narsil.listDocuments} returns: one page of stored documents and
+ * the cursor that reaches the next one.
+ *
+ * @typeParam T - Shape of the stored documents.
+ *
+ * @public
+ */
+interface ListResult<T = AnyDocument> {
+    /** These documents make up the page, in ascending document-id order. */
+    documents: Array<ListedDocument<T>>;
+    /** This opaque cursor reaches the next page, and is null once the listing is finished. */
+    cursor: string | null;
+    /** The listing covers this many documents in total, and any filter narrows that count. */
+    total: number;
+    /** The engine spent this many milliseconds building the page. */
+    elapsed: number;
+}
 
 /**
  * Compares one field against a value. Setting several keys narrows the match,
@@ -569,12 +683,36 @@ type SearchMode = 'fulltext' | 'vector' | 'hybrid';
  * @public
  */
 type TermMatchPolicy = 'all' | 'any' | number;
+/**
+ * One field of a sort, and the direction that field orders by.
+ *
+ * @public
+ */
+interface SortField {
+    /** The field the engine reads, which may name a nested field with dots. */
+    field: string;
+    /** Ascending or descending order for this field. */
+    direction: 'asc' | 'desc';
+}
+/**
+ * A sort, either as an object keyed by field or as a list of fields in the
+ * order they apply.
+ *
+ * Both forms order by the first field, break a tie on the second, and carry on
+ * that way. Prefer the list where the order of the fields matters, because
+ * JavaScript moves an all-digit key such as `2024` to the front of an object
+ * and the list keeps the order you wrote.
+ *
+ * @public
+ */
+type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
 /**
  * Everything {@link Narsil.query} accepts.
  *
- * Every field is optional, so a query with nothing set returns the first page
- * of the index. Set `term` for keyword search, `vector` for similarity
- * search, and `mode` when you want both.
+ * Set `term` for keyword search, `vector` for similarity search, and `mode`
+ * when you want both. The engine matches nothing for a query carrying neither
+ * of them, so page through an index with {@link Narsil.listDocuments}
+ * instead.
  *
  * @public
  */
@@ -610,8 +748,14 @@ interface QueryParams {
     exact?: boolean;
     /** These settings name the fields the query counts values for, and control how each count is cut and sorted. */
     facets?: FacetConfig;
-    /** This sorts the hits by field value, keyed by field, which replaces the relevance ranking. */
-    sort?: Record<string, 'asc' | 'desc'>;
+    /**
+     * This sorts the hits by field value, which replaces the relevance ranking.
+     * Pass an object keyed by field, or a list of fields in the order they
+     * apply. Fusion defines the order of hybrid results, so a hybrid query takes
+     * no sort. The engine throws `SEARCH_INVALID_MODE` for a query that sets
+     * both.
+     */
+    sort?: SortSpec;
     /** These settings collapse the hits into groups by field value. */
     group?: GroupConfig;
     /** The query returns this many hits, and 10 by default. */
@@ -633,9 +777,38 @@ interface QueryParams {
     vector?: VectorQueryConfig;
     /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
     hybrid?: HybridConfig;
+    /**
+     * Setting this returns relevance scores on a sorted query. A query that
+     * names a sort ranks by sort values alone and computes no scores, so its
+     * hits carry none until this restores them. A query without a sort ignores
+     * this and always carries scores.
+     */
+    includeScores?: boolean;
     /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
     includeScoreComponents?: boolean;
+    /** This chooses how much of each stored document comes back, and the whole document by default. */
+    document?: DocumentProjection;
 }
+/**
+ * How much of a stored document each hit carries back.
+ *
+ * Pass `false` when the ids and scores are all you need, and every hit's
+ * `document` is then an empty object. Pass `include` to keep named fields
+ * alone, or `exclude` to drop named fields and keep the rest; naming both
+ * keeps the included fields and then drops the excluded ones from those. Use
+ * dots to name a nested field, so `author.name` addresses the `name` inside
+ * `author`, and a name that matches no field changes nothing.
+ *
+ * Drop a vector field on a similarity search, because the engine otherwise
+ * reads every hit's vector back out of the index and writes it into the
+ * response.
+ *
+ * @public
+ */
+type DocumentProjection = boolean | {
+    include?: string[];
+    exclude?: string[];
+};
 /**
  * Vector-search inputs passed under `QueryParams.vector`.
  *
@@ -783,5 +956,44 @@ interface SuggestParams {
     /** The lookup returns this many completions, most widely used first, and 10 by default. */
     limit?: number;
 }
+/**
+ * Everything {@link Narsil.listDocuments} accepts.
+ *
+ * {@link Narsil.listDocuments} reads the stored documents without ranking them,
+ * which is how you page through a whole index. Leave `cursor` out to start at
+ * the first document, then pass back the cursor each result carries until it
+ * comes back null.
+ *
+ * A cursor belongs to the sort it was made under, so pass the same `sort` back
+ * with it. Changing `sort` invalidates the cursor, and the engine then throws
+ * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
+ *
+ * @public
+ */
+interface ListParams {
+    /**
+     * This cursor comes from a previous result, and continues where it stopped.
+     * The engine ties a cursor to the sort that produced it, and it throws
+     * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
+     */
+    cursor?: string;
+    /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
+    limit?: number;
+    /** This narrows the listing to the documents the filter accepts. */
+    filters?: FilterExpression;
+    /**
+     * This orders the listing by field value rather than by document id, and the
+     * engine applies the fields in the order they are listed. Pass an object
+     * keyed by field, or a list of fields in the order they apply. It breaks a
+     * tie on document id, and it sorts by at most eight fields. The engine uses
+     * document-id order when you leave this out.
+     *
+     * The engine reads every document the listing covers to build a sorted page,
+     * so a sorted listing costs more than the default order on a large index.
+     */
+    sort?: SortSpec;
+    /** This chooses how much of each stored document comes back, and the whole document by default. */
+    document?: DocumentProjection;
+}
 
-export { type ArrayFilter as A, type BatchResult as B, type ComparisonFilter as C, type ErrorCode as E, type FacetConfig as F, type GeoFilter as G, type HighlightConfig as H, type IndexInfo as I, type MemoryStats as M, NarsilError as N, type PartitionStatsResult as P, type QueryParams as Q, type ScoreComponents as S, type TermMatchPolicy as T, type VectorMaintenanceResult as V, ErrorCodes as a, type FacetResult as b, type FieldFilter as c, type FilterExpression as d, type GeoPolygonFilter as e, type GeoRadiusFilter as f, type GroupConfig as g, type GroupReducer as h, type GroupResult as i, type HighlightMatch as j, type Hit as k, type HybridConfig as l, type IndexStats as m, type PreflightResult as n, type PresenceFilter as o, type ProcessMemoryReport as p, type QueryResult as q, type SearchMode as r, type StringFilter as s, type SuggestParams as t, type SuggestResult as u, type VectorQueryConfig as v };
+export { type ArrayFilter as A, type BatchResult as B, type ClientErrorCode as C, type DocumentProjection as D, type ErrorCode as E, type FacetConfig as F, type GeoFilter as G, type HighlightConfig as H, type IndexInfo as I, type SearchMode as J, type SortField as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type SortSpec as O, type PartitionStatsResult as P, type QueryParams as Q, type StringFilter as R, type ServerErrorCode as S, type TermMatchPolicy as T, type VectorQueryConfig as U, type VectorMaintenanceResult as V, ClientErrorCodes as a, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type QueryResult as e, type IndexStats as f, type ListResult as g, type PreflightResult as h, type SuggestParams as i, type SuggestResult as j, type ComparisonFilter as k, type FacetResult as l, type FieldFilter as m, type FilterExpression as n, type GeoPolygonFilter as o, type GeoRadiusFilter as p, type GroupConfig as q, type GroupReducer as r, type GroupResult as s, type HighlightMatch as t, type Hit as u, type HybridConfig as v, type ListedDocument as w, type PresenceFilter as x, type ProcessMemoryReport as y, type ScoreComponents as z };