@matrixai/events - npm Package Compare versions

Comparing version 1.0.0 to 2.0.2

dist/EventAny.d.ts

@@ -1,8 +0,8 @@
-declare class EventAny extends Event {
+import AbstractEvent from './AbstractEvent';
+declare class EventAny<T = Event> extends AbstractEvent<T> {
     static type: string;
-    detail: Event;
     constructor(options: EventInit & {
-        detail: Event;
+        detail: T;
     });
 }
 export default EventAny;

dist/EventAny.js

 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-// @ts-ignore package.json is outside rootDir
+const AbstractEvent_1 = __importDefault(require("./AbstractEvent"));
+// @ts-ignore package.json is outside root dir
 const package_json_1 = require("../package.json");
-class EventAny extends Event {
+class EventAny extends AbstractEvent_1.default {
     static type = `${package_json_1.name}/${this.name}`;
-    detail;
     constructor(options) {
-        super(EventAny.type, options);
-        this.detail = options.detail;
+        super(EventAny.type, options, arguments);
     }
@@ -12,0 +14,0 @@ }

dist/Evented.d.ts

@@ -5,5 +5,5 @@ import { _eventTarget, eventTarget } from './utils';
     addEventListener(type: string, callback: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions | boolean): void;
-    dispatchEvent(event: Event): boolean;
     removeEventListener(callback: EventListenerOrEventListenerObject | null, options?: EventListenerOptions | boolean): void;
     removeEventListener(type: string, callback: EventListenerOrEventListenerObject | null, options?: EventListenerOptions | boolean): void;
+    dispatchEvent(event: Event): boolean;
 }
@@ -10,0 +10,0 @@ declare function Evented(): <T extends new (...args: any[]) => object>(constructor: T) => {

dist/index.d.ts

@@ -0,3 +1,4 @@
+export { default as AbstractEvent } from './AbstractEvent';
+export { default as EventAny } from './EventAny';
 export { Evented } from './Evented';
-export { default as EventAny } from './EventAny';
 export * as utils from './utils';

dist/index.js

@@ -29,8 +29,10 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.utils = exports.EventAny = exports.Evented = void 0;
+exports.utils = exports.Evented = exports.EventAny = exports.AbstractEvent = void 0;
+var AbstractEvent_1 = require("./AbstractEvent");
+Object.defineProperty(exports, "AbstractEvent", { enumerable: true, get: function () { return __importDefault(AbstractEvent_1).default; } });
+var EventAny_1 = require("./EventAny");
+Object.defineProperty(exports, "EventAny", { enumerable: true, get: function () { return __importDefault(EventAny_1).default; } });
 var Evented_1 = require("./Evented");
 Object.defineProperty(exports, "Evented", { enumerable: true, get: function () { return Evented_1.Evented; } });
-var EventAny_1 = require("./EventAny");
-Object.defineProperty(exports, "EventAny", { enumerable: true, get: function () { return __importDefault(EventAny_1).default; } });
 exports.utils = __importStar(require("./utils"));
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "@matrixai/events",
-  "version": "1.0.0",
+  "version": "2.0.2",
   "author": "Matrix AI",
@@ -50,3 +50,6 @@ "contributors": [
     "typescript": "^4.9.3"
+  },
+  "engines": {
+    "node": ">=19.0.0"
   }
 }

README.md

@@ -8,2 +8,75 @@ # js-events
 
+### `AbstractEvent`
+
+```ts
+// For when you just want a regular event without `detail`
+// Note that the `detail` type is `null`
+class Event1 extends AbstractEvent {}
+
+// For when you want a event with `detail`
+class Event2 extends AbstractEvent<string> {}
+
+// Allow caller to customise the `detail` type
+// Note that the `detail` type is `unknown`
+// This would be rare to use, prefer `Event4`
+class Event3<T> extends AbstractEvent<T> {}
+
+// Allow caller to customise the `detail` type
+// But this is more accurate as not passing anything
+// Would mean the `detail` is in fact `null`
+class Event4<T = null> extends AbstractEvent<T> {}
+
+// When you need to customise the constructor signature
+class Event5 extends AbstractEvent<string> {
+  constructor(options: CustomEventInit<string>) {
+    // Make sure you pass `arguments`!
+    super(Event5.name, options, arguments);
+  }
+}
+```
+
+When redispatching an event, you must call `event.clone()`. The same instance cannot be redispatched. When the event is cloned, all constructor parameters are shallow-copied.
+
+### `Evented`
+
+We combine `Evented` with `AbstractEvent` to gain type-safety and convenience of the wildcard any handler.
+
+```ts
+class EventCustom extends AbstractEvent {}
+
+interface X extends Evented {}
+@Evented()
+class X {}
+
+const x = new X();
+
+// Handle specific event, use the `name` property as the key
+x.addEventListener(EventCustom.name, (e) => {
+  console.log(e as EventCustom);
+});
+
+// Handle any event
+x.addEventListener((e) => {
+  // This is the wrapped underlying event
+  console.log((e as EventAny).detail);
+})
+```
+
+Note that all events pass through the any event handler, it is not a "fall through" handler.
+
+You can use this style to handle relevant events to perform side-effects, as well as propagate upwards irrelevant events.
+
+Note that some side-effects you perform may trigger an infinite loop by causing something to emit the specific event type that you are handling. In these cases you should specialise handling of those events with a `once: true`  option, so that they are only handled once.
+
+```ts
+x.addEventListener(EventInfinite.name, (e) => {
+  console.log(e as EventInfinite);
+  performActionThatMayTriggerEventInfinite();
+}, { once: true });
+```
+
+This will terminate the infinite loop on the first time it gets handled.
+
+Therefore it is a good idea to always be as specific with your event types as possible.
+
 ## Installation
@@ -10,0 +83,0 @@

No alert changes

Improved metrics

Total package byte prevSize

29135

increased by24.69%

Number of package files

18

increased by20%

Lines of code

202

increased by41.26%

Number of lines in readme file

144

increased by102.82%

No dependency changes