@delali/narsil 0.3.1-next.157 → 0.3.1-next.160

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 (565) hide show
  1. package/dist/adapters/filesystem.mjs +3 -3
  2. package/dist/adapters/gcs.mjs +3 -3
  3. package/dist/adapters/indexeddb.mjs +1 -1
  4. package/dist/adapters/s3.mjs +3 -3
  5. package/dist/browser/{chunk-N23GL72Q.mjs → chunk-4RNSFVWI.mjs} +20777 -19056
  6. package/dist/browser/chunk-MMHIIL5B.mjs +564 -0
  7. package/dist/browser/chunk-MZHQ65VI.mjs +1228 -0
  8. package/dist/browser/chunk-WC2DEXWU.mjs +29 -0
  9. package/dist/browser/{chunk-VLJQW4J6.mjs → core-leaf-TJAGWPZZ.mjs} +4674 -3102
  10. package/dist/{react-native/chunks/durability-config-QXVZEO7T.mjs → browser/durability-config-SGB5ZP5K.mjs} +8 -3
  11. package/dist/browser/embed-RF2MPGAO.mjs +222 -0
  12. package/dist/{react-native/chunks/geo-index-PX3BIHAH.mjs → browser/geo-index-GNHY4PUB.mjs} +190 -93
  13. package/dist/{react-native/chunks/module-TTEVPRCW.mjs → browser/module-362VSIGR.mjs} +1570 -275
  14. package/dist/browser/msgpack-leaf-44XNWSSY.mjs +302 -0
  15. package/dist/browser/optional-reads-XMVPG6HG.mjs +3230 -0
  16. package/dist/browser/optional-writes-WMZX4OEC.mjs +3196 -0
  17. package/dist/browser/phrase-module-22TKMXWI.mjs +616 -0
  18. package/dist/browser/resolve-vector-text-KI65IHMD.mjs +60 -0
  19. package/dist/browser/{restore-hooks-IE3GGYHG.mjs → restore-queue-S4BWOGMU.mjs} +98 -24
  20. package/dist/{react-native/chunks/runtime-R5E3TB3J.mjs → browser/runtime-NU6VOVH2.mjs} +61 -25
  21. package/dist/browser/segment-codec-leaf-A427QJUX.mjs +554 -0
  22. package/dist/browser/segment-merge-leaf-7BZ54JPI.mjs +1636 -0
  23. package/dist/browser/storage-leaf-X6CNRHJS.mjs +18221 -0
  24. package/dist/browser/store-leaf-AEMTAVHX.mjs +2069 -0
  25. package/dist/browser/{chunk-GFAZPSWK.mjs → suggestions-leaf-3Y6MR6OF.mjs} +441 -119
  26. package/dist/browser/worker-copies-WQCPP3TS.mjs +2750 -0
  27. package/dist/{capabilities-D3AoBJoF.d.ts → capabilities-BKDrry0z.d.ts} +2 -2
  28. package/dist/chunk-2JRERUNZ.mjs +217 -0
  29. package/dist/chunk-2RIS76RJ.mjs +212 -0
  30. package/dist/chunk-3B775F3C.mjs +252 -0
  31. package/dist/{chunk-24FNVRKB.mjs → chunk-3D6RZGJH.mjs} +3 -3
  32. package/dist/{chunk-INJYO3BU.mjs → chunk-4CAMH7FO.mjs} +1 -1
  33. package/dist/{chunk-U476IXKQ.mjs → chunk-4PY4JYMY.mjs} +2 -1
  34. package/dist/chunk-6EZW2GQL.mjs +978 -0
  35. package/dist/chunk-75UNINFA.mjs +271 -0
  36. package/dist/chunk-77AUVDQ5.mjs +7 -0
  37. package/dist/{chunk-JTYPJF3T.mjs → chunk-7MWYORQC.mjs} +2 -2
  38. package/dist/{chunk-TGP5M5R7.mjs → chunk-7T4LAYT4.mjs} +1 -1
  39. package/dist/{chunk-XIHUI4KB.mjs → chunk-AB27FWZM.mjs} +8 -3
  40. package/dist/{chunk-FUD5XSZ5.mjs → chunk-BXM7XM4G.mjs} +7 -3
  41. package/dist/{chunk-HJJI72X7.mjs → chunk-C7YQHCSO.mjs} +1 -1
  42. package/dist/{chunk-RVGRFOGN.mjs → chunk-D456ZFPQ.mjs} +2 -1
  43. package/dist/{chunk-KKQC526K.mjs → chunk-E2F6LZR3.mjs} +19 -21
  44. package/dist/{chunk-SMOOSIAW.mjs → chunk-FE3MRIBN.mjs} +104 -13
  45. package/dist/{chunk-KYYABCSW.mjs → chunk-FETZYCH7.mjs} +15 -1
  46. package/dist/{chunk-XXJZMTZT.mjs → chunk-FVZ5DB6Y.mjs} +3 -2
  47. package/dist/{chunk-EYD7K3H6.mjs → chunk-GF4K7IUK.mjs} +317 -120
  48. package/dist/chunk-GXCDWLQI.mjs +193 -0
  49. package/dist/{chunk-IIRIG7H5.mjs → chunk-H64YDF5M.mjs} +3 -3
  50. package/dist/{browser/chunk-VY5KW3HN.mjs → chunk-HOOR4CP5.mjs} +63 -7
  51. package/dist/chunk-IB4BYLE3.mjs +127 -0
  52. package/dist/{chunk-3C7MTCCI.mjs → chunk-IE3Q62QD.mjs} +2 -2
  53. package/dist/chunk-IH3G6SJO.mjs +40 -0
  54. package/dist/chunk-JV74RKCY.mjs +3041 -0
  55. package/dist/{chunk-ZPZ3YGXV.mjs → chunk-K67I3RF4.mjs} +261 -101
  56. package/dist/chunk-KLVMK3R5.mjs +47 -0
  57. package/dist/{chunk-5VV4R6P7.mjs → chunk-LAWIJRMJ.mjs} +4154 -2577
  58. package/dist/chunk-LF4GB4PO.mjs +281 -0
  59. package/dist/chunk-NC4QLCZC.mjs +59 -0
  60. package/dist/chunk-OOO54OVC.mjs +627 -0
  61. package/dist/chunk-OUWZKNO3.mjs +207 -0
  62. package/dist/{chunk-FJKKCV4D.mjs → chunk-P5YLI5ED.mjs} +343 -182
  63. package/dist/{chunk-4ZTHGTVX.mjs → chunk-PTTMGRG5.mjs} +9 -10
  64. package/dist/{react-native/chunks/chunk-DZ7H7D2C.mjs → chunk-Q3ZZH5Z7.mjs} +6 -0
  65. package/dist/{browser/chunk-EKMGCRSR.mjs → chunk-QBVTYY4J.mjs} +2 -9
  66. package/dist/{chunk-W5EB5XKI.mjs → chunk-R4CE4IVU.mjs} +341 -183
  67. package/dist/chunk-S2POFTLN.mjs +10 -0
  68. package/dist/{chunk-KJ3RTZDJ.mjs → chunk-S3BSDBF7.mjs} +10 -3
  69. package/dist/{chunk-4LMSZAK6.mjs → chunk-SHGN3QIF.mjs} +69 -13
  70. package/dist/chunk-SXIRM4MX.mjs +3549 -0
  71. package/dist/{chunk-TBC3XUL2.mjs → chunk-TGPKS2UM.mjs} +47 -1
  72. package/dist/chunk-TINW4BSH.mjs +31301 -0
  73. package/dist/{cold-module-VOJXMNZB.mjs → chunk-TSLV5P2J.mjs} +397 -80
  74. package/dist/{chunk-HHBUCIUY.mjs → chunk-TW543F33.mjs} +3 -3
  75. package/dist/chunk-U6B7DUQW.mjs +788 -0
  76. package/dist/{chunk-OQLD2BSW.mjs → chunk-V3SGPXWQ.mjs} +8 -9
  77. package/dist/chunk-W34VJXY7.mjs +4723 -0
  78. package/dist/chunk-YETKPX5M.mjs +5 -0
  79. package/dist/chunk-ZQ6QY42L.mjs +59 -0
  80. package/dist/{client-kqSMevVi.d.ts → client-CTp8RRiK.d.ts} +4 -4
  81. package/dist/client.d.ts +8 -8
  82. package/dist/client.mjs +66 -18
  83. package/dist/{config-B4v_Htpu.d.ts → config-PCNzWjHL.d.ts} +6 -3
  84. package/dist/{config-CTP01fns.d.ts → config-_WT5grSL.d.ts} +3 -3
  85. package/dist/core-leaf-KXFGP74A.mjs +7 -0
  86. package/dist/digest-leaf-KXBGKYHZ.mjs +1 -0
  87. package/dist/direct-executor-MKTZBR26.mjs +16 -0
  88. package/dist/distribution/coordinator/etcd.d.ts +2 -2
  89. package/dist/distribution/coordinator/etcd.mjs +7 -4
  90. package/dist/distribution/coordinator/in-memory.d.ts +2 -2
  91. package/dist/distribution/coordinator/in-memory.mjs +1 -2
  92. package/dist/distribution/transport/grpc.mjs +7 -2
  93. package/dist/distribution/transport/tcp.mjs +7 -1
  94. package/dist/distribution.d.ts +7 -7
  95. package/dist/distribution.mjs +1199 -1092
  96. package/dist/{browser/durability-config-TIYKW6XX.mjs → durability-config-XV4XR7Y4.mjs} +7 -3
  97. package/dist/embed-4H7RTBVL.mjs +221 -0
  98. package/dist/embeddings/openai.mjs +2 -2
  99. package/dist/{engine-CkPn2PWE.d.ts → engine-DBRVR_d-.d.ts} +1252 -1239
  100. package/dist/{browser/geo-index-OTV7VPIR.mjs → geo-index-2ZMMWWSK.mjs} +190 -93
  101. package/dist/{index-C4AmUnl1.d.ts → index-Ck9w5WHz.d.ts} +1 -1
  102. package/dist/index.browser.mjs +4 -16
  103. package/dist/index.d.ts +1495 -78
  104. package/dist/index.mjs +14 -50
  105. package/dist/index.react-native.mjs +11 -28
  106. package/dist/invalidation/filesystem.mjs +1 -2
  107. package/dist/languages/albanian.mjs +1 -1
  108. package/dist/languages/amharic.mjs +1 -1
  109. package/dist/languages/arabic.mjs +1 -1
  110. package/dist/languages/armenian.mjs +1 -1
  111. package/dist/languages/azerbaijani.mjs +1 -1
  112. package/dist/languages/bambara.mjs +1 -1
  113. package/dist/languages/basque.mjs +1 -1
  114. package/dist/languages/belarusian.mjs +1 -1
  115. package/dist/languages/bengali.mjs +1 -1
  116. package/dist/languages/bosnian.mjs +1 -1
  117. package/dist/languages/breton.mjs +1 -1
  118. package/dist/languages/bulgarian.mjs +1 -1
  119. package/dist/languages/burmese.mjs +1 -1
  120. package/dist/languages/catalan.mjs +1 -1
  121. package/dist/languages/chinese.mjs +1 -1
  122. package/dist/languages/croatian.mjs +1 -1
  123. package/dist/languages/czech.mjs +1 -1
  124. package/dist/languages/dagbani.mjs +1 -1
  125. package/dist/languages/danish.mjs +1 -1
  126. package/dist/languages/dutch.mjs +1 -1
  127. package/dist/languages/english.mjs +1 -1
  128. package/dist/languages/esperanto.mjs +1 -1
  129. package/dist/languages/estonian.mjs +1 -1
  130. package/dist/languages/ewe.mjs +1 -1
  131. package/dist/languages/faroese.mjs +1 -1
  132. package/dist/languages/fijian.mjs +1 -1
  133. package/dist/languages/finnish.mjs +1 -1
  134. package/dist/languages/french.mjs +1 -1
  135. package/dist/languages/ga.mjs +1 -1
  136. package/dist/languages/galician.mjs +1 -1
  137. package/dist/languages/georgian.mjs +1 -1
  138. package/dist/languages/german.mjs +1 -1
  139. package/dist/languages/greek.mjs +1 -1
  140. package/dist/languages/guarani.mjs +1 -1
  141. package/dist/languages/gujarati.mjs +1 -1
  142. package/dist/languages/haitian-creole.mjs +1 -1
  143. package/dist/languages/hausa.mjs +1 -1
  144. package/dist/languages/hawaiian.mjs +1 -1
  145. package/dist/languages/hebrew.mjs +1 -1
  146. package/dist/languages/hindi.mjs +1 -1
  147. package/dist/languages/hungarian.mjs +1 -1
  148. package/dist/languages/icelandic.mjs +1 -1
  149. package/dist/languages/igbo.mjs +1 -1
  150. package/dist/languages/indonesian.mjs +1 -1
  151. package/dist/languages/irish.mjs +1 -1
  152. package/dist/languages/italian.mjs +1 -1
  153. package/dist/languages/japanese.mjs +1 -1
  154. package/dist/languages/kannada.mjs +1 -1
  155. package/dist/languages/kazakh.mjs +1 -1
  156. package/dist/languages/khmer.mjs +1 -1
  157. package/dist/languages/kinyarwanda.mjs +1 -1
  158. package/dist/languages/kirundi.mjs +1 -1
  159. package/dist/languages/korean.mjs +1 -1
  160. package/dist/languages/kurmanji.mjs +1 -1
  161. package/dist/languages/kyrgyz.mjs +1 -1
  162. package/dist/languages/lao.mjs +1 -1
  163. package/dist/languages/latin.mjs +1 -1
  164. package/dist/languages/latvian.mjs +1 -1
  165. package/dist/languages/lingala.mjs +1 -1
  166. package/dist/languages/lithuanian.mjs +1 -1
  167. package/dist/languages/luxembourgish.mjs +1 -1
  168. package/dist/languages/macedonian.mjs +1 -1
  169. package/dist/languages/malagasy.mjs +1 -1
  170. package/dist/languages/malay.mjs +1 -1
  171. package/dist/languages/malayalam.mjs +1 -1
  172. package/dist/languages/maltese.mjs +1 -1
  173. package/dist/languages/maori.mjs +1 -1
  174. package/dist/languages/marathi.mjs +1 -1
  175. package/dist/languages/nepali.mjs +1 -1
  176. package/dist/languages/norwegian.mjs +1 -1
  177. package/dist/languages/oromo.mjs +1 -1
  178. package/dist/languages/persian.mjs +1 -1
  179. package/dist/languages/polish.mjs +1 -1
  180. package/dist/languages/portuguese.mjs +1 -1
  181. package/dist/languages/punjabi.mjs +1 -1
  182. package/dist/languages/romanian.mjs +1 -1
  183. package/dist/languages/russian.mjs +1 -1
  184. package/dist/languages/samoan.mjs +1 -1
  185. package/dist/languages/sanskrit.mjs +1 -1
  186. package/dist/languages/scottish-gaelic.mjs +1 -1
  187. package/dist/languages/serbian.mjs +1 -1
  188. package/dist/languages/shona.mjs +1 -1
  189. package/dist/languages/sinhala.mjs +1 -1
  190. package/dist/languages/slovak.mjs +1 -1
  191. package/dist/languages/slovenian.mjs +1 -1
  192. package/dist/languages/sorani.mjs +1 -1
  193. package/dist/languages/spanish.mjs +1 -1
  194. package/dist/languages/swahili.mjs +1 -1
  195. package/dist/languages/swedish.mjs +1 -1
  196. package/dist/languages/tagalog.mjs +1 -1
  197. package/dist/languages/tamil.mjs +1 -1
  198. package/dist/languages/tatar.mjs +1 -1
  199. package/dist/languages/telugu.mjs +1 -1
  200. package/dist/languages/thai.mjs +1 -1
  201. package/dist/languages/tibetan.mjs +1 -1
  202. package/dist/languages/tigrinya.mjs +1 -1
  203. package/dist/languages/tongan.mjs +1 -1
  204. package/dist/languages/turkish.mjs +1 -1
  205. package/dist/languages/twi.mjs +1 -1
  206. package/dist/languages/ukrainian.mjs +1 -1
  207. package/dist/languages/urdu.mjs +1 -1
  208. package/dist/languages/vietnamese.mjs +1 -1
  209. package/dist/languages/welsh.mjs +1 -1
  210. package/dist/languages/wolof.mjs +1 -1
  211. package/dist/languages/xhosa.mjs +1 -1
  212. package/dist/languages/yoruba.mjs +1 -1
  213. package/dist/languages/zulu.mjs +1 -1
  214. package/dist/{long-query-thread-QDFQSJD6.mjs → long-query-thread-JMGNGF6V.mjs} +74 -58
  215. package/dist/{module-N55W4Q5C.mjs → module-ZJ6ARG6V.mjs} +444 -111
  216. package/dist/msgpack-leaf-5WFRP6JM.mjs +9 -0
  217. package/dist/optional-reads-BR3BOVZW.mjs +3373 -0
  218. package/dist/optional-writes-DDFHYUOH.mjs +218 -0
  219. package/dist/{paged-partition-archive-RLRGOXDX.mjs → paged-partition-archive-G576XGVE.mjs} +29 -69
  220. package/dist/partial-words.browser.mjs +1649 -0
  221. package/dist/partial-words.mjs +15 -14
  222. package/dist/{chunk-CITFCZKF.mjs → pattern.browser.mjs} +153 -186
  223. package/dist/pattern.mjs +6 -8
  224. package/dist/persistence/durability/checkpoint-worker.d.ts +32 -24
  225. package/dist/persistence/durability/checkpoint-worker.mjs +27 -59
  226. package/dist/phrase-module-XK3T44VU.mjs +634 -0
  227. package/dist/query-actions-OMXJEC2J.mjs +118 -0
  228. package/dist/query-suggestions/merge-worker.mjs +18 -54
  229. package/dist/query-suggestions.browser.mjs +26 -227
  230. package/dist/query-suggestions.d.ts +2 -2
  231. package/dist/query-suggestions.mjs +16 -67
  232. package/dist/react-native/chunks/chunk-4EXKQ2IB.mjs +565 -0
  233. package/dist/react-native/chunks/chunk-52QD7CBJ.mjs +52 -0
  234. package/dist/react-native/chunks/chunk-72OKYHZL.mjs +969 -0
  235. package/dist/react-native/chunks/chunk-AQOWRH2C.mjs +802 -0
  236. package/dist/react-native/chunks/{chunk-4COWCEY7.mjs → chunk-FTQ7JNMU.mjs} +341 -180
  237. package/dist/react-native/chunks/chunk-G3CUQ333.mjs +42 -0
  238. package/dist/react-native/chunks/{chunk-EJ33LCHV.mjs → chunk-HRDMIQ63.mjs} +53 -1
  239. package/dist/react-native/chunks/{chunk-4AV5PPH6.mjs → chunk-IY6U6HRA.mjs} +63 -7
  240. package/dist/react-native/chunks/chunk-J2NQW353.mjs +212 -0
  241. package/dist/react-native/chunks/chunk-L4R5ITVG.mjs +29047 -0
  242. package/dist/react-native/chunks/{chunk-OXM66LO6.mjs → chunk-OK3WUA6N.mjs} +2 -10
  243. package/dist/react-native/chunks/{chunk-MVXELMJX.mjs → chunk-PVMEHBQO.mjs} +1 -1
  244. package/dist/{browser/chunk-SRMZXJSL.mjs → react-native/chunks/chunk-TQ26BKBH.mjs} +6 -0
  245. package/dist/{browser/chunk-GPPOG6PT.mjs → react-native/chunks/chunk-VUJCSQG5.mjs} +3 -1
  246. package/dist/react-native/chunks/{chunk-ENLMYKSX.mjs → chunk-XEGKQKLY.mjs} +5385 -3114
  247. package/dist/react-native/chunks/chunk-YOTP2FPE.mjs +232 -0
  248. package/dist/react-native/chunks/chunk-ZIU6TWXG.mjs +127 -0
  249. package/dist/react-native/chunks/core-leaf-5B4JXCVA.mjs +6 -0
  250. package/dist/react-native/chunks/digest-leaf-X6OIFDIU.mjs +1 -0
  251. package/dist/{durability-config-GE4U7MCZ.mjs → react-native/chunks/durability-config-3IOXIPYZ.mjs} +7 -3
  252. package/dist/react-native/chunks/embed-3WQ2CCR5.mjs +221 -0
  253. package/dist/{geo-index-MRH5JMIR.mjs → react-native/chunks/geo-index-QEYKEVPH.mjs} +190 -93
  254. package/dist/react-native/chunks/{chunk-CKNRFDTZ.mjs → gzip.react-native-DLO4WW27.mjs} +2 -1
  255. package/dist/{browser/module-TCT66FWA.mjs → react-native/chunks/module-VUA27HZZ.mjs} +1018 -540
  256. package/dist/react-native/chunks/msgpack-leaf-TR66ZVAX.mjs +7 -0
  257. package/dist/react-native/chunks/optional-reads-WDTLLHUT.mjs +3364 -0
  258. package/dist/react-native/chunks/optional-writes-FZV3QW34.mjs +267 -0
  259. package/dist/react-native/chunks/phrase-module-KCQWVXYZ.mjs +635 -0
  260. package/dist/react-native/chunks/resolve-vector-text-LXRYXF7M.mjs +59 -0
  261. package/dist/react-native/chunks/restore-queue-EI2V2I4S.mjs +179 -0
  262. package/dist/{browser/runtime-OTAGEFQW.mjs → react-native/chunks/runtime-BUCSAK4U.mjs} +61 -25
  263. package/dist/react-native/chunks/segment-codec-leaf-6ULP7H3I.mjs +12 -0
  264. package/dist/react-native/chunks/segment-merge-leaf-F4GQZNK6.mjs +13 -0
  265. package/dist/react-native/chunks/storage-leaf-OAXBU2L6.mjs +18042 -0
  266. package/dist/react-native/chunks/store-leaf-GY2ZZFXB.mjs +14 -0
  267. package/dist/react-native/chunks/{chunk-WW2X2AEI.mjs → suggestions-leaf-SQEZ4IBS.mjs} +332 -118
  268. package/dist/react-native/chunks/worker-copies-EEHSCFJW.mjs +2627 -0
  269. package/dist/react-native/partial-words.mjs +954 -35
  270. package/dist/react-native/pattern.mjs +238 -111
  271. package/dist/react-native/query-suggestions.mjs +33 -239
  272. package/dist/react-native/sync.mjs +95 -52
  273. package/dist/react-native/synonyms.mjs +256 -112
  274. package/dist/react.d.ts +9 -9
  275. package/dist/react.mjs +6 -0
  276. package/dist/{rerank-MQ37IYRV.mjs → rerank-Y6MWBMTT.mjs} +17 -8
  277. package/dist/rerankers/http.mjs +2 -2
  278. package/dist/resolve-vector-text-4PDRTPNQ.mjs +2 -0
  279. package/dist/restore-queue-KPYSRJ4A.mjs +184 -0
  280. package/dist/runtime-4GKUIAKV.mjs +595 -0
  281. package/dist/{schema-Jwt928nJ.d.ts → schema-C_7yRJLt.d.ts} +1 -1
  282. package/dist/segment-codec-leaf-6IFBSBPN.mjs +17 -0
  283. package/dist/segment-merge-leaf-VE3FUSVE.mjs +17 -0
  284. package/dist/server.d.ts +33 -13
  285. package/dist/server.mjs +81 -100
  286. package/dist/{browser/durability-wiring-GVZEE46O.mjs → storage-leaf-HMIIOUYN.mjs} +2334 -931
  287. package/dist/store-leaf-M7T7SUZJ.mjs +19 -0
  288. package/dist/stored-values-BWIMpiT_.d.ts +25 -0
  289. package/dist/suggestions-leaf-Q3Q5D6XV.mjs +53 -0
  290. package/dist/sync/filesystem.d.ts +3 -3
  291. package/dist/sync/filesystem.mjs +27 -11
  292. package/dist/sync/indexeddb.browser.mjs +287 -0
  293. package/dist/sync/indexeddb.d.ts +3 -3
  294. package/dist/sync/indexeddb.mjs +7 -2
  295. package/dist/sync.browser.mjs +88 -72
  296. package/dist/sync.d.ts +4 -4
  297. package/dist/sync.mjs +89 -59
  298. package/dist/{chunk-I5B7RXU7.mjs → synonyms.browser.mjs} +248 -135
  299. package/dist/synonyms.mjs +15 -11
  300. package/dist/{tasks-CoNjxbop.d.ts → tasks-B4tT4vmP.d.ts} +4 -4
  301. package/dist/thread-SNILJXX3.mjs +30 -0
  302. package/dist/{types-DPMjfOr_.d.ts → types-CTg0KaMy.d.ts} +2 -2
  303. package/dist/vector/search-worker.d.ts +7 -1
  304. package/dist/vector/search-worker.mjs +9 -13
  305. package/dist/worker-copies-ZLZS2CUM.mjs +2152 -0
  306. package/dist/workers/entry.mjs +60 -30
  307. package/openapi.json +66 -50
  308. package/package.json +233 -8
  309. package/dist/analysis-change-CKEMM2MC.mjs +0 -55
  310. package/dist/analysis-change-entry-SEDMJ6MW.mjs +0 -1
  311. package/dist/archive-history-E4R73RWD.mjs +0 -29
  312. package/dist/browser/analysis-change-ZKGJFENM.mjs +0 -942
  313. package/dist/browser/analysis-change-entry-5BFUVMHJ.mjs +0 -1
  314. package/dist/browser/archive-history-4IP5XQZY.mjs +0 -29
  315. package/dist/browser/chunk-25MTVDYD.mjs +0 -432
  316. package/dist/browser/chunk-3I27KXQD.mjs +0 -34
  317. package/dist/browser/chunk-3NLMB5CC.mjs +0 -217
  318. package/dist/browser/chunk-4RD3AFSB.mjs +0 -32
  319. package/dist/browser/chunk-5W3MMTLG.mjs +0 -19
  320. package/dist/browser/chunk-5YWB3E2W.mjs +0 -92
  321. package/dist/browser/chunk-7IGKGWSQ.mjs +0 -79
  322. package/dist/browser/chunk-AI5UI46D.mjs +0 -12
  323. package/dist/browser/chunk-ATEBYXP6.mjs +0 -10
  324. package/dist/browser/chunk-BLT4RHCJ.mjs +0 -241
  325. package/dist/browser/chunk-C26SPCGQ.mjs +0 -2636
  326. package/dist/browser/chunk-C4FJ3WDY.mjs +0 -177
  327. package/dist/browser/chunk-CXNTHHA7.mjs +0 -63
  328. package/dist/browser/chunk-DSXIBE6N.mjs +0 -78
  329. package/dist/browser/chunk-DUH6QUVU.mjs +0 -2374
  330. package/dist/browser/chunk-ELV4OZOI.mjs +0 -29
  331. package/dist/browser/chunk-EXQZGUQH.mjs +0 -193
  332. package/dist/browser/chunk-G64Q6OJF.mjs +0 -96
  333. package/dist/browser/chunk-HOZW3PKP.mjs +0 -9
  334. package/dist/browser/chunk-HUCSHDTB.mjs +0 -100
  335. package/dist/browser/chunk-JPTQZWJQ.mjs +0 -10
  336. package/dist/browser/chunk-K3IPRX6D.mjs +0 -2559
  337. package/dist/browser/chunk-ML7THVLJ.mjs +0 -38
  338. package/dist/browser/chunk-MY2XKH22.mjs +0 -40
  339. package/dist/browser/chunk-NLWTBAGB.mjs +0 -111
  340. package/dist/browser/chunk-NXQG7DRA.mjs +0 -318
  341. package/dist/browser/chunk-OEDCEZXJ.mjs +0 -92
  342. package/dist/browser/chunk-OIZS5KIX.mjs +0 -6
  343. package/dist/browser/chunk-RA6LSBCM.mjs +0 -43
  344. package/dist/browser/chunk-TK63WFXK.mjs +0 -90
  345. package/dist/browser/chunk-TY7L6OXO.mjs +0 -69
  346. package/dist/browser/chunk-U3JOQGWX.mjs +0 -19
  347. package/dist/browser/chunk-U4YDIBUT.mjs +0 -653
  348. package/dist/browser/chunk-UATIJ4KU.mjs +0 -21
  349. package/dist/browser/chunk-UKOWD2K5.mjs +0 -315
  350. package/dist/browser/chunk-UTMHUHUV.mjs +0 -150
  351. package/dist/browser/chunk-V43N6TZO.mjs +0 -857
  352. package/dist/browser/chunk-VI7BQR4U.mjs +0 -21
  353. package/dist/browser/chunk-WN464PTL.mjs +0 -375
  354. package/dist/browser/chunk-WXLBZJMT.mjs +0 -25
  355. package/dist/browser/chunk-X7TXYUKO.mjs +0 -86
  356. package/dist/browser/chunk-XAWNZ4G2.mjs +0 -151
  357. package/dist/browser/chunk-Y6IBAUNO.mjs +0 -561
  358. package/dist/browser/chunk-ZI2V4VD7.mjs +0 -21
  359. package/dist/browser/cold-module-YNUUDNOM.mjs +0 -761
  360. package/dist/browser/engine-hooks-HBVS6YM4.mjs +0 -18
  361. package/dist/browser/gzip-5S7ROJFJ.mjs +0 -1
  362. package/dist/browser/import-5ESVMFDJ.mjs +0 -20
  363. package/dist/browser/methods-KTQCSIN4.mjs +0 -30
  364. package/dist/browser/module-NDSQLPMQ.mjs +0 -25
  365. package/dist/browser/operations-OJ3BXS55.mjs +0 -5
  366. package/dist/browser/phrase-module-HAT3TLZN.mjs +0 -328
  367. package/dist/browser/pool-3JLET5RO.mjs +0 -297
  368. package/dist/browser/release-HYXPVJVS.mjs +0 -32
  369. package/dist/browser/restore-queue-LQBBTODR.mjs +0 -55
  370. package/dist/browser/retention-TY3L3BFN.mjs +0 -211
  371. package/dist/browser/snapshot-5FHPPCNZ.mjs +0 -965
  372. package/dist/browser/start-2UZTOBG5.mjs +0 -26
  373. package/dist/browser/sync-state-P5XG6LTQ.mjs +0 -15
  374. package/dist/browser/write-ULXAN5B4.mjs +0 -196
  375. package/dist/chunk-2NE7VCYE.mjs +0 -212
  376. package/dist/chunk-2ROUFMQX.mjs +0 -543
  377. package/dist/chunk-37CD3OKS.mjs +0 -87
  378. package/dist/chunk-3MXV3VHR.mjs +0 -46
  379. package/dist/chunk-3OH67G7R.mjs +0 -214
  380. package/dist/chunk-4B7JIGQD.mjs +0 -106
  381. package/dist/chunk-5YNRKI2C.mjs +0 -81
  382. package/dist/chunk-6HTGOXIK.mjs +0 -875
  383. package/dist/chunk-6OEGXLBX.mjs +0 -57
  384. package/dist/chunk-6RC4K46J.mjs +0 -86
  385. package/dist/chunk-7GFE3PEY.mjs +0 -40
  386. package/dist/chunk-7GXJUJ24.mjs +0 -49
  387. package/dist/chunk-7V5IUP2T.mjs +0 -63
  388. package/dist/chunk-A4L7YTKX.mjs +0 -458
  389. package/dist/chunk-BEZH7VEH.mjs +0 -23
  390. package/dist/chunk-BNL5OPRV.mjs +0 -634
  391. package/dist/chunk-BTPGQC6Z.mjs +0 -27
  392. package/dist/chunk-C7XQYG6U.mjs +0 -50
  393. package/dist/chunk-CQZXZ75V.mjs +0 -562
  394. package/dist/chunk-CWS55TEX.mjs +0 -242
  395. package/dist/chunk-CZQ33DLW.mjs +0 -78
  396. package/dist/chunk-EEBCDP36.mjs +0 -32
  397. package/dist/chunk-FB6463IN.mjs +0 -1499
  398. package/dist/chunk-FCJ553HS.mjs +0 -655
  399. package/dist/chunk-FEZVDOWX.mjs +0 -6996
  400. package/dist/chunk-FOCV4CBZ.mjs +0 -87
  401. package/dist/chunk-FQBFZAWG.mjs +0 -27
  402. package/dist/chunk-G6HRSGOU.mjs +0 -74
  403. package/dist/chunk-GES7U2PM.mjs +0 -68
  404. package/dist/chunk-GH4WQ22V.mjs +0 -34
  405. package/dist/chunk-GPWMUPCA.mjs +0 -1126
  406. package/dist/chunk-GQPTDQCL.mjs +0 -54
  407. package/dist/chunk-HJSN7UYG.mjs +0 -10
  408. package/dist/chunk-I54T6CQP.mjs +0 -117
  409. package/dist/chunk-IPN7S4KX.mjs +0 -130
  410. package/dist/chunk-J4IJTTEX.mjs +0 -226
  411. package/dist/chunk-JSV6OQ4C.mjs +0 -74
  412. package/dist/chunk-K4ZIGL2O.mjs +0 -290
  413. package/dist/chunk-KAKQ74LS.mjs +0 -53
  414. package/dist/chunk-KCQYFO4K.mjs +0 -62
  415. package/dist/chunk-KHKIRS5D.mjs +0 -113
  416. package/dist/chunk-KOKM4PQN.mjs +0 -52
  417. package/dist/chunk-KP7TYHWT.mjs +0 -92
  418. package/dist/chunk-KZ3NX2P7.mjs +0 -21
  419. package/dist/chunk-L5ORED7V.mjs +0 -25
  420. package/dist/chunk-LDNCLRZU.mjs +0 -218
  421. package/dist/chunk-LHKOSI2J.mjs +0 -58
  422. package/dist/chunk-LQG5G2LY.mjs +0 -39
  423. package/dist/chunk-MATMVH65.mjs +0 -9
  424. package/dist/chunk-MP7ABPTD.mjs +0 -189
  425. package/dist/chunk-MW6BR4QP.mjs +0 -316
  426. package/dist/chunk-MWD5VPN7.mjs +0 -21
  427. package/dist/chunk-ODYKO5TO.mjs +0 -101
  428. package/dist/chunk-OG7UGJ6F.mjs +0 -63
  429. package/dist/chunk-ORN5BLL7.mjs +0 -11
  430. package/dist/chunk-OYABFKTW.mjs +0 -1974
  431. package/dist/chunk-P5LANSH6.mjs +0 -121
  432. package/dist/chunk-PELHVTO7.mjs +0 -24
  433. package/dist/chunk-PIH5SJ4N.mjs +0 -7481
  434. package/dist/chunk-PSZI4O24.mjs +0 -253
  435. package/dist/chunk-PV2CG7EJ.mjs +0 -886
  436. package/dist/chunk-PWGYQXML.mjs +0 -470
  437. package/dist/chunk-Q2UL2TPC.mjs +0 -21
  438. package/dist/chunk-QHPYS427.mjs +0 -66
  439. package/dist/chunk-QJVOLKU6.mjs +0 -111
  440. package/dist/chunk-QLDABJZM.mjs +0 -20
  441. package/dist/chunk-QYRNLLLI.mjs +0 -99
  442. package/dist/chunk-RCX4WNLC.mjs +0 -151
  443. package/dist/chunk-RFBLQLLZ.mjs +0 -16
  444. package/dist/chunk-RIHIVFIQ.mjs +0 -240
  445. package/dist/chunk-RLOES5SX.mjs +0 -31
  446. package/dist/chunk-RWURUDSP.mjs +0 -2639
  447. package/dist/chunk-RZWWB2XR.mjs +0 -96
  448. package/dist/chunk-S5LN746F.mjs +0 -10
  449. package/dist/chunk-SOI6LTHM.mjs +0 -216
  450. package/dist/chunk-SQJWAIF4.mjs +0 -12
  451. package/dist/chunk-TDIK6NTV.mjs +0 -10
  452. package/dist/chunk-TQXHPFWT.mjs +0 -177
  453. package/dist/chunk-U55XJEIG.mjs +0 -18
  454. package/dist/chunk-UD5HIS4U.mjs +0 -382
  455. package/dist/chunk-UHICS3JI.mjs +0 -83
  456. package/dist/chunk-UJDJB3NE.mjs +0 -913
  457. package/dist/chunk-VD7J552I.mjs +0 -28
  458. package/dist/chunk-VSLSGASN.mjs +0 -30
  459. package/dist/chunk-VZ2ONHEE.mjs +0 -3715
  460. package/dist/chunk-W7OSSKH5.mjs +0 -1427
  461. package/dist/chunk-WZ7YV54N.mjs +0 -152
  462. package/dist/chunk-X5CV2E2B.mjs +0 -1
  463. package/dist/chunk-Y4WPNHMC.mjs +0 -50
  464. package/dist/chunk-YEKL4JBK.mjs +0 -96
  465. package/dist/chunk-ZXNQEW43.mjs +0 -18
  466. package/dist/chunk-ZYAY26KG.mjs +0 -29
  467. package/dist/direct-executor-V5DRIECI.mjs +0 -34
  468. package/dist/durability-wiring-3TD62MBI.mjs +0 -4072
  469. package/dist/engine-hooks-HA3SBOBR.mjs +0 -54
  470. package/dist/gzip-F4HMIEEQ.mjs +0 -1
  471. package/dist/import-GPKLTSKA.mjs +0 -56
  472. package/dist/methods-7IOINERF.mjs +0 -30
  473. package/dist/module-JYHFTVPS.mjs +0 -63
  474. package/dist/operations-G5EP6JPX.mjs +0 -5
  475. package/dist/phrase-module-XW5MKWP5.mjs +0 -330
  476. package/dist/pool-Y4A46T36.mjs +0 -298
  477. package/dist/react-native/chunks/analysis-change-QUVDNABS.mjs +0 -934
  478. package/dist/react-native/chunks/analysis-change-entry-OC4XASBF.mjs +0 -1
  479. package/dist/react-native/chunks/archive-history-MJKUQLSU.mjs +0 -29
  480. package/dist/react-native/chunks/chunk-2PRHILX3.mjs +0 -529
  481. package/dist/react-native/chunks/chunk-3NQOVO3K.mjs +0 -1
  482. package/dist/react-native/chunks/chunk-3WI35N75.mjs +0 -226
  483. package/dist/react-native/chunks/chunk-4DII3ZSM.mjs +0 -73
  484. package/dist/react-native/chunks/chunk-4J74WHQM.mjs +0 -177
  485. package/dist/react-native/chunks/chunk-4NWR3NGS.mjs +0 -151
  486. package/dist/react-native/chunks/chunk-5CQX3XXV.mjs +0 -17
  487. package/dist/react-native/chunks/chunk-5MSX5FRT.mjs +0 -858
  488. package/dist/react-native/chunks/chunk-6OFDUYVX.mjs +0 -92
  489. package/dist/react-native/chunks/chunk-6VBXNFLE.mjs +0 -9
  490. package/dist/react-native/chunks/chunk-6ZELFCK5.mjs +0 -315
  491. package/dist/react-native/chunks/chunk-AAAETEJK.mjs +0 -27
  492. package/dist/react-native/chunks/chunk-AM7RSBPF.mjs +0 -32
  493. package/dist/react-native/chunks/chunk-BITYFZSZ.mjs +0 -242
  494. package/dist/react-native/chunks/chunk-C5G6TJ7A.mjs +0 -140
  495. package/dist/react-native/chunks/chunk-CHPTFFJM.mjs +0 -43
  496. package/dist/react-native/chunks/chunk-DIYDOIM4.mjs +0 -10
  497. package/dist/react-native/chunks/chunk-DMIFXZ3Q.mjs +0 -432
  498. package/dist/react-native/chunks/chunk-DVDX4SDR.mjs +0 -375
  499. package/dist/react-native/chunks/chunk-DXRSEWA2.mjs +0 -12
  500. package/dist/react-native/chunks/chunk-F753DA54.mjs +0 -23
  501. package/dist/react-native/chunks/chunk-FHPW7P2O.mjs +0 -40
  502. package/dist/react-native/chunks/chunk-FTZHMRD2.mjs +0 -18
  503. package/dist/react-native/chunks/chunk-HJBJBH26.mjs +0 -34
  504. package/dist/react-native/chunks/chunk-IAENKE2D.mjs +0 -21
  505. package/dist/react-native/chunks/chunk-IO2SMUQD.mjs +0 -10
  506. package/dist/react-native/chunks/chunk-IYNT75CE.mjs +0 -111
  507. package/dist/react-native/chunks/chunk-JDOEEMEF.mjs +0 -38
  508. package/dist/react-native/chunks/chunk-JWUCMVRK.mjs +0 -15
  509. package/dist/react-native/chunks/chunk-KSBYEMCB.mjs +0 -100
  510. package/dist/react-native/chunks/chunk-KU646XXT.mjs +0 -164
  511. package/dist/react-native/chunks/chunk-LU3Y3P63.mjs +0 -68
  512. package/dist/react-native/chunks/chunk-LVIKKAA6.mjs +0 -93
  513. package/dist/react-native/chunks/chunk-LZSLNSUN.mjs +0 -193
  514. package/dist/react-native/chunks/chunk-MJDQU5MW.mjs +0 -1225
  515. package/dist/react-native/chunks/chunk-NNE4VDMM.mjs +0 -8
  516. package/dist/react-native/chunks/chunk-NVVRSRX5.mjs +0 -78
  517. package/dist/react-native/chunks/chunk-OCSLSH27.mjs +0 -22723
  518. package/dist/react-native/chunks/chunk-PB2YXVQW.mjs +0 -29
  519. package/dist/react-native/chunks/chunk-PJHAB5ZY.mjs +0 -79
  520. package/dist/react-native/chunks/chunk-PSWKQVVT.mjs +0 -9
  521. package/dist/react-native/chunks/chunk-RDWG33MM.mjs +0 -79
  522. package/dist/react-native/chunks/chunk-SK2PWYDH.mjs +0 -654
  523. package/dist/react-native/chunks/chunk-SUPXRTMD.mjs +0 -96
  524. package/dist/react-native/chunks/chunk-TORU2OHQ.mjs +0 -218
  525. package/dist/react-native/chunks/chunk-U4KSKA4Z.mjs +0 -23
  526. package/dist/react-native/chunks/chunk-UNUFZ2QY.mjs +0 -68
  527. package/dist/react-native/chunks/chunk-WBYQRHDY.mjs +0 -86
  528. package/dist/react-native/chunks/chunk-WVWJNUMN.mjs +0 -2562
  529. package/dist/react-native/chunks/chunk-YH7QY657.mjs +0 -288
  530. package/dist/react-native/chunks/chunk-YZW4CHM6.mjs +0 -562
  531. package/dist/react-native/chunks/chunk-ZNZ6CPAZ.mjs +0 -562
  532. package/dist/react-native/chunks/chunk-ZVQMBF2H.mjs +0 -63
  533. package/dist/react-native/chunks/chunk-ZWAIN4GG.mjs +0 -2636
  534. package/dist/react-native/chunks/chunk-ZZT7CEN7.mjs +0 -92
  535. package/dist/react-native/chunks/cold-module-N6KFNNZA.mjs +0 -773
  536. package/dist/react-native/chunks/durability-wiring-RN64S2TL.mjs +0 -4984
  537. package/dist/react-native/chunks/engine-hooks-CWA5CKCA.mjs +0 -30
  538. package/dist/react-native/chunks/gzip.react-native-HLEPDKZ3.mjs +0 -3
  539. package/dist/react-native/chunks/import-5UAWBRJP.mjs +0 -32
  540. package/dist/react-native/chunks/methods-6W5U4C3H.mjs +0 -30
  541. package/dist/react-native/chunks/module-6RP4ZCBW.mjs +0 -37
  542. package/dist/react-native/chunks/operations-GNRMD6EX.mjs +0 -5
  543. package/dist/react-native/chunks/phrase-module-QK22HSQ2.mjs +0 -329
  544. package/dist/react-native/chunks/pool-JR3NJCAF.mjs +0 -297
  545. package/dist/react-native/chunks/release-2SIHZWDO.mjs +0 -32
  546. package/dist/react-native/chunks/restore-hooks-ENFMDTWC.mjs +0 -127
  547. package/dist/react-native/chunks/restore-queue-4R6AASE5.mjs +0 -55
  548. package/dist/react-native/chunks/retention-5GTFT3GR.mjs +0 -223
  549. package/dist/react-native/chunks/snapshot-5LGPQXFS.mjs +0 -976
  550. package/dist/react-native/chunks/start-ZQJVZ5DN.mjs +0 -38
  551. package/dist/react-native/chunks/sync-state-PASCIHHT.mjs +0 -15
  552. package/dist/react-native/chunks/write-6BRYIIZ7.mjs +0 -208
  553. package/dist/release-SMR4WJD4.mjs +0 -32
  554. package/dist/restore-hooks-HXLIEB4A.mjs +0 -153
  555. package/dist/restore-queue-LZH7LMLR.mjs +0 -55
  556. package/dist/retention-3K7ARGAG.mjs +0 -66
  557. package/dist/runtime-COIUORCN.mjs +0 -177
  558. package/dist/snapshot-O7ICP7NJ.mjs +0 -783
  559. package/dist/start-S4PFP6RS.mjs +0 -66
  560. package/dist/sync-state-ZWHLAFLE.mjs +0 -15
  561. package/dist/thread-YLJ3ZPQ3.mjs +0 -50
  562. package/dist/write-2OBJGLFS.mjs +0 -233
  563. /package/dist/browser/{chunk-M3MQE2X7.mjs → digest-leaf-64IPRPZD.mjs} +0 -0
  564. /package/dist/browser/{chunk-JNOAKDUM.mjs → gzip-JF3S6PPT.mjs} +0 -0
  565. /package/dist/{chunk-ZXNNR73R.mjs → gzip-2UCZW2MM.mjs} +0 -0
