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

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.
@@ -19,36 +23,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 +90,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,20 +3,17 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.0",
+  "version": "0.1.1-alpha.10",
   "description": "Lightweight pub/sub event system for the Stonyx framework",
   "main": "src/main.js",
   "type": "module",
   "files": [
-    "*"
+    "src",
+    "README.md"
   ],
   "exports": {
     ".": "./src/main.js"
   },
-  "scripts": {
-    "test": "qunit",
-    "prepublishOnly": "npm test"
-  },
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -35,9 +32,12 @@
   },
   "homepage": "https://github.com/abofs/stonyx-events#readme",
   "devDependencies": {
-    "@stonyx/utils": "^0.2.2",
+    "@stonyx/utils": "0.2.3-beta.13",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },
-  "dependencies": {}
-}
+  "dependencies": {},
+  "scripts": {
+    "test": "qunit"
+  }
+}

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/.claude/project-structure.md

@@ -1,421 +0,0 @@
-# @stonyx/events - Project Structure & Architecture
-
-## 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
-├── .claude/
-│   ├── settings.local.json     # Claude Code permissions
-│   └── project-structure.md    # This file
-├── config/
-│   └── environment.js          # Environment configuration
-├── 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
-└── stonyx-bootstrap.cjs        # CommonJS bootstrap for testing
-```
-
-## 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
-
-### Direct Dependencies
-
-**stonyx** (file:../stonyx)
-- Core Stonyx framework
-- Provides base configuration and bootstrapping
-- Required for module initialization
-
-### Dev Dependencies
-
-**@stonyx/utils** (file:../stonyx-utils)
-- Utility functions (currently unused but available)
-
-**qunit** (^2.24.1)
-- Testing framework
-- Runs via CLI with stonyx-bootstrap.cjs
-
-**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
-- No named exports (single-purpose module)
-
-### 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`
-
-### config/environment.js
-
-```javascript
-{
-  log: EVENTS_LOG ?? false,  // Debug logging flag
-  logColor: '#888',           // Color for log output
-}
-```
-
-Currently, these config values are prepared but not used in the Events implementation. They provide a foundation for future debug logging features.
-
-## Package Exports
-
-### Main Export
-
-```javascript
-import Events from '@stonyx/events';
-```
-
-The package exports a single default export: the Events 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' });
-```
-
-## 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
-
-**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
-
-## 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
-
-## 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)
-- [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)
-
----
-
-This document is maintained by the Stonyx team and should be updated whenever architectural changes are made to the @stonyx/events module.

package/.github/workflows/ci.yml

@@ -1,24 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches:
-      - dev
-      - main
-
-concurrency:
-  group: ${{ github.head_ref }}
-  cancel-in-progress: true
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '24.13.0'
-          cache: 'pnpm'
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm test

package/.github/workflows/publish.yml

@@ -1,94 +0,0 @@
-name: Publish to NPM
-
-on:
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - alpha
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-
-permissions:
-  contents: write
-  id-token: write  # Required for npm provenance
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 24.13.0
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
-
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      - name: Bump version (custom)
-        if: ${{ github.event.inputs.custom-version != '' }}
-        run: npm version ${{ github.event.inputs.custom-version }} --no-git-tag-version
-
-      - name: Bump version (prerelease alpha)
-        if: ${{ github.event.inputs.version-type == 'alpha' && github.event.inputs.custom-version == '' }}
-        run: npm version prerelease --preid=alpha --no-git-tag-version
-
-      - name: Bump version (standard)
-        if: ${{ github.event.inputs.version-type != 'alpha' && github.event.inputs.custom-version == '' }}
-        run: npm version ${{ github.event.inputs.version-type }} --no-git-tag-version
-
-      - name: Get package version
-        id: package-version
-        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
-
-      - name: Publish to NPM (alpha)
-        if: ${{ github.event.inputs.version-type == 'alpha' || contains(steps.package-version.outputs.version, 'alpha') }}
-        run: npm publish --tag alpha --access public
-      - name: Publish to NPM (stable)
-        if: ${{ github.event.inputs.version-type != 'alpha' && !contains(steps.package-version.outputs.version, 'alpha') }}
-        run: npm publish --access public
-      - name: Commit version bump
-        run: |
-          git add package.json
-          git commit -m "chore: release v${{ steps.package-version.outputs.version }}"
-          git tag v${{ steps.package-version.outputs.version }}
-          git push origin main --tags
-
-      - name: Create GitHub Release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: v${{ steps.package-version.outputs.version }}
-          release_name: v${{ steps.package-version.outputs.version }}
-          draft: false
-          prerelease: ${{ contains(steps.package-version.outputs.version, 'alpha') }}

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/.nvmrc

@@ -1 +0,0 @@
-v24.13.0

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;

package/test/unit/events-test.js

@@ -1,341 +0,0 @@
-import QUnit from 'qunit';
-import Events from '../../src/main.js';
-
-const { module, test } = QUnit;
-
-module('[Unit] Events', function () {
-
-test('Events: setup() registers event names', function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent1', 'testEvent2']);
-
-  assert.ok(events.registeredEvents.has('testEvent1'), 'testEvent1 is registered');
-  assert.ok(events.registeredEvents.has('testEvent2'), 'testEvent2 is registered');
-  assert.strictEqual(events.registeredEvents.size, 2, 'Two events are registered');
-
-  events.reset();
-});
-
-test('Events: setup() throws on invalid input', function (assert) {
-  const events = new Events();
-  events.reset();
-
-  assert.throws(
-    () => events.setup('not-an-array'),
-    /setup\(\) requires an array/,
-    'Throws error for non-array input'
-  );
-
-  assert.throws(
-    () => events.setup([123]),
-    /Event names must be strings/,
-    'Throws error for non-string event names'
-  );
-
-  events.reset();
-});
-
-test('Events: subscribe() adds callbacks', function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  const callback1 = () => {};
-  const callback2 = () => {};
-
-  events.subscribe('testEvent', callback1);
-  events.subscribe('testEvent', callback2);
-
-  const subscribers = events.events.get('testEvent');
-  assert.strictEqual(subscribers.size, 2, 'Two callbacks subscribed');
-  assert.ok(subscribers.has(callback1), 'callback1 is subscribed');
-  assert.ok(subscribers.has(callback2), 'callback2 is subscribed');
-
-  events.reset();
-});
-
-test('Events: subscribe() throws for unregistered events', function (assert) {
-  const events = new Events();
-  events.reset();
-
-  assert.throws(
-    () => events.subscribe('unregisteredEvent', () => {}),
-    /Event "unregisteredEvent" is not registered/,
-    'Throws error for unregistered event'
-  );
-
-  events.reset();
-});
-
-test('Events: subscribe() throws for non-function callbacks', function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  assert.throws(
-    () => events.subscribe('testEvent', 'not-a-function'),
-    /Callback must be a function/,
-    'Throws error for non-function callback'
-  );
-
-  events.reset();
-});
-
-test('Events: emit() calls all subscribed callbacks', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  let call1 = false;
-  let call2 = false;
-  let receivedData = null;
-
-  events.subscribe('testEvent', (data) => {
-    call1 = true;
-    receivedData = data;
-  });
-
-  events.subscribe('testEvent', () => {
-    call2 = true;
-  });
-
-  await events.emit('testEvent', { value: 42 });
-
-  assert.ok(call1, 'First callback was called');
-  assert.ok(call2, 'Second callback was called');
-  assert.deepEqual(receivedData, { value: 42 }, 'Callback received correct data');
-
-  events.reset();
-});
-
-test('Events: emit() supports async handlers', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  let asyncComplete = false;
-
-  events.subscribe('testEvent', async () => {
-    await new Promise((resolve) => setTimeout(resolve, 10));
-    asyncComplete = true;
-  });
-
-  await events.emit('testEvent');
-
-  assert.ok(asyncComplete, 'Async handler completed');
-
-  events.reset();
-});
-
-test('Events: emit() isolates errors per handler', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  let handler1Called = false;
-  let handler2Called = false;
-  let handler3Called = false;
-
-  events.subscribe('testEvent', () => {
-    handler1Called = true;
-  });
-
-  events.subscribe('testEvent', () => {
-    handler2Called = true;
-    throw new Error('Handler 2 failed');
-  });
-
-  events.subscribe('testEvent', () => {
-    handler3Called = true;
-  });
-
-  // Suppress console.error during test
-  const originalConsoleError = console.error;
-  console.error = () => {};
-
-  await events.emit('testEvent');
-
-  console.error = originalConsoleError;
-
-  assert.ok(handler1Called, 'Handler 1 was called');
-  assert.ok(handler2Called, 'Handler 2 was called (even though it threw)');
-  assert.ok(handler3Called, 'Handler 3 was called (despite handler 2 throwing)');
-
-  events.reset();
-});
-
-test('Events: once() subscribes and auto-unsubscribes after first emit', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  let callCount = 0;
-
-  events.once('testEvent', () => {
-    callCount++;
-  });
-
-  await events.emit('testEvent');
-  assert.strictEqual(callCount, 1, 'Callback called on first emit');
-
-  await events.emit('testEvent');
-  assert.strictEqual(callCount, 1, 'Callback not called on second emit');
-
-  events.reset();
-});
-
-test('Events: once() throws for unregistered events', function (assert) {
-  const events = new Events();
-  events.reset();
-
-  assert.throws(
-    () => events.once('unregisteredEvent', () => {}),
-    /Event "unregisteredEvent" is not registered/,
-    'Throws error for unregistered event'
-  );
-
-  events.reset();
-});
-
-test('Events: unsubscribe() removes specific callback', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  let call1 = false;
-  let call2 = false;
-
-  const callback1 = () => {
-    call1 = true;
-  };
-  const callback2 = () => {
-    call2 = true;
-  };
-
-  events.subscribe('testEvent', callback1);
-  events.subscribe('testEvent', callback2);
-
-  events.unsubscribe('testEvent', callback1);
-
-  await events.emit('testEvent');
-
-  assert.notOk(call1, 'Unsubscribed callback1 was not called');
-  assert.ok(call2, 'Callback2 was still called');
-
-  events.reset();
-});
-
-test('Events: subscribe() returns unsubscribe function', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  let callCount = 0;
-
-  const unsubscribe = events.subscribe('testEvent', () => {
-    callCount++;
-  });
-
-  await events.emit('testEvent');
-  assert.strictEqual(callCount, 1, 'Callback called before unsubscribe');
-
-  unsubscribe();
-
-  await events.emit('testEvent');
-  assert.strictEqual(callCount, 1, 'Callback not called after unsubscribe');
-
-  events.reset();
-});
-
-test('Events: clear() removes all subscriptions for an event', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  let call1 = false;
-  let call2 = false;
-
-  events.subscribe('testEvent', () => {
-    call1 = true;
-  });
-  events.subscribe('testEvent', () => {
-    call2 = true;
-  });
-
-  events.clear('testEvent');
-
-  await events.emit('testEvent');
-
-  assert.notOk(call1, 'Callback1 was not called after clear');
-  assert.notOk(call2, 'Callback2 was not called after clear');
-
-  events.reset();
-});
-
-test('Events: reset() clears all subscriptions and events', function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent1', 'testEvent2']);
-  events.subscribe('testEvent1', () => {});
-
-  events.reset();
-
-  assert.strictEqual(events.registeredEvents.size, 0, 'No events registered after reset');
-  assert.strictEqual(events.events.size, 0, 'No subscriptions after reset');
-
-  events.reset();
-});
-
-test('Events: singleton pattern works', function (assert) {
-  const events1 = new Events();
-  events1.reset();
-
-  events1.setup(['testEvent']);
-
-  const events2 = new Events();
-
-  assert.strictEqual(events1, events2, 'Both instances are the same');
-  assert.ok(events2.registeredEvents.has('testEvent'), 'Second instance has same registered events');
-
-  events1.reset();
-});
-
-test('Events: emit() does nothing for events with no subscribers', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  events.setup(['testEvent']);
-
-  // Should not throw
-  await events.emit('testEvent');
-
-  assert.ok(true, 'No error when emitting to event with no subscribers');
-
-  events.reset();
-});
-
-test('Events: emit() does nothing for unregistered events', async function (assert) {
-  const events = new Events();
-  events.reset();
-
-  // Should not throw
-  await events.emit('unregisteredEvent');
-
-  assert.ok(true, 'No error when emitting unregistered event');
-
-  events.reset();
-});
-
-});