@delali/narsil 0.3.1-next.99 → 0.4.1-next.211

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 (426) hide show
  1. package/NOTICE +45 -0
  2. package/README.md +30 -11
  3. package/dist/adapters/filesystem.d.ts +1 -1
  4. package/dist/adapters/filesystem.mjs +101 -13
  5. package/dist/adapters/gcs.d.ts +49 -0
  6. package/dist/adapters/gcs.mjs +213 -0
  7. package/dist/adapters/indexeddb.d.ts +1 -1
  8. package/dist/adapters/indexeddb.mjs +2 -7
  9. package/dist/adapters/memory.d.ts +1 -1
  10. package/dist/adapters/memory.mjs +5 -0
  11. package/dist/adapters/s3.d.ts +53 -0
  12. package/dist/adapters/s3.mjs +263 -0
  13. package/dist/{adapters-BQFQ4PRz.d.ts → adapters-pljAqmrC.d.ts} +33 -0
  14. package/dist/browser/chunk-4E5APHTM.mjs +1459 -0
  15. package/dist/browser/chunk-NDYADQ4Y.mjs +23426 -0
  16. package/dist/browser/chunk-QAOVAYAG.mjs +564 -0
  17. package/dist/browser/chunk-WC2DEXWU.mjs +29 -0
  18. package/dist/browser/chunk-YINZFPLT.mjs +1239 -0
  19. package/dist/browser/chunk-YJHGOJAC.mjs +15 -0
  20. package/dist/browser/{chunk-Z7QH2XHB.mjs → core-leaf-HWAXCEWX.mjs} +3987 -2103
  21. package/dist/browser/custom-token-results-R5BIX7SL.mjs +59 -0
  22. package/dist/browser/digest-leaf-64IPRPZD.mjs +151 -0
  23. package/dist/browser/durability-config-75NSFCQN.mjs +97 -0
  24. package/dist/browser/embed-GG6PS3EA.mjs +264 -0
  25. package/dist/browser/geo-index-GNHY4PUB.mjs +1484 -0
  26. package/dist/browser/gzip-JF3S6PPT.mjs +31 -0
  27. package/dist/browser/module-ZZTNG5JZ.mjs +5762 -0
  28. package/dist/browser/msgpack-leaf-44XNWSSY.mjs +302 -0
  29. package/dist/browser/optional-reads-XMVPG6HG.mjs +3230 -0
  30. package/dist/browser/optional-writes-76DWMRQH.mjs +3603 -0
  31. package/dist/browser/phrase-module-6UGFVW5J.mjs +617 -0
  32. package/dist/browser/resolve-vector-text-XRR2OVHE.mjs +85 -0
  33. package/dist/browser/restore-queue-SG5O735W.mjs +196 -0
  34. package/dist/browser/{runtime-NYE5TB6O.mjs → runtime-OMKE7DF4.mjs} +83 -25
  35. package/dist/browser/segment-codec-leaf-A427QJUX.mjs +554 -0
  36. package/dist/browser/segment-merge-leaf-7BZ54JPI.mjs +1636 -0
  37. package/dist/browser/storage-leaf-5UTR5K7J.mjs +19829 -0
  38. package/dist/browser/store-leaf-3L33V35P.mjs +2070 -0
  39. package/dist/browser/suggestions-leaf-UBNDVKBD.mjs +1430 -0
  40. package/dist/browser/worker-copies-JXSGYR5X.mjs +2951 -0
  41. package/dist/{capabilities-BTTIs96E.d.ts → capabilities-DMte5K9_.d.ts} +162 -18
  42. package/dist/chunk-2AFZE7Y3.mjs +72 -0
  43. package/dist/chunk-2CKDCC65.mjs +47 -0
  44. package/dist/chunk-3ECIRFS5.mjs +61 -0
  45. package/dist/chunk-44W3CBNG.mjs +7 -0
  46. package/dist/chunk-4H4RG2FR.mjs +13 -0
  47. package/dist/chunk-4PY4JYMY.mjs +11 -0
  48. package/dist/chunk-4ZPVAHWF.mjs +1289 -0
  49. package/dist/chunk-5EI5CXO6.mjs +197 -0
  50. package/dist/chunk-5F5MXWS5.mjs +283 -0
  51. package/dist/{chunk-OHP7QR33.mjs → chunk-5FLRXF73.mjs} +25 -4
  52. package/dist/chunk-6FOENO4E.mjs +273 -0
  53. package/dist/chunk-6GHX35ZM.mjs +108 -0
  54. package/dist/chunk-6MSZ543Y.mjs +32 -0
  55. package/dist/chunk-6N6HHBCQ.mjs +4596 -0
  56. package/dist/{chunk-LXPIXDUJ.mjs → chunk-7P5YWDRQ.mjs} +403 -169
  57. package/dist/{chunk-TGP5M5R7.mjs → chunk-7T4LAYT4.mjs} +1 -1
  58. package/dist/{chunk-GGSH6KBQ.mjs → chunk-ASZLNVWW.mjs} +23 -3
  59. package/dist/chunk-AVBPB3MI.mjs +602 -0
  60. package/dist/{chunk-UCDF35PU.mjs → chunk-AVGUEEQ3.mjs} +494 -245
  61. package/dist/chunk-BUMREPLU.mjs +15 -0
  62. package/dist/chunk-BY6NALRK.mjs +31921 -0
  63. package/dist/chunk-C4ZMXXTL.mjs +92 -0
  64. package/dist/{chunk-2WYMG3OZ.mjs → chunk-C74KPRR7.mjs} +274 -19
  65. package/dist/{chunk-RSRVGAIQ.mjs → chunk-D456ZFPQ.mjs} +3 -2
  66. package/dist/chunk-DXZ6JDWG.mjs +797 -0
  67. package/dist/chunk-FJXJZUWF.mjs +209 -0
  68. package/dist/chunk-FS3HPPSC.mjs +212 -0
  69. package/dist/chunk-FT4KLZXW.mjs +1164 -0
  70. package/dist/chunk-GR5GMFJJ.mjs +104 -0
  71. package/dist/chunk-GXCDWLQI.mjs +193 -0
  72. package/dist/chunk-GXED6R3Q.mjs +271 -0
  73. package/dist/chunk-HLPRHOSO.mjs +17 -0
  74. package/dist/chunk-IL5DRCNU.mjs +3041 -0
  75. package/dist/{chunk-P36MUFEJ.mjs → chunk-JDDXV6UF.mjs} +2 -1
  76. package/dist/chunk-K5HSUPYS.mjs +11 -0
  77. package/dist/chunk-KYIRXTCA.mjs +100 -0
  78. package/dist/chunk-LFXS6OF7.mjs +289 -0
  79. package/dist/chunk-LNGE7SLY.mjs +151 -0
  80. package/dist/chunk-M2Z5WVWW.mjs +194 -0
  81. package/dist/{chunk-45AVKHMJ.mjs → chunk-M3B7SGJB.mjs} +63 -50
  82. package/dist/chunk-M3OW2XSP.mjs +40 -0
  83. package/dist/chunk-MFPSQZ6P.mjs +127 -0
  84. package/dist/chunk-MRCJBWJZ.mjs +1292 -0
  85. package/dist/chunk-MSIN4NM3.mjs +25 -0
  86. package/dist/chunk-MW3CJVGP.mjs +219 -0
  87. package/dist/chunk-MYM6CAVK.mjs +76 -0
  88. package/dist/chunk-NJJN4FMM.mjs +84 -0
  89. package/dist/chunk-NM7I3BM7.mjs +59 -0
  90. package/dist/chunk-OIJ64LGT.mjs +19 -0
  91. package/dist/{chunk-K7D4ZTSW.mjs → chunk-P4F4UWLC.mjs} +1 -1
  92. package/dist/chunk-Q2AP2FSN.mjs +15 -0
  93. package/dist/chunk-R2PJKSNL.mjs +54 -0
  94. package/dist/{chunk-HXJBSHXF.mjs → chunk-R724DJSG.mjs} +5056 -2619
  95. package/dist/chunk-S2POFTLN.mjs +10 -0
  96. package/dist/chunk-S5QMWECL.mjs +7 -0
  97. package/dist/chunk-SLAC5PAB.mjs +5008 -0
  98. package/dist/chunk-T4HMSZCX.mjs +5 -0
  99. package/dist/chunk-TACP6VK6.mjs +111 -0
  100. package/dist/chunk-TGPKS2UM.mjs +125 -0
  101. package/dist/chunk-TKKXPKEO.mjs +979 -0
  102. package/dist/chunk-V6EUBAIT.mjs +19 -0
  103. package/dist/chunk-XL56L4IR.mjs +228 -0
  104. package/dist/chunk-XQIAMDAG.mjs +3076 -0
  105. package/dist/chunk-YTUZ4R22.mjs +1063 -0
  106. package/dist/{chunk-KV3AZFT3.mjs → chunk-ZKOQR7EA.mjs} +45 -1
  107. package/dist/chunk-ZPJFGGGI.mjs +638 -0
  108. package/dist/chunk-ZXX5GZEX.mjs +17 -0
  109. package/dist/{client-i9eLJrw5.d.ts → client-BKqtl0_V.d.ts} +442 -22
  110. package/dist/client.d.ts +11 -10
  111. package/dist/client.mjs +8 -898
  112. package/dist/config-Bnl7L-0H.d.ts +608 -0
  113. package/dist/{config-P__Diiy4.d.ts → config-CJ-jfI0a.d.ts} +119 -9
  114. package/dist/core-leaf-6JVHEVFB.mjs +8 -0
  115. package/dist/custom-token-results-NXHBVY7U.mjs +59 -0
  116. package/dist/digest-leaf-KXBGKYHZ.mjs +1 -0
  117. package/dist/direct-executor-V3WOYU2Y.mjs +17 -0
  118. package/dist/distribution/coordinator/etcd.d.ts +63 -7
  119. package/dist/distribution/coordinator/etcd.mjs +725 -81
  120. package/dist/distribution/coordinator/in-memory.d.ts +3 -3
  121. package/dist/distribution/coordinator/in-memory.mjs +65 -10
  122. package/dist/distribution/transport/grpc.d.ts +2 -2
  123. package/dist/distribution/transport/grpc.mjs +39 -10
  124. package/dist/distribution/transport/in-memory.d.ts +2 -2
  125. package/dist/distribution/transport/in-memory.mjs +9 -6
  126. package/dist/distribution/transport/tcp.d.ts +2 -2
  127. package/dist/distribution/transport/tcp.mjs +20 -15
  128. package/dist/distribution.d.ts +267 -56
  129. package/dist/distribution.mjs +23156 -11362
  130. package/dist/durability-config-VWS2K24E.mjs +96 -0
  131. package/dist/embed-4PHHKGBK.mjs +263 -0
  132. package/dist/embeddings/openai.d.ts +1 -1
  133. package/dist/embeddings/openai.mjs +2 -2
  134. package/dist/{memory-CUEDwr-F.d.ts → engine-qjAxJSKk.d.ts} +2254 -1123
  135. package/dist/geo-index-2ZMMWWSK.mjs +1484 -0
  136. package/dist/gzip-2UCZW2MM.mjs +31 -0
  137. package/dist/{index-lcdGLyJH.d.ts → index-B_vmxpgW.d.ts} +260 -102
  138. package/dist/index.browser.mjs +4 -4
  139. package/dist/index.d.ts +2133 -57
  140. package/dist/index.mjs +16 -32
  141. package/dist/index.react-native.mjs +12 -0
  142. package/dist/invalidation/broadcast-channel.d.ts +1 -1
  143. package/dist/invalidation/filesystem.d.ts +1 -1
  144. package/dist/invalidation/filesystem.mjs +1 -2
  145. package/dist/invalidation/noop.d.ts +1 -1
  146. package/dist/languages/albanian.mjs +1 -1
  147. package/dist/languages/amharic.mjs +1 -1
  148. package/dist/languages/arabic.mjs +1 -1
  149. package/dist/languages/armenian.mjs +1 -1
  150. package/dist/languages/azerbaijani.mjs +1 -1
  151. package/dist/languages/bambara.mjs +1 -1
  152. package/dist/languages/basque.mjs +1 -1
  153. package/dist/languages/belarusian.mjs +1 -1
  154. package/dist/languages/bengali.mjs +1 -1
  155. package/dist/languages/bosnian.mjs +1 -1
  156. package/dist/languages/breton.mjs +1 -1
  157. package/dist/languages/bulgarian.mjs +1 -1
  158. package/dist/languages/burmese.mjs +1 -1
  159. package/dist/languages/catalan.mjs +1 -1
  160. package/dist/languages/chinese.mjs +1 -1
  161. package/dist/languages/croatian.mjs +1 -1
  162. package/dist/languages/czech.mjs +1 -1
  163. package/dist/languages/dagbani.mjs +1 -1
  164. package/dist/languages/danish.mjs +1 -1
  165. package/dist/languages/dutch.mjs +1 -1
  166. package/dist/languages/english.mjs +1 -1
  167. package/dist/languages/esperanto.mjs +1 -1
  168. package/dist/languages/estonian.mjs +1 -1
  169. package/dist/languages/ewe.mjs +1 -1
  170. package/dist/languages/faroese.mjs +1 -1
  171. package/dist/languages/fijian.mjs +1 -1
  172. package/dist/languages/finnish.mjs +1 -1
  173. package/dist/languages/french.mjs +1 -1
  174. package/dist/languages/ga.mjs +1 -1
  175. package/dist/languages/galician.mjs +1 -1
  176. package/dist/languages/georgian.mjs +1 -1
  177. package/dist/languages/german.mjs +1 -1
  178. package/dist/languages/greek.mjs +1 -1
  179. package/dist/languages/guarani.mjs +1 -1
  180. package/dist/languages/gujarati.mjs +1 -1
  181. package/dist/languages/haitian-creole.mjs +1 -1
  182. package/dist/languages/hausa.mjs +1 -1
  183. package/dist/languages/hawaiian.mjs +1 -1
  184. package/dist/languages/hebrew.mjs +1 -1
  185. package/dist/languages/hindi.mjs +1 -1
  186. package/dist/languages/hungarian.mjs +1 -1
  187. package/dist/languages/icelandic.mjs +1 -1
  188. package/dist/languages/igbo.mjs +1 -1
  189. package/dist/languages/indonesian.mjs +1 -1
  190. package/dist/languages/irish.mjs +1 -1
  191. package/dist/languages/italian.mjs +1 -1
  192. package/dist/languages/japanese.mjs +1 -1
  193. package/dist/languages/kannada.mjs +1 -1
  194. package/dist/languages/kazakh.mjs +1 -1
  195. package/dist/languages/khmer.mjs +1 -1
  196. package/dist/languages/kinyarwanda.mjs +1 -1
  197. package/dist/languages/kirundi.mjs +1 -1
  198. package/dist/languages/korean.mjs +1 -1
  199. package/dist/languages/kurmanji.mjs +1 -1
  200. package/dist/languages/kyrgyz.mjs +1 -1
  201. package/dist/languages/lao.mjs +1 -1
  202. package/dist/languages/latin.mjs +1 -1
  203. package/dist/languages/latvian.mjs +1 -1
  204. package/dist/languages/lingala.mjs +1 -1
  205. package/dist/languages/lithuanian.mjs +1 -1
  206. package/dist/languages/luxembourgish.mjs +1 -1
  207. package/dist/languages/macedonian.mjs +1 -1
  208. package/dist/languages/malagasy.mjs +1 -1
  209. package/dist/languages/malay.mjs +1 -1
  210. package/dist/languages/malayalam.mjs +1 -1
  211. package/dist/languages/maltese.mjs +1 -1
  212. package/dist/languages/maori.mjs +1 -1
  213. package/dist/languages/marathi.mjs +1 -1
  214. package/dist/languages/nepali.mjs +1 -1
  215. package/dist/languages/norwegian.mjs +1 -1
  216. package/dist/languages/oromo.mjs +1 -1
  217. package/dist/languages/persian.mjs +1 -1
  218. package/dist/languages/polish.mjs +1 -1
  219. package/dist/languages/portuguese.mjs +1 -1
  220. package/dist/languages/punjabi.mjs +1 -1
  221. package/dist/languages/romanian.mjs +1 -1
  222. package/dist/languages/russian.mjs +1 -1
  223. package/dist/languages/samoan.mjs +1 -1
  224. package/dist/languages/sanskrit.mjs +1 -1
  225. package/dist/languages/scottish-gaelic.mjs +1 -1
  226. package/dist/languages/serbian.mjs +1 -1
  227. package/dist/languages/shona.mjs +1 -1
  228. package/dist/languages/sinhala.mjs +1 -1
  229. package/dist/languages/slovak.mjs +1 -1
  230. package/dist/languages/slovenian.mjs +1 -1
  231. package/dist/languages/sorani.mjs +1 -1
  232. package/dist/languages/spanish.mjs +1 -1
  233. package/dist/languages/swahili.mjs +1 -1
  234. package/dist/languages/swedish.mjs +1 -1
  235. package/dist/languages/tagalog.mjs +1 -1
  236. package/dist/languages/tamil.mjs +1 -1
  237. package/dist/languages/tatar.mjs +1 -1
  238. package/dist/languages/telugu.mjs +1 -1
  239. package/dist/languages/thai.mjs +1 -1
  240. package/dist/languages/tibetan.mjs +1 -1
  241. package/dist/languages/tigrinya.mjs +1 -1
  242. package/dist/languages/tongan.mjs +1 -1
  243. package/dist/languages/turkish.mjs +1 -1
  244. package/dist/languages/twi.mjs +1 -1
  245. package/dist/languages/ukrainian.mjs +1 -1
  246. package/dist/languages/urdu.mjs +1 -1
  247. package/dist/languages/vietnamese.mjs +1 -1
  248. package/dist/languages/welsh.mjs +1 -1
  249. package/dist/languages/wolof.mjs +1 -1
  250. package/dist/languages/xhosa.mjs +1 -1
  251. package/dist/languages/yoruba.mjs +1 -1
  252. package/dist/languages/zulu.mjs +1 -1
  253. package/dist/long-query-thread-UCRK7MSI.mjs +154 -0
  254. package/dist/module-5ZSLUQII.mjs +3729 -0
  255. package/dist/msgpack-leaf-H5ZYW7S7.mjs +9 -0
  256. package/dist/optional-reads-5HFMF2QZ.mjs +3373 -0
  257. package/dist/optional-writes-4UOQKETU.mjs +247 -0
  258. package/dist/paged-partition-archive-BBRLZCIF.mjs +253 -0
  259. package/dist/partial-words.browser.mjs +1650 -0
  260. package/dist/partial-words.mjs +17 -11
  261. package/dist/{chunk-ASY5PHYI.mjs → pattern.browser.mjs} +253 -311
  262. package/dist/pattern.mjs +6 -7
  263. package/dist/persistence/durability/checkpoint-worker.d.ts +93 -25
  264. package/dist/persistence/durability/checkpoint-worker.mjs +51 -41
  265. package/dist/phrase-module-EFESWOCR.mjs +635 -0
  266. package/dist/query-actions-HMJUVWGT.mjs +119 -0
  267. package/dist/query-suggestions/merge-worker.d.ts +55 -0
  268. package/dist/query-suggestions/merge-worker.mjs +53 -0
  269. package/dist/query-suggestions-CBYkrQ5T.d.ts +311 -0
  270. package/dist/query-suggestions.browser.mjs +47 -0
  271. package/dist/query-suggestions.d.ts +20 -0
  272. package/dist/query-suggestions.mjs +19 -0
  273. package/dist/react-native/chunks/chunk-3OEFSHVV.mjs +970 -0
  274. package/dist/{browser/chunk-RELZRJNR.mjs → react-native/chunks/chunk-43R4GCM7.mjs} +49 -50
  275. package/dist/react-native/chunks/chunk-AKRYHAVG.mjs +6729 -0
  276. package/dist/react-native/chunks/chunk-CW2ZFXSE.mjs +14 -0
  277. package/dist/react-native/chunks/chunk-G3WCDTOF.mjs +29640 -0
  278. package/dist/react-native/chunks/chunk-GXXHHA2T.mjs +212 -0
  279. package/dist/react-native/chunks/chunk-H3MDVPBO.mjs +151 -0
  280. package/dist/react-native/chunks/chunk-HQEVQEDJ.mjs +52 -0
  281. package/dist/react-native/chunks/chunk-HRDMIQ63.mjs +131 -0
  282. package/dist/react-native/chunks/chunk-HTBY4GON.mjs +565 -0
  283. package/dist/react-native/chunks/chunk-LX62Y4B5.mjs +61 -0
  284. package/dist/react-native/chunks/chunk-MRH36RN3.mjs +902 -0
  285. package/dist/react-native/chunks/chunk-Q32DDFKX.mjs +19 -0
  286. package/dist/react-native/chunks/chunk-UE4ANHSX.mjs +127 -0
  287. package/dist/react-native/chunks/chunk-UNZPWLVL.mjs +1063 -0
  288. package/dist/react-native/chunks/chunk-UO44MA5M.mjs +232 -0
  289. package/dist/react-native/chunks/chunk-UYKIV2KT.mjs +42 -0
  290. package/dist/react-native/chunks/chunk-VUJCSQG5.mjs +11 -0
  291. package/dist/react-native/chunks/chunk-WVHF4ZAK.mjs +802 -0
  292. package/dist/react-native/chunks/chunk-ZUJCUPVS.mjs +54 -0
  293. package/dist/react-native/chunks/core-leaf-S2KNBWDY.mjs +7 -0
  294. package/dist/react-native/chunks/custom-token-results-3OZEMRE7.mjs +59 -0
  295. package/dist/react-native/chunks/digest-leaf-X6OIFDIU.mjs +1 -0
  296. package/dist/react-native/chunks/durability-config-FCSD4MXY.mjs +96 -0
  297. package/dist/react-native/chunks/embed-HA2I7RCF.mjs +263 -0
  298. package/dist/react-native/chunks/geo-index-QEYKEVPH.mjs +1484 -0
  299. package/dist/react-native/chunks/gzip.react-native-CVM4NQG2.mjs +12 -0
  300. package/dist/react-native/chunks/module-FMBX75GP.mjs +5209 -0
  301. package/dist/react-native/chunks/msgpack-leaf-JMNGSTRW.mjs +7 -0
  302. package/dist/react-native/chunks/optional-reads-AFPO2FEB.mjs +3364 -0
  303. package/dist/react-native/chunks/optional-writes-XOH25XZI.mjs +296 -0
  304. package/dist/react-native/chunks/phrase-module-IGYBK7XH.mjs +636 -0
  305. package/dist/react-native/chunks/replace-IMZUVUOE.mjs +57 -0
  306. package/dist/react-native/chunks/resolve-vector-text-GE2CRJKI.mjs +84 -0
  307. package/dist/react-native/chunks/restore-queue-LLNMYB4Z.mjs +187 -0
  308. package/dist/react-native/chunks/runtime-UOHD2XUJ.mjs +615 -0
  309. package/dist/react-native/chunks/segment-codec-leaf-VR6O5GLC.mjs +13 -0
  310. package/dist/react-native/chunks/segment-merge-leaf-LLMWU4EW.mjs +14 -0
  311. package/dist/react-native/chunks/storage-leaf-JD7PIDO4.mjs +19633 -0
  312. package/dist/react-native/chunks/store-leaf-4UVCMYGN.mjs +15 -0
  313. package/dist/react-native/chunks/suggestions-leaf-J5VT5RHY.mjs +1321 -0
  314. package/dist/react-native/chunks/worker-copies-ZYHY7FKJ.mjs +2831 -0
  315. package/dist/react-native/partial-words.mjs +1658 -0
  316. package/dist/react-native/pattern.mjs +2570 -0
  317. package/dist/react-native/query-suggestions.mjs +55 -0
  318. package/dist/react-native/sync.mjs +2759 -0
  319. package/dist/react-native/synonyms.mjs +676 -0
  320. package/dist/react.d.ts +12 -8
  321. package/dist/react.mjs +45 -1
  322. package/dist/{rerank-NWTKK636.mjs → rerank-RI2PMNOD.mjs} +22 -12
  323. package/dist/rerankers/http.d.ts +1 -1
  324. package/dist/rerankers/http.mjs +2 -2
  325. package/dist/resolve-vector-text-OD4J3WHF.mjs +3 -0
  326. package/dist/restore-queue-PCKWDAKQ.mjs +192 -0
  327. package/dist/runtime-USQYKN3I.mjs +615 -0
  328. package/dist/{schema-4W_7tk1f.d.ts → schema-CzG9OUw5.d.ts} +70 -30
  329. package/dist/segment-codec-leaf-QJM7I6QG.mjs +18 -0
  330. package/dist/segment-merge-leaf-4BJGIJHY.mjs +18 -0
  331. package/dist/server.d.ts +348 -22
  332. package/dist/server.mjs +2211 -327
  333. package/dist/storage-leaf-GRRRI7UV.mjs +5962 -0
  334. package/dist/store-leaf-6VMMSVBE.mjs +20 -0
  335. package/dist/stored-values-BWIMpiT_.d.ts +25 -0
  336. package/dist/suggestions-leaf-4KPTMPTL.mjs +54 -0
  337. package/dist/sync/filesystem.d.ts +30 -0
  338. package/dist/sync/filesystem.mjs +288 -0
  339. package/dist/sync/indexeddb.browser.mjs +287 -0
  340. package/dist/sync/indexeddb.d.ts +30 -0
  341. package/dist/sync/indexeddb.mjs +242 -0
  342. package/dist/sync.browser.mjs +1271 -0
  343. package/dist/sync.d.ts +23 -0
  344. package/dist/sync.mjs +2712 -0
  345. package/dist/synonyms.browser.mjs +658 -0
  346. package/dist/synonyms.mjs +17 -7
  347. package/dist/tasks-65b6t6lk.d.ts +782 -0
  348. package/dist/thread-UJ3W5LVI.mjs +31 -0
  349. package/dist/{types-B3b68nfF.d.ts → types-Ck97nB3D.d.ts} +1 -1
  350. package/dist/types-CpCg-Gq-.d.ts +227 -0
  351. package/dist/{types-Cb9kiY5P.d.ts → types-DvncmvuQ.d.ts} +12 -1
  352. package/dist/vector/search-worker.d.ts +10 -2
  353. package/dist/vector/search-worker.mjs +11 -11
  354. package/dist/worker-copies-YSXZXIGC.mjs +2232 -0
  355. package/dist/workers/entry.mjs +75 -15
  356. package/openapi.json +6840 -0
  357. package/package.json +404 -19
  358. package/dist/browser/chunk-CN4I4FZU.mjs +0 -602
  359. package/dist/browser/chunk-HOZW3PKP.mjs +0 -9
  360. package/dist/browser/chunk-JPTQZWJQ.mjs +0 -10
  361. package/dist/browser/chunk-LD55ZGU3.mjs +0 -347
  362. package/dist/browser/chunk-NAFT3K6X.mjs +0 -24546
  363. package/dist/browser/chunk-NNG3EEB6.mjs +0 -2728
  364. package/dist/browser/chunk-QWES44AW.mjs +0 -473
  365. package/dist/browser/durability-wiring-PY3L7DES.mjs +0 -3679
  366. package/dist/browser/module-PDXYHT75.mjs +0 -2822
  367. package/dist/browser/release-76MXRPGV.mjs +0 -33
  368. package/dist/browser/restore-queue-DVIYJ7RU.mjs +0 -35
  369. package/dist/browser/snapshot-J57MZK6L.mjs +0 -1207
  370. package/dist/browser/write-L7FAQA47.mjs +0 -208
  371. package/dist/chunk-37CD3OKS.mjs +0 -87
  372. package/dist/chunk-5XNIRLFC.mjs +0 -96
  373. package/dist/chunk-7X5JST5L.mjs +0 -114
  374. package/dist/chunk-AV4IJKD2.mjs +0 -35
  375. package/dist/chunk-AY3AQ3UH.mjs +0 -73
  376. package/dist/chunk-BKB3XTMI.mjs +0 -707
  377. package/dist/chunk-C7SLA6CM.mjs +0 -19
  378. package/dist/chunk-COVCQ73F.mjs +0 -587
  379. package/dist/chunk-DJHHF2L5.mjs +0 -17
  380. package/dist/chunk-E74YLAIG.mjs +0 -24
  381. package/dist/chunk-FMWRCP2C.mjs +0 -57
  382. package/dist/chunk-GES7U2PM.mjs +0 -68
  383. package/dist/chunk-HJSN7UYG.mjs +0 -10
  384. package/dist/chunk-JFRNNBOM.mjs +0 -35
  385. package/dist/chunk-K25LZA54.mjs +0 -8484
  386. package/dist/chunk-KEHK2O6P.mjs +0 -13
  387. package/dist/chunk-KOKM4PQN.mjs +0 -52
  388. package/dist/chunk-KZ3NX2P7.mjs +0 -21
  389. package/dist/chunk-L3L5YFXC.mjs +0 -614
  390. package/dist/chunk-L5ORED7V.mjs +0 -25
  391. package/dist/chunk-LH4NZNJJ.mjs +0 -1731
  392. package/dist/chunk-LU2CE5AE.mjs +0 -507
  393. package/dist/chunk-LXWDQLTW.mjs +0 -30
  394. package/dist/chunk-MHOSCQCQ.mjs +0 -948
  395. package/dist/chunk-NKRBEGJZ.mjs +0 -1705
  396. package/dist/chunk-NTRMFARG.mjs +0 -462
  397. package/dist/chunk-NW4XDSP2.mjs +0 -212
  398. package/dist/chunk-OOEXLUGR.mjs +0 -117
  399. package/dist/chunk-ORBLD3EL.mjs +0 -6
  400. package/dist/chunk-OWNZYMRE.mjs +0 -3591
  401. package/dist/chunk-PPY2GSIB.mjs +0 -44
  402. package/dist/chunk-QY7GC2MW.mjs +0 -33
  403. package/dist/chunk-R6A773WK.mjs +0 -226
  404. package/dist/chunk-R6PR4WYZ.mjs +0 -68
  405. package/dist/chunk-R7EEKAJE.mjs +0 -593
  406. package/dist/chunk-RONEOEON.mjs +0 -426
  407. package/dist/chunk-VWULPWRJ.mjs +0 -7469
  408. package/dist/chunk-WCJKUGHB.mjs +0 -262
  409. package/dist/chunk-WQBCBKY3.mjs +0 -8
  410. package/dist/chunk-X5CV2E2B.mjs +0 -1
  411. package/dist/chunk-YA7XLE2R.mjs +0 -1256
  412. package/dist/chunk-YTJCGKM4.mjs +0 -56
  413. package/dist/chunk-ZG477IPV.mjs +0 -526
  414. package/dist/chunk-ZYNAMIYX.mjs +0 -113
  415. package/dist/config-BGB_fDtq.d.ts +0 -237
  416. package/dist/direct-executor-CXZ66ACP.mjs +0 -22
  417. package/dist/durability-wiring-QTHOGFMZ.mjs +0 -3229
  418. package/dist/engine-BGCEm9E_.d.ts +0 -577
  419. package/dist/module-3NONKBZX.mjs +0 -1860
  420. package/dist/release-BH3DKW3T.mjs +0 -33
  421. package/dist/restore-queue-JPRBUYII.mjs +0 -35
  422. package/dist/runtime-ZKYZFJJC.mjs +0 -177
  423. package/dist/snapshot-HOGXNO5W.mjs +0 -793
  424. package/dist/tasks-HG3rlxx6.d.ts +0 -302
  425. package/dist/thread-B657LQXK.mjs +0 -692
  426. package/dist/write-XLIGTXBU.mjs +0 -238
