@aiao/rxdb-react 0.0.7

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/README.md

@@ -0,0 +1 @@
+# rxdb-react

package/dist/hooks.d.ts

@@ -0,0 +1,163 @@
+import { EntityStaticType, EntityType } from '../../rxdb/src/index.ts';
+type UseOptions<T> = T | (() => T);
+export interface RxDBResource<T> {
+    /**
+     * 资源的数值
+     */
+    readonly value: T;
+    /**
+     * 资源的错误
+     */
+    readonly error: Error | undefined;
+    /**
+     * 资源的加载状态
+     */
+    readonly isLoading: boolean;
+    /**
+     * 资源的空状态
+     */
+    readonly isEmpty: boolean | undefined;
+    /**
+     * 资源是否具有数值
+     */
+    readonly hasValue: boolean;
+}
+/**
+ * 通过 ID 获取单个实体
+ *
+ * @param EntityType 实体类
+ * @param options 实体的 ID 或选项对象
+ * @returns 包含实体、加载状态和错误的资源对象
+ *
+ * @example
+ * ```typescript
+ * const { value: user, isLoading } = useGet(User, 'user-1');
+ * ```
+ */
+export declare const useGet: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "getOptions">>) => RxDBResource<InstanceType<T> | undefined>;
+/**
+ * Find one entity matching the criteria
+ *
+ * @param EntityType The entity class
+ * @param options Query options (where clause, sort, etc.)
+ * @returns A resource object containing the entity
+ *
+ * @example
+ * ```typescript
+ * const { value: user } = useFindOne(User, { where: { name: 'Alice' } });
+ * ```
+ */
+export declare const useFindOne: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findOneOptions">>) => RxDBResource<InstanceType<T> | undefined>;
+/**
+ * Find one entity or throw an error if not found
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing the entity
+ */
+export declare const useFindOneOrFail: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findOneOrFailOptions">>) => RxDBResource<InstanceType<T> | undefined>;
+/**
+ * Find multiple entities matching the criteria
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing an array of entities
+ *
+ * @example
+ * ```typescript
+ * const { value: users } = useFind(User, { where: { age: { $gt: 18 } } });
+ * ```
+ */
+export declare const useFind: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findOptions">>) => RxDBResource<InstanceType<T>[]>;
+/**
+ * Find all entities
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing all entities
+ */
+export declare const useFindAll: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findAllOptions">>) => RxDBResource<InstanceType<T>[]>;
+/**
+ * Count entities matching the criteria
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing the count
+ */
+export declare const useCount: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "countOptions">>) => RxDBResource<number>;
+/**
+ * Find all descendant entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options (entityId, depth, etc.)
+ * @returns A resource object containing descendant entities
+ */
+export declare const useFindDescendants: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findTreeOptions">>) => RxDBResource<InstanceType<T>[]>;
+/**
+ * Count descendant entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options
+ * @returns A resource object containing the count
+ */
+export declare const useCountDescendants: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findTreeOptions">>) => RxDBResource<number>;
+/**
+ * Find all ancestor entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options
+ * @returns A resource object containing ancestor entities
+ */
+export declare const useFindAncestors: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findTreeOptions">>) => RxDBResource<InstanceType<T>[]>;
+/**
+ * Count ancestor entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options
+ * @returns A resource object containing the count
+ */
+export declare const useCountAncestors: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findTreeOptions">>) => RxDBResource<number>;
+/**
+ * Find neighbor entities in a graph structure
+ *
+ * @param EntityType The entity class
+ * @param options Graph query options (entityId, direction, level, etc.)
+ * @returns A resource object containing neighbor entities
+ *
+ * @example
+ * ```typescript
+ * const { value: friends } = useGraphNeighbors(User, {
+ *   entityId: 'user-1',
+ *   direction: 'out',
+ *   level: 1
+ * });
+ * ```
+ */
+export declare const useGraphNeighbors: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findNeighborsOptions">>) => RxDBResource<InstanceType<T>[]>;
+/**
+ * Count neighbor entities in a graph structure
+ *
+ * @param EntityType The entity class
+ * @param options Graph query options
+ * @returns A resource object containing the count
+ */
+export declare const useCountNeighbors: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findNeighborsOptions">>) => RxDBResource<number>;
+/**
+ * Find paths between two entities in a graph
+ *
+ * @param EntityType The entity class
+ * @param options Path query options (fromId, toId, maxDepth, etc.)
+ * @returns A resource object containing paths
+ *
+ * @example
+ * ```typescript
+ * const { value: paths } = useGraphPaths(User, {
+ *   fromId: 'user-1',
+ *   toId: 'user-2',
+ *   maxDepth: 5
+ * });
+ * ```
+ */
+export declare const useGraphPaths: <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, "findPathsOptions">>) => RxDBResource<any[]>;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hooks';
+export * from './rxdb-react';
+//# 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":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,72 @@
+import { isFunction as m } from "@aiao/utils";
+import { useState as i, useRef as h, useMemo as F, useEffect as A, createContext as B, useContext as E } from "react";
+import { jsx as O } from "react/jsx-runtime";
+const s = (r, e, o, c) => {
+  const [D, R] = i(o), [b, d] = i(void 0), [g, f] = i(!0), [p, l] = i(void 0), [y, v] = i(!1), t = h(void 0), u = h(!0), x = F(() => m(c) ? c() : c, [c]);
+  return A(() => {
+    u.current = !0, t.current && (t.current.unsubscribe(), t.current = void 0);
+    const a = r[e];
+    if (!a || typeof a != "function") {
+      const n = new Error(`Method "${String(e)}" not found on EntityType`);
+      Promise.resolve().then(() => {
+        u.current && (d(n), f(!1));
+      });
+      return;
+    }
+    try {
+      t.current = a(x).subscribe({
+        next: (n) => {
+          u.current && (f(!1), v(!0), d(void 0), Array.isArray(n) ? l(n.length === 0) : l(n == null), R(n));
+        },
+        error: (n) => {
+          u.current && (f(!1), v(!1), d(n), console.error(`RxDB query error in ${String(e)}:`, n));
+        }
+      });
+    } catch (n) {
+      const P = n instanceof Error ? n : new Error(String(n));
+      Promise.resolve().then(() => {
+        u.current && (f(!1), d(P));
+      });
+    }
+    return () => {
+      u.current = !1, t.current && (t.current.unsubscribe(), t.current = void 0);
+    };
+  }, [r, e, x]), {
+    value: D,
+    error: b,
+    isLoading: g,
+    isEmpty: p,
+    hasValue: y
+  };
+}, S = (r, e) => s(r, "get", void 0, e), G = (r, e) => s(r, "findOne", void 0, e), V = (r, e) => s(r, "findOneOrFail", void 0, e), q = (r, e) => s(r, "find", [], e), I = (r, e) => s(r, "findAll", [], e), L = (r, e) => s(r, "count", 0, e), $ = (r, e) => s(r, "findDescendants", [], e), j = (r, e) => s(r, "countDescendants", 0, e), k = (r, e) => s(r, "findAncestors", [], e), H = (r, e) => s(r, "countAncestors", 0, e), Q = (r, e) => s(r, "findNeighbors", [], e), z = (r, e) => s(r, "countNeighbors", 0, e), J = (r, e) => s(r, "findPaths", [], e);
+function C() {
+  const r = B(void 0);
+  return {
+    useRxDB: ((e) => {
+      const o = E(r);
+      if (e !== void 0) return e;
+      if (!o) throw new Error("No RxDB instance found, use RxDBProvider to provide one");
+      return o;
+    }),
+    RxDBProvider: ({ children: e, db: o }) => /* @__PURE__ */ O(r.Provider, { value: o, children: e })
+  };
+}
+const { RxDBProvider: K, useRxDB: T } = C();
+export {
+  K as RxDBProvider,
+  C as makeRxDBProvider,
+  L as useCount,
+  H as useCountAncestors,
+  j as useCountDescendants,
+  z as useCountNeighbors,
+  q as useFind,
+  I as useFindAll,
+  k as useFindAncestors,
+  $ as useFindDescendants,
+  G as useFindOne,
+  V as useFindOneOrFail,
+  S as useGet,
+  Q as useGraphNeighbors,
+  J as useGraphPaths,
+  T as useRxDB
+};

