svstate 1.0.1 → 1.2.0

package/README.md

@@ -73,6 +73,7 @@ const customer = $state({
 - ⚡ **Fires effects** when any property changes (with full context)
 - ⏪ **Snapshots & undo** for complex editing workflows
 - 🎯 **Tracks dirty state** automatically
+- 🔧 **Supports methods** on state objects for computed values and formatting
 
 ```typescript
 import { createSvState, stringValidator, numberValidator } from 'svstate';
@@ -104,6 +105,8 @@ npm install svstate
 
 **Requirements:** Node.js ≥20, Svelte 5
 
+**Note:** This package is distributed as ESM (ES Modules) only.
+
 ---
 
 ## 🎯 Core Features
@@ -332,6 +335,70 @@ const { data } = createSvState(formData, actuators, {
 
 ---
 
+### 6️⃣ State Objects with Methods
+
+State objects can include methods that operate on `this`. Methods are preserved through snapshots and undo operations, making it easy to encapsulate computed values and formatting logic:
+
+```typescript
+import { createSvState, numberValidator } from 'svstate';
+
+// Define state with methods
+type InvoiceData = {
+  unitPrice: number;
+  quantity: number;
+  subtotal: number;
+  tax: number;
+  total: number;
+  calculateTotals: (taxRate?: number) => void;
+  formatCurrency: (value: number) => string;
+};
+
+const createInvoice = (): InvoiceData => ({
+  unitPrice: 0,
+  quantity: 1,
+  subtotal: 0,
+  tax: 0,
+  total: 0,
+  calculateTotals(taxRate = 0.08) {
+    this.subtotal = this.unitPrice * this.quantity;
+    this.tax = this.subtotal * taxRate;
+    this.total = this.subtotal + this.tax;
+  },
+  formatCurrency(value: number) {
+    return `$${value.toFixed(2)}`;
+  }
+});
+
+const {
+  data,
+  state: { errors }
+} = createSvState(createInvoice(), {
+  validator: (source) => ({
+    unitPrice: numberValidator(source.unitPrice).required().positive().getError(),
+    quantity: numberValidator(source.quantity).required().integer().min(1).getError()
+  }),
+  effect: ({ property }) => {
+    // Call method directly on state when inputs change
+    if (property === 'unitPrice' || property === 'quantity') {
+      data.calculateTotals();
+    }
+  }
+});
+
+// In template: use methods for formatting
+// {data.formatCurrency(data.subtotal)} → "$99.00"
+// {data.formatCurrency(data.total)} → "$106.92"
+```
+
+**Key features:**
+
+- 🔧 Methods can modify `this` properties (triggers validation/effects)
+- 📸 Methods preserved through `rollback()` and `reset()`
+- 🎯 Call methods from effects to compute derived values
+- 📐 Encapsulate formatting and business logic in state object
+
+---
+
 ## 🏗️ Complete Examples
 
 ### Example 1: ERP Customer Form with Nested Addresses
@@ -696,7 +763,7 @@ Creates a supercharged state object.
 **Returns:**
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `T` | Deep reactive proxy — bind directly |
+| `data` | `T` | Deep reactive proxy — bind directly, methods preserved |
 | `execute(params?)` | `(P?) => Promise<void>` | Run the configured action |
 | `rollback(steps?)` | `(n?: number) => void` | Undo N changes (default: 1) |
 | `reset()` | `() => void` | Return to initial state |
@@ -784,6 +851,7 @@ const { data, state } = createSvState<UserData, UserErrors, object>(
 | Undo/Redo              | ❌ DIY             | ✅ Built-in     |
 | Dirty tracking         | ❌ DIY             | ✅ Automatic    |
 | Action loading states  | ❌ DIY             | ✅ Built-in     |
+| State with methods     | ⚠️ Manual cloning  | ✅ Automatic    |
 
 **svstate is for:**
 
@@ -798,6 +866,7 @@ const { data, state } = createSvState<UserData, UserErrors, object>(
 ## 📚 Resources
 
 - 🎮 [Live Demo](https://bcsabaengine.github.io/svstate/) — Try it in your browser
+- 🛠️ [SvelteKit Example](https://github.com/BCsabaEngine/svstate-kit) — Example SvelteKit application using svstate
 - 📖 [Documentation](https://github.com/BCsabaEngine/svstate)
 - 🐛 [Report Issues](https://github.com/BCsabaEngine/svstate/issues)
 - 💬 [Discussions](https://github.com/BCsabaEngine/svstate/discussions)

package/dist/index.js

@@ -1,10 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.stringValidator = exports.numberValidator = exports.dateValidator = exports.arrayValidator = exports.createSvState = void 0;
-var state_svelte_1 = require("./state.svelte");
-Object.defineProperty(exports, "createSvState", { enumerable: true, get: function () { return state_svelte_1.createSvState; } });
-var validators_1 = require("./validators");
-Object.defineProperty(exports, "arrayValidator", { enumerable: true, get: function () { return validators_1.arrayValidator; } });
-Object.defineProperty(exports, "dateValidator", { enumerable: true, get: function () { return validators_1.dateValidator; } });
-Object.defineProperty(exports, "numberValidator", { enumerable: true, get: function () { return validators_1.numberValidator; } });
-Object.defineProperty(exports, "stringValidator", { enumerable: true, get: function () { return validators_1.stringValidator; } });
+export { createSvState } from './state.svelte';
+export { arrayValidator, dateValidator, numberValidator, stringValidator } from './validators';

package/dist/proxy.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChangeProxy = void 0;
 const isProxiable = (value) => typeof value === 'object' &&
     value !== null &&
     !(value instanceof Date) &&
@@ -11,7 +8,7 @@ const isProxiable = (value) => typeof value === 'object' &&
     !(value instanceof RegExp) &&
     !(value instanceof Error) &&
     !(value instanceof Promise);
-const ChangeProxy = (source, changed) => {
+export const ChangeProxy = (source, changed) => {
     const createProxy = (target, parentPath) => new Proxy(target, {
         get(object, property) {
             const value = object[property];
@@ -36,4 +33,3 @@ const ChangeProxy = (source, changed) => {
     const data = createProxy(source, '');
     return data;
 };
-exports.ChangeProxy = ChangeProxy;

package/dist/state.svelte.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSvState = createSvState;
-const store_1 = require("svelte/store");
-const proxy_1 = require("./proxy");
+import { derived, get, writable } from 'svelte/store';
+import { ChangeProxy } from './proxy';
 const checkHasErrors = (validator) => Object.values(validator).some((item) => (typeof item === 'string' ? !!item : checkHasErrors(item)));
 const hasAnyErrors = ($errors) => !!$errors && checkHasErrors($errors);
 const deepClone = (object) => {
@@ -12,7 +9,7 @@ const deepClone = (object) => {
         return new Date(object);
     if (Array.isArray(object))
         return object.map((item) => deepClone(item));
-    const cloned = {};
+    const cloned = Object.create(Object.getPrototypeOf(object));
     for (const key of Object.keys(object))
         cloned[key] = deepClone(object[key]);
     return cloned;
@@ -23,18 +20,18 @@ const defaultOptions = {
     allowConcurrentActions: false,
     persistActionError: false
 };
-function createSvState(init, actuators, options) {
+export function createSvState(init, actuators, options) {
     const usedOptions = { ...defaultOptions, ...options };
     const { validator, effect } = actuators ?? {};
-    const errors = (0, store_1.writable)();
-    const hasErrors = (0, store_1.derived)(errors, hasAnyErrors);
-    const isDirty = (0, store_1.writable)(false);
-    const actionInProgress = (0, store_1.writable)(false);
-    const actionError = (0, store_1.writable)();
-    const snapshots = (0, store_1.writable)([{ title: 'Initial', data: deepClone(init) }]);
+    const errors = writable();
+    const hasErrors = derived(errors, hasAnyErrors);
+    const isDirty = writable(false);
+    const actionInProgress = writable(false);
+    const actionError = writable();
+    const snapshots = writable([{ title: 'Initial', data: deepClone(init) }]);
     const stateObject = $state(init);
     const createSnapshot = (title, replace = true) => {
-        const currentSnapshots = (0, store_1.get)(snapshots);
+        const currentSnapshots = get(snapshots);
         const createdSnapshot = { title, data: deepClone(stateObject) };
         const lastSnapshot = currentSnapshots.at(-1);
         if (replace && lastSnapshot && lastSnapshot.title === title)
@@ -63,7 +60,7 @@ function createSvState(init, actuators, options) {
             });
         }
     };
-    const data = (0, proxy_1.ChangeProxy)(stateObject, (target, property, currentValue, oldValue) => {
+    const data = ChangeProxy(stateObject, (target, property, currentValue, oldValue) => {
         if (!usedOptions.persistActionError)
             actionError.set(undefined);
         isDirty.set(true);
@@ -75,7 +72,7 @@ function createSvState(init, actuators, options) {
     if (validator)
         errors.set(validator(data));
     const execute = async (parameters) => {
-        if (!usedOptions.allowConcurrentActions && (0, store_1.get)(actionInProgress))
+        if (!usedOptions.allowConcurrentActions && get(actionInProgress))
             return;
         actionError.set(undefined);
         actionInProgress.set(true);
@@ -95,7 +92,7 @@ function createSvState(init, actuators, options) {
         }
     };
     const rollback = (steps = 1) => {
-        const currentSnapshots = (0, store_1.get)(snapshots);
+        const currentSnapshots = get(snapshots);
         if (currentSnapshots.length <= 1)
             return;
         const targetIndex = Math.max(0, currentSnapshots.length - 1 - steps);
@@ -108,7 +105,7 @@ function createSvState(init, actuators, options) {
             errors.set(validator(data));
     };
     const reset = () => {
-        const currentSnapshots = (0, store_1.get)(snapshots);
+        const currentSnapshots = get(snapshots);
         const initialSnapshot = currentSnapshots[0];
         if (!initialSnapshot)
             return;

package/dist/validators.js

@@ -1,16 +1,10 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.stringValidator = stringValidator;
-exports.numberValidator = numberValidator;
-exports.arrayValidator = arrayValidator;
-exports.dateValidator = dateValidator;
 const prepareOps = {
     trim: (s) => s.trim(),
     normalize: (s) => s.replaceAll(/\s{2,}/g, ' '),
     upper: (s) => s.toUpperCase(),
     lower: (s) => s.toLowerCase()
 };
-function stringValidator(input, ...prepares) {
+export function stringValidator(input, ...prepares) {
     let error = '';
     const setError = (message) => {
         if (!error)
@@ -113,7 +107,7 @@ function stringValidator(input, ...prepares) {
     };
     return builder;
 }
-function numberValidator(input) {
+export function numberValidator(input) {
     let error = '';
     const setError = (message) => {
         if (!error)
@@ -185,7 +179,7 @@ function numberValidator(input) {
     };
     return builder;
 }
-function arrayValidator(input) {
+export function arrayValidator(input) {
     let error = '';
     const setError = (message) => {
         if (!error)
@@ -227,7 +221,7 @@ function arrayValidator(input) {
     };
     return builder;
 }
-function dateValidator(input) {
+export function dateValidator(input) {
     let error = '';
     const setError = (message) => {
         if (!error)

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "svstate",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Supercharged $state() for Svelte 5: deep reactive proxy with validation, cross-field rules, computed & side-effects",
   "author": "BCsabaEngine",
   "license": "ISC",
+  "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "import": "./dist/index.js"
     }
   },
   "engines": {
@@ -53,21 +54,21 @@
   ],
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
-    "@types/node": "^25.0.9",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
-    "@vitest/coverage-v8": "^4.0.17",
+    "@types/node": "^25.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-unicorn": "^62.0.0",
     "nodemon": "^3.1.11",
-    "prettier": "^3.8.0",
-    "svelte": "^5.46.4",
+    "prettier": "^3.8.1",
+    "svelte": "^5.48.5",
     "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"