@@ -1,4 +1,867 @@
1
- import { A as AnyDocument, S as SchemaDefinition, d as ScoringMode } from './schema-4W_7tk1f.js';
1
+ import { E as EmbeddingAdapter, R as RerankAdapter } from './adapters-pljAqmrC.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-CzG9OUw5.js';
3
+ import { h as QuerySuggestionsBuildEvent, j as QuerySuggestionsWarningEvent } from './query-suggestions-CBYkrQ5T.js';
4
+ import { a as SynonymRule } from './synonyms-CpOAHPa-.js';
5
+
6
+ /**
7
+ * Compares one field against a value. Setting several keys narrows the match,
8
+ * because a document has to satisfy all of them.
9
+ *
10
+ * @public
11
+ */
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];
31
+ };
32
+ /**
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.
71
+ *
72
+ * @public
73
+ */
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
+ };
174
+ /**
175
+ * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
176
+ * `enum[]`, `verbatim[]`, or `string[]` field.
177
+ *
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`.
182
+ *
183
+ * @public
184
+ */
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;
192
+ };
193
+ /**
194
+ * Tests whether a field carries a value at all, without looking at what it
195
+ * holds.
196
+ *
197
+ * @public
198
+ */
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
+ };
209
+ /**
210
+ * Matches a `geopoint` field against a circle drawn on the earth.
211
+ *
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.
243
+ *
244
+ * @public
245
+ */
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
+ };
270
+ };
271
+ /**
272
+ * Either shape a `geopoint` field is matched against.
273
+ *
274
+ * @public
275
+ */
276
+ type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
277
+ /**
278
+ * The filter one field accepts. Which of these forms applies follows from the
279
+ * field's declared type.
280
+ *
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.
294
+ *
295
+ * @public
296
+ */
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
+
308
+ /**
309
+ * How a query reorders its top hits with a rerank adapter.
310
+ *
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.
316
+ *
317
+ * @public
318
+ */
319
+ interface RerankConfig {
320
+ /**
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.
324
+ */
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;
349
+ }
350
+
351
+ /**
352
+ * Vector-search inputs passed under `QueryParams.vector`.
353
+ *
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.
357
+ *
358
+ * @public
359
+ */
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
+ * A vector or hybrid query throws a `NarsilError` with `CONFIG_INVALID`
403
+ * before it searches when `efSearch` is not a whole number from 1 to
404
+ * 10,000, whether or not the field holds a graph yet and whether or not
405
+ * its filter matches a document.
406
+ */
407
+ efSearch?: number;
408
+ /**
409
+ * The engine re-scores this many times k candidates in a quantized field
410
+ * against the full-precision vectors before it returns the best `limit`,
411
+ * where k is one more than the number of hits up to the end of the page, so
412
+ * k is `limit` plus 1 on a first page. For a value below 1, or for a value
413
+ * that is not a finite number, the engine throws a `NarsilError` with code
414
+ * `CONFIG_INVALID`. The engine ignores it on a field whose quantization is
415
+ * `none`. When a query leaves it unset, the engine sets the number of
416
+ * candidates that it re-scores from k and from the field's dimension. It
417
+ * rounds that number up, and it re-scores at least 3k candidates under
418
+ * `osq1` and `osq2`, and at least k under `osq4` and `osq8`. Below 768
419
+ * dimensions, it re-scores 3.23k + 55.9√k under `osq1` and 2.6k + 22.5√k under
420
+ * `osq2`. From 768 to 1,023 dimensions, it re-scores 2.2k + 27√k under
421
+ * `osq1` and k + 16√k under `osq2`, and under `osq2` it re-scores at least
422
+ * the smaller of k + 75 and k + 18√k. At 1,024 dimensions and above, it
423
+ * re-scores 3k under both. Under `osq4`, it re-scores 5k below 1,024
424
+ * dimensions and 2k from 1,024 dimensions, while under `osq8` it re-scores
425
+ * 2k at every dimension. Under a filter, the engine counts only the
426
+ * candidates that pass the filter. On vectors spread evenly across every
427
+ * dimension, a one-bit or two-bit code can find fewer than 95% of the true
428
+ * nearest neighbours at these defaults, so raise `oversample` on a query that
429
+ * needs more of them. The engine re-scores at most the larger of 10,000 and
430
+ * the default depth, so a larger `oversample` can't lengthen the walk past
431
+ * that. A vector or hybrid query throws a `NarsilError` with
432
+ * `CONFIG_INVALID` before it searches when `oversample` is not a finite
433
+ * number of at least 1.
434
+ */
435
+ oversample?: number;
436
+ }
437
+ /**
438
+ * How a hybrid query merges its keyword ranking with its vector ranking.
439
+ *
440
+ * `rrf` combines the two by rank alone, which needs no tuning and handles
441
+ * scores that live on different scales. `linear` blends the scores directly,
442
+ * which gives you control once you know what each side's scores look like.
443
+ *
444
+ * @public
445
+ */
446
+ interface HybridConfig {
447
+ /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
448
+ strategy?: 'rrf' | 'linear';
449
+ /** 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. */
450
+ k?: number;
451
+ /** 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. */
452
+ alpha?: number;
453
+ /**
454
+ * Set a depth to get the same fused order on every page of one query, and
455
+ * a cursor that resumes it. The engine then fetches this many results from
456
+ * the keyword search and from the vector search, fuses them, and pages
457
+ * through the top `depth` of the fused list. The last page stops at this
458
+ * depth, so it can hold fewer hits than the limit. Set a whole number from 1
459
+ * to 10,000. The engine throws `CONFIG_INVALID` for any other value, and
460
+ * `SEARCH_RESULT_WINDOW_EXCEEDED` for a page that starts at this depth or
461
+ * beyond. Where you leave the depth out, each search fetches only enough
462
+ * results to fill the page, so the fused order can change from one page to
463
+ * the next, and a cluster refuses a cursor with `SEARCH_INVALID_CURSOR`.
464
+ */
465
+ depth?: number;
466
+ }
467
+
468
+ /**
469
+ * Everything {@link Narsil.suggest} accepts.
470
+ *
471
+ * @public
472
+ */
473
+ interface SuggestParams {
474
+ /** The returned terms complete this text. */
475
+ prefix: string;
476
+ /** The lookup returns this many completions, most widely used first, and 10 by default. */
477
+ limit?: number;
478
+ }
479
+ /**
480
+ * Everything {@link Narsil.listDocuments} accepts.
481
+ *
482
+ * {@link Narsil.listDocuments} reads the stored documents without ranking them,
483
+ * which is how you page through a whole index. Leave `cursor` out to start at
484
+ * the first document, then pass back the cursor each result carries until it
485
+ * comes back null.
486
+ *
487
+ * A cursor belongs to the sort it was made under, so pass the same `sort` back
488
+ * with it. Changing `sort` invalidates the cursor, and the engine then throws
489
+ * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
490
+ *
491
+ * @public
492
+ */
493
+ interface ListParams {
494
+ /**
495
+ * This cursor comes from a previous result, and continues where it stopped.
496
+ * The engine ties a cursor to the sort that produced it, and it throws
497
+ * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
498
+ */
499
+ cursor?: string;
500
+ /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
501
+ limit?: number;
502
+ /** This narrows the listing to the documents the filter accepts. */
503
+ filters?: FilterExpression;
504
+ /**
505
+ * This orders the listing by field value rather than by document id, and the
506
+ * engine applies the fields in the order they are listed. Pass an object
507
+ * keyed by field, or a list of fields in the order they apply. It breaks a
508
+ * tie on document id, and it sorts by at most eight fields. The engine uses
509
+ * document-id order when you leave this out.
510
+ *
511
+ * The engine reads every document the listing covers to build a sorted page,
512
+ * so a sorted listing costs more than the default order on a large index.
513
+ */
514
+ sort?: SortSpec;
515
+ /** This chooses how much of each stored document comes back, and the whole document by default. */
516
+ document?: DocumentProjection;
517
+ }
518
+
519
+ /**
520
+ * Which engine answers a query: keyword matching, vector similarity, or both
521
+ * merged into one ranking.
522
+ *
523
+ * @public
524
+ */
525
+ type SearchMode = 'fulltext' | 'vector' | 'hybrid';
526
+ /**
527
+ * How many of a query's terms a document has to carry. `all` demands every
528
+ * term, `any` accepts one, and a number demands that many.
529
+ *
530
+ * @public
531
+ */
532
+ type TermMatchPolicy = 'all' | 'any' | number;
533
+ /**
534
+ * One field of a sort, and the direction that field orders by.
535
+ *
536
+ * @public
537
+ */
538
+ interface SortField {
539
+ /** The field the engine reads, which may name a nested field with dots. */
540
+ field: string;
541
+ /** Ascending or descending order for this field. */
542
+ direction: 'asc' | 'desc';
543
+ /**
544
+ * Where a document's field holds a list, the engine sorts that document by
545
+ * one value from the list: the smallest under `'min'`, the largest under
546
+ * `'max'`, and the mean or the median of the list's numbers under `'avg'`
547
+ * or `'median'`. Where you leave this out, the engine uses `'min'` for an
548
+ * ascending sort and `'max'` for a descending one. It sorts by a field that
549
+ * holds a single value as that value stands, under every mode. It throws
550
+ * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
551
+ * schema declares as anything other than `number` or `number[]`.
552
+ */
553
+ mode?: 'min' | 'max' | 'avg' | 'median';
554
+ }
555
+ /**
556
+ * A sort, either as an object keyed by field or as a list of fields in the
557
+ * order they apply.
558
+ *
559
+ * Both forms order by the first field, break a tie on the second, and carry on
560
+ * that way. Prefer the list where the order of the fields matters, because
561
+ * JavaScript moves an all-digit key such as `2024` to the front of an object
562
+ * and the list keeps the order you wrote.
563
+ *
564
+ * @public
565
+ */
566
+ type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
567
+ /**
568
+ * Everything {@link Narsil.query} accepts.
569
+ *
570
+ * Set `term` for keyword search, `vector` for similarity search, and `mode`
571
+ * when you want both. The engine matches nothing for a query carrying neither
572
+ * of them, so page through an index with {@link Narsil.listDocuments}
573
+ * instead.
574
+ *
575
+ * @public
576
+ */
577
+ interface QueryParams {
578
+ /**
579
+ * The engine analyses this text with the index's language module and searches
580
+ * for the terms that result. Words inside double quotes form a phrase, which
581
+ * a document has to hold side by side and in that order inside one field. The
582
+ * engine throws `SEARCH_INVALID_PHRASE` for a phrase of more than 32 words, for
583
+ * more than 32 phrases, and for a phrase on an index with `trackPositions` off.
584
+ * It throws `SEARCH_PHRASE_NOT_READY` while an index with a `string[]` field
585
+ * waits for a rebuild.
586
+ */
587
+ term?: string;
588
+ /** The engine searches the term in these fields, and in every text field in the schema by default. */
589
+ fields?: string[];
590
+ /**
591
+ * The engine scores only the documents that pass this filter. It throws
592
+ * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
593
+ * operator on a field of another type, such as `startsWith` on a number
594
+ * field.
595
+ */
596
+ filters?: FilterExpression;
597
+ /**
598
+ * The engine multiplies the score from each named field by its weight. It
599
+ * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
600
+ * the schema declares, and `CONFIG_INVALID` for a weight that is not a
601
+ * finite number.
602
+ */
603
+ boost?: Record<string, number>;
604
+ /**
605
+ * These BM25 parameters score this search alone, and they override the
606
+ * index's parameters, so a `k1` here also overrides a `k1` that the index
607
+ * sets for a field. The engine validates them on every search, and it throws
608
+ * the same errors as {@link IndexConfig.bm25}, except `SEARCH_INVALID_FIELD`
609
+ * for a name in `fields` that is not a text field. They change no score on a
610
+ * vector search, and on a hybrid search they apply to the keyword ranking
611
+ * alone. A cursor pages only a search with the same parameters.
612
+ */
613
+ bm25?: BM25Params;
614
+ /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
615
+ scoring?: ScoringMode;
616
+ /**
617
+ * The engine drops any hit scoring below this value. It ranks with BM25,
618
+ * which has no fixed upper bound, so a floor that suits one index and one
619
+ * query can reject every hit in another.
620
+ */
621
+ minScore?: number;
622
+ /**
623
+ * The engine keeps a document only where the document matches this many
624
+ * query terms, under the same `tolerance` and `prefixLength` that the search
625
+ * uses. One term is enough by default.
626
+ */
627
+ termMatch?: TermMatchPolicy;
628
+ /**
629
+ * The engine matches an indexed term within this edit distance of a query
630
+ * term, so it finds a document for a query with a typo. It counts each
631
+ * Unicode code point as one character. Set an integer from 0 to 10.
632
+ */
633
+ tolerance?: number;
634
+ /**
635
+ * The engine applies `tolerance` only to the indexed terms that share this
636
+ * many leading characters with the query term, or to the terms that start
637
+ * with the whole query term when the query term is shorter. Set an integer
638
+ * from 0 to 1,024; the default is 2.
639
+ */
640
+ prefixLength?: number;
641
+ /**
642
+ * With this set, the engine treats the last query term as an unfinished
643
+ * word, so `secur` matches `security`. The engine matches that last term by
644
+ * its stem or by completing it, while `tolerance` applies only to the earlier
645
+ * terms, which have to match whole. The engine scores completions against a
646
+ * shared document frequency. It also ranks them below whole-word matches.
647
+ * The engine ignores this setting where `exact` is true, and the setting is
648
+ * false by default.
649
+ */
650
+ prefix?: boolean;
651
+ /**
652
+ * With this set, the engine also matches each query word of three or more
653
+ * characters inside the longer words of every field whose type includes
654
+ * `partial`, so a search for `proof` matches a document with `waterproof`
655
+ * in such a field. The engine counts each Unicode code point as one
656
+ * character. It looks for the query word, before stemming, inside each word
657
+ * exactly as that word appears in a document.
658
+ *
659
+ * The engine adds at most 50 such words to a query, which it divides as
660
+ * evenly as it can among the query words. Within the share of each query
661
+ * word, it adds first the words that the most documents contain. It scores
662
+ * a match inside a longer word in proportion to the part of that word that
663
+ * the query word makes up, so it scores such a match below a whole-word
664
+ * match at the same frequency in a field of the same length. With
665
+ * `highlight`, it tags each whole word that contains a query word in a
666
+ * searched `partial` field.
667
+ *
668
+ * The engine applies no `tolerance` to these matches. It ignores this
669
+ * setting where `exact` is true or where the searched fields include no
670
+ * `partial` field. Where the setting is absent, the engine treats it as
671
+ * false, while it throws `CONFIG_INVALID` for any value other than `true`
672
+ * or `false`.
673
+ */
674
+ partialWords?: boolean;
675
+ /**
676
+ * With this set, the engine matches each query term only against an equal
677
+ * indexed term, so it turns off fuzzy matching, prefix completion,
678
+ * partial-word matching, and synonyms. The engine still stems the query, because the
679
+ * index stores stemmed terms, so a search for `running` matches a document
680
+ * that contains `runs` through the stem that both words share.
681
+ */
682
+ exact?: boolean;
683
+ /**
684
+ * The engine counts the values of these fields across the matching
685
+ * documents, and each entry sets how it cuts and sorts that field's counts.
686
+ * For a field outside the schema, it counts the values that the documents
687
+ * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
688
+ * field.
689
+ */
690
+ facets?: FacetConfig;
691
+ /**
692
+ * The engine sorts the hits by the values of these fields, in place of the
693
+ * relevance ranking. Pass an object keyed by field, or a list of fields in
694
+ * the order that the engine compares them. The engine sorts by a `number`,
695
+ * `boolean`, or `enum` field, by a text field whose type includes
696
+ * `sortable`, or by a list of any of these, which it reduces to one value by
697
+ * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
698
+ * `geopoint` or a vector field, because neither type has an order. It throws
699
+ * the same code for a sort on any other text field, since the engine keeps
700
+ * up to the first 512 code points of every document's value in memory to
701
+ * sort by a text field. The engine orders hybrid results by fusion, so it
702
+ * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
703
+ * that code for a direction other than `asc` and `desc`.
704
+ */
705
+ sort?: SortSpec;
706
+ /** These settings collapse the hits into groups by field value. */
707
+ group?: GroupConfig;
708
+ /**
709
+ * The query returns this many hits, and 10 by default. Pass 0 to read the
710
+ * match count with no hits. The engine reads a value below 0 as 0. It falls
711
+ * back to the default for `NaN` and for an infinite value, so a page size
712
+ * that you compute from user input never fails the query.
713
+ */
714
+ limit?: number;
715
+ /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
716
+ offset?: number;
717
+ /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
718
+ searchAfter?: string;
719
+ /** These settings name the fields that come back with highlighted snippets. */
720
+ highlight?: HighlightConfig;
721
+ /** These documents take fixed positions, ahead of the ranking. */
722
+ pinned?: Array<{
723
+ /** The engine places the document with this id. */
724
+ docId: string;
725
+ /** The document takes this place in the results, counting from zero. */
726
+ position: number;
727
+ }>;
728
+ /** This picks which engine answers the query. Keyword search runs by default. */
729
+ mode?: SearchMode;
730
+ /** These vector-search inputs are required in `vector` and `hybrid` mode. */
731
+ vector?: VectorQueryConfig;
732
+ /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
733
+ hybrid?: HybridConfig;
734
+ /**
735
+ * These settings reorder the top hits with a rerank adapter, such as a
736
+ * cross-encoder, after the keyword, vector, or hybrid ranking. The count
737
+ * matches the count of the same query without `rerank`, while the facets
738
+ * and the groups come from the first ranking. The engine throws
739
+ * `SEARCH_INVALID_MODE` for a query that also sets a sort, and
740
+ * `RERANK_FAILED` where the adapter fails or outlasts the engine's
741
+ * `rerankTimeout`.
742
+ */
743
+ rerank?: RerankConfig;
744
+ /**
745
+ * Setting this returns relevance scores on a sorted query. A query that
746
+ * names a sort ranks by sort values alone and computes no scores, so its
747
+ * hits carry none until this restores them. A query without a sort ignores
748
+ * this and always carries scores.
749
+ */
750
+ includeScores?: boolean;
751
+ /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
752
+ includeScoreComponents?: boolean;
753
+ /** This chooses how much of each stored document comes back, and the whole document by default. */
754
+ document?: DocumentProjection;
755
+ }
756
+ /**
757
+ * How much of a stored document each hit carries back.
758
+ *
759
+ * Pass `false` when the ids and scores are all you need, and every hit's
760
+ * `document` is then an empty object. Pass `include` to keep named fields
761
+ * alone, or `exclude` to drop named fields and keep the rest; naming both
762
+ * keeps the included fields and then drops the excluded ones from those. Use
763
+ * dots to name a nested field, so `author.name` addresses the `name` inside
764
+ * `author`, and a name that matches no field changes nothing.
765
+ *
766
+ * Drop a vector field on a similarity search, because the engine otherwise
767
+ * reads every hit's vector back out of the index and writes it into the
768
+ * response.
769
+ *
770
+ * @public
771
+ */
772
+ type DocumentProjection = boolean | {
773
+ /** Names the fields to keep, so every field left out of this list is dropped. */
774
+ include?: string[];
775
+ /** Names the fields to drop, so every other field is kept. */
776
+ exclude?: string[];
777
+ };
778
+ /**
779
+ * Fields a query counts values for, keyed by field name.
780
+ *
781
+ * @public
782
+ */
783
+ interface FacetConfig {
784
+ /** Each key names a field the query counts values for. */
785
+ [field: string]: {
786
+ /** 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`. */
787
+ limit?: number;
788
+ /** 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. */
789
+ sort?: 'asc' | 'desc';
790
+ /** 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. */
791
+ ranges?: Array<{
792
+ /** The range starts at this value. */
793
+ from: number;
794
+ /** The range ends at this value. */
795
+ to: number;
796
+ }>;
797
+ };
798
+ }
799
+ /**
800
+ * How a query collapses its hits into groups.
801
+ *
802
+ * @public
803
+ */
804
+ interface GroupConfig {
805
+ /** The values of these fields define a group, and several fields group by their combination. */
806
+ fields: string[];
807
+ /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
808
+ maxPerGroup?: number;
809
+ /** The engine returns this many groups, best first, and every group where you leave this out. */
810
+ limit?: number;
811
+ /**
812
+ * The engine folds every hit of each group into one value, such as a sum or
813
+ * an average, including the hits beyond `maxPerGroup`. In cluster mode the
814
+ * coordinator fetches up to 10,000 hits of each group to fold.
815
+ */
816
+ reduce?: GroupReducer;
817
+ }
818
+ /**
819
+ * Folds the hits of one group into a single value.
820
+ *
821
+ * @public
822
+ */
823
+ type GroupReducer = {
824
+ /**
825
+ * Folds one hit into the running value.
826
+ *
827
+ * @param accumulator - What the previous call returned, or what
828
+ * `initialValue` produced for the first hit.
829
+ * @param doc - The hit's stored document.
830
+ * @param score - The hit's relevance score.
831
+ * @returns The new running value.
832
+ */
833
+ reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
834
+ /** Produces the starting value for each group. The engine calls it once per group. */
835
+ initialValue: () => unknown;
836
+ };
837
+ /**
838
+ * This configuration names the fields that receive highlighted snippets. It
839
+ * also sets how the engine marks those snippets up.
840
+ *
841
+ * The engine analyses the text of each returned field again to tag every word
842
+ * that it matched, so it tags the same words whatever the index's
843
+ * `trackPositions` setting is. It tags a word whose stem equals a query stem,
844
+ * and a word within the query's `tolerance` of a query stem. For a `prefix`
845
+ * query, it tags a word for the last query term only when that word completes
846
+ * the term or shares its stem.
847
+ *
848
+ * @public
849
+ */
850
+ interface HighlightConfig {
851
+ /** The engine highlights these fields. */
852
+ fields: string[];
853
+ /** The engine writes this before each match, and writes `<mark>` by default. */
854
+ preTag?: string;
855
+ /** The engine writes this after each match, and writes `</mark>` by default. */
856
+ postTag?: string;
857
+ /**
858
+ * The engine takes this many characters of the field around the densest run
859
+ * of matches, 200 by default. It returns a snippet longer than that number,
860
+ * because it then adds the opening and closing tags, and an ellipsis at each
861
+ * end where it cuts the field.
862
+ */
863
+ maxSnippetLength?: number;
864
+ }
2
865
 
