@latticexyz/react 2.0.0-alpha.1.78 → 2.0.0-alpha.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latticexyz/react",
-  "version": "2.0.0-alpha.1.78+3079e4de",
+  "version": "2.0.0-alpha.1.80+943e962f",
   "description": "React tools for MUD client.",
   "repository": {
     "type": "git",
@@ -23,7 +23,7 @@
     "test": "tsc --noEmit && jest"
   },
   "dependencies": {
-    "@latticexyz/recs": "2.0.0-alpha.1.78+3079e4de",
+    "@latticexyz/recs": "2.0.0-alpha.1.80+943e962f",
     "fast-deep-equal": "^3.1.3",
     "mobx": "^6.7.0",
     "react": "^18.2.0",
@@ -43,5 +43,5 @@
     "typedoc": "0.23.21",
     "typedoc-plugin-markdown": "^3.13.6"
   },
-  "gitHead": "3079e4de73039f54accb227c3e2d3f538cdbceb5"
+  "gitHead": "943e962f0380d629612c4b843d4dd22b9996c41f"
 }

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./useComponentValue";
+export * from "./useDeprecatedComputedValue";
+export * from "./useEntityQuery";
+export * from "./useObservableValue";

package/src/useComponentValue.test.ts

@@ -0,0 +1,88 @@
+import { renderHook, act } from "@testing-library/react-hooks";
+import {
+  World,
+  Type,
+  createWorld,
+  defineComponent,
+  Component,
+  createEntity,
+  withValue,
+  setComponent,
+  removeComponent,
+} from "@latticexyz/recs";
+import { useComponentValue } from "./useComponentValue";
+
+describe("useComponentValue", () => {
+  let world: World;
+  let Position: Component<{
+    x: Type.Number;
+    y: Type.Number;
+  }>;
+
+  beforeEach(() => {
+    world = createWorld();
+    Position = defineComponent(world, { x: Type.Number, y: Type.Number }, { id: "Position" });
+  });
+
+  it("should return Position value for entity", () => {
+    const entity = createEntity(world, [withValue(Position, { x: 1, y: 1 })]);
+
+    const { result } = renderHook(() => useComponentValue(Position, entity));
+    expect(result.current).toEqual({ x: 1, y: 1 });
+
+    act(() => {
+      setComponent(Position, entity, { x: 0, y: 0 });
+    });
+    expect(result.current).toEqual({ x: 0, y: 0 });
+
+    act(() => {
+      removeComponent(Position, entity);
+    });
+    expect(result.current).toBe(undefined);
+  });
+
+  it("should re-render only when Position changes for entity", () => {
+    const entity = createEntity(world, [withValue(Position, { x: 1, y: 1 })]);
+    const otherEntity = createEntity(world, [withValue(Position, { x: 2, y: 2 })]);
+
+    const { result } = renderHook(() => useComponentValue(Position, entity));
+    expect(result.all.length).toBe(2);
+    expect(result.current).toEqual({ x: 1, y: 1 });
+
+    act(() => {
+      setComponent(Position, entity, { x: 0, y: 0 });
+    });
+    expect(result.all.length).toBe(3);
+    expect(result.current).toEqual({ x: 0, y: 0 });
+
+    act(() => {
+      setComponent(Position, otherEntity, { x: 0, y: 0 });
+      removeComponent(Position, otherEntity);
+    });
+    expect(result.all.length).toBe(3);
+    expect(result.current).toEqual({ x: 0, y: 0 });
+
+    act(() => {
+      removeComponent(Position, entity);
+    });
+    expect(result.all.length).toBe(4);
+    expect(result.current).toBe(undefined);
+  });
+
+  it("should return default value when Position is not set", () => {
+    const entity = createEntity(world);
+
+    const { result } = renderHook(() => useComponentValue(Position, entity, { x: -1, y: -1 }));
+    expect(result.current).toEqual({ x: -1, y: -1 });
+
+    act(() => {
+      setComponent(Position, entity, { x: 0, y: 0 });
+    });
+    expect(result.current).toEqual({ x: 0, y: 0 });
+
+    act(() => {
+      removeComponent(Position, entity);
+    });
+    expect(result.current).toEqual({ x: -1, y: -1 });
+  });
+});

