@stonyx/events 0.1.1-beta.0 → 0.1.1-beta.10

package/.claude/improvements.md

@@ -0,0 +1,21 @@
+# @stonyx/events - Improvement Opportunities
+
+## Orphaned config/environment.js reference
+
+**Status**: Documentation / .gitignore reference with no actual file
+
+The `.gitignore` includes `config/environment.js`, and the old `.claude/index.md` documented an `EVENTS_LOG` env var and a `config/environment.js` file. However, neither the file nor the directory exists, and no source code reads `EVENTS_LOG` or any configuration.
+
+**Options**:
+1. **Remove the reference** -- delete the `config/environment.js` line from `.gitignore` since there is nothing to ignore.
+2. **Create the file** -- if debug logging is planned, implement `config/environment.js` and wire it into `src/main.js`.
+
+## Overly broad `"files"` field in package.json
+
+**Current**: `"files": ["*"]`
+
+This tells npm to publish every file in the repo (except those in `.npmignore`). The `.npmignore` only excludes `test/` and `.nvmrc`, so the published package will include `.github/`, `.claude/`, `.gitignore`, `pnpm-lock.yaml`, and other development-only files.
+
+**Options**:
+1. **Use more specific globs** -- e.g., `"files": ["src/", "LICENSE.md", "README.md"]` to ship only what consumers need.
+2. **Remove the field entirely** -- npm's default behavior already includes `package.json`, `README.md`, `LICENSE.md`, and the `main`/`exports` entry points, which is likely sufficient.

package/.claude/project-structure.md

@@ -1,5 +1,10 @@
 # @stonyx/events - Project Structure & Architecture
 
+## Detailed Guides
+
+- [Testing Guidelines](./testing.md) — Test structure, patterns, and coverage areas
+- [Improvements](./improvements.md) — Documented improvement opportunities
+
 ## Project Overview
 
 **@stonyx/events** is a lightweight pub/sub event system for the Stonyx framework. It provides a singleton-based event management system with error isolation, async support, and type-safe event registration.
@@ -46,24 +51,23 @@
 stonyx-events/
 ├── .github/
 │   └── workflows/
-│       └── ci.yml              # GitHub Actions CI pipeline
+│       ├── ci.yml                # GitHub Actions CI pipeline
+│       └── publish.yml           # NPM publish workflow (alpha + stable)
 ├── .claude/
-│   ├── settings.local.json     # Claude Code permissions
-│   └── project-structure.md    # This file
-├── config/
-│   └── environment.js          # Environment configuration
+│   ├── project-structure.md      # This file
+│   ├── testing.md                # Testing guidelines
+│   └── improvements.md           # Improvement opportunities
 ├── src/
-│   └── main.js                 # Events class implementation
+│   └── main.js                   # Events class implementation
 ├── test/
 │   └── unit/
