@aiao/rxdb-angular 0.0.2 → 0.0.7

package/src/hooks.ts

@@ -0,0 +1,307 @@
+import { EntityStaticType, EntityType, TreeEntityType } from '@aiao/rxdb';
+import { GraphEntityType } from '@aiao/rxdb-plugin-graph';
+import { isFunction } from '@aiao/utils';
+import { effect, Signal, signal } from '@angular/core';
+import { toLazySignal } from 'ngxtension/to-lazy-signal';
+import { Observable, Subscriber, Subscription } from 'rxjs';
+
+type UseOptions<T> = T | (() => T);
+
+export interface RxDBResource<T> {
+  /**
+   * 资源的值
+   */
+  readonly value: Signal<T>;
+  /**
+   * 资源的错误
+   */
+  readonly error: Signal<Error | undefined>;
+  /**
+   * 资源的加载状态
+   */
+  readonly isLoading: Signal<boolean>;
+  /**
+   * 资源是否为空
+   */
+  readonly isEmpty: Signal<boolean | undefined>;
+  /**
+   * 资源是否有值
+   */
+  readonly hasValue: Signal<boolean>;
+}
+
+export const useRepositoryQuery = <T extends EntityType, RT>(
+  EntityType: T,
+  method: string,
+  defaultValue: any,
+  options: UseOptions<any>
+): RxDBResource<RT> => {
+  let _observer: Subscriber<any>;
+  let sub: Subscription;
+
+  const _has_sub = signal<boolean>(false);
+  const _refresh = signal<number>(0);
+
+  const _eff = effect(() => {
+    if (_has_sub() === false) return;
+    // re-run when refresh is called or options change
+    _refresh();
+    const opt = isFunction(options) ? options() : options;
+    if (sub) sub.unsubscribe();
+    // reset state for a new request
+    isLoading.set(true);
+    error.set(undefined);
+    hasValue.set(false);
+    isEmpty.set(undefined);
+    // 优化：使用 Record<string, any> 替代 any，以提高类型安全性
+    const func = (EntityType as unknown as Record<string, any>)[method];
+    sub =
+      func &&
+      func(opt).subscribe({
+        next: (d: any) => {
+          isLoading.set(false);
+          hasValue.set(true);
+          if (Array.isArray(d)) {
+            isEmpty.set(d.length === 0);
+          } else if (d == null) {
+            // null/undefined treated as empty
+            isEmpty.set(true);
+          } else {
+            isEmpty.set(false);
+          }
+          _observer.next(d);
+        },
+        error: (e: any) => {
+          isLoading.set(false);
+          error.set(e);
+        },
+        complete: () => {
+          // ensure loading is false even if observable completes without next
+          isLoading.set(false);
+        }
+      });
+  });
+  const ob = new Observable<RT>(observer => {
+    _has_sub.set(true);
+    _observer = observer;
+    _observer.next(defaultValue);
+    return () => {
+      _eff.destroy();
+      sub?.unsubscribe();
+    };
+  });
+
+  const value = toLazySignal<RT>(ob, {
+    initialValue: defaultValue
+  }) as Signal<RT>;
+  const error = signal<Error | undefined>(undefined);
+  const isLoading = signal<boolean>(false);
+  const hasValue = signal<boolean>(false);
+  const isEmpty = signal<boolean | undefined>(undefined);
+  return {
+    value,
+    error,
+    isLoading,
+    isEmpty,
+    hasValue
+  };
+};
+
+/*
+ * Repository
+ */
+
+/**
+ * 通过 ID 获取单个实体
+ *
+ * @param EntityType 实体类
+ * @param options 实体 ID 或查询参数对象
+ * @returns 返回包含实体的资源 signal
+ *
+ * @example
+ * ```typescript
+ * const user = useGet(User, 'user-1');
+ * ```
+ */
+export const useGet = <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, 'getOptions'>>) =>
+  useRepositoryQuery<T, InstanceType<T>>(EntityType, 'get', undefined, options);
+
+/**
+ * 查找第一个匹配条件的实体
+ *
+ * @param EntityType 实体类
+ * @param options 查询参数（where、排序等）
+ * @returns 返回包含实体的资源 signal
+ */
+export const useFindOne = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findOneOptions'>>
+) => useRepositoryQuery<T, InstanceType<T> | undefined>(EntityType, 'findOne', undefined, options);
+
+/**
+ * 查找匹配的实体，未找到则抛出错误
+ *
+ * @param EntityType 实体类
+ * @param options 查询参数
+ * @returns 返回包含实体的资源 signal
+ */
+export const useFindOneOrFail = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findOneOrFailOptions'>>
+) => useRepositoryQuery<T, InstanceType<T>>(EntityType, 'findOneOrFail', undefined, options);
+
+/**
+ * 查找符合条件的多个实体
+ *
+ * @param EntityType 实体类
+ * @param options 查询参数
+ * @returns 返回包含实体数组的资源 signal
+ */
+export const useFind = <T extends EntityType>(EntityType: T, options: UseOptions<EntityStaticType<T, 'findOptions'>>) =>
+  useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'find', [], options);
+
+/**
+ * 使用游标分页查找实体
+ *
+ * @param EntityType 实体类
+ * @param options 游标参数
+ * @returns 返回包含实体数组的资源 signal
+ */
+export const useFindByCursor = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findByCursorOptions'>>
+) => useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findByCursor', [], options);
+
+/**
+ * 查找全部实体
+ *
+ * @param EntityType 实体类
+ * @param options 查询参数
+ * @returns 返回包含全部实体的资源 signal
+ */
+export const useFindAll = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findAllOptions'>>
+) => useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findAll', [], options);
+
+/**
+ * 统计满足条件的实体数量
+ *
+ * @param EntityType 实体类
+ * @param options 查询参数
+ * @returns 返回包含数量的资源 signal
+ */
+export const useCount = <T extends EntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'countOptions'>>
+) => useRepositoryQuery<T, number>(EntityType, 'count', undefined, options);
+
+/*
+ * TreeRepository
+ */
+
+/**
+ * 查找树结构中的所有子孙实体
+ *
+ * @param EntityType 实体类
+ * @param options 树查询参数（entityId、深度等）
+ * @returns 返回包含子孙实体的资源 signal
+ */
+export const useFindDescendants = <T extends TreeEntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+) => useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findDescendants', [], options);
+
+/**
+ * 统计树结构中的子孙数量
+ *
+ * @param EntityType 实体类
+ * @param options 树查询参数
+ * @returns 返回包含数量的资源 signal
+ */
+export const useCountDescendants = <T extends TreeEntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+) => useRepositoryQuery<T, number>(EntityType, 'countDescendants', undefined, options);
+
+/**
+ * 查找树结构中的所有祖先实体
+ *
+ * @param EntityType 实体类
+ * @param options 树查询参数
+ * @returns 返回包含祖先实体的资源 signal
+ */
+export const useFindAncestors = <T extends TreeEntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+) => useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findAncestors', [], options);
+
+/**
+ * 统计树结构中的祖先数量
+ *
+ * @param EntityType 实体类
+ * @param options 树查询参数
+ * @returns 返回包含数量的资源 signal
+ */
+export const useCountAncestors = <T extends TreeEntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findTreeOptions'>>
+) => useRepositoryQuery<T, number>(EntityType, 'countAncestors', undefined, options);
+
+/*
+ * GraphRepository
+ */
+
+/**
+ * 查找图结构中的邻接实体
+ *
+ * @param EntityType 实体类
+ * @param options 图查询参数（entityId、方向、层级等）
+ * @returns 返回包含邻居实体的资源 signal
+ *
+ * @example
+ * ```typescript
+ * const friends = useGraphNeighbors(User, {
+ *   entityId: 'user-1',
+ *   direction: 'out',
+ *   level: 1
+ * });
+ * ```
+ */
+export const useGraphNeighbors = <T extends GraphEntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findNeighborsOptions'>>
+) => useRepositoryQuery<T, InstanceType<T>[]>(EntityType, 'findNeighbors', [], options);
+
+/**
+ * 统计图结构中的邻接数量
+ *
+ * @param EntityType 实体类
+ * @param options 图查询参数
+ * @returns 返回包含数量的资源 signal
+ */
+export const useCountNeighbors = <T extends GraphEntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findNeighborsOptions'>>
+) => useRepositoryQuery<T, number>(EntityType, 'countNeighbors', 0, options);
+
+/**
+ * 查找图结构中两个实体之间的路径
+ *
+ * @param EntityType 实体类
+ * @param options 路径查询参数（fromId、toId、最大深度等）
+ * @returns 返回包含路径的资源 signal
+ *
+ * @example
+ * ```typescript
+ * const paths = useGraphPaths(User, {
+ *   fromId: 'user-1',
+ *   toId: 'user-2',
+ *   maxDepth: 5
+ * });
+ * ```
+ */
+export const useGraphPaths = <T extends GraphEntityType>(
+  EntityType: T,
+  options: UseOptions<EntityStaticType<T, 'findPathsOptions'>>
+) => useRepositoryQuery<T, any[]>(EntityType, 'findPaths', [], options);

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './hooks';
+export * from './InfiniteScrollingList';
+export { RxDBEntityChangeDirective } from './rxdb-change-detector.directive';
+export { provideRxDB } from './rxdb.provider';
+export * from './rxdb.service';
+export * from './use-action';
+export * from './use-state';

