@delali/narsil 0.2.0 → 0.2.1

package/dist/search-CgQQIciB.d.ts

@@ -0,0 +1,786 @@
+import { A as AnyDocument, b as SchemaDefinition, c as ScoringMode } from './schema-CE6S_aAr.js';
+
+/**
+ * Every code a {@link NarsilError} carries, grouped by the part of the engine
+ * that raises it.
+ *
+ * Match on the code rather than on the message, because a code is stable and a
+ * message is not. The HTTP server maps each code to a status, so a code also
+ * tells you whether the caller or the engine is at fault.
+ *
+ * @public
+ */
+declare const ErrorCodes: {
+    readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
+    readonly SCHEMA_MISSING_FIELD: "SCHEMA_MISSING_FIELD";
+    readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
+    readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
+    readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
+    readonly DOC_NOT_FOUND: "DOC_NOT_FOUND";
+    readonly DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS";
+    readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
+    readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
+    readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
+    readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
+    readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
+    readonly WORKER_CRASHED: "WORKER_CRASHED";
+    readonly WORKER_BUSY: "WORKER_BUSY";
+    readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
+    readonly PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED";
+    readonly PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED";
+    readonly PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED";
+    readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
+    readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
+    readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
+    readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
+    readonly SEARCH_INVALID_VECTOR_SIZE: "SEARCH_INVALID_VECTOR_SIZE";
+    readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
+    readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
+    readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
+    readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
+    readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
+    readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
+    readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
+    readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
+    readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
+    readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
+    readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
+    readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
+    readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
+    readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
+    readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
+    readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
+    readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
+    readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
+    readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
+    readonly CONTROLLER_LEASE_LOST: "CONTROLLER_LEASE_LOST";
+    readonly CONTROLLER_NOT_ACTIVE: "CONTROLLER_NOT_ACTIVE";
+    readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
+    readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
+    readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
+    readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
+    readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_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";
+    readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
+    readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
+    readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
+    readonly REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH";
+    readonly REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED";
+    readonly PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY";
+    readonly PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED";
+    readonly INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS";
+    readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
+    readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
+    readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
+    readonly SNAPSHOT_SYNC_TOO_LARGE: "SNAPSHOT_SYNC_TOO_LARGE";
+    readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
+    readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
+    readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
+    readonly SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID";
+    readonly SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID";
+    readonly SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH";
+    readonly SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER";
+    readonly SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW";
+    readonly SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED";
+    readonly SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING";
+    readonly SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING";
+    readonly SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH";
+    readonly SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR";
+    readonly SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS";
+    readonly SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED";
+    readonly SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE";
+    readonly SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED";
+    readonly SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED";
+    readonly SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT";
+    readonly SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE";
+    readonly SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED";
+    readonly SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED";
+};
+/**
+ * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
+ * when you branch on a failure.
+ *
+ * @public
+ */
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * The error every part of the engine throws.
+ *
+ * Catch it, read {@link NarsilError.code} to decide what to do, and read
+ * {@link NarsilError.details} for the values that caused it. The engine lets
+ * this error propagate unchanged, so the code you catch is the code the
+ * failing operation raised.
+ *
+ * @public
+ */
+declare class NarsilError extends Error {
+    /** This says which failure it is. */
+    readonly code: ErrorCode;
+    /** 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 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>);
+}
+
+/**
+ * What {@link Narsil.query} returns: the ranked hits and everything the query
+ * asked for alongside them.
+ *
+ * @typeParam T - Shape of the stored documents, which flows through to each
+ * hit's `document`.
+ *
+ * @public
+ */
+interface QueryResult<T = AnyDocument> {
+    /** These documents matched, best score first, cut to the query's `limit`. */
+    hits: Array<Hit<T>>;
+    /** This many documents matched in total, before `limit` and `offset` applied. */
+    count: number;
+    /** The engine spent this many milliseconds on the search. */
+    elapsed: number;
+    /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
+    cursor?: string;
+    /** These facet counts are keyed by the field each facet was asked for. */
+    facets?: Record<string, FacetResult>;
+    /** These groups arrive when the query asked for grouping. */
+    groups?: GroupResult[];
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
+}
+/**
+ * One matching document, with the score that ranked it.
+ *
+ * @typeParam T - Shape of the stored document.
+ *
+ * @public
+ */
+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 is the stored document. */
+    document: T;
+    /** These are the parts the score was built from, which arrive when the query asked for them. */
+    scoreComponents?: ScoreComponents;
+    /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
+    highlights?: Record<string, HighlightMatch>;
+}
+/**
+ * The numbers BM25 combined into one hit's score, which is what you read when
+ * a ranking surprises you.
+ *
+ * @public
+ */
+interface ScoreComponents {
+    /** Each query term appears in this document this often, keyed by term. */
+    termFrequencies: Record<string, number>;
+    /** Each field the query searched holds this many tokens, keyed by field. */
+    fieldLengths: Record<string, number>;
+    /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
+    idf: Record<string, number>;
+}
+/**
+ * A highlighted field, ready to render.
+ *
+ * @public
+ */
+interface HighlightMatch {
+    /** This is the field's text around the match, wrapped in the query's tags. */
+    snippet: string;
+    /** The match covers these character ranges in the original field, for rendering the highlight yourself. */
+    positions: Array<{
+        start: number;
+        end: number;
+    }>;
+}
+/**
+ * Counts for one faceted field.
+ *
+ * @public
+ */
+interface FacetResult {
+    /** This many documents matched per value, keyed by value. */
+    values: Record<string, number>;
+    /** The field held this many distinct values across the matching documents. */
+    count: number;
+}
+/**
+ * One group of hits, produced by a query that grouped its results.
+ *
+ * @public
+ */
+interface GroupResult {
+    /** Each grouping field holds this value for the group, keyed by field. */
+    values: Record<string, unknown>;
+    /** These hits fall in the group, cut to the query's `maxPerGroup`. */
+    hits: Array<Hit>;
+}
+/**
+ * What {@link Narsil.preflight} returns: how many documents a query matches,
+ * without building or ranking a single hit.
+ *
+ * @public
+ */
+interface PreflightResult {
+    /** The query matches this many documents. */
+    count: number;
+    /** The count took this many milliseconds. */
+    elapsed: number;
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
+}
+/**
+ * What a batch write returns. One bad document never abandons the rest, so
+ * read both lists.
+ *
+ * @public
+ */
+interface BatchResult {
+    /** The engine wrote the documents under these ids. */
+    succeeded: string[];
+    /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
+    failed: Array<{
+        docId: string;
+        error: NarsilError;
+    }>;
+}
+/**
+ * What {@link Narsil.getStats} returns about one index.
+ *
+ * @public
+ */
+interface IndexStats {
+    /** The index holds this many documents. */
+    documentCount: number;
+    /** The index is spread across this many partitions. */
+    partitionCount: number;
+    /**
+     * Formula-based estimate of the index's main-thread memory footprint, summed
+     * across every partition and vector index for this index. Computed from
+     * structural counters (document count, posting counts, field-index sizes),
+     * not measured. Per-object V8 overhead (hidden classes, map transitions,
+     * GC headers) is not captured here, so this number routinely undershoots
+     * the real heap by a meaningful factor. Use {@link Narsil.getMemoryStats}
+     * when sizing host memory.
+     */
+    estimatedMemoryBytes: number;
+    /** The index analyses text with this language module. */
+    language: string;
+    /** The index was created with this field layout. */
+    schema: SchemaDefinition;
+}
+/**
+ * A summary of one index, as {@link Narsil.listIndexes} reports it.
+ *
+ * @public
+ */
+interface IndexInfo {
+    /** The index was created under this name. */
+    name: string;
+    /** The index holds this many documents. */
+    documentCount: number;
+    /** The index is spread across this many partitions. */
+    partitionCount: number;
+    /** The index analyses text with this language module. */
+    language: string;
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
+}
+/**
+ * What {@link Narsil.getPartitionStats} reports for one partition, which is
+ * where you look when an index grows unevenly.
+ *
+ * @public
+ */
+interface PartitionStatsResult {
+    /** This identifies the partition within its index. */
+    partitionId: number;
+    /** The partition holds this many documents. */
+    documentCount: number;
+    /**
+     * Formula-based estimate of this partition's memory footprint. V8 has no
+     * per-object heap accounting API, so this number is derived from structural
+     * counters (document count, posting counts, field-index sizes) and does not
+     * include per-object overhead. Treat as an estimate, not a measurement.
+     */
+    estimatedMemoryBytes: number;
+}
+/**
+ * What {@link Narsil.suggest} returns: the indexed terms that complete a
+ * prefix, ready to offer as you-type suggestions.
+ *
+ * @public
+ */
+interface SuggestResult {
+    /** These completions run most widely used first. */
+    terms: Array<{
+        /** This is the completed term, as the index holds it. */
+        term: string;
+        /** The term appears in this many documents, which is what ordered the list. */
+        documentFrequency: number;
+    }>;
+    /** The lookup took this many milliseconds. */
+    elapsed: number;
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
+}
+/**
+ * Snapshot of V8 heap usage as reported by `process.memoryUsage()`. All values
+ * are bytes. `null` in environments that do not expose `process.memoryUsage`,
+ * such as browsers.
+ *
+ * @public
+ */
+interface ProcessMemoryReport {
+    /** The process is using this much heap. */
+    heapUsed: number;
+    /** V8 has reserved this much heap. */
+    heapTotal: number;
+    /** The process holds this much outside the heap, such as buffers. */
+    external: number;
+    /** The process occupies this much physical memory in total. */
+    rss: number;
+}
+/**
+ * What {@link Narsil.getMemoryStats} returns, which is what you size a host
+ * from.
+ *
+ * @public
+ */
+interface MemoryStats {
+    /**
+     * V8 heap usage for the host process at the moment the call was made. This
+     * is process-wide, not engine-wide; if multiple Narsil engines are running
+     * in the same process every engine's `getMemoryStats` returns the same
+     * `process` figures. `null` in browsers and any runtime where
+     * `process.memoryUsage` is unavailable.
+     */
+    process: ProcessMemoryReport | null;
+    /**
+     * Sum of every index's {@link IndexStats.estimatedMemoryBytes} held by this
+     * engine. Formula-based; treat as an estimate, not a measurement. Useful
+     * for cross-engine relative comparisons inside a single process where
+     * `process.heapUsed` cannot tell engines apart.
+     */
+    estimatedIndexBytes: number;
+    /**
+     * Per-worker V8 heap usage when the engine has been promoted to a worker
+     * pool. Empty when no workers are active.
+     */
+    workers: Array<{
+        /** This identifies the worker within the pool. */
+        workerId: number;
+        /** That worker is using this much heap. */
+        heapUsed: number;
+        /** V8 has reserved this much heap in that worker. */
+        heapTotal: number;
+        /** That worker holds this much outside its heap. */
+        external: number;
+    }>;
+}
+/**
+ * The state of one vector field, and what maintenance would cost, as
+ * {@link Narsil.vectorMaintenanceStatus} reports it.
+ *
+ * Removing a vector leaves a tombstone in the graph, and enough of them slow a
+ * search down. Read this to decide when compaction earns its cost.
+ *
+ * @public
+ */
+interface VectorMaintenanceResult {
+    /** This describes the named vector field. */
+    fieldName: string;
+    /** Tombstones make up this share of the graph's nodes, from 0 to 1. */
+    tombstoneRatio: number;
+    /** The field's HNSW graph holds this many vectors. */
+    graphCount: number;
+    /** This many vectors wait outside the graph, which a search scans one by one. */
+    bufferSize: number;
+    /** This stays true while a graph build runs. */
+    building: boolean;
+    /** {@link Narsil.compactVectors} would take about this many milliseconds. */
+    estimatedCompactMs: number;
+    /** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
+    estimatedOptimizeMs: number;
+}
+
+/**
+ * Compares one field against a value. Setting several keys narrows the match,
+ * because a document has to satisfy all of them.
+ *
+ * @public
+ */
+type ComparisonFilter = {
+    /** This matches a field equal to the value. */
+    eq?: number | string | boolean;
+    /** This matches a field holding anything other than the value. */
+    ne?: number | string | boolean;
+    /** This matches a field greater than the number. */
+    gt?: number;
+    /** This matches a field less than the number. */
+    lt?: number;
+    /** This matches a field greater than or equal to the number. */
+    gte?: number;
+    /** This matches a field less than or equal to the number. */
+    lte?: number;
+    /** This matches a field inside the inclusive range, given as `[low, high]`. */
+    between?: [number, number];
+};
+/**
+ * Everything {@link ComparisonFilter} offers, with the set and prefix tests a
+ * string field also supports.
+ *
+ * @public
+ */
+type StringFilter = ComparisonFilter & {
+    /** This matches a field equal to any value in the list. */
+    in?: string[];
+    /** This matches a field equal to none of the values in the list. */
+    nin?: string[];
+    /** This matches a field starting with the text. */
+    startsWith?: string;
+    /** This matches a field ending with the text. */
+    endsWith?: string;
+};
+/**
+ * Tests the contents of an array field.
+ *
+ * @public
+ */
+type ArrayFilter = {
+    /** This matches an array holding every one of the values. */
+    containsAll?: (string | number | boolean)[];
+    /** This matches an array holding at least one of the values. */
+    matchesAny?: (string | number | boolean)[];
+    /** This compares the array's length. */
+    size?: ComparisonFilter;
+};
+/**
+ * Tests whether a field carries a value at all, without looking at what it
+ * holds.
+ *
+ * @public
+ */
+type PresenceFilter = {
+    /** This matches a document where the field is present. */
+    exists?: boolean;
+    /** This matches a document where the field is absent. */
+    notExists?: boolean;
+    /** This matches an empty string or an empty array. */
+    isEmpty?: boolean;
+    /** This matches a string or array holding something. */
+    isNotEmpty?: boolean;
+};
+/**
+ * Matches a `geopoint` field against a circle drawn on the earth.
+ *
+ * @public
+ */
+type GeoRadiusFilter = {
+    /** The filter tests the field against this circle. */
+    radius: {
+        /** The centre has this latitude, in degrees. */
+        lat: number;
+        /** The centre has this longitude, in degrees. */
+        lon: number;
+        /** The circle reaches this far, measured in `unit`. */
+        distance: number;
+        /** `distance` is given in kilometres, miles, or metres. */
+        unit: 'km' | 'mi' | 'm';
+        /** This keeps the points inside the circle. Set it to false to keep the points outside. It is true by default. */
+        inside?: boolean;
+        /** Setting this measures along the earth's curve instead of a flat approximation, which costs time and gains accuracy over long distances. */
+        highPrecision?: boolean;
+    };
+};
+/**
+ * Matches a `geopoint` field against a polygon drawn on the earth.
+ *
+ * @public
+ */
+type GeoPolygonFilter = {
+    /** The filter tests the field against this polygon. */
+    polygon: {
+        /** These corners run in order. The engine closes the ring, so repeating the first point is unnecessary. */
+        points: Array<{
+            lat: number;
+            lon: number;
+        }>;
+        /** This keeps the points inside the polygon. Set it to false to keep the points outside. It is true by default. */
+        inside?: boolean;
+    };
+};
+/**
+ * Either shape a `geopoint` field is matched against.
+ *
+ * @public
+ */
+type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
+/**
+ * The filter one field accepts. Which of these forms applies follows from the
+ * field's declared type.
+ *
+ * @public
+ */
+type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
+/**
+ * The filter a query runs, built from per-field tests and the boolean
+ * operators that combine them.
+ *
+ * Nest the operators to whatever depth the query needs. The engine applies the
+ * filter before scoring, so a narrow filter makes a search cheaper.
+ *
+ * @public
+ */
+type FilterExpression = {
+    /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
+    fields?: Record<string, FieldFilter>;
+    /** Every nested expression has to match. */
+    and?: FilterExpression[];
+    /** At least one nested expression has to match. */
+    or?: FilterExpression[];
+    /** The nested expression has to fail. */
+    not?: FilterExpression;
+};
+
+/**
+ * Which engine answers a query: keyword matching, vector similarity, or both
+ * merged into one ranking.
+ *
+ * @public
+ */
+type SearchMode = 'fulltext' | 'vector' | 'hybrid';
+/**
+ * How many of a query's terms a document has to carry. `all` demands every
+ * term, `any` accepts one, and a number demands that many.
+ *
+ * @public
+ */
+type TermMatchPolicy = 'all' | 'any' | number;
+/**
+ * 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.
+ *
+ * @public
+ */
+interface QueryParams {
+    /** The engine searches for this text, analysed with the index's own language module. */
+    term?: string;
+    /** The engine searches the term in these fields, and in every text field in the schema by default. */
+    fields?: string[];
+    /** This narrows the candidates before scoring. */
+    filters?: FilterExpression;
+    /** These multipliers raise or lower each field's contribution to the score, keyed by field. */
+    boost?: Record<string, number>;
+    /** The query gathers term statistics this way, and follows the index's `defaultScoring` otherwise. */
+    scoring?: ScoringMode;
+    /** The engine drops any hit scoring below this value. */
+    minScore?: number;
+    /** A document has to carry this many query terms. The engine accepts one by default. */
+    termMatch?: TermMatchPolicy;
+    /** A term may differ by this edit distance and still match, which is how a typo still finds its document. */
+    tolerance?: number;
+    /** This many leading characters have to match exactly before `tolerance` applies, which keeps fuzzy matching honest. */
+    prefixLength?: number;
+    /**
+     * Treat the last query token as an unfinished word so it also matches
+     * indexed terms that complete it ('secur' matches 'security'). Earlier
+     * tokens must match fully; `tolerance` keeps applying to them but not to
+     * the prefix token. Completions score against a shared document frequency
+     * and are demoted below full-word matches. Ignored when `exact` is true.
+     * Off by default.
+     */
+    prefix?: boolean;
+    /** Setting this matches the term as written, skipping stemming and fuzzy matching. */
+    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'>;
+    /** These settings collapse the hits into groups by field value. */
+    group?: GroupConfig;
+    /** The query returns this many hits, and 10 by default. */
+    limit?: number;
+    /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
+    offset?: number;
+    /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
+    searchAfter?: string;
+    /** These settings name the fields that come back with highlighted snippets. */
+    highlight?: HighlightConfig;
+    /** These documents take fixed positions, ahead of the ranking. */
+    pinned?: Array<{
+        docId: string;
+        position: number;
+    }>;
+    /** This picks which engine answers the query. Keyword search runs by default. */
+    mode?: SearchMode;
+    /** These vector-search inputs are required in `vector` and `hybrid` mode. */
+    vector?: VectorQueryConfig;
+    /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
+    hybrid?: HybridConfig;
+    /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
+    includeScoreComponents?: boolean;
+}
+/**
+ * Vector-search inputs passed under `QueryParams.vector`.
+ *
+ * Supply either a raw `value` array or a `text` string for auto-embedding;
+ * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
+ * by the outer query's `limit`, not by any field on this object.
+ *
+ * @public
+ */
+interface VectorQueryConfig {
+    /**
+     * Name of the schema field that holds the vector to compare against.
+     * Must reference a field declared as `vector[N]` in the index schema.
+     */
+    field: string;
+    /**
+     * Raw query vector. Length must match the indexed field's dimension or
+     * the search rejects the request with `VECTOR_DIMENSION_MISMATCH`.
+     */
+    value?: number[];
+    /**
+     * Text to embed at query time using the index or instance embedding
+     * adapter. Mutually exclusive with `value`; requires a configured adapter.
+     */
+    text?: string;
+    /**
+     * Score floor applied during ranking. Hits scoring below this value
+     * are dropped before `limit` is enforced, so the returned hit count
+     * can be smaller than `limit` even when more documents exist. The
+     * floor is interpreted in score space for every metric; for
+     * `euclidean`, distance is mapped to a similarity score of
+     * `1 / (1 + distance)` first. Defaults to no floor.
+     */
+    similarity?: number;
+    /**
+     * Similarity metric used for ranking. Defaults to `cosine`. Choose
+     * `dotProduct` for raw inner-product scoring on already-normalised
+     * vectors and `euclidean` for distance-based ordering.
+     */
+    metric?: 'cosine' | 'dotProduct' | 'euclidean';
+    /**
+     * HNSW exploration factor for approximate search. Higher values raise
+     * recall at the cost of latency. Ignored while the field is still
+     * served by the brute-force backend. Defaults to the engine's built-in
+     * value when omitted.
+     */
+    efSearch?: number;
+}
+/**
+ * How a hybrid query merges its keyword ranking with its vector ranking.
+ *
+ * `rrf` combines the two by rank alone, which needs no tuning and handles
+ * scores that live on different scales. `linear` blends the scores directly,
+ * which gives you control once you know what each side's scores look like.
+ *
+ * @public
+ */
+interface HybridConfig {
+    /** The rankings merge this way, and by rank fusion by default. */
+    strategy?: 'rrf' | 'linear';
+    /** This rank-fusion constant softens the advantage of the top ranks, and `rrf` alone reads it. */
+    k?: number;
+    /** This weights the vector score, from 0 to 1, and `linear` alone reads it. */
+    alpha?: number;
+}
+/**
+ * Fields a query counts values for, keyed by field name.
+ *
+ * @public
+ */
+interface FacetConfig {
+    /** Each key names a field the query counts values for. */
+    [field: string]: {
+        /** The facet returns this many values for the field, most frequent first. */
+        limit?: number;
+        /** This orders the returned values by their count. */
+        sort?: 'asc' | 'desc';
+        /** These ranges bucket a numeric field, instead of counting each value. */
+        ranges?: Array<{
+            from: number;
+            to: number;
+        }>;
+    };
+}
+/**
+ * How a query collapses its hits into groups.
+ *
+ * @public
+ */
+interface GroupConfig {
+    /** The values of these fields define a group, and several fields group by their combination. */
+    fields: string[];
+    /** Each group keeps this many hits, and one by default, which is the collapse behaviour. */
+    maxPerGroup?: number;
+    /** This folds each group's hits into one value, such as a sum or an average. */
+    reduce?: GroupReducer;
+}
+/**
+ * Folds the hits of one group into a single value.
+ *
+ * @public
+ */
+type GroupReducer = {
+    /**
+     * Folds one hit into the running value.
+     *
+     * @param accumulator - What the previous call returned, or what
+     * `initialValue` produced for the first hit.
+     * @param doc - The hit's stored document.
+     * @param score - The hit's relevance score.
+     * @returns The new running value.
+     */
+    reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
+    /** Produces the starting value for each group. The engine calls it once per group. */
+    initialValue: () => unknown;
+};
+/**
+ * Which fields a query returns highlighted snippets for, and how those
+ * snippets are marked up.
+ *
+ * The index has to have been created with `trackPositions`, because
+ * highlighting reads the positions that setting records.
+ *
+ * @public
+ */
+interface HighlightConfig {
+    /** The engine highlights these fields. */
+    fields: string[];
+    /** This opens each match, and is `<mark>` by default. */
+    preTag?: string;
+    /** This closes each match, and is `</mark>` by default. */
+    postTag?: string;
+    /** A snippet runs to this many characters before the engine trims it. */
+    maxSnippetLength?: number;
+}
+/**
+ * Everything {@link Narsil.suggest} accepts.
+ *
+ * @public
+ */
+interface SuggestParams {
+    /** The returned terms complete this text. */
+    prefix: string;
+    /** The lookup returns this many completions, most widely used first, and 10 by default. */
+    limit?: number;
+}
+
+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 };