New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
seng-event
Advanced tools
seng-event - npm Package Compare versions
Comparing version 2.0.0-alpha.7 to 2.0.0
@@ -0,5 +1,10 @@ | ||
| /** | ||
| * @module seng-event | ||
| * @preferred | ||
| * | ||
| * The main seng-event module | ||
| */ | ||
| import { default as _export } from './lib/EventDispatcher'; | ||
| export { default as BaseEvent } from './lib/BaseEvent'; | ||
| export { default as createEventType } from './lib/createEventType'; | ||
| export { default as createIsomorphicEventType } from './lib/createIsomorphicEventType'; | ||
| export { default as createEventClass } from './lib/createEventClass'; | ||
| export { default as createIsomorphicEventClass } from './lib/createIsomorphicEventClass'; | ||
| export { default as EventPhase } from './lib/EventPhase'; | ||
@@ -6,0 +11,0 @@ export { default as EventListenerData } from './lib/EventListenerData'; |
21
index.js
@@ -6,18 +6,14 @@ "use strict"; | ||
| exports.__esModule = true; | ||
| exports.default = exports.AbstractEvent = exports.CallListenerResult = exports.EventListenerData = exports.EventPhase = exports.createIsomorphicEventType = exports.createEventType = exports.BaseEvent = void 0; | ||
| exports.default = exports.AbstractEvent = exports.CallListenerResult = exports.EventListenerData = exports.EventPhase = exports.createIsomorphicEventClass = exports.createEventClass = void 0; | ||
| var _EventDispatcher = _interopRequireDefault(require("./lib/EventDispatcher")); | ||
| var _BaseEvent = _interopRequireDefault(require("./lib/BaseEvent")); | ||
| var _createEventClass = _interopRequireDefault(require("./lib/createEventClass")); | ||
| exports.BaseEvent = _BaseEvent.default; | ||
| exports.createEventClass = _createEventClass.default; | ||
| var _createEventType = _interopRequireDefault(require("./lib/createEventType")); | ||
| var _createIsomorphicEventClass = _interopRequireDefault(require("./lib/createIsomorphicEventClass")); | ||
| exports.createEventType = _createEventType.default; | ||
| exports.createIsomorphicEventClass = _createIsomorphicEventClass.default; | ||
| var _createIsomorphicEventType = _interopRequireDefault(require("./lib/createIsomorphicEventType")); | ||
| exports.createIsomorphicEventType = _createIsomorphicEventType.default; | ||
| var _EventPhase = _interopRequireDefault(require("./lib/EventPhase")); | ||
@@ -38,3 +34,10 @@ | ||
| exports.AbstractEvent = _AbstractEvent.default; | ||
| /** | ||
| * @module seng-event | ||
| * @preferred | ||
| * | ||
| * The main seng-event module | ||
| */ | ||
| var _default = _EventDispatcher.default; | ||
| exports.default = _default; |
@@ -0,1 +1,4 @@ | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| import EventPhase from './EventPhase'; | ||
@@ -7,8 +10,22 @@ import CallListenerResult from './CallListenerResult'; | ||
| * Abstract base class for all events that can be dispatched through [[EventDispatcher]]. This class | ||
| * should not be instantiated but extended by a specific event class. For an event class with basic | ||
| * functionality that can be instantiated see [[BasicEvent]] | ||
| * should not be instantiated but extended by a specific event class. | ||
| * | ||
| * @see [[createEventClass]] | ||
| */ | ||
| declare abstract class AbstractEvent { | ||
| /** | ||
| * The type of the event. Event listeners will only be called if their eventType match this type. | ||
| */ | ||
| type: string; | ||
| /** | ||
| * If true, the event will also go through a bubbling phase. See [[EventDispatcher.dispatchEvent]] | ||
| * for more information on the event phases. | ||
| */ | ||
| bubbles: boolean; | ||
| /** | ||
| * Indicates if [[preventDefault]] can be called on this event. This will prevent the 'default | ||
| * action' of the event from being executed. It is up to the [[EventDispatcher]] instance that dispatches the | ||
| * event to stop the default action from executing when the [[EventDispatcher.dispatchEvent|dispatchEvent]] | ||
| * method returns `false` | ||
| */ | ||
| cancelable: boolean; | ||
@@ -18,3 +35,3 @@ /** | ||
| * listeners are currently being called on. After completion of an event dispatch this value | ||
| * will be reset to _null_. | ||
| * will be reset to `null`. | ||
| */ | ||
@@ -38,7 +55,7 @@ currentTarget: EventDispatcher | null; | ||
| * _1 January 1970 00:00:00 UTC_. This value will only be set if the setTimestamp parameter in the constructor | ||
| * is set to _true_. Otherwise, this value will be _0_. | ||
| * is set to `true`. Otherwise, this value will be _0_. | ||
| */ | ||
| timeStamp: number; | ||
| /** | ||
| * _true_ if [[cancelable]] is true and [[preventDefault]] has been called on this event. | ||
| * `true` if [[cancelable]] is true and [[preventDefault]] has been called on this event. | ||
| */ | ||
@@ -54,3 +71,3 @@ defaultPrevented: boolean; | ||
| * event to stop the default action from executing when the [[EventDispatcher.dispatchEvent|dispatchEvent]] | ||
| * method returns _false_ | ||
| * method returns `false` | ||
| * @param setTimeStamp If true, will set the [[timeStamp]] property of this event to the current time whenever | ||
@@ -73,3 +90,3 @@ * this event is dispatched. | ||
| /** | ||
| * May only be called when the [[cancelable]] property of an event is set to _true_. Indicates to the | ||
| * May only be called when the [[cancelable]] property of an event is set to `true`. Indicates to the | ||
| * instance that dispatched the event that the default action for the event should not be executed. | ||
@@ -76,0 +93,0 @@ */ |
@@ -14,7 +14,15 @@ "use strict"; | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| /** | ||
| * @ignore | ||
| */ | ||
| var callListenerResult = _CallListenerResult.default.NONE; | ||
| /** | ||
| * Abstract base class for all events that can be dispatched through [[EventDispatcher]]. This class | ||
| * should not be instantiated but extended by a specific event class. For an event class with basic | ||
| * functionality that can be instantiated see [[BasicEvent]] | ||
| * should not be instantiated but extended by a specific event class. | ||
| * | ||
| * @see [[createEventClass]] | ||
| */ | ||
@@ -26,5 +34,21 @@ | ||
| /** | ||
| * The type of the event. Event listeners will only be called if their eventType match this type. | ||
| */ | ||
| /** | ||
| * If true, the event will also go through a bubbling phase. See [[EventDispatcher.dispatchEvent]] | ||
| * for more information on the event phases. | ||
| */ | ||
| /** | ||
| * Indicates if [[preventDefault]] can be called on this event. This will prevent the 'default | ||
| * action' of the event from being executed. It is up to the [[EventDispatcher]] instance that dispatches the | ||
| * event to stop the default action from executing when the [[EventDispatcher.dispatchEvent|dispatchEvent]] | ||
| * method returns `false` | ||
| */ | ||
| /** | ||
| * Will be updated by [[EventDispatcher]] during the dispatch of an event to the target that | ||
| * listeners are currently being called on. After completion of an event dispatch this value | ||
| * will be reset to _null_. | ||
| * will be reset to `null`. | ||
| */ | ||
@@ -48,7 +72,7 @@ | ||
| * _1 January 1970 00:00:00 UTC_. This value will only be set if the setTimestamp parameter in the constructor | ||
| * is set to _true_. Otherwise, this value will be _0_. | ||
| * is set to `true`. Otherwise, this value will be _0_. | ||
| */ | ||
| /** | ||
| * _true_ if [[cancelable]] is true and [[preventDefault]] has been called on this event. | ||
| * `true` if [[cancelable]] is true and [[preventDefault]] has been called on this event. | ||
| */ | ||
@@ -64,3 +88,3 @@ | ||
| * event to stop the default action from executing when the [[EventDispatcher.dispatchEvent|dispatchEvent]] | ||
| * method returns _false_ | ||
| * method returns `false` | ||
| * @param setTimeStamp If true, will set the [[timeStamp]] property of this event to the current time whenever | ||
@@ -120,3 +144,3 @@ * this event is dispatched. | ||
| /** | ||
| * May only be called when the [[cancelable]] property of an event is set to _true_. Indicates to the | ||
| * May only be called when the [[cancelable]] property of an event is set to `true`. Indicates to the | ||
| * instance that dispatched the event that the default action for the event should not be executed. | ||
@@ -123,0 +147,0 @@ */ |
@@ -0,5 +1,25 @@ | ||
| /** | ||
| * @module seng-event/lib/BaseEvent | ||
| */ | ||
| import AbstractEvent from './AbstractEvent'; | ||
| /** | ||
| * Base class for classes generated by [[createEventClass]]. Thin abstraction of [[AbstractEvent]] | ||
| * that adds an additional typed `data` field to events. | ||
| * | ||
| * @typeparam TDataType The type of the `data` field on this event. If not given, will set the type | ||
| * to `undefined` (no data field) | ||
| * @typeparam TEventType A union type of the possible string literals that are possibilities for the | ||
| * `type` property. If not set, will default to `string` (allows for all strings) | ||
| */ | ||
| declare class BaseEvent<TDataType = void, TEventType extends string = string> extends AbstractEvent { | ||
| type: TEventType; | ||
| data: TDataType; | ||
| /** | ||
| * | ||
| * @param type The event type | ||
| * @param data The data to attach to the event | ||
| * @param bubbles see [[AbstractEvent]] | ||
| * @param cancelable see [[AbstractEvent]] | ||
| * @param setTimeStamp see [[AbstractEvent]] | ||
| */ | ||
| constructor(type: TEventType, data: TDataType, bubbles?: boolean, cancelable?: boolean, setTimeStamp?: boolean); | ||
@@ -6,0 +26,0 @@ clone(): BaseEvent<TDataType, TEventType>; |
@@ -16,2 +16,15 @@ "use strict"; | ||
| /** | ||
| * @module seng-event/lib/BaseEvent | ||
| */ | ||
| /** | ||
| * Base class for classes generated by [[createEventClass]]. Thin abstraction of [[AbstractEvent]] | ||
| * that adds an additional typed `data` field to events. | ||
| * | ||
| * @typeparam TDataType The type of the `data` field on this event. If not given, will set the type | ||
| * to `undefined` (no data field) | ||
| * @typeparam TEventType A union type of the possible string literals that are possibilities for the | ||
| * `type` property. If not set, will default to `string` (allows for all strings) | ||
| */ | ||
| var BaseEvent = | ||
@@ -22,2 +35,10 @@ /*#__PURE__*/ | ||
| /** | ||
| * | ||
| * @param type The event type | ||
| * @param data The data to attach to the event | ||
| * @param bubbles see [[AbstractEvent]] | ||
| * @param cancelable see [[AbstractEvent]] | ||
| * @param setTimeStamp see [[AbstractEvent]] | ||
| */ | ||
| function BaseEvent(type, data, bubbles, cancelable, setTimeStamp) { | ||
@@ -41,2 +62,3 @@ var _this; | ||
| (0, _defineProperty2.default)((0, _assertThisInitialized2.default)((0, _assertThisInitialized2.default)(_this)), "data", void 0); | ||
| _this.type = type; | ||
| _this.data = data; | ||
@@ -43,0 +65,0 @@ return _this; |
| /** | ||
| * @module seng-event | ||
| */ | ||
| /** | ||
| * Enum that is returned by the [[AbstractEvent.callListener]] method | ||
@@ -6,13 +9,13 @@ */ | ||
| /** | ||
| * Indicates that neither [[IEvent.stopPropagation|stopPropagation]] nor | ||
| * [[IEvent.stopImmediatePropagation|stopImmediatePropagation]] has been called | ||
| * Indicates that neither [[AbstractEvent.stopPropagation|stopPropagation]] nor | ||
| * [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation]] has been called | ||
| */ | ||
| NONE = 0, | ||
| /** | ||
| * Indicates that [[IEvent.stopPropagation|stopPropagation]] has been called, but | ||
| * [[IEvent.stopImmediatePropagation|stopImmediatePropagation]] hasn't | ||
| * Indicates that [[AbstractEvent.stopPropagation|stopPropagation]] has been called, but | ||
| * [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation]] hasn't | ||
| */ | ||
| PROPAGATION_STOPPED = 1, | ||
| /** | ||
| * Indicates that [[IEvent.stopImmediatePropagation|stopImmediatePropagation]] has been called | ||
| * Indicates that [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation]] has been called | ||
| */ | ||
@@ -19,0 +22,0 @@ IMMEDIATE_PROPAGATION_STOPPED = 2 |
@@ -7,2 +7,6 @@ "use strict"; | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| /** | ||
| * Enum that is returned by the [[AbstractEvent.callListener]] method | ||
@@ -9,0 +13,0 @@ */ |
@@ -0,1 +1,4 @@ | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| import SengDisposable from 'seng-disposable'; | ||
@@ -12,2 +15,7 @@ import EventListenerData from './EventListenerData'; | ||
| * [DOM Event W3 spec](https://www.w3.org/TR/DOM-Level-2-Events/events.html) | ||
| * | ||
| * @typeparam TEvent The type of the events that this EventDispatcher is expected to dispatch. To | ||
| * allow for multiple event classes, use a union type here. If you don't specify an event type, | ||
| * any event that `extends` [[AbstractEvent]] can be dispatched, but you won't get automatic typing | ||
| * for event handlers. | ||
| */ | ||
@@ -17,3 +25,3 @@ export default class EventDispatcher<TEvent extends AbstractEvent = any> extends SengDisposable { | ||
| * The parent EventDispatcher instance. If this instance has no parent, this value will be | ||
| * set to _null_. The parent is used in the bubbling and capturing phases of events. | ||
| * set to `null`. The parent is used in the bubbling and capturing phases of events. | ||
| * @see [[dispatchEvent]] for more information on the bubbling and capturing chain | ||
@@ -23,12 +31,12 @@ */ | ||
| /** | ||
| * An object containing all event listeners by [[IEvent.type|event type]]. Each value | ||
| * An object containing all event listeners by [[AbstractEvent.type|event type]]. Each value | ||
| * on this object is an Array of [[EventListenerData]] objects for each event listener | ||
| * added with that type. | ||
| */ | ||
| private listeners; | ||
| protected listeners: EventListenerMap<TEvent>; | ||
| /** | ||
| * The value that will be set as [[IEvent.target|target]] on events that are dispatched | ||
| * by this EventDispatcher instance. | ||
| * The value that will be set as [[AbstractEvent.target|target]] on events that are dispatched | ||
| * by this EventDispatcher instance. Set to the value passed to the constructor | ||
| */ | ||
| private target; | ||
| protected target: EventDispatcher; | ||
| /** | ||
@@ -40,5 +48,18 @@ * Creates an EventDispatcher instance. | ||
| * bubbling and capturing, see [[dispatchEvent]] | ||
| * @param target If set, will set the [[IEvent.target|target]] attribute of all events | ||
| * @param target If set, will set the [[AbstractEvent.target|target]] attribute of all events | ||
| * dispatched by this EventDispatcher to the given object. If not set, will use this instance | ||
| * as a target for dispatched events. | ||
| * @example You can use the `target` parameter to proxy the EventDispatcher instead of extending | ||
| * it directly. | ||
| * ```ts | ||
| * class Foo { | ||
| * public dispatcher:EventDispatcher<FooEvent>; | ||
| * | ||
| * constructor() { | ||
| * this.dispatcher = new EventDispatcher<FooEvent>(null, this); | ||
| * } | ||
| * | ||
| * ... | ||
| * }; | ||
| * ``` | ||
| */ | ||
@@ -50,27 +71,27 @@ constructor(parent?: EventDispatcher | null, target?: EventDispatcher); | ||
| * top-most instance first and the direct parent of this EventDispatcher last. On each | ||
| * ancestor, we call all event handlers that are added with the _useCapture_ argument | ||
| * set to _true_ and the _eventType_ set to the same [[IEvent.type|type]] as | ||
| * ancestor, we call all event handlers that are added with the `useCapture` argument | ||
| * set to `true` and the `eventType` set to the same [[AbstractEvent.type|type]] as | ||
| * the given event. | ||
| * If this EventDispatcher has no parent, this phase will be skipped. | ||
| * 2. The target phase. In this phase we call all event handlers on this EventDispatcher | ||
| * instance that listen for the same [[IEvent.type|type]] as the given event. | ||
| * instance that listen for the same [[AbstractEvent.type|type]] as the given event. | ||
| * 3. The bubbling phase. This phase will only be executed if the given event has the | ||
| * [[IEvent.bubbles|bubbles]] property set to _true_. If so, we will again walk through | ||
| * [[AbstractEvent.bubbles|bubbles]] property set to `true`. If so, we will again walk through | ||
| * all ancestors of this EventDispatcher, but in the reverse order: the direct parent | ||
| * of this instance first and the top-most parent last. On every ancestor, we will call | ||
| * all event handlers that are added with the _useCapture_ argument set to _false_ and the | ||
| * _eventType_ set to the same [[IEvent.type|type]] as the given event. | ||
| * all event handlers that are added with the `useCapture` argument set to `false` and the | ||
| * `eventType` set to the same [[AbstractEvent.type|type]] as the given event. | ||
| * | ||
| * If any of the event handlers call [[IEvent.stopPropagation|stopPropagation()]], we will | ||
| * If any of the event handlers call [[AbstractEvent.stopPropagation|stopPropagation()]], we will | ||
| * skip all event handlers that occur on a target later in the event chain. If an event handler | ||
| * calls [[IEvent.stopImmediatePropagation|stopImmediatePropagation()]], we will also skip | ||
| * calls [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation()]], we will also skip | ||
| * any event handlers on the same target in the event chain. | ||
| * @param event The event to dispatch | ||
| * @returns If one of the handlers that have been called during this dispatch | ||
| * called [[IEvent.preventDefault|event.preventDefault()]], this method will return _false_. | ||
| * called [[AbstractEvent.preventDefault|event.preventDefault()]], this method will return `false`. | ||
| * If no handlers have been called or none of the handlers have called | ||
| * [[IEvent.preventDefault|event.preventDefault()]], this method will return _true_. | ||
| * [[AbstractEvent.preventDefault|event.preventDefault()]], this method will return `true`. | ||
| * | ||
| * _Please note: [[IEvent.preventDefault|preventDefault()]] can only be called on | ||
| * events that have their [[IEvent.cancelable|cancelable]] property set to true_ | ||
| * > Please note: [[AbstractEvent.preventDefault|preventDefault()]] can only be called on | ||
| * > events that have their [[AbstractEvent.cancelable|cancelable]] property set to `true` | ||
| */ | ||
@@ -80,9 +101,9 @@ dispatchEvent(event: TEvent): boolean; | ||
| * Adds a new event listener. The given handler function will be called in the following cases: | ||
| * - An event with a [[IEvent.type|type]] that is equal to the given _eventType_ is dispatched | ||
| * - An event with a [[AbstractEvent.type|type]] that is equal to the given `eventType` is dispatched | ||
| * on this EventDispatcher instance. | ||
| * - An event with a [[IEvent.type|type]] that is equal to the given _eventType_ is dispatched | ||
| * on a child EventDispatcher, and the _useCapture_ parameter is set to _true_ | ||
| * - An event with [[IEvent.bubbles|bubbles]] set to _true_ and a [[IEvent.type|type]] that | ||
| * is equal to the given _eventType_ is dispatched on a child EventDispatcher, and the | ||
| * _useCapture_ parameter is set to _false_ | ||
| * - An event with a [[AbstractEvent.type|type]] that is equal to the given `eventType` is dispatched | ||
| * on a child EventDispatcher, and the `useCapture` parameter is set to `true` | ||
| * - An event with [[AbstractEvent.bubbles|bubbles]] set to `true` and a [[AbstractEvent.type|type]] that | ||
| * is equal to the given `eventType` is dispatched on a child EventDispatcher, and the | ||
| * `useCapture` parameter is set to `false` | ||
| * | ||
@@ -93,5 +114,5 @@ * @see [[dispatchEvent]] for more info on the which event listeners are called during | ||
| * @param handler The handler function that will be called when a matching event is dispatched. | ||
| * This function will retrieve the dispatched [[IEvent|event]] as a parameter | ||
| * This function will retrieve the dispatched [[AbstractEvent|event]] as a parameter | ||
| * @param useCapture Indicates if this handler should be called during the capturing phase | ||
| * of an event chain. If and only if this is set to _false_ will this handler be called | ||
| * of an event chain. If and only if this is set to `false` will this handler be called | ||
| * during the bubbling phase of an event chain. | ||
@@ -108,7 +129,8 @@ * @param priority A number that indicates the priority of this event listener relative | ||
| * instance. | ||
| * @param eventType Will only look for event listeners with this _eventType_ | ||
| * @param eventType Will only look for event listeners with this `eventType` | ||
| * @param handler If set, will only match event listeners that have the same handler function | ||
| * @param useCapture If set, will only match event listeners that have the same _useCapture_ | ||
| * argument. _Please note: if no useCapture argument was provided to [[addEventListener]], it | ||
| * is set to false by default_ | ||
| * @param useCapture If set, will only match event listeners that have the same `useCapture` | ||
| * argument. | ||
| * > Please note: if no `useCapture` argument was provided to [[addEventListener]], it | ||
| * is set to `false` by default | ||
| * @returns {boolean} True if one or more event listeners exist | ||
@@ -118,6 +140,6 @@ */ | ||
| /** | ||
| * Checks if an event listener with a [[EventListenerData.type|type]] of the given _eventType_ exists | ||
| * Checks if an event listener with a [[EventListenerData.type|type]] of the given `eventType` exists | ||
| * on this EventDispatcher or any ancestor EventDispatcher instance. | ||
| * @param eventType The event type to check for | ||
| * @returns _true_ if a matching listener is found | ||
| * @returns `true` if a matching listener is found | ||
| */ | ||
@@ -131,5 +153,5 @@ willTrigger(eventType: TypesForEvent<TEvent>): boolean; | ||
| * not be called anymore, even if it was supposed to be called in the same event chain_ | ||
| * @param eventType Only event listeners of that have this _eventType_ are removed | ||
| * @param eventType Only event listeners of that have this `eventType` are removed | ||
| * @param handler Only event listeners that have this handler function will be removed | ||
| * @param useCapture Only event listeners that have been added with the same _useCapture_ | ||
| * @param useCapture Only event listeners that have been added with the same `useCapture` | ||
| * parameter will be removed. _Please note: if no useCapture argument is provided, only | ||
@@ -140,3 +162,3 @@ * event listeners that have useCapture set to false will be removed._ | ||
| /** | ||
| * Removes all event listeners that have a [[IEvent.type|type]] of the given _eventType_ | ||
| * Removes all event listeners that have a [[AbstractEvent.type|type]] of the given `eventType` | ||
| * from this EventDispatcher instance, regardless of their [[EventListenerData.handler|handler]] or | ||
@@ -147,3 +169,3 @@ * [[EventListenerData.useCapture|useCapture]] property. | ||
| * not be called anymore, even if it was supposed to be called in the same event chain_ | ||
| * @param eventType The [[IEvent.type|type]] of event to remove. If not provided, all event listeners | ||
| * @param eventType The [[AbstractEvent.type|type]] of event to remove. If not provided, all event listeners | ||
| * will be removed regardless of their type. | ||
@@ -154,3 +176,3 @@ */ | ||
| * Cleans up this EventListener instance. No event handlers on this EventDispatcher will be called | ||
| * and future calls to dispatchEvent() will be ignored. | ||
| * and future calls to [[EventDispatcher.dispatchEvent|dispatchEvent()]] will be ignored. | ||
| */ | ||
@@ -165,3 +187,3 @@ dispose(): void; | ||
| */ | ||
| private listenerSorter; | ||
| protected listenerSorter(e1: EventListenerData, e2: EventListenerData): number; | ||
| } | ||
@@ -174,6 +196,7 @@ /** | ||
| * possible values for that parameter. | ||
| * @hidden | ||
| * @param listeners A map of listeners to remove from. See [[EventDispatcher.listeners]] | ||
| * @param eventType If set, will only remove listeners added with this _eventType_ | ||
| * @param eventType If set, will only remove listeners added with this `eventType` | ||
| * @param handler If set, will only remove listeners with this _handler_ | ||
| * @param useCapture If set, will only remove listeners with the same value for _useCapture_ | ||
| * @param useCapture If set, will only remove listeners with the same value for `useCapture` | ||
| */ | ||
@@ -184,2 +207,3 @@ export declare const removeListenersFrom: <TEvent extends AbstractEvent>(listeners: EventListenerMap<TEvent>, eventType?: TEvent["type"] | null | undefined, handler?: EventHandlerForEvent<TEvent> | null | undefined, useCapture?: boolean | undefined) => void; | ||
| * parent (if it has one) will be first in the Array, and the most top-level parent will be last. | ||
| * @hidden | ||
| * @param target The instance to get parents for | ||
@@ -192,2 +216,3 @@ * @returns {Array<EventDispatcher>} The array of parents | ||
| * See [[EventDispatcher.dispatchEvent]] for more information on the event phases | ||
| * @hidden | ||
| * @param target The target to get the call tree for | ||
@@ -203,10 +228,11 @@ * @param bubbles If true, will also include the target instances of the _bubbling_ phase. If false, will | ||
| * dispatched. If no matching listeners are present, this function has no effect | ||
| * @hidden | ||
| * @param listeners The object that contains listeners to call. Has the same format as the | ||
| * [[EventDispatcher.listeners|listeners]] property on [[EventDispatcher]] | ||
| * @param event The event that may trigger listeners in the map | ||
| * @returns True if any of the listeners call [[IEvent.stopPropagation|stopPropagation()]] or | ||
| * [[IEvent.stopImmediatePropagation|stopImmediatePropagation]]. False if no listeners are called or none | ||
| * of them call [[IEvent.stopPropagation|stopPropagation()]] or | ||
| * [[IEvent.stopImmediatePropagation|stopImmediatePropagation]] | ||
| * @returns True if any of the listeners call [[AbstractEvent.stopPropagation|stopPropagation()]] or | ||
| * [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation]]. False if no listeners are called or none | ||
| * of them call [[AbstractEvent.stopPropagation|stopPropagation()]] or | ||
| * [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation]] | ||
| */ | ||
| export declare const callListeners: <TEvent extends AbstractEvent>(listeners: EventListenerMap<TEvent>, event: TEvent) => boolean; |
@@ -23,2 +23,6 @@ "use strict"; | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| /** | ||
| * Base class that adds the ability to dispatch events and attach handlers that should be | ||
@@ -30,2 +34,7 @@ * called when such events are triggered. | ||
| * [DOM Event W3 spec](https://www.w3.org/TR/DOM-Level-2-Events/events.html) | ||
| * | ||
| * @typeparam TEvent The type of the events that this EventDispatcher is expected to dispatch. To | ||
| * allow for multiple event classes, use a union type here. If you don't specify an event type, | ||
| * any event that `extends` [[AbstractEvent]] can be dispatched, but you won't get automatic typing | ||
| * for event handlers. | ||
| */ | ||
@@ -39,3 +48,3 @@ var EventDispatcher = | ||
| * The parent EventDispatcher instance. If this instance has no parent, this value will be | ||
| * set to _null_. The parent is used in the bubbling and capturing phases of events. | ||
| * set to `null`. The parent is used in the bubbling and capturing phases of events. | ||
| * @see [[dispatchEvent]] for more information on the bubbling and capturing chain | ||
@@ -45,3 +54,3 @@ */ | ||
| /** | ||
| * An object containing all event listeners by [[IEvent.type|event type]]. Each value | ||
| * An object containing all event listeners by [[AbstractEvent.type|event type]]. Each value | ||
| * on this object is an Array of [[EventListenerData]] objects for each event listener | ||
@@ -52,4 +61,4 @@ * added with that type. | ||
| /** | ||
| * The value that will be set as [[IEvent.target|target]] on events that are dispatched | ||
| * by this EventDispatcher instance. | ||
| * The value that will be set as [[AbstractEvent.target|target]] on events that are dispatched | ||
| * by this EventDispatcher instance. Set to the value passed to the constructor | ||
| */ | ||
@@ -63,5 +72,18 @@ | ||
| * bubbling and capturing, see [[dispatchEvent]] | ||
| * @param target If set, will set the [[IEvent.target|target]] attribute of all events | ||
| * @param target If set, will set the [[AbstractEvent.target|target]] attribute of all events | ||
| * dispatched by this EventDispatcher to the given object. If not set, will use this instance | ||
| * as a target for dispatched events. | ||
| * @example You can use the `target` parameter to proxy the EventDispatcher instead of extending | ||
| * it directly. | ||
| * ```ts | ||
| * class Foo { | ||
| * public dispatcher:EventDispatcher<FooEvent>; | ||
| * | ||
| * constructor() { | ||
| * this.dispatcher = new EventDispatcher<FooEvent>(null, this); | ||
| * } | ||
| * | ||
| * ... | ||
| * }; | ||
| * ``` | ||
| */ | ||
@@ -87,27 +109,27 @@ function EventDispatcher(parent, target) { | ||
| * top-most instance first and the direct parent of this EventDispatcher last. On each | ||
| * ancestor, we call all event handlers that are added with the _useCapture_ argument | ||
| * set to _true_ and the _eventType_ set to the same [[IEvent.type|type]] as | ||
| * ancestor, we call all event handlers that are added with the `useCapture` argument | ||
| * set to `true` and the `eventType` set to the same [[AbstractEvent.type|type]] as | ||
| * the given event. | ||
| * If this EventDispatcher has no parent, this phase will be skipped. | ||
| * 2. The target phase. In this phase we call all event handlers on this EventDispatcher | ||
| * instance that listen for the same [[IEvent.type|type]] as the given event. | ||
| * instance that listen for the same [[AbstractEvent.type|type]] as the given event. | ||
| * 3. The bubbling phase. This phase will only be executed if the given event has the | ||
| * [[IEvent.bubbles|bubbles]] property set to _true_. If so, we will again walk through | ||
| * [[AbstractEvent.bubbles|bubbles]] property set to `true`. If so, we will again walk through | ||
| * all ancestors of this EventDispatcher, but in the reverse order: the direct parent | ||
| * of this instance first and the top-most parent last. On every ancestor, we will call | ||
| * all event handlers that are added with the _useCapture_ argument set to _false_ and the | ||
| * _eventType_ set to the same [[IEvent.type|type]] as the given event. | ||
| * all event handlers that are added with the `useCapture` argument set to `false` and the | ||
| * `eventType` set to the same [[AbstractEvent.type|type]] as the given event. | ||
| * | ||
| * If any of the event handlers call [[IEvent.stopPropagation|stopPropagation()]], we will | ||
| * If any of the event handlers call [[AbstractEvent.stopPropagation|stopPropagation()]], we will | ||
| * skip all event handlers that occur on a target later in the event chain. If an event handler | ||
| * calls [[IEvent.stopImmediatePropagation|stopImmediatePropagation()]], we will also skip | ||
| * calls [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation()]], we will also skip | ||
| * any event handlers on the same target in the event chain. | ||
| * @param event The event to dispatch | ||
| * @returns If one of the handlers that have been called during this dispatch | ||
| * called [[IEvent.preventDefault|event.preventDefault()]], this method will return _false_. | ||
| * called [[AbstractEvent.preventDefault|event.preventDefault()]], this method will return `false`. | ||
| * If no handlers have been called or none of the handlers have called | ||
| * [[IEvent.preventDefault|event.preventDefault()]], this method will return _true_. | ||
| * [[AbstractEvent.preventDefault|event.preventDefault()]], this method will return `true`. | ||
| * | ||
| * _Please note: [[IEvent.preventDefault|preventDefault()]] can only be called on | ||
| * events that have their [[IEvent.cancelable|cancelable]] property set to true_ | ||
| * > Please note: [[AbstractEvent.preventDefault|preventDefault()]] can only be called on | ||
| * > events that have their [[AbstractEvent.cancelable|cancelable]] property set to `true` | ||
| */ | ||
@@ -157,9 +179,9 @@ | ||
| * Adds a new event listener. The given handler function will be called in the following cases: | ||
| * - An event with a [[IEvent.type|type]] that is equal to the given _eventType_ is dispatched | ||
| * - An event with a [[AbstractEvent.type|type]] that is equal to the given `eventType` is dispatched | ||
| * on this EventDispatcher instance. | ||
| * - An event with a [[IEvent.type|type]] that is equal to the given _eventType_ is dispatched | ||
| * on a child EventDispatcher, and the _useCapture_ parameter is set to _true_ | ||
| * - An event with [[IEvent.bubbles|bubbles]] set to _true_ and a [[IEvent.type|type]] that | ||
| * is equal to the given _eventType_ is dispatched on a child EventDispatcher, and the | ||
| * _useCapture_ parameter is set to _false_ | ||
| * - An event with a [[AbstractEvent.type|type]] that is equal to the given `eventType` is dispatched | ||
| * on a child EventDispatcher, and the `useCapture` parameter is set to `true` | ||
| * - An event with [[AbstractEvent.bubbles|bubbles]] set to `true` and a [[AbstractEvent.type|type]] that | ||
| * is equal to the given `eventType` is dispatched on a child EventDispatcher, and the | ||
| * `useCapture` parameter is set to `false` | ||
| * | ||
@@ -170,5 +192,5 @@ * @see [[dispatchEvent]] for more info on the which event listeners are called during | ||
| * @param handler The handler function that will be called when a matching event is dispatched. | ||
| * This function will retrieve the dispatched [[IEvent|event]] as a parameter | ||
| * This function will retrieve the dispatched [[AbstractEvent|event]] as a parameter | ||
| * @param useCapture Indicates if this handler should be called during the capturing phase | ||
| * of an event chain. If and only if this is set to _false_ will this handler be called | ||
| * of an event chain. If and only if this is set to `false` will this handler be called | ||
| * during the bubbling phase of an event chain. | ||
@@ -204,7 +226,8 @@ * @param priority A number that indicates the priority of this event listener relative | ||
| * instance. | ||
| * @param eventType Will only look for event listeners with this _eventType_ | ||
| * @param eventType Will only look for event listeners with this `eventType` | ||
| * @param handler If set, will only match event listeners that have the same handler function | ||
| * @param useCapture If set, will only match event listeners that have the same _useCapture_ | ||
| * argument. _Please note: if no useCapture argument was provided to [[addEventListener]], it | ||
| * is set to false by default_ | ||
| * @param useCapture If set, will only match event listeners that have the same `useCapture` | ||
| * argument. | ||
| * > Please note: if no `useCapture` argument was provided to [[addEventListener]], it | ||
| * is set to `false` by default | ||
| * @returns {boolean} True if one or more event listeners exist | ||
@@ -234,6 +257,6 @@ */ | ||
| /** | ||
| * Checks if an event listener with a [[EventListenerData.type|type]] of the given _eventType_ exists | ||
| * Checks if an event listener with a [[EventListenerData.type|type]] of the given `eventType` exists | ||
| * on this EventDispatcher or any ancestor EventDispatcher instance. | ||
| * @param eventType The event type to check for | ||
| * @returns _true_ if a matching listener is found | ||
| * @returns `true` if a matching listener is found | ||
| */ | ||
@@ -251,5 +274,5 @@ ; | ||
| * not be called anymore, even if it was supposed to be called in the same event chain_ | ||
| * @param eventType Only event listeners of that have this _eventType_ are removed | ||
| * @param eventType Only event listeners of that have this `eventType` are removed | ||
| * @param handler Only event listeners that have this handler function will be removed | ||
| * @param useCapture Only event listeners that have been added with the same _useCapture_ | ||
| * @param useCapture Only event listeners that have been added with the same `useCapture` | ||
| * parameter will be removed. _Please note: if no useCapture argument is provided, only | ||
@@ -268,3 +291,3 @@ * event listeners that have useCapture set to false will be removed._ | ||
| /** | ||
| * Removes all event listeners that have a [[IEvent.type|type]] of the given _eventType_ | ||
| * Removes all event listeners that have a [[AbstractEvent.type|type]] of the given `eventType` | ||
| * from this EventDispatcher instance, regardless of their [[EventListenerData.handler|handler]] or | ||
@@ -275,3 +298,3 @@ * [[EventListenerData.useCapture|useCapture]] property. | ||
| * not be called anymore, even if it was supposed to be called in the same event chain_ | ||
| * @param eventType The [[IEvent.type|type]] of event to remove. If not provided, all event listeners | ||
| * @param eventType The [[AbstractEvent.type|type]] of event to remove. If not provided, all event listeners | ||
| * will be removed regardless of their type. | ||
@@ -286,3 +309,3 @@ */ | ||
| * Cleans up this EventListener instance. No event handlers on this EventDispatcher will be called | ||
| * and future calls to dispatchEvent() will be ignored. | ||
| * and future calls to [[EventDispatcher.dispatchEvent|dispatchEvent()]] will be ignored. | ||
| */ | ||
@@ -317,6 +340,7 @@ ; | ||
| * possible values for that parameter. | ||
| * @hidden | ||
| * @param listeners A map of listeners to remove from. See [[EventDispatcher.listeners]] | ||
| * @param eventType If set, will only remove listeners added with this _eventType_ | ||
| * @param eventType If set, will only remove listeners added with this `eventType` | ||
| * @param handler If set, will only remove listeners with this _handler_ | ||
| * @param useCapture If set, will only remove listeners with the same value for _useCapture_ | ||
| * @param useCapture If set, will only remove listeners with the same value for `useCapture` | ||
| */ | ||
@@ -357,2 +381,3 @@ | ||
| * parent (if it has one) will be first in the Array, and the most top-level parent will be last. | ||
| * @hidden | ||
| * @param target The instance to get parents for | ||
@@ -379,2 +404,3 @@ * @returns {Array<EventDispatcher>} The array of parents | ||
| * See [[EventDispatcher.dispatchEvent]] for more information on the event phases | ||
| * @hidden | ||
| * @param target The target to get the call tree for | ||
@@ -409,9 +435,10 @@ * @param bubbles If true, will also include the target instances of the _bubbling_ phase. If false, will | ||
| * dispatched. If no matching listeners are present, this function has no effect | ||
| * @hidden | ||
| * @param listeners The object that contains listeners to call. Has the same format as the | ||
| * [[EventDispatcher.listeners|listeners]] property on [[EventDispatcher]] | ||
| * @param event The event that may trigger listeners in the map | ||
| * @returns True if any of the listeners call [[IEvent.stopPropagation|stopPropagation()]] or | ||
| * [[IEvent.stopImmediatePropagation|stopImmediatePropagation]]. False if no listeners are called or none | ||
| * of them call [[IEvent.stopPropagation|stopPropagation()]] or | ||
| * [[IEvent.stopImmediatePropagation|stopImmediatePropagation]] | ||
| * @returns True if any of the listeners call [[AbstractEvent.stopPropagation|stopPropagation()]] or | ||
| * [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation]]. False if no listeners are called or none | ||
| * of them call [[AbstractEvent.stopPropagation|stopPropagation()]] or | ||
| * [[AbstractEvent.stopImmediatePropagation|stopImmediatePropagation]] | ||
| */ | ||
@@ -418,0 +445,0 @@ |
@@ -0,3 +1,13 @@ | ||
| /** | ||
| * @module seng-event/lib/eventHasType | ||
| */ | ||
| import BaseEvent from './BaseEvent'; | ||
| /** | ||
| * Checks if the given [[BaseEvent]] has a the given type and if so, | ||
| * asserts to the compiler that it is a [[BaseEvent]] with that specific type | ||
| * as the `type` property. | ||
| * @param event The event to check | ||
| * @param type A string literal `type` | ||
| */ | ||
| declare function eventHasType<TType extends string>(event: BaseEvent<any, any>, type: TType): event is BaseEvent<any, TType>; | ||
| export default eventHasType; |
@@ -6,2 +6,13 @@ "use strict"; | ||
| /** | ||
| * @module seng-event/lib/eventHasType | ||
| */ | ||
| /** | ||
| * Checks if the given [[BaseEvent]] has a the given type and if so, | ||
| * asserts to the compiler that it is a [[BaseEvent]] with that specific type | ||
| * as the `type` property. | ||
| * @param event The event to check | ||
| * @param type A string literal `type` | ||
| */ | ||
| function eventHasType(event, type) { | ||
@@ -8,0 +19,0 @@ return event.type === type; |
@@ -0,1 +1,4 @@ | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| import sengDisposable from 'seng-disposable'; | ||
@@ -17,3 +20,3 @@ import EventDispatcher from './EventDispatcher'; | ||
| /** | ||
| * This property will be set to _true_ by the [[EventDispatcher]] this listener is bound to when | ||
| * This property will be set to `true` by the [[EventDispatcher]] this listener is bound to when | ||
| * the listener is removed. This is to make sure the handler is not called, even if the listener | ||
@@ -27,5 +30,5 @@ * is removed while dispatching the event. | ||
| * @param handler The handler function that will be called when a matching event is dispatched | ||
| * @param useCapture Set to the _useCapture_ argument passed to [[EventDispatcher.addEventListener|addEventListener]] | ||
| * @param priority Set to the _priority_ argument passed to [[EventDispatcher.addEventListener|addEventListener]]. | ||
| * Used to sort the listener within the [[EventDispatcher._listeners|_listeners]] object of the EventDispatcher | ||
| * @param useCapture Set to the `useCapture` argument passed to [[EventDispatcher.addEventListener|addEventListener]] | ||
| * @param priority Set to the `priority` argument passed to [[EventDispatcher.addEventListener|addEventListener]]. | ||
| * Used to sort the listener within the [[EventDispatcher.listeners|listeners]] object of the EventDispatcher | ||
| */ | ||
@@ -32,0 +35,0 @@ constructor(dispatcher: EventDispatcher<TEvent>, type: TypesForEvent<TEvent>, handler: EventHandlerForEvent<any>, useCapture: boolean, priority: number); |
@@ -17,2 +17,6 @@ "use strict"; | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| /** | ||
| * Data object that is created on every call to [[EventDispatcher.addEventListener]]. The object is | ||
@@ -28,3 +32,3 @@ * saved on the [[EventDispatcher.listeners]] object for internal use but is also returned by the | ||
| /** | ||
| * This property will be set to _true_ by the [[EventDispatcher]] this listener is bound to when | ||
| * This property will be set to `true` by the [[EventDispatcher]] this listener is bound to when | ||
| * the listener is removed. This is to make sure the handler is not called, even if the listener | ||
@@ -38,5 +42,5 @@ * is removed while dispatching the event. | ||
| * @param handler The handler function that will be called when a matching event is dispatched | ||
| * @param useCapture Set to the _useCapture_ argument passed to [[EventDispatcher.addEventListener|addEventListener]] | ||
| * @param priority Set to the _priority_ argument passed to [[EventDispatcher.addEventListener|addEventListener]]. | ||
| * Used to sort the listener within the [[EventDispatcher._listeners|_listeners]] object of the EventDispatcher | ||
| * @param useCapture Set to the `useCapture` argument passed to [[EventDispatcher.addEventListener|addEventListener]] | ||
| * @param priority Set to the `priority` argument passed to [[EventDispatcher.addEventListener|addEventListener]]. | ||
| * Used to sort the listener within the [[EventDispatcher.listeners|listeners]] object of the EventDispatcher | ||
| */ | ||
@@ -43,0 +47,0 @@ function EventListenerData(dispatcher, type, handler, useCapture, priority) { |
| /** | ||
| * @module seng-event | ||
| */ | ||
| /** | ||
| * An enum for possible event phases that an event can be in | ||
@@ -3,0 +6,0 @@ */ |
@@ -7,2 +7,6 @@ "use strict"; | ||
| /** | ||
| * @module seng-event | ||
| */ | ||
| /** | ||
| * An enum for possible event phases that an event can be in | ||
@@ -9,0 +13,0 @@ */ |
@@ -0,15 +1,54 @@ | ||
| /** | ||
| * @module seng-event/lib/EventTypings | ||
| */ | ||
| import AbstractEvent from './AbstractEvent'; | ||
| import EventListenerData from './EventListenerData'; | ||
| import IsomorphicBaseEvent from './IsomorphicBaseEvent'; | ||
| /** | ||
| * Extract the typeof the `type` property of an [[AbstractEvent]] (which is possibly a union) | ||
| */ | ||
| export declare type TypesForEvent<TEvent extends AbstractEvent> = TEvent['type']; | ||
| /** | ||
| * Event handler for an event with the given type | ||
| */ | ||
| export declare type EventHandlerForEvent<TEvent extends AbstractEvent> = (event: TEvent) => any; | ||
| /** | ||
| * Map of [[EventListenerData]] which is stored on each [[EventDispatcher]] | ||
| */ | ||
| export declare type EventListenerMap<TEvent extends AbstractEvent> = { | ||
| [type: string]: Array<EventListenerData<TEvent>>; | ||
| }; | ||
| /** | ||
| * Returns the (union) type of the `type` property on an event *if and only if* that type contains | ||
| * the given `TType` | ||
| * | ||
| * @example If `TEvent` is an `AbstractEvent` with `type` `'FOO'|'BAR'`, and `TType` is | ||
| * `'BAR'`, this will return `'FOO'|'BAR'` | ||
| * | ||
| * @example If `TEvent` is an `AbstractEvent` with `type` `'FOO'|'BAR'`, and `TType` is | ||
| * `'FOOBAR'`, this will return `never` | ||
| */ | ||
| export declare type ExtractEventTypeIfContains<TEvent extends AbstractEvent, TType extends string> = TType extends TEvent['type'] ? TEvent['type'] : never; | ||
| /** | ||
| * Takes a union of possible events `TEvent`, and extract only the events that contain a `type` | ||
| * property that can possibly be `TType` | ||
| */ | ||
| export declare type ExtractEventIfTypeContains<TEvent extends AbstractEvent, TType extends string> = TEvent extends { | ||
| type: ExtractEventTypeIfContains<TEvent, TType>; | ||
| } ? TEvent : never; | ||
| /** | ||
| * Takes an event `TEvent`. If `TEvent` extends `IsomorphicBaseEvent`, it will narrow down | ||
| * this `IsomorphicBaseEvent` to one which has the given `TType` | ||
| */ | ||
| export declare type UnpackIsomorphic<TEvent extends AbstractEvent, TType extends string> = TEvent extends IsomorphicBaseEvent<infer T, infer U, any> ? IsomorphicBaseEvent<T, U, TType> : TEvent; | ||
| /** | ||
| * Takes a union of event types, possible created with [[createEventClass]] or | ||
| * [[createIsomorphicEventClass]], and extracts the correct typings based on the | ||
| * given type `TType` | ||
| */ | ||
| export declare type ExtractEventOfType<TEvent extends AbstractEvent, TType extends string> = UnpackIsomorphic<ExtractEventIfTypeContains<TEvent, TType>, TType>; | ||
| /** | ||
| * Looks up the string literal type `T` in the tuple type `TTypes`, and returns the data | ||
| * type that can be found at the same index on `TDataTypes` | ||
| */ | ||
| export declare type DataForIsomorphicEvent<T extends string, TTypes extends Array<string>, TDataTypes extends Array<any>> = T extends TTypes[0] ? TDataTypes[0] : T extends TTypes[1] ? TDataTypes[1] : T extends TTypes[2] ? TDataTypes[2] : T extends TTypes[3] ? TDataTypes[3] : T extends TTypes[4] ? TDataTypes[4] : T extends TTypes[5] ? TDataTypes[5] : T extends TTypes[6] ? TDataTypes[6] : T extends TTypes[7] ? TDataTypes[7] : T extends TTypes[8] ? TDataTypes[8] : T extends TTypes[9] ? TDataTypes[9] : T extends TTypes[10] ? TDataTypes[10] : T extends TTypes[11] ? TDataTypes[11] : never; |
@@ -0,3 +1,9 @@ | ||
| /** | ||
| * @module seng-event/lib/IsomorphicBaseEvent | ||
| */ | ||
| import BaseEvent from './BaseEvent'; | ||
| import { DataForIsomorphicEvent } from './EventTypings'; | ||
| /** | ||
| * Options object as passed to [[createIsomorphicEventClass]] | ||
| */ | ||
| export interface EventOptions { | ||
@@ -8,5 +14,16 @@ bubbles?: boolean; | ||
| } | ||
| /** | ||
| * @ignore | ||
| */ | ||
| export declare type EventOptionsMap<TTypes extends string> = { | ||
| [T in TTypes]: EventOptions; | ||
| }; | ||
| /** | ||
| * Base class for classes generated by [[createIsomorphicEventClass]]. Thin abstraction of [[AbstractEvent]] | ||
| * that adds an additional typed `data` field to events. | ||
| * | ||
| * @typeparam TTypes Tuple type of all possible `type` string literals | ||
| * @typeparam TDataTypes Tuple type of all possible `data` objects | ||
| * @typeparam TType The string literal `type` of this particular instance | ||
| */ | ||
| declare class IsomorphicBaseEvent<TTypes extends Array<string>, TDataTypes extends Array<any>, TType extends TTypes[number]> extends BaseEvent<DataForIsomorphicEvent<TType, TTypes, TDataTypes>, TType> { | ||
@@ -13,0 +30,0 @@ type: TType; |
@@ -16,2 +16,14 @@ "use strict"; | ||
| /** | ||
| * @module seng-event/lib/IsomorphicBaseEvent | ||
| */ | ||
| /** | ||
| * Base class for classes generated by [[createIsomorphicEventClass]]. Thin abstraction of [[AbstractEvent]] | ||
| * that adds an additional typed `data` field to events. | ||
| * | ||
| * @typeparam TTypes Tuple type of all possible `type` string literals | ||
| * @typeparam TDataTypes Tuple type of all possible `data` objects | ||
| * @typeparam TType The string literal `type` of this particular instance | ||
| */ | ||
| var IsomorphicBaseEvent = | ||
@@ -25,6 +37,7 @@ /*#__PURE__*/ | ||
| var _typeOptions$type = typeOptions[type], | ||
| bubbles = _typeOptions$type.bubbles, | ||
| cancelable = _typeOptions$type.cancelable, | ||
| setTimeStamp = _typeOptions$type.setTimeStamp; | ||
| var _ref = typeOptions[type] || {}, | ||
| bubbles = _ref.bubbles, | ||
| cancelable = _ref.cancelable, | ||
| setTimeStamp = _ref.setTimeStamp; | ||
| _this = _BaseEvent.call(this, type, data, bubbles, cancelable, setTimeStamp) || this; | ||
@@ -35,2 +48,3 @@ (0, _defineProperty2.default)((0, _assertThisInitialized2.default)((0, _assertThisInitialized2.default)(_this)), "type", void 0); | ||
| _this.typeOptions = typeOptions; | ||
| _this.type = type; | ||
| return _this; | ||
@@ -37,0 +51,0 @@ } |
| { | ||
| "name": "seng-event", | ||
| "version": "2.0.0-alpha.7", | ||
| "version": "2.0.0", | ||
| "description": "Provides Classes and utilities for dispatching and listening to events.", | ||
@@ -22,4 +22,4 @@ "main": "./index.js", | ||
| "clean:npm": "shx rm -rf lib tmp index.js", | ||
| "doc": "npm-run-all -p doc:*", | ||
| "doc:typedoc": "typedoc --out docs/ src/ --mode file", | ||
| "docs": "npm-run-all -p docs:*", | ||
| "docs:typedoc": "typedoc --tsconfig tsconfig-docs.json --readme api-readme.md --mode modules --out docs/ src/", | ||
| "lint": "npm-run-all lint:*", | ||
@@ -39,2 +39,3 @@ "lint:js": "eslint src --ext .js --cache", | ||
| "npm run lint:js" | ||
| ], | ||
@@ -96,3 +97,5 @@ "src/**/*.ts": [ | ||
| "tslint-config-prettier": "^1.18.0", | ||
| "typedoc": "^0.9.0", | ||
| "typedoc": "^0.14.2", | ||
| "typedoc-plugin-external-module-name": "^2.0.0", | ||
| "typedoc-plugin-internal-external": "^2.0.1", | ||
| "typescript": "^3.3.3" | ||
@@ -99,0 +102,0 @@ }, |
210
README.md
| [](https://travis-ci.org/mediamonks/seng-event) | ||
| [](https://codeclimate.com/github/mediamonks/seng-event) | ||
| [](https://coveralls.io/github/mediamonks/seng-event?branch=master) | ||
@@ -19,3 +18,2 @@ [](https://www.npmjs.com/package/seng-event) | ||
| ## Installation | ||
@@ -26,3 +24,3 @@ | ||
| ``` | ||
| or | ||
| ```sh | ||
@@ -34,37 +32,201 @@ npm i -S seng-event | ||
| ### 1. Extend the EventDispatcher class | ||
| By extending `EventDispatcher`, your class gains the ability to dispatch events using `this.dispatchEvent()`. Other code | ||
| can listen to events by calling the `addEventListener()` method on your class. For more methods, see the generated | ||
| [API Docs](https://mediamonks.github.io/seng-event/) | ||
| ```ts | ||
| import EventDispatcher, {AbstractEvent} from 'seng-event'; | ||
| import {generateEventTypes, EVENT_TYPE_PLACEHOLDER} from 'seng-event/lib/util/eventTypeUtils'; | ||
| import EventDispatcher from 'seng-event'; | ||
| // extend EventDispatcher | ||
| class Foo extends EventDispatcher { | ||
| class Dog extends EventDispatcher { | ||
| ... | ||
| } | ||
| ``` | ||
| // Create your own event class | ||
| class FooEvent extends AbstractEvent { | ||
| ... | ||
| public static COMPLETE:string = EVENT_TYPE_PLACEHOLDER; | ||
| ... | ||
| ### 2. Create your own event class | ||
| Create an event class that defines the structure of the events you want to dispatch. This event class should extends the | ||
| base class `AbstractEvent`. There are multiple ways of doing this: | ||
| #### Use the `createEventClass()` utiltiy | ||
| ```ts | ||
| import { createEventClass } from 'seng-event'; | ||
| class DogEvent extends createEventClass()('BARK','JUMP','RUN','WALK') {} | ||
| ``` | ||
| #### Manually extend AbstractEvent | ||
| ```ts | ||
| import { AbstractEvent } from 'seng-event'; | ||
| class DogEvent extends AbstractEvent { | ||
| public static types = { | ||
| BARK: 'BARK', | ||
| JUMP: 'JUMP', | ||
| RUN: 'RUN', | ||
| WALK: 'WALK' | ||
| }; | ||
| public clone():DogEvent { | ||
| return new DogEvent(this.type); | ||
| } | ||
| } | ||
| generateEventTypes({FooEvent}); | ||
| ``` | ||
| > Note: we recommend the above convention of putting the available event types as a static member on the event. However, you are free to use any string as an event type. | ||
| // listener for events | ||
| const foo = new Foo(); | ||
| const exampleHandler = (event:FooEvent) => | ||
| { | ||
| console.log('Handler called!', event.type, event.target); | ||
| #### 3. Dispatch events | ||
| ```ts | ||
| const dog = new Dog(); | ||
| const runHandler = (event:DogEvent) => { | ||
| console.log('Dog is running!'); | ||
| } | ||
| foo.addEventListener(FooEvent.COMPLETE, exampleHandler); | ||
| dog.addEventListener(DogEvent.types.RUN, runHandler); | ||
| // dispatch an event (will execute exampleHandler and log 'Handler called!') | ||
| foo.dispatchEvent(new FooEvent(FooEvent.COMPLETE)); | ||
| // dispatch an event (will execute runHandler and log 'Dog is running!') | ||
| dog.dispatchEvent(new DogEvent(DogEvent.types.RUN)); | ||
| ``` | ||
| ## Binding your EventDispatcher child class to certain event classes | ||
| If you define which events your EventDispatcher is expected to dispatch, the class will have better typings on methods like `dispatchEvent` and `addEventListener`: | ||
| ```ts | ||
| class Dog extends EventDispatcher<DogEvent> { | ||
| ``` | ||
| You can use a union type to allow for multiple event classes: | ||
| ```ts | ||
| class Dog extends EventDispatcher<DogEvent|SomeOtherEvent|AnotherEvent> { | ||
| ``` | ||
| ## Documentation | ||
| ## Adding data to your events | ||
| It is common to attach some data to an event that can be read from the event handler. You can implement this manually if you extend `AbstractEvent`, but this can more easily be achieved with the `createEventClass` util: | ||
| ```ts | ||
| interface DogEventData { | ||
| mood: 'happy'|'sad'; | ||
| } | ||
| View the [generated documentation](http://mediamonks.github.io/seng-event/). | ||
| class DogEvent extends createEventClass<DogEventData>()('BARK','JUMP','RUN','WALK') {} | ||
| ``` | ||
| ```ts | ||
| // creating and dispatching events in the `Dog` class: | ||
| this.dispatchEvent(new DogEvent(DogEvent.types.JUMP, { mood: 'happy' })); | ||
| ``` | ||
| ```ts | ||
| // accessing the data | ||
| dog.addEventListener(DogEvent.types.JUMP, event => { | ||
| console.log(`Dog jumped in a ${event.mood} mood!`); | ||
| }); | ||
| ``` | ||
| ## Cancellation, propagation and setTimestamp | ||
| The cancellation, bubbling and timestamp functionality of this libary are heavily inspired by the [DOM Event W3 spec](https://www.w3.org/TR/DOM-Level-2-Events/events.html). These options can be enabled by passing `true` to the `createEventClass` util or `AbstractEvent` constructor: | ||
| ```ts | ||
| class DogEvent extends createEventClass<DogEventData>( | ||
| true, // bubbles | ||
| true, // cancelable | ||
| true // setTimestamp | ||
| )('BARK','JUMP','RUN','WALK') {} | ||
| ``` | ||
| ```ts | ||
| class DogEvent extends AbstractEvent { | ||
| constructor(type: string) { | ||
| super( | ||
| type, | ||
| true, // bubbles | ||
| true, // cancelable | ||
| true // setTimestamp | ||
| ); | ||
| } | ||
| } | ||
| ``` | ||
| #### Cancellation | ||
| Setting `cancelable` to true allows `preventDefault` to be called on the event. Checking if `preventDefault()` has been called is up to the implementer that calls `dispatchEvent()`: | ||
| ```ts | ||
| const event = new DogEvent(DogEvent.types.WALK, { mood: 'happy' }); | ||
| this.dispatchEvent(event); | ||
| if (!event.defaultPrevented) { | ||
| // do the default action here | ||
| } | ||
| ``` | ||
| #### Bubbling | ||
| Setting `bubbling` to `true` enables event propagation for the event if the event is dispatched on an `EventDispatcher` instance with a parent. See [this page](https://javascript.info/bubbling-and-capturing) for a general guide on how event bubbling works. | ||
| ```ts | ||
| class CustomElement extends EventDispatcher<ElementEvent> { | ||
| public name: string; | ||
| constructor(name: string, parent: CustomElement|null = null) { | ||
| super(parent); | ||
| this.name = name; | ||
| } | ||
| ... | ||
| } | ||
| const elementA = new CustomElement('A'); | ||
| const elementB = new CustomElement('B', elementA); | ||
| const elementC = new CustomElement('C', elementB); | ||
| elementA.addEventListener(ElementEvent.types.CLICK, (event) => { | ||
| console.log(`The element ${event.target.name} has been clicked!`); | ||
| }); | ||
| elementC.dispatchEvent(new ElementEvent(ElementEvent.types.CLICK)); // logs "The element C has been clicked!" | ||
| ``` | ||
| This library also supports a capturing phase. You can listen to events in the capturing phase by setting the `useCapture` parameter to `true` in the `addEventListener` method: | ||
| ```ts | ||
| elementA.addEventListener(ElementEvent.types.CLICK, (event) => console.log('Capture listener on A'), true); | ||
| elementA.addEventListener(ElementEvent.types.CLICK, (event) => console.log('Bubbling listener on A')); | ||
| elementB.addEventListener(ElementEvent.types.CLICK, (event) => console.log('Capture listener on B'), true); | ||
| elementB.addEventListener(ElementEvent.types.CLICK, (event) => console.log('Bubbling listener on B')); | ||
| elementC.dispatchEvent(new ElementEvent(ElementEvent.types.CLICK)); | ||
| // logs in the following order: | ||
| // Capture listener on A | ||
| // Capture listener on B | ||
| // Bubbling listener on B | ||
| // Bubbling listener on A | ||
| ``` | ||
| #### setTimestamp | ||
| Setting `setTimestamp` to `true` will cause a `timeStamp` property to be set on the event which is a UNIX timestamp of the time the event was dispatched. | ||
| ## Isomorphic event classes | ||
| An isomorphic event class can have different data and options for each event `type`. It can be created using the `createIsomorphicEventClass` util: | ||
| ```ts | ||
| interface DogEventData { | ||
| mood: 'happy'|'sad'; | ||
| } | ||
| interface DogMoveEventData extends DogEventData { | ||
| speed: number; | ||
| } | ||
| class DogEvent extends createIsomorphicEventClass< | ||
| DogEventData, DogEventData, DogMoveEventData, DogMoveEventData | ||
| >( | ||
| {}, {}, {}, { cancelable: true } | ||
| )( | ||
| 'BARK','JUMP','RUN','WALK' | ||
| ) {} | ||
| ``` | ||
| In the above example, a `RUN` and a `WALK` event now have a `speed` property on their event data, whereas the other events do not. In addition, all `WALK` events are cancelable. | ||
| ```ts | ||
| // OK | ||
| this.dispatchEvent(new DogEvent(DogEvent.types.JUMP, { mood: 'happy' })); | ||
| this.dispatchEvent(new DogEvent(DogEvent.types.BARK, { mood: 'sad' })); | ||
| this.dispatchEvent(new DogEvent(DogEvent.types.WALK, { mood: 'sad', speed: 0 })); | ||
| // NOT OK (will give a compiler error) | ||
| this.dispatchEvent(new DogEvent(DogEvent.types.JUMP, { mood: 'happy', speed: 10 })); | ||
| this.dispatchEvent(new DogEvent(DogEvent.types.RUN, { mood: 'happy' })); | ||
| ``` | ||
| ```ts | ||
| dog.addEventListener(DogEvent.types.JUMP, event => { | ||
| console.log(typeof event.data.speed); // logs undefined | ||
| }); | ||
| dog.addEventListener(DogEvent.types.WALK, event => { | ||
| console.log(typeof event.data.speed); // logs "number" | ||
| event.preventDefault(); // possible because 'WALK' is cancelable | ||
| }); | ||
| ``` | ||
| ## API documentation | ||
| View the full generated documentation [here](http://mediamonks.github.io/seng-event/). | ||
| ## Building | ||
@@ -121,3 +283,1 @@ | ||
| [MIT](./LICENSE) © MediaMonks | ||
@@ -8,4 +8,5 @@ { | ||
| "declarationDir": "./decl", | ||
| "baseUrl": ".", | ||
| "emitDeclarationOnly": true | ||
| } | ||
| } |
Sorry, the diff of this file is not supported yet
Fixed alerts
No v1
QualityPackage is not semver >=1. This means it is not stable and does not support ^ ranges.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by8.75%
338135
- Number of package files
- increased by9.68%
34
- Lines of code
- increased by34.16%
1614
- Number of low quality alerts
- decreased by-100%
0
- Number of lines in readme file
- increased by133.33%
280
Worsened metrics
- Dev dependency count
- increased by6.67%
32
No dependency changes