RJS-2648: Add ability for Realm instance to be used in RealmProvider

CHANGELOG.md

@@ -6,6 +6,29 @@
 ### Enhancements
 * Report the originating error that caused a client reset to occur. ([realm/realm-core#6154](https://github.com/realm/realm-core/issues/6154))
 * Reduce the size of the local transaction log produced by creating objects, improving the performance of insertion-heavy transactions. ([realm/realm-core#7734](https://github.com/realm/realm-core/pull/7734))
+* Added the ability to use an existing Realm instance in `RealmProvider` and `createRealmContext`. ([#6714](https://github.com/realm/realm-js/pull/6714))
+```jsx
+// Using RealmProvider
+import { RealmProvider } from "@realm/react";
+...
+  const realm = new Realm(...);
+  ...
+  return <RealmProvider realm={realm}> 
+    ...
+  </RealmProvider>
+
+// Using createRealmContext
+import { createRealmContext } from "@realm/react";
+...
+  const realm = new Realm(...);
+
+  const { RealmProvider, useRealm } = createRealmContext(realm);
+  ...
+  return <RealmProvider> 
+    ...
+  </RealmProvider>
+```
+
 
 ### Fixed
 * After compacting, a file upgrade would be triggered. This could cause loss of data for synced Realms. ([realm/realm-core#7747](https://github.com/realm/realm-core/issues/7747), since 12.7.0-rc.0)

packages/realm-react/src/RealmContext.ts

@@ -0,0 +1,109 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2024 Realm Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+////////////////////////////////////////////////////////////////////////////
+
+import { createUseObject } from "./useObject";
+import { createUseQuery } from "./useQuery";
+import { createUseRealm } from "./useRealm";
+import { GeneralizedRealmProviderFC } from "./RealmProvider";
+
+export type RealmContext<RealmProvider = GeneralizedRealmProviderFC> = {
+  /**
+   * The Provider component that is required to wrap any component using
+   * the Realm hooks.
+   * @example
+   * ```
+   * const AppRoot = () => {
+   *   const syncConfig = {
+   *     flexible: true,
+   *     user: currentUser
+   *   };
+   *
+   *   return (
+   *     <RealmProvider schema={[Task, User]} path={"data.realm"} sync={syncConfig}>
+   *       <App/>
+   *     </RealmProvider>
+   *   )
+   * }
+   * ```
+   * @param props - The {@link Realm.Configuration} or {@link Realm} of the provider
+   * are set based on the options passed to `createRealmProvider`. When using a
+   * {@link Realm.Configuration}, individual config keys can be overridden when
+   * creating a `<RealmProvider>` by passing them as props. For example, to override
+   * the `path` config value, use a prop named `path` e.g., `path="newPath.realm"` an
+   * attribute of the same key.
+   */
+  RealmProvider: RealmProvider;
+  /**
+   * Returns the instance of the {@link Realm} opened by the `RealmProvider`.
+   * @example
+   * ```
+   * const realm = useRealm();
+   * ```
+   * @returns a realm instance
+   */
+  useRealm: ReturnType<typeof createUseRealm>;
+
+  /**
+   * Returns a {@link Realm.Collection} of {@link Realm.Object}s from a given type.
+   * The hook will update on any changes to any object in the collection
+   * and return an empty array if the collection is empty.
+   *
+   * The result of this can be consumed directly by the `data` argument of any React Native
+   * VirtualizedList or FlatList.  If the component used for the list's `renderItem` prop is {@link React.Memo}ized,
+   * then only the modified object will re-render.
+   * @example
+   * ```tsx
+   * // Return all collection items
+   * const collection = useQuery({ type: Object });
+   *
+   * // Return all collection items sorted by name and filtered by category
+   * const filteredAndSorted = useQuery({
+   *   type: Object,
+   *   query: (collection) => collection.filtered('category == $0',category).sorted('name'),
+   * }, [category]);
+   *
+   * // Return all collection items sorted by name and filtered by category, triggering re-renders only if "name" changes
+   * const filteredAndSorted = useQuery({
+   *   type: Object,
+   *   query: (collection) => collection.filtered('category == $0',category).sorted('name'),
+   *   keyPaths: ["name"]
+   * }, [category]);
+   * ```
+   * @param options
+   * @param options.type - The object type, depicted by a string or a class extending Realm.Object
+   * @param options.query - A function that takes a {@link Realm.Collection} and returns a {@link Realm.Collection} of the same type. This allows for filtering and sorting of the collection, before it is returned.
+   * @param options.keyPaths - Indicates a lower bound on the changes relevant for the hook. This is a lower bound, since if multiple hooks add listeners (each with their own `keyPaths`) the union of these key-paths will determine the changes that are considered relevant for all listeners registered on the collection. In other words: A listener might fire and cause a re-render more than the key-paths specify, if other listeners with different key-paths are present.
+   * @param deps - An array of dependencies that will be passed to {@link React.useMemo}
+   * @returns a collection of realm objects or an empty array
+   */
+  useQuery: ReturnType<typeof createUseQuery>;
+  /**
+   * Returns a {@link Realm.Object} from a given type and value of primary key.
+   * The hook will update on any changes to the properties on the returned object
+   * and return null if it either doesn't exists or has been deleted.
+   * @example
+   * ```
+   * const object = useObject(ObjectClass, objectId);
+   * ```
+   * @param type - The object type, depicted by a string or a class extending {@link Realm.Object}
+   * @param primaryKey - The primary key of the desired object which will be retrieved using {@link Realm.objectForPrimaryKey}
+   * @param keyPaths - Indicates a lower bound on the changes relevant for the hook. This is a lower bound, since if multiple hooks add listeners (each with their own `keyPaths`) the union of these key-paths will determine the changes that are considered relevant for all listeners registered on the object. In other words: A listener might fire and cause a re-render more than the key-paths specify, if other listeners with different key-paths are present.
+   * @returns either the desired {@link Realm.Object} or `null` in the case of it being deleted or not existing.
+   */
+  useObject: ReturnType<typeof createUseObject>;
+};

packages/realm-react/src/RealmProvider.tsx

@@ -16,7 +16,7 @@
 //
 ////////////////////////////////////////////////////////////////////////////
 
-import React, { useContext, useEffect, useRef, useState } from "react";
+import React, { useContext, useEffect, useMemo, useRef, useState } from "react";
 import Realm from "realm";
 import { isEqual } from "lodash";
 
@@ -26,11 +26,11 @@ type PartialRealmConfiguration = Omit<Partial<Realm.Configuration>, "sync"> & {
   sync?: Partial<Realm.SyncConfiguration>;
 };
 
-type ProviderProps = PartialRealmConfiguration & {
+type RealmProviderProps = {
   /**
-   * The fallback component to render if the Realm is not opened.
+   * The Realm instance to be used by the provider.
    */
-  fallback?: React.ComponentType<unknown> | React.ReactElement | null | undefined;
+  realm?: Realm;
   /**
    * If false, Realm will not be closed when the component unmounts.
    * @default true
@@ -41,43 +41,73 @@ type ProviderProps = PartialRealmConfiguration & {
    * instance outside of a component that uses the Realm hooks.
    */
   realmRef?: React.MutableRefObject<Realm | null>;
+  /**
+   * The fallback component to render if the Realm is not open.
+   */
+  fallback?: React.ComponentType<unknown> | React.ReactElement | null | undefined;
   children: React.ReactNode;
-};
+} & PartialRealmConfiguration;
+
+/**
+  Represents the provider returned from using an existing realm at context creation i.e. `createRealmContext(new Realm))`.
+ */
+export type RealmProviderFromRealmInstanceFC = React.FC<Pick<RealmProviderProps, "children">>;
+
+/**
+ * Represents the provider returned from using a Realm configuration at context creation i.e. `createRealmContext({schema: []}))`.
+ */
+export type RealmProviderFromConfigFC = React.FC<
+  Pick<RealmProviderProps, "closeOnUnmount" | "realmRef" | "fallback" | "children" | keyof PartialRealmConfiguration>
+>;
+
+/**
+ * Explicitly sets the unpicked properties of a type to never instead of dropping them like in Pick.
+ * Useful for ensuring different prop types are mutually exclusive as React expects the union type
+ * of different prop types to include all the fields.
+ */
+type RestrictivePick<T, K extends keyof T> = Pick<T, K> & { [RestrictedKey in keyof Omit<T, K>]?: never };
+
+/**
+ * Represents properties of a generic RealmProvider where the realm is set and therefore all other
+ * props should be disallowed.
+ */
+export type RealmProviderWithRealmInstanceProps = RestrictivePick<RealmProviderProps, "realm" | "children">;
+
+/*
+ * Represents properties of a generic RealmProvider where Realm configuration props are used and no realm is set
+ */
+export type RealmProviderWithConfigurationProps = RestrictivePick<
+  RealmProviderProps,
+  "closeOnUnmount" | "realmRef" | "fallback" | "children" | keyof PartialRealmConfiguration
+>;
+
+/**
+ * Represents the provider returned from creating context with no arguments (including the default context).
+ * Supports either passing a `realm` as a property or the schema configuration.
+ */
+export type GeneralizedRealmProviderFC = React.FC<
+  RealmProviderWithRealmInstanceProps | RealmProviderWithConfigurationProps
+>;
+
+export function createRealmProviderFromRealm(
+  realm: Realm | null,
+  RealmContext: React.Context<Realm | null>,
+): RealmProviderFromRealmInstanceFC {
+  return ({ children }) => {
+    return <RealmContext.Provider value={realm} children={children} />;
+  };
+}
 
 /**
  * Generates a `RealmProvider` given a {@link Realm.Configuration} and {@link React.Context}.
  * @param realmConfig - The configuration of the Realm to be instantiated
  * @param RealmContext - The context that will contain the Realm instance
  * @returns a RealmProvider component that provides context to all context hooks
  */
-export function createRealmProvider(
+export function createRealmProviderFromConfig(
   realmConfig: Realm.Configuration,
   RealmContext: React.Context<Realm | null>,
-): React.FC<ProviderProps> {
-  /**
-   * Returns a Context Provider component that is required to wrap any component using
-   * the Realm hooks.
-   * @example
-   * ```
-   * const AppRoot = () => {
-   *   const syncConfig = {
-   *     flexible: true,
-   *     user: currentUser
-   *   };
-   *
-   *   return (
-   *     <RealmProvider path="data.realm" sync={syncConfig}>
-   *       <App/>
-   *     </RealmProvider>
-   *   )
-   * }
-   * ```
-   * @param props - The {@link Realm.Configuration} for this Realm defaults to
-   * the config passed to `createRealmProvider`, but individual config keys can
-   * be overridden when creating a `<RealmProvider>` by passing them as props.
-   * For example, to override the `path` config value, use a prop named `path`,
-   * e.g. `path="newPath.realm"`
-   */
+): RealmProviderFromConfigFC {
   return ({ children, fallback: Fallback, closeOnUnmount = true, realmRef, ...restProps }) => {
     const [realm, setRealm] = useState<Realm | null>(() =>
       realmConfig.sync === undefined && restProps.sync === undefined
@@ -161,6 +191,45 @@ export function createRealmProvider(
   };
 }
 
+/**
+ * Generates a flexible `RealmProvider` which is either based on a configuration
+ * or based on a realm, depending on its props.
+ * @param RealmContext - The context that will contain the Realm instance
+ * @returns a RealmProvider component that provides context to all context hooks
+ */
+export function createGeneralizedRealmProvider(RealmContext: React.Context<Realm | null>): GeneralizedRealmProviderFC {
+  return ({ realm, ...restProps }) => {
+    return useMemo(() => {
+      if (realm != null) {
+        const RealmProviderFromRealm = createRealmProviderFromRealm(realm, RealmContext);
+        return <RealmProviderFromRealm {...restProps} />;
+      } else {
+        const RealmProviderFromConfig = createRealmProviderFromConfig({}, RealmContext);
+        return <RealmProviderFromConfig {...restProps} />;
+      }
+    }, [realm]);
+  };
+}
+
+/**
+ * Generates the appropriate `RealmProvider` based on whether there is a config, realm, or neither given.
+ * @param realmOrRealmConfig - An existing Realm, a configuration, or undefined (including default provider).
+ * @param RealmContext - The context that will contain the Realm instance
+ * @returns a RealmProvider component that provides context to all context hooks
+ */
+export function createRealmProvider(
+  realmOrRealmConfig: Realm.Configuration | Realm | undefined,
+  RealmContext: React.Context<Realm | null>,
+): RealmProviderFromConfigFC | RealmProviderFromRealmInstanceFC | GeneralizedRealmProviderFC {
+  if (realmOrRealmConfig == undefined) {
+    return createGeneralizedRealmProvider(RealmContext);
+  } else if (realmOrRealmConfig instanceof Realm) {
+    return createRealmProviderFromRealm(realmOrRealmConfig, RealmContext);
+  } else {
+    return createRealmProviderFromConfig(realmOrRealmConfig, RealmContext);
+  }
+}
+
 /**
  * Merge two configurations, creating a configuration using `configA` as the default,
  * merged with `configB`, with properties in `configB` overriding `configA`.