diff --git a/src/modules/esl-event-listener/README.md b/src/modules/esl-event-listener/README.md index a105a798c..491065a2e 100644 --- a/src/modules/esl-event-listener/README.md +++ b/src/modules/esl-event-listener/README.md @@ -61,6 +61,7 @@ All active subscriptions are stored in a hidden property of the `host` object. - `capture` - marker to use the capture phase of the DOM event life-cycle; - `passive` - marker to use passive (non-blocking) subscription of the native event (if supported); - `once` - marker to destroy the subscription after the first event catch. +- `group` - auxiliary property to group subscriptions. Does not affect the subscription behavior. Can be used for filtering and bulk operations. All of the `ESLEventListener` instance fields are read-only; the subscription can't be changed once created. @@ -170,6 +171,19 @@ Here is the list of supported keys of `ESLEventDesriptor`: Default Value: `false` Description: marker to unsubscribe the listener after the first successful handling of the event. + +- #### `group` key + Type: `string` + Description: auxiliary property to group subscriptions. Does not affect the subscription behavior. Can be used for filtering and bulk operations. + + E.g.: + ```typescript + ESLEventUtils.subscribe(host, {event: 'click', group: 'group'}, handler1); + ESLEventUtils.subscribe(host, {event: 'click', group: 'group'}, handler2); + // ... + ESLEventUtils.unsubscribe(host, {group: 'group'}); // Unsubscribes all subscriptions with the 'group' key + ``` + - #### `auto` key (for `ESLEventDesriptorFn` declaration only) Type: `boolean` Default Value: `false` for `ESLEventUtils.initDescriptor`, `true` for `@listen` decorator @@ -180,6 +194,7 @@ Here is the list of supported keys of `ESLEventDesriptor`: Allows to inherit `ESLEventDesriptor` data from the `ESLEventDesriptorFn` from the prototype chain. See [`initDescriptor`](#-esleventutilsinitdescriptor) usages example. + ### Automatic (collectable) descriptors Auto-collectable (or auto-subscribable) descriptors can be subscribed at once during the initialization of the `host` object. diff --git a/src/modules/esl-event-listener/core/listener.ts b/src/modules/esl-event-listener/core/listener.ts index aece3edaa..1193c5bf7 100644 --- a/src/modules/esl-event-listener/core/listener.ts +++ b/src/modules/esl-event-listener/core/listener.ts @@ -49,6 +49,8 @@ export class ESLEventListener implements ESLListenerDefinition, EventListenerObj public readonly auto?: boolean; public readonly passive?: boolean; + public readonly group?: string; + protected constructor( public readonly host: object, public readonly event: string, diff --git a/src/modules/esl-event-listener/core/types.ts b/src/modules/esl-event-listener/core/types.ts index e6ecb5930..ae218a8f6 100644 --- a/src/modules/esl-event-listener/core/types.ts +++ b/src/modules/esl-event-listener/core/types.ts @@ -52,6 +52,9 @@ export type ESLListenerDescriptor { const div = document.createElement('div'); beforeEach(() => { - ESLEventUtils.subscribe(div, {event: 'click'}, handle); - ESLEventUtils.subscribe(div, {event: 'event'}, handle); + ESLEventUtils.subscribe(div, {event: 'click', group: 'test'}, handle); + ESLEventUtils.subscribe(div, {event: 'event', group: 'test'}, handle); }); test('all', () => { @@ -39,6 +39,11 @@ describe('ESLEventUtils:unsubscribe successfully removes listener', () => { expect(ESLEventUtils.listeners(div).length).toBe(0); }); + test('by group', () => { + ESLEventUtils.unsubscribe(div, {group: 'test'}); + expect(ESLEventUtils.listeners(div).length).toBe(0); + }); + test('with multiple criteria', () => { ESLEventUtils.unsubscribe(div, handle, {event: 'key'}); expect(ESLEventUtils.listeners(div).length).toBe(2);