3
866
  /**
4
867
  * Every code a {@link NarsilError} carries, grouped by the part of the engine
@@ -35,6 +898,28 @@ declare const ErrorCodes: {
35
898
  readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
36
899
  readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
37
900
  readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
901
+ readonly PERSISTENCE_DEPENDENCY_MISSING: "PERSISTENCE_DEPENDENCY_MISSING";
902
+ readonly BACKUP_NOT_FOUND: "BACKUP_NOT_FOUND";
903
+ readonly BACKUP_ALREADY_EXISTS: "BACKUP_ALREADY_EXISTS";
904
+ readonly BACKUP_DAMAGED: "BACKUP_DAMAGED";
905
+ readonly BACKUP_DURABILITY_REQUIRED: "BACKUP_DURABILITY_REQUIRED";
906
+ readonly BACKUP_IN_PROGRESS: "BACKUP_IN_PROGRESS";
907
+ readonly BACKUP_STORE_CLAIMED: "BACKUP_STORE_CLAIMED";
908
+ readonly BACKUP_STORE_NOT_CONFIGURED: "BACKUP_STORE_NOT_CONFIGURED";
909
+ readonly BACKUP_NOT_READY: "BACKUP_NOT_READY";
910
+ readonly SYNC_DURABILITY_REQUIRED: "SYNC_DURABILITY_REQUIRED";
911
+ readonly SYNC_BACKUP_STORE_REQUIRED: "SYNC_BACKUP_STORE_REQUIRED";
912
+ readonly SYNC_NOT_READY: "SYNC_NOT_READY";
913
+ readonly SYNC_NOT_ENABLED: "SYNC_NOT_ENABLED";
914
+ readonly SYNC_SNAPSHOT_PREPARING: "SYNC_SNAPSHOT_PREPARING";
915
+ readonly CHANGES_DURABILITY_REQUIRED: "CHANGES_DURABILITY_REQUIRED";
916
+ readonly CHANGES_BACKUP_STORE_REQUIRED: "CHANGES_BACKUP_STORE_REQUIRED";
917
+ readonly CHANGES_NOT_READY: "CHANGES_NOT_READY";
918
+ readonly CHANGES_NOT_ENABLED: "CHANGES_NOT_ENABLED";
919
+ readonly CHANGES_PREVIOUS_DOCUMENT_REQUIRED: "CHANGES_PREVIOUS_DOCUMENT_REQUIRED";
920
+ readonly CHANGES_EXPORT_PREPARING: "CHANGES_EXPORT_PREPARING";
921
+ readonly CHANGES_INVALID_POSITIONS: "CHANGES_INVALID_POSITIONS";
922
+ readonly QUERY_SUGGESTIONS_NOT_ENABLED: "QUERY_SUGGESTIONS_NOT_ENABLED";
38
923
  readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
39
924
  readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
40
925
  readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
@@ -42,11 +927,25 @@ declare const ErrorCodes: {
42
927
  readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
43
928
  readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
44
929
  readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
930
+ /**
931
+ * An engine fault: a write changed the index during a search that held every
932
+ * write, so the search could not answer from one state. A correct engine
933
+ * never raises it, and retrying the request does not help.
934
+ */
935
+ readonly SEARCH_STATE_MOVED: "SEARCH_STATE_MOVED";
936
+ readonly SEARCH_INVALID_PHRASE: "SEARCH_INVALID_PHRASE";
937
+ readonly SEARCH_PHRASE_NOT_READY: "SEARCH_PHRASE_NOT_READY";
938
+ readonly BM25_NOT_READY: "BM25_NOT_READY";
45
939
  readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
46
940
  readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
47
941
  readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
48
942
  readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
49
943
  readonly RESTORE_MEMORY_EXCEEDED: "RESTORE_MEMORY_EXCEEDED";
944
+ readonly MEMORY_WRITE_BLOCKED: "MEMORY_WRITE_BLOCKED";
945
+ readonly ANALYSIS_CHANGE_REPLACED: "ANALYSIS_CHANGE_REPLACED";
946
+ readonly ANALYSIS_CHANGE_NOT_READY: "ANALYSIS_CHANGE_NOT_READY";
947
+ readonly ANALYSIS_GENERATION_MISSING: "ANALYSIS_GENERATION_MISSING";
948
+ readonly ANALYSIS_REBUILD_MEMORY_EXCEEDED: "ANALYSIS_REBUILD_MEMORY_EXCEEDED";
50
949
  readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
51
950
  readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
52
951
  readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
@@ -59,6 +958,7 @@ declare const ErrorCodes: {
59
958
  readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
60
959
  readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
61
960
  readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
961
+ readonly SEARCH_CONTEXT_MISSING: "SEARCH_CONTEXT_MISSING";
62
962
  readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
63
963
  readonly CLUSTER_WRITE_BLOCKED: "CLUSTER_WRITE_BLOCKED";
64
964
  readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
@@ -70,11 +970,17 @@ declare const ErrorCodes: {
70
970
  readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
71
971
  readonly NODE_NOT_READY: "NODE_NOT_READY";
72
972
  readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
973
+ readonly NODE_VERSION_INCOMPATIBLE: "NODE_VERSION_INCOMPATIBLE";
73
974
  readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
975
+ readonly COORDINATOR_AUTH_FAILED: "COORDINATOR_AUTH_FAILED";
976
+ readonly COORDINATOR_UNAVAILABLE: "COORDINATOR_UNAVAILABLE";
74
977
  readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
978
+ readonly NATIVE_DEPENDENCY_MISSING: "NATIVE_DEPENDENCY_MISSING";
75
979
  readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
76
980
  readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
77
981
  readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
982
+ readonly REPLICATION_OUTCOME_UNKNOWN: "REPLICATION_OUTCOME_UNKNOWN";
983
+ readonly REPLICATION_WRITE_CONFLICT: "REPLICATION_WRITE_CONFLICT";
78
984
  readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
79
985
  readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
80
986
  readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
@@ -150,8 +1056,10 @@ type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
150
1056
  * a server, or where the caller cannot read the answer.
151
1057
  *
152
1058
  * The HTTP client raises the first five. The React bindings raise
153
- * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. No
154
- * server sends any of them, so a failure under one means the exchange broke
1059
+ * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. A
1060
+ * synced device raises `SYNC_ANALYSIS_UNAVAILABLE` before it downloads a
1061
+ * snapshot whose language, tokeniser, or stop words it has not registered,
1062
+ * and it keeps its copy of the index. No server sends any of them, so a failure under one means the exchange broke
155
1063
  * before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
156
1064
  * therefore maps none of them, because no request can arrive under one and no
157
1065
  * HTTP status belongs to one.
@@ -165,6 +1073,7 @@ declare const ClientErrorCodes: {
165
1073
  readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
166
1074
  readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
167
1075
  readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
1076
+ readonly SYNC_ANALYSIS_UNAVAILABLE: "SYNC_ANALYSIS_UNAVAILABLE";
168
1077
  };
169
1078
  /**
170
1079
  * Any one of the codes in {@link ClientErrorCodes}.
@@ -222,230 +1131,13 @@ declare class NarsilError extends Error {
222
1131
  * that the constructor writes, so it returns true for an error from any entry
223
1132
  * point.
224
1133
  *
225
- * @param value - The value that a `catch` block receives.
226
- * @returns True where the value holds a code in {@link NarsilError.code}.
227
- *
228
- * @public
229
- */
230
- declare function isNarsilError(value: unknown): value is NarsilError;
231
-
232
- /**
233
- * What {@link Narsil.query} returns: the ranked hits and everything the query
234
- * asked for alongside them.
235
- *
236
- * @typeParam T - Shape of the stored documents, which flows through to each
237
- * hit's `document`.
238
- *
239
- * @public
240
- */
241
- interface QueryResult<T = AnyDocument> {
242
- /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
243
- hits: Array<Hit<T>>;
244
- /**
245
- * This many documents match in total, before the engine applies `limit`
246
- * and `offset`. For a keyword search the engine counts every match. For a
247
- * vector search it counts every vector that passes the query's filter and
248
- * its `similarity` floor, which is every vector in the field where the query
249
- * sets neither of them. The engine also counts each pinned document that
250
- * the query does not match, since it places that document among the hits.
251
- */
252
- count: number;
253
- /**
254
- * `count` holds the exact number of matches where this is true, and a
255
- * number at or below the true total where it is false. Where a query sets a
256
- * `similarity` floor on a vector field that holds a graph, the engine
257
- * counts only the vectors that it fetches, because it compares the query
258
- * with only a fraction of that field's vectors. For a hybrid query the
259
- * engine fuses two rankings, so the count is exact only where each of those
260
- * rankings contains every matching document. Where you pin a document from
261
- * outside the hits that the engine fetches, the engine reports true only
262
- * where it holds every match of the query, because only then can it test
263
- * whether the query matches that document.
264
- */
265
- countExact: boolean;
266
- /** The engine spent this many milliseconds on the search. */
267
- elapsed: number;
268
- /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
269
- cursor?: string;
270
- /** These facet counts are keyed by the field each facet was asked for. */
271
- facets?: Record<string, FacetResult>;
272
- /** These groups arrive when the query asked for grouping. */
273
- groups?: GroupResult[];
274
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
275
- analysisStale?: boolean;
276
- /** The search read this much of the index, which is how you spot a degraded answer. */
277
- coverage: QueryCoverage;
278
- }
279
- /**
280
- * How much of an index one search read, which is what you check before you
281
- * trust a count or a ranking.
282
- *
283
- * An embedded engine reads every partition it holds, so `queriedPartitions`
284
- * matches `totalPartitions` there and the other two stay zero. A search across
285
- * a cluster may find a node slow or unreachable, which it counts here while
286
- * still returning the hits the other nodes gave it.
287
- *
288
- * @public
289
- */
290
- interface QueryCoverage {
291
- /** The search should have read this many partitions. */
292
- totalPartitions: number;
293
- /** The search read this many of them. */
294
- queriedPartitions: number;
295
- /** The search counts a partition here when the node holding it took longer than the query allowed. */
296
- timedOutPartitions: number;
297
- /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
298
- failedPartitions: number;
299
- }
300
- /**
301
- * One matching document, with the score that ranked it.
302
- *
303
- * @typeParam T - Shape of the stored document.
304
- *
305
- * @public
306
- */
307
- interface Hit<T = AnyDocument> {
308
- /** The document is stored under this id. */
309
- id: string;
310
- /**
311
- * This score ranked the hit. Scores compare within one result set, never
312
- * across searches. A sorted query ranks by sort values instead and carries
313
- * no score unless it sets `includeScores`.
314
- */
315
- score?: number;
316
- /** This is the stored document. */
317
- document: T;
318
- /** These are the parts the score was built from, which arrive when the query asked for them. */
319
- scoreComponents?: ScoreComponents;
320
- /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
321
- highlights?: Record<string, HighlightMatch>;
322
- }
323
- /**
324
- * The numbers BM25 combined into one hit's score, which is what you read when
325
- * a ranking surprises you.
326
- *
327
- * @public
328
- */
329
- interface ScoreComponents {
330
- /**
331
- * Each query term appears in one field of this document this many times,
332
- * under a key of `field:term`. A term that appears in two fields therefore
333
- * has two entries here, while the keys of {@link ScoreComponents.idf} hold
334
- * the bare term.
335
- */
336
- termFrequencies: Record<string, number>;
337
- /** Each field the query searched holds this many tokens, keyed by field. */
338
- fieldLengths: Record<string, number>;
339
- /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
340
- idf: Record<string, number>;
341
- }
342
- /**
343
- * A highlighted field, ready to render.
344
- *
345
- * @public
346
- */
347
- interface HighlightMatch {
348
- /** This is the field's text around the match, wrapped in the query's tags. */
349
- snippet: string;
350
- /**
351
- * Each range gives the start and the end of one match in the original field,
352
- * so you can render the highlight yourself. Where the snippet covers part of
353
- * the field alone, the engine lists only the matches that the snippet
354
- * displays. Every offset is a character count from the start of the original
355
- * field, whatever the snippet contains.
356
- */
357
- positions: Array<{
358
- start: number;
359
- end: number;
360
- }>;
361
- }
362
- /**
363
- * Counts for one faceted field.
364
- *
365
- * @public
366
- */
367
- interface FacetResult {
368
- /** This many documents match per value, keyed by value. */
369
- values: Record<string, number>;
370
- /** This is the number of entries in `values`, which is at most the facet's `limit`. */
371
- count: number;
372
- /**
373
- * Every count in `values` is at most this far below its true count. A value
374
- * that the engine leaves out of `values` because of `limit` has a true
375
- * count of at most this figure too. Where the engine counts a field on one
376
- * thread, it counts every value exactly, so this figure is the largest
377
- * count that it leaves out. Where it splits the count across worker copies
378
- * or cluster nodes, each of them returns only its own top values, so the
379
- * merged count of a value that is common overall but rare on one of them
380
- * can lack the matches on that one. A bound of 0 means that `values` holds
381
- * every matching value, each with its exact count.
382
- */
383
- errorBound: number;
384
- }
385
- /**
386
- * One group of hits, produced by a query that grouped its results.
387
- *
388
- * @public
389
- */
390
- interface GroupResult {
391
- /** Each grouping field holds this value for the group, keyed by field. */
392
- values: Record<string, unknown>;
393
- /** These hits fall in the group, cut to the query's `maxPerGroup`. */
394
- hits: Array<Hit>;
395
- /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
396
- reduced?: unknown;
397
- /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
398
- reducerError?: string;
399
- }
400
- /**
401
- * What {@link Narsil.preflight} returns: how many documents a query matches,
402
- * without building or ranking a single hit.
403
- *
404
- * @public
405
- */
406
- interface PreflightResult {
407
- /** The query matches this many documents. */
408
- count: number;
409
- /** `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}. */
410
- countExact: boolean;
411
- /** The count took this many milliseconds. */
412
- elapsed: number;
413
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
414
- analysisStale?: boolean;
415
- }
416
- /**
417
- * What a batch write returns. One bad document never abandons the rest, so
418
- * read both lists.
419
- *
420
- * @public
421
- */
422
- interface BatchResult {
423
- /** The engine wrote the documents under these ids. */
424
- succeeded: string[];
425
- /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
426
- failed: Array<{
427
- docId: string;
428
- error: NarsilError;
429
- }>;
430
- }
431
- /**
432
- * What {@link Narsil.importDocumentExport} returns. The engine continues past each
433
- * refused line, so read the refusals to learn which documents it skipped.
434
- *
435
- * @public
436
- */
437
- interface DocumentImportResult {
438
- /** The engine wrote this many documents, counting each one that it replaced. */
439
- imported: number;
440
- /** The engine refused this many lines in total. */
441
- refusedCount: number;
442
- /** 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. */
443
- refused: Array<{
444
- line: number;
445
- code: NarsilErrorCode;
446
- message: string;
447
- }>;
448
- }
1134
+ * @param value - The value that a `catch` block receives.
1135
+ * @returns True where the value holds a code in {@link NarsilError.code}.
1136
+ *
1137
+ * @public
1138
+ */
1139
+ declare function isNarsilError(value: unknown): value is NarsilError;
1140
+
449
1141
  /**
450
1142
  * What {@link Narsil.getStats} returns about one index.
451
1143
  *
@@ -466,10 +1158,47 @@ interface IndexStats {
466
1158
  * when sizing host memory.
467
1159
  */
468
1160
  estimatedMemoryBytes: number;
1161
+ /**
1162
+ * The files that the index's current checkpoint lists hold this many bytes:
1163
+ * the segment files of every partition, the vector files, and the graph
1164
+ * parts. The figure changes only when a checkpoint commits, so an unchanged
1165
+ * index reports the same size before and after a restart. A closed index
1166
+ * reports the size that its last checkpoint recorded, and an index that
1167
+ * saves nothing reports no figure. In a cluster, the figure covers the copy
1168
+ * of each partition that the stats call read.
1169
+ */
1170
+ savedBytes?: number;
1171
+ /**
1172
+ * The index's write-ahead log and the history that it keeps for device sync
1173
+ * hold this many bytes. The figure grows with every write, and it falls when
1174
+ * the engine deletes log or history files. A closed index reports no figure,
1175
+ * and neither does an index that saves nothing.
1176
+ */
1177
+ logBytes?: number;
1178
+ /**
1179
+ * A cluster adds up {@link IndexStats.savedBytes} over every copy of every
1180
+ * partition, which shows the disk space that the index takes across all of
1181
+ * its nodes. The figure is absent outside a cluster, and it is absent
1182
+ * whenever a copy fails to answer or reports no saved size.
1183
+ */
1184
+ savedBytesOfEveryCopy?: number;
1185
+ /**
1186
+ * A cluster adds up {@link IndexStats.logBytes} over every copy of every
1187
+ * partition. The figure is absent outside a cluster, and it is absent
1188
+ * whenever a copy fails to answer or reports no log size.
1189
+ */
1190
+ logBytesOfEveryCopy?: number;
469
1191
  /** The index analyses text with this language module. */
470
1192
  language: string;
471
1193
  /** The index was created with this field layout. */
472
1194
  schema: SchemaDefinition;
1195
+ /**
1196
+ * This many searches on this instance's main copy hold a state of the index
1197
+ * open right now. Each search holds one state from its start until it
1198
+ * answers, fails, or is cancelled, so the figure falls back to 0 once every
1199
+ * search has finished. A cluster reports no figure.
1200
+ */
1201
+ heldSearchStates?: number;
473
1202
  }
474
1203
  /**
475
1204
  * A summary of one index, as {@link Narsil.listIndexes} reports it.
@@ -510,913 +1239,636 @@ interface PartitionStatsResult {
510
1239
  * include per-object overhead. Treat as an estimate, not a measurement.
511
1240
  */
512
1241
  estimatedMemoryBytes: number;
513
- }
514
- /**
515
- * What {@link Narsil.suggest} returns: the indexed terms that complete a
516
- * prefix, ready to offer as you-type suggestions.
517
- *
518
- * @public
519
- */
520
- interface SuggestResult {
521
- /** These completions run most widely used first. */
522
- terms: Array<{
523
- /** This is the completed term, as the index holds it. */
524
- term: string;
525
- /** The term appears in this many documents, which is what ordered the list. */
526
- documentFrequency: number;
527
- }>;
528
- /** The lookup took this many milliseconds. */
529
- elapsed: number;
530
- /** This turns true when the index's terms came from an older analysis than its language module produces now. */
531
- analysisStale?: boolean;
532
- }
533
- /**
534
- * The state of one vector field, and what maintenance would cost, as
535
- * {@link Narsil.vectorMaintenanceStatus} reports it.
536
- *
537
- * Removing a vector leaves a tombstone in the graph, and enough of them slow a
538
- * search down. Read this to decide when compaction earns its cost.
539
- *
540
- * @public
541
- */
542
- interface VectorMaintenanceResult {
543
- /** This describes the named vector field. */
544
- fieldName: string;
545
1242
  /**
546
- * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
547
- * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
548
- * the engine divides by the number of stored vectors, because no graph
549
- * exists yet.
1243
+ * The segment files that the index's current checkpoint lists for this
1244
+ * partition hold this many bytes. The vector files and graph parts belong to
1245
+ * the whole index, so only {@link IndexStats.savedBytes} counts them.
550
1246
  */
551
- tombstoneRatio: number;
552
- /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
553
- graphCount: number;
554
- /** This many vectors wait outside the graph, which a search scans one by one. */
555
- bufferSize: number;
556
- /** This stays true while a graph build runs. */
557
- building: boolean;
558
- /** {@link Narsil.compactVectors} would take about this many milliseconds. */
559
- estimatedCompactMs: number;
560
- /** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
561
- estimatedOptimizeMs: number;
562
- }
563
- /**
564
- * One stored document, as {@link Narsil.listDocuments} returns it.
565
- *
566
- * @typeParam T - Shape of the stored document.
567
- *
568
- * @public
569
- */
570
- interface ListedDocument<T = AnyDocument> {
571
- /** The document is stored under this id. */
572
- id: string;
573
- /** This holds the stored document, cut down to what the projection kept. */
574
- document: T;
575
- }
576
- /**
577
- * What {@link Narsil.listDocuments} returns: one page of stored documents and
578
- * the cursor that reaches the next one.
579
- *
580
- * @typeParam T - Shape of the stored documents.
581
- *
582
- * @public
583
- */
584
- interface ListResult<T = AnyDocument> {
585
- /** These documents make up the page, in ascending document-id order. */
586
- documents: Array<ListedDocument<T>>;
587
- /** This opaque cursor reaches the next page, and is null once the listing is finished. */
588
- cursor: string | null;
589
- /** The listing covers this many documents in total, and any filter narrows that count. */
590
- total: number;
591
- /** The engine spent this many milliseconds building the page. */
592
- elapsed: number;
593
- }
594
-
595
- /**
596
- * Compares one field against a value. Setting several keys narrows the match,
597
- * because a document has to satisfy all of them.
598
- *
599
- * @public
600
- */
601
- type ComparisonFilter = {
602
- /** This matches a field equal to the value, or a list field where one element equals it. */
603
- eq?: number | string | boolean;
1247
+ savedBytes?: number;
1248
+ /** This partition's write-ahead log files and device-sync history files hold this many bytes. */
1249
+ logBytes?: number;
604
1250
  /**
605
- * This matches a document that holds the field with a value other than this
606
- * one, or a list field where every element differs from it, which an empty
607
- * list does.
1251
+ * A cluster adds up {@link PartitionStatsResult.savedBytes} over every copy
1252
+ * of this partition. The figure is absent outside a cluster, and it is
1253
+ * absent whenever a copy fails to answer or reports no saved size.
608
1254
  */
609
- ne?: number | string | boolean;
610
- /** This matches a field greater than the number. */
611
- gt?: number;
612
- /** This matches a field less than the number. */
613
- lt?: number;
614
- /** This matches a field greater than or equal to the number. */
615
- gte?: number;
616
- /** This matches a field less than or equal to the number. */
617
- lte?: number;
618
- /** This matches a field inside the inclusive range, given as `[low, high]`. */
619
- between?: [number, number];
620
- };
1255
+ savedBytesOfEveryCopy?: number;
1256
+ /**
1257
+ * A cluster adds up {@link PartitionStatsResult.logBytes} over every copy of
1258
+ * this partition. The figure is absent outside a cluster, and it is absent
1259
+ * whenever a copy fails to answer or reports no log size.
1260
+ */
1261
+ logBytesOfEveryCopy?: number;
1262
+ }
1263
+
621
1264
  /**
622
- * The engine tests a text field against this filter for equality, for a text
623
- * range, or with the set, prefix, and pattern tests.
624
- *
625
- * On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
626
- * element of the list on its own. A document passes `eq`, `in`, `startsWith`,
627
- * `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
628
- * test. However, a document passes `ne` or `nin` only when every element
629
- * differs from the values.
630
- *
631
- * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
632
- * to a single `string` or `verbatim` field whose type includes `sortable`. It
633
- * throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
634
- * orders the values as a sort on the field does, so it compares their case
635
- * folds first and compares their raw code points only where the folds are
636
- * equal.
637
- *
638
- * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
639
- * `string[]` field whose type includes `pattern`. On a pattern field, the
640
- * engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
641
- * `contains`, `wildcard`, and `regex` from the field's pattern index, and
642
- * `caseFold` applies to each of those tests. The engine compares the code
643
- * points of each value as they are stored, with no Unicode normalisation.
644
- *
645
- * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
646
- * `startsWith`, and `endsWith` from the field's index of values. A `string` or
647
- * `string[]` field whose type leaves out `pattern` keeps no index of whole
648
- * values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
649
- * and for `matchesAny` and `containsAll`, on such a field.
650
- *
651
- * The engine also throws `SEARCH_INVALID_FILTER` in these cases:
1265
+ * What {@link Narsil.query} returns: the ranked hits and everything the query
1266
+ * asked for alongside them.
652
1267
  *
653
- * - The filter sets `contains`, `wildcard`, `regex`, or `caseFold` on a field
654
- * that is not a pattern field.
655
- * - The text or the pattern of a test on a pattern field holds more than 1,024
656
- * code points.
657
- * - A literal test under `caseFold` has a text whose case fold holds more than
658
- * 2,048 code points.
659
- * - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
1268
+ * @typeParam T - Shape of the stored documents, which flows through to each
1269
+ * hit's `document`.
660
1270
  *
661
1271
  * @public
662
1272
  */
