@pomwik/afterdb-react 0.0.0-stage → 0.20.2

package/src/types.ts

@@ -0,0 +1,92 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2023 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.
+//
+////////////////////////////////////////////////////////////////////////////
+
+export enum AuthOperationName {
+  LogIn = "logIn",
+  LogInWithAnonymous = "logInWithAnonymous",
+  LogInWithApiKey = "logInWithApiKey",
+  LogInWithEmailPassword = "logInWithEmailPassword",
+  LogInWithJWT = "logInWithJWT",
+  LogInWithGoogle = "logInWithGoogle",
+  LogInWithApple = "logInWithApple",
+  LogInWithFacebook = "logInWithFacebook",
+  LogInWithFunction = "logInWithFunction",
+  LogOut = "logOut",
+  Register = "register",
+  Confirm = "confirm",
+  ResendConfirmationEmail = "resendConfirmationEmail",
+  RetryCustomConfirmation = "retryCustomConfirmation",
+  SendResetPasswordEmail = "sendResetPasswordEmail",
+  ResetPassword = "resetPassword",
+  CallResetPasswordFunction = "callResetPasswordFunction",
+}
+
+/**
+ * The `AuthError` is set based on the operation name and the error message.
+ */
+export class AuthError extends Error {
+  public operation: AuthOperationName;
+  constructor(operation: AuthOperationName, message: string) {
+    super(message);
+    this.name = "AuthError";
+    this.operation = operation;
+  }
+}
+
+/**
+ * The possible states an {@link OperationResult} can be in.
+ */
+export enum OperationState {
+  NotStarted = "not-started",
+  Pending = "pending",
+  Success = "success",
+  Error = "error",
+}
+
+/**
+ * Represents the state and result of a call to a hook operation. This is
+ * designed to allow the user to update their UI accordingly without needing to
+ * store separate React state to keep track of pending/error states etc.
+ */
+export type OperationResult = {
+  /**
+   * The current state of the operation.
+   */
+  state: OperationState;
+
+  /**
+   * The string name of the current operation running.
+   */
+  operation: AuthOperationName | null;
+
+  /**
+   * Convenience accessors, so users can write e.g. `loginResult.pending`
+   * instead of `loginResult.state === OperationState.Pending`
+   */
+  pending: boolean;
+  success: boolean;
+
+  /**
+   * The error returned from the operation, if any. This will only be populated
+   * if `state === OperationState.Error`, and will be cleared each time the
+   * operation is called.
+   */
+  error: AuthError | undefined;
+};
+
+export type AuthResult = OperationResult;

package/src/useObject.tsx

