@topgunbuild/react 0.7.0 → 0.8.1

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import React, { ReactNode } from 'react';
 import * as _topgunbuild_client from '@topgunbuild/client';
-import { TopGunClient, ChangeEvent, QueryResultItem, QueryFilter, TopicCallback, RegisterResult, ResolverInfo } from '@topgunbuild/client';
-import { LWWMap, ORMap, EntryProcessorResult, EntryProcessorDef, JournalEventType, JournalEvent, MergeRejection, ConflictResolverDef } from '@topgunbuild/core';
+import { TopGunClient, ChangeEvent, QueryResultItem, QueryFilter, TopicCallback, RegisterResult, ResolverInfo, SearchResult, HybridResultItem, HybridQueryFilter } from '@topgunbuild/client';
+import { LWWMap, ORMap, EntryProcessorResult, EntryProcessorDef, JournalEventType, JournalEvent, MergeRejection, ConflictResolverDef, SearchOptions } from '@topgunbuild/core';
 
 interface TopGunProviderProps {
     client: TopGunClient;
@@ -607,4 +607,200 @@ interface UseConflictResolverResult {
  */
 declare function useConflictResolver(mapName: string, options?: UseConflictResolverOptions): UseConflictResolverResult;
 
-export { TopGunProvider, type TopGunProviderProps, type UseConflictResolverOptions, type UseConflictResolverResult, type UseEntryProcessorOptions, type UseEntryProcessorResult, type UseEventJournalOptions, type UseEventJournalResult, type UseMergeRejectionsOptions, type UseMergeRejectionsResult, type UseMutationResult, type UsePNCounterResult, type UseQueryOptions, type UseQueryResult, useClient, useConflictResolver, useEntryProcessor, useEventJournal, useMap, useMergeRejections, useMutation, useORMap, usePNCounter, useQuery, useTopic };
+/**
+ * Extended search options for useSearch hook.
+ */
+interface UseSearchOptions extends SearchOptions {
+    /**
+     * Debounce delay in milliseconds.
+     * If specified, query changes will be debounced before sending to the server.
+     * Useful for search-as-you-type interfaces.
+     */
+    debounceMs?: number;
+}
+/**
+ * Result type for the useSearch hook.
+ */
+interface UseSearchResult<T> {
+    /** Current search results sorted by relevance */
+    results: SearchResult<T>[];
+    /** True while waiting for initial results */
+    loading: boolean;
+    /** Error if search failed */
+    error: Error | null;
+}
+/**
+ * React hook for live full-text search with real-time updates.
+ *
+ * Creates a search subscription that receives delta updates when documents
+ * matching the query are added, updated, or removed. Results are automatically
+ * sorted by BM25 relevance score.
+ *
+ * @param mapName - Name of the map to search
+ * @param query - Search query text
+ * @param options - Search options (limit, minScore, boost, debounceMs)
+ * @returns Object containing results, loading state, and error
+ *
+ * @example Basic usage
+ * ```tsx
+ * function SearchResults() {
+ *   const [searchTerm, setSearchTerm] = useState('');
+ *   const { results, loading } = useSearch<Article>('articles', searchTerm, {
+ *     limit: 20,
+ *     boost: { title: 2.0 }
+ *   });
+ *
+ *   if (loading) return <Spinner />;
+ *
+ *   return (
+ *     <ul>
+ *       {results.map(r => (
+ *         <li key={r.key}>
+ *           [{r.score.toFixed(2)}] {r.value.title}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example With debounce for search-as-you-type
+ * ```tsx
+ * function SearchInput() {
+ *   const [input, setInput] = useState('');
+ *   const { results, loading, error } = useSearch<Product>('products', input, {
+ *     debounceMs: 300,
+ *     limit: 10
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={input}
+ *         onChange={(e) => setInput(e.target.value)}
+ *         placeholder="Search products..."
+ *       />
+ *       {loading && <span>Searching...</span>}
+ *       {error && <span className="error">{error.message}</span>}
+ *       <ul>
+ *         {results.map(r => (
+ *           <li key={r.key}>{r.value.name}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSearch<T = unknown>(mapName: string, query: string, options?: UseSearchOptions): UseSearchResult<T>;
+
+/**
+ * Extended options for useHybridQuery hook.
+ */
+interface UseHybridQueryOptions {
+    /**
+     * Whether to skip the query (don't execute).
+     * Useful for conditional queries.
+     */
+    skip?: boolean;
+}
+/**
+ * Result type for the useHybridQuery hook.
+ */
+interface UseHybridQueryResult<T> {
+    /** Current query results with _key, value, _score, _matchedTerms */
+    results: HybridResultItem<T>[];
+    /** True while waiting for initial results */
+    loading: boolean;
+    /** Error if query failed */
+    error: Error | null;
+}
+/**
+ * React hook for hybrid queries combining FTS with traditional filters.
+ *
+ * Creates a subscription that receives live updates when documents
+ * matching the query change. Results include relevance scores for FTS predicates.
+ *
+ * @param mapName - Name of the map to query
+ * @param filter - Hybrid query filter with predicate, where, sort, limit, offset
+ * @param options - Hook options (skip)
+ * @returns Object containing results, loading state, and error
+ *
+ * @example Basic hybrid query (FTS + filter)
+ * ```tsx
+ * import { Predicates } from '@topgunbuild/core';
+ *
+ * function TechArticles() {
+ *   const { results, loading } = useHybridQuery<Article>('articles', {
+ *     predicate: Predicates.and(
+ *       Predicates.match('body', 'machine learning'),
+ *       Predicates.equal('category', 'tech')
+ *     ),
+ *     sort: { _score: 'desc' },
+ *     limit: 20
+ *   });
+ *
+ *   if (loading) return <Spinner />;
+ *
+ *   return (
+ *     <ul>
+ *       {results.map(r => (
+ *         <li key={r._key}>
+ *           [{r._score?.toFixed(2)}] {r.value.title}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example With dynamic filter
+ * ```tsx
+ * function SearchWithFilters() {
+ *   const [searchTerm, setSearchTerm] = useState('');
+ *   const [category, setCategory] = useState('all');
+ *
+ *   const filter = useMemo(() => ({
+ *     predicate: searchTerm
+ *       ? category !== 'all'
+ *         ? Predicates.and(
+ *             Predicates.match('body', searchTerm),
+ *             Predicates.equal('category', category)
+ *           )
+ *         : Predicates.match('body', searchTerm)
+ *       : category !== 'all'
+ *         ? Predicates.equal('category', category)
+ *         : undefined,
+ *     sort: searchTerm ? { _score: 'desc' } : { createdAt: 'desc' },
+ *     limit: 20
+ *   }), [searchTerm, category]);
+ *
+ *   const { results, loading, error } = useHybridQuery<Article>('articles', filter);
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={searchTerm}
+ *         onChange={(e) => setSearchTerm(e.target.value)}
+ *         placeholder="Search..."
+ *       />
+ *       <select value={category} onChange={(e) => setCategory(e.target.value)}>
+ *         <option value="all">All</option>
+ *         <option value="tech">Tech</option>
+ *         <option value="science">Science</option>
+ *       </select>
+ *       {loading && <span>Loading...</span>}
+ *       {error && <span className="error">{error.message}</span>}
+ *       <ul>
+ *         {results.map(r => (
+ *           <li key={r._key}>{r.value.title}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useHybridQuery<T = unknown>(mapName: string, filter?: HybridQueryFilter, options?: UseHybridQueryOptions): UseHybridQueryResult<T>;
+
+export { TopGunProvider, type TopGunProviderProps, type UseConflictResolverOptions, type UseConflictResolverResult, type UseEntryProcessorOptions, type UseEntryProcessorResult, type UseEventJournalOptions, type UseEventJournalResult, type UseHybridQueryOptions, type UseHybridQueryResult, type UseMergeRejectionsOptions, type UseMergeRejectionsResult, type UseMutationResult, type UsePNCounterResult, type UseQueryOptions, type UseQueryResult, type UseSearchOptions, type UseSearchResult, useClient, useConflictResolver, useEntryProcessor, useEventJournal, useHybridQuery, useMap, useMergeRejections, useMutation, useORMap, usePNCounter, useQuery, useSearch, useTopic };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import React, { ReactNode } from 'react';
 import * as _topgunbuild_client from '@topgunbuild/client';
-import { TopGunClient, ChangeEvent, QueryResultItem, QueryFilter, TopicCallback, RegisterResult, ResolverInfo } from '@topgunbuild/client';
-import { LWWMap, ORMap, EntryProcessorResult, EntryProcessorDef, JournalEventType, JournalEvent, MergeRejection, ConflictResolverDef } from '@topgunbuild/core';
+import { TopGunClient, ChangeEvent, QueryResultItem, QueryFilter, TopicCallback, RegisterResult, ResolverInfo, SearchResult, HybridResultItem, HybridQueryFilter } from '@topgunbuild/client';
+import { LWWMap, ORMap, EntryProcessorResult, EntryProcessorDef, JournalEventType, JournalEvent, MergeRejection, ConflictResolverDef, SearchOptions } from '@topgunbuild/core';
 
 interface TopGunProviderProps {
     client: TopGunClient;
@@ -607,4 +607,200 @@ interface UseConflictResolverResult {
  */
 declare function useConflictResolver(mapName: string, options?: UseConflictResolverOptions): UseConflictResolverResult;
 
-export { TopGunProvider, type TopGunProviderProps, type UseConflictResolverOptions, type UseConflictResolverResult, type UseEntryProcessorOptions, type UseEntryProcessorResult, type UseEventJournalOptions, type UseEventJournalResult, type UseMergeRejectionsOptions, type UseMergeRejectionsResult, type UseMutationResult, type UsePNCounterResult, type UseQueryOptions, type UseQueryResult, useClient, useConflictResolver, useEntryProcessor, useEventJournal, useMap, useMergeRejections, useMutation, useORMap, usePNCounter, useQuery, useTopic };
+/**
+ * Extended search options for useSearch hook.
+ */
+interface UseSearchOptions extends SearchOptions {
+    /**
+     * Debounce delay in milliseconds.
+     * If specified, query changes will be debounced before sending to the server.
+     * Useful for search-as-you-type interfaces.
+     */
+    debounceMs?: number;
+}
+/**
+ * Result type for the useSearch hook.
+ */
+interface UseSearchResult<T> {
+    /** Current search results sorted by relevance */
+    results: SearchResult<T>[];
+    /** True while waiting for initial results */
+    loading: boolean;
+    /** Error if search failed */
+    error: Error | null;
+}
+/**
+ * React hook for live full-text search with real-time updates.
+ *
+ * Creates a search subscription that receives delta updates when documents
+ * matching the query are added, updated, or removed. Results are automatically
+ * sorted by BM25 relevance score.
+ *
+ * @param mapName - Name of the map to search
+ * @param query - Search query text
+ * @param options - Search options (limit, minScore, boost, debounceMs)
+ * @returns Object containing results, loading state, and error
+ *
+ * @example Basic usage
+ * ```tsx
+ * function SearchResults() {
+ *   const [searchTerm, setSearchTerm] = useState('');
+ *   const { results, loading } = useSearch<Article>('articles', searchTerm, {
+ *     limit: 20,
+ *     boost: { title: 2.0 }
+ *   });
+ *
+ *   if (loading) return <Spinner />;
+ *
+ *   return (
+ *     <ul>
+ *       {results.map(r => (
+ *         <li key={r.key}>
+ *           [{r.score.toFixed(2)}] {r.value.title}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example With debounce for search-as-you-type
+ * ```tsx
+ * function SearchInput() {
+ *   const [input, setInput] = useState('');
+ *   const { results, loading, error } = useSearch<Product>('products', input, {
+ *     debounceMs: 300,
+ *     limit: 10
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={input}
+ *         onChange={(e) => setInput(e.target.value)}
+ *         placeholder="Search products..."
+ *       />
+ *       {loading && <span>Searching...</span>}
+ *       {error && <span className="error">{error.message}</span>}
+ *       <ul>
+ *         {results.map(r => (
+ *           <li key={r.key}>{r.value.name}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSearch<T = unknown>(mapName: string, query: string, options?: UseSearchOptions): UseSearchResult<T>;
+
+/**
+ * Extended options for useHybridQuery hook.
+ */
+interface UseHybridQueryOptions {
+    /**
+     * Whether to skip the query (don't execute).
+     * Useful for conditional queries.
+     */
+    skip?: boolean;
+}
+/**
+ * Result type for the useHybridQuery hook.
+ */
+interface UseHybridQueryResult<T> {
+    /** Current query results with _key, value, _score, _matchedTerms */
+    results: HybridResultItem<T>[];
+    /** True while waiting for initial results */
+    loading: boolean;
+    /** Error if query failed */
+    error: Error | null;
+}
+/**
+ * React hook for hybrid queries combining FTS with traditional filters.
+ *
+ * Creates a subscription that receives live updates when documents
+ * matching the query change. Results include relevance scores for FTS predicates.
+ *
+ * @param mapName - Name of the map to query
+ * @param filter - Hybrid query filter with predicate, where, sort, limit, offset
+ * @param options - Hook options (skip)
+ * @returns Object containing results, loading state, and error
+ *
+ * @example Basic hybrid query (FTS + filter)
+ * ```tsx
+ * import { Predicates } from '@topgunbuild/core';
+ *
+ * function TechArticles() {
+ *   const { results, loading } = useHybridQuery<Article>('articles', {
+ *     predicate: Predicates.and(
+ *       Predicates.match('body', 'machine learning'),
+ *       Predicates.equal('category', 'tech')
+ *     ),
+ *     sort: { _score: 'desc' },
+ *     limit: 20
+ *   });
+ *
+ *   if (loading) return <Spinner />;
+ *
+ *   return (
+ *     <ul>
+ *       {results.map(r => (
+ *         <li key={r._key}>
+ *           [{r._score?.toFixed(2)}] {r.value.title}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example With dynamic filter
+ * ```tsx
+ * function SearchWithFilters() {
+ *   const [searchTerm, setSearchTerm] = useState('');
+ *   const [category, setCategory] = useState('all');
+ *
+ *   const filter = useMemo(() => ({
+ *     predicate: searchTerm
+ *       ? category !== 'all'
+ *         ? Predicates.and(
+ *             Predicates.match('body', searchTerm),
+ *             Predicates.equal('category', category)
+ *           )
+ *         : Predicates.match('body', searchTerm)
+ *       : category !== 'all'
+ *         ? Predicates.equal('category', category)
+ *         : undefined,
+ *     sort: searchTerm ? { _score: 'desc' } : { createdAt: 'desc' },
+ *     limit: 20
+ *   }), [searchTerm, category]);
+ *
+ *   const { results, loading, error } = useHybridQuery<Article>('articles', filter);
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={searchTerm}
+ *         onChange={(e) => setSearchTerm(e.target.value)}
+ *         placeholder="Search..."
+ *       />
+ *       <select value={category} onChange={(e) => setCategory(e.target.value)}>
+ *         <option value="all">All</option>
+ *         <option value="tech">Tech</option>
+ *         <option value="science">Science</option>
+ *       </select>
+ *       {loading && <span>Loading...</span>}
+ *       {error && <span className="error">{error.message}</span>}
+ *       <ul>
+ *         {results.map(r => (
+ *           <li key={r._key}>{r.value.title}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useHybridQuery<T = unknown>(mapName: string, filter?: HybridQueryFilter, options?: UseHybridQueryOptions): UseHybridQueryResult<T>;
+
+export { TopGunProvider, type TopGunProviderProps, type UseConflictResolverOptions, type UseConflictResolverResult, type UseEntryProcessorOptions, type UseEntryProcessorResult, type UseEventJournalOptions, type UseEventJournalResult, type UseHybridQueryOptions, type UseHybridQueryResult, type UseMergeRejectionsOptions, type UseMergeRejectionsResult, type UseMutationResult, type UsePNCounterResult, type UseQueryOptions, type UseQueryResult, type UseSearchOptions, type UseSearchResult, useClient, useConflictResolver, useEntryProcessor, useEventJournal, useHybridQuery, useMap, useMergeRejections, useMutation, useORMap, usePNCounter, useQuery, useSearch, useTopic };

package/dist/index.js

@@ -25,12 +25,14 @@ __export(index_exports, {
   useConflictResolver: () => useConflictResolver,
   useEntryProcessor: () => useEntryProcessor,
   useEventJournal: () => useEventJournal,
+  useHybridQuery: () => useHybridQuery,
   useMap: () => useMap,
   useMergeRejections: () => useMergeRejections,
   useMutation: () => useMutation,
   useORMap: () => useORMap,
   usePNCounter: () => usePNCounter,
   useQuery: () => useQuery,
+  useSearch: () => useSearch,
   useTopic: () => useTopic
 });
 module.exports = __toCommonJS(index_exports);
@@ -540,6 +542,179 @@ function useConflictResolver(mapName, options = {}) {
     registered
   };
 }
+
+// src/hooks/useSearch.ts
+var import_react12 = require("react");
+function useSearch(mapName, query, options) {
+  const client = useClient();
+  const [results, setResults] = (0, import_react12.useState)([]);
+  const [loading, setLoading] = (0, import_react12.useState)(true);
+  const [error, setError] = (0, import_react12.useState)(null);
+  const isMounted = (0, import_react12.useRef)(true);
+  const handleRef = (0, import_react12.useRef)(null);
+  const unsubscribeRef = (0, import_react12.useRef)(null);
+  const debounceTimeoutRef = (0, import_react12.useRef)(null);
+  const debounceMs = options?.debounceMs;
+  const searchOptions = (0, import_react12.useMemo)(() => {
+    if (!options) return {};
+    const { debounceMs: _, ...opts } = options;
+    return opts;
+  }, [options?.limit, options?.minScore, options?.boost]);
+  const [debouncedQuery, setDebouncedQuery] = (0, import_react12.useState)(query);
+  const isFirstQuery = (0, import_react12.useRef)(true);
+  (0, import_react12.useEffect)(() => {
+    if (debounceMs != null && debounceMs > 0) {
+      if (debounceTimeoutRef.current) {
+        clearTimeout(debounceTimeoutRef.current);
+      }
+      debounceTimeoutRef.current = setTimeout(() => {
+        if (isMounted.current) {
+          setDebouncedQuery(query);
+        }
+      }, debounceMs);
+      return () => {
+        if (debounceTimeoutRef.current) {
+          clearTimeout(debounceTimeoutRef.current);
+        }
+      };
+    } else {
+      setDebouncedQuery(query);
+    }
+  }, [query, debounceMs]);
+  (0, import_react12.useEffect)(() => {
+    isMounted.current = true;
+    isFirstQuery.current = true;
+    return () => {
+      isMounted.current = false;
+      if (unsubscribeRef.current) {
+        unsubscribeRef.current();
+        unsubscribeRef.current = null;
+      }
+      if (handleRef.current) {
+        handleRef.current.dispose();
+        handleRef.current = null;
+      }
+    };
+  }, [client, mapName]);
+  (0, import_react12.useEffect)(() => {
+    if (!debouncedQuery.trim()) {
+      setResults([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      if (handleRef.current && !isFirstQuery.current) {
+        handleRef.current.setQuery(debouncedQuery);
+      } else {
+        if (handleRef.current) {
+          if (unsubscribeRef.current) {
+            unsubscribeRef.current();
+          }
+          handleRef.current.dispose();
+        }
+        const handle = client.searchSubscribe(mapName, debouncedQuery, searchOptions);
+        handleRef.current = handle;
+        isFirstQuery.current = false;
+        let hasReceivedResults = false;
+        unsubscribeRef.current = handle.subscribe((newResults) => {
+          if (isMounted.current) {
+            setResults(newResults);
+            if (!hasReceivedResults) {
+              hasReceivedResults = true;
+              setLoading(false);
+            }
+          }
+        });
+      }
+    } catch (err) {
+      if (isMounted.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      }
+    }
+  }, [client, mapName, debouncedQuery, searchOptions]);
+  (0, import_react12.useEffect)(() => {
+    if (!handleRef.current || isFirstQuery.current) {
+      return;
+    }
+    handleRef.current.setOptions(searchOptions);
+  }, [searchOptions]);
+  return (0, import_react12.useMemo)(
+    () => ({ results, loading, error }),
+    [results, loading, error]
+  );
+}
+
+// src/hooks/useHybridQuery.ts
+var import_react13 = require("react");
+function useHybridQuery(mapName, filter = {}, options) {
+  const client = useClient();
+  const [results, setResults] = (0, import_react13.useState)([]);
+  const [loading, setLoading] = (0, import_react13.useState)(true);
+  const [error, setError] = (0, import_react13.useState)(null);
+  const isMounted = (0, import_react13.useRef)(true);
+  const handleRef = (0, import_react13.useRef)(null);
+  const unsubscribeRef = (0, import_react13.useRef)(null);
+  const memoizedFilter = (0, import_react13.useMemo)(() => filter, [
+    JSON.stringify(filter.predicate),
+    JSON.stringify(filter.where),
+    JSON.stringify(filter.sort),
+    filter.limit,
+    filter.offset
+  ]);
+  const skip = options?.skip ?? false;
+  (0, import_react13.useEffect)(() => {
+    isMounted.current = true;
+    if (skip) {
+      setResults([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      if (handleRef.current) {
+        if (unsubscribeRef.current) {
+          unsubscribeRef.current();
+          unsubscribeRef.current = null;
+        }
+      }
+      const handle = client.hybridQuery(mapName, memoizedFilter);
+      handleRef.current = handle;
+      let hasReceivedResults = false;
+      unsubscribeRef.current = handle.subscribe((newResults) => {
+        if (isMounted.current) {
+          setResults(newResults);
+          if (!hasReceivedResults) {
+            hasReceivedResults = true;
+            setLoading(false);
+          }
+        }
+      });
+    } catch (err) {
+      if (isMounted.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      }
+    }
+    return () => {
+      isMounted.current = false;
+      if (unsubscribeRef.current) {
+        unsubscribeRef.current();
+        unsubscribeRef.current = null;
+      }
+      handleRef.current = null;
+    };
+  }, [client, mapName, memoizedFilter, skip]);
+  return (0, import_react13.useMemo)(
+    () => ({ results, loading, error }),
+    [results, loading, error]
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TopGunProvider,
@@ -547,12 +722,14 @@ function useConflictResolver(mapName, options = {}) {
   useConflictResolver,
   useEntryProcessor,
   useEventJournal,
+  useHybridQuery,
   useMap,
   useMergeRejections,
   useMutation,
   useORMap,
   usePNCounter,
   useQuery,
+  useSearch,
   useTopic
 });
 //# sourceMappingURL=index.js.map