@glandjs/events@2.0.0
Changelog — @glandjs/events
Release history for @glandjs/events, mirrored from the repository.
[2.0.0] – 2026-10-02
Section titled “[2.0.0] – 2026-10-02”A correctness release. Most of what changed here was already promised by the documentation — this version makes the code match the docs, and removes a signature that could not have worked.
The headline: send() never carried a payload, and a channel’s watch()
could never settle. Both are fixed below, and both are breaking.
Breaking changes
Section titled “Breaking changes”send() now takes a payload
Section titled “send() now takes a payload”payload is a required third argument. In 1.x it was absent from both the
signature and the forwarding call, so the target always received a literal
null.
// 1.x — payload was unreachablebroker.send('user:login', peer);
// 2.0.0broker.send('user:login', peer, { id: 'u1' });payload sits before options, so any existing three-argument call that was
passing options in that position must move it.
BrokerChannel.watch() now namespaces the event name
Section titled “BrokerChannel.watch() now namespaces the event name”user.watch('login') used to watch the bare name login — an event a user
channel can never emit, because a channel only ever writes user:login. The
promise therefore always timed out. It now watches user:login, consistent with
every other method on the channel.
EventEmitter.shutdown()now removes listeners. It previously shut down only the watcher, leaving every registration live.EventEmitter.off()now updates the listener registry. Removals were applied to the underlying emitter but not the bookkeeping, sogetListener()kept reporting detached listeners andmaxListenersnever freed a slot.getListener()no longer reaches into private fields of@glandjs/emitter(spliter,tree). Those names are dependency-private and have already changed once; a dependency bump would have silently madegetListenerreturn zero listeners.defaultValueis now tested with!== undefinedrather than truthiness, so0,'',falseandnullwork as watcher fallbacks. Previously only a truthy value could be used.emit(..., { watch: true })no longer produces an unhandled rejection when the watcher it opens times out. The promise is not returned to the caller, so its failure is now swallowed deliberately.once(event, null)outside watch mode now throws, matchingon, instead of silently registering nothing.- A
oncewrapper detaches before invoking the listener, so a re-entrant emit inside the handler cannot run it a second time. - Event-trace dedup is now bounded. Traces record a
visitedset per correlation id in a FIFO map capped at 4096 entries, so the map can no longer grow for the life of the process. - Automatic forwarding no longer loops.
ConnectionOptions.eventsis now routing state rather than a listener that re-emitted with a fresh id. Because it shares the original correlation id, the return leg is deduped away instead of ping-ponging between two brokers until the stack overflowed. It also no longer consumes listener slots — previouslyconnectTocould throw on a broker with a tightmaxListeners— and it correctly stops ondisconnect. Broker.shutdown()now clears the event-trace map, so a reused correlation id is processed again after a restart.generateUUIDdegrades instead of throwing. A runtime that exposescrypto.getRandomValuesbut rejects the call now falls through to theMath.randomtier instead of taking the broker down.EventWatcherno longer writes aconsole.warnon timeout. The rejection is the contract; a side-channel log line for an expected outcome was noise.
BrokerChannelandEventWatcherare now exported from the package root.BrokerChannelwas previously unreachable to consumers, despite being the documented way to own a namespace.BrokerConnection— the live link to a peer, plus the events it auto-forwards. Exported from the package root.CallStrategy—type CallStrategy = 'all', extracted so the strategy argument is named rather than an inline literal.BrokerIdmoved into the shared type vocabulary alongside the other identifier types.Brokernow defaults its type parameter toEventRecord, so an untypedBrokeris usable where the mesh cannot know a node’s event map in advance.EventWatcher.pending— the count of unsettled watchers, so a teardown path (or a test) can assert nothing is left holding a timer.tsconfig.test.json— type-checkssrc/andtests/withnoUnusedLocals,noUnusedParametersandnoImplicitOverride. Previously onlysrc/was checked.- New scripts:
format,format:check,test:unit, andverify(typecheck + test + format:check).testnow runs the whole suite instead of only the integration tests.
Changed
Section titled “Changed”- Tests are organised into
tests/unitandtests/integration, with shared fixtures intests/helpers.ts. ABrokerFactorycentralises teardown so a forgottenshutdown()cannot leak an armed timer and keep the test process alive. - Line and function coverage of
src/is at 100%, up from a suite that did not exist in this form. - Removed every
@ts-ignorefromsrc/. broadcastTonow delegates toemitTorather than duplicating the routing logic.- Per-call typing tightened across
BrokerChannel,EventEmitterandEventWatcherto useEventPayload<TEvents, K>rather thanTEvents[K], so anIOEventpayload is unwrapped at the boundary.
Documentation
Section titled “Documentation”- New
docs/api/README.md— the full API reference. The source JSDoc already linked to this path, but the file did not exist. - Corrected the
ChannelMethoddoc, which claimed a'user'prefix also claims'username:verify'. It does not:ChannelEventsdrops that key rather than re-labelling it, because the match is textual and a channel only ever writes<name><delimiter><event>. Verified against the compiler, not assumed. - README — added an install/usage section and repaired the documentation
links, which pointed at
#and#/api. - Quick Start — rewritten against the current API. The previous version
documented a
'every'call strategy that was removed in 1.1.0 and never existed as of this release. - CONTRIBUTING — corrected. It listed Node 14 (the package targets Node 18+)
and told contributors to run
npm testandnpm run lint, the latter of which is not a script in this repository. - Package description — dropped the “zero-dependency” claim. The package has
one runtime dependency,
@glandjs/emitter.
Examples
Section titled “Examples”mesh-network.ts— removed a stray+that turned a subscription into a unary plus expression. It ran by accident; it was not valid TypeScript.auth-service.ts— replaced acall(..., 'first')call (a strategy removed in 1.1.0, and a compile error) with a realIOEventrequest/response flow.basic.ts— imported from../dist, which is gitignored and absent on a fresh clone. Now imports from../srclike the other examples.simple.ts— annotated a parameter that was implicitlyany.
Migration
Section titled “Migration”// send — payload is now required and sits before optionsbroker.send('user:login', peer, { id: 'u1' });broker.send('user:login', peer, { id: 'u1' }, { timeout: 100 });
// channel watch — now works; previously always timed outconst payload = await broker.channel('user').watch('login', 5_000);
// call — 'first' and 'last' were removed in 1.1.0 and are not in 2.0.0 eitherbroker.call('user:validate', data); // first listener's resultbroker.call('user:validate', data, 'all'); // every result, in orderEverything else in 1.x keeps working. If you do not call send() or a channel’s
watch(), this is a drop-in upgrade.
[1.1.2] – 2025-10-14
Section titled “[1.1.2] – 2025-10-14”- Chore: version bump only. No source changes from 1.1.1.
[1.1.1] – 2025-10-14
Section titled “[1.1.1] – 2025-10-14”- Chore: version bump only. No source changes from 1.1.0.
[1.0.0-beta-1] – 2025-05-01
Section titled “[1.0.0-beta-1] – 2025-05-01”This is the first stable release of @glandjs/events. It provides a fast, zero-dependency event broker and message bus designed for building scalable, event-driven applications based on a modular and protocol-agnostic architecture.
This release introduces a solid and extensible foundation for building high-performance event systems in TypeScript and JavaScript environments using Bun. All events are fully type-safe, ensuring better maintainability and fewer runtime errors. Brokers are designed with peer-to-peer (P2P) and mesh networking architecture, enabling high scalability and flexible event routing across distributed systems.
Features
Section titled “Features”Core Architecture
Section titled “Core Architecture”-
EventBroker Class
- Implements the core logic for event propagation, namespacing, and broker-to-broker communication.
- Supports hierarchical event propagation between nested brokers, making it easy to scale applications by adding more brokers without increasing complexity.
- Brokers operate using a P2P mesh architecture, allowing direct communication and event routing between them, enabling low-latency, high-throughput messaging in large-scale systems.
- Type-safe event handling is fully supported across brokers, ensuring that the types of events and handlers match perfectly at compile time.
- Supports the registration of event handlers with strategies like
parallel,sync, andasync, enabling flexible event processing patterns.
-
BrokerChannel Class
- Acts as a bridge between event channels and brokers.
- Handles fully namespaced event routing, which helps in avoiding collisions and ensuring events are handled in the correct context.
- Scoped event listener registration allows for better modularity with dot-separated namespaces, ensuring that events are processed in the right context.
- Supports isolated channel-level event handling, making it possible to separate concerns and reduce complexity in large applications.
Event Engine
Section titled “Event Engine”-
EventEmitter
- A lightweight and efficient emitter designed for pub/sub use cases.
- Optimized for zero-allocation and fast lookup via a Radix Tree structure, providing a significant performance boost over other event systems.
- Fully supports wildcards and event pooling, enabling efficient handling of events in high-frequency environments.
-
EventWatcher
- Promise-based event observer designed for async workflows.
- Useful for scenarios where you need to wait on specific events or implement dynamic workflows that depend on asynchronous events.
Typings & Interfaces
Section titled “Typings & Interfaces”- Fully TypeScript-compatible with comprehensive type definitions for all major components:
- EventApi, EventOptions, BrokerOptions, ChannelInterface, and other critical components.
- Type-safe methods for event handling, including
emit,on,off, andwatch. All events and their respective handlers are type-checked at compile time, eliminating potential runtime errors. - Strongly-typed broker and event interfaces that ensure the correctness of event data passed between components.
Modular Design
Section titled “Modular Design”- Designed with separation of concerns into substructures:
core,channel,engine, andcommon. - Easily extendable to support multiple protocols (e.g., HTTP, WebSocket) by creating custom brokers that can communicate seamlessly via the
BrokerChannel. - P2P and mesh architecture ensures brokers can interconnect easily, making it ideal for distributed systems where events need to flow between independent services.
Performance Optimizations
Section titled “Performance Optimizations”- Zero-dependency emitter optimized for performance, utilizing advanced techniques like caching and pooling to reduce overhead during event processing.
- Radix Tree structure for faster event lookups and memory efficiency, especially in applications that handle high-throughput events.
- The internal caching and pooling mechanisms minimize redundant event emissions and optimize memory usage for large-scale applications.
Broker Communication and Networking
Section titled “Broker Communication and Networking”- Brokers communicate in a peer-to-peer (P2P) manner, where each broker can directly connect to another, facilitating fast and reliable event propagation across distributed systems.
- This mesh network of brokers allows for high scalability as brokers can be added or removed without disrupting event flow, making it an ideal solution for microservices or event-driven architectures.
Build and Tooling
Section titled “Build and Tooling”- Native ESM support via Bun, enabling modern JavaScript/TypeScript workflows without needing a bundler.
- TypeScript types (
.d.ts) included in thedist/directory for better IDE support and auto-completion. - Supports Bun version ≥ 1.0.0 and TypeScript version ≥ 5.
- Optimized for bundler-free environments, which means you can work with the project directly in Bun or any modern JavaScript runtime.
- Linting, formatting, and type checking integrated with Prettier, TypeScript, and Husky for a seamless development experience.
Testing and Quality Assurance
Section titled “Testing and Quality Assurance”- Full test coverage with Bun. The engine and broker classes have been thoroughly tested with both unit and integration tests.
- Tests ensure that P2P communication, event propagation, and type safety are functioning as expected in different scenarios.
- Code coverage integrated into Bun’s testing suite, ensuring the reliability and correctness of all event-handling features.
Migration Notes
Section titled “Migration Notes”This is the first stable release, so there are no breaking changes from previous versions. However, if you are upgrading from a pre-release (such as 1.0.0-alpha or 1.0.0-beta), please review any changes in method signatures, file organization, or type definitions, as these have been fine-tuned for better consistency and type safety.
[1.0.0-beta] – 2025-05-03
Section titled “[1.0.0-beta] – 2025-05-03”- Package: Added
exportsfield topackage.jsonfor proper ESM resolution. - Version: Bumped from
1.0.0-beta-1to1.0.0-beta.
[1.0.2-beta] – 2025-05-04
Section titled “[1.0.2-beta] – 2025-05-04”Changed
Section titled “Changed”- package.json
- Added
"main": "./dist/index.js"so that CommonJS consumers canrequire()the package. - Expanded
"exports"to include both"import"and"require"targets, ensuring proper resolution in ESM and CJS contexts. - Removed Bun‑only build pipeline; build now runs purely via
tsc. - Switched
moduletoCommonJSandtargettoES2021for broader runtime support. - Simplified compiler options, removing Bun‑specific and unused flags.
- Consolidated to a single
"build": "tsc"entry, dropping the separatebun buildstep. - Ensures both
.jsand.d.tsoutputs land indist/.
- Added
[1.0.0] – 2025-05-08
Section titled “[1.0.0] – 2025-05-08”-
EventEmitter
- Added
maxListenersparameter to constructor andBrokerOptionsinterface to limit the maximum number of listeners per event (default: 5) - Implemented listener count validation in
on()andonce()methods to prevent potential memory leaks - Added error handling when listener limit is exceeded, with clear error messages indicating the event name and limit
- Added
-
Types
- Added
IOEvent<TPayload, TReturn>generic type for explicit payload and return type definition - Added
Events<TEvents>as an alias forkeyof TEvents & stringfor better type inference - Added
EventPayload<TEvents, K>andEventReturn<TEvents, K>helper types for improved type safety
- Added
-
CallMethod
- Remove
race-some-everystrategies:
- Remove
Changed
Section titled “Changed”-
Broker
- Improved type definitions across all methods for better TypeScript inference
- Enhanced method signatures to use new type system with
EventPayloadandEventReturn
-
EventEmitter
- Refactored internal code to use new type definitions
- Improved error messages with more context about the failure reason
- Fixed potential memory leak by enforcing maximum listener count
- Improved type safety across the codebase by using more specific type definitions
[1.1.0] - 2025-05-10
Section titled “[1.1.0] - 2025-05-10”-
A new UUID generation utility (
generateUUID) to replace runtime‑specific APIs and ensure consistent ID creation across environments. -
Broker mesh management methods:
getConnections&getConnectionfor inspecting active connections.disconnectAllto tear down all peer connections in one call.callTofor invoking an action on a specific broker by ID.broadcastTofor sending an event to a selected subset of brokers.findBrokerto locate a broker in the mesh—directly or via multi‑hop.
Changed
Section titled “Changed”-
Simplified the
callAPI:- The default invocation (no strategy) now returns the first listener’s result.
- Passing the
'all'strategy returns an array of all listener results. - Removed explicit support for
'first'and'last'parameters.
-
Refactored method overloads in broker and channel classes to match the new call signature.
-
Replaced all
crypto.randomUUID()calls with the newgenerateUUID()utility for platform‑agnostic behavior. -
Streamlined private state initialization and TypeScript declarations for stronger type safety.
Removed
Section titled “Removed”- Deprecated the explicit
'first'/'last'call strategies. - Eliminated obsolete API overloads and unused code paths to reduce maintenance burden.