@connecttomahdi/rxdb 17.0.0-beta.17

package/src/plugins/react/hooks/use-rx-collection.ts

@@ -0,0 +1,73 @@
+import { useState, useEffect } from 'react';
+import { filter } from 'rxjs';
+
+import type { RxCollection, RxCollectionEvent, RxDatabase } from '../../../types/index.d.ts';
+import { useRxDatabase } from './use-rx-database.ts';
+
+/**
+ * The `useRxCollection` hook retrieves an RxDB collection by name and maintains
+ * its state as the collection lifecycle changes.
+ *
+ * @param {string} name The name of the collection to retrieve.
+ * @returns The RxCollection instance or null
+ * if the collection does not exist or has been closed.
+ */
+export function useRxCollection<
+    RxDocumentType = any,
+    OrmMethods = {},
+    StaticMethods = {},
+    InstanceCreationOptions = {},
+    Reactivity = unknown,
+>(
+    name: string,
+): RxCollection<
+    RxDocumentType,
+    OrmMethods,
+    StaticMethods,
+    InstanceCreationOptions,
+    Reactivity
+> | null {
+    const [collection, setCollection] = useState<RxCollection<
+        RxDocumentType,
+        OrmMethods,
+        StaticMethods,
+        InstanceCreationOptions,
+        Reactivity
+    > | null>(null);
+    const database = useRxDatabase() as RxDatabase;
+
+    useEffect(() => {
+        if (database == null) {
+            return;
+        }
+        const dbCollection = database.collections[name] as RxCollection<
+            RxDocumentType,
+            OrmMethods,
+            StaticMethods,
+            InstanceCreationOptions,
+            Reactivity
+        >;
+        if (dbCollection != null) {
+            setCollection(dbCollection);
+        }
+        database.collections$
+            .pipe(filter((evt: RxCollectionEvent) => evt.collection.name === name))
+            .subscribe((evt: RxCollectionEvent) => {
+                if (evt.type == 'ADDED') {
+                    setCollection(
+                        evt.collection as RxCollection<
+                            RxDocumentType,
+                            OrmMethods,
+                            StaticMethods,
+                            InstanceCreationOptions,
+                            Reactivity
+                        >,
+                    );
+                } else if (evt.type == 'CLOSED') {
+                    setCollection(null);
+                }
+            });
+    }, [database, name]);
+
+    return collection;
+}

package/src/plugins/react/hooks/use-rx-database.ts

@@ -0,0 +1,35 @@
+import { useContext } from 'react';
+
+import type {
+    CollectionsOfDatabase,
+    RxDatabase,
+} from '../../../types/index.d.ts';
+import { RxDatabaseContext } from '../database-context.ts';
+import { newRxError } from '../../../rx-error.ts';
+
+/**
+ * The `useRxDatabase` hook retrieves the RxDB database instance from context.
+ *
+ * @returns The RxDB database instance.
+ * @throws {Error} Throws an error if the component is not wrapped in a <RxDatabaseProvider>.
+ * This ensures the database context is properly initialized before use.
+ */
+export function useRxDatabase<
+    Collections = CollectionsOfDatabase,
+    Internals = any,
+    InstanceCreationOptions = any,
+    Reactivity = any,
+>(): RxDatabase<Collections, Internals, InstanceCreationOptions, Reactivity> {
+    const database = useContext(RxDatabaseContext) as unknown as RxDatabase<
+        Collections,
+        Internals,
+        InstanceCreationOptions,
+        Reactivity
+    >;
+
+    if (database == null) {
+        throw newRxError('R2');
+    }
+
+    return database;
+}

package/src/plugins/react/hooks/use-rx-query.ts

