@view-models/core 2.0.0 → 2.1.1

package/README.md

@@ -31,10 +31,6 @@ type CounterState = {
 };
 
 class CounterViewModel extends ViewModel<CounterState> {
-  constructor() {
-    super({ count: 0 });
-  }
-
   increment() {
     this.update(({ count }) => ({
       count: count + 1,
@@ -46,10 +42,6 @@ class CounterViewModel extends ViewModel<CounterState> {
       count: count - 1,
     }));
   }
-
-  reset() {
-    this.update(() => ({ count: 0 }));
-  }
 }
 ```
 
@@ -73,7 +65,7 @@ describe("CounterViewModel", () => {
     const counter = new CounterViewModel();
     const updates = [];
 
-    counter.subscribe((state) => updates.push(state));
+    counter.subscribe(() => updates.push(counter.state));
 
     counter.increment();
     counter.increment();
@@ -83,6 +75,65 @@ describe("CounterViewModel", () => {
 });
 ```
 
+## View Models with Derived State
+
+When you need to compute derived values from your state (like counts, filtered lists, or formatted data), use `ViewModelWithDerivedState`:
+
+```typescript
+import { ViewModelWithDerivedState } from "@view-models/core";
+
+type TodoState = {
+  items: Array<{ id: string; text: string; done: boolean }>;
+};
+
+type TodoDerivedState = TodoState & {
+  totalCount: number;
+  completedCount: number;
+  remainingCount: number;
+};
+
+class TodoViewModel extends ViewModelWithDerivedState<
+  TodoState,
+  TodoDerivedState
+> {
+  constructor() {
+    super({ items: [] });
+  }
+
+  computeDerivedState({ items }: TodoState): TodoDerivedState {
+    return {
+      items,
+      totalCount: items.length,
+      completedCount: items.filter((item) => item.done).length,
+      remainingCount: items.filter((item) => !item.done).length,
+    };
+  }
+
+  addTodo(text: string) {
+    this.update(({ items }) => ({
+      items: [...items, { id: crypto.randomUUID(), text, done: false }],
+    }));
+  }
+
+  toggleTodo(id: string) {
+    this.update(({ items }) => ({
+      items: items.map((item) =>
+        item.id === id ? { ...item, done: !item.done } : item,
+      ),
+    }));
+  }
+}
+
+const todos = new TodoViewModel();
+console.log(todos.state.totalCount); // 0
+
+todos.addTodo("Learn ViewModels");
+console.log(todos.state.totalCount); // 1
+console.log(todos.state.remainingCount); // 1
+```
+
+The derived state is automatically recomputed whenever the internal state changes, ensuring your computed properties are always up-to-date.
+
 ## Framework Integration
 
 The view models are designed to work with framework-specific adapters. Upcoming adapters include:
@@ -109,55 +160,7 @@ function Counter({ model }) {
 
 ## API Reference
 
-### `ViewModel<T>`
-
-Abstract base class for creating view models.
-
-#### Constructor
-
-```typescript
-constructor(initialState: T)
-```
-
-Initialize the view model with an initial state.
-
-#### Methods
-
-##### `subscribe(listener: ViewModelListener<T>): void`
-
-Subscribe to state changes. The listener will be called with the new state whenever `update()` is called.
-
-```typescript
-const unsubscribe = viewModel.subscribe((state) => {
-  console.log("State changed:", state);
-});
-```
-
-##### `unsubscribe(listener: ViewModelListener<T>): void`
-
-Unsubscribe a previously subscribed listener.
-
-```typescript
-viewModel.unsubscribe(listener);
-```
-
-##### `update(updater: Updater<T>): void` (protected)
-
-Update the state and notify all subscribers. This method is protected and should only be called from within your view model subclass.
-
-```typescript
-protected update(updater: (currentState: T) => T): void
-```
-
-The updater function receives the current state and should return the new state.
-
-##### `state: T` (getter)
-
-Access the current state.
-
-```typescript
-const currentState = viewModel.state;
-```
+For detailed API documentation, see [docs](./docs).
 
 ## Patterns and Best Practices
 

package/dist/ViewModel.d.ts

@@ -1,19 +1,4 @@
-/**
- * Function that receives the current state and returns the new state.
- * The updater function should be pure and return a new state object.
- *
- * @template T - The state type
- * @param currentState - The current state
- * @returns The new state
- */
-export type Updater<T> = (currentState: T) => T;
-/**
- * Function that gets called when the state changes.
- *
- * @template T - The state type
- * @param state - The new state
- */
-export type ViewModelListener = () => void;
+import { ViewModelWithDerivedState } from "./ViewModelWithDerivedState.js";
 /**
  * Abstract base class for creating reactive view models.
  *
@@ -43,57 +28,13 @@ export type ViewModelListener = () => void;
  * counter.increment(); // Logs: Count: 1
  * ```
  */
-export declare abstract class ViewModel<S> {
-    private _listeners;
-    /**
-     * 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;
-    private _state;
+export declare abstract class ViewModel<S> extends ViewModelWithDerivedState<S, S> {
     /**
      * Create a new ViewModel with the given initial state.
      *
      * @param initialState - The initial state of the view model
      */
     constructor(initialState: S);
-    /**
-     * Update the state and notify all subscribers.
-     *
-     * This method is protected and should only be called from within your view model subclass.
-     * The updater function receives the current state and should return the new state.
-     * Always return a new state object to ensure immutability.
-     *
-     * @param updater - Function that receives current state and returns new state
-     *
-     * @example
-     * ```typescript
-     * this.update((currentState) => ({
-     *   ...currentState,
-     *   count: currentState.count + 1
-     * }));
-     * ```
-     */
-    protected update(updater: Updater<S>): void;
-    /**
-     * Get the current state.
-     *
-     * @returns The current state
-     */
-    get state(): S;
+    computeDerivedState(state: S): S;
 }
 //# sourceMappingURL=ViewModel.d.ts.map

package/dist/ViewModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ViewModel.d.ts","sourceRoot":"","sources":["../src/ViewModel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,SAAS,CAAC,CAAC;IAC/B,OAAO,CAAC,UAAU,CAAqC;IAEvD;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAOlD,OAAO,CAAC,MAAM,CAAI;IAElB;;;;OAIG;gBACS,YAAY,EAAE,CAAC;IAI3B;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAQpC;;;;OAIG;IACH,IAAI,KAAK,IAAI,CAAC,CAEb;CACF"}
+{"version":3,"file":"ViewModel.d.ts","sourceRoot":"","sources":["../src/ViewModel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,SAAS,CAAC,CAAC,CAAE,SAAQ,yBAAyB,CAAC,CAAC,EAAE,CAAC,CAAC;IACxE;;;;OAIG;gBACS,YAAY,EAAE,CAAC;IAI3B,mBAAmB,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC;CAGjC"}

package/dist/ViewModel.js

@@ -1,3 +1,4 @@
+import { ViewModelWithDerivedState } from "./ViewModelWithDerivedState.js";
 /**
  * Abstract base class for creating reactive view models.
  *
@@ -27,69 +28,16 @@
  * counter.increment(); // Logs: Count: 1
  * ```
  */
-export class ViewModel {
-    /**
-     * 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) {
-        this._listeners.add(listener);
-        return () => {
-            this._listeners.delete(listener);
-        };
-    }
+export class ViewModel extends ViewModelWithDerivedState {
     /**
      * Create a new ViewModel with the given initial state.
      *
      * @param initialState - The initial state of the view model
      */
     constructor(initialState) {
-        this._listeners = new Set();
-        this._state = initialState;
-    }
-    /**
-     * Update the state and notify all subscribers.
-     *
-     * This method is protected and should only be called from within your view model subclass.
-     * The updater function receives the current state and should return the new state.
-     * Always return a new state object to ensure immutability.
-     *
-     * @param updater - Function that receives current state and returns new state
-     *
-     * @example
-     * ```typescript
-     * this.update((currentState) => ({
-     *   ...currentState,
-     *   count: currentState.count + 1
-     * }));
-     * ```
-     */
-    update(updater) {
-        this._state = updater(this._state);
-        for (const listener of this._listeners) {
-            listener();
-        }
+        super(initialState);
     }
-    /**
-     * Get the current state.
-     *
-     * @returns The current state
-     */
-    get state() {
-        return this._state;
+    computeDerivedState(state) {
+        return state;
     }
 }

package/dist/ViewModelWithDerivedState.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Function that receives the current state and returns the new state.
+ * The updater function should be pure and return a new state object.
+ *
+ * @template T - The state type
+ * @param currentState - The current state
+ * @returns The new state
+ */
+export type Updater<T> = (currentState: T) => T;
+/**
+ * Function that gets called when the state changes.
+ *
+ * @template T - The state type
+ */
+export type ViewModelListener = () => void;
+/**
+ * Abstract base class for creating reactive view models with derived state.
+ *
+ * This class extends the basic ViewModel pattern by allowing you to compute
+ * derived state from internal state. The internal state is managed privately,
+ * while the derived state (which can include computed properties) is exposed
+ * to subscribers.
+ *
+ * @template S - The internal state type (managed internally)
+ * @template D - The derived state type (exposed to subscribers)
+ *
+ * @example
+ * ```typescript
+ * type TodoState = {
+ *   items: Array<{ id: string; text: string; done: boolean }>;
+ * };
+ *
+ * type TodoDerivedState = TodoState & {
+ *   totalCount: number;
+ *   completedCount: number;
+ *   remainingCount: number;
+ * };
+ *
+ * class TodoViewModel extends ViewModelWithDerivedState<TodoState, TodoDerivedState> {
+ *   constructor() {
+ *     super({ items: [] });
+ *   }
+ *
+ *   computeDerivedState({ items }: TodoState): TodoDerivedState {
+ *     return {
+ *       items,
+ *       totalCount: items.length,
+ *       completedCount: items.filter(item => item.done).length,
+ *       remainingCount: items.filter(item => !item.done).length,
+ *     };
+ *   }
+ *
+ *   addTodo(text: string) {
+ *     this.update(({ items }) => ({
+ *       items: [...items, { id: crypto.randomUUID(), text, done: false }],
+ *     }));
+ *   }
+ * }
+ *
+ * const todos = new TodoViewModel();
+ * todos.subscribe(() => {
+ *   console.log('Completed:', todos.state.completedCount);
+ * });
+ * todos.addTodo('Learn ViewModels'); // Logs: Completed: 0
+ * ```
+ */
+export declare abstract class ViewModelWithDerivedState<S, D> {
+    private _listeners;
+    private _internalState;
+    private _state;
+    /**
+     * 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;
+    /**
+     * Create a new ViewModel with the given initial internal state.
+     *
+     * The constructor initializes the internal state and immediately computes
+     * the derived state by calling `computeDerivedState`.
+     *
+     * @param initialState - The initial internal state of the view model
+     */
+    constructor(initialState: S);
+    /**
+     * Update the internal state, recompute derived state, and notify all subscribers.
+     *
+     * This method is protected and should only be called from within your view model subclass.
+     * The updater function receives the current internal state and should return the new internal state.
+     * After updating, the derived state is automatically recomputed via `computeDerivedState`.
+     * Always return a new state object to ensure immutability.
+     *
+     * @param updater - Function that receives current internal state and returns new internal state
+     *
+     * @example
+     * ```typescript
+     * this.update((currentState) => ({
+     *   ...currentState,
+     *   count: currentState.count + 1
+     * }));
+     * ```
+     */
+    protected update(updater: Updater<S>): void;
+    /**
+     * Compute the derived state from the internal state.
+     *
+     * This abstract method must be implemented by subclasses to transform
+     * the internal state into the derived state that will be exposed to
+     * subscribers. This method is called automatically after each state
+     * update and during initialization.
+     *
+     * @param state - The current internal state
+     * @returns The derived state with any computed properties
+     *
+     * @example
+     * ```typescript
+     * computeDerivedState({ count }: CounterState): CounterDerivedState {
+     *   return {
+     *     count,
+     *     isEven: count % 2 === 0,
+     *     isPositive: count > 0,
+     *   };
+     * }
+     * ```
+     */
+    abstract computeDerivedState(state: S): D;
+    /**
+     * Get the current derived state.
+     *
+     * This returns the derived state computed by `computeDerivedState`,
+     * not the internal state.
+     *
+     * @returns The current derived state
+     */
+    get state(): D;
+}
+//# sourceMappingURL=ViewModelWithDerivedState.d.ts.map

package/dist/ViewModelWithDerivedState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewModelWithDerivedState.d.ts","sourceRoot":"","sources":["../src/ViewModelWithDerivedState.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,8BAAsB,yBAAyB,CAAC,CAAC,EAAE,CAAC;IAClD,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,MAAM,CAAI;IAElB;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAOlD;;;;;;;OAOG;gBACS,YAAY,EAAE,CAAC;IAK3B;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IASpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,mBAAmB,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC;IAEzC;;;;;;;OAOG;IACH,IAAI,KAAK,IAAI,CAAC,CAEb;CACF"}

package/dist/ViewModelWithDerivedState.js

@@ -0,0 +1,126 @@
+/**
+ * Abstract base class for creating reactive view models with derived state.
+ *
+ * This class extends the basic ViewModel pattern by allowing you to compute
+ * derived state from internal state. The internal state is managed privately,
+ * while the derived state (which can include computed properties) is exposed
+ * to subscribers.
+ *
+ * @template S - The internal state type (managed internally)
+ * @template D - The derived state type (exposed to subscribers)
+ *
+ * @example
+ * ```typescript
+ * type TodoState = {
+ *   items: Array<{ id: string; text: string; done: boolean }>;
+ * };
+ *
+ * type TodoDerivedState = TodoState & {
+ *   totalCount: number;
+ *   completedCount: number;
+ *   remainingCount: number;
+ * };
+ *
+ * class TodoViewModel extends ViewModelWithDerivedState<TodoState, TodoDerivedState> {
+ *   constructor() {
+ *     super({ items: [] });
+ *   }
+ *
+ *   computeDerivedState({ items }: TodoState): TodoDerivedState {
+ *     return {
+ *       items,
+ *       totalCount: items.length,
+ *       completedCount: items.filter(item => item.done).length,
+ *       remainingCount: items.filter(item => !item.done).length,
+ *     };
+ *   }
+ *
+ *   addTodo(text: string) {
+ *     this.update(({ items }) => ({
+ *       items: [...items, { id: crypto.randomUUID(), text, done: false }],
+ *     }));
+ *   }
+ * }
+ *
+ * const todos = new TodoViewModel();
+ * todos.subscribe(() => {
+ *   console.log('Completed:', todos.state.completedCount);
+ * });
+ * todos.addTodo('Learn ViewModels'); // Logs: Completed: 0
+ * ```
+ */
+export class ViewModelWithDerivedState {
+    /**
+     * 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) {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    }
+    /**
+     * Create a new ViewModel with the given initial internal state.
+     *
+     * The constructor initializes the internal state and immediately computes
+     * the derived state by calling `computeDerivedState`.
+     *
+     * @param initialState - The initial internal state of the view model
+     */
+    constructor(initialState) {
+        this._listeners = new Set();
+        this._internalState = initialState;
+        this._state = this.computeDerivedState(this._internalState);
+    }
+    /**
+     * Update the internal state, recompute derived state, and notify all subscribers.
+     *
+     * This method is protected and should only be called from within your view model subclass.
+     * The updater function receives the current internal state and should return the new internal state.
+     * After updating, the derived state is automatically recomputed via `computeDerivedState`.
+     * Always return a new state object to ensure immutability.
+     *
+     * @param updater - Function that receives current internal state and returns new internal state
+     *
+     * @example
+     * ```typescript
+     * this.update((currentState) => ({
+     *   ...currentState,
+     *   count: currentState.count + 1
+     * }));
+     * ```
+     */
+    update(updater) {
+        this._internalState = updater(this._internalState);
+        this._state = this.computeDerivedState(this._internalState);
+        for (const listener of this._listeners) {
+            listener();
+        }
+    }
+    /**
+     * Get the current derived state.
+     *
+     * This returns the derived state computed by `computeDerivedState`,
+     * not the internal state.
+     *
+     * @returns The current derived state
+     */
+    get state() {
+        return this._state;
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./ViewModel.js";
+export * from "./ViewModelWithDerivedState.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gCAAgC,CAAC"}

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@view-models/core",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "A lightweight, framework-agnostic library for building reactive view models with TypeScript",
   "keywords": [
     "view",
@@ -43,11 +43,14 @@
     "test:coverage": "vitest run --coverage",
     "format": "prettier --write \"**/*.{ts,js,json,md}\"",
     "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
+    "docs": "typedoc && npm run format",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.16",
     "prettier": "^3.7.4",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.7.3",
     "vitest": "^4.0.16"
   },

package/src/ViewModel.ts

@@ -1,20 +1,4 @@
-/**
- * Function that receives the current state and returns the new state.
- * The updater function should be pure and return a new state object.
- *
- * @template T - The state type
- * @param currentState - The current state
- * @returns The new state
- */
-export type Updater<T> = (currentState: T) => T;
-
-/**
- * Function that gets called when the state changes.
- *
- * @template T - The state type
- * @param state - The new state
- */
-export type ViewModelListener = () => void;
+import { ViewModelWithDerivedState } from "./ViewModelWithDerivedState.js";
 
 /**
  * Abstract base class for creating reactive view models.
@@ -45,76 +29,17 @@ export type ViewModelListener = () => void;
  * counter.increment(); // Logs: Count: 1
  * ```
  */
-export abstract class ViewModel<S> {
-  private _listeners: Set<ViewModelListener> = new Set();
-
-  /**
-   * 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 {
-    this._listeners.add(listener);
-    return () => {
-      this._listeners.delete(listener);
-    };
-  }
-
-  private _state: S;
-
+export abstract class ViewModel<S> extends ViewModelWithDerivedState<S, S> {
   /**
    * Create a new ViewModel with the given initial state.
    *
    * @param initialState - The initial state of the view model
    */
   constructor(initialState: S) {
-    this._state = initialState;
-  }
-
-  /**
-   * Update the state and notify all subscribers.
-   *
-   * This method is protected and should only be called from within your view model subclass.
-   * The updater function receives the current state and should return the new state.
-   * Always return a new state object to ensure immutability.
-   *
-   * @param updater - Function that receives current state and returns new state
-   *
-   * @example
-   * ```typescript
-   * this.update((currentState) => ({
-   *   ...currentState,
-   *   count: currentState.count + 1
-   * }));
-   * ```
-   */
-  protected update(updater: Updater<S>) {
-    this._state = updater(this._state);
-
-    for (const listener of this._listeners) {
-      listener();
-    }
+    super(initialState);
   }
 
-  /**
-   * Get the current state.
-   *
-   * @returns The current state
-   */
-  get state(): S {
-    return this._state;
+  computeDerivedState(state: S): S {
+    return state;
   }
 }

package/src/ViewModelWithDerivedState.ts

@@ -0,0 +1,174 @@
+/**
+ * Function that receives the current state and returns the new state.
+ * The updater function should be pure and return a new state object.
+ *
+ * @template T - The state type
+ * @param currentState - The current state
+ * @returns The new state
+ */
+export type Updater<T> = (currentState: T) => T;
+
+/**
+ * Function that gets called when the state changes.
+ *
+ * @template T - The state type
+ */
+export type ViewModelListener = () => void;
+
+/**
+ * Abstract base class for creating reactive view models with derived state.
+ *
+ * This class extends the basic ViewModel pattern by allowing you to compute
+ * derived state from internal state. The internal state is managed privately,
+ * while the derived state (which can include computed properties) is exposed
+ * to subscribers.
+ *
+ * @template S - The internal state type (managed internally)
+ * @template D - The derived state type (exposed to subscribers)
+ *
+ * @example
+ * ```typescript
+ * type TodoState = {
+ *   items: Array<{ id: string; text: string; done: boolean }>;
+ * };
+ *
+ * type TodoDerivedState = TodoState & {
+ *   totalCount: number;
+ *   completedCount: number;
+ *   remainingCount: number;
+ * };
+ *
+ * class TodoViewModel extends ViewModelWithDerivedState<TodoState, TodoDerivedState> {
+ *   constructor() {
+ *     super({ items: [] });
+ *   }
+ *
+ *   computeDerivedState({ items }: TodoState): TodoDerivedState {
+ *     return {
+ *       items,
+ *       totalCount: items.length,
+ *       completedCount: items.filter(item => item.done).length,
+ *       remainingCount: items.filter(item => !item.done).length,
+ *     };
+ *   }
+ *
+ *   addTodo(text: string) {
+ *     this.update(({ items }) => ({
+ *       items: [...items, { id: crypto.randomUUID(), text, done: false }],
+ *     }));
+ *   }
+ * }
+ *
+ * const todos = new TodoViewModel();
+ * todos.subscribe(() => {
+ *   console.log('Completed:', todos.state.completedCount);
+ * });
+ * todos.addTodo('Learn ViewModels'); // Logs: Completed: 0
+ * ```
+ */
+export abstract class ViewModelWithDerivedState<S, D> {
+  private _listeners: Set<ViewModelListener> = new Set();
+  private _internalState: S;
+  private _state: D;
+
+  /**
+   * 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 {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Create a new ViewModel with the given initial internal state.
+   *
+   * The constructor initializes the internal state and immediately computes
+   * the derived state by calling `computeDerivedState`.
+   *
+   * @param initialState - The initial internal state of the view model
+   */
+  constructor(initialState: S) {
+    this._internalState = initialState;
+    this._state = this.computeDerivedState(this._internalState);
+  }
+
+  /**
+   * Update the internal state, recompute derived state, and notify all subscribers.
+   *
+   * This method is protected and should only be called from within your view model subclass.
+   * The updater function receives the current internal state and should return the new internal state.
+   * After updating, the derived state is automatically recomputed via `computeDerivedState`.
+   * Always return a new state object to ensure immutability.
+   *
+   * @param updater - Function that receives current internal state and returns new internal state
+   *
+   * @example
+   * ```typescript
+   * this.update((currentState) => ({
+   *   ...currentState,
+   *   count: currentState.count + 1
+   * }));
+   * ```
+   */
+  protected update(updater: Updater<S>) {
+    this._internalState = updater(this._internalState);
+    this._state = this.computeDerivedState(this._internalState);
+
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+
+  /**
+   * Compute the derived state from the internal state.
+   *
+   * This abstract method must be implemented by subclasses to transform
+   * the internal state into the derived state that will be exposed to
+   * subscribers. This method is called automatically after each state
+   * update and during initialization.
+   *
+   * @param state - The current internal state
+   * @returns The derived state with any computed properties
+   *
+   * @example
+   * ```typescript
+   * computeDerivedState({ count }: CounterState): CounterDerivedState {
+   *   return {
+   *     count,
+   *     isEven: count % 2 === 0,
+   *     isPositive: count > 0,
+   *   };
+   * }
+   * ```
+   */
+  abstract computeDerivedState(state: S): D;
+
+  /**
+   * Get the current derived state.
+   *
+   * This returns the derived state computed by `computeDerivedState`,
+   * not the internal state.
+   *
+   * @returns The current derived state
+   */
+  get state(): D {
+    return this._state;
+  }
+}

package/src/index.ts

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