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

package/dist/react.mjs

@@ -1,4 +1,4 @@
-import { createContext, useState, useEffect, createElement, useRef, useEffectEvent, useCallback, useMemo, useContext, useSyncExternalStore } from 'react';
+import { createContext, useState, createElement, useRef, useEffectEvent, useEffect, useCallback, useMemo, useContext, useSyncExternalStore } from 'react';
 
 // src/errors.ts
 var NARSIL_ERROR_MARKER = /* @__PURE__ */ Symbol.for("@delali/narsil.NarsilError");
@@ -147,8 +147,53 @@ function isNarsilError(value) {
   return typeof value === "object" && value !== null && NARSIL_ERROR_MARKER in value;
 }
 
+// src/react/reader.ts
+function plainNumbersIn(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (ArrayBuffer.isView(value)) {
+    return value instanceof DataView ? value : Array.from(value);
+  }
+  if (Array.isArray(value)) {
+    let copy2 = null;
+    for (let at = 0; at < value.length; at++) {
+      const converted = plainNumbersIn(value[at]);
+      if (converted === value[at]) continue;
+      copy2 ??= value.slice();
+      copy2[at] = converted;
+    }
+    return copy2 ?? value;
+  }
+  let copy = null;
+  for (const [key, held] of Object.entries(value)) {
+    const converted = plainNumbersIn(held);
+    if (converted === held) continue;
+    copy ??= { ...value };
+    copy[key] = converted;
+  }
+  return copy ?? value;
+}
+function withPlainNumbers(answer) {
+  return answer.then((value) => plainNumbersIn(value));
+}
+function engineReader(engine) {
+  return {
+    query(indexName, params) {
+      return withPlainNumbers(engine.query(indexName, params));
+    },
+    preflight: (indexName, params) => engine.preflight(indexName, params),
+    suggest: (indexName, params) => engine.suggest(indexName, params),
+    get: (indexName, docId) => withPlainNumbers(engine.get(indexName, docId)),
+    listDocuments(indexName, params) {
+      return withPlainNumbers(engine.listDocuments(indexName, params));
+    },
+    listIndexes: async () => engine.listIndexes(),
+    getStats: async (indexName) => engine.getStats(indexName)
+  };
+}
+
 // src/react/constants.ts
 var DEFAULT_KEEP_ALIVE_MS = 2e3;
+var DEFAULT_REFRESH_AFTER_WRITE_MS = 200;
 var DEFAULT_TASK_POLL_INTERVAL_MS = 250;
 var ERROR_RETRY_INTERVAL_MS = 5e3;
 var MAX_QUERY_KEY_DEPTH = 32;
@@ -173,10 +218,13 @@ var IDLE_SNAPSHOT = Object.freeze({
   isLoading: false,
   isFetching: false
 });
-function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
+var ANY_INDEX = /* @__PURE__ */ Symbol("any index");
+var NO_INDEX = /* @__PURE__ */ Symbol("no index");
+function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS, refreshAfterWriteMs = DEFAULT_REFRESH_AFTER_WRITE_MS) {
   const entries = /* @__PURE__ */ new Map();
   let holders = 0;
   let closing = null;
+  const staleRefreshes = /* @__PURE__ */ new Map();
   function publish(entry, next) {
     entry.snapshot = next;
     for (const listener of entry.listeners) listener();
@@ -185,6 +233,7 @@ function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
     if (entry.controller !== null) return;
     const controller = new AbortController();
     entry.controller = controller;
+    entry.stale = false;
     entry.version++;
     const version = entry.version;
     if (!entry.snapshot.isFetching) publish(entry, { ...entry.snapshot, isFetching: true });
@@ -209,9 +258,32 @@ function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
     );
   }
   function disposeAll() {
+    for (const timer of staleRefreshes.values()) clearTimeout(timer);
+    staleRefreshes.clear();
     for (const [key, entry] of [...entries]) drop(key, entry);
     entries.clear();
   }
