@view-models/react 1.3.0 → 2.0.0

package/README.md

@@ -46,6 +46,80 @@ function Counter() {
 }
 ```
 
+### Derived State
+
+Use `useDerivedState` with the `derived` helper to compute values from your model state. The `derived` function creates a memoized mapper that uses reference equality (`Object.is`) to cache results, which works perfectly with immutable state.
+
+Derived mappers should be defined outside your components:
+
+```tsx
+import { ViewModel } from "@view-models/core";
+import { useDerivedState, derived } from "@view-models/react";
+
+type TodoItem = {
+  id: number;
+  text: string;
+  completed: boolean;
+};
+
+type TodoState = Readonly<{
+  items: TodoItem[];
+  filter: "all" | "active" | "completed";
+}>;
+
+class TodoViewModel extends ViewModel<TodoState> {
+  // ... methods to modify state
+}
+
+const todoModel = new TodoViewModel({ items: [], filter: "all" });
+
+// Create derived mappers using the derived helper
+const selectStats = derived(({ items }): TodoState) => ({
+  total: items.length,
+  completed: items.filter((item) => item.completed).length,
+  active: items.filter((item) => !item.completed).length,
+}));
+
+function TodoStats() {
+  // Use the derived mapper with useDerivedState
+  const stats = useDerivedState(todoModel, selectStats);
+
+  return (
+    <div>
+      <p>Total: {stats.total}</p>
+      <p>Completed: {stats.completed}</p>
+      <p>Active: {stats.active}</p>
+    </div>
+  );
+}
+```
+
+You can create multiple derived mappers for different parts of your state:
+
+```tsx
+// Create derived mappers outside your components
+const selectFilteredItems = derived(({ items, filter }: TodoState) =>
+  items.filter((item) => {
+    if (filter === "active") return !item.completed;
+    if (filter === "completed") return item.completed;
+    return true;
+  }),
+);
+
+function TodoList() {
+  // The mapper only re-runs when the state reference changes
+  const filteredItems = useDerivedState(todoModel, selectFilteredItems);
+
+  return (
+    <ul>
+      {filteredItems.map((item) => (
+        <li key={item.id}>{item.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
 ### Creating view models inside components
 
 When you need to create a view model from within a React component, use `useMemo` to ensure the model is only created once.

package/dist/index.d.ts

@@ -55,6 +55,7 @@ interface ViewModel<T> {
      */
     get state(): T;
 }
+
 /**
  * A React hook that subscribes a component to a ViewModel's state updates.
  *
@@ -86,5 +87,81 @@ interface ViewModel<T> {
  */
 declare function useModelState<T>(model: ViewModel<T>): T;
 
-export { useModelState };
-export type { ViewModel, ViewModelListener };
+type Mapper<I, O> = (input: I) => O;
+/**
+ * A branded type for derived state mapper functions created by the `derived` utility.
+ * This type ensures that mapper functions are properly memoized before being used
+ * with hooks like `useDerivedState`.
+ */
+type DerivedMapper<I, O> = Mapper<I, O> & {
+    __brand: "derived";
+};
+/**
+ * Creates a memoized derived state mapper function that caches results based on input identity.
+ *
+ * The memoization uses `Object.is` to compare inputs, making it ideal for use with
+ * immutable state objects. When the input reference hasn't changed, the cached output
+ * is returned without re-executing the function.
+ *
+ * This is the required way to create mapper functions for use with `useDerivedState`.
+ *
+ * @template I - The input type
+ * @template O - The output type
+ * @param fn - A pure function that transforms input to output
+ * @returns A memoized derived mapper function
+ *
+ * @example
+ * ```ts
+ * const selectStats = derived(({ items }: AppState) => ({
+ *   total: items.reduce((sum, item) => sum + item.price, 0),
+ *   count: items.length
+ * }));
+ *
+ * // Use with useDerivedState
+ * const stats = useDerivedState(model, selectStats);
+ * ```
+ */
+declare const derived: <I, O>(fn: Mapper<I, O>) => DerivedMapper<I, O>;
+
+/**
+ * A React hook that subscribes to a ViewModel and returns derived state.
+ *
+ * This hook combines `useModelState` with a derived mapper function to compute derived values
+ * from the model's state. The component will re-render whenever the model state changes.
+ *
+ * The mapper must be created using the `derived` utility, which provides memoization
+ * based on state identity to prevent unnecessary recalculations.
+ *
+ * @template S - The model state type
+ * @template D - The derived state type
+ * @param model - The ViewModel instance to subscribe to
+ * @param mapper - A derived mapper function created with the `derived` utility
+ * @returns The derived state computed from the current model state
+ *
+ * @example
+ * ```tsx
+ * import { ViewModel } from "@view-models/core";
+ * import { useDerivedState, derived } from "@view-models/react";
+ *
+ * type TodoState = {
+ *   items: Array<{ id: string; text: string; completed: boolean }>;
+ * };
+ *
+ * const todoModel = new ViewModel<TodoState>({ items: [] });
+ *
+ * // Create a derived mapper function
+ * const selectCompletedCount = derived(({ items }: TodoState) => ({
+ *   completed: items.filter(item => item.completed).length,
+ *   total: items.length
+ * }));
+ *
+ * function TodoStats() {
+ *   const stats = useDerivedState(todoModel, selectCompletedCount);
+ *   return <div>{stats.completed} of {stats.total} completed</div>;
+ * }
+ * ```
+ */
+declare const useDerivedState: <S, D>(model: ViewModel<S>, mapper: DerivedMapper<S, D>) => D;
+
+export { derived, useDerivedState, useModelState };
+export type { DerivedMapper };

package/dist/index.js

@@ -1,2 +1,2 @@
-import{useSyncExternalStore as r}from"react";function t(t){return r(t.subscribe.bind(t),()=>t.state)}export{t as useModelState};
+import{useSyncExternalStore as t}from"react";function r(r){return t(r.subscribe.bind(r),()=>r.state)}const e=(t,e)=>e(r(t)),n={},o=t=>{let r=n,e=n;return o=>r!==n&&Object.is(r,o)?e:e=t(r=o)};export{o as derived,e as useDerivedState,r as useModelState};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/useModelState.ts"],"sourcesContent":["import { useSyncExternalStore } from \"react\";\n\n/**\n * Function that gets called when the state changes.\n *\n * @template T - The state type\n * @param state - The new state\n */\nexport type ViewModelListener = () => void;\n\n/**\n * Interface for a ViewModel that manages state and notifies subscribers of changes.\n *\n * ViewModels provide a way to manage component state outside of the component tree,\n * allowing multiple components to share and react to the same state. They follow\n * the observer pattern, where components can subscribe to state changes and receive\n * notifications when updates occur.\n *\n * @template T - The type of state managed by this ViewModel\n *\n * @example\n * ```typescript\n * // Implementing a ViewModel\n * class CounterViewModel extends ViewModel<{ count: number }> {\n *   increment = () => super.update({ count: super.state.count + 1 });\n *   decrement = () => super.update(({ count: super.state.count - 1  }));\n * }\n *\n * // Using in a component\n * const counterModel = new CounterViewModel({ count: 0 });\n * const { count } = useModelState(counterModel);\n * ```\n */\nexport interface ViewModel<T> {\n  /**\n   * Subscribe to state changes.\n   *\n   * The listener will be called immediately after any state update.\n   *\n   * @param listener - Function to call when state changes\n   * @returns Function to unsubscribe the listener\n   *\n   * @example\n   * ```typescript\n   * const unsubscribe = viewModel.subscribe((state) => {\n   *   console.log('State changed:', state);\n   * });\n   *\n   * // Later, when you want to stop listening:\n   * unsubscribe();\n   * ```\n   */\n  subscribe(listener: ViewModelListener): () => void;\n\n  /**\n   * Get the current state.\n   *\n   * @returns The current state\n   */\n  get state(): T;\n}\n\n/**\n * A React hook that subscribes a component to a ViewModel's state updates.\n *\n * This hook connects a React component to a ViewModel instance, automatically\n * subscribing to state changes and triggering re-renders when the state updates.\n *\n * @template T - The state type, which must extend the State interface\n * @param model - The ViewModel instance to subscribe to\n * @returns The current state from the ViewModel\n *\n * @example\n * ```tsx\n * class CounterViewModel extends ViewModel<{ count: number }> {\n *   increment = () => super.update({ count: super.state.count + 1 });\n * }\n *\n * function Counter() {\n *   const counterModel = useMemo(() => new CounterViewModel({ count: 0 }), []);\n *   const { count } = useModelState(counterModel);\n *\n *   return (\n *     <div>\n *       <p>Count: {count}</p>\n *       <button onClick={counterModel.increment}>+</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useModelState<T>(model: ViewModel<T>): T {\n  return useSyncExternalStore(model.subscribe.bind(model), () => model.state);\n}\n"],"names":["useModelState","model","useSyncExternalStore","subscribe","bind","state"],"mappings":"6CA2FM,SAAUA,EAAiBC,GAC/B,OAAOC,EAAqBD,EAAME,UAAUC,KAAKH,GAAQ,IAAMA,EAAMI,MACvE"}
+{"version":3,"file":"index.js","sources":["../src/useModelState.ts","../src/useDerivedState.ts","../src/derived.ts"],"sourcesContent":["import { useSyncExternalStore } from \"react\";\nimport { ViewModel } from \"./ViewModel\";\n\n/**\n * A React hook that subscribes a component to a ViewModel's state updates.\n *\n * This hook connects a React component to a ViewModel instance, automatically\n * subscribing to state changes and triggering re-renders when the state updates.\n *\n * @template T - The state type, which must extend the State interface\n * @param model - The ViewModel instance to subscribe to\n * @returns The current state from the ViewModel\n *\n * @example\n * ```tsx\n * class CounterViewModel extends ViewModel<{ count: number }> {\n *   increment = () => super.update({ count: super.state.count + 1 });\n * }\n *\n * function Counter() {\n *   const counterModel = useMemo(() => new CounterViewModel({ count: 0 }), []);\n *   const { count } = useModelState(counterModel);\n *\n *   return (\n *     <div>\n *       <p>Count: {count}</p>\n *       <button onClick={counterModel.increment}>+</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useModelState<T>(model: ViewModel<T>): T {\n  return useSyncExternalStore(model.subscribe.bind(model), () => model.state);\n}\n","import { useModelState } from \"./useModelState\";\nimport { ViewModel } from \"./ViewModel\";\nimport { DerivedMapper } from \"./derived\";\n\n/**\n * A React hook that subscribes to a ViewModel and returns derived state.\n *\n * This hook combines `useModelState` with a derived mapper function to compute derived values\n * from the model's state. The component will re-render whenever the model state changes.\n *\n * The mapper must be created using the `derived` utility, which provides memoization\n * based on state identity to prevent unnecessary recalculations.\n *\n * @template S - The model state type\n * @template D - The derived state type\n * @param model - The ViewModel instance to subscribe to\n * @param mapper - A derived mapper function created with the `derived` utility\n * @returns The derived state computed from the current model state\n *\n * @example\n * ```tsx\n * import { ViewModel } from \"@view-models/core\";\n * import { useDerivedState, derived } from \"@view-models/react\";\n *\n * type TodoState = {\n *   items: Array<{ id: string; text: string; completed: boolean }>;\n * };\n *\n * const todoModel = new ViewModel<TodoState>({ items: [] });\n *\n * // Create a derived mapper function\n * const selectCompletedCount = derived(({ items }: TodoState) => ({\n *   completed: items.filter(item => item.completed).length,\n *   total: items.length\n * }));\n *\n * function TodoStats() {\n *   const stats = useDerivedState(todoModel, selectCompletedCount);\n *   return <div>{stats.completed} of {stats.total} completed</div>;\n * }\n * ```\n */\nexport const useDerivedState = <S, D>(\n  model: ViewModel<S>,\n  mapper: DerivedMapper<S, D>,\n) => mapper(useModelState(model));\n","type Mapper<I, O> = (input: I) => O;\n\n/**\n * A branded type for derived state mapper functions created by the `derived` utility.\n * This type ensures that mapper functions are properly memoized before being used\n * with hooks like `useDerivedState`.\n */\nexport type DerivedMapper<I, O> = Mapper<I, O> & { __brand: \"derived\" };\n\nconst UNINITIALIZED = {};\n\n/**\n * Creates a memoized derived state mapper function that caches results based on input identity.\n *\n * The memoization uses `Object.is` to compare inputs, making it ideal for use with\n * immutable state objects. When the input reference hasn't changed, the cached output\n * is returned without re-executing the function.\n *\n * This is the required way to create mapper functions for use with `useDerivedState`.\n *\n * @template I - The input type\n * @template O - The output type\n * @param fn - A pure function that transforms input to output\n * @returns A memoized derived mapper function\n *\n * @example\n * ```ts\n * const selectStats = derived(({ items }: AppState) => ({\n *   total: items.reduce((sum, item) => sum + item.price, 0),\n *   count: items.length\n * }));\n *\n * // Use with useDerivedState\n * const stats = useDerivedState(model, selectStats);\n * ```\n */\nexport const derived = <I, O>(fn: Mapper<I, O>): DerivedMapper<I, O> => {\n  let lastInput: I | typeof UNINITIALIZED = UNINITIALIZED;\n  let lastOutput: O | typeof UNINITIALIZED = UNINITIALIZED;\n  return ((input: I) => {\n    if (lastInput !== UNINITIALIZED && Object.is(lastInput, input)) {\n      return lastOutput as O;\n    }\n    return (lastOutput = fn((lastInput = input)));\n  }) as DerivedMapper<I, O>;\n};\n"],"names":["useModelState","model","useSyncExternalStore","subscribe","bind","state","useDerivedState","mapper","UNINITIALIZED","derived","fn","lastInput","lastOutput","input","Object","is"],"mappings":"6CAgCM,SAAUA,EAAiBC,GAC/B,OAAOC,EAAqBD,EAAME,UAAUC,KAAKH,GAAQ,IAAMA,EAAMI,MACvE,CCQO,MAAMC,EAAkB,CAC7BL,EACAM,IACGA,EAAOP,EAAcC,ICpCpBO,EAAgB,CAAA,EA2BTC,EAAiBC,IAC5B,IAAIC,EAAsCH,EACtCI,EAAuCJ,EAC3C,OAASK,GACHF,IAAcH,GAAiBM,OAAOC,GAAGJ,EAAWE,GAC/CD,EAEDA,EAAaF,EAAIC,EAAYE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@view-models/react",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "React integration for @view-models/core",
   "type": "module",
   "main": "./dist/index.js",
@@ -54,7 +54,7 @@
     "@rollup/plugin-typescript": "^12.3.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.18",
-    "@view-models/core": "^3.0.0",
+    "@view-models/core": "^4.0.0",
     "@vitest/coverage-v8": "^2.1.8",
     "jsdom": "^26.0.0",
     "prettier": "^3.4.2",

package/src/ViewModel.ts

@@ -0,0 +1,59 @@
+/**
+ * Function that gets called when the state changes.
+ *
+ * @template T - The state type
+ * @param state - The new state
+ */
+export type ViewModelListener = () => void;
+
+/**
+ * Interface for a ViewModel that manages state and notifies subscribers of changes.
+ *
+ * ViewModels provide a way to manage component state outside of the component tree,
+ * allowing multiple components to share and react to the same state. They follow
+ * the observer pattern, where components can subscribe to state changes and receive
+ * notifications when updates occur.
+ *
+ * @template T - The type of state managed by this ViewModel
+ *
+ * @example
+ * ```typescript
+ * // Implementing a ViewModel
+ * class CounterViewModel extends ViewModel<{ count: number }> {
+ *   increment = () => super.update({ count: super.state.count + 1 });
+ *   decrement = () => super.update(({ count: super.state.count - 1  }));
+ * }
+ *
+ * // Using in a component
+ * const counterModel = new CounterViewModel({ count: 0 });
+ * const { count } = useModelState(counterModel);
+ * ```
+ */
+export interface ViewModel<T> {
+  /**
+   * Subscribe to state changes.
+   *
+   * The listener will be called immediately after any state update.
+   *
+   * @param listener - Function to call when state changes
+   * @returns Function to unsubscribe the listener
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = viewModel.subscribe((state) => {
+   *   console.log('State changed:', state);
+   * });
+   *
+   * // Later, when you want to stop listening:
+   * unsubscribe();
+   * ```
+   */
+  subscribe(listener: ViewModelListener): () => void;
+
+  /**
+   * Get the current state.
+   *
+   * @returns The current state
+   */
+  get state(): T;
+}

package/src/derived.ts

@@ -0,0 +1,46 @@
+type Mapper<I, O> = (input: I) => O;
+
+/**
+ * A branded type for derived state mapper functions created by the `derived` utility.
+ * This type ensures that mapper functions are properly memoized before being used
+ * with hooks like `useDerivedState`.
+ */
+export type DerivedMapper<I, O> = Mapper<I, O> & { __brand: "derived" };
+
+const UNINITIALIZED = {};
+
+/**
+ * Creates a memoized derived state mapper function that caches results based on input identity.
+ *
+ * The memoization uses `Object.is` to compare inputs, making it ideal for use with
+ * immutable state objects. When the input reference hasn't changed, the cached output
+ * is returned without re-executing the function.
+ *
+ * This is the required way to create mapper functions for use with `useDerivedState`.
+ *
+ * @template I - The input type
+ * @template O - The output type
+ * @param fn - A pure function that transforms input to output
+ * @returns A memoized derived mapper function
+ *
+ * @example
+ * ```ts
+ * const selectStats = derived(({ items }: AppState) => ({
+ *   total: items.reduce((sum, item) => sum + item.price, 0),
+ *   count: items.length
+ * }));
+ *
+ * // Use with useDerivedState
+ * const stats = useDerivedState(model, selectStats);
+ * ```
+ */
+export const derived = <I, O>(fn: Mapper<I, O>): DerivedMapper<I, O> => {
+  let lastInput: I | typeof UNINITIALIZED = UNINITIALIZED;
+  let lastOutput: O | typeof UNINITIALIZED = UNINITIALIZED;
+  return ((input: I) => {
+    if (lastInput !== UNINITIALIZED && Object.is(lastInput, input)) {
+      return lastOutput as O;
+    }
+    return (lastOutput = fn((lastInput = input)));
+  }) as DerivedMapper<I, O>;
+};

package/src/index.ts

@@ -1 +1,3 @@
 export * from "./useModelState.js";
+export * from "./useDerivedState.js";
+export * from "./derived.js";

package/src/useDerivedState.ts

@@ -0,0 +1,46 @@
+import { useModelState } from "./useModelState";
+import { ViewModel } from "./ViewModel";
+import { DerivedMapper } from "./derived";
+
+/**
+ * A React hook that subscribes to a ViewModel and returns derived state.
+ *
+ * This hook combines `useModelState` with a derived mapper function to compute derived values
+ * from the model's state. The component will re-render whenever the model state changes.
+ *
+ * The mapper must be created using the `derived` utility, which provides memoization
+ * based on state identity to prevent unnecessary recalculations.
+ *
+ * @template S - The model state type
+ * @template D - The derived state type
+ * @param model - The ViewModel instance to subscribe to
+ * @param mapper - A derived mapper function created with the `derived` utility
+ * @returns The derived state computed from the current model state
+ *
+ * @example
+ * ```tsx
+ * import { ViewModel } from "@view-models/core";
+ * import { useDerivedState, derived } from "@view-models/react";
+ *
+ * type TodoState = {
+ *   items: Array<{ id: string; text: string; completed: boolean }>;
+ * };
+ *
+ * const todoModel = new ViewModel<TodoState>({ items: [] });
+ *
+ * // Create a derived mapper function
+ * const selectCompletedCount = derived(({ items }: TodoState) => ({
+ *   completed: items.filter(item => item.completed).length,
+ *   total: items.length
+ * }));
+ *
+ * function TodoStats() {
+ *   const stats = useDerivedState(todoModel, selectCompletedCount);
+ *   return <div>{stats.completed} of {stats.total} completed</div>;
+ * }
+ * ```
+ */
+export const useDerivedState = <S, D>(
+  model: ViewModel<S>,
+  mapper: DerivedMapper<S, D>,
+) => mapper(useModelState(model));

package/src/useModelState.ts

@@ -1,64 +1,5 @@
 import { useSyncExternalStore } from "react";
-
-/**
- * Function that gets called when the state changes.
- *
- * @template T - The state type
- * @param state - The new state
- */
-export type ViewModelListener = () => void;
-
-/**
- * Interface for a ViewModel that manages state and notifies subscribers of changes.
- *
- * ViewModels provide a way to manage component state outside of the component tree,
- * allowing multiple components to share and react to the same state. They follow
- * the observer pattern, where components can subscribe to state changes and receive
- * notifications when updates occur.
- *
- * @template T - The type of state managed by this ViewModel
- *
- * @example
- * ```typescript
- * // Implementing a ViewModel
- * class CounterViewModel extends ViewModel<{ count: number }> {
- *   increment = () => super.update({ count: super.state.count + 1 });
- *   decrement = () => super.update(({ count: super.state.count - 1  }));
- * }
- *
- * // Using in a component
- * const counterModel = new CounterViewModel({ count: 0 });
- * const { count } = useModelState(counterModel);
- * ```
- */
-export interface ViewModel<T> {
-  /**
-   * Subscribe to state changes.
-   *
-   * The listener will be called immediately after any state update.
-   *
-   * @param listener - Function to call when state changes
-   * @returns Function to unsubscribe the listener
-   *
-   * @example
-   * ```typescript
-   * const unsubscribe = viewModel.subscribe((state) => {
-   *   console.log('State changed:', state);
-   * });
-   *
-   * // Later, when you want to stop listening:
-   * unsubscribe();
-   * ```
-   */
-  subscribe(listener: ViewModelListener): () => void;
-
-  /**
-   * Get the current state.
-   *
-   * @returns The current state
-   */
-  get state(): T;
-}
+import { ViewModel } from "./ViewModel";
 
 /**
  * A React hook that subscribes a component to a ViewModel's state updates.