@delali/narsil 0.3.0 → 0.3.1-next.101

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 (165) hide show
  1. package/README.md +9 -8
  2. package/dist/adapters/filesystem.d.ts +1 -1
  3. package/dist/adapters/filesystem.mjs +1 -1
  4. package/dist/adapters/indexeddb.d.ts +1 -1
  5. package/dist/adapters/indexeddb.mjs +1 -1
  6. package/dist/adapters/memory.d.ts +1 -1
  7. package/dist/{adapters-79OIa4xm.d.ts → adapters-BQFQ4PRz.d.ts} +27 -1
  8. package/dist/browser/chunk-BDOSMEEP.mjs +493 -0
  9. package/dist/browser/chunk-EJDUFWSO.mjs +602 -0
  10. package/dist/browser/chunk-HOZW3PKP.mjs +9 -0
  11. package/dist/browser/chunk-JOVZ6HMT.mjs +4358 -0
  12. package/dist/browser/chunk-JPTQZWJQ.mjs +10 -0
  13. package/dist/browser/chunk-KPJMDPHG.mjs +24558 -0
  14. package/dist/browser/chunk-PGIM3HIM.mjs +2743 -0
  15. package/dist/browser/chunk-RHG4O77A.mjs +206 -0
  16. package/dist/browser/chunk-RIJSLY2I.mjs +360 -0
  17. package/dist/browser/durability-wiring-SRUYT3VV.mjs +3875 -0
  18. package/dist/browser/module-CBB2ETYP.mjs +3111 -0
  19. package/dist/browser/release-76MXRPGV.mjs +33 -0
  20. package/dist/browser/replace-RURXTGVG.mjs +57 -0
  21. package/dist/browser/restore-queue-EEZQO6RF.mjs +35 -0
  22. package/dist/browser/runtime-7ZAHCHWR.mjs +557 -0
  23. package/dist/browser/snapshot-OAAA5UJ7.mjs +1210 -0
  24. package/dist/browser/write-7D6VIK6O.mjs +208 -0
  25. package/dist/{capabilities-DSsOGz6F.d.ts → capabilities-DiGlB6Sr.d.ts} +68 -7
  26. package/dist/chunk-2RIRGOUL.mjs +113 -0
  27. package/dist/chunk-37CD3OKS.mjs +87 -0
  28. package/dist/chunk-44W3CBNG.mjs +7 -0
  29. package/dist/chunk-46D6JQIG.mjs +426 -0
  30. package/dist/{chunk-VMRR3DQU.mjs → chunk-5JNA5SKS.mjs} +546 -35
  31. package/dist/chunk-747OHOUA.mjs +11 -0
  32. package/dist/chunk-75XIEF6H.mjs +126 -0
  33. package/dist/chunk-7X5JST5L.mjs +114 -0
  34. package/dist/chunk-BOFBLJFZ.mjs +209 -0
  35. package/dist/{chunk-USKFU7J5.mjs → chunk-BWJVNZPR.mjs} +8 -1
  36. package/dist/chunk-C7SLA6CM.mjs +19 -0
  37. package/dist/{chunk-POWOTUKJ.mjs → chunk-CQUMNIIG.mjs} +3 -6
  38. package/dist/chunk-CVXLLEQ3.mjs +1011 -0
  39. package/dist/chunk-DJHHF2L5.mjs +17 -0
  40. package/dist/chunk-E74YLAIG.mjs +24 -0
  41. package/dist/{chunk-UXNWQZST.mjs → chunk-EMRMGYRE.mjs} +236 -18
  42. package/dist/chunk-EWZLIYHV.mjs +57 -0
  43. package/dist/chunk-GBEEG5AN.mjs +35 -0
  44. package/dist/chunk-GES7U2PM.mjs +68 -0
  45. package/dist/chunk-HJSN7UYG.mjs +10 -0
  46. package/dist/chunk-HLPRHOSO.mjs +17 -0
  47. package/dist/chunk-HMFNFVP7.mjs +14 -0
  48. package/dist/chunk-J5QP52HA.mjs +1751 -0
  49. package/dist/{chunk-YNVIUGF5.mjs → chunk-JZVARCRZ.mjs} +3 -28
  50. package/dist/chunk-KOKM4PQN.mjs +52 -0
  51. package/dist/{chunk-B2TFROFX.mjs → chunk-KWTW6VTG.mjs} +465 -250
  52. package/dist/chunk-KZ3NX2P7.mjs +21 -0
  53. package/dist/chunk-L5ORED7V.mjs +25 -0
  54. package/dist/{chunk-THYRHHO2.mjs → chunk-LGAMKHA2.mjs} +2009 -2351
  55. package/dist/chunk-LKOB5COA.mjs +117 -0
  56. package/dist/chunk-LPQOEU5M.mjs +96 -0
  57. package/dist/{chunk-3LHGNRYE.mjs → chunk-LXWDQLTW.mjs} +7 -2
  58. package/dist/{chunk-L6TNPLAR.mjs → chunk-OEYI3KRB.mjs} +270 -108
  59. package/dist/chunk-OM362BRO.mjs +948 -0
  60. package/dist/chunk-OZDFA4WC.mjs +67 -0
  61. package/dist/chunk-P36MUFEJ.mjs +10 -0
  62. package/dist/chunk-PC2G76VW.mjs +2540 -0
  63. package/dist/{chunk-GCM3JFVA.mjs → chunk-PNEYIHA4.mjs} +11 -2
  64. package/dist/chunk-PNFKUCG3.mjs +1130 -0
  65. package/dist/chunk-Q6XWVUZX.mjs +44 -0
  66. package/dist/chunk-R27EMH5M.mjs +617 -0
  67. package/dist/{chunk-YMZCMH5M.mjs → chunk-R6A773WK.mjs} +19 -24
  68. package/dist/chunk-RF7PLG43.mjs +106 -0
  69. package/dist/chunk-RFBLQLLZ.mjs +16 -0
  70. package/dist/{chunk-Y3L5MDRV.mjs → chunk-RFVUDM5E.mjs} +17 -2
  71. package/dist/chunk-S7FL6UAH.mjs +521 -0
  72. package/dist/chunk-S7GNDRPS.mjs +651 -0
  73. package/dist/chunk-SP3NM3ZG.mjs +3537 -0
  74. package/dist/chunk-U476IXKQ.mjs +10 -0
  75. package/dist/chunk-UA3AUGNV.mjs +462 -0
  76. package/dist/chunk-UTG5YNXV.mjs +507 -0
  77. package/dist/chunk-VI4R6W25.mjs +8484 -0
  78. package/dist/chunk-WQBCBKY3.mjs +8 -0
  79. package/dist/{chunk-24RXHMEL.mjs → chunk-WVCOCKBU.mjs} +3794 -7570
  80. package/dist/chunk-X5CV2E2B.mjs +1 -0
  81. package/dist/chunk-XADZPPZI.mjs +614 -0
  82. package/dist/chunk-YEEQHT4V.mjs +212 -0
  83. package/dist/chunk-YTJCGKM4.mjs +56 -0
  84. package/dist/chunk-YYQIODMF.mjs +275 -0
  85. package/dist/chunk-ZI34TVOA.mjs +144 -0
  86. package/dist/{chunk-OOSIDHA3.mjs → chunk-ZKWYWW4Y.mjs} +1 -1
  87. package/dist/chunk-ZM7KU4YW.mjs +35 -0
  88. package/dist/{client-BQK6Tf6A.d.ts → client-BOStAkc5.d.ts} +160 -37
  89. package/dist/client.d.ts +11 -10
  90. package/dist/client.mjs +209 -45
  91. package/dist/{config-DmXULPa-.d.ts → config-Cjvzbs_j.d.ts} +51 -3
  92. package/dist/config-DffQlmRq.d.ts +421 -0
  93. package/dist/direct-executor-ZD64PPEZ.mjs +24 -0
  94. package/dist/distribution/coordinator/etcd.d.ts +79 -18
  95. package/dist/distribution/coordinator/etcd.mjs +553 -109
  96. package/dist/distribution/coordinator/in-memory.d.ts +4 -3
  97. package/dist/distribution/coordinator/in-memory.mjs +22 -3
  98. package/dist/distribution/transport/grpc.d.ts +2 -2
  99. package/dist/distribution/transport/grpc.mjs +79 -14
  100. package/dist/distribution/transport/in-memory.d.ts +2 -2
  101. package/dist/distribution/transport/in-memory.mjs +12 -7
  102. package/dist/distribution/transport/tcp.d.ts +2 -2
  103. package/dist/distribution/transport/tcp.mjs +50 -28
  104. package/dist/distribution.d.ts +144 -23
  105. package/dist/distribution.mjs +14479 -8173
  106. package/dist/durability-wiring-FEUBR5BT.mjs +3330 -0
  107. package/dist/embeddings/openai.d.ts +2 -2
  108. package/dist/embeddings/openai.mjs +22 -133
  109. package/dist/{engine-CIOyFozK.d.ts → engine-rC0vjjY-.d.ts} +165 -141
  110. package/dist/{memory-yFaVn2xZ.d.ts → events-DqOIg5xa.d.ts} +645 -136
  111. package/dist/{types-DAK7mnUZ.d.ts → index-Bkdt8nDw.d.ts} +182 -45
  112. package/dist/index.browser.mjs +4 -32180
  113. package/dist/index.d.ts +91 -20
  114. package/dist/index.mjs +33 -16
  115. package/dist/invalidation/broadcast-channel.d.ts +1 -1
  116. package/dist/invalidation/filesystem.d.ts +1 -1
  117. package/dist/invalidation/filesystem.mjs +2 -1
  118. package/dist/invalidation/noop.d.ts +1 -1
  119. package/dist/module-3S65MVCM.mjs +2151 -0
  120. package/dist/partial-words-DTIHO8G4.d.ts +19 -0
  121. package/dist/partial-words.d.ts +22 -0
  122. package/dist/partial-words.mjs +17 -0
  123. package/dist/pattern-Cledccbl.d.ts +18 -0
  124. package/dist/pattern.d.ts +22 -0
  125. package/dist/pattern.mjs +12 -0
  126. package/dist/persistence/durability/checkpoint-worker.d.ts +119 -72
  127. package/dist/persistence/durability/checkpoint-worker.mjs +51 -18
  128. package/dist/react.d.ts +279 -183
  129. package/dist/react.mjs +201 -48
  130. package/dist/release-BH3DKW3T.mjs +33 -0
  131. package/dist/replace-CEO5KJJ3.mjs +57 -0
  132. package/dist/rerank-K7C4WZFG.mjs +60 -0
  133. package/dist/rerankers/http.d.ts +50 -0
  134. package/dist/rerankers/http.mjs +104 -0
  135. package/dist/restore-queue-KQHA7ZV2.mjs +35 -0
  136. package/dist/runtime-6Y4ZYXOG.mjs +177 -0
  137. package/dist/{schema-d5Afu03A.d.ts → schema-4W_7tk1f.d.ts} +81 -11
  138. package/dist/server.d.ts +13 -12
  139. package/dist/server.mjs +611 -80
  140. package/dist/snapshot-QGZPODM5.mjs +799 -0
  141. package/dist/synonyms-CpOAHPa-.d.ts +52 -0
  142. package/dist/synonyms.d.ts +22 -0
  143. package/dist/synonyms.mjs +12 -0
  144. package/dist/{tasks-CH2Dod8w.d.ts → tasks-CwPTz-tP.d.ts} +10 -3
  145. package/dist/thread-N3IUGUS3.mjs +697 -0
  146. package/dist/{types-BQDlIvfS.d.ts → types-2qoitTXg.d.ts} +1 -1
  147. package/dist/{types-D5OwhtsQ.d.ts → types-Cz5okLml.d.ts} +2 -2
  148. package/dist/vector/search-worker.d.ts +46 -4
  149. package/dist/vector/search-worker.mjs +21 -11
  150. package/dist/workers/entry.mjs +9 -6
  151. package/dist/write-U5RI7MAX.mjs +241 -0
  152. package/package.json +55 -9
  153. package/dist/chunk-3L4U6EJQ.mjs +0 -49
  154. package/dist/chunk-IFBKLBGB.mjs +0 -7
  155. package/dist/chunk-ORBLD3EL.mjs +0 -6
  156. package/dist/chunk-U7KYW4BA.mjs +0 -135
  157. package/dist/chunk-ZJ4CSAB2.mjs +0 -13
  158. package/dist/chunk-ZNZBXMP5.mjs +0 -2117
  159. package/dist/chunk-ZZT3EAUC.mjs +0 -11168
  160. package/dist/config-BhldZgaK.d.ts +0 -194
  161. package/dist/direct-executor-ALAVE7FC.mjs +0 -12
  162. package/dist/serialization/crc32-worker.d.ts +0 -20
  163. package/dist/serialization/crc32-worker.mjs +0 -62
  164. package/dist/simd-DW5AtJ6B.d.ts +0 -41
  165. package/dist/thread-DYHEQRVY.mjs +0 -402