-│       └── events-test.js      # QUnit tests for Events
-├── .gitignore                  # Git ignore patterns
-├── .npmignore                  # NPM ignore patterns
-├── .nvmrc                      # Node version specification
-├── LICENSE.md                  # Apache 2.0 license
-├── README.md                   # User-facing documentation
-├── package.json                # NPM package configuration
-└── stonyx-bootstrap.cjs        # CommonJS bootstrap for testing
+│       └── events-test.js        # QUnit tests for Events
+├── .gitignore                    # Git ignore patterns
+├── .npmignore                    # NPM ignore patterns
+├── .nvmrc                        # Node version specification
+├── LICENSE.md                    # Apache 2.0 license
+├── README.md                     # User-facing documentation
+└── package.json                  # NPM package configuration
 ```
 
 ## Core Components Deep Dive
@@ -134,12 +138,8 @@ The Events class is the heart of the module, providing all pub/sub functionality
 
 ## Dependencies & Integration
 
-### Direct Dependencies
-
-**stonyx** (file:../stonyx)
-- Core Stonyx framework
-- Provides base configuration and bootstrapping
-- Required for module initialization
+### Production Dependencies
+None. This module has zero production dependencies.
 
 ### Dev Dependencies
 
@@ -148,7 +148,7 @@ The Events class is the heart of the module, providing all pub/sub functionality
 
 **qunit** (^2.24.1)
 - Testing framework
-- Runs via CLI with stonyx-bootstrap.cjs
+- Runs via `pnpm test` (which invokes `qunit`)
 
 **sinon** (^21.0.0)
 - Mocking/stubbing library
@@ -166,122 +166,35 @@ The Events class is the heart of the module, providing all pub/sub functionality
 ### Module System
 - ES Modules throughout
 - Default export for Events class
-- No named exports (single-purpose module)
+- Named convenience exports: `setup`, `subscribe`, `once`, `unsubscribe`, `emit`, `clear`, `reset`
 
 ### Error Handling
 - Validation errors throw immediately
 - Runtime errors in handlers are caught and logged
 - No silent failures
 
-### Logging
-- Environment variable: `EVENTS_LOG` (currently unused in implementation)
-- Configuration prepared in `config/environment.js`
-- Future: Could add debug logging for emit/subscribe events
-
 ### Naming Conventions
 - Event names: camelCase strings (e.g., 'userLogin', 'dataChange')
 - Method names: lowercase verbs (setup, subscribe, emit)
 - Private instance variables: None (all properties public for testing)
 
-## Testing Guidelines
-
-### Test Structure
-- All tests in `test/unit/events-test.js`
-- QUnit module: `[Unit] Events`
-- 18 test cases covering all functionality
-- Each test calls `events.reset()` before and after
-
-### Test Patterns
-
-**Singleton Isolation**
-```javascript
-const events = new Events();
-events.reset(); // Clear any previous state
-// ... test code ...
-events.reset(); // Clean up after test
-```
-
-**Async Testing**
-```javascript
-test('description', async function (assert) {
-  // Use async/await for emit()
-  await events.emit('event');
-  assert.ok(condition);
-});
-```
-
-**Error Suppression**
-```javascript
-const originalConsoleError = console.error;
-console.error = () => {}; // Suppress expected errors
-// ... test code ...
-console.error = originalConsoleError; // Restore
-```
-
-### Coverage Areas
-1. Event registration (setup)
-2. Subscription management (subscribe, unsubscribe)
-3. Event emission (emit)
-4. One-time subscriptions (once)
-5. Error isolation
-6. Async support
-7. Singleton behavior
-8. Edge cases (unregistered events, no subscribers)
-
-## Extension Points
-
-While the Events system is intentionally minimal, potential future enhancements include:
-
-### Event Priorities
-- Add priority levels for subscribers
-- Execute high-priority handlers first
-- Use case: Logging before business logic
-
-### Wildcard Events
-- Support pattern matching (e.g., 'user:*')
-- Subscribe to multiple events at once
-- Use case: Debugging, logging all events
-
-### Event History
-- Optional recording of emitted events
-- Replay functionality for debugging
-- Use case: Time-travel debugging, audit logs
-
-### Middleware
-- Pre/post-emit hooks
-- Event transformation pipeline
-- Use case: Validation, logging, metrics
-
-## Configuration Reference
-
-### Environment Variables
-
-**EVENTS_LOG**
-- Type: Boolean (truthy/falsy)
-- Default: `false`
-- Purpose: Enable debug logging (not yet implemented)
-- Usage: `EVENTS_LOG=true npm test`
+## Package Exports
 
-### config/environment.js
+### Default Export
 
 ```javascript
-{
-  log: EVENTS_LOG ?? false,  // Debug logging flag
-  logColor: '#888',           // Color for log output
-}
+import Events from '@stonyx/events';
 ```
 
-Currently, these config values are prepared but not used in the Events implementation. They provide a foundation for future debug logging features.
+The Events class.
 
-## Package Exports
-
-### Main Export
+### Named Convenience Exports
 
 ```javascript
-import Events from '@stonyx/events';
+import { setup, subscribe, once, unsubscribe, emit, clear, reset } from '@stonyx/events';
 ```
 
-The package exports a single default export: the Events class.
+All convenience functions use a singleton Events instance internally, providing a cleaner API without needing to instantiate the class.
 
 ### Usage Pattern
 
@@ -304,59 +217,14 @@ events.emit('userLogin', { id: 1, name: 'Alice' });
 await events.emit('userLogin', { id: 1, name: 'Alice' });
 ```
 
