Add type-safe useValues hook

Author: axelboc

packages/app/README.md

@@ -541,71 +541,73 @@ function MyApp() {
 }
 ```
 
-For convenience, the following hooks are available to access data through the
-data context: `useEntity`, `useDatasets`, `useDatasetValue`,
-`useDatasetsValues`, `usePrefetchValues`.
-
-We also provide a large number of type guards and assertion functions to narrow
-down the kind/shape/type of HDF5 entities returned by `useEntity`, as well as a
-memoised hook called `useNdArray` to create ndarrays that can be passed to the
-visualization components (available in `@h5web/lib`).
+A common need is to find specific datasets in a file and retrieve their values.
+You can do so with hooks `useDatasets` and `useValues` as follows:
 
 ```tsx
-function MyApp() {
-  const entity = useEntity('/nD_datasets/twoD'); // ProvidedEntity
-  assertDataset(entity); // Dataset
-  assertArrayShape(entity); // Dataset<ArrayShape>
-  assertFloatType(entity); // Dataset<ArrayShape, FloatType>
+const DATASETS_DEFS = {
+  twoD: { path: '/twoD', shape: ShapeClass.Array, type: DTypeClass.Float }
+  title: { path: '/title', shape: ShapeClass.Scalar, type: DTypeClass.String }
+};
 
-  const value = useDatasetValue(entity); // number[] | TypedArray
-  const dataArray = useNdArray(value, entity.shape);
-  const domain = useDomain(dataArray);
+function MyApp() {
+  const datasets = useDatasets(DATASETS_DEFS);
+  const { twoD, title } = useValues(datasets); // `number[] | TypedArray` and `string` respectively
 
-  return (
-    <HeatmapVis
-      style={{ width: '100vw', height: '100vh' }}
-      dataArray={dataArray}
-      domain={domain}
-    />
-  );
+  // Or if you just need a specific slice from the `twoD` dataset:
+  const { slice, title } = useValues({
+    slice: { dataset: datasets.twoD, selection: '2,:' },
+    title: dataset.title,
+  })
 }
 ```
 
-The `useDatasets` hook is a declarative alternative to `useEntity` that can
-retrieve multiple datasets at once and doesn't require invoking assertion
-functions afterwards:
+We also provide two simpler hooks, `useEntity` and `useValue`, as well as a
+large number of type guards and assertion functions to narrow down the
+kind/shape/type of HDF5 entities returned by `useEntity`.
 
-```ts
-// `twoD` => `Dataset<ArrayShape, FloatType>`
-// `title` => `Dataset<ScalarShape, StringType>`
-const { twoD, title } = useDatasets({
-  twoD: { path: '/nD_datasets/twoD', shape: ShapeClass.Array, type: DTypeClass.Float }
-  title: { path: '/path/to/title', shape: ShapeClass.Scalar, type: DTypeClass.String }
-});
+```tsx
+const entity = useEntity('/nD_datasets/twoD'); // ProvidedEntity
+assertDataset(entity); // Dataset
+assertArrayShape(entity); // Dataset<ArrayShape>
+assertFloatType(entity); // Dataset<ArrayShape, FloatType>
+
+const value = useValue(entity); // number[] | TypedArray
+
+// Or a specific slice:
+const slice = useValue(entity, '2,:');
 ```
 
-When accessing the values of multiple datasets with multiple consecutive calls
-to `useDatasetValue` (and/or `useDatasetsValues`), invoke `usePrefetchValues`
-first to ensure that the values are requested in parallel rather than
-sequentially:
+Once you have a raw value array, you can use the memoised hook `useNdArray` to
+wrap it in an ndarray, and then pass it down to a visualization component from
+`@h5web/lib`:
 
 ```tsx
-const axesDatasets = [abscissasDataset, ordinatesDataset];
-usePrefetchValues([valuesDataset, ...axesDatasets]);
-
-const values = useDatasetValue(valuesDataset);
-const [abscissas, ordinates] = useDatasetsValues(axesDatasets);
+const value = useValue(entity); // number[] | TypedArray
+const dataArray = useNdArray(value, entity.shape); // NdArray<number[] | TypedArray>
+const domain = useDomain(dataArray); // [number, number]
+
+return (
+  <HeatmapVis
+    style={{ width: '100vw', height: '100vh' }}
+    dataArray={dataArray}
+    domain={domain}
+  />
+);
 ```
 
-All three hooks accept a `selection` parameter to request specific slices from
-n-dimensional datasets:
+Every store comes with a `prefetch` method that works like `get` but doesn't
+trigger the `Suspense` boundary and doesn't return a value. If you work with a
+remote provider like H5Grove and need to access multiple entities/values at
+once, it's important to prefetch every entity/value first so the requests are
+done in parallel. `useDatasets` and `useValues` do this automatically, but not
+`useEntity` and `useValue`:
 
 ```tsx
-const selection = '0,:,:';
-usePrefetchValues([valuesDataset], selection); // prefetch the first 2D slice
-usePrefetchValues([abscissasDataset, ordinatesDataset]); // pretech in full (i.e. no selection)
+const { valuesStore } = useDataContext();
+valuesStore.prefetch(abscissasDataset);
+valuesStore.prefetch(ordinatesDataset);
 
-const values = useDatasetValue(valuesDataset, selection);
-const abscissas = useDatasetValue(abscissasDataset);
-const ordinates = useDatasetValue(ordinatesDataset);
+const abscissas = useValue(abscissasDataset);
+const ordinates = useValue(ordinatesDataset);
 ```

packages/app/src/hooks.ts

@@ -16,6 +16,7 @@ import {
 } from '@h5web/shared/hdf5-models';
 
 import { useDataContext } from './providers/DataProvider';
+import { type ValuesStoreParams } from './providers/models';
 
 export function useEntity(path: string): ProvidedEntity {
   const { entitiesStore } = useDataContext();
@@ -77,6 +78,33 @@ export function useValue<D extends Dataset<ArrayShape | ScalarShape>>(
   return value;
 }
 
+type ValueFromParams<
+  T extends ValuesStoreParams['dataset'] | ValuesStoreParams,
+> = Value<T extends ValuesStoreParams ? T['dataset'] : T>;
+
+export function useValues<
+  R extends Record<string, ValuesStoreParams['dataset'] | ValuesStoreParams>,
+>(datasets: R): { [K in keyof R]: ValueFromParams<R[K]> } {
+  const { valuesStore } = useDataContext();
+
+  const withSelections = Object.entries(datasets).map(([key, dataset]) => {
+    return [
+      key,
+      'dataset' in dataset ? dataset : { dataset, selection: undefined },
+    ] as const;
+  });
+
+  withSelections.forEach(([, { dataset, selection }]) => {
+    valuesStore.prefetch({ dataset, selection });
+  });
+
+  return Object.fromEntries(
+    withSelections.map(([key, withSelection]) => {
+      return [key, valuesStore.get(withSelection)];
+    }),
+  ) as { [K in keyof R]: ValueFromParams<R[K]> };
+}
+
 export function useValuesInCache(
   ...datasets: (Dataset<ScalarShape | ArrayShape> | undefined)[]
 ): (dimMapping: DimensionMapping) => boolean {

packages/app/src/index.ts

@@ -38,7 +38,7 @@ export type {
 } from './providers/models';
 
 // Hooks
-export { useEntity, useDatasets, useValue } from './hooks';
+export { useEntity, useDatasets, useValue, useValues } from './hooks';
 export { useBaseArray as useNdArray } from './vis-packs/core/hooks';
 
 // Models

packages/app/src/vis-packs/nexus/NxNoteFetcher.tsx

@@ -5,7 +5,7 @@ import {
 } from '@h5web/shared/hdf5-models';
 import { type ReactNode } from 'react';
 
-import { useNxValues, usePrefetchNxValues } from './hooks';
+import { useValues } from '../../hooks';
 
 interface Props {
   dataDataset: Dataset<ScalarShape, StringType>;
@@ -16,8 +16,10 @@ interface Props {
 function NxNoteFetcher(props: Props) {
   const { dataDataset, typeDataset, render } = props;
 
-  usePrefetchNxValues([dataDataset, typeDataset]);
-  const [value, mimeType] = useNxValues([dataDataset, typeDataset]);
+  const { value, mimeType } = useValues({
+    value: dataDataset,
+    mimeType: typeDataset,
+  });
 
   return <>{render(value, mimeType)}</>;
 }