@everystate/core 1.0.3 → 1.0.5

package/README.md

@@ -1,4 +1,4 @@
-# @everystate/core
+# @everystate/core v1.0.5
 
 **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
@@ -37,6 +39,66 @@ store.subscribe('user.*', ({ path, value }) => {
 unsub();
 ```
 
+## Self-test (CLI, opt-in)
+
+Run the bundled **zero-dependency** self-test locally to verify core behavior.
+It is **opt-in** and never runs automatically on install:
+
+```bash
+# via npx (no install needed)
+npx everystate-self-test
+
+# if installed locally
+everystate-self-test
+
+# or directly
+node node_modules/@everystate/core/self-test.js
+```
+
+You can also run the npm script from the package folder:
+
+```bash
+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` (declared as `devDependency`). This is an intentional
+tradeoff: the **self-test** stays lightweight, while integration tests
+remain available for deeper validation.
+
+**For end users** (after installing the package):
+
+```bash
+# Install test dependency
+npm install @everystate/test
+
+# Run from package folder
+cd node_modules/@everystate/core
+npm run test:integration
+# or short alias
+npm run test:i
+```
+
+Or, from your project root:
+
+```bash
+npm --prefix node_modules/@everystate/core run test:integration
+# or short alias
+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:
@@ -64,15 +126,6 @@ EveryState makes state **addressable, observable, and testable** without special
 
 ## Ecosystem
 
-- `@everystate/core`: Core state engine (you are here)
-- `@everystate/css`: Reactive styling and design tokens
-- `@everystate/perf`: Performance monitoring overlay
-- `@everystate/react`: React hooks adapter
-- `@everystate/router`: SPA routing as state
-- `@everystate/test`: Zero-dependency testing
-- `@everystate/view`: DOM-as-state with surgical updates
-
-
 | Package | Description | License |
 |---|---|---|
 | [@everystate/aliases](https://www.npmjs.com/package/@everystate/aliases) | Ergonomic single-character and short-name DOM aliases for vanilla JS | MIT |

package/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+/**
+ * @everystate/core CLI (opt-in)
+ *
+ * Usage:
+ *   npx everystate-self-test
+ *   everystate-self-test
+ *   everystate-self-test --self-test
+ */
+
+const args = process.argv.slice(2);
+const wantsHelp = args.includes('-h') || args.includes('--help');
+const wantsSelfTest =
+  args.length === 0 ||
+  args.includes('self-test') ||
+  args.includes('--self-test') ||
+  args.includes('test') ||
+  args.includes('--test');
+
+if (wantsHelp) {
+  console.log(`@everystate/core self-test (opt-in)\n\nUsage:\n  everystate-self-test [--self-test]\n\nNotes:\n  - This command is opt-in and never runs automatically.\n  - It runs a zero-dependency self-test bundled with the package.\n\nFlags:\n  --self-test   Run the bundled self-test (default)\n  -h, --help    Show this help message\n`);
+  process.exit(0);
+}
+
+if (!wantsSelfTest) {
+  console.error('Unknown arguments. Run with --help for usage.');
+  process.exit(1);
+}
+
+(async () => {
+  try {
+    console.log('@everystate/core: running opt-in self-test...');
+    await import('./self-test.js');
+  } catch (error) {
+    console.error('Self-test failed to run.');
+    console.error(error);
+    process.exit(1);
+  }
+})();

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@everystate/core",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "EveryState: Lightweight event-driven state management with path-based subscriptions, wildcards, and async support",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "everystate-self-test": "cli.js"
+  },
   "scripts": {
-    "test": "node self-test.js"
+    "test": "node self-test.js",
+    "self-test": "node self-test.js",
+    "test:integration": "node tests/core.test.js",
+    "test:i": "node tests/core.test.js"
   },
   "keywords": [
     "everystate",
@@ -37,6 +43,10 @@
     "*.d.ts",
     "*.md",
     "*.html",
+    "cli.js",
     "tests/"
-  ]
+  ],
+  "devDependencies": {
+    "@everystate/test": "^1.0.0"
+  }
 }

package/tests/core.test.js

@@ -1,17 +1,17 @@
 /**
- * @everystate/core — eventTest-based integration tests
+ * @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 { createEventTest, runTests } from '@everystate/test';
 import { createEveryState } from '@everystate/core';
 
 const results = runTests({
 
-  // ── batch ─────────────────────────────────────────────────────────
+  // -- batch ---------------------------------------------------------
 
   'batch: coalesces — same-path deduplication': () => {
     const t = createEventTest({ count: 0 });
@@ -80,7 +80,7 @@ const results = runTests({
     store.destroy();
   },
 
-  // ── setMany ───────────────────────────────────────────────────────
+  // -- setMany -------------------------------------------------------
 
   'setMany: plain object': () => {
     const t = createEventTest({});
@@ -116,7 +116,7 @@ const results = runTests({
     t.assertPath('x.z', 'world');
   },
 
-  // ── setAsync ──────────────────────────────────────────────────────
+  // -- setAsync ------------------------------------------------------
 
   'setAsync: batches loading phase writes': () => {
     const store = createEveryState({});
@@ -176,7 +176,7 @@ const results = runTests({
     store.destroy();
   },
 
-  // ── destroy ───────────────────────────────────────────────────────
+  // -- destroy -------------------------------------------------------
 
   'destroy: batch throws after destroy': () => {
     const store = createEveryState({ z: 0 });
@@ -194,7 +194,7 @@ const results = runTests({
     if (!threw) throw new Error('setMany() should throw after destroy');
   },
 
-  // ── core regression ───────────────────────────────────────────────
+  // -- core regression -----------------------------------------------
 
   'core: basic get/set/subscribe': () => {
     const t = createEventTest({ name: 'Alice' });