@everystate/core 1.0.4 → 1.0.6

package/README.md

@@ -1,4 +1,4 @@
-# @everystate/core
+# @everystate/core v1.0.6
 
 **EveryState: Observable state management with dot-path addressing**
 
@@ -10,6 +10,8 @@ Every piece of state has a name. Every name is subscribable. Every operation is
 npm install @everystate/core
 ```
 
+> **Zero external dependencies** - Pure state management with no third-party packages required.
+
 ## Quick Start
 
 ```js
@@ -33,6 +35,14 @@ store.subscribe('user.*', ({ path, value }) => {
   console.log(`User field ${path} changed to:`, value);
 });
 
+// Check if a path exists (handles intentional undefined)
+store.has('count');        // true
+store.has('nonexistent');  // false
+
+// List all leaf paths under a prefix
+store.keys('user');        // ['user.name']
+store.keys();              // ['count', 'user.name']
+
 // Cleanup
 unsub();
 ```
@@ -62,20 +72,17 @@ npm --prefix node_modules/@everystate/core run self-test
 ### Integration tests (@everystate/test)
 
 The `tests/` folder contains a separate integration suite that uses
-`@everystate/test` (not zero-dep). This is an intentional tradeoff:
-the **self-test** stays lightweight, while integration tests remain available
-for deeper validation.
+`@everystate/test` (declared as `devDependency`). This is an intentional
+tradeoff: the **self-test** stays lightweight, while integration tests
+remain available for deeper validation.
 
-Run the integration suite (opt-in):
+**For end users** (after installing the package):
 
 ```bash
+# Install test dependency
 npm install @everystate/test
-node node_modules/@everystate/core/tests/core.test.js
-```
-
-Short form (from the package folder):
 
-```bash
+# Run from package folder
 cd node_modules/@everystate/core
 npm run test:integration
 # or short alias
