reactfire 4.0.0 → 4.0.1-exp.f6d2351

package/README.md

@@ -28,7 +28,6 @@ Depending on your targeted platforms you may need to install polyfills. The most
 ## Docs
 
 - [**Quickstart**](./docs/quickstart.md)
-  - Advanced: If you're using Concurrent Mode, check out the [Concurrent Mode quickstart](./docs/quickstart-concurrent-mode.md)
 - [**Common Use Cases**](./docs/use.md)
 - [**API Reference**](./docs/reference)
 - [**v3 -> v4 Upgrade Guide**](./docs/upgrade-guide.md)
@@ -92,7 +91,17 @@ This repository is maintained by Googlers but is not a supported Firebase produc
 
 ### Extra Experimental [concurrent mode](https://reactjs.org/docs/concurrent-mode-suspense.html) features
 
+These features are marked as *extra experimental* because they use experimental React features that [will not be stable until sometime after React 18 is released](https://github.com/reactwg/react-18/discussions/47#:~:text=Likely%20after%20React%2018.0%3A%20Suspense%20for%20Data%20Fetching).
+
 - **Loading states handled by `<Suspense>`** - ReactFire's hooks throw promises
-  that Suspense can catch. No more `isLoaded ?...` - let React
-  [handle it for you](https://reactjs.org/docs/concurrent-mode-suspense.html).
+  that Suspense can catch. Let React
+  [handle loading states for you](https://reactjs.org/docs/concurrent-mode-suspense.html).
 - **Automatically instrument your `Suspense` load times** - Need to automatically instrument your `Suspense` load times with [RUM](https://firebase.google.com/docs/perf-mon)? Use `<SuspenseWithPerf />`.
+
+Enable concurrent mode features by following the [concurrent mode setup guide](https://reactjs.org/docs/concurrent-mode-adoption.html#installation) and then setting the `suspense` prop in `FirebaseAppProvider`:
+
+```jsx
+<FirebaseAppProvider firebaseConfig={firebaseConfig} suspense={true}>
+```
+
+See concurrent mode code samples in [example/withSuspense](https://github.com/FirebaseExtended/reactfire/tree/main/example/withSuspense)

package/dist/SuspenseSubject.d.ts

@@ -1,21 +1,21 @@
-import { Observable, Subject, Subscriber, Subscription } from 'rxjs';
-export declare class SuspenseSubject<T> extends Subject<T> {
-    private _timeoutWindow;
-    private _value;
-    private _hasValue;
-    private _timeoutHandler;
-    private _firstEmission;
-    private _error;
-    private _innerObservable;
-    private _warmupSubscription;
-    private _innerSubscriber;
-    private _resolveFirstEmission;
-    constructor(innerObservable: Observable<T>, _timeoutWindow: number);
-    get hasValue(): boolean;
-    get value(): T | undefined;
-    get firstEmission(): Promise<void>;
-    private _next;
-    private _reset;
-    _subscribe(subscriber: Subscriber<T>): Subscription;
-    get ourError(): any;
-}
+import { Observable, Subject, Subscriber, Subscription } from 'rxjs';
+export declare class SuspenseSubject<T> extends Subject<T> {
+    private _timeoutWindow;
+    private _value;
+    private _hasValue;
+    private _timeoutHandler;
+    private _firstEmission;
+    private _error;
+    private _innerObservable;
+    private _warmupSubscription;
+    private _innerSubscriber;
+    private _resolveFirstEmission;
+    constructor(innerObservable: Observable<T>, _timeoutWindow: number);
+    get hasValue(): boolean;
+    get value(): T;
+    get firstEmission(): Promise<void>;
+    private _next;
+    private _reset;
+    _subscribe(subscriber: Subscriber<T>): Subscription;
+    get ourError(): any;
+}

package/dist/auth.d.ts

@@ -1,104 +1,104 @@
-import * as React from 'react';
-import { ReactFireOptions, ObservableStatus } from './';
-import type { Auth, User, IdTokenResult } from 'firebase/auth';
-declare type Claims = IdTokenResult['claims'];
-export declare function preloadUser(authResolver: () => Promise<Auth>): Promise<User | null | undefined>;
-/**
- * Subscribe to Firebase auth state changes, including token refresh
- *
- * @param options
- */
-export declare function useUser<T = unknown>(options?: ReactFireOptions<T>): ObservableStatus<User | null>;
-export declare function useIdTokenResult(user: User, forceRefresh?: boolean, options?: ReactFireOptions<IdTokenResult>): ObservableStatus<IdTokenResult>;
-export interface AuthCheckProps {
-    fallback: React.ReactNode;
-    children: React.ReactNode;
-    requiredClaims?: Object;
-}
-export interface ClaimsCheckProps {
-    user: User;
-    fallback: React.ReactNode;
-    children: React.ReactNode;
-    requiredClaims: {
-        [key: string]: any;
-    };
-}
-export interface ClaimCheckErrors {
-    [key: string]: any[];
-}
-export declare type SigninCheckResult = {
-    signedIn: false;
-    hasRequiredClaims: false;
-    errors: {};
-    user: null;
-} | {
-    signedIn: true;
-    hasRequiredClaims: boolean;
-    errors: ClaimCheckErrors;
-    user: User;
-};
-export interface SignInCheckOptionsBasic extends ReactFireOptions<SigninCheckResult> {
-    forceRefresh?: boolean;
-}
-export interface SignInCheckOptionsClaimsObject extends SignInCheckOptionsBasic {
-    requiredClaims: Claims;
-}
-export interface ClaimsValidator {
-    (claims: Claims): {
-        hasRequiredClaims: boolean;
-        errors: ClaimCheckErrors | {};
-    };
-}
-export interface SignInCheckOptionsClaimsValidator extends SignInCheckOptionsBasic {
-    validateCustomClaims: ClaimsValidator;
-}
-/**
- * Subscribe to the signed-in status of a user.
- *
- * ```ts
- * const { status, data:signInCheckResult } = useSigninCheck();
- *
- * if (status === 'loading') {
- *   return <LoadingSpinner />}
- *
- *
- * if (signInCheckResult.signedIn === true) {
- *   return <ProfilePage user={signInCheckResult.user}/>
- * } else {
- *   return <SignInForm />
- * }
- * ```
- *
- * Optionally check [custom claims](https://firebase.google.com/docs/auth/admin/custom-claims) of a user as well.
- *
- * ```ts
- * // pass in an object describing the custom claims a user must have
- * const {status, data: signInCheckResult} = useSignInCheck({requiredClaims: {admin: true}});
- *
- * // pass in a custom claims validator function
- * const {status, data: signInCheckResult} = useSignInCheck({validateCustomClaims: (userClaims) => {
- *   // custom validation logic...
- * }});
- *
- * // You can optionally force-refresh the token
- * const {status, data: signInCheckResult} = useSignInCheck({forceRefresh: true, requiredClaims: {admin: true}});
- * ```
- */
-export declare function useSigninCheck(options?: SignInCheckOptionsBasic | SignInCheckOptionsClaimsObject | SignInCheckOptionsClaimsValidator): ObservableStatus<SigninCheckResult>;
-/**
- * @deprecated Use `useSignInCheck` instead
- *
- * Conditionally render children based on [custom claims](https://firebase.google.com/docs/auth/admin/custom-claims).
- *
- * Meant for Concurrent mode only (`<FirebaseAppProvider suspense=true />`). [More detail](https://github.com/FirebaseExtended/reactfire/issues/325#issuecomment-827654376).
- */
-export declare function ClaimsCheck({ user, fallback, children, requiredClaims }: ClaimsCheckProps): JSX.Element;
-/**
- * @deprecated Use `useSignInCheck` instead
- *
- * Conditionally render children based on signed-in status and [custom claims](https://firebase.google.com/docs/auth/admin/custom-claims).
- *
- * Meant for Concurrent mode only (`<FirebaseAppProvider suspense=true />`). [More detail](https://github.com/FirebaseExtended/reactfire/issues/325#issuecomment-827654376).
- */
-export declare function AuthCheck({ fallback, children, requiredClaims }: AuthCheckProps): JSX.Element;
-export {};
+import * as React from 'react';
+import { ReactFireOptions, ObservableStatus } from './';
+import type { Auth, User, IdTokenResult } from 'firebase/auth';
+declare type Claims = IdTokenResult['claims'];
+export declare function preloadUser(authResolver: () => Promise<Auth>): Promise<User | null | undefined>;
+/**
+ * Subscribe to Firebase auth state changes, including token refresh
+ *
+ * @param options
+ */
+export declare function useUser<T = unknown>(options?: ReactFireOptions<T>): ObservableStatus<User | null>;
+export declare function useIdTokenResult(user: User, forceRefresh?: boolean, options?: ReactFireOptions<IdTokenResult>): ObservableStatus<IdTokenResult>;
+export interface AuthCheckProps {
+    fallback: React.ReactNode;
+    children: React.ReactNode;
+    requiredClaims?: Object;
+}
+export interface ClaimsCheckProps {
+    user: User;
+    fallback: React.ReactNode;
+    children: React.ReactNode;
+    requiredClaims: {
+        [key: string]: any;
+    };
+}
+export interface ClaimCheckErrors {
+    [key: string]: any[];
+}
+export declare type SigninCheckResult = {
+    signedIn: false;
+    hasRequiredClaims: false;
+    errors: {};
+    user: null;
+} | {
+    signedIn: true;
+    hasRequiredClaims: boolean;
+    errors: ClaimCheckErrors;
+    user: User;
+};
+export interface SignInCheckOptionsBasic extends ReactFireOptions<SigninCheckResult> {
+    forceRefresh?: boolean;
+}
+export interface SignInCheckOptionsClaimsObject extends SignInCheckOptionsBasic {
+    requiredClaims: Claims;
+}
+export interface ClaimsValidator {
+    (claims: Claims): {
+        hasRequiredClaims: boolean;
+        errors: ClaimCheckErrors | {};
+    };
+}
+export interface SignInCheckOptionsClaimsValidator extends SignInCheckOptionsBasic {
+    validateCustomClaims: ClaimsValidator;
+}
+/**
+ * Subscribe to the signed-in status of a user.
+ *
+ * ```ts
+ * const { status, data:signInCheckResult } = useSigninCheck();
+ *
+ * if (status === 'loading') {
+ *   return <LoadingSpinner />}
+ *
+ *
+ * if (signInCheckResult.signedIn === true) {
+ *   return <ProfilePage user={signInCheckResult.user}/>
+ * } else {
+ *   return <SignInForm />
+ * }
+ * ```
+ *
+ * Optionally check [custom claims](https://firebase.google.com/docs/auth/admin/custom-claims) of a user as well.
+ *
+ * ```ts
+ * // pass in an object describing the custom claims a user must have
+ * const {status, data: signInCheckResult} = useSignInCheck({requiredClaims: {admin: true}});
+ *
+ * // pass in a custom claims validator function
+ * const {status, data: signInCheckResult} = useSignInCheck({validateCustomClaims: (userClaims) => {
+ *   // custom validation logic...
+ * }});
+ *
+ * // You can optionally force-refresh the token
+ * const {status, data: signInCheckResult} = useSignInCheck({forceRefresh: true, requiredClaims: {admin: true}});
+ * ```
+ */
+export declare function useSigninCheck(options?: SignInCheckOptionsBasic | SignInCheckOptionsClaimsObject | SignInCheckOptionsClaimsValidator): ObservableStatus<SigninCheckResult>;
+/**
+ * @deprecated Use `useSignInCheck` instead
+ *
+ * Conditionally render children based on [custom claims](https://firebase.google.com/docs/auth/admin/custom-claims).
+ *
+ * Meant for Concurrent mode only (`<FirebaseAppProvider suspense=true />`). [More detail](https://github.com/FirebaseExtended/reactfire/issues/325#issuecomment-827654376).
+ */
+export declare function ClaimsCheck({ user, fallback, children, requiredClaims }: ClaimsCheckProps): JSX.Element;
+/**
+ * @deprecated Use `useSignInCheck` instead
+ *
+ * Conditionally render children based on signed-in status and [custom claims](https://firebase.google.com/docs/auth/admin/custom-claims).
+ *
+ * Meant for Concurrent mode only (`<FirebaseAppProvider suspense=true />`). [More detail](https://github.com/FirebaseExtended/reactfire/issues/325#issuecomment-827654376).
+ */
+export declare function AuthCheck({ fallback, children, requiredClaims }: AuthCheckProps): JSX.Element;
+export {};

package/dist/database.d.ts

@@ -1,23 +1,23 @@
-import { QueryChange } from 'rxfire/database';
-import { ReactFireOptions, ObservableStatus } from './';
-import type { Query as DatabaseQuery, DatabaseReference } from 'firebase/database';
-/**
- * Subscribe to a Realtime Database object
- *
- * @param ref - Reference to the DB object you want to listen to
- * @param options
- */
-export declare function useDatabaseObject<T = unknown>(ref: DatabaseReference, options?: ReactFireOptions<T>): ObservableStatus<QueryChange | T>;
-export declare function useDatabaseObjectData<T>(ref: DatabaseReference, options?: ReactFireOptions<T>): ObservableStatus<T>;
-/**
- * Subscribe to a Realtime Database list
- *
- * @param ref - Reference to the DB List you want to listen to
- * @param options
- */
-export declare function useDatabaseList<T = {
-    [key: string]: unknown;
-}>(ref: DatabaseReference | DatabaseQuery, options?: ReactFireOptions<T[]>): ObservableStatus<QueryChange[] | T[]>;
-export declare function useDatabaseListData<T = {
-    [key: string]: unknown;
-}>(ref: DatabaseReference | DatabaseQuery, options?: ReactFireOptions<T[]>): ObservableStatus<T[] | null>;
+import { QueryChange } from 'rxfire/database';
+import { ReactFireOptions, ObservableStatus } from './';
+import type { Query as DatabaseQuery, DatabaseReference } from 'firebase/database';
+/**
+ * Subscribe to a Realtime Database object
+ *
+ * @param ref - Reference to the DB object you want to listen to
+ * @param options
+ */
+export declare function useDatabaseObject<T = unknown>(ref: DatabaseReference, options?: ReactFireOptions<T>): ObservableStatus<QueryChange | T>;
+export declare function useDatabaseObjectData<T>(ref: DatabaseReference, options?: ReactFireOptions<T>): ObservableStatus<T>;
+/**
+ * Subscribe to a Realtime Database list
+ *
+ * @param ref - Reference to the DB List you want to listen to
+ * @param options
+ */
+export declare function useDatabaseList<T = {
+    [key: string]: unknown;
+}>(ref: DatabaseReference | DatabaseQuery, options?: ReactFireOptions<T[]>): ObservableStatus<QueryChange[] | T[]>;
+export declare function useDatabaseListData<T = {
+    [key: string]: unknown;
+}>(ref: DatabaseReference | DatabaseQuery, options?: ReactFireOptions<T[]>): ObservableStatus<T[] | null>;

package/dist/firebaseApp.d.ts

@@ -1,14 +1,14 @@
-import * as React from 'react';
-import type { FirebaseApp, FirebaseOptions } from 'firebase/app';
-interface FirebaseAppProviderProps {
-    firebaseApp?: FirebaseApp;
-    firebaseConfig?: FirebaseOptions;
-    appName?: string;
-    suspense?: boolean;
-}
-export declare const version: any;
-export declare function FirebaseAppProvider(props: React.PropsWithChildren<FirebaseAppProviderProps>): JSX.Element;
-export declare function useIsSuspenseEnabled(): boolean;
-export declare function useSuspenseEnabledFromConfigAndContext(suspenseFromConfig?: boolean): boolean;
-export declare function useFirebaseApp(): FirebaseApp;
-export {};
+import * as React from 'react';
+import type { FirebaseApp, FirebaseOptions } from 'firebase/app';
+interface FirebaseAppProviderProps {
+    firebaseApp?: FirebaseApp;
+    firebaseConfig?: FirebaseOptions;
+    appName?: string;
+    suspense?: boolean;
+}
+export declare const version: string;
+export declare function FirebaseAppProvider(props: React.PropsWithChildren<FirebaseAppProviderProps>): JSX.Element;
+export declare function useIsSuspenseEnabled(): boolean;
+export declare function useSuspenseEnabledFromConfigAndContext(suspenseFromConfig?: boolean): boolean;
+export declare function useFirebaseApp(): FirebaseApp;
+export {};

package/dist/firestore.d.ts

@@ -1,35 +1,35 @@
-import { ReactFireOptions } from './';
-import { ObservableStatus } from './useObservable';
-import { Query as FirestoreQuery, QuerySnapshot, DocumentReference, DocumentData, DocumentSnapshot } from 'firebase/firestore';
-/**
- * Preload a subscription to a Firestore document reference.
- *
- * Use this to warm up `useFirestoreDoc` for a specific document
- */
-export declare function preloadFirestoreDoc(refProvider: () => Promise<DocumentReference>): Promise<import("./SuspenseSubject").SuspenseSubject<DocumentSnapshot<DocumentData>>>;
-/**
- * Suscribe to Firestore Document changes
- *
- * You can preload data for this hook by calling `preloadFirestoreDoc`
- */
-export declare function useFirestoreDoc<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<DocumentSnapshot<T>>;
-/**
- * Get a firestore document and don't subscribe to changes
- */
-export declare function useFirestoreDocOnce<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<DocumentSnapshot<T>>;
-/**
- * Suscribe to Firestore Document changes and unwrap the document into a plain object
- */
-export declare function useFirestoreDocData<T = unknown>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<T>;
-/**
- * Get a Firestore document, unwrap the document into a plain object, and don't subscribe to changes
- */
-export declare function useFirestoreDocDataOnce<T = unknown>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<T>;
-/**
- * Subscribe to a Firestore collection
- */
-export declare function useFirestoreCollection<T = DocumentData>(query: FirestoreQuery<T>, options?: ReactFireOptions<T[]>): ObservableStatus<QuerySnapshot<T>>;
-/**
- * Subscribe to a Firestore collection and unwrap the snapshot into an array.
- */
-export declare function useFirestoreCollectionData<T = DocumentData>(query: FirestoreQuery<T>, options?: ReactFireOptions<T[]>): ObservableStatus<T[]>;
+import { ReactFireOptions } from './';
+import { ObservableStatus } from './useObservable';
+import { Query as FirestoreQuery, QuerySnapshot, DocumentReference, DocumentData, DocumentSnapshot } from 'firebase/firestore';
+/**
+ * Preload a subscription to a Firestore document reference.
+ *
+ * Use this to warm up `useFirestoreDoc` for a specific document
+ */
+export declare function preloadFirestoreDoc(refProvider: () => Promise<DocumentReference>): Promise<import("./SuspenseSubject").SuspenseSubject<DocumentSnapshot<DocumentData>>>;
+/**
+ * Suscribe to Firestore Document changes
+ *
+ * You can preload data for this hook by calling `preloadFirestoreDoc`
+ */
+export declare function useFirestoreDoc<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<DocumentSnapshot<T>>;
+/**
+ * Get a firestore document and don't subscribe to changes
+ */
+export declare function useFirestoreDocOnce<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<DocumentSnapshot<T>>;
+/**
+ * Suscribe to Firestore Document changes and unwrap the document into a plain object
+ */
+export declare function useFirestoreDocData<T = unknown>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<T>;
+/**
+ * Get a Firestore document, unwrap the document into a plain object, and don't subscribe to changes
+ */
+export declare function useFirestoreDocDataOnce<T = unknown>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<T>;
+/**
+ * Subscribe to a Firestore collection
+ */
+export declare function useFirestoreCollection<T = DocumentData>(query: FirestoreQuery<T>, options?: ReactFireOptions<T[]>): ObservableStatus<QuerySnapshot<T>>;
+/**
+ * Subscribe to a Firestore collection and unwrap the snapshot into an array.
+ */
+export declare function useFirestoreCollectionData<T = DocumentData>(query: FirestoreQuery<T>, options?: ReactFireOptions<T[]>): ObservableStatus<T[]>;

package/dist/functions.d.ts

@@ -0,0 +1,12 @@
+import { ReactFireOptions, ObservableStatus } from './';
+import type { HttpsCallableOptions } from 'firebase/functions';
+/**
+ * Calls a callable function.
+ *
+ * @param functionName - The name of the function to call
+ * @param options
+ */
+export declare function useCallableFunctionResponse<RequestData, ResponseData>(functionName: string, options?: ReactFireOptions<ResponseData> & {
+    httpsCallableOptions?: HttpsCallableOptions;
+    data?: RequestData;
+}): ObservableStatus<ResponseData>;

package/dist/index.d.ts

@@ -1,35 +1,36 @@
-import { SuspenseSubject } from './SuspenseSubject';
-import type { Query as FirestoreQuery } from 'firebase/firestore';
-import type { Query as DatabaseQuery } from 'firebase/database';
-export declare type ReactFireGlobals = {
-    _reactFireDatabaseCachedQueries: Array<DatabaseQuery>;
-    _reactFireFirestoreQueryCache: Array<FirestoreQuery>;
-    _reactFirePreloadedObservables: Map<string, SuspenseSubject<any>>;
-};
-export declare class ReactFireError extends Error {
-    readonly code: string;
-    customData?: Record<string, unknown> | undefined;
-    readonly name = "ReactFireError";
-    constructor(code: string, message: string, customData?: Record<string, unknown> | undefined);
-}
-export interface ReactFireOptions<T = unknown> {
-    idField?: string;
-    initialData?: T | any;
-    /**
-     * @deprecated use initialData instead
-     */
-    startWithValue?: T | any;
-    suspense?: boolean;
-}
-export declare function checkOptions(options: ReactFireOptions, field: string): any;
-export declare function checkinitialData(options: ReactFireOptions): any;
-export declare function checkIdField(options: ReactFireOptions): any;
-export * from './auth';
-export * from './database';
-export * from './firebaseApp';
-export * from './firestore';
-export * from './performance';
-export * from './remote-config';
-export * from './storage';
-export * from './useObservable';
-export * from './sdk';
+import { SuspenseSubject } from './SuspenseSubject';
+import type { Query as FirestoreQuery } from 'firebase/firestore';
+import type { Query as DatabaseQuery } from 'firebase/database';
+export declare type ReactFireGlobals = {
+    _reactFireDatabaseCachedQueries: Array<DatabaseQuery>;
+    _reactFireFirestoreQueryCache: Array<FirestoreQuery>;
+    _reactFirePreloadedObservables: Map<string, SuspenseSubject<any>>;
+};
+export declare class ReactFireError extends Error {
+    readonly code: string;
+    customData?: Record<string, unknown> | undefined;
+    readonly name = "ReactFireError";
+    constructor(code: string, message: string, customData?: Record<string, unknown> | undefined);
+}
+export interface ReactFireOptions<T = unknown> {
+    idField?: string;
+    initialData?: T | any;
+    /**
+     * @deprecated use initialData instead
+     */
+    startWithValue?: T | any;
+    suspense?: boolean;
+}
+export declare function checkOptions(options: ReactFireOptions, field: string): any;
+export declare function checkinitialData(options: ReactFireOptions): any;
+export declare function checkIdField(options: ReactFireOptions): any;
+export * from './auth';
+export * from './database';
+export * from './firebaseApp';
+export * from './firestore';
+export * from './functions';
+export * from './performance';
+export * from './remote-config';
+export * from './storage';
+export * from './useObservable';
+export * from './sdk';