663
- type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
664
- /** This matches a value that comes after the text in sort order. */
665
- gt?: string;
666
- /** This matches a value that comes before the text in sort order. */
667
- lt?: string;
668
- /** This matches a value equal to the text or after it in sort order. */
669
- gte?: string;
670
- /** This matches a value equal to the text or before it in sort order. */
671
- lte?: string;
672
- /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
673
- between?: [string, string];
674
- /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
675
- in?: string[];
676
- /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
677
- nin?: string[];
678
- /** This matches a field starting with the text. */
679
- startsWith?: string;
680
- /** This matches a field ending with the text. */
681
- endsWith?: string;
682
- /** This matches a pattern field whose value holds the text anywhere in it. */
683
- contains?: string;
1273
+ interface QueryResult<T = AnyDocument> {
1274
+ /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
1275
+ hits: Array<Hit<T>>;
684
1276
  /**
685
- * This matches a pattern field when the whole value matches the wildcard
686
- * pattern. For example, `INV-*-2024` matches `INV-0042-2024`.
687
- *
688
- * In the pattern, `*` matches any sequence of code points, including an
689
- * empty one, and `?` matches exactly one code point. Write `\` before a code
690
- * point to match that code point itself, so `\*` matches an asterisk.
691
- *
692
- * The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
693
- * `\` with no code point after it. It throws the same error for a pattern
694
- * with more than 2,048 positions. Each `*`, each `?`, and each other code
695
- * point counts as one position, except that under `caseFold` a code point
696
- * counts once for each code point of its case fold.
1277
+ * This many documents match in total, before the engine applies `limit`
1278
+ * and `offset`. For a keyword search the engine counts every match. For a
1279
+ * vector search it counts every vector that passes the query's filter and
1280
+ * its `similarity` floor, which is every vector in the field where the query
1281
+ * sets neither of them. The engine also counts each pinned document that
1282
+ * the query does not match, since it places that document among the hits.
697
1283
  */
698
- wildcard?: string;
1284
+ count: number;
699
1285
  /**
700
- * This matches a pattern field when some part of the value matches the
701
- * regular expression. `^` and `$` match only at the start and at the end of
702
- * the whole value.
703
- *
704
- * The engine accepts literal code points, `.`, `\d`, `\w`, and `\s`, sets
705
- * such as `[a-z]` and `[^0-9]`, groups, and `|`. It also accepts the repeats
706
- * `*`, `+`, `?`, `{n}`, `{n,}`, and `{n,m}`, the anchors `^` and `$`, the
707
- * word edge `\b`, and number ranges such as `<1-65535>`. A number range
708
- * matches the digits of any whole number from its low end to its high end.
709
- * Write `\` before an ASCII punctuation mark to match the mark itself. The
710
- * `.` matches any code point, including a line break.
711
- *
712
- * The matcher never backtracks, so it checks a value in at most as many
713
- * steps as the value's code points multiplied by the pattern's positions.
714
- *
715
- * The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
716
- * syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
717
- * flag. It throws the same error when the groups of a pattern nest more than
718
- * 32 deep, when a count is above 2,048, and when a pattern holds more than
719
- * 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
720
- * option to false, the server refuses every `regex` test.
1286
+ * `count` holds the exact number of matches where this is true, and a
1287
+ * number at or below the true total where it is false. Where a query sets a
1288
+ * `similarity` floor on a vector field that holds a graph, the engine
1289
+ * counts only the vectors that it fetches, because it compares the query
1290
+ * with only a fraction of that field's vectors. For a hybrid query the
1291
+ * engine fuses two rankings, so the count is exact only where each of those
1292
+ * rankings contains every matching document. Where you pin a document from
1293
+ * outside the hits that the engine fetches, the engine reports true only
1294
+ * where it holds every match of the query, because only then can it test
1295
+ * whether the query matches that document.
721
1296
  */
722
- regex?: string;
1297
+ countExact: boolean;
1298
+ /** The engine spent this many milliseconds on the search. */
1299
+ elapsed: number;
1300
+ /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
1301
+ cursor?: string;
1302
+ /** These facet counts are keyed by the field each facet was asked for. */
1303
+ facets?: Record<string, FacetResult>;
1304
+ /** These groups arrive when the query asked for grouping. */
1305
+ groups?: GroupResult[];
1306
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1307
+ analysisStale?: boolean;
1308
+ /** The search read this much of the index, which is how you spot a degraded answer. */
1309
+ coverage: QueryCoverage;
1310
+ }
1311
+ /**
1312
+ * How much of an index one search read, which is what you check before you
1313
+ * trust a count or a ranking.
1314
+ *
1315
+ * An embedded engine reads every partition it holds, so `queriedPartitions`
1316
+ * matches `totalPartitions` there and the other two stay zero. A search across
1317
+ * a cluster may find a node slow or unreachable, which it counts here while
1318
+ * still returning the hits the other nodes gave it.
1319
+ *
1320
+ * @public
1321
+ */
1322
+ interface QueryCoverage {
1323
+ /** The search should have read this many partitions. */
1324
+ totalPartitions: number;
1325
+ /** The search read this many of them. */
1326
+ queriedPartitions: number;
1327
+ /** The search counts a partition here when the node holding it took longer than the query allowed. */
1328
+ timedOutPartitions: number;
1329
+ /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
1330
+ failedPartitions: number;
1331
+ }
1332
+ /**
1333
+ * One matching document, with the score that ranked it.
1334
+ *
1335
+ * @typeParam T - Shape of the stored document.
1336
+ *
1337
+ * @public
1338
+ */
1339
+ interface Hit<T = AnyDocument> {
1340
+ /** The document is stored under this id. */
1341
+ id: string;
723
1342
  /**
724
- * When this is true, the engine compares the case fold of each value of a
725
- * pattern field with the case fold of the text, so a test for `error`
726
- * matches `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`,
727
- * `endsWith`, `contains`, `wildcard`, and `regex`.
728
- *
729
- * Under `caseFold`, a set that does not open with `^` can also match a
730
- * sequence of code points. When a member that the set holds on its own folds
731
- * to several code points, the set matches that whole fold, so `[ß]` matches
732
- * `ss`.
1343
+ * This score ranked the hit. Scores compare within one result set, never
1344
+ * across searches. A sorted query ranks by sort values instead and carries
1345
+ * no score unless it sets `includeScores`.
733
1346
  */
734
- caseFold?: boolean;
1347
+ score?: number;
1348
+ /** This is the stored document. */
1349
+ document: T;
1350
+ /** These are the parts the score was built from, which arrive when the query asked for them. */
1351
+ scoreComponents?: ScoreComponents;
1352
+ /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
1353
+ highlights?: Record<string, HighlightMatch>;
1354
+ }
1355
+ /**
1356
+ * The numbers BM25 combined into one hit's score, which is what you read when
1357
+ * a ranking surprises you.
1358
+ *
1359
+ * @public
1360
+ */
1361
+ interface ScoreComponents {
735
1362
  /**
736
- * This lets the `eq` test of a pattern field match a value within this many
737
- * edits of the text, so a test for `INV-2O24` with a tolerance of 1 matches
738
- * `INV-2024`. An edit inserts, deletes, or replaces one code point, so a
739
- * swap of two neighbouring code points counts as two edits. With `caseFold`,
740
- * the engine counts the edits between the case folds of the value and the
741
- * text. The tolerance applies to `eq` alone, so the other tests of the field
742
- * still compare exactly.
743
- *
744
- * The engine takes its candidates from the pattern index, so the case fold
745
- * of the text has to hold enough distinct runs of three code points. For a
746
- * tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
747
- * the number of code points in the longest case fold among the text's code
748
- * points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
749
- * therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
750
- * `'auto'`, the engine uses 2 where the text holds enough runs for 2,
751
- * otherwise 1 where it holds enough for 1, and otherwise 0.
752
- *
753
- * The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
754
- * text with too few runs, stating how many runs that tolerance needs. It
755
- * throws the same error for any other tolerance, for a tolerance on a field
756
- * that is not a pattern field, and for a tolerance in a filter without an
757
- * `eq` test. Towards the pattern work cap, it counts one unit for each cell
758
- * that it fills in the table of edit distances between the text and a
759
- * value.
1363
+ * Each query term appears in one field of this document this many times,
1364
+ * under a key of `field:term`. A term that appears in two fields therefore
1365
+ * has two entries here, while the keys of {@link ScoreComponents.idf} hold
1366
+ * the bare term.
760
1367
  */
761
- tolerance?: 0 | 1 | 2 | 'auto';
762
- };
1368
+ termFrequencies: Record<string, number>;
1369
+ /** Each field the query searched holds this many tokens, keyed by field. */
1370
+ fieldLengths: Record<string, number>;
1371
+ /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
1372
+ idf: Record<string, number>;
1373
+ }
763
1374
  /**
764
- * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
765
- * `enum[]`, `verbatim[]`, or `string[]` field.
766
- *
767
- * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
768
- * field, for a value whose type differs from the type of the list's elements,
769
- * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
770
- * out `pattern`.
1375
+ * A highlighted field, ready to render.
771
1376
  *
772
1377
  * @public
773
1378
  */
774
- type ArrayFilter = {
775
- /** 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. */
776
- containsAll?: (string | number | boolean)[];
777
- /** This matches a list holding at least one of the values, at most 65,536 of them. */
778
- matchesAny?: (string | number | boolean)[];
779
- /** This compares the number of elements in the list. */
780
- size?: ComparisonFilter;
781
- };
1379
+ interface HighlightMatch {
1380
+ /** This is the field's text around the match, wrapped in the query's tags. */
1381
+ snippet: string;
1382
+ /**
1383
+ * Each range gives the start and the end of one match in the original field,
1384
+ * so you can render the highlight yourself. Where the snippet covers part of
1385
+ * the field alone, the engine lists only the matches that the snippet
1386
+ * displays. Every offset is a character count from the start of the original
1387
+ * field, whatever the snippet contains.
1388
+ */
1389
+ positions: Array<{
1390
+ /** The match starts at this offset. */
1391
+ start: number;
1392
+ /** The match ends at this offset. */
1393
+ end: number;
1394
+ }>;
1395
+ }
782
1396
  /**
783
- * Tests whether a field carries a value at all, without looking at what it
784
- * holds.
1397
+ * Counts for one faceted field.
785
1398
  *
786
1399
  * @public
787
1400
  */
788
- type PresenceFilter = {
789
- /** This matches a document where the field holds a value other than null. */
790
- exists?: boolean;
791
- /** This matches a document where the field is absent or null. */
792
- notExists?: boolean;
793
- /** This matches a document where the field is absent, null, an empty string, or an empty list. */
794
- isEmpty?: boolean;
795
- /** This matches a document where the field holds a value other than an empty string or an empty list. */
796
- isNotEmpty?: boolean;
797
- };
1401
+ interface FacetResult {
1402
+ /** This many documents match per value, keyed by value. */
1403
+ values: Record<string, number>;
1404
+ /** This is the number of entries in `values`, which is at most the facet's `limit`. */
1405
+ count: number;
1406
+ /**
1407
+ * Every count in `values` is at most this far below its true count. A value
1408
+ * that the engine leaves out of `values` because of `limit` has a true
1409
+ * count of at most this figure too. Where the engine counts a field on one
1410
+ * thread, it counts every value exactly, so this figure is the largest
1411
+ * count that it leaves out. Where it splits the count across worker copies
1412
+ * or cluster nodes, each of them returns only its own top values, so the
1413
+ * merged count of a value that is common overall but rare on one of them
1414
+ * can lack the matches on that one. A bound of 0 means that `values` holds
1415
+ * every matching value, each with its exact count.
1416
+ */
1417
+ errorBound: number;
1418
+ }
798
1419
  /**
799
- * Matches a `geopoint` field against a circle drawn on the earth.
1420
+ * One group of hits, produced by a query that grouped its results.
800
1421
  *
801
1422
  * @public
802
1423
  */
803
- type GeoRadiusFilter = {
804
- /** The engine tests the field against this circle. */
805
- radius: {
806
- /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
807
- lat: number;
808
- /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
809
- lon: number;
810
- /** The circle has this radius, measured in `unit`. */
811
- distance: number;
812
- /**
813
- * The engine measures `distance` in kilometres under `'km'`, in miles
814
- * under `'mi'`, and in metres under `'m'`. For any other unit, it throws
815
- * `SEARCH_INVALID_FILTER`.
816
- */
817
- unit: 'km' | 'mi' | 'm';
818
- /** 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. */
819
- inside?: boolean;
820
- /**
821
- * The engine measures each distance with the Haversine formula on a sphere
822
- * by default, and with Vincenty's formula on the WGS-84 ellipsoid while
823
- * this is true. Vincenty's formula iterates, so the engine takes longer
824
- * to compute each distance. The two formulas differ by less than 0.3% under about
825
- * 100 km, while across a continent they can differ by up to 0.5%.
826
- */
827
- highPrecision?: boolean;
828
- };
829
- };
1424
+ interface GroupResult {
1425
+ /** Each grouping field holds this value for the group, keyed by field. */
1426
+ values: Record<string, unknown>;
1427
+ /** These hits fall in the group, cut to the query's `maxPerGroup`. */
1428
+ hits: Array<Hit>;
1429
+ /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
1430
+ reduced?: unknown;
1431
+ /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
1432
+ reducerError?: string;
1433
+ }
830
1434
  /**
831
- * Matches a `geopoint` field against a polygon drawn on the earth.
1435
+ * What {@link Narsil.preflight} returns: how many documents a query matches,
1436
+ * without building or ranking a single hit.
832
1437
  *
833
1438
  * @public
834
1439
  */
