@pomwik/afterdb-react 0.0.0-stage → 0.20.1

package/src/cachedCollection.ts

@@ -0,0 +1,210 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2022 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 { CollectionCallback } from "./helpers";
+
+const numericRegEx = /^-?\d+$/;
+
+function getCacheKey(id: string) {
+  return `${id}`;
+}
+
+/**
+ * Arguments object for {@link createCachedCollection}.
+ */
+type CachedCollectionArgs<T> = {
+  /**
+   * The {@link Realm.Collection} to proxy
+   */
+  collection: Realm.List<T> | Realm.Results<T>;
+
+  /**
+   * The {@link Realm} instance
+   */
+  realm: Realm;
+
+  /**
+   * Callback which is called whenever an object in the collection changes
+   */
+  updateCallback: () => void;
+
+  /**
+   * Reference boolean which is set to true whenever an object in the collection changes
+   * It is used to determine if the collection's object reference should be updated
+   * The implementing component should reset this to false when updating its object reference
+   */
+  updatedRef: React.MutableRefObject<boolean>;
+
+  /**
+   * Optional Map to be used as the cache. This is used to allow a `sorted` or `filtered`
+   * (derived) version of the collection to reuse the same cache, preventing excess new object
+   * references being created.
+   */
+  objectCache?: Map<string, T>;
+
+  /**
+   * Optional flag specifying that this is a derived (`sorted` or `filtered`) version of
+   * an existing collection, so we should not create or remove listeners or clear the cache
+   * when this is torn down.
+   */
+  isDerived?: boolean;
+
+  /**
+   * Optional list of key-paths to limit notifications.
+   */
+  keyPaths?: string[];
+};
+
+/**
+ * Creates a proxy around a {@link Realm.Collection} that will create new {@link Realm.Object}
+ * references on any relevant change (update, insert, deletion) and return the same
+ * object reference if no changes have occurred since the last access.
+ *
+ * This makes the {@link Realm.Collection} behaves in an immutable way, as React expects, so
+ * that a {@link Realm.Object} can be wrapped in {@link React.memo} to prevent unnecessary
+ * rendering (see {@link useQuery} hook).
+ * @param args {@link CachedCollectionArgs} object arguments
+ * @returns Proxy object wrapping the collection
+ */
+export function createCachedCollection<T extends Realm.Object<any>>({
+  collection,
+  realm,
+  updateCallback,
+  updatedRef,
+  objectCache = new Map(),
+  isDerived = false,
+  keyPaths,
+}: CachedCollectionArgs<T>): { collection: Realm.Results<T> | Realm.List<T>; tearDown: () => void } {
+  const cachedCollectionHandler: ProxyHandler<Realm.Results<T> | Realm.List<T>> = {
+    get: function (target, key, receiver) {
+      // Pass functions through
+      const value = Reflect.get(target, key, receiver);
+      if (typeof value === "function") {
+        if (key === "sorted" || key === "filtered") {
+          return (...args: unknown[]) => {
+            const col: Realm.Results<T & Realm.Object> = Reflect.apply(value, target, args);
+            const { collection: newCol } = createCachedCollection({
+              collection: col,
+              realm,
+              updateCallback,
+              updatedRef,
+              objectCache,
+              isDerived: true,
+              keyPaths,
+            });
+            return newCol;
+          };
+        }
+        return value;
+      }
+
+      // If the key is not numeric, pass it through
+      if (typeof key === "symbol" || !numericRegEx.test(key)) {
+        return value;
+      }
+
+      // If the key is numeric, check if we have a cached object for this key
+      const index = Number(key);
+      const object = target[index];
+
+      // If the collection is modeled in a way that objects can be null
+      // then we should return null instead of undefined to stay semantically
+      // correct
+      if (object === null) {
+        return null;
+      } else if (typeof object === "undefined") {
+        // If there is no object at this index, return undefined
+        return undefined;
+      }
+
+      const objectId = object._objectKey();
+      const cacheKey = getCacheKey(objectId);
+
+      // If we do, return it...
+      if (objectCache.get(cacheKey)) {
+        return objectCache.get(cacheKey);
+      }
+
+      // If not then this index has either not been accessed before, or has been invalidated due
+      // to a modification. Fetch it from the collection and store it in the cache
+      objectCache.set(cacheKey, object);
+
+      return object;
+    },
+  };
+
+  const cachedCollectionResult = new Proxy(collection, cachedCollectionHandler);
+
+  const listenerCallback: CollectionCallback = (listenerCollection, changes) => {
+    if (changes.deletions.length > 0 || changes.insertions.length > 0 || changes.newModifications.length > 0) {
+      // TODO: There is currently no way to rebuild the cache key from the changes array for deleted object.
+      // Until it is possible, we clear the cache on deletions.
+      // Blocking issue: https://github.com/realm/realm-core/issues/5220
+
+      // Possible solutions:
+      // a. the listenerCollection is a frozen copy of the collection before the deletion,
+      // allowing accessing the _objectKey() using listenerCollection[index]._objectKey()
+      // b. the callback provides an array of changed objectIds
+
+      if (changes.deletions.length > 0) {
+        objectCache.clear();
+      }
+
+      // Item(s) were modified, just clear them from the cache so that we return new instances for them
+      changes.newModifications.forEach((index) => {
+        const objectId = listenerCollection[index]._objectKey();
+        if (objectId) {
+          const cacheKey = getCacheKey(objectId);
+          if (objectCache.has(cacheKey)) {
+            objectCache.delete(cacheKey);
+          }
+        }
+      });
+      updatedRef.current = true;
+      updateCallback();
+    }
+  };
+
+  let setImmediateId: ReturnType<typeof setImmediate> | undefined = undefined;
+  if (!isDerived) {
+    // If we are in a transaction, then push adding the listener to the event loop.  This will allow the write transaction to finish.
+    // see https://github.com/realm/realm-js/issues/4375
+    if (realm.isInTransaction) {
+      setImmediateId = setImmediate(() => {
+        collection.addListener(listenerCallback, keyPaths);
+      });
+    } else {
+      collection.addListener(listenerCallback, keyPaths);
+    }
+  }
+
+  const tearDown = () => {
+    if (!isDerived) {
+      if (setImmediateId) {
+        clearImmediate(setImmediateId);
+        setImmediateId = undefined;
+      }
+      collection.removeListener(listenerCallback);
+      objectCache.clear();
+    }
+  };
+
+  return { collection: cachedCollectionResult, tearDown };
+}