@@ -0,0 +1,227 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// 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 { useEffect, useMemo, useReducer, useRef } from "react";
+import Realm from "realm";
+
+import { CachedObject, createCachedObject } from "./cachedObject";
+import {
+  AnyRealmObject,
+  CollectionCallback,
+  getObjectForPrimaryKey,
+  getObjects,
+  isClassModelConstructor,
+} from "./helpers";
+import { UseRealmHook } from "./useRealm";
+
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+type RealmClassType<T = any> = { new (...args: any): T };
+
+export type ObjectHookOptions<T> = {
+  type: string;
+  primaryKey: T[keyof T];
+  keyPaths?: string | string[];
+};
+
+export type ObjectHookClassBasedOptions<T> = {
+  type: RealmClassType<T>;
+  primaryKey: T[keyof T];
+  keyPaths?: string | string[];
+};
+
+export type UseObjectHook = {
+  <T>(options: ObjectHookOptions<T>): (T & Realm.Object<T>) | null;
+  <T extends AnyRealmObject>(options: ObjectHookClassBasedOptions<T>): T | null;
+
+  <T>(type: string, primaryKey: T[keyof T], keyPaths?: string | string[]): (T & Realm.Object<T>) | null;
+  <T extends AnyRealmObject>(type: RealmClassType<T>, primaryKey: T[keyof T], keyPaths?: string | string[]): T | null;
+};
+
+/**
+ * Generates the `useObject` hook from a given `useRealm` hook.
+ * @param useRealm - Hook that returns an open Realm instance
+ * @returns useObject - Hook that is used to gain access to a single Realm object from a primary key
+ */
+export function createUseObject(useRealm: UseRealmHook): UseObjectHook {
+  function useObject<T extends AnyRealmObject>(
+    type: string | RealmClassType<T>,
+    primaryKey: T[keyof T],
+    keyPaths?: string | string[],
+  ): T | null {
+    const realm = useRealm();
+
+    // Create a forceRerender function for the cachedObject to use as its updateCallback, so that
+    // the cachedObject can force the component using this hook to re-render when a change occurs.
+    const [, forceRerender] = useReducer((x) => x + 1, 0);
+
+    // Get the original object from the realm, so we can check if it exists
+    const originalObject = getObjectForPrimaryKey(realm, type, primaryKey);
+
+    // Store the primaryKey as a ref, since when it is an objectId or UUID, it will be a new instance on every render
+    const primaryKeyRef = useRef(primaryKey);
+
+    const collectionRef = useRef(getObjects(realm, type));
+
+    const objectRef = useRef<T & Realm.Object<T>>(null);
+    const updatedRef = useRef(true);
+
+    // Initializing references with a function call or class constructor will
+    // cause the function or constructor to be called on ever render.
+    // Even though this value is thrown away on subsequent renders, `createCachedObject` will end up registering a listener.
+    // Therefore, we initialize the references with null, and only create the object if it is null
+    // Ref: https://github.com/facebook/react/issues/14490
+    const cachedObjectRef = useRef<null | CachedObject>(null);
+
+    const memoizedKeyPaths = useMemo(
+      () => (typeof keyPaths === "string" ? [keyPaths] : keyPaths),
+      /* eslint-disable-next-line react-hooks/exhaustive-deps -- Memoizing the keyPaths to avoid renders */
+      [JSON.stringify(keyPaths)],
+    );
+
+    if (!cachedObjectRef.current) {
+      cachedObjectRef.current = createCachedObject({
+        object: originalObject ?? null,
+        realm,
+        updateCallback: forceRerender,
+        updatedRef,
+        keyPaths: memoizedKeyPaths,
+      });
+    }
+
+    // Create a ref, since the object returned from `objectForPrimaryKey` is always going to have a different reference
+    const originalObjectRef = useRef(originalObject);
+
+    // Wrap the cachedObject in useMemo, so we only replace it with a new instance if `primaryKey` or `type` change
+    const { object, tearDown } = useMemo(
+      // TODO: There will be an upcoming breaking change that makes objectForPrimaryKey return null
+      // When this is implemented, remove `?? null`
+      () => {
+        // This should never happen, but if it does, we want to return a null result
+        if (!cachedObjectRef.current) {
+          return { object: null, tearDown: () => undefined };
+        }
+
+        // Re-instantiate the cachedObject if the primaryKey has changed or the originalObject has gone from null to not null
+        if (
+          !arePrimaryKeysIdentical(primaryKey, primaryKeyRef.current) ||
+          (!originalObjectRef.current && originalObject)
+        ) {
+          cachedObjectRef.current = createCachedObject({
+            object: originalObject ?? null,
+            realm,
+            updateCallback: forceRerender,
+            updatedRef,
+            keyPaths: memoizedKeyPaths,
+          });
+          originalObjectRef.current = originalObject;
+
+          // Primary key has updated, so update the reference
+          primaryKeyRef.current = primaryKey;
+          // Signal that the object reference needs to be updated
+          updatedRef.current = true;
+        }
+        return cachedObjectRef.current;
+      },
+      [realm, originalObject, primaryKey, memoizedKeyPaths],
+    );
+
+    // Invoke the tearDown of the cachedObject when useObject is unmounted
+    useEffect(() => {
+      return tearDown;
+    }, [tearDown]);
+
+    // If the object doesn't exist, listen for insertions to the collection and force a rerender if the inserted object has the correct primary key
+    useEffect(() => {
+      const collection = collectionRef.current;
+      const collectionListener: CollectionCallback = (_, changes) => {
+        const primaryKeyProperty = collection?.[0]?.objectSchema()?.primaryKey;
+        for (const index of changes.insertions) {
+          const object = collection[index];
+          if (primaryKeyProperty) {
+            //@ts-expect-error - if the primaryKeyProperty exists, then it is indexable. However, we don't allow it when we don't actually know the type of the object
+            const insertedPrimaryKey = object[primaryKeyProperty];
+            if (arePrimaryKeysIdentical(insertedPrimaryKey, primaryKeyRef.current)) {
+              forceRerender();
+              collection.removeListener(collectionListener);
+              break;
+            }
+          }
+        }
+      };
+
+      if (!originalObjectRef.current) {
+        collection.addListener(collectionListener);
+      }
+
+      return () => {
+        // If the app is closing, the realm will be closed and the listener does not need to be removed if
+        if (!realm.isClosed && collection) {
+          collection.removeListener(collectionListener);
+        }
+      };
+    }, [realm, type, forceRerender]);
+
+    // If the object has been deleted or doesn't exist for the given primary key, just return null
+    if (!object?.isValid()) {
+      return null;
+    }
+
+    if (updatedRef.current) {
+      // Wrap object in a proxy to update the reference on rerender ( should only rerender when something has changed )
+      objectRef.current = new Proxy(object, {}) as T & Realm.Object<T>;
+      updatedRef.current = false;
+    }
+    // This will never be undefined, but the type system doesn't know that
+    return objectRef.current as T;
+  }
+
+  return function useObjectOverload<T extends AnyRealmObject>(
+    typeOrOptions: string | RealmClassType<T> | ObjectHookOptions<T> | ObjectHookClassBasedOptions<T>,
+    primaryKey?: T[keyof T],
+    keyPaths?: string | string[],
+  ): T | null {
+    if (typeof typeOrOptions === "string" || isClassModelConstructor(typeOrOptions)) {
+      if (typeof primaryKey === "undefined") {
+        throw new Error("Expected a primary key");
+      }
+      /* eslint-disable-next-line react-hooks/rules-of-hooks -- We're calling `useQuery` once in any of the brances */
+      return useObject<T>(typeOrOptions, primaryKey, keyPaths);
+    } else {
+      const { type, primaryKey, keyPaths } = typeOrOptions;
+      /* eslint-disable-next-line react-hooks/rules-of-hooks -- We're calling `useQuery` once in any of the brances */
+      return useObject<T>(type, primaryKey, keyPaths);
+    }
+  };
+}
+
+// This is a helper function that determines if two primary keys are equal.  It will also handle the case where the primary key is an ObjectId or UUID
+function arePrimaryKeysIdentical(a: unknown, b: unknown): boolean {
+  if (typeof a !== typeof b) {
+    return false;
+  }
+  if (typeof a === "string" || typeof a === "number") {
+    return a === b;
+  }
+  if (a instanceof Realm.BSON.ObjectId && b instanceof Realm.BSON.ObjectId) {
+    return a.toHexString() === b.toHexString();
+  }
+  if (a instanceof Realm.BSON.UUID && b instanceof Realm.BSON.UUID) {
+    return a.toHexString() === b.toHexString();
+  }
+  return false;
+}