package/src/rxdb-change-detector.directive.spec.ts

@@ -0,0 +1,94 @@
+import { ChangeDetectionStrategy, Component, provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { Subject } from 'rxjs';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { RxDBEntityChangeDirective } from './rxdb-change-detector.directive';
+
+// Mock entity type
+const mockEntity = {
+  id: 'test-1',
+  name: 'Test Entity'
+};
+
+const mockPatchesSubject = new Subject();
+
+// Mock getEntityStatus
+vi.mock('@aiao/rxdb', () => ({
+  getEntityStatus: vi.fn(() => ({
+    patches$: mockPatchesSubject.asObservable()
+  }))
+}));
+
+@Component({
+  // eslint-disable-next-line @angular-eslint/component-selector
+  selector: 'test-component',
+  standalone: true,
+  imports: [RxDBEntityChangeDirective],
+  template: '<div [rxdbChangeDetector]="entity"></div>',
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+class TestComponent {
+  entity = mockEntity;
+}
+
+describe('RxDBEntityChangeDirective', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [provideZonelessChangeDetection()]
+    });
+  });
+
+  it('should create directive', () => {
+    const fixture = TestBed.createComponent(TestComponent);
+    expect(fixture).toBeDefined();
+  });
+
+  it('should subscribe to patches$ on initialization', () => {
+    const fixture = TestBed.createComponent(TestComponent);
+    fixture.detectChanges();
+
+    // Verify component was created successfully with the directive
+    expect(fixture.componentInstance).toBeDefined();
+
+    // 指令应该已经设置了订阅
+    // Testing the actual subscription behavior requires more complex mocking
+  });
+
+  it('should handle debounceTime input', () => {
+    @Component({
+      // eslint-disable-next-line @angular-eslint/component-selector
+      selector: 'test-debounce',
+      standalone: true,
+      imports: [RxDBEntityChangeDirective],
+      template: '<div [rxdbChangeDetector]="entity" [debounceTime]="100"></div>',
+      changeDetection: ChangeDetectionStrategy.OnPush
+    })
+    class TestDebounceComponent {
+      entity = mockEntity;
+    }
+
+    const fixture = TestBed.createComponent(TestDebounceComponent);
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance).toBeDefined();
+  });
+
+  it('should handle auditTime input', () => {
+    @Component({
+      // eslint-disable-next-line @angular-eslint/component-selector
+      selector: 'test-audit',
+      standalone: true,
+      imports: [RxDBEntityChangeDirective],
+      template: '<div [rxdbChangeDetector]="entity" [auditTime]="50"></div>',
+      changeDetection: ChangeDetectionStrategy.OnPush
+    })
+    class TestAuditComponent {
+      entity = mockEntity;
+    }
+
+    const fixture = TestBed.createComponent(TestAuditComponent);
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance).toBeDefined();
+  });
+});