package/src/cachedObject.ts

@@ -0,0 +1,164 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2022 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 { createCachedCollection } from "./cachedCollection";
+
+/**
+ * Arguments object for `cachedObject`.
+ */
+type CachedObjectArgs = {
+  /**
+   * The {@link Realm.Object} to proxy
+   */
+  object: Realm.Object | null;
+  /**
+   * The {@link Realm} instance
+   */
+  realm: Realm;
+  /**
+   * Callback function called whenver the object changes. Used to force a component
+   * using the {@link useObject} hook to re-render.
+   */
+  updateCallback: () => void;
+
+  /**
+   * Reference boolean which is set to true whenever the object changes
+   * It is used to determine if the object's reference should be updated
+   * The implementing component should reset this to false when updating its object reference
+   */
+  updatedRef: React.MutableRefObject<boolean>;
+
+  /**
+   * Optional list of key-paths to limit notifications.
+   */
+  keyPaths?: string[];
+};
+
+export type CachedObject = {
+  object: Realm.Object | null;
+  tearDown: () => void;
+};
+
+/**
+ * Creates a proxy around a {@link Realm.Object} that will return a new reference
+ * on any relevant update to the object itself. It also wraps accesses to {@link Realm.List}
+ * attributes into a {@link cachedCollection}, so that any update, insert or deletion to the
+ * list will also return a new object reference.
+ *
+ * See {@link cachedCollection} and the `useObject` hook for description of how this
+ * helps prevent unnecessary rendering.
+ * @param args - {@link CachedObjectArgs} object arguments
+ * @returns Proxy object wrapping the {@link Realm.Object}
+ */
+export function createCachedObject({
+  object,
+  realm,
+  updateCallback,
+  updatedRef,
+  keyPaths,
+}: CachedObjectArgs): CachedObject {
+  const listCaches = new Map();
+  const listTearDowns: Array<() => void> = [];
+  // If the object doesn't exist, just return it with an noop tearDown
+  //
+  if (object === null) {
+    return { object, tearDown: () => undefined };
+  }
+
+  // Create a cache for any Realm.List properties on the object
+  for (const key of object.keys()) {
+    //@ts-expect-error - TS doesn't know that the key is a valid property
+    const value = object[key];
+    if (value instanceof Realm.List && value.type === "object") {
+      const updatedRef = { current: true };
+      const { collection, tearDown } = createCachedCollection({ collection: value, realm, updateCallback, updatedRef });
+      listCaches.set(key, { collection, updatedRef });
+      listTearDowns.push(tearDown);
+    }
+  }
+
+  // This Proxy handler intercepts any accesses into properties of the cached object
+  // of type `Realm.List`, and returns a `cachedCollection` wrapping those properties
+  // to allow changes in the list to trigger re-renders
+  const cachedObjectHandler: ProxyHandler<Realm.Object> = {
+    get: function (target, key, receiver) {
+      const value = Reflect.get(target, key, receiver);
+
+      // If its a Realm.List we need to add a proxy cache around it
+      if (value instanceof Realm.List && value.type === "object") {
+        if (listCaches.has(key)) {
+          // Return a new proxy wrapping the cachedCollection so that its reference gets updated,
+          // otherwise the list component will not re-render. The cachedCollection then ensures that
+          // only the modified children of the list component actually re-render.
+          const { collection, updatedRef } = listCaches.get(key);
+          if (updatedRef.current) {
+            updatedRef.current = false;
+            const proxyCollection = new Proxy(collection, {});
+            listCaches.set(key, { collection: proxyCollection, updatedRef });
+            return proxyCollection;
+          }
+          return collection;
+        }
+      }
+      return value;
+    },
+  };
+
+  const cachedObjectResult = new Proxy(object, cachedObjectHandler);
+  const listenerCallback: Realm.ObjectChangeCallback<any> = (obj, changes) => {
+    updatedRef.current = true;
+    if (changes.deleted) {
+      updateCallback();
+    } else if (changes.changedProperties.length > 0) {
+      // Don't force a second re-render if any of the changed properties is a Realm.List,
+      // as the List's cachedCollection will force a re-render itself
+      const anyListPropertyModified = changes.changedProperties.some((property) => {
+        return obj[property] instanceof Realm.List && obj[property].type === "object";
+      });
+      const shouldRerender = !anyListPropertyModified;
+
+      if (shouldRerender) {
+        updateCallback();
+      }
+    }
+  };
+
+  // We cannot add a listener to an invalid object
+  if (object.isValid()) {
+    // If we are in a transaction, then push adding the listener to the event loop.  This will allow the write transaction to finish.
+    // see https://github.com/realm/realm-js/issues/4375
+    if (realm.isInTransaction) {
+      setImmediate(() => {
+        object.addListener(listenerCallback, keyPaths);
+      });
+    } else {
+      object.addListener(listenerCallback, keyPaths);
+    }
+  }
+
+  const tearDown = () => {
+    object.removeListener(listenerCallback);
+    for (const listTearDown of listTearDowns) {
+      listTearDown();
+    }
+  };
+
+  return { object: cachedObjectResult, tearDown };
+}

