@everystate/core 1.0.2 → 1.0.3

package/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing to @everystate/core
+
+## Current Contribution Policy
+
+**@everystate/core is currently not accepting external contributions.**
+
+This project represents a focused approach to event-driven state management. I'm maintaining tight control over the architecture and implementation to keep the library lean, coherent, and production-ready.
+
+## How You Can Help
+
+While I'm not accepting code contributions, you can still support the project:
+
+- **Report bugs** via GitHub issues
+- **Share your experience** using EveryState in your projects
+- **Spread the word** about path-based reactive state
+- **Provide feedback** on the API and documentation
+
+## Future Contributions
+
+This policy may evolve as the project matures.
+
+## Questions?
+
+Feel free to open an issue for questions about usage or to report bugs.

package/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @everystate/core
+ *
+ * Path-based reactive state management.
+ */
+
+/** Detail object passed to wildcard and global subscribers */
+export interface ChangeDetail {
+  path: string;
+  value: any;
+  oldValue: any;
+}
+
+/** Unsubscribe function returned by store.subscribe() */
+export type Unsubscribe = () => void;
+
+/** The EveryState store instance */
+export interface EveryStateStore {
+  /**
+   * Get value at a dot-separated path.
+   * Returns entire state if no path is provided.
+   */
+  get(path?: string): any;
+
+  /**
+   * Set value at a dot-separated path and notify subscribers.
+   * @returns The value that was set
+   */
+  set(path: string, value: any): any;
+
+  /**
+   * Run an async fetcher and manage loading/success/error status at `path.status`, `path.data`, `path.error`.
+   * Supports AbortController cancellation.
+   */
+  setAsync(path: string, fetcher: (signal: AbortSignal) => Promise<any>): Promise<any>;
+
+  /**
+   * Cancel an in-flight async operation at path.
+   */
+  cancel(path: string): void;
+
+  /**
+   * Batch multiple set() calls. Subscribers fire once per unique path after the batch completes.
+   * Supports nesting.
+   */
+  batch(fn: () => void): void;
+
+  /**
+   * Set multiple paths atomically.
+   * Accepts a plain object `{ path: value }`, an array of `[path, value]` pairs, or a Map.
+   */
+  setMany(entries: Record<string, any> | [string, any][] | Map<string, any>): void;
+
+  /**
+   * Subscribe to changes at a path.
+   * - Exact path: `handler(value, detail)` fires when that specific path changes.
+   * - Wildcard (`'user.*'`): `handler(detail)` fires when any child of `user` changes.
+   * - Global (`'*'`): `handler(detail)` fires on any change.
+   * @returns Unsubscribe function
+   */
+  subscribe(path: string, handler: (valueOrDetail: any, detail?: ChangeDetail) => void): Unsubscribe;
+
+  /**
+   * Destroy the store, abort all async ops, and clear all subscriptions.
+   */
+  destroy(): void;
+}
+
+/**
+ * Create a new EveryState store.
+ * @param initial - Initial state object (deep-cloned)
+ */
+export function createEveryState(initial?: Record<string, any>): EveryStateStore;
+
+/** Query client wrapper for EveryState async patterns */
+export interface QueryClient {
+  query(key: string, fetcher: (signal: AbortSignal) => Promise<any>): Promise<any>;
+  subscribe(key: string, cb: (value: any) => void): Unsubscribe;
+  subscribeToStatus(key: string, cb: (status: string) => void): Unsubscribe;
+  subscribeToError(key: string, cb: (error: any) => void): Unsubscribe;
+  getData(key: string): any;
+  getStatus(key: string): string | undefined;
+  getError(key: string): any;
+  cancel(key: string): void;
+  invalidate(key: string): void;
+}
+
+/**
+ * Create a QueryClient that wraps an EveryState store with standard query patterns.
+ */
+export function createQueryClient(store: EveryStateStore): QueryClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystate/core",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "EveryState: Lightweight event-driven state management with path-based subscriptions, wildcards, and async support",
   "type": "module",
   "main": "index.js",