package/src/rxdb-change-detector.directive.ts

@@ -0,0 +1,35 @@
+import { EntityType, getEntityStatus } from '@aiao/rxdb';
+import { ChangeDetectorRef, DestroyRef, Directive, effect, inject, input } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { auditTime, debounceTime, Subscription } from 'rxjs';
+
+/**
+ * RxDB 实体变化指令
+ * 如果你使用了 `changeDetection: ChangeDetectionStrategy.OnPush`
+ * 那么正在输入的变化不会触发 angular 渲染机制，使用这个指令可以实现实时渲染
+ *
+ * @example
+ * 当修改实体时，需要在多个地方预览修改变化时，可以使用这个指令
+ */
+@Directive({ selector: '[rxdbChangeDetector]' })
+export class RxDBEntityChangeDirective {
+  #destroyRef = inject(DestroyRef);
+  #changeDetectorRef = inject(ChangeDetectorRef);
+  #sub?: Subscription;
+  public readonly rxdbChangeDetector = input<InstanceType<EntityType>>();
+  public readonly debounceTime = input<number>(0);
+  public readonly auditTime = input<number>(0);
+
+  constructor() {
+    effect(() => {
+      const rxdbChange = this.rxdbChangeDetector();
+      const dt = this.debounceTime();
+      const at = this.auditTime();
+      const status = getEntityStatus(rxdbChange);
+      this.#sub?.unsubscribe();
+      this.#sub = status.patches$
+        .pipe(takeUntilDestroyed(this.#destroyRef), debounceTime(dt), auditTime(at))
+        .subscribe(() => this.#changeDetectorRef.markForCheck());
+    });
+  }
+}

package/src/rxdb.provider.ts

@@ -0,0 +1,13 @@
+import { RxDB } from '@aiao/rxdb';
+import { makeEnvironmentProviders } from '@angular/core';
+
+/**
+ * RxDB 配置
+ */
+export const provideRxDB = (useFactory?: () => RxDB) =>
+  makeEnvironmentProviders([
+    {
+      provide: RxDB,
+      useFactory
+    }
+  ]);

package/src/rxdb.service.spec.ts

@@ -0,0 +1,31 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { RxDBService } from './rxdb.service';
+
+describe('RxDBService', () => {
+  let service: RxDBService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [provideZonelessChangeDetection(), RxDBService]
+    });
+    service = TestBed.inject(RxDBService);
+  });
+
+  it('should be created', () => {
+    expect(service).toBeDefined();
+  });
+
+  it('should not throw when closing devtools if not open', () => {
+    expect(() => service.closeDevTools()).not.toThrow();
+  });
+
+  it('should not throw when setting theme if devtools not open', () => {
+    expect(() => service.setDevToolsTheme('dark')).not.toThrow();
+  });
+
+  // Note: Tests for devtools loading are skipped because they require
+  // full RxDB setup with database connections, which is better tested
+  // in integration tests with actual Angular applications.
+});