package/src/useQuery.tsx

@@ -0,0 +1,205 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// 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 { useCallback, useEffect, useMemo, useReducer, useRef } from "react";
+import Realm from "realm";
+
+import { createCachedCollection } from "./cachedCollection";
+import { AnyRealmObject, RealmClassType, getObjects, isClassModelConstructor } from "./helpers";
+
+type QueryCallback<T> = (collection: Realm.Results<T>) => Realm.Results<T>;
+type DependencyList = ReadonlyArray<unknown>;
+
+export type QueryHookPartialOptions<T> = {
+  type: string | RealmClassType<T>;
+  keyPaths?: string | string[];
+};
+
+export type QueryHookOptions<T> = QueryHookPartialOptions<T> & {
+  query?: QueryCallback<T>;
+};
+
+export type UseQueryHook = {
+  <T>(options: QueryHookOptions<T>, deps?: DependencyList): Realm.Results<T & Realm.Object<T>>;
+  <T extends AnyRealmObject>(options: QueryHookOptions<T>, deps?: DependencyList): Realm.Results<T>;
+  <T>(type: string): Realm.Results<T & Realm.Object<T>>;
+  <T extends AnyRealmObject>(type: RealmClassType<T>): Realm.Results<T>;
+  <T extends AnyRealmObject>(
+    query: QueryCallback<T>,
+    deps: DependencyList,
+    options: QueryHookPartialOptions<T>,
+  ): Realm.Results<T>;
+  <T>(query: QueryCallback<T>, deps: DependencyList, options: QueryHookPartialOptions<T>): Realm.Results<
+    T & Realm.Object<T>
+  >;
+
+  /** @deprecated To help the `react-hooks/exhaustive-deps` eslint rule detect missing dependencies, we've suggest passing a option object as the first argument */
+  <T>(type: string, query?: QueryCallback<T>, deps?: DependencyList): Realm.Results<T & Realm.Object<T>>;
+  /** @deprecated To help the `react-hooks/exhaustive-deps` eslint rule detect missing dependencies, we've suggest passing a option object as the first argument */
+  <T extends AnyRealmObject>(
+    type: RealmClassType<T>,
+    query?: QueryCallback<T>,
+    deps?: DependencyList,
+  ): Realm.Results<T>;
+};
+
+type PossibleQueryArgs<T> = {
+  typeOrOptionsOrQuery: QueryHookOptions<T> | string | RealmClassType<T> | QueryCallback<T>;
+  queryOrDeps?: DependencyList | QueryCallback<T>;
+  depsOrPartialOptions?: DependencyList | QueryHookPartialOptions<T>;
+};
+
+/**
+ * Maps a value to itself
+ */
+function identity<T>(value: T): T {
+  return value;
+}
+
+/**
+ * Generates the `useQuery` hook from a given `useRealm` hook.
+ * @param useRealm - Hook that returns an open Realm instance
+ * @returns useObject - Hook that is used to gain access to a {@link Realm.Collection}
+ */
+export function createUseQuery(useRealm: () => Realm): UseQueryHook {
+  function useQuery<T extends AnyRealmObject>(
+    { type, query = identity, keyPaths }: QueryHookOptions<T>,
+    deps: DependencyList = [],
+  ): Realm.Results<T> {
+    const realm = useRealm();
+
+    // We need to add the type to the deps, so that if the type changes, the query will be re-run.
+    // This will be saved in an array which will be spread into the provided deps.
+    const requiredDeps = [type];
+
+    // Create a forceRerender function for the cachedCollection to use as its updateCallback, so that
+    // the cachedCollection can force the component using this hook to re-render when a change occurs.
+    const [, forceRerender] = useReducer((x) => x + 1, 0);
+    const collectionRef = useRef<Realm.Results<T>>(null);
+    const updatedRef = useRef(true);
+    const queryCallbackRef = useRef<QueryCallback<T> | null>(null);
+
+    /* eslint-disable-next-line react-hooks/exhaustive-deps -- We want the user of this hook to be able pass in the `query` function inline (without the need to `useCallback` on it)
+    This means that the query function is unstable and will be a redefined on each render of the component where `useQuery` is used
+    Therefore we use the `deps` array to memoize the query function internally, and only use the returned `queryCallback` */
+    const queryCallback = useCallback(query, [...deps, ...requiredDeps]);
+
+    // If the query function changes, we need to update the cachedCollection
+    if (queryCallbackRef.current !== queryCallback) {
+      queryCallbackRef.current = queryCallback;
+      updatedRef.current = true;
+    }
+
+    const queryResult = useMemo(() => {
+      return queryCallback(getObjects(realm, type));
+    }, [type, realm, queryCallback]);
+
+    const memoizedKeyPaths = useMemo(
+      () => (typeof keyPaths === "string" ? [keyPaths] : keyPaths),
+      /* eslint-disable-next-line react-hooks/exhaustive-deps -- Memoizing the keyPaths to avoid renders */
+      [JSON.stringify(keyPaths)],
+    );
+
+    // Wrap the cachedObject in useMemo, so we only replace it with a new instance if `realm` or `queryResult` change
+    const { collection, tearDown } = useMemo(() => {
+      return createCachedCollection<T>({
+        collection: queryResult,
+        realm,
+        updateCallback: forceRerender,
+        updatedRef,
+        keyPaths: memoizedKeyPaths,
+      });
+    }, [realm, queryResult, memoizedKeyPaths]);
+
+    // Invoke the tearDown of the cachedCollection when useQuery is unmounted
+    useEffect(() => {
+      return tearDown;
+    }, [tearDown]);
+
+    // This makes sure the collection has a different reference on a rerender
+    // Also we are ensuring the type returned is Realm.Results, as this is known in this context
+    if (updatedRef.current) {
+      updatedRef.current = false;
+      collectionRef.current = new Proxy(collection as Realm.Results<T & Realm.Object>, {});
+    }
+
+    // This will never not be defined, but the type system doesn't know that
+    return collectionRef.current as Realm.Results<T>;
+  }
+
+  return function useQueryOverload<T extends AnyRealmObject>(
+    typeOrOptionsOrQuery: PossibleQueryArgs<T>["typeOrOptionsOrQuery"],
+    queryOrDeps: PossibleQueryArgs<T>["queryOrDeps"] = identity,
+    depsOrPartialOptions: PossibleQueryArgs<T>["depsOrPartialOptions"] = [],
+  ): Realm.Results<T> {
+    const args = { typeOrOptionsOrQuery, queryOrDeps, depsOrPartialOptions };
+    /* eslint-disable react-hooks/rules-of-hooks -- We're calling `useQuery` once in any of the brances */
+    if (isTypeFunctionDeps(args)) {
+      return useQuery({ type: args.typeOrOptionsOrQuery, query: args.queryOrDeps }, args.depsOrPartialOptions);
+    }
+    if (isOptionsDepsNone(args)) {
+      return useQuery(args.typeOrOptionsOrQuery, Array.isArray(args.queryOrDeps) ? args.queryOrDeps : []);
+    }
+    if (isFunctionDepsOptions(args)) {
+      return useQuery({ ...args.depsOrPartialOptions, query: args.typeOrOptionsOrQuery }, args.queryOrDeps);
+    }
+    /* eslint-enable react-hooks/rules-of-hooks */
+
+    throw new Error("Unexpected arguments passed to useQuery");
+  };
+}
+
+function isTypeFunctionDeps<T>(args: PossibleQueryArgs<T>): args is {
+  typeOrOptionsOrQuery: string | RealmClassType<T>;
+  queryOrDeps: QueryCallback<T>;
+  depsOrPartialOptions: DependencyList;
+} {
+  const { typeOrOptionsOrQuery, queryOrDeps, depsOrPartialOptions } = args;
+  return (
+    (typeof typeOrOptionsOrQuery === "string" || isClassModelConstructor(typeOrOptionsOrQuery)) &&
+    typeof queryOrDeps === "function" &&
+    Array.isArray(depsOrPartialOptions)
+  );
+}
+
+function isOptionsDepsNone<T>(args: PossibleQueryArgs<T>): args is {
+  typeOrOptionsOrQuery: QueryHookOptions<T>;
+  queryOrDeps: DependencyList | typeof identity;
+  depsOrPartialOptions: never;
+} {
+  const { typeOrOptionsOrQuery, queryOrDeps } = args;
+  return (
+    typeof typeOrOptionsOrQuery === "object" &&
+    typeOrOptionsOrQuery !== null &&
+    (Array.isArray(queryOrDeps) || queryOrDeps === identity)
+  );
+}
+
+function isFunctionDepsOptions<T>(args: PossibleQueryArgs<T>): args is {
+  typeOrOptionsOrQuery: QueryCallback<T>;
+  queryOrDeps: DependencyList;
+  depsOrPartialOptions: QueryHookPartialOptions<T>;
+} {
+  const { typeOrOptionsOrQuery, queryOrDeps, depsOrPartialOptions } = args;
+  return (
+    typeof typeOrOptionsOrQuery === "function" &&
+    Array.isArray(queryOrDeps) &&
+    typeof depsOrPartialOptions === "object" &&
+    depsOrPartialOptions !== null
+  );
+}

package/src/useRealm.tsx

@@ -0,0 +1,41 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// 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 Realm from "realm";
+import { useContext } from "react";
+
+export type UseRealmHook = {
+  (): Realm;
+};
+
+/**
+ * Generates a `useRealm` hook given a RealmContext.  This allows access to the {@link Realm}
+ * instance anywhere within the RealmProvider.
+ * @param RealmContext - The context containing the {@link Realm} instance
+ * @returns useRealm - Hook that is used to gain access to the {@link Realm} instance
+ */
+export const createUseRealm = (RealmContext: React.Context<Realm | null>): UseRealmHook => {
+  return function useRealm() {
+    // This is the context setup by `createRealmContext`
+    const context = useContext(RealmContext);
+    if (context === null) {
+      throw new Error("Realm context not found.  Did you call useRealm() within a <RealmProvider/>?");
+    }
+    return context;
+  };
+};