@@ -0,0 +1,168 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import type {
+    MangoQuery,
+    RxCollection,
+    RxDocument,
+} from '../../../types/index.d.ts';
+import { isRxCollection } from '../../../rx-collection.ts';
+import { useRxCollection } from './use-rx-collection.ts';
+import { newRxError } from '../../../rx-error.ts';
+
+export type UseRxQueryOptions<
+    RxDocumentType = any,
+    OrmMethods = {},
+    StaticMethods = {},
+    InstanceCreationOptions = {},
+    Reactivity = unknown,
+> = {
+    collection:
+    | string
+    | RxCollection<
+        RxDocumentType,
+        OrmMethods,
+        StaticMethods,
+        InstanceCreationOptions,
+        Reactivity
+    >;
+    query: MangoQuery<RxDocumentType>;
+};
+
+export type UseRxQueryResult<RxDocumentType = any, OrmMethods = {}> = {
+    results: RxDocument<RxDocumentType, OrmMethods>[];
+    loading: boolean;
+    error: string | null;
+};
+
+/**
+ * React hook to query an RxDB collection with Mango queries.
+ *
+ * @param {UseRxQueryOptions<RxDocumentType, OrmMethods, StaticMethods, InstanceCreationOptions, Reactivity>} options - Options for the query.
+ * @param {string|RxCollection} options.collection - The collection name or instance to query.
+ * @param {MangoQuery<RxDocumentType>} options.query - The Mango query to execute.
+ * @param {boolean} [options.live] - Whether to subscribe to live query updates.
+ *
+ * @returns {UseRxQueryResult<RxDocumentType, OrmMethods>} The query result, loading state, and error.
+ */
+export function useRxQueryBase<
+    RxDocumentType = any,
+    OrmMethods = {},
+    StaticMethods = {},
+    InstanceCreationOptions = {},
+    Reactivity = unknown,
+>({
+    collection,
+    query,
+    live,
+}: UseRxQueryOptions<
+    RxDocumentType,
+    OrmMethods,
+    StaticMethods,
+    InstanceCreationOptions,
+    Reactivity
+> & { live: boolean }): UseRxQueryResult<RxDocumentType, OrmMethods> {
+    const [results, setResults] = useState(
+        [] as RxDocument<RxDocumentType, OrmMethods>[],
+    );
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    let dbCollection: RxCollection<
+        RxDocumentType,
+        OrmMethods,
+        StaticMethods,
+        InstanceCreationOptions,
+        Reactivity
+    > | null;
+    if (typeof collection === 'string') {
+        dbCollection = useRxCollection<
+            RxDocumentType,
+            OrmMethods,
+            StaticMethods,
+            InstanceCreationOptions,
+            Reactivity
+        >(collection);
+    } else {
+        if (!isRxCollection(collection)) {
+            throw newRxError('R3', {
+                collection
+            });
+        }
+        dbCollection = collection;
+    }
+    (window as any).collection = dbCollection;
+
+    const emitResults = (res: RxDocument<RxDocumentType, OrmMethods>[]) => {
+        setResults(res);
+        if (loading) {
+            setLoading(false);
+        }
+    };
+
+    const emitError = (e: Error) => {
+        setError(e.message);
+        if (loading) {
+            setLoading(false);
+        }
+    };
+
+    const runQuery = useCallback(async () => {
+        if (dbCollection == null) {
+            return;
+        }
+        setError(null);
+        setLoading(loading);
+        const rxQuery = dbCollection.find(query);
+        if (live) {
+            const subscription = rxQuery.$.subscribe({
+                next: (res: RxDocument<RxDocumentType, OrmMethods>[]) => emitResults(res),
+                error: (err: Error) => emitError(err),
+            });
+
+            return () => {
+                subscription.unsubscribe();
+            };
+        } else {
+            try {
+                emitResults(await rxQuery.exec());
+            } catch (e) {
+                emitError(e as Error);
+            }
+        }
+    }, [dbCollection, query]);
+
+    useEffect(() => {
+        if (collection == null) {
+            return;
+        }
+
+        runQuery();
+    }, [runQuery]);
+
+    return { results, loading, error };
+}
+
+
+
+export function useRxQuery<
+    RxDocumentType = any,
+    OrmMethods = {},
+    StaticMethods = {},
+    InstanceCreationOptions = {},
+    Reactivity = unknown,
+>({
+    collection,
+    query,
+}: UseRxQueryOptions<
+    RxDocumentType,
+    OrmMethods,
+    StaticMethods,
+    InstanceCreationOptions,
+    Reactivity
+>): UseRxQueryResult<RxDocumentType, OrmMethods> {
+    return useRxQueryBase({
+        collection,
+        query,
+        live: false
+    });
+}

package/src/plugins/react/index.ts

@@ -0,0 +1,2 @@
+export { RxDatabaseProvider } from './database-provider.tsx';
+export * from './hooks/index.ts';

package/src/plugins/reactivity-angular/index.ts

@@ -0,0 +1,32 @@
+import { Signal, untracked, Injector } from '@angular/core';
+import type { RxReactivityFactory, ReactivityLambda } from '../../types';
+import { toSignal } from '@angular/core/rxjs-interop';
+
+/**
+ * Type-level function (ReactivityLambda) for Angular signals.
+ * Use this as the Reactivity type parameter for properly typed signals.
+ *
+ * @example
+ * const db = await createRxDatabase<MyCollections, any, any, AngularSignalReactivityLambda>({
+ *     reactivity: createReactivityFactory(injector)
+ * });
+ * const signal = doc.age$$; // Signal<number>
+ */
+export interface AngularSignalReactivityLambda extends ReactivityLambda {
+    readonly _result: Signal<this['_data']>;
+}
+
+export function createReactivityFactory(
+    injector: Injector
+): RxReactivityFactory<AngularSignalReactivityLambda> {
+    return {
+        fromObservable(observable$: any, initialValue: any): any {
+            return untracked(() =>
+                toSignal(observable$, {
+                    initialValue,
+                    injector
+                })
+            );
+        }
+    };
+}

package/src/plugins/reactivity-preact-signals/index.ts