@@ -33,9 +33,10 @@
   },
   "homepage": "https://github.com/ImsirovicAjdin/everystate-core#readme",
   "files": [
-    "index.js",
-    "everyState.js",
-    "queryClient.js",
-    "README.md"
+    "*.js",
+    "*.d.ts",
+    "*.md",
+    "*.html",
+    "tests/"
   ]
 }

package/self-test.js

@@ -0,0 +1,292 @@
+/**
+ * @everystate/core self-test
+ *
+ * Standalone test of core EveryState functionality. No dependencies beyond everyState.js.
+ * Runs on `node self-test.js` or as a postinstall hook.
+ */
+
+import { createEveryState } from './everyState.js';
+
+let passed = 0;
+let failed = 0;
+
+function assert(name, condition) {
+  if (condition) {
+    passed++;
+    console.log(`  ✓ ${name}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${name}`);
+  }
+}
+
+console.log('\n1. get / set');
+const s1 = createEveryState({ count: 0, user: { name: 'Alice', age: 30 } });
+
+assert('get: primitive', s1.get('count') === 0);
+assert('get: nested', s1.get('user.name') === 'Alice');
+assert('get: object', s1.get('user')?.name === 'Alice');
+assert('get: entire state', s1.get('')?.count === 0);
+assert('get: missing path → undefined', s1.get('nonexistent') === undefined);
+assert('get: deep missing → undefined', s1.get('user.email') === undefined);
+
+s1.set('count', 5);
+assert('set: primitive', s1.get('count') === 5);
+
+s1.set('user.name', 'Bob');
+assert('set: nested', s1.get('user.name') === 'Bob');
+
+s1.set('user.email', 'bob@example.com');
+assert('set: auto-creates path', s1.get('user.email') === 'bob@example.com');
+
+s1.set('deep.nested.path', 'value');
+assert('set: deep auto-create', s1.get('deep.nested.path') === 'value');
+
+s1.destroy();
+
+console.log('\n2. subscribe: exact path');
+const s2 = createEveryState({ count: 0 });
+let lastValue = null;
+let fireCount = 0;
+
+const unsub = s2.subscribe('count', (value) => {
+  lastValue = value;
+  fireCount++;
+});
+
+s2.set('count', 1);
+assert('subscribe: fires on change', fireCount === 1);
+assert('subscribe: receives value', lastValue === 1);
+
+s2.set('count', 2);
+assert('subscribe: fires again', fireCount === 2);
+assert('subscribe: receives new value', lastValue === 2);
+
+unsub();
+s2.set('count', 3);
+assert('unsubscribe: stops firing', fireCount === 2);
+assert('unsubscribe: value unchanged in handler', lastValue === 2);
+assert('set still works after unsub', s2.get('count') === 3);
+
+s2.destroy();
+
+console.log('\n3. subscribe: wildcard');
+const s3 = createEveryState({ user: { name: 'Alice', age: 30 } });
+let wildcardFires = 0;
+let wildcardDetail = null;
+
+s3.subscribe('user.*', (detail) => {
+  wildcardFires++;
+  wildcardDetail = detail;
+});
+
+s3.set('user.name', 'Bob');
+assert('wildcard: fires on child change', wildcardFires === 1);
+assert('wildcard: detail has path', wildcardDetail?.path === 'user.name');
+assert('wildcard: detail has value', wildcardDetail?.value === 'Bob');
+
+s3.set('user.age', 31);
+assert('wildcard: fires on other child', wildcardFires === 2);
+
+s3.destroy();
+
+console.log('\n4. subscribe: global');
+const s4 = createEveryState({ a: 1, b: { c: 2 } });
+let globalFires = 0;
+
+s4.subscribe('*', () => { globalFires++; });
+
+s4.set('a', 10);
+assert('global: fires on root path', globalFires === 1);
+
+s4.set('b.c', 20);
+assert('global: fires on nested path', globalFires === 2);
+
+s4.destroy();
+
+console.log('\n5. batch');
+const s5 = createEveryState({ x: 0, y: 0 });
+let batchFires = 0;
+s5.subscribe('*', () => { batchFires++; });
+
+s5.batch(() => {
+  s5.set('x', 1);
+  s5.set('y', 2);
+});
+assert('batch: fires after (not during)', batchFires === 2);
+assert('batch: x set', s5.get('x') === 1);
+assert('batch: y set', s5.get('y') === 2);
+
+// Deduplication
+batchFires = 0;
+s5.batch(() => {
+  s5.set('x', 10);
+  s5.set('x', 20);
+  s5.set('x', 30);
+});
+assert('batch: deduplicates same path (1 fire)', batchFires === 1);
+assert('batch: last write wins', s5.get('x') === 30);
+
+// Nested batch
+batchFires = 0;
+s5.batch(() => {
+  s5.set('x', 100);
+  s5.batch(() => {
+    s5.set('y', 200);
+  });
+});
+assert('nested batch: both fire after outermost', batchFires === 2);
+assert('nested batch: x', s5.get('x') === 100);
+assert('nested batch: y', s5.get('y') === 200);
+
+// No notifications during batch
+const seen = [];
+const s5b = createEveryState({ v: 0 });
+s5b.subscribe('v', (val) => seen.push(val));
+s5b.batch(() => {
+  s5b.set('v', 1);
+  s5b.set('v', 2);
+});
+assert('batch: no mid-batch notifications', seen.length === 1);
+assert('batch: final value delivered', seen[0] === 2);
+
+s5.destroy();
+s5b.destroy();
+
+console.log('\n6. setMany');
+const s6 = createEveryState({});
+
+// Plain object
+s6.setMany({ 'a.b': 1, 'a.c': 2 });
+assert('setMany object: a.b', s6.get('a.b') === 1);
+assert('setMany object: a.c', s6.get('a.c') === 2);
+
+// Array of pairs
+s6.setMany([['x.y', 'hello'], ['x.z', 'world']]);
+assert('setMany array: x.y', s6.get('x.y') === 'hello');
+assert('setMany array: x.z', s6.get('x.z') === 'world');
+
+// Map
+s6.setMany(new Map([['m.a', true], ['m.b', false]]));
+assert('setMany Map: m.a', s6.get('m.a') === true);
+assert('setMany Map: m.b', s6.get('m.b') === false);
+
+s6.destroy();
+
+console.log('\n7. destroy');
+const s7 = createEveryState({ z: 0 });
+s7.destroy();
+
+let threw = false;
+try { s7.get('z'); } catch { threw = true; }
+assert('destroy: get throws', threw);
+
+threw = false;
+try { s7.set('z', 1); } catch { threw = true; }
+assert('destroy: set throws', threw);
+
+threw = false;
+try { s7.batch(() => {}); } catch { threw = true; }
+assert('destroy: batch throws', threw);
+
+threw = false;
+try { s7.setMany({ a: 1 }); } catch { threw = true; }
+assert('destroy: setMany throws', threw);
+
+threw = false;
+try { s7.subscribe('z', () => {}); } catch { threw = true; }
+assert('destroy: subscribe throws', threw);
+
+console.log('\n8. subscribe: detail object');
+const s8 = createEveryState({ count: 10 });
+let detail = null;
+s8.subscribe('count', (value, d) => { detail = d; });
+s8.set('count', 20);
+assert('detail: has path', detail?.path === 'count');
+assert('detail: has value', detail?.value === 20);
+assert('detail: has oldValue', detail?.oldValue === 10);
+
+s8.destroy();
+
+console.log('\n9. detail: shared across listener types');
+const s9 = createEveryState({ user: { name: 'Alice' } });
+let s9exact = null;
+let s9wildcard = null;
+let s9global = null;
+
+s9.subscribe('user.name', (value, d) => { s9exact = d; });
+s9.subscribe('user.*', (d) => { s9wildcard = d; });
+s9.subscribe('*', (d) => { s9global = d; });
+
+s9.set('user.name', 'Bob');
+assert('detail shared: exact has detail', s9exact !== null);
+assert('detail shared: wildcard === exact (same ref)', s9wildcard === s9exact);
+assert('detail shared: global === exact (same ref)', s9global === s9exact);
+
+s9.destroy();
+
+console.log('\n10. unsubscribe: Map cleanup (fast-path recovery)');
+const s10 = createEveryState({ x: 0 });
+let s10fires = 0;
+
+const unsub10 = s10.subscribe('x', () => { s10fires++; });
+s10.set('x', 1);
+assert('unsub cleanup: fires while subscribed', s10fires === 1);
+
+unsub10();
+s10.set('x', 2);
+assert('unsub cleanup: stops firing after unsub', s10fires === 1);
+assert('unsub cleanup: value still written', s10.get('x') === 2);
+
+// Re-subscribe to same path after full cleanup
+let s10fires2 = 0;
+const unsub10b = s10.subscribe('x', () => { s10fires2++; });
+s10.set('x', 3);
+assert('unsub cleanup: re-subscribe works after cleanup', s10fires2 === 1);
+
+unsub10b();
+s10.destroy();
+
+console.log('\n11. fast-path: no detail allocated without listeners');
+const s11 = createEveryState({ a: 0 });
+let s11fires = 0;
+
+// set with zero subscribers — fast-path should skip all dispatch
+s11.set('a', 1);
+s11.set('a', 2);
+s11.set('a', 3);
+assert('fast-path: value written without subscribers', s11.get('a') === 3);
+
+// subscribe, fire, unsub, then set again — fast-path should re-engage
+const unsub11 = s11.subscribe('a', () => { s11fires++; });
+s11.set('a', 4);
+assert('fast-path: fires with subscriber', s11fires === 1);
+
+unsub11();
+s11fires = 0;
+s11.set('a', 5);
+assert('fast-path: no fire after full unsub', s11fires === 0);
+assert('fast-path: value still written after full unsub', s11.get('a') === 5);
+
+s11.destroy();
+
+console.log('\n12. wildcard-only: detail allocated for wildcard without exact');
+const s12 = createEveryState({ user: { name: 'Alice' } });
+let s12detail = null;
+
+// Only wildcard subscriber, no exact subscriber for user.name
+s12.subscribe('user.*', (d) => { s12detail = d; });
+s12.set('user.name', 'Bob');
+assert('wildcard-only: detail created', s12detail !== null);
+assert('wildcard-only: detail.path correct', s12detail?.path === 'user.name');
+assert('wildcard-only: detail.value correct', s12detail?.value === 'Bob');
+assert('wildcard-only: detail.oldValue correct', s12detail?.oldValue === 'Alice');
+
+s12.destroy();
+
+// Results
+
+console.log(`\n@everystate/core v1.0.0 self-test`);
+console.log(`✓ ${passed} assertions passed${failed ? `, ✗ ${failed} failed` : ''}\n`);
+
+if (failed > 0) process.exit(1);