835
- type GeoPolygonFilter = {
836
- /** The engine tests the field against this polygon. */
837
- polygon: {
838
- /**
839
- * The engine closes the ring through these corners in the order that you
840
- * list them, so you can leave the first point off the end. It throws
841
- * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
842
- * encloses no area, and for a corner whose latitude is outside -90 to 90
843
- * or whose longitude is outside -180 to 180. It also throws that error for
844
- * a ring of more than 65,536 corners. List the corners counter-clockwise
845
- * around the area, as in an exterior ring of GeoJSON. Where the corners
846
- * span 180 degrees of longitude or more, the engine matches the area on
847
- * the left of that path, so a ring listed that way can cross the
848
- * antimeridian or span more than half the globe.
849
- */
850
- points: Array<{
851
- lat: number;
852
- lon: number;
853
- }>;
854
- /** 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. */
855
- inside?: boolean;
856
- };
857
- };
1440
+ interface PreflightResult {
1441
+ /** The query matches this many documents. */
1442
+ count: number;
1443
+ /** `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}. */
1444
+ countExact: boolean;
1445
+ /** The count took this many milliseconds. */
1446
+ elapsed: number;
1447
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1448
+ analysisStale?: boolean;
1449
+ }
858
1450
  /**
859
- * Either shape a `geopoint` field is matched against.
1451
+ * What a batch write returns. One bad document never abandons the rest, so
1452
+ * read both lists.
860
1453
  *
861
1454
  * @public
862
1455
  */
863
- type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
1456
+ interface BatchResult {
1457
+ /** The engine wrote the documents under these ids. */
1458
+ succeeded: string[];
1459
+ /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
1460
+ failed: Array<{
1461
+ docId: string;
1462
+ error: NarsilError;
1463
+ }>;
1464
+ }
864
1465
  /**
865
- * The filter one field accepts. Which of these forms applies follows from the
866
- * field's declared type.
1466
+ * What {@link Narsil.importDocumentExport} returns. The engine continues past each
1467
+ * refused line, so read the refusals to learn which documents it skipped.
867
1468
  *
868
1469
  * @public
869
1470
  */
870
- type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
1471
+ interface DocumentImportResult {
1472
+ /** The engine wrote this many documents, counting each one that it replaced. */
1473
+ imported: number;
1474
+ /** The engine refused this many lines in total. */
1475
+ refusedCount: number;
1476
+ /** 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. */
1477
+ refused: Array<{
1478
+ line: number;
1479
+ code: NarsilErrorCode;
1480
+ message: string;
1481
+ }>;
1482
+ }
871
1483
  /**
872
- * The filter that a query runs, built from per-field tests and the boolean
873
- * operators that combine them.
874
- *
875
- * The engine answers every test from an index that it keeps for the field. It
876
- * applies the filter before scoring, so a narrow filter makes a search
877
- * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
878
- * tests, counted across every field and nested expression. Past either limit,
879
- * the engine throws `SEARCH_INVALID_FILTER`, while it throws
880
- * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
1484
+ * What {@link Narsil.suggest} returns: the indexed terms that complete a
1485
+ * prefix, ready to offer as you-type suggestions.
881
1486
  *
882
1487
  * @public
883
1488
  */
884
- type FilterExpression = {
885
- /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
886
- fields?: Record<string, FieldFilter>;
887
- /** Every nested expression has to match. */
888
- and?: FilterExpression[];
889
- /** At least one nested expression has to match. */
890
- or?: FilterExpression[];
891
- /** The nested expression has to fail. */
892
- not?: FilterExpression;
893
- };
894
-
1489
+ interface SuggestResult {
1490
+ /** These completions run most widely used first. */
1491
+ terms: Array<{
1492
+ /** This is the completed term, as the index holds it. */
1493
+ term: string;
1494
+ /** The term appears in this many documents, which is what ordered the list. */
1495
+ documentFrequency: number;
1496
+ }>;
1497
+ /** The lookup took this many milliseconds. */
1498
+ elapsed: number;
1499
+ /** This turns true when the index's terms came from an older analysis than its language module produces now. */
1500
+ analysisStale?: boolean;
1501
+ }
895
1502
  /**
896
- * How a query reorders its top hits with a rerank adapter.
1503
+ * The state of one vector field, and what maintenance would cost, as
1504
+ * {@link VectorMaintenanceOperations.vectorMaintenanceStatus} reports it.
897
1505
  *
898
- * The engine ranks the query as it would without this setting, passes the
899
- * top `window` hits to the adapter, and orders them by the adapter's scores.
900
- * The hits past the window follow in their first ranking, with their scores
901
- * scaled below the lowest reranked score, so every page of one query comes
902
- * from the same order.
1506
+ * Removing a vector leaves a tombstone in the graph, and enough of them slow a
1507
+ * search down. Read this to decide when compaction earns its cost.
903
1508
  *
904
1509
  * @public
905
1510
  */
