events-ex 1.1.7 → 2.0.0-alpha.1

package/.babelrc

@@ -0,0 +1,9 @@
+{
+  "plugins": [
+    ["@babel/plugin-proposal-dynamic-import"],
+    ["@babel/plugin-transform-modules-commonjs", {
+      "allowTopLevelThis": true,
+      // "importInterop": "node",
+    }]
+  ]
+}

package/.eslintrc.yml

@@ -0,0 +1,30 @@
+extends:
+  - '@antfu'
+  - prettier
+plugins:
+  - eslint-plugin-tsdoc
+ignorePatterns:
+  - web/**
+  - docs/**
+rules:
+  tsdoc/syntax: off
+  no-cond-assign: off
+  max-statements-per-line:
+    - error
+    - max: 3
+  prefer-rest-params: off
+  no-prototype-builtins: off
+  prefer-spread: off
+  prefer-arrow-callback: off
+  n/prefer-global/buffer: off
+  unicorn/prefer-includes: off
+  prefer-template: off
+  "@typescript-eslint/no-this-alias": off
+  "@typescript-eslint/no-invalid-this": off
+  "prefer-exponentiation-operator": off
+  # curly: [error, multi, consistent]
+  # curly: [error, multi-line]
+  # max-statements-per-line: off
+  # brace-style: [error, 1tbs, {allowSingleLine: true}]
+  # '@typescript-eslint/brace-style': off
+  # '@typescript-eslint/comma-dangle': off

package/.mocharc.yml

@@ -0,0 +1,3 @@
+require: '@babel/register'
+spec:
+  - 'test/**/*-test.js' # the positional arguments!

package/.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+web
+docs

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "arrowParens": "always",
+  "semi": false,
+  "bracketSpacing": true,
+  "trailingComma": "es5",
+  "printWidth": 80
+}

package/.versionrc