@@ -90,6 +97,16 @@ npm --prefix node_modules/@everystate/core run test:integration
 npm --prefix node_modules/@everystate/core run test:i
 ```
 
+**For package developers** (working in the source repo):
+
+```bash
+# Install dev dependencies first
+npm install
+
+# Run integration tests
+npm run test:integration
+```
+
 ## What is EveryState?
 
 EveryState is a reactive state management library where:
@@ -103,6 +120,7 @@ EveryState is a reactive state management library where:
 - **Path-based subscriptions**: Subscribe to exactly what you need
 - **Wildcard support**: `user.*` catches all user changes
 - **Atomic batching**: Multiple writes, single notification per path
+- **Path introspection**: `has()` and `keys()` for runtime path discovery
 - **Zero dependencies**: ~2KB minified
 - **Framework-agnostic**: Works with React, Vue, Angular, Svelte, or vanilla JS
 

package/everyState.js

@@ -142,6 +142,57 @@ export function createEveryState(initial = {}) {
       return cur;
     },
 
+    /**
+     * Check if a path exists in the store.
+     * Unlike get(path) !== undefined, this correctly handles
+     * paths whose value is intentionally set to undefined.
+     * @param {string} path - Dot-separated path
+     * @returns {boolean} true if the path exists
+     */
+    has(path) {
+      if (destroyed) throw new Error('Cannot check destroyed store');
+      if (!path) return true;
+      const parts = path.split('.');
+      let cur = state;
+      for (const p of parts) {
+        if (cur == null || typeof cur !== 'object' || !(p in cur)) return false;
+        cur = cur[p];
+      }
+      return true;
+    },
+
+    /**
+     * List all leaf paths under a prefix.
+     * @param {string} [prefix] - Dot-separated prefix (e.g., 'css').
+     *   If omitted, lists all paths in the entire store.
+     * @returns {string[]} Array of dot-separated leaf paths
+     */
+    keys(prefix) {
+      if (destroyed) throw new Error('Cannot list keys of destroyed store');
+      let root = state;
+      let base = '';
+      if (prefix) {
+        base = prefix;
+        const parts = prefix.split('.');
+        for (const p of parts) {
+          if (root == null || typeof root !== 'object' || !(p in root)) return [];
+          root = root[p];
+        }
+      }
+      const result = [];
+      function walk(obj, path) {
+        if (obj == null || typeof obj !== 'object') {
+          result.push(path);
+          return;
+        }
+        for (const k of Object.keys(obj)) {
+          walk(obj[k], path ? `${path}.${k}` : k);
+        }
+      }
+      walk(root, base);
+      return result;
+    },
+
     /**
      * Set value at path and notify subscribers
      * @param {string} path - Dot-separated path (e.g., 'user.profile.name')

package/index.d.ts

@@ -22,6 +22,18 @@ export interface EveryStateStore {
    */
   get(path?: string): any;
 
+  /**
+   * Check if a path exists in the store.
+   * Unlike `get(path) !== undefined`, correctly handles intentionally-stored undefined.
+   */
+  has(path: string): boolean;
+
+  /**
+   * List all leaf paths under a prefix.
+   * If no prefix is provided, lists all paths in the entire store.
+   */
+  keys(prefix?: string): string[];
+
   /**
    * Set value at a dot-separated path and notify subscribers.
    * @returns The value that was set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystate/core",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "EveryState: Lightweight event-driven state management with path-based subscriptions, wildcards, and async support",
   "type": "module",
   "main": "index.js",
@@ -45,5 +45,8 @@
     "*.html",
     "cli.js",
     "tests/"
-  ]
+  ],
+  "devDependencies": {
+    "@everystate/test": "^1.0.0"
+  }
 }

package/self-test.js

@@ -284,9 +284,72 @@ assert('wildcard-only: detail.oldValue correct', s12detail?.oldValue === 'Alice'
 
 s12.destroy();
 
+console.log('\n13. has()');
+const s13 = createEveryState({ count: 0, user: { name: 'Alice' }, empty: undefined });
+
+assert('has: existing primitive', s13.has('count') === true);
+assert('has: existing nested', s13.has('user.name') === true);
+assert('has: existing parent', s13.has('user') === true);
+assert('has: missing path', s13.has('nonexistent') === false);
+assert('has: deep missing', s13.has('user.email') === false);
+assert('has: deep missing parent', s13.has('a.b.c') === false);
+assert('has: no path returns true', s13.has('') === true);
+
+// set undefined intentionally, then check
+s13.set('maybe', undefined);
+assert('has: intentionally undefined', s13.has('maybe') === true);
+
+// destroyed store
+s13.destroy();
+let threwHas = false;
+try { s13.has('count'); } catch { threwHas = true; }
+assert('has: destroyed throws', threwHas);
+
+console.log('\n14. keys()');
+const s14 = createEveryState({ count: 0, user: { name: 'Alice', age: 30 }, flag: true });
+
+// All keys
+const allKeys = s14.keys();
+assert('keys: returns array', Array.isArray(allKeys));
+assert('keys: has count', allKeys.includes('count'));
+assert('keys: has user.name', allKeys.includes('user.name'));
+assert('keys: has user.age', allKeys.includes('user.age'));
+assert('keys: has flag', allKeys.includes('flag'));
+assert('keys: no parent objects', !allKeys.includes('user'));
+assert('keys: correct count', allKeys.length === 4);
+
+// Prefix
+const userKeys = s14.keys('user');
+assert('keys(prefix): returns children', userKeys.length === 2);
+assert('keys(prefix): has user.name', userKeys.includes('user.name'));
+assert('keys(prefix): has user.age', userKeys.includes('user.age'));
+
+// Missing prefix
+const missing = s14.keys('nonexistent');
+assert('keys(missing): empty array', missing.length === 0);
+
+// Deep prefix
+s14.set('a.b.c', 1);
+s14.set('a.b.d', 2);
+s14.set('a.e', 3);
+const aKeys = s14.keys('a');
+assert('keys(deep prefix): a has 3 leaves', aKeys.length === 3);
+assert('keys(deep prefix): a.b.c', aKeys.includes('a.b.c'));
+assert('keys(deep prefix): a.b.d', aKeys.includes('a.b.d'));
+assert('keys(deep prefix): a.e', aKeys.includes('a.e'));
+
+const abKeys = s14.keys('a.b');
+assert('keys(deep prefix): a.b has 2 leaves', abKeys.length === 2);
+
+// Destroyed store
+s14.destroy();
+let threwKeys = false;
+try { s14.keys(); } catch { threwKeys = true; }
+assert('keys: destroyed throws', threwKeys);
+
 // Results
 
-console.log(`\n@everystate/core v1.0.0 self-test`);
+console.log(`\n@everystate/core v1.0.6 self-test`);
 console.log(`✓ ${passed} assertions passed${failed ? `, ✗ ${failed} failed` : ''}\n`);
 
 if (failed > 0) process.exit(1);