@uistate/core 5.4.0 → 5.5.1

package/README.md

@@ -1,21 +1,11 @@
-# UIstate v5
+# @uistate/core
 
-**Lightweight event-driven state management for modern web applications**
+Path-based state management with wildcard subscriptions and async support.
 
 [![npm version](https://img.shields.io/npm/v/@uistate/core.svg)](https://www.npmjs.com/package/@uistate/core)
-[![License: MIT + Commercial](https://img.shields.io/badge/License-MIT%20%2B%20Commercial-blue.svg)](#license)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
 
-After many experiments exploring different state management paradigms, UIstate v5 emerges as a focused, production-ready solution for complex UIs. Born from real-world challenges like building data tables, dashboards, and interactive applications.
-
-## What's New in v5
-
-- **EventState Core**: Path-based subscriptions with wildcard support (~80 LOC)
-- **Slot Orchestration**: Atomic component swapping without layout shift
-- **Intent-Driven**: Declarative command handling for decoupled architecture
-- **Zero Dependencies**: Pure JavaScript, works in any modern browser
-- **Framework-Free**: No build step required (but works great with Vite)
-
-## Installation
+## Install
 
 ```bash
 npm install @uistate/core
@@ -26,424 +16,101 @@ npm install @uistate/core
 ```javascript
 import { createEventState } from '@uistate/core';
 
-const store = createEventState({
-  user: { name: 'Alice' },
-  count: 0
-});
+const store = createEventState({ user: { name: 'Alice' }, count: 0 });
 
-// Subscribe to specific paths
-store.subscribe('user.name', (value) => {
-  console.log('Name changed:', value);
-});
+// Exact path
+store.subscribe('count', (value) => console.log('Count:', value));
 
-// Subscribe with wildcards
-store.subscribe('user.*', ({ path, value }) => {
-  console.log(`${path} changed to:`, value);
-});
+// Wildcard — fires on any child of 'user'
+store.subscribe('user.*', ({ path, value }) => console.log(path, value));
+
+// Global — fires on every change
+store.subscribe('*', ({ path, value }) => console.log(path, value));
 
-// Update state
-store.set('user.name', 'Bob');  // → Name changed: Bob
+store.set('user.name', 'Bob');
 store.set('count', 1);
 ```
 
-## Core API
-
-### `createEventState(initial?)`
+## API
 
-Creates a new reactive store.
-
-```javascript
-const store = createEventState({ count: 0 });
-```
+### `createEventState(initialState)`
 
-### `store.get(path)`
+Returns a store with `get`, `set`, `subscribe`, `setAsync`, `cancel`, `destroy`.
 
-Retrieves a value by path.
+### `store.get(path?)`
 
 ```javascript
-const count = store.get('count');
-const user = store.get('user');  // Returns entire user object
-const all = store.get();          // Returns entire store
+store.get('user.name');  // 'Alice'
+store.get('user');       // { name: 'Alice' }
+store.get();             // entire state
 ```
 
 ### `store.set(path, value)`
 
-Sets a value and triggers subscriptions.
+Sets a value and notifies subscribers. Creates intermediate objects if needed.
 
 ```javascript
-store.set('count', 42);
 store.set('user.email', 'alice@example.com');
+// state.user.email now exists even if it didn't before
 ```
 
 ### `store.subscribe(path, handler)`
 
-Subscribes to changes. Returns an unsubscribe function.
+Returns an unsubscribe function. Exact subscribers get `(value, detail)`. Wildcard/global subscribers get `(detail)` where detail is `{ path, value, oldValue }`.
 
 ```javascript
-// Exact path
-const unsub = store.subscribe('count', (value) => {
-  console.log('Count:', value);
-});
-
-// Wildcard (child changes)
-store.subscribe('user.*', ({ path, value }) => {
-  console.log(`User property ${path} changed`);
+const unsub = store.subscribe('count', (value, { oldValue }) => {
+  console.log(`${oldValue} → ${value}`);
 });
-
-// Global wildcard (all changes)
-store.subscribe('*', ({ path, value }) => {
-  console.log('Something changed');
-});
-
-// Cleanup
-unsub();
+unsub(); // cleanup
 ```
 
-### `store.destroy()`
-
-Cleans up the event bus and prevents further updates.
-
-```javascript
-store.destroy();
-```
-
-# Changelog
-
-## [5.0.0] - 2025-12-09
+### `store.setAsync(path, fetcher)`
 
-### Breaking Changes
-- eventState is now primary export (was cssState)
-- DOM element event bus replaced with EventTarget
-- ...
-
-### Added
-- Slot orchestration pattern
-- Intent-driven architecture
-- Event-sequence testing (experimental)
-- Example 009: Financial dashboard
-- Example 010: Event testing
-
-## Architecture Patterns
-
-UIstate v5 introduces battle-tested patterns from many experiments:
-
-### 1. **Intent-Driven Updates** (Declarative Commands)
-
-Intents are just regular state paths—no special API needed. Components subscribe to intent paths and execute logic when triggered:
+Manages async state at `${path}.status`, `${path}.data`, `${path}.error`. Supports abort on re-call.
 
 ```javascript
-// Subscribe to an intent path
-store.subscribe('intent.todo.add', ({ text }) => {
-  const items = store.get('todos.items') || [];
-  store.set('todos.items', [...items, { id: Date.now(), text, done: false }]);
-});
-
-// Trigger intent from UI by setting the path
-button.addEventListener('click', () => {
-  store.set('intent.todo.add', { text: input.value });
+await store.setAsync('users', async (signal) => {
+  const res = await fetch('/api/users', { signal });
+  return res.json();
 });
+// store.get('users.data')   → [...]
+// store.get('users.status') → 'success'
 ```
 
-**Key insight**: Intents are paths, not events. This means:
-- Subscribe once at component mount
-- Multiple components can listen to the same intent
-- Easy to test (just `set()` the intent path)
-- No special event emitter needed
-
-### 2. **Slot Orchestration** (Flicker-free component loading)
-
-Load layouts and components separately for atomic, layout-shift-free updates:
-
-```javascript
-// 1. Mount persistent layout once
-async function mountMaster(master) {
-  const layout = await fetchHTML(master.layout);
-  document.getElementById('app').innerHTML = layout;
-}
-
-// 2. Load components into slots atomically
-async function loadSlot({ slot, url }) {
-  const config = await fetchJSON(url);
-  const html = await fetchHTML(config.component);
-
-  // Find slot container
-  const slotHost = document.querySelector(`[data-slot="${slot}"]`);
-
-  // Atomic replacement - no layout shift!
-  const fragment = createFragment(html);
-  slotHost.replaceChildren(fragment);
-
-  // Wire up component subscriptions
-  wireComponent(slotHost, config.bindings);
-}
-
-// Trigger slot loading via intent
-store.subscribe('intent.slot.load', loadSlot);
-store.set('intent.slot.load', { slot: 'main', url: '/slots/todo.json' });
-```
-
-**Key insight**: Separate layout (skeleton) from content (slots):
-- Layout provides stable structure
-- Slots swap atomically without reflow
-- Each component manages its own subscriptions
-- Clean separation of concerns
-
-### 3. **Component Bindings** (Path-based reactivity)
-
-Components subscribe to specific state paths, not global wildcards:
-
-```javascript
-function wireComponent(root, bindings) {
-  const input = root.querySelector('#input');
-  const list = root.querySelector('#list');
-  const itemsPath = bindings.items || 'domain.items';
-
-  // Subscribe to specific path for this component
-  const unsubscribe = store.subscribe(itemsPath, (items) => {
-    list.replaceChildren();
-    items.forEach(item => {
-      const li = document.createElement('li');
-      li.textContent = item.text;
-      list.appendChild(li);
-    });
-  });
-
-  // Initial render
-  const items = store.get(itemsPath);
-  if (items) store.set(itemsPath, items);
-
-  // Return cleanup function
-  return unsubscribe;
-}
-```
+### `store.cancel(path)` / `store.destroy()`
 
-**Key insight**: Each component subscribes to its own paths:
-- No global `*` wildcards in production code
-- Components are isolated and testable
-- Easy cleanup when unmounting
-- Clear data dependencies
+Cancel an in-flight async operation, or tear down the entire store.
 
-### 4. **Component Lifecycle Pattern**
+## Query Client
 
-Proper mount/unmount with subscription cleanup:
+Convenience wrapper around `setAsync` for data-fetching patterns.
 
 ```javascript
-const componentRegistry = new Map();
-
-async function loadSlot({ slot, url }) {
-  // Cleanup previous component in this slot
-  const existing = componentRegistry.get(slot);
-  if (existing?.cleanup) {
-    existing.cleanup();
-  }
-
-  // Load and mount new component
-  const config = await fetchJSON(url);
-  const html = await fetchHTML(config.component);
-  const slotHost = document.querySelector(`[data-slot="${slot}"]`);
-  slotHost.replaceChildren(createFragment(html));
-
-  // Wire up with cleanup function
-  const cleanup = wireComponent(slotHost, config.bindings);
-
-  // Store for later cleanup
-  componentRegistry.set(slot, { cleanup });
-}
+import { createQueryClient } from '@uistate/core/query';
+
+const qc = createQueryClient(store);
+await qc.query('users', (signal) => fetch('/api/users', { signal }).then(r => r.json()));
+qc.getData('users');
+qc.getStatus('users');
+qc.cancel('users');
+qc.invalidate('users');
 ```
 
-**Key insight**: Always clean up subscriptions:
-- Prevents memory leaks
-- Allows safe component swapping
-- Components are truly hot-swappable
-- No zombie subscriptions
+## Ecosystem
 
-### 5. **Content-Driven Layout** (Layout morphs based on active content)
-
-One layout HTML can adapt to different use cases by subscribing to state and toggling CSS classes:
-
-```javascript
-function wireLayout(root, bindings) {
-  // ...existing button wiring...
-
-  // Layout adapts based on which slot is active
-  store.subscribe('ui.view.active', (active) => {
-    const kpiCol = root.querySelector('[data-slot="kpi"]').closest('.col-12');
-    const newsCol = root.querySelector('[data-slot="news"]').closest('.col-12');
-    const positionsCol = root.querySelector('[data-slot="positions"]').closest('.col-12');
-
-    if (active === 'todos') {
-      // Full-width editing mode
-      kpiCol.classList.add('d-none');
-      newsCol.classList.add('d-none');
-      positionsCol.classList.remove('col-md-6', 'col-lg-4');
-      positionsCol.classList.add('col-md-12', 'col-lg-8');
-    } else {
-      // Multi-column dashboard mode
-      kpiCol.classList.remove('d-none');
-      newsCol.classList.remove('d-none');
-      positionsCol.classList.remove('col-md-12', 'col-lg-8');
-      positionsCol.classList.add('col-md-6', 'col-lg-4');
-    }
-  });
-}
-```
-
-**Key insight**: Content configures layout, not the other way around:
-- One layout HTML handles all scenarios
-- Panels show/hide based on active content
-- Sections expand/collapse responsively
-- Pure CSS class manipulation - no DOM restructuring
-- Declarative layout rules via state subscription
-
-**Real-world applications**:
-```javascript
-// E-commerce: hide sidebar, expand product grid
-if (active === 'products') hideSlots(['filters', 'cart']); expandSlot('grid');
-
-// Admin: hide navigation, expand table
-if (active === 'report') hideSlots(['nav', 'sidebar']); expandSlot('table');
-
-// Editor: focus mode - hide everything except content
-if (active === 'editor') hideSlots(['toolbar', 'preview']); expandSlot('content');
-```
-
-This pattern eliminates the "rigid layout" criticism - UIstate layouts are as flexible as any framework, with zero VDOM overhead.
-
-## Complete Example
-
-See `examples/009-financial-dashboard` for a real-world application featuring:
-
-- Multi-slot dashboard layout
-- TodoList with filtering
-- Financial data tables (KPI, Positions, Debts, Sales, News)
-- Intent-driven architecture
-- Atomic slot swapping
-- State inspector
-
-Run the example:
-
-```bash
-cd node_modules/@uistate/core/examples/009-financial-dashboard
-npx serve .
-```
-
-Open http://localhost:3000 and explore the multi-slot dashboard!
-
-## Why UIstate v5?
-
-### vs. React/Vue
-
-- ✅ **No VDOM overhead** - Direct DOM manipulation with surgical updates
-- ✅ **No build step required** - Works in browsers directly
-- ✅ **Simpler mental model** - Paths + subscriptions, not components + lifecycle hooks
-- ✅ **Smaller bundle** - ~3KB core vs ~40KB+ frameworks
-- ✅ **Explicit reactivity** - Know exactly what triggers what
-- ❌ No component ecosystem
-- ❌ Manual DOM updates (but that's the point!)
-
-### vs. Alpine.js
-
-- ✅ **Better for complex state** - Nested paths, cross-component communication
-- ✅ **First-class SPA patterns** - Slot orchestration, intent-driven updates
-- ✅ **More powerful subscriptions** - Path-based, wildcard support, granular control
-- ✅ **Explicit data flow** - No magic, clear cause and effect
-- ❌ More JavaScript required (Alpine is more declarative HTML)
-
-### vs. Zustand/Jotai
-
-- ✅ **Framework-agnostic** - Not tied to React
-- ✅ **Path-based state** - More intuitive for deeply nested data
-- ✅ **Wildcard subscriptions** - Subscribe to entire subtrees when needed
-- ✅ **Simpler API** - Just get/set/subscribe, no atoms or stores
-- ❌ Smaller ecosystem
-- ❌ No React DevTools integration
-
-## Use Cases
-
-UIstate v5 excels at:
-
-- ✅ **Internal dashboards** - Complex state, multiple data sources
-- ✅ **Admin panels** - CRUD operations, forms, data tables
-- ✅ **Financial applications** - Real-time updates, calculations
-- ✅ **Data-heavy UIs** - Large datasets, filtered views
-- ✅ **Multi-pane interfaces** - Independent but coordinated components
-- ✅ **Progressive enhancement** - Add interactivity to server-rendered HTML
-
-## Browser Support
-
-- Chrome 60+
-- Firefox 54+
-- Safari 10.1+
-- Edge 79+
-
-## Migration from v4
-
-UIstate v5 shifts focus from CSS-driven state to event-driven state. Key changes:
-
-1. **eventState is now primary** - Import from root or `/eventState`
-2. **cssState still available** - Import from `/cssState`
-3. **New examples** - See `009-financial-dashboard`
-4. **Breaking changes** - Major version bump
-
-## Philosophy
-
-UIstate challenges traditional assumptions:
-
-- **State should be simple** - Paths + subscriptions, not selectors + reducers
-- **Reactivity should be explicit** - Know what updates what
-- **DOM updates can be fast** - Atomic replacements beat VDOM for many use cases
-- **Components should own their subscriptions** - No global wildcards in production
-- **Frameworks aren't always needed** - Pure JS + patterns can go far
-- **Build steps should be optional** - ESM works in browsers
-- **Intents are just paths** - No special event system needed
-
-UIstate v5 represents lessons learned from building:
-- Data tables with 1M+ rows
-- Multi-tab synchronized state
-- Workflowy-style nested lists
-- Financial dashboards
-- Admin panels
-
-The core insight: **Most web UIs need reactive state and component orchestration, not a full framework.**
-
-## Testing (Experimental)
-
-UIstate includes `eventTest.js` for event-sequence testing:
-
-**Note:** `eventTest.js` is dual-licensed. Free for personal/OSS use. Commercial use requires a separate license. See LICENSE-eventTest.md for details.
-
-```javascript
-import { createEventTest } from '@uistate/core/eventTest';
-
-const test = createEventTest({ count: 0 });
-
-test
-  .trigger('intent.increment')
-  .assertPath('count', 1)
-  .assertEventFired('count', 1);
-```
-
-See `examples/010-event-testing` for more.
+| Package | Description |
+|---|---|
+| [@uistate/core](https://www.npmjs.com/package/@uistate/core) | This package — event-driven state management |
+| [@uistate/css](https://www.npmjs.com/package/@uistate/css) | CSS-native state via custom properties and data attributes |
+| [@uistate/event-test](https://www.npmjs.com/package/@uistate/event-test) | Event-sequence testing (proprietary license) |
+| [@uistate/examples](https://www.npmjs.com/package/@uistate/examples) | Example applications and patterns |
 
 ## License
 
-**@uistate/core** is licensed under the **MIT License**, with an exception, as decribed next.
-
-**Exception:** `eventTest.js` is licensed under a **proprietary license** that permits:
-- ✅ Personal use
-- ✅ Open-source projects
-- ✅ Educational use
-
-For **commercial use** of `eventTest.js`, please contact: [ajdika@live.com](mailto:ajdika@live.com)
-
-See the file header in `eventTest.js` for full terms.
-
----
-
-Copyright © 2025 Ajdin Imsirovic (ajdika@live.com)
+MIT — see [LICENSE](./LICENSE).
 
-- Core library: MIT License
-- eventTest.js: Commercial License (free for personal/OSS)
+Copyright © 2025 Ajdin Imsirovic
 
 ## Links
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uistate/core",
-  "version": "5.4.0",
-  "description": "Lightweight event-driven state management with slot orchestration and experimental event-sequence testing (eventTest.js available under dual license)",
+  "version": "5.5.1",
+  "description": "Lightweight event-driven state management with path-based subscriptions, wildcards, and async support",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -15,9 +15,7 @@
     "eventState.js",
     "eventStateNew.js",
     "queryClient.js",
-    "eventTest.js",
-    "LICENSE",
-    "LICENSE-eventTest.md"
+    "LICENSE"
   ],
   "keywords": [
     "state-management",
@@ -28,8 +26,8 @@
     "zero-dependency",
     "framework-free",
     "micro-framework",
-    "testing",
-    "event-testing"
+    "async-state",
+    "query-client"
   ],
   "author": "Ajdin Imsirovic",
   "license": "MIT",

package/LICENSE-eventTest.md

@@ -1,26 +0,0 @@
-# Proprietary License for eventTest.js
-
-Copyright (c) 2025 Ajdin Imsirovic
-
-## Permitted Uses
-
-You may use `eventTest.js` for:
-- Personal projects
-- Open-source projects
-- Educational purposes
-
-## Restrictions
-
-You may NOT:
-- Use this file in commercial products without a license
-- Modify or create derivative works
-- Redistribute this file separately from @uistate/core
-- Remove or alter this license notice
-
-## Commercial Licensing
-
-For commercial use, please contact: your@email.com
-
----
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

package/eventTest.js

@@ -1,196 +0,0 @@
-/**
- * eventTest.js - Event-Sequence Testing for UIstate
- * 
- * Copyright (c) 2025 Ajdin Imsirovic
- * 
- * This file is licensed under a PROPRIETARY LICENSE.
- * 
- * Permission is hereby granted to USE this software for:
- * - Personal projects
- * - Open-source projects
- * - Educational purposes
- * 
- * RESTRICTIONS:
- * - Commercial use requires a separate license (contact: your@email.com)
- * - Modification and redistribution of this file are NOT permitted
- * - This file may not be included in derivative works without permission
- * 
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
- * 
- * For commercial licensing inquiries: your@email.com
- * 
- * eventTest.js - Event-Sequence Testing for EventState
- * 
- * Provides TDD-style testing with type extraction capabilities
- */
-
-import { createEventState } from './eventStateNew.js';
-
-export function createEventTest(initialState = {}) {
-  const store = createEventState(initialState);
-  const eventLog = [];
-  const typeAssertions = [];
-
-  // Spy on all events
-  store.subscribe('*', (detail) => {
-    const { path, value } = detail;
-    eventLog.push({ timestamp: Date.now(), path, value });
-  });
-
-  const api = {
-    store,
-
-    // Trigger a state change
-    trigger(path, value) {
-      store.set(path, value);
-      return this;
-    },
-
-    // Assert exact value
-    assertPath(path, expected) {
-      const actual = store.get(path);
-      if (JSON.stringify(actual) !== JSON.stringify(expected)) {
-        throw new Error(`Expected ${path} to be ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
-      }
-      return this;
-    },
-
-    // Assert type (for type generation)
-    assertType(path, expectedType) {
-      const actual = store.get(path);
-      const actualType = typeof actual;
-      
-      if (actualType !== expectedType) {
-        throw new Error(`Expected ${path} to be type ${expectedType}, got ${actualType}`);
-      }
-      
-      // Store for type generation
-      typeAssertions.push({ path, type: expectedType });
-      return this;
-    },
-
-    // Assert array with element shape (for type generation)
-    assertArrayOf(path, elementShape) {
-      const actual = store.get(path);
-      
-      if (!Array.isArray(actual)) {
-        throw new Error(`Expected ${path} to be an array, got ${typeof actual}`);
-      }
-      
-      // Validate first element matches shape (if array not empty)
-      if (actual.length > 0) {
-        validateShape(actual[0], elementShape, path);
-      }
-      
-      // Store for type generation
-      typeAssertions.push({ path, type: 'array', elementShape });
-      return this;
-    },
-
-    // Assert object shape (for type generation)
-    assertShape(path, objectShape) {
-      const actual = store.get(path);
-      
-      if (typeof actual !== 'object' || actual === null || Array.isArray(actual)) {
-        throw new Error(`Expected ${path} to be an object, got ${typeof actual}`);
-      }
-      
-      validateShape(actual, objectShape, path);
-      
-      // Store for type generation
-      typeAssertions.push({ path, type: 'object', shape: objectShape });
-      return this;
-    },
-
-    // Assert array length
-    assertArrayLength(path, expectedLength) {
-      const actual = store.get(path);
-      
-      if (!Array.isArray(actual)) {
-        throw new Error(`Expected ${path} to be an array`);
-      }
-      
-      if (actual.length !== expectedLength) {
-        throw new Error(`Expected ${path} to have length ${expectedLength}, got ${actual.length}`);
-      }
-      
-      return this;
-    },
-
-    // Assert event fired N times
-    assertEventFired(path, times) {
-      const count = eventLog.filter(e => e.path === path).length;
-      if (times !== undefined && count !== times) {
-        throw new Error(`Expected ${path} to fire ${times} times, fired ${count}`);
-      }
-      return this;
-    },
-
-    // Get event log
-    getEventLog() {
-      return [...eventLog];
-    },
-
-    // Get type assertions (for type generation)
-    getTypeAssertions() {
-      return [...typeAssertions];
-    }
-  };
-
-  return api;
-}
-
-// Helper to validate object shape
-function validateShape(actual, shape, path) {
-  for (const [key, expectedType] of Object.entries(shape)) {
-    if (!(key in actual)) {
-      throw new Error(`Expected ${path} to have property ${key}`);
-    }
-    
-    const actualValue = actual[key];
-    
-    // Handle nested objects
-    if (typeof expectedType === 'object' && !Array.isArray(expectedType)) {
-      validateShape(actualValue, expectedType, `${path}.${key}`);
-    } else {
-      // Primitive type check
-      const actualType = typeof actualValue;
-      if (actualType !== expectedType) {
-        throw new Error(`Expected ${path}.${key} to be type ${expectedType}, got ${actualType}`);
-      }
-    }
-  }
-}
-
-// Simple test runner
-export function test(name, fn) {
-  try {
-    fn();
-    console.log(`✓ ${name}`);
-    return true;
-  } catch (error) {
-    console.error(`✗ ${name}`);
-    console.error(`  ${error.message}`);
-    return false;
-  }
-}
-
-// Run multiple tests
-export function runTests(tests) {
-  console.log('\n🧪 Running tests...\n');
-  
-  let passed = 0;
-  let failed = 0;
-  
-  for (const [name, fn] of Object.entries(tests)) {
-    if (test(name, fn)) {
-      passed++;
-    } else {
-      failed++;
-    }
-  }
-  
-  console.log(`\n📊 Results: ${passed} passed, ${failed} failed\n`);
-  
-  return { passed, failed };
-}