package/dist/react.d.ts CHANGED
@@ -1,340 +1,436 @@
1
- import { N as NarsilError, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, Q as QueryParams, h as PreflightResult, e as QueryResult, j as SuggestParams, k as SuggestResult } from './memory-yFaVn2xZ.js';
2
- export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-yFaVn2xZ.js';
3
- import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-CH2Dod8w.js';
4
- export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-CH2Dod8w.js';
1
+ import { N as NarsilError, L as ListParams, g as ListResult, I as IndexInfo, k as IndexStats, Q as QueryParams, P as PreflightResult, e as QueryResult, h as SuggestParams, j as SuggestResult } from './events-DqOIg5xa.js';
2
+ export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './events-DqOIg5xa.js';
3
+ import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-CwPTz-tP.js';
4
+ export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-CwPTz-tP.js';
5
5
  import { ReactNode, ReactElement } from 'react';
6
- import { N as NarsilClient, I as ImportSource } from './client-BQK6Tf6A.js';
7
- import { A as AnyDocument } from './schema-d5Afu03A.js';
8
- import './adapters-79OIa4xm.js';
6
+ import { N as Narsil } from './engine-rC0vjjY-.js';
7
+ import { N as NarsilClient, I as ImportSource } from './client-BOStAkc5.js';
8
+ import { A as AnyDocument } from './schema-4W_7tk1f.js';
9
+ import './synonyms-CpOAHPa-.js';
10
+ import './adapters-BQFQ4PRz.js';
9
11
 