package/tests/core.test.js

@@ -0,0 +1,237 @@
+/**
+ * @everystate/core — eventTest-based integration tests
+ *
+ * Merged from test-batch.js and test-batch-dogfood.js.
+ * Tests batch, setMany, setAsync, destroy, and core regression tests
+ * using @everystate/event-test.
+ */
+
+import { createEventTest, runTests } from '@everystate/event-test';
+import { createEveryState } from '@everystate/core';
+
+const results = runTests({
+
+  // ── batch ─────────────────────────────────────────────────────────
+
+  'batch: coalesces — same-path deduplication': () => {
+    const t = createEventTest({ count: 0 });
+    t.store.batch(() => {
+      t.trigger('count', 1);
+      t.trigger('count', 2);
+      t.trigger('count', 3);
+    });
+    t.assertPath('count', 3);
+    t.assertEventFired('count', 1);
+  },
+
+  'batch: fires once per unique path after flush': () => {
+    const t = createEventTest({ user: { name: 'Alice', email: 'a@b.com' } });
+    t.store.batch(() => {
+      t.trigger('user.name', 'Bob');
+      t.trigger('user.email', 'bob@b.com');
+    });
+    t.assertPath('user.name', 'Bob');
+    t.assertPath('user.email', 'bob@b.com');
+    t.assertEventFired('user.name', 1);
+    t.assertEventFired('user.email', 1);
+  },
+
+  'batch: no notifications during, only after': () => {
+    const store = createEveryState({ x: 0 });
+    const seen = [];
+    store.subscribe('x', (v) => seen.push(v));
+    store.batch(() => {
+      store.set('x', 1);
+      if (seen.length !== 0) throw new Error('Notification fired during batch');
+      store.set('x', 2);
+      if (seen.length !== 0) throw new Error('Notification fired during batch');
+    });
+    if (seen.length !== 1) throw new Error(`Expected 1 notification after batch, got ${seen.length}`);
+    if (seen[0] !== 2) throw new Error(`Expected final value 2, got ${seen[0]}`);
+    store.destroy();
+  },
+
+  'batch: nested — only outermost flushes': () => {
+    const t = createEventTest({ a: 0, b: 0 });
+    t.store.batch(() => {
+      t.trigger('a', 1);
+      t.store.batch(() => {
+        t.trigger('b', 2);
+      });
+    });
+    t.assertPath('a', 1);
+    t.assertPath('b', 2);
+    t.assertEventFired('a', 1);
+    t.assertEventFired('b', 1);
+  },
+
+  'batch: get() during batch reads committed state (not buffer)': () => {
+    const store = createEveryState({ v: 'old' });
+    store.batch(() => {
+      store.set('v', 'new');
+      const read = store.get('v');
+      if (read !== 'old') {
+        throw new Error(`get() during batch should read committed state, got "${read}"`);
+      }
+    });
+    if (store.get('v') !== 'new') {
+      throw new Error('After batch, get() should read new value');
+    }
+    store.destroy();
+  },
+
+  // ── setMany ───────────────────────────────────────────────────────
+
+  'setMany: plain object': () => {
+    const t = createEventTest({});
+    t.store.setMany({
+      'ui.route.view': 'home',
+      'ui.route.path': '/',
+      'ui.route.params': {},
+    });
+    t.assertPath('ui.route.view', 'home');
+    t.assertPath('ui.route.path', '/');
+    t.assertType('ui.route.view', 'string');
+    t.assertType('ui.route.path', 'string');
+    t.assertShape('ui.route.params', {});
+  },
+
+  'setMany: array of [path, value] pairs': () => {
+    const t = createEventTest({});
+    t.store.setMany([
+      ['a.b', 1],
+      ['a.c', 2],
+    ]);
+    t.assertPath('a.b', 1);
+    t.assertPath('a.c', 2);
+    t.assertType('a.b', 'number');
+    t.assertType('a.c', 'number');
+  },
+
+  'setMany: Map': () => {
+    const t = createEventTest({});
+    const m = new Map([['x.y', 'hello'], ['x.z', 'world']]);
+    t.store.setMany(m);
+    t.assertPath('x.y', 'hello');
+    t.assertPath('x.z', 'world');
+  },
+
+  // ── setAsync ──────────────────────────────────────────────────────
+
+  'setAsync: batches loading phase writes': () => {
+    const store = createEveryState({});
+    let wildcardFires = 0;
+    store.subscribe('users.*', () => { wildcardFires++; });
+
+    const promise = store.setAsync('users', async (signal) => {
+      return [{ id: 1, name: 'Alice' }];
+    });
+
+    if (wildcardFires !== 2) {
+      throw new Error(`Loading phase: expected 2 wildcard fires, got ${wildcardFires}`);
+    }
+    if (store.get('users.status') !== 'loading') {
+      throw new Error(`Expected status=loading, got ${store.get('users.status')}`);
+    }
+    if (store.get('users.error') !== null) {
+      throw new Error(`Expected error=null, got ${store.get('users.error')}`);
+    }
+
+    promise.catch(() => {});
+    store.destroy();
+  },
+
+  'setAsync: batches success phase writes': async () => {
+    const store = createEveryState({});
+    await store.setAsync('data', async () => ({ result: 42 }));
+
+    if (store.get('data.status') !== 'success') {
+      throw new Error(`Expected status=success, got ${store.get('data.status')}`);
+    }
+    if (store.get('data.data')?.result !== 42) {
+      throw new Error('Expected data.result=42');
+    }
+    store.destroy();
+  },
+
+  'setAsync: full wildcard fire count': async () => {
+    const store = createEveryState({});
+    let wildcardFires = 0;
+    store.subscribe('users.*', () => { wildcardFires++; });
+
+    await store.setAsync('users', async (signal) => {
+      return [{ id: 1, name: 'Alice' }];
+    });
+
+    // Loading: status+error = 2, Success: data+status = 2, Total = 4
+    if (wildcardFires !== 4) {
+      throw new Error(`Expected 4 wildcard fires, got ${wildcardFires}`);
+    }
+    if (store.get('users.status') !== 'success') {
+      throw new Error(`Expected status=success`);
+    }
+    if (!Array.isArray(store.get('users.data'))) {
+      throw new Error('Expected data to be array');
+    }
+    store.destroy();
+  },
+
+  // ── destroy ───────────────────────────────────────────────────────
+
+  'destroy: batch throws after destroy': () => {
+    const store = createEveryState({ z: 0 });
+    store.destroy();
+    let threw = false;
+    try { store.batch(() => {}); } catch { threw = true; }
+    if (!threw) throw new Error('batch() should throw after destroy');
+  },
+
+  'destroy: setMany throws after destroy': () => {
+    const store = createEveryState({ z: 0 });
+    store.destroy();
+    let threw = false;
+    try { store.setMany({ a: 1 }); } catch { threw = true; }
+    if (!threw) throw new Error('setMany() should throw after destroy');
+  },
+
+  // ── core regression ───────────────────────────────────────────────
+
+  'core: basic get/set/subscribe': () => {
+    const t = createEventTest({ name: 'Alice' });
+    t.trigger('name', 'Bob');
+    t.assertPath('name', 'Bob');
+    t.assertType('name', 'string');
+    t.assertEventFired('name', 1);
+  },
+
+  'core: wildcard subscription': () => {
+    const t = createEventTest({ user: { name: 'Alice', age: 30 } });
+    t.trigger('user.name', 'Bob');
+    t.trigger('user.age', 31);
+    t.assertPath('user.name', 'Bob');
+    t.assertPath('user.age', 31);
+  },
+
+  'core: nested path auto-creation': () => {
+    const t = createEventTest({});
+    t.trigger('deep.nested.path', 'value');
+    t.assertPath('deep.nested.path', 'value');
+    t.assertType('deep.nested.path', 'string');
+  },
+
+  'core: type assertions for type generation': () => {
+    const t = createEventTest({
+      count: 0,
+      user: { name: 'Alice', active: true },
+      items: [{ id: 1, text: 'Todo' }],
+    });
+    t.assertType('count', 'number');
+    t.assertShape('user', { name: 'string', active: 'boolean' });
+    t.assertArrayOf('items', { id: 'number', text: 'string' });
+
+    const types = t.getTypeAssertions();
+    if (types.length !== 3) throw new Error(`Expected 3 type assertions, got ${types.length}`);
+  },
+});
+
+if (results.failed > 0) process.exit(1);