package/src/rxdb.service.ts

@@ -0,0 +1,35 @@
+import { ComponentRef, Injectable, ViewContainerRef } from '@angular/core';
+import { RxDBDevtools } from './devtools/devtools';
+import { RxDBDevToolsOptions } from './devtools/devtools.interface';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class RxDBService {
+  #componentRef?: ComponentRef<RxDBDevtools>;
+
+  async devtools(view: ViewContainerRef, options?: RxDBDevToolsOptions) {
+    if (this.#componentRef) {
+      this.closeDevTools();
+      return;
+    }
+    const { RxDBDevtools } = await import('./devtools/devtools.js');
+    const componentRef = view.createComponent(RxDBDevtools);
+    this.#componentRef = componentRef;
+    componentRef.setInput('componentRef', componentRef);
+    if (options) {
+      if (options.theme) this.setDevToolsTheme(options.theme);
+    }
+    componentRef.onDestroy(() => {
+      this.#componentRef = undefined;
+    });
+  }
+
+  closeDevTools() {
+    this.#componentRef?.instance.close_rxdb_devtools();
+  }
+
+  setDevToolsTheme(theme: 'light' | 'dark') {
+    this.#componentRef?.setInput('theme', theme);
+  }
+}

package/src/test-setup.ts

@@ -0,0 +1,14 @@
+import '@angular/compiler';
+
+import { getTestBed } from '@angular/core/testing';
+import { BrowserTestingModule, platformBrowserTesting } from '@angular/platform-browser/testing';
+
+const testBed = getTestBed();
+if (!testBed.platform) {
+  testBed.initTestEnvironment(BrowserTestingModule, platformBrowserTesting());
+}
+
+import { afterEach } from 'vitest';
+afterEach(() => {
+  getTestBed().resetTestingModule();
+});