@@ -1,1495 +1,1508 @@
1
1
  import { E as EmbeddingAdapter, R as RerankAdapter } from './adapters-pljAqmrC.js';
2
- import { A as AnyDocument, S as SchemaDefinition, B as BM25Params, e as ScoringMode, a as InsertOptions, W as WriteOptions, I as IndexConfig, P as PartitionConfig } from './schema-Jwt928nJ.js';
2
+ import { A as AnyDocument, B as BM25Params, d as ScoringMode, S as SchemaDefinition, a as InsertOptions, W as WriteOptions, I as IndexConfig, P as PartitionConfig } from './schema-C_7yRJLt.js';
3
3
  import { h as QuerySuggestionsBuildEvent, j as QuerySuggestionsWarningEvent } from './query-suggestions-CBYkrQ5T.js';
4
4
  import { a as SynonymRule } from './synonyms-CpOAHPa-.js';
5
5
 
6
6
  /**
7
- * Every code a {@link NarsilError} carries, grouped by the part of the engine
8
- * that raises it.
9
- *
10
- * Match on the code rather than on the message, because a code is stable and a
11
- * message is not. The HTTP server maps each code to a status, so a code also
12
- * tells you whether the caller or the engine is at fault.
7
+ * Compares one field against a value. Setting several keys narrows the match,
8
+ * because a document has to satisfy all of them.
13
9
  *
14
10
  * @public
15
11
  */
