@pomwik/afterdb-react 0.0.0-stage → 0.20.2

package/src/RealmContext.ts

@@ -0,0 +1,196 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// 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 {
+  DynamicRealmProvider,
+  RealmProviderFromConfiguration,
+  RealmProviderFromRealm,
+  createRealmProvider,
+} from "./RealmProvider";
+import { createContext } from "react";
+import Realm from "realm";
+
+export type RealmContext<RealmProvider = DynamicRealmProvider> = {
+  /**
+   * 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.
+   *
+   * 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>;
+};
+
+/**
+ * Creates Realm React hooks and Provider component for a given Realm configuration
+ * @example
+ * ```
+ *class Task extends Realm.Object {
+ *  ...
+ *
+ *  static schema: ObjectSchema = {
+ *    name: 'Task',
+ *    primaryKey: '_id',
+ *    properties: {
+ *      ...
+ *    },
+ *  };
+ *}
+ *
+ *const {useRealm, useQuery, useObject, RealmProvider} = createRealmContext({schema: [Task]});
+ * ```
+ * @param realmConfig - {@link Realm.Configuration} used to open the Realm
+ * @returns An object containing a `RealmProvider` component, and `useRealm`, `useQuery` and `useObject` hooks
+ */
+export function createRealmContext(realmConfig: Realm.Configuration): RealmContext<RealmProviderFromConfiguration>;
+/**
+ * Creates Realm React hooks and Provider component for a given Realm instance.
+ *
+ * **Note:** the hooks returned from `createRealmContext` using an existing Realm can be used outside of the scope of the provider.
+ * @example
+ * ```
+ * const realm = new Realm({ schema: [...] });
+ * const {useRealm, useQuery, useObject, RealmProvider} = createRealmContext(realm);
+ * ```
+ * @param realm - {@link Realm} instance
+ * @returns An object containing a `RealmProvider` component, and `useRealm`, `useQuery` and `useObject` hooks
+ */
+export function createRealmContext(realm: Realm): RealmContext<RealmProviderFromRealm>;
+/**
+ * Creates Realm React hooks and Provider component.
+ * @example
+ * ```
+ * class Task extends Realm.Object {
+ *  ...
+ *  static schema: ObjectSchema = {
+ *    name: 'Task',
+ *    primaryKey: '_id',
+ *    properties: {
+ *      ...
+ *    },
+ *  };
+ * }
+ * const {useRealm, useQuery, useObject, RealmProvider} = createRealmContext();
+ * ...
+ * <RealmProvider schema={[Task]}></RealmProvider>
+ * ```
+ * @example
+ * ```
+ * const realm = await Realm.open({ path: "example.realm", schema: [Task] });
+ * const {RealmProvider} = createRealmContext();
+ * ...
+ * <RealmProvider realm={realm}></RealmProvider>
+ * ```
+ * @returns An object containing a `RealmProvider` component, and `useRealm`, `useQuery` and `useObject` hooks
+ */
+export function createRealmContext(): RealmContext<DynamicRealmProvider>;
+export function createRealmContext(
+  realmOrConfig?: Realm | Realm.Configuration,
+): RealmContext<RealmProviderFromConfiguration | RealmProviderFromRealm | DynamicRealmProvider> {
+  const RealmContext = createContext<Realm | null>(realmOrConfig instanceof Realm ? realmOrConfig : null);
+  const RealmProvider = createRealmProvider(realmOrConfig, RealmContext);
+
+  const useRealm = createUseRealm(RealmContext);
+  const useQuery = createUseQuery(useRealm);
+  const useObject = createUseObject(useRealm);
+
+  return {
+    RealmProvider,
+    useRealm,
+    useQuery,
+    useObject,
+  };
+}

package/src/RealmProvider.tsx

@@ -0,0 +1,251 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2021 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 React, { useContext, useEffect, useRef, useState } from "react";
+import Realm from "realm";
+import isEqual from "lodash.isequal";
+
+import { RestrictivePick } from "./helpers";
+
+type PartialRealmConfiguration = Partial<Realm.Configuration>;
+
+export type RealmProviderFallback = React.ComponentType;
+
+/** Props used for a configuration-based Realm provider */
+type RealmProviderConfigurationProps = {
+  /**
+   * If false, Realm will not be closed when the component unmounts.
+   * @default true
+   */
+  closeOnUnmount?: boolean;
+  /**
+   * A ref to the Realm instance. This is useful if you need to access the Realm
+   * 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?: RealmProviderFallback | React.ComponentType | React.ReactElement | null | undefined;
+  children: React.ReactNode;
+} & PartialRealmConfiguration;
+
+/** Props used for a Realm instance-based Realm provider */
+type RealmProviderRealmProps = {
+  /**
+   * The Realm instance to be used by the provider.
+   */
+  realm: Realm;
+  children: React.ReactNode;
+};
+
+type RealmProviderProps = RealmProviderConfigurationProps & RealmProviderRealmProps;
+
+/**
+ * Represents the provider returned from `createRealmContext` with a Realm instance  i.e. `createRealmContext(new Realm(...))`.
+ * Omits "realm" as it gets set at creation and cannot be changed.
+ 
+ * **Note:** the hooks returned from `createRealmContext` using an existing Realm can be used outside of the scope of the provider.
+ */
+export type RealmProviderFromRealm = React.FC<Omit<RealmProviderRealmProps, "realm">>;
+
+/**
+ * Represents the provider returned from `createRealmContext` with a configuration, i.e. `createRealmContext({schema: [...]})`.
+ */
+export type RealmProviderFromConfiguration = React.FC<RealmProviderConfigurationProps>;
+
+/**
+ * Represents properties of a {@link DynamicRealmProvider} where Realm instance props are set and Configuration props are disallowed.
+ */
+export type DynamicRealmProviderWithRealmProps = RestrictivePick<RealmProviderProps, keyof RealmProviderRealmProps>;
+
+/**
+ * Represents properties of a {@link DynamicRealmProvider} where Realm configuration props are set and Realm instance props are disallowed.
+ */
+export type DynamicRealmProviderWithConfigurationProps = RestrictivePick<
+  RealmProviderProps,
+  keyof RealmProviderConfigurationProps
+>;
+
+/**
+ * Represents the provider returned from creating context with no arguments (including the default context).
+ * Supports either {@link RealmProviderRealmProps} or {@link RealmProviderConfigurationProps}.
+ */
+export type DynamicRealmProvider = React.FC<
+  DynamicRealmProviderWithRealmProps | DynamicRealmProviderWithConfigurationProps
+>;
+
+export function createRealmProviderFromRealm(
+  realm: Realm,
+  RealmContext: React.Context<Realm | null>,
+): RealmProviderFromRealm {
+  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 createRealmProviderFromConfig(
+  realmConfig: Realm.Configuration,
+  RealmContext: React.Context<Realm | null>,
+): RealmProviderFromConfiguration {
+  return ({ children, fallback: Fallback, closeOnUnmount = true, realmRef, ...restProps }) => {
+    const [realm, setRealm] = useState<Realm | null>(() =>
+      realmConfig.sync === undefined && restProps.sync === undefined
+        ? new Realm(mergeRealmConfiguration(realmConfig, restProps))
+        : null,
+    );
+
+    // We increment `configVersion` when a config override passed as a prop
+    // changes, which triggers a `useEffect` to re-open the Realm with the
+    // new config
+    const [configVersion, setConfigVersion] = useState(0);
+
+    // We put realm in a ref to avoid have an endless loop of updates when the realm is updated
+    const currentRealm = useRef(realm);
+
+    // This will merge the configuration provided by createRealmContext and any configuration properties
+    // set directly on the RealmProvider component.  Any settings on the component will override the original configuration.
+    const configuration = useRef<Realm.Configuration>(mergeRealmConfiguration(realmConfig, restProps));
+
+    // Merge and set the configuration again and increment the version if any
+    // of the RealmProvider properties change.
+    useEffect(() => {
+      const combinedConfig = mergeRealmConfiguration(realmConfig, restProps);
+
+      if (!areConfigurationsIdentical(configuration.current, combinedConfig)) {
+        configuration.current = combinedConfig;
+        // Only rerender if realm has already been configured
+        if (currentRealm.current != null) {
+          setConfigVersion((x) => x + 1);
+        }
+      }
+    }, [restProps]);
+
+    useEffect(() => {
+      currentRealm.current = realm;
+      if (realmRef) {
+        realmRef.current = realm;
+      }
+    }, [realm]);
+
+    useEffect(() => {
+      const realmRef = currentRealm.current;
+      // Check if we currently have an open Realm. If we do not (i.e. it is the first
+      // render, or the Realm has been closed due to a config change), then we
+      // need to open a new Realm.
+      const shouldInitRealm = realmRef === null;
+      const initRealm = async () => {
+        const openRealm = await Realm.open(configuration.current);
+        setRealm(openRealm);
+      };
+      if (shouldInitRealm) {
+        initRealm().catch(console.error);
+      }
+
+      return () => {
+        if (realm) {
+          if (closeOnUnmount) {
+            realm.close();
+          }
+          setRealm(null);
+        }
+      };
+    }, [configVersion, realm, setRealm, closeOnUnmount]);
+
+    if (!realm) {
+      if (typeof Fallback === "function") {
+        return <Fallback />;
+      }
+      return <>{Fallback}</>;
+    }
+
+    return <RealmContext.Provider value={realm} children={children} />;
+  };
+}
+
+/**
+ * Generates a `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 createDynamicRealmProvider(RealmContext: React.Context<Realm | null>): DynamicRealmProvider {
+  const RealmProviderFromConfig = createRealmProviderFromConfig({}, RealmContext);
+  return ({ realm, children, ...config }) => {
+    if (realm) {
+      if (Object.keys(config).length > 0) {
+        throw new Error("Cannot use configuration props when using an existing Realm instance.");
+      }
+      return <RealmContext.Provider value={realm} children={children} />;
+    } else {
+      return <RealmProviderFromConfig {...config} children={children} />;
+    }
+  };
+}
+
+/**
+ * Generates the appropriate `RealmProvider` based on whether there is a config, realm, or neither given.
+ * @param realmOrConfig - A Realm instance, 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(
+  realmOrConfig: Realm.Configuration | Realm | undefined,
+  RealmContext: React.Context<Realm | null>,
+): RealmProviderFromConfiguration | RealmProviderFromRealm | DynamicRealmProvider {
+  if (!realmOrConfig) {
+    return createDynamicRealmProvider(RealmContext);
+  } else if (realmOrConfig instanceof Realm) {
+    return createRealmProviderFromRealm(realmOrConfig, RealmContext);
+  } else {
+    return createRealmProviderFromConfig(realmOrConfig, RealmContext);
+  }
+}
+
+/**
+ * Merge two configurations, creating a configuration using `configA` as the default,
+ * merged with `configB`, with properties in `configB` overriding `configA`.
+ * @param configA - The default config object
+ * @param configB - Config overrides object
+ * @returns Merged config object
+ */
+export function mergeRealmConfiguration(
+  configA: PartialRealmConfiguration,
+  configB: PartialRealmConfiguration,
+): Realm.Configuration {
+  return {
+    ...configA,
+    ...configB,
+  };
+}
+
+/**
+ * Utility function that does a deep comparison (key: value) of object a with object b
+ * @param a - Object to compare
+ * @param b - Object to compare
+ * @returns True if the objects are identical
+ */
+export function areConfigurationsIdentical(a: Realm.Configuration, b: Realm.Configuration): boolean {
+  return isEqual(a, b);
+}