package/dist/rxdb-react.d.ts

@@ -0,0 +1,19 @@
+import { RxDB } from '../../rxdb/src/index.ts';
+import { default as React } from 'react';
+interface Props<T extends RxDB> {
+    children?: React.ReactNode;
+    db?: T;
+}
+type RxDBProviderType<T extends RxDB> = (props: Props<T>) => React.JSX.Element;
+type UseRxDB<T extends RxDB> = (db?: T) => T;
+interface RxDBProviderSet<T extends RxDB> {
+    RxDBProvider: RxDBProviderType<T>;
+    useRxDB: UseRxDB<T>;
+}
+/**
+ * RxDB 依赖注入
+ */
+declare function makeRxDBProvider<T extends RxDB>(): RxDBProviderSet<T>;
+declare const RxDBProvider: RxDBProviderType<RxDB>, useRxDB: UseRxDB<RxDB>;
+export { makeRxDBProvider, RxDBProvider, useRxDB };
+//# sourceMappingURL=rxdb-react.d.ts.map

package/dist/rxdb-react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rxdb-react.d.ts","sourceRoot":"","sources":["../src/rxdb-react.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,KAAoC,MAAM,OAAO,CAAC;AAEzD,UAAU,KAAK,CAAC,CAAC,SAAS,IAAI;IAC5B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,EAAE,CAAC,EAAE,CAAC,CAAC;CACR;AAED,KAAK,gBAAgB,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;AAC/E,KAAK,OAAO,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAE7C,UAAU,eAAe,CAAC,CAAC,SAAS,IAAI;IACtC,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,iBAAS,gBAAgB,CAAC,CAAC,SAAS,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,CAc9D;AAED,QAAA,MAAQ,YAAY,0BAAE,OAAO,eAA6B,CAAC;AAE3D,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC"}