-## Development Workflow
-
-### Local Development
-
-1. **Install dependencies**
-   ```bash
-   cd /Users/mstonepc/Repos/abofs
-   ./linker.sh local  # Link all local Stonyx modules
-   cd stonyx-events
-   npm install
-   ```
-
-2. **Run tests**
-   ```bash
-   npm test
-   ```
-
-3. **Make changes**
-   - Edit `src/main.js` for implementation
-   - Edit `test/unit/events-test.js` for tests
-   - Follow TDD: Write failing test, implement feature, verify
-
-### Test-Driven Development
-
-The module follows TDD principles:
-1. Write a failing test for new functionality
-2. Implement the minimum code to pass the test
-3. Refactor while keeping tests green
-4. Ensure all tests pass before committing
-
-### CI/CD Pipeline
+### Convenience Exports Usage
 
-**GitHub Actions** (`.github/workflows/ci.yml`)
-- Triggers on PRs to `dev` and `main` branches
-- Uses pnpm for package management
-- Runs `pnpm test` to verify all tests pass
-- Cancels previous runs on new commits
-
-### Publishing Workflow
-
-1. **Version bump**
-   ```bash
-   npm version patch|minor|major
-   ```
-
-2. **Publish to NPM**
-   ```bash
-   npm publish
-   ```
-
-3. **Update dependents**
-   - Update `@stonyx/orm` to use published version
-   - Update other modules as needed
+```javascript
+import { setup, subscribe, emit } from '@stonyx/events';
+setup(['myEvent']);
+subscribe('myEvent', handler);
+emit('myEvent', data);
+```
 
 ## Common Pitfalls & Gotchas
 
@@ -385,29 +253,6 @@ The module follows TDD principles:
 - **Solution**: Use different function instances for multiple subscriptions
 - **Note**: This is by design to prevent accidental duplicate subscriptions
 
