Add TypeScript implementation and expand Python documentation

Closed
PI
9mo ago
+21600-679

Summary

This PR introduces a TypeScript/Node.js implementation of bubus alongside the existing Python library, significantly expands the README with comprehensive documentation, and updates the project configuration to support multi-language development.

Key Changes

New TypeScript Implementation

  • Added complete bubus-ts/ directory with TypeScript event bus implementation
  • Mirrors Python API for consistency across languages (.on(), .emit(), .find(), etc.)
  • Includes npm publishing workflow (.github/workflows/publish-npm.yml)
  • Supports both Node.js and browser environments

Documentation Improvements

  • Completely rewrote README.md with:
    • Multi-language positioning (Python + TypeScript)
    • Expanded feature descriptions with code examples
    • New sections: Event Debouncing, ContextVar Propagation, Middleware System
    • Comprehensive API reference with all methods documented
    • Better examples showing real-world patterns
  • Added badges for DeepWiki documentation links and version info
  • Clarified differences between find() (new unified method) and expect() (backwards-compatible wrapper)

API Enhancements

  • Introduced find() method as the recommended unified approach for event lookup with flexible past/future parameters
  • Added query() method for searching completed event history
  • Added event_is_child_of() and event_is_parent_of() helper methods
  • Introduced EventBusMiddleware system for extensible handler lifecycle hooks
  • Added SQLiteHistoryMirrorMiddleware for event persistence and auditing
  • Improved context variable propagation through nested events

Configuration Updates

  • Updated .claude/settings.local.json to allow broader pytest and git operations
  • Updated .gitignore to include node_modules/ and *.sqlite* files
  • Refactored event persistence from wal_path parameter to middleware-based approach

Bug Fixes & Improvements

  • Fixed example code (SomeClass → SomeService)
  • Clarified event timeout default (300s instead of 60s)
  • Improved error handling documentation
  • Better explanation of context isolation between concurrent dispatches

Notable Implementation Details

  • The TypeScript implementation maintains API parity with Python for seamless cross-language event exchange
  • Middleware system allows for flexible extensibility without modifying core EventBus
  • The find() method unifies history search and future waiting with intuitive boolean/float parameters
  • ContextVar propagation ensures request-scoped context flows through nested event handlers
  • SQLite-based history mirroring provides audit trail and debugging capabilities

https://claude.ai/code/session_01TyuqFQFwDXa4h5QzQDCUsv

Summary by cubic

Adds a full TypeScript/ESM port of bubus (with a TC39-decorator-compatible retry) and upgrades the Python package with middleware, a pluggable history backend, ContextVar propagation, and a unified find/query API. Expands docs, adds npm publish CI, introduces semaphore_scope for retry, and adds a new test that wraps the full emit→done cycle in parallel with other events.

  • New Features

    • TypeScript: new bubus-ts with .on/.emit/.find parity, Node + browser support, and a retry decorator (backoff, timeouts, semaphores, re-entrancy safe); supports @retry on class methods and works with bus.on() via .bind(); retry_on_errors accepts error classes, string names, and RegExp; semaphore_scope ('global' | 'class' | 'instance') with sane fallbacks; docs now include TC39 @retry examples, .bind() ordering, and scope fallback notes; tests added for these, including wrapping emit→done with parallel events; deterministic handler IDs to avoid same-ms collisions; GitHub Action for npm publish.
    • Python: EventBusMiddleware hooks; WALEventBusMiddleware and SQLiteHistoryMirrorMiddleware; swappable EventHistory backend; ContextVar propagation from dispatch to handlers; new find(past/future) and query(); EventStatus enum; logging/tree fixes.
    • Docs: README rewritten with multi-language examples and API reference; clarified defaults and result typing; updated retry_on_errors and semaphore_scope docs; added @retry decorator usage as the recommended handler-level pattern and discouraged emit-level wrapping (still supported); explained retry semaphores as orthogonal to bus concurrency.

  • Migration

    • Replace wal_path persistence with WALEventBusMiddleware or SQLiteHistoryMirrorMiddleware.
    • Prefer bus.find()/bus.query() for history and debouncing; expect() remains as a wrapper.
    • EventStatus enum added; string comparisons still work (no code changes required).