package/src/useComponentValue.ts

@@ -0,0 +1,48 @@
+import {
+  Component,
+  ComponentValue,
+  defineQuery,
+  Entity,
+  getComponentValue,
+  Has,
+  isComponentUpdate,
+  Metadata,
+  Schema,
+} from "@latticexyz/recs";
+import { useEffect, useState } from "react";
+
+export function useComponentValue<S extends Schema>(
+  component: Component<S, Metadata, undefined>,
+  entity: Entity | undefined,
+  defaultValue: ComponentValue<S>
+): ComponentValue<S>;
+
+export function useComponentValue<S extends Schema>(
+  component: Component<S, Metadata, undefined>,
+  entity: Entity | undefined
+): ComponentValue<S> | undefined;
+
+export function useComponentValue<S extends Schema>(
+  component: Component<S, Metadata, undefined>,
+  entity: Entity | undefined,
+  defaultValue?: ComponentValue<S>
+) {
+  const [value, setValue] = useState(entity != null ? getComponentValue(component, entity) : undefined);
+
+  useEffect(() => {
+    // component or entity changed, update state to latest value
+    setValue(entity != null ? getComponentValue(component, entity) : undefined);
+    if (entity == null) return;
+
+    const queryResult = defineQuery([Has(component)], { runOnInit: false });
+    const subscription = queryResult.update$.subscribe((update) => {
+      if (isComponentUpdate(update, component) && update.entity === entity) {
+        const [nextValue] = update.value;
+        setValue(nextValue);
+      }
+    });
+    return () => subscription.unsubscribe();
+  }, [component, entity]);
+
+  return value ?? defaultValue;
+}

package/src/useDeprecatedComputedValue.ts

@@ -0,0 +1,14 @@
+import { IComputedValue } from "mobx";
+import { useEffect, useState } from "react";
+
+/** @deprecated See https://github.com/latticexyz/mud/issues/339 */
+export const useDeprecatedComputedValue = <T>(computedValue: IComputedValue<T> & { observe_: any }) => {
+  const [value, setValue] = useState<T>(computedValue.get());
+
+  useEffect(() => {
+    const unsubscribe = computedValue.observe_(() => setValue(computedValue.get()));
+    return () => unsubscribe();
+  }, [computedValue]);
+
+  return value;
+};

package/src/useEntityQuery.test.ts