16
- declare const ErrorCodes: {
17
- readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
18
- readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
19
- readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
20
- readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
21
- readonly DOC_NOT_FOUND: "DOC_NOT_FOUND";
22
- readonly DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS";
23
- readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
24
- readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
25
- readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
26
- readonly INDEX_ORPHANED: "INDEX_ORPHANED";
27
- readonly INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED";
28
- readonly INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN";
29
- readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
30
- readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
31
- readonly WORKER_CRASHED: "WORKER_CRASHED";
32
- readonly WORKER_BUSY: "WORKER_BUSY";
33
- readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
34
- readonly WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED";
35
- readonly PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED";
36
- readonly PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED";
37
- readonly PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED";
38
- readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
39
- readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
40
- readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
41
- readonly PERSISTENCE_DEPENDENCY_MISSING: "PERSISTENCE_DEPENDENCY_MISSING";
42
- readonly BACKUP_NOT_FOUND: "BACKUP_NOT_FOUND";
43
- readonly BACKUP_ALREADY_EXISTS: "BACKUP_ALREADY_EXISTS";
44
- readonly BACKUP_DAMAGED: "BACKUP_DAMAGED";
45
- readonly BACKUP_DURABILITY_REQUIRED: "BACKUP_DURABILITY_REQUIRED";
46
- readonly BACKUP_IN_PROGRESS: "BACKUP_IN_PROGRESS";
47
- readonly BACKUP_STORE_CLAIMED: "BACKUP_STORE_CLAIMED";
48
- readonly BACKUP_STORE_NOT_CONFIGURED: "BACKUP_STORE_NOT_CONFIGURED";
49
- readonly BACKUP_NOT_READY: "BACKUP_NOT_READY";
50
- readonly SYNC_DURABILITY_REQUIRED: "SYNC_DURABILITY_REQUIRED";
51
- readonly SYNC_BACKUP_STORE_REQUIRED: "SYNC_BACKUP_STORE_REQUIRED";
52
- readonly SYNC_NOT_READY: "SYNC_NOT_READY";
53
- readonly SYNC_NOT_ENABLED: "SYNC_NOT_ENABLED";
54
- readonly SYNC_SNAPSHOT_PREPARING: "SYNC_SNAPSHOT_PREPARING";
55
- readonly QUERY_SUGGESTIONS_NOT_ENABLED: "QUERY_SUGGESTIONS_NOT_ENABLED";
56
- readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
57
- readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
58
- readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
59
- readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
60
- readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
61
- readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
62
- readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
63
- readonly SEARCH_INVALID_PHRASE: "SEARCH_INVALID_PHRASE";
64
- readonly SEARCH_PHRASE_NOT_READY: "SEARCH_PHRASE_NOT_READY";
65
- readonly BM25_NOT_READY: "BM25_NOT_READY";
66
- readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
67
- readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
68
- readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
69
- readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
70
- readonly RESTORE_MEMORY_EXCEEDED: "RESTORE_MEMORY_EXCEEDED";
71
- readonly MEMORY_WRITE_BLOCKED: "MEMORY_WRITE_BLOCKED";
72
- readonly ANALYSIS_CHANGE_REPLACED: "ANALYSIS_CHANGE_REPLACED";
73
- readonly ANALYSIS_CHANGE_NOT_READY: "ANALYSIS_CHANGE_NOT_READY";
74
- readonly ANALYSIS_GENERATION_MISSING: "ANALYSIS_GENERATION_MISSING";
75
- readonly ANALYSIS_REBUILD_MEMORY_EXCEEDED: "ANALYSIS_REBUILD_MEMORY_EXCEEDED";
76
- readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
77
- readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
78
- readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
79
- readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
80
- readonly RERANK_FAILED: "RERANK_FAILED";
81
- readonly RERANK_CONFIG_INVALID: "RERANK_CONFIG_INVALID";
82
- readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
83
- readonly CONFIG_INVALID: "CONFIG_INVALID";
84
- readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
85
- readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
86
- readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
87
- readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
88
- readonly SEARCH_CONTEXT_MISSING: "SEARCH_CONTEXT_MISSING";
89
- readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
90
- readonly CLUSTER_WRITE_BLOCKED: "CLUSTER_WRITE_BLOCKED";
91
- readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
92
- readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
93
- readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
94
- readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
95
- readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
96
- readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
97
- readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
98
- readonly NODE_NOT_READY: "NODE_NOT_READY";
99
- readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
100
- readonly NODE_VERSION_INCOMPATIBLE: "NODE_VERSION_INCOMPATIBLE";
101
- readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
102
- readonly COORDINATOR_AUTH_FAILED: "COORDINATOR_AUTH_FAILED";
103
- readonly COORDINATOR_UNAVAILABLE: "COORDINATOR_UNAVAILABLE";
104
- readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
105
- readonly NATIVE_DEPENDENCY_MISSING: "NATIVE_DEPENDENCY_MISSING";
106
- readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
107
- readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
108
- readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
109
- readonly REPLICATION_OUTCOME_UNKNOWN: "REPLICATION_OUTCOME_UNKNOWN";
110
- readonly REPLICATION_WRITE_CONFLICT: "REPLICATION_WRITE_CONFLICT";
111
- readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
112
- readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
113
- readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
114
- readonly REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH";
115
- readonly REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED";
116
- readonly PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY";
117
- readonly PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED";
118
- readonly INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS";
119
- readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
120
- readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
121
- readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
122
- readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
123
- readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
124
- readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
125
- readonly SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID";
126
- readonly SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID";
127
- readonly SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH";
128
- readonly SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER";
129
- readonly SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW";
130
- readonly SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED";
131
- readonly SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING";
132
- readonly SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING";
133
- readonly SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH";
134
- readonly SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR";
135
- readonly SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS";
136
- readonly SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED";
137
- readonly SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE";
138
- readonly SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED";
139
- readonly SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED";
140
- readonly SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT";
141
- readonly SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE";
142
- readonly SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED";
143
- readonly SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED";
12
+ type ComparisonFilter = {
13
+ /** This matches a field equal to the value, or a list field where one element equals it. */
14
+ eq?: number | string | boolean;
15
+ /**
16
+ * This matches a document that holds the field with a value other than this
17
+ * one, or a list field where every element differs from it, which an empty
18
+ * list does.
19
+ */
20
+ ne?: number | string | boolean;
21
+ /** This matches a field greater than the number. */
22
+ gt?: number;
23
+ /** This matches a field less than the number. */
24
+ lt?: number;
25
+ /** This matches a field greater than or equal to the number. */
26
+ gte?: number;
27
+ /** This matches a field less than or equal to the number. */
28
+ lte?: number;
29
+ /** This matches a field inside the inclusive range, given as `[low, high]`. */
30
+ between?: [number, number];
144
31
  };
145
32
  /**
146
- * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
147
- * when you branch on a failure the engine raised.
33
+ * The engine tests a text field against this filter for equality, for a text
34
+ * range, or with the set, prefix, and pattern tests.
35
+ *
36
+ * On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
37
+ * element of the list on its own. A document passes `eq`, `in`, `startsWith`,
38
+ * `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
39
+ * test. However, a document passes `ne` or `nin` only when every element
40
+ * differs from the values.
41
+ *
42
+ * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
43
+ * to a single `string` or `verbatim` field whose type includes `sortable`. It
44
+ * throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
45
+ * orders the values as a sort on the field does, so it compares their case
46
+ * folds first and compares their raw code points only where the folds are
47
+ * equal.
48
+ *
49
+ * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
50
+ * `string[]` field whose type includes `pattern`. On a pattern field, the
51
+ * engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
52
+ * `contains`, `wildcard`, and `regex` from the field's pattern index, and
53
+ * `caseFold` applies to each of those tests. The engine compares the code
54
+ * points of each value as they are stored, with no Unicode normalisation.
55
+ *
56
+ * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
57
+ * `startsWith`, and `endsWith` from the field's index of values. A `string` or
58
+ * `string[]` field whose type leaves out `pattern` keeps no index of whole
59
+ * values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
60
+ * and for `matchesAny` and `containsAll`, on such a field.
61
+ *
62
+ * The engine also throws `SEARCH_INVALID_FILTER` in these cases:
63
+ *
64
+ * - The filter sets `contains`, `wildcard`, `regex`, or `caseFold` on a field
65
+ * that is not a pattern field.
66
+ * - The text or the pattern of a test on a pattern field holds more than 1,024
67
+ * code points.
68
+ * - A literal test under `caseFold` has a text whose case fold holds more than
69
+ * 2,048 code points.
70
+ * - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
148
71
  *
149
72
  * @public
150
73
  */
151
- type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
74
+ type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
75
+ /** This matches a value that comes after the text in sort order. */
76
+ gt?: string;
77
+ /** This matches a value that comes before the text in sort order. */
78
+ lt?: string;
79
+ /** This matches a value equal to the text or after it in sort order. */
80
+ gte?: string;
81
+ /** This matches a value equal to the text or before it in sort order. */
82
+ lte?: string;
83
+ /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
84
+ between?: [string, string];
85
+ /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
86
+ in?: string[];
87
+ /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
88
+ nin?: string[];
89
+ /** This matches a field starting with the text. */
90
+ startsWith?: string;
91
+ /** This matches a field ending with the text. */
92
+ endsWith?: string;
93
+ /** This matches a pattern field whose value holds the text anywhere in it. */
94
+ contains?: string;
95
+ /**
96
+ * This matches a pattern field when the whole value matches the wildcard
97
+ * pattern. For example, `INV-*-2024` matches `INV-0042-2024`.
98
+ *
99
+ * In the pattern, `*` matches any sequence of code points, including an
100
+ * empty one, and `?` matches exactly one code point. Write `\` before a code
101
+ * point to match that code point itself, so `\*` matches an asterisk.
102
+ *
103
+ * The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
104
+ * `\` with no code point after it. It throws the same error for a pattern
105
+ * with more than 2,048 positions. Each `*`, each `?`, and each other code
106
+ * point counts as one position, except that under `caseFold` a code point
107
+ * counts once for each code point of its case fold.
108
+ */
109
+ wildcard?: string;
110
+ /**
111
+ * This matches a pattern field when some part of the value matches the
112
+ * regular expression. `^` and `$` match only at the start and at the end of
113
+ * the whole value.
114
+ *
115
+ * The engine accepts literal code points, `.`, `\d`, `\w`, and `\s`, sets
116
+ * such as `[a-z]` and `[^0-9]`, groups, and `|`. It also accepts the repeats
117
+ * `*`, `+`, `?`, `{n}`, `{n,}`, and `{n,m}`, the anchors `^` and `$`, the
118
+ * word edge `\b`, and number ranges such as `<1-65535>`. A number range
119
+ * matches the digits of any whole number from its low end to its high end.
120
+ * Write `\` before an ASCII punctuation mark to match the mark itself. The
121
+ * `.` matches any code point, including a line break.
122
+ *
123
+ * The matcher never backtracks, so it checks a value in at most as many
124
+ * steps as the value's code points multiplied by the pattern's positions.
125
+ *
126
+ * The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
127
+ * syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
128
+ * flag. It throws the same error when the groups of a pattern nest more than
129
+ * 32 deep, when a count is above 2,048, and when a pattern holds more than
130
+ * 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
131
+ * option to false, the server refuses every `regex` test.
132
+ */
133
+ regex?: string;
134
+ /**
135
+ * When this is true, the engine compares the case fold of each value of a
136
+ * pattern field with the case fold of the text, so a test for `error`
137
+ * matches `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`,
138
+ * `endsWith`, `contains`, `wildcard`, and `regex`.
139
+ *
140
+ * Under `caseFold`, a set that does not open with `^` can also match a
141
+ * sequence of code points. When a member that the set holds on its own folds
142
+ * to several code points, the set matches that whole fold, so `[ß]` matches
143
+ * `ss`.
144
+ */
145
+ caseFold?: boolean;
146
+ /**
147
+ * This lets the `eq` test of a pattern field match a value within this many
148
+ * edits of the text, so a test for `INV-2O24` with a tolerance of 1 matches
149
+ * `INV-2024`. An edit inserts, deletes, or replaces one code point, so a
150
+ * swap of two neighbouring code points counts as two edits. With `caseFold`,
151
+ * the engine counts the edits between the case folds of the value and the
152
+ * text. The tolerance applies to `eq` alone, so the other tests of the field
153
+ * still compare exactly.
154
+ *
155
+ * The engine takes its candidates from the pattern index, so the case fold
156
+ * of the text has to hold enough distinct runs of three code points. For a
157
+ * tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
158
+ * the number of code points in the longest case fold among the text's code
159
+ * points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
160
+ * therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
161
+ * `'auto'`, the engine uses 2 where the text holds enough runs for 2,
162
+ * otherwise 1 where it holds enough for 1, and otherwise 0.
163
+ *
164
+ * The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
165
+ * text with too few runs, stating how many runs that tolerance needs. It
166
+ * throws the same error for any other tolerance, for a tolerance on a field
167
+ * that is not a pattern field, and for a tolerance in a filter without an
168
+ * `eq` test. Towards the pattern work cap, it counts one unit for each cell
169
+ * that it fills in the table of edit distances between the text and a
170
+ * value.
171
+ */
172
+ tolerance?: 0 | 1 | 2 | 'auto';
173
+ };
152
174
  /**
153
- * Every code the HTTP layer raises for a failure that arises before or around
154
- * the engine call, such as parsing the body, enforcing a limit, or routing.
175
+ * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
176
+ * `enum[]`, `verbatim[]`, or `string[]` field.
155
177
  *
156
- * The engine raises none of these, so a failure carrying one of them says the
157
- * request never reached the engine.
178
+ * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
179
+ * field, for a value whose type differs from the type of the list's elements,
180
+ * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
181
+ * out `pattern`.
158
182
  *
159
183
  * @public
160
184
  */