@@ -0,0 +1,85 @@
+import { signal, Signal } from "@preact/signals-core";
+import type {
+    Observable,
+    Subscription
+} from 'rxjs';
+import type {
+    WeakRef,
+    FinalizationRegistry,
+    RxReactivityFactory,
+    ReactivityLambda
+} from '../../types/index.d.ts';
+
+/**
+ * Type-level function (ReactivityLambda) for Preact signals.
+ * Use this as the Reactivity type parameter for properly typed signals.
+ *
+ * @example
+ * const db = await createRxDatabase<MyCollections, any, any, PreactSignalReactivityLambda>({
+ *     reactivity: PreactSignalsRxReactivityFactory
+ * });
+ * const signal = doc.age$$; // Signal<number>
+ */
+export interface PreactSignalReactivityLambda extends ReactivityLambda {
+    readonly _result: Signal<this['_data']>;
+}
+
+export type PreactSignal<T = any> = Signal<T>;
+
+/**
+ * Exported to debug and test
+ * the behavior
+ */
+export const PREACT_SIGNAL_STATE = {
+    subscribeCount: 0,
+    signalBySubscription: new WeakMap<Subscription, PreactSignal>(),
+    aliveSubscription: new Set<Subscription>(),
+};
+
+
+function removeSubscription(sub: Subscription) {
+    const isAlive = PREACT_SIGNAL_STATE.aliveSubscription.has(sub);
+    if (isAlive) {
+        PREACT_SIGNAL_STATE.aliveSubscription.delete(sub);
+        PREACT_SIGNAL_STATE.signalBySubscription.delete(sub);
+        PREACT_SIGNAL_STATE.subscribeCount = PREACT_SIGNAL_STATE.subscribeCount - 1;
+        sub.unsubscribe();
+    }
+}
+
+function cleanupCallback(sub: Subscription) {
+    // called when a signal becomes garbage collected
+    removeSubscription(sub);
+}
+
+const cleanupRegistry: FinalizationRegistry<Subscription> = new FinalizationRegistry(cleanupCallback) as any;
+
+export const PreactSignalsRxReactivityFactory: RxReactivityFactory<PreactSignalReactivityLambda> = {
+    fromObservable<Data, InitData>(
+        obs: Observable<Data>,
+        initialValue: InitData
+    ): PreactSignal<Data | InitData> {
+        const mySignal = signal<Data | InitData>(initialValue);
+        const sigRef: WeakRef = new WeakRef(mySignal);
+        const sub = obs.subscribe((value: Data) => {
+            const sig = PREACT_SIGNAL_STATE.signalBySubscription.get(sub);
+            if (sig && sigRef.deref()) {
+                sig.value = value;
+            } else {
+                /**
+                 * The callback of FinalizationRegistry is not reliable by definition
+                 * so we have this fallback to still clean unused signals subscriptions
+                 * when they emit but the signal is already not used anymore.
+                 * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry#notes_on_cleanup_callbacks
+                 */
+                removeSubscription(sub);
+            }
+        });
+        PREACT_SIGNAL_STATE.aliveSubscription.add(sub);
+        PREACT_SIGNAL_STATE.signalBySubscription.set(sub, mySignal);
+        PREACT_SIGNAL_STATE.subscribeCount = PREACT_SIGNAL_STATE.subscribeCount + 1;
+
+        cleanupRegistry.register({}, sub);
+        return mySignal;
+    }
+}; 

package/src/plugins/reactivity-vue/index.ts

@@ -0,0 +1,43 @@
+import {
+    shallowRef,
+    triggerRef,
+    onScopeDispose,
+    Ref
+} from 'vue';
+import type {
+    Observable
+} from 'rxjs';
+import type { RxReactivityFactory, ReactivityLambda } from '../../types';
+
+/**
+ * Type-level function (ReactivityLambda) for Vue refs.
+ * Use this as the Reactivity type parameter for properly typed refs.
+ *
+ * @example
+ * const db = await createRxDatabase<MyCollections, any, any, VueRefReactivityLambda>({
+ *     reactivity: VueRxReactivityFactory
+ * });
+ * const ref = doc.age$$; // Ref<number>
+ */
+export interface VueRefReactivityLambda extends ReactivityLambda {
+    readonly _result: Ref<this['_data']>;
+}
+
+export type VueRef<T = any> = Ref<T>;
+
+export const VueRxReactivityFactory: RxReactivityFactory<VueRefReactivityLambda> = {
+    fromObservable<Data, InitData>(
+        obs: Observable<Data>,
+        initialValue: InitData
+    ): VueRef<Data | InitData> {
+        const ref = shallowRef(initialValue);
+        const sub = obs.subscribe((value: Data) => {
+            ref.value = value;
+            triggerRef(ref);
+        });
+        onScopeDispose(() => {
+            sub.unsubscribe();
+        });
+        return ref;
+    }
+};