@@ -0,0 +1,163 @@
+import { renderHook, act } from "@testing-library/react-hooks";
+import {
+  World,
+  Type,
+  createWorld,
+  defineComponent,
+  Component,
+  createEntity,
+  withValue,
+  Has,
+  setComponent,
+  HasValue,
+  removeComponent,
+} from "@latticexyz/recs";
+import { useEntityQuery } from "./useEntityQuery";
+
+describe("useEntityQuery", () => {
+  let world: World;
+  let Position: Component<{
+    x: Type.Number;
+    y: Type.Number;
+  }>;
+  let OwnedBy: Component<{ value: Type.Entity }>;
+
+  beforeEach(() => {
+    world = createWorld();
+    Position = defineComponent(world, { x: Type.Number, y: Type.Number }, { id: "Position" });
+    OwnedBy = defineComponent(world, { value: Type.Entity }, { id: "OwnedBy" });
+  });
+
+  it("should find entities with Position component", () => {
+    const entity1 = createEntity(world, [withValue(Position, { x: 1, y: 1 })]);
+    const entity2 = createEntity(world, [withValue(Position, { x: 2, y: 2 })]);
+    const entity3 = createEntity(world, []);
+
+    const { result } = renderHook(() => useEntityQuery([Has(Position)], { updateOnValueChange: false }));
+    const { result: resultOnValueChange } = renderHook(() =>
+      useEntityQuery([Has(Position)], { updateOnValueChange: true })
+    );
+
+    expect(result.current.length).toBe(2);
+    expect(result.current).toContain(entity1);
+    expect(result.current).toContain(entity2);
+    expect(result.current).not.toContain(entity3);
+    expect(resultOnValueChange.current).toEqual(result.current);
+
+    act(() => {
+      setComponent(Position, entity3, { x: 0, y: 0 });
+    });
+
+    expect(result.current.length).toBe(3);
+    expect(result.current).toContain(entity1);
+    expect(result.current).toContain(entity2);
+    expect(result.current).toContain(entity3);
+    expect(resultOnValueChange.current).toEqual(result.current);
+
+    act(() => {
+      removeComponent(Position, entity1);
+      removeComponent(Position, entity3);
+    });
+
+    expect(result.current.length).toBe(1);
+    expect(result.current).not.toContain(entity1);
+    expect(result.current).toContain(entity2);
+    expect(result.current).not.toContain(entity3);
+    expect(resultOnValueChange.current).toEqual(result.current);
+
+    act(() => {
+      removeComponent(Position, entity2);
+    });
+
+    expect(result.current.length).toBe(0);
+  });
+
+  it("should re-render only when Position changes", () => {
+    const entity1 = createEntity(world, [withValue(Position, { x: 1, y: 1 })]);
+    const entity2 = createEntity(world, [withValue(Position, { x: 2, y: 2 })]);
+    const entity3 = createEntity(world, []);
+
+    const { result } = renderHook(() => useEntityQuery([Has(Position)], { updateOnValueChange: false }));
+    const { result: resultOnValueChange } = renderHook(() =>
+      useEntityQuery([Has(Position)], { updateOnValueChange: true })
+    );
+
+    expect(result.all).toHaveLength(2);
+    expect(result.current).toHaveLength(2);
+    expect(result.current).toContain(entity1);
+    expect(result.current).toContain(entity2);
+    expect(result.current).not.toContain(entity3);
+
+    // Changing an entity's component value should NOT re-render,
+    // unless updateOnValueChange === true
+    act(() => {
+      setComponent(Position, entity2, { x: 0, y: 0 });
+    });
+
+    expect(result.all).toHaveLength(2);
+    expect(resultOnValueChange.all).toHaveLength(3);
+
+    // Changing a different component value should NOT re-render
+    act(() => {
+      setComponent(OwnedBy, entity2, { value: entity1 });
+      setComponent(OwnedBy, entity3, { value: entity1 });
+    });
+
+    expect(result.all).toHaveLength(2);
+    expect(resultOnValueChange.all).toHaveLength(3);
+
+    // Changing which entities have the component should re-render
+    act(() => {
+      setComponent(Position, entity3, { x: 0, y: 0 });
+    });
+
+    expect(result.all).toHaveLength(3);
+    expect(resultOnValueChange.all).toHaveLength(4);
+    expect(result.current).toHaveLength(3);
+    expect(result.current).toContain(entity1);
+    expect(result.current).toContain(entity2);
+    expect(result.current).toContain(entity3);
+
+    // Changing which entities have the component should re-render
+    act(() => {
+      removeComponent(Position, entity1);
+    });
+
+    expect(result.all).toHaveLength(4);
+    expect(resultOnValueChange.all).toHaveLength(5);
+    expect(result.current).toHaveLength(2);
+    expect(result.current).toContain(entity2);
+    expect(result.current).toContain(entity3);
+  });
+
+  it("should re-render as hook arguments change", () => {
+    // TODO: reduce re-renders during argument changes?
+
+    const entity1 = createEntity(world, [withValue(Position, { x: 1, y: 1 })]);
+    const entity2 = createEntity(world, [withValue(Position, { x: 2, y: 2 })]);
+    const entity3 = createEntity(world, [withValue(Position, { x: 2, y: 2 })]);
+
+    const { result, rerender } = renderHook(({ x, y }) => useEntityQuery([HasValue(Position, { x, y })]), {
+      initialProps: { x: 1, y: 1 },
+    });
+
+    expect(result.all).toHaveLength(2);
+    expect(result.current).toHaveLength(1);
+    expect(result.current).toContain(entity1);
+
+    rerender({ x: 1, y: 1 });
+    expect(result.all).toHaveLength(3);
+    expect(result.current).toHaveLength(1);
+    expect(result.current).toContain(entity1);
+
+    rerender({ x: 2, y: 2 });
+    expect(result.all).toHaveLength(6);
+    expect(result.current).toHaveLength(2);
+    expect(result.current).toContain(entity2);
+    expect(result.current).toContain(entity3);
+
+    rerender({ x: -1, y: -1 });
+    expect(result.all).toHaveLength(9);
+    expect(result.current).toHaveLength(0);
+  });
+});

