C#-Style Typescript Events/Weak Events
npm install weak-eventC#-Style Typescript Events/Weak Events
 
Javascript's event are somewhat awkward to use and lack first-class typing support or a native 'weak event' implementation.
This package seeks to allow for lightweight, zero dependency, easy to use C#-style events that work on NodeJS and modern browsers
> #### Note:
> Weak events carry a measurable overhead over conventional events.
> Be wary of this in performance-critical applications.
The package is quite similar to strongly-typed-events (a.k.a ts-events) but is significantly
smaller and less featured.
The main focus however, is support for modern weak events that require NodeJS >= 14.6 or an updated, modern browser due to
the use of FinalizationRegistry
Weak events are useful when object life-cycles cannot be guaranteed or controlled.
This tends to happen in collaborative/enterprise scenarios where several developers may create or consume events or entities without fully understanding their life-cycles and exceptional conditions or the code's ecosystem.
Usage of weak references in such cases may help prevent hard to detect event handler leaks which are some of the most common causes of slow memory leaks.
> npm install weak-event or yarn install weak-event
Please note that this package is __unbundled__
Estimated efficiency values of package code.
Note that ECMA does not specify any complexity constraints for array functions
so actual complexity may vary.
| Function | Average Time | Average Space |
|---------------------------|---------------|---------------|
| ITypedEvent.attach | O(1) | O(1) |
| ITypedEvent.detach | O(n) | O(1) |
| ITypedEvent.invoke | O(n) | O(1) |
| ITypedEvent.invokeAsync | O(n) | O(n) |
For any bugs, questions or suggestions or comments, feel free to hit me on my mail at yuval.pomer
Feedback, positive or otherwise is appreciated.
For more reading material regarding the necessity and/or potential use-cases of the 'Weak Event' pattern in general, please refer to:
* https://v8.dev/features/weak-references
* https://docs.microsoft.com/en-us/dotnet/desktop/wpf/advanced/weak-event-patterns
The below example is a simplified but rather typical use-case where an event listener object goes
out of scope.
Under normal circumstances, the Garbage Collector would not reclaim the object as it's still
referenced by the the event source's listener's dictionary.
Using WeakEvent, however, GC can collect the object, at which point a finalizer will be invoked and the dead reference cleaned from the event source's map.
This ensures memory is eventually reclaimed and can, over time, make a significant difference.
``typescript
import { TypedEvent, ITypedEvent } from 'weak-event';
class DummyEventSource {
private _someEvent = new WeakEvent
public get someEvent(): ITypedEvent
return this._someEvent;
}
private async raiseEventAsynchronously(): Promise
this._someEvent.invokeAsync(this, true);
}
}
class DummyEventConsumer {
public constructor(eventSource: DummyEventSource) {
// Valid usage. Handler signature matches event.
eventSource.someEvent.attach(this.onEvent);
}
private onEvent(sender: DummyEventSource, e: boolean): void {
console.log(Event payload: ${e});
}
}
class LeakyClass {
private _eventSource = new DummyEventSource();
public createConsumer(): void {
const consumer = new DummyEventConsumer(this._eventSource);
/* Do something with consumer
...
...
...
Forget to 'dispose'. Consumer goes out of scope. Memory is leaked
*/
}
}
`
The most basic type of event. Uses strong references and behaves like other events do
`typescript
import { TypedEvent, ITypedEvent } from 'weak-event';
class DummyEventSource {
public get someProperty(): string {
return "I'm an event source";
}
private _someEvent = new TypedEvent
public get someEvent(): ITypedEvent
return this._someEvent;
}
private raiseEventSynchronously(): void {
this._someEvent.invoke(this, 'Some value');
// We get here after all events have been synchronously invoked
console.log('Done!');
}
private async raiseEventAsynchronously(): Promise
this._someEvent.invokeAsync(this, 'Some value');
// We get here as soon as the 'invokeAsync' method yields.
// Events are invoked asynchronously.
console.log('Done!');
}
}
class DummyEventConsumer {
private _eventSource: DummyEventSource;
public constructor(eventSource: DummyEventSource) {
this._eventSource = eventSource;
// Valid usage. Handler signature matches event.
eventSource.someEvent.attach(this.onEvent);
}
private onEvent(sender: DummyEventSource, e: string): void {
console.log(Caller property: ${sender.someProperty}, Event payload: ${e});
}
public dispose(): void {
// Detach the event handler
this._eventSource.someEvent.detach(this.onEvent);
}
}
``
Changelog may be found at the project's GitHub here