906
- interface RerankConfig {
907
- /**
908
- * The engine scores the hits with the rerank adapter registered under this
909
- * key. It throws `RERANK_CONFIG_INVALID` for a key that it has not
910
- * registered.
911
- */
912
- adapter: string;
1511
+ interface VectorMaintenanceResult {
1512
+ /** This describes the named vector field. */
1513
+ fieldName: string;
913
1514
  /**
914
- * The engine sends the adapter the values of these text fields, in this
915
- * order and joined with newlines, as the text of each hit. Each member of a
916
- * list field takes a line of its own. The engine throws
917
- * `RERANK_CONFIG_INVALID` for an empty list, for a field that the schema
918
- * does not declare as text, and for a field that the list gives twice.
1515
+ * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
1516
+ * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
1517
+ * the engine divides by the number of stored vectors, because no graph
1518
+ * exists yet.
919
1519
  */
920
- fields: string[];
1520
+ tombstoneRatio: number;
1521
+ /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
1522
+ graphCount: number;
1523
+ /** This many vectors wait outside the graph, which a search scans one by one. */
1524
+ bufferSize: number;
1525
+ /** This stays true while a graph build runs. */
1526
+ building: boolean;
921
1527
  /**
922
- * The adapter compares each hit with this text. Where you leave it out, the
923
- * engine sends the query's `term`, or else its `vector.text`, and it throws
924
- * `RERANK_CONFIG_INVALID` where the query carries neither.
1528
+ * This turns true while a rebuild that keeps recall up waits for the node to have
1529
+ * room for a second graph beside the one it serves, and false once it starts.
925
1530
  */
926
- query?: string;
1531
+ waitingForMemory: boolean;
927
1532
  /**
928
- * The engine reranks this many of the top hits, from 1 to the engine's
929
- * `maxRerankWindow`. Where you leave the window out, the engine reranks the
930
- * smallest of 100 and `maxRerankWindow`, and no more than the `hybrid.depth`
931
- * of a hybrid query that sets one. A hybrid query that sets `hybrid.depth`
932
- * reranks its fused list at that depth, so the engine throws
933
- * `RERANK_CONFIG_INVALID` when you set a window above that depth.
1533
+ * This stays true after a restart while a field kept on disk loads its codes and graph in the
1534
+ * background, during which a search reads them from the field's files.
934
1535
  */
935
- window?: number;
1536
+ loadingFromFiles: boolean;
1537
+ /** {@link VectorMaintenanceOperations.compactVectors} would take about this many milliseconds. */
1538
+ estimatedCompactMs: number;
1539
+ /** {@link VectorMaintenanceOperations.optimizeVectors} would take about this many milliseconds. */
1540
+ estimatedOptimizeMs: number;
936
1541
  }
937
-
938
1542
  /**
939
- * Vector-search inputs passed under `QueryParams.vector`.
1543
+ * One stored document, as {@link Narsil.listDocuments} returns it.
940
1544
  *
941
- * Supply either a raw `value` array or a `text` string for auto-embedding;
942
- * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
943
- * by the outer query's `limit`, not by any field on this object.
1545
+ * @typeParam T - Shape of the stored document.
944
1546
  *
945
1547
  * @public
946
1548
  */
947
- interface VectorQueryConfig {
948
- /**
949
- * Name of the schema field that holds the vector to compare against.
950
- * Must reference a field declared as `vector[N]` in the index schema.
951
- */
952
- field: string;
953
- /**
954
- * Raw query vector, given as a number array or a `Float32Array`. Length
955
- * must match the indexed field's dimension or the search rejects the
956
- * request with `VECTOR_DIMENSION_MISMATCH`.
957
- */
958
- value?: number[] | Float32Array;
959
- /**
960
- * Text to embed at query time using the index or instance embedding
961
- * adapter. Mutually exclusive with `value`; requires a configured adapter.
962
- */
963
- text?: string;
964
- /**
965
- * Score floor applied during ranking. Hits scoring below this value
966
- * are dropped before `limit` is enforced, so the returned hit count
967
- * can be smaller than `limit` even when more documents exist. The
968
- * floor is interpreted in score space for every metric; for
969
- * `euclidean`, distance is mapped to a similarity score of
970
- * `1 / (1 + distance)` first. Defaults to no floor.
971
- */
972
- similarity?: number;
973
- /**
974
- * Similarity metric used for ranking. Defaults to `cosine`. Choose
975
- * `dotProduct` for raw inner-product scoring on already-normalised
976
- * vectors and `euclidean` for distance-based ordering.
977
- */
978
- metric?: 'cosine' | 'dotProduct' | 'euclidean';
979
- /**
980
- * The engine keeps this many candidates as it walks the HNSW graph, so a
981
- * higher value can find more of the true neighbours, although each query
982
- * takes longer. The engine applies it only once the field holds a graph.
983
- * The engine fetches k hits, where k is one more than the number of hits up
984
- * to the end of the page, so k is `limit` plus 1 on a first page. When a
985
- * query leaves `efSearch` unset, the engine keeps the larger of 50 and k
986
- * plus a margin, where the margin is 50 below 768 dimensions, 75 from 768
987
- * to 1,023 dimensions, and 0 at 1,024 dimensions and above. Under a
988
- * filter, the engine counts only the candidates that pass the filter.
989
- */
990
- efSearch?: number;
991
- /**
992
- * The engine re-scores this many times k candidates in a quantized field
993
- * against the full-precision vectors before it returns the best `limit`,
994
- * where k is one more than the number of hits up to the end of the page, so
995
- * k is `limit` plus 1 on a first page. For a value below 1, or for a value
996
- * that is not a finite number, the engine throws a `NarsilError` with code
997
- * `CONFIG_INVALID`. The engine ignores it on a field whose quantization is
998
- * `none`. When a query leaves it unset, the engine sets the number of
999
- * candidates that it re-scores from k and from the field's dimension. It
1000
- * rounds that number up, and it re-scores at least 3k candidates under
1001
- * `osq1` and `osq2`, and at least k under `osq4` and `osq8`. Below 768
1002
- * dimensions, it re-scores 3.23k + 55.9√k under `osq1` and 2.6k + 22.5√k under
1003
- * `osq2`. From 768 to 1,023 dimensions, it re-scores 2.2k + 27√k under
1004
- * `osq1` and k + 16√k under `osq2`. At 1,024 dimensions and above, it
1005
- * re-scores 3k under both. Under `osq4`, it re-scores 5k below 1,024
1006
- * dimensions and 2k from 1,024 dimensions, while under `osq8` it re-scores
1007
- * 2k at every dimension. Under a filter, the engine counts only the
1008
- * candidates that pass the filter. On vectors spread evenly across every
1009
- * dimension, a one-bit or two-bit code can find fewer than 95% of the true
1010
- * nearest neighbours at these defaults, so raise `oversample` on a query that
1011
- * needs more of them.
1012
- */
1013
- oversample?: number;
1549
+ interface ListedDocument<T = AnyDocument> {
1550
+ /** The document is stored under this id. */
1551
+ id: string;
1552
+ /** This holds the stored document, cut down to what the projection kept. */
1553
+ document: T;
1014
1554
  }
1015
1555
  /**
1016
- * How a hybrid query merges its keyword ranking with its vector ranking.
1556
+ * What {@link Narsil.listDocuments} returns: one page of stored documents and
1557
+ * the cursor that reaches the next one.
1017
1558
  *
1018
- * `rrf` combines the two by rank alone, which needs no tuning and handles
1019
- * scores that live on different scales. `linear` blends the scores directly,
1020
- * which gives you control once you know what each side's scores look like.
1559
+ * @typeParam T - Shape of the stored documents.
1021
1560
  *
1022
1561
  * @public
1023
1562
  */
1024
- interface HybridConfig {
1025
- /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
1026
- strategy?: 'rrf' | 'linear';
1027
- /** 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. */
1028
- k?: number;
1029
- /** 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. */
1030
- alpha?: number;
1563
+ interface ListResult<T = AnyDocument> {
1564
+ /** These documents make up the page, in ascending document-id order. */
1565
+ documents: Array<ListedDocument<T>>;
1566
+ /** This opaque cursor reaches the next page, and is null once the listing is finished. */
1567
+ cursor: string | null;
1568
+ /** The listing covers this many documents in total, and any filter narrows that count. */
1569
+ total: number;
1570
+ /** The engine spent this many milliseconds building the page. */
1571
+ elapsed: number;
1572
+ }
1573
+
1574
+ /**
1575
+ * The change capture setting of one index, which {@link ChangesOperations.updateChanges} takes.
1576
+ *
1577
+ * A subscriber receives the documents of the whole index, so decide which callers may follow an index before you turn
1578
+ * capture on. A filter only chooses which changes a subscriber receives, and it grants no access.
1579
+ *
1580
+ * @public
1581
+ */
1582
+ interface ChangesSetting {
1583
+ /** This turns change capture on or off. Turning it on gives the index a new epoch unless device sync is on. */
1584
+ enabled: boolean;
1031
1585
  /**
1032
- * Set a depth to get the same fused order on every page of one query, and
1033
- * a cursor that resumes it. The engine then fetches this many results from
1034
- * the keyword search and from the vector search, fuses them, and pages
1035
- * through the top `depth` of the fused list. The last page stops at this
1036
- * depth, so it can hold fewer hits than the limit. Set a whole number from 1
1037
- * to 10,000. The engine throws `CONFIG_INVALID` for any other value, and
1038
- * `SEARCH_RESULT_WINDOW_EXCEEDED` for a page that starts at this depth or
1039
- * beyond. Where you leave the depth out, each search fetches only enough
1040
- * results to fill the page, so the fused order can change from one page to
1041
- * the next, and a cluster refuses a cursor with `SEARCH_INVALID_CURSOR`.
1586
+ * Set this to write into each log entry the document that the entry replaces or removes. A change then holds the
1587
+ * document before the write, and a subscription can hold a filter. It defaults to false, because the engine then
1588
+ * reads the stored document and writes it to the log again on every update and removal.
1042
1589
  */
1043
- depth?: number;
1590
+ previousDocument?: boolean;
1591
+ /** This is the age in milliseconds after which the engine deletes a log segment from history. It defaults to 30
1592
+ * days. */
1593
+ historyMaxAgeMs?: number;
1594
+ /** This is the byte count above which the engine deletes the oldest log segment from history. It defaults to the
1595
+ * larger of the checkpoint's length and 1 GiB. */
1596
+ historyMaxBytes?: number;
1044
1597
  }
1045
-
1046
1598
  /**
1047
- * Everything {@link Narsil.suggest} accepts.
1599
+ * The change capture state of one index, which {@link ChangesOperations.getChanges} returns.
1048
1600
  *
1049
1601
  * @public
1050
1602
  */
1051
- interface SuggestParams {
1052
- /** The returned terms complete this text. */
1053
- prefix: string;
1054
- /** The lookup returns this many completions, most widely used first, and 10 by default. */
1055
- limit?: number;
1603
+ interface ChangesStatus extends ChangesSetting {
1604
+ /** This is true when the engine writes the document before the write into each log entry. */
1605
+ previousDocument: boolean;
1606
+ /** This is the index epoch, 32 lowercase hexadecimal digits, or `null` while capture is off. */
1607
+ epoch: string | null;
1056
1608
  }
1057
1609
  /**
1058
- * Everything {@link Narsil.listDocuments} accepts.
1610
+ * A subscriber's place in one partition of an index: the highest `seqNo` whose change it has applied.
1059
1611
  *
1060
- * {@link Narsil.listDocuments} reads the stored documents without ranking them,
1061
- * which is how you page through a whole index. Leave `cursor` out to start at
1062
- * the first document, then pass back the cursor each result carries until it
1063
- * comes back null.
1612
+ * @public
1613
+ */
1614
+ interface ChangePosition {
1615
+ /** This is the partition that the position belongs to. */
1616
+ partitionId: number;
1617
+ /** This is the sequence number of the last entry that the subscriber has examined in that partition. */
1618
+ seqNo: number;
1619
+ }
1620
+ /**
1621
+ * What a write did to a document. A `put` comes from an entry that the engine wrote while `previousDocument` was off,
1622
+ * so it can be an insert or an update.
1064
1623
  *
1065
- * A cursor belongs to the sort it was made under, so pass the same `sort` back
1066
- * with it. Changing `sort` invalidates the cursor, and the engine then throws
1067
- * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
1624
+ * @public
1625
+ */
1626
+ type ChangeType = 'put' | 'insert' | 'update' | 'remove';
1627
+ /**
1628
+ * One write to an index, as {@link ChangesOperations.followChanges} returns it.
1068
1629
  *
1069
1630
  * @public
1070
1631
  */
1071
- interface ListParams {
1072
- /**
1073
- * This cursor comes from a previous result, and continues where it stopped.
1074
- * The engine ties a cursor to the sort that produced it, and it throws
1075
- * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
1076
- */
1077
- cursor?: string;
1078
- /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
1079
- limit?: number;
1080
- /** This narrows the listing to the documents the filter accepts. */
1081
- filters?: FilterExpression;
1632
+ interface Change {
1633
+ /** This is the sequence number of the log entry within its partition. */
1634
+ seqNo: number;
1635
+ /** This is what the write did to the document. */
1636
+ type: ChangeType;
1637
+ /** This is the ID of the document that the write touched. */
1638
+ documentId: string;
1639
+ /** This is the document after the write, with every field and every computed vector, and absent after a removal. */
1640
+ document?: AnyDocument;
1641
+ /** This is the document before the write, present only for an update or a removal with `previousDocument` on. */
1642
+ previousDocument?: AnyDocument;
1643
+ }
1644
+ /**
1645
+ * Where {@link ChangesOperations.followChanges} starts and which changes it returns.
1646
+ *
1647
+ * @public
1648
+ */
1649
+ interface FollowChangesOptions {
1650
+ /** This is the epoch that the positions belong to. Pass it together with `positions`, or leave both out. */
1651
+ epoch?: string;
1652
+ /** This holds one position for each partition. Leave it out, with `epoch`, to start at the index's current heads. */
1653
+ positions?: ChangePosition[];
1082
1654
  /**
1083
- * This orders the listing by field value rather than by document id, and the
1084
- * engine applies the fields in the order they are listed. Pass an object
1085
- * keyed by field, or a list of fields in the order they apply. It breaks a
1086
- * tie on document id, and it sorts by at most eight fields. The engine uses
1087
- * document-id order when you leave this out.
1088
- *
1089
- * The engine reads every document the listing covers to build a sorted page,
1090
- * so a sorted listing costs more than the default order on a large index.
1091
- */
1092
- sort?: SortSpec;
1093
- /** This chooses how much of each stored document comes back, and the whole document by default. */
1094
- document?: DocumentProjection;
1655
+ * This keeps only the changes whose document before or after the write matches it, in the syntax of a query's
1656
+ * filters. It needs `previousDocument` on.
1657
+ */
1658
+ filter?: FilterExpression;
1659
+ /** This ends the iteration when it aborts. */
1660
+ signal?: AbortSignal;
1095
1661
  }
1096
-
1097
1662
  /**
1098
- * Which engine answers a query: keyword matching, vector similarity, or both
1099
- * merged into one ranking.
1663
+ * The first event of {@link ChangesOperations.followChanges}, which gives the positions that the changes follow.
1100
1664
  *
1101
1665
  * @public
1102
1666
  */
1103
- type SearchMode = 'fulltext' | 'vector' | 'hybrid';
1667
+ interface ChangesSubscribed {
1668
+ /** This marks the event. */
1669
+ type: 'subscribed';
1670
+ /** This is the index's epoch. Save it with the positions. */
1671
+ epoch: string;
1672
+ /** This is the number of partitions, each of which has a position. */
1673
+ partitionCount: number;
1674
+ /** These are the positions that the changes follow. */
1675
+ positions: ChangePosition[];
1676
+ /** These are the heads of the partitions when the subscription started. */
1677
+ heads: ChangePosition[];
1678
+ /** This is the length in bytes of the history and log between the positions and the heads. */
1679
+ bytesBehind: number;
1680
+ /** This is true when a change can hold the document before the write. */
1681
+ previousDocument: boolean;
1682
+ }
1104
1683
  /**
1105
- * How many of a query's terms a document has to carry. `all` demands every
1106
- * term, `any` accepts one, and a number demands that many.
1684
+ * A group of changes from one partition. Apply the changes, then save `scannedSeqNo` as the partition's position.
1107
1685
  *
1108
1686
  * @public
1109
1687
  */
1110
- type TermMatchPolicy = 'all' | 'any' | number;
1688
+ interface ChangesBatch {
1689
+ /** This marks the event. */
1690
+ type: 'changes';
1691
+ /** This is the partition that the changes come from. */
1692
+ partitionId: number;
1693
+ /** These are the changes in `seqNo` order, which can be empty under a filter. */
1694
+ changes: Change[];
1695
+ /** This is the highest `seqNo` of the partition that the engine examined, which is the next position to save. */
1696
+ scannedSeqNo: number;
1697
+ }
1111
1698
  /**
1112
- * One field of a sort, and the direction that field orders by.
1699
+ * The last event of {@link ChangesOperations.followChanges} when the positions no longer lead to the index's changes.
1700
+ * Export the index, replace your copy with the export's documents, and follow again from the export's header.
1113
1701
  *
1114
1702
  * @public
1115
1703
  */
1116
- interface SortField {
1117
- /** The field the engine reads, which may name a nested field with dots. */
1118
- field: string;
1119
- /** Ascending or descending order for this field. */
1120
- direction: 'asc' | 'desc';
1704
+ interface ChangesResync {
1705
+ /** This marks the event. */
1706
+ type: 'resync';
1121
1707
  /**
1122
- * Where a document's field holds a list, the engine sorts that document by
1123
- * one value from the list: the smallest under `'min'`, the largest under
1124
- * `'max'`, and the mean or the median of the list's numbers under `'avg'`
1125
- * or `'median'`. Where you leave this out, the engine uses `'min'` for an
1126
- * ascending sort and `'max'` for a descending one. It sorts by a field that
1127
- * holds a single value as that value stands, under every mode. It throws
1128
- * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
1129
- * schema declares as anything other than `number` or `number[]`.
1708
+ * This is `epoch` when the index has a new epoch, `history` when the history no longer holds the entries above a
1709
+ * position, and `ahead` when a position lies above every entry of its partition.
1130
1710
  */
1131
- mode?: 'min' | 'max' | 'avg' | 'median';
1711
+ reason: 'epoch' | 'history' | 'ahead';
1132
1712
  }
1133
1713
  /**
1134
- * A sort, either as an object keyed by field or as a list of fields in the
1135
- * order they apply.
1136
- *
1137
- * Both forms order by the first field, break a tie on the second, and carry on
1138
- * that way. Prefer the list where the order of the fields matters, because
1139
- * JavaScript moves an all-digit key such as `2024` to the front of an object
1140
- * and the list keeps the order you wrote.
1714
+ * One event of {@link ChangesOperations.followChanges}.
1141
1715
  *
1142
1716
  * @public
1143
1717
  */
1144
- type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
1718
+ type ChangesEvent = ChangesSubscribed | ChangesBatch | ChangesResync;
1145
1719
  /**
1146
- * Everything {@link Narsil.query} accepts.
1147
- *
1148
- * Set `term` for keyword search, `vector` for similarity search, and `mode`
1149
- * when you want both. The engine matches nothing for a query carrying neither
1150
- * of them, so page through an index with {@link Narsil.listDocuments}
1151
- * instead.
1720
+ * The methods that turn change capture on and off for an index and follow its changes.
1152
1721
  *
1153
1722
  * @public
1154
1723
  */
1155
- interface QueryParams {
1156
- /** The engine analyses this text with the index's language module and searches for the terms that result. */
1157
- term?: string;
1158
- /** The engine searches the term in these fields, and in every text field in the schema by default. */
1159
- fields?: string[];
1160
- /**
1161
- * The engine scores only the documents that pass this filter. It throws
1162
- * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
1163
- * operator on a field of another type, such as `startsWith` on a number
1164
- * field.
1165
- */
1166
- filters?: FilterExpression;
1167
- /**
1168
- * The engine multiplies the score from each named field by its weight. It
1169
- * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
1170
- * the schema declares, and `CONFIG_INVALID` for a weight that is not a
1171
- * finite number.
1172
- */
1173
- boost?: Record<string, number>;
1174
- /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
1175
- scoring?: ScoringMode;
1176
- /**
1177
- * The engine drops any hit scoring below this value. It ranks with BM25,
1178
- * which has no fixed upper bound, so a floor that suits one index and one
1179
- * query can reject every hit in another.
1180
- */
1181
- minScore?: number;
1182
- /**
1183
- * The engine keeps a document only where the document matches this many
1184
- * query terms, under the same `tolerance` and `prefixLength` that the search
1185
- * uses. One term is enough by default.
1186
- */
1187
- termMatch?: TermMatchPolicy;
1188
- /**
1189
- * The engine matches an indexed term within this edit distance of a query
1190
- * term, so it finds a document for a query with a typo. It counts each
1191
- * Unicode code point as one character. Set an integer from 0 to 10.
1192
- */
1193
- tolerance?: number;
1194
- /**
1195
- * The engine applies `tolerance` only to the indexed terms that share this
1196
- * many leading characters with the query term, or to the terms that start
1197
- * with the whole query term when the query term is shorter. Set an integer
1198
- * from 0 to 1,024; the default is 2.
1199
- */
1200
- prefixLength?: number;
1201
- /**
1202
- * With this set, the engine treats the last query term as an unfinished
1203
- * word, so `secur` matches `security`. The engine matches that last term by
1204
- * its stem or by completing it, while `tolerance` applies only to the earlier
1205
- * terms, which have to match whole. The engine scores completions against a
1206
- * shared document frequency. It also ranks them below whole-word matches.
1207
- * The engine ignores this setting where `exact` is true, and the setting is
1208
- * false by default.
1209
- */
1210
- prefix?: boolean;
1724
+ interface ChangesOperations {
1211
1725
  /**
1212
- * With this set, the engine also matches each query word of three or more
1213
- * characters inside the longer words of every field whose type includes
1214
- * `partial`, so a search for `proof` matches a document with `waterproof`
1215
- * in such a field. The engine counts each Unicode code point as one
1216
- * character. It looks for the query word, before stemming, inside each word
1217
- * exactly as that word appears in a document.
1726
+ * Replaces the change capture setting of an index.
1218
1727
  *
1219
- * The engine adds at most 50 such words to a query, which it divides as
1220
- * evenly as it can among the query words. Within the share of each query
1221
- * word, it adds first the words that the most documents contain. It scores
1222
- * a match inside a longer word in proportion to the part of that word that
1223
- * the query word makes up, so it scores such a match below a whole-word
1224
- * match at the same frequency in a field of the same length. With
1225
- * `highlight`, it tags each whole word that contains a query word in a
1226
- * searched `partial` field.
1728
+ * Turning capture on gives the index a new epoch unless device sync is on, and the engine keeps the log segments
1729
+ * that a checkpoint covers as history from then on. Turning it off ends every follower of the index and deletes the
1730
+ * history unless a device has asked for the index's sync snapshot. The engine saves the setting with the index, and
1731
+ * no snapshot of the index includes it.
1227
1732
  *
1228
- * The engine applies no `tolerance` to these matches. It ignores this
1229
- * setting where `exact` is true or where the searched fields include no
1230
- * `partial` field. Where the setting is absent, the engine treats it as
1231
- * false, while it throws `CONFIG_INVALID` for any value other than `true`
1232
- * or `false`.
1233
- */
1234
- partialWords?: boolean;
1235
- /**
1236
- * With this set, the engine matches each query term only against an equal
1237
- * indexed term, so it turns off fuzzy matching, prefix completion,
1238
- * partial-word matching, and synonyms. The engine still stems the query, because the
1239
- * index stores stemmed terms, so a search for `running` matches a document
1240
- * that contains `runs` through the stem that both words share.
1241
- */
1242
- exact?: boolean;
1243
- /**
1244
- * The engine counts the values of these fields across the matching
1245
- * documents, and each entry sets how it cuts and sorts that field's counts.
1246
- * For a field outside the schema, it counts the values that the documents
1247
- * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
1248
- * field.
1249
- */
1250
- facets?: FacetConfig;
1251
- /**
1252
- * The engine sorts the hits by the values of these fields, in place of the
1253
- * relevance ranking. Pass an object keyed by field, or a list of fields in
1254
- * the order that the engine compares them. The engine sorts by a `number`,
1255
- * `boolean`, or `enum` field, by a text field whose type includes
1256
- * `sortable`, or by a list of any of these, which it reduces to one value by
1257
- * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
1258
- * `geopoint` or a vector field, because neither type has an order. It throws
1259
- * the same code for a sort on any other text field, since the engine keeps
1260
- * up to the first 512 code points of every document's value in memory to
1261
- * sort by a text field. The engine orders hybrid results by fusion, so it
1262
- * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
1263
- * that code for a direction other than `asc` and `desc`.
1264
- */
1265
- sort?: SortSpec;
1266
- /** These settings collapse the hits into groups by field value. */
1267
- group?: GroupConfig;
1268
- /**
1269
- * The query returns this many hits, and 10 by default. Pass 0 to read the
1270
- * match count with no hits. The engine reads a value below 0 as 0. It falls
1271
- * back to the default for `NaN` and for an infinite value, so a page size
1272
- * that you compute from user input never fails the query.
1733
+ * @param indexName - The index whose setting the engine replaces.
1734
+ * @param setting - The new setting.
1735
+ * @throws A `NarsilError` with `CHANGES_DURABILITY_REQUIRED` when the engine has no write-ahead log durability, and
1736
+ * with `CONFIG_INVALID` when a field has the wrong type or a history limit is not a positive whole number.
1273
1737
  */
1274
- limit?: number;
1275
- /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
1276
- offset?: number;
1277
- /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
1278
- searchAfter?: string;
1279
- /** These settings name the fields that come back with highlighted snippets. */
1280
- highlight?: HighlightConfig;
1281
- /** These documents take fixed positions, ahead of the ranking. */
1282
- pinned?: Array<{
1283
- docId: string;
1284
- position: number;
1285
- }>;
1286
- /** This picks which engine answers the query. Keyword search runs by default. */
1287
- mode?: SearchMode;
1288
- /** These vector-search inputs are required in `vector` and `hybrid` mode. */
1289
- vector?: VectorQueryConfig;
1290
- /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
1291
- hybrid?: HybridConfig;
1738
+ updateChanges(indexName: string, setting: ChangesSetting): Promise<void>;
1292
1739
  /**
1293
- * These settings reorder the top hits with a rerank adapter, such as a
1294
- * cross-encoder, after the keyword, vector, or hybrid ranking. The count
1295
- * matches the count of the same query without `rerank`, while the facets
1296
- * and the groups come from the first ranking. The engine throws
1297
- * `SEARCH_INVALID_MODE` for a query that also sets a sort, and
1298
- * `RERANK_FAILED` where the adapter fails or outlasts the engine's
1299
- * `rerankTimeout`.
1740
+ * Returns the change capture state of an index.
1741
+ *
1742
+ * @param indexName - The index whose state the engine returns.
1743
+ * @returns The setting and the epoch.
1744
+ * @throws A `NarsilError` with `INDEX_NOT_FOUND` when no index has that name.
1300
1745
  */
1301
- rerank?: RerankConfig;
1746
+ getChanges(indexName: string): Promise<ChangesStatus>;
1302
1747
  /**
1303
- * Setting this returns relevance scores on a sorted query. A query that
1304
- * names a sort ranks by sort values alone and computes no scores, so its
1305
- * hits carry none until this restores them. A query without a sort ignores
1306
- * this and always carries scores.
1748
+ * Returns the changes of an index above a list of positions, and then each later change as the log makes it
1749
+ * durable, until the signal aborts or the caller stops iterating.
1750
+ *
1751
+ * The first event gives the epoch and the positions. Each later event holds the changes of one partition in `seqNo`
1752
+ * order. Where the positions no longer lead to the index's changes, the last event is a resync.
1753
+ *
1754
+ * @param indexName - The index whose changes the engine returns.
1755
+ * @param options - The epoch and positions to start from, a filter, and a signal.
1756
+ * @returns The events, one at a time.
1757
+ * @throws A `NarsilError` with `CHANGES_NOT_ENABLED` when capture is off or turns off, with
1758
+ * `CHANGES_INVALID_POSITIONS` for a malformed epoch or list of positions, with `SEARCH_INVALID_FILTER` for a filter
1759
+ * that breaks the shape or the limits of a query's filters, with `SEARCH_INVALID_FIELD` for a filter that tests a
1760
+ * field which the schema leaves out, and with `CHANGES_PREVIOUS_DOCUMENT_REQUIRED` for a filter while
1761
+ * `previousDocument` is off.
1307
1762
  */
1308
- includeScores?: boolean;
1309
- /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
1310
- includeScoreComponents?: boolean;
1311
- /** This chooses how much of each stored document comes back, and the whole document by default. */
1312
- document?: DocumentProjection;
1763
+ followChanges(indexName: string, options?: FollowChangesOptions): AsyncIterable<ChangesEvent>;
1313
1764
  }
1765
+
1314
1766
  /**
1315
- * How much of a stored document each hit carries back.
1316
- *
1317
- * Pass `false` when the ids and scores are all you need, and every hit's
1318
- * `document` is then an empty object. Pass `include` to keep named fields
1319
- * alone, or `exclude` to drop named fields and keep the rest; naming both
1320
- * keeps the included fields and then drops the excluded ones from those. Use
1321
- * dots to name a nested field, so `author.name` addresses the `name` inside
1322
- * `author`, and a name that matches no field changes nothing.
1323
- *
1324
- * Drop a vector field on a similarity search, because the engine otherwise
1325
- * reads every hit's vector back out of the index and writes it into the
1326
- * response.
1767
+ * Snapshot of V8 heap usage as reported by `process.memoryUsage()`, with the
1768
+ * limit the heap may grow to. All values are bytes. `null` in environments
1769
+ * that do not expose `process.memoryUsage`, such as browsers.
1327
1770
  *
1328
1771
  * @public
1329
1772
  */
1330
- type DocumentProjection = boolean | {
1331
- /** Names the fields to keep, so every field left out of this list is dropped. */
1332
- include?: string[];
1333
- /** Names the fields to drop, so every other field is kept. */
1334
- exclude?: string[];
1335
- };
1773
+ interface ProcessMemoryReport {
1774
+ /** The process is using this much heap. */
1775
+ heapUsed: number;
1776
+ /** V8 has reserved this much heap. */
1777
+ heapTotal: number;
1778
+ /**
1779
+ * The heap may grow to this many bytes before the runtime ends the process
1780
+ * for running out of memory. Node sets it from `--max-old-space-size`, from
1781
+ * `--max-old-space-size-percentage`, or from the memory the host or the
1782
+ * container reports. `null` where the runtime cannot report it.
1783
+ */
1784
+ heapLimit: number | null;
1785
+ /** The process holds this much outside the heap, such as buffers. */
1786
+ external: number;
1787
+ /** The process occupies this much physical memory in total. */
1788
+ rss: number;
1789
+ }
1336
1790
  /**
1337
- * Fields a query counts values for, keyed by field name.
1791
+ * Whether one index holds worker copies at the moment
1792
+ * {@link Narsil.getMemoryStats} reads it, and how many times it has loaded
1793
+ * them again after giving them up while idle.
1338
1794
  *
1339
1795
  * @public
1340
1796
  */
1341
- interface FacetConfig {
1342
- /** Each key names a field the query counts values for. */
1343
- [field: string]: {
1344
- /** 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`. */
1345
- limit?: number;
1346
- /** 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. */
1347
- sort?: 'asc' | 'desc';
1348
- /** 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. */
1349
- ranges?: Array<{
1350
- from: number;
1351
- to: number;
1352
- }>;
1353
- };
1797
+ interface WorkerCopyReport {
1798
+ /** This names the index. */
1799
+ indexName: string;
1800
+ /** This is true while every worker holds a copy of the index. */
1801
+ scaledOut: boolean;
1802
+ /** The index has loaded its copies again this many times after an idle spell dropped them. */
1803
+ reloadCount: number;
1354
1804
  }
1355
1805
  /**
1356
- * How a query collapses its hits into groups.
1806
+ * An index whose checkpoints wait until a failed partition recovers, as
1807
+ * {@link Narsil.getMemoryStats} reports it. The engine holds these
1808
+ * checkpoints only for an index with a vector field, because each vector file
1809
+ * mixes every partition's vectors, so a checkpoint would save the failed
1810
+ * partition's vectors from memory. The write-ahead log of the index grows
1811
+ * until the partition recovers or you restore the index from a snapshot.
1357
1812
  *
1358
1813
  * @public
1359
1814
  */
1360
- interface GroupConfig {
1361
- /** The values of these fields define a group, and several fields group by their combination. */
1362
- fields: string[];
1363
- /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
1364
- maxPerGroup?: number;
1365
- /** The engine returns this many groups, best first, and every group where you leave this out. */
1366
- limit?: number;
1367
- /**
1368
- * The engine folds every hit of each group into one value, such as a sum or
1369
- * an average, including the hits beyond `maxPerGroup`. In cluster mode the
1370
- * coordinator fetches up to 10,000 hits of each group to fold.
1371
- */
1372
- reduce?: GroupReducer;
1815
+ interface HeldCheckpointReport {
1816
+ /** This is the index whose checkpoints wait. */
1817
+ indexName: string;
1818
+ /** These are the partitions of that index whose copy failed. */
1819
+ partitionIds: number[];
1820
+ /** This many write-ahead log records of the index wait for a checkpoint. */
1821
+ recordsSinceCheckpoint: number;
1822
+ /** The documents in those records hold about this many bytes. */
1823
+ documentBytesSinceCheckpoint: number;
1373
1824
  }
1374
1825
  /**
1375
- * Folds the hits of one group into a single value.
1826
+ * What {@link Narsil.getMemoryStats} returns, which is what you size a host
1827
+ * from.
1376
1828
  *
1377
1829
  * @public
1378
1830
  */
1379
- type GroupReducer = {
1831
+ interface MemoryStats {
1380
1832
  /**
1381
- * Folds one hit into the running value.
1382
- *
1383
- * @param accumulator - What the previous call returned, or what
1384
- * `initialValue` produced for the first hit.
1385
- * @param doc - The hit's stored document.
1386
- * @param score - The hit's relevance score.
1387
- * @returns The new running value.
1833
+ * V8 heap usage for the host process at the moment of the call. It covers
1834
+ * the whole process, so every Narsil engine in one process returns the same
1835
+ * `process` figures from `getMemoryStats`. `null` in browsers and in any
1836
+ * runtime that does not expose `process.memoryUsage`.
1388
1837
  */
1389
- reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
1390
- /** Produces the starting value for each group. The engine calls it once per group. */
1391
- initialValue: () => unknown;
1392
- };
1393
- /**
1394
- * This configuration names the fields that receive highlighted snippets. It
1395
- * also sets how the engine marks those snippets up.
1396
- *
1397
- * The engine analyses the text of each returned field again to tag every word
1398
- * that it matched, so it tags the same words whatever the index's
1399
- * `trackPositions` setting is. It tags a word whose stem equals a query stem,
1400
- * and a word within the query's `tolerance` of a query stem. For a `prefix`
1401
- * query, it tags a word for the last query term only when that word completes
1402
- * the term or shares its stem.
1403
- *
1404
- * @public
1405
- */
1406
- interface HighlightConfig {
1407
- /** The engine highlights these fields. */
1408
- fields: string[];
1409
- /** The engine writes this before each match, and writes `<mark>` by default. */
1410
- preTag?: string;
1411
- /** The engine writes this after each match, and writes `</mark>` by default. */
1412
- postTag?: string;
1838
+ process: ProcessMemoryReport | null;
1413
1839
  /**
1414
- * The engine takes this many characters of the field around the densest run
1415
- * of matches, 200 by default. It returns a snippet longer than that number,
1416
- * because it then adds the opening and closing tags, and an ellipsis at each
1417
- * end where it cuts the field.
1840
+ * The sum of every index's {@link IndexStats.estimatedMemoryBytes} held by
1841
+ * this engine. A formula produces it, so read it as an estimate. It compares
1842
+ * engines inside one process, where `process.heapUsed` cannot tell them
1843
+ * apart.
1418
1844
  */
1419
- maxSnippetLength?: number;
1845
+ estimatedIndexBytes: number;
1846
+ /** This many indexes currently occupy engine memory. */
1847
+ openIndexCount: number;
1848
+ /** This many indexes remain registered without occupying engine memory, including parked recovery failures. */
1849
+ closedIndexCount: number;
1850
+ /** This counts successful index loads since this engine started. */
1851
+ reopenCount: number;
1852
+ /** One entry per index, saying whether it holds worker copies now and how many times it has reloaded them. */
1853
+ workerCopies: WorkerCopyReport[];
1854
+ /** One entry per index whose checkpoints wait until a failed partition recovers. */
1855
+ heldCheckpoints: HeldCheckpointReport[];
1856
+ /**
1857
+ * Per-worker V8 heap usage once the engine has started its worker pool.
1858
+ * Empty while no worker is running.
1859
+ */
1860
+ workers: Array<{
1861
+ /** This identifies the worker within the pool. */
1862
+ workerId: number;
1863
+ /** That worker is using this much heap. */
1864
+ heapUsed: number;
1865
+ /** V8 has reserved this much heap in that worker. */
1866
+ heapTotal: number;
1867
+ /** That worker's heap may grow to this many bytes, or `null` where its runtime cannot report it. */
1868
+ heapLimit: number | null;
1869
+ /** That worker holds this much outside its heap. */
1870
+ external: number;
1871
+ }>;
1420
1872
  }
1421
1873
 
1422
1874
  /**
@@ -1544,159 +1996,838 @@ type NarsilEventMap = {
1544
1996
  * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
1545
1997
  * idle index; see {@link ProcessMemoryReport.heapLimit}.
1546
1998
  */
1547
- heapPressure: {
1548
- /** This is the index that a write or a load was touching when the heap
1549
- * reached that point. */
1550
- indexName: string;
1551
- /** This is the heap that the process uses, in bytes. */
1552
- heapUsed: number;
1553
- /** This is the size in bytes that the heap can grow to. */
1554
- heapLimit: number;
1555
- /** This is the estimate of the bytes that the index holds. */
1556
- estimatedMemoryBytes: number;
1557
- };
1558
- /** The engine started, completed, or failed a rebuild that brings the terms
1559
- * of an index up to the current analysis of its language module. */
1560
- analysisRebuild: {
1561
- /** This is the name of the index under rebuild. */
1562
- indexName: string;
1563
- /** This is the stage that the rebuild has reached. */
1564
- status: 'started' | 'completed' | 'failed';
1565
- /** This is the number of partitions that the rebuild has covered so far. */
1566
- partitionsRebuilt: number;
1567
- /** This is the number of partitions that the rebuild covers in total. */
1568
- partitionCount: number;
1569
- /** This is the error that stopped the rebuild, which only a `failed`
1570
- * status includes. */
1571
- error?: Error;
1572
- };
1573
- /** The engine started, completed, or failed the rewrite of an index that you
1574
- * saved with an earlier release. The engine rewrites the index as it
1575
- * recovers it, before it serves the index's first request. Because the
1576
- * engine writes the new manifest last, the earlier files stay intact through
1577
- * a failed rewrite. The engine then starts the rewrite again the next time
1578
- * it recovers the index. Without index lifecycle settings, the engine
1579
- * recovers every index before {@link createNarsil} returns, so pass the
1580
- * listener in the `events` setting of {@link createNarsil}. */
1581
- layoutUpgrade: {
1582
- /** This is the name of the index under rewrite. */
1583
- indexName: string;
1584
- /** This is the stage that the rewrite has reached. */
1585
- status: 'started' | 'completed' | 'failed';
1586
- /** This is `manifest` where the earlier index is a segment manifest with
1587
- * its files, and `bundle` where it is a single snapshot bundle. */
1588
- layout: 'manifest' | 'bundle';
1589
- /** This is the error that stopped the rewrite, which only a `failed`
1590
- * status includes. */
1591
- error?: Error;
1592
- };
1593
- /** A write to the write-ahead log or a checkpoint failed, so the writes since
1594
- * the last checkpoint are at risk. */
1595
- durabilityError: {
1596
- /** This is the error that the durability layer threw. */
1597
- error: Error;
1598
- };
1599
- /** The invalidation channel failed, so this instance can serve partitions
1600
- * that another instance has since changed. */
1601
- invalidationError: {
1602
- /** This is the error that the adapter threw. */
1603
- error: Error;
1604
- };
1605
- };
1999
+ heapPressure: {
2000
+ /** This is the index that a write or a load was touching when the heap
2001
+ * reached that point. */
2002
+ indexName: string;
2003
+ /** This is the heap that the process uses, in bytes. */
2004
+ heapUsed: number;
2005
+ /** This is the size in bytes that the heap can grow to. */
2006
+ heapLimit: number;
2007
+ /** This is the estimate of the bytes that the index holds. */
2008
+ estimatedMemoryBytes: number;
2009
+ };
2010
+ /** The engine started, completed, or failed a rebuild that brings the terms
2011
+ * of an index up to the current analysis of its language module. */
2012
+ analysisRebuild: {
2013
+ /** This is the name of the index under rebuild. */
2014
+ indexName: string;
2015
+ /** This is the stage that the rebuild has reached. */
2016
+ status: 'started' | 'completed' | 'failed';
2017
+ /** This is the number of partitions that the rebuild has covered so far. */
2018
+ partitionsRebuilt: number;
2019
+ /** This is the number of partitions that the rebuild covers in total. */
2020
+ partitionCount: number;
2021
+ /** This is the error that stopped the rebuild, which only a `failed`
2022
+ * status includes. */
2023
+ error?: Error;
2024
+ };
2025
+ /** The engine started, completed, or failed the rewrite of an index that you
2026
+ * saved with an earlier release. The engine rewrites the index as it
2027
+ * recovers it, before it serves the index's first request. Because the
2028
+ * engine writes the new manifest last, the earlier files stay intact through
2029
+ * a failed rewrite. The engine then starts the rewrite again the next time
2030
+ * it recovers the index. Without index lifecycle settings, the engine
2031
+ * recovers every index before {@link createNarsil} returns, so pass the
2032
+ * listener in the `events` setting of {@link createNarsil}. */
2033
+ layoutUpgrade: {
2034
+ /** This is the name of the index under rewrite. */
2035
+ indexName: string;
2036
+ /** This is the stage that the rewrite has reached. */
2037
+ status: 'started' | 'completed' | 'failed';
2038
+ /** This is `manifest` where the earlier index is a segment manifest with
2039
+ * its files, and `bundle` where it is a single snapshot bundle. */
2040
+ layout: 'manifest' | 'bundle';
2041
+ /** This is the error that stopped the rewrite, which only a `failed`
2042
+ * status includes. */
2043
+ error?: Error;
2044
+ };
2045
+ /** The engine stopped taking checkpoints of an index with a vector field,
2046
+ * because one of its partitions failed and each vector file mixes every
2047
+ * partition's vectors. The write-ahead log of the index grows until the
2048
+ * partition recovers; {@link MemoryStats.heldCheckpoints} reports how far. */
2049
+ checkpointHeld: HeldCheckpointReport;
2050
+ /** A write to the write-ahead log or a checkpoint failed, so the writes since
2051
+ * the last checkpoint are at risk. */
2052
+ durabilityError: {
2053
+ /** This is the error that the durability layer threw. */
2054
+ error: Error;
2055
+ };
2056
+ /** The invalidation channel failed, so this instance can serve partitions
2057
+ * that another instance has since changed. */
2058
+ invalidationError: {
2059
+ /** This is the error that the adapter threw. */
2060
+ error: Error;
2061
+ };
2062
+ /**
2063
+ * A popular query suggestions build started, completed, failed, or skipped.
2064
+ * The payload carries counts alone, never a phrase.
2065
+ */
2066
+ querySuggestionsBuild: QuerySuggestionsBuildEvent;
2067
+ /**
2068
+ * The engine skipped a history file, failed to save the counts of a day,
2069
+ * reached a daily limit, or holds an index with the feature on while it has
2070
+ * no key. The payload carries no search text.
2071
+ */
2072
+ querySuggestionsWarning: QuerySuggestionsWarningEvent;
2073
+ };
2074
+ /**
2075
+ * This map holds a listener for any event of {@link NarsilEventMap}, so that
2076
+ * the engine can register each listener before it starts.
2077
+ *
2078
+ * @public
2079
+ */
2080
+ type NarsilEventHandlers = {
2081
+ [K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
2082
+ };
2083
+
2084
+ /**
2085
+ * Registers the adapters that indexes and queries reach by name, which is
2086
+ * what lets a binding outlive a restart and reach a worker thread or another
2087
+ * node.
2088
+ *
2089
+ * @public
2090
+ */
2091
+ interface AdapterRegistrationOperations {
2092
+ /**
2093
+ * Registers an embedding adapter under a name that an index config can
2094
+ * give and that durability metadata keeps. Registering a name again binds
2095
+ * every index that gives that name to the new adapter.
2096
+ *
2097
+ * @param name - The name that an index config gives in `embedding.adapter`.
2098
+ * @param adapter - The adapter that embeds documents and queries.
2099
+ */
2100
+ registerEmbeddingAdapter(name: string, adapter: EmbeddingAdapter): void;
2101
+ /**
2102
+ * Registers a rerank adapter under a name that a query gives in
2103
+ * `rerank.adapter`. Registering a name again sends every later query that
2104
+ * gives that name to the new adapter. The engine throws
2105
+ * `RERANK_CONFIG_INVALID` for an empty name and for an adapter without a
2106
+ * `rerank` function.
2107
+ *
2108
+ * @param name - The name that a query gives in `rerank.adapter`.
2109
+ * @param adapter - The adapter that scores the top hits of a query.
2110
+ */
2111
+ registerRerankAdapter(name: string, adapter: RerankAdapter): void;
2112
+ }
2113
+
2114
+ /**
2115
+ * The analysis settings that {@link AnalysisOperations.changeAnalysis} changes
2116
+ * on a live index. A key that you leave out keeps its current value.
2117
+ *
2118
+ * @public
2119
+ */
2120
+ interface AnalysisChange {
2121
+ /** This is the name of a registered language. */
2122
+ language?: string;
2123
+ /**
2124
+ * This is a name that {@link registerTokenizer} bound. Pass `null` to return
2125
+ * to the tokeniser of the language.
2126
+ */
2127
+ tokenizer?: string | null;
2128
+ /**
2129
+ * This is a name that {@link registerStopWords} bound, or a list of words.
2130
+ * Pass `null` to return to the stop words of the language.
2131
+ */
2132
+ stopWords?: string | readonly string[] | ReadonlySet<string> | null;
2133
+ }
2134
+ /**
2135
+ * Changes how an index turns text into terms while the index keeps answering
2136
+ * searches.
2137
+ *
2138
+ * @public
2139
+ */
2140
+ interface AnalysisOperations {
2141
+ /**
2142
+ * Gives you an index that matches text under new settings, while the index
2143
+ * keeps answering searches and accepting writes.
2144
+ *
2145
+ * The engine builds the new terms beside the old ones. Searches keep matching
2146
+ * under the old settings during that time, while every write that the engine
2147
+ * accepts reaches the new terms. Each search matches under one set of
2148
+ * settings, either the old or the new, and the rebuild leaves vectors alone.
2149
+ * The promise resolves once a durable checkpoint holds the new terms, or once
2150
+ * the switch happens on an engine without durability. After a restart at any
2151
+ * point, the engine goes on to finish the change.
2152
+ *
2153
+ * @param indexName - The index to change.
2154
+ * @param change - The settings to change. A change to the values that the
2155
+ * index already holds completes with no rebuild.
2156
+ * @throws A `NarsilError` with `LANGUAGE_NOT_SUPPORTED` for an unregistered
2157
+ * language, with `CONFIG_INVALID` for an unregistered name, a tokeniser
2158
+ * instance, a stop word function, or a synonym word that breaks the synonym
2159
+ * rules under the new settings, with `ANALYSIS_REBUILD_MEMORY_EXCEEDED` when a
2160
+ * second copy of the terms does not fit in memory, with
2161
+ * `ANALYSIS_CHANGE_REPLACED` when a later change or a restore replaces this
2162
+ * one or when a restore of the index is in flight, with
2163
+ * `ANALYSIS_CHANGE_NOT_READY` when the previous change has no durable
2164
+ * checkpoint yet, with `PERSISTENCE_SAVE_FAILED` when the new terms
2165
+ * answer searches before a durable checkpoint holds them, and with
2166
+ * `PARTITION_REBALANCING_BACKPRESSURE` during a rebalance.
2167
+ */
2168
+ changeAnalysis(indexName: string, change: AnalysisChange): Promise<void>;
2169
+ }
2170
+
2171
+ /**
2172
+ * Changes the BM25 setting of a live index, which
2173
+ * {@link IndexConfig.bm25} sets when the index is created.
2174
+ *
2175
+ * @public
2176
+ */
2177
+ interface BM25Operations {
2178
+ /**
2179
+ * Replaces the BM25 setting of an index, so that every search that starts
2180
+ * after the promise resolves scores under the new setting.
2181
+ *
2182
+ * The call replaces the whole setting, so a value that it leaves out returns
2183
+ * to its default, and `{}` clears the setting. The engine rebuilds nothing,
2184
+ * because the setting changes no stored token. It saves the setting with the
2185
+ * index, so the setting stays in place after a restart, and every snapshot
2186
+ * of the index includes it. Where the index has copies on worker threads,
2187
+ * the promise resolves only once every copy holds the new setting. A cursor
2188
+ * from before the change keeps working, and its next pages can repeat or
2189
+ * skip documents, because the scores that order them can change.
2190
+ *
2191
+ * @param indexName - The index whose setting the engine replaces.
2192
+ * @param bm25 - The new setting, in the shape that {@link BM25Params} describes.
2193
+ * @throws A `NarsilError` with `CONFIG_INVALID` when `k1` is not a number from
2194
+ * 0 to 1,000, when `b` is not a number from 0 to 1, or when `fields` holds a
2195
+ * name that is not a text field. The index then keeps the setting that it
2196
+ * held before the call.
2197
+ */
2198
+ updateBM25(indexName: string, bm25: BM25Params): Promise<void>;
2199
+ }
2200
+
2201
+ /**
2202
+ * The bytes that {@link Narsil.restore} and {@link Narsil.importDocumentExport}
2203
+ * accept, as one array, a stream of chunks, or an async iterable of chunks,
2204
+ * such as a Node.js file stream.
2205
+ *
2206
+ * @public
2207
+ */
2208
+ type ByteSource = Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
2209
+
2210
+ /**
2211
+ * Opens and closes durable indexes without deleting them.
2212
+ *
2213
+ * @public
2214
+ */
2215
+ interface IndexLifecycleOperations {
2216
+ /**
2217
+ * Loads a closed index from its durable checkpoint and resets a parked recovery failure.
2218
+ *
2219
+ * @param indexName - The index to load.
2220
+ * @returns A promise that settles when the index is ready for operations.
2221
+ */
2222
+ open(indexName: string): Promise<void>;
2223
+ /**
2224
+ * Drains active work, checkpoints the index, releases its memory, and keeps its durable files.
2225
+ *
2226
+ * @param indexName - The index to close.
2227
+ * @returns A promise that settles after the index releases its memory.
2228
+ */
2229
+ close(indexName: string): Promise<void>;
2230
+ }
2231
+
2232
+ /**
2233
+ * The device sync setting of one index, which {@link SyncOperations.updateSync} takes.
2234
+ *
2235
+ * Turn sync on only for an index whose every document belongs to one user, because every device that syncs the index
2236
+ * receives the whole index. Create one index for each user, and leave sync off for a public index or for an index that
2237
+ * holds the data of several users.
2238
+ *
2239
+ * @public
2240
+ */
2241
+ interface SyncSetting {
2242
+ /** This turns sync on or off. Turning it on gives the index a new epoch, so every synced device loads a new copy. */
2243
+ enabled: boolean;
2244
+ /** This is the age in milliseconds after which the server deletes a log segment from history. It defaults to 30
2245
+ * days. */
2246
+ historyMaxAgeMs?: number;
2247
+ /** This is the byte count above which the server deletes the oldest log segment from history. It defaults to the
2248
+ * length of the published snapshot. */
2249
+ historyMaxBytes?: number;
2250
+ }
2251
+ /**
2252
+ * The device sync state of one index, which {@link SyncOperations.getSync} returns.
2253
+ *
2254
+ * @public
2255
+ */
2256
+ interface SyncStatus extends SyncSetting {
2257
+ /** This is true once a device has asked for the published snapshot, from when the server keeps history. */
2258
+ active: boolean;
2259
+ /** This is the index epoch, 32 lowercase hexadecimal digits, or `null` while sync is off. */
2260
+ epoch: string | null;
2261
+ }
2262
+ /**
2263
+ * The methods that turn device sync on and off for an index.
2264
+ *
2265
+ * @public
2266
+ */
2267
+ interface SyncOperations {
2268
+ /**
2269
+ * Replaces the device sync setting of an index.
2270
+ *
2271
+ * Turning sync on gives the index a new epoch. Changing a history limit while sync is on keeps the epoch. Turning
2272
+ * sync off deletes the published snapshot and the history, and the server closes every feed of the index with
2273
+ * close code 4410. The engine saves the setting with the index, so the setting stays in place after a restart, and
2274
+ * no snapshot of the index includes it.
2275
+ *
2276
+ * @param indexName - The index whose setting the engine replaces.
2277
+ * @param setting - The new setting.
2278
+ * @throws A `NarsilError` with `SYNC_DURABILITY_REQUIRED` when the engine has no write-ahead log durability, and
2279
+ * with `CONFIG_INVALID` when a history limit is not a positive whole number.
2280
+ */
2281
+ updateSync(indexName: string, setting: SyncSetting): Promise<void>;
2282
+ /**
2283
+ * Returns the device sync state of an index.
2284
+ *
2285
+ * @param indexName - The index whose state the engine returns.
2286
+ * @returns The setting, whether a device has asked for the snapshot, and the epoch.
2287
+ * @throws A `NarsilError` with `INDEX_NOT_FOUND` when no index has that name.
2288
+ */
2289
+ getSync(indexName: string): Promise<SyncStatus>;
2290
+ }
2291
+
2292
+ /**
2293
+ * Reads and replaces the synonym set of an index, which
2294
+ * {@link IndexConfig.synonyms} sets when the index is created.
2295
+ *
2296
+ * @public
2297
+ */
2298
+ interface SynonymOperations {
2299
+ /**
2300
+ * Replaces the synonym set of an index, so that every search that starts
2301
+ * after the promise resolves expands its words with the new set.
2302
+ *
2303
+ * The engine applies the set without rebuilding the index, because a
2304
+ * synonym set changes no stored token. It saves the set with the index, so
2305
+ * the set stays in place after a restart, and every snapshot of the index
2306
+ * includes it. Where the index has copies on worker threads, the promise
2307
+ * resolves only once every copy uses the new set. Pass an empty list to
2308
+ * remove the set.
2309
+ *
2310
+ * @param indexName - The index whose set the engine replaces.
2311
+ * @param synonyms - The new set, in the shape that {@link SynonymRule}
2312
+ * describes.
2313
+ * @throws A `NarsilError` with `CONFIG_INVALID` when a rule breaks that
2314
+ * shape, when a word analyses to no token or to more than one, or when the
2315
+ * set passes 100,000 rules, 500,000 words, or 4,194,304 bytes of words in
2316
+ * UTF-8. The index then keeps the set that it held before the call.
2317
+ */
2318
+ updateSynonyms(indexName: string, synonyms: SynonymRule[]): Promise<void>;
2319
+ /**
2320
+ * Returns the synonym set of an index with every word as the caller wrote
2321
+ * it, or an empty list when the index holds no set.
2322
+ *
2323
+ * @param indexName - The index whose set the engine returns.
2324
+ */
2325
+ getSynonyms(indexName: string): Promise<SynonymRule[]>;
2326
+ }
2327
+
1606
2328
  /**
1607
- * This map holds a listener for any event of {@link NarsilEventMap}, so that
1608
- * the engine can register each listener before it starts.
2329
+ * Reports on and rebuilds the graphs of an index's vector fields.
1609
2330
  *
1610
2331
  * @public
1611
2332
  */
1612
- type NarsilEventHandlers = {
1613
- [K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
1614
- };
2333
+ interface VectorMaintenanceOperations {
2334
+ /**
2335
+ * Rebuilds a vector field's graph without the tombstones removed documents
2336
+ * left behind, which returns the memory they held and speeds searches up.
2337
+ *
2338
+ * Read {@link VectorMaintenanceOperations.vectorMaintenanceStatus} first to
2339
+ * see whether the work is worth its cost.
2340
+ *
2341
+ * @param indexName - The index holding the field.
2342
+ * @param fieldName - The vector field to compact. Omit it to compact every
2343
+ * vector field in the index.
2344
+ */
2345
+ compactVectors(indexName: string, fieldName?: string): Promise<void>;
2346
+ /**
2347
+ * Rebuilds a vector field's graph from scratch, which recovers the recall a
2348
+ * long run of inserts and removals costs.
2349
+ *
2350
+ * This is heavier than {@link VectorMaintenanceOperations.compactVectors} and
2351
+ * gives a better graph, so run it once a search starts missing documents it
2352
+ * should find, rather than on a schedule.
2353
+ *
2354
+ * @param indexName - The index holding the field.
2355
+ * @param fieldName - The vector field to rebuild. Omit it to rebuild every
2356
+ * vector field in the index.
2357
+ */
2358
+ optimizeVectors(indexName: string, fieldName?: string): Promise<void>;
2359
+ /**
2360
+ * Reports the state of each vector field in an index, and what compaction or
2361
+ * optimisation would cost.
2362
+ *
2363
+ * @param indexName - The index to describe.
2364
+ * @returns One entry per vector field, or an empty list while the index is closed.
2365
+ */
2366
+ vectorMaintenanceStatus(indexName: string): VectorMaintenanceResult[];
2367
+ }
1615
2368
 
1616
2369
  /**
1617
- * Snapshot of V8 heap usage as reported by `process.memoryUsage()`, with the
1618
- * limit the heap may grow to. All values are bytes. `null` in environments
1619
- * that do not expose `process.memoryUsage`, such as browsers.
2370
+ * Adds, replaces, and removes documents, and waits for the worker copies to
2371
+ * catch up with those writes.
2372
+ *
2373
+ * A write returns once the main copy holds it, and the worker copies apply
2374
+ * it afterwards, so a query that a copy answers can come back without a write
2375
+ * that returned before it. Every write takes a `wait` option for the cases
2376
+ * where the next query has to see it.
1620
2377
  *
1621
2378
  * @public
1622
2379
  */
1623
- interface ProcessMemoryReport {
1624
- /** The process is using this much heap. */
1625
- heapUsed: number;
1626
- /** V8 has reserved this much heap. */
1627
- heapTotal: number;
2380
+ interface DocumentWriteOperations {
1628
2381
  /**
1629
- * The heap may grow to this many bytes before the runtime ends the process
1630
- * for running out of memory. Node sets it from `--max-old-space-size`, from
1631
- * `--max-old-space-size-percentage`, or from the memory the host or the
1632
- * container reports. `null` where the runtime cannot report it.
2382
+ * Adds one document to an index and returns the id it is stored under.
2383
+ *
2384
+ * The id comes from the `docId` argument when you pass one, otherwise from
2385
+ * the document's own `id` field, and otherwise the engine generates it. Use
2386
+ * {@link DocumentWriteOperations.insertBatch} for a large load, so that one
2387
+ * bad document cannot abandon the rest.
2388
+ *
2389
+ * @param indexName - The index that receives the document.
2390
+ * @param document - Its fields must match the types the schema declares.
2391
+ * @param docId - Pass an id to control it yourself, or omit it and read the
2392
+ * returned value. An id that differs from the document's own `id` field
2393
+ * raises `DOC_VALIDATION_FAILED`, because the stored document would
2394
+ * otherwise contradict the key that it is stored under.
2395
+ * @param options - Per-write settings, such as skipping the defensive copy
2396
+ * or waiting for every worker copy to apply the write.
2397
+ * @returns The id the document is stored under.
1633
2398
  */
1634
- heapLimit: number | null;
1635
- /** The process holds this much outside the heap, such as buffers. */
1636
- external: number;
1637
- /** The process occupies this much physical memory in total. */
1638
- rss: number;
2399
+ insert(indexName: string, document: AnyDocument, docId?: string, options?: InsertOptions): Promise<string>;
2400
+ /**
2401
+ * Adds many documents in one pass and reports each one's outcome.
2402
+ *
2403
+ * A document the engine rejects appears in `failed` with the error that
2404
+ * rejected it, and every other document is still written, which is what
2405
+ * makes this the call to load a corpus with.
2406
+ *
2407
+ * @param indexName - The index that receives the documents.
2408
+ * @param documents - The documents to write, each carrying its own id or
2409
+ * leaving the engine to generate one.
2410
+ * @param options - Per-write settings applied to every document.
2411
+ * @returns The ids written, and each rejection with its error.
2412
+ */
2413
+ insertBatch(indexName: string, documents: AnyDocument[], options?: InsertOptions): Promise<BatchResult>;
2414
+ /**
2415
+ * Removes one document.
2416
+ *
2417
+ * @param indexName - The index holding the document.
2418
+ * @param docId - The document to remove.
2419
+ * @param options - Per-write settings, such as waiting for every worker
2420
+ * copy to apply the removal.
2421
+ * @throws A `NarsilError` with `DOC_NOT_FOUND` when the index holds no such
2422
+ * document.
2423
+ */
2424
+ remove(indexName: string, docId: string, options?: WriteOptions): Promise<void>;
2425
+ /**
2426
+ * Removes many documents in one pass and reports each one's outcome.
2427
+ *
2428
+ * @param indexName - The index holding the documents.
2429
+ * @param docIds - The documents to remove.
2430
+ * @param options - Per-write settings applied to the whole batch.
2431
+ * @returns The ids removed, and each failure with its error.
2432
+ */
2433
+ removeBatch(indexName: string, docIds: string[], options?: WriteOptions): Promise<BatchResult>;
2434
+ /**
2435
+ * Replaces a stored document with the one you pass.
2436
+ *
2437
+ * The engine removes the old document and indexes the new one, so the
2438
+ * document you supply has to be complete, with every field it should hold
2439
+ * afterwards.
2440
+ *
2441
+ * @param indexName - The index holding the document.
2442
+ * @param docId - The document to replace.
2443
+ * @param document - The complete replacement.
2444
+ * @param options - Per-write settings, such as waiting for every worker
2445
+ * copy to apply the replacement.
2446
+ */
2447
+ update(indexName: string, docId: string, document: AnyDocument, options?: WriteOptions): Promise<void>;
2448
+ /**
2449
+ * Replaces many documents in one pass and reports each one's outcome.
2450
+ *
2451
+ * @param indexName - The index holding the documents.
2452
+ * @param updates - Each id with the complete document that replaces it.
2453
+ * @param options - Per-write settings applied to the whole batch.
2454
+ * @returns The ids replaced, and each failure with its error.
2455
+ */
2456
+ updateBatch(indexName: string, updates: Array<{
2457
+ docId: string;
2458
+ document: AnyDocument;
2459
+ }>, options?: WriteOptions): Promise<BatchResult>;
2460
+ /**
2461
+ * Resolves once every worker copy of an index has applied every write that
2462
+ * returned before the call.
2463
+ *
2464
+ * Call this after a run of writes, or pass `wait: true` on one write,
2465
+ * before a query that has to see them. An index that holds no copies
2466
+ * resolves at once.
2467
+ *
2468
+ * @param indexName - The index whose copies have to catch up.
2469
+ */
2470
+ waitForWrites(indexName: string): Promise<void>;
1639
2471
  }
2472
+
1640
2473
  /**
1641
- * Whether one index holds worker copies at the moment
1642
- * {@link Narsil.getMemoryStats} reads it, and how many times it has loaded
1643
- * them again after giving them up while idle.
2474
+ * What {@link Narsil.snapshot} adds to the archive beyond the checkpoint.
1644
2475
  *
1645
2476
  * @public
1646
2477
  */
1647
- interface WorkerCopyReport {
1648
- /** This names the index. */
1649
- indexName: string;
1650
- /** This is true while every worker holds a copy of the index. */
1651
- scaledOut: boolean;
1652
- /** The index has loaded its copies again this many times after an idle spell dropped them. */
1653
- reloadCount: number;
2478
+ interface SnapshotOptions {
2479
+ /**
2480
+ * Set this to add the index's popular query history, which holds raw
2481
+ * searches, so that a restore on a node with the same key keeps the counts.
2482
+ * Defaults to false, because a backup that holds history can keep searches
2483
+ * past their retention.
2484
+ */
2485
+ queryHistory?: boolean;
1654
2486
  }
1655
2487
  /**
1656
- * What {@link Narsil.getMemoryStats} returns, which is what you size a host
1657
- * from.
2488
+ * The search engine, and everything you do with it.
2489
+ *
2490
+ * One instance holds every index you create, so an application usually keeps a
2491
+ * single engine for its lifetime and reaches each index by name. Build one
2492
+ * with {@link createNarsil}. Its write, open and close, synonym, analysis, BM25,
2493
+ * device sync, change capture, vector maintenance, and adapter registration
2494
+ * methods come from {@link DocumentWriteOperations},
2495
+ * {@link IndexLifecycleOperations}, {@link SynonymOperations},
2496
+ * {@link AnalysisOperations}, {@link BM25Operations}, {@link SyncOperations},
2497
+ * {@link ChangesOperations}, {@link VectorMaintenanceOperations}, and
2498
+ * {@link AdapterRegistrationOperations}.
1658
2499
  *
1659
2500
  * @public
1660
2501
  */
1661
- interface MemoryStats {
2502
+ interface Narsil extends IndexLifecycleOperations, DocumentWriteOperations, SynonymOperations, AnalysisOperations, BM25Operations, SyncOperations, ChangesOperations, VectorMaintenanceOperations, AdapterRegistrationOperations {
1662
2503
  /**
1663
- * V8 heap usage for the host process at the moment of the call. It covers
1664
- * the whole process, so every Narsil engine in one process returns the same
1665
- * `process` figures from `getMemoryStats`. `null` in browsers and in any
1666
- * runtime that does not expose `process.memoryUsage`.
2504
+ * Creates an index you can insert documents into and query.
2505
+ *
2506
+ * The schema sets the type of each field, marks which fields you can
2507
+ * filter and sort on, and controls how the engine tokenises text. The
2508
+ * `language` option picks the analyser that stems those text fields.
2509
+ *
2510
+ * @param name - Every later call uses this name to reach the index.
2511
+ * @param config - This carries the schema, and the language, partitioning,
2512
+ * and scoring settings.
1667
2513
  */
1668
- process: ProcessMemoryReport | null;
2514
+ createIndex(name: string, config: IndexConfig): Promise<void>;
1669
2515
  /**
1670
- * The sum of every index's {@link IndexStats.estimatedMemoryBytes} held by
1671
- * this engine. A formula produces it, so read it as an estimate. It compares
1672
- * engines inside one process, where `process.heapUsed` cannot tell them
1673
- * apart.
2516
+ * Removes an index and everything it holds, including whatever persistence
2517
+ * wrote for it. The documents do not come back.
2518
+ *
2519
+ * @param name - The index to drop.
1674
2520
  */
1675
- estimatedIndexBytes: number;
1676
- /** This many indexes currently occupy engine memory. */
1677
- openIndexCount: number;
1678
- /** This many indexes remain registered without occupying engine memory, including parked recovery failures. */
1679
- closedIndexCount: number;
1680
- /** This counts successful index loads since this engine started. */
1681
- reopenCount: number;
1682
- /** One entry per index, saying whether it holds worker copies now and how many times it has reloaded them. */
1683
- workerCopies: WorkerCopyReport[];
2521
+ dropIndex(name: string): Promise<void>;
1684
2522
  /**
1685
- * Per-worker V8 heap usage once the engine has started its worker pool.
1686
- * Empty while no worker is running.
2523
+ * Lists every index this engine holds, with its size and its language.
2524
+ *
2525
+ * @returns One entry per index, in creation order.
1687
2526
  */
1688
- workers: Array<{
1689
- /** This identifies the worker within the pool. */
1690
- workerId: number;
1691
- /** That worker is using this much heap. */
1692
- heapUsed: number;
1693
- /** V8 has reserved this much heap in that worker. */
1694
- heapTotal: number;
1695
- /** That worker's heap may grow to this many bytes, or `null` where its runtime cannot report it. */
1696
- heapLimit: number | null;
1697
- /** That worker holds this much outside its heap. */
1698
- external: number;
1699
- }>;
2527
+ listIndexes(): IndexInfo[];
2528
+ /**
2529
+ * Returns one index's document count, partition count, memory estimate,
2530
+ * language, and schema.
2531
+ *
2532
+ * @param indexName - The index to describe.
2533
+ * @returns The index's current figures.
2534
+ * @throws A `NarsilError` with `INDEX_NOT_FOUND` for an unknown name.
2535
+ */
2536
+ getStats(indexName: string): IndexStats;
2537
+ /**
2538
+ * Returns per-partition figures for one index, which is where you look when
2539
+ * an index grows unevenly or a rebalance is worth running.
2540
+ *
2541
+ * @param indexName - The index to describe.
2542
+ * @returns One entry per open partition, in partition order, or an empty list while the index is closed.
2543
+ */
2544
+ getPartitionStats(indexName: string): PartitionStatsResult[];
2545
+ /**
2546
+ * Fetches one stored document by id, without searching.
2547
+ *
2548
+ * A vector field comes back as a `Float32Array`, whatever form you give it.
2549
+ * `JSON.stringify` writes one as an object keyed by index, so convert it
2550
+ * with `Array.from`, or project the field away, before you serialise the
2551
+ * document yourself. The HTTP routes convert it for you.
2552
+ *
2553
+ * @param indexName - The index holding the document.
2554
+ * @param docId - The document to fetch.
2555
+ * @returns The document, or `undefined` when the index holds no such id.
2556
+ */
2557
+ get(indexName: string, docId: string): Promise<AnyDocument | undefined>;
2558
+ /**
2559
+ * Fetches many stored documents by id in one pass.
2560
+ *
2561
+ * @param indexName - The index holding the documents.
2562
+ * @param docIds - The documents to fetch.
2563
+ * @returns A map from id to document, holding an entry for each id that
2564
+ * exists and nothing for the rest.
2565
+ */
2566
+ getMultiple(indexName: string, docIds: string[]): Promise<Map<string, AnyDocument>>;
2567
+ /**
2568
+ * Reports whether an index holds a document, without reading it.
2569
+ *
2570
+ * @param indexName - The index to check.
2571
+ * @param docId - The document to look for.
2572
+ * @returns True when the index holds that id.
2573
+ */
2574
+ has(indexName: string, docId: string): Promise<boolean>;
2575
+ /**
2576
+ * Counts the documents an index holds.
2577
+ *
2578
+ * @param indexName - The index to count.
2579
+ * @returns The document count across every partition.
2580
+ */
2581
+ countDocuments(indexName: string): Promise<number>;
2582
+ /**
2583
+ * Reads one page of stored documents in document-id order, without
2584
+ * searching, which is how you page through a whole index.
2585
+ *
2586
+ * Leave `cursor` out for the first page, pass the returned cursor back for
2587
+ * each page after it, and stop when the cursor comes back null. A document
2588
+ * that stays in the index for the whole listing comes back exactly once. The
2589
+ * engine skips a document you remove part-way through. It returns one you
2590
+ * insert part-way through once that document's id sorts above the cursor.
2591
+ * The cursor holds no engine state, so it stays valid after a restart, a
2592
+ * snapshot restore, and a rebalance.
2593
+ *
2594
+ * The engine compares document ids by their UTF-16 code units, so `"10"`
2595
+ * sorts ahead of `"9"`.
2596
+ *
2597
+ * Set `document` to drop a vector field, because the engine otherwise reads
2598
+ * every listed document's vector back out of the index.
2599
+ *
2600
+ * @typeParam T - Shape of the stored documents, which flows through to each
2601
+ * entry's `document`.
2602
+ * @param indexName - The index to walk.
2603
+ * @param params - These set the cursor, the page size, the filter, and how
2604
+ * much of each document comes back.
2605
+ * @returns The page, the cursor for the next page, how many documents the
2606
+ * listing walks in total, and the time the page took.
2607
+ */
2608
+ listDocuments<T = AnyDocument>(indexName: string, params?: ListParams): Promise<ListResult<T>>;
2609
+ /**
2610
+ * Runs a search against an index and returns the ranked hits.
2611
+ *
2612
+ * One call covers keyword search, vector search, and a hybrid of the two,
2613
+ * chosen by the `mode` parameter. BM25 ranks keyword results by default.
2614
+ * Every hit carries its score and its document, along with highlights when
2615
+ * you ask for them.
2616
+ *
2617
+ * @typeParam T - Shape of the stored documents, which flows through to each
2618
+ * hit's `document`.
2619
+ * @param indexName - The index the search runs against.
2620
+ * @param params - These set the search term, filters, field boosts, sorting,
2621
+ * facets, highlighting, and the result limit.
2622
+ * @returns The hits, the total count, the elapsed time, and any facets or
2623
+ * groups the query asked for.
2624
+ */
2625
+ query<T = AnyDocument>(indexName: string, params: QueryParams): Promise<QueryResult<T>>;
2626
+ /**
2627
+ * Counts what a query would match without building a single hit, which is
2628
+ * how a result-count badge stays cheap. A full-text count also skips scoring
2629
+ * unless the query carries `minScore`, which prunes matches by score, or a
2630
+ * `termMatch` policy other than `any`, which prunes them by term coverage. A
2631
+ * vector or hybrid count still runs its search.
2632
+ *
2633
+ * @param indexName - The index the query would run against.
2634
+ * @param params - The same parameters {@link Narsil.query} takes. Anything
2635
+ * that shapes the output alone, such as `limit` or `highlight`, is ignored.
2636
+ * @returns The match count and the time the count took.
2637
+ */
2638
+ preflight(indexName: string, params: QueryParams): Promise<PreflightResult>;
2639
+ /**
2640
+ * Returns the indexed terms that complete a prefix, ready to offer as
2641
+ * you-type suggestions.
2642
+ *
2643
+ * The terms come back as the index holds them, which means stems unless the
2644
+ * index was created with `surfaceForms`.
2645
+ *
2646
+ * @param indexName - The index to draw completions from.
2647
+ * @param params - The prefix typed so far, and how many completions to
2648
+ * return.
2649
+ * @returns The completions, most widely used first.
2650
+ */
2651
+ suggest(indexName: string, params: SuggestParams): Promise<SuggestResult>;
2652
+ /**
2653
+ * Rebuilds an index's terms from the documents it already stores, and
2654
+ * resolves once every partition carries terms the current language module
2655
+ * produced.
2656
+ *
2657
+ * An index whose stored analysis revision differs from the one its language
2658
+ * module carries answers text queries from terms an earlier analysis wrote,
2659
+ * and every such result reports `analysisStale`. Call this after the engine
2660
+ * reports a stale index to configuration that declined an automatic rebuild.
2661
+ * Calling it for an index whose terms are current does nothing.
2662
+ *
2663
+ * @param indexName - The index whose terms are rebuilt.
2664
+ */
2665
+ rebuildAnalysis(indexName: string): Promise<void>;
2666
+ /**
2667
+ * Returns a stream of the index's snapshot archive. The archive is a pax
2668
+ * file containing the index's configuration and the files of one
2669
+ * checkpoint, and any implementation of the Narsil format can restore it.
2670
+ *
2671
+ * With write-ahead log durability, the engine takes a checkpoint before it
2672
+ * starts the stream, so the archive contains every write that the engine
2673
+ * acknowledged before the call. The engine keeps that checkpoint's files on
2674
+ * disk until the stream ends or you cancel it. Without write-ahead log
2675
+ * durability, the engine builds the archive's files from the index in
2676
+ * memory.
2677
+ *
2678
+ * @param indexName - The index to stream.
2679
+ * @param options - Set `queryHistory` to add the index's popular query
2680
+ * history, which holds raw searches, after the checkpoint's files.
2681
+ * @returns A stream of the archive's bytes, which you can write to a file or
2682
+ * send over a network.
2683
+ */
2684
+ snapshot(indexName: string, options?: SnapshotOptions): Promise<ReadableStream<Uint8Array>>;
2685
+ /**
2686
+ * Creates an index from a snapshot under the name that you pass, replacing
2687
+ * any index of that name.
2688
+ *
2689
+ * The engine accepts the archive that {@link Narsil.snapshot} streams and
2690
+ * the `.nrsl` file of release 0.3. It checks each archive file against its
2691
+ * manifest and loads the restored index beside the existing one, which
2692
+ * answers requests until the swap. A failed restore leaves the existing index
2693
+ * serving, and after a crash the engine reopens either the old or the new one.
2694
+ *
2695
+ * @param indexName - The name that the restored index takes.
2696
+ * @param data - The snapshot's bytes, as an array, a stream, or async chunks.
2697
+ * @throws A `NarsilError` with `PERSISTENCE_LOAD_FAILED` when the archive is
2698
+ * malformed or a file's length differs from the manifest. The engine raises
2699
+ * `PERSISTENCE_CRC_MISMATCH` when a file's checksum differs from its
2700
+ * contents, and `ENVELOPE_VERSION_MISMATCH` when a file has a format version
2701
+ * other than the ones that this release implements. It raises
2702
+ * `CONFIG_INVALID` when the archive's configuration is invalid,
2703
+ * `DOC_VALIDATION_FAILED` when the data is empty or the release 0.3 file is
2704
+ * invalid, `RESTORE_MEMORY_EXCEEDED` when the restored index needs more
2705
+ * memory than the process has free, and `WORKER_TIMEOUT` when a
2706
+ * worker still holds the old index 30 seconds after the engine asks for it.
2707
+ */
2708
+ restore(indexName: string, data: ByteSource): Promise<void>;
2709
+ /**
2710
+ * Returns a stream of the index's document export. The export is JSON Lines
2711
+ * text whose format stays the same in every release, so you can use it to
2712
+ * move an index across releases or between implementations.
2713
+ *
2714
+ * The first line is a header containing the format name, the format
2715
+ * version, and the index configuration. Each later line contains one
2716
+ * document, with its ID under `id` and the value of each vector field as an
2717
+ * array of numbers. With write-ahead log durability, the engine exports every
2718
+ * document from one checkpoint; otherwise, it exports them from the index in
2719
+ * memory at one moment.
2720
+ *
2721
+ * JSON has no type for a date, for raw bytes, or for an infinite number or
2722
+ * `NaN`, so the engine writes each such value as a tag. Each tag is an
2723
+ * object with one key that begins with `$`, such as
2724
+ * `{"$date":[1700000000,123000000]}`. The engine also wraps a stored object
2725
+ * whose only key begins with `$` in an `$object` tag, because the import
2726
+ * decodes every other object of that shape as a tag.
2727
+ *
2728
+ * @param indexName - The index to export.
2729
+ * @returns A stream of the export's UTF-8 bytes.
2730
+ */
2731
+ exportDocuments(indexName: string): Promise<ReadableStream<Uint8Array>>;
2732
+ /**
2733
+ * Imports a document export into the named index. Where the name is free,
2734
+ * the engine creates the index from the export's configuration.
2735
+ *
2736
+ * The engine writes the documents in batches and replaces any document
2737
+ * whose ID the index already contains. Because it replaces existing
2738
+ * documents, you can run an interrupted import again to make the index equal
2739
+ * to the export. When a line is invalid or the engine rejects its document,
2740
+ * the engine records the refusal and continues with the next line.
2741
+ *
2742
+ * The engine converts each tag that {@link Narsil.exportDocuments} writes
2743
+ * into the value that the tag stands for. When an object has one key that
2744
+ * begins with `$` and that key names no tag, or when a tag holds an invalid
2745
+ * value, the engine refuses the line.
2746
+ *
2747
+ * @param indexName - The index that receives the documents.
2748
+ * @param data - The export's bytes, as one array, a stream, or an async
2749
+ * iterable of chunks.
2750
+ * @returns The number of imported documents, the number of refused lines,
2751
+ * and the 1,000 refusals with the lowest line numbers.
2752
+ * @throws A `NarsilError` with `CONFIG_INVALID` when the first line is
2753
+ * anything other than a version 1 header, or when the named index exists
2754
+ * with a different schema.
2755
+ */
2756
+ importDocumentExport(indexName: string, data: ByteSource): Promise<DocumentImportResult>;
2757
+ /**
2758
+ * Writes an index's current state to the durability directory, so a restart
2759
+ * replays less of the log.
2760
+ *
2761
+ * @param indexName - The index to checkpoint.
2762
+ */
2763
+ checkpoint(indexName: string): Promise<void>;
2764
+ /**
2765
+ * Removes every document from an index and keeps the index itself, along
2766
+ * with its schema and settings.
2767
+ *
2768
+ * @param indexName - The index to empty.
2769
+ */
2770
+ clear(indexName: string): Promise<void>;
2771
+ /**
2772
+ * Spreads an index's documents across a different number of partitions.
2773
+ *
2774
+ * The engine keeps answering queries throughout, and it queues the writes
2775
+ * that arrive while the work runs, replaying them in order once it finishes.
2776
+ *
2777
+ * @param indexName - The index to rebalance.
2778
+ * @param targetPartitionCount - Partitions the index ends up with, at most
2779
+ * the index's `maxPartitions`, which defaults to 1. Raise that limit first
2780
+ * with {@link Narsil.updatePartitionConfig}.
2781
+ * @throws A `NarsilError` with `PARTITION_CAPACITY_EXCEEDED` when
2782
+ * `targetPartitionCount` is above `maxPartitions`.
2783
+ */
2784
+ rebalance(indexName: string, targetPartitionCount: number): Promise<void>;
2785
+ /**
2786
+ * Changes how an index grows into new partitions, without moving the
2787
+ * documents it already holds.
2788
+ *
2789
+ * @param indexName - The index to reconfigure.
2790
+ * @param config - The partitioning fields to change. Anything you leave out
2791
+ * keeps its current value.
2792
+ */
2793
+ updatePartitionConfig(indexName: string, config: Partial<PartitionConfig>): Promise<void>;
2794
+ /**
2795
+ * Reports what this engine and its host process are using, which is what you
2796
+ * size a host from.
2797
+ *
2798
+ * @returns Process heap figures, the engine's own estimate, and one entry
2799
+ * per worker once the engine has promoted.
2800
+ */
2801
+ getMemoryStats(): Promise<MemoryStats>;
2802
+ /**
2803
+ * Starts delivering one kind of engine event to your listener.
2804
+ *
2805
+ * These events report work the engine does on its own, away from the call
2806
+ * that triggered it, so this is where a failed background save or a worker
2807
+ * crash reaches you.
2808
+ *
2809
+ * @typeParam K - The event name, which fixes the payload the listener gets.
2810
+ * @param event - Which event to listen for.
2811
+ * @param handler - Called once per event.
2812
+ */
2813
+ on<K extends keyof NarsilEventMap>(event: K, handler: (payload: NarsilEventMap[K]) => void): void;
2814
+ /**
2815
+ * Removes a listener {@link Narsil.on} registered, so it receives no
2816
+ * further events.
2817
+ *
2818
+ * @typeParam K - The event name.
2819
+ * @param event - The event the listener was registered for.
2820
+ * @param handler - The same function reference that was registered.
2821
+ */
2822
+ off<K extends keyof NarsilEventMap>(event: K, handler: (payload: NarsilEventMap[K]) => void): void;
2823
+ /**
2824
+ * Closes the engine: it flushes pending writes, ends its workers, and
2825
+ * releases every adapter it opened.
2826
+ *
2827
+ * Call it before the process exits, because writes still in flight are lost
2828
+ * otherwise. The engine rejects new work once this starts.
2829
+ */
2830
+ shutdown(): Promise<void>;
1700
2831
  }
1701
2832
 
1702
- export { type VectorQueryConfig as $, type ArrayFilter as A, type BatchResult as B, type ClientErrorCode as C, type DocumentImportResult as D, type ErrorCode as E, type FacetConfig as F, type GeoFilter as G, type HighlightConfig as H, type IndexStats as I, type ListedDocument as J, type PresenceFilter as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type ProcessMemoryReport as O, type PreflightResult as P, type QueryParams as Q, type QueryCoverage as R, type ServerErrorCode as S, type RerankConfig as T, type ScoreComponents as U, type VectorMaintenanceResult as V, type SearchMode as W, type SortField as X, type SortSpec as Y, type StringFilter as Z, type TermMatchPolicy as _, ClientErrorCodes as a, type WorkerCopyReport as a0, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type QueryResult as e, type NarsilEventHandlers as f, type ListResult as g, type SuggestParams as h, isNarsilError as i, type SuggestResult as j, type PartitionStatsResult as k, type NarsilEventMap as l, type IndexInfo as m, type ComparisonFilter as n, type DocumentProjection as o, type FacetResult as p, type FieldFilter as q, type FilterExpression as r, type GeoPolygonFilter as s, type GeoRadiusFilter as t, type GroupConfig as u, type GroupReducer as v, type GroupResult as w, type HighlightMatch as x, type Hit as y, type HybridConfig as z };
2833
+ export { type FacetResult as $, type SuggestResult as A, type BatchResult as B, type Change as C, type AnalysisChange as D, type ErrorCode as E, type FollowChangesOptions as F, type GroupResult as G, type Hit as H, type IndexInfo as I, type NarsilEventMap as J, type AdapterRegistrationOperations as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type AnalysisOperations as O, type PartitionStatsResult as P, type QueryParams as Q, type ArrayFilter as R, type ServerErrorCode as S, type BM25Operations as T, type ByteSource as U, type VectorMaintenanceResult as V, type ComparisonFilter as W, type DocumentImportResult as X, type DocumentProjection as Y, type DocumentWriteOperations as Z, type FacetConfig as _, type ChangePosition as a, type FieldFilter as a0, type FilterExpression as a1, type GeoFilter as a2, type GeoPolygonFilter as a3, type GeoRadiusFilter as a4, type GroupReducer as a5, type HeldCheckpointReport as a6, type HighlightConfig as a7, type HighlightMatch as a8, type HybridConfig as a9, type IndexLifecycleOperations as aa, type ListedDocument as ab, type PresenceFilter as ac, type ProcessMemoryReport as ad, type QueryCoverage as ae, type RerankConfig as af, type ScoreComponents as ag, type SearchMode as ah, type SortField as ai, type SortSpec as aj, type StringFilter as ak, type SyncOperations as al, type SynonymOperations as am, type TermMatchPolicy as an, type VectorMaintenanceOperations as ao, type VectorQueryConfig as ap, type WorkerCopyReport as aq, type ChangeType as b, type ChangesBatch as c, type ChangesEvent as d, type ChangesOperations as e, type ChangesResync as f, type ChangesSetting as g, type ChangesStatus as h, type ChangesSubscribed as i, type ClientErrorCode as j, ClientErrorCodes as k, ErrorCodes as l, type NarsilErrorCode as m, ServerErrorCodes as n, type SnapshotOptions as o, type SyncSetting as p, type SyncStatus as q, isNarsilError as r, type Narsil as s, type QueryResult as t, type NarsilEventHandlers as u, type GroupConfig as v, type SuggestParams as w, type IndexStats as x, type ListResult as y, type PreflightResult as z };