@delali/narsil 0.3.1-next.79 → 0.3.1-next.82

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +3 -3
  2. package/dist/adapters/filesystem.mjs +1 -1
  3. package/dist/adapters/indexeddb.mjs +1 -1
  4. package/dist/{capabilities-1lEYL3WK.d.ts → capabilities-CAdkp2P-.d.ts} +2 -2
  5. package/dist/{chunk-XSZTF4ZQ.mjs → chunk-2453RJYK.mjs} +2 -2
  6. package/dist/{chunk-DFW3U5UW.mjs → chunk-4CWHWOBI.mjs} +24 -195
  7. package/dist/{chunk-R6WBLBTC.mjs → chunk-4D6OH4EF.mjs} +10 -46
  8. package/dist/{chunk-RTR44V2A.mjs → chunk-4VBG6PEH.mjs} +586 -4
  9. package/dist/{chunk-Y3L5MDRV.mjs → chunk-5XNIRLFC.mjs} +2 -2
  10. package/dist/{chunk-2E35UM3G.mjs → chunk-B3UOQJD3.mjs} +1 -1
  11. package/dist/{chunk-PJWG547Z.mjs → chunk-GNYXCLJS.mjs} +5 -5
  12. package/dist/{chunk-55WEJKWT.mjs → chunk-IH3GKNDQ.mjs} +197 -93
  13. package/dist/{chunk-AMGDG4ZJ.mjs → chunk-IN5CH4P2.mjs} +3 -3
  14. package/dist/{chunk-PXDQFYD5.mjs → chunk-KJ7LB3TR.mjs} +24 -140
  15. package/dist/chunk-LS5IRM23.mjs +140 -0
  16. package/dist/{chunk-4MQ5F4IL.mjs → chunk-OLXM65YH.mjs} +1 -1
  17. package/dist/{chunk-IBR6634K.mjs → chunk-R6A773WK.mjs} +2 -69
  18. package/dist/{chunk-4344I4MR.mjs → chunk-SREPGC6O.mjs} +336 -13
  19. package/dist/{chunk-I64LXKO3.mjs → chunk-TPJU7NDJ.mjs} +1 -0
  20. package/dist/chunk-WQBCBKY3.mjs +8 -0
  21. package/dist/{chunk-P2BEMMOD.mjs → chunk-XYDP7CCJ.mjs} +151 -204
  22. package/dist/{chunk-Z3BXCZXS.mjs → chunk-XZF4LZ3X.mjs} +5 -3
  23. package/dist/chunk-YTJCGKM4.mjs +56 -0
  24. package/dist/chunk-ZCKPRCYI.mjs +30 -0
  25. package/dist/{client-ZXcbSViH.d.ts → client-CKUtkLz3.d.ts} +2 -2
  26. package/dist/client.d.ts +7 -7
  27. package/dist/client.mjs +1 -0
  28. package/dist/{config-DHL2KsfD.d.ts → config-BuIkeM5C.d.ts} +39 -3
  29. package/dist/{config-DTe5EbWW.d.ts → config-CSDEPraV.d.ts} +1 -1
  30. package/dist/direct-executor-JVXDR5Y5.mjs +19 -0
  31. package/dist/distribution/coordinator/etcd.d.ts +1 -1
  32. package/dist/distribution/coordinator/etcd.mjs +3 -2
  33. package/dist/distribution/coordinator/in-memory.d.ts +1 -1
  34. package/dist/distribution/coordinator/in-memory.mjs +2 -1
  35. package/dist/distribution/transport/grpc.mjs +1 -1
  36. package/dist/distribution.d.ts +7 -7
  37. package/dist/distribution.mjs +759 -65
  38. package/dist/embeddings/openai.mjs +1 -1
  39. package/dist/{engine-BjPBzWkA.d.ts → engine-DMNZJAUq.d.ts} +1 -1
  40. package/dist/{types-ChrVy4lH.d.ts → index-DzONZUKE.d.ts} +79 -37
  41. package/dist/index.browser.mjs +138 -539
  42. package/dist/index.d.ts +5 -5
  43. package/dist/index.mjs +17 -15
  44. package/dist/invalidation/filesystem.mjs +2 -1
  45. package/dist/{memory-DW3OJ0im.d.ts → memory-BPKNx9Tl.d.ts} +1288 -1287
  46. package/dist/partial-words.mjs +6 -5
  47. package/dist/pattern.mjs +5 -2
  48. package/dist/persistence/durability/checkpoint-worker.d.ts +7 -7
  49. package/dist/persistence/durability/checkpoint-worker.mjs +17 -15
  50. package/dist/react.d.ts +6 -6
  51. package/dist/react.mjs +1 -0
  52. package/dist/server.d.ts +9 -9
  53. package/dist/server.mjs +21 -13
  54. package/dist/{tasks-BTbwBqar.d.ts → tasks-DGyz586z.d.ts} +1 -1
  55. package/dist/{thread-XBDVXKUE.mjs → thread-33M5AOEI.mjs} +13 -10
  56. package/dist/vector/search-worker.mjs +5 -4
  57. package/dist/workers/entry.mjs +5 -5
  58. package/package.json +13 -7
  59. package/dist/chunk-IOZPBNSG.mjs +0 -55
  60. package/dist/chunk-WFVOBZS4.mjs +0 -485
  61. package/dist/direct-executor-WB2HKU4N.mjs +0 -17
@@ -1,1528 +1,1529 @@
1
- import { A as AnyDocument, d as ScoringMode, S as SchemaDefinition } from './schema-DgyDijhf.js';
1
+ import { A as AnyDocument, S as SchemaDefinition, d as ScoringMode } from './schema-DgyDijhf.js';
2
2
 
3
3
  /**
4
- * Compares one field against a value. Setting several keys narrows the match,
5
- * because a document has to satisfy all of them.
6
- *
7
- * @public
8
- */
9
- type ComparisonFilter = {
10
- /** This matches a field equal to the value, or a list field where one element equals it. */
11
- eq?: number | string | boolean;
12
- /**
13
- * This matches a document that holds the field with a value other than this
14
- * one, or a list field where every element differs from it, which an empty
15
- * list does.
16
- */
17
- ne?: number | string | boolean;
18
- /** This matches a field greater than the number. */
19
- gt?: number;
20
- /** This matches a field less than the number. */
21
- lt?: number;
22
- /** This matches a field greater than or equal to the number. */
23
- gte?: number;
24
- /** This matches a field less than or equal to the number. */
25
- lte?: number;
26
- /** This matches a field inside the inclusive range, given as `[low, high]`. */
27
- between?: [number, number];
28
- };
29
- /**
30
- * The engine tests a text field against this filter for equality, for a text
31
- * range, or with the set, prefix, and pattern tests.
32
- *
33
- * On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
34
- * element of the list on its own. A document passes `eq`, `in`, `startsWith`,
35
- * `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
36
- * test. However, a document passes `ne` or `nin` only when every element
37
- * differs from the values.
38
- *
39
- * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
40
- * to a single `string` or `verbatim` field whose type includes `sortable`. It
41
- * throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
42
- * orders the values as a sort on the field does, so it compares their case
43
- * folds first and compares their raw code points only where the folds are
44
- * equal.
45
- *
46
- * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
47
- * `string[]` field whose type includes `pattern`. On a pattern field, the
48
- * engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
49
- * `contains`, `wildcard`, and `regex` from the field's pattern index, and
50
- * `caseFold` applies to each of those tests. The engine compares the code
51
- * points of each value as they are stored, with no Unicode normalisation.
52
- *
53
- * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
54
- * `startsWith`, and `endsWith` from the field's index of values. A `string` or
55
- * `string[]` field whose type leaves out `pattern` keeps no index of whole
56
- * values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
57
- * and for `matchesAny` and `containsAll`, on such a field.
58
- *
59
- * The engine also throws `SEARCH_INVALID_FILTER` in these cases:
60
- *
61
- * - The filter sets `contains`, `wildcard`, `regex`, or `caseFold` on a field
62
- * that is not a pattern field.
63
- * - The text or the pattern of a test on a pattern field holds more than 1,024
64
- * code points.
65
- * - A literal test under `caseFold` has a text whose case fold holds more than
66
- * 2,048 code points.
67
- * - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
68
- *
69
- * @public
70
- */
71
- type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
72
- /** This matches a value that comes after the text in sort order. */
73
- gt?: string;
74
- /** This matches a value that comes before the text in sort order. */
75
- lt?: string;
76
- /** This matches a value equal to the text or after it in sort order. */
77
- gte?: string;
78
- /** This matches a value equal to the text or before it in sort order. */
79
- lte?: string;
80
- /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
81
- between?: [string, string];
82
- /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
83
- in?: string[];
84
- /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
85
- nin?: string[];
86
- /** This matches a field starting with the text. */
87
- startsWith?: string;
88
- /** This matches a field ending with the text. */
89
- endsWith?: string;
90
- /** This matches a pattern field whose value holds the text anywhere in it. */
91
- contains?: string;
92
- /**
93
- * This matches a pattern field when the whole value matches the wildcard
94
- * pattern. For example, `INV-*-2024` matches `INV-0042-2024`.
95
- *
96
- * In the pattern, `*` matches any sequence of code points, including an
97
- * empty one, and `?` matches exactly one code point. Write `\` before a code
98
- * point to match that code point itself, so `\*` matches an asterisk.
99
- *
100
- * The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
101
- * `\` with no code point after it. It throws the same error for a pattern
102
- * with more than 2,048 positions. Each `*`, each `?`, and each other code
103
- * point counts as one position, except that under `caseFold` a code point
104
- * counts once for each code point of its case fold.
105
- */
106
- wildcard?: string;
107
- /**
108
- * This matches a pattern field when some part of the value matches the
109
- * regular expression. `^` and `$` match only at the start and at the end of
110
- * the whole value.
111
- *
112
- * The engine accepts literal code points, `.`, `\d`, `\w`, and `\s`, sets
113
- * such as `[a-z]` and `[^0-9]`, groups, and `|`. It also accepts the repeats
114
- * `*`, `+`, `?`, `{n}`, `{n,}`, and `{n,m}`, the anchors `^` and `$`, the
115
- * word edge `\b`, and number ranges such as `<1-65535>`. A number range
116
- * matches the digits of any whole number from its low end to its high end.
117
- * Write `\` before an ASCII punctuation mark to match the mark itself. The
118
- * `.` matches any code point, including a line break.
119
- *
120
- * The matcher never backtracks, so it checks a value in at most as many
121
- * steps as the value's code points multiplied by the pattern's positions.
122
- *
123
- * The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
124
- * syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
125
- * flag. It throws the same error when the groups of a pattern nest more than
126
- * 32 deep, when a count is above 2,048, and when a pattern holds more than
127
- * 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
128
- * option to false, the server refuses every `regex` test.
129
- */
130
- regex?: string;
131
- /**
132
- * When this is true, the engine compares the case fold of each value of a
133
- * pattern field with the case fold of the text, so a test for `error`
134
- * matches `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`,
135
- * `endsWith`, `contains`, `wildcard`, and `regex`.
136
- *
137
- * Under `caseFold`, a set that does not open with `^` can also match a
138
- * sequence of code points. When a member that the set holds on its own folds
139
- * to several code points, the set matches that whole fold, so `[ß]` matches
140
- * `ss`.
141
- */
142
- caseFold?: boolean;
143
- /**
144
- * This lets the `eq` test of a pattern field match a value within this many
145
- * edits of the text, so a test for `INV-2O24` with a tolerance of 1 matches
146
- * `INV-2024`. An edit inserts, deletes, or replaces one code point, so a
147
- * swap of two neighbouring code points counts as two edits. With `caseFold`,
148
- * the engine counts the edits between the case folds of the value and the
149
- * text. The tolerance applies to `eq` alone, so the other tests of the field
150
- * still compare exactly.
151
- *
152
- * The engine takes its candidates from the pattern index, so the case fold
153
- * of the text has to hold enough distinct runs of three code points. For a
154
- * tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
155
- * the number of code points in the longest case fold among the text's code
156
- * points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
157
- * therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
158
- * `'auto'`, the engine uses 2 where the text holds enough runs for 2,
159
- * otherwise 1 where it holds enough for 1, and otherwise 0.
160
- *
161
- * The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
162
- * text with too few runs, stating how many runs that tolerance needs. It
163
- * throws the same error for any other tolerance, for a tolerance on a field
164
- * that is not a pattern field, and for a tolerance in a filter without an
165
- * `eq` test. Towards the pattern work cap, it counts one unit for each cell
166
- * that it fills in the table of edit distances between the text and a
167
- * value.
168
- */
169
- tolerance?: 0 | 1 | 2 | 'auto';
170
- };
171
- /**
172
- * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
173
- * `enum[]`, `verbatim[]`, or `string[]` field.
174
- *
175
- * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
176
- * field, for a value whose type differs from the type of the list's elements,
177
- * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
178
- * out `pattern`.
179
- *
180
- * @public
181
- */
182
- type ArrayFilter = {
183
- /** This matches a list holding every one of the values, at most 65,536 of them, so an empty set of values matches every list. */
184
- containsAll?: (string | number | boolean)[];
185
- /** This matches a list holding at least one of the values, at most 65,536 of them. */
186
- matchesAny?: (string | number | boolean)[];
187
- /** This compares the number of elements in the list. */
188
- size?: ComparisonFilter;
189
- };
190
- /**
191
- * Tests whether a field carries a value at all, without looking at what it
192
- * holds.
193
- *
194
- * @public
195
- */
196
- type PresenceFilter = {
197
- /** This matches a document where the field holds a value other than null. */
198
- exists?: boolean;
199
- /** This matches a document where the field is absent or null. */
200
- notExists?: boolean;
201
- /** This matches a document where the field is absent, null, an empty string, or an empty list. */
202
- isEmpty?: boolean;
203
- /** This matches a document where the field holds a value other than an empty string or an empty list. */
204
- isNotEmpty?: boolean;
205
- };
206
- /**
207
- * Matches a `geopoint` field against a circle drawn on the earth.
208
- *
209
- * @public
210
- */
211
- type GeoRadiusFilter = {
212
- /** The engine tests the field against this circle. */
213
- radius: {
214
- /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
215
- lat: number;
216
- /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
217
- lon: number;
218
- /** The circle has this radius, measured in `unit`. */
219
- distance: number;
220
- /**
221
- * The engine measures `distance` in kilometres under `'km'`, in miles
222
- * under `'mi'`, and in metres under `'m'`. For any other unit, it throws
223
- * `SEARCH_INVALID_FILTER`.
224
- */
225
- unit: 'km' | 'mi' | 'm';
226
- /** The engine matches the points inside the circle while this is true, which is the default, and the points outside it while this is false. */
227
- inside?: boolean;
228
- /**
229
- * The engine measures each distance with the Haversine formula on a sphere
230
- * by default, and with Vincenty's formula on the WGS-84 ellipsoid while
231
- * this is true. Vincenty's formula iterates, so the engine takes longer
232
- * to compute each distance. The two formulas differ by less than 0.3% under about
233
- * 100 km, while across a continent they can differ by up to 0.5%.
234
- */
235
- highPrecision?: boolean;
236
- };
237
- };
238
- /**
239
- * Matches a `geopoint` field against a polygon drawn on the earth.
240
- *
241
- * @public
242
- */
243
- type GeoPolygonFilter = {
244
- /** The engine tests the field against this polygon. */
245
- polygon: {
246
- /**
247
- * The engine closes the ring through these corners in the order that you
248
- * list them, so you can leave the first point off the end. It throws
249
- * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
250
- * encloses no area, and for a corner whose latitude is outside -90 to 90
251
- * or whose longitude is outside -180 to 180. It also throws that error for
252
- * a ring of more than 65,536 corners. List the corners counter-clockwise
253
- * around the area, as in an exterior ring of GeoJSON. Where the corners
254
- * span 180 degrees of longitude or more, the engine matches the area on
255
- * the left of that path, so a ring listed that way can cross the
256
- * antimeridian or span more than half the globe.
257
- */
258
- points: Array<{
259
- lat: number;
260
- lon: number;
261
- }>;
262
- /** The engine matches the points inside the polygon while this is true, which is the default, and the points outside it while this is false. */
263
- inside?: boolean;
264
- };
265
- };
266
- /**
267
- * Either shape a `geopoint` field is matched against.
268
- *
269
- * @public
270
- */
271
- type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
272
- /**
273
- * The filter one field accepts. Which of these forms applies follows from the
274
- * field's declared type.
275
- *
276
- * @public
277
- */
278
- type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
279
- /**
280
- * The filter that a query runs, built from per-field tests and the boolean
281
- * operators that combine them.
4
+ * Every code a {@link NarsilError} carries, grouped by the part of the engine
5
+ * that raises it.
282
6
  *
283
- * The engine answers every test from an index that it keeps for the field. It
284
- * applies the filter before scoring, so a narrow filter makes a search
285
- * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
286
- * tests, counted across every field and nested expression. Past either limit,
287
- * the engine throws `SEARCH_INVALID_FILTER`, while it throws
288
- * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
7
+ * Match on the code rather than on the message, because a code is stable and a
8
+ * message is not. The HTTP server maps each code to a status, so a code also
9
+ * tells you whether the caller or the engine is at fault.
289
10
  *
290
11
  * @public
291
12
  */
