@aiao/rxdb-plugin-search-react 0.0.20

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aiao Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * rxdb-plugin-search-react - React 集成层
+ *
+ * 提供 `useSearch()` hook，将 `@aiao/rxdb-plugin-search` 的 `SearchHandle` 适配为 React 状态消费接口。
+ *
+ * @packageDocumentation
+ */
+export { useSearch } from './use-search.js';
+export type { SearchSourceLike, UseSearchReturn } from './use-search.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+"use client";
+import { useCallback as e, useEffect as t, useMemo as n, useRef as r, useState as i } from "react";
+import { Subscription as a } from "rxjs";
+//#region src/use-search.ts
+function o(o, s) {
+	let c = s?.initialQuery ?? "", l = r(null), u = r(null);
+	l.current === null && (l.current = o.search(c, s));
+	let d = l.current, [f, p] = i(c), [m, h] = i([]), [g, _] = i("idle"), [v, y] = i(void 0), [b, x] = i(!1);
+	t(() => {
+		u.current !== null && (clearTimeout(u.current), u.current = null);
+		let e = new a();
+		return e.add(d.results$.subscribe((e) => h(e))), e.add(d.state$.subscribe((e) => _(e))), e.add(d.error$.subscribe((e) => y(e))), e.add(d.hasMore$.subscribe((e) => x(e))), () => {
+			e.unsubscribe(), u.current = setTimeout(() => {
+				d.destroy(), l.current = null, u.current = null;
+			}, 0);
+		};
+	}, []);
+	let S = e((e) => {
+		p(e), d.setQuery(e);
+	}, [d]), C = e(() => {
+		p(""), d.clear();
+	}, [d]), w = e(() => d.retry(), [d]), T = e(() => d.loadMore(), [d]);
+	return n(() => ({
+		query: f,
+		setQuery: S,
+		results: m,
+		state: g,
+		error: v,
+		hasMore: b,
+		loadMore: T,
+		clear: C,
+		retry: w
+	}), [
+		f,
+		S,
+		m,
+		g,
+		v,
+		b,
+		T,
+		C,
+		w
+	]);
+}
+//#endregion
+export { o as useSearch };

package/dist/use-search.d.ts

@@ -0,0 +1,50 @@
+import { SearchExecutionError, SearchOptions, SearchResult, SearchSourceLike, SearchState } from '../packages/rxdb-plugin-search/src/index.ts';
+/**
+ * React 集成 - rxdb-plugin-search
+ *
+ * 提供 `useSearch()`，将 `SearchHandle` 的 Observable 适配为 React state；
+ * 通过 `useEffect` 清理函数在组件卸载时自动释放 handle。
+ *
+ * @packageDocumentation
+ */
+export type { SearchSourceLike };
+/**
+ * {@link useSearch} 返回值。
+ *
+ * @public
+ */
+export interface UseSearchReturn {
+    /** 当前查询词 */
+    query: string;
+    /** 写入查询词；触发插件防抖 */
+    setQuery: (q: string) => void;
+    /** 当前结果 */
+    results: readonly SearchResult[];
+    /** 当前状态 */
+    state: SearchState;
+    /** 最近一次执行错误 */
+    error: SearchExecutionError | undefined;
+    /** 是否还有下一页 */
+    hasMore: boolean;
+    /** 加载下一页；无更多时 no-op */
+    loadMore: () => Promise<void>;
+    /** 清空查询与结果并回到 idle */
+    clear: () => void;
+    /** 在 error 状态下重试 */
+    retry: () => void;
+}
+/**
+ * 将 `SearchHandle` 的响应式输出适配为 React hook。
+ *
+ * @example
+ * ```tsx
+ * const { query, setQuery, results, state } = useSearch(db, { debounce: 200 });
+ * return <input value={query} onChange={e => setQuery(e.target.value)} />;
+ * ```
+ *
+ * @param source - 暴露 `search()` 方法的数据源（`RxDB` / `RxCollection`）
+ * @param options - 单次调用级 {@link SearchOptions}
+ * @public
+ */
+export declare function useSearch(source: SearchSourceLike, options?: SearchOptions): UseSearchReturn;
+//# sourceMappingURL=use-search.d.ts.map

