@stonyx/events 0.1.1-beta.2 → 0.1.1-beta.20

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-events/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-events/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/events.svg)](https://www.npmjs.com/package/@stonyx/events)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # @stonyx/events
 
 A lightweight pub/sub event system for the Stonyx framework. Provides singleton event management with error isolation, async support, and type-safe event registration.

package/package.json

@@ -3,12 +3,13 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.2",
+  "version": "0.1.1-beta.20",
   "description": "Lightweight pub/sub event system for the Stonyx framework",
   "main": "src/main.js",
   "type": "module",
   "files": [
-    "*"
+    "src",
+    "README.md"
   ],
   "exports": {
     ".": "./src/main.js"
@@ -31,7 +32,7 @@
   },
   "homepage": "https://github.com/abofs/stonyx-events#readme",
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.3",
+    "@stonyx/utils": "0.2.3-beta.11",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/.claude/improvements.md

@@ -1,21 +0,0 @@
-# @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,262 +0,0 @@
-# @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.
-
-### Core Purpose
-- Provide application-wide event bus for decoupled communication
-- Support async event handlers with error isolation
-- Ensure type safety through event registration
-- Maintain singleton pattern for shared event system
-
-### Technology Stack
-- **Runtime**: Node.js v24.13.0
-- **Module System**: ES Modules
-- **Testing**: QUnit 2.24.1 + Sinon 21.0.0
-- **License**: Apache 2.0
-
-## Architecture Overview
-
-### Design Patterns
-
-**Singleton Pattern**
-- Single Events instance shared across the application
-- Prevents multiple competing event systems
-- Ensures all parts of the application use the same event bus
-
-**Error Isolation**
-- Errors in one handler don't affect other handlers
-- All handlers run even if some fail
-- Errors are logged to console.error but don't propagate
-
-**Async Support**
-- All event handlers can be async functions
-- `emit()` waits for all handlers to complete
-- Handlers run in parallel via Promise.all()
-
-**Type Safety**
-- Events must be registered with `setup()` before use
-- Prevents typos and invalid event names
-- Enforces explicit event declarations
-
-## File Structure
-
-```
-stonyx-events/
-├── .github/
-│   └── workflows/
-│       ├── ci.yml                # GitHub Actions CI pipeline
-│       └── publish.yml           # NPM publish workflow (alpha + stable)
-├── .claude/
-│   ├── project-structure.md      # This file
-│   ├── testing.md                # Testing guidelines
-│   └── improvements.md           # Improvement opportunities
-├── src/
-│   └── 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
-```
-
-## Core Components Deep Dive
-
-### Events Class (`src/main.js`)
-
-The Events class is the heart of the module, providing all pub/sub functionality.
-
-#### Properties
-
-**`static instance`** (Events|null)
-- Singleton instance reference
-- Ensures only one Events instance exists
-
-**`events`** (Map<string, Set<Function>>)
-- Map of event names to their subscriber sets
-- Uses Set to prevent duplicate subscriptions
-- Automatically created when events are registered
-
-**`registeredEvents`** (Set<string>)
-- Set of all registered event names
-- Used to validate subscriptions
-- Prevents subscribing to unregistered events
-
-#### Methods
-
-**`setup(eventNames: string[])`**
-- Register available event names
-- Must be called before subscribing to events
-- Validates that all names are strings
-- Creates empty subscriber sets for each event
-
-**`subscribe(event: string, callback: Function)`**
-- Subscribe to an event
-- Throws if event is not registered
-- Throws if callback is not a function
-- Returns an unsubscribe function
-- Callback signature: `(...args: any[]) => void | Promise<void>`
-
-**`once(event: string, callback: Function)`**
-- Subscribe to an event once
-- Auto-unsubscribes after first emit
-- Wraps callback in a self-removing wrapper
-- Returns an unsubscribe function
-- Supports async callbacks
-
-**`emit(event: string, ...args: any[])`**
-- Emit an event with arguments
-- Async function that waits for all handlers
-- Runs all handlers in parallel
-- Isolates errors per handler
-- Does nothing if event has no subscribers
-
-**`unsubscribe(event: string, callback: Function)`**
-- Remove a specific subscription
-- Safe to call multiple times
-- Does nothing if event or callback doesn't exist
-
-**`clear(event: string)`**
-- Remove all subscriptions for an event
-- Useful for cleanup between tests
-- Event remains registered
-
-**`reset()`**
-- Clear all subscriptions and registrations
-- Resets to pristine state
-- Essential for test isolation
-
-## Dependencies & Integration
-
-### Production Dependencies
-None. This module has zero production dependencies.
-
-### Dev Dependencies
-
-**@stonyx/utils** (file:../stonyx-utils)
-- Utility functions (currently unused but available)
-
-**qunit** (^2.24.1)
-- Testing framework
-- Runs via `pnpm test` (which invokes `qunit`)
-
-**sinon** (^21.0.0)
-- Mocking/stubbing library
-- Available for advanced testing scenarios
-
-### Modules That Depend on @stonyx/events
-
-**@stonyx/orm**
-- Uses Events for CRUD lifecycle hooks
-- Fires events: create:before, create:after, update:before, update:after, delete:before, delete:after
-- Provides `ormEvents` singleton instance
-
-## Code Patterns & Conventions
-
-### Module System
-- ES Modules throughout
-- Default export for Events class
-- 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
-
-### 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)
-
-## Package Exports
-
-### Default Export
-
-```javascript
-import Events from '@stonyx/events';
-```
-
-The Events class.
-
-### Named Convenience Exports
-
-```javascript
-import { setup, subscribe, once, unsubscribe, emit, clear, reset } from '@stonyx/events';
-```
-
-All convenience functions use a singleton Events instance internally, providing a cleaner API without needing to instantiate the class.
-
-### Usage Pattern
-
-```javascript
-// Create/get singleton instance
-const events = new Events();
-
-// Register events
-events.setup(['userLogin', 'userLogout']);
-
-// Subscribe
-events.subscribe('userLogin', (user) => {
-  console.log('User logged in:', user);
-});
-
-// Emit (fire-and-forget, don't await)
-events.emit('userLogin', { id: 1, name: 'Alice' });
-
-// Or await if you need to ensure all handlers complete
-await events.emit('userLogin', { id: 1, name: 'Alice' });
-```
-
-### Convenience Exports Usage
-
-```javascript
-import { setup, subscribe, emit } from '@stonyx/events';
-setup(['myEvent']);
-subscribe('myEvent', handler);
-emit('myEvent', data);
-```
-
-## Common Pitfalls & Gotchas
-
-### Singleton Behavior
-- **Issue**: Creating new Events() always returns the same instance
-- **Solution**: Don't rely on local variables; singleton ensures shared state
-- **Testing**: Always call `reset()` between tests to clear state
-
-### Async Handling
-- **Issue**: Forgetting to await emit() can lead to race conditions
-- **Solution**: Use `await events.emit()` when order matters
-- **Note**: For fire-and-forget, omit await (e.g., in synchronous createRecord)
-
-### Error Isolation
-- **Issue**: One handler error doesn't stop other handlers, but logs to console
-- **Solution**: Expect console.error output in tests with failing handlers
-- **Testing**: Suppress console.error when testing error isolation
-
-### Event Registration
-- **Issue**: Subscribing to unregistered events throws an error
-- **Solution**: Always call `setup()` with event names before subscribing
-- **Why**: Prevents typos and ensures explicit event declarations
-
-### Set-based Subscriptions
-- **Issue**: Adding the same callback function twice only subscribes once
-- **Solution**: Use different function instances for multiple subscriptions
-- **Note**: This is by design to prevent accidental duplicate subscriptions
-
-## Related Resources
-
-- [Stonyx Framework](https://github.com/abofs/stonyx)
-- [QUnit Documentation](https://qunitjs.com/)
-- [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)

package/.claude/testing.md

@@ -1,44 +0,0 @@
-# @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/ci.yml

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,51 +0,0 @@
-name: Publish to NPM
-
-on:
-  repository_dispatch:
-    types: [cascade-publish]
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-  pull_request:
-    types: [opened, synchronize, reopened]
-    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
-  pull-requests: write
-
-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/.gitignore

@@ -1,9 +0,0 @@
-node_modules/
-config/environment.js
-*logs/*
-.vscode/*
-*.vsix
-*DS_Store*
-
-# npm auth (never commit tokens)
-.npmrc

package/.npmignore

@@ -1,2 +0,0 @@
-test/
-.nvmrc

package/pnpm-lock.yaml

@@ -1,134 +0,0 @@
-lockfileVersion: '9.0'
-
-settings:
-  autoInstallPeers: true
-  excludeLinksFromLockfile: false
-
-importers:
-
-  .:
-    devDependencies:
-      '@stonyx/utils':
-        specifier: 0.2.3-beta.3
-        version: 0.2.3-beta.3
-      qunit:
-        specifier: ^2.24.1
-        version: 2.25.0
-      sinon:
-        specifier: ^21.0.0
-        version: 21.0.1
-
-packages:
-
-  '@sinonjs/commons@3.0.1':
-    resolution: {integrity: sha512-K3mCHKQ9sVh8o1C9cxkwxaOmXoAMlDxC1mYyHrjqOWEcBjYr76t96zL2zlj5dUGZ3HSw240X1qgH3Mjf1yJWpQ==}
-
-  '@sinonjs/fake-timers@15.1.0':
-    resolution: {integrity: sha512-cqfapCxwTGsrR80FEgOoPsTonoefMBY7dnUEbQ+GRcved0jvkJLzvX6F4WtN+HBqbPX/SiFsIRUp+IrCW/2I2w==}
-
-  '@sinonjs/samsam@8.0.3':
-    resolution: {integrity: sha512-hw6HbX+GyVZzmaYNh82Ecj1vdGZrqVIn/keDTg63IgAwiQPO+xCz99uG6Woqgb4tM0mUiFENKZ4cqd7IX94AXQ==}
-
-  '@stonyx/utils@0.2.3-beta.3':
-    resolution: {integrity: sha512-CLmz/DPgNWU7IXJYQXzmAdph65iapp6mHnvKZQULrd6IdKPGb6KlVMVL29yuyXg0fOapkkoPV4Xf6PmksSE8bw==}
-
-  commander@7.2.0:
-    resolution: {integrity: sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==}
-    engines: {node: '>= 10'}
-
-  diff@8.0.3:
-    resolution: {integrity: sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==}
-    engines: {node: '>=0.3.1'}
-
-  globalyzer@0.1.0:
-    resolution: {integrity: sha512-40oNTM9UfG6aBmuKxk/giHn5nQ8RVz/SS4Ir6zgzOv9/qC3kKZ9v4etGTcJbEl/NyVQH7FGU7d+X1egr57Md2Q==}
-
-  globrex@0.1.2:
-    resolution: {integrity: sha512-uHJgbwAMwNFf5mLst7IWLNg14x1CkeqglJb/K3doi4dw6q2IvAAmM/Y81kevy83wP+Sst+nutFTYOGg3d1lsxg==}
-
-  has-flag@4.0.0:
-    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
-    engines: {node: '>=8'}
-
-  node-watch@0.7.3:
-    resolution: {integrity: sha512-3l4E8uMPY1HdMMryPRUAl+oIHtXtyiTlIiESNSVSNxcPfzAFzeTbXFQkZfAwBbo0B1qMSG8nUABx+Gd+YrbKrQ==}
-    engines: {node: '>=6'}
-
-  qunit@2.25.0:
-    resolution: {integrity: sha512-MONPKgjavgTqArCwZOEz8nEMbA19zNXIp5ZOW9rPYj5cbgQp0fiI36c9dPTSzTRRzx+KcfB5eggYB/ENqxi0+w==}
-    engines: {node: '>=10'}
-    hasBin: true
-
-  sinon@21.0.1:
-    resolution: {integrity: sha512-Z0NVCW45W8Mg5oC/27/+fCqIHFnW8kpkFOq0j9XJIev4Ld0mKmERaZv5DMLAb9fGCevjKwaEeIQz5+MBXfZcDw==}
-
-  supports-color@7.2.0:
-    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
-    engines: {node: '>=8'}
-
-  tiny-glob@0.2.9:
-    resolution: {integrity: sha512-g/55ssRPUjShh+xkfx9UPDXqhckHEsHr4Vd9zX55oSdGZc/MD0m3sferOkwWtp98bv+kcVfEHtRJgBVJzelrzg==}
-
-  type-detect@4.0.8:
-    resolution: {integrity: sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==}
-    engines: {node: '>=4'}
-
-  type-detect@4.1.0:
-    resolution: {integrity: sha512-Acylog8/luQ8L7il+geoSxhEkazvkslg7PSNKOX59mbB9cOveP5aq9h74Y7YU8yDpJwetzQQrfIwtf4Wp4LKcw==}
-    engines: {node: '>=4'}
-
-snapshots:
-
-  '@sinonjs/commons@3.0.1':
-    dependencies:
-      type-detect: 4.0.8
-
-  '@sinonjs/fake-timers@15.1.0':
-    dependencies:
-      '@sinonjs/commons': 3.0.1
-
-  '@sinonjs/samsam@8.0.3':
-    dependencies:
-      '@sinonjs/commons': 3.0.1
-      type-detect: 4.1.0
-
-  '@stonyx/utils@0.2.3-beta.3': {}
-
-  commander@7.2.0: {}
-
-  diff@8.0.3: {}
-
-  globalyzer@0.1.0: {}
-
-  globrex@0.1.2: {}
-
-  has-flag@4.0.0: {}
-
-  node-watch@0.7.3: {}
-
-  qunit@2.25.0:
-    dependencies:
-      commander: 7.2.0
-      node-watch: 0.7.3
-      tiny-glob: 0.2.9
-
-  sinon@21.0.1:
-    dependencies:
-      '@sinonjs/commons': 3.0.1
-      '@sinonjs/fake-timers': 15.1.0
-      '@sinonjs/samsam': 8.0.3
-      diff: 8.0.3
-      supports-color: 7.2.0
-
-  supports-color@7.2.0:
-    dependencies:
-      has-flag: 4.0.0
-
-  tiny-glob@0.2.9:
-    dependencies:
-      globalyzer: 0.1.0
-      globrex: 0.1.2
-
-  type-detect@4.0.8: {}
-
-  type-detect@4.1.0: {}