@delali/narsil 0.2.2 → 0.2.3-next.32

package/dist/react.d.ts

@@ -0,0 +1,340 @@
+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, i as SuggestParams, j as SuggestResult } from './search-CQ-9bKxo.js';
+export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes } from './search-CQ-9bKxo.js';
+import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-CnMLpfk-.js';
+export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-CnMLpfk-.js';
+import { ReactNode, ReactElement } from 'react';
+import { N as NarsilClient, I as ImportSource } from './client-DQHB_swQ.js';
+import { A as AnyDocument } from './schema-emTQfEiX.js';
+import './adapters-79OIa4xm.js';
+
+/**
+ * These are the settings {@link NarsilProvider} takes.
+ *
+ * @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. */
+    keepAliveMs?: number;
+    /** These are the components the provider covers. */
+    children?: ReactNode;
+}
+/**
+ * Gives every hook below it the client to send through, and the shared state
+ * they read.
+ *
+ * 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.
+ *
+ * @param props - These name the client and the components the provider covers.
+ * @returns The provider renders its children unchanged.
+ *
+ * @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.
+ *
+ * @returns This is the client the provider was given.
+ * @throws A `NarsilError` with `CONFIG_INVALID` when no provider stands above
+ * the component.
+ *
+ * @public
+ */
+declare function useNarsilClient(): NarsilClient;
+
+/**
+ * What every hook sends with each request it makes.
+ *
+ * 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.
+ *
+ * @public
+ */
+interface NarsilRequestSettings {
+    /** 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. */
+    timeoutMs?: number;
+}
+/**
+ * These settings change what a read hook does, and every read hook takes them
+ * as its last argument.
+ *
+ * @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. */
+    enabled?: boolean;
+    /** The hook keeps showing the last answer while the next one loads, which
+     * holds a result list steady 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. */
+    refreshIntervalMs?: number;
+}
+/**
+ * What a read hook reports.
+ *
+ * `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.
+ *
+ * @typeParam T - This is what the underlying client method answers with.
+ *
+ * @public
+ */
+interface NarsilReadState<T> {
+    /** This is the answer, and it stays undefined until the first one arrives. */
+    data: T | undefined;
+    /** This is the failure the last request ended on, and the next success clears it. */
+    error: NarsilError | undefined;
+    /** This is true while the hook waits for an answer and has none to show. */
+    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. */
+    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.
+ *
+ * @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.
+ *
+ * @typeParam T - This is the shape of the stored documents.
+ * @param indexName - This names 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.
+ *
+ * @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.
+ *
+ * @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. */
+    pollIntervalMs?: number;
+    /** The hook calls this once the load reaches a final status, whichever status
+     * that is. */
+    onSettled?: (record: TaskRecord) => void;
+}
+/**
+ * What {@link useImport} reports, and what it offers to call.
+ *
+ * @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.
+     *
+     * @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.
+     */
+    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. */
+    cancel: () => void;
+    /** Clears the record and the failure, ready for another load. */
+    reset: () => void;
+    /** This is the task, from the moment the server takes the load on. */
+    task: TaskRecord | undefined;
+    /** This is how far the load has gone, which a progress bar reads. */
+    progress: TaskProgress | undefined;
+    /** This counts what the server accepted and refused, and it arrives once the
+     * load finishes. */
+    result: ImportResult | undefined;
+    /** This is the failure that stopped the load, or the one the last poll ended
+     * on. */
+    error: NarsilError | undefined;
+    /** This is true from the moment you call `start` until the load reaches a
+     * final status. */
+    isImporting: boolean;
+}
+/**
+ * Loads a corpus into an index and reports how far the load has gone.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare function useImport(indexName: string, options?: NarsilImportOptions): NarsilImportState;
+
+/**
+ * Lists every index the server holds, with its size and its language.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare function useIndexes(options?: NarsilReadOptions): NarsilReadState<IndexInfo[]>;
+/**
+ * Reads one index's document count, partition count, memory estimate, language,
+ * and schema.
+ *
+ * Set `refreshIntervalMs` to watch the figures move while a load runs.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare function useSuggest(indexName: string, params: SuggestParams, options?: NarsilReadOptions): NarsilReadState<SuggestResult>;
+
+/**
+ * These settings say how a task hook follows the work.
+ *
+ * @public
+ */
+interface NarsilTaskOptions extends NarsilReadOptions {
+    /** 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. */
+    pollIntervalMs?: number;
+}
+/**
+ * Follows one long-running operation, and stops asking once it finishes.
+ *
+ * The hook polls while the task is queued or running, 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.
+ *
+ * @public
+ */
+declare function useTask(taskId: string | null | undefined, options?: NarsilTaskOptions): NarsilReadState<TaskRecord | null>;
+/**
+ * Lists the task records the server still holds, newest first.
+ *
+ * Set `refreshIntervalMs` to keep a table of running work 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.
+ *
+ * @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 };