package/eslint.config.mjs

@@ -0,0 +1,12 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  ...nx.configs['flat/react'],
+  {
+    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+    // Override or add rules here
+    rules: {}
+  }
+];

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@aiao/rxdb-react",
+  "version": "0.0.7",
+  "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": "0.0.7",
+    "@aiao/utils": "0.0.7"
+  },
+  "nx": {
+    "name": "rxdb-react",
+    "tags": [
+      "react-lib"
+    ]
+  }
+}

package/src/hooks.spec.ts

@@ -0,0 +1,127 @@
+import { of } from 'rxjs';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { useFind, useFindOne, useGet } from './hooks';
+
+// Mock React hooks
+let mockState: any[] = [];
+let mockStateIndex = 0;
+let mockEffectCleanups: Array<() => void> = [];
+
+vi.mock('react', () => ({
+  useState: (initial: any) => {
+    const index = mockStateIndex++;
+    if (mockState[index] === undefined) {
+      mockState[index] = initial;
+    }
+    const setState = (newValue: any) => {
+      mockState[index] = typeof newValue === 'function' ? newValue(mockState[index]) : newValue;
+    };
+    return [mockState[index], setState];
+  },
+  useEffect: (effect: () => any) => {
+    const cleanup = effect();
+    if (cleanup) mockEffectCleanups.push(cleanup);
+  },
+  useRef: (initial: any) => ({ current: initial }),
+  useMemo: (fn: () => any, deps: any[]) => fn()
+}));
+
+// Mock entity type
+class MockEntity {
+  id!: string;
+  name!: string;
+  static get = vi.fn();
+  static findOne = vi.fn();
+  static find = vi.fn();
+}
+
+describe('useGet', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockState = [];
+    mockStateIndex = 0;
+    mockEffectCleanups = [];
+  });
+
+  it('should initialize hook with default state', () => {
+    const mockData = { id: '1', name: 'Test' };
+    MockEntity.get.mockReturnValue(of(mockData));
+
+    const result = useGet(MockEntity as any, '1');
+
+    expect(result).toBeDefined();
+    expect(typeof result.isLoading).toBe('boolean');
+    expect(typeof result.hasValue).toBe('boolean');
+  });
+
+  it('should call entity method with correct options', () => {
+    MockEntity.get.mockReturnValue(of({ id: '1', name: 'Test' }));
+
+    useGet(MockEntity as any, '1');
+
+    expect(MockEntity.get).toHaveBeenCalledWith('1');
+  });
+
+  it('should accept function as options', () => {
+    MockEntity.get.mockReturnValue(of({ id: '2', name: 'Dynamic' }));
+
+    useGet(MockEntity as any, () => '2');
+
+    expect(MockEntity.get).toHaveBeenCalledWith('2');
+  });
+});
+
+describe('useFindOne', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockState = [];
+    mockStateIndex = 0;
+    mockEffectCleanups = [];
+  });
+
+  it('should call findOne method', () => {
+    MockEntity.findOne.mockReturnValue(of({ id: '1', name: 'Found' }));
+
+    useFindOne(MockEntity as any, { where: { name: 'Found' } });
+
+    expect(MockEntity.findOne).toHaveBeenCalledWith({ where: { name: 'Found' } });
+  });
+});
+
+describe('useFind', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockState = [];
+    mockStateIndex = 0;
+    mockEffectCleanups = [];
+  });
+
+  it('should call find method', () => {
+    const mockData = [
+      { id: '1', name: 'User1' },
+      { id: '2', name: 'User2' }
+    ];
+    MockEntity.find.mockReturnValue(of(mockData));
+
+    useFind(MockEntity as any, {});
+
+    expect(MockEntity.find).toHaveBeenCalled();
+  });
+});
+
+describe('Hook cleanup', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockState = [];
+    mockStateIndex = 0;
+    mockEffectCleanups = [];
+  });
+
+  it('should register cleanup function', () => {
+    MockEntity.get.mockReturnValue(of({ id: '1' }));
+
+    useGet(MockEntity as any, '1');
+
+    expect(mockEffectCleanups.length).toBeGreaterThan(0);
+  });
+});

