@aiao/rxdb-plugin-search-react 0.0.20 → 0.0.22

package/REVIEW.md

@@ -0,0 +1,23 @@
+# `@aiao/rxdb-plugin-search-react` 代码评审
+
+## 结论
+
+🔴 不通过。`useSearch()` 宣称 source 变化时重建 handle，但实际把首次 source 永久锁进 ref；组件切换数据库/collection 后仍订阅和查询旧 source。
+
+## 评审基线
+
+- 基线提交：`03a46a5d5992a958c19ae33d5fed15c9c3322021`
+- 评审日期：2026-07-14
+- 范围：React 搜索 hook、测试、公开入口；10 个文件，约 311 行 TS
+- 自动校验：`lint`、`test`、`typecheck`、`build` 全部通过
+
+## 问题
+
+| ID | 级别 | 位置 | 问题与影响 | 建议 |
+| --- | --- | --- | --- | --- |
+| SEARCH-REACT-001 | P1 | `src/use-search.ts:67` | `handleRef` 只在 null 时用 source 创建，订阅 effect 的依赖数组为空；rerender 传入新 source/options 时，hook 仍对旧 handle 调用 setQuery/loadMore，并显示旧数据库结果。源码注释“仅在 source 变化时重建”与实现相反。 | 用 source/稳定 options key 作为 handle 生命周期依赖，切换时先取消旧订阅并 destroy 旧 handle；增加 rerender source A→B 后只能调用 B 的测试。 |
+
+## 三端对称性
+
+- 共享类型透传与 Vue/Angular 一致；运行时入口 `useSearch` 符合 React 约定。
+- source 切换语义目前不可靠，是此三端组唯一 P1。

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  *
  * @packageDocumentation
  */
+export type { SearchExecutionError, SearchHandle, SearchOptions, SearchResult, SearchState } from '@aiao/rxdb-plugin-search';
 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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -2,24 +2,35 @@
 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);
+function o(e, t) {
+	return e === t ? !0 : e === void 0 || t === void 0 || e.length !== t.length ? !1 : e.every((e, n) => e === t[n]);
+}
+function s(e, t) {
+	return e === t ? !0 : e === void 0 || t === void 0 ? !1 : e.debounce === t.debounce && e.pageSize === t.pageSize && e.snippetLength === t.snippetLength && e.initialQuery === t.initialQuery && o(e.collections, t.collections);
+}
+function c(e) {
+	let t = r(e);
+	return s(t.current, e) || (t.current = e), t.current;
+}
+function l(o, s) {
+	let l = c(s), u = l?.initialQuery ?? "", d = r(null), [f, p] = i(u), [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 e = o.search(u, l);
+		d.current = e, p(u);
+		let t = new a();
+		return t.add(e.results$.subscribe((e) => h(e))), t.add(e.state$.subscribe((e) => _(e))), t.add(e.error$.subscribe((e) => y(e))), t.add(e.hasMore$.subscribe((e) => x(e))), () => {
+			t.unsubscribe(), e.destroy(), d.current === e && (d.current = null);
 		};
-	}, []);
+	}, [
+		o,
+		l,
+		u
+	]);
 	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]);