+  function refreshStale(scope) {
+    staleRefreshes.delete(scope);
+    for (const [key, entry] of entries) {
+      if (entry.writeScope === scope && entry.stale && entry.listeners.size > 0) load(key, entry);
+    }
+  }
+  function scheduleRefresh(scope) {
+    const pending = staleRefreshes.get(scope);
+    if (pending !== void 0) clearTimeout(pending);
+    staleRefreshes.set(
+      scope,
+      setTimeout(() => refreshStale(scope), refreshAfterWriteMs)
+    );
+  }
+  function markStale(entry) {
+    entry.stale = true;
+    if (entry.controller === null) return;
+    entry.controller.abort();
+    entry.controller = null;
+    entry.version++;
+  }
   function drop(key, entry) {
     if (entries.get(key) === entry) entries.delete(key);
     if (entry.disposal !== null) clearTimeout(entry.disposal);
@@ -220,7 +292,7 @@ function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
     entry.controller = null;
   }
   return {
-    subscribe(key, loader, onChange) {
+    subscribe(key, loader, onChange, writeScope) {
       let entry = entries.get(key);
       if (entry === void 0) {
         entry = {
@@ -229,7 +301,9 @@ function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
           loader,
           controller: null,
           version: 0,
-          disposal: null
+          disposal: null,
+          writeScope,
+          stale: false
         };
         entries.set(key, entry);
       } else {
@@ -241,7 +315,7 @@ function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
       }
       const held = entry;
       held.listeners.add(onChange);
-      const retryable = held.snapshot.isLoading || held.snapshot.error !== void 0;
+      const retryable = held.stale || held.snapshot.isLoading || held.snapshot.error !== void 0;
       if (retryable && held.controller === null) load(key, held);
       return () => {
         held.listeners.delete(onChange);
@@ -259,6 +333,15 @@ function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
       const entry = entries.get(key);
       if (entry !== void 0) load(key, entry);
     },
+    invalidate(indexName) {
+      const marked = /* @__PURE__ */ new Set();
+      for (const entry of entries.values()) {
+        if (entry.writeScope !== ANY_INDEX && entry.writeScope !== indexName) continue;
+        markStale(entry);
+        marked.add(entry.writeScope);
+      }
+      for (const scope of marked) scheduleRefresh(scope);
+    },
     retain() {
       holders++;
       if (closing !== null) {
@@ -283,30 +366,72 @@ function createResourceStore(keepAliveMs = DEFAULT_KEEP_ALIVE_MS) {
 
 // src/react/context.ts
 var NarsilContext = createContext(null);
-function build(client, keepAliveMs) {
-  return { client, store: createResourceStore(keepAliveMs), keepAliveMs };
+function buildContextValue(props) {
+  const { client, engine, keepAliveMs, refreshAfterWriteMs } = props;
+  const shared = { store: createResourceStore(keepAliveMs, refreshAfterWriteMs), keepAliveMs, refreshAfterWriteMs };
+  if (client !== void 0 && engine === void 0) return { ...shared, reader: client, client, engine: null };
+  if (engine !== void 0 && client === void 0) {
+    return { ...shared, reader: engineReader(engine), client: null, engine };
+  }
+  throw new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    "A NarsilProvider requires exactly one of client and engine, but its props set both or neither"
+  );
+}
+function providerPropsChanged(value, props) {
+  return value.client !== (props.client ?? null) || value.engine !== (props.engine ?? null) || value.keepAliveMs !== props.keepAliveMs || value.refreshAfterWriteMs !== props.refreshAfterWriteMs;
+}
+function useStoreRetention(store) {
+  useEffect(() => store.retain(), [store]);
+}
+function useRefreshAfterWrites(engine, store) {
+  useEffect(() => {
+    if (engine === null) return;
+    const onWrite = (payload) => {
+      store.invalidate(payload.indexName);
+    };
+    engine.on("write", onWrite);
+    return () => {
+      engine.off("write", onWrite);
+    };
+  }, [engine, store]);
 }
 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));
+  const [value, setValue] = useState(() => buildContextValue(props));
+  if (providerPropsChanged(value, props)) {
+    setValue(buildContextValue(props));
   }
-  useEffect(() => value.store.retain(), [value]);
-  return createElement(NarsilContext.Provider, { value }, children);
+  useStoreRetention(value.store);
+  useRefreshAfterWrites(value.engine, value.store);
+  return createElement(NarsilContext.Provider, { value }, props.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"
+      "A Narsil hook was called outside a NarsilProvider, so no client or engine is available to it"
     );
   }
   return value;
 }
+function useServerClient(hookName) {
+  const { client } = useNarsilContext();
+  if (client !== null) return client;
+  throw new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `${hookName} works only under a client of a server, because only a server handles tasks and imports, while the NarsilProvider above it holds an engine`,
+    { hook: hookName }
+  );
+}
 function useNarsilClient() {
-  return useNarsilContext().client;
+  const { client } = useNarsilContext();
+  if (client !== null) return client;
+  throw new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    "useNarsilClient returns a client, while the NarsilProvider above it holds an engine, so import that engine directly",
+    { hook: "useNarsilClient" }
+  );
 }
 
 // src/react/key.ts