package/src/useEntityQuery.ts

@@ -0,0 +1,37 @@
+import { defineQuery, QueryFragment } from "@latticexyz/recs";
+import { useEffect, useMemo, useState } from "react";
+import { useDeepMemo } from "./utils/useDeepMemo";
+import isEqual from "fast-deep-equal";
+import { distinctUntilChanged, map } from "rxjs";
+
+// This does a little more rendering than is necessary when arguments change,
+// but at least it's giving correct results now. Will optimize later!
+
+/**
+ * Returns all matching entities for a given entity query,
+ * and triggers a re-render as new query results come in.
+ *
+ * @param fragments Query fragments to match against, executed from left to right.
+ * @param options.updateOnValueChange False - re-renders only on entity array changes. True (default) - also on component value changes.
+ * @returns Set of entities matching the query fragments.
+ */
+export function useEntityQuery(fragments: QueryFragment[], options?: { updateOnValueChange?: boolean }) {
+  const updateOnValueChange = options?.updateOnValueChange ?? true;
+
+  const stableFragments = useDeepMemo(fragments);
+  const query = useMemo(() => defineQuery(stableFragments, { runOnInit: true }), [stableFragments]);
+  const [entities, setEntities] = useState([...query.matching]);
+
+  useEffect(() => {
+    setEntities([...query.matching]);
+    let observable = query.update$.pipe(map(() => [...query.matching]));
+    if (!updateOnValueChange) {
+      // re-render only on entity array changes
+      observable = observable.pipe(distinctUntilChanged((a, b) => isEqual(a, b)));
+    }
+    const subscription = observable.subscribe((entities) => setEntities(entities));
+    return () => subscription.unsubscribe();
+  }, [query, updateOnValueChange]);
+
+  return entities;
+}

package/src/useObservableValue.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from "react";
+import { Observable } from "rxjs";
+
+export function useObservableValue<T>(observable: Observable<T>, defaultValue: T): T;
+
+export function useObservableValue<T>(observable: Observable<T>): T | undefined;
+
+export function useObservableValue<T>(observable: Observable<T>, defaultValue?: T) {
+  const [value, setValue] = useState(defaultValue);
+
+  useEffect(() => {
+    const subscription = observable.subscribe(setValue);
+    return () => subscription.unsubscribe();
+  }, [observable]);
+
+  return value;
+}

package/src/utils/useDeepMemo.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState } from "react";
+import isEqual from "fast-deep-equal";
+
+export const useDeepMemo = <T>(currentValue: T): T => {
+  const [stableValue, setStableValue] = useState(currentValue);
+
+  useEffect(() => {
+    if (!isEqual(currentValue, stableValue)) {
+      setStableValue(currentValue);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentValue]);
+
+  return stableValue;
+};