package/src/helpers.ts

@@ -0,0 +1,60 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// 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.
+//
+////////////////////////////////////////////////////////////////////////////
+
+import Realm from "realm";
+
+// Convenience function that returns the correct type for the objectForPrimaryKey function
+// Since we don't have a combined declaration for this function, typescript needs to know
+// which return to use based on the typeof the type argument
+export function getObjectForPrimaryKey<T extends Realm.Object>(
+  realm: Realm,
+  type: string | { new (...args: any): T },
+  primaryKey: T[keyof T],
+) {
+  return typeof type === "string"
+    ? realm.objectForPrimaryKey(type, primaryKey)
+    : realm.objectForPrimaryKey(type, primaryKey);
+}
+
+// Convenience function that returns the correct type for the objects function
+// Since we don't have a combined declaration for this function, typescript needs to know
+// which return to use based on the typeof the type argument
+export function getObjects<T extends Realm.Object>(
+  realm: Realm,
+  type: string | { new (...args: any): T },
+): Realm.Results<T> {
+  return (typeof type === "string" ? realm.objects(type) : realm.objects(type)) as Realm.Results<T>;
+}
+
+export type CollectionCallback = Parameters<typeof Realm.Results.prototype.addListener>[0];
+
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+export type AnyRealmObject = Realm.Object<any>;
+
+export type RealmClassType<T = any> = { new (...args: any): T };
+
+/**
+ * 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.
+ */
+export type RestrictivePick<T, K extends keyof T> = Pick<T, K> & { [RestrictedKey in keyof Omit<T, K>]?: never };
+
+export function isClassModelConstructor(value: unknown): value is RealmClassType<unknown> {
+  return Object.getPrototypeOf(value) === Realm.Object;
+}

package/src/index.tsx

@@ -0,0 +1,130 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// 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 React from "react";
+import { createRealmContext } from "./RealmContext";
+
+export type { UseObjectHook } from "./useObject";
+export type { UseQueryHook, QueryHookOptions } from "./useQuery";
+
+const defaultContext = createRealmContext();
+
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ * @example
+ *  const syncConfig = {
+ *     flexible: true,
+ *     user: currentUser
+ *   };
+ *  const realm = new Realm(schema:[Task, User], path:"data.realm", sync: syncConfig);
+ *  ...
+ *  const AppRoot = () => {
+ *   return (
+ *     <RealmProvider>
+ *       <App/>
+ *     </RealmProvider>
+ *   )
+ * }
+ * @param props - The {@link Realm.Configuration} or {@link Realm} for this Provider, passed as props.
+ */
+export const RealmProvider = defaultContext.RealmProvider;
+
+/**
+ * Returns the instance of the {@link Realm} opened by the `RealmProvider`.
+ * @example
+ * ```
+ * const realm = useRealm();
+ * ```
+ * @returns a realm instance
+ */
+export const useRealm = defaultContext.useRealm;
+
+/**
+ * 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
+ */
+export const useQuery = defaultContext.useQuery;
+
+/**
+ * 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.
+ */
+export const useObject = defaultContext.useObject;
+
+/*
+ * @ignore This will end up documenting all of Realm, which is documented elsewhere
+ */
+export { Realm };
+export { createRealmContext } from "./RealmContext";
+export * from "./types";
+export { createUseObject } from "./useObject";
+export { createUseQuery } from "./useQuery";

package/src/runtime.d.ts

@@ -0,0 +1,31 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// 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.
+//
+////////////////////////////////////////////////////////////////////////////
+
+declare type Console = {
+  log(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+};
+
+declare const console: Console;
+
+declare function setImmediate(cb: (...args: unknown[]) => void);
+
+declare type Timer = unknown;
+declare function clearImmediate(timer: Timer): void;
+