package/dist/use-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-search.d.ts","sourceRoot":"","sources":["../src/use-search.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,oBAAoB,EAEpB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC;;;;;;;GAOG;AAEH,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,WAAW;IACX,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,WAAW;IACX,KAAK,EAAE,WAAW,CAAC;IACnB,eAAe;IACf,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACxC,cAAc;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,uBAAuB;IACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,sBAAsB;IACtB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,oBAAoB;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,eAAe,CA0D5F"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@aiao/rxdb-plugin-search-react",
+  "version": "0.0.20",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@aiao/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@aiao/rxdb-plugin-search": "0.0.20"
+  },
+  "peerDependencies": {
+    "@aiao/rxdb": "*",
+    "react": ">=18.0.0",
+    "rxjs": "^7.8.2",
+    "@aiao/rxdb-plugin-search": "0.0.20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "name": "rxdb-plugin-search-react",
+  "projectType": "library",
+  "sourceRoot": "packages/rxdb-plugin-search-react/src",
+  "tags": ["react-lib"],
+  "targets": {}
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+'use client';
+
+/**
+ * rxdb-plugin-search-react - React 集成层
+ *
+ * 提供 `useSearch()` hook，将 `@aiao/rxdb-plugin-search` 的 `SearchHandle` 适配为 React 状态消费接口。
+ *
+ * @packageDocumentation
+ */
+
+export { useSearch } from './use-search.js';
+export type { SearchSourceLike, UseSearchReturn } from './use-search.js';

package/src/use-search.spec.ts

@@ -0,0 +1,151 @@
+// @vitest-environment jsdom
+
+import { act, renderHook } from '@testing-library/react';
+import { StrictMode, createElement, type PropsWithChildren } from 'react';
+import { BehaviorSubject } from 'rxjs';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { SearchExecutionError, SearchHandle, SearchResult, SearchState } from '@aiao/rxdb-plugin-search';
+
+import { useSearch, type SearchSourceLike } from '../src/use-search.js';
+
+const makeHandle = () => {
+  const results$ = new BehaviorSubject<SearchResult[]>([]);
+  const state$ = new BehaviorSubject<SearchState>('idle');
+  const error$ = new BehaviorSubject<SearchExecutionError | undefined>(undefined);
+  const hasMore$ = new BehaviorSubject<boolean>(false);
+  const destroyed = { value: false };
+  const setQuery = vi.fn();
+  const loadMore = vi.fn(async () => {
+    /* noop */
+  });
+  const clear = vi.fn();
+  const retry = vi.fn();
+
+  const handle: SearchHandle = {
+    results$,
+    state$,
+    error$,
+    hasMore$,
+    setQuery,
+    loadMore,
+    clear,
+    retry,
+    destroy: vi.fn(() => {
+      destroyed.value = true;
+    })
+  };
+  return { handle, results$, state$, error$, hasMore$, setQuery, loadMore, clear, retry, destroyed };
+};
+
+const makeSource = (handle: SearchHandle): SearchSourceLike & { searchSpy: ReturnType<typeof vi.fn> } => {
+  const searchSpy = vi.fn(() => handle);
+  return {
+    search: searchSpy,
+    searchSpy
+  };
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('useSearch (React binding, T039)', () => {
+  it('initial render mirrors handle observables', () => {
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const { result } = renderHook(() => useSearch(src));
+    expect(result.current.query).toBe('');
+    expect(result.current.results).toEqual([]);
+    expect(result.current.state).toBe('idle');
+    expect(result.current.hasMore).toBe(false);
+    expect(src.searchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('setQuery forwards to handle.setQuery and updates local query state', () => {
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const { result } = renderHook(() => useSearch(src));
+    act(() => result.current.setQuery('foo'));
+    expect(h.setQuery).toHaveBeenCalledWith('foo');
+    expect(result.current.query).toBe('foo');
+  });
+
+  it('handle observable updates propagate to hook state', () => {
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const { result } = renderHook(() => useSearch(src));
+    const rows: SearchResult[] = [{ entity: 'A', collection: 'a', id: '1', rank: -1, matchedField: 'x', snippet: 's' }];
+    act(() => {
+      h.results$.next(rows);
+      h.state$.next('success');
+      h.hasMore$.next(true);
+    });
+    expect(result.current.results).toEqual(rows);
+    expect(result.current.state).toBe('success');
+    expect(result.current.hasMore).toBe(true);
+  });
+
+  it('unmount calls handle.destroy', () => {
+    vi.useFakeTimers();
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const { unmount } = renderHook(() => useSearch(src));
+    unmount();
+    vi.runAllTimers();
+    expect(h.destroyed.value).toBe(true);
+  });
+
+  it('keeps the handle usable under React StrictMode double effects', () => {
+    vi.useFakeTimers();
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const StrictWrapper = ({ children }: PropsWithChildren) => createElement(StrictMode, null, children);
+
+    const { result, unmount } = renderHook(() => useSearch(src), { wrapper: StrictWrapper });
+
+    act(() => {
+      vi.runAllTimers();
+    });
+    expect(h.destroyed.value).toBe(false);
+
+    act(() => result.current.setQuery('foo'));
+    expect(h.setQuery).toHaveBeenCalledWith('foo');
+    expect(result.current.query).toBe('foo');
+
+    unmount();
+    act(() => {
+      vi.runAllTimers();
+    });
+    expect(h.destroyed.value).toBe(true);
+  });
+
+  it('clear() resets query to empty and calls handle.clear', () => {
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const { result } = renderHook(() => useSearch(src));
+    act(() => result.current.setQuery('foo'));
+    act(() => result.current.clear());
+    expect(h.clear).toHaveBeenCalledTimes(1);
+    expect(result.current.query).toBe('');
+  });
+
+  it('retry() and loadMore() forward to handle', async () => {
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const { result } = renderHook(() => useSearch(src));
+    act(() => result.current.retry());
+    await act(async () => {
+      await result.current.loadMore();
+    });
+    expect(h.retry).toHaveBeenCalledTimes(1);
+    expect(h.loadMore).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes initialQuery to source.search', () => {
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    renderHook(() => useSearch(src, { initialQuery: 'hi' }));
+    expect(src.searchSpy).toHaveBeenCalledWith('hi', { initialQuery: 'hi' });
+  });
+});

package/src/use-search.ts

@@ -0,0 +1,123 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Subscription } from 'rxjs';
+
+import type {
+  SearchExecutionError,
+  SearchHandle,
+  SearchOptions,
+  SearchResult,
+  SearchSourceLike,
+  SearchState
+} from '@aiao/rxdb-plugin-search';
+
+/**
+ * React 集成 - rxdb-plugin-search
+ *
+ * 提供 `useSearch()`，将 `SearchHandle` 的 Observable 适配为 React state；
+ * 通过 `useEffect` 清理函数在组件卸载时自动释放 handle。
+ *
+ * @packageDocumentation
+ */
+
+export type { SearchSourceLike };
+
+/**
+ * {@link useSearch} 返回值。
+ *
+ * @public
+ */
+export interface UseSearchReturn {
+  /** 当前查询词 */
+  query: string;
+  /** 写入查询词；触发插件防抖 */
+  setQuery: (q: string) => void;
+  /** 当前结果 */
+  results: readonly SearchResult[];
+  /** 当前状态 */
+  state: SearchState;
+  /** 最近一次执行错误 */
+  error: SearchExecutionError | undefined;
+  /** 是否还有下一页 */
+  hasMore: boolean;
+  /** 加载下一页；无更多时 no-op */
+  loadMore: () => Promise<void>;
+  /** 清空查询与结果并回到 idle */
+  clear: () => void;
+  /** 在 error 状态下重试 */
+  retry: () => void;
+}
+
+/**
+ * 将 `SearchHandle` 的响应式输出适配为 React hook。
+ *
+ * @example
+ * ```tsx
+ * const { query, setQuery, results, state } = useSearch(db, { debounce: 200 });
+ * return <input value={query} onChange={e => setQuery(e.target.value)} />;
+ * ```
+ *
+ * @param source - 暴露 `search()` 方法的数据源（`RxDB` / `RxCollection`）
+ * @param options - 单次调用级 {@link SearchOptions}
+ * @public
+ */
+export function useSearch(source: SearchSourceLike, options?: SearchOptions): UseSearchReturn {
+  const initial = options?.initialQuery ?? '';
+  // 保持 handle 引用稳定：仅在 source 变化时重建
+  const handleRef = useRef<SearchHandle | null>(null);
+  const destroyTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  if (handleRef.current === null) {
+    handleRef.current = source.search(initial, options);
+  }
+  const handle = handleRef.current;
+
+  const [query, setQueryState] = useState<string>(initial);
+  const [results, setResults] = useState<readonly SearchResult[]>([]);
+  const [state, setState] = useState<SearchState>('idle');
+  const [error, setError] = useState<SearchExecutionError | undefined>(undefined);
+  const [hasMore, setHasMore] = useState<boolean>(false);
+
+  useEffect(() => {
+    if (destroyTimerRef.current !== null) {
+      clearTimeout(destroyTimerRef.current);
+      destroyTimerRef.current = null;
+    }
+
+    const subs = new Subscription();
+    subs.add(handle.results$.subscribe(r => setResults(r)));
+    subs.add(handle.state$.subscribe(s => setState(s)));
+    subs.add(handle.error$.subscribe(e => setError(e)));
+    subs.add(handle.hasMore$.subscribe(h => setHasMore(h)));
+    return () => {
+      subs.unsubscribe();
+      destroyTimerRef.current = setTimeout(() => {
+        handle.destroy();
+        handleRef.current = null;
+        destroyTimerRef.current = null;
+      }, 0);
+    };
+    // handle 生命周期由 ref 管理，仅挂载时订阅一次
+  }, []);
+
+  const setQuery = useCallback(
+    (q: string) => {
+      setQueryState(q);
+      handle.setQuery(q);
+    },
+    [handle]
+  );
+
+  const clear = useCallback(() => {
+    setQueryState('');
+    handle.clear();
+  }, [handle]);
+
+  const retry = useCallback(() => handle.retry(), [handle]);
+  const loadMore = useCallback(() => handle.loadMore(), [handle]);
+
+  return useMemo(
+    () => ({ query, setQuery, results, state, error, hasMore, loadMore, clear, retry }),
+    [query, setQuery, results, state, error, hasMore, loadMore, clear, retry]
+  );
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "types": ["node", "vite/client"],
+    "rootDir": "src",
+    "jsx": "react-jsx",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo"
+  },
+  "exclude": [
+    "out-tsc",
+    "dist",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.spec.tsx",
+    "**/*.test.tsx",
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "eslint.config.js",
+    "eslint.config.cjs",
+    "eslint.config.mjs"
+  ],
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "references": [
+    {
+      "path": "../rxdb-plugin-search/tsconfig.lib.json"
+    },
+    {
+      "path": "../rxdb/tsconfig.lib.json"
+    }
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "types": ["vitest/globals", "vitest/importMeta", "vite/client", "node", "vitest"],
+    "jsx": "react-jsx",
+    "module": "esnext",
+    "moduleResolution": "bundler"
+  },
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/vite.config.mts

@@ -0,0 +1,55 @@
+/// <reference types='vitest' />
+import { codecovVitePlugin } from '@codecov/vite-plugin';
+import react from '@vitejs/plugin-react';
+import * as path from 'path';
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig(() => ({
+  root: import.meta.dirname,
+  cacheDir: '../../node_modules/.vite/packages/rxdb-plugin-search-react',
+  plugins: [
+    react(),
+    dts({ entryRoot: 'src', tsconfigPath: path.join(import.meta.dirname, 'tsconfig.lib.json') }),
+    ...(process.env.CI === 'true' && process.env.CODECOV_TOKEN ?
+      [
+        codecovVitePlugin({
+          enableBundleAnalysis: true,
+          telemetry: false,
+          bundleName: 'rxdb-plugin-search-react',
+          uploadToken: process.env.CODECOV_TOKEN
+        })
+      ]
+    : [])
+  ],
+  build: {
+    outDir: './dist',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true
+    },
+    lib: {
+      entry: 'src/index.ts',
+      name: 'rxdb-plugin-search-react',
+      fileName: 'index',
+      formats: ['es' as const]
+    },
+    rollupOptions: {
+      external: [/^@aiao\//, 'react', 'react-dom', 'react/jsx-runtime', 'rxjs']
+    }
+  },
+  test: {
+    name: 'rxdb-plugin-search-react',
+    watch: false,
+    globals: true,
+    environment: 'jsdom',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    passWithNoTests: true,
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const
+    }
+  }
+}));