10
12
  /**
11
- * These are the settings {@link NarsilProvider} takes.
13
+ * These settings apply to {@link NarsilProvider} whether it holds a client or
14
+ * an engine.
12
15
  *
13
16
  * @public
14
17
  */
15
- interface NarsilProviderProps {
16
- /** Every hook under the provider sends through this client. Build it once,
17
- * outside the component tree, because a client built during a render would
18
- * throw away everything the hooks under it hold. */
19
- client: NarsilClient;
20
- /** The hooks keep an answer for this many milliseconds after the last
21
- * component reading it has gone, and 2000 unless you say otherwise. The wait
22
- * covers the gap between React unmounting a component and mounting it again,
23
- * so a quick navigation back shows what it showed before and sends no second
24
- * request. */
18
+ interface NarsilProviderSettings {
19
+ /** The provider keeps each answer for this many milliseconds after the last
20
+ * component that reads the answer unmounts, which is 2000 unless you set
21
+ * another value. That wait spans the gap between React unmounting a component
22
+ * and mounting it again, so a quick navigation back can show the earlier
23
+ * answer without sending a second request. */
25
24
  keepAliveMs?: number;
26
- /** These are the components the provider covers. */
25
+ /** Under an engine, the hooks that read a written index search again once
26
+ * this many milliseconds pass without another write to that index, so each
27
+ * mounted hook searches once for a whole burst of writes. `useIndexes`
28
+ * searches again once that many milliseconds pass without a write to any
29
+ * index. The wait lasts 200 milliseconds unless you set another value. Under
30
+ * a client, the setting has no effect,
31
+ * because a server sends the client no write events. */
32
+ refreshAfterWriteMs?: number;
33
+ /** React renders these components under the provider. */
27
34
  children?: ReactNode;
28
35
  }
29
36
  /**
30
- * Gives every hook below it the client to send through, and the shared state
31
- * they read.
37
+ * These props give {@link NarsilProvider} a client, so that every hook under
38
+ * the provider sends its requests to a server.
32
39
  *
33
- * Two components asking for the same thing under one provider send one request
34
- * and read one answer. The provider drops that state once it unmounts, and it
35
- * stops whatever is still in flight.
40
+ * @public
41
+ */
42
+ interface NarsilClientProviderProps extends NarsilProviderSettings {
43
+ /** Every hook under the provider sends its requests through this client.
44
+ * Build the client once, outside the component tree, because a render that
45
+ * builds a client builds a new one each time, so every hook under the
46
+ * provider starts again. */
47
+ client: NarsilClient;
48
+ /** Leave this unset, because a provider holds either a client or an engine. */
49
+ engine?: undefined;
50
+ }
51
+ /**
52
+ * These props give {@link NarsilProvider} an engine in the same page, so that
53
+ * every read hook under the provider calls that engine and searches again after
54
+ * each burst of writes to an index that the hook reads.
36
55
  *
37
- * @param props - These name the client and the components the provider covers.
38
- * @returns The provider renders its children unchanged.
56
+ * @public
57
+ */
58
+ interface NarsilEngineProviderProps extends NarsilProviderSettings {
59
+ /** Every read hook under the provider calls this engine. Create the engine
60
+ * once, outside the component tree, because a render that creates an engine
61
+ * creates a new one each time, so every hook under the provider starts
62
+ * again. */
63
+ engine: Narsil;
64
+ /** Leave this unset, because a provider holds either a client or an engine. */
65
+ client?: undefined;
66
+ }
67
+ /**
68
+ * These are the props of {@link NarsilProvider}, which hold either a client of
69
+ * a server or an engine in the same page, together with the settings that both
70
+ * cases share.
71
+ *
72
+ * @public
73
+ */
74
+ type NarsilProviderProps = NarsilClientProviderProps | NarsilEngineProviderProps;
75
+ /**
76
+ * This component gives every hook under it the client or the engine to call,
77
+ * together with one store of answers that those hooks share.
78
+ *
79
+ * Every read hook calls the method of the same name on the client or on the
80
+ * engine. When two components under one provider ask for the same thing, they
81
+ * send one request and receive one answer. Under an engine, the provider
82
+ * registers a listener for the engine's `write` event, so every mounted hook
83
+ * that reads the written index searches again once per burst of writes. Once
84
+ * the provider unmounts and `keepAliveMs` passes, the provider drops the shared
85
+ * answers and stops waiting for the requests that are still in flight.
86
+ *
87
+ * @param props - These props set the client or the engine, the settings, and
88
+ * the components that render under the provider.
89
+ * @returns The element renders the children unchanged.
90
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render, when the
91
+ * props set both a client and an engine, or neither.
39
92
  *
40
93
  * @public
41
94
  */
42
95
  declare function NarsilProvider(props: NarsilProviderProps): ReactElement;
43
96
  /**
44
- * Reads the client the nearest {@link NarsilProvider} holds, which is what any
45
- * call the hooks leave out goes through.
97
+ * This hook returns the client that the nearest {@link NarsilProvider} holds,
98
+ * which serves every call that has no hook of its own, such as a write.
46
99
  *
47
- * @returns This is the client the provider was given.
48
- * @throws A `NarsilError` with `CONFIG_INVALID` when no provider stands above
49
- * the component.
100
+ * @returns This is the client that the provider holds.
101
+ * @throws A `NarsilError` with `CONFIG_INVALID` when no provider wraps the
102
+ * component, and also when the provider holds an engine, which the component
103
+ * can import directly.
50
104
  *
51
105
  * @public
52
106
  */
53
107
  declare function useNarsilClient(): NarsilClient;
54
108
 
55
109
  /**
56
- * What every hook sends with each request it makes.
110
+ * A hook sends these settings with each request that it makes through a
111
+ * client.
57
112
  *
58
- * A hook owns the lifetime of its own request, so it takes no signal. The store
59
- * behind it stops a request the moment nothing reads the answer.
113
+ * These settings include no signal, because each hook controls the lifetime of
114
+ * its own request. The provider stops waiting for a request once `keepAliveMs`
115
+ * passes with no component reading the answer. Under an engine, the hooks pass
116
+ * neither setting to the engine, because the engine computes its results in the
117
+ * same page.
60
118
  *
61
119
  * @public
62
120
  */
63
121
  interface NarsilRequestSettings {
64
- /** The hook sends these headers with its request. */
122
+ /** Under a client, the hook sends these headers with its request. */
65
123
  headers?: Record<string, string>;
66
- /** The hook gives the server this many milliseconds to answer, and 0 waits
67
- * for as long as the server takes. */
124
+ /** Under a client, the hook gives the server this many milliseconds to
125
+ * respond, while 0 sets no deadline. */
68
126
  timeoutMs?: number;
69
127
  }
70
128
  /**
71
- * These settings change what a read hook does, and every read hook takes them
72
- * as its last argument.
129
+ * These settings, which form the last argument of every read hook, change what
130
+ * the hook does.
73
131
  *
74
132
  * @public
75
133
  */
76
134
  interface NarsilReadOptions extends NarsilRequestSettings {
77
- /** The hook sends nothing while this is false, and it reports no data and no
78
- * failure, which is how a search waits for a term. */
135
+ /** While this is false, the hook sends no request and reports neither data
136
+ * nor a failure, so keep it false until a search has a term. */
79
137
  enabled?: boolean;
80
- /** The hook keeps showing the last answer while the next one loads, which
81
- * holds a result list steady as somebody types. */
138
+ /** The hook keeps showing the last answer while the next request is in
139
+ * flight, which keeps a result list in place as somebody types. */
82
140
  keepPreviousData?: boolean;
83
- /** The hook asks again this often, in milliseconds, and it pauses while the
84
- * page is hidden. It asks once and stops unless you set this. */
141
+ /** The hook sends the request again at this interval in milliseconds,
142
+ * pausing while the page is hidden. Without this setting, the hook sends the
143
+ * request once, then again after each burst of writes when the provider holds
144
+ * an engine. */
85
145
  refreshIntervalMs?: number;
86
146
  }
87
147
  /**
88
- * What a read hook reports.
148
+ * These fields report where the request of a read hook stands.
89
149
  *
90
- * `isLoading` covers the wait for the first answer, so a spinner branches on
91
- * it, while `isFetching` covers every request including a refresh, so a quieter
92
- * indicator branches on that one.
150
+ * `isLoading` covers the wait for the first answer, so show a spinner while it
151
+ * is true. `isFetching` covers every request, including a refresh, so show a
152
+ * quieter indicator while that one is true.
93
153
  *
94
- * @typeParam T - This is what the underlying client method answers with.
154
+ * @typeParam T - This is the type that the method behind the hook returns.
95
155
  *
96
156
  * @public
97
157
  */
98
158
  interface NarsilReadState<T> {
99
- /** This is the answer, and it stays undefined until the first one arrives. */
159
+ /** This is the answer, which stays undefined until the first request
160
+ * succeeds. */
100
161
  data: T | undefined;
101
- /** This is the failure the last request ended on, and the next success clears it. */
162
+ /** This is the failure that ended the last request, until the next success
163
+ * clears it. */
102
164
  error: NarsilError | undefined;
103
- /** This is true while the hook waits for an answer and has none to show. */
165
+ /** This is true while the hook has no answer to show and a request is in
166
+ * flight. */
104
167
  isLoading: boolean;
105
168
  /** This is true while a request is in flight, including a refresh. */
106
169
  isFetching: boolean;
107
- /** Calling this asks the server again, keeping the answer already on screen
108
- * until the new one arrives. */
170
+ /** Calling this sends the request again, while the answer already on screen
171
+ * stays until the new answer replaces it. */
109
172
  refresh: () => void;
110
173
  }
111
174
 
112
175
  /**
113
- * Reads one stored document, and reads it again whenever the id changes.
114
- *
115
- * A document the index does not hold comes back as `data: undefined` with no
116
- * failure, so read `isLoading` to tell an empty answer from one still on its
117
- * way. Passing no id switches the hook off, which is what a detail panel does
118
- * until somebody picks a row.
119
- *
120
- * @param indexName - This names the index holding the document.
121
- * @param docId - This names the document to read, and a nullish or empty id
122
- * switches the hook off.
123
- * @param options - These switch the hook off, keep the last document on screen,
124
- * and set the refresh interval, the headers, and the deadline.
125
- * @returns The state holds the document, the failure, the loading flags, and
126
- * the way to read it again.
176
+ * This hook fetches one stored document, then fetches it again whenever the id
177
+ * changes and, under an engine, after each burst of writes to the index.
178
+ *
179
+ * For a document that the index does not hold, the hook reports
180
+ * `data: undefined` with no failure, so check `isLoading` to tell an empty
181
+ * answer from one that is still in flight. A missing id switches the hook off,
182
+ * which suits a detail panel until somebody picks a row.
183
+ *
184
+ * @param indexName - This is the name of the index that holds the document.
185
+ * @param docId - This is the id of the document to fetch, where a nullish or
186
+ * empty id switches the hook off.
187
+ * @param options - These settings can switch the hook off, keep the last
188
+ * document on screen, and set the refresh interval, the headers, and the
189
+ * deadline.
190
+ * @returns The state holds the document, the failure, the two loading flags,
191
+ * and the `refresh` function.
127
192
  *
128
193
  * @public
129
194
  */
130
195
  declare function useDocument(indexName: string, docId: string | null | undefined, options?: NarsilReadOptions): NarsilReadState<AnyDocument | undefined>;
131
196
  /**
132
- * Pages through the stored documents without searching, which is what a table
133
- * of everything an index holds reads.
197
+ * This hook pages through the stored documents of an index without searching,
198
+ * which suits a table of everything that the index holds. Under an engine, the
199
+ * hook fetches the page again after each burst of writes to the index.
134
200
  *
135
- * @typeParam T - This is the shape of the stored documents.
136
- * @param indexName - This names the index to page through.
201
+ * @typeParam T - This is the type of the stored documents.
202
+ * @param indexName - This is the name of the index to page through.
137
203
  * @param params - These set the page size, the cursor, and any filter, sort, or
138
204
  * projection.
139
- * @param options - These switch the hook off, keep the last page on screen, and
140
- * set the refresh interval, the headers, and the deadline.
141
- * @returns The state holds the page and the cursor that reaches the next one.
205
+ * @param options - These settings can switch the hook off, keep the last page
206
+ * on screen, and set the refresh interval, the headers, and the deadline.
207
+ * @returns The state holds the page and the cursor for the next page.
142
208
  *
143
209
  * @public
144
210
  */
145
211
  declare function useDocuments<T = AnyDocument>(indexName: string, params?: ListParams, options?: NarsilReadOptions): NarsilReadState<ListResult<T>>;
146
212
 
147
213
  /**
148
- * These settings say how {@link useImport} runs a load and follows it.
214
+ * These settings control how {@link useImport} starts a load and polls its
215
+ * progress.
149
216
  *
150
217
  * @public
151
218
  */
152
219
  interface NarsilImportOptions extends NarsilRequestSettings {
153
- /** The hook asks the server how far the load has gone this often, and every
154
- * 250 ms unless you say otherwise, which is how often the server writes the
155
- * figures. It leaves five seconds between attempts while the server is
156
- * failing. */
220
+ /** The hook asks the server for the progress of the load at this interval in
221
+ * milliseconds, which is 250 unless you set another value. That default
222
+ * matches the interval at which the server updates the figures. While the
223
+ * server is failing, the hook waits five seconds between attempts. */
157
224
  pollIntervalMs?: number;
158
- /** The hook calls this once the load reaches a final status, whichever status
159
- * that is. */
225
+ /** The hook calls this function once the load reaches a final status,
226
+ * whatever that status is. */
160
227
  onSettled?: (record: TaskRecord) => void;
161
228
  }
162
229
  /**
163
- * What {@link useImport} reports, and what it offers to call.
230
+ * These fields report where a load from {@link useImport} stands, together with
231
+ * the functions that control the load.
164
232
  *
165
233
  * @public
166
234
  */
167
235
  interface NarsilImportState {
168
236
  /**
169
- * Sends a corpus and returns once the server has read the body and taken the
170
- * work on. The server loads the documents afterwards, and this hook follows
171
- * that work.
237
+ * This function sends a corpus, then returns once the server has received the
238
+ * body and started the task. The server loads the documents after that, while
239
+ * the hook polls the task.
172
240
  *
173
- * @param source - These are the documents, or the NDJSON you already hold.
174
- * @returns The record is the task the server started.
175
- * @throws A `NarsilError` under the code the server sent, and with
176
- * `NOT_FOUND` where the server predates the asynchronous import.
241
+ * @param source - These are the documents, or the NDJSON text that you
242
+ * already hold.
243
+ * @returns This is the record of the task that the server started.
244
+ * @throws A `NarsilError` under the code that the server sent, or with
245
+ * `NOT_FOUND` when the server is older than the asynchronous import.
177
246
  */
178
247
  start: (source: ImportSource) => Promise<TaskRecord>;
179
- /** Asks the running load to stop. Calling it while the corpus is still going
180
- * up stops the upload, and calling it afterwards asks the server to stop the
181
- * task, which stops between batches, so whatever it had already written stays
182
- * written. */
248
+ /** This function asks the load in progress to stop. While the browser is
249
+ * still sending the corpus, a call aborts the upload; after that, a call asks
250
+ * the server to stop the task. The server stops between batches, so the
251
+ * documents that it has already written stay in the index. */
183
252
  cancel: () => void;
184
- /** Clears the record and the failure, ready for another load. */
253
+ /** This function clears the record and the failure, so that the hook is
254
+ * ready for another load. */
185
255
  reset: () => void;
186
- /** This is the task, from the moment the server takes the load on. */
256
+ /** This is the record of the task, from the moment that the server starts
257
+ * it. */
187
258
  task: TaskRecord | undefined;
188
- /** This is how far the load has gone, which a progress bar reads. */
259
+ /** This is the progress of the load, which suits a progress bar. */
189
260
  progress: TaskProgress | undefined;
190
- /** This counts what the server accepted and refused, and it arrives once the
191
- * load finishes. */
261
+ /** This counts the documents that the server indexed and refused, which the
262
+ * hook sets once the load finishes. */
192
263
  result: ImportResult | undefined;
193
- /** This is the failure that stopped the load, or the one the last poll ended
194
- * on. */
264
+ /** This is the failure that stopped the load, or the failure that ended the
265
+ * last poll. */
195
266
  error: NarsilError | undefined;
196
- /** This is true from the moment you call `start` until the load reaches a
197
- * final status. */
267
+ /** This is true from the call to `start` until the load reaches a final
268
+ * status. */
198
269
  isImporting: boolean;
199
270
  }
200
271
  /**
201
- * Loads a corpus into an index and reports how far the load has gone.
272
+ * This hook loads a corpus into an index on a server and reports the progress
273
+ * of the load.
202
274
  *
203
275
  * The hook starts the load as a task, so the request returns as soon as the
204
- * server has read the body. A corpus that would outlast a proxy's response
205
- * timeout therefore still loads. The hook then polls the task, pausing while
206
- * the page is hidden, until the load succeeds, fails, or is cancelled.
276
+ * server has received the body. A corpus can therefore load even when the load
277
+ * takes longer than the response timeout of a proxy. The hook then polls the
278
+ * task until the load succeeds, fails, or ends in a cancellation, pausing
279
+ * whenever the page is hidden.
207
280
  *
208
281
  * Unmounting the component stops the polling alone, because the server finishes
209
- * the load either way. Follow it again with {@link useTask}, under the id of the
210
- * record `start` returned.
282
+ * the load either way. Follow the load again with {@link useTask}, under the id
283
+ * of the record that `start` returns.
211
284
  *
212
- * @param indexName - This names the index that receives the corpus.
213
- * @param options - These set the poll interval, the callback for the final
214
- * record, the headers, and the deadline.
215
- * @returns The state holds the task, the progress, the result, the failure, and
216
- * the three methods that drive a load.
285
+ * @param indexName - This is the name of the index that receives the corpus.
286
+ * @param options - These settings can set the poll interval, the callback for
287
+ * the final record, the headers, and the deadline.
288
+ * @returns The state holds the task, the progress, the result, the failure,
289
+ * and the three functions that control a load.
290
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render under a
291
+ * provider that holds an engine, because only a server handles imports.
217
292
  *
218
293
  * @public
219
294
  */
220
295
  declare function useImport(indexName: string, options?: NarsilImportOptions): NarsilImportState;
221
296
 
222
297
  /**
223
- * Lists every index the server holds, with its size and its language.
298
+ * This hook lists every index that the server or the engine holds, with the
299
+ * size and the language of each one. Under an engine, the hook fetches the list
300
+ * again after each burst of writes to any index.
224
301
  *
225
- * @param options - These switch the hook off, keep the last list on screen, and
226
- * set the refresh interval, the headers, and the deadline.
227
- * @returns The state holds the indexes in creation order.
302
+ * @param options - These settings can switch the hook off, keep the last list
303
+ * on screen, and set the refresh interval, the headers, and the deadline.
304
+ * @returns The state holds the indexes in the order of their creation.
228
305
  *
229
306
  * @public
230
307
  */
231
308
  declare function useIndexes(options?: NarsilReadOptions): NarsilReadState<IndexInfo[]>;
232
309
  /**
233
- * Reads one index's document count, partition count, memory estimate, language,
234
- * and schema.
310
+ * This hook fetches the document count, the partition count, the memory
311
+ * estimate, the language, and the schema of one index.
235
312
  *
236
- * Set `refreshIntervalMs` to watch the figures move while a load runs.
313
+ * Set `refreshIntervalMs` to watch the figures change while a load is in
314
+ * progress. Under an engine, the hook fetches the figures again after each
315
+ * burst of writes to the index.
237
316
  *
238
- * @param indexName - This names the index to describe.
239
- * @param options - These switch the hook off, keep the last figures on screen,
240
- * and set the refresh interval, the headers, and the deadline.
241
- * @returns The state holds the figures as they stood when the server answered.
317
+ * @param indexName - This is the name of the index to describe.
318
+ * @param options - These settings can switch the hook off, keep the last
319
+ * figures on screen, and set the refresh interval, the headers, and the
320
+ * deadline.
321
+ * @returns The state holds the figures as they stood when the server or the
322
+ * engine returned them.
242
323
  *
243
324
  * @public
244
325
  */
245
326
  declare function useStats(indexName: string, options?: NarsilReadOptions): NarsilReadState<IndexStats>;
246
327
 
247
328
  /**
248
- * Searches an index and re-runs the search whenever the parameters change.
249
- *
250
- * The parameters are the ones {@link SearchOperations.query} takes, and the
251
- * answer is the same `QueryResult`. Set `keepPreviousData` for a
252
- * search-as-you-type box, so that the hits already on screen stay there while
253
- * the next answer loads.
254
- *
255
- * @typeParam T - This is the shape of the stored documents, which flows through
256
- * to each hit's `document`.
257
- * @param indexName - This names the index to search.
258
- * @param params - These carry the text, the filters, the sort, and everything
259
- * else the search asks for.
260
- * @param options - These switch the hook off, keep the last answer on screen,
261
- * and set the refresh interval, the headers, and the deadline.
262
- * @returns The state holds the result, the failure, the loading flags, and the
263
- * way to search again.
329
+ * This hook searches an index, then searches it again whenever the parameters
330
+ * change and, under an engine, after each burst of writes to the index.
331
+ *
332
+ * Its parameters and its result match those of {@link SearchOperations.query}.
333
+ * Set `keepPreviousData` for a search-as-you-type box, so that the hits
334
+ * already on screen stay there while the next request is in flight.
335
+ *
336
+ * @typeParam T - This is the type of the stored documents, which also types the
337
+ * `document` field of each hit.
338
+ * @param indexName - This is the name of the index to search.
339
+ * @param params - These set the text, the filters, the sort, and every other
340
+ * part of the search.
341
+ * @param options - These settings can switch the hook off, keep the last answer
342
+ * on screen, and set the refresh interval, the headers, and the deadline.
343
+ * @returns The state holds the result, the failure, the two loading flags, and
344
+ * the `refresh` function.
264
345
  *
265
346
  * @public
266
347
  */
267
348
  declare function useQuery<T = AnyDocument>(indexName: string, params: QueryParams, options?: NarsilReadOptions): NarsilReadState<QueryResult<T>>;
268
349
  /**
269
- * Counts what a search would match, without building or ranking a single hit,
270
- * which is what a result count beside a filter reads.
350
+ * This hook counts the documents that a search matches without building or
351
+ * ranking a single hit, which suits a result count beside a filter. Under an
352
+ * engine, it counts again after each burst of writes to the index.
271
353
  *
272
- * @param indexName - This names the index to count in.
273
- * @param params - These are the parameters {@link useQuery} takes.
274
- * @param options - These switch the hook off, keep the last answer, and set the
275
- * refresh interval, the headers, and the deadline.
276
- * @returns The state holds the match count and how long the count took.
354
+ * @param indexName - This is the name of the index to count in.
355
+ * @param params - These have the same form as the parameters of
356
+ * {@link useQuery}.
357
+ * @param options - These settings can switch the hook off, keep the last count
358
+ * on screen, and set the refresh interval, the headers, and the deadline.
359
+ * @returns The state holds the match count and the time that the count took.
277
360
  *
278
361
  * @public
279
362
  */
280
363
  declare function usePreflight(indexName: string, params: QueryParams, options?: NarsilReadOptions): NarsilReadState<PreflightResult>;
281
364
  /**
282
- * Completes a prefix from the terms an index holds, ready to offer under a
283
- * search box.
284
- *
285
- * @param indexName - This names the index to complete from.
286
- * @param params - These set the prefix and how many completions come back.
287
- * @param options - These switch the hook off, keep the last completions on
288
- * screen, and set the refresh interval, the headers, and the deadline.
289
- * @returns The state holds the completions, most widely used first.
365
+ * This hook completes a prefix from the terms that an index holds, so that a
366
+ * search box can offer the completions as somebody types. Under an engine, it
367
+ * completes the prefix again after each burst of writes to the index.
368
+ *
369
+ * @param indexName - This is the name of the index whose terms complete the
370
+ * prefix.
371
+ * @param params - These set the prefix and the number of completions to
372
+ * return.
373
+ * @param options - These settings can switch the hook off, keep the last
374
+ * completions on screen, and set the refresh interval, the headers, and the
375
+ * deadline.
376
+ * @returns The state holds the completions, with the most widely used term
377
+ * first.
290
378
  *
291
379
  * @public
292
380
  */
293
381
  declare function useSuggest(indexName: string, params: SuggestParams, options?: NarsilReadOptions): NarsilReadState<SuggestResult>;
294
382
 
295
383
  /**
296
- * These settings say how a task hook follows the work.
384
+ * These settings control how often a task hook polls its task.
297
385
  *
298
386
  * @public
299
387
  */
300
388
  interface NarsilTaskOptions extends Omit<NarsilReadOptions, 'refreshIntervalMs'> {
301
- /** The hook asks again this often while the task runs, and every 250 ms
302
- * unless you say otherwise, which is how often a running import writes its
303
- * progress. It stops once the task reaches a final status. */
389
+ /** The hook polls the task at this interval in milliseconds while the task
390
+ * is in progress, which is 250 unless you set another value. That default
391
+ * matches the interval at which the server updates the figures of an import.
392
+ * The hook stops polling once the task reaches a final status. */
304
393
  pollIntervalMs?: number;
305
394
  }
306
395
  /**
307
- * Follows one long-running operation, and stops asking once it finishes.
308
- *
309
- * The hook polls while the task runs, pauses while the page is hidden, and
310
- * reads the figures once more as soon as the page comes back. A failed task
311
- * arrives as a record carrying its `error`, because a part-finished import
312
- * still reports what it indexed, so read the status you get.
313
- *
314
- * @param taskId - This names the task to follow, and a nullish or empty id
315
- * switches the hook off.
316
- * @param options - These set the poll interval, switch the hook off, and carry
317
- * the headers and the deadline.
318
- * @returns The state holds the record, and `data: null` says the server no
319
- * longer holds it.
396
+ * This hook polls one long-running task on a server until the task reaches a
397
+ * final status.
398
+ *
399
+ * The hook pauses polling while the page is hidden, then fetches the figures
400
+ * once more as soon as the page is visible again. A failed task comes back as
401
+ * a record with its `error` field set, because the record of a part-finished
402
+ * import still counts the documents that it indexed. Check the `status` field
403
+ * to tell the outcomes apart.
404
+ *
405
+ * @param taskId - This is the id of the task to poll, where a nullish or empty
406
+ * id switches the hook off.
407
+ * @param options - These settings can set the poll interval, switch the hook
408
+ * off, and set the headers and the deadline.
409
+ * @returns The state holds the record, while `data: null` means that the
410
+ * server no longer holds the task.
411
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render under a
412
+ * provider that holds an engine, because only a server handles tasks.
320
413
  *
321
414
  * @public
322
415
  */
323
416
  declare function useTask(taskId: string | null | undefined, options?: NarsilTaskOptions): NarsilReadState<TaskRecord | null>;
324
417
  /**
325
- * Lists the task records the server still holds, newest first.
418
+ * This hook lists the task records that the server holds, with the newest
419
+ * record first.
326
420
  *
327
- * Set `refreshIntervalMs` to keep a table of running work up to date.
421
+ * Set `refreshIntervalMs` to keep a table of the work in progress up to date.
328
422
  *
329
- * @param query - This says which records to keep and where the page starts.
330
- * Omit it for the newest 20 records.
331
- * @param options - These switch the hook off, keep the last page on screen, and
332
- * set the refresh interval, the headers, and the deadline.
333
- * @returns The state holds the records, the total the filters matched, and the
334
- * offset the next page starts at.
423
+ * @param query - This selects the records and sets where the page starts.
424
+ * Without it, the hook lists the newest 20 records.
425
+ * @param options - These settings can switch the hook off, keep the last page
426
+ * on screen, and set the refresh interval, the headers, and the deadline.
427
+ * @returns The state holds the records, the total that the filters matched,
428
+ * and the offset where the next page starts.
429
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render under a
430
+ * provider that holds an engine, because only a server handles tasks.
335
431
  *
336
432
  * @public
337
433
  */
338
434
  declare function useTasks(query?: TaskListQuery, options?: NarsilReadOptions): NarsilReadState<TaskListPage>;
339
435
 
340
- export { ImportResult, NarsilError, type NarsilImportOptions, type NarsilImportState, NarsilProvider, type NarsilProviderProps, type NarsilReadOptions, type NarsilReadState, type NarsilRequestSettings, type NarsilTaskOptions, TaskListPage, TaskListQuery, TaskProgress, TaskRecord, useDocument, useDocuments, useImport, useIndexes, useNarsilClient, usePreflight, useQuery, useStats, useSuggest, useTask, useTasks };
436
+ export { ImportResult, type NarsilClientProviderProps, type NarsilEngineProviderProps, NarsilError, type NarsilImportOptions, type NarsilImportState, NarsilProvider, type NarsilProviderProps, type NarsilProviderSettings, type NarsilReadOptions, type NarsilReadState, type NarsilRequestSettings, type NarsilTaskOptions, TaskListPage, TaskListQuery, TaskProgress, TaskRecord, useDocument, useDocuments, useImport, useIndexes, useNarsilClient, usePreflight, useQuery, useStats, useSuggest, useTask, useTasks };