292
- type FilterExpression = {
293
- /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
294
- fields?: Record<string, FieldFilter>;
295
- /** Every nested expression has to match. */
296
- and?: FilterExpression[];
297
- /** At least one nested expression has to match. */
298
- or?: FilterExpression[];
299
- /** The nested expression has to fail. */
300
- not?: FilterExpression;
13
+ declare const ErrorCodes: {
14
+ readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
15
+ readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
16
+ readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
17
+ readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
18
+ readonly DOC_NOT_FOUND: "DOC_NOT_FOUND";
19
+ readonly DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS";
20
+ readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
21
+ readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
22
+ readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
23
+ readonly INDEX_ORPHANED: "INDEX_ORPHANED";
24
+ readonly INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED";
25
+ readonly INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN";
26
+ readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
27
+ readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
28
+ readonly WORKER_CRASHED: "WORKER_CRASHED";
29
+ readonly WORKER_BUSY: "WORKER_BUSY";
30
+ readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
31
+ readonly WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED";
32
+ readonly PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED";
33
+ readonly PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED";
34
+ readonly PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED";
35
+ readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
36
+ readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
37
+ readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
38
+ readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
39
+ readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
40
+ readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
41
+ readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
42
+ readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
43
+ readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
44
+ readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
45
+ readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
46
+ readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
47
+ readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
48
+ readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
49
+ readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
50
+ readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
51
+ readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
52
+ readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
53
+ readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
54
+ readonly CONFIG_INVALID: "CONFIG_INVALID";
55
+ readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
56
+ readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
57
+ readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
58
+ readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
59
+ readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
60
+ readonly CLUSTER_WRITE_BLOCKED: "CLUSTER_WRITE_BLOCKED";
61
+ readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
62
+ readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
63
+ readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
64
+ readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
65
+ readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
66
+ readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
67
+ readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
68
+ readonly NODE_NOT_READY: "NODE_NOT_READY";
69
+ readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
70
+ readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
71
+ readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
72
+ readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
73
+ readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
74
+ readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
75
+ readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
76
+ readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
77
+ readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
78
+ readonly REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH";
79
+ readonly REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED";
80
+ readonly PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY";
81
+ readonly PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED";
82
+ readonly INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS";
83
+ readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
84
+ readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
85
+ readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
86
+ readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
87
+ readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
88
+ readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
89
+ readonly SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID";
90
+ readonly SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID";
91
+ readonly SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH";
92
+ readonly SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER";
93
+ readonly SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW";
94
+ readonly SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED";
95
+ readonly SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING";
96
+ readonly SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING";
97
+ readonly SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH";
98
+ readonly SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR";
99
+ readonly SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS";
100
+ readonly SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED";
101
+ readonly SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE";
102
+ readonly SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED";
103
+ readonly SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED";
104
+ readonly SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT";
105
+ readonly SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE";
106
+ readonly SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED";
107
+ readonly SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED";
301
108
  };
302
-
303
109
  /**
304
- * Everything {@link Narsil.suggest} accepts.
110
+ * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
111
+ * when you branch on a failure the engine raised.
305
112
  *
306
113
  * @public
307
114
  */
308
- interface SuggestParams {
309
- /** The returned terms complete this text. */
310
- prefix: string;
311
- /** The lookup returns this many completions, most widely used first, and 10 by default. */
312
- limit?: number;
313
- }
115
+ type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
314
116
  /**
315
- * Everything {@link Narsil.listDocuments} accepts.
316
- *
317
- * {@link Narsil.listDocuments} reads the stored documents without ranking them,
318
- * which is how you page through a whole index. Leave `cursor` out to start at
319
- * the first document, then pass back the cursor each result carries until it
320
- * comes back null.
117
+ * Every code the HTTP layer raises for a failure that arises before or around
118
+ * the engine call, such as parsing the body, enforcing a limit, or routing.
321
119
  *
322
- * A cursor belongs to the sort it was made under, so pass the same `sort` back
323
- * with it. Changing `sort` invalidates the cursor, and the engine then throws
324
- * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
120
+ * The engine raises none of these, so a failure carrying one of them says the
121
+ * request never reached the engine.
325
122
  *
326
123
  * @public
327
124
  */
328
- interface ListParams {
329
- /**
330
- * This cursor comes from a previous result, and continues where it stopped.
331
- * The engine ties a cursor to the sort that produced it, and it throws
332
- * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
333
- */
334
- cursor?: string;
335
- /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
336
- limit?: number;
337
- /** This narrows the listing to the documents the filter accepts. */
338
- filters?: FilterExpression;
339
- /**
340
- * This orders the listing by field value rather than by document id, and the
341
- * engine applies the fields in the order they are listed. Pass an object
342
- * keyed by field, or a list of fields in the order they apply. It breaks a
343
- * tie on document id, and it sorts by at most eight fields. The engine uses
344
- * document-id order when you leave this out.
345
- *
346
- * The engine reads every document the listing covers to build a sorted page,
347
- * so a sorted listing costs more than the default order on a large index.
348
- */
349
- sort?: SortSpec;
350
- /** This chooses how much of each stored document comes back, and the whole document by default. */
351
- document?: DocumentProjection;
352
- }
353
-
125
+ declare const ServerErrorCodes: {
126
+ readonly INVALID_REQUEST: "INVALID_REQUEST";
127
+ readonly INVALID_JSON: "INVALID_JSON";
128
+ readonly EMPTY_BODY: "EMPTY_BODY";
129
+ readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
130
+ readonly NOT_FOUND: "NOT_FOUND";
131
+ readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
132
+ readonly TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE";
133
+ readonly TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE";
134
+ readonly TASK_INTERRUPTED: "TASK_INTERRUPTED";
135
+ readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
136
+ readonly HOOK_ERROR: "HOOK_ERROR";
137
+ readonly INTERNAL_ERROR: "INTERNAL_ERROR";
138
+ };
354
139
  /**
355
- * Which engine answers a query: keyword matching, vector similarity, or both
356
- * merged into one ranking.
140
+ * Any one of the codes in {@link ServerErrorCodes}.
357
141
  *
358
142
  * @public
359
143
  */
360
- type SearchMode = 'fulltext' | 'vector' | 'hybrid';
144
+ type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
361
145
  /**
362
- * How many of a query's terms a document has to carry. `all` demands every
363
- * term, `any` accepts one, and a number demands that many.
146
+ * Every code that the caller's own side raises, where a request never reaches
147
+ * a server, or where the caller cannot read the answer.
148
+ *
149
+ * The HTTP client raises the first five. The React bindings raise
150
+ * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. No
151
+ * server sends any of them, so a failure under one means the exchange broke
152
+ * before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
153
+ * therefore maps none of them, because no request can arrive under one and no
154
+ * HTTP status belongs to one.
364
155
  *
365
156
  * @public
366
157
  */
367
- type TermMatchPolicy = 'all' | 'any' | number;
158
+ declare const ClientErrorCodes: {
159
+ readonly CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED";
160
+ readonly CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT";
161
+ readonly CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED";
162
+ readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
163
+ readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
164
+ readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
165
+ };
368
166
  /**
369
- * One field of a sort, and the direction that field orders by.
167
+ * Any one of the codes in {@link ClientErrorCodes}.
370
168
  *
371
169
  * @public
372
170
  */
373
- interface SortField {
374
- /** The field the engine reads, which may name a nested field with dots. */
375
- field: string;
376
- /** Ascending or descending order for this field. */
377
- direction: 'asc' | 'desc';
378
- /**
379
- * Where a document's field holds a list, the engine sorts that document by
380
- * one value from the list: the smallest under `'min'`, the largest under
381
- * `'max'`, and the mean or the median of the list's numbers under `'avg'`
382
- * or `'median'`. Where you leave this out, the engine uses `'min'` for an
383
- * ascending sort and `'max'` for a descending one. It sorts by a field that
384
- * holds a single value as that value stands, under every mode. It throws
385
- * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
386
- * schema declares as anything other than `number` or `number[]`.
387
- */
388
- mode?: 'min' | 'max' | 'avg' | 'median';
389
- }
171
+ type ClientErrorCode = (typeof ClientErrorCodes)[keyof typeof ClientErrorCodes];
390
172
  /**
391
- * A sort, either as an object keyed by field or as a list of fields in the
392
- * order they apply.
173
+ * Every code a {@link NarsilError} can carry: one the engine raised, one the
174
+ * HTTP layer raised, one the client raised, or any other string.
393
175
  *
394
- * Both forms order by the first field, break a tie on the second, and carry on
395
- * that way. Prefer the list where the order of the fields matters, because
396
- * JavaScript moves an all-digit key such as `2024` to the front of an object
397
- * and the list keeps the order you wrote.
176
+ * The last arm exists for a server's `onRequest` hook, which rejects a request
177
+ * under a code of its own, such as `UNAUTHORIZED`, and the client then passes
178
+ * that code through unchanged. An editor still completes every code Narsil
179
+ * defines.
398
180
  *
399
181
  * @public
400
182
  */
401
- type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
183
+ type NarsilErrorCode = ErrorCode | ServerErrorCode | ClientErrorCode | (string & {});
402
184
  /**
403
- * Everything {@link Narsil.query} accepts.
185
+ * The error every part of the engine throws.
404
186
  *
405
- * Set `term` for keyword search, `vector` for similarity search, and `mode`
406
- * when you want both. The engine matches nothing for a query carrying neither
407
- * of them, so page through an index with {@link Narsil.listDocuments}
408
- * instead.
187
+ * Catch it, read {@link NarsilError.code} to decide what to do, and read
188
+ * {@link NarsilError.details} for the values that caused it. The engine lets
189
+ * this error propagate unchanged, so the code you catch is the code the
190
+ * failing operation raised.
409
191
  *
410
192
  * @public
411
193
  */
412
- interface QueryParams {
413
- /** The engine analyses this text with the index's language module and searches for the terms that result. */
414
- term?: string;
415
- /** The engine searches the term in these fields, and in every text field in the schema by default. */
416
- fields?: string[];
417
- /**
418
- * The engine scores only the documents that pass this filter. It throws
419
- * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
420
- * operator on a field of another type, such as `startsWith` on a number
421
- * field.
422
- */
423
- filters?: FilterExpression;
424
- /**
425
- * The engine multiplies the score from each named field by its weight. It
426
- * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
427
- * the schema declares, and `CONFIG_INVALID` for a weight that is not a
428
- * finite number.
429
- */
430
- boost?: Record<string, number>;
431
- /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
432
- scoring?: ScoringMode;
433
- /**
434
- * The engine drops any hit scoring below this value. It ranks with BM25,
435
- * which has no fixed upper bound, so a floor that suits one index and one
436
- * query can reject every hit in another.
437
- */
438
- minScore?: number;
439
- /**
440
- * The engine keeps a document only where the document matches this many
441
- * query terms, under the same `tolerance` and `prefixLength` that the search
442
- * uses. One term is enough by default.
443
- */
444
- termMatch?: TermMatchPolicy;
445
- /**
446
- * The engine matches an indexed term within this edit distance of a query
447
- * term, so it finds a document for a query with a typo. It counts each
448
- * Unicode code point as one character. Set an integer from 0 to 10.
449
- */
450
- tolerance?: number;
451
- /**
452
- * The engine applies `tolerance` only to the indexed terms that share this
453
- * many leading characters with the query term, or to the terms that start
454
- * with the whole query term when the query term is shorter. Set an integer
455
- * from 0 to 1,024; the default is 2.
456
- */
457
- prefixLength?: number;
458
- /**
459
- * With this set, the engine treats the last query term as an unfinished
460
- * word, so `secur` matches `security`. The engine matches that last term by
461
- * its stem or by completing it, while `tolerance` applies only to the earlier
462
- * terms, which have to match whole. The engine scores completions against a
463
- * shared document frequency. It also ranks them below whole-word matches.
464
- * The engine ignores this setting where `exact` is true, and the setting is
465
- * false by default.
466
- */
467
- prefix?: boolean;
194
+ declare class NarsilError extends Error {
195
+ /** This says which failure it is. */
196
+ readonly code: NarsilErrorCode;
197
+ /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
198
+ readonly details: Record<string, unknown>;
468
199
  /**
469
- * With this set, the engine also matches each query word of three or more
470
- * characters inside the longer words of every field whose type includes
471
- * `partial`, so a search for `proof` matches a document with `waterproof`
472
- * in such a field. The engine counts each Unicode code point as one
473
- * character. It looks for the query word, before stemming, inside each word
474
- * exactly as that word appears in a document.
475
- *
476
- * The engine adds at most 50 such words to a query, which it divides as
477
- * evenly as it can among the query words. Within the share of each query
478
- * word, it adds first the words that the most documents contain. It scores
479
- * a match inside a longer word in proportion to the part of that word that
480
- * the query word makes up, so it scores such a match below a whole-word
481
- * match at the same frequency in a field of the same length. With
482
- * `highlight`, it tags each whole word that contains a query word in a
483
- * searched `partial` field.
200
+ * Builds an error carrying a code the caller can branch on.
484
201
  *
485
- * The engine applies no `tolerance` to these matches. It ignores this
486
- * setting where `exact` is true or where the searched fields include no
487
- * `partial` field. Where the setting is absent, the engine treats it as
488
- * false, while it throws `CONFIG_INVALID` for any value other than `true`
489
- * or `false`.
490
- */
491
- partialWords?: boolean;
492
- /**
493
- * With this set, the engine matches each query term only against an equal
494
- * indexed term, so it turns off fuzzy matching, prefix completion, and
495
- * partial-word matching. The engine still stems the query, because the
496
- * index stores stemmed terms, so a search for `running` matches a document
497
- * that contains `runs` through the stem that both words share.
498
- */
499
- exact?: boolean;
500
- /**
501
- * The engine counts the values of these fields across the matching
502
- * documents, and each entry sets how it cuts and sorts that field's counts.
503
- * For a field outside the schema, it counts the values that the documents
504
- * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
505
- * field.
506
- */
507
- facets?: FacetConfig;
508
- /**
509
- * The engine sorts the hits by the values of these fields, in place of the
510
- * relevance ranking. Pass an object keyed by field, or a list of fields in
511
- * the order that the engine compares them. The engine sorts by a `number`,
512
- * `boolean`, or `enum` field, by a text field whose type includes
513
- * `sortable`, or by a list of any of these, which it reduces to one value by
514
- * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
515
- * `geopoint` or a vector field, because neither type has an order. It throws
516
- * the same code for a sort on any other text field, since the engine keeps
517
- * up to the first 512 code points of every document's value in memory to
518
- * sort by a text field. The engine orders hybrid results by fusion, so it
519
- * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
520
- * that code for a direction other than `asc` and `desc`.
521
- */
522
- sort?: SortSpec;
523
- /** These settings collapse the hits into groups by field value. */
524
- group?: GroupConfig;
525
- /**
526
- * The query returns this many hits, and 10 by default. Pass 0 to read the
527
- * match count with no hits. The engine reads a value below 0 as 0. It falls
528
- * back to the default for `NaN` and for an infinite value, so a page size
529
- * that you compute from user input never fails the query.
530
- */
531
- limit?: number;
532
- /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
533
- offset?: number;
534
- /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
535
- searchAfter?: string;
536
- /** These settings name the fields that come back with highlighted snippets. */
537
- highlight?: HighlightConfig;
538
- /** These documents take fixed positions, ahead of the ranking. */
539
- pinned?: Array<{
540
- docId: string;
541
- position: number;
542
- }>;
543
- /** This picks which engine answers the query. Keyword search runs by default. */
544
- mode?: SearchMode;
545
- /** These vector-search inputs are required in `vector` and `hybrid` mode. */
546
- vector?: VectorQueryConfig;
547
- /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
548
- hybrid?: HybridConfig;
549
- /**
550
- * Setting this returns relevance scores on a sorted query. A query that
551
- * names a sort ranks by sort values alone and computes no scores, so its
552
- * hits carry none until this restores them. A query without a sort ignores
553
- * this and always carries scores.
202
+ * @param code - The failure this error reports, from {@link ErrorCodes} for
203
+ * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
204
+ * or {@link ClientErrorCodes} for one that stopped a request from reaching a
205
+ * server.
206
+ * @param message - Plain description, for a log or a person.
207
+ * @param details - Values behind the failure, which reach
208
+ * {@link NarsilError.details}.
554
209
  */
555
- includeScores?: boolean;
556
- /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
557
- includeScoreComponents?: boolean;
558
- /** This chooses how much of each stored document comes back, and the whole document by default. */
559
- document?: DocumentProjection;
210
+ constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
560
211
  }
561
212
  /**
562
- * How much of a stored document each hit carries back.
213
+ * Reports whether a caught value is a {@link NarsilError}, including one that
214
+ * another entry point of this package raises.
563
215
  *
564
- * Pass `false` when the ids and scores are all you need, and every hit's
565
- * `document` is then an empty object. Pass `include` to keep named fields
566
- * alone, or `exclude` to drop named fields and keep the rest; naming both
567
- * keeps the included fields and then drops the excluded ones from those. Use
568
- * dots to name a nested field, so `author.name` addresses the `name` inside
569
- * `author`, and a name that matches no field changes nothing.
216
+ * Each browser bundle holds its own copy of the class, so an `instanceof` test
217
+ * inside the React bindings returns false for an error that the client raises,
218
+ * although that error still holds its code. This function tests for the marker
219
+ * that the constructor writes, so it returns true for an error from any entry
220
+ * point.
570
221
  *
571
- * Drop a vector field on a similarity search, because the engine otherwise
572
- * reads every hit's vector back out of the index and writes it into the
573
- * response.
222
+ * @param value - The value that a `catch` block receives.
223
+ * @returns True where the value holds a code in {@link NarsilError.code}.
574
224
  *
575
225
  * @public
576
226
  */
577
- type DocumentProjection = boolean | {
578
- /** Names the fields to keep, so every field left out of this list is dropped. */
579
- include?: string[];
580
- /** Names the fields to drop, so every other field is kept. */
581
- exclude?: string[];
582
- };
227
+ declare function isNarsilError(value: unknown): value is NarsilError;
228
+
583
229
  /**
584
- * Vector-search inputs passed under `QueryParams.vector`.
230
+ * What {@link Narsil.query} returns: the ranked hits and everything the query
231
+ * asked for alongside them.
585
232
  *
586
- * Supply either a raw `value` array or a `text` string for auto-embedding;
587
- * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
588
- * by the outer query's `limit`, not by any field on this object.
233
+ * @typeParam T - Shape of the stored documents, which flows through to each
234
+ * hit's `document`.
589
235
  *
590
236
  * @public
591
237
  */
592
- interface VectorQueryConfig {
593
- /**
594
- * Name of the schema field that holds the vector to compare against.
595
- * Must reference a field declared as `vector[N]` in the index schema.
596
- */
597
- field: string;
598
- /**
599
- * Raw query vector, given as a number array or a `Float32Array`. Length
600
- * must match the indexed field's dimension or the search rejects the
601
- * request with `VECTOR_DIMENSION_MISMATCH`.
602
- */
603
- value?: number[] | Float32Array;
604
- /**
605
- * Text to embed at query time using the index or instance embedding
606
- * adapter. Mutually exclusive with `value`; requires a configured adapter.
607
- */
608
- text?: string;
609
- /**
610
- * Score floor applied during ranking. Hits scoring below this value
611
- * are dropped before `limit` is enforced, so the returned hit count
612
- * can be smaller than `limit` even when more documents exist. The
613
- * floor is interpreted in score space for every metric; for
614
- * `euclidean`, distance is mapped to a similarity score of
615
- * `1 / (1 + distance)` first. Defaults to no floor.
616
- */
617
- similarity?: number;
618
- /**
619
- * Similarity metric used for ranking. Defaults to `cosine`. Choose
620
- * `dotProduct` for raw inner-product scoring on already-normalised
621
- * vectors and `euclidean` for distance-based ordering.
622
- */
623
- metric?: 'cosine' | 'dotProduct' | 'euclidean';
238
+ interface QueryResult<T = AnyDocument> {
239
+ /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
240
+ hits: Array<Hit<T>>;
624
241
  /**
625
- * HNSW exploration factor for approximate search. Higher values raise
626
- * recall at the cost of latency. Ignored while the field is still
627
- * served by the brute-force backend. Defaults to the engine's built-in
628
- * value when omitted.
242
+ * This many documents match in total, before the engine applies `limit`
243
+ * and `offset`. For a keyword search the engine counts every match. For a
244
+ * vector search it counts every vector that passes the query's filter and
245
+ * its `similarity` floor, which is every vector in the field where the query
246
+ * sets neither of them. The engine also counts each pinned document that
247
+ * the query does not match, since it places that document among the hits.
629
248
  */
630
- efSearch?: number;
249
+ count: number;
631
250
  /**
632
- * How many times `limit` a quantized field re-scores against its
633
- * full-precision vectors before it returns the best `limit`. A value below
634
- * 1 or one that is not a finite number fails with `CONFIG_INVALID`. The
635
- * engine ignores this on a field whose quantization is `none`. When a query
636
- * omits it, the engine takes 3 for `osq1` and `osq2`, 2 for `osq8`, and 2
637
- * for `osq4` at 1,024 dimensions and above, but 5 for `osq4` below 1,024,
638
- * where a four-bit code ranks the true neighbours less reliably.
251
+ * `count` holds the exact number of matches where this is true, and a
252
+ * number at or below the true total where it is false. Where a query sets a
253
+ * `similarity` floor on a vector field that holds a graph, the engine
254
+ * counts only the vectors that it fetches, because it compares the query
255
+ * with only a fraction of that field's vectors. For a hybrid query the
256
+ * engine fuses two rankings, so the count is exact only where each of those
257
+ * rankings contains every matching document. Where you pin a document from
258
+ * outside the hits that the engine fetches, the engine reports true only
259
+ * where it holds every match of the query, because only then can it test
260
+ * whether the query matches that document.
639
261
  */
640
- oversample?: number;
262
+ countExact: boolean;
263
+ /** The engine spent this many milliseconds on the search. */
264
+ elapsed: number;
265
+ /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
266
+ cursor?: string;
267
+ /** These facet counts are keyed by the field each facet was asked for. */
268
+ facets?: Record<string, FacetResult>;
269
+ /** These groups arrive when the query asked for grouping. */
270
+ groups?: GroupResult[];
271
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
272
+ analysisStale?: boolean;
273
+ /** The search read this much of the index, which is how you spot a degraded answer. */
274
+ coverage: QueryCoverage;
641
275
  }
642
276
  /**
643
- * How a hybrid query merges its keyword ranking with its vector ranking.
277
+ * How much of an index one search read, which is what you check before you
278
+ * trust a count or a ranking.
644
279
  *
645
- * `rrf` combines the two by rank alone, which needs no tuning and handles
646
- * scores that live on different scales. `linear` blends the scores directly,
647
- * which gives you control once you know what each side's scores look like.
280
+ * An embedded engine reads every partition it holds, so `queriedPartitions`
281
+ * matches `totalPartitions` there and the other two stay zero. A search across
282
+ * a cluster may find a node slow or unreachable, which it counts here while
283
+ * still returning the hits the other nodes gave it.
648
284
  *
649
285
  * @public
650
286
  */
651
- interface HybridConfig {
652
- /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
653
- strategy?: 'rrf' | 'linear';
654
- /** The engine uses this rank-fusion constant under `rrf` alone, where a larger value reduces the lead of the top ranks. Set a whole number of at least 1, or leave it out for 60. The engine throws `CONFIG_INVALID` for any other value. */
655
- k?: number;
656
- /** The engine uses this weight of the vector score, from 0 to 1, under `linear` alone, and 0.5 where you leave it out. It throws `CONFIG_INVALID` for a value outside that range. */
657
- alpha?: number;
287
+ interface QueryCoverage {
288
+ /** The search should have read this many partitions. */
289
+ totalPartitions: number;
290
+ /** The search read this many of them. */
291
+ queriedPartitions: number;
292
+ /** The search counts a partition here when the node holding it took longer than the query allowed. */
293
+ timedOutPartitions: number;
294
+ /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
295
+ failedPartitions: number;
658
296
  }
659
297
  /**
660
- * Fields a query counts values for, keyed by field name.
298
+ * One matching document, with the score that ranked it.
661
299
  *
662
- * @public
663
- */
664
- interface FacetConfig {
665
- /** Each key names a field the query counts values for. */
666
- [field: string]: {
667
- /** The engine returns this many values for the field, in the order of `sort`. An engine returns every value where you leave this out, while a cluster returns 10, or every range of a field that sets `ranges`. */
668
- limit?: number;
669
- /** The engine orders the returned values by their count, putting the highest first under `'desc'`, which is the default, and the lowest first under `'asc'`. Under `'asc'`, each cluster node sends the count of up to 10,000 values of the field, so the lowest counts are exact wherever no node holds more values than that. */
670
- sort?: 'asc' | 'desc';
671
- /** The engine counts a numeric field's matches into these ranges, with one count for each range. A cluster search counts up to 1,000 ranges on a field and throws `CONFIG_INVALID` for more. */
672
- ranges?: Array<{
673
- from: number;
674
- to: number;
675
- }>;
676
- };
677
- }
678
- /**
679
- * How a query collapses its hits into groups.
300
+ * @typeParam T - Shape of the stored document.
680
301
  *
681
302
  * @public
682
303
  */
683
- interface GroupConfig {
684
- /** The values of these fields define a group, and several fields group by their combination. */
685
- fields: string[];
686
- /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
687
- maxPerGroup?: number;
688
- /** The engine returns this many groups, best first, and every group where you leave this out. */
689
- limit?: number;
304
+ interface Hit<T = AnyDocument> {
305
+ /** The document is stored under this id. */
306
+ id: string;
690
307
  /**
691
- * The engine folds every hit of each group into one value, such as a sum or
692
- * an average, including the hits beyond `maxPerGroup`. In cluster mode the
693
- * coordinator fetches up to 10,000 hits of each group to fold.
308
+ * This score ranked the hit. Scores compare within one result set, never
309
+ * across searches. A sorted query ranks by sort values instead and carries
310
+ * no score unless it sets `includeScores`.
694
311
  */
695
- reduce?: GroupReducer;
312
+ score?: number;
313
+ /** This is the stored document. */
314
+ document: T;
315
+ /** These are the parts the score was built from, which arrive when the query asked for them. */
316
+ scoreComponents?: ScoreComponents;
317
+ /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
318
+ highlights?: Record<string, HighlightMatch>;
696
319
  }
697
320
  /**
698
- * Folds the hits of one group into a single value.
321
+ * The numbers BM25 combined into one hit's score, which is what you read when
322
+ * a ranking surprises you.
699
323
  *
700
324
  * @public
701
325
  */
702
- type GroupReducer = {
326
+ interface ScoreComponents {
703
327
  /**
704
- * Folds one hit into the running value.
705
- *
706
- * @param accumulator - What the previous call returned, or what
707
- * `initialValue` produced for the first hit.
708
- * @param doc - The hit's stored document.
709
- * @param score - The hit's relevance score.
710
- * @returns The new running value.
328
+ * Each query term appears in one field of this document this many times,
329
+ * under a key of `field:term`. A term that appears in two fields therefore
330
+ * has two entries here, while the keys of {@link ScoreComponents.idf} hold
331
+ * the bare term.
711
332
  */
712
- reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
713
- /** Produces the starting value for each group. The engine calls it once per group. */
714
- initialValue: () => unknown;
715
- };
333
+ termFrequencies: Record<string, number>;
334
+ /** Each field the query searched holds this many tokens, keyed by field. */
335
+ fieldLengths: Record<string, number>;
336
+ /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
337
+ idf: Record<string, number>;
338
+ }
716
339
  /**
717
- * This configuration names the fields that receive highlighted snippets. It
718
- * also sets how the engine marks those snippets up.
719
- *
720
- * The engine analyses the text of each returned field again to tag every word
721
- * that it matched, so it tags the same words whatever the index's
722
- * `trackPositions` setting is. It tags a word whose stem equals a query stem,
723
- * and a word within the query's `tolerance` of a query stem. For a `prefix`
724
- * query, it tags a word for the last query term only when that word completes
725
- * the term or shares its stem.
340
+ * A highlighted field, ready to render.
726
341
  *
727
342
  * @public
728
343
  */
729
- interface HighlightConfig {
730
- /** The engine highlights these fields. */
731
- fields: string[];
732
- /** The engine writes this before each match, and writes `<mark>` by default. */
733
- preTag?: string;
734
- /** The engine writes this after each match, and writes `</mark>` by default. */
735
- postTag?: string;
344
+ interface HighlightMatch {
345
+ /** This is the field's text around the match, wrapped in the query's tags. */
346
+ snippet: string;
736
347
  /**
737
- * The engine takes this many characters of the field around the densest run
738
- * of matches, 200 by default. It returns a snippet longer than that number,
739
- * because it then adds the opening and closing tags, and an ellipsis at each
740
- * end where it cuts the field.
348
+ * Each range gives the start and the end of one match in the original field,
349
+ * so you can render the highlight yourself. Where the snippet covers part of
350
+ * the field alone, the engine lists only the matches that the snippet
351
+ * displays. Every offset is a character count from the start of the original
352
+ * field, whatever the snippet contains.
741
353
  */
742
- maxSnippetLength?: number;
354
+ positions: Array<{
355
+ start: number;
356
+ end: number;
357
+ }>;
743
358
  }
744
-
745
359
  /**
746
- * Every code a {@link NarsilError} carries, grouped by the part of the engine
747
- * that raises it.
748
- *
749
- * Match on the code rather than on the message, because a code is stable and a
750
- * message is not. The HTTP server maps each code to a status, so a code also
751
- * tells you whether the caller or the engine is at fault.
360
+ * Counts for one faceted field.
752
361
  *
753
362
  * @public
754
363
  */
755
- declare const ErrorCodes: {
756
- readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
757
- readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
758
- readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
759
- readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
760
- readonly DOC_NOT_FOUND: "DOC_NOT_FOUND";
761
- readonly DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS";
762
- readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
763
- readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
764
- readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
765
- readonly INDEX_ORPHANED: "INDEX_ORPHANED";
766
- readonly INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED";
767
- readonly INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN";
768
- readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
769
- readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
770
- readonly WORKER_CRASHED: "WORKER_CRASHED";
771
- readonly WORKER_BUSY: "WORKER_BUSY";
772
- readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
773
- readonly WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED";
774
- readonly PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED";
775
- readonly PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED";
776
- readonly PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED";
777
- readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
778
- readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
779
- readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
780
- readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
781
- readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
782
- readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
783
- readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
784
- readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
785
- readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
786
- readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
787
- readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
788
- readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
789
- readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
790
- readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
791
- readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
792
- readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
793
- readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
794
- readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
795
- readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
796
- readonly CONFIG_INVALID: "CONFIG_INVALID";
797
- readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
798
- readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
799
- readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
800
- readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
801
- readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
802
- readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
803
- readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
804
- readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
805
- readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
806
- readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
807
- readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
808
- readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
809
- readonly NODE_NOT_READY: "NODE_NOT_READY";
810
- readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
811
- readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
812
- readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
813
- readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
814
- readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
815
- readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
816
- readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
817
- readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
818
- readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
819
- readonly REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH";
820
- readonly REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED";
821
- readonly PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY";
822
- readonly PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED";
823
- readonly INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS";
824
- readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
825
- readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
826
- readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
827
- readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
828
- readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
829
- readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
830
- readonly SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID";
831
- readonly SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID";
832
- readonly SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH";
833
- readonly SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER";
834
- readonly SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW";
835
- readonly SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED";
836
- readonly SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING";
837
- readonly SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING";
838
- readonly SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH";
839
- readonly SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR";
840
- readonly SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS";
841
- readonly SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED";
842
- readonly SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE";
843
- readonly SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED";
844
- readonly SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED";
845
- readonly SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT";
846
- readonly SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE";
847
- readonly SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED";
848
- readonly SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED";
849
- };
364
+ interface FacetResult {
365
+ /** This many documents match per value, keyed by value. */
366
+ values: Record<string, number>;
367
+ /** This is the number of entries in `values`, which is at most the facet's `limit`. */
368
+ count: number;
369
+ /**
370
+ * Every count in `values` is at most this far below its true count. A value
371
+ * that the engine leaves out of `values` because of `limit` has a true
372
+ * count of at most this figure too. Where the engine counts a field on one
373
+ * thread, it counts every value exactly, so this figure is the largest
374
+ * count that it leaves out. Where it splits the count across worker copies
375
+ * or cluster nodes, each of them returns only its own top values, so the
376
+ * merged count of a value that is common overall but rare on one of them
377
+ * can lack the matches on that one. A bound of 0 means that `values` holds
378
+ * every matching value, each with its exact count.
379
+ */
380
+ errorBound: number;
381
+ }
850
382
  /**
851
- * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
852
- * when you branch on a failure the engine raised.
383
+ * One group of hits, produced by a query that grouped its results.
853
384
  *
854
385
  * @public
855
386
  */
856
- type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
387
+ interface GroupResult {
388
+ /** Each grouping field holds this value for the group, keyed by field. */
389
+ values: Record<string, unknown>;
390
+ /** These hits fall in the group, cut to the query's `maxPerGroup`. */
391
+ hits: Array<Hit>;
392
+ /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
393
+ reduced?: unknown;
394
+ /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
395
+ reducerError?: string;
396
+ }
857
397
  /**
858
- * Every code the HTTP layer raises for a failure that arises before or around
859
- * the engine call, such as parsing the body, enforcing a limit, or routing.
860
- *
861
- * The engine raises none of these, so a failure carrying one of them says the
862
- * request never reached the engine.
398
+ * What {@link Narsil.preflight} returns: how many documents a query matches,
399
+ * without building or ranking a single hit.
863
400
  *
864
401
  * @public
865
402
  */
866
- declare const ServerErrorCodes: {
867
- readonly INVALID_REQUEST: "INVALID_REQUEST";
868
- readonly INVALID_JSON: "INVALID_JSON";
869
- readonly EMPTY_BODY: "EMPTY_BODY";
870
- readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
871
- readonly NOT_FOUND: "NOT_FOUND";
872
- readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
873
- readonly TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE";
874
- readonly TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE";
875
- readonly TASK_INTERRUPTED: "TASK_INTERRUPTED";
876
- readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
877
- readonly HOOK_ERROR: "HOOK_ERROR";
878
- readonly INTERNAL_ERROR: "INTERNAL_ERROR";
879
- };
403
+ interface PreflightResult {
404
+ /** The query matches this many documents. */
405
+ count: number;
406
+ /** `count` holds the exact number of matches where this is true, and a number at or below the true total where it is false, under the rule in {@link QueryResult.countExact}. */
407
+ countExact: boolean;
408
+ /** The count took this many milliseconds. */
409
+ elapsed: number;
410
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
411
+ analysisStale?: boolean;
412
+ }
880
413
  /**
881
- * Any one of the codes in {@link ServerErrorCodes}.
414
+ * What a batch write returns. One bad document never abandons the rest, so
415
+ * read both lists.
882
416
  *
883
417
  * @public
884
418
  */
885
- type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
419
+ interface BatchResult {
420
+ /** The engine wrote the documents under these ids. */
421
+ succeeded: string[];
422
+ /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
423
+ failed: Array<{
424
+ docId: string;
425
+ error: NarsilError;
426
+ }>;
427
+ }
886
428
  /**
887
- * Every code that the caller's own side raises, where a request never reaches
888
- * a server, or where the caller cannot read the answer.
429
+ * What {@link Narsil.importDocumentExport} returns. The engine continues past each
430
+ * refused line, so read the refusals to learn which documents it skipped.
889
431
  *
890
- * The HTTP client raises the first five. The React bindings raise
891
- * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. No
892
- * server sends any of them, so a failure under one means the exchange broke
893
- * before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
894
- * therefore maps none of them, because no request can arrive under one and no
895
- * HTTP status belongs to one.
432
+ * @public
433
+ */
434
+ interface DocumentImportResult {
435
+ /** The engine wrote this many documents, counting each one that it replaced. */
436
+ imported: number;
437
+ /** The engine refused this many lines in total. */
438
+ refusedCount: number;
439
+ /** These are the 1,000 refusals with the lowest line numbers. Each entry contains the line number, where the header is line 1, along with the error code and a message. */
440
+ refused: Array<{
441
+ line: number;
442
+ code: NarsilErrorCode;
443
+ message: string;
444
+ }>;
445
+ }
446
+ /**
447
+ * What {@link Narsil.getStats} returns about one index.
896
448
  *
897
449
  * @public
898
450
  */
899
- declare const ClientErrorCodes: {
900
- readonly CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED";
901
- readonly CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT";
902
- readonly CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED";
903
- readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
904
- readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
905
- readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
906
- };
451
+ interface IndexStats {
452
+ /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
453
+ documentCount: number;
454
+ /** The index is spread across this many partitions. */
455
+ partitionCount: number;
456
+ /**
457
+ * Formula-based estimate of the index's main-thread memory footprint, summed
458
+ * across every partition and vector index for this index. Computed from
459
+ * structural counters (document count, posting counts, field-index sizes),
460
+ * not measured. Per-object V8 overhead (hidden classes, map transitions,
461
+ * GC headers) is not captured here, so this number routinely undershoots
462
+ * the real heap by a meaningful factor. Use {@link Narsil.getMemoryStats}
463
+ * when sizing host memory.
464
+ */
465
+ estimatedMemoryBytes: number;
466
+ /** The index analyses text with this language module. */
467
+ language: string;
468
+ /** The index was created with this field layout. */
469
+ schema: SchemaDefinition;
470
+ }
907
471
  /**
908
- * Any one of the codes in {@link ClientErrorCodes}.
472
+ * A summary of one index, as {@link Narsil.listIndexes} reports it.
909
473
  *
910
474
  * @public
911
475
  */
912
- type ClientErrorCode = (typeof ClientErrorCodes)[keyof typeof ClientErrorCodes];
476
+ interface IndexInfo {
477
+ /** The index was created under this name. */
478
+ name: string;
479
+ /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
480
+ documentCount: number;
481
+ /** The index is spread across this many partitions. */
482
+ partitionCount: number;
483
+ /** The index analyses text with this language module. */
484
+ language: string;
485
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
486
+ analysisStale?: boolean;
487
+ /** This is `open` in memory, `closed` after release, and `reopen-failed` after five recovery failures. */
488
+ state: 'open' | 'closed' | 'reopen-failed';
489
+ /** This counts successful loads since this engine started. */
490
+ reopenCount: number;
491
+ }
913
492
  /**
914
- * Every code a {@link NarsilError} can carry: one the engine raised, one the
915
- * HTTP layer raised, one the client raised, or any other string.
493
+ * What {@link Narsil.getPartitionStats} reports for one partition, which is
494
+ * where you look when an index grows unevenly.
916
495
  *
917
- * The last arm exists for a server's `onRequest` hook, which rejects a request
918
- * under a code of its own, such as `UNAUTHORIZED`, and the client then passes
919
- * that code through unchanged. An editor still completes every code Narsil
920
- * defines.
496
+ * @public
497
+ */
498
+ interface PartitionStatsResult {
499
+ /** This identifies the partition within its index. */
500
+ partitionId: number;
501
+ /** The partition holds this many documents. */
502
+ documentCount: number;
503
+ /**
504
+ * Formula-based estimate of this partition's memory footprint. V8 has no
505
+ * per-object heap accounting API, so this number is derived from structural
506
+ * counters (document count, posting counts, field-index sizes) and does not
507
+ * include per-object overhead. Treat as an estimate, not a measurement.
508
+ */
509
+ estimatedMemoryBytes: number;
510
+ }
511
+ /**
512
+ * What {@link Narsil.suggest} returns: the indexed terms that complete a
513
+ * prefix, ready to offer as you-type suggestions.
921
514
  *
922
515
  * @public
923
516
  */
924
- type NarsilErrorCode = ErrorCode | ServerErrorCode | ClientErrorCode | (string & {});
517
+ interface SuggestResult {
518
+ /** These completions run most widely used first. */
519
+ terms: Array<{
520
+ /** This is the completed term, as the index holds it. */
521
+ term: string;
522
+ /** The term appears in this many documents, which is what ordered the list. */
523
+ documentFrequency: number;
524
+ }>;
525
+ /** The lookup took this many milliseconds. */
526
+ elapsed: number;
527
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
528
+ analysisStale?: boolean;
529
+ }
925
530
  /**
926
- * The error every part of the engine throws.
531
+ * The state of one vector field, and what maintenance would cost, as
532
+ * {@link Narsil.vectorMaintenanceStatus} reports it.
927
533
  *
928
- * Catch it, read {@link NarsilError.code} to decide what to do, and read
929
- * {@link NarsilError.details} for the values that caused it. The engine lets
930
- * this error propagate unchanged, so the code you catch is the code the
931
- * failing operation raised.
534
+ * Removing a vector leaves a tombstone in the graph, and enough of them slow a
535
+ * search down. Read this to decide when compaction earns its cost.
932
536
  *
933
537
  * @public
934
538
  */
935
- declare class NarsilError extends Error {
936
- /** This says which failure it is. */
937
- readonly code: NarsilErrorCode;
938
- /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
939
- readonly details: Record<string, unknown>;
539
+ interface VectorMaintenanceResult {
540
+ /** This describes the named vector field. */
541
+ fieldName: string;
940
542
  /**
941
- * Builds an error carrying a code the caller can branch on.
942
- *
943
- * @param code - The failure this error reports, from {@link ErrorCodes} for
944
- * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
945
- * or {@link ClientErrorCodes} for one that stopped a request from reaching a
946
- * server.
947
- * @param message - Plain description, for a log or a person.
948
- * @param details - Values behind the failure, which reach
949
- * {@link NarsilError.details}.
543
+ * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
544
+ * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
545
+ * the engine divides by the number of stored vectors, because no graph
546
+ * exists yet.
950
547
  */
951
- constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
548
+ tombstoneRatio: number;
549
+ /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
550
+ graphCount: number;
551
+ /** This many vectors wait outside the graph, which a search scans one by one. */
552
+ bufferSize: number;
553
+ /** This stays true while a graph build runs. */
554
+ building: boolean;
555
+ /** {@link Narsil.compactVectors} would take about this many milliseconds. */
556
+ estimatedCompactMs: number;
557
+ /** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
558
+ estimatedOptimizeMs: number;
559
+ }
560
+ /**
561
+ * One stored document, as {@link Narsil.listDocuments} returns it.
562
+ *
563
+ * @typeParam T - Shape of the stored document.
564
+ *
565
+ * @public
566
+ */
567
+ interface ListedDocument<T = AnyDocument> {
568
+ /** The document is stored under this id. */
569
+ id: string;
570
+ /** This holds the stored document, cut down to what the projection kept. */
571
+ document: T;
572
+ }
573
+ /**
574
+ * What {@link Narsil.listDocuments} returns: one page of stored documents and
575
+ * the cursor that reaches the next one.
576
+ *
577
+ * @typeParam T - Shape of the stored documents.
578
+ *
579
+ * @public
580
+ */
581
+ interface ListResult<T = AnyDocument> {
582
+ /** These documents make up the page, in ascending document-id order. */
583
+ documents: Array<ListedDocument<T>>;
584
+ /** This opaque cursor reaches the next page, and is null once the listing is finished. */
585
+ cursor: string | null;
586
+ /** The listing covers this many documents in total, and any filter narrows that count. */
587
+ total: number;
588
+ /** The engine spent this many milliseconds building the page. */
589
+ elapsed: number;
952
590
  }
591
+
953
592
  /**
954
- * Reports whether a caught value is a {@link NarsilError}, including one that
955
- * another entry point of this package raises.
956
- *
957
- * Each browser bundle holds its own copy of the class, so an `instanceof` test
958
- * inside the React bindings returns false for an error that the client raises,
959
- * although that error still holds its code. This function tests for the marker
960
- * that the constructor writes, so it returns true for an error from any entry
961
- * point.
962
- *
963
- * @param value - The value that a `catch` block receives.
964
- * @returns True where the value holds a code in {@link NarsilError.code}.
593
+ * Compares one field against a value. Setting several keys narrows the match,
594
+ * because a document has to satisfy all of them.
965
595
  *
966
596
  * @public
967
597
  */
968
- declare function isNarsilError(value: unknown): value is NarsilError;
969
-
598
+ type ComparisonFilter = {
599
+ /** This matches a field equal to the value, or a list field where one element equals it. */
600
+ eq?: number | string | boolean;
601
+ /**
602
+ * This matches a document that holds the field with a value other than this
603
+ * one, or a list field where every element differs from it, which an empty
604
+ * list does.
605
+ */
606
+ ne?: number | string | boolean;
607
+ /** This matches a field greater than the number. */
608
+ gt?: number;
609
+ /** This matches a field less than the number. */
610
+ lt?: number;
611
+ /** This matches a field greater than or equal to the number. */
612
+ gte?: number;
613
+ /** This matches a field less than or equal to the number. */
614
+ lte?: number;
615
+ /** This matches a field inside the inclusive range, given as `[low, high]`. */
616
+ between?: [number, number];
617
+ };
970
618
  /**
971
- * This map lists every event that the engine emits, with the payload of each
972
- * one.
619
+ * The engine tests a text field against this filter for equality, for a text
620
+ * range, or with the set, prefix, and pattern tests.
973
621
  *
974
- * {@link Narsil.on} registers a listener under a key from this map, so that the
975
- * engine can pass the matching payload to that listener. Most of these events
976
- * report work that the engine does in the background, away from the call that
977
- * started it, so a failure that such an event reports never rejects a promise
978
- * that you are holding.
622
+ * On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
623
+ * element of the list on its own. A document passes `eq`, `in`, `startsWith`,
624
+ * `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
625
+ * test. However, a document passes `ne` or `nin` only when every element
626
+ * differs from the values.
627
+ *
628
+ * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
629
+ * to a single `string` or `verbatim` field whose type includes `sortable`. It
630
+ * throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
631
+ * orders the values as a sort on the field does, so it compares their case
632
+ * folds first and compares their raw code points only where the folds are
633
+ * equal.
634
+ *
635
+ * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
636
+ * `string[]` field whose type includes `pattern`. On a pattern field, the
637
+ * engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
638
+ * `contains`, `wildcard`, and `regex` from the field's pattern index, and
639
+ * `caseFold` applies to each of those tests. The engine compares the code
640
+ * points of each value as they are stored, with no Unicode normalisation.
641
+ *
642
+ * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
643
+ * `startsWith`, and `endsWith` from the field's index of values. A `string` or
644
+ * `string[]` field whose type leaves out `pattern` keeps no index of whole
645
+ * values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
646
+ * and for `matchesAny` and `containsAll`, on such a field.
647
+ *
648
+ * The engine also throws `SEARCH_INVALID_FILTER` in these cases:
649
+ *
650
+ * - The filter sets `contains`, `wildcard`, `regex`, or `caseFold` on a field
651
+ * that is not a pattern field.
652
+ * - The text or the pattern of a test on a pattern field holds more than 1,024
653
+ * code points.
654
+ * - A literal test under `caseFold` has a text whose case fold holds more than
655
+ * 2,048 code points.
656
+ * - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
979
657
  *
980
658
  * @public
981
659
  */
982
- type NarsilEventMap = {
660
+ type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
661
+ /** This matches a value that comes after the text in sort order. */
662
+ gt?: string;
663
+ /** This matches a value that comes before the text in sort order. */
664
+ lt?: string;
665
+ /** This matches a value equal to the text or after it in sort order. */
666
+ gte?: string;
667
+ /** This matches a value equal to the text or before it in sort order. */
668
+ lte?: string;
669
+ /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
670
+ between?: [string, string];
671
+ /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
672
+ in?: string[];
673
+ /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
674
+ nin?: string[];
675
+ /** This matches a field starting with the text. */
676
+ startsWith?: string;
677
+ /** This matches a field ending with the text. */
678
+ endsWith?: string;
679
+ /** This matches a pattern field whose value holds the text anywhere in it. */
680
+ contains?: string;
983
681
  /**
984
- * The engine emits this event after a call changes what a read returns from
985
- * an index. The calls are the inserts, updates, and removals, singly or in a
986
- * batch, together with `clear`, `restore`, `rebalance`, `rebuildAnalysis`,
987
- * `compactVectors`, `optimizeVectors`, `createIndex`, and `dropIndex`. The
988
- * engine emits the event after a call that throws as well, because a call can
989
- * change the index before it throws. It also emits the event after it reloads
990
- * an index, once a shared invalidation adapter reports that another instance
991
- * saved that index. The engine emits one event per batch, however many
992
- * documents the batch holds.
682
+ * This matches a pattern field when the whole value matches the wildcard
683
+ * pattern. For example, `INV-*-2024` matches `INV-0042-2024`.
993
684
  *
994
- * The engine emits the event once a query can see the change, which means
995
- * after every worker copy applies the change and after any rebalance in
996
- * progress replays it. A query that a listener sends from its handler
997
- * therefore returns results that include the change. The engine waits for the
998
- * change to become visible only while a listener is registered for the event.
685
+ * In the pattern, `*` matches any sequence of code points, including an
686
+ * empty one, and `?` matches exactly one code point. Write `\` before a code
687
+ * point to match that code point itself, so `\*` matches an asterisk.
688
+ *
689
+ * The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
690
+ * `\` with no code point after it. It throws the same error for a pattern
691
+ * with more than 2,048 positions. Each `*`, each `?`, and each other code
692
+ * point counts as one position, except that under `caseFold` a code point
693
+ * counts once for each code point of its case fold.
999
694
  */
1000
- write: {
1001
- /** This is the name of the index that changed. */
1002
- indexName: string;
1003
- };
695
+ wildcard?: string;
1004
696
  /**
1005
- * A worker thread exited unexpectedly. The pool removes the thread and fails
1006
- * the requests that the thread was serving with `WORKER_CRASHED`. The engine
1007
- * then sends each of those queries again on the main thread, so the caller
1008
- * receives a result with no error. The remaining workers keep serving
1009
- * queries, because each of them holds a full worker copy of every promoted
1010
- * index.
697
+ * This matches a pattern field when some part of the value matches the
698
+ * regular expression. `^` and `$` match only at the start and at the end of
699
+ * the whole value.
1011
700
  *
1012
- * After a delay, the engine spawns a replacement and loads every copy onto
1013
- * it before it sends queries to the replacement. Once no worker is left, the
1014
- * main thread serves every query, because it holds every document. The first
1015
- * request after the delay then starts a new pool. The delay starts at one
1016
- * second and doubles up to a minute while replacements keep failing.
701
+ * The engine accepts literal code points, `.`, `\d`, `\w`, and `\s`, sets
702
+ * such as `[a-z]` and `[^0-9]`, groups, and `|`. It also accepts the repeats
703
+ * `*`, `+`, `?`, `{n}`, `{n,}`, and `{n,m}`, the anchors `^` and `$`, the
704
+ * word edge `\b`, and number ranges such as `<1-65535>`. A number range
705
+ * matches the digits of any whole number from its low end to its high end.
706
+ * Write `\` before an ASCII punctuation mark to match the mark itself. The
707
+ * `.` matches any code point, including a line break.
708
+ *
709
+ * The matcher never backtracks, so it checks a value in at most as many
710
+ * steps as the value's code points multiplied by the pattern's positions.
711
+ *
712
+ * The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
713
+ * syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
714
+ * flag. It throws the same error when the groups of a pattern nest more than
715
+ * 32 deep, when a count is above 2,048, and when a pattern holds more than
716
+ * 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
717
+ * option to false, the server refuses every `regex` test.
1017
718
  */
1018
- workerCrash: {
1019
- /** This is the id of the worker that exited. */
1020
- workerId: number;
1021
- /** These are the indexes that the worker held. */
1022
- indexNames: string[];
1023
- /** This is the error that ended the worker. */
1024
- error: Error;
1025
- };
1026
- /** An index gained worker copies, either because it reached the copy
1027
- * threshold or because a request loaded its copies again after an idle
1028
- * spell. */
1029
- workerPromote: {
1030
- /** This is the number of workers in the pool. */
1031
- workerCount: number;
1032
- /** This is the reason that the index gained its copies, such as the copy
1033
- * threshold that it reached. */
1034
- reason: string;
1035
- };
1036
- /** An index could not gain worker copies, so the main thread keeps serving
1037
- * its queries. */
1038
- workerPromoteFailure: {
1039
- /** This is the reason that the engine tried to load the copies. */
1040
- reason: string;
1041
- /** This is the error that stopped the load. */
1042
- error: Error;
1043
- /** This is true when the engine will try again at a later threshold. */
1044
- retryable: boolean;
1045
- };
1046
- /** An index finished spreading its documents across a new number of
1047
- * partitions. */
1048
- partitionRebalance: {
1049
- /** This is the name of the index that the engine rebalanced. */
1050
- indexName: string;
1051
- /** This is the number of partitions before the rebalance. */
1052
- oldCount: number;
1053
- /** This is the number of partitions after the rebalance. */
1054
- newCount: number;
1055
- };
719
+ regex?: string;
1056
720
  /**
1057
- * An index passed its watermark, so its partitions are close to their
1058
- * capacity. On a cluster node, the engine reports the document count and the
1059
- * capacity of the one partition that `partitionId` identifies, which this
1060
- * node leads.
721
+ * When this is true, the engine compares the case fold of each value of a
722
+ * pattern field with the case fold of the text, so a test for `error`
723
+ * matches `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`,
724
+ * `endsWith`, `contains`, `wildcard`, and `regex`.
725
+ *
726
+ * Under `caseFold`, a set that does not open with `^` can also match a
727
+ * sequence of code points. When a member that the set holds on its own folds
728
+ * to several code points, the set matches that whole fold, so `[ß]` matches
729
+ * `ss`.
1061
730
  */
1062
- partitionWatermark: {
1063
- /** This is the name of the index that crossed the mark. */
1064
- indexName: string;
1065
- /** This is the number of documents in the index, or in the partition on a
1066
- * cluster node. */
1067
- documentCount: number;
1068
- /** This is the number of documents that the current partitions of the
1069
- * index can hold, or that the partition can hold on a cluster node. */
1070
- capacity: number;
1071
- /** This is the number of partitions in the index. */
1072
- partitionCount: number;
1073
- /** On a cluster node, this is the partition that crossed the mark, while
1074
- * outside a cluster the field is absent. */
1075
- partitionId?: number;
1076
- };
731
+ caseFold?: boolean;
1077
732
  /**
1078
- * The process uses nine tenths of its heap, as measured during a write or a
1079
- * load, so the next large index can end the process with an out-of-memory
1080
- * error.
733
+ * This lets the `eq` test of a pattern field match a value within this many
734
+ * edits of the text, so a test for `INV-2O24` with a tolerance of 1 matches
735
+ * `INV-2024`. An edit inserts, deletes, or replaces one code point, so a
736
+ * swap of two neighbouring code points counts as two edits. With `caseFold`,
737
+ * the engine counts the edits between the case folds of the value and the
738
+ * text. The tolerance applies to `eq` alone, so the other tests of the field
739
+ * still compare exactly.
1081
740
  *
1082
- * Where `--max-old-space-size` or `--max-old-space-size-percentage` sets a
1083
- * limit, on the command line or in `NODE_OPTIONS`, the engine measures the
1084
- * used bytes against that limit, which `heapLimit` then reports. Where
1085
- * neither flag sets a limit, the engine measures the share of the heap that
1086
- * V8 reports as no longer available. V8 reports a limit about 192 MB above
1087
- * the true ceiling, so a process on a default heap below about 2 GB can end before
1088
- * this event fires.
741
+ * The engine takes its candidates from the pattern index, so the case fold
742
+ * of the text has to hold enough distinct runs of three code points. For a
743
+ * tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
744
+ * the number of code points in the longest case fold among the text's code
745
+ * points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
746
+ * therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
747
+ * `'auto'`, the engine uses 2 where the text holds enough runs for 2,
748
+ * otherwise 1 where it holds enough for 1, and otherwise 0.
1089
749
  *
1090
- * The engine emits the event once per crossing, then arms it again once the
1091
- * free share of the heap recovers to two tenths. Raise the limit with
1092
- * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
1093
- * idle index; see {@link ProcessMemoryReport.heapLimit}.
750
+ * The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
751
+ * text with too few runs, stating how many runs that tolerance needs. It
752
+ * throws the same error for any other tolerance, for a tolerance on a field
753
+ * that is not a pattern field, and for a tolerance in a filter without an
754
+ * `eq` test. Towards the pattern work cap, it counts one unit for each cell
755
+ * that it fills in the table of edit distances between the text and a
756
+ * value.
1094
757
  */
1095
- heapPressure: {
1096
- /** This is the index that a write or a load was touching when the heap
1097
- * reached that point. */
1098
- indexName: string;
1099
- /** This is the heap that the process uses, in bytes. */
1100
- heapUsed: number;
1101
- /** This is the size in bytes that the heap can grow to. */
1102
- heapLimit: number;
1103
- /** This is the estimate of the bytes that the index holds. */
1104
- estimatedMemoryBytes: number;
1105
- };
1106
- /** The engine started, completed, or failed a rebuild that brings the terms
1107
- * of an index up to the current analysis of its language module. */
1108
- analysisRebuild: {
1109
- /** This is the name of the index under rebuild. */
1110
- indexName: string;
1111
- /** This is the stage that the rebuild has reached. */
1112
- status: 'started' | 'completed' | 'failed';
1113
- /** This is the number of partitions that the rebuild has covered so far. */
1114
- partitionsRebuilt: number;
1115
- /** This is the number of partitions that the rebuild covers in total. */
1116
- partitionCount: number;
1117
- /** This is the error that stopped the rebuild, which only a `failed`
1118
- * status includes. */
1119
- error?: Error;
1120
- };
1121
- /** The engine started, completed, or failed the rewrite of an index that you
1122
- * saved with an earlier release. The engine rewrites the index as it
1123
- * recovers it, before it serves the index's first request. Because the
1124
- * engine writes the new manifest last, the earlier files stay intact through
1125
- * a failed rewrite. The engine then starts the rewrite again the next time
1126
- * it recovers the index. Without index lifecycle settings, the engine
1127
- * recovers every index before {@link createNarsil} returns, so pass the
1128
- * listener in the `events` setting of {@link createNarsil}. */
1129
- layoutUpgrade: {
1130
- /** This is the name of the index under rewrite. */
1131
- indexName: string;
1132
- /** This is the stage that the rewrite has reached. */
1133
- status: 'started' | 'completed' | 'failed';
1134
- /** This is `manifest` where the earlier index is a segment manifest with
1135
- * its files, and `bundle` where it is a single snapshot bundle. */
1136
- layout: 'manifest' | 'bundle';
1137
- /** This is the error that stopped the rewrite, which only a `failed`
1138
- * status includes. */
1139
- error?: Error;
1140
- };
1141
- /** A write to the write-ahead log or a checkpoint failed, so the writes since
1142
- * the last checkpoint are at risk. */
1143
- durabilityError: {
1144
- /** This is the error that the durability layer threw. */
1145
- error: Error;
758
+ tolerance?: 0 | 1 | 2 | 'auto';
759
+ };
760
+ /**
761
+ * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
762
+ * `enum[]`, `verbatim[]`, or `string[]` field.
763
+ *
764
+ * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
765
+ * field, for a value whose type differs from the type of the list's elements,
766
+ * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
767
+ * out `pattern`.
768
+ *
769
+ * @public
770
+ */
771
+ type ArrayFilter = {
772
+ /** This matches a list holding every one of the values, at most 65,536 of them, so an empty set of values matches every list. */
773
+ containsAll?: (string | number | boolean)[];
774
+ /** This matches a list holding at least one of the values, at most 65,536 of them. */
775
+ matchesAny?: (string | number | boolean)[];
776
+ /** This compares the number of elements in the list. */
777
+ size?: ComparisonFilter;
778
+ };
779
+ /**
780
+ * Tests whether a field carries a value at all, without looking at what it
781
+ * holds.
782
+ *
783
+ * @public
784
+ */
785
+ type PresenceFilter = {
786
+ /** This matches a document where the field holds a value other than null. */
787
+ exists?: boolean;
788
+ /** This matches a document where the field is absent or null. */
789
+ notExists?: boolean;
790
+ /** This matches a document where the field is absent, null, an empty string, or an empty list. */
791
+ isEmpty?: boolean;
792
+ /** This matches a document where the field holds a value other than an empty string or an empty list. */
793
+ isNotEmpty?: boolean;
794
+ };
795
+ /**
796
+ * Matches a `geopoint` field against a circle drawn on the earth.
797
+ *
798
+ * @public
799
+ */
800
+ type GeoRadiusFilter = {
801
+ /** The engine tests the field against this circle. */
802
+ radius: {
803
+ /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
804
+ lat: number;
805
+ /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
806
+ lon: number;
807
+ /** The circle has this radius, measured in `unit`. */
808
+ distance: number;
809
+ /**
810
+ * The engine measures `distance` in kilometres under `'km'`, in miles
811
+ * under `'mi'`, and in metres under `'m'`. For any other unit, it throws
812
+ * `SEARCH_INVALID_FILTER`.
813
+ */
814
+ unit: 'km' | 'mi' | 'm';
815
+ /** The engine matches the points inside the circle while this is true, which is the default, and the points outside it while this is false. */
816
+ inside?: boolean;
817
+ /**
818
+ * The engine measures each distance with the Haversine formula on a sphere
819
+ * by default, and with Vincenty's formula on the WGS-84 ellipsoid while
820
+ * this is true. Vincenty's formula iterates, so the engine takes longer
821
+ * to compute each distance. The two formulas differ by less than 0.3% under about
822
+ * 100 km, while across a continent they can differ by up to 0.5%.
823
+ */
824
+ highPrecision?: boolean;
1146
825
  };
1147
- /** The invalidation channel failed, so this instance can serve partitions
1148
- * that another instance has since changed. */
1149
- invalidationError: {
1150
- /** This is the error that the adapter threw. */
1151
- error: Error;
826
+ };
827
+ /**
828
+ * Matches a `geopoint` field against a polygon drawn on the earth.
829
+ *
830
+ * @public
831
+ */
832
+ type GeoPolygonFilter = {
833
+ /** The engine tests the field against this polygon. */
834
+ polygon: {
835
+ /**
836
+ * The engine closes the ring through these corners in the order that you
837
+ * list them, so you can leave the first point off the end. It throws
838
+ * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
839
+ * encloses no area, and for a corner whose latitude is outside -90 to 90
840
+ * or whose longitude is outside -180 to 180. It also throws that error for
841
+ * a ring of more than 65,536 corners. List the corners counter-clockwise
842
+ * around the area, as in an exterior ring of GeoJSON. Where the corners
843
+ * span 180 degrees of longitude or more, the engine matches the area on
844
+ * the left of that path, so a ring listed that way can cross the
845
+ * antimeridian or span more than half the globe.
846
+ */
847
+ points: Array<{
848
+ lat: number;
849
+ lon: number;
850
+ }>;
851
+ /** The engine matches the points inside the polygon while this is true, which is the default, and the points outside it while this is false. */
852
+ inside?: boolean;
1152
853
  };
1153
854
  };
1154
855
  /**
1155
- * This map holds a listener for any event of {@link NarsilEventMap}, so that
1156
- * the engine can register each listener before it starts.
856
+ * Either shape a `geopoint` field is matched against.
1157
857
  *
1158
858
  * @public
1159
859
  */
1160
- type NarsilEventHandlers = {
1161
- [K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
860
+ type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
861
+ /**
862
+ * The filter one field accepts. Which of these forms applies follows from the
863
+ * field's declared type.
864
+ *
865
+ * @public
866
+ */
867
+ type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
868
+ /**
869
+ * The filter that a query runs, built from per-field tests and the boolean
870
+ * operators that combine them.
871
+ *
872
+ * The engine answers every test from an index that it keeps for the field. It
873
+ * applies the filter before scoring, so a narrow filter makes a search
874
+ * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
875
+ * tests, counted across every field and nested expression. Past either limit,
876
+ * the engine throws `SEARCH_INVALID_FILTER`, while it throws
877
+ * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
878
+ *
879
+ * @public
880
+ */
881
+ type FilterExpression = {
882
+ /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
883
+ fields?: Record<string, FieldFilter>;
884
+ /** Every nested expression has to match. */
885
+ and?: FilterExpression[];
886
+ /** At least one nested expression has to match. */
887
+ or?: FilterExpression[];
888
+ /** The nested expression has to fail. */
889
+ not?: FilterExpression;
1162
890
  };
1163
891
 
1164
892
  /**
1165
- * What {@link Narsil.query} returns: the ranked hits and everything the query
1166
- * asked for alongside them.
893
+ * Everything {@link Narsil.suggest} accepts.
1167
894
  *
1168
- * @typeParam T - Shape of the stored documents, which flows through to each
1169
- * hit's `document`.
895
+ * @public
896
+ */
897
+ interface SuggestParams {
898
+ /** The returned terms complete this text. */
899
+ prefix: string;
900
+ /** The lookup returns this many completions, most widely used first, and 10 by default. */
901
+ limit?: number;
902
+ }
903
+ /**
904
+ * Everything {@link Narsil.listDocuments} accepts.
905
+ *
906
+ * {@link Narsil.listDocuments} reads the stored documents without ranking them,
907
+ * which is how you page through a whole index. Leave `cursor` out to start at
908
+ * the first document, then pass back the cursor each result carries until it
909
+ * comes back null.
910
+ *
911
+ * A cursor belongs to the sort it was made under, so pass the same `sort` back
912
+ * with it. Changing `sort` invalidates the cursor, and the engine then throws
913
+ * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
1170
914
  *
1171
915
  * @public
1172
916
  */
1173
- interface QueryResult<T = AnyDocument> {
1174
- /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
1175
- hits: Array<Hit<T>>;
917
+ interface ListParams {
1176
918
  /**
1177
- * This many documents match in total, before the engine applies `limit`
1178
- * and `offset`. For a keyword search the engine counts every match. For a
1179
- * vector search it counts every vector that passes the query's filter and
1180
- * its `similarity` floor, which is every vector in the field where the query
1181
- * sets neither of them. The engine also counts each pinned document that
1182
- * the query does not match, since it places that document among the hits.
919
+ * This cursor comes from a previous result, and continues where it stopped.
920
+ * The engine ties a cursor to the sort that produced it, and it throws
921
+ * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
1183
922
  */
1184
- count: number;
923
+ cursor?: string;
924
+ /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
925
+ limit?: number;
926
+ /** This narrows the listing to the documents the filter accepts. */
927
+ filters?: FilterExpression;
1185
928
  /**
1186
- * `count` holds the exact number of matches where this is true, and a
1187
- * number at or below the true total where it is false. Where a query sets a
1188
- * `similarity` floor on a vector field that holds a graph, the engine
1189
- * counts only the vectors that it fetches, because it compares the query
1190
- * with only a fraction of that field's vectors. For a hybrid query the
1191
- * engine fuses two rankings, so the count is exact only where each of those
1192
- * rankings contains every matching document. Where you pin a document from
1193
- * outside the hits that the engine fetches, the engine reports true only
1194
- * where it holds every match of the query, because only then can it test
1195
- * whether the query matches that document.
929
+ * This orders the listing by field value rather than by document id, and the
930
+ * engine applies the fields in the order they are listed. Pass an object
931
+ * keyed by field, or a list of fields in the order they apply. It breaks a
932
+ * tie on document id, and it sorts by at most eight fields. The engine uses
933
+ * document-id order when you leave this out.
934
+ *
935
+ * The engine reads every document the listing covers to build a sorted page,
936
+ * so a sorted listing costs more than the default order on a large index.
1196
937
  */
1197
- countExact: boolean;
1198
- /** The engine spent this many milliseconds on the search. */
1199
- elapsed: number;
1200
- /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
1201
- cursor?: string;
1202
- /** These facet counts are keyed by the field each facet was asked for. */
1203
- facets?: Record<string, FacetResult>;
1204
- /** These groups arrive when the query asked for grouping. */
1205
- groups?: GroupResult[];
1206
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1207
- analysisStale?: boolean;
1208
- /** The search read this much of the index, which is how you spot a degraded answer. */
1209
- coverage: QueryCoverage;
938
+ sort?: SortSpec;
939
+ /** This chooses how much of each stored document comes back, and the whole document by default. */
940
+ document?: DocumentProjection;
1210
941
  }
942
+
1211
943
  /**
1212
- * How much of an index one search read, which is what you check before you
1213
- * trust a count or a ranking.
1214
- *
1215
- * An embedded engine reads every partition it holds, so `queriedPartitions`
1216
- * matches `totalPartitions` there and the other two stay zero. A search across
1217
- * a cluster may find a node slow or unreachable, which it counts here while
1218
- * still returning the hits the other nodes gave it.
944
+ * Which engine answers a query: keyword matching, vector similarity, or both
945
+ * merged into one ranking.
1219
946
  *
1220
947
  * @public
1221
948
  */
1222
- interface QueryCoverage {
1223
- /** The search should have read this many partitions. */
1224
- totalPartitions: number;
1225
- /** The search read this many of them. */
1226
- queriedPartitions: number;
1227
- /** The search counts a partition here when the node holding it took longer than the query allowed. */
1228
- timedOutPartitions: number;
1229
- /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
1230
- failedPartitions: number;
1231
- }
949
+ type SearchMode = 'fulltext' | 'vector' | 'hybrid';
1232
950
  /**
1233
- * One matching document, with the score that ranked it.
1234
- *
1235
- * @typeParam T - Shape of the stored document.
951
+ * How many of a query's terms a document has to carry. `all` demands every
952
+ * term, `any` accepts one, and a number demands that many.
1236
953
  *
1237
954
  * @public
1238
955
  */
1239
- interface Hit<T = AnyDocument> {
1240
- /** The document is stored under this id. */
1241
- id: string;
1242
- /**
1243
- * This score ranked the hit. Scores compare within one result set, never
1244
- * across searches. A sorted query ranks by sort values instead and carries
1245
- * no score unless it sets `includeScores`.
1246
- */
1247
- score?: number;
1248
- /** This is the stored document. */
1249
- document: T;
1250
- /** These are the parts the score was built from, which arrive when the query asked for them. */
1251
- scoreComponents?: ScoreComponents;
1252
- /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
1253
- highlights?: Record<string, HighlightMatch>;
1254
- }
956
+ type TermMatchPolicy = 'all' | 'any' | number;
1255
957
  /**
1256
- * The numbers BM25 combined into one hit's score, which is what you read when
1257
- * a ranking surprises you.
958
+ * One field of a sort, and the direction that field orders by.
1258
959
  *
1259
960
  * @public
1260
961
  */
1261
- interface ScoreComponents {
962
+ interface SortField {
963
+ /** The field the engine reads, which may name a nested field with dots. */
964
+ field: string;
965
+ /** Ascending or descending order for this field. */
966
+ direction: 'asc' | 'desc';
1262
967
  /**
1263
- * Each query term appears in one field of this document this many times,
1264
- * under a key of `field:term`. A term that appears in two fields therefore
1265
- * has two entries here, while the keys of {@link ScoreComponents.idf} hold
1266
- * the bare term.
968
+ * Where a document's field holds a list, the engine sorts that document by
969
+ * one value from the list: the smallest under `'min'`, the largest under
970
+ * `'max'`, and the mean or the median of the list's numbers under `'avg'`
971
+ * or `'median'`. Where you leave this out, the engine uses `'min'` for an
972
+ * ascending sort and `'max'` for a descending one. It sorts by a field that
973
+ * holds a single value as that value stands, under every mode. It throws
974
+ * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
975
+ * schema declares as anything other than `number` or `number[]`.
1267
976
  */
1268
- termFrequencies: Record<string, number>;
1269
- /** Each field the query searched holds this many tokens, keyed by field. */
1270
- fieldLengths: Record<string, number>;
1271
- /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
1272
- idf: Record<string, number>;
977
+ mode?: 'min' | 'max' | 'avg' | 'median';
1273
978
  }
1274
979
  /**
1275
- * A highlighted field, ready to render.
980
+ * A sort, either as an object keyed by field or as a list of fields in the
981
+ * order they apply.
982
+ *
983
+ * Both forms order by the first field, break a tie on the second, and carry on
984
+ * that way. Prefer the list where the order of the fields matters, because
985
+ * JavaScript moves an all-digit key such as `2024` to the front of an object
986
+ * and the list keeps the order you wrote.
1276
987
  *
1277
988
  * @public
1278
989
  */
1279
- interface HighlightMatch {
1280
- /** This is the field's text around the match, wrapped in the query's tags. */
1281
- snippet: string;
1282
- /**
1283
- * Each range gives the start and the end of one match in the original field,
1284
- * so you can render the highlight yourself. Where the snippet covers part of
1285
- * the field alone, the engine lists only the matches that the snippet
1286
- * displays. Every offset is a character count from the start of the original
1287
- * field, whatever the snippet contains.
1288
- */
1289
- positions: Array<{
1290
- start: number;
1291
- end: number;
1292
- }>;
1293
- }
990
+ type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
1294
991
  /**
1295
- * Counts for one faceted field.
992
+ * Everything {@link Narsil.query} accepts.
993
+ *
994
+ * Set `term` for keyword search, `vector` for similarity search, and `mode`
995
+ * when you want both. The engine matches nothing for a query carrying neither
996
+ * of them, so page through an index with {@link Narsil.listDocuments}
997
+ * instead.
1296
998
  *
1297
999
  * @public
1298
1000
  */
1299
- interface FacetResult {
1300
- /** This many documents match per value, keyed by value. */
1301
- values: Record<string, number>;
1302
- /** This is the number of entries in `values`, which is at most the facet's `limit`. */
1303
- count: number;
1001
+ interface QueryParams {
1002
+ /** The engine analyses this text with the index's language module and searches for the terms that result. */
1003
+ term?: string;
1004
+ /** The engine searches the term in these fields, and in every text field in the schema by default. */
1005
+ fields?: string[];
1006
+ /**
1007
+ * The engine scores only the documents that pass this filter. It throws
1008
+ * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
1009
+ * operator on a field of another type, such as `startsWith` on a number
1010
+ * field.
1011
+ */
1012
+ filters?: FilterExpression;
1013
+ /**
1014
+ * The engine multiplies the score from each named field by its weight. It
1015
+ * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
1016
+ * the schema declares, and `CONFIG_INVALID` for a weight that is not a
1017
+ * finite number.
1018
+ */
1019
+ boost?: Record<string, number>;
1020
+ /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
1021
+ scoring?: ScoringMode;
1022
+ /**
1023
+ * The engine drops any hit scoring below this value. It ranks with BM25,
1024
+ * which has no fixed upper bound, so a floor that suits one index and one
1025
+ * query can reject every hit in another.
1026
+ */
1027
+ minScore?: number;
1028
+ /**
1029
+ * The engine keeps a document only where the document matches this many
1030
+ * query terms, under the same `tolerance` and `prefixLength` that the search
1031
+ * uses. One term is enough by default.
1032
+ */
1033
+ termMatch?: TermMatchPolicy;
1034
+ /**
1035
+ * The engine matches an indexed term within this edit distance of a query
1036
+ * term, so it finds a document for a query with a typo. It counts each
1037
+ * Unicode code point as one character. Set an integer from 0 to 10.
1038
+ */
1039
+ tolerance?: number;
1040
+ /**
1041
+ * The engine applies `tolerance` only to the indexed terms that share this
1042
+ * many leading characters with the query term, or to the terms that start
1043
+ * with the whole query term when the query term is shorter. Set an integer
1044
+ * from 0 to 1,024; the default is 2.
1045
+ */
1046
+ prefixLength?: number;
1047
+ /**
1048
+ * With this set, the engine treats the last query term as an unfinished
1049
+ * word, so `secur` matches `security`. The engine matches that last term by
1050
+ * its stem or by completing it, while `tolerance` applies only to the earlier
1051
+ * terms, which have to match whole. The engine scores completions against a
1052
+ * shared document frequency. It also ranks them below whole-word matches.
1053
+ * The engine ignores this setting where `exact` is true, and the setting is
1054
+ * false by default.
1055
+ */
1056
+ prefix?: boolean;
1057
+ /**
1058
+ * With this set, the engine also matches each query word of three or more
1059
+ * characters inside the longer words of every field whose type includes
1060
+ * `partial`, so a search for `proof` matches a document with `waterproof`
1061
+ * in such a field. The engine counts each Unicode code point as one
1062
+ * character. It looks for the query word, before stemming, inside each word
1063
+ * exactly as that word appears in a document.
1064
+ *
1065
+ * The engine adds at most 50 such words to a query, which it divides as
1066
+ * evenly as it can among the query words. Within the share of each query
1067
+ * word, it adds first the words that the most documents contain. It scores
1068
+ * a match inside a longer word in proportion to the part of that word that
1069
+ * the query word makes up, so it scores such a match below a whole-word
1070
+ * match at the same frequency in a field of the same length. With
1071
+ * `highlight`, it tags each whole word that contains a query word in a
1072
+ * searched `partial` field.
1073
+ *
1074
+ * The engine applies no `tolerance` to these matches. It ignores this
1075
+ * setting where `exact` is true or where the searched fields include no
1076
+ * `partial` field. Where the setting is absent, the engine treats it as
1077
+ * false, while it throws `CONFIG_INVALID` for any value other than `true`
1078
+ * or `false`.
1079
+ */
1080
+ partialWords?: boolean;
1081
+ /**
1082
+ * With this set, the engine matches each query term only against an equal
1083
+ * indexed term, so it turns off fuzzy matching, prefix completion, and
1084
+ * partial-word matching. The engine still stems the query, because the
1085
+ * index stores stemmed terms, so a search for `running` matches a document
1086
+ * that contains `runs` through the stem that both words share.
1087
+ */
1088
+ exact?: boolean;
1089
+ /**
1090
+ * The engine counts the values of these fields across the matching
1091
+ * documents, and each entry sets how it cuts and sorts that field's counts.
1092
+ * For a field outside the schema, it counts the values that the documents
1093
+ * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
1094
+ * field.
1095
+ */
1096
+ facets?: FacetConfig;
1097
+ /**
1098
+ * The engine sorts the hits by the values of these fields, in place of the
1099
+ * relevance ranking. Pass an object keyed by field, or a list of fields in
1100
+ * the order that the engine compares them. The engine sorts by a `number`,
1101
+ * `boolean`, or `enum` field, by a text field whose type includes
1102
+ * `sortable`, or by a list of any of these, which it reduces to one value by
1103
+ * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
1104
+ * `geopoint` or a vector field, because neither type has an order. It throws
1105
+ * the same code for a sort on any other text field, since the engine keeps
1106
+ * up to the first 512 code points of every document's value in memory to
1107
+ * sort by a text field. The engine orders hybrid results by fusion, so it
1108
+ * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
1109
+ * that code for a direction other than `asc` and `desc`.
1110
+ */
1111
+ sort?: SortSpec;
1112
+ /** These settings collapse the hits into groups by field value. */
1113
+ group?: GroupConfig;
1114
+ /**
1115
+ * The query returns this many hits, and 10 by default. Pass 0 to read the
1116
+ * match count with no hits. The engine reads a value below 0 as 0. It falls
1117
+ * back to the default for `NaN` and for an infinite value, so a page size
1118
+ * that you compute from user input never fails the query.
1119
+ */
1120
+ limit?: number;
1121
+ /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
1122
+ offset?: number;
1123
+ /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
1124
+ searchAfter?: string;
1125
+ /** These settings name the fields that come back with highlighted snippets. */
1126
+ highlight?: HighlightConfig;
1127
+ /** These documents take fixed positions, ahead of the ranking. */
1128
+ pinned?: Array<{
1129
+ docId: string;
1130
+ position: number;
1131
+ }>;
1132
+ /** This picks which engine answers the query. Keyword search runs by default. */
1133
+ mode?: SearchMode;
1134
+ /** These vector-search inputs are required in `vector` and `hybrid` mode. */
1135
+ vector?: VectorQueryConfig;
1136
+ /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
1137
+ hybrid?: HybridConfig;
1304
1138
  /**
1305
- * Every count in `values` is at most this far below its true count. A value
1306
- * that the engine leaves out of `values` because of `limit` has a true
1307
- * count of at most this figure too. Where the engine counts a field on one
1308
- * thread, it counts every value exactly, so this figure is the largest
1309
- * count that it leaves out. Where it splits the count across worker copies
1310
- * or cluster nodes, each of them returns only its own top values, so the
1311
- * merged count of a value that is common overall but rare on one of them
1312
- * can lack the matches on that one. A bound of 0 means that `values` holds
1313
- * every matching value, each with its exact count.
1139
+ * Setting this returns relevance scores on a sorted query. A query that
1140
+ * names a sort ranks by sort values alone and computes no scores, so its
1141
+ * hits carry none until this restores them. A query without a sort ignores
1142
+ * this and always carries scores.
1314
1143
  */
1315
- errorBound: number;
1144
+ includeScores?: boolean;
1145
+ /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
1146
+ includeScoreComponents?: boolean;
1147
+ /** This chooses how much of each stored document comes back, and the whole document by default. */
1148
+ document?: DocumentProjection;
1316
1149
  }
1317
1150
  /**
1318
- * One group of hits, produced by a query that grouped its results.
1151
+ * How much of a stored document each hit carries back.
1319
1152
  *
1320
- * @public
1321
- */
1322
- interface GroupResult {
1323
- /** Each grouping field holds this value for the group, keyed by field. */
1324
- values: Record<string, unknown>;
1325
- /** These hits fall in the group, cut to the query's `maxPerGroup`. */
1326
- hits: Array<Hit>;
1327
- /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
1328
- reduced?: unknown;
1329
- /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
1330
- reducerError?: string;
1331
- }
1332
- /**
1333
- * What {@link Narsil.preflight} returns: how many documents a query matches,
1334
- * without building or ranking a single hit.
1153
+ * Pass `false` when the ids and scores are all you need, and every hit's
1154
+ * `document` is then an empty object. Pass `include` to keep named fields
1155
+ * alone, or `exclude` to drop named fields and keep the rest; naming both
1156
+ * keeps the included fields and then drops the excluded ones from those. Use
1157
+ * dots to name a nested field, so `author.name` addresses the `name` inside
1158
+ * `author`, and a name that matches no field changes nothing.
1335
1159
  *
1336
- * @public
1337
- */
1338
- interface PreflightResult {
1339
- /** The query matches this many documents. */
1340
- count: number;
1341
- /** `count` holds the exact number of matches where this is true, and a number at or below the true total where it is false, under the rule in {@link QueryResult.countExact}. */
1342
- countExact: boolean;
1343
- /** The count took this many milliseconds. */
1344
- elapsed: number;
1345
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1346
- analysisStale?: boolean;
1347
- }
1348
- /**
1349
- * What a batch write returns. One bad document never abandons the rest, so
1350
- * read both lists.
1160
+ * Drop a vector field on a similarity search, because the engine otherwise
1161
+ * reads every hit's vector back out of the index and writes it into the
1162
+ * response.
1351
1163
  *
1352
1164
  * @public
1353
1165
  */
1354
- interface BatchResult {
1355
- /** The engine wrote the documents under these ids. */
1356
- succeeded: string[];
1357
- /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
1358
- failed: Array<{
1359
- docId: string;
1360
- error: NarsilError;
1361
- }>;
1362
- }
1166
+ type DocumentProjection = boolean | {
1167
+ /** Names the fields to keep, so every field left out of this list is dropped. */
1168
+ include?: string[];
1169
+ /** Names the fields to drop, so every other field is kept. */
1170
+ exclude?: string[];
1171
+ };
1363
1172
  /**
1364
- * What {@link Narsil.importDocumentExport} returns. The engine continues past each
1365
- * refused line, so read the refusals to learn which documents it skipped.
1173
+ * Vector-search inputs passed under `QueryParams.vector`.
1174
+ *
1175
+ * Supply either a raw `value` array or a `text` string for auto-embedding;
1176
+ * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
1177
+ * by the outer query's `limit`, not by any field on this object.
1366
1178
  *
1367
1179
  * @public
1368
1180
  */
1369
- interface DocumentImportResult {
1370
- /** The engine wrote this many documents, counting each one that it replaced. */
1371
- imported: number;
1372
- /** The engine refused this many lines in total. */
1373
- refusedCount: number;
1374
- /** These are the 1,000 refusals with the lowest line numbers. Each entry contains the line number, where the header is line 1, along with the error code and a message. */
1375
- refused: Array<{
1376
- line: number;
1377
- code: NarsilErrorCode;
1378
- message: string;
1379
- }>;
1181
+ interface VectorQueryConfig {
1182
+ /**
1183
+ * Name of the schema field that holds the vector to compare against.
1184
+ * Must reference a field declared as `vector[N]` in the index schema.
1185
+ */
1186
+ field: string;
1187
+ /**
1188
+ * Raw query vector, given as a number array or a `Float32Array`. Length
1189
+ * must match the indexed field's dimension or the search rejects the
1190
+ * request with `VECTOR_DIMENSION_MISMATCH`.
1191
+ */
1192
+ value?: number[] | Float32Array;
1193
+ /**
1194
+ * Text to embed at query time using the index or instance embedding
1195
+ * adapter. Mutually exclusive with `value`; requires a configured adapter.
1196
+ */
1197
+ text?: string;
1198
+ /**
1199
+ * Score floor applied during ranking. Hits scoring below this value
1200
+ * are dropped before `limit` is enforced, so the returned hit count
1201
+ * can be smaller than `limit` even when more documents exist. The
1202
+ * floor is interpreted in score space for every metric; for
1203
+ * `euclidean`, distance is mapped to a similarity score of
1204
+ * `1 / (1 + distance)` first. Defaults to no floor.
1205
+ */
1206
+ similarity?: number;
1207
+ /**
1208
+ * Similarity metric used for ranking. Defaults to `cosine`. Choose
1209
+ * `dotProduct` for raw inner-product scoring on already-normalised
1210
+ * vectors and `euclidean` for distance-based ordering.
1211
+ */
1212
+ metric?: 'cosine' | 'dotProduct' | 'euclidean';
1213
+ /**
1214
+ * HNSW exploration factor for approximate search. Higher values raise
1215
+ * recall at the cost of latency. Ignored while the field is still
1216
+ * served by the brute-force backend. Defaults to the engine's built-in
1217
+ * value when omitted.
1218
+ */
1219
+ efSearch?: number;
1220
+ /**
1221
+ * How many times `limit` a quantized field re-scores against its
1222
+ * full-precision vectors before it returns the best `limit`. A value below
1223
+ * 1 or one that is not a finite number fails with `CONFIG_INVALID`. The
1224
+ * engine ignores this on a field whose quantization is `none`. When a query
1225
+ * omits it, the engine takes 3 for `osq1` and `osq2`, 2 for `osq8`, and 2
1226
+ * for `osq4` at 1,024 dimensions and above, but 5 for `osq4` below 1,024,
1227
+ * where a four-bit code ranks the true neighbours less reliably.
1228
+ */
1229
+ oversample?: number;
1380
1230
  }
1381
1231
  /**
1382
- * What {@link Narsil.getStats} returns about one index.
1232
+ * How a hybrid query merges its keyword ranking with its vector ranking.
1233
+ *
1234
+ * `rrf` combines the two by rank alone, which needs no tuning and handles
1235
+ * scores that live on different scales. `linear` blends the scores directly,
1236
+ * which gives you control once you know what each side's scores look like.
1383
1237
  *
1384
1238
  * @public
1385
1239
  */
1386
- interface IndexStats {
1387
- /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
1388
- documentCount: number;
1389
- /** The index is spread across this many partitions. */
1390
- partitionCount: number;
1391
- /**
1392
- * Formula-based estimate of the index's main-thread memory footprint, summed
1393
- * across every partition and vector index for this index. Computed from
1394
- * structural counters (document count, posting counts, field-index sizes),
1395
- * not measured. Per-object V8 overhead (hidden classes, map transitions,
1396
- * GC headers) is not captured here, so this number routinely undershoots
1397
- * the real heap by a meaningful factor. Use {@link Narsil.getMemoryStats}
1398
- * when sizing host memory.
1399
- */
1400
- estimatedMemoryBytes: number;
1401
- /** The index analyses text with this language module. */
1402
- language: string;
1403
- /** The index was created with this field layout. */
1404
- schema: SchemaDefinition;
1240
+ interface HybridConfig {
1241
+ /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
1242
+ strategy?: 'rrf' | 'linear';
1243
+ /** The engine uses this rank-fusion constant under `rrf` alone, where a larger value reduces the lead of the top ranks. Set a whole number of at least 1, or leave it out for 60. The engine throws `CONFIG_INVALID` for any other value. */
1244
+ k?: number;
1245
+ /** The engine uses this weight of the vector score, from 0 to 1, under `linear` alone, and 0.5 where you leave it out. It throws `CONFIG_INVALID` for a value outside that range. */
1246
+ alpha?: number;
1405
1247
  }
1406
1248
  /**
1407
- * A summary of one index, as {@link Narsil.listIndexes} reports it.
1249
+ * Fields a query counts values for, keyed by field name.
1408
1250
  *
1409
1251
  * @public
1410
1252
  */
1411
- interface IndexInfo {
1412
- /** The index was created under this name. */
1413
- name: string;
1414
- /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
1415
- documentCount: number;
1416
- /** The index is spread across this many partitions. */
1417
- partitionCount: number;
1418
- /** The index analyses text with this language module. */
1419
- language: string;
1420
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1421
- analysisStale?: boolean;
1422
- /** This is `open` in memory, `closed` after release, and `reopen-failed` after five recovery failures. */
1423
- state: 'open' | 'closed' | 'reopen-failed';
1424
- /** This counts successful loads since this engine started. */
1425
- reopenCount: number;
1253
+ interface FacetConfig {
1254
+ /** Each key names a field the query counts values for. */
1255
+ [field: string]: {
1256
+ /** The engine returns this many values for the field, in the order of `sort`. An engine returns every value where you leave this out, while a cluster returns 10, or every range of a field that sets `ranges`. */
1257
+ limit?: number;
1258
+ /** The engine orders the returned values by their count, putting the highest first under `'desc'`, which is the default, and the lowest first under `'asc'`. Under `'asc'`, each cluster node sends the count of up to 10,000 values of the field, so the lowest counts are exact wherever no node holds more values than that. */
1259
+ sort?: 'asc' | 'desc';
1260
+ /** The engine counts a numeric field's matches into these ranges, with one count for each range. A cluster search counts up to 1,000 ranges on a field and throws `CONFIG_INVALID` for more. */
1261
+ ranges?: Array<{
1262
+ from: number;
1263
+ to: number;
1264
+ }>;
1265
+ };
1426
1266
  }
1427
1267
  /**
1428
- * What {@link Narsil.getPartitionStats} reports for one partition, which is
1429
- * where you look when an index grows unevenly.
1268
+ * How a query collapses its hits into groups.
1430
1269
  *
1431
1270
  * @public
1432
1271
  */
1433
- interface PartitionStatsResult {
1434
- /** This identifies the partition within its index. */
1435
- partitionId: number;
1436
- /** The partition holds this many documents. */
1437
- documentCount: number;
1272
+ interface GroupConfig {
1273
+ /** The values of these fields define a group, and several fields group by their combination. */
1274
+ fields: string[];
1275
+ /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
1276
+ maxPerGroup?: number;
1277
+ /** The engine returns this many groups, best first, and every group where you leave this out. */
1278
+ limit?: number;
1438
1279
  /**
1439
- * Formula-based estimate of this partition's memory footprint. V8 has no
1440
- * per-object heap accounting API, so this number is derived from structural
1441
- * counters (document count, posting counts, field-index sizes) and does not
1442
- * include per-object overhead. Treat as an estimate, not a measurement.
1280
+ * The engine folds every hit of each group into one value, such as a sum or
1281
+ * an average, including the hits beyond `maxPerGroup`. In cluster mode the
1282
+ * coordinator fetches up to 10,000 hits of each group to fold.
1443
1283
  */
1444
- estimatedMemoryBytes: number;
1284
+ reduce?: GroupReducer;
1445
1285
  }
1446
1286
  /**
1447
- * What {@link Narsil.suggest} returns: the indexed terms that complete a
1448
- * prefix, ready to offer as you-type suggestions.
1287
+ * Folds the hits of one group into a single value.
1449
1288
  *
1450
1289
  * @public
1451
1290
  */
1452
- interface SuggestResult {
1453
- /** These completions run most widely used first. */
1454
- terms: Array<{
1455
- /** This is the completed term, as the index holds it. */
1456
- term: string;
1457
- /** The term appears in this many documents, which is what ordered the list. */
1458
- documentFrequency: number;
1459
- }>;
1460
- /** The lookup took this many milliseconds. */
1461
- elapsed: number;
1462
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1463
- analysisStale?: boolean;
1464
- }
1291
+ type GroupReducer = {
1292
+ /**
1293
+ * Folds one hit into the running value.
1294
+ *
1295
+ * @param accumulator - What the previous call returned, or what
1296
+ * `initialValue` produced for the first hit.
1297
+ * @param doc - The hit's stored document.
1298
+ * @param score - The hit's relevance score.
1299
+ * @returns The new running value.
1300
+ */
1301
+ reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
1302
+ /** Produces the starting value for each group. The engine calls it once per group. */
1303
+ initialValue: () => unknown;
1304
+ };
1465
1305
  /**
1466
- * The state of one vector field, and what maintenance would cost, as
1467
- * {@link Narsil.vectorMaintenanceStatus} reports it.
1306
+ * This configuration names the fields that receive highlighted snippets. It
1307
+ * also sets how the engine marks those snippets up.
1468
1308
  *
1469
- * Removing a vector leaves a tombstone in the graph, and enough of them slow a
1470
- * search down. Read this to decide when compaction earns its cost.
1309
+ * The engine analyses the text of each returned field again to tag every word
1310
+ * that it matched, so it tags the same words whatever the index's
1311
+ * `trackPositions` setting is. It tags a word whose stem equals a query stem,
1312
+ * and a word within the query's `tolerance` of a query stem. For a `prefix`
1313
+ * query, it tags a word for the last query term only when that word completes
1314
+ * the term or shares its stem.
1471
1315
  *
1472
1316
  * @public
1473
1317
  */
1474
- interface VectorMaintenanceResult {
1475
- /** This describes the named vector field. */
1476
- fieldName: string;
1318
+ interface HighlightConfig {
1319
+ /** The engine highlights these fields. */
1320
+ fields: string[];
1321
+ /** The engine writes this before each match, and writes `<mark>` by default. */
1322
+ preTag?: string;
1323
+ /** The engine writes this after each match, and writes `</mark>` by default. */
1324
+ postTag?: string;
1477
1325
  /**
1478
- * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
1479
- * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
1480
- * the engine divides by the number of stored vectors, because no graph
1481
- * exists yet.
1326
+ * The engine takes this many characters of the field around the densest run
1327
+ * of matches, 200 by default. It returns a snippet longer than that number,
1328
+ * because it then adds the opening and closing tags, and an ellipsis at each
1329
+ * end where it cuts the field.
1482
1330
  */
1483
- tombstoneRatio: number;
1484
- /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
1485
- graphCount: number;
1486
- /** This many vectors wait outside the graph, which a search scans one by one. */
1487
- bufferSize: number;
1488
- /** This stays true while a graph build runs. */
1489
- building: boolean;
1490
- /** {@link Narsil.compactVectors} would take about this many milliseconds. */
1491
- estimatedCompactMs: number;
1492
- /** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
1493
- estimatedOptimizeMs: number;
1331
+ maxSnippetLength?: number;
1494
1332
  }
1333
+
1495
1334
  /**
1496
- * One stored document, as {@link Narsil.listDocuments} returns it.
1335
+ * This map lists every event that the engine emits, with the payload of each
1336
+ * one.
1497
1337
  *
1498
- * @typeParam T - Shape of the stored document.
1338
+ * {@link Narsil.on} registers a listener under a key from this map, so that the
1339
+ * engine can pass the matching payload to that listener. Most of these events
1340
+ * report work that the engine does in the background, away from the call that
1341
+ * started it, so a failure that such an event reports never rejects a promise
1342
+ * that you are holding.
1499
1343
  *
1500
1344
  * @public
1501
1345
  */
1502
- interface ListedDocument<T = AnyDocument> {
1503
- /** The document is stored under this id. */
1504
- id: string;
1505
- /** This holds the stored document, cut down to what the projection kept. */
1506
- document: T;
1507
- }
1346
+ type NarsilEventMap = {
1347
+ /**
1348
+ * The engine emits this event after a call changes what a read returns from
1349
+ * an index. The calls are the inserts, updates, and removals, singly or in a
1350
+ * batch, together with `clear`, `restore`, `rebalance`, `rebuildAnalysis`,
1351
+ * `compactVectors`, `optimizeVectors`, `createIndex`, and `dropIndex`. The
1352
+ * engine emits the event after a call that throws as well, because a call can
1353
+ * change the index before it throws. It also emits the event after it reloads
1354
+ * an index, once a shared invalidation adapter reports that another instance
1355
+ * saved that index. The engine emits one event per batch, however many
1356
+ * documents the batch holds.
1357
+ *
1358
+ * The engine emits the event once a query can see the change, which means
1359
+ * after every worker copy applies the change and after any rebalance in
1360
+ * progress replays it. A query that a listener sends from its handler
1361
+ * therefore returns results that include the change. The engine waits for the
1362
+ * change to become visible only while a listener is registered for the event.
1363
+ */
1364
+ write: {
1365
+ /** This is the name of the index that changed. */
1366
+ indexName: string;
1367
+ };
1368
+ /**
1369
+ * A worker thread exited unexpectedly. The pool removes the thread and fails
1370
+ * the requests that the thread was serving with `WORKER_CRASHED`. The engine
1371
+ * then sends each of those queries again on the main thread, so the caller
1372
+ * receives a result with no error. The remaining workers keep serving
1373
+ * queries, because each of them holds a full worker copy of every promoted
1374
+ * index.
1375
+ *
1376
+ * After a delay, the engine spawns a replacement and loads every copy onto
1377
+ * it before it sends queries to the replacement. Once no worker is left, the
1378
+ * main thread serves every query, because it holds every document. The first
1379
+ * request after the delay then starts a new pool. The delay starts at one
1380
+ * second and doubles up to a minute while replacements keep failing.
1381
+ */
1382
+ workerCrash: {
1383
+ /** This is the id of the worker that exited. */
1384
+ workerId: number;
1385
+ /** These are the indexes that the worker held. */
1386
+ indexNames: string[];
1387
+ /** This is the error that ended the worker. */
1388
+ error: Error;
1389
+ };
1390
+ /** An index gained worker copies, either because it reached the copy
1391
+ * threshold or because a request loaded its copies again after an idle
1392
+ * spell. */
1393
+ workerPromote: {
1394
+ /** This is the number of workers in the pool. */
1395
+ workerCount: number;
1396
+ /** This is the reason that the index gained its copies, such as the copy
1397
+ * threshold that it reached. */
1398
+ reason: string;
1399
+ };
1400
+ /** An index could not gain worker copies, so the main thread keeps serving
1401
+ * its queries. */
1402
+ workerPromoteFailure: {
1403
+ /** This is the reason that the engine tried to load the copies. */
1404
+ reason: string;
1405
+ /** This is the error that stopped the load. */
1406
+ error: Error;
1407
+ /** This is true when the engine will try again at a later threshold. */
1408
+ retryable: boolean;
1409
+ };
1410
+ /** An index finished spreading its documents across a new number of
1411
+ * partitions. */
1412
+ partitionRebalance: {
1413
+ /** This is the name of the index that the engine rebalanced. */
1414
+ indexName: string;
1415
+ /** This is the number of partitions before the rebalance. */
1416
+ oldCount: number;
1417
+ /** This is the number of partitions after the rebalance. */
1418
+ newCount: number;
1419
+ };
1420
+ /**
1421
+ * An index passed its watermark, so its partitions are close to their
1422
+ * capacity. On a cluster node, the engine reports the document count and the
1423
+ * capacity of the one partition that `partitionId` identifies, which this
1424
+ * node leads.
1425
+ */
1426
+ partitionWatermark: {
1427
+ /** This is the name of the index that crossed the mark. */
1428
+ indexName: string;
1429
+ /** This is the number of documents in the index, or in the partition on a
1430
+ * cluster node. */
1431
+ documentCount: number;
1432
+ /** This is the number of documents that the current partitions of the
1433
+ * index can hold, or that the partition can hold on a cluster node. */
1434
+ capacity: number;
1435
+ /** This is the number of partitions in the index. */
1436
+ partitionCount: number;
1437
+ /** On a cluster node, this is the partition that crossed the mark, while
1438
+ * outside a cluster the field is absent. */
1439
+ partitionId?: number;
1440
+ };
1441
+ /**
1442
+ * The process uses nine tenths of its heap, as measured during a write or a
1443
+ * load, so the next large index can end the process with an out-of-memory
1444
+ * error.
1445
+ *
1446
+ * Where `--max-old-space-size` or `--max-old-space-size-percentage` sets a
1447
+ * limit, on the command line or in `NODE_OPTIONS`, the engine measures the
1448
+ * used bytes against that limit, which `heapLimit` then reports. Where
1449
+ * neither flag sets a limit, the engine measures the share of the heap that
1450
+ * V8 reports as no longer available. V8 reports a limit about 192 MB above
1451
+ * the true ceiling, so a process on a default heap below about 2 GB can end before
1452
+ * this event fires.
1453
+ *
1454
+ * The engine emits the event once per crossing, then arms it again once the
1455
+ * free share of the heap recovers to two tenths. Raise the limit with
1456
+ * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
1457
+ * idle index; see {@link ProcessMemoryReport.heapLimit}.
1458
+ */
1459
+ heapPressure: {
1460
+ /** This is the index that a write or a load was touching when the heap
1461
+ * reached that point. */
1462
+ indexName: string;
1463
+ /** This is the heap that the process uses, in bytes. */
1464
+ heapUsed: number;
1465
+ /** This is the size in bytes that the heap can grow to. */
1466
+ heapLimit: number;
1467
+ /** This is the estimate of the bytes that the index holds. */
1468
+ estimatedMemoryBytes: number;
1469
+ };
1470
+ /** The engine started, completed, or failed a rebuild that brings the terms
1471
+ * of an index up to the current analysis of its language module. */
1472
+ analysisRebuild: {
1473
+ /** This is the name of the index under rebuild. */
1474
+ indexName: string;
1475
+ /** This is the stage that the rebuild has reached. */
1476
+ status: 'started' | 'completed' | 'failed';
1477
+ /** This is the number of partitions that the rebuild has covered so far. */
1478
+ partitionsRebuilt: number;
1479
+ /** This is the number of partitions that the rebuild covers in total. */
1480
+ partitionCount: number;
1481
+ /** This is the error that stopped the rebuild, which only a `failed`
1482
+ * status includes. */
1483
+ error?: Error;
1484
+ };
1485
+ /** The engine started, completed, or failed the rewrite of an index that you
1486
+ * saved with an earlier release. The engine rewrites the index as it
1487
+ * recovers it, before it serves the index's first request. Because the
1488
+ * engine writes the new manifest last, the earlier files stay intact through
1489
+ * a failed rewrite. The engine then starts the rewrite again the next time
1490
+ * it recovers the index. Without index lifecycle settings, the engine
1491
+ * recovers every index before {@link createNarsil} returns, so pass the
1492
+ * listener in the `events` setting of {@link createNarsil}. */
1493
+ layoutUpgrade: {
1494
+ /** This is the name of the index under rewrite. */
1495
+ indexName: string;
1496
+ /** This is the stage that the rewrite has reached. */
1497
+ status: 'started' | 'completed' | 'failed';
1498
+ /** This is `manifest` where the earlier index is a segment manifest with
1499
+ * its files, and `bundle` where it is a single snapshot bundle. */
1500
+ layout: 'manifest' | 'bundle';
1501
+ /** This is the error that stopped the rewrite, which only a `failed`
1502
+ * status includes. */
1503
+ error?: Error;
1504
+ };
1505
+ /** A write to the write-ahead log or a checkpoint failed, so the writes since
1506
+ * the last checkpoint are at risk. */
1507
+ durabilityError: {
1508
+ /** This is the error that the durability layer threw. */
1509
+ error: Error;
1510
+ };
1511
+ /** The invalidation channel failed, so this instance can serve partitions
1512
+ * that another instance has since changed. */
1513
+ invalidationError: {
1514
+ /** This is the error that the adapter threw. */
1515
+ error: Error;
1516
+ };
1517
+ };
1508
1518
  /**
1509
- * What {@link Narsil.listDocuments} returns: one page of stored documents and
1510
- * the cursor that reaches the next one.
1511
- *
1512
- * @typeParam T - Shape of the stored documents.
1519
+ * This map holds a listener for any event of {@link NarsilEventMap}, so that
1520
+ * the engine can register each listener before it starts.
1513
1521
  *
1514
1522
  * @public
1515
1523
  */
1516
- interface ListResult<T = AnyDocument> {
1517
- /** These documents make up the page, in ascending document-id order. */
1518
- documents: Array<ListedDocument<T>>;
1519
- /** This opaque cursor reaches the next page, and is null once the listing is finished. */
1520
- cursor: string | null;
1521
- /** The listing covers this many documents in total, and any filter narrows that count. */
1522
- total: number;
1523
- /** The engine spent this many milliseconds building the page. */
1524
- elapsed: number;
1525
- }
1524
+ type NarsilEventHandlers = {
1525
+ [K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
1526
+ };
1526
1527
 
1527
1528
  /**
1528
1529
  * Snapshot of V8 heap usage as reported by `process.memoryUsage()`, with the