@@ -0,0 +1,36 @@
+{
+  "types": [
+    {
+      "type": "feat",
+      "section": "Features"
+    },
+    {
+      "type": "fix",
+      "section": "Bug Fixes"
+    },
+    {
+      "type": "chore",
+      "hidden": true
+    },
+    {
+      "type": "docs",
+      "hidden": true
+    },
+    {
+      "type": "style",
+      "hidden": true
+    },
+    {
+      "type": "refactor",
+      "section": "Refactor"
+    },
+    {
+      "type": "perf",
+      "section": "Performance"
+    },
+    {
+      "type": "test",
+      "hidden": true
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
+
+## [2.0.0-alpha.1](https://github.com/snowyu/events-ex.js/compare/v2.0.0-alpha.0...v2.0.0-alpha.1) (2023-06-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* remove deprecated files
+
+### Refactor
+
+* remove deprecated files ([d733a5c](https://github.com/snowyu/events-ex.js/commit/d733a5c6a6c554739ecbcb653996f1e546579fa4))
+
+## [2.0.0-alpha.0](https://github.com/snowyu/events-ex.js/compare/v1.1.7...v2.0.0-alpha.0) (2023-05-25)
+
+
+### Features
+
+* Add emitAsync supports ([c5a52e9](https://github.com/snowyu/events-ex.js/commit/c5a52e93e707b3f9f62b2d39eeb1e4870c0af185))
+* Add emitAsync supports ([97d44df](https://github.com/snowyu/events-ex.js/commit/97d44dfb5b2d5cda34848aaff4ea94c5af67b8f6))
+* **util:** extract util functions to here ([5bedb98](https://github.com/snowyu/events-ex.js/commit/5bedb98486dfa50c09f51d0fc669beb43b39c3b6))
+
+
+### Refactor
+
+* **benchmark:** use esm instead of commonjs ([366039e](https://github.com/snowyu/events-ex.js/commit/366039e9ddb8723db8d8a8257436f34af0a8ece8))
+* change exported name to wrapEventEmitter ([b0be8e7](https://github.com/snowyu/events-ex.js/commit/b0be8e72826fa189d03831c747367cfd8b8a6f78))
+* **consts:** change export name to states ([bf5c926](https://github.com/snowyu/events-ex.js/commit/bf5c9268ae29956d7281b4a1fc101952ef81896a))
+* **test:** use mocha instead of tad ([74261eb](https://github.com/snowyu/events-ex.js/commit/74261ebf632274eed90796d84c8f2df3352e62fb))
+* use esm instead of commonjs ([b1f55dc](https://github.com/snowyu/events-ex.js/commit/b1f55dcd15d6e91ec639baa022de68ae874bf109))

package/README.cn.md

@@ -0,0 +1,248 @@
+### events-ex [![Build Status](https://img.shields.io/travis/snowyu/events-ex.js/master.png)](http://travis-ci.org/snowyu/events-ex.js) [![npm](https://img.shields.io/npm/v/events-ex.svg)](https://npmjs.org/package/events-ex) [![downloads](https://img.shields.io/npm/dm/events-ex.svg)](https://npmjs.org/package/events-ex) [![license](https://img.shields.io/npm/l/events-ex.svg)](https://npmjs.org/package/events-ex)
+
+
+浏览器友好的增强的**事件**[能力][Ability]和类。 它主要是从 [event-emitter][event-emitter] 修改而来的。 本库可以为你的任何类添加(注入)**事件**[能力][Ability]。
+
+
+TODO: 异步事件,添加`emitAsync`方法. 没这么简单,因为要支持bubbling,所以必须顺序执行事件.
+将`bubbling`作为功能选项.如果没有启用,就可以乱发了.
+
+当关闭`bubbling`的时候,那么是否还需要用`event`对象传递.
+
+首先完成异步支持.已经完成.`emitAsync`方法已经加上.
+
+### Features
+
+* 重写核心架构
+* 尽最大可能性与[node events][Node Events] and [event-emitter][event-emitter]保持兼容
+* 更强大的 event-able [能力][Ability]
+* 可挂载的事件系统, 用于更好地控制事件处理
+* 支持异步事件通过 `emitAsync` 方法.
+
+### 区别
+
+* 与 [Node 事件模块](https://nodejs.org/api/events.html) 的区别
+  * **`改变`**: 事件支持冒泡机制与中断
+    * 事件对象(`Event Object`)作为监听器的 "this" 对象。
+      * `result` 属性: 可选, 如果设置,则将该结果返回到事件发射器(`Event Emitter`)。
+      * `stopped` 属性: 可选, 如果设置为 `true`，则会阻止剩余的监听器被执行。
+      * `target`属性: 事件发射器对象,原本的`this`
+    * **`改变`**: `emit` 方法返回监听器回调函数的结果而不是成功状态。
+    * **`改变`**: 监听器回调函数的 `this` 对象是 `Event Object` 事件对象而不是事件发射器对象。
+      * 事件发射器对象被放入 `Event` 对象的 `target` 属性中。
+  * 添加了`emitAsync`方法,支持异步事件
+* 与 [event-emitter](https://github.com/medikoo/event-emitter) 的区别
+  * **`改变`**: 事件支持冒泡机制（如上所述）
+  * 添加了默认最大监听器数量的类属性，以保持与 Node 事件模块的兼容性。
+  * 添加了 `setMaxListeners` 方法，以保持与 Node 事件模块的兼容性。
+  * 添加了 `error`、`newListener` 和 `removeListener` 事件，以保持与 Node 事件模块的兼容性。
+  * 添加了 `listeners()` 方法，以保持与 Node 事件模块的兼容性。
+  * 添加了 `listenerCount()` 类方法，以保持与 Node 事件模块的兼容性。
+  * 添加了`emitAsync`方法,支持异步事件
+
+
+### 安装
+
+```
+npm install events-ex@alpha
+```
+
+
+### 用法
+
+直接继承使用 `EventEmitter` 类
+
+```js
+import {EventEmitter} from 'events-ex';
+
+class MyClass extends EventEmitter {}
+```
+
+直接添加/注入事件(event-able)[能力][Ability] 到你的类:
+
+```js
+import {eventable} from 'events-ex';
+
+class MyClass extends MyRoot {}
+
+// inject the eventable ability to MyClass
+eventable(MyClass);
+```
+
+现在,可以在你的类中使用事件了:
+
+```js
+const my = new MyClass;
+
+my.on('event', function() {
+  console.log('event occur');
+});
+
+my.emit('event');
+```
+
+事件冒泡机制的使用:
+
+```js
+import {EventEmitter, states} from 'events-ex';
+import {isObject} from 'util-ex';
+
+class MyDb extends EventEmitter {
+  get(key) {
+    // Demo the event object bubbling usage:
+    let result = this.emit('getting', key)
+    if(isObject(result)) {
+      if (result.state === states.ABORT) return
+      if (result.state === states.DONE)  return result.result
+    }
+    return _get(key)
+  }
+}
+
+let db = new MyDb
+db.on('getting', function(key){
+  result = myGet(key);
+  if (result != null) {
+    // get the key succ
+    this.result = {
+      state: states.DONE,
+      result: result,
+    }
+  } else if (result === null) {
+    // abort default get key.
+    this.result = {state: states.ABORT};
+    // this.stopped = true // it will skip other listeners if true
+  }
+})
+```
+
+event-emitter usage:
+
+```javascript
+
+import {wrapEventEmitter as ee} from 'events-ex';
+
+class MyClass { /* .. */ };
+ee(MyClass.prototype); // All instances of MyClass will expose event-emitter interface
+
+const emitter = new MyClass();
+let listener;
+
+emitter.on('test', listener = function (args) {
+  // … react to 'test' event
+});
+
+emitter.once('test', function (args) {
+  // … react to first 'test' event (invoked only once!)
+});
+
+emitter.emit('test', arg1, arg2/*…args*/); // Two above listeners invoked
+emitter.emit('test', arg1, arg2/*…args*/); // Only first listener invoked
+
+emitter.off('test', listener);              // Removed first listener
+emitter.emit('test', arg1, arg2/*…args*/); // No listeners invoked
+```
+
+### API
+
+#### eventable(class[, options]) _(events-ex/eventable)_
+
+Add the event-able ability to the class directly.
+
+* `class`: the class to be injected the ability.
+* `options` _(object)_: optional options
+  * `include` _(string[]|string)_: only these emitter methods will be added to the class
+    * **NOTE:** static method should use the prefix '@' with name.
+  * `exclude` _(string[]|string)_: theses emitter methods would not be added to the class
+    * **NOTE:** static method should use the prefix '@' with name.
+  * `methods` _(object)_: hooked methods to the class
+    * key: the method name to hook.
+    * value: the new method function
+      * use `this.super()` to call the original method.
+      * `this.self` is the original `this` object.
+  * `classMethods` _(object)_: hooked class methods to the class
+
+```coffee
+  eventable  = require('events-ex/eventable')
+  #OtherClass = require('OtherClass')
+  class OtherClass
+    exec: -> console.log "my original exec"
+
+  class MyClass
+    # only 'on', 'off', 'emit' and static methods 'listenerCount' added to the class
+    eventable MyClass, include: ['on', 'off', 'emit', '@listenerCount']
+
+  # add the eventable ability to OtherClass and inject the exec method of OtherClass.
+  eventable OtherClass, methods:
+    exec: ->
+      console.log "new exec"
+      @super() # call the original method
+```
+
+#### allOff(obj) _(events-ex/all-off)_
+
+**keep compatible only**: the `removeAllListeners` has already been buildin.
+
+Removes all listeners from given event emitter object
+
+#### hasListeners(obj[, name]) _(events-ex/has-listeners)_
+
+Whether object has some listeners attached to the object.
+When `name` is provided, it checks listeners for specific event name
+
+```javascript
+var emitter = ee();
+var hasListeners = require('events-ex/has-listeners');
+var listener = function () {};
+
+hasListeners(emitter); // false
+
+emitter.on('foo', listener);
+hasListeners(emitter); // true
+hasListeners(emitter, 'foo'); // true
+hasListeners(emitter, 'bar'); // false
+
+emitter.off('foo', listener);
+hasListeners(emitter, 'foo'); // false
+```
+
+#### pipe(source, target[, emitMethodName]) _(events-ex/pipe)_
+
+Pipes all events from _source_ emitter onto _target_ emitter (all events from _source_ emitter will be emitted also on _target_ emitter, but not other way).
+Returns _pipe_ object which exposes `pipe.close` function. Invoke it to close configured _pipe_.
+It works internally by redefinition of `emit` method, if in your interface this method is referenced differently, provide its name (or symbol) with third argument.
+
+#### unify(emitter1, emitter2) _(events-ex/unify)_
+
+Unifies event handling for two objects. Events emitted on _emitter1_ would be also emitter on _emitter2_, and other way back.
+Non reversible.
+
+```javascript
+var eeUnify = require('events-ex/unify');
+
+var emitter1 = ee(), listener1, listener3;
+var emitter2 = ee(), listener2, listener4;
+
+emitter1.on('test', listener1 = function () { });
+emitter2.on('test', listener2 = function () { });
+
+emitter1.emit('test'); // Invoked listener1
+emitter2.emit('test'); // Invoked listener2
+
+var unify = eeUnify(emitter1, emitter2);
+
+emitter1.emit('test'); // Invoked listener1 and listener2
+emitter2.emit('test'); // Invoked listener1 and listener2
+
+emitter1.on('test', listener3 = function () { });
+emitter2.on('test', listener4 = function () { });
+
+emitter1.emit('test'); // Invoked listener1, listener2, listener3 and listener4
+emitter2.emit('test'); // Invoked listener1, listener2, listener3 and listener4
+```
+
+
+[event-emitter]: https://github.com/medikoo/event-emitter
+[Node Events]: https://nodejs.org/api/events.html
+[Ability]: https://github.com/snowyu/custom-ability.js
+

package/README.md

@@ -1,76 +1,68 @@
 ### events-ex [![Build Status](https://img.shields.io/travis/snowyu/events-ex.js/master.png)](http://travis-ci.org/snowyu/events-ex.js) [![npm](https://img.shields.io/npm/v/events-ex.svg)](https://npmjs.org/package/events-ex) [![downloads](https://img.shields.io/npm/dm/events-ex.svg)](https://npmjs.org/package/events-ex) [![license](https://img.shields.io/npm/l/events-ex.svg)](https://npmjs.org/package/events-ex)
 
 
-Browser-friendly enhanced events most compatible with standard node.js and coffee-script. It's modified from [event-emitter](https://github.com/medikoo/event-emitter) mainly. It can add event-able to your class directly.
-
+Browser-friendly enhanced event emitter [ability][Ability] and class. It's modified from [event-emitter][event-emitter] mainly. It can add/inject the event-able [ability][Ability] to your any class.
 
 ### Features
 
-* rewrite the core architecture
-* keep most compatible with [node events](nodejs.org/api/events.html) and [event-emitter](https://github.com/medikoo/event-emitter)
-+ more powerful event-able ability
-* hookable event system
+* Rewrite of the core architecture for improved performance and more powerful event-able ability
+* keep most compatible with [node events](nodejs.org/api/events.html) and [event-emitter][event-emitter]
+* Hookable event system for more control over event handling
+* Supports async event emitting via `emitAsync` method.
 
 ### Differences
 
-* Difference with [node events](nodejs.org/api/events.html)
-  - domain is not supported yet(TODO)
-  + **`broken change`**: The event object bubbling Supports
-    + the event object as listener's "this" object.
-    + return the result property of event object to emitter.
-    + prevent the rest of listener from be excuted if set the stopped property of event object to true
-    * **`broken change`**: the `emit` return the result of listeners's callback function instead of the successful state.
-    * **`broken change`**: the `this` object of listeners' callback function is the `Event` Object instead of the emitter object.
-      * the emitter object is put into the `target` property of the `Event` Object.
+* Difference with [node events](https://nodejs.org/api/events.html)
+  + **`broken change`**: The event supports bubbling and interruption
+    + the `event object` as listener's "this" object:
+      * `result`: If set, the result is returned to the `Event Emitter`.
+      * `stopped`: If set to `true`, it prevents the remaining listeners from being executed.
+      * `target`: The `Event Emitter` object, which was originally the `this` object.
+    * **`broken change`**: The `emit` return the result of listeners's callback function instead of the successful state.
+    * **`broken change`**: The `this` object of listeners' callback function is the `Event` Object instead of the emitter object.
+      * The emitter object is put into the `target` property of the `Event` Object.
+  * Adds async event emitting via `emitAsync` method.
 * Difference with [event-emitter](https://github.com/medikoo/event-emitter)
-  + **`broken change`**: The event object bubbling Supports(see above)
-  + add the defaultMaxListeners class property to keep compatible with node events.
-  + add the setMaxListeners method to keep compatible with node events.
-  + add `error`, `newListener` and `removeListener` events to keep compatible with node events.
-  + add listeners() method to keep compatible with node events.
-  + add listenerCount() class method to keep compatible with node events.
+  + **`broken change`**: The event supports bubbling and interruption(see above)
+  + Adds the defaultMaxListeners class property to keep compatibility with node events.
+  + Adds the setMaxListeners method to keep compatible with node events.
+  + Adds `error`, `newListener` and `removeListener` events to keep compatibility with node events.
+  + Adds listeners() method to keep compatibility with node events.
+  + Adds listenerCount() class method to keep compatibility with node events.
+  * Adds async event emitting via `emitAsync` method.
 
 
 ### Installation
 
-	$ npm install events-ex
-
-To port it to Browser or any other (non CJS) environment, use your favorite CJS bundler. No favorite yet? Try: [Browserify](http://browserify.org/), [Webmake](https://github.com/medikoo/modules-webmake) or [Webpack](http://webpack.github.io/)
+```bash
+npm install events-ex
+```
 
 ### Usage
 
+Extends from `EventEmitter` class:
 
-Add the event-able feature to your class directly:
-
-```coffee
-
-eventable = require('events-ex/eventable')
-
-class MyClass
-  # advanced usage see API topic.
-  eventable MyClass
-
-my = new MyClass
-
-my.on 'event', ->
-  console.log 'event occur'
-  # be care: @(this) is the event object. not the `my` instance.
-  # the my instance is @target.
-
-my.emit 'event'
+```js
+import {EventEmitter} from 'events-ex';
 
+class MyClass extends EventEmitter {}
 ```
 
-the following is javascript:
+Add/Inject the event-able [ability][Ability] to your class directly:
 
 ```js
-var eventable = require('events-ex/eventable');
+import {eventable} from 'events-ex';
 
-function MyClass() {}
+class MyClass extends MyRoot {}
 
+// inject the eventable ability to MyClass
 eventable(MyClass);
+```
+
+Now, you can use events in your class:
 
-var my = new MyClass;
+```js
+const my = new MyClass;
 
 my.on('event', function() {
   console.log('event occur');
@@ -79,53 +71,19 @@ my.on('event', function() {
 my.emit('event');
 ```
 
-Node JS events Usage:
-
-```coffee
-## Coffee-script demo bubbling usage:
-EventEmitter = require('events-ex')
-inherits     = require('inherits-ex')
-ABORT = -1
-DONE = 0
-
-class MyDb
-  inherits MyDb, EventEmitter
-  get: (key)->
-    # Demo the event object bubbling usage:
-    result = @emit 'getting', key
-    if isObject result
-      return if result.state is ABORT
-      return result.result if result.state is DONE
-    _get(key)
-
-db = new MyDb
-db.on 'getting', (key)->
-  result = myGet(key);
-  if result?
-    # get the key succ
-    this.result =
-      state: DONE
-      result: result
-  else if result is null
-    # abort default get key.
-    this.result = state: ABORT;
-    # this.stopped = true # it will skip other listeners if true
-```
+Bubbling event usage:
 
 ```js
-// js demo bubbling usage:
-let EventEmitter = require('events-ex')
-let isObject = require('util-ex/lib/is/type/object')
-const ABORT = -1
-const DONE = 0
+import {EventEmitter, states} from 'events-ex';
+import {isObject} from 'util-ex';
 
 class MyDb extends EventEmitter {
   get(key) {
     // Demo the event object bubbling usage:
     let result = this.emit('getting', key)
     if(isObject(result)) {
-      if (result.state === ABORT) return
-      if (result.state === DONE)  return result.result
+      if (result.state === states.ABORT) return
+      if (result.state === states.DONE)  return result.result
     }
     return _get(key)
   }
@@ -137,12 +95,12 @@ db.on('getting', function(key){
   if (result != null) {
     // get the key succ
     this.result = {
-      state: DONE,
+      state: states.DONE,
       result: result,
     }
   } else if (result === null) {
     // abort default get key.
-    this.result = {state: ABORT};
+    this.result = {state: states.ABORT};
     // this.stopped = true // it will skip other listeners if true
   }
 })
@@ -152,12 +110,13 @@ event-emitter usage:
 
 ```javascript
 
-var ee = require('event-ex/event-emitter');
+import {wrapEventEmitter as ee} from 'events-ex';
 
-var MyClass = function () { /* .. */ };
+class MyClass { /* .. */ };
 ee(MyClass.prototype); // All instances of MyClass will expose event-emitter interface
 
-var emitter = new MyClass(), listener;
+const emitter = new MyClass();
+let listener;
 
 emitter.on('test', listener = function (args) {
   // … react to 'test' event
@@ -193,22 +152,26 @@ Add the event-able ability to the class directly.
       * `this.self` is the original `this` object.
   * `classMethods` *(object)*: hooked class methods to the class
 
-```coffee
-  eventable  = require('events-ex/eventable')
-  #OtherClass = require('OtherClass')
-  class OtherClass
-    exec: -> console.log "my original exec"
-
-  class MyClass
-    # only 'on', 'off', 'emit' and static methods 'listenerCount' added to the class
-    eventable MyClass, include: ['on', 'off', 'emit', '@listenerCount']
-
-  # add the eventable ability to OtherClass and inject the exec method of OtherClass.
-  eventable OtherClass, methods:
-    exec: ->
-      console.log "new exec"
-      @super() # call the original method
+```js
+  import {eventable} from 'events-ex'
+
+  class OtherClass {
+    exec() {console.log "my original exec"}
+  }
+
+  class MyClass {}
+    // only 'on', 'off', 'emit', 'emitAsync' and static methods 'listenerCount' added to the class
+  eventable(MyClass, include: ['on', 'off', 'emit', 'emitAsync', '@listenerCount'])
+
+  // add the eventable ability to OtherClass and inject the exec method of OtherClass.
+  eventable(OtherClass, {methods: {
+    exec() {
+      console.log("new exec")
+      this.super() //call the original method
+    }}
+  })
 ```
+
 #### allOff(obj) _(events-ex/all-off)_
 
 **keep compatible only**: the `removeAllListeners` has already been buildin.
@@ -221,8 +184,8 @@ Whether object has some listeners attached to the object.
 When `name` is provided, it checks listeners for specific event name
 
 ```javascript
+import {hasListeners, wrapEventEmitter as ee} from 'events-ex/has-listeners';
 var emitter = ee();
-var hasListeners = require('events-ex/has-listeners');
 var listener = function () {};
 
 hasListeners(emitter); // false
@@ -248,7 +211,7 @@ Unifies event handling for two objects. Events emitted on _emitter1_ would be al
 Non reversible.
 
 ```javascript
-var eeUnify = require('events-ex/unify');
+import {unify as eeUnify, wrapEventEmitter as ee} from 'events-ex';
 
 var emitter1 = ee(), listener1, listener3;
 var emitter2 = ee(), listener2, listener4;
@@ -272,3 +235,5 @@ emitter2.emit('test'); // Invoked listener1, listener2, listener3 and listener4
 ```
 
 
+[event-emitter]: https://github.com/medikoo/event-emitter
+[Ability]: https://github.com/snowyu/custom-ability.js

package/ability.js

@@ -1 +1 @@
-module.exports = require('./eventable')
+module.exports = require('./lib/eventable')