@latticexyz/react 0.0.0-indexing-20230707130424

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Change Log
+
+## 0.0.0-indexing-20230707130424
+
+### Patch Changes
+
+- Updated dependencies [[`904fd7d4`](https://github.com/latticexyz/mud/commit/904fd7d4ee06a86e481e3e02fd5744224376d0c9)]:
+  - @latticexyz/store@0.0.0-indexing-20230707130424
+  - @latticexyz/store-cache@0.0.0-indexing-20230707130424
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.42.0](https://github.com/latticexyz/mud/compare/v1.41.0...v1.42.0) (2023-04-13)
+
+### Features
+
+- v2 event decoding ([#415](https://github.com/latticexyz/mud/issues/415)) ([374ed54](https://github.com/latticexyz/mud/commit/374ed542c3387a4ec2b36ab68ae534419aa58763))
+
+# [1.41.0](https://github.com/latticexyz/mud/compare/v1.40.0...v1.41.0) (2023-03-09)
+
+### Features
+
+- **react:** option for useEntityQuery to re-render on value changes ([#460](https://github.com/latticexyz/mud/issues/460)) ([6b90b85](https://github.com/latticexyz/mud/commit/6b90b85febe00ff0a2c9a3c4642d0197b5107e35))
+
+# [1.40.0](https://github.com/latticexyz/mud/compare/v1.39.0...v1.40.0) (2023-03-03)
+
+**Note:** Version bump only for package @latticexyz/react
+
+# [1.39.0](https://github.com/latticexyz/mud/compare/v1.38.0...v1.39.0) (2023-02-22)
+
+**Note:** Version bump only for package @latticexyz/react
+
+# [1.38.0](https://github.com/latticexyz/mud/compare/v1.37.1...v1.38.0) (2023-02-22)
+
+**Note:** Version bump only for package @latticexyz/react
+
+## [1.37.1](https://github.com/latticexyz/mud/compare/v1.37.0...v1.37.1) (2023-02-17)
+
+**Note:** Version bump only for package @latticexyz/react
+
+# [1.37.0](https://github.com/latticexyz/mud/compare/v1.36.1...v1.37.0) (2023-02-16)
+
+### Bug Fixes
+
+- package entry points, peer dep versions ([#409](https://github.com/latticexyz/mud/issues/409)) ([66a7fd6](https://github.com/latticexyz/mud/commit/66a7fd6f74620ce02c60e3d55701d4740cc65251))
+
+### Reverts
+
+- Revert "chore(release): publish v1.37.0" ([c934f53](https://github.com/latticexyz/mud/commit/c934f5388c1e56f2fe6390fdda30f5b9b1ea1c20))
+
+## [1.36.1](https://github.com/latticexyz/mud/compare/v1.36.0...v1.36.1) (2023-02-16)
+
+**Note:** Version bump only for package @latticexyz/react
+
+# [1.35.0](https://github.com/latticexyz/mud/compare/v1.34.0...v1.35.0) (2023-02-15)
+
+**Note:** Version bump only for package @latticexyz/react
+
+# [1.34.0](https://github.com/latticexyz/mud/compare/v1.33.1...v1.34.0) (2023-01-29)
+
+**Note:** Version bump only for package @latticexyz/react
+
+## [1.33.1](https://github.com/latticexyz/mud/compare/v1.33.0...v1.33.1) (2023-01-12)
+
+**Note:** Version bump only for package @latticexyz/react
+
+# [1.33.0](https://github.com/latticexyz/mud/compare/v1.32.0...v1.33.0) (2023-01-12)
+
+### Features
+
+- **react:** add react package ([#294](https://github.com/latticexyz/mud/issues/294)) ([f5ee290](https://github.com/latticexyz/mud/commit/f5ee290e776276b2b0dd273705694df04a85f400))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-present Lattice Labs Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# MUD React
+
+React hooks (and more) for building MUD clients.
+
+## Hooks for `store-cache`
+
+### useRows
+
+Returns an array of all rows matching the provided filter. Re-renders if the filter changes or if table entries matching the provided filter change.
+
+```typescript
+// get a list of all entries in the database
+const allRows = useRows(storeCache);
+// -> [ { namespace: "", table: "Position", key: { key: "0x01" }, value: { x: 1, y: 2 } }, ... ]
+
+// get a list of all entries in the Position table
+const allPositionRows = useRows(storeCache, { table: "Position" });
+
+// get a list of all entries in the position table with key greater than `0x0A`
+const filteredRows = useRows(storeCache, { table: "Position", key: { gt: { key: "0x0A" } } });
+```
+
+### useRow
+
+Returns a single row with the provided key in the provided table. Re-renders if the filter changes or if the value of this row changes.
+
+```typescript
+// get the Position value of key `0x01`
+const position = useRow(storeCache, { table: "Position", key: { key: "0x01" } });
+// -> { namespace: "", table: "Position", key: { key: "0x01" }, value: { x: 1, y: 2 } }
+```
+
+## Hooks for `recs`
+
+### useComponentValue
+
+Returns the value of the component for the entity, and triggers a re-render as the component is added/removed/updated.
+
+```typescript
+const position = useComponentValue(Position, entity);
+```
+
+### useEntityQuery
+
+Returns all matching `EntityIndex`es for a given entity query, and triggers a re-render as new query results come in.
+
+```typescript
+const entities = useEntityQuery([Has(Position)]);
+const playersAtPosition = useEntityQuery([Has(Player), HasValue(Position, { x: 0, y: 0 })]);
+```

package/dist/index.js

@@ -0,0 +1,2 @@
+import{defineQuery as d,getComponentValue as p,Has as C,isComponentUpdate as S}from"@latticexyz/recs";import{useEffect as T,useState as x}from"react";function G(e,t,s){let[o,n]=x(t!=null?p(e,t):void 0);return T(()=>{if(n(t!=null?p(e,t):void 0),t==null)return;let a=d([C(e)],{runOnInit:!1}).update$.subscribe(u=>{if(S(u,e)&&u.entity===t){let[f]=u.value;n(f)}});return()=>a.unsubscribe()},[e,t]),o??s}import{useEffect as g,useState as y}from"react";var N=e=>{let[t,s]=y(e.get());return g(()=>{let o=e.observe_(()=>s(e.get()));return()=>o()},[e]),t};import{defineQuery as E}from"@latticexyz/recs";import{useEffect as R,useMemo as h,useState as M}from"react";import{useEffect as V,useState as O}from"react";import v from"fast-deep-equal";var i=e=>{let[t,s]=O(e);return V(()=>{v(e,t)||s(e)},[e]),t};import D from"fast-deep-equal";import{distinctUntilChanged as k,map as w}from"rxjs";function ue(e,t){let s=t?.updateOnValueChange??!0,o=i(e),n=h(()=>E(o,{runOnInit:!0}),[o]),[r,a]=M([...n.matching]);return R(()=>{a([...n.matching]);let u=n.update$.pipe(w(()=>[...n.matching]));s||(u=u.pipe(k((m,b)=>D(m,b))));let f=u.subscribe(m=>a(m));return()=>f.unsubscribe()},[n,s]),r}import{useEffect as F,useState as q}from"react";function fe(e,t){let[s,o]=q(t);return F(()=>{let n=e.subscribe(o);return()=>n.unsubscribe()},[e]),s}import{useEffect as K}from"react";import{useCallback as I,useEffect as Q,useRef as U,useState as A}from"react";function l(e){let[t,s]=A(e),o=U(!1);Q(()=>(o.current=!0,()=>{o.current=!1}));let n=I((...r)=>{o.current?s(...r):console.warn("Ignoring `setState` call because component unmounted",...r)},[]);return[t,n]}function c(e,t){let[s,o]=l([]),n=i(t);return K(()=>{e.scan(n).then(o);let r=e.subscribe(()=>{e.scan(n).then(o)},n);return()=>{r.then(a=>a())}},[n,o,e]),s}function ye(e,t){let{namespace:s,table:o,key:n}=t;return c(e,{namespace:s,table:o,key:{eq:n}})[0]}export{G as useComponentValue,N as useDeprecatedComputedValue,ue as useEntityQuery,fe as useObservableValue,ye as useRow,c as useRows};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useComponentValue.ts","../src/useDeprecatedComputedValue.ts","../src/useEntityQuery.ts","../src/utils/useDeepMemo.ts","../src/useObservableValue.ts","../src/store-cache/useRows.ts","../src/utils/useMountedState.ts","../src/store-cache/useRow.ts"],"sourcesContent":["import {\n  Component,\n  ComponentValue,\n  defineQuery,\n  Entity,\n  getComponentValue,\n  Has,\n  isComponentUpdate,\n  Metadata,\n  Schema,\n} from \"@latticexyz/recs\";\nimport { useEffect, useState } from \"react\";\n\nexport function useComponentValue<S extends Schema>(\n  component: Component<S, Metadata, undefined>,\n  entity: Entity | undefined,\n  defaultValue: ComponentValue<S>\n): ComponentValue<S>;\n\nexport function useComponentValue<S extends Schema>(\n  component: Component<S, Metadata, undefined>,\n  entity: Entity | undefined\n): ComponentValue<S> | undefined;\n\nexport function useComponentValue<S extends Schema>(\n  component: Component<S, Metadata, undefined>,\n  entity: Entity | undefined,\n  defaultValue?: ComponentValue<S>\n) {\n  const [value, setValue] = useState(entity != null ? getComponentValue(component, entity) : undefined);\n\n  useEffect(() => {\n    // component or entity changed, update state to latest value\n    setValue(entity != null ? getComponentValue(component, entity) : undefined);\n    if (entity == null) return;\n\n    const queryResult = defineQuery([Has(component)], { runOnInit: false });\n    const subscription = queryResult.update$.subscribe((update) => {\n      if (isComponentUpdate(update, component) && update.entity === entity) {\n        const [nextValue] = update.value;\n        setValue(nextValue);\n      }\n    });\n    return () => subscription.unsubscribe();\n  }, [component, entity]);\n\n  return value ?? defaultValue;\n}\n","import { IComputedValue } from \"mobx\";\nimport { useEffect, useState } from \"react\";\n\n/** @deprecated See https://github.com/latticexyz/mud/issues/339 */\nexport const useDeprecatedComputedValue = <T>(computedValue: IComputedValue<T> & { observe_: any }) => {\n  const [value, setValue] = useState<T>(computedValue.get());\n\n  useEffect(() => {\n    const unsubscribe = computedValue.observe_(() => setValue(computedValue.get()));\n    return () => unsubscribe();\n  }, [computedValue]);\n\n  return value;\n};\n","import { defineQuery, QueryFragment } from \"@latticexyz/recs\";\nimport { useEffect, useMemo, useState } from \"react\";\nimport { useDeepMemo } from \"./utils/useDeepMemo\";\nimport isEqual from \"fast-deep-equal\";\nimport { distinctUntilChanged, map } from \"rxjs\";\n\n// This does a little more rendering than is necessary when arguments change,\n// but at least it's giving correct results now. Will optimize later!\n\n/**\n * Returns all matching entities for a given entity query,\n * and triggers a re-render as new query results come in.\n *\n * @param fragments Query fragments to match against, executed from left to right.\n * @param options.updateOnValueChange False - re-renders only on entity array changes. True (default) - also on component value changes.\n * @returns Set of entities matching the query fragments.\n */\nexport function useEntityQuery(fragments: QueryFragment[], options?: { updateOnValueChange?: boolean }) {\n  const updateOnValueChange = options?.updateOnValueChange ?? true;\n\n  const stableFragments = useDeepMemo(fragments);\n  const query = useMemo(() => defineQuery(stableFragments, { runOnInit: true }), [stableFragments]);\n  const [entities, setEntities] = useState([...query.matching]);\n\n  useEffect(() => {\n    setEntities([...query.matching]);\n    let observable = query.update$.pipe(map(() => [...query.matching]));\n    if (!updateOnValueChange) {\n      // re-render only on entity array changes\n      observable = observable.pipe(distinctUntilChanged((a, b) => isEqual(a, b)));\n    }\n    const subscription = observable.subscribe((entities) => setEntities(entities));\n    return () => subscription.unsubscribe();\n  }, [query, updateOnValueChange]);\n\n  return entities;\n}\n","import { useEffect, useState } from \"react\";\nimport isEqual from \"fast-deep-equal\";\n\nexport const useDeepMemo = <T>(currentValue: T): T => {\n  const [stableValue, setStableValue] = useState(currentValue);\n\n  useEffect(() => {\n    if (!isEqual(currentValue, stableValue)) {\n      setStableValue(currentValue);\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [currentValue]);\n\n  return stableValue;\n};\n","import { useEffect, useState } from \"react\";\nimport { Observable } from \"rxjs\";\n\nexport function useObservableValue<T>(observable: Observable<T>, defaultValue: T): T;\n\nexport function useObservableValue<T>(observable: Observable<T>): T | undefined;\n\nexport function useObservableValue<T>(observable: Observable<T>, defaultValue?: T) {\n  const [value, setValue] = useState(defaultValue);\n\n  useEffect(() => {\n    const subscription = observable.subscribe(setValue);\n    return () => subscription.unsubscribe();\n  }, [observable]);\n\n  return value;\n}\n","import { DatabaseClient, FilterOptions, ScanResult } from \"@latticexyz/store-cache\";\nimport { StoreConfig } from \"@latticexyz/store\";\nimport { useEffect, useState } from \"react\";\nimport { useDeepMemo } from \"../utils/useDeepMemo\";\nimport { useMountedState } from \"../utils/useMountedState\";\n\n/**\n * Returns an array of all rows matching the provided filter\n */\nexport function useRows<C extends StoreConfig, T extends keyof C[\"tables\"] & string>(\n  storeCache: DatabaseClient<C>,\n  filter?: FilterOptions<C, T>\n) {\n  const [rows, setRows] = useMountedState<ScanResult<C, T>>([]);\n  const filterMemo = useDeepMemo(filter);\n\n  useEffect(() => {\n    storeCache.scan(filterMemo).then(setRows);\n\n    const unsubscribePromise = storeCache.subscribe(() => {\n      // very naive implementation for now, but easier and probably more efficient than\n      // manually looping through the `rows` array for every update event\n      storeCache.scan(filterMemo).then(setRows);\n    }, filterMemo);\n\n    return () => {\n      unsubscribePromise.then((unsubscribe) => unsubscribe());\n    };\n  }, [filterMemo, setRows, storeCache]);\n\n  return rows;\n}\n","import { Dispatch, SetStateAction, useCallback, useEffect, useRef, useState } from \"react\";\n\n/**\n * Use in place of useState when the component may be unmounted before the state is updated.\n */\nexport function useMountedState<T>(initialState: T | (() => T)): [T, Dispatch<SetStateAction<T>>] {\n  const [state, setState] = useState<T>(initialState);\n  const mountedRef = useRef(false);\n  useEffect(() => {\n    mountedRef.current = true;\n    return () => {\n      mountedRef.current = false;\n    };\n  });\n  const mountedSetState: typeof setState = useCallback((...args) => {\n    if (mountedRef.current) {\n      setState(...args);\n    } else {\n      console.warn(\"Ignoring `setState` call because component unmounted\", ...args);\n    }\n  }, []);\n  return [state, mountedSetState];\n}\n","import { StoreConfig } from \"@latticexyz/store\";\nimport { DatabaseClient, Key, ScanResult } from \"@latticexyz/store-cache\";\nimport { useRows } from \"./useRows\";\n\nexport type UseRowFilterOptions<\n  C extends StoreConfig = StoreConfig,\n  T extends keyof C[\"tables\"] & string = keyof C[\"tables\"] & string\n> = {\n  namespace?: C[\"namespace\"];\n  table: T;\n  key: Key<C, T>;\n};\n\n/**\n * Returns a single row of a given table at the given key, updates when the key changes\n */\nexport function useRow<C extends StoreConfig, T extends keyof C[\"tables\"] & string>(\n  storeCache: DatabaseClient<C>,\n  filter: UseRowFilterOptions<C, T>\n): ScanResult<C, T>[0] | undefined {\n  const { namespace, table, key } = filter;\n  return useRows(storeCache, { namespace, table, key: { eq: key } })[0];\n}\n"],"mappings":"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","names":["defineQuery","getComponentValue","Has","isComponentUpdate","useEffect","useState","useComponentValue","component","entity","defaultValue","value","setValue","subscription","update","nextValue","useEffect","useState","useDeprecatedComputedValue","computedValue","value","setValue","unsubscribe","defineQuery","useEffect","useMemo","useState","useEffect","useState","isEqual","useDeepMemo","currentValue","stableValue","setStableValue","isEqual","distinctUntilChanged","map","useEntityQuery","fragments","options","updateOnValueChange","stableFragments","useDeepMemo","query","useMemo","defineQuery","entities","setEntities","useState","useEffect","observable","a","subscription","useEffect","useState","useObservableValue","observable","defaultValue","value","setValue","subscription","useEffect","useCallback","useEffect","useRef","useState","useMountedState","initialState","state","setState","mountedRef","mountedSetState","args","useRows","storeCache","filter","rows","setRows","useMountedState","filterMemo","useDeepMemo","useEffect","unsubscribePromise","unsubscribe","useRow","storeCache","filter","namespace","table","key","useRows"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@latticexyz/react",
+  "version": "0.0.0-indexing-20230707130424",
+  "description": "React tools for MUD client.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latticexyz/mud.git",
+    "directory": "packages/react"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "src/index.ts",
+  "dependencies": {
+    "fast-deep-equal": "^3.1.3",
+    "mobx": "^6.7.0",
+    "react": "^18.2.0",
+    "rxjs": "7.5.5",
+    "@latticexyz/recs": "1.42.0",
+    "@latticexyz/store": "0.0.0-indexing-20230707130424",
+    "@latticexyz/store-cache": "0.0.0-indexing-20230707130424"
+  },
+  "devDependencies": {
+    "@testing-library/react-hooks": "^8.0.1",
+    "@types/react": "^18.2.6",
+    "@vitejs/plugin-react": "^4.0.0",
+    "eslint-plugin-react": "7.31.11",
+    "eslint-plugin-react-hooks": "4.6.0",
+    "react-test-renderer": "^18.2.0",
+    "tsup": "^6.7.0",
+    "typedoc": "0.23.21",
+    "typedoc-plugin-markdown": "^3.13.6",
+    "vite": "^4.3.6",
+    "vitest": "0.31.4"
+  },
+  "gitHead": "914a1e0ae4a573d685841ca2ea921435057deb8f",
+  "scripts": {
+    "build": "pnpm run build:js",
+    "build:js": "tsup",
+    "clean": "pnpm run clean:js",
+    "clean:js": "rimraf dist",
+    "dev": "tsup --watch",
+    "docs": "rimraf API && typedoc src && find API -type f -name '*.md' -exec sed -E -i \"\" \"s/(#.*)(<.*>)/\\1/\" {} \\;",
+    "test": "tsc --noEmit && vitest --run"
+  }
+}

package/src/index.ts

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

package/src/store-cache/index.ts

@@ -0,0 +1,2 @@
+export * from "./useRows";
+export * from "./useRow";

package/src/store-cache/useRow.test.ts

@@ -0,0 +1,197 @@
+import { renderHook, act } from "@testing-library/react-hooks";
+import { UseRowFilterOptions, useRow } from "./useRow";
+import { mudConfig } from "@latticexyz/store/register";
+import { KeyValue, createDatabase, createDatabaseClient } from "@latticexyz/store-cache";
+import { describe, it, beforeEach, expect } from "vitest";
+
+const config = mudConfig({
+  tables: {
+    MultiKey: { keySchema: { first: "bytes32", second: "uint32" }, schema: "int32" },
+    Position: { schema: { x: "int32", y: "int32" } },
+  },
+});
+
+describe("useRow", () => {
+  let db: ReturnType<typeof createDatabase>;
+  let client: ReturnType<typeof createDatabaseClient<typeof config>>;
+
+  beforeEach(() => {
+    db = createDatabase();
+    client = createDatabaseClient(db, config);
+  });
+
+  it("should return the row of the position table with the specified key", async () => {
+    const { result } = renderHook(() => useRow(client, { table: "Position", key: { key: "0x01" } }));
+    expect(result.current).toBe(undefined);
+
+    const positionUpdates: KeyValue<typeof config, "Position">[] = [
+      { key: { key: "0x00" }, value: { x: 1, y: 2 } },
+      { key: { key: "0x01" }, value: { x: 2, y: 3 } },
+      { key: { key: "0x02" }, value: { x: 3, y: 4 } },
+      { key: { key: "0x03" }, value: { x: 4, y: 5 } },
+    ];
+
+    const multiKeyUpdates: KeyValue<typeof config, "MultiKey">[] = [
+      { key: { first: "0x00", second: 4 }, value: { value: 1 } },
+      { key: { first: "0x01", second: 3 }, value: { value: 2 } },
+      { key: { first: "0x02", second: 2 }, value: { value: 3 } },
+      { key: { first: "0x03", second: 1 }, value: { value: 4 } },
+    ];
+
+    await act(async () => {
+      // Set values in the tables
+      for (const update of positionUpdates) {
+        await client.tables.Position.set(update.key, update.value);
+      }
+      for (const update of multiKeyUpdates) {
+        await client.tables.MultiKey.set(update.key, update.value);
+      }
+    });
+
+    expect(result.current).toEqual({
+      key: { key: "0x01" },
+      value: { x: 2, y: 3 },
+      namespace: config["namespace"],
+      table: "Position",
+    });
+
+    await act(async () => {
+      for (const update of positionUpdates.slice(0, 3)) {
+        await client.tables.Position.remove(update.key);
+      }
+    });
+
+    expect(result.current).toBe(undefined);
+  });
+
+  it("should re-render only when the position value of the specified key changes", async () => {
+    const { result } = renderHook(() => useRow(client, { table: "Position", key: { key: "0x00" } }));
+    expect(result.all.length).toBe(1);
+
+    // Update the position table
+    await act(async () => {
+      await client.tables.Position.set({ key: "0x00" }, { x: 1, y: 2 });
+    });
+    expect(result.all.length).toBe(3);
+    expect(result.current).toEqual({
+      key: { key: "0x00" },
+      value: { x: 1, y: 2 },
+      namespace: config["namespace"],
+      table: "Position",
+    });
+
+    // Update an unrelated table
+    await act(async () => {
+      await client.tables.MultiKey.set({ first: "0x03", second: 1 }, { value: 4 });
+    });
+    expect(result.all.length).toBe(3);
+    expect(result.current).toEqual({
+      key: { key: "0x00" },
+      value: { x: 1, y: 2 },
+      namespace: config["namespace"],
+      table: "Position",
+    });
+
+    // Update the position table
+    await act(async () => {
+      await client.tables.Position.set({ key: "0x00" }, { x: 2, y: 2 });
+    });
+    expect(result.all.length).toBe(4);
+    expect(result.current).toEqual({
+      key: { key: "0x00" },
+      value: { x: 2, y: 2 },
+      namespace: config["namespace"],
+      table: "Position",
+    });
+
+    // Update an unrelated key
+    await act(async () => {
+      await client.tables.Position.set({ key: "0x01" }, { x: 2, y: 2 });
+    });
+    expect(result.all.length).toBe(4);
+    expect(result.current).toEqual({
+      key: { key: "0x00" },
+      value: { x: 2, y: 2 },
+      namespace: config["namespace"],
+      table: "Position",
+    });
+
+    // Update the position table
+    await act(async () => {
+      await client.tables.Position.remove({ key: "0x00" });
+    });
+    expect(result.all.length).toBe(5);
+    expect(result.current).toEqual(undefined);
+  });
+
+  it("should re-render when the filter changes", async () => {
+    const { result, rerender, waitForNextUpdate } = renderHook(({ filter }) => useRow(client, filter), {
+      initialProps: {
+        filter: { table: "Position", key: { key: "0x01" } } as UseRowFilterOptions<typeof config>,
+      },
+    });
+
+    expect(result.all.length).toBe(1);
+    expect(result.current).toBe(undefined);
+
+    const positionUpdates: KeyValue<typeof config, "Position">[] = [
+      { key: { key: "0x00" }, value: { x: 1, y: 2 } },
+      { key: { key: "0x01" }, value: { x: 2, y: 3 } },
+      { key: { key: "0x02" }, value: { x: 3, y: 4 } },
+      { key: { key: "0x03" }, value: { x: 4, y: 5 } },
+    ];
+
+    const multiKeyUpdates: KeyValue<typeof config, "MultiKey">[] = [
+      { key: { first: "0x00", second: 4 }, value: { value: 1 } },
+      { key: { first: "0x01", second: 3 }, value: { value: 2 } },
+      { key: { first: "0x02", second: 2 }, value: { value: 3 } },
+      { key: { first: "0x03", second: 1 }, value: { value: 4 } },
+    ];
+
+    await act(async () => {
+      // Set values in the tables
+      for (const update of positionUpdates) {
+        await client.tables.Position.set(update.key, update.value);
+      }
+      for (const update of multiKeyUpdates) {
+        await client.tables.MultiKey.set(update.key, update.value);
+      }
+    });
+
+    expect(result.all.length).toBe(3);
+    expect(result.current).toEqual({
+      key: { key: "0x01" },
+      value: { x: 2, y: 3 },
+      namespace: config["namespace"],
+      table: "Position",
+    });
+
+    // Change the filter
+    rerender({ filter: { table: "Position", key: { key: "0x02" } } });
+    await waitForNextUpdate();
+
+    // Expect hook to rerender three times:
+    // 1. New prop, everything else changes the same
+    // 2. `filterMemo` is updated by `useDeepMemo` because of the new prop
+    // 3. `useEffect` runs because of the new `filterMemo`, scan is executed, new rows are returned
+    expect(result.all.length).toBe(6);
+    expect(result.current).toEqual({
+      key: { key: "0x02" },
+      value: { x: 3, y: 4 },
+      namespace: config["namespace"],
+      table: "Position",
+    });
+
+    // Change the filter
+    rerender({ filter: { table: "MultiKey", key: { first: "0x00", second: 4 } } });
+    await waitForNextUpdate();
+
+    expect(result.all.length).toBe(9);
+    expect(result.current).toEqual({
+      key: { first: "0x00", second: 4 },
+      value: { value: 1 },
+      namespace: config["namespace"],
+      table: "MultiKey",
+    });
+  });
+});

package/src/store-cache/useRow.ts

@@ -0,0 +1,23 @@
+import { StoreConfig } from "@latticexyz/store";
+import { DatabaseClient, Key, ScanResult } from "@latticexyz/store-cache";
+import { useRows } from "./useRows";
+
+export type UseRowFilterOptions<
+  C extends StoreConfig = StoreConfig,
+  T extends keyof C["tables"] & string = keyof C["tables"] & string
+> = {
+  namespace?: C["namespace"];
+  table: T;
+  key: Key<C, T>;
+};
+
+/**
+ * Returns a single row of a given table at the given key, updates when the key changes
+ */
+export function useRow<C extends StoreConfig, T extends keyof C["tables"] & string>(
+  storeCache: DatabaseClient<C>,
+  filter: UseRowFilterOptions<C, T>
+): ScanResult<C, T>[0] | undefined {
+  const { namespace, table, key } = filter;
+  return useRows(storeCache, { namespace, table, key: { eq: key } })[0];
+}

package/src/store-cache/useRows.test.ts

@@ -0,0 +1,168 @@
+import { renderHook, act } from "@testing-library/react-hooks";
+import { useRows } from "./useRows";
+import { mudConfig } from "@latticexyz/store/register";
+import { KeyValue, createDatabase, createDatabaseClient } from "@latticexyz/store-cache";
+import { describe, it, beforeEach, expect } from "vitest";
+
+const config = mudConfig({
+  tables: {
+    MultiKey: { keySchema: { first: "bytes32", second: "uint32" }, schema: "int32" },
+    Position: { schema: { x: "int32", y: "int32" } },
+  },
+});
+
+describe("useRows", () => {
+  let db: ReturnType<typeof createDatabase>;
+  let client: ReturnType<typeof createDatabaseClient<typeof config>>;
+
+  beforeEach(() => {
+    db = createDatabase();
+    client = createDatabaseClient(db, config);
+  });
+
+  it("should return all rows of the position table", async () => {
+    const { result } = renderHook(() => useRows(client, { table: "Position" }));
+    expect(result.current.length).toBe(0);
+
+    const positionUpdates: KeyValue<typeof config, "Position">[] = [
+      { key: { key: "0x00" }, value: { x: 1, y: 2 } },
+      { key: { key: "0x01" }, value: { x: 2, y: 3 } },
+      { key: { key: "0x02" }, value: { x: 3, y: 4 } },
+      { key: { key: "0x03" }, value: { x: 4, y: 5 } },
+    ];
+
+    const multiKeyUpdates: KeyValue<typeof config, "MultiKey">[] = [
+      { key: { first: "0x00", second: 4 }, value: { value: 1 } },
+      { key: { first: "0x01", second: 3 }, value: { value: 2 } },
+      { key: { first: "0x02", second: 2 }, value: { value: 3 } },
+      { key: { first: "0x03", second: 1 }, value: { value: 4 } },
+    ];
+
+    await act(async () => {
+      // Set values in the tables
+      for (const update of positionUpdates) {
+        await client.tables.Position.set(update.key, update.value);
+      }
+      for (const update of multiKeyUpdates) {
+        await client.tables.MultiKey.set(update.key, update.value);
+      }
+    });
+
+    expect(result.current.length).toBe(positionUpdates.length);
+    expect(result.current).toEqual([
+      ...positionUpdates.map((row) => ({ ...row, namespace: config["namespace"], table: "Position" })),
+    ]);
+
+    await act(async () => {
+      for (const update of positionUpdates.slice(0, 3)) {
+        await client.tables.Position.remove(update.key);
+      }
+    });
+
+    expect(result.current.length).toBe(1);
+    expect(result.current).toEqual([
+      { key: { key: "0x03" }, value: { x: 4, y: 5 }, namespace: config["namespace"], table: "Position" },
+    ]);
+  });
+
+  it("should re-render only when the position table changes", async () => {
+    const { result } = renderHook(() => useRows(client, { namespace: config["namespace"], table: "Position" }));
+    expect(result.all.length).toBe(1);
+
+    // Update the position table
+    await act(async () => {
+      await client.tables.Position.set({ key: "0x00" }, { x: 1, y: 2 });
+    });
+    expect(result.all.length).toBe(3);
+    expect(result.current).toEqual([
+      { key: { key: "0x00" }, value: { x: 1, y: 2 }, namespace: config["namespace"], table: "Position" },
+    ]);
+
+    // Update an unrelated table
+    await act(async () => {
+      await client.tables.MultiKey.set({ first: "0x03", second: 1 }, { value: 4 });
+    });
+    expect(result.all.length).toBe(3);
+    expect(result.current).toEqual([
+      { key: { key: "0x00" }, value: { x: 1, y: 2 }, namespace: config["namespace"], table: "Position" },
+    ]);
+
+    // Update the position table
+    await act(async () => {
+      await client.tables.Position.set({ key: "0x00" }, { x: 2, y: 2 });
+    });
+    expect(result.all.length).toBe(4);
+    expect(result.current).toEqual([
+      { key: { key: "0x00" }, value: { x: 2, y: 2 }, namespace: config["namespace"], table: "Position" },
+    ]);
+
+    // Update an unrelated table
+    await act(async () => {
+      await client.tables.MultiKey.remove({ first: "0x03", second: 1 });
+    });
+    expect(result.all.length).toBe(4);
+    expect(result.current).toEqual([
+      { key: { key: "0x00" }, value: { x: 2, y: 2 }, namespace: config["namespace"], table: "Position" },
+    ]);
+
+    // Update the position table
+    await act(async () => {
+      await client.tables.Position.remove({ key: "0x00" });
+    });
+    expect(result.all.length).toBe(5);
+    expect(result.current).toEqual([]);
+  });
+
+  it("should re-render when the filter changes", async () => {
+    const { result, rerender, waitForNextUpdate } = renderHook(({ filter }) => useRows(client, filter), {
+      initialProps: { filter: { table: "Position" as keyof (typeof config)["tables"] } },
+    });
+
+    expect(result.all.length).toBe(1);
+    expect(result.current.length).toBe(0);
+
+    const positionUpdates: KeyValue<typeof config, "Position">[] = [
+      { key: { key: "0x00" }, value: { x: 1, y: 2 } },
+      { key: { key: "0x01" }, value: { x: 2, y: 3 } },
+      { key: { key: "0x02" }, value: { x: 3, y: 4 } },
+      { key: { key: "0x03" }, value: { x: 4, y: 5 } },
+    ];
+
+    const multiKeyUpdates: KeyValue<typeof config, "MultiKey">[] = [
+      { key: { first: "0x00", second: 4 }, value: { value: 1 } },
+      { key: { first: "0x01", second: 3 }, value: { value: 2 } },
+      { key: { first: "0x02", second: 2 }, value: { value: 3 } },
+      { key: { first: "0x03", second: 1 }, value: { value: 4 } },
+    ];
+
+    await act(async () => {
+      // Set values in the tables
+      for (const update of positionUpdates) {
+        await client.tables.Position.set(update.key, update.value);
+      }
+      for (const update of multiKeyUpdates) {
+        await client.tables.MultiKey.set(update.key, update.value);
+      }
+    });
+
+    expect(result.all.length).toBe(6);
+    expect(result.current.length).toBe(positionUpdates.length);
+    expect(result.current).toEqual([
+      ...positionUpdates.map((row) => ({ ...row, namespace: config["namespace"], table: "Position" })),
+    ]);
+
+    // Change the filter
+    rerender({ filter: { table: "MultiKey" } });
+    await waitForNextUpdate();
+
+    // Expect hook to rerender three times:
+    // 1. New prop, everything else changes the same
+    // 2. `filterMemo` is updated by `useDeepMemo` because of the new prop
+    // 3. `useEffect` runs because of the new `filterMemo`, scan is executed, new rows are returned
+    expect(result.all.length).toBe(9);
+    expect(result.current.length).toBe(multiKeyUpdates.length);
+    expect(result.current).toEqual([
+      ...multiKeyUpdates.map((row) => ({ ...row, namespace: config["namespace"], table: "MultiKey" })),
+    ]);
+  });
+});

package/src/store-cache/useRows.ts

@@ -0,0 +1,32 @@
+import { DatabaseClient, FilterOptions, ScanResult } from "@latticexyz/store-cache";
+import { StoreConfig } from "@latticexyz/store";
+import { useEffect, useState } from "react";
+import { useDeepMemo } from "../utils/useDeepMemo";
+import { useMountedState } from "../utils/useMountedState";
+
+/**
+ * Returns an array of all rows matching the provided filter
+ */
+export function useRows<C extends StoreConfig, T extends keyof C["tables"] & string>(
+  storeCache: DatabaseClient<C>,
+  filter?: FilterOptions<C, T>
+) {
+  const [rows, setRows] = useMountedState<ScanResult<C, T>>([]);
+  const filterMemo = useDeepMemo(filter);
+
+  useEffect(() => {
+    storeCache.scan(filterMemo).then(setRows);
+
+    const unsubscribePromise = storeCache.subscribe(() => {
+      // very naive implementation for now, but easier and probably more efficient than
+      // manually looping through the `rows` array for every update event
+      storeCache.scan(filterMemo).then(setRows);
+    }, filterMemo);
+
+    return () => {
+      unsubscribePromise.then((unsubscribe) => unsubscribe());
+    };
+  }, [filterMemo, setRows, storeCache]);
+
+  return rows;
+}

package/src/useComponentValue.test.ts

@@ -0,0 +1,89 @@
+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";
+import { describe, it, expect, beforeEach } from "vitest";
+
+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,164 @@
+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";
+import { describe, beforeEach, it, expect } from "vitest";
+
+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;
+};

package/src/utils/useMountedState.ts

@@ -0,0 +1,23 @@
+import { Dispatch, SetStateAction, useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Use in place of useState when the component may be unmounted before the state is updated.
+ */
+export function useMountedState<T>(initialState: T | (() => T)): [T, Dispatch<SetStateAction<T>>] {
+  const [state, setState] = useState<T>(initialState);
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  });
+  const mountedSetState: typeof setState = useCallback((...args) => {
+    if (mountedRef.current) {
+      setState(...args);
+    } else {
+      console.warn("Ignoring `setState` call because component unmounted", ...args);
+    }
+  }, []);
+  return [state, mountedSetState];
+}