+		p(e), d.current?.setQuery(e);
+	}, []), C = e(() => {
+		p(""), d.current?.clear();
+	}, []), w = e(() => d.current?.retry(), []), T = e(() => d.current?.loadMore() ?? Promise.resolve(), []);
 	return n(() => ({
 		query: f,
 		setQuery: S,
@@ -43,4 +54,4 @@ function o(o, s) {
 	]);
 }
 //#endregion
-export { o as useSearch };
+export { l as useSearch };

package/dist/use-search.d.ts

@@ -1,4 +1,4 @@
-import { SearchExecutionError, SearchOptions, SearchResult, SearchSourceLike, SearchState } from '../packages/rxdb-plugin-search/src/index.ts';
+import { SearchExecutionError, SearchOptions, SearchResult, SearchSourceLike, SearchState } from '@aiao/rxdb-plugin-search';
 /**
  * React 集成 - rxdb-plugin-search
  *

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

@@ -1 +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"}
+{"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;AA0BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,eAAe,CAgD5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiao/rxdb-plugin-search-react",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -15,13 +15,13 @@
     }
   },
   "dependencies": {
-    "@aiao/rxdb-plugin-search": "0.0.20"
+    "@aiao/rxdb-plugin-search": "0.0.22"
   },
   "peerDependencies": {
     "@aiao/rxdb": "*",
-    "react": ">=18.0.0",
+    "react": "^19.2.7",
     "rxjs": "^7.8.2",
-    "@aiao/rxdb-plugin-search": "0.0.20"
+    "@aiao/rxdb-plugin-search": "0.0.22"
   },
   "publishConfig": {
     "access": "public"

package/src/index.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import type { SearchExecutionError, SearchHandle, SearchOptions, SearchResult, SearchState } from './index.js';
+
+type PublicSearchApi = {
+  error: SearchExecutionError | undefined;
+  handle: SearchHandle;
+  options: SearchOptions;
+  result: SearchResult;
+  state: SearchState;
+};
+
+describe('React public search API', () => {
+  it('exposes the core search types from the package entrypoint', () => {
+    const contract: PublicSearchApi | undefined = undefined;
+    expect(contract).toBeUndefined();
+  });
+});

package/src/index.ts

@@ -8,5 +8,12 @@
  * @packageDocumentation
  */
 
+export type {
+  SearchExecutionError,
+  SearchHandle,
+  SearchOptions,
+  SearchResult,
+  SearchState
+} from '@aiao/rxdb-plugin-search';
 export { useSearch } from './use-search.js';
 export type { SearchSourceLike, UseSearchReturn } from './use-search.js';

package/src/use-search.spec.ts

@@ -148,4 +148,77 @@ describe('useSearch (React binding, T039)', () => {
     renderHook(() => useSearch(src, { initialQuery: 'hi' }));
     expect(src.searchSpy).toHaveBeenCalledWith('hi', { initialQuery: 'hi' });
   });
+
+  it('rebuilds the handle when source changes', () => {
+    vi.useFakeTimers();
+    const first = makeHandle();
+    const second = makeHandle();
+    const firstSource = makeSource(first.handle);
+    const secondSource = makeSource(second.handle);
+    const { result, rerender } = renderHook(({ source }) => useSearch(source), {
+      initialProps: { source: firstSource as SearchSourceLike }
+    });
+
+    rerender({ source: secondSource });
+    act(() => vi.runAllTimers());
+    act(() => result.current.setQuery('next'));
+
+    expect(first.destroyed.value).toBe(true);
+    expect(first.setQuery).not.toHaveBeenCalled();
+    expect(secondSource.searchSpy).toHaveBeenCalledTimes(1);
+    expect(second.setQuery).toHaveBeenCalledWith('next');
+  });
+
+  it('does not rebuild for a semantically identical inline options object', () => {
+    vi.useFakeTimers();
+    const h = makeHandle();
+    const src = makeSource(h.handle);
+    const { rerender } = renderHook(() => useSearch(src, { debounce: 10, collections: ['Todo'] }));
+
+    rerender();
+    act(() => vi.runAllTimers());
+
+    expect(src.searchSpy).toHaveBeenCalledTimes(1);
+    expect(h.destroyed.value).toBe(false);
+  });
+
+  it('routes calls to the latest handle even via a callback captured before rebuild', () => {
+    vi.useFakeTimers();
+    const first = makeHandle();
+    const second = makeHandle();
+    const firstSource = makeSource(first.handle);
+    const secondSource = makeSource(second.handle);
+    const { result, rerender } = renderHook(({ source }) => useSearch(source), {
+      initialProps: { source: firstSource as SearchSourceLike }
+    });
+    const staleSetQuery = result.current.setQuery;
+
+    rerender({ source: secondSource });
+    act(() => vi.runAllTimers());
+
+    act(() => staleSetQuery('after-rebuild'));
+
+    expect(second.setQuery).toHaveBeenCalledWith('after-rebuild');
+    expect(first.setQuery).not.toHaveBeenCalled();
+  });
+
+  it('keeps stable setQuery/clear/retry/loadMore identities across handle rebuilds', () => {
+    vi.useFakeTimers();
+    const first = makeHandle();
+    const second = makeHandle();
+    const firstSource = makeSource(first.handle);
+    const secondSource = makeSource(second.handle);
+    const { result, rerender } = renderHook(({ source }) => useSearch(source), {
+      initialProps: { source: firstSource as SearchSourceLike }
+    });
+    const { setQuery, clear, retry, loadMore } = result.current;
+
+    rerender({ source: secondSource });
+    act(() => vi.runAllTimers());
+
+    expect(result.current.setQuery).toBe(setQuery);
+    expect(result.current.clear).toBe(clear);
+    expect(result.current.retry).toBe(retry);
+    expect(result.current.loadMore).toBe(loadMore);
+  });
 });

package/src/use-search.ts

@@ -49,6 +49,30 @@ export interface UseSearchReturn {
   retry: () => void;
 }
 
