@delali/narsil 0.3.1-next.70 → 0.3.1-next.71

package/dist/react.d.ts

@@ -3,338 +3,433 @@ export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as Error
 import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-BZt_zes6.js';
 export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-BZt_zes6.js';
 import { ReactNode, ReactElement } from 'react';
+import { a as Narsil } from './engine-igk0aMpQ.js';
 import { N as NarsilClient, I as ImportSource } from './client-COek5GXK.js';
 import { A as AnyDocument } from './schema-Bgzr4g7b.js';
 import './adapters-79OIa4xm.js';
 
 /**
- * These are the settings {@link NarsilProvider} takes.
+ * These settings apply to {@link NarsilProvider} whether it holds a client or
+ * an engine.
  *
  * @public
  */
-interface NarsilProviderProps {
-    /** Every hook under the provider sends through this client. Build it once,
-     * outside the component tree, because a client built during a render would
-     * throw away everything the hooks under it hold. */
-    client: NarsilClient;
-    /** The hooks keep an answer for this many milliseconds after the last
-     * component reading it has gone, and 2000 unless you say otherwise. The wait
-     * covers the gap between React unmounting a component and mounting it again,
-     * so a quick navigation back shows what it showed before and sends no second
-     * request. */
+interface NarsilProviderSettings {
+    /** The provider keeps each answer for this many milliseconds after the last
+     * component that reads the answer unmounts, which is 2000 unless you set
+     * another value. That wait spans the gap between React unmounting a component
+     * and mounting it again, so a quick navigation back can show the earlier
+     * answer without sending a second request. */
     keepAliveMs?: number;
-    /** These are the components the provider covers. */
+    /** Under an engine, the hooks that read a written index search again once
+     * this many milliseconds pass without another write to that index, so each
+     * mounted hook searches once for a whole burst of writes. `useIndexes`
+     * searches again once that many milliseconds pass without a write to any
+     * index. The wait lasts 200 milliseconds unless you set another value. Under
+     * a client, the setting has no effect,
+     * because a server sends the client no write events. */
+    refreshAfterWriteMs?: number;
+    /** React renders these components under the provider. */
     children?: ReactNode;
 }
 /**
- * Gives every hook below it the client to send through, and the shared state
- * they read.
+ * These props give {@link NarsilProvider} a client, so that every hook under
+ * the provider sends its requests to a server.
  *
- * Two components asking for the same thing under one provider send one request
- * and read one answer. The provider drops that state once it unmounts, and it
- * stops whatever is still in flight.
+ * @public
+ */
+interface NarsilClientProviderProps extends NarsilProviderSettings {
+    /** Every hook under the provider sends its requests through this client.
+     * Build the client once, outside the component tree, because a render that
+     * builds a client builds a new one each time, so every hook under the
+     * provider starts again. */
+    client: NarsilClient;
+    /** Leave this unset, because a provider holds either a client or an engine. */
+    engine?: undefined;
+}
+/**
+ * These props give {@link NarsilProvider} an engine in the same page, so that
+ * every read hook under the provider calls that engine and searches again after
+ * each burst of writes to an index that the hook reads.
  *
- * @param props - These name the client and the components the provider covers.
- * @returns The provider renders its children unchanged.
+ * @public
+ */
+interface NarsilEngineProviderProps extends NarsilProviderSettings {
+    /** Every read hook under the provider calls this engine. Create the engine
+     * once, outside the component tree, because a render that creates an engine
+     * creates a new one each time, so every hook under the provider starts
+     * again. */
+    engine: Narsil;
+    /** Leave this unset, because a provider holds either a client or an engine. */
+    client?: undefined;
+}
+/**
+ * These are the props of {@link NarsilProvider}, which hold either a client of
+ * a server or an engine in the same page, together with the settings that both
+ * cases share.
+ *
+ * @public
+ */
+type NarsilProviderProps = NarsilClientProviderProps | NarsilEngineProviderProps;
+/**
+ * This component gives every hook under it the client or the engine to call,
+ * together with one store of answers that those hooks share.
+ *
+ * Every read hook calls the method of the same name on the client or on the
+ * engine. When two components under one provider ask for the same thing, they
+ * send one request and receive one answer. Under an engine, the provider
+ * registers a listener for the engine's `write` event, so every mounted hook
+ * that reads the written index searches again once per burst of writes. Once
+ * the provider unmounts and `keepAliveMs` passes, the provider drops the shared
+ * answers and stops waiting for the requests that are still in flight.
+ *
+ * @param props - These props set the client or the engine, the settings, and
+ * the components that render under the provider.
+ * @returns The element renders the children unchanged.
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render, when the
+ * props set both a client and an engine, or neither.
  *
  * @public
  */
 declare function NarsilProvider(props: NarsilProviderProps): ReactElement;
 /**
- * Reads the client the nearest {@link NarsilProvider} holds, which is what any
- * call the hooks leave out goes through.
+ * This hook returns the client that the nearest {@link NarsilProvider} holds,
+ * which serves every call that has no hook of its own, such as a write.
  *
- * @returns This is the client the provider was given.
- * @throws A `NarsilError` with `CONFIG_INVALID` when no provider stands above
- * the component.
+ * @returns This is the client that the provider holds.
+ * @throws A `NarsilError` with `CONFIG_INVALID` when no provider wraps the
+ * component, and also when the provider holds an engine, which the component
+ * can import directly.
  *
  * @public
  */
 declare function useNarsilClient(): NarsilClient;
 
 /**
- * What every hook sends with each request it makes.
+ * A hook sends these settings with each request that it makes through a
+ * client.
  *
- * A hook owns the lifetime of its own request, so it takes no signal. The store
- * behind it stops a request the moment nothing reads the answer.
+ * These settings include no signal, because each hook controls the lifetime of
+ * its own request. The provider stops waiting for a request once `keepAliveMs`
+ * passes with no component reading the answer. Under an engine, the hooks pass
+ * neither setting to the engine, because the engine computes its results in the
+ * same page.
  *
  * @public
  */
 interface NarsilRequestSettings {
-    /** The hook sends these headers with its request. */
+    /** Under a client, the hook sends these headers with its request. */
     headers?: Record<string, string>;
-    /** The hook gives the server this many milliseconds to answer, and 0 waits
-     * for as long as the server takes. */
+    /** Under a client, the hook gives the server this many milliseconds to
+     * respond, while 0 sets no deadline. */
     timeoutMs?: number;
 }
 /**
- * These settings change what a read hook does, and every read hook takes them
- * as its last argument.
+ * These settings, which form the last argument of every read hook, change what
+ * the hook does.
  *
  * @public
  */
 interface NarsilReadOptions extends NarsilRequestSettings {
-    /** The hook sends nothing while this is false, and it reports no data and no
-     * failure, which is how a search waits for a term. */
+    /** While this is false, the hook sends no request and reports neither data
+     * nor a failure, so keep it false until a search has a term. */
     enabled?: boolean;
-    /** The hook keeps showing the last answer while the next one loads, which
-     * holds a result list steady as somebody types. */
+    /** The hook keeps showing the last answer while the next request is in
+     * flight, which keeps a result list in place as somebody types. */
     keepPreviousData?: boolean;
-    /** The hook asks again this often, in milliseconds, and it pauses while the
-     * page is hidden. It asks once and stops unless you set this. */
+    /** The hook sends the request again at this interval in milliseconds,
+     * pausing while the page is hidden. Without this setting, the hook sends the
+     * request once, then again after each burst of writes when the provider holds
+     * an engine. */
     refreshIntervalMs?: number;
 }
 /**
- * What a read hook reports.
+ * These fields report where the request of a read hook stands.
  *
- * `isLoading` covers the wait for the first answer, so a spinner branches on
- * it, while `isFetching` covers every request including a refresh, so a quieter
- * indicator branches on that one.
+ * `isLoading` covers the wait for the first answer, so show a spinner while it
+ * is true. `isFetching` covers every request, including a refresh, so show a
+ * quieter indicator while that one is true.
  *
- * @typeParam T - This is what the underlying client method answers with.
+ * @typeParam T - This is the type that the method behind the hook returns.
  *
  * @public
  */
 interface NarsilReadState<T> {
-    /** This is the answer, and it stays undefined until the first one arrives. */
+    /** This is the answer, which stays undefined until the first request
+     * succeeds. */
     data: T | undefined;
-    /** This is the failure the last request ended on, and the next success clears it. */
+    /** This is the failure that ended the last request, until the next success
+     * clears it. */
     error: NarsilError | undefined;
-    /** This is true while the hook waits for an answer and has none to show. */
+    /** This is true while the hook has no answer to show and a request is in
+     * flight. */
     isLoading: boolean;
     /** This is true while a request is in flight, including a refresh. */
     isFetching: boolean;
-    /** Calling this asks the server again, keeping the answer already on screen
-     * until the new one arrives. */
+    /** Calling this sends the request again, while the answer already on screen
+     * stays until the new answer replaces it. */
     refresh: () => void;
 }
 
 /**
- * Reads one stored document, and reads it again whenever the id changes.
- *
- * A document the index does not hold comes back as `data: undefined` with no
- * failure, so read `isLoading` to tell an empty answer from one still on its
- * way. Passing no id switches the hook off, which is what a detail panel does
- * until somebody picks a row.
- *
- * @param indexName - This names the index holding the document.
- * @param docId - This names the document to read, and a nullish or empty id
- * switches the hook off.
- * @param options - These switch the hook off, keep the last document on screen,
- * and set the refresh interval, the headers, and the deadline.
- * @returns The state holds the document, the failure, the loading flags, and
- * the way to read it again.
+ * This hook fetches one stored document, then fetches it again whenever the id
+ * changes and, under an engine, after each burst of writes to the index.
+ *
+ * For a document that the index does not hold, the hook reports
+ * `data: undefined` with no failure, so check `isLoading` to tell an empty
+ * answer from one that is still in flight. A missing id switches the hook off,
+ * which suits a detail panel until somebody picks a row.
+ *
+ * @param indexName - This is the name of the index that holds the document.
+ * @param docId - This is the id of the document to fetch, where a nullish or
+ * empty id switches the hook off.
+ * @param options - These settings can switch the hook off, keep the last
+ * document on screen, and set the refresh interval, the headers, and the
+ * deadline.
+ * @returns The state holds the document, the failure, the two loading flags,
+ * and the `refresh` function.
  *
  * @public
  */
 declare function useDocument(indexName: string, docId: string | null | undefined, options?: NarsilReadOptions): NarsilReadState<AnyDocument | undefined>;
 /**
- * Pages through the stored documents without searching, which is what a table
- * of everything an index holds reads.
+ * This hook pages through the stored documents of an index without searching,
+ * which suits a table of everything that the index holds. Under an engine, the
+ * hook fetches the page again after each burst of writes to the index.
  *
- * @typeParam T - This is the shape of the stored documents.
- * @param indexName - This names the index to page through.
+ * @typeParam T - This is the type of the stored documents.
+ * @param indexName - This is the name of the index to page through.
  * @param params - These set the page size, the cursor, and any filter, sort, or
  * projection.
- * @param options - These switch the hook off, keep the last page on screen, and
- * set the refresh interval, the headers, and the deadline.
- * @returns The state holds the page and the cursor that reaches the next one.
+ * @param options - These settings can switch the hook off, keep the last page
+ * on screen, and set the refresh interval, the headers, and the deadline.
+ * @returns The state holds the page and the cursor for the next page.
  *
  * @public
  */
 declare function useDocuments<T = AnyDocument>(indexName: string, params?: ListParams, options?: NarsilReadOptions): NarsilReadState<ListResult<T>>;
 
 /**
- * These settings say how {@link useImport} runs a load and follows it.
+ * These settings control how {@link useImport} starts a load and polls its
+ * progress.
  *
  * @public
  */
 interface NarsilImportOptions extends NarsilRequestSettings {
-    /** The hook asks the server how far the load has gone this often, and every
-     * 250 ms unless you say otherwise, which is how often the server writes the
-     * figures. It leaves five seconds between attempts while the server is
-     * failing. */
+    /** The hook asks the server for the progress of the load at this interval in
+     * milliseconds, which is 250 unless you set another value. That default
+     * matches the interval at which the server updates the figures. While the
+     * server is failing, the hook waits five seconds between attempts. */
     pollIntervalMs?: number;
-    /** The hook calls this once the load reaches a final status, whichever status
-     * that is. */
+    /** The hook calls this function once the load reaches a final status,
+     * whatever that status is. */
     onSettled?: (record: TaskRecord) => void;
 }
 /**
- * What {@link useImport} reports, and what it offers to call.
+ * These fields report where a load from {@link useImport} stands, together with
+ * the functions that control the load.
  *
  * @public
  */
 interface NarsilImportState {
     /**
-     * Sends a corpus and returns once the server has read the body and taken the
-     * work on. The server loads the documents afterwards, and this hook follows
-     * that work.
+     * This function sends a corpus, then returns once the server has received the
+     * body and started the task. The server loads the documents after that, while
+     * the hook polls the task.
      *
-     * @param source - These are the documents, or the NDJSON you already hold.
-     * @returns The record is the task the server started.
-     * @throws A `NarsilError` under the code the server sent, and with
-     * `NOT_FOUND` where the server predates the asynchronous import.
+     * @param source - These are the documents, or the NDJSON text that you
+     * already hold.
+     * @returns This is the record of the task that the server started.
+     * @throws A `NarsilError` under the code that the server sent, or with
+     * `NOT_FOUND` when the server is older than the asynchronous import.
      */
     start: (source: ImportSource) => Promise<TaskRecord>;
-    /** Asks the running load to stop. Calling it while the corpus is still going
-     * up stops the upload, and calling it afterwards asks the server to stop the
-     * task, which stops between batches, so whatever it had already written stays
-     * written. */
+    /** This function asks the load in progress to stop. While the browser is
+     * still sending the corpus, a call aborts the upload; after that, a call asks
+     * the server to stop the task. The server stops between batches, so the
+     * documents that it has already written stay in the index. */
     cancel: () => void;
-    /** Clears the record and the failure, ready for another load. */
+    /** This function clears the record and the failure, so that the hook is
+     * ready for another load. */
     reset: () => void;
-    /** This is the task, from the moment the server takes the load on. */
+    /** This is the record of the task, from the moment that the server starts
+     * it. */
     task: TaskRecord | undefined;
-    /** This is how far the load has gone, which a progress bar reads. */
+    /** This is the progress of the load, which suits a progress bar. */
     progress: TaskProgress | undefined;
-    /** This counts what the server accepted and refused, and it arrives once the
-     * load finishes. */
+    /** This counts the documents that the server indexed and refused, which the
+     * hook sets once the load finishes. */
     result: ImportResult | undefined;
-    /** This is the failure that stopped the load, or the one the last poll ended
-     * on. */
+    /** This is the failure that stopped the load, or the failure that ended the
+     * last poll. */
     error: NarsilError | undefined;
-    /** This is true from the moment you call `start` until the load reaches a
-     * final status. */
+    /** This is true from the call to `start` until the load reaches a final
+     * status. */
     isImporting: boolean;
 }
 /**
- * Loads a corpus into an index and reports how far the load has gone.
+ * This hook loads a corpus into an index on a server and reports the progress
+ * of the load.
  *
  * The hook starts the load as a task, so the request returns as soon as the
- * server has read the body. A corpus that would outlast a proxy's response
- * timeout therefore still loads. The hook then polls the task, pausing while
- * the page is hidden, until the load succeeds, fails, or is cancelled.
+ * server has received the body. A corpus can therefore load even when the load
+ * takes longer than the response timeout of a proxy. The hook then polls the
+ * task until the load succeeds, fails, or ends in a cancellation, pausing
+ * whenever the page is hidden.
  *
  * Unmounting the component stops the polling alone, because the server finishes
- * the load either way. Follow it again with {@link useTask}, under the id of the
- * record `start` returned.
+ * the load either way. Follow the load again with {@link useTask}, under the id
+ * of the record that `start` returns.
  *
- * @param indexName - This names the index that receives the corpus.
- * @param options - These set the poll interval, the callback for the final
- * record, the headers, and the deadline.
- * @returns The state holds the task, the progress, the result, the failure, and
- * the three methods that drive a load.
+ * @param indexName - This is the name of the index that receives the corpus.
+ * @param options - These settings can set the poll interval, the callback for
+ * the final record, the headers, and the deadline.
+ * @returns The state holds the task, the progress, the result, the failure,
+ * and the three functions that control a load.
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render under a
+ * provider that holds an engine, because only a server handles imports.
  *
  * @public
  */
 declare function useImport(indexName: string, options?: NarsilImportOptions): NarsilImportState;
 
 /**
- * Lists every index the server holds, with its size and its language.
+ * This hook lists every index that the server or the engine holds, with the
+ * size and the language of each one. Under an engine, the hook fetches the list
+ * again after each burst of writes to any index.
  *
- * @param options - These switch the hook off, keep the last list on screen, and
- * set the refresh interval, the headers, and the deadline.
- * @returns The state holds the indexes in creation order.
+ * @param options - These settings can switch the hook off, keep the last list
+ * on screen, and set the refresh interval, the headers, and the deadline.
+ * @returns The state holds the indexes in the order of their creation.
  *
  * @public
  */
 declare function useIndexes(options?: NarsilReadOptions): NarsilReadState<IndexInfo[]>;
 /**
- * Reads one index's document count, partition count, memory estimate, language,
- * and schema.
+ * This hook fetches the document count, the partition count, the memory
+ * estimate, the language, and the schema of one index.
  *
- * Set `refreshIntervalMs` to watch the figures move while a load runs.
+ * Set `refreshIntervalMs` to watch the figures change while a load is in
+ * progress. Under an engine, the hook fetches the figures again after each
+ * burst of writes to the index.
  *
- * @param indexName - This names the index to describe.
- * @param options - These switch the hook off, keep the last figures on screen,
- * and set the refresh interval, the headers, and the deadline.
- * @returns The state holds the figures as they stood when the server answered.
+ * @param indexName - This is the name of the index to describe.
+ * @param options - These settings can switch the hook off, keep the last
+ * figures on screen, and set the refresh interval, the headers, and the
+ * deadline.
+ * @returns The state holds the figures as they stood when the server or the
+ * engine returned them.
  *
  * @public
  */
 declare function useStats(indexName: string, options?: NarsilReadOptions): NarsilReadState<IndexStats>;
 
 /**
- * Searches an index and re-runs the search whenever the parameters change.
- *
- * The parameters are the ones {@link SearchOperations.query} takes, and the
- * answer is the same `QueryResult`. Set `keepPreviousData` for a
- * search-as-you-type box, so that the hits already on screen stay there while
- * the next answer loads.
- *
- * @typeParam T - This is the shape of the stored documents, which flows through
- * to each hit's `document`.
- * @param indexName - This names the index to search.
- * @param params - These carry the text, the filters, the sort, and everything
- * else the search asks for.
- * @param options - These switch the hook off, keep the last answer on screen,
- * and set the refresh interval, the headers, and the deadline.
- * @returns The state holds the result, the failure, the loading flags, and the
- * way to search again.
+ * This hook searches an index, then searches it again whenever the parameters
+ * change and, under an engine, after each burst of writes to the index.
+ *
+ * Its parameters and its result match those of {@link SearchOperations.query}.
+ * Set `keepPreviousData` for a search-as-you-type box, so that the hits
+ * already on screen stay there while the next request is in flight.
+ *
+ * @typeParam T - This is the type of the stored documents, which also types the
+ * `document` field of each hit.
+ * @param indexName - This is the name of the index to search.
+ * @param params - These set the text, the filters, the sort, and every other
+ * part of the search.
+ * @param options - These settings can switch the hook off, keep the last answer
+ * on screen, and set the refresh interval, the headers, and the deadline.
+ * @returns The state holds the result, the failure, the two loading flags, and
+ * the `refresh` function.
  *
  * @public
  */
 declare function useQuery<T = AnyDocument>(indexName: string, params: QueryParams, options?: NarsilReadOptions): NarsilReadState<QueryResult<T>>;
 /**
- * Counts what a search would match, without building or ranking a single hit,
- * which is what a result count beside a filter reads.
+ * This hook counts the documents that a search matches without building or
+ * ranking a single hit, which suits a result count beside a filter. Under an
+ * engine, it counts again after each burst of writes to the index.
  *
- * @param indexName - This names the index to count in.
- * @param params - These are the parameters {@link useQuery} takes.
- * @param options - These switch the hook off, keep the last answer, and set the
- * refresh interval, the headers, and the deadline.
- * @returns The state holds the match count and how long the count took.
+ * @param indexName - This is the name of the index to count in.
+ * @param params - These have the same form as the parameters of
+ * {@link useQuery}.
+ * @param options - These settings can switch the hook off, keep the last count
+ * on screen, and set the refresh interval, the headers, and the deadline.
+ * @returns The state holds the match count and the time that the count took.
  *
  * @public
  */
 declare function usePreflight(indexName: string, params: QueryParams, options?: NarsilReadOptions): NarsilReadState<PreflightResult>;
 /**
- * Completes a prefix from the terms an index holds, ready to offer under a
- * search box.
- *
- * @param indexName - This names the index to complete from.
- * @param params - These set the prefix and how many completions come back.
- * @param options - These switch the hook off, keep the last completions on
- * screen, and set the refresh interval, the headers, and the deadline.
- * @returns The state holds the completions, most widely used first.
+ * This hook completes a prefix from the terms that an index holds, so that a
+ * search box can offer the completions as somebody types. Under an engine, it
+ * completes the prefix again after each burst of writes to the index.
+ *
+ * @param indexName - This is the name of the index whose terms complete the
+ * prefix.
+ * @param params - These set the prefix and the number of completions to
+ * return.
+ * @param options - These settings can switch the hook off, keep the last
+ * completions on screen, and set the refresh interval, the headers, and the
+ * deadline.
+ * @returns The state holds the completions, with the most widely used term
+ * first.
  *
  * @public
  */
 declare function useSuggest(indexName: string, params: SuggestParams, options?: NarsilReadOptions): NarsilReadState<SuggestResult>;
 
 /**
- * These settings say how a task hook follows the work.
+ * These settings control how often a task hook polls its task.
  *
  * @public
  */
 interface NarsilTaskOptions extends Omit<NarsilReadOptions, 'refreshIntervalMs'> {
-    /** The hook asks again this often while the task runs, and every 250 ms
-     * unless you say otherwise, which is how often a running import writes its
-     * progress. It stops once the task reaches a final status. */
+    /** The hook polls the task at this interval in milliseconds while the task
+     * is in progress, which is 250 unless you set another value. That default
+     * matches the interval at which the server updates the figures of an import.
+     * The hook stops polling once the task reaches a final status. */
     pollIntervalMs?: number;
 }
 /**
- * Follows one long-running operation, and stops asking once it finishes.
- *
- * The hook polls while the task runs, pauses while the page is hidden, and
- * reads the figures once more as soon as the page comes back. A failed task
- * arrives as a record carrying its `error`, because a part-finished import
- * still reports what it indexed, so read the status you get.
- *
- * @param taskId - This names the task to follow, and a nullish or empty id
- * switches the hook off.
- * @param options - These set the poll interval, switch the hook off, and carry
- * the headers and the deadline.
- * @returns The state holds the record, and `data: null` says the server no
- * longer holds it.
+ * This hook polls one long-running task on a server until the task reaches a
+ * final status.
+ *
+ * The hook pauses polling while the page is hidden, then fetches the figures
+ * once more as soon as the page is visible again. A failed task comes back as
+ * a record with its `error` field set, because the record of a part-finished
+ * import still counts the documents that it indexed. Check the `status` field
+ * to tell the outcomes apart.
+ *
+ * @param taskId - This is the id of the task to poll, where a nullish or empty
+ * id switches the hook off.
+ * @param options - These settings can set the poll interval, switch the hook
+ * off, and set the headers and the deadline.
+ * @returns The state holds the record, while `data: null` means that the
+ * server no longer holds the task.
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render under a
+ * provider that holds an engine, because only a server handles tasks.
  *
  * @public
  */
 declare function useTask(taskId: string | null | undefined, options?: NarsilTaskOptions): NarsilReadState<TaskRecord | null>;
 /**
- * Lists the task records the server still holds, newest first.
+ * This hook lists the task records that the server holds, with the newest
+ * record first.
  *
- * Set `refreshIntervalMs` to keep a table of running work up to date.
+ * Set `refreshIntervalMs` to keep a table of the work in progress up to date.
  *
- * @param query - This says which records to keep and where the page starts.
- * Omit it for the newest 20 records.
- * @param options - These switch the hook off, keep the last page on screen, and
- * set the refresh interval, the headers, and the deadline.
- * @returns The state holds the records, the total the filters matched, and the
- * offset the next page starts at.
+ * @param query - This selects the records and sets where the page starts.
+ * Without it, the hook lists the newest 20 records.
+ * @param options - These settings can switch the hook off, keep the last page
+ * on screen, and set the refresh interval, the headers, and the deadline.
+ * @returns The state holds the records, the total that the filters matched,
+ * and the offset where the next page starts.
+ * @throws A `NarsilError` with `CONFIG_INVALID` during the render under a
+ * provider that holds an engine, because only a server handles tasks.
  *
  * @public
  */
 declare function useTasks(query?: TaskListQuery, options?: NarsilReadOptions): NarsilReadState<TaskListPage>;
 
-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 };
+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 };