package/src/hooks.ts

@@ -0,0 +1,343 @@
+import { EntityStaticType, EntityType } from '@aiao/rxdb';
+import { isFunction } from '@aiao/utils';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Subscription } from 'rxjs';
+
+type UseOptions<T> = T | (() => T);
+
+export interface RxDBResource<T> {
+  /**
+   * 资源的数值
+   */
+  readonly value: T;
+  /**
+   * 资源的错误
+   */
+  readonly error: Error | undefined;
+  /**
+   * 资源的加载状态
+   */
+  readonly isLoading: boolean;
+  /**
+   * 资源的空状态
+   */
+  readonly isEmpty: boolean | undefined;
+  /**
+   * 资源是否具有数值
+   */
+  readonly hasValue: boolean;
+}
+
+/**
+ * RxDB 仓库查询的核心钩子实现
+ * 管理响应式订阅和状态更新
+ */
+const useRepositoryQuery = <T extends EntityType, RT>(
+  EntityType: T,
+  method: string,
+  defaultValue: RT,
+  options: UseOptions<any>
+): RxDBResource<RT> => {
+  // 状态管理
+  const [value, setValue] = useState<RT>(defaultValue);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [isEmpty, setIsEmpty] = useState<boolean | undefined>(undefined);
+  const [hasValue, setHasValue] = useState<boolean>(false);
+
+  // 订阅管理
+  const subscriptionRef = useRef<Subscription | undefined>(undefined);
+  const isMountedRef = useRef(true);
+
+  const resolvedOptions = useMemo(() => {
+    return isFunction(options) ? options() : options;
+  }, [options]);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+
+    // 清理之前的订阅
+    if (subscriptionRef.current) {
+      subscriptionRef.current.unsubscribe();
+      subscriptionRef.current = undefined;
+    }
+
+    // 从 EntityType 获取方法
+    // 优化：使用 Record<string, any> 替代 any，以提高类型安全性
+    const queryMethod = (EntityType as unknown as Record<string, any>)[method];
+
+    if (!queryMethod || typeof queryMethod !== 'function') {
+      const err = new Error(`Method "${String(method)}" not found on EntityType`);
+      Promise.resolve().then(() => {
+        if (isMountedRef.current) {
+          setError(err);
+          setIsLoading(false);
+        }
+      });
+      return;
+    }
+
+    // 执行查询并订阅结果
+    try {
+      subscriptionRef.current = queryMethod(resolvedOptions).subscribe({
+        next: (data: RT) => {
+          if (!isMountedRef.current) return;
+
+          setIsLoading(false);
+          setHasValue(true);
+          setError(undefined);
+
+          // 为数组更新空状态
+          if (Array.isArray(data)) {
+            setIsEmpty(data.length === 0);
+          } else {
+            setIsEmpty(data == null);
+          }
+
+          setValue(data);
+        },
+        error: (err: Error) => {
+          if (!isMountedRef.current) return;
+
+          setIsLoading(false);
+          setHasValue(false);
+          setError(err);
+          console.error(`RxDB query error in ${String(method)}:`, err);
+        }
+      });
+    } catch (err) {
+      // 延迟状态更新以避免在 effect 中同步 setState
+      const error = err instanceof Error ? err : new Error(String(err));
+      Promise.resolve().then(() => {
+        if (isMountedRef.current) {
+          setIsLoading(false);
+          setError(error);
+        }
+      });
+    }
+
+    // 清理函数
+    return () => {
+      isMountedRef.current = false;
+      if (subscriptionRef.current) {
+        subscriptionRef.current.unsubscribe();
+        subscriptionRef.current = undefined;
+      }
+    };
+  }, [EntityType, method, resolvedOptions]);
+
+  return {
+    value,
+    error,
+    isLoading,
+    isEmpty,
+    hasValue
+  };
+};
+
+/*
+ * 仓库钩子
+ */
+
+/**
+ * 通过 ID 获取单个实体
+ *
+ * @param EntityType 实体类
+ * @param options 实体的 ID 或选项对象
+ * @returns 包含实体、加载状态和错误的资源对象
+ *
+ * @example
+ * ```typescript
+ * const { value: user, isLoading } = useGet(User, 'user-1');
+ * ```
+ */
+export const useGet = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'getOptions'>>
+): RxDBResource<InstanceType<T> | undefined> =>
+  useRepositoryQuery<T, InstanceType<T> | undefined>(EntityType, 'get', undefined, options);
+
+/**
+ * Find one entity matching the criteria
+ *
+ * @param EntityType The entity class
+ * @param options Query options (where clause, sort, etc.)
+ * @returns A resource object containing the entity
+ *
+ * @example
+ * ```typescript
+ * const { value: user } = useFindOne(User, { where: { name: 'Alice' } });
+ * ```
+ */
+export const useFindOne = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findOneOptions'>>
+): RxDBResource<InstanceType<T> | undefined> =>
+  useRepositoryQuery<T, InstanceType<T> | undefined>(EntityType, 'findOne', undefined, options);
+
+/**
+ * Find one entity or throw an error if not found
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing the entity
+ */
+export const useFindOneOrFail = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findOneOrFailOptions'>>
+): RxDBResource<InstanceType<T> | undefined> =>
+  useRepositoryQuery<T, InstanceType<T> | undefined>(EntityType, 'findOneOrFail', undefined, options);
+
+/**
+ * Find multiple entities matching the criteria
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing an array of entities
+ *
+ * @example
+ * ```typescript
+ * const { value: users } = useFind(User, { where: { age: { $gt: 18 } } });
+ * ```
+ */
+export const useFind = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findOptions'>>
+): RxDBResource<InstanceType<T>[]> => useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'find', [], options);
+
+/**
+ * Find all entities
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing all entities
+ */
+export const useFindAll = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findAllOptions'>>
+): RxDBResource<InstanceType<T>[]> => useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findAll', [], options);
+
+/**
+ * Count entities matching the criteria
+ *
+ * @param EntityType The entity class
+ * @param options Query options
+ * @returns A resource object containing the count
+ */
+export const useCount = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'countOptions'>>
+): RxDBResource<number> => useRepositoryQuery<T, number>(EntityType, 'count', 0, options);
+
+/*
+ * Tree Repository Hooks
+ */
+
+/**
+ * Find all descendant entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options (entityId, depth, etc.)
+ * @returns A resource object containing descendant entities
+ */
+export const useFindDescendants = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+): RxDBResource<InstanceType<T>[]> =>
+  useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findDescendants', [], options);
+
+/**
+ * Count descendant entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options
+ * @returns A resource object containing the count
+ */
+export const useCountDescendants = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+): RxDBResource<number> => useRepositoryQuery<T, number>(EntityType, 'countDescendants', 0, options);
+
+/**
+ * Find all ancestor entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options
+ * @returns A resource object containing ancestor entities
+ */
+export const useFindAncestors = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+): RxDBResource<InstanceType<T>[]> =>
+  useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findAncestors', [], options);
+
+/**
+ * Count ancestor entities in a tree structure
+ *
+ * @param EntityType The entity class
+ * @param options Tree query options
+ * @returns A resource object containing the count
+ */
+export const useCountAncestors = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+): RxDBResource<number> => useRepositoryQuery<T, number>(EntityType, 'countAncestors', 0, options);
+
+/*
+ * Graph Repository Hooks
+ */
+
+/**
+ * Find neighbor entities in a graph structure
+ *
+ * @param EntityType The entity class
+ * @param options Graph query options (entityId, direction, level, etc.)
+ * @returns A resource object containing neighbor entities
+ *
+ * @example
+ * ```typescript
+ * const { value: friends } = useGraphNeighbors(User, {
+ *   entityId: 'user-1',
+ *   direction: 'out',
+ *   level: 1
+ * });
+ * ```
+ */
+export const useGraphNeighbors = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findNeighborsOptions'>>
+): RxDBResource<InstanceType<T>[]> =>
+  useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findNeighbors', [], options);
+
+/**
+ * Count neighbor entities in a graph structure
+ *
+ * @param EntityType The entity class
+ * @param options Graph query options
+ * @returns A resource object containing the count
+ */
+export const useCountNeighbors = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findNeighborsOptions'>>
+): RxDBResource<number> => useRepositoryQuery<T, number>(EntityType, 'countNeighbors', 0, options);
+
+/**
+ * Find paths between two entities in a graph
+ *
+ * @param EntityType The entity class
+ * @param options Path query options (fromId, toId, maxDepth, etc.)
+ * @returns A resource object containing paths
+ *
+ * @example
+ * ```typescript
+ * const { value: paths } = useGraphPaths(User, {
+ *   fromId: 'user-1',
+ *   toId: 'user-2',
+ *   maxDepth: 5
+ * });
+ * ```
+ */
+export const useGraphPaths = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findPathsOptions'>>
+): RxDBResource<any[]> => useRepositoryQuery<T, any[]>(EntityType, 'findPaths', [], options);

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './hooks';
+export * from './rxdb-react';

