@view-models/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sune Simonsen <sune@we-knowhow.dk>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# @view-models/core
+
+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.
+
+## Why View Models?
+
+- **Framework Agnostic**: Write your logic once, use it with React, Preact, or any other framework
+- **Easy Testing**: Test your view logic without rendering anything to the DOM
+- **Simple API**: Just extend `ViewModel` and you're ready to go
+- **Type Safe**: Built with TypeScript for excellent IDE support
+- **Minimal Boilerplate**: Much lighter than Redux with no reducers, actions, or middleware needed
+- **Natural Organization**: A clear place to put your application logic
+
+## Installation
+
+```bash
+npm install @view-models/core
+```
+
+## Quick Start
+
+Define your state type and extend `ViewModel`:
+
+```typescript
+import { ViewModel } from "@view-models/core";
+
+type CounterState = {
+  count: number;
+};
+
+class CounterViewModel extends ViewModel<CounterState> {
+  constructor() {
+    super({ count: 0 });
+  }
+
+  increment() {
+    this.update(({ count }) => ({
+      count: count + 1,
+    }));
+  }
+
+  decrement() {
+    this.update(({ count }) => ({
+      count: count - 1,
+    }));
+  }
+
+  reset() {
+    this.update(() => ({ count: 0 }));
+  }
+}
+```
+
+Use it in your tests:
+
+```typescript
+import { describe, it, expect } from "vitest";
+
+describe("CounterViewModel", () => {
+  it("increments the counter", () => {
+    const counter = new CounterViewModel();
+
+    counter.increment();
+    expect(counter.state.count).toBe(1);
+
+    counter.increment();
+    expect(counter.state.count).toBe(2);
+  });
+
+  it("notifies subscribers on updates", () => {
+    const counter = new CounterViewModel();
+    const updates = [];
+
+    counter.subscribe((state) => updates.push(state));
+
+    counter.increment();
+    counter.increment();
+
+    expect(updates).toEqual([{ count: 1 }, { count: 2 }]);
+  });
+});
+```
+
+## Framework Integration
+
+The view models are designed to work with framework-specific adapters. Upcoming adapters include:
+
+- **@view-models/react** - React hooks integration
+- **@view-models/preact** - Preact hooks integration
+
+These adapters will allow you to use the same view model with different frameworks:
+
+```typescript
+// Coming soon with @view-models/react
+function Counter({ model }) {
+  const { count } = useModelState(model);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={model.increment}>+</button>
+      <button onClick={model.decrement}>-</button>
+    </div>
+  );
+}
+```
+
+## 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;
+```
+
+## Patterns and Best Practices
+
+### Keep State Immutable
+
+Always return new state objects from your updater functions:
+
+```typescript
+// Good
+this.update(({ count }) => ({
+  ...state,
+  count: count + 1,
+}));
+
+// Bad - mutates existing state
+this.update((state) => {
+  state.count++;
+  return state;
+});
+```
+
+### Use Readonly Types
+
+TypeScript's `Readonly` and `ReadonlyArray` help ensure immutability:
+
+```typescript
+type State = {
+  items: ReadonlyArray<string>;
+  config: Readonly<{ enabled: boolean }>;
+};
+```
+
+### Compose Multiple View Models
+
+You can compose view models for complex UIs:
+
+```typescript
+class AppViewModel {
+  readonly user = new UserViewModel();
+  readonly cart = new CartViewModel();
+  readonly products = new ProductsViewModel();
+}
+```
+
+### Handle Side Effects
+
+Keep your update logic pure, but expose methods for side effects:
+
+```typescript
+class TodosViewModel extends ViewModel<TodosState> {
+  private api: API
+
+  constructor(state: TodosState, api: API) {
+    super(state)
+    this.api = api
+  }
+
+  async loadTodos() {
+    this.update((state) => ({ ...state, loading: true, failed: false }));
+    try {
+      const todos = await this.api.fetchTodos();
+      this.update(() => ({ todos, loading: false }));
+    } catch {
+      this.update((state) => ({ ...state, loading: false: failed: true }));
+    }
+  }
+
+  async addTodo(text: string) {
+    try {
+      const todo = await this.api.createTodo(text);
+      this.update(({ todos }) => ({
+        todos: [...todos, todo],
+      }));
+    } catch {
+      // TODO show error
+    }
+  }
+}
+```
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Sune Simonsen <sune@we-knowhow.dk>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ViewModel.d.ts

@@ -0,0 +1,101 @@
+type State = Readonly<object>;
+/**
+ * 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 extends State> = (currentState: T) => T;
+/**
+ * Function that gets called when the state changes.
+ *
+ * @template T - The state type
+ * @param state - The new state
+ */
+export type ViewModelListener<T> = (state: T) => void;
+/**
+ * Abstract base class for creating reactive view models.
+ *
+ * A ViewModel manages state and notifies subscribers when the state changes.
+ * Extend this class to create your own view models with custom business logic.
+ *
+ * @template T - The state type (must be a readonly object)
+ *
+ * @example
+ * ```typescript
+ * type CounterState = { count: number };
+ *
+ * class CounterViewModel extends ViewModel<CounterState> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *   }
+ *
+ *   increment() {
+ *     this.update(({ count }) => ({ count: count + 1 }));
+ *   }
+ * }
+ *
+ * const counter = new CounterViewModel();
+ * const unsubscribe = counter.subscribe((state) => {
+ *   console.log('Count:', state.count);
+ * });
+ * counter.increment(); // Logs: Count: 1
+ * ```
+ */
+export declare abstract class ViewModel<T extends State> {
+    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<T>): () => void;
+    private _state;
+    /**
+     * Create a new ViewModel with the given initial state.
+     *
+     * @param initialState - The initial state of the view model
+     */
+    constructor(initialState: T);
+    /**
+     * 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<T>): void;
+    /**
+     * Get the current state.
+     *
+     * @returns The current state
+     */
+    get state(): T;
+}
+export {};
+//# sourceMappingURL=ViewModel.d.ts.map

package/dist/ViewModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewModel.d.ts","sourceRoot":"","sources":["../src/ViewModel.ts"],"names":[],"mappings":"AAAA,KAAK,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,SAAS,CAAC,CAAC,SAAS,KAAK;IAC7C,OAAO,CAAC,UAAU,CAAwC;IAE1D;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAOrD,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"}

package/dist/ViewModel.js

@@ -0,0 +1,95 @@
+/**
+ * Abstract base class for creating reactive view models.
+ *
+ * A ViewModel manages state and notifies subscribers when the state changes.
+ * Extend this class to create your own view models with custom business logic.
+ *
+ * @template T - The state type (must be a readonly object)
+ *
+ * @example
+ * ```typescript
+ * type CounterState = { count: number };
+ *
+ * class CounterViewModel extends ViewModel<CounterState> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *   }
+ *
+ *   increment() {
+ *     this.update(({ count }) => ({ count: count + 1 }));
+ *   }
+ * }
+ *
+ * const counter = new CounterViewModel();
+ * const unsubscribe = counter.subscribe((state) => {
+ *   console.log('Count:', state.count);
+ * });
+ * 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);
+        };
+    }
+    /**
+     * 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(this._state);
+        }
+    }
+    /**
+     * Get the current state.
+     *
+     * @returns The current state
+     */
+    get state() {
+        return this._state;
+    }
+}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@view-models/core",
+  "version": "1.0.0",
+  "description": "A lightweight, framework-agnostic library for building reactive view models with TypeScript",
+  "keywords": [
+    "view",
+    "viewmodel",
+    "reactive",
+    "state",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Sune Simonsen",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sunesimonsen/view-models-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sunesimonsen/view-models-core/issues"
+  },
+  "homepage": "https://github.com/sunesimonsen/view-models-core#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "format": "prettier --write \"**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.16",
+    "prettier": "^3.7.4",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/ViewModel.ts