161
- declare const ServerErrorCodes: {
162
- readonly INVALID_REQUEST: "INVALID_REQUEST";
163
- readonly INVALID_JSON: "INVALID_JSON";
164
- readonly EMPTY_BODY: "EMPTY_BODY";
165
- readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
166
- readonly NOT_FOUND: "NOT_FOUND";
167
- readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
168
- readonly TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE";
169
- readonly TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE";
170
- readonly TASK_INTERRUPTED: "TASK_INTERRUPTED";
171
- readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
172
- readonly HOOK_ERROR: "HOOK_ERROR";
173
- readonly INTERNAL_ERROR: "INTERNAL_ERROR";
185
+ type ArrayFilter = {
186
+ /** 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. */
187
+ containsAll?: (string | number | boolean)[];
188
+ /** This matches a list holding at least one of the values, at most 65,536 of them. */
189
+ matchesAny?: (string | number | boolean)[];
190
+ /** This compares the number of elements in the list. */
191
+ size?: ComparisonFilter;
174
192
  };
175
193
  /**
176
- * Any one of the codes in {@link ServerErrorCodes}.
194
+ * Tests whether a field carries a value at all, without looking at what it
195
+ * holds.
177
196
  *
178
197
  * @public
179
198
  */
180
- type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
199
+ type PresenceFilter = {
200
+ /** This matches a document where the field holds a value other than null. */
201
+ exists?: boolean;
202
+ /** This matches a document where the field is absent or null. */
203
+ notExists?: boolean;
204
+ /** This matches a document where the field is absent, null, an empty string, or an empty list. */
205
+ isEmpty?: boolean;
206
+ /** This matches a document where the field holds a value other than an empty string or an empty list. */
207
+ isNotEmpty?: boolean;
208
+ };
181
209
  /**
182
- * Every code that the caller's own side raises, where a request never reaches
183
- * a server, or where the caller cannot read the answer.
210
+ * Matches a `geopoint` field against a circle drawn on the earth.
184
211
  *
185
- * The HTTP client raises the first five. The React bindings raise
186
- * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. A
187
- * synced device raises `SYNC_ANALYSIS_UNAVAILABLE` before it downloads a
188
- * snapshot whose language, tokeniser, or stop words it has not registered,
189
- * and it keeps its copy of the index. No server sends any of them, so a failure under one means the exchange broke
190
- * before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
191
- * therefore maps none of them, because no request can arrive under one and no
192
- * HTTP status belongs to one.
212
+ * @public
213
+ */
214
+ type GeoRadiusFilter = {
215
+ /** The engine tests the field against this circle. */
216
+ radius: {
217
+ /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
218
+ lat: number;
219
+ /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
220
+ lon: number;
221
+ /** The circle has this radius, measured in `unit`. */
222
+ distance: number;
223
+ /**
224
+ * The engine measures `distance` in kilometres under `'km'`, in miles
225
+ * under `'mi'`, and in metres under `'m'`. For any other unit, it throws
226
+ * `SEARCH_INVALID_FILTER`.
227
+ */
228
+ unit: 'km' | 'mi' | 'm';
229
+ /** 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. */
230
+ inside?: boolean;
231
+ /**
232
+ * The engine measures each distance with the Haversine formula on a sphere
233
+ * by default, and with Vincenty's formula on the WGS-84 ellipsoid while
234
+ * this is true. Vincenty's formula iterates, so the engine takes longer
235
+ * to compute each distance. The two formulas differ by less than 0.3% under about
236
+ * 100 km, while across a continent they can differ by up to 0.5%.
237
+ */
238
+ highPrecision?: boolean;
239
+ };
240
+ };
241
+ /**
242
+ * Matches a `geopoint` field against a polygon drawn on the earth.
193
243
  *
194
244
  * @public
195
245
  */
196
- declare const ClientErrorCodes: {
197
- readonly CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED";
198
- readonly CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT";
199
- readonly CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED";
200
- readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
201
- readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
202
- readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
203
- readonly SYNC_ANALYSIS_UNAVAILABLE: "SYNC_ANALYSIS_UNAVAILABLE";
246
+ type GeoPolygonFilter = {
247
+ /** The engine tests the field against this polygon. */
248
+ polygon: {
249
+ /**
250
+ * The engine closes the ring through these corners in the order that you
251
+ * list them, so you can leave the first point off the end. It throws
252
+ * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
253
+ * encloses no area, and for a corner whose latitude is outside -90 to 90
254
+ * or whose longitude is outside -180 to 180. It also throws that error for
255
+ * a ring of more than 65,536 corners. List the corners counter-clockwise
256
+ * around the area, as in an exterior ring of GeoJSON. Where the corners
257
+ * span 180 degrees of longitude or more, the engine matches the area on
258
+ * the left of that path, so a ring listed that way can cross the
259
+ * antimeridian or span more than half the globe.
260
+ */
261
+ points: Array<{
262
+ /** The corner has this latitude, in degrees. */
263
+ lat: number;
264
+ /** The corner has this longitude, in degrees. */
265
+ lon: number;
266
+ }>;
267
+ /** 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. */
268
+ inside?: boolean;
269
+ };
204
270
  };
205
271
  /**
206
- * Any one of the codes in {@link ClientErrorCodes}.
272
+ * Either shape a `geopoint` field is matched against.
207
273
  *
208
274
  * @public
209
275
  */
210
- type ClientErrorCode = (typeof ClientErrorCodes)[keyof typeof ClientErrorCodes];
276
+ type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
211
277
  /**
212
- * Every code a {@link NarsilError} can carry: one the engine raised, one the
213
- * HTTP layer raised, one the client raised, or any other string.
278
+ * The filter one field accepts. Which of these forms applies follows from the
279
+ * field's declared type.
214
280
  *
215
- * The last arm exists for a server's `onRequest` hook, which rejects a request
216
- * under a code of its own, such as `UNAUTHORIZED`, and the client then passes
217
- * that code through unchanged. An editor still completes every code Narsil
218
- * defines.
281
+ * @public
282
+ */
283
+ type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
284
+ /**
285
+ * The filter that a query runs, built from per-field tests and the boolean
286
+ * operators that combine them.
287
+ *
288
+ * The engine answers every test from an index that it keeps for the field. It
289
+ * applies the filter before scoring, so a narrow filter makes a search
290
+ * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
291
+ * tests, counted across every field and nested expression. Past either limit,
292
+ * the engine throws `SEARCH_INVALID_FILTER`, while it throws
293
+ * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
219
294
  *
220
295
  * @public
221
296
  */
222
- type NarsilErrorCode = ErrorCode | ServerErrorCode | ClientErrorCode | (string & {});
297
+ type FilterExpression = {
298
+ /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
299
+ fields?: Record<string, FieldFilter>;
300
+ /** Every nested expression has to match. */
301
+ and?: FilterExpression[];
302
+ /** At least one nested expression has to match. */
303
+ or?: FilterExpression[];
304
+ /** The nested expression has to fail. */
305
+ not?: FilterExpression;
306
+ };
307
+
223
308
  /**
224
- * The error every part of the engine throws.
309
+ * How a query reorders its top hits with a rerank adapter.
225
310
  *
226
- * Catch it, read {@link NarsilError.code} to decide what to do, and read
227
- * {@link NarsilError.details} for the values that caused it. The engine lets
228
- * this error propagate unchanged, so the code you catch is the code the
229
- * failing operation raised.
311
+ * The engine ranks the query as it would without this setting, passes the
312
+ * top `window` hits to the adapter, and orders them by the adapter's scores.
313
+ * The hits past the window follow in their first ranking, with their scores
314
+ * scaled below the lowest reranked score, so every page of one query comes
315
+ * from the same order.
230
316
  *
231
317
  * @public
232
318
  */
233
- declare class NarsilError extends Error {
234
- /** This says which failure it is. */
235
- readonly code: NarsilErrorCode;
236
- /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
237
- readonly details: Record<string, unknown>;
319
+ interface RerankConfig {
238
320
  /**
239
- * Builds an error carrying a code the caller can branch on.
240
- *
241
- * @param code - The failure this error reports, from {@link ErrorCodes} for
242
- * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
243
- * or {@link ClientErrorCodes} for one that stopped a request from reaching a
244
- * server.
245
- * @param message - Plain description, for a log or a person.
246
- * @param details - Values behind the failure, which reach
247
- * {@link NarsilError.details}.
321
+ * The engine scores the hits with the rerank adapter registered under this
322
+ * key. It throws `RERANK_CONFIG_INVALID` for a key that it has not
323
+ * registered.
248
324
  */
249
- constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
325
+ adapter: string;
326
+ /**
327
+ * The engine sends the adapter the values of these text fields, in this
328
+ * order and joined with newlines, as the text of each hit. Each member of a
329
+ * list field takes a line of its own. The engine throws
330
+ * `RERANK_CONFIG_INVALID` for an empty list, for a field that the schema
331
+ * does not declare as text, and for a field that the list gives twice.
332
+ */
333
+ fields: string[];
334
+ /**
335
+ * The adapter compares each hit with this text. Where you leave it out, the
336
+ * engine sends the query's `term`, or else its `vector.text`, and it throws
337
+ * `RERANK_CONFIG_INVALID` where the query carries neither.
338
+ */
339
+ query?: string;
340
+ /**
341
+ * The engine reranks this many of the top hits, from 1 to the engine's
342
+ * `maxRerankWindow`. Where you leave the window out, the engine reranks the
343
+ * smallest of 100 and `maxRerankWindow`, and no more than the `hybrid.depth`
344
+ * of a hybrid query that sets one. A hybrid query that sets `hybrid.depth`
345
+ * reranks its fused list at that depth, so the engine throws
346
+ * `RERANK_CONFIG_INVALID` when you set a window above that depth.
347
+ */
348
+ window?: number;
250
349
  }
350
+
251
351
  /**
252
- * Reports whether a caught value is a {@link NarsilError}, including one that
253
- * another entry point of this package raises.
254
- *
255
- * Each browser bundle holds its own copy of the class, so an `instanceof` test
256
- * inside the React bindings returns false for an error that the client raises,
257
- * although that error still holds its code. This function tests for the marker
258
- * that the constructor writes, so it returns true for an error from any entry
259
- * point.
352
+ * Vector-search inputs passed under `QueryParams.vector`.
260
353
  *
261
- * @param value - The value that a `catch` block receives.
262
- * @returns True where the value holds a code in {@link NarsilError.code}.
354
+ * Supply either a raw `value` array or a `text` string for auto-embedding;
355
+ * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
356
+ * by the outer query's `limit`, not by any field on this object.
263
357
  *
264
358
  * @public
265
359
  */
266
- declare function isNarsilError(value: unknown): value is NarsilError;
267
-
360
+ interface VectorQueryConfig {
361
+ /**
362
+ * Name of the schema field that holds the vector to compare against.
363
+ * Must reference a field declared as `vector[N]` in the index schema.
364
+ */
365
+ field: string;
366
+ /**
367
+ * Raw query vector, given as a number array or a `Float32Array`. Length
368
+ * must match the indexed field's dimension or the search rejects the
369
+ * request with `VECTOR_DIMENSION_MISMATCH`.
370
+ */
371
+ value?: number[] | Float32Array;
372
+ /**
373
+ * Text to embed at query time using the index or instance embedding
374
+ * adapter. Mutually exclusive with `value`; requires a configured adapter.
375
+ */
376
+ text?: string;
377
+ /**
378
+ * Score floor applied during ranking. Hits scoring below this value
379
+ * are dropped before `limit` is enforced, so the returned hit count
380
+ * can be smaller than `limit` even when more documents exist. The
381
+ * floor is interpreted in score space for every metric; for
382
+ * `euclidean`, distance is mapped to a similarity score of
383
+ * `1 / (1 + distance)` first. Defaults to no floor.
384
+ */
385
+ similarity?: number;
386
+ /**
387
+ * Similarity metric used for ranking. Defaults to `cosine`. Choose
388
+ * `dotProduct` for raw inner-product scoring on already-normalised
389
+ * vectors and `euclidean` for distance-based ordering.
390
+ */
391
+ metric?: 'cosine' | 'dotProduct' | 'euclidean';
392
+ /**
393
+ * The engine keeps this many candidates as it walks the HNSW graph, so a
394
+ * higher value can find more of the true neighbours, although each query
395
+ * takes longer. The engine applies it only once the field holds a graph.
396
+ * The engine fetches k hits, where k is one more than the number of hits up
397
+ * to the end of the page, so k is `limit` plus 1 on a first page. When a
398
+ * query leaves `efSearch` unset, the engine keeps the larger of 50 and k
399
+ * plus a margin, where the margin is 50 below 768 dimensions, 75 from 768
400
+ * to 1,023 dimensions, and 0 at 1,024 dimensions and above. Under a
401
+ * filter, the engine counts only the candidates that pass the filter.
402
+ */
403
+ efSearch?: number;
404
+ /**
405
+ * The engine re-scores this many times k candidates in a quantized field
406
+ * against the full-precision vectors before it returns the best `limit`,
407
+ * where k is one more than the number of hits up to the end of the page, so
408
+ * k is `limit` plus 1 on a first page. For a value below 1, or for a value
409
+ * that is not a finite number, the engine throws a `NarsilError` with code
410
+ * `CONFIG_INVALID`. The engine ignores it on a field whose quantization is
411
+ * `none`. When a query leaves it unset, the engine sets the number of
412
+ * candidates that it re-scores from k and from the field's dimension. It
413
+ * rounds that number up, and it re-scores at least 3k candidates under
414
+ * `osq1` and `osq2`, and at least k under `osq4` and `osq8`. Below 768
415
+ * dimensions, it re-scores 3.23k + 55.9√k under `osq1` and 2.6k + 22.5√k under
416
+ * `osq2`. From 768 to 1,023 dimensions, it re-scores 2.2k + 27√k under
417
+ * `osq1` and k + 16√k under `osq2`, and under `osq2` it re-scores at least
418
+ * the smaller of k + 75 and k + 18√k. At 1,024 dimensions and above, it
419
+ * re-scores 3k under both. Under `osq4`, it re-scores 5k below 1,024
420
+ * dimensions and 2k from 1,024 dimensions, while under `osq8` it re-scores
421
+ * 2k at every dimension. Under a filter, the engine counts only the
422
+ * candidates that pass the filter. On vectors spread evenly across every
423
+ * dimension, a one-bit or two-bit code can find fewer than 95% of the true
424
+ * nearest neighbours at these defaults, so raise `oversample` on a query that
425
+ * needs more of them.
426
+ */
427
+ oversample?: number;
428
+ }
268
429
  /**
269
- * What {@link Narsil.query} returns: the ranked hits and everything the query
270
- * asked for alongside them.
430
+ * How a hybrid query merges its keyword ranking with its vector ranking.
271
431
  *
272
- * @typeParam T - Shape of the stored documents, which flows through to each
273
- * hit's `document`.
432
+ * `rrf` combines the two by rank alone, which needs no tuning and handles
433
+ * scores that live on different scales. `linear` blends the scores directly,
434
+ * which gives you control once you know what each side's scores look like.
274
435
  *
275
436
  * @public
276
437
  */
277
- interface QueryResult<T = AnyDocument> {
278
- /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
279
- hits: Array<Hit<T>>;
280
- /**
281
- * This many documents match in total, before the engine applies `limit`
282
- * and `offset`. For a keyword search the engine counts every match. For a
283
- * vector search it counts every vector that passes the query's filter and
284
- * its `similarity` floor, which is every vector in the field where the query
285
- * sets neither of them. The engine also counts each pinned document that
286
- * the query does not match, since it places that document among the hits.
287
- */
288
- count: number;
438
+ interface HybridConfig {
439
+ /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
440
+ strategy?: 'rrf' | 'linear';
441
+ /** 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. */
442
+ k?: number;
443
+ /** 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. */
444
+ alpha?: number;
289
445
  /**
290
- * `count` holds the exact number of matches where this is true, and a
291
- * number at or below the true total where it is false. Where a query sets a
292
- * `similarity` floor on a vector field that holds a graph, the engine
293
- * counts only the vectors that it fetches, because it compares the query
294
- * with only a fraction of that field's vectors. For a hybrid query the
295
- * engine fuses two rankings, so the count is exact only where each of those
296
- * rankings contains every matching document. Where you pin a document from
297
- * outside the hits that the engine fetches, the engine reports true only
298
- * where it holds every match of the query, because only then can it test
299
- * whether the query matches that document.
446
+ * Set a depth to get the same fused order on every page of one query, and
447
+ * a cursor that resumes it. The engine then fetches this many results from
448
+ * the keyword search and from the vector search, fuses them, and pages
449
+ * through the top `depth` of the fused list. The last page stops at this
450
+ * depth, so it can hold fewer hits than the limit. Set a whole number from 1
451
+ * to 10,000. The engine throws `CONFIG_INVALID` for any other value, and
452
+ * `SEARCH_RESULT_WINDOW_EXCEEDED` for a page that starts at this depth or
453
+ * beyond. Where you leave the depth out, each search fetches only enough
454
+ * results to fill the page, so the fused order can change from one page to
455
+ * the next, and a cluster refuses a cursor with `SEARCH_INVALID_CURSOR`.
300
456
  */
301
- countExact: boolean;
302
- /** The engine spent this many milliseconds on the search. */
303
- elapsed: number;
304
- /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
305
- cursor?: string;
306
- /** These facet counts are keyed by the field each facet was asked for. */
307
- facets?: Record<string, FacetResult>;
308
- /** These groups arrive when the query asked for grouping. */
309
- groups?: GroupResult[];
310
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
311
- analysisStale?: boolean;
312
- /** The search read this much of the index, which is how you spot a degraded answer. */
313
- coverage: QueryCoverage;
457
+ depth?: number;
314
458
  }
459
+
315
460
  /**
316
- * How much of an index one search read, which is what you check before you
317
- * trust a count or a ranking.
318
- *
319
- * An embedded engine reads every partition it holds, so `queriedPartitions`
320
- * matches `totalPartitions` there and the other two stay zero. A search across
321
- * a cluster may find a node slow or unreachable, which it counts here while
322
- * still returning the hits the other nodes gave it.
461
+ * Everything {@link Narsil.suggest} accepts.
323
462
  *
324
463
  * @public
325
464
  */
326
- interface QueryCoverage {
327
- /** The search should have read this many partitions. */
328
- totalPartitions: number;
329
- /** The search read this many of them. */
330
- queriedPartitions: number;
331
- /** The search counts a partition here when the node holding it took longer than the query allowed. */
332
- timedOutPartitions: number;
333
- /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
334
- failedPartitions: number;
465
+ interface SuggestParams {
466
+ /** The returned terms complete this text. */
467
+ prefix: string;
468
+ /** The lookup returns this many completions, most widely used first, and 10 by default. */
469
+ limit?: number;
335
470
  }
336
471
  /**
337
- * One matching document, with the score that ranked it.
472
+ * Everything {@link Narsil.listDocuments} accepts.
338
473
  *
339
- * @typeParam T - Shape of the stored document.
474
+ * {@link Narsil.listDocuments} reads the stored documents without ranking them,
475
+ * which is how you page through a whole index. Leave `cursor` out to start at
476
+ * the first document, then pass back the cursor each result carries until it
477
+ * comes back null.
478
+ *
479
+ * A cursor belongs to the sort it was made under, so pass the same `sort` back
480
+ * with it. Changing `sort` invalidates the cursor, and the engine then throws
481
+ * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
340
482
  *
341
483
  * @public
342
484
  */
343
- interface Hit<T = AnyDocument> {
344
- /** The document is stored under this id. */
345
- id: string;
485
+ interface ListParams {
346
486
  /**
347
- * This score ranked the hit. Scores compare within one result set, never
348
- * across searches. A sorted query ranks by sort values instead and carries
349
- * no score unless it sets `includeScores`.
487
+ * This cursor comes from a previous result, and continues where it stopped.
488
+ * The engine ties a cursor to the sort that produced it, and it throws
489
+ * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
350
490
  */
351
- score?: number;
352
- /** This is the stored document. */
353
- document: T;
354
- /** These are the parts the score was built from, which arrive when the query asked for them. */
355
- scoreComponents?: ScoreComponents;
356
- /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
357
- highlights?: Record<string, HighlightMatch>;
491
+ cursor?: string;
492
+ /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
493
+ limit?: number;
494
+ /** This narrows the listing to the documents the filter accepts. */
495
+ filters?: FilterExpression;
496
+ /**
497
+ * This orders the listing by field value rather than by document id, and the
498
+ * engine applies the fields in the order they are listed. Pass an object
499
+ * keyed by field, or a list of fields in the order they apply. It breaks a
500
+ * tie on document id, and it sorts by at most eight fields. The engine uses
501
+ * document-id order when you leave this out.
502
+ *
503
+ * The engine reads every document the listing covers to build a sorted page,
504
+ * so a sorted listing costs more than the default order on a large index.
505
+ */
506
+ sort?: SortSpec;
507
+ /** This chooses how much of each stored document comes back, and the whole document by default. */
508
+ document?: DocumentProjection;
358
509
  }
510
+
359
511
  /**
360
- * The numbers BM25 combined into one hit's score, which is what you read when
361
- * a ranking surprises you.
512
+ * Which engine answers a query: keyword matching, vector similarity, or both
513
+ * merged into one ranking.
362
514
  *
363
515
  * @public
364
516
  */
365
- interface ScoreComponents {
366
- /**
367
- * Each query term appears in one field of this document this many times,
368
- * under a key of `field:term`. A term that appears in two fields therefore
369
- * has two entries here, while the keys of {@link ScoreComponents.idf} hold
370
- * the bare term.
371
- */
372
- termFrequencies: Record<string, number>;
373
- /** Each field the query searched holds this many tokens, keyed by field. */
374
- fieldLengths: Record<string, number>;
375
- /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
376
- idf: Record<string, number>;
377
- }
517
+ type SearchMode = 'fulltext' | 'vector' | 'hybrid';
378
518
  /**
379
- * A highlighted field, ready to render.
519
+ * How many of a query's terms a document has to carry. `all` demands every
520
+ * term, `any` accepts one, and a number demands that many.
380
521
  *
381
522
  * @public
382
523
  */
383
- interface HighlightMatch {
384
- /** This is the field's text around the match, wrapped in the query's tags. */
385
- snippet: string;
386
- /**
387
- * Each range gives the start and the end of one match in the original field,
388
- * so you can render the highlight yourself. Where the snippet covers part of
389
- * the field alone, the engine lists only the matches that the snippet
390
- * displays. Every offset is a character count from the start of the original
391
- * field, whatever the snippet contains.
392
- */
393
- positions: Array<{
394
- /** The match starts at this offset. */
395
- start: number;
396
- /** The match ends at this offset. */
397
- end: number;
398
- }>;
399
- }
524
+ type TermMatchPolicy = 'all' | 'any' | number;
400
525
  /**
401
- * Counts for one faceted field.
526
+ * One field of a sort, and the direction that field orders by.
402
527
  *
403
528
  * @public
404
529
  */
405
- interface FacetResult {
406
- /** This many documents match per value, keyed by value. */
407
- values: Record<string, number>;
408
- /** This is the number of entries in `values`, which is at most the facet's `limit`. */
409
- count: number;
530
+ interface SortField {
531
+ /** The field the engine reads, which may name a nested field with dots. */
532
+ field: string;
533
+ /** Ascending or descending order for this field. */
534
+ direction: 'asc' | 'desc';
410
535
  /**
411
- * Every count in `values` is at most this far below its true count. A value
412
- * that the engine leaves out of `values` because of `limit` has a true
413
- * count of at most this figure too. Where the engine counts a field on one
414
- * thread, it counts every value exactly, so this figure is the largest
415
- * count that it leaves out. Where it splits the count across worker copies
416
- * or cluster nodes, each of them returns only its own top values, so the
417
- * merged count of a value that is common overall but rare on one of them
418
- * can lack the matches on that one. A bound of 0 means that `values` holds
419
- * every matching value, each with its exact count.
536
+ * Where a document's field holds a list, the engine sorts that document by
537
+ * one value from the list: the smallest under `'min'`, the largest under
538
+ * `'max'`, and the mean or the median of the list's numbers under `'avg'`
539
+ * or `'median'`. Where you leave this out, the engine uses `'min'` for an
540
+ * ascending sort and `'max'` for a descending one. It sorts by a field that
541
+ * holds a single value as that value stands, under every mode. It throws
542
+ * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
543
+ * schema declares as anything other than `number` or `number[]`.
420
544
  */
421
- errorBound: number;
545
+ mode?: 'min' | 'max' | 'avg' | 'median';
422
546
  }
423
547
  /**
424
- * One group of hits, produced by a query that grouped its results.
548
+ * A sort, either as an object keyed by field or as a list of fields in the
549
+ * order they apply.
425
550
  *
426
- * @public
427
- */
428
- interface GroupResult {
429
- /** Each grouping field holds this value for the group, keyed by field. */
430
- values: Record<string, unknown>;
431
- /** These hits fall in the group, cut to the query's `maxPerGroup`. */
432
- hits: Array<Hit>;
433
- /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
434
- reduced?: unknown;
435
- /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
436
- reducerError?: string;
437
- }
438
- /**
439
- * What {@link Narsil.preflight} returns: how many documents a query matches,
440
- * without building or ranking a single hit.
551
+ * Both forms order by the first field, break a tie on the second, and carry on
552
+ * that way. Prefer the list where the order of the fields matters, because
553
+ * JavaScript moves an all-digit key such as `2024` to the front of an object
554
+ * and the list keeps the order you wrote.
441
555
  *
442
556
  * @public
443
557
  */
444
- interface PreflightResult {
445
- /** The query matches this many documents. */
446
- count: number;
447
- /** `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}. */
448
- countExact: boolean;
449
- /** The count took this many milliseconds. */
450
- elapsed: number;
451
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
452
- analysisStale?: boolean;
453
- }
558
+ type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
454
559
  /**
455
- * What a batch write returns. One bad document never abandons the rest, so
456
- * read both lists.
560
+ * Everything {@link Narsil.query} accepts.
561
+ *
562
+ * Set `term` for keyword search, `vector` for similarity search, and `mode`
563
+ * when you want both. The engine matches nothing for a query carrying neither
564
+ * of them, so page through an index with {@link Narsil.listDocuments}
565
+ * instead.
457
566
  *
458
567
  * @public
459
568
  */
460
- interface BatchResult {
461
- /** The engine wrote the documents under these ids. */
462
- succeeded: string[];
463
- /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
464
- failed: Array<{
569
+ interface QueryParams {
570
+ /**
571
+ * The engine analyses this text with the index's language module and searches
572
+ * for the terms that result. Words inside double quotes form a phrase, which
573
+ * a document has to hold side by side and in that order inside one field. The
574
+ * engine throws `SEARCH_INVALID_PHRASE` for a phrase of more than 32 words, for
575
+ * more than 32 phrases, and for a phrase on an index with `trackPositions` off.
576
+ * It throws `SEARCH_PHRASE_NOT_READY` while an index with a `string[]` field
577
+ * waits for a rebuild.
578
+ */
579
+ term?: string;
580
+ /** The engine searches the term in these fields, and in every text field in the schema by default. */
581
+ fields?: string[];
582
+ /**
583
+ * The engine scores only the documents that pass this filter. It throws
584
+ * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
585
+ * operator on a field of another type, such as `startsWith` on a number
586
+ * field.
587
+ */
588
+ filters?: FilterExpression;
589
+ /**
590
+ * The engine multiplies the score from each named field by its weight. It
591
+ * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
592
+ * the schema declares, and `CONFIG_INVALID` for a weight that is not a
593
+ * finite number.
594
+ */
595
+ boost?: Record<string, number>;
596
+ /**
597
+ * These BM25 parameters score this search alone, and they override the
598
+ * index's parameters, so a `k1` here also overrides a `k1` that the index
599
+ * sets for a field. The engine validates them on every search, and it throws
600
+ * the same errors as {@link IndexConfig.bm25}, except `SEARCH_INVALID_FIELD`
601
+ * for a name in `fields` that is not a text field. They change no score on a
602
+ * vector search, and on a hybrid search they apply to the keyword ranking
603
+ * alone. A cursor pages only a search with the same parameters.
604
+ */
605
+ bm25?: BM25Params;
606
+ /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
607
+ scoring?: ScoringMode;
608
+ /**
609
+ * The engine drops any hit scoring below this value. It ranks with BM25,
610
+ * which has no fixed upper bound, so a floor that suits one index and one
611
+ * query can reject every hit in another.
612
+ */
613
+ minScore?: number;
614
+ /**
615
+ * The engine keeps a document only where the document matches this many
616
+ * query terms, under the same `tolerance` and `prefixLength` that the search
617
+ * uses. One term is enough by default.
618
+ */
619
+ termMatch?: TermMatchPolicy;
620
+ /**
621
+ * The engine matches an indexed term within this edit distance of a query
622
+ * term, so it finds a document for a query with a typo. It counts each
623
+ * Unicode code point as one character. Set an integer from 0 to 10.
624
+ */
625
+ tolerance?: number;
626
+ /**
627
+ * The engine applies `tolerance` only to the indexed terms that share this
628
+ * many leading characters with the query term, or to the terms that start
629
+ * with the whole query term when the query term is shorter. Set an integer
630
+ * from 0 to 1,024; the default is 2.
631
+ */
632
+ prefixLength?: number;
633
+ /**
634
+ * With this set, the engine treats the last query term as an unfinished
635
+ * word, so `secur` matches `security`. The engine matches that last term by
636
+ * its stem or by completing it, while `tolerance` applies only to the earlier
637
+ * terms, which have to match whole. The engine scores completions against a
638
+ * shared document frequency. It also ranks them below whole-word matches.
639
+ * The engine ignores this setting where `exact` is true, and the setting is
640
+ * false by default.
641
+ */
642
+ prefix?: boolean;
643
+ /**
644
+ * With this set, the engine also matches each query word of three or more
645
+ * characters inside the longer words of every field whose type includes
646
+ * `partial`, so a search for `proof` matches a document with `waterproof`
647
+ * in such a field. The engine counts each Unicode code point as one
648
+ * character. It looks for the query word, before stemming, inside each word
649
+ * exactly as that word appears in a document.
650
+ *
651
+ * The engine adds at most 50 such words to a query, which it divides as
652
+ * evenly as it can among the query words. Within the share of each query
653
+ * word, it adds first the words that the most documents contain. It scores
654
+ * a match inside a longer word in proportion to the part of that word that
655
+ * the query word makes up, so it scores such a match below a whole-word
656
+ * match at the same frequency in a field of the same length. With
657
+ * `highlight`, it tags each whole word that contains a query word in a
658
+ * searched `partial` field.
659
+ *
660
+ * The engine applies no `tolerance` to these matches. It ignores this
661
+ * setting where `exact` is true or where the searched fields include no
662
+ * `partial` field. Where the setting is absent, the engine treats it as
663
+ * false, while it throws `CONFIG_INVALID` for any value other than `true`
664
+ * or `false`.
665
+ */
666
+ partialWords?: boolean;
667
+ /**
668
+ * With this set, the engine matches each query term only against an equal
669
+ * indexed term, so it turns off fuzzy matching, prefix completion,
670
+ * partial-word matching, and synonyms. The engine still stems the query, because the
671
+ * index stores stemmed terms, so a search for `running` matches a document
672
+ * that contains `runs` through the stem that both words share.
673
+ */
674
+ exact?: boolean;
675
+ /**
676
+ * The engine counts the values of these fields across the matching
677
+ * documents, and each entry sets how it cuts and sorts that field's counts.
678
+ * For a field outside the schema, it counts the values that the documents
679
+ * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
680
+ * field.
681
+ */
682
+ facets?: FacetConfig;
683
+ /**
684
+ * The engine sorts the hits by the values of these fields, in place of the
685
+ * relevance ranking. Pass an object keyed by field, or a list of fields in
686
+ * the order that the engine compares them. The engine sorts by a `number`,
687
+ * `boolean`, or `enum` field, by a text field whose type includes
688
+ * `sortable`, or by a list of any of these, which it reduces to one value by
689
+ * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
690
+ * `geopoint` or a vector field, because neither type has an order. It throws
691
+ * the same code for a sort on any other text field, since the engine keeps
692
+ * up to the first 512 code points of every document's value in memory to
693
+ * sort by a text field. The engine orders hybrid results by fusion, so it
694
+ * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
695
+ * that code for a direction other than `asc` and `desc`.
696
+ */
697
+ sort?: SortSpec;
698
+ /** These settings collapse the hits into groups by field value. */
699
+ group?: GroupConfig;
700
+ /**
701
+ * The query returns this many hits, and 10 by default. Pass 0 to read the
702
+ * match count with no hits. The engine reads a value below 0 as 0. It falls
703
+ * back to the default for `NaN` and for an infinite value, so a page size
704
+ * that you compute from user input never fails the query.
705
+ */
706
+ limit?: number;
707
+ /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
708
+ offset?: number;
709
+ /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
710
+ searchAfter?: string;
711
+ /** These settings name the fields that come back with highlighted snippets. */
712
+ highlight?: HighlightConfig;
713
+ /** These documents take fixed positions, ahead of the ranking. */
714
+ pinned?: Array<{
715
+ /** The engine places the document with this id. */
465
716
  docId: string;
466
- error: NarsilError;
467
- }>;
468
- }
469
- /**
470
- * What {@link Narsil.importDocumentExport} returns. The engine continues past each
471
- * refused line, so read the refusals to learn which documents it skipped.
472
- *
473
- * @public
474
- */
475
- interface DocumentImportResult {
476
- /** The engine wrote this many documents, counting each one that it replaced. */
477
- imported: number;
478
- /** The engine refused this many lines in total. */
479
- refusedCount: number;
480
- /** 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. */
481
- refused: Array<{
482
- line: number;
483
- code: NarsilErrorCode;
484
- message: string;
717
+ /** The document takes this place in the results, counting from zero. */
718
+ position: number;
485
719
  }>;
486
- }
487
- /**
488
- * What {@link Narsil.getStats} returns about one index.
489
- *
490
- * @public
491
- */
492
- interface IndexStats {
493
- /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
494
- documentCount: number;
495
- /** The index is spread across this many partitions. */
496
- partitionCount: number;
720
+ /** This picks which engine answers the query. Keyword search runs by default. */
721
+ mode?: SearchMode;
722
+ /** These vector-search inputs are required in `vector` and `hybrid` mode. */
723
+ vector?: VectorQueryConfig;
724
+ /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
725
+ hybrid?: HybridConfig;
497
726
  /**
498
- * Formula-based estimate of the index's main-thread memory footprint, summed
499
- * across every partition and vector index for this index. Computed from
500
- * structural counters (document count, posting counts, field-index sizes),
501
- * not measured. Per-object V8 overhead (hidden classes, map transitions,
502
- * GC headers) is not captured here, so this number routinely undershoots
503
- * the real heap by a meaningful factor. Use {@link Narsil.getMemoryStats}
504
- * when sizing host memory.
727
+ * These settings reorder the top hits with a rerank adapter, such as a
728
+ * cross-encoder, after the keyword, vector, or hybrid ranking. The count
729
+ * matches the count of the same query without `rerank`, while the facets
730
+ * and the groups come from the first ranking. The engine throws
731
+ * `SEARCH_INVALID_MODE` for a query that also sets a sort, and
732
+ * `RERANK_FAILED` where the adapter fails or outlasts the engine's
733
+ * `rerankTimeout`.
505
734
  */
506
- estimatedMemoryBytes: number;
507
- /** The index analyses text with this language module. */
508
- language: string;
509
- /** The index was created with this field layout. */
510
- schema: SchemaDefinition;
511
- }
512
- /**
513
- * A summary of one index, as {@link Narsil.listIndexes} reports it.
514
- *
515
- * @public
516
- */
517
- interface IndexInfo {
518
- /** The index was created under this name. */
519
- name: string;
520
- /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
521
- documentCount: number;
522
- /** The index is spread across this many partitions. */
523
- partitionCount: number;
524
- /** The index analyses text with this language module. */
525
- language: string;
526
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
527
- analysisStale?: boolean;
528
- /** This is `open` in memory, `closed` after release, and `reopen-failed` after five recovery failures. */
529
- state: 'open' | 'closed' | 'reopen-failed';
530
- /** This counts successful loads since this engine started. */
531
- reopenCount: number;
532
- }
533
- /**
534
- * What {@link Narsil.getPartitionStats} reports for one partition, which is
535
- * where you look when an index grows unevenly.
536
- *
537
- * @public
538
- */
539
- interface PartitionStatsResult {
540
- /** This identifies the partition within its index. */
541
- partitionId: number;
542
- /** The partition holds this many documents. */
543
- documentCount: number;
735
+ rerank?: RerankConfig;
544
736
  /**
545
- * Formula-based estimate of this partition's memory footprint. V8 has no
546
- * per-object heap accounting API, so this number is derived from structural
547
- * counters (document count, posting counts, field-index sizes) and does not
548
- * include per-object overhead. Treat as an estimate, not a measurement.
737
+ * Setting this returns relevance scores on a sorted query. A query that
738
+ * names a sort ranks by sort values alone and computes no scores, so its
739
+ * hits carry none until this restores them. A query without a sort ignores
740
+ * this and always carries scores.
549
741
  */
550
- estimatedMemoryBytes: number;
742
+ includeScores?: boolean;
743
+ /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
744
+ includeScoreComponents?: boolean;
745
+ /** This chooses how much of each stored document comes back, and the whole document by default. */
746
+ document?: DocumentProjection;
551
747
  }
552
748
  /**
553
- * What {@link Narsil.suggest} returns: the indexed terms that complete a
554
- * prefix, ready to offer as you-type suggestions.
749
+ * How much of a stored document each hit carries back.
555
750
  *
556
- * @public
557
- */
558
- interface SuggestResult {
559
- /** These completions run most widely used first. */
560
- terms: Array<{
561
- /** This is the completed term, as the index holds it. */
562
- term: string;
563
- /** The term appears in this many documents, which is what ordered the list. */
564
- documentFrequency: number;
565
- }>;
566
- /** The lookup took this many milliseconds. */
567
- elapsed: number;
568
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
569
- analysisStale?: boolean;
570
- }
571
- /**
572
- * The state of one vector field, and what maintenance would cost, as
573
- * {@link VectorMaintenanceOperations.vectorMaintenanceStatus} reports it.
751
+ * Pass `false` when the ids and scores are all you need, and every hit's
752
+ * `document` is then an empty object. Pass `include` to keep named fields
753
+ * alone, or `exclude` to drop named fields and keep the rest; naming both
754
+ * keeps the included fields and then drops the excluded ones from those. Use
755
+ * dots to name a nested field, so `author.name` addresses the `name` inside
756
+ * `author`, and a name that matches no field changes nothing.
574
757
  *
575
- * Removing a vector leaves a tombstone in the graph, and enough of them slow a
576
- * search down. Read this to decide when compaction earns its cost.
758
+ * Drop a vector field on a similarity search, because the engine otherwise
759
+ * reads every hit's vector back out of the index and writes it into the
760
+ * response.
577
761
  *
578
762
  * @public
579
763
  */
580
- interface VectorMaintenanceResult {
581
- /** This describes the named vector field. */
582
- fieldName: string;
583
- /**
584
- * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
585
- * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
586
- * the engine divides by the number of stored vectors, because no graph
587
- * exists yet.
588
- */
589
- tombstoneRatio: number;
590
- /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
591
- graphCount: number;
592
- /** This many vectors wait outside the graph, which a search scans one by one. */
593
- bufferSize: number;
594
- /** This stays true while a graph build runs. */
595
- building: boolean;
596
- /**
597
- * This turns true while a rebuild that keeps recall up waits for the node to have
598
- * room for a second graph beside the one it serves, and false once it starts.
599
- */
600
- waitingForMemory: boolean;
601
- /**
602
- * This stays true after a restart while a field kept on disk loads its codes and graph in the
603
- * background, during which a search reads them from the field's files.
604
- */
605
- loadingFromFiles: boolean;
606
- /** {@link VectorMaintenanceOperations.compactVectors} would take about this many milliseconds. */
607
- estimatedCompactMs: number;
608
- /** {@link VectorMaintenanceOperations.optimizeVectors} would take about this many milliseconds. */
609
- estimatedOptimizeMs: number;
610
- }
764
+ type DocumentProjection = boolean | {
765
+ /** Names the fields to keep, so every field left out of this list is dropped. */
766
+ include?: string[];
767
+ /** Names the fields to drop, so every other field is kept. */
768
+ exclude?: string[];
769
+ };
611
770
  /**
612
- * One stored document, as {@link Narsil.listDocuments} returns it.
613
- *
614
- * @typeParam T - Shape of the stored document.
771
+ * Fields a query counts values for, keyed by field name.
615
772
  *
616
773
  * @public
617
774
  */
618
- interface ListedDocument<T = AnyDocument> {
619
- /** The document is stored under this id. */
620
- id: string;
621
- /** This holds the stored document, cut down to what the projection kept. */
622
- document: T;
775
+ interface FacetConfig {
776
+ /** Each key names a field the query counts values for. */
777
+ [field: string]: {
778
+ /** 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`. */
779
+ limit?: number;
780
+ /** 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. */
781
+ sort?: 'asc' | 'desc';
782
+ /** 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. */
783
+ ranges?: Array<{
784
+ /** The range starts at this value. */
785
+ from: number;
786
+ /** The range ends at this value. */
787
+ to: number;
788
+ }>;
789
+ };
623
790
  }
624
791
  /**
625
- * What {@link Narsil.listDocuments} returns: one page of stored documents and
626
- * the cursor that reaches the next one.
627
- *
628
- * @typeParam T - Shape of the stored documents.
792
+ * How a query collapses its hits into groups.
629
793
  *
630
794
  * @public
631
795
  */
632
- interface ListResult<T = AnyDocument> {
633
- /** These documents make up the page, in ascending document-id order. */
634
- documents: Array<ListedDocument<T>>;
635
- /** This opaque cursor reaches the next page, and is null once the listing is finished. */
636
- cursor: string | null;
637
- /** The listing covers this many documents in total, and any filter narrows that count. */
638
- total: number;
639
- /** The engine spent this many milliseconds building the page. */
640
- elapsed: number;
796
+ interface GroupConfig {
797
+ /** The values of these fields define a group, and several fields group by their combination. */
798
+ fields: string[];
799
+ /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
800
+ maxPerGroup?: number;
801
+ /** The engine returns this many groups, best first, and every group where you leave this out. */
802
+ limit?: number;
803
+ /**
804
+ * The engine folds every hit of each group into one value, such as a sum or
805
+ * an average, including the hits beyond `maxPerGroup`. In cluster mode the
806
+ * coordinator fetches up to 10,000 hits of each group to fold.
807
+ */
808
+ reduce?: GroupReducer;
641
809
  }
642
-
643
810
  /**
644
- * Compares one field against a value. Setting several keys narrows the match,
645
- * because a document has to satisfy all of them.
811
+ * Folds the hits of one group into a single value.
646
812
  *
647
813
  * @public
648
814
  */
649
- type ComparisonFilter = {
650
- /** This matches a field equal to the value, or a list field where one element equals it. */
651
- eq?: number | string | boolean;
815
+ type GroupReducer = {
652
816
  /**
653
- * This matches a document that holds the field with a value other than this
654
- * one, or a list field where every element differs from it, which an empty
655
- * list does.
817
+ * Folds one hit into the running value.
818
+ *
819
+ * @param accumulator - What the previous call returned, or what
820
+ * `initialValue` produced for the first hit.
821
+ * @param doc - The hit's stored document.
822
+ * @param score - The hit's relevance score.
823
+ * @returns The new running value.
656
824
  */
657
- ne?: number | string | boolean;
658
- /** This matches a field greater than the number. */
659
- gt?: number;
660
- /** This matches a field less than the number. */
661
- lt?: number;
662
- /** This matches a field greater than or equal to the number. */
663
- gte?: number;
664
- /** This matches a field less than or equal to the number. */
665
- lte?: number;
666
- /** This matches a field inside the inclusive range, given as `[low, high]`. */
667
- between?: [number, number];
825
+ reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
826
+ /** Produces the starting value for each group. The engine calls it once per group. */
827
+ initialValue: () => unknown;
668
828
  };
669
829
  /**
670
- * The engine tests a text field against this filter for equality, for a text
671
- * range, or with the set, prefix, and pattern tests.
672
- *
673
- * On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
674
- * element of the list on its own. A document passes `eq`, `in`, `startsWith`,
675
- * `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
676
- * test. However, a document passes `ne` or `nin` only when every element
677
- * differs from the values.
678
- *
679
- * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
680
- * to a single `string` or `verbatim` field whose type includes `sortable`. It
681
- * throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
682
- * orders the values as a sort on the field does, so it compares their case
683
- * folds first and compares their raw code points only where the folds are
684
- * equal.
685
- *
686
- * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
687
- * `string[]` field whose type includes `pattern`. On a pattern field, the
688
- * engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
689
- * `contains`, `wildcard`, and `regex` from the field's pattern index, and
690
- * `caseFold` applies to each of those tests. The engine compares the code
691
- * points of each value as they are stored, with no Unicode normalisation.
692
- *
693
- * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
694
- * `startsWith`, and `endsWith` from the field's index of values. A `string` or
695
- * `string[]` field whose type leaves out `pattern` keeps no index of whole
696
- * values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
697
- * and for `matchesAny` and `containsAll`, on such a field.
698
- *
699
- * The engine also throws `SEARCH_INVALID_FILTER` in these cases:
830
+ * This configuration names the fields that receive highlighted snippets. It
831
+ * also sets how the engine marks those snippets up.
700
832
  *
701
- * - The filter sets `contains`, `wildcard`, `regex`, or `caseFold` on a field
702
- * that is not a pattern field.
703
- * - The text or the pattern of a test on a pattern field holds more than 1,024
704
- * code points.
705
- * - A literal test under `caseFold` has a text whose case fold holds more than
706
- * 2,048 code points.
707
- * - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
833
+ * The engine analyses the text of each returned field again to tag every word
834
+ * that it matched, so it tags the same words whatever the index's
835
+ * `trackPositions` setting is. It tags a word whose stem equals a query stem,
836
+ * and a word within the query's `tolerance` of a query stem. For a `prefix`
837
+ * query, it tags a word for the last query term only when that word completes
838
+ * the term or shares its stem.
708
839
  *
709
840
  * @public
710
841
  */
711
- type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
712
- /** This matches a value that comes after the text in sort order. */
713
- gt?: string;
714
- /** This matches a value that comes before the text in sort order. */
715
- lt?: string;
716
- /** This matches a value equal to the text or after it in sort order. */
717
- gte?: string;
718
- /** This matches a value equal to the text or before it in sort order. */
719
- lte?: string;
720
- /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
721
- between?: [string, string];
722
- /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
723
- in?: string[];
724
- /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
725
- nin?: string[];
726
- /** This matches a field starting with the text. */
727
- startsWith?: string;
728
- /** This matches a field ending with the text. */
729
- endsWith?: string;
730
- /** This matches a pattern field whose value holds the text anywhere in it. */
731
- contains?: string;
732
- /**
733
- * This matches a pattern field when the whole value matches the wildcard
734
- * pattern. For example, `INV-*-2024` matches `INV-0042-2024`.
735
- *
736
- * In the pattern, `*` matches any sequence of code points, including an
737
- * empty one, and `?` matches exactly one code point. Write `\` before a code
738
- * point to match that code point itself, so `\*` matches an asterisk.
739
- *
740
- * The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
741
- * `\` with no code point after it. It throws the same error for a pattern
742
- * with more than 2,048 positions. Each `*`, each `?`, and each other code
743
- * point counts as one position, except that under `caseFold` a code point
744
- * counts once for each code point of its case fold.
745
- */
746
- wildcard?: string;
747
- /**
748
- * This matches a pattern field when some part of the value matches the
749
- * regular expression. `^` and `$` match only at the start and at the end of
750
- * the whole value.
751
- *
752
- * The engine accepts literal code points, `.`, `\d`, `\w`, and `\s`, sets
753
- * such as `[a-z]` and `[^0-9]`, groups, and `|`. It also accepts the repeats
754
- * `*`, `+`, `?`, `{n}`, `{n,}`, and `{n,m}`, the anchors `^` and `$`, the
755
- * word edge `\b`, and number ranges such as `<1-65535>`. A number range
756
- * matches the digits of any whole number from its low end to its high end.
757
- * Write `\` before an ASCII punctuation mark to match the mark itself. The
758
- * `.` matches any code point, including a line break.
759
- *
760
- * The matcher never backtracks, so it checks a value in at most as many
761
- * steps as the value's code points multiplied by the pattern's positions.
762
- *
763
- * The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
764
- * syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
765
- * flag. It throws the same error when the groups of a pattern nest more than
766
- * 32 deep, when a count is above 2,048, and when a pattern holds more than
767
- * 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
768
- * option to false, the server refuses every `regex` test.
769
- */
770
- regex?: string;
842
+ interface HighlightConfig {
843
+ /** The engine highlights these fields. */
844
+ fields: string[];
845
+ /** The engine writes this before each match, and writes `<mark>` by default. */
846
+ preTag?: string;
847
+ /** The engine writes this after each match, and writes `</mark>` by default. */
848
+ postTag?: string;
771
849
  /**
772
- * When this is true, the engine compares the case fold of each value of a
773
- * pattern field with the case fold of the text, so a test for `error`
774
- * matches `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`,
775
- * `endsWith`, `contains`, `wildcard`, and `regex`.
776
- *
777
- * Under `caseFold`, a set that does not open with `^` can also match a
778
- * sequence of code points. When a member that the set holds on its own folds
779
- * to several code points, the set matches that whole fold, so `[ß]` matches
780
- * `ss`.
850
+ * The engine takes this many characters of the field around the densest run
851
+ * of matches, 200 by default. It returns a snippet longer than that number,
852
+ * because it then adds the opening and closing tags, and an ellipsis at each
853
+ * end where it cuts the field.
781
854
  */
782
- caseFold?: boolean;
855
+ maxSnippetLength?: number;
856
+ }
857
+
858
+ /**
859
+ * Every code a {@link NarsilError} carries, grouped by the part of the engine
860
+ * that raises it.
861
+ *
862
+ * Match on the code rather than on the message, because a code is stable and a
863
+ * message is not. The HTTP server maps each code to a status, so a code also
864
+ * tells you whether the caller or the engine is at fault.
865
+ *
866
+ * @public
867
+ */
868
+ declare const ErrorCodes: {
869
+ readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
870
+ readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
871
+ readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
872
+ readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
873
+ readonly DOC_NOT_FOUND: "DOC_NOT_FOUND";
874
+ readonly DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS";
875
+ readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
876
+ readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
877
+ readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
878
+ readonly INDEX_ORPHANED: "INDEX_ORPHANED";
879
+ readonly INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED";
880
+ readonly INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN";
881
+ readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
882
+ readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
883
+ readonly WORKER_CRASHED: "WORKER_CRASHED";
884
+ readonly WORKER_BUSY: "WORKER_BUSY";
885
+ readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
886
+ readonly WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED";
887
+ readonly PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED";
888
+ readonly PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED";
889
+ readonly PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED";
890
+ readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
891
+ readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
892
+ readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
893
+ readonly PERSISTENCE_DEPENDENCY_MISSING: "PERSISTENCE_DEPENDENCY_MISSING";
894
+ readonly BACKUP_NOT_FOUND: "BACKUP_NOT_FOUND";
895
+ readonly BACKUP_ALREADY_EXISTS: "BACKUP_ALREADY_EXISTS";
896
+ readonly BACKUP_DAMAGED: "BACKUP_DAMAGED";
897
+ readonly BACKUP_DURABILITY_REQUIRED: "BACKUP_DURABILITY_REQUIRED";
898
+ readonly BACKUP_IN_PROGRESS: "BACKUP_IN_PROGRESS";
899
+ readonly BACKUP_STORE_CLAIMED: "BACKUP_STORE_CLAIMED";
900
+ readonly BACKUP_STORE_NOT_CONFIGURED: "BACKUP_STORE_NOT_CONFIGURED";
901
+ readonly BACKUP_NOT_READY: "BACKUP_NOT_READY";
902
+ readonly SYNC_DURABILITY_REQUIRED: "SYNC_DURABILITY_REQUIRED";
903
+ readonly SYNC_BACKUP_STORE_REQUIRED: "SYNC_BACKUP_STORE_REQUIRED";
904
+ readonly SYNC_NOT_READY: "SYNC_NOT_READY";
905
+ readonly SYNC_NOT_ENABLED: "SYNC_NOT_ENABLED";
906
+ readonly SYNC_SNAPSHOT_PREPARING: "SYNC_SNAPSHOT_PREPARING";
907
+ readonly QUERY_SUGGESTIONS_NOT_ENABLED: "QUERY_SUGGESTIONS_NOT_ENABLED";
908
+ readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
909
+ readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
910
+ readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
911
+ readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
912
+ readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
913
+ readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
914
+ readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
783
915
  /**
784
- * This lets the `eq` test of a pattern field match a value within this many
785
- * edits of the text, so a test for `INV-2O24` with a tolerance of 1 matches
786
- * `INV-2024`. An edit inserts, deletes, or replaces one code point, so a
787
- * swap of two neighbouring code points counts as two edits. With `caseFold`,
788
- * the engine counts the edits between the case folds of the value and the
789
- * text. The tolerance applies to `eq` alone, so the other tests of the field
790
- * still compare exactly.
791
- *
792
- * The engine takes its candidates from the pattern index, so the case fold
793
- * of the text has to hold enough distinct runs of three code points. For a
794
- * tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
795
- * the number of code points in the longest case fold among the text's code
796
- * points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
797
- * therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
798
- * `'auto'`, the engine uses 2 where the text holds enough runs for 2,
799
- * otherwise 1 where it holds enough for 1, and otherwise 0.
800
- *
801
- * The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
802
- * text with too few runs, stating how many runs that tolerance needs. It
803
- * throws the same error for any other tolerance, for a tolerance on a field
804
- * that is not a pattern field, and for a tolerance in a filter without an
805
- * `eq` test. Towards the pattern work cap, it counts one unit for each cell
806
- * that it fills in the table of edit distances between the text and a
807
- * value.
916
+ * An engine fault: a write changed the index during a search that held every
917
+ * write, so the search could not answer from one state. A correct engine
918
+ * never raises it, and retrying the request does not help.
808
919
  */
809
- tolerance?: 0 | 1 | 2 | 'auto';
920
+ readonly SEARCH_STATE_MOVED: "SEARCH_STATE_MOVED";
921
+ readonly SEARCH_INVALID_PHRASE: "SEARCH_INVALID_PHRASE";
922
+ readonly SEARCH_PHRASE_NOT_READY: "SEARCH_PHRASE_NOT_READY";
923
+ readonly BM25_NOT_READY: "BM25_NOT_READY";
924
+ readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
925
+ readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
926
+ readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
927
+ readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
928
+ readonly RESTORE_MEMORY_EXCEEDED: "RESTORE_MEMORY_EXCEEDED";
929
+ readonly MEMORY_WRITE_BLOCKED: "MEMORY_WRITE_BLOCKED";
930
+ readonly ANALYSIS_CHANGE_REPLACED: "ANALYSIS_CHANGE_REPLACED";
931
+ readonly ANALYSIS_CHANGE_NOT_READY: "ANALYSIS_CHANGE_NOT_READY";
932
+ readonly ANALYSIS_GENERATION_MISSING: "ANALYSIS_GENERATION_MISSING";
933
+ readonly ANALYSIS_REBUILD_MEMORY_EXCEEDED: "ANALYSIS_REBUILD_MEMORY_EXCEEDED";
934
+ readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
935
+ readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
936
+ readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
937
+ readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
938
+ readonly RERANK_FAILED: "RERANK_FAILED";
939
+ readonly RERANK_CONFIG_INVALID: "RERANK_CONFIG_INVALID";
940
+ readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
941
+ readonly CONFIG_INVALID: "CONFIG_INVALID";
942
+ readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
943
+ readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
944
+ readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
945
+ readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
946
+ readonly SEARCH_CONTEXT_MISSING: "SEARCH_CONTEXT_MISSING";
947
+ readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
948
+ readonly CLUSTER_WRITE_BLOCKED: "CLUSTER_WRITE_BLOCKED";
949
+ readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
950
+ readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
951
+ readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
952
+ readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
953
+ readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
954
+ readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
955
+ readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
956
+ readonly NODE_NOT_READY: "NODE_NOT_READY";
957
+ readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
958
+ readonly NODE_VERSION_INCOMPATIBLE: "NODE_VERSION_INCOMPATIBLE";
959
+ readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
960
+ readonly COORDINATOR_AUTH_FAILED: "COORDINATOR_AUTH_FAILED";
961
+ readonly COORDINATOR_UNAVAILABLE: "COORDINATOR_UNAVAILABLE";
962
+ readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
963
+ readonly NATIVE_DEPENDENCY_MISSING: "NATIVE_DEPENDENCY_MISSING";
964
+ readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
965
+ readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
966
+ readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
967
+ readonly REPLICATION_OUTCOME_UNKNOWN: "REPLICATION_OUTCOME_UNKNOWN";
968
+ readonly REPLICATION_WRITE_CONFLICT: "REPLICATION_WRITE_CONFLICT";
969
+ readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
970
+ readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
971
+ readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
972
+ readonly REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH";
973
+ readonly REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED";
974
+ readonly PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY";
975
+ readonly PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED";
976
+ readonly INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS";
977
+ readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
978
+ readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
979
+ readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
980
+ readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
981
+ readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
982
+ readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
983
+ readonly SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID";
984
+ readonly SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID";
985
+ readonly SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH";
986
+ readonly SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER";
987
+ readonly SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW";
988
+ readonly SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED";
989
+ readonly SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING";
990
+ readonly SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING";
991
+ readonly SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH";
992
+ readonly SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR";
993
+ readonly SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS";
994
+ readonly SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED";
995
+ readonly SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE";
996
+ readonly SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED";
997
+ readonly SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED";
998
+ readonly SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT";
999
+ readonly SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE";
1000
+ readonly SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED";
1001
+ readonly SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED";
810
1002
  };
811
1003
  /**
812
- * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
813
- * `enum[]`, `verbatim[]`, or `string[]` field.
814
- *
815
- * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
816
- * field, for a value whose type differs from the type of the list's elements,
817
- * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
818
- * out `pattern`.
1004
+ * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
1005
+ * when you branch on a failure the engine raised.
819
1006
  *
820
1007
  * @public
821
1008
  */
822
- type ArrayFilter = {
823
- /** 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. */
824
- containsAll?: (string | number | boolean)[];
825
- /** This matches a list holding at least one of the values, at most 65,536 of them. */
826
- matchesAny?: (string | number | boolean)[];
827
- /** This compares the number of elements in the list. */
828
- size?: ComparisonFilter;
829
- };
1009
+ type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
830
1010
  /**
831
- * Tests whether a field carries a value at all, without looking at what it
832
- * holds.
1011
+ * Every code the HTTP layer raises for a failure that arises before or around
1012
+ * the engine call, such as parsing the body, enforcing a limit, or routing.
1013
+ *
1014
+ * The engine raises none of these, so a failure carrying one of them says the
1015
+ * request never reached the engine.
833
1016
  *
834
1017
  * @public
835
1018
  */
836
- type PresenceFilter = {
837
- /** This matches a document where the field holds a value other than null. */
838
- exists?: boolean;
839
- /** This matches a document where the field is absent or null. */
840
- notExists?: boolean;
841
- /** This matches a document where the field is absent, null, an empty string, or an empty list. */
842
- isEmpty?: boolean;
843
- /** This matches a document where the field holds a value other than an empty string or an empty list. */
844
- isNotEmpty?: boolean;
1019
+ declare const ServerErrorCodes: {
1020
+ readonly INVALID_REQUEST: "INVALID_REQUEST";
1021
+ readonly INVALID_JSON: "INVALID_JSON";
1022
+ readonly EMPTY_BODY: "EMPTY_BODY";
1023
+ readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
1024
+ readonly NOT_FOUND: "NOT_FOUND";
1025
+ readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
1026
+ readonly TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE";
1027
+ readonly TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE";
1028
+ readonly TASK_INTERRUPTED: "TASK_INTERRUPTED";
1029
+ readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
1030
+ readonly HOOK_ERROR: "HOOK_ERROR";
1031
+ readonly INTERNAL_ERROR: "INTERNAL_ERROR";
845
1032
  };
846
1033
  /**
847
- * Matches a `geopoint` field against a circle drawn on the earth.
1034
+ * Any one of the codes in {@link ServerErrorCodes}.
848
1035
  *
849
1036
  * @public
850
1037
  */
851
- type GeoRadiusFilter = {
852
- /** The engine tests the field against this circle. */
853
- radius: {
854
- /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
855
- lat: number;
856
- /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
857
- lon: number;
858
- /** The circle has this radius, measured in `unit`. */
859
- distance: number;
860
- /**
861
- * The engine measures `distance` in kilometres under `'km'`, in miles
862
- * under `'mi'`, and in metres under `'m'`. For any other unit, it throws
863
- * `SEARCH_INVALID_FILTER`.
864
- */
865
- unit: 'km' | 'mi' | 'm';
866
- /** 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. */
867
- inside?: boolean;
868
- /**
869
- * The engine measures each distance with the Haversine formula on a sphere
870
- * by default, and with Vincenty's formula on the WGS-84 ellipsoid while
871
- * this is true. Vincenty's formula iterates, so the engine takes longer
872
- * to compute each distance. The two formulas differ by less than 0.3% under about
873
- * 100 km, while across a continent they can differ by up to 0.5%.
874
- */
875
- highPrecision?: boolean;
876
- };
877
- };
1038
+ type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
878
1039
  /**
879
- * Matches a `geopoint` field against a polygon drawn on the earth.
1040
+ * Every code that the caller's own side raises, where a request never reaches
1041
+ * a server, or where the caller cannot read the answer.
1042
+ *
1043
+ * The HTTP client raises the first five. The React bindings raise
1044
+ * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. A
1045
+ * synced device raises `SYNC_ANALYSIS_UNAVAILABLE` before it downloads a
1046
+ * snapshot whose language, tokeniser, or stop words it has not registered,
1047
+ * and it keeps its copy of the index. No server sends any of them, so a failure under one means the exchange broke
1048
+ * before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
1049
+ * therefore maps none of them, because no request can arrive under one and no
1050
+ * HTTP status belongs to one.
880
1051
  *
881
1052
  * @public
882
1053
  */
883
- type GeoPolygonFilter = {
884
- /** The engine tests the field against this polygon. */
885
- polygon: {
886
- /**
887
- * The engine closes the ring through these corners in the order that you
888
- * list them, so you can leave the first point off the end. It throws
889
- * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
890
- * encloses no area, and for a corner whose latitude is outside -90 to 90
891
- * or whose longitude is outside -180 to 180. It also throws that error for
892
- * a ring of more than 65,536 corners. List the corners counter-clockwise
893
- * around the area, as in an exterior ring of GeoJSON. Where the corners
894
- * span 180 degrees of longitude or more, the engine matches the area on
895
- * the left of that path, so a ring listed that way can cross the
896
- * antimeridian or span more than half the globe.
897
- */
898
- points: Array<{
899
- /** The corner has this latitude, in degrees. */
900
- lat: number;
901
- /** The corner has this longitude, in degrees. */
902
- lon: number;
903
- }>;
904
- /** 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. */
905
- inside?: boolean;
906
- };
1054
+ declare const ClientErrorCodes: {
1055
+ readonly CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED";
1056
+ readonly CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT";
1057
+ readonly CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED";
1058
+ readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
1059
+ readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
1060
+ readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
1061
+ readonly SYNC_ANALYSIS_UNAVAILABLE: "SYNC_ANALYSIS_UNAVAILABLE";
907
1062
  };
908
1063
  /**
909
- * Either shape a `geopoint` field is matched against.
1064
+ * Any one of the codes in {@link ClientErrorCodes}.
910
1065
  *
911
1066
  * @public
912
1067
  */
913
- type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
1068
+ type ClientErrorCode = (typeof ClientErrorCodes)[keyof typeof ClientErrorCodes];
914
1069
  /**
915
- * The filter one field accepts. Which of these forms applies follows from the
916
- * field's declared type.
1070
+ * Every code a {@link NarsilError} can carry: one the engine raised, one the
1071
+ * HTTP layer raised, one the client raised, or any other string.
1072
+ *
1073
+ * The last arm exists for a server's `onRequest` hook, which rejects a request
1074
+ * under a code of its own, such as `UNAUTHORIZED`, and the client then passes
1075
+ * that code through unchanged. An editor still completes every code Narsil
1076
+ * defines.
917
1077
  *
918
1078
  * @public
919
1079
  */
920
- type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
1080
+ type NarsilErrorCode = ErrorCode | ServerErrorCode | ClientErrorCode | (string & {});
921
1081
  /**
922
- * The filter that a query runs, built from per-field tests and the boolean
923
- * operators that combine them.
1082
+ * The error every part of the engine throws.
924
1083
  *
925
- * The engine answers every test from an index that it keeps for the field. It
926
- * applies the filter before scoring, so a narrow filter makes a search
927
- * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
928
- * tests, counted across every field and nested expression. Past either limit,
929
- * the engine throws `SEARCH_INVALID_FILTER`, while it throws
930
- * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
1084
+ * Catch it, read {@link NarsilError.code} to decide what to do, and read
1085
+ * {@link NarsilError.details} for the values that caused it. The engine lets
1086
+ * this error propagate unchanged, so the code you catch is the code the
1087
+ * failing operation raised.
931
1088
  *
932
1089
  * @public
933
1090
  */
934
- type FilterExpression = {
935
- /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
936
- fields?: Record<string, FieldFilter>;
937
- /** Every nested expression has to match. */
938
- and?: FilterExpression[];
939
- /** At least one nested expression has to match. */
940
- or?: FilterExpression[];
941
- /** The nested expression has to fail. */
942
- not?: FilterExpression;
943
- };
944
-
1091
+ declare class NarsilError extends Error {
1092
+ /** This says which failure it is. */
1093
+ readonly code: NarsilErrorCode;
1094
+ /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
1095
+ readonly details: Record<string, unknown>;
1096
+ /**
1097
+ * Builds an error carrying a code the caller can branch on.
1098
+ *
1099
+ * @param code - The failure this error reports, from {@link ErrorCodes} for
1100
+ * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
1101
+ * or {@link ClientErrorCodes} for one that stopped a request from reaching a
1102
+ * server.
1103
+ * @param message - Plain description, for a log or a person.
1104
+ * @param details - Values behind the failure, which reach
1105
+ * {@link NarsilError.details}.
1106
+ */
1107
+ constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
1108
+ }
945
1109
  /**
946
- * How a query reorders its top hits with a rerank adapter.
1110
+ * Reports whether a caught value is a {@link NarsilError}, including one that
1111
+ * another entry point of this package raises.
947
1112
  *
948
- * The engine ranks the query as it would without this setting, passes the
949
- * top `window` hits to the adapter, and orders them by the adapter's scores.
950
- * The hits past the window follow in their first ranking, with their scores
951
- * scaled below the lowest reranked score, so every page of one query comes
952
- * from the same order.
1113
+ * Each browser bundle holds its own copy of the class, so an `instanceof` test
1114
+ * inside the React bindings returns false for an error that the client raises,
1115
+ * although that error still holds its code. This function tests for the marker
1116
+ * that the constructor writes, so it returns true for an error from any entry
1117
+ * point.
1118
+ *
1119
+ * @param value - The value that a `catch` block receives.
1120
+ * @returns True where the value holds a code in {@link NarsilError.code}.
953
1121
  *
954
1122
  * @public
955
1123
  */
956
- interface RerankConfig {
957
- /**
958
- * The engine scores the hits with the rerank adapter registered under this
959
- * key. It throws `RERANK_CONFIG_INVALID` for a key that it has not
960
- * registered.
961
- */
962
- adapter: string;
963
- /**
964
- * The engine sends the adapter the values of these text fields, in this
965
- * order and joined with newlines, as the text of each hit. Each member of a
966
- * list field takes a line of its own. The engine throws
967
- * `RERANK_CONFIG_INVALID` for an empty list, for a field that the schema
968
- * does not declare as text, and for a field that the list gives twice.
969
- */
970
- fields: string[];
971
- /**
972
- * The adapter compares each hit with this text. Where you leave it out, the
973
- * engine sends the query's `term`, or else its `vector.text`, and it throws
974
- * `RERANK_CONFIG_INVALID` where the query carries neither.
975
- */
976
- query?: string;
977
- /**
978
- * The engine reranks this many of the top hits, from 1 to the engine's
979
- * `maxRerankWindow`. Where you leave the window out, the engine reranks the
980
- * smallest of 100 and `maxRerankWindow`, and no more than the `hybrid.depth`
981
- * of a hybrid query that sets one. A hybrid query that sets `hybrid.depth`
982
- * reranks its fused list at that depth, so the engine throws
983
- * `RERANK_CONFIG_INVALID` when you set a window above that depth.
984
- */
985
- window?: number;
986
- }
1124
+ declare function isNarsilError(value: unknown): value is NarsilError;
987
1125
 
988
1126
  /**
989
- * Vector-search inputs passed under `QueryParams.vector`.
1127
+ * What {@link Narsil.query} returns: the ranked hits and everything the query
1128
+ * asked for alongside them.
990
1129
  *
991
- * Supply either a raw `value` array or a `text` string for auto-embedding;
992
- * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
993
- * by the outer query's `limit`, not by any field on this object.
1130
+ * @typeParam T - Shape of the stored documents, which flows through to each
1131
+ * hit's `document`.
994
1132
  *
995
1133
  * @public
996
1134
  */
997
- interface VectorQueryConfig {
998
- /**
999
- * Name of the schema field that holds the vector to compare against.
1000
- * Must reference a field declared as `vector[N]` in the index schema.
1001
- */
1002
- field: string;
1003
- /**
1004
- * Raw query vector, given as a number array or a `Float32Array`. Length
1005
- * must match the indexed field's dimension or the search rejects the
1006
- * request with `VECTOR_DIMENSION_MISMATCH`.
1007
- */
1008
- value?: number[] | Float32Array;
1009
- /**
1010
- * Text to embed at query time using the index or instance embedding
1011
- * adapter. Mutually exclusive with `value`; requires a configured adapter.
1012
- */
1013
- text?: string;
1014
- /**
1015
- * Score floor applied during ranking. Hits scoring below this value
1016
- * are dropped before `limit` is enforced, so the returned hit count
1017
- * can be smaller than `limit` even when more documents exist. The
1018
- * floor is interpreted in score space for every metric; for
1019
- * `euclidean`, distance is mapped to a similarity score of
1020
- * `1 / (1 + distance)` first. Defaults to no floor.
1021
- */
1022
- similarity?: number;
1023
- /**
1024
- * Similarity metric used for ranking. Defaults to `cosine`. Choose
1025
- * `dotProduct` for raw inner-product scoring on already-normalised
1026
- * vectors and `euclidean` for distance-based ordering.
1027
- */
1028
- metric?: 'cosine' | 'dotProduct' | 'euclidean';
1135
+ interface QueryResult<T = AnyDocument> {
1136
+ /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
1137
+ hits: Array<Hit<T>>;
1029
1138
  /**
1030
- * The engine keeps this many candidates as it walks the HNSW graph, so a
1031
- * higher value can find more of the true neighbours, although each query
1032
- * takes longer. The engine applies it only once the field holds a graph.
1033
- * The engine fetches k hits, where k is one more than the number of hits up
1034
- * to the end of the page, so k is `limit` plus 1 on a first page. When a
1035
- * query leaves `efSearch` unset, the engine keeps the larger of 50 and k
1036
- * plus a margin, where the margin is 50 below 768 dimensions, 75 from 768
1037
- * to 1,023 dimensions, and 0 at 1,024 dimensions and above. Under a
1038
- * filter, the engine counts only the candidates that pass the filter.
1139
+ * This many documents match in total, before the engine applies `limit`
1140
+ * and `offset`. For a keyword search the engine counts every match. For a
1141
+ * vector search it counts every vector that passes the query's filter and
1142
+ * its `similarity` floor, which is every vector in the field where the query
1143
+ * sets neither of them. The engine also counts each pinned document that
1144
+ * the query does not match, since it places that document among the hits.
1039
1145
  */
1040
- efSearch?: number;
1146
+ count: number;
1041
1147
  /**
1042
- * The engine re-scores this many times k candidates in a quantized field
1043
- * against the full-precision vectors before it returns the best `limit`,
1044
- * where k is one more than the number of hits up to the end of the page, so
1045
- * k is `limit` plus 1 on a first page. For a value below 1, or for a value
1046
- * that is not a finite number, the engine throws a `NarsilError` with code
1047
- * `CONFIG_INVALID`. The engine ignores it on a field whose quantization is
1048
- * `none`. When a query leaves it unset, the engine sets the number of
1049
- * candidates that it re-scores from k and from the field's dimension. It
1050
- * rounds that number up, and it re-scores at least 3k candidates under
1051
- * `osq1` and `osq2`, and at least k under `osq4` and `osq8`. Below 768
1052
- * dimensions, it re-scores 3.23k + 55.9√k under `osq1` and 2.6k + 22.5√k under
1053
- * `osq2`. From 768 to 1,023 dimensions, it re-scores 2.2k + 27√k under
1054
- * `osq1` and k + 16√k under `osq2`, and under `osq2` it re-scores at least
1055
- * the smaller of k + 75 and k + 18√k. At 1,024 dimensions and above, it
1056
- * re-scores 3k under both. Under `osq4`, it re-scores 5k below 1,024
1057
- * dimensions and 2k from 1,024 dimensions, while under `osq8` it re-scores
1058
- * 2k at every dimension. Under a filter, the engine counts only the
1059
- * candidates that pass the filter. On vectors spread evenly across every
1060
- * dimension, a one-bit or two-bit code can find fewer than 95% of the true
1061
- * nearest neighbours at these defaults, so raise `oversample` on a query that
1062
- * needs more of them.
1148
+ * `count` holds the exact number of matches where this is true, and a
1149
+ * number at or below the true total where it is false. Where a query sets a
1150
+ * `similarity` floor on a vector field that holds a graph, the engine
1151
+ * counts only the vectors that it fetches, because it compares the query
1152
+ * with only a fraction of that field's vectors. For a hybrid query the
1153
+ * engine fuses two rankings, so the count is exact only where each of those
1154
+ * rankings contains every matching document. Where you pin a document from
1155
+ * outside the hits that the engine fetches, the engine reports true only
1156
+ * where it holds every match of the query, because only then can it test
1157
+ * whether the query matches that document.
1063
1158
  */
1064
- oversample?: number;
1159
+ countExact: boolean;
1160
+ /** The engine spent this many milliseconds on the search. */
1161
+ elapsed: number;
1162
+ /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
1163
+ cursor?: string;
1164
+ /** These facet counts are keyed by the field each facet was asked for. */
1165
+ facets?: Record<string, FacetResult>;
1166
+ /** These groups arrive when the query asked for grouping. */
1167
+ groups?: GroupResult[];
1168
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1169
+ analysisStale?: boolean;
1170
+ /** The search read this much of the index, which is how you spot a degraded answer. */
1171
+ coverage: QueryCoverage;
1065
1172
  }
1066
1173
  /**
1067
- * How a hybrid query merges its keyword ranking with its vector ranking.
1068
- *
1069
- * `rrf` combines the two by rank alone, which needs no tuning and handles
1070
- * scores that live on different scales. `linear` blends the scores directly,
1071
- * which gives you control once you know what each side's scores look like.
1174
+ * How much of an index one search read, which is what you check before you
1175
+ * trust a count or a ranking.
1072
1176
  *
1073
- * @public
1074
- */
1075
- interface HybridConfig {
1076
- /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
1077
- strategy?: 'rrf' | 'linear';
1078
- /** 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. */
1079
- k?: number;
1080
- /** 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. */
1081
- alpha?: number;
1082
- /**
1083
- * Set a depth to get the same fused order on every page of one query, and
1084
- * a cursor that resumes it. The engine then fetches this many results from
1085
- * the keyword search and from the vector search, fuses them, and pages
1086
- * through the top `depth` of the fused list. The last page stops at this
1087
- * depth, so it can hold fewer hits than the limit. Set a whole number from 1
1088
- * to 10,000. The engine throws `CONFIG_INVALID` for any other value, and
1089
- * `SEARCH_RESULT_WINDOW_EXCEEDED` for a page that starts at this depth or
1090
- * beyond. Where you leave the depth out, each search fetches only enough
1091
- * results to fill the page, so the fused order can change from one page to
1092
- * the next, and a cluster refuses a cursor with `SEARCH_INVALID_CURSOR`.
1093
- */
1094
- depth?: number;
1095
- }
1096
-
1097
- /**
1098
- * Everything {@link Narsil.suggest} accepts.
1177
+ * An embedded engine reads every partition it holds, so `queriedPartitions`
1178
+ * matches `totalPartitions` there and the other two stay zero. A search across
1179
+ * a cluster may find a node slow or unreachable, which it counts here while
1180
+ * still returning the hits the other nodes gave it.
1099
1181
  *
1100
1182
  * @public
1101
1183
  */
1102
- interface SuggestParams {
1103
- /** The returned terms complete this text. */
1104
- prefix: string;
1105
- /** The lookup returns this many completions, most widely used first, and 10 by default. */
1106
- limit?: number;
1184
+ interface QueryCoverage {
1185
+ /** The search should have read this many partitions. */
1186
+ totalPartitions: number;
1187
+ /** The search read this many of them. */
1188
+ queriedPartitions: number;
1189
+ /** The search counts a partition here when the node holding it took longer than the query allowed. */
1190
+ timedOutPartitions: number;
1191
+ /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
1192
+ failedPartitions: number;
1107
1193
  }
1108
1194
  /**
1109
- * Everything {@link Narsil.listDocuments} accepts.
1110
- *
1111
- * {@link Narsil.listDocuments} reads the stored documents without ranking them,
1112
- * which is how you page through a whole index. Leave `cursor` out to start at
1113
- * the first document, then pass back the cursor each result carries until it
1114
- * comes back null.
1195
+ * One matching document, with the score that ranked it.
1115
1196
  *
1116
- * A cursor belongs to the sort it was made under, so pass the same `sort` back
1117
- * with it. Changing `sort` invalidates the cursor, and the engine then throws
1118
- * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
1197
+ * @typeParam T - Shape of the stored document.
1119
1198
  *
1120
1199
  * @public
1121
1200
  */
1122
- interface ListParams {
1123
- /**
1124
- * This cursor comes from a previous result, and continues where it stopped.
1125
- * The engine ties a cursor to the sort that produced it, and it throws
1126
- * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
1127
- */
1128
- cursor?: string;
1129
- /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
1130
- limit?: number;
1131
- /** This narrows the listing to the documents the filter accepts. */
1132
- filters?: FilterExpression;
1201
+ interface Hit<T = AnyDocument> {
1202
+ /** The document is stored under this id. */
1203
+ id: string;
1133
1204
  /**
1134
- * This orders the listing by field value rather than by document id, and the
1135
- * engine applies the fields in the order they are listed. Pass an object
1136
- * keyed by field, or a list of fields in the order they apply. It breaks a
1137
- * tie on document id, and it sorts by at most eight fields. The engine uses
1138
- * document-id order when you leave this out.
1139
- *
1140
- * The engine reads every document the listing covers to build a sorted page,
1141
- * so a sorted listing costs more than the default order on a large index.
1205
+ * This score ranked the hit. Scores compare within one result set, never
1206
+ * across searches. A sorted query ranks by sort values instead and carries
1207
+ * no score unless it sets `includeScores`.
1142
1208
  */
1143
- sort?: SortSpec;
1144
- /** This chooses how much of each stored document comes back, and the whole document by default. */
1145
- document?: DocumentProjection;
1209
+ score?: number;
1210
+ /** This is the stored document. */
1211
+ document: T;
1212
+ /** These are the parts the score was built from, which arrive when the query asked for them. */
1213
+ scoreComponents?: ScoreComponents;
1214
+ /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
1215
+ highlights?: Record<string, HighlightMatch>;
1146
1216
  }
1147
-
1148
1217
  /**
1149
- * Which engine answers a query: keyword matching, vector similarity, or both
1150
- * merged into one ranking.
1218
+ * The numbers BM25 combined into one hit's score, which is what you read when
1219
+ * a ranking surprises you.
1151
1220
  *
1152
1221
  * @public
1153
1222
  */
1154
- type SearchMode = 'fulltext' | 'vector' | 'hybrid';
1223
+ interface ScoreComponents {
1224
+ /**
1225
+ * Each query term appears in one field of this document this many times,
1226
+ * under a key of `field:term`. A term that appears in two fields therefore
1227
+ * has two entries here, while the keys of {@link ScoreComponents.idf} hold
1228
+ * the bare term.
1229
+ */
1230
+ termFrequencies: Record<string, number>;
1231
+ /** Each field the query searched holds this many tokens, keyed by field. */
1232
+ fieldLengths: Record<string, number>;
1233
+ /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
1234
+ idf: Record<string, number>;
1235
+ }
1155
1236
  /**
1156
- * How many of a query's terms a document has to carry. `all` demands every
1157
- * term, `any` accepts one, and a number demands that many.
1237
+ * A highlighted field, ready to render.
1158
1238
  *
1159
1239
  * @public
1160
1240
  */
1161
- type TermMatchPolicy = 'all' | 'any' | number;
1241
+ interface HighlightMatch {
1242
+ /** This is the field's text around the match, wrapped in the query's tags. */
1243
+ snippet: string;
1244
+ /**
1245
+ * Each range gives the start and the end of one match in the original field,
1246
+ * so you can render the highlight yourself. Where the snippet covers part of
1247
+ * the field alone, the engine lists only the matches that the snippet
1248
+ * displays. Every offset is a character count from the start of the original
1249
+ * field, whatever the snippet contains.
1250
+ */
1251
+ positions: Array<{
1252
+ /** The match starts at this offset. */
1253
+ start: number;
1254
+ /** The match ends at this offset. */
1255
+ end: number;
1256
+ }>;
1257
+ }
1162
1258
  /**
1163
- * One field of a sort, and the direction that field orders by.
1259
+ * Counts for one faceted field.
1164
1260
  *
1165
1261
  * @public
1166
1262
  */
1167
- interface SortField {
1168
- /** The field the engine reads, which may name a nested field with dots. */
1169
- field: string;
1170
- /** Ascending or descending order for this field. */
1171
- direction: 'asc' | 'desc';
1263
+ interface FacetResult {
1264
+ /** This many documents match per value, keyed by value. */
1265
+ values: Record<string, number>;
1266
+ /** This is the number of entries in `values`, which is at most the facet's `limit`. */
1267
+ count: number;
1172
1268
  /**
1173
- * Where a document's field holds a list, the engine sorts that document by
1174
- * one value from the list: the smallest under `'min'`, the largest under
1175
- * `'max'`, and the mean or the median of the list's numbers under `'avg'`
1176
- * or `'median'`. Where you leave this out, the engine uses `'min'` for an
1177
- * ascending sort and `'max'` for a descending one. It sorts by a field that
1178
- * holds a single value as that value stands, under every mode. It throws
1179
- * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
1180
- * schema declares as anything other than `number` or `number[]`.
1269
+ * Every count in `values` is at most this far below its true count. A value
1270
+ * that the engine leaves out of `values` because of `limit` has a true
1271
+ * count of at most this figure too. Where the engine counts a field on one
1272
+ * thread, it counts every value exactly, so this figure is the largest
1273
+ * count that it leaves out. Where it splits the count across worker copies
1274
+ * or cluster nodes, each of them returns only its own top values, so the
1275
+ * merged count of a value that is common overall but rare on one of them
1276
+ * can lack the matches on that one. A bound of 0 means that `values` holds
1277
+ * every matching value, each with its exact count.
1181
1278
  */
1182
- mode?: 'min' | 'max' | 'avg' | 'median';
1279
+ errorBound: number;
1183
1280
  }
1184
1281
  /**
1185
- * A sort, either as an object keyed by field or as a list of fields in the
1186
- * order they apply.
1187
- *
1188
- * Both forms order by the first field, break a tie on the second, and carry on
1189
- * that way. Prefer the list where the order of the fields matters, because
1190
- * JavaScript moves an all-digit key such as `2024` to the front of an object
1191
- * and the list keeps the order you wrote.
1282
+ * One group of hits, produced by a query that grouped its results.
1192
1283
  *
1193
1284
  * @public
1194
1285
  */
1195
- type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
1286
+ interface GroupResult {
1287
+ /** Each grouping field holds this value for the group, keyed by field. */
1288
+ values: Record<string, unknown>;
1289
+ /** These hits fall in the group, cut to the query's `maxPerGroup`. */
1290
+ hits: Array<Hit>;
1291
+ /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
1292
+ reduced?: unknown;
1293
+ /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
1294
+ reducerError?: string;
1295
+ }
1196
1296
  /**
1197
- * Everything {@link Narsil.query} accepts.
1297
+ * What {@link Narsil.preflight} returns: how many documents a query matches,
1298
+ * without building or ranking a single hit.
1198
1299
  *
1199
- * Set `term` for keyword search, `vector` for similarity search, and `mode`
1200
- * when you want both. The engine matches nothing for a query carrying neither
1201
- * of them, so page through an index with {@link Narsil.listDocuments}
1202
- * instead.
1300
+ * @public
1301
+ */
1302
+ interface PreflightResult {
1303
+ /** The query matches this many documents. */
1304
+ count: number;
1305
+ /** `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}. */
1306
+ countExact: boolean;
1307
+ /** The count took this many milliseconds. */
1308
+ elapsed: number;
1309
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1310
+ analysisStale?: boolean;
1311
+ }
1312
+ /**
1313
+ * What a batch write returns. One bad document never abandons the rest, so
1314
+ * read both lists.
1203
1315
  *
1204
1316
  * @public
1205
1317
  */
1206
- interface QueryParams {
1207
- /**
1208
- * The engine analyses this text with the index's language module and searches
1209
- * for the terms that result. Words inside double quotes form a phrase, which
1210
- * a document has to hold side by side and in that order inside one field. The
1211
- * engine throws `SEARCH_INVALID_PHRASE` for a phrase of more than 32 words, for
1212
- * more than 32 phrases, and for a phrase on an index with `trackPositions` off.
1213
- * It throws `SEARCH_PHRASE_NOT_READY` while an index with a `string[]` field
1214
- * waits for a rebuild.
1215
- */
1216
- term?: string;
1217
- /** The engine searches the term in these fields, and in every text field in the schema by default. */
1218
- fields?: string[];
1219
- /**
1220
- * The engine scores only the documents that pass this filter. It throws
1221
- * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
1222
- * operator on a field of another type, such as `startsWith` on a number
1223
- * field.
1224
- */
1225
- filters?: FilterExpression;
1226
- /**
1227
- * The engine multiplies the score from each named field by its weight. It
1228
- * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
1229
- * the schema declares, and `CONFIG_INVALID` for a weight that is not a
1230
- * finite number.
1231
- */
1232
- boost?: Record<string, number>;
1233
- /**
1234
- * These BM25 parameters score this search alone, and they override the
1235
- * index's parameters, so a `k1` here also overrides a `k1` that the index
1236
- * sets for a field. The engine validates them on every search, and it throws
1237
- * the same errors as {@link IndexConfig.bm25}, except `SEARCH_INVALID_FIELD`
1238
- * for a name in `fields` that is not a text field. They change no score on a
1239
- * vector search, and on a hybrid search they apply to the keyword ranking
1240
- * alone. A cursor pages only a search with the same parameters.
1241
- */
1242
- bm25?: BM25Params;
1243
- /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
1244
- scoring?: ScoringMode;
1245
- /**
1246
- * The engine drops any hit scoring below this value. It ranks with BM25,
1247
- * which has no fixed upper bound, so a floor that suits one index and one
1248
- * query can reject every hit in another.
1249
- */
1250
- minScore?: number;
1251
- /**
1252
- * The engine keeps a document only where the document matches this many
1253
- * query terms, under the same `tolerance` and `prefixLength` that the search
1254
- * uses. One term is enough by default.
1255
- */
1256
- termMatch?: TermMatchPolicy;
1257
- /**
1258
- * The engine matches an indexed term within this edit distance of a query
1259
- * term, so it finds a document for a query with a typo. It counts each
1260
- * Unicode code point as one character. Set an integer from 0 to 10.
1261
- */
1262
- tolerance?: number;
1263
- /**
1264
- * The engine applies `tolerance` only to the indexed terms that share this
1265
- * many leading characters with the query term, or to the terms that start
1266
- * with the whole query term when the query term is shorter. Set an integer
1267
- * from 0 to 1,024; the default is 2.
1268
- */
1269
- prefixLength?: number;
1270
- /**
1271
- * With this set, the engine treats the last query term as an unfinished
1272
- * word, so `secur` matches `security`. The engine matches that last term by
1273
- * its stem or by completing it, while `tolerance` applies only to the earlier
1274
- * terms, which have to match whole. The engine scores completions against a
1275
- * shared document frequency. It also ranks them below whole-word matches.
1276
- * The engine ignores this setting where `exact` is true, and the setting is
1277
- * false by default.
1278
- */
1279
- prefix?: boolean;
1280
- /**
1281
- * With this set, the engine also matches each query word of three or more
1282
- * characters inside the longer words of every field whose type includes
1283
- * `partial`, so a search for `proof` matches a document with `waterproof`
1284
- * in such a field. The engine counts each Unicode code point as one
1285
- * character. It looks for the query word, before stemming, inside each word
1286
- * exactly as that word appears in a document.
1287
- *
1288
- * The engine adds at most 50 such words to a query, which it divides as
1289
- * evenly as it can among the query words. Within the share of each query
1290
- * word, it adds first the words that the most documents contain. It scores
1291
- * a match inside a longer word in proportion to the part of that word that
1292
- * the query word makes up, so it scores such a match below a whole-word
1293
- * match at the same frequency in a field of the same length. With
1294
- * `highlight`, it tags each whole word that contains a query word in a
1295
- * searched `partial` field.
1296
- *
1297
- * The engine applies no `tolerance` to these matches. It ignores this
1298
- * setting where `exact` is true or where the searched fields include no
1299
- * `partial` field. Where the setting is absent, the engine treats it as
1300
- * false, while it throws `CONFIG_INVALID` for any value other than `true`
1301
- * or `false`.
1302
- */
1303
- partialWords?: boolean;
1304
- /**
1305
- * With this set, the engine matches each query term only against an equal
1306
- * indexed term, so it turns off fuzzy matching, prefix completion,
1307
- * partial-word matching, and synonyms. The engine still stems the query, because the
1308
- * index stores stemmed terms, so a search for `running` matches a document
1309
- * that contains `runs` through the stem that both words share.
1310
- */
1311
- exact?: boolean;
1312
- /**
1313
- * The engine counts the values of these fields across the matching
1314
- * documents, and each entry sets how it cuts and sorts that field's counts.
1315
- * For a field outside the schema, it counts the values that the documents
1316
- * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
1317
- * field.
1318
- */
1319
- facets?: FacetConfig;
1320
- /**
1321
- * The engine sorts the hits by the values of these fields, in place of the
1322
- * relevance ranking. Pass an object keyed by field, or a list of fields in
1323
- * the order that the engine compares them. The engine sorts by a `number`,
1324
- * `boolean`, or `enum` field, by a text field whose type includes
1325
- * `sortable`, or by a list of any of these, which it reduces to one value by
1326
- * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
1327
- * `geopoint` or a vector field, because neither type has an order. It throws
1328
- * the same code for a sort on any other text field, since the engine keeps
1329
- * up to the first 512 code points of every document's value in memory to
1330
- * sort by a text field. The engine orders hybrid results by fusion, so it
1331
- * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
1332
- * that code for a direction other than `asc` and `desc`.
1333
- */
1334
- sort?: SortSpec;
1335
- /** These settings collapse the hits into groups by field value. */
1336
- group?: GroupConfig;
1337
- /**
1338
- * The query returns this many hits, and 10 by default. Pass 0 to read the
1339
- * match count with no hits. The engine reads a value below 0 as 0. It falls
1340
- * back to the default for `NaN` and for an infinite value, so a page size
1341
- * that you compute from user input never fails the query.
1342
- */
1343
- limit?: number;
1344
- /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
1345
- offset?: number;
1346
- /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
1347
- searchAfter?: string;
1348
- /** These settings name the fields that come back with highlighted snippets. */
1349
- highlight?: HighlightConfig;
1350
- /** These documents take fixed positions, ahead of the ranking. */
1351
- pinned?: Array<{
1352
- /** The engine places the document with this id. */
1318
+ interface BatchResult {
1319
+ /** The engine wrote the documents under these ids. */
1320
+ succeeded: string[];
1321
+ /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
1322
+ failed: Array<{
1353
1323
  docId: string;
1354
- /** The document takes this place in the results, counting from zero. */
1355
- position: number;
1324
+ error: NarsilError;
1356
1325
  }>;
1357
- /** This picks which engine answers the query. Keyword search runs by default. */
1358
- mode?: SearchMode;
1359
- /** These vector-search inputs are required in `vector` and `hybrid` mode. */
1360
- vector?: VectorQueryConfig;
1361
- /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
1362
- hybrid?: HybridConfig;
1326
+ }
1327
+ /**
1328
+ * What {@link Narsil.importDocumentExport} returns. The engine continues past each
1329
+ * refused line, so read the refusals to learn which documents it skipped.
1330
+ *
1331
+ * @public
1332
+ */
1333
+ interface DocumentImportResult {
1334
+ /** The engine wrote this many documents, counting each one that it replaced. */
1335
+ imported: number;
1336
+ /** The engine refused this many lines in total. */
1337
+ refusedCount: number;
1338
+ /** 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. */
1339
+ refused: Array<{
1340
+ line: number;
1341
+ code: NarsilErrorCode;
1342
+ message: string;
1343
+ }>;
1344
+ }
1345
+ /**
1346
+ * What {@link Narsil.getStats} returns about one index.
1347
+ *
1348
+ * @public
1349
+ */
1350
+ interface IndexStats {
1351
+ /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
1352
+ documentCount: number;
1353
+ /** The index is spread across this many partitions. */
1354
+ partitionCount: number;
1363
1355
  /**
1364
- * These settings reorder the top hits with a rerank adapter, such as a
1365
- * cross-encoder, after the keyword, vector, or hybrid ranking. The count
1366
- * matches the count of the same query without `rerank`, while the facets
1367
- * and the groups come from the first ranking. The engine throws
1368
- * `SEARCH_INVALID_MODE` for a query that also sets a sort, and
1369
- * `RERANK_FAILED` where the adapter fails or outlasts the engine's
1370
- * `rerankTimeout`.
1356
+ * Formula-based estimate of the index's main-thread memory footprint, summed
1357
+ * across every partition and vector index for this index. Computed from
1358
+ * structural counters (document count, posting counts, field-index sizes),
1359
+ * not measured. Per-object V8 overhead (hidden classes, map transitions,
1360
+ * GC headers) is not captured here, so this number routinely undershoots
1361
+ * the real heap by a meaningful factor. Use {@link Narsil.getMemoryStats}
1362
+ * when sizing host memory.
1371
1363
  */
1372
- rerank?: RerankConfig;
1364
+ estimatedMemoryBytes: number;
1365
+ /** The index analyses text with this language module. */
1366
+ language: string;
1367
+ /** The index was created with this field layout. */
1368
+ schema: SchemaDefinition;
1373
1369
  /**
1374
- * Setting this returns relevance scores on a sorted query. A query that
1375
- * names a sort ranks by sort values alone and computes no scores, so its
1376
- * hits carry none until this restores them. A query without a sort ignores
1377
- * this and always carries scores.
1370
+ * This many searches on this instance's main copy hold a state of the index
1371
+ * open right now. Each search holds one state from its start until it
1372
+ * answers, fails, or is cancelled, so the figure falls back to 0 once every
1373
+ * search has finished. A cluster reports no figure.
1378
1374
  */
1379
- includeScores?: boolean;
1380
- /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
1381
- includeScoreComponents?: boolean;
1382
- /** This chooses how much of each stored document comes back, and the whole document by default. */
1383
- document?: DocumentProjection;
1375
+ heldSearchStates?: number;
1384
1376
  }
1385
1377
  /**
1386
- * How much of a stored document each hit carries back.
1387
- *
1388
- * Pass `false` when the ids and scores are all you need, and every hit's
1389
- * `document` is then an empty object. Pass `include` to keep named fields
1390
- * alone, or `exclude` to drop named fields and keep the rest; naming both
1391
- * keeps the included fields and then drops the excluded ones from those. Use
1392
- * dots to name a nested field, so `author.name` addresses the `name` inside
1393
- * `author`, and a name that matches no field changes nothing.
1378
+ * A summary of one index, as {@link Narsil.listIndexes} reports it.
1394
1379
  *
1395
- * Drop a vector field on a similarity search, because the engine otherwise
1396
- * reads every hit's vector back out of the index and writes it into the
1397
- * response.
1380
+ * @public
1381
+ */
1382
+ interface IndexInfo {
1383
+ /** The index was created under this name. */
1384
+ name: string;
1385
+ /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
1386
+ documentCount: number;
1387
+ /** The index is spread across this many partitions. */
1388
+ partitionCount: number;
1389
+ /** The index analyses text with this language module. */
1390
+ language: string;
1391
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1392
+ analysisStale?: boolean;
1393
+ /** This is `open` in memory, `closed` after release, and `reopen-failed` after five recovery failures. */
1394
+ state: 'open' | 'closed' | 'reopen-failed';
1395
+ /** This counts successful loads since this engine started. */
1396
+ reopenCount: number;
1397
+ }
1398
+ /**
1399
+ * What {@link Narsil.getPartitionStats} reports for one partition, which is
1400
+ * where you look when an index grows unevenly.
1398
1401
  *
1399
1402
  * @public
1400
1403
  */
1401
- type DocumentProjection = boolean | {
1402
- /** Names the fields to keep, so every field left out of this list is dropped. */
1403
- include?: string[];
1404
- /** Names the fields to drop, so every other field is kept. */
1405
- exclude?: string[];
1406
- };
1404
+ interface PartitionStatsResult {
1405
+ /** This identifies the partition within its index. */
1406
+ partitionId: number;
1407
+ /** The partition holds this many documents. */
1408
+ documentCount: number;
1409
+ /**
1410
+ * Formula-based estimate of this partition's memory footprint. V8 has no
1411
+ * per-object heap accounting API, so this number is derived from structural
1412
+ * counters (document count, posting counts, field-index sizes) and does not
1413
+ * include per-object overhead. Treat as an estimate, not a measurement.
1414
+ */
1415
+ estimatedMemoryBytes: number;
1416
+ }
1407
1417
  /**
1408
- * Fields a query counts values for, keyed by field name.
1418
+ * What {@link Narsil.suggest} returns: the indexed terms that complete a
1419
+ * prefix, ready to offer as you-type suggestions.
1409
1420
  *
1410
1421
  * @public
1411
1422
  */
1412
- interface FacetConfig {
1413
- /** Each key names a field the query counts values for. */
1414
- [field: string]: {
1415
- /** 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`. */
1416
- limit?: number;
1417
- /** 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. */
1418
- sort?: 'asc' | 'desc';
1419
- /** 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. */
1420
- ranges?: Array<{
1421
- /** The range starts at this value. */
1422
- from: number;
1423
- /** The range ends at this value. */
1424
- to: number;
1425
- }>;
1426
- };
1423
+ interface SuggestResult {
1424
+ /** These completions run most widely used first. */
1425
+ terms: Array<{
1426
+ /** This is the completed term, as the index holds it. */
1427
+ term: string;
1428
+ /** The term appears in this many documents, which is what ordered the list. */
1429
+ documentFrequency: number;
1430
+ }>;
1431
+ /** The lookup took this many milliseconds. */
1432
+ elapsed: number;
1433
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1434
+ analysisStale?: boolean;
1427
1435
  }
1428
1436
  /**
1429
- * How a query collapses its hits into groups.
1437
+ * The state of one vector field, and what maintenance would cost, as
1438
+ * {@link VectorMaintenanceOperations.vectorMaintenanceStatus} reports it.
1439
+ *
1440
+ * Removing a vector leaves a tombstone in the graph, and enough of them slow a
1441
+ * search down. Read this to decide when compaction earns its cost.
1430
1442
  *
1431
1443
  * @public
1432
1444
  */
1433
- interface GroupConfig {
1434
- /** The values of these fields define a group, and several fields group by their combination. */
1435
- fields: string[];
1436
- /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
1437
- maxPerGroup?: number;
1438
- /** The engine returns this many groups, best first, and every group where you leave this out. */
1439
- limit?: number;
1445
+ interface VectorMaintenanceResult {
1446
+ /** This describes the named vector field. */
1447
+ fieldName: string;
1440
1448
  /**
1441
- * The engine folds every hit of each group into one value, such as a sum or
1442
- * an average, including the hits beyond `maxPerGroup`. In cluster mode the
1443
- * coordinator fetches up to 10,000 hits of each group to fold.
1449
+ * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
1450
+ * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
1451
+ * the engine divides by the number of stored vectors, because no graph
1452
+ * exists yet.
1444
1453
  */
1445
- reduce?: GroupReducer;
1454
+ tombstoneRatio: number;
1455
+ /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
1456
+ graphCount: number;
1457
+ /** This many vectors wait outside the graph, which a search scans one by one. */
1458
+ bufferSize: number;
1459
+ /** This stays true while a graph build runs. */
1460
+ building: boolean;
1461
+ /**
1462
+ * This turns true while a rebuild that keeps recall up waits for the node to have
1463
+ * room for a second graph beside the one it serves, and false once it starts.
1464
+ */
1465
+ waitingForMemory: boolean;
1466
+ /**
1467
+ * This stays true after a restart while a field kept on disk loads its codes and graph in the
1468
+ * background, during which a search reads them from the field's files.
1469
+ */
1470
+ loadingFromFiles: boolean;
1471
+ /** {@link VectorMaintenanceOperations.compactVectors} would take about this many milliseconds. */
1472
+ estimatedCompactMs: number;
1473
+ /** {@link VectorMaintenanceOperations.optimizeVectors} would take about this many milliseconds. */
1474
+ estimatedOptimizeMs: number;
1446
1475
  }
1447
1476
  /**
1448
- * Folds the hits of one group into a single value.
1477
+ * One stored document, as {@link Narsil.listDocuments} returns it.
1478
+ *
1479
+ * @typeParam T - Shape of the stored document.
1449
1480
  *
1450
1481
  * @public
1451
1482
  */
1452
- type GroupReducer = {
1453
- /**
1454
- * Folds one hit into the running value.
1455
- *
1456
- * @param accumulator - What the previous call returned, or what
1457
- * `initialValue` produced for the first hit.
1458
- * @param doc - The hit's stored document.
1459
- * @param score - The hit's relevance score.
1460
- * @returns The new running value.
1461
- */
1462
- reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
1463
- /** Produces the starting value for each group. The engine calls it once per group. */
1464
- initialValue: () => unknown;
1465
- };
1483
+ interface ListedDocument<T = AnyDocument> {
1484
+ /** The document is stored under this id. */
1485
+ id: string;
1486
+ /** This holds the stored document, cut down to what the projection kept. */
1487
+ document: T;
1488
+ }
1466
1489
  /**
1467
- * This configuration names the fields that receive highlighted snippets. It
1468
- * also sets how the engine marks those snippets up.
1490
+ * What {@link Narsil.listDocuments} returns: one page of stored documents and
1491
+ * the cursor that reaches the next one.
1469
1492
  *
1470
- * The engine analyses the text of each returned field again to tag every word
1471
- * that it matched, so it tags the same words whatever the index's
1472
- * `trackPositions` setting is. It tags a word whose stem equals a query stem,
1473
- * and a word within the query's `tolerance` of a query stem. For a `prefix`
1474
- * query, it tags a word for the last query term only when that word completes
1475
- * the term or shares its stem.
1493
+ * @typeParam T - Shape of the stored documents.
1476
1494
  *
1477
1495
  * @public
1478
1496
  */
1479
- interface HighlightConfig {
1480
- /** The engine highlights these fields. */
1481
- fields: string[];
1482
- /** The engine writes this before each match, and writes `<mark>` by default. */
1483
- preTag?: string;
1484
- /** The engine writes this after each match, and writes `</mark>` by default. */
1485
- postTag?: string;
1486
- /**
1487
- * The engine takes this many characters of the field around the densest run
1488
- * of matches, 200 by default. It returns a snippet longer than that number,
1489
- * because it then adds the opening and closing tags, and an ellipsis at each
1490
- * end where it cuts the field.
1491
- */
1492
- maxSnippetLength?: number;
1497
+ interface ListResult<T = AnyDocument> {
1498
+ /** These documents make up the page, in ascending document-id order. */
1499
+ documents: Array<ListedDocument<T>>;
1500
+ /** This opaque cursor reaches the next page, and is null once the listing is finished. */
1501
+ cursor: string | null;
1502
+ /** The listing covers this many documents in total, and any filter narrows that count. */
1503
+ total: number;
1504
+ /** The engine spent this many milliseconds building the page. */
1505
+ elapsed: number;
1493
1506
  }
1494
1507
 
1495
1508
  /**
@@ -2555,4 +2568,4 @@ interface Narsil extends IndexLifecycleOperations, DocumentWriteOperations, Syno
2555
2568
  shutdown(): Promise<void>;
2556
2569
  }
2557
2570
 
2558
- export { type IndexLifecycleOperations as $, type AnalysisChange as A, type BatchResult as B, type ClientErrorCode as C, type DocumentImportResult as D, type ErrorCode as E, type FacetConfig as F, type GroupResult as G, type FacetResult as H, type IndexInfo as I, type FieldFilter as J, type FilterExpression as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type GeoFilter as O, type PartitionStatsResult as P, type QueryParams as Q, type GeoPolygonFilter as R, type ServerErrorCode as S, type GeoRadiusFilter as T, type GroupReducer as U, type VectorMaintenanceResult as V, type HeldCheckpointReport as W, type HighlightConfig as X, type HighlightMatch as Y, type Hit as Z, type HybridConfig as _, ClientErrorCodes as a, type ListedDocument as a0, type PresenceFilter as a1, type ProcessMemoryReport as a2, type QueryCoverage as a3, type RerankConfig as a4, type ScoreComponents as a5, type SearchMode as a6, type SortField as a7, type SortSpec as a8, type StringFilter as a9, type SyncOperations as aa, type SynonymOperations as ab, type TermMatchPolicy as ac, type VectorMaintenanceOperations as ad, type VectorQueryConfig as ae, type WorkerCopyReport as af, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type SnapshotOptions as e, type SyncSetting as f, type SyncStatus as g, type Narsil as h, isNarsilError as i, type QueryResult as j, type NarsilEventHandlers as k, type ListResult as l, type SuggestParams as m, type SuggestResult as n, type PreflightResult as o, type IndexStats as p, type NarsilEventMap as q, type GroupConfig as r, type AdapterRegistrationOperations as s, type AnalysisOperations as t, type ArrayFilter as u, type BM25Operations as v, type ByteSource as w, type ComparisonFilter as x, type DocumentProjection as y, type DocumentWriteOperations as z };
2571
+ export { type IndexLifecycleOperations as $, type AnalysisChange as A, type BatchResult as B, type ClientErrorCode as C, type DocumentImportResult as D, type ErrorCode as E, type FacetConfig as F, type GroupResult as G, type Hit as H, type IndexInfo as I, type FacetResult as J, type FieldFilter as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type FilterExpression as O, type PartitionStatsResult as P, type QueryParams as Q, type GeoFilter as R, type ServerErrorCode as S, type GeoPolygonFilter as T, type GeoRadiusFilter as U, type VectorMaintenanceResult as V, type GroupReducer as W, type HeldCheckpointReport as X, type HighlightConfig as Y, type HighlightMatch as Z, type HybridConfig as _, ClientErrorCodes as a, type ListedDocument as a0, type PresenceFilter as a1, type ProcessMemoryReport as a2, type QueryCoverage as a3, type RerankConfig as a4, type ScoreComponents as a5, type SearchMode as a6, type SortField as a7, type SortSpec as a8, type StringFilter as a9, type SyncOperations as aa, type SynonymOperations as ab, type TermMatchPolicy as ac, type VectorMaintenanceOperations as ad, type VectorQueryConfig as ae, type WorkerCopyReport as af, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type SnapshotOptions as e, type SyncSetting as f, type SyncStatus as g, type Narsil as h, isNarsilError as i, type QueryResult as j, type NarsilEventHandlers as k, type ListResult as l, type SuggestParams as m, type SuggestResult as n, type PreflightResult as o, type IndexStats as p, type NarsilEventMap as q, type GroupConfig as r, type AdapterRegistrationOperations as s, type AnalysisOperations as t, type ArrayFilter as u, type BM25Operations as v, type ByteSource as w, type ComparisonFilter as x, type DocumentProjection as y, type DocumentWriteOperations as z };