events-ex 2.1.1 → 2.3.0

package/docs/event-emitter/classes/EventEmitter.md

@@ -0,0 +1,369 @@
+[**events-ex**](../../README.md)
+
+***
+
+[events-ex](../../modules.md) / [event-emitter](../README.md) / EventEmitter
+
+# Class: EventEmitter
+
+Defined in: [src/event-emitter.d.ts:6](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L6)
+
+Class that represents an event emitter.
+
+## Constructors
+
+### Constructor
+
+> **new EventEmitter**(): `EventEmitter`
+
+#### Returns
+
+`EventEmitter`
+
+## Properties
+
+### defaultMaxListeners
+
+> `static` **defaultMaxListeners**: `number`
+
+Defined in: [src/event-emitter.d.ts:7](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L7)
+
+## Methods
+
+### emit()
+
+> **emit**(`eventName`, ...`args`): `any`
+
+Defined in: [src/event-emitter.d.ts:58](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L58)
+
+Emits the specified event type with the given arguments.
+
+#### Parameters
+
+##### eventName
+
+`string`
+
+##### args
+
+...`any`[]
+
+The event type followed by any number of arguments to be passed to the listener functions.
+
+#### Returns
+
+`any`
+
+The result of the event.
+
+***
+
+### emitAsync()
+
+> **emitAsync**(`eventName`, ...`args`): `Promise`\<`any`\>
+
+Defined in: [src/event-emitter.d.ts:64](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L64)
+
+Asynchronously emits the specified event type with the given arguments.
+
+#### Parameters
+
+##### eventName
+
+`string`
+
+##### args
+
+...`any`[]
+
+The event type followed by any number of arguments to be passed to the listener functions.
+
+#### Returns
+
+`Promise`\<`any`\>
+
+A promise that resolves with the result of the event.
+
+***
+
+### listenerCount()
+
+> **listenerCount**(`eventName`): `number`
+
+Defined in: [src/event-emitter.d.ts:93](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L93)
+
+Returns the count of listeners that are registered to listen for the specified event.
+
+#### Parameters
+
+##### eventName
+
+The name of the event to get the listeners for.
+
+`string` | `RegExp`
+
+#### Returns
+
+`number`
+
+- the listeners count
+
+***
+
+### listeners()
+
+> **listeners**(`eventName`): `Function`[]
+
+Defined in: [src/event-emitter.d.ts:86](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L86)
+
+Returns an array of functions that are registered to listen for the specified event.
+
+#### Parameters
+
+##### eventName
+
+The name of the event to get the listeners for.
+
+`string` | `RegExp`
+
+#### Returns
+
+`Function`[]
+
+- An array of functions that are registered to listen for the specified event.
+
+***
+
+### off()
+
+> **off**(`eventName`, `listener`): `EventEmitter`
+
+Defined in: [src/event-emitter.d.ts:43](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L43)
+
+Removes a listener function from the specified event type.
+
+#### Parameters
+
+##### eventName
+
+`string` | `RegExp`
+
+##### listener
+
+`Function`
+
+The listener function to be removed.
+
+#### Returns
+
+`EventEmitter`
+
+The EventEmitter instance to allow chaining.
+
+#### Throws
+
+If the listener is not a function.
+
+#### See
+
+[removeListener](#removelistener)
+
+***
+
+### on()
+
+> **on**(`eventName`, `listener`, `index?`): `EventEmitter`
+
+Defined in: [src/event-emitter.d.ts:21](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L21)
+
+Adds a listener function to the specified event type.
+
+#### Parameters
+
+##### eventName
+
+`string` | `RegExp`
+
+##### listener
+
+`Function`
+
+The listener function to be called when the event is emitted.
+
+##### index?
+
+The index at which to insert the listener.
+       - 'first' or -Infinity: adds to the beginning of the listeners (stay at the front).
+       - 'last' or Infinity: adds to the end of the listeners (stay at the back).
+       - number: inserts at the specified index within the normal listeners zone.
+       If not specified, the listener will be added at the end of the normal listeners.
+
+`number` | `"first"` | `"last"`
+
+#### Returns
+
+`EventEmitter`
+
+The EventEmitter instance to allow chaining.
+
+#### Throws
+
+If the listener is not a function.
+
+***
+
+### once()
+
+> **once**(`eventName`, `listener`, `index?`): `EventEmitter`
+
+Defined in: [src/event-emitter.d.ts:34](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L34)
+
+Adds a one-time listener function to the specified event type.
+
+#### Parameters
+
+##### eventName
+
+`string` | `RegExp`
+
+##### listener
+
+`Function`
+
+The listener function to be called once when the event is emitted.
+
+##### index?
+
+The index at which to insert the listener.
+       - 'first' or -Infinity: adds to the beginning of the listeners (stay at the front).
+       - 'last' or Infinity: adds to the end of the listeners (stay at the back).
+       - number: inserts at the specified index within the normal listeners zone.
+       If not specified, the listener will be added at the end of the normal listeners.
+
+`number` | `"first"` | `"last"`
+
+#### Returns
+
+`EventEmitter`
+
+The EventEmitter instance to allow chaining.
+
+#### Throws
+
+If the listener is not a function.
+
+***
+
+### removeAllListeners()
+
+> **removeAllListeners**(`eventName?`): `EventEmitter`
+
+Defined in: [src/event-emitter.d.ts:71](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L71)
+
+Removes all listeners for a specific event or all events from an event emitter.
+
+#### Parameters
+
+##### eventName?
+
+The event to remove listeners for. If not provided, all listeners for all events will be removed.
+
+`string` | `RegExp`
+
+#### Returns
+
+`EventEmitter`
+
+- The event emitter with all listeners removed.
+
+***
+
+### removeListener()
+
+> **removeListener**(`eventName`, `listener`): `EventEmitter`
+
+Defined in: [src/event-emitter.d.ts:52](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L52)
+
+Removes a listener function from the specified event type.
+
+#### Parameters
+
+##### eventName
+
+`string` | `RegExp`
+
+##### listener
+
+`Function`
+
+The listener function to be removed.
+
+#### Returns
+
+`EventEmitter`
+
+The EventEmitter instance to allow chaining.
+
+#### Throws
+
+If the listener is not a function.
+
+#### See
+
+[off](#off)
+
+***
+
+### setMaxListeners()
+
+> **setMaxListeners**(`n`): `EventEmitter`
+
+Defined in: [src/event-emitter.d.ts:79](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L79)
+
+Sets the maximum number of listeners allowed for the event emitter.
+
+#### Parameters
+
+##### n
+
+`number`
+
+The maximum number of listeners to set. Must be a positive integer.
+
+#### Returns
+
+`EventEmitter`
+
+The EventEmitter instance for method chaining.
+
+#### Throws
+
+If `n` is not a positive integer.
+
+***
+
+### ~~listenerCount()~~
+
+> `static` **listenerCount**(`emitter`, `eventName`): `number`
+
+Defined in: [src/event-emitter.d.ts:101](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/event-emitter.d.ts#L101)
+
+Returns the count of listeners that are registered to listen for the specified event.
+
+#### Parameters
+
+##### emitter
+
+`EventEmitter`
+
+##### eventName
+
+`string` | `RegExp`
+
+#### Returns
+
+`number`
+
+#### Deprecated
+
+use emitter.listenerCount instead

package/docs/eventable/README.md

@@ -0,0 +1,17 @@
+[**events-ex**](../README.md)
+
+***
+
+[events-ex](../modules.md) / eventable
+
+# eventable
+
+## Functions
+
+- [eventable](functions/eventable.md)
+
+## References
+
+### default
+
+Renames and re-exports [eventable](functions/eventable.md)

package/docs/eventable/functions/eventable.md

@@ -0,0 +1,82 @@
+[**events-ex**](../../README.md)
+
+***
+
+[events-ex](../../modules.md) / [eventable](../README.md) / eventable
+
+# Function: eventable()
+
+> **eventable**\<`T`\>(`targetClass?`, `options?`): `EnhancedClass`\<`T`, (`aClass?`) => `Function`\>
+
+Defined in: [src/eventable.js:89](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/eventable.js#L89)
+
+Adds event-emitting capabilities to a class by injecting necessary methods and properties.
+
+This function uses `createAbilityInjector` from `custom-ability` to inject event-related methods
+into the target class. The injected methods include standard EventEmitter functionality such as
+`on`, `off`, `emit`, `emitAsync`, `once`, `listeners`, `@listenerCount` and more. It also ensures compatibility with Node.js `EventEmitter`
+by including methods like `listenerCount`, `setMaxListeners`, `addListener`, `removeListener`, and `removeAllListeners`.
+
+ eventable
+
+## Type Parameters
+
+### T
+
+`T` *extends* `ClassEx`
+
+## Parameters
+
+### targetClass?
+
+`T`
+
+### options?
+
+`AbilityOptions`
+
+Optional configuration for the injection process:
+  * `include` (string[]|string): Specifies which methods should be added.
+    Static methods should use the prefix '@'.
+  * `exclude` (string[]|string): Specifies which methods should not be added.
+    Static methods should use the prefix '@'.
+  * `methods` (Object): Custom methods to override or extend the default behavior.
+    Use `this.super()` to call the original method and `this.self` to access the original context.
+  * `classMethods` (Object): Custom static methods to be added to the class.
+
+## Returns
+
+`EnhancedClass`\<`T`, (`aClass?`) => `Function`\>
+
+The same `aClass` class with event capabilities injected. The return value is the modified `aClass` itself.
+
+## Examples
+
+```ts
+import { eventable } from 'events-ex';
+
+class MyClass {}
+
+// Inject only specific methods: 'on', 'off', 'emit', 'emitAsync', and the static 'listenerCount'
+eventable(MyClass, { include: ['on', 'off', 'emit', 'emitAsync', '@listenerCount'] });
+```
+
+```ts
+import { eventable } from 'events-ex';
+
+class OtherClass {
+  exec() {
+    console.log("Original exec");
+  }
+}
+
+// Inject event capabilities and override the `exec` method
+eventable(OtherClass, {
+  methods: {
+    exec() {
+      console.log("New exec");
+      this.super(); // Calls the original `exec` method
+    }
+  }
+});
+```

package/docs/has-listeners/README.md

@@ -0,0 +1,17 @@
+[**events-ex**](../README.md)
+
+***
+
+[events-ex](../modules.md) / has-listeners
+
+# has-listeners
+
+## Functions
+
+- [hasListeners](functions/hasListeners.md)
+
+## References
+
+### default
+
+Renames and re-exports [hasListeners](functions/hasListeners.md)

package/docs/has-listeners/functions/hasListeners.md

@@ -0,0 +1,38 @@
+[**events-ex**](../../README.md)
+
+***
+
+[events-ex](../../modules.md) / [has-listeners](../README.md) / hasListeners
+
+# Function: hasListeners()
+
+> **hasListeners**(`obj`, `type?`): `boolean`
+
+Defined in: [src/has-listeners.js:20](https://github.com/snowyu/events-ex.js/blob/53cfb5bb3f7229cb549e99d410c0d6d39665eb0a/src/has-listeners.js#L20)
+
+Checks if an object has event listeners.
+
+## Parameters
+
+### obj
+
+`any`
+
+The object to check. Must not be null or undefined.
+
+### type?
+
+`string`
+
+Optional parameter specifying the event type. If provided, checks for the existence of listeners for this specific type.
+
+## Returns
+
+`boolean`
+
+- If `type` is provided, returns whether listeners for the specified event type exist.
+         - If `type` is not provided, returns whether the object has any event listeners.
+
+## Throws
+
+Throws a TypeError if `obj` is null or undefined.

package/docs/index/README.md

@@ -0,0 +1,85 @@
+[**events-ex**](../README.md)
+
+***
+
+[events-ex](../modules.md) / index
+
+# index
+
+## References
+
+### allOff
+
+Re-exports [allOff](../all-off/functions/allOff.md)
+
+***
+
+### default
+
+Renames and re-exports [EventEmitter](../event-emitter/classes/EventEmitter.md)
+
+***
+
+### Event
+
+Re-exports [Event](../event/classes/Event.md)
+
+***
+
+### eventable
+
+Re-exports [eventable](../eventable/functions/eventable.md)
+
+***
+
+### EventEmitter
+
+Re-exports [EventEmitter](../event-emitter/classes/EventEmitter.md)
+
+***
+
+### hasListeners
+
+Re-exports [hasListeners](../has-listeners/functions/hasListeners.md)
+
+***
+
+### methods
+
+Re-exports [methods](../wrap-event-emitter/variables/methods.md)
+
+***
+
+### pipe
+
+Re-exports [pipe](../pipe/functions/pipe.md)
+
+***
+
+### pipeAsync
+
+Re-exports [pipeAsync](../pipe-async/functions/pipeAsync.md)
+
+***
+
+### RegExpEventSymbol
+
+Re-exports [RegExpEventSymbol](../consts/variables/RegExpEventSymbol.md)
+
+***
+
+### states
+
+Re-exports [states](../consts/variables/states.md)
+
+***
+
+### unify
+
+Re-exports [unify](../unify/functions/unify.md)
+
+***
+
+### wrapEventEmitter
+
+Re-exports [wrapEventEmitter](../wrap-event-emitter/functions/wrapEventEmitter.md)

package/docs/modules.md

@@ -1,27 +1,28 @@
-[events-ex](README.md) / Exports
+[**events-ex**](README.md)
 
-# events-ex
+***
 
-## Table of contents
+# events-ex
 
-### Modules
+## Modules
 
-- [all-off](modules/all_off.md)
-- [consts](modules/consts.md)
-- [default-methods](modules/default_methods.md)
-- [event](modules/event.md)
-- [event-emitter](modules/event_emitter.md)
-- [event-emitter](modules/event_emitter-1.md)
-- [eventable](modules/eventable.md)
-- [has-listeners](modules/has_listeners.md)
-- [index](modules/index.md)
-- [pipe](modules/pipe.md)
-- [pipe-async](modules/pipe_async.md)
-- [unify](modules/unify.md)
-- [util/array-remove](modules/util_array_remove.md)
-- [util/object-for-each](modules/util_object_for_each.md)
-- [util/string-pad](modules/util_string_pad.md)
-- [util/to-int](modules/util_to_int.md)
-- [util/valid-callable](modules/util_valid_callable.md)
-- [util/valid-object](modules/util_valid_object.md)
-- [wrap-event-emitter](modules/wrap_event_emitter.md)
+- [all-off](all-off/README.md)
+- [consts](consts/README.md)
+- [default-methods](default-methods/README.md)
+- [event](event/README.md)
+- [event-emitter](event-emitter/README.md)
+- [event-emitter](event-emitter/README-1.md)
+- [eventable](eventable/README.md)
+- [has-listeners](has-listeners/README.md)
+- [index](index/README.md)
+- [pipe](pipe/README.md)
+- [pipe-async](pipe-async/README.md)
+- [unify](unify/README.md)
+- [util/array-remove](util/array-remove/README.md)
+- [util/object-for-each](util/object-for-each/README.md)
+- [util/promise-any](util/promise-any/README.md)
+- [util/string-pad](util/string-pad/README.md)
+- [util/to-int](util/to-int/README.md)
+- [util/valid-callable](util/valid-callable/README.md)
+- [util/valid-object](util/valid-object/README.md)
+- [wrap-event-emitter](wrap-event-emitter/README.md)

package/docs/pipe/README.md

@@ -0,0 +1,17 @@
+[**events-ex**](../README.md)
+
+***
+
+[events-ex](../modules.md) / pipe
+
+# pipe
+
+## Functions
+
+- [pipe](functions/pipe.md)
+
+## References
+
+### default
+
+Renames and re-exports [pipe](functions/pipe.md)