@view-models/core 4.1.0 → 6.0.0

package/README.md

@@ -3,7 +3,9 @@
 [![CI](https://github.com/sunesimonsen/view-models-core/actions/workflows/ci.yml/badge.svg)](https://github.com/sunesimonsen/view-models-core/actions/workflows/ci.yml)
 [![Bundle Size](https://img.badgesize.io/https://unpkg.com/@view-models/core@latest/dist/index.js?label=gzip&compression=gzip)](https://unpkg.com/@view-models/core@latest/dist/index.js)
 
-A lightweight, framework-agnostic library for building reactive view models with TypeScript. Separate your business logic from your UI framework with a simple, testable pattern.
+A lightweight, framework-agnostic library for building reactive view models with
+TypeScript. Separate your business logic from your UI framework with a simple,
+testable pattern.
 
 ![View models banner](./view-models.png)
 
@@ -38,17 +40,17 @@ class CounterViewModel extends ViewModel<CounterState> {
     super({ count: 0 });
   }
 
-  increment() {
+  increment = () => {
     super.update({
       count: super.state.count + 1,
     });
-  }
+  };
 
-  decrement() {
+  decrement = () => {
     super.update({
       count: super.state.count - 1,
     });
-  }
+  };
 }
 ```
 
@@ -84,7 +86,8 @@ describe("CounterViewModel", () => {
 
 ## Framework Integration
 
-The view models are designed to work with framework-specific adapters. Upcoming adapters include:
+The view models are designed to work with framework-specific adapters. Upcoming
+adapters include:
 
 - [@view-models/react](https://github.com/sunesimonsen/view-models-react) - React hooks integration
 - [@view-models/preact](https://github.com/sunesimonsen/view-models-preact) - Preact hooks integration
@@ -106,60 +109,6 @@ function Counter({ model }) {
 }
 ```
 
-## Derived State
-
-The `derived` utility creates memoized mapper functions for computing derived state from your view model. This is useful when you need to transform or aggregate state values without recomputing on every render.
-
-The `derived` function uses `Object.is` to compare inputs. When the input reference hasn't changed (which is guaranteed when using immutable updates), the cached output is returned without re-executing the mapper function.
-
-```typescript
-import { ViewModel, derived } from "@view-models/core";
-
-type CartState = {
-  items: Array<{ id: string; price: number; quantity: number }>;
-};
-
-class CartViewModel extends ViewModel<CartState> {
-  constructor() {
-    super({ items: [] });
-  }
-
-  addItem(item: { id: string; price: number; quantity: number }) {
-    super.update({
-      items: [...super.state.items, item],
-    });
-  }
-}
-
-// Create a derived mapper that computes cart statistics
-const selectCartStats = derived((state: CartState) => ({
-  total: state.items.reduce((sum, item) => sum + item.price * item.quantity, 0),
-  itemCount: state.items.reduce((sum, item) => sum + item.quantity, 0),
-}));
-
-// Use it to compute derived state
-const cart = new CartViewModel();
-cart.addItem({ id: "1", price: 10, quantity: 2 });
-cart.addItem({ id: "2", price: 15, quantity: 1 });
-const stats = selectCartStats(cart.state); // { total: 35, itemCount: 3 }
-```
-
-Derived mappers are particularly useful with framework hooks like `useDerivedState` (from [@view-models/react](https://github.com/sunesimonsen/view-models-react)):
-
-```typescript
-function CartSummary({ cart }) {
-  // Only recomputes when cart.state reference changes
-  const stats = useDerivedState(cart, selectCartStats);
-
-  return (
-    <div>
-      <p>Items: {stats.itemCount}</p>
-      <p>Total: ${stats.total}</p>
-    </div>
-  );
-}
-```
-
 ## API Reference
 
 For detailed API documentation, see [docs](./docs).
@@ -242,6 +191,58 @@ class TodosViewModel extends ViewModel<TodosState> {
 }
 ```
 
+### Derived State
+
+When you have state values that are derived from other state, create a dedicated
+update method that computes these values. This approach is more explicit and
+efficient than intercepting every state update:
+
+```typescript
+type TodoState = {
+  todos: ReadonlyArray<{ id: number; text: string; completed: boolean }>;
+  completedCount: number;
+  pendingCount: number;
+};
+
+class TodoViewModel extends ViewModel<TodoState> {
+  private nextId = 1;
+
+  constructor() {
+    super({ todos: [], completedCount: 0, pendingCount: 0 });
+  }
+
+  add(text: string) {
+    const todos = [
+      ...super.state.todos,
+      { id: this.nextId++, text, completed: false },
+    ];
+    this.updateTodos(todos);
+  }
+
+  toggle(id: number) {
+    const todos = super.state.todos.map((todo) =>
+      todo.id === id ? { ...todo, completed: !todo.completed } : todo,
+    );
+    this.updateTodos(todos);
+  }
+
+  private updateTodos(todos: TodoState["todos"]) {
+    super.update({
+      todos,
+      completedCount: todos.filter((t) => t.completed).length,
+      pendingCount: todos.filter((t) => !t.completed).length,
+    });
+  }
+}
+
+const todoModel = new TodoViewModel();
+todoModel.add("Buy milk");
+todoModel.add("Walk the dog");
+todoModel.toggle(1);
+console.log(todoModel.state.completedCount); // 1
+console.log(todoModel.state.pendingCount); // 1
+```
+
 ## License
 
 MIT License

package/dist/index.d.ts

@@ -1,37 +1,3 @@
-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.
- *
- * @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 = selectStats(model.state);
- * ```
- */
-declare const derived: <I, O>(fn: Mapper<I, O>) => DerivedMapper<I, O>;
-
 /**
  * Function that gets called when the state changes.
  */
@@ -99,7 +65,7 @@ declare abstract class ViewModel<S extends object> {
      * This method is protected and should only be called from within your view model subclass.
      * The partial state is merged with the current state to create the new state.
      *
-     * @param partial - Partial state to merge with the current state
+     * @param update - Partial state to merge with the current state
      *
      * @example
      * ```typescript
@@ -108,7 +74,7 @@ declare abstract class ViewModel<S extends object> {
      * });
      * ```
      */
-    protected update(partial: Partial<S>): void;
+    protected update(update: Partial<S>): void;
     /**
      * Get the current state.
      *
@@ -117,5 +83,5 @@ declare abstract class ViewModel<S extends object> {
     get state(): S;
 }
 
-export { ViewModel, derived };
-export type { DerivedMapper, ViewModelListener };
+export { ViewModel };
+export type { ViewModelListener };

package/dist/index.js

@@ -1,2 +1,2 @@
-const t={},s=s=>{let e=t,r=t;return i=>e!==t&&Object.is(e,i)?r:r=s(e=i)};class e{subscribe(t){return this.t.add(t),()=>{this.t.delete(t)}}constructor(t){this.t=new Set,this.i=t}update(t){this.i={...this.i,...t},this.t.forEach(t=>t())}get state(){return this.i}}export{e as ViewModel,s as derived};
+class t{subscribe(t){return this.t.add(t),()=>{this.t.delete(t)}}constructor(t){this.t=new Set,this.i=t}update(t){this.i={...this.i,...t},this.t.forEach(t=>t())}get state(){return this.i}}export{t as ViewModel};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/derived.ts","../src/ViewModel.ts"],"sourcesContent":["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 * @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 = selectStats(model.state);\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","/**\n * Function that gets called when the state changes.\n */\nexport type ViewModelListener = () => void;\n\n/**\n * Abstract base class for creating reactive view models.\n *\n * A ViewModel manages state and notifies subscribers when the state changes.\n * Extend this class to create your own view models with custom business logic.\n *\n * @template S - The state type\n *\n * @example\n * ```typescript\n * type CounterState = { count: number };\n *\n * class CounterViewModel extends ViewModel<CounterState> {\n *   constructor() {\n *     super({ count: 0 });\n *   }\n *\n *   increment() {\n *     super.update({ count: super.state.count + 1 });\n *   }\n * }\n *\n * const counter = new CounterViewModel();\n * const unsubscribe = counter.subscribe(() => {\n *   console.log('Count:', counter.state.count);\n * });\n * counter.increment(); // Logs: Count: 1\n * ```\n */\nexport abstract class ViewModel<S extends object> {\n  private _listeners = new Set<ViewModelListener>();\n  private _state: S;\n\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(() => {\n   *   console.log('State changed:', viewModel.state);\n   * });\n   *\n   * // Later, when you want to stop listening:\n   * unsubscribe();\n   * ```\n   */\n  subscribe(listener: ViewModelListener): () => void {\n    this._listeners.add(listener);\n    return () => {\n      this._listeners.delete(listener);\n    };\n  }\n\n  /**\n   * Create a new ViewModel with the given initial state.\n   *\n   * @param initialState - The initial state of the view model\n   */\n  constructor(initialState: S) {\n    this._state = initialState;\n  }\n\n  /**\n   * Update the state and notify all subscribers.\n   *\n   * This method is protected and should only be called from within your view model subclass.\n   * The partial state is merged with the current state to create the new state.\n   *\n   * @param partial - Partial state to merge with the current state\n   *\n   * @example\n   * ```typescript\n   * super.update({\n   *   count: super.state.count + 1\n   * });\n   * ```\n   */\n  protected update(partial: Partial<S>) {\n    this._state = { ...this._state, ...partial };\n    this._listeners.forEach((l) => l());\n  }\n\n  /**\n   * Get the current state.\n   *\n   * @returns The current state\n   */\n  get state(): S {\n    return this._state;\n  }\n}\n"],"names":["UNINITIALIZED","derived","fn","lastInput","lastOutput","input","Object","is","ViewModel","subscribe","listener","this","_listeners","add","delete","constructor","initialState","Set","_state","update","partial","forEach","l","state"],"mappings":"AASA,MAAMA,EAAgB,CAAA,EAyBTC,EAAiBC,IAC5B,IAAIC,EAAsCH,EACtCI,EAAuCJ,EAC3C,OAASK,GACHF,IAAcH,GAAiBM,OAAOC,GAAGJ,EAAWE,GAC/CD,EAEDA,EAAaF,EAAIC,EAAYE,UCPnBG,EAsBpB,SAAAC,CAAUC,GAER,OADAC,KAAKC,EAAWC,IAAIH,GACb,KACLC,KAAKC,EAAWE,OAAOJ,GAE3B,CAOA,WAAAK,CAAYC,GAjCJL,KAAAC,EAAa,IAAIK,IAkCvBN,KAAKO,EAASF,CAChB,CAiBU,MAAAG,CAAOC,GACfT,KAAKO,EAAS,IAAKP,KAAKO,KAAWE,GACnCT,KAAKC,EAAWS,QAASC,GAAMA,IACjC,CAOA,SAAIC,GACF,OAAOZ,KAAKO,CACd"}
+{"version":3,"file":"index.js","sources":["../src/ViewModel.ts"],"sourcesContent":["/**\n * Function that gets called when the state changes.\n */\nexport type ViewModelListener = () => void;\n\n/**\n * Abstract base class for creating reactive view models.\n *\n * A ViewModel manages state and notifies subscribers when the state changes.\n * Extend this class to create your own view models with custom business logic.\n *\n * @template S - The state type\n *\n * @example\n * ```typescript\n * type CounterState = { count: number };\n *\n * class CounterViewModel extends ViewModel<CounterState> {\n *   constructor() {\n *     super({ count: 0 });\n *   }\n *\n *   increment() {\n *     super.update({ count: super.state.count + 1 });\n *   }\n * }\n *\n * const counter = new CounterViewModel();\n * const unsubscribe = counter.subscribe(() => {\n *   console.log('Count:', counter.state.count);\n * });\n * counter.increment(); // Logs: Count: 1\n * ```\n */\nexport abstract class ViewModel<S extends object> {\n  private _listeners = new Set<ViewModelListener>();\n  private _state: S;\n\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(() => {\n   *   console.log('State changed:', viewModel.state);\n   * });\n   *\n   * // Later, when you want to stop listening:\n   * unsubscribe();\n   * ```\n   */\n  subscribe(listener: ViewModelListener): () => void {\n    this._listeners.add(listener);\n    return () => {\n      this._listeners.delete(listener);\n    };\n  }\n\n  /**\n   * Create a new ViewModel with the given initial state.\n   *\n   * @param initialState - The initial state of the view model\n   */\n  constructor(initialState: S) {\n    this._state = initialState;\n  }\n\n  /**\n   * Update the state and notify all subscribers.\n   *\n   * This method is protected and should only be called from within your view model subclass.\n   * The partial state is merged with the current state to create the new state.\n   *\n   * @param update - Partial state to merge with the current state\n   *\n   * @example\n   * ```typescript\n   * super.update({\n   *   count: super.state.count + 1\n   * });\n   * ```\n   */\n  protected update(update: Partial<S>) {\n    this._state = { ...this._state, ...update };\n    this._listeners.forEach((l) => l());\n  }\n\n  /**\n   * Get the current state.\n   *\n   * @returns The current state\n   */\n  get state(): S {\n    return this._state;\n  }\n}\n"],"names":["ViewModel","subscribe","listener","this","_listeners","add","delete","constructor","initialState","Set","_state","update","forEach","l","state"],"mappings":"MAkCsBA,EAsBpB,SAAAC,CAAUC,GAER,OADAC,KAAKC,EAAWC,IAAIH,GACb,KACLC,KAAKC,EAAWE,OAAOJ,GAE3B,CAOA,WAAAK,CAAYC,GAjCJL,KAAAC,EAAa,IAAIK,IAkCvBN,KAAKO,EAASF,CAChB,CAiBU,MAAAG,CAAOA,GACfR,KAAKO,EAAS,IAAKP,KAAKO,KAAWC,GACnCR,KAAKC,EAAWQ,QAASC,GAAMA,IACjC,CAOA,SAAIC,GACF,OAAOX,KAAKO,CACd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@view-models/core",
-  "version": "4.1.0",
+  "version": "6.0.0",
   "description": "A lightweight, framework-agnostic library for building reactive view models with TypeScript",
   "keywords": [
     "view",

package/src/ViewModel.ts

@@ -76,7 +76,7 @@ export abstract class ViewModel<S extends object> {
    * This method is protected and should only be called from within your view model subclass.
    * The partial state is merged with the current state to create the new state.
    *
-   * @param partial - Partial state to merge with the current state
+   * @param update - Partial state to merge with the current state
    *
    * @example
    * ```typescript
@@ -85,8 +85,8 @@ export abstract class ViewModel<S extends object> {
    * });
    * ```
    */
-  protected update(partial: Partial<S>) {
-    this._state = { ...this._state, ...partial };
+  protected update(update: Partial<S>) {
+    this._state = { ...this._state, ...update };
     this._listeners.forEach((l) => l());
   }
 

package/src/index.ts

@@ -1,2 +1 @@
-export * from "./derived.js";
 export * from "./ViewModel.js";

package/src/derived.ts

@@ -1,44 +0,0 @@
-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.
- *
- * @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 = selectStats(model.state);
- * ```
- */
-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>;
-};