@latticexyz/react 2.0.0-alpha.1.21 → 2.0.0-alpha.1.210

package/README.md

@@ -2,11 +2,41 @@
 
 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);
 ```
 
@@ -14,7 +44,7 @@ const position = useComponentValue(Position, entity);
 
 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

@@ -1,128 +1,2 @@
-import { getComponentValue, defineQuery, Has, isComponentUpdate } from '@latticexyz/recs';
-import { useState, useEffect, useMemo } from 'react';
-import { map, distinctUntilChanged } from 'rxjs';
-
-function useComponentValue(component, entityIndex, defaultValue) {
-    const [value, setValue] = useState(entityIndex != null ? getComponentValue(component, entityIndex) : undefined);
-    useEffect(() => {
-        // component or entityIndex changed, update state to latest value
-        setValue(entityIndex != null ? getComponentValue(component, entityIndex) : undefined);
-        if (entityIndex == null)
-            return;
-        const queryResult = defineQuery([Has(component)], { runOnInit: false });
-        const subscription = queryResult.update$.subscribe((update) => {
-            if (isComponentUpdate(update, component) && update.entity === entityIndex) {
-                const [nextValue] = update.value;
-                setValue(nextValue);
-            }
-        });
-        return () => subscription.unsubscribe();
-    }, [component, entityIndex]);
-    return value ?? defaultValue;
-}
-
-/** @deprecated See https://github.com/latticexyz/mud/issues/339 */
-const useDeprecatedComputedValue = (computedValue) => {
-    const [value, setValue] = useState(computedValue.get());
-    useEffect(() => {
-        const unsubscribe = computedValue.observe_(() => setValue(computedValue.get()));
-        return () => unsubscribe();
-    }, [computedValue]);
-    return value;
-};
-
-// do not edit .js files directly - edit src/index.jst
-
-
-
-var fastDeepEqual = function equal(a, b) {
-  if (a === b) return true;
-
-  if (a && b && typeof a == 'object' && typeof b == 'object') {
-    if (a.constructor !== b.constructor) return false;
-
-    var length, i, keys;
-    if (Array.isArray(a)) {
-      length = a.length;
-      if (length != b.length) return false;
-      for (i = length; i-- !== 0;)
-        if (!equal(a[i], b[i])) return false;
-      return true;
-    }
-
-
-
-    if (a.constructor === RegExp) return a.source === b.source && a.flags === b.flags;
-    if (a.valueOf !== Object.prototype.valueOf) return a.valueOf() === b.valueOf();
-    if (a.toString !== Object.prototype.toString) return a.toString() === b.toString();
-
-    keys = Object.keys(a);
-    length = keys.length;
-    if (length !== Object.keys(b).length) return false;
-
-    for (i = length; i-- !== 0;)
-      if (!Object.prototype.hasOwnProperty.call(b, keys[i])) return false;
-
-    for (i = length; i-- !== 0;) {
-      var key = keys[i];
-
-      if (!equal(a[key], b[key])) return false;
-    }
-
-    return true;
-  }
-
-  // true if both NaN, false otherwise
-  return a!==a && b!==b;
-};
-
-const useDeepMemo = (currentValue) => {
-    const [stableValue, setStableValue] = useState(currentValue);
-    useEffect(() => {
-        if (!fastDeepEqual(currentValue, stableValue)) {
-            setStableValue(currentValue);
-        }
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [currentValue]);
-    return stableValue;
-};
-
-// 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 `EntityIndex`es 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.
- */
-function useEntityQuery(fragments, options) {
-    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) => fastDeepEqual(a, b)));
-        }
-        const subscription = observable.subscribe((entities) => setEntities(entities));
-        return () => subscription.unsubscribe();
-    }, [query, updateOnValueChange]);
-    return entities;
-}
-
-function useObservableValue(observable, defaultValue) {
-    const [value, setValue] = useState(defaultValue);
-    useEffect(() => {
-        const subscription = observable.subscribe(setValue);
-        return () => subscription.unsubscribe();
-    }, [observable]);
-    return value;
-}
-
-export { useComponentValue, useDeprecatedComputedValue, useEntityQuery, useObservableValue };
-//# sourceMappingURL=index.js.map
+import{defineQuery as c,getComponentValue as p,Has as d,isComponentUpdate as C}from"@latticexyz/recs";import{useEffect as S,useState as x}from"react";function z(e,t,n){let[s,o]=x(t!=null?p(e,t):void 0);return S(()=>{if(o(t!=null?p(e,t):void 0),t==null)return;let u=c([d(e)],{runOnInit:!1}).update$.subscribe(r=>{if(C(r,e)&&r.entity===t){let[m]=r.value;o(m)}});return()=>u.unsubscribe()},[e,t]),s??n}import{useEffect as T,useState as g}from"react";var G=e=>{let[t,n]=g(e.get());return T(()=>{let s=e.observe_(()=>n(e.get()));return()=>s()},[e]),t};import{defineQuery as v}from"@latticexyz/recs";import{useEffect as E,useMemo as R,useState as h}from"react";import{useEffect as y,useState as V}from"react";import O from"fast-deep-equal";var a=e=>{let[t,n]=V(e);return y(()=>{O(e,t)||n(e)},[e]),t};import M from"fast-deep-equal";import{distinctUntilChanged as D,map as k}from"rxjs";function ne(e,t){let n=t?.updateOnValueChange??!0,s=a(e),o=R(()=>v(s,{runOnInit:!0}),[s]),[i,u]=h([...o.matching]);return E(()=>{u([...o.matching]);let r=o.update$.pipe(k(()=>[...o.matching]));n||(r=r.pipe(D((f,b)=>M(f,b))));let m=r.subscribe(f=>u(f));return()=>m.unsubscribe()},[o,n]),i}import{useEffect as w,useState as F}from"react";function re(e,t){let[n,s]=F(t);return w(()=>{let o=e.subscribe(s);return()=>o.unsubscribe()},[e]),n}import{useEffect as q,useState as Q}from"react";function l(e,t){let[n,s]=Q([]),o=a(t);return q(()=>(s(e.scan(t)),e.subscribe(()=>{s(e.scan(t))},t)),[o]),n}function pe(e,t){let{namespace:n,table:s,key:o}=t;return l(e,{namespace:n,table:s,key:{eq:o}})[0]}export{z as useComponentValue,G as useDeprecatedComputedValue,ne as useEntityQuery,re as useObservableValue,pe as useRow,l as useRows};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/useComponentValue.ts","../src/useDeprecatedComputedValue.ts","../../../node_modules/.pnpm/fast-deep-equal@3.1.3/node_modules/fast-deep-equal/index.js","../src/utils/useDeepMemo.ts","../src/useEntityQuery.ts","../src/useObservableValue.ts"],"sourcesContent":[null,null,"'use strict';\n\n// do not edit .js files directly - edit src/index.jst\n\n\n\nmodule.exports = function equal(a, b) {\n  if (a === b) return true;\n\n  if (a && b && typeof a == 'object' && typeof b == 'object') {\n    if (a.constructor !== b.constructor) return false;\n\n    var length, i, keys;\n    if (Array.isArray(a)) {\n      length = a.length;\n      if (length != b.length) return false;\n      for (i = length; i-- !== 0;)\n        if (!equal(a[i], b[i])) return false;\n      return true;\n    }\n\n\n\n    if (a.constructor === RegExp) return a.source === b.source && a.flags === b.flags;\n    if (a.valueOf !== Object.prototype.valueOf) return a.valueOf() === b.valueOf();\n    if (a.toString !== Object.prototype.toString) return a.toString() === b.toString();\n\n    keys = Object.keys(a);\n    length = keys.length;\n    if (length !== Object.keys(b).length) return false;\n\n    for (i = length; i-- !== 0;)\n      if (!Object.prototype.hasOwnProperty.call(b, keys[i])) return false;\n\n    for (i = length; i-- !== 0;) {\n      var key = keys[i];\n\n      if (!equal(a[key], b[key])) return false;\n    }\n\n    return true;\n  }\n\n  // true if both NaN, false otherwise\n  return a!==a && b!==b;\n};\n",null,null,null],"names":["isEqual"],"mappings":";;;;SAwBgB,iBAAiB,CAC/B,SAA4C,EAC5C,WAAoC,EACpC,YAAgC,EAAA;IAEhC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,WAAW,IAAI,IAAI,GAAG,iBAAiB,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,SAAS,CAAC,CAAC;IAEhH,SAAS,CAAC,MAAK;;AAEb,QAAA,QAAQ,CAAC,WAAW,IAAI,IAAI,GAAG,iBAAiB,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,SAAS,CAAC,CAAC;QACtF,IAAI,WAAW,IAAI,IAAI;YAAE,OAAO;AAEhC,QAAA,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QACxE,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,KAAI;AAC5D,YAAA,IAAI,iBAAiB,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE;AACzE,gBAAA,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;gBACjC,QAAQ,CAAC,SAAS,CAAC,CAAC;AACrB,aAAA;AACH,SAAC,CAAC,CAAC;AACH,QAAA,OAAO,MAAM,YAAY,CAAC,WAAW,EAAE,CAAC;AAC1C,KAAC,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAE7B,OAAO,KAAK,IAAI,YAAY,CAAC;AAC/B;;AC5CA;AACa,MAAA,0BAA0B,GAAG,CAAI,aAAoD,KAAI;AACpG,IAAA,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAI,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AAChF,QAAA,OAAO,MAAM,WAAW,EAAE,CAAC;AAC7B,KAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;AAEpB,IAAA,OAAO,KAAK,CAAC;AACf;;ACXA;AACA;AACA;AACA;AACA,IAAA,aAAc,GAAG,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE;AACtC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,IAAI,CAAC;AAC3B;AACA,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,QAAQ,IAAI,OAAO,CAAC,IAAI,QAAQ,EAAE;AAC9D,IAAI,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,EAAE,OAAO,KAAK,CAAC;AACtD;AACA,IAAI,IAAI,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC;AACxB,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;AAC1B,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;AACxB,MAAM,IAAI,MAAM,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,CAAC;AAC3C,MAAM,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC;AAChC,QAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC;AAC7C,MAAM,OAAO,IAAI,CAAC;AAClB,KAAK;AACL;AACA;AACA;AACA,IAAI,IAAI,CAAC,CAAC,WAAW,KAAK,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC;AACtF,IAAI,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;AACnF,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;AACvF;AACA,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC1B,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;AACzB,IAAI,IAAI,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,CAAC;AACvD;AACA,IAAI,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC;AAC9B,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC;AAC1E;AACA,IAAI,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG;AACjC,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AACxB;AACA,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC;AAC/C,KAAK;AACL;AACA,IAAI,OAAO,IAAI,CAAC;AAChB,GAAG;AACH;AACA;AACA,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;;AC1CM,MAAM,WAAW,GAAG,CAAI,YAAe,KAAO;IACnD,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAE7D,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,CAACA,aAAO,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE;YACvC,cAAc,CAAC,YAAY,CAAC,CAAC;AAC9B,SAAA;;AAEH,KAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;AAEnB,IAAA,OAAO,WAAW,CAAC;AACrB,CAAC;;ACRD;AACA;AAEA;;;;;;;AAOG;AACa,SAAA,cAAc,CAAC,SAA0B,EAAE,OAA2C,EAAA;AACpG,IAAA,MAAM,mBAAmB,GAAG,OAAO,EAAE,mBAAmB,IAAI,IAAI,CAAC;AAEjE,IAAA,MAAM,eAAe,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,WAAW,CAAC,eAAe,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC;AAClG,IAAA,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE9D,SAAS,CAAC,MAAK;QACb,WAAW,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QACjC,IAAI,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC,mBAAmB,EAAE;;YAExB,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,KAAKA,aAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7E,SAAA;AACD,QAAA,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,QAAQ,KAAK,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/E,QAAA,OAAO,MAAM,YAAY,CAAC,WAAW,EAAE,CAAC;AAC1C,KAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAEjC,IAAA,OAAO,QAAQ,CAAC;AAClB;;AC7BgB,SAAA,kBAAkB,CAAI,UAAyB,EAAE,YAAgB,EAAA;IAC/E,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAEjD,SAAS,CAAC,MAAK;QACb,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AACpD,QAAA,OAAO,MAAM,YAAY,CAAC,WAAW,EAAE,CAAC;AAC1C,KAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;AAEjB,IAAA,OAAO,KAAK,CAAC;AACf;;;;"}
+{"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/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\";\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] = useState<ScanResult<C, T>>([]);\n  const filterMemo = useDeepMemo(filter);\n\n  useEffect(() => {\n    setRows(storeCache.scan(filter));\n\n    const unsubscribe = 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      setRows(storeCache.scan(filter));\n    }, filter);\n\n    return unsubscribe;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [filterMemo]);\n\n  return rows;\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":"AAAA,OAGE,eAAAA,EAEA,qBAAAC,EACA,OAAAC,EACA,qBAAAC,MAGK,mBACP,OAAS,aAAAC,EAAW,YAAAC,MAAgB,QAa7B,SAASC,EACdC,EACAC,EACAC,EACA,CACA,GAAM,CAACC,EAAOC,CAAQ,EAAIN,EAASG,GAAU,KAAOP,EAAkBM,EAAWC,CAAM,EAAI,MAAS,EAEpG,OAAAJ,EAAU,IAAM,CAGd,GADAO,EAASH,GAAU,KAAOP,EAAkBM,EAAWC,CAAM,EAAI,MAAS,EACtEA,GAAU,KAAM,OAGpB,IAAMI,EADcZ,EAAY,CAACE,EAAIK,CAAS,CAAC,EAAG,CAAE,UAAW,EAAM,CAAC,EACrC,QAAQ,UAAWM,GAAW,CAC7D,GAAIV,EAAkBU,EAAQN,CAAS,GAAKM,EAAO,SAAWL,EAAQ,CACpE,GAAM,CAACM,CAAS,EAAID,EAAO,MAC3BF,EAASG,CAAS,EAEtB,CAAC,EACD,MAAO,IAAMF,EAAa,YAAY,CACxC,EAAG,CAACL,EAAWC,CAAM,CAAC,EAEfE,GAASD,CAClB,CC9CA,OAAS,aAAAM,EAAW,YAAAC,MAAgB,QAG7B,IAAMC,EAAiCC,GAAyD,CACrG,GAAM,CAACC,EAAOC,CAAQ,EAAIJ,EAAYE,EAAc,IAAI,CAAC,EAEzD,OAAAH,EAAU,IAAM,CACd,IAAMM,EAAcH,EAAc,SAAS,IAAME,EAASF,EAAc,IAAI,CAAC,CAAC,EAC9E,MAAO,IAAMG,EAAY,CAC3B,EAAG,CAACH,CAAa,CAAC,EAEXC,CACT,ECbA,OAAS,eAAAG,MAAkC,mBAC3C,OAAS,aAAAC,EAAW,WAAAC,EAAS,YAAAC,MAAgB,QCD7C,OAAS,aAAAC,EAAW,YAAAC,MAAgB,QACpC,OAAOC,MAAa,kBAEb,IAAMC,EAAkBC,GAAuB,CACpD,GAAM,CAACC,EAAaC,CAAc,EAAIL,EAASG,CAAY,EAE3D,OAAAJ,EAAU,IAAM,CACTE,EAAQE,EAAcC,CAAW,GACpCC,EAAeF,CAAY,CAG/B,EAAG,CAACA,CAAY,CAAC,EAEVC,CACT,EDXA,OAAOE,MAAa,kBACpB,OAAS,wBAAAC,EAAsB,OAAAC,MAAW,OAanC,SAASC,GAAeC,EAA4BC,EAA6C,CACtG,IAAMC,EAAsBD,GAAS,qBAAuB,GAEtDE,EAAkBC,EAAYJ,CAAS,EACvCK,EAAQC,EAAQ,IAAMC,EAAYJ,EAAiB,CAAE,UAAW,EAAK,CAAC,EAAG,CAACA,CAAe,CAAC,EAC1F,CAACK,EAAUC,CAAW,EAAIC,EAAS,CAAC,GAAGL,EAAM,QAAQ,CAAC,EAE5D,OAAAM,EAAU,IAAM,CACdF,EAAY,CAAC,GAAGJ,EAAM,QAAQ,CAAC,EAC/B,IAAIO,EAAaP,EAAM,QAAQ,KAAKP,EAAI,IAAM,CAAC,GAAGO,EAAM,QAAQ,CAAC,CAAC,EAC7DH,IAEHU,EAAaA,EAAW,KAAKf,EAAqB,CAACgB,EAAG,IAAMjB,EAAQiB,EAAG,CAAC,CAAC,CAAC,GAE5E,IAAMC,EAAeF,EAAW,UAAWJ,GAAaC,EAAYD,CAAQ,CAAC,EAC7E,MAAO,IAAMM,EAAa,YAAY,CACxC,EAAG,CAACT,EAAOH,CAAmB,CAAC,EAExBM,CACT,CEpCA,OAAS,aAAAO,EAAW,YAAAC,MAAgB,QAO7B,SAASC,GAAsBC,EAA2BC,EAAkB,CACjF,GAAM,CAACC,EAAOC,CAAQ,EAAIL,EAASG,CAAY,EAE/C,OAAAJ,EAAU,IAAM,CACd,IAAMO,EAAeJ,EAAW,UAAUG,CAAQ,EAClD,MAAO,IAAMC,EAAa,YAAY,CACxC,EAAG,CAACJ,CAAU,CAAC,EAERE,CACT,CCdA,OAAS,aAAAG,EAAW,YAAAC,MAAgB,QAM7B,SAASC,EACdC,EACAC,EACA,CACA,GAAM,CAACC,EAAMC,CAAO,EAAIC,EAA2B,CAAC,CAAC,EAC/CC,EAAaC,EAAYL,CAAM,EAErC,OAAAM,EAAU,KACRJ,EAAQH,EAAW,KAAKC,CAAM,CAAC,EAEXD,EAAW,UAAU,IAAM,CAG7CG,EAAQH,EAAW,KAAKC,CAAM,CAAC,CACjC,EAAGA,CAAM,GAIR,CAACI,CAAU,CAAC,EAERH,CACT,CCbO,SAASM,GACdC,EACAC,EACiC,CACjC,GAAM,CAAE,UAAAC,EAAW,MAAAC,EAAO,IAAAC,CAAI,EAAIH,EAClC,OAAOI,EAAQL,EAAY,CAAE,UAAAE,EAAW,MAAAC,EAAO,IAAK,CAAE,GAAIC,CAAI,CAAE,CAAC,EAAE,CAAC,CACtE","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","useState","useRows","storeCache","filter","rows","setRows","useState","filterMemo","useDeepMemo","useEffect","useRow","storeCache","filter","namespace","table","key","useRows"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latticexyz/react",
-  "version": "2.0.0-alpha.1.21+4ad66187",
+  "version": "2.0.0-alpha.1.210+69c126a9",
   "description": "React tools for MUD client.",
   "repository": {
     "type": "git",
@@ -8,49 +8,41 @@
     "directory": "packages/react"
   },
   "license": "MIT",
-  "main": "dist/index.js",
-  "source": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "src/index.ts",
   "scripts": {
-    "build": "rimraf dist && rollup -c rollup.config.js",
+    "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/\" {} \\;",
-    "prepack": "mv package.json package.json.bak && jq \".main = \\\"dist/index.js\\\"\" package.json.bak > package.json ",
-    "postpack": "mv package.json.bak package.json || echo 'no package.json.bak'",
-    "release": "npm publish --access=public",
-    "test": "tsc --noEmit && jest"
+    "test": "tsc --noEmit && vitest --run"
   },
   "dependencies": {
-    "fast-deep-equal": "^3.1.3"
+    "@latticexyz/recs": "2.0.0-alpha.1.210+69c126a9",
+    "@latticexyz/store": "2.0.0-alpha.1.210+69c126a9",
+    "@latticexyz/store-cache": "2.0.0-alpha.1.210+69c126a9",
+    "fast-deep-equal": "^3.1.3",
+    "mobx": "^6.7.0",
+    "react": "^18.2.0",
+    "rxjs": "^7.5.5"
   },
   "devDependencies": {
-    "@latticexyz/recs": "2.0.0-alpha.1.21+4ad66187",
-    "@rollup/plugin-json": "^4.1.0",
-    "@rollup/plugin-node-resolve": "^13.1.3",
-    "@rollup/plugin-typescript": "^11.0.0",
     "@testing-library/react-hooks": "^8.0.1",
-    "@types/jest": "^27.4.1",
-    "@types/react": "^18.0.12",
-    "eslint-plugin-react": "^7.31.11",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "jest": "^29.3.1",
-    "mobx": "^6.4.2",
-    "react": "^18.2.0",
+    "@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",
-    "rimraf": "^3.0.2",
-    "rollup": "^2.69.0",
-    "rollup-plugin-commonjs": "^10.1.0",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "rxjs": "^7.5.5",
-    "ts-jest": "^29.0.5",
-    "tslib": "^2.5.0",
+    "tsup": "^6.7.0",
     "typedoc": "0.23.21",
     "typedoc-plugin-markdown": "^3.13.6",
-    "typescript": "^4.9.5"
-  },
-  "peerDependencies": {
-    "@latticexyz/recs": "latest",
-    "mobx": "^6.4.2",
-    "react": "^18.2.0",
-    "rxjs": "^7.5.5"
+    "vite": "^4.3.6",
+    "vitest": "^0.31.0"
   },
-  "gitHead": "4ad661878bcf916a9ab7fd4d72d051b372af74c5"
+  "gitHead": "69c126a9e3d95a451b88d36c50e30279cc628a9d"
 }

package/{dist/index.d.ts → src/index.ts}

@@ -2,3 +2,4 @@ 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,185 @@
+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", () => {
+    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 } },
+    ];
+
+    act(() => {
+      // Set values in the tables
+      for (const update of positionUpdates) client.tables.Position.set(update.key, update.value);
+      for (const update of multiKeyUpdates) 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",
+    });
+
+    act(() => {
+      for (const update of positionUpdates.slice(0, 3)) 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", () => {
+    const { result } = renderHook(() => useRow(client, { table: "Position", key: { key: "0x00" } }));
+    expect(result.all.length).toBe(2);
+
+    // Update the position table
+    act(() => {
+      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
+    act(() => {
+      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
+    act(() => {
+      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
+    act(() => {
+      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
+    act(() => {
+      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", () => {
+    const { result, rerender } = renderHook(({ filter }) => useRow(client, filter), {
+      initialProps: {
+        filter: { table: "Position", key: { key: "0x01" } } as UseRowFilterOptions<typeof config>,
+      },
+    });
+
+    expect(result.all.length).toBe(2);
+    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 } },
+    ];
+
+    act(() => {
+      // Set values in the tables
+      for (const update of positionUpdates) client.tables.Position.set(update.key, update.value);
+      for (const update of multiKeyUpdates) 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" } } });
+
+    // 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 } } });
+
+    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,157 @@
+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", () => {
+    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 } },
+    ];
+
+    act(() => {
+      // Set values in the tables
+      for (const update of positionUpdates) client.tables.Position.set(update.key, update.value);
+      for (const update of multiKeyUpdates) 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" })),
+    ]);
+
+    act(() => {
+      for (const update of positionUpdates.slice(0, 3)) 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", () => {
+    const { result } = renderHook(() => useRows(client, { namespace: config["namespace"], table: "Position" }));
+    expect(result.all.length).toBe(2);
+
+    // Update the position table
+    act(() => {
+      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
+    act(() => {
+      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
+    act(() => {
+      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
+    act(() => {
+      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
+    act(() => {
+      client.tables.Position.remove({ key: "0x00" });
+    });
+    expect(result.all.length).toBe(5);
+    expect(result.current).toEqual([]);
+  });
+
+  it("should re-render when the filter changes", () => {
+    const { result, rerender } = renderHook(({ filter }) => useRows(client, filter), {
+      initialProps: { filter: { table: "Position" as keyof (typeof config)["tables"] } },
+    });
+
+    expect(result.all.length).toBe(2);
+    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 } },
+    ];
+
+    act(() => {
+      // Set values in the tables
+      for (const update of positionUpdates) client.tables.Position.set(update.key, update.value);
+      for (const update of multiKeyUpdates) client.tables.MultiKey.set(update.key, update.value);
+    });
+
+    expect(result.all.length).toBe(3);
+    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" } });
+
+    // 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.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,30 @@
+import { DatabaseClient, FilterOptions, ScanResult } from "@latticexyz/store-cache";
+import { StoreConfig } from "@latticexyz/store";
+import { useEffect, useState } from "react";
+import { useDeepMemo } from "../utils/useDeepMemo";
+
+/**
+ * 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] = useState<ScanResult<C, T>>([]);
+  const filterMemo = useDeepMemo(filter);
+
+  useEffect(() => {
+    setRows(storeCache.scan(filter));
+
+    const unsubscribe = storeCache.subscribe(() => {
+      // very naive implementation for now, but easier and probably more efficient than
+      // manually looping through the `rows` array for every update event
+      setRows(storeCache.scan(filter));
+    }, filter);
+
+    return unsubscribe;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filterMemo]);
+
+  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/dist/useComponentValue.d.ts

@@ -1,3 +0,0 @@
-import { Component, ComponentValue, EntityIndex, Metadata, Schema } from "@latticexyz/recs";
-export declare function useComponentValue<S extends Schema>(component: Component<S, Metadata, undefined>, entityIndex: EntityIndex | undefined, defaultValue: ComponentValue<S>): ComponentValue<S>;
-export declare function useComponentValue<S extends Schema>(component: Component<S, Metadata, undefined>, entityIndex: EntityIndex | undefined): ComponentValue<S> | undefined;

package/dist/useComponentValue.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/useDeprecatedComputedValue.d.ts

@@ -1,5 +0,0 @@
-import { IComputedValue } from "mobx";
-/** @deprecated See https://github.com/latticexyz/mud/issues/339 */
-export declare const useDeprecatedComputedValue: <T>(computedValue: IComputedValue<T> & {
-    observe_: any;
-}) => T;

package/dist/useEntityQuery.d.ts

@@ -1,12 +0,0 @@
-import { QueryFragment } from "@latticexyz/recs";
-/**
- * Returns all matching `EntityIndex`es 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 declare function useEntityQuery(fragments: QueryFragment[], options?: {
-    updateOnValueChange?: boolean;
-}): import("@latticexyz/recs").EntityIndex[];

package/dist/useEntityQuery.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/useObservableValue.d.ts

@@ -1,3 +0,0 @@
-import { Observable } from "rxjs";
-export declare function useObservableValue<T>(observable: Observable<T>, defaultValue: T): T;
-export declare function useObservableValue<T>(observable: Observable<T>): T | undefined;

package/dist/utils/useDeepMemo.d.ts

@@ -1 +0,0 @@
-export declare const useDeepMemo: <T>(currentValue: T) => T;