+function collectionsEqual(left: readonly string[] | undefined, right: readonly string[] | undefined): boolean {
+  if (left === right) return true;
+  if (left === undefined || right === undefined || left.length !== right.length) return false;
+  return left.every((value, index) => value === right[index]);
+}
+
+function searchOptionsEqual(left: SearchOptions | undefined, right: SearchOptions | undefined): boolean {
+  if (left === right) return true;
+  if (left === undefined || right === undefined) return false;
+  return (
+    left.debounce === right.debounce &&
+    left.pageSize === right.pageSize &&
+    left.snippetLength === right.snippetLength &&
+    left.initialQuery === right.initialQuery &&
+    collectionsEqual(left.collections, right.collections)
+  );
+}
+
+function useStableSearchOptions(options: SearchOptions | undefined): SearchOptions | undefined {
+  const stableOptions = useRef(options);
+  if (!searchOptionsEqual(stableOptions.current, options)) stableOptions.current = options;
+  return stableOptions.current;
+}
+
 /**
  * 将 `SearchHandle` 的响应式输出适配为 React hook。
  *
@@ -63,15 +87,10 @@ export interface UseSearchReturn {
  * @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 stableOptions = useStableSearchOptions(options);
+  const initial = stableOptions?.initialQuery ?? '';
 
+  const handleRef = useRef<SearchHandle | null>(null);
   const [query, setQueryState] = useState<string>(initial);
   const [results, setResults] = useState<readonly SearchResult[]>([]);
   const [state, setState] = useState<SearchState>('idle');
@@ -79,42 +98,37 @@ export function useSearch(source: SearchSourceLike, options?: SearchOptions): Us
   const [hasMore, setHasMore] = useState<boolean>(false);
 
   useEffect(() => {
-    if (destroyTimerRef.current !== null) {
-      clearTimeout(destroyTimerRef.current);
-      destroyTimerRef.current = null;
-    }
+    // handle 是命令式控制器，不参与渲染，存入 ref 而非 state：
+    // 避免 handle 变化触发多余的重渲染，并让 setQuery/clear/retry/loadMore
+    // 始终读取最新 handle，不会在 rebuild 后仍调用到已销毁的旧实例。
+    const newHandle = source.search(initial, stableOptions);
+    handleRef.current = newHandle;
+    setQueryState(initial);
 
     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)));
+    subs.add(newHandle.results$.subscribe(r => setResults(r)));
+    subs.add(newHandle.state$.subscribe(s => setState(s)));
+    subs.add(newHandle.error$.subscribe(e => setError(e)));
+    subs.add(newHandle.hasMore$.subscribe(h => setHasMore(h)));
     return () => {
       subs.unsubscribe();
-      destroyTimerRef.current = setTimeout(() => {
-        handle.destroy();
-        handleRef.current = null;
-        destroyTimerRef.current = null;
-      }, 0);
+      newHandle.destroy();
+      if (handleRef.current === newHandle) handleRef.current = null;
     };
-    // handle 生命周期由 ref 管理，仅挂载时订阅一次
-  }, []);
+  }, [source, stableOptions, initial]);
 
-  const setQuery = useCallback(
-    (q: string) => {
-      setQueryState(q);
-      handle.setQuery(q);
-    },
-    [handle]
-  );
+  const setQuery = useCallback((q: string) => {
+    setQueryState(q);
+    handleRef.current?.setQuery(q);
+  }, []);
 
   const clear = useCallback(() => {
     setQueryState('');
-    handle.clear();
-  }, [handle]);
+    handleRef.current?.clear();
+  }, []);
 
-  const retry = useCallback(() => handle.retry(), [handle]);
-  const loadMore = useCallback(() => handle.loadMore(), [handle]);
+  const retry = useCallback(() => handleRef.current?.retry(), []);
+  const loadMore = useCallback(() => handleRef.current?.loadMore() ?? Promise.resolve(), []);
 
   return useMemo(
     () => ({ query, setQuery, results, state, error, hasMore, loadMore, clear, retry }),

package/tsconfig.json

@@ -1,4 +1,7 @@
 {
+  "compilerOptions": {
+    "ignoreDeprecations": "6.0"
+  },
   "extends": "../../tsconfig.base.json",
   "files": [],
   "include": [],

package/tsconfig.spec.json

@@ -4,7 +4,8 @@
     "types": ["vitest/globals", "vitest/importMeta", "vite/client", "node", "vitest"],
     "jsx": "react-jsx",
     "module": "esnext",
-    "moduleResolution": "bundler"
+    "moduleResolution": "bundler",
+    "rootDir": "."
   },
   "extends": "../../tsconfig.base.json",
   "include": [

package/vite.config.mts

@@ -10,7 +10,11 @@ export default defineConfig(() => ({
   cacheDir: '../../node_modules/.vite/packages/rxdb-plugin-search-react',
   plugins: [
     react(),
-    dts({ entryRoot: 'src', tsconfigPath: path.join(import.meta.dirname, 'tsconfig.lib.json') }),
+    dts({
+      entryRoot: 'src',
+      pathsToAliases: false,
+      tsconfigPath: path.join(import.meta.dirname, 'tsconfig.lib.json')
+    }),
     ...(process.env.CI === 'true' && process.env.CODECOV_TOKEN ?
       [
         codecovVitePlugin({
@@ -35,7 +39,9 @@ export default defineConfig(() => ({
       fileName: 'index',
       formats: ['es' as const]
     },
-    rollupOptions: {
+    rolldownOptions: {
+      // dts 插件生成声明文件天然比 Rolldown 原生链接阶段慢，抑制误报的 PLUGIN_TIMINGS 警告
+      checks: { pluginTimings: false },
       external: [/^@aiao\//, 'react', 'react-dom', 'react/jsx-runtime', 'rxjs']
     }
   },
@@ -45,7 +51,6 @@ export default defineConfig(() => ({
     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',