feat(stash): add useRecord and useRecords hooks (#3450)

.changeset/slimy-lemons-think.md

@@ -0,0 +1,17 @@
+---
+"@latticexyz/stash": patch
+---
+
+Added `useRecord` and `useRecords` hooks for convenience.
+
+```ts
+import { useRecords } from "@latticexyz/stash/react";
+
+const players = useRecords({ stash, table: Position });
+```
+
+```ts
+import { useRecord } from "@latticexyz/stash/react";
+
+const player = useRecord({ stash, table: Position, key: { player: "0x..." } });
+```

packages/stash/src/exports/react.ts

@@ -1 +1,3 @@
 export { useStash, type UseStashOptions } from "../react/useStash";
+export { useRecord, type UseRecordOptions, type UseRecordResult } from "../react/useRecord";
+export { useRecords, type UseRecordsOptions, type UseRecordsResult } from "../react/useRecords";

packages/stash/src/react/isArrayEqual.ts

@@ -0,0 +1,8 @@
+export function isArrayEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = a.length - 1; i >= 0; i--) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}

packages/stash/src/react/useRecord.ts

@@ -0,0 +1,26 @@
+import { Table } from "@latticexyz/config";
+import { TableRecord, Stash, Key } from "../common";
+import { useStash } from "./useStash";
+import { getRecord } from "../actions/getRecord";
+
+export type UseRecordOptions<
+  table extends Table = Table,
+  defaultValue extends Omit<TableRecord<table>, keyof Key<table>> | undefined = undefined,
+> = {
+  stash: Stash;
+  table: table;
+  key: Key<table>;
+  defaultValue?: defaultValue;
+};
+
+export type UseRecordResult<
+  table extends Table = Table,
+  defaultValue extends Omit<TableRecord<table>, keyof Key<table>> | undefined = undefined,
+> = defaultValue extends undefined ? TableRecord<table> | undefined : TableRecord<table>;
+
+export function useRecord<
+  const table extends Table,
+  const defaultValue extends Omit<TableRecord<table>, keyof Key<table>> | undefined = undefined,
+>({ stash, ...args }: UseRecordOptions<table, defaultValue>): UseRecordResult<table, defaultValue> {
+  return useStash(stash, (state) => getRecord({ state, ...args }));
+}

packages/stash/src/react/useRecords.ts

@@ -0,0 +1,22 @@
+import { Table } from "@latticexyz/config";
+import { Key, Stash, TableRecord } from "../common";
+import { useStash } from "./useStash";
+import { getRecords } from "../actions/getRecords";
+import { isArrayEqual } from "./isArrayEqual";
+
+export type UseRecordsOptions<table extends Table = Table> = {
+  stash: Stash;
+  table: table;
+  keys?: readonly Key<table>[];
+};
+
+export type UseRecordsResult<table extends Table = Table> = readonly TableRecord<table>[];
+
+export function useRecords<const table extends Table>({
+  stash,
+  ...args
+}: UseRecordsOptions<table>): UseRecordsResult<table> {
+  return useStash(stash, (state) => Object.values(getRecords({ state, ...args })), {
+    isEqual: isArrayEqual,
+  });
+}