@@ -0,0 +1,122 @@
+type State = Readonly<object>;
+
+/**
+ * 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 extends State> = (currentState: T) => T;
+
+/**
+ * Function that gets called when the state changes.
+ *
+ * @template T - The state type
+ * @param state - The new state
+ */
+export type ViewModelListener<T> = (state: T) => void;
+
+/**
+ * Abstract base class for creating reactive view models.
+ *
+ * A ViewModel manages state and notifies subscribers when the state changes.
+ * Extend this class to create your own view models with custom business logic.
+ *
+ * @template T - The state type (must be a readonly object)
+ *
+ * @example
+ * ```typescript
+ * type CounterState = { count: number };
+ *
+ * class CounterViewModel extends ViewModel<CounterState> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *   }
+ *
+ *   increment() {
+ *     this.update(({ count }) => ({ count: count + 1 }));
+ *   }
+ * }
+ *
+ * const counter = new CounterViewModel();
+ * const unsubscribe = counter.subscribe((state) => {
+ *   console.log('Count:', state.count);
+ * });
+ * counter.increment(); // Logs: Count: 1
+ * ```
+ */
+export abstract class ViewModel<T extends State> {
+  private _listeners: Set<ViewModelListener<T>> = 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<T>): () => void {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+
+  private _state: T;
+
+  /**
+   * Create a new ViewModel with the given initial state.
+   *
+   * @param initialState - The initial state of the view model
+   */
+  constructor(initialState: T) {
+    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<T>) {
+    this._state = updater(this._state);
+
+    for (const listener of this._listeners) {
+      listener(this._state);
+    }
+  }
+
+  /**
+   * Get the current state.
+   *
+   * @returns The current state
+   */
+  get state(): T {
+    return this._state;
+  }
+}

package/src/index.ts

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