@delali/narsil 0.2.2 → 0.2.3-next.32

package/dist/react.mjs

@@ -0,0 +1,687 @@
+import { createContext, useState, useEffect, createElement, useRef, useEffectEvent, useCallback, useMemo, useContext, useSyncExternalStore } from 'react';
+
+// src/errors.ts
+var ErrorCodes = {
+  SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE",
+  SCHEMA_MISSING_FIELD: "SCHEMA_MISSING_FIELD",
+  SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED",
+  SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION",
+  SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT",
+  DOC_NOT_FOUND: "DOC_NOT_FOUND",
+  DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS",
+  DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED",
+  INDEX_NOT_FOUND: "INDEX_NOT_FOUND",
+  INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS",
+  INDEX_ORPHANED: "INDEX_ORPHANED",
+  PARTITION_CORRUPTED: "PARTITION_CORRUPTED",
+  PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE",
+  WORKER_CRASHED: "WORKER_CRASHED",
+  WORKER_BUSY: "WORKER_BUSY",
+  WORKER_TIMEOUT: "WORKER_TIMEOUT",
+  PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED",
+  PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED",
+  PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED",
+  PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH",
+  PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT",
+  PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED",
+  SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD",
+  SEARCH_INVALID_VECTOR_SIZE: "SEARCH_INVALID_VECTOR_SIZE",
+  VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH",
+  SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER",
+  SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE",
+  SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR",
+  SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED",
+  LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED",
+  ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH",
+  ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC",
+  PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED",
+  EMBEDDING_FAILED: "EMBEDDING_FAILED",
+  EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH",
+  EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE",
+  EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID",
+  DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD",
+  CONFIG_INVALID: "CONFIG_INVALID",
+  QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED",
+  QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE",
+  QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT",
+  QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA",
+  CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED",
+  ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES",
+  ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG",
+  ALLOCATION_FAILED: "ALLOCATION_FAILED",
+  CONTROLLER_LEASE_LOST: "CONTROLLER_LEASE_LOST",
+  CONTROLLER_NOT_ACTIVE: "CONTROLLER_NOT_ACTIVE",
+  CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID",
+  NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED",
+  NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED",
+  NODE_NOT_JOINED: "NODE_NOT_JOINED",
+  COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING",
+  TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING",
+  REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID",
+  REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED",
+  REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED",
+  REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL",
+  REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT",
+  REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT",
+  REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH",
+  REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED",
+  PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY",
+  PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED",
+  INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS",
+  SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED",
+  SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID",
+  SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND",
+  SNAPSHOT_SYNC_TOO_LARGE: "SNAPSHOT_SYNC_TOO_LARGE",
+  SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED",
+  SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED",
+  SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED",
+  SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID",
+  SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID",
+  SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH",
+  SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER",
+  SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW",
+  SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED",
+  SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING",
+  SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING",
+  SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH",
+  SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR",
+  SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS",
+  SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED",
+  SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE",
+  SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED",
+  SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED",
+  SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT",
+  SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE",
+  SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED",
+  SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED"
+};
+var ServerErrorCodes = {
+  INVALID_REQUEST: "INVALID_REQUEST",
+  INVALID_JSON: "INVALID_JSON",
+  EMPTY_BODY: "EMPTY_BODY",
+  PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+  NOT_FOUND: "NOT_FOUND",
+  TASK_NOT_FOUND: "TASK_NOT_FOUND",
+  TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE",
+  TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE",
+  TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS",
+  HOOK_ERROR: "HOOK_ERROR",
+  INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+var ClientErrorCodes = {
+  CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED",
+  CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT",
+  CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED",
+  CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE",
+  CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT",
+  CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR"
+};
+var NarsilError = class extends Error {
+  /** This says which failure it is. */
+  code;
+  /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
+  details;
+  /**
+   * Builds an error carrying a code the caller can branch on.
+   *
+   * @param code - The failure this error reports, from {@link ErrorCodes} for
+   * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
+   * or {@link ClientErrorCodes} for one that stopped a request from reaching a
+   * server.
+   * @param message - Plain description, for a log or a person.
+   * @param details - Values behind the failure, which reach
+   * {@link NarsilError.details}.
+   */
+  constructor(code, message, details) {
+    super(message);
+    this.name = "NarsilError";
+    this.code = code;
+    this.details = details ?? {};
+  }
+};
+
+// src/react/failure.ts
+function asNarsilError(err, whatFailed) {
+  if (err instanceof NarsilError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new NarsilError(ClientErrorCodes.CLIENT_UNEXPECTED_ERROR, `${whatFailed} failed unexpectedly: ${message}`);
+}
+
+// src/react/store.ts
+var DEFAULT_KEEP_ALIVE_MS = 2e3;
+var LOADING_SNAPSHOT = Object.freeze({
+  data: void 0,
+  error: void 0,
+  isLoading: true,
+  isFetching: true
+});
+var IDLE_SNAPSHOT = Object.freeze({
+  data: void 0,
+  error: void 0,
+  isLoading: false,
+  isFetching: false
+});
+function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
+  const entries = /* @__PURE__ */ new Map();
+  let holders = 0;
+  let closing = null;
+  function publish(entry, next) {
+    entry.snapshot = next;
+    for (const listener of entry.listeners) listener();
+  }
+  function load(key, entry) {
+    if (entry.controller !== null) return;
+    const controller = new AbortController();
+    entry.controller = controller;
+    entry.version++;
+    const version = entry.version;
+    if (!entry.snapshot.isFetching) publish(entry, { ...entry.snapshot, isFetching: true });
+    const current = () => entries.get(key) === entry && entry.version === version;
+    entry.loader(controller.signal).then(
+      (data) => {
+        if (!current()) return;
+        entry.controller = null;
+        publish(entry, { data, error: void 0, isLoading: false, isFetching: false });
+      },
+      (err) => {
+        if (!current()) return;
+        entry.controller = null;
+        if (controller.signal.aborted) return;
+        publish(entry, {
+          data: entry.snapshot.data,
+          error: asNarsilError(err, "A Narsil hook"),
+          isLoading: false,
+          isFetching: false
+        });
+      }
+    );
+  }
+  function disposeAll() {
+    for (const [key, entry] of [...entries]) drop(key, entry);
+    entries.clear();
+  }
+  function drop(key, entry) {
+    if (entries.get(key) === entry) entries.delete(key);
+    if (entry.disposal !== null) clearTimeout(entry.disposal);
+    entry.disposal = null;
+    entry.controller?.abort();
+    entry.controller = null;
+  }
+  return {
+    subscribe(key, loader, onChange) {
+      let entry = entries.get(key);
+      if (entry === void 0) {
+        entry = {
+          snapshot: LOADING_SNAPSHOT,
+          listeners: /* @__PURE__ */ new Set(),
+          loader,
+          controller: null,
+          version: 0,
+          disposal: null
+        };
+        entries.set(key, entry);
+      } else {
+        entry.loader = loader;
+        if (entry.disposal !== null) {
+          clearTimeout(entry.disposal);
+          entry.disposal = null;
+        }
+      }
+      const held = entry;
+      held.listeners.add(onChange);
+      const retryable = held.snapshot.isLoading || held.snapshot.error !== void 0;
+      if (retryable && held.controller === null) load(key, held);
+      return () => {
+        held.listeners.delete(onChange);
+        if (held.listeners.size > 0 || entries.get(key) !== held || held.disposal !== null) return;
+        held.disposal = setTimeout(() => {
+          held.disposal = null;
+          if (held.listeners.size === 0) drop(key, held);
+        }, keepAliveMs);
+      };
+    },
+    snapshot(key) {
+      return entries.get(key)?.snapshot ?? LOADING_SNAPSHOT;
+    },
+    refresh(key) {
+      const entry = entries.get(key);
+      if (entry !== void 0) load(key, entry);
+    },
+    retain() {
+      holders++;
+      if (closing !== null) {
+        clearTimeout(closing);
+        closing = null;
+      }
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        holders--;
+        if (holders > 0) return;
+        closing = setTimeout(() => {
+          closing = null;
+          if (holders === 0) disposeAll();
+        }, keepAliveMs);
+      };
+    },
+    dispose: disposeAll
+  };
+}
+
+// src/react/context.ts
+var NarsilContext = createContext(null);
+function build(client, keepAliveMs) {
+  return { client, store: createResourceStore(keepAliveMs), keepAliveMs };
+}
+function NarsilProvider(props) {
+  const { client, keepAliveMs, children } = props;
+  const [value, setValue] = useState(() => build(client, keepAliveMs));
+  if (value.client !== client || value.keepAliveMs !== keepAliveMs) {
+    setValue(build(client, keepAliveMs));
+  }
+  useEffect(() => value.store.retain(), [value]);
+  return createElement(NarsilContext.Provider, { value }, children);
+}
+function useNarsilContext() {
+  const value = useContext(NarsilContext);
+  if (value === null) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      "A Narsil hook ran outside a NarsilProvider, so it found no client to send through"
+    );
+  }
+  return value;
+}
+function useNarsilClient() {
+  return useNarsilContext().client;
+}
+
+// src/react/key.ts
+var MAX_DEPTH = 32;
+function refuse(reason) {
+  return new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `A hook argument ${reason}, so the React bindings cannot tell one request from another`
+  );
+}
+function writeList(values, out, depth, seen) {
+  out.push("[");
+  for (let index = 0; index < values.length; index++) {
+    if (index > 0) out.push(",");
+    write(values[index], out, depth, seen);
+  }
+  out.push("]");
+}
+function writeObject(value, out, depth, seen) {
+  const record = value;
+  const keys = Object.keys(record).sort();
+  out.push("{");
+  let written = 0;
+  for (const key of keys) {
+    const held = record[key];
+    if (held === void 0) continue;
+    if (written > 0) out.push(",");
+    out.push(JSON.stringify(key), ":");
+    write(held, out, depth, seen);
+    written++;
+  }
+  out.push("}");
+}
+function write(value, out, depth, seen) {
+  if (value === null) {
+    out.push("null");
+    return;
+  }
+  switch (typeof value) {
+    case "undefined":
+      out.push("undefined");
+      return;
+    case "string":
+      out.push(JSON.stringify(value));
+      return;
+    case "number":
+    case "boolean":
+      out.push(String(value));
+      return;
+    case "bigint":
+      out.push(`${value}n`);
+      return;
+    case "function":
+    case "symbol":
+      throw refuse(`is a ${typeof value}, which carries no value a request depends on`);
+  }
+  if (depth >= MAX_DEPTH) throw refuse(`nests deeper than ${MAX_DEPTH} levels`);
+  const held = value;
+  if (seen.includes(held)) throw refuse("holds a reference back to itself");
+  seen.push(held);
+  const custom = held.toJSON;
+  if (typeof custom === "function") {
+    write(custom.call(held), out, depth + 1, seen);
+  } else if (Array.isArray(held)) {
+    writeList(held, out, depth + 1, seen);
+  } else if (ArrayBuffer.isView(held) && !(held instanceof DataView)) {
+    writeList(held, out, depth + 1, seen);
+  } else {
+    writeObject(held, out, depth + 1, seen);
+  }
+  seen.pop();
+}
+function hashKey(parts) {
+  const out = [];
+  writeList(parts, out, 0, []);
+  return out.join("");
+}
+
+// src/react/options.ts
+function requestOf(settings) {
+  return { headers: settings?.headers, timeoutMs: settings?.timeoutMs };
+}
+var watchers = /* @__PURE__ */ new Set();
+var listening = false;
+function isHidden() {
+  return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+function announce() {
+  for (const watcher of [...watchers]) watcher();
+}
+function watchVisibility(watcher) {
+  if (typeof document === "undefined") return () => void 0;
+  watchers.add(watcher);
+  if (!listening) {
+    listening = true;
+    document.addEventListener("visibilitychange", announce);
+  }
+  return () => {
+    watchers.delete(watcher);
+    if (watchers.size > 0) return;
+    listening = false;
+    document.removeEventListener("visibilitychange", announce);
+  };
+}
+function usePolling(action, intervalMs, active) {
+  const run = useEffectEvent(action);
+  useEffect(() => {
+    if (!active || intervalMs <= 0) return;
+    let timer;
+    const stop = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+    };
+    const tick = () => {
+      run();
+      timer = setTimeout(tick, intervalMs);
+    };
+    const start = () => {
+      stop();
+      timer = setTimeout(tick, intervalMs);
+    };
+    const onVisibilityChange = () => {
+      if (isHidden()) {
+        stop();
+        return;
+      }
+      run();
+      start();
+    };
+    if (!isHidden()) start();
+    const unwatch = watchVisibility(onVisibilityChange);
+    return () => {
+      stop();
+      unwatch();
+    };
+  }, [active, intervalMs]);
+}
+
+// src/react/read.ts
+var NO_SUBSCRIPTION = () => {
+};
+function useKey(parts) {
+  const cached = useRef(null);
+  const held = cached.current;
+  if (held !== null && held.parts.length === parts.length && parts.every((part, at) => Object.is(part, held.parts[at]))) {
+    return held.key;
+  }
+  const key = hashKey(parts);
+  cached.current = { parts, key };
+  return key;
+}
+function useRead(parts, run, options) {
+  const { client, store } = useNarsilContext();
+  const enabled = options?.enabled ?? true;
+  const headers = options?.headers;
+  const timeoutMs = options?.timeoutMs;
+  const key = useKey([...parts, headers, timeoutMs]);
+  const call = useRef({ run, request: requestOf(options) });
+  useEffect(() => {
+    call.current = { run, request: requestOf(options) };
+  });
+  const subscribe = useCallback(
+    (onChange) => {
+      if (!enabled) return NO_SUBSCRIPTION;
+      const loader = (signal) => {
+        const held = call.current;
+        return held.run(client, { ...held.request, signal });
+      };
+      return store.subscribe(key, loader, onChange);
+    },
+    [enabled, store, client, key]
+  );
+  const readSnapshot = useCallback(
+    () => enabled ? store.snapshot(key) : IDLE_SNAPSHOT,
+    [enabled, store, key]
+  );
+  const readServerSnapshot = useCallback(
+    () => enabled ? LOADING_SNAPSHOT : IDLE_SNAPSHOT,
+    [enabled]
+  );
+  const snapshot = useSyncExternalStore(subscribe, readSnapshot, readServerSnapshot);
+  const kept = useRef(void 0);
+  useEffect(() => {
+    if (snapshot.data !== void 0) kept.current = snapshot.data;
+  }, [snapshot.data]);
+  const refresh = useCallback(() => {
+    if (enabled) store.refresh(key);
+  }, [enabled, store, key]);
+  usePolling(refresh, options?.refreshIntervalMs ?? 0, enabled);
+  const keepPrevious = (options?.keepPreviousData ?? false) && snapshot.isLoading;
+  const data = keepPrevious && snapshot.data === void 0 ? kept.current : snapshot.data;
+  return useMemo(
+    () => ({
+      data,
+      error: snapshot.error,
+      isLoading: snapshot.isLoading && data === void 0,
+      isFetching: snapshot.isFetching,
+      refresh
+    }),
+    [data, snapshot, refresh]
+  );
+}
+
+// src/react/documents.ts
+function useDocument(indexName, docId, options) {
+  const id = docId ?? "";
+  const enabled = (options?.enabled ?? true) && id.length > 0;
+  return useRead(["get", indexName, id], (client, request) => client.get(indexName, id, request), {
+    ...options,
+    enabled
+  });
+}
+function useDocuments(indexName, params, options) {
+  return useRead(
+    ["listDocuments", indexName, params],
+    (client, request) => client.listDocuments(indexName, params, request),
+    options
+  );
+}
+
+// src/react/task-state.ts
+var DEFAULT_TASK_POLL_INTERVAL_MS = 250;
+var ERROR_RETRY_INTERVAL_MS = 5e3;
+function pollInterval(interval, failed) {
+  return failed ? Math.max(interval, ERROR_RETRY_INTERVAL_MS) : interval;
+}
+function isTerminalTask(record) {
+  if (record === null || record === void 0) return false;
+  return record.status === "succeeded" || record.status === "failed" || record.status === "cancelled";
+}
+
+// src/react/import.ts
+var NOTHING = { task: void 0, error: void 0, starting: false };
+function useImport(indexName, options) {
+  const client = useNarsilClient();
+  const [progress, setProgress] = useState(NOTHING);
+  const polling = useRef(null);
+  const sending = useRef(null);
+  const inFlight = useRef(false);
+  const reported = useRef(null);
+  const request = useRef(requestOf(options));
+  const settled = useEffectEvent((record) => options?.onSettled?.(record));
+  useEffect(() => {
+    request.current = requestOf(options);
+  });
+  useEffect(() => {
+    return () => {
+      polling.current?.abort();
+    };
+  }, []);
+  const finished = progress.task !== void 0 && isTerminalTask(progress.task);
+  useEffect(() => {
+    const record = progress.task;
+    if (record === void 0 || !finished || reported.current === record.id) return;
+    reported.current = record.id;
+    settled(record);
+  }, [progress.task, finished]);
+  const start = useCallback(
+    async (source) => {
+      const controller = new AbortController();
+      sending.current = controller;
+      setProgress({ task: void 0, error: void 0, starting: true });
+      try {
+        const record = await client.startImport(indexName, source, { ...request.current, signal: controller.signal });
+        setProgress({ task: record, error: void 0, starting: false });
+        return record;
+      } catch (err) {
+        const failure = asNarsilError(err, "The import");
+        const stopped = controller.signal.aborted;
+        setProgress({ task: void 0, error: stopped ? void 0 : failure, starting: false });
+        throw failure;
+      } finally {
+        if (sending.current === controller) sending.current = null;
+      }
+    },
+    [client, indexName]
+  );
+  const taskId = progress.task?.id;
+  const running = progress.task !== void 0 && !finished;
+  const readTask = () => {
+    if (taskId === void 0 || inFlight.current) return;
+    const controller = new AbortController();
+    polling.current = controller;
+    inFlight.current = true;
+    client.getTask(taskId, { ...request.current, signal: controller.signal }).then((next) => {
+      setProgress((prev) => {
+        if (prev.task?.id !== taskId) return prev;
+        if (next === null) {
+          return {
+            ...prev,
+            error: new NarsilError(
+              ServerErrorCodes.TASK_NOT_FOUND,
+              `The server no longer holds task "${taskId}", so the outcome of the load is unknown`,
+              { taskId }
+            )
+          };
+        }
+        return { task: next, error: void 0, starting: false };
+      });
+    }).catch((err) => {
+      if (controller.signal.aborted) return;
+      setProgress((prev) => prev.task?.id === taskId ? { ...prev, error: asNarsilError(err, "The import") } : prev);
+    }).finally(() => {
+      inFlight.current = false;
+    });
+  };
+  const cancel = useCallback(() => {
+    if (progress.starting) {
+      sending.current?.abort();
+      return;
+    }
+    if (taskId === void 0 || !running) return;
+    client.cancelTask(taskId, request.current).then((next) => {
+      setProgress((prev) => prev.task?.id === taskId ? { task: next, error: void 0, starting: false } : prev);
+    }).catch((err) => {
+      if (err instanceof NarsilError && err.code === ServerErrorCodes.TASK_NOT_CANCELLABLE) return;
+      setProgress((prev) => prev.task?.id === taskId ? { ...prev, error: asNarsilError(err, "The import") } : prev);
+    });
+  }, [client, taskId, running, progress.starting]);
+  const reset = useCallback(() => {
+    reported.current = null;
+    setProgress(NOTHING);
+  }, []);
+  const interval = pollInterval(options?.pollIntervalMs ?? DEFAULT_TASK_POLL_INTERVAL_MS, progress.error !== void 0);
+  usePolling(readTask, interval, running);
+  return useMemo(
+    () => ({
+      start,
+      cancel,
+      reset,
+      task: progress.task,
+      progress: progress.task?.progress,
+      result: progress.task?.result,
+      error: progress.error,
+      isImporting: progress.starting || running
+    }),
+    [start, cancel, reset, progress, running]
+  );
+}
+
+// src/react/indexes.ts
+function useIndexes(options) {
+  return useRead(["listIndexes"], (client, request) => client.listIndexes(request), options);
+}
+function useStats(indexName, options) {
+  return useRead(["getStats", indexName], (client, request) => client.getStats(indexName, request), options);
+}
+
+// src/react/search.ts
+function useQuery(indexName, params, options) {
+  return useRead(
+    ["query", indexName, params],
+    (client, request) => client.query(indexName, params, request),
+    options
+  );
+}
+function usePreflight(indexName, params, options) {
+  return useRead(
+    ["preflight", indexName, params],
+    (client, request) => client.preflight(indexName, params, request),
+    options
+  );
+}
+function useSuggest(indexName, params, options) {
+  return useRead(
+    ["suggest", indexName, params],
+    (client, request) => client.suggest(indexName, params, request),
+    options
+  );
+}
+
+// src/react/tasks.ts
+function useTask(taskId, options) {
+  const id = taskId ?? "";
+  const enabled = (options?.enabled ?? true) && id.length > 0;
+  const state = useRead(["getTask", id], (client, request) => client.getTask(id, request), {
+    ...options,
+    enabled,
+    refreshIntervalMs: 0
+  });
+  const running = state.data !== null && !isTerminalTask(state.data);
+  const interval = pollInterval(options?.pollIntervalMs ?? DEFAULT_TASK_POLL_INTERVAL_MS, state.error !== void 0);
+  usePolling(state.refresh, interval, enabled && running);
+  return state;
+}
+function useTasks(query, options) {
+  return useRead(["listTasks", query], (client, request) => client.listTasks(query, request), options);
+}
+
+export { ClientErrorCodes, ErrorCodes, NarsilError, NarsilProvider, ServerErrorCodes, useDocument, useDocuments, useImport, useIndexes, useNarsilClient, usePreflight, useQuery, useStats, useSuggest, useTask, useTasks };