svstate 1.1.0 → 1.3.0

package/README.md

@@ -70,9 +70,11 @@ const customer = $state({
 
 - 🔍 **Detects changes** at any nesting level (`customer.billing.bankAccount.iban`)
 - ✅ **Validates** with a structure that mirrors your data
+- 🌐 **Async validation** for server-side checks (username availability, email verification)
 - ⚡ **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 +106,8 @@ npm install svstate
 
 **Requirements:** Node.js ≥20, Svelte 5
 
+**Note:** This package is distributed as ESM (ES Modules) only.
+
 ---
 
 ## 🎯 Core Features
@@ -130,7 +134,8 @@ const {
   {
     validator: (source) => ({
       // Fluent API: chain validations, get first error
-      email: stringValidator(source.email, 'trim') // 'trim' preprocesses input
+      email: stringValidator(source.email)
+        .prepare('trim') // preprocessing applied before validation
         .required()
         .email()
         .maxLength(100)
@@ -154,8 +159,66 @@ const {
 
 - 🔄 Automatic re-validation on any change (debounced via microtask)
 - 📐 Error structure matches data structure exactly
-- 🧹 String preprocessing: `'trim'`, `'normalize'`, `'upper'`, `'lower'`
+- 🧹 String preprocessing via `.prepare()`: `'trim'`, `'normalize'`, `'upper'`, `'lower'`, `'localeUpper'`, `'localeLower'`
 - ⚡ First-error-wins: `getError()` returns the first failure
+- 🔀 Conditional validation: `requiredIf(condition)` on all validators
+
+#### Async Validation
+
+For server-side validation (checking username availability, email verification, etc.), svstate supports async validators that run after sync validation passes:
+
+```typescript
+import { createSvState, stringValidator, type AsyncValidator } from 'svstate';
+
+type UserForm = { username: string; email: string };
+
+const asyncValidators: AsyncValidator<UserForm> = {
+  username: async (value, source, signal) => {
+    // Skip if empty (let sync validation handle required)
+    if (!value) return '';
+
+    const response = await fetch(`/api/check-username?name=${value}`, { signal });
+    const { available } = await response.json();
+    return available ? '' : 'Username already taken';
+  },
+  email: async (value, source, signal) => {
+    if (!value) return '';
+
+    const response = await fetch(`/api/check-email?email=${value}`, { signal });
+    const { valid } = await response.json();
+    return valid ? '' : 'Email not deliverable';
+  }
+};
+
+const {
+  data,
+  state: { errors, asyncErrors, asyncValidating, hasAsyncErrors, hasCombinedErrors }
+} = createSvState(
+  { username: '', email: '' },
+  {
+    validator: (source) => ({
+      username: stringValidator(source.username).required().minLength(3).getError(),
+      email: stringValidator(source.email).required().email().getError()
+    }),
+    asyncValidator: asyncValidators
+  },
+  { debounceAsyncValidation: 500 }
+);
+
+// In template:
+// {#if $asyncValidating.includes('username')}Checking...{/if}
+// {#if $asyncErrors.username}{$asyncErrors.username}{/if}
+// <button disabled={$hasCombinedErrors}>Submit</button>
+```
+
+**Key features:**
+
+- 🌐 Async validators receive `AbortSignal` for automatic cancellation
+- ⏱️ Debounced by default (300ms) to avoid excessive API calls
+- 🔄 Auto-cancels on property change or new validation
+- 🚫 Skipped if sync validation fails for the same path
+- 🎯 `asyncValidating` shows which paths are currently checking
+- 🔒 `maxConcurrentAsyncValidations` limits parallel requests (default: 4)
 
 ---
 
@@ -312,23 +375,103 @@ const { data } = createSvState(formData, actuators, {
   // Reset isDirty after successful action (default: true)
   resetDirtyOnAction: true,
 
-  // Debounce validation in ms (default: 0 = microtask)
+  // Debounce sync validation in ms (default: 0 = microtask)
   debounceValidation: 300,
 
   // Allow concurrent action executions (default: false)
   allowConcurrentActions: false,
 
   // Keep actionError until next action (default: false)
-  persistActionError: false
+  persistActionError: false,
+
+  // Debounce async validation in ms (default: 300)
+  debounceAsyncValidation: 500,
+
+  // Run async validators on state creation (default: false)
+  runAsyncValidationOnInit: false,
+
+  // Clear async error when property changes (default: true)
+  clearAsyncErrorsOnChange: true,
+
+  // Max concurrent async validators (default: 4)
+  maxConcurrentAsyncValidations: 4
+});
+```
+
+| Option                          | Default | Description                                |
+| ------------------------------- | ------- | ------------------------------------------ |
+| `resetDirtyOnAction`            | `true`  | Clear dirty flag after successful action   |
+| `debounceValidation`            | `0`     | Delay sync validation (0 = next microtask) |
+| `allowConcurrentActions`        | `false` | Block execute() while action runs          |
+| `persistActionError`            | `false` | Clear error on next change or action       |
+| `debounceAsyncValidation`       | `300`   | Delay async validation in ms               |
+| `runAsyncValidationOnInit`      | `false` | Run async validators on creation           |
+| `clearAsyncErrorsOnChange`      | `true`  | Clear async error when property changes    |
+| `maxConcurrentAsyncValidations` | `4`     | Max concurrent async validators            |
+
+---
+
+### 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"
 ```
 
-| Option                   | Default | Description                              |
-| ------------------------ | ------- | ---------------------------------------- |
-| `resetDirtyOnAction`     | `true`  | Clear dirty flag after successful action |
-| `debounceValidation`     | `0`     | Delay validation (0 = next microtask)    |
-| `allowConcurrentActions` | `false` | Block execute() while action runs        |
-| `persistActionError`     | `false` | Clear error on next change or action     |
+**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
 
 ---
 
@@ -384,13 +527,15 @@ const {
 
   // ✅ Validator mirrors data structure exactly
   validator: (source) => ({
-    name: stringValidator(source.name, 'trim')
+    name: stringValidator(source.name)
+      .prepare('trim')
       .required()
       .minLength(2)
       .maxLength(100)
       .getError(),
 
-    taxId: stringValidator(source.taxId, 'trim', 'upper')
+    taxId: stringValidator(source.taxId)
+      .prepare('trim', 'upper')
       .required()
       .regexp(/^[A-Z]{2}-\d{8}$/, 'Format: XX-12345678')
       .getError(),
@@ -403,20 +548,23 @@ const {
 
     // 📍 Nested address validation
     address: {
-      street: stringValidator(source.address.street, 'trim')
+      street: stringValidator(source.address.street)
+        .prepare('trim')
         .required()
         .minLength(5)
         .getError(),
-      city: stringValidator(source.address.city, 'trim')
+      city: stringValidator(source.address.city)
+        .prepare('trim')
         .required()
         .getError(),
-      zip: stringValidator(source.address.zip, 'trim')
+      zip: stringValidator(source.address.zip)
+        .prepare('trim')
         .required()
         .minLength(5)
         .getError(),
       country: stringValidator(source.address.country)
         .required()
-        .inArray(['US', 'CA', 'UK', 'DE', 'FR'])
+        .in(['US', 'CA', 'UK', 'DE', 'FR'])
         .getError()
     },
 
@@ -430,19 +578,21 @@ const {
     billing: {
       paymentTerms: stringValidator(source.billing.paymentTerms)
         .required()
-        .inArray(['NET15', 'NET30', 'NET60', 'COD'])
+        .in(['NET15', 'NET30', 'NET60', 'COD'])
         .getError(),
       currency: stringValidator(source.billing.currency)
         .required()
-        .inArray(['USD', 'EUR', 'GBP'])
+        .in(['USD', 'EUR', 'GBP'])
         .getError(),
       bankAccount: {
-        iban: stringValidator(source.billing.bankAccount.iban, 'trim', 'upper')
+        iban: stringValidator(source.billing.bankAccount.iban)
+          .prepare('trim', 'upper')
           .required()
           .minLength(15)
           .maxLength(34)
           .getError(),
-        swift: stringValidator(source.billing.bankAccount.swift, 'trim', 'upper')
+        swift: stringValidator(source.billing.bankAccount.swift)
+          .prepare('trim', 'upper')
           .required()
           .minLength(8)
           .maxLength(11)
@@ -552,18 +702,21 @@ const {
 } = createSvState(initialProduct, {
 
   validator: (source) => ({
-    sku: stringValidator(source.sku, 'trim', 'upper')
+    sku: stringValidator(source.sku)
+      .prepare('trim', 'upper')
       .required()
       .regexp(/^[A-Z]{3}-\d{4}$/, 'Format: ABC-1234')
       .getError(),
 
-    name: stringValidator(source.name, 'trim')
+    name: stringValidator(source.name)
+      .prepare('trim')
       .required()
       .minLength(3)
       .maxLength(100)
       .getError(),
 
-    description: stringValidator(source.description, 'trim')
+    description: stringValidator(source.description)
+      .prepare('trim')
       .maxLength(500)
       .getError(),
 
@@ -696,16 +849,20 @@ 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 |
-| `state.errors` | `Readable<V>` | Validation errors store |
-| `state.hasErrors` | `Readable<boolean>` | Quick error check |
+| `state.errors` | `Readable<V>` | Sync validation errors store |
+| `state.hasErrors` | `Readable<boolean>` | Has sync errors? |
 | `state.isDirty` | `Readable<boolean>` | Has state changed? |
 | `state.actionInProgress` | `Readable<boolean>` | Is action running? |
 | `state.actionError` | `Readable<Error>` | Last action error |
 | `state.snapshots` | `Readable<Snapshot[]>` | Undo history |
+| `state.asyncErrors` | `Readable<AsyncErrors>` | Async validation errors (keyed by path) |
+| `state.hasAsyncErrors` | `Readable<boolean>` | Has async errors? |
+| `state.asyncValidating` | `Readable<string[]>` | Paths currently validating |
+| `state.hasCombinedErrors` | `Readable<boolean>` | Has sync OR async errors? |
 
 ### Built-in Validators
 
@@ -713,28 +870,40 @@ svstate ships with four fluent validator builders that cover the most common val
 
 String validators support optional preprocessing (`'trim'`, `'normalize'`, `'upper'`, `'lower'`) applied before validation. All validators return descriptive error messages that you can customize or use as-is.
 
-| Validator                             | Methods                                                                                                                                                                                                                         |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `stringValidator(input, ...prepares)` | `required()`, `minLength(n)`, `maxLength(n)`, `email()`, `regexp(re)`, `inArray(arr)`, `startsWith(s)`, `endsWith(s)`, `contains(s)`, `noSpace()`, `uppercase()`, `lowercase()`, `alphanumeric()`, `numeric()`, `website(mode)` |
-| `numberValidator(input)`              | `required()`, `min(n)`, `max(n)`, `between(min, max)`, `integer()`, `positive()`, `negative()`, `nonNegative()`, `multipleOf(n)`, `decimal(places)`, `percentage()`                                                             |
-| `arrayValidator(input)`               | `required()`, `minLength(n)`, `maxLength(n)`, `unique()`                                                                                                                                                                        |
-| `dateValidator(input)`                | `required()`, `before(date)`, `after(date)`, `between(start, end)`, `past()`, `future()`, `weekday()`, `weekend()`, `minAge(years)`, `maxAge(years)`                                                                            |
+| Validator                | Methods                                                                                                                                                                                                                                                                                                                       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stringValidator(input)` | `prepare(...ops)`, `required()`, `requiredIf(cond)`, `minLength(n)`, `maxLength(n)`, `email()`, `regexp(re, msg?)`, `in(arr)`, `notIn(arr)`, `startsWith(s)`, `endsWith(s)`, `contains(s)`, `noSpace()`, `notBlank()`, `uppercase()`, `lowercase()`, `alphanumeric()`, `numeric()`, `slug()`, `identifier()`, `website(mode)` |
+| `numberValidator(input)` | `required()`, `requiredIf(cond)`, `min(n)`, `max(n)`, `between(min, max)`, `integer()`, `positive()`, `negative()`, `nonNegative()`, `notZero()`, `multipleOf(n)`, `step(n)`, `decimal(places)`, `percentage()`                                                                                                               |
+| `arrayValidator(input)`  | `required()`, `requiredIf(cond)`, `minLength(n)`, `maxLength(n)`, `ofLength(n)`, `unique()`, `includes(item)`, `includesAny(items)`, `includesAll(items)`                                                                                                                                                                     |
+| `dateValidator(input)`   | `required()`, `requiredIf(cond)`, `before(date)`, `after(date)`, `between(start, end)`, `past()`, `future()`, `weekday()`, `weekend()`, `minAge(years)`, `maxAge(years)`                                                                                                                                                      |
 
 ### TypeScript Types
 
 svstate exports TypeScript types to help you write type-safe external validator and effect functions. This is useful when you want to define these functions outside the `createSvState` call or reuse them across multiple state instances.
 
 ```typescript
-import type { Validator, EffectContext, Snapshot, SnapshotFunction, SvStateOptions } from 'svstate';
+import type {
+  Validator,
+  EffectContext,
+  Snapshot,
+  SnapshotFunction,
+  SvStateOptions,
+  AsyncValidator,
+  AsyncValidatorFunction,
+  AsyncErrors
+} from 'svstate';
 ```
 
-| Type               | Description                                                                                         |
-| ------------------ | --------------------------------------------------------------------------------------------------- |
-| `Validator`        | Nested object type for validation errors — leaf values are error strings (empty = valid)            |
-| `EffectContext<T>` | Context object passed to effect callbacks: `{ snapshot, target, property, currentValue, oldValue }` |
-| `SnapshotFunction` | Type for the `snapshot(title, replace?)` function used in effects                                   |
-| `Snapshot<T>`      | Shape of a snapshot entry: `{ title: string; data: T }`                                             |
-| `SvStateOptions`   | Configuration options type for `createSvState`                                                      |
+| Type                        | Description                                                                                         |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| `Validator`                 | Nested object type for validation errors — leaf values are error strings (empty = valid)            |
+| `EffectContext<T>`          | Context object passed to effect callbacks: `{ snapshot, target, property, currentValue, oldValue }` |
+| `SnapshotFunction`          | Type for the `snapshot(title, replace?)` function used in effects                                   |
+| `Snapshot<T>`               | Shape of a snapshot entry: `{ title: string; data: T }`                                             |
+| `SvStateOptions`            | Configuration options type for `createSvState`                                                      |
+| `AsyncValidator<T>`         | Object mapping property paths to async validator functions                                          |
+| `AsyncValidatorFunction<T>` | Async function: `(value, source, signal) => Promise<string>`                                        |
+| `AsyncErrors`               | Object mapping property paths to error strings                                                      |
 
 **Example: External validator and effect functions**
 
@@ -781,9 +950,11 @@ const { data, state } = createSvState<UserData, UserErrors, object>(
 | Deep nested objects    | ⚠️ Manual tracking | ✅ Automatic    |
 | Property change events | ❌ Not available   | ✅ Full context |
 | Structured validation  | ❌ DIY             | ✅ Mirrors data |
+| Async validation       | ❌ DIY             | ✅ Built-in     |
 | 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 +969,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.d.ts

@@ -1,2 +1,2 @@
-export { createSvState, type EffectContext, type Snapshot, type SnapshotFunction, type SvStateOptions, type Validator } from './state.svelte';
+export { type AsyncErrors, type AsyncValidator, type AsyncValidatorFunction, createSvState, type EffectContext, type Snapshot, type SnapshotFunction, type SvStateOptions, type Validator } from './state.svelte';
 export { arrayValidator, dateValidator, numberValidator, stringValidator } from './validators';

package/dist/state.svelte.d.ts

@@ -15,11 +15,19 @@ export type EffectContext<T> = {
     currentValue: unknown;
     oldValue: unknown;
 };
+export type AsyncValidatorFunction<T> = (value: unknown, source: T, signal: AbortSignal) => Promise<string>;
+export type AsyncValidator<T> = {
+    [propertyPath: string]: AsyncValidatorFunction<T>;
+};
+export type AsyncErrors = {
+    [propertyPath: string]: string;
+};
 type Actuators<T extends Record<string, unknown>, V extends Validator, P extends object> = {
     validator?: (source: T) => V;
     effect?: (context: EffectContext<T>) => void;
     action?: Action<P>;
     actionCompleted?: (error?: unknown) => void | Promise<void>;
+    asyncValidator?: AsyncValidator<T>;
 };
 type StateResult<T, V> = {
     errors: Readable<V | undefined>;
@@ -28,12 +36,20 @@ type StateResult<T, V> = {
     actionInProgress: Readable<boolean>;
     actionError: Readable<Error | undefined>;
     snapshots: Readable<Snapshot<T>[]>;
+    asyncErrors: Readable<AsyncErrors>;
+    hasAsyncErrors: Readable<boolean>;
+    asyncValidating: Readable<string[]>;
+    hasCombinedErrors: Readable<boolean>;
 };
 export type SvStateOptions = {
     resetDirtyOnAction: boolean;
     debounceValidation: number;
     allowConcurrentActions: boolean;
     persistActionError: boolean;
+    debounceAsyncValidation: number;
+    runAsyncValidationOnInit: boolean;
+    clearAsyncErrorsOnChange: boolean;
+    maxConcurrentAsyncValidations: number;
 };
 export declare function createSvState<T extends Record<string, unknown>, V extends Validator, P extends object>(init: T, actuators?: Actuators<T, V, P>, options?: Partial<SvStateOptions>): {
     data: T;

package/dist/state.svelte.js

@@ -9,26 +9,70 @@ 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;
 };
+const getValueAtPath = (source, path) => {
+    const parts = path.split('.');
+    let current = source;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+};
+const getSyncErrorForPath = (errors, path) => {
+    if (!errors)
+        return '';
+    const parts = path.split('.');
+    let current = errors;
+    for (const part of parts) {
+        if (typeof current === 'string')
+            return '';
+        if (current[part] === undefined)
+            return '';
+        current = current[part];
+    }
+    return typeof current === 'string' ? current : '';
+};
+const getMatchingAsyncValidatorPaths = (asyncValidator, changedPath) => {
+    const matches = [];
+    for (const registeredPath of Object.keys(asyncValidator))
+        if (registeredPath === changedPath || registeredPath.startsWith(changedPath + '.'))
+            matches.push(registeredPath);
+        else if (changedPath.startsWith(registeredPath + '.'))
+            matches.push(registeredPath);
+    return matches;
+};
 const defaultOptions = {
     resetDirtyOnAction: true,
     debounceValidation: 0,
     allowConcurrentActions: false,
-    persistActionError: false
+    persistActionError: false,
+    debounceAsyncValidation: 300,
+    runAsyncValidationOnInit: false,
+    clearAsyncErrorsOnChange: true,
+    maxConcurrentAsyncValidations: 4
 };
 export function createSvState(init, actuators, options) {
     const usedOptions = { ...defaultOptions, ...options };
-    const { validator, effect } = actuators ?? {};
+    const { validator, effect, asyncValidator } = actuators ?? {};
     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 asyncErrorsStore = writable({});
+    const asyncValidatingSet = writable(new Set());
+    const asyncValidating = derived(asyncValidatingSet, ($set) => [...$set]);
+    const hasAsyncErrors = derived(asyncErrorsStore, ($asyncErrors) => Object.values($asyncErrors).some((error) => !!error));
+    const hasCombinedErrors = derived([hasErrors, hasAsyncErrors], ([$hasErrors, $hasAsyncErrors]) => $hasErrors || $hasAsyncErrors);
+    const asyncValidationTrackers = new Map();
+    const asyncValidationQueue = [];
     const stateObject = $state(init);
     const createSnapshot = (title, replace = true) => {
         const currentSnapshots = get(snapshots);
@@ -60,6 +104,110 @@ export function createSvState(init, actuators, options) {
             });
         }
     };
+    const removeFromQueue = (path) => {
+        const index = asyncValidationQueue.indexOf(path);
+        if (index !== -1)
+            asyncValidationQueue.splice(index, 1);
+    };
+    const cancelAsyncValidation = (path) => {
+        removeFromQueue(path);
+        const tracker = asyncValidationTrackers.get(path);
+        if (tracker) {
+            clearTimeout(tracker.timeoutId);
+            tracker.controller.abort();
+            asyncValidationTrackers.delete(path);
+            asyncValidatingSet.update(($set) => {
+                $set.delete(path);
+                return new Set($set);
+            });
+        }
+    };
+    const cancelAllAsyncValidations = () => {
+        asyncValidationQueue.length = 0;
+        for (const path of asyncValidationTrackers.keys())
+            cancelAsyncValidation(path);
+        asyncErrorsStore.set({});
+    };
+    const executeAsyncValidation = async (path, onComplete) => {
+        if (!asyncValidator) {
+            onComplete();
+            return;
+        }
+        const asyncValidatorForPath = asyncValidator[path];
+        if (!asyncValidatorForPath) {
+            onComplete();
+            return;
+        }
+        const syncError = getSyncErrorForPath(get(errors), path);
+        if (syncError) {
+            onComplete();
+            return;
+        }
+        const controller = new AbortController();
+        asyncValidationTrackers.set(path, { controller, timeoutId: 0 });
+        asyncValidatingSet.update(($set) => new Set([...$set, path]));
+        try {
+            const value = getValueAtPath(data, path);
+            const error = await asyncValidatorForPath(value, data, controller.signal);
+            if (!controller.signal.aborted)
+                asyncErrorsStore.update(($asyncErrors) => ({
+                    ...$asyncErrors,
+                    [path]: error
+                }));
+        }
+        catch (error) {
+            if (error instanceof Error && error.name !== 'AbortError')
+                throw error;
+        }
+        finally {
+            asyncValidationTrackers.delete(path);
+            asyncValidatingSet.update(($set) => {
+                $set.delete(path);
+                return new Set($set);
+            });
+            onComplete();
+        }
+    };
+    const processAsyncValidationQueue = () => {
+        while (asyncValidationQueue.length > 0) {
+            const currentActiveCount = get(asyncValidatingSet).size;
+            if (currentActiveCount >= usedOptions.maxConcurrentAsyncValidations)
+                break;
+            const path = asyncValidationQueue.shift();
+            if (path)
+                executeAsyncValidation(path, processAsyncValidationQueue);
+        }
+    };
+    const scheduleAsyncValidation = (path) => {
+        if (!asyncValidator || !asyncValidator[path])
+            return;
+        cancelAsyncValidation(path);
+        if (usedOptions.clearAsyncErrorsOnChange)
+            asyncErrorsStore.update(($asyncErrors) => {
+                const updated = { ...$asyncErrors };
+                delete updated[path];
+                return updated;
+            });
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            asyncValidationTrackers.delete(path);
+            const activeCount = get(asyncValidatingSet).size;
+            if (activeCount < usedOptions.maxConcurrentAsyncValidations)
+                executeAsyncValidation(path, processAsyncValidationQueue);
+            else {
+                removeFromQueue(path);
+                asyncValidationQueue.push(path);
+            }
+        }, usedOptions.debounceAsyncValidation);
+        asyncValidationTrackers.set(path, { controller, timeoutId });
+    };
+    const scheduleAsyncValidationsForPath = (changedPath) => {
+        if (!asyncValidator)
+            return;
+        const matchingPaths = getMatchingAsyncValidatorPaths(asyncValidator, changedPath);
+        for (const path of matchingPaths)
+            scheduleAsyncValidation(path);
+    };
     const data = ChangeProxy(stateObject, (target, property, currentValue, oldValue) => {
         if (!usedOptions.persistActionError)
             actionError.set(undefined);
@@ -68,9 +216,13 @@ export function createSvState(init, actuators, options) {
         if (effectResult instanceof Promise)
             throw new Error('svstate: effect callback must be synchronous. Use action for async operations.');
         scheduleValidation();
+        scheduleAsyncValidationsForPath(property);
     });
     if (validator)
         errors.set(validator(data));
+    if (asyncValidator && usedOptions.runAsyncValidationOnInit)
+        for (const path of Object.keys(asyncValidator))
+            scheduleAsyncValidation(path);
     const execute = async (parameters) => {
         if (!usedOptions.allowConcurrentActions && get(actionInProgress))
             return;
@@ -99,6 +251,7 @@ export function createSvState(init, actuators, options) {
         const targetSnapshot = currentSnapshots[targetIndex];
         if (!targetSnapshot)
             return;
+        cancelAllAsyncValidations();
         Object.assign(stateObject, deepClone(targetSnapshot.data));
         snapshots.set(currentSnapshots.slice(0, targetIndex + 1));
         if (validator)
@@ -109,6 +262,7 @@ export function createSvState(init, actuators, options) {
         const initialSnapshot = currentSnapshots[0];
         if (!initialSnapshot)
             return;
+        cancelAllAsyncValidations();
         Object.assign(stateObject, deepClone(initialSnapshot.data));
         snapshots.set([initialSnapshot]);
         if (validator)
@@ -120,7 +274,11 @@ export function createSvState(init, actuators, options) {
         isDirty,
         actionInProgress,
         actionError,
-        snapshots
+        snapshots,
+        asyncErrors: asyncErrorsStore,
+        hasAsyncErrors,
+        asyncValidating,
+        hasCombinedErrors
     };
     return { data, execute, state, rollback, reset };
 }

package/dist/validators.d.ts

@@ -1,28 +1,37 @@
 type BaseOption = 'trim' | 'normalize';
-export declare function stringValidator(input: string, ...prepares: (BaseOption | 'upper')[]): StringValidatorBuilder;
-export declare function stringValidator(input: string, ...prepares: (BaseOption | 'lower')[]): StringValidatorBuilder;
-export declare function stringValidator(input: string, ...prepares: BaseOption[]): StringValidatorBuilder;
+export declare function stringValidator(input: string | null | undefined): StringValidatorBuilder;
 type StringValidatorBuilder = {
+    prepare(...prepares: (BaseOption | 'upper')[]): StringValidatorBuilder;
+    prepare(...prepares: (BaseOption | 'lower')[]): StringValidatorBuilder;
+    prepare(...prepares: (BaseOption | 'localeUpper')[]): StringValidatorBuilder;
+    prepare(...prepares: (BaseOption | 'localeLower')[]): StringValidatorBuilder;
+    prepare(...prepares: BaseOption[]): StringValidatorBuilder;
     required(): StringValidatorBuilder;
+    requiredIf(cond: boolean): StringValidatorBuilder;
     noSpace(): StringValidatorBuilder;
+    notBlank(): StringValidatorBuilder;
     minLength(length: number): StringValidatorBuilder;
     maxLength(length: number): StringValidatorBuilder;
     uppercase(): StringValidatorBuilder;
     lowercase(): StringValidatorBuilder;
     startsWith(prefix: string | string[]): StringValidatorBuilder;
     regexp(regexp: RegExp, message?: string): StringValidatorBuilder;
-    inArray(values: string[] | Record<string, unknown>): StringValidatorBuilder;
+    in(values: string[] | Record<string, unknown>): StringValidatorBuilder;
+    notIn(values: string[] | Record<string, unknown>): StringValidatorBuilder;
     email(): StringValidatorBuilder;
     website(prefix?: 'required' | 'forbidden' | 'optional'): StringValidatorBuilder;
     endsWith(suffix: string | string[]): StringValidatorBuilder;
     contains(substring: string): StringValidatorBuilder;
     alphanumeric(): StringValidatorBuilder;
     numeric(): StringValidatorBuilder;
+    slug(): StringValidatorBuilder;
+    identifier(): StringValidatorBuilder;
     getError(): string;
 };
-export declare function numberValidator(input: number): NumberValidatorBuilder;
+export declare function numberValidator(input: number | null | undefined): NumberValidatorBuilder;
 type NumberValidatorBuilder = {
     required(): NumberValidatorBuilder;
+    requiredIf(cond: boolean): NumberValidatorBuilder;
     min(n: number): NumberValidatorBuilder;
     max(n: number): NumberValidatorBuilder;
     between(min: number, max: number): NumberValidatorBuilder;
@@ -30,22 +39,30 @@ type NumberValidatorBuilder = {
     positive(): NumberValidatorBuilder;
     negative(): NumberValidatorBuilder;
     nonNegative(): NumberValidatorBuilder;
+    notZero(): NumberValidatorBuilder;
     multipleOf(n: number): NumberValidatorBuilder;
+    step(n: number): NumberValidatorBuilder;
     decimal(places: number): NumberValidatorBuilder;
     percentage(): NumberValidatorBuilder;
     getError(): string;
 };
-export declare function arrayValidator<T>(input: T[]): ArrayValidatorBuilder;
-type ArrayValidatorBuilder = {
-    required(): ArrayValidatorBuilder;
-    minLength(n: number): ArrayValidatorBuilder;
-    maxLength(n: number): ArrayValidatorBuilder;
-    unique(): ArrayValidatorBuilder;
+export declare function arrayValidator<T>(input: T[] | null | undefined): ArrayValidatorBuilder<T>;
+type ArrayValidatorBuilder<T> = {
+    required(): ArrayValidatorBuilder<T>;
+    requiredIf(cond: boolean): ArrayValidatorBuilder<T>;
+    minLength(n: number): ArrayValidatorBuilder<T>;
+    maxLength(n: number): ArrayValidatorBuilder<T>;
+    unique(): ArrayValidatorBuilder<T>;
+    ofLength(n: number): ArrayValidatorBuilder<T>;
+    includes(item: T): ArrayValidatorBuilder<T>;
+    includesAny(items: T[]): ArrayValidatorBuilder<T>;
+    includesAll(items: T[]): ArrayValidatorBuilder<T>;
     getError(): string;
 };
-export declare function dateValidator(input: Date | string | number): DateValidatorBuilder;
+export declare function dateValidator(input: Date | string | number | null | undefined): DateValidatorBuilder;
 type DateValidatorBuilder = {
     required(): DateValidatorBuilder;
+    requiredIf(cond: boolean): DateValidatorBuilder;
     before(target: Date | string | number): DateValidatorBuilder;
     after(target: Date | string | number): DateValidatorBuilder;
     between(start: Date | string | number, end: Date | string | number): DateValidatorBuilder;

package/dist/validators.js

@@ -2,42 +2,71 @@ const prepareOps = {
     trim: (s) => s.trim(),
     normalize: (s) => s.replaceAll(/\s{2,}/g, ' '),
     upper: (s) => s.toUpperCase(),
-    lower: (s) => s.toLowerCase()
+    lower: (s) => s.toLowerCase(),
+    localeUpper: (s) => s.toLocaleUpperCase(),
+    localeLower: (s) => s.toLocaleLowerCase()
 };
-export function stringValidator(input, ...prepares) {
+export function stringValidator(input) {
     let error = '';
+    const isNullish = input === null || input === undefined;
+    let processedInput = input ?? '';
     const setError = (message) => {
         if (!error)
             error = message;
     };
-    const processedInput = prepares.reduce((s, op) => prepareOps[op](s), input);
     const builder = {
+        prepare(...prepares) {
+            processedInput = prepares.reduce((s, op) => prepareOps[op](s), processedInput);
+            return builder;
+        },
         required() {
-            if (!error && !processedInput)
+            if (!error && (isNullish || !processedInput))
+                setError('Required');
+            return builder;
+        },
+        requiredIf(cond) {
+            if (cond && !error && (isNullish || !processedInput))
                 setError('Required');
             return builder;
         },
         noSpace() {
+            if (isNullish)
+                return builder;
             if (!error && processedInput.includes(' '))
                 setError('No space allowed');
             return builder;
         },
+        notBlank() {
+            if (isNullish)
+                return builder;
+            if (!error && processedInput.length > 0 && processedInput.trim().length === 0)
+                setError('Must not be blank');
+            return builder;
+        },
         minLength(length) {
+            if (isNullish)
+                return builder;
             if (!error && processedInput.length < length)
                 setError(`Min length ${length}`);
             return builder;
         },
         maxLength(length) {
+            if (isNullish)
+                return builder;
             if (!error && processedInput.length > length)
                 setError(`Max length ${length}`);
             return builder;
         },
         uppercase() {
+            if (isNullish)
+                return builder;
             if (!error && processedInput !== processedInput.toUpperCase())
                 setError('Uppercase only');
             return builder;
         },
         lowercase() {
+            if (isNullish)
+                return builder;
             if (!error && processedInput !== processedInput.toLowerCase())
                 setError('Lowercase only');
             return builder;
@@ -55,7 +84,7 @@ export function stringValidator(input, ...prepares) {
                 setError(message ?? 'Not allowed chars');
             return builder;
         },
-        inArray(values) {
+        in(values) {
             if (error)
                 return builder;
             const allowed = Array.isArray(values) ? values : Object.keys(values);
@@ -63,6 +92,14 @@ export function stringValidator(input, ...prepares) {
                 setError(`Must be one of: ${allowed.join(', ')}`);
             return builder;
         },
+        notIn(values) {
+            if (error)
+                return builder;
+            const disallowed = Array.isArray(values) ? values : Object.keys(values);
+            if (processedInput && disallowed.includes(processedInput))
+                setError(`Must not be one of: ${disallowed.join(', ')}`);
+            return builder;
+        },
         email() {
             if (!error && processedInput && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(processedInput))
                 setError('Invalid email format');
@@ -101,6 +138,16 @@ export function stringValidator(input, ...prepares) {
                 setError('Only numbers allowed');
             return builder;
         },
+        slug() {
+            if (!error && processedInput && !/^[\da-z-]+$/.test(processedInput))
+                setError('Invalid slug format');
+            return builder;
+        },
+        identifier() {
+            if (!error && processedInput && !/^[A-Z_a-z]\w*$/.test(processedInput))
+                setError('Invalid identifier format');
+            return builder;
+        },
         getError() {
             return error;
         }
@@ -109,57 +156,95 @@ export function stringValidator(input, ...prepares) {
 }
 export function numberValidator(input) {
     let error = '';
+    const isNullish = input === null || input === undefined;
     const setError = (message) => {
         if (!error)
             error = message;
     };
     const builder = {
         required() {
-            if (!error && Number.isNaN(input))
+            if (!error && (isNullish || Number.isNaN(input)))
+                setError('Required');
+            return builder;
+        },
+        requiredIf(cond) {
+            if (cond && !error && (isNullish || Number.isNaN(input)))
                 setError('Required');
             return builder;
         },
         min(n) {
+            if (isNullish)
+                return builder;
             if (!error && input < n)
                 setError(`Minimum ${n}`);
             return builder;
         },
         max(n) {
+            if (isNullish)
+                return builder;
             if (!error && input > n)
                 setError(`Maximum ${n}`);
             return builder;
         },
         between(min, max) {
+            if (isNullish)
+                return builder;
             if (!error && (input < min || input > max))
                 setError(`Must be between ${min} and ${max}`);
             return builder;
         },
         integer() {
+            if (isNullish)
+                return builder;
             if (!error && !Number.isInteger(input))
                 setError('Must be an integer');
             return builder;
         },
         positive() {
+            if (isNullish)
+                return builder;
             if (!error && input <= 0)
                 setError('Must be positive');
             return builder;
         },
         negative() {
+            if (isNullish)
+                return builder;
             if (!error && input >= 0)
                 setError('Must be negative');
             return builder;
         },
         nonNegative() {
+            if (isNullish)
+                return builder;
             if (!error && input < 0)
                 setError('Must be non-negative');
             return builder;
         },
+        notZero() {
+            if (isNullish)
+                return builder;
+            if (!error && input === 0)
+                setError('Must not be zero');
+            return builder;
+        },
         multipleOf(n) {
+            if (isNullish)
+                return builder;
+            if (!error && input % n !== 0)
+                setError(`Must be a multiple of ${n}`);
+            return builder;
+        },
+        step(n) {
+            if (isNullish)
+                return builder;
             if (!error && input % n !== 0)
                 setError(`Must be a multiple of ${n}`);
             return builder;
         },
         decimal(places) {
+            if (isNullish)
+                return builder;
             if (error || Number.isNaN(input))
                 return builder;
             const parts = String(input).split('.');
@@ -169,6 +254,8 @@ export function numberValidator(input) {
             return builder;
         },
         percentage() {
+            if (isNullish)
+                return builder;
             if (!error && (input < 0 || input > 100))
                 setError('Must be between 0 and 100');
             return builder;
@@ -181,31 +268,44 @@ export function numberValidator(input) {
 }
 export function arrayValidator(input) {
     let error = '';
+    const isNullish = input === null || input === undefined;
+    const array = input ?? [];
     const setError = (message) => {
         if (!error)
             error = message;
     };
     const builder = {
         required() {
-            if (!error && input.length === 0)
+            if (!error && (isNullish || array.length === 0))
+                setError('Required');
+            return builder;
+        },
+        requiredIf(cond) {
+            if (cond && !error && (isNullish || array.length === 0))
                 setError('Required');
             return builder;
         },
         minLength(n) {
-            if (!error && input.length < n)
+            if (isNullish)
+                return builder;
+            if (!error && array.length < n)
                 setError(`Minimum ${n} items`);
             return builder;
         },
         maxLength(n) {
-            if (!error && input.length > n)
+            if (isNullish)
+                return builder;
+            if (!error && array.length > n)
                 setError(`Maximum ${n} items`);
             return builder;
         },
         unique() {
+            if (isNullish)
+                return builder;
             if (error)
                 return builder;
             const seen = new Set();
-            for (const item of input) {
+            for (const item of array) {
                 const key = typeof item === 'object' ? JSON.stringify(item) : String(item);
                 if (seen.has(key)) {
                     setError('Items must be unique');
@@ -215,6 +315,57 @@ export function arrayValidator(input) {
             }
             return builder;
         },
+        ofLength(n) {
+            if (isNullish)
+                return builder;
+            if (!error && array.length !== n)
+                setError(`Must have exactly ${n} items`);
+            return builder;
+        },
+        includes(item) {
+            if (isNullish)
+                return builder;
+            if (error)
+                return builder;
+            const itemKey = typeof item === 'object' ? JSON.stringify(item) : String(item);
+            const found = array.some((element) => {
+                const elementKey = typeof element === 'object' ? JSON.stringify(element) : String(element);
+                return elementKey === itemKey;
+            });
+            if (!found)
+                setError(`Must include ${itemKey}`);
+            return builder;
+        },
+        includesAny(items) {
+            if (isNullish)
+                return builder;
+            if (error)
+                return builder;
+            const itemKeys = items.map((entry) => (typeof entry === 'object' ? JSON.stringify(entry) : String(entry)));
+            const found = array.some((element) => {
+                const elementKey = typeof element === 'object' ? JSON.stringify(element) : String(element);
+                return itemKeys.includes(elementKey);
+            });
+            if (!found)
+                setError(`Must include at least one of: ${itemKeys.join(', ')}`);
+            return builder;
+        },
+        includesAll(items) {
+            if (isNullish)
+                return builder;
+            if (error)
+                return builder;
+            const arrayKeys = new Set(array.map((element) => (typeof element === 'object' ? JSON.stringify(element) : String(element))));
+            const missing = items.filter((entry) => {
+                const entryKey = typeof entry === 'object' ? JSON.stringify(entry) : String(entry);
+                return !arrayKeys.has(entryKey);
+            });
+            if (missing.length > 0) {
+                const missingKeys = missing.map((entry) => (typeof entry === 'object' ? JSON.stringify(entry) : String(entry)));
+                setError(`Missing required items: ${missingKeys.join(', ')}`);
+            }
+            return builder;
+        },
         getError() {
             return error;
         }
@@ -223,18 +374,24 @@ export function arrayValidator(input) {
 }
 export function dateValidator(input) {
     let error = '';
+    const isNullish = input === null || input === undefined;
     const setError = (message) => {
         if (!error)
             error = message;
     };
-    const date = input instanceof Date ? input : new Date(input);
-    const isValid = !Number.isNaN(date.getTime());
+    const date = isNullish ? new Date(Number.NaN) : input instanceof Date ? input : new Date(input);
+    const isValid = !isNullish && !Number.isNaN(date.getTime());
     const builder = {
         required() {
             if (!error && !isValid)
                 setError('Required');
             return builder;
         },
+        requiredIf(cond) {
+            if (cond && !error && !isValid)
+                setError('Required');
+            return builder;
+        },
         before(target) {
             if (!error && isValid) {
                 const targetDate = target instanceof Date ? target : new Date(target);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svstate",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Supercharged $state() for Svelte 5: deep reactive proxy with validation, cross-field rules, computed & side-effects",
   "author": "BCsabaEngine",
   "license": "ISC",
@@ -54,21 +54,21 @@
   ],
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
-    "@types/node": "^25.0.9",
-    "@typescript-eslint/eslint-plugin": "^8.53.1",
-    "@typescript-eslint/parser": "^8.53.1",
-    "@vitest/coverage-v8": "^4.0.17",
+    "@types/node": "^25.1.0",
+    "@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.47.1",
+    "prettier": "^3.8.1",
+    "svelte": "^5.49.1",
     "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"