@@ -457,8 +582,8 @@ function useKey(parts) {
   cached.current = { parts, key };
   return key;
 }
-function useRead(parts, run, options) {
-  const { client, store } = useNarsilContext();
+function useRead(source, parts, run, options, writeScope) {
+  const { store } = useNarsilContext();
   const enabled = options?.enabled ?? true;
   const headers = options?.headers;
   const timeoutMs = options?.timeoutMs;
@@ -472,11 +597,11 @@ function useRead(parts, run, options) {
       if (!enabled) return NO_SUBSCRIPTION;
       const loader = (signal) => {
         const held = call.current;
-        return held.run(client, { ...held.request, signal });
+        return held.run(source, { ...held.request, signal });
       };
-      return store.subscribe(key, loader, onChange);
+      return store.subscribe(key, loader, onChange, writeScope);
     },
-    [enabled, store, client, key]
+    [enabled, store, source, key, writeScope]
   );
   const readSnapshot = useCallback(
     () => enabled ? store.snapshot(key) : IDLE_SNAPSHOT,
@@ -508,21 +633,28 @@ function useRead(parts, run, options) {
     [data, snapshot, refresh]
   );
 }
+function useProviderRead(parts, run, options, writeScope) {
+  const { reader } = useNarsilContext();
+  return useRead(reader, parts, run, options, writeScope);
+}
 
 // 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
-  });
+  return useProviderRead(
+    ["get", indexName, id],
+    (reader, request) => reader.get(indexName, id, request),
+    { ...options, enabled },
+    indexName
+  );
 }
 function useDocuments(indexName, params, options) {
-  return useRead(
+  return useProviderRead(
     ["listDocuments", indexName, params],
-    (client, request) => client.listDocuments(indexName, params, request),
-    options
+    (reader, request) => reader.listDocuments(indexName, params, request),
+    options,
+    indexName
   );
 }
 
@@ -544,7 +676,7 @@ function isTerminalTask(record) {
 // src/react/import.ts
 var NOTHING = { task: void 0, error: void 0, starting: false };
 function useImport(indexName, options) {
-  const client = useNarsilClient();
+  const client = useServerClient("useImport");
   const [progress, setProgress] = useState(NOTHING);
   const polling = useRef(null);
   const sending = useRef(null);
@@ -652,51 +784,63 @@ function useImport(indexName, options) {
 
 // src/react/indexes.ts
 function useIndexes(options) {
-  return useRead(["listIndexes"], (client, request) => client.listIndexes(request), options);
+  return useProviderRead(["listIndexes"], (reader, request) => reader.listIndexes(request), options, ANY_INDEX);
 }
 function useStats(indexName, options) {
-  return useRead(["getStats", indexName], (client, request) => client.getStats(indexName, request), options);
+  return useProviderRead(
+    ["getStats", indexName],
+    (reader, request) => reader.getStats(indexName, request),
+    options,
+    indexName
+  );
 }
 
 // src/react/search.ts
 function useQuery(indexName, params, options) {
-  return useRead(
+  return useProviderRead(
     ["query", indexName, params],
-    (client, request) => client.query(indexName, params, request),
-    options
+    (reader, request) => reader.query(indexName, params, request),
+    options,
+    indexName
   );
 }
 function usePreflight(indexName, params, options) {
-  return useRead(
+  return useProviderRead(
     ["preflight", indexName, params],
-    (client, request) => client.preflight(indexName, params, request),
-    options
+    (reader, request) => reader.preflight(indexName, params, request),
+    options,
+    indexName
   );
 }
 function useSuggest(indexName, params, options) {
-  return useRead(
+  return useProviderRead(
     ["suggest", indexName, params],
-    (client, request) => client.suggest(indexName, params, request),
-    options
+    (reader, request) => reader.suggest(indexName, params, request),
+    options,
+    indexName
   );
 }
 
 // src/react/tasks.ts
 function useTask(taskId, options) {
+  const client = useServerClient("useTask");
   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 state = useRead(
+    client,
+    ["getTask", id],
+    (server, request) => server.getTask(id, request),
+    { ...options, enabled, refreshIntervalMs: 0 },
+    NO_INDEX
+  );
   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);
+  const client = useServerClient("useTasks");
+  return useRead(client, ["listTasks", query], (server, request) => server.listTasks(query, request), options, NO_INDEX);
 }
 
 export { ClientErrorCodes, ErrorCodes, NarsilError, NarsilProvider, ServerErrorCodes, isNarsilError, useDocument, useDocuments, useImport, useIndexes, useNarsilClient, usePreflight, useQuery, useStats, useSuggest, useTask, useTasks };

package/dist/server.d.ts

@@ -1,7 +1,7 @@
 export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, N as NarsilError, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-C7UMCMH3.js';
 import { b as ServerOptions, N as NarsilServer } from './capabilities-Dt-7B4Wz.js';
 export { A as ASYNC_IMPORT_CAPABILITY, C as CorsOptions, E as ErrorEnvelope, I as INDEX_LIFECYCLE_CAPABILITY, O as OnRequestHook, R as REBUILD_ANALYSIS_CAPABILITY, c as RequestContext, d as RequestDenial, S as SERVER_CAPABILITIES, e as ServerLimits, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './capabilities-Dt-7B4Wz.js';
-import { a as Narsil } from './engine-CXKfmK7I.js';
+import { a as Narsil } from './engine-igk0aMpQ.js';
 import { d as TaskProgress, b as ImportResult, h as TaskStore, e as TaskRecord } from './tasks-BZt_zes6.js';
 export { C as CapabilitiesResponse, a as CreateIndexEmbedding, i as CreateIndexRequest, H as HttpIndexConfig, I as ImportError, M as MemoryStatsResponse, T as TaskListPage, c as TaskListQuery, f as TaskStatus, g as TaskType } from './tasks-BZt_zes6.js';
 import './schema-Bgzr4g7b.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delali/narsil",
-  "version": "0.3.1-next.70",
+  "version": "0.3.1-next.71",
   "type": "module",
   "description": "Distributed search engine with full-text, vector, hybrid, and geosearch. One engine, embedded or on a server, with a cross-language .nrsl format.",
   "author": "Delali (https://sondelali.com)",
@@ -223,11 +223,11 @@
     }
   },
   "optionalDependencies": {
-    "@delali/narsil-native-darwin-arm64": "0.3.1-next.70",
-    "@delali/narsil-native-darwin-x64": "0.3.1-next.70",
-    "@delali/narsil-native-linux-arm64": "0.3.1-next.70",
-    "@delali/narsil-native-linux-x64": "0.3.1-next.70",
-    "@delali/narsil-native-win32-arm64": "0.3.1-next.70",
-    "@delali/narsil-native-win32-x64": "0.3.1-next.70"
+    "@delali/narsil-native-darwin-arm64": "0.3.1-next.71",
+    "@delali/narsil-native-darwin-x64": "0.3.1-next.71",
+    "@delali/narsil-native-linux-arm64": "0.3.1-next.71",
+    "@delali/narsil-native-linux-x64": "0.3.1-next.71",
+    "@delali/narsil-native-win32-arm64": "0.3.1-next.71",
+    "@delali/narsil-native-win32-x64": "0.3.1-next.71"
   }
 }