package/src/use-action.spec.ts

@@ -0,0 +1,88 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { useAction } from './use-action';
+
+describe('useAction', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [provideZonelessChangeDetection()]
+    });
+  });
+  it('should create an action with isPending signal', () => {
+    TestBed.runInInjectionContext(() => {
+      const mockFn = vi.fn(async () => 'result');
+      const action = useAction(mockFn);
+
+      expect(action.isPending).toBeDefined();
+      expect(action.execute).toBeDefined();
+      expect(action.isPending()).toBe(false);
+    });
+  });
+
+  it('should set isPending to true during execution', async () => {
+    await TestBed.runInInjectionContext(async () => {
+      let resolvePromise: (value: string) => void;
+      const mockFn = vi.fn(
+        () =>
+          new Promise<string>(resolve => {
+            resolvePromise = resolve;
+          })
+      );
+      const action = useAction(mockFn);
+
+      const executePromise = action.execute();
+      expect(action.isPending()).toBe(true);
+
+      resolvePromise!('result');
+      await executePromise;
+      expect(action.isPending()).toBe(false);
+    });
+  });
+
+  it('should execute the promise function with options', async () => {
+    await TestBed.runInInjectionContext(async () => {
+      const mockFn = vi.fn(async (options?: { id: number }) => `result-${options?.id}`);
+      const action = useAction(mockFn);
+
+      const result = await action.execute({ id: 123 });
+
+      expect(mockFn).toHaveBeenCalledWith({ id: 123 });
+      expect(result).toBe('result-123');
+    });
+  });
+
+  it('should reset isPending to false after success', async () => {
+    await TestBed.runInInjectionContext(async () => {
+      const mockFn = vi.fn(async () => 'success');
+      const action = useAction(mockFn);
+
+      await action.execute();
+
+      expect(action.isPending()).toBe(false);
+    });
+  });
+
+  it('should reset isPending to false after error', async () => {
+    await TestBed.runInInjectionContext(async () => {
+      const mockFn = vi.fn(async () => {
+        throw new Error('test error');
+      });
+      const action = useAction(mockFn);
+
+      await expect(action.execute()).rejects.toThrow('test error');
+      expect(action.isPending()).toBe(false);
+    });
+  });
+
+  it('should return the result from promise function', async () => {
+    await TestBed.runInInjectionContext(async () => {
+      const mockFn = vi.fn(async () => ({ data: 'test' }));
+      const action = useAction(mockFn);
+
+      const result = await action.execute();
+
+      expect(result).toEqual({ data: 'test' });
+    });
+  });
+});

package/src/use-action.ts

@@ -0,0 +1,20 @@
+import { signal } from '@angular/core';
+
+const action = <Options = any, RT = any>(promiseFn: (options?: Options) => Promise<RT>) => {
+  const isPending = signal<boolean>(false);
+  return {
+    isPending,
+    execute: async (options?: Options) => {
+      isPending.set(true);
+      try {
+        const d = await promiseFn(options);
+        return d;
+      } finally {
+        isPending.set(false);
+      }
+    }
+  };
+};
+
+export const useAction = <Options = any, RT = any>(promiseFn: (options?: Options) => Promise<RT>) =>
+  action<Options, RT>(promiseFn);