-## Future Enhancement Opportunities
-
-### Performance Optimizations
-- Lazy initialization of event subscriber sets
-- Debouncing/throttling for high-frequency events
-- Event batching for bulk updates
-
-### Developer Experience
-- TypeScript definitions for type-safe event names and payloads
-- Debug mode with detailed logging
-- Event visualization/monitoring tools
-
-### Advanced Features
-- Event namespacing (e.g., 'user:login:success')
-- Event bubbling/capturing (DOM-like event propagation)
-- Async middleware pipeline
-- Event replay for debugging
-
-### Integration
-- Automatic event logging to @stonyx/logger (when it exists)
-- Metrics/telemetry integration
-- Event persistence for audit trails
-
 ## Related Resources
 
 - [Stonyx Framework](https://github.com/abofs/stonyx)
@@ -415,7 +260,3 @@ The module follows TDD principles:
 - [Sinon.js Documentation](https://sinonjs.org/)
 - [Node.js ES Modules](https://nodejs.org/api/esm.html)
 - [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0)
-
----
-
-This document is maintained by the Stonyx team and should be updated whenever architectural changes are made to the @stonyx/events module.

package/.claude/testing.md

@@ -0,0 +1,44 @@
+# @stonyx/events - Testing Guidelines
+
+## Test Structure
+- All tests in `test/unit/events-test.js`
+- QUnit module: `[Unit] Events`
+- 17 test cases covering all functionality
+- Each test calls `events.reset()` before and after
+
+## Test Patterns
+
+### Singleton Isolation
+```javascript
+const events = new Events();
+events.reset(); // Clear any previous state
+// ... test code ...
+events.reset(); // Clean up after test
+```
+
+### Async Testing
+```javascript
+test('description', async function (assert) {
+  // Use async/await for emit()
+  await events.emit('event');
+  assert.ok(condition);
+});
+```
+
+### Error Suppression
+```javascript
+const originalConsoleError = console.error;
+console.error = () => {}; // Suppress expected errors
+// ... test code ...
+console.error = originalConsoleError; // Restore
+```
+
+## Coverage Areas
+1. Event registration (setup)
+2. Subscription management (subscribe, unsubscribe)
+3. Event emission (emit)
+4. One-time subscriptions (once)
+5. Error isolation
+6. Async support
+7. Singleton behavior
+8. Edge cases (unregistered events, no subscribers)

package/.github/workflows/publish.yml

@@ -1,6 +1,8 @@
 name: Publish to NPM
 
 on:
+  repository_dispatch:
+    types: [cascade-publish]
   workflow_dispatch:
     inputs:
       version-type:
@@ -17,10 +19,14 @@ on:
         type: string
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: [main, dev]
+    branches: [main]
   push:
     branches: [main]
 
+concurrency:
+  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
   id-token: write
@@ -28,8 +34,18 @@ permissions:
 
 jobs:
   publish:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
     uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
     with:
       version-type: ${{ github.event.inputs.version-type }}
       custom-version: ${{ github.event.inputs.custom-version }}
+      cascade-source: ${{ github.event.client_payload.source_package || '' }}
+    secrets: inherit
+
+  cascade:
+    needs: publish
+    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
+    with:
+      package-name: ${{ needs.publish.outputs.package-name }}
+      published-version: ${{ needs.publish.outputs.published-version }}
     secrets: inherit

package/.npmignore

@@ -1,2 +1,5 @@
 test/
 .nvmrc
+
+# git
+.git

package/README.md

@@ -19,36 +19,65 @@ npm install @stonyx/events
 
 ## Usage
 
-```javascript
-import Events from '@stonyx/events';
+### Option 1: Convenience Functions (Recommended)
 
-const events = new Events();
+The package exports convenience functions that use a singleton instance:
+
+```javascript
+import { setup, subscribe, emit, once } from '@stonyx/events';
 
 // Register available events
-events.setup(['userLogin', 'userLogout', 'dataChange']);
+setup(['userLogin', 'userLogout', 'dataChange']);
 
 // Subscribe to events
-events.subscribe('userLogin', (user) => {
+subscribe('userLogin', (user) => {
   console.log(`${user.name} logged in`);
 });
 
 // Subscribe once (auto-unsubscribe after first fire)
-events.once('dataChange', () => {
+once('dataChange', () => {
   console.log('Data changed for the first time');
 });
 
 // Emit events
-events.emit('userLogin', { name: 'Alice' });
+emit('userLogin', { name: 'Alice' });
 
 // Unsubscribe
-const unsub = events.subscribe('userLogout', handler);
+const unsub = subscribe('userLogout', handler);
 unsub(); // Remove subscription
 ```
 
+### Option 2: Class-based (Advanced)
+
+You can also instantiate the Events class directly for more control:
+
+```javascript
+import Events from '@stonyx/events';
+
+const events = new Events();
+
+// Register available events
+events.setup(['userLogin', 'userLogout', 'dataChange']);
+
+// Subscribe to events
+events.subscribe('userLogin', (user) => {
+  console.log(`${user.name} logged in`);
+});
+
+// Emit events
+events.emit('userLogin', { name: 'Alice' });
+```
+
+**Note:** The Events class uses a singleton pattern, so all instances share the same event registry.
+
 ## API Reference
 
-| Method | Parameters | Description |
-|--------|-----------|-------------|
+### Convenience Functions (Exported)
+
+All functions use a singleton Events instance:
+
+| Function | Parameters | Description |
+|----------|-----------|-------------|
 | `setup()` | `eventNames: string[]` | Register available event names. Events must be registered before subscribing. |
 | `subscribe()` | `event: string, callback: Function` | Subscribe to an event. Returns an unsubscribe function. |
 | `once()` | `event: string, callback: Function` | Subscribe to an event once. Auto-unsubscribes after first emit. |
@@ -57,16 +86,26 @@ unsub(); // Remove subscription
 | `clear()` | `event: string` | Remove all subscriptions for an event. |
 | `reset()` | none | Clear all subscriptions and events. Useful for testing. |
 
-## How It Works
+### Events Class Methods
 
-The Events class provides a lightweight pub/sub system with the following features:
+If using the class directly, all methods above are available as instance methods:
 
-- **Event Registration**: Events must be registered with `setup()` before use, ensuring type safety
-- **Singleton Pattern**: Single Events instance shared across your application
-- **Async Support**: Event handlers can be async functions
-- **Error Isolation**: Errors in one handler don't affect others or prevent other handlers from running
-- **One-time Subscriptions**: Use `once()` for handlers that should only fire once
-- **Unsubscribe**: All subscriptions return an unsubscribe function for cleanup
+```javascript
+import Events from '@stonyx/events';
+const events = new Events();
+
+events.setup(['myEvent']);
+events.subscribe('myEvent', handler);
+events.emit('myEvent', data);
+```
+
+## How It Works
+
+- The `Events` class uses a static `instance` property to enforce a singleton -- every `new Events()` returns the same object
+- Event names are held in a `registeredEvents` Set; subscribing to an unregistered name throws immediately, catching typos early
+- Subscribers are stored in a `Map<string, Set<Function>>`, so duplicate function references are automatically deduplicated
+- `emit()` is async: it maps every subscriber into a `Promise`, wraps each in a try/catch for error isolation, and awaits them all with `Promise.all()`
+- `once()` wraps the callback in a self-removing wrapper that calls `unsubscribe` before invoking the original handler
 
 ## License
 

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.0",
+  "version": "0.1.1-beta.10",
   "description": "Lightweight pub/sub event system for the Stonyx framework",
   "main": "src/main.js",
   "type": "module",
@@ -31,7 +31,7 @@
   },
   "homepage": "https://github.com/abofs/stonyx-events#readme",
   "devDependencies": {
-    "@stonyx/utils": "^0.2.2",
+    "@stonyx/utils": "0.2.3-beta.7",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/pnpm-lock.yaml

@@ -9,8 +9,8 @@ importers:
   .:
     devDependencies:
       '@stonyx/utils':
-        specifier: ^0.2.2
-        version: 0.2.2
+        specifier: 0.2.3-beta.7
+        version: 0.2.3-beta.7
       qunit:
         specifier: ^2.24.1
         version: 2.25.0
@@ -29,8 +29,8 @@ packages:
   '@sinonjs/samsam@8.0.3':
     resolution: {integrity: sha512-hw6HbX+GyVZzmaYNh82Ecj1vdGZrqVIn/keDTg63IgAwiQPO+xCz99uG6Woqgb4tM0mUiFENKZ4cqd7IX94AXQ==}
 
-  '@stonyx/utils@0.2.2':
-    resolution: {integrity: sha512-z/pDbX3QPeVJ3kFpU1rQURj3+BLwvGkLHVJiSckmjaBZ/vQIZzaerkf6BTZnHbSmQuUwO0lFzJRwlKOTIaXp0g==}
+  '@stonyx/utils@0.2.3-beta.7':
+    resolution: {integrity: sha512-SF6ZZZJ/f1n/+SJJDj8BJdlgvv+WDLGWGUMIkwTpruA5jv/AYJqSoVIgTpYfuMTnYDIsp3KoruaIKy/qd2ETPQ==}
 
   commander@7.2.0:
     resolution: {integrity: sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==}
@@ -92,7 +92,7 @@ snapshots:
       '@sinonjs/commons': 3.0.1
       type-detect: 4.1.0
 
-  '@stonyx/utils@0.2.2': {}
+  '@stonyx/utils@0.2.3-beta.7': {}
 
   commander@7.2.0: {}
 

package/src/main.js

@@ -165,3 +165,15 @@ class Events {
 }
 
 export default Events;
+
+// Create singleton instance
+const events = new Events();
+
+// Export convenience functions that use the singleton
+export const setup = (...args) => events.setup(...args);
+export const subscribe = (...args) => events.subscribe(...args);
+export const once = (...args) => events.once(...args);
+export const unsubscribe = (...args) => events.unsubscribe(...args);
+export const emit = (...args) => events.emit(...args);
+export const clear = (...args) => events.clear(...args);
+export const reset = (...args) => events.reset(...args);

package/stonyx-bootstrap.cjs

@@ -1,9 +0,0 @@
-/**
- * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
- */
-const { default:Stonyx } = require('stonyx');
-const { default:config } = require('./config/environment.js');
-
-new Stonyx(config, __dirname);
-
-module.exports = Stonyx;