package/src/rxdb-react.spec.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { makeRxDBProvider, RxDBProvider, useRxDB } from './rxdb-react';
+
+describe('makeRxDBProvider', () => {
+  it('should create RxDBProvider and useRxDB hook', () => {
+    const { RxDBProvider, useRxDB } = makeRxDBProvider();
+
+    expect(RxDBProvider).toBeDefined();
+    expect(useRxDB).toBeDefined();
+    expect(typeof RxDBProvider).toBe('function');
+    expect(typeof useRxDB).toBe('function');
+  });
+
+  it('should create context provider component', () => {
+    const mockDB = { name: 'test-db' } as any;
+    const { RxDBProvider } = makeRxDBProvider();
+
+    const element = React.createElement(RxDBProvider, { db: mockDB }, 'children');
+
+    expect(element).toBeDefined();
+    expect(element.type).toBe(RxDBProvider);
+  });
+});
+
+describe('Default exports', () => {
+  it('should export default RxDBProvider', () => {
+    expect(RxDBProvider).toBeDefined();
+    expect(typeof RxDBProvider).toBe('function');
+  });
+
+  it('should export default useRxDB', () => {
+    expect(useRxDB).toBeDefined();
+    expect(typeof useRxDB).toBe('function');
+  });
+
+  it('should export makeRxDBProvider function', () => {
+    expect(makeRxDBProvider).toBeDefined();
+    expect(typeof makeRxDBProvider).toBe('function');
+  });
+});

package/src/rxdb-react.tsx

@@ -0,0 +1,38 @@
+import { RxDB } from '@aiao/rxdb';
+import React, { createContext, useContext } from 'react';
+
+interface Props<T extends RxDB> {
+  children?: React.ReactNode;
+  db?: T;
+}
+
+type RxDBProviderType<T extends RxDB> = (props: Props<T>) => React.JSX.Element;
+type UseRxDB<T extends RxDB> = (db?: T) => T;
+
+interface RxDBProviderSet<T extends RxDB> {
+  RxDBProvider: RxDBProviderType<T>;
+  useRxDB: UseRxDB<T>;
+}
+
+/**
+ * RxDB 依赖注入
+ */
+function makeRxDBProvider<T extends RxDB>(): RxDBProviderSet<T> {
+  const ctx = createContext<T | undefined>(undefined);
+  return {
+    useRxDB: ((db?: T) => {
+      const dbProvided = useContext(ctx);
+      if (db !== undefined) return db;
+      if (!dbProvided) throw new Error('No RxDB instance found, use RxDBProvider to provide one');
+
+      return dbProvided;
+    }) as UseRxDB<T>,
+    RxDBProvider: ({ children, db }: Props<T>) => {
+      return <ctx.Provider value={db}>{children}</ctx.Provider>;
+    }
+  };
+}
+
+const { RxDBProvider, useRxDB } = makeRxDBProvider<RxDB>();
+
+export { makeRxDBProvider, RxDBProvider, useRxDB };

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,48 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "types": ["node", "@nx/react/typings/cssmodule.d.ts", "@nx/react/typings/image.d.ts", "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",
+    "**/*.spec.js",
+    "**/*.test.js",
+    "**/*.spec.jsx",
+    "**/*.test.jsx",
+    "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/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "eslint.config.js",
+    "eslint.config.cjs",
+    "eslint.config.mjs"
+  ],
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.js", "src/**/*.jsx", "src/**/*.ts", "src/**/*.tsx"],
+  "references": [
+    {
+      "path": "../utils/tsconfig.lib.json"
+    },
+    {
+      "path": "../rxdb/tsconfig.lib.json"
+    }
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,30 @@
+{
+  "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/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/vite.config.ts

@@ -0,0 +1,80 @@
+/// <reference types='vitest' />
+import { codecovVitePlugin } from '@codecov/vite-plugin';
+import react from '@vitejs/plugin-react';
+import * as path from 'path';
+import dts from 'vite-plugin-dts';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/packages/rxdb-react',
+  plugins: [
+    react(),
+    dts({ entryRoot: 'src', tsconfigPath: path.join(__dirname, 'tsconfig.lib.json') }),
+    // Codecov Bundle Analysis - 仅在 CI 环境中启用
+    // TECH DEBT: @codecov/vite-plugin@1.9.1 不支持 Vite 7.x (仅支持 4/5/6)
+    // 临时使用类型断言绕过编译错误,功能运行时正常
+    // TODO: 等待上游支持 Vite 7 后移除 as any
+    ...(process.env.CI === 'true' && process.env.CODECOV_TOKEN ?
+      [
+        codecovVitePlugin({
+          enableBundleAnalysis: true,
+          telemetry: false,
+          bundleName: 'rxdb-react',
+          uploadToken: process.env.CODECOV_TOKEN
+        }) as any
+      ]
+    : [])
+  ],
+  // Uncomment this if you are using workers.
+  // worker: {
+  //  plugins: [ nxViteTsPaths() ],
+  // },
+  // Configuration for building your library.
+  // See: https://vitejs.dev/guide/build.html#library-mode
+  build: {
+    outDir: './dist',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true
+    },
+    lib: {
+      // Could also be a dictionary or array of multiple entry points.
+      entry: 'src/index.ts',
+      name: 'rxdb-react',
+      fileName: 'index',
+      // Change this to the formats you want to support.
+      // Don't forget to update your package.json as well.
+      formats: ['es' as const]
+    },
+    rollupOptions: {
+      // External packages that should not be bundled into your library.
+      external: ['react', 'react-dom', 'react/jsx-runtime', '@aiao/rxdb', '@aiao/utils', 'rxjs']
+    }
+  },
+  optimizeDeps: {
+    exclude: ['rxjs', 'ms', 'fastest-levenshtein', 'ts-xor', '@aiao/rxdb', '@aiao/utils']
+  },
+  test: {
+    name: 'rxdb-react',
+    watch: false,
+    globals: true,
+    environment: 'happy-dom',
+    passWithNoTests: true,
+    testTimeout: 2000,
+    hookTimeout: 2000,
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default', 'junit'],
+    outputFile: {
+      junit: '../../coverage/packages/rxdb-react/junit.xml'
+    },
+    coverage: {
+      enabled: true,
+      reportsDirectory: '../../coverage/packages/rxdb-react',
+      provider: 'v8',
+      include: ['src/**/*'],
+      exclude: ['**/index.ts', '**/dist/**']
+    }
+  }
+});