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);