happened - npm Package Compare versions

Comparing version 0.0.1 to 0.8.0

package.json

 {
   "name": "happened",
-  "version": "0.0.1",
-  "description": "PubSub for modern era",
-  "main": "index.js",
+  "description": "Small and nice PubSub and event bus library with custom dispatcher support.",
+  "repository": "https://github.com/grassator/happened.git",
+  "version": "0.8.0",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "gulp test"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/grassator/happened.git"
-  },
-  "keywords": [
-    "pubsub",
-    "events",
-    "event",
-    "event-bus",
-    "async"
-  ],
-  "author": "Dmitriy Kubyshkin",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/grassator/happened/issues"
-  },
-  "homepage": "https://github.com/grassator/happened"
+  "main": "dist/happened.js",
+  "devDependencies": {
+    "babel-core": "^4.7.12",
+    "babel-loader": "^4.1.0",
+    "bondjs": "^1.2.2",
+    "chai": "^2.1.1",
+    "del": "^1.1.1",
+    "es5-shim": "^4.1.0",
+    "eslint": "^0.18.0",
+    "eslint-loader": "^0.9.0",
+    "gulp": "^3.8.11",
+    "gulp-babel": "^5.1.0",
+    "gulp-rename": "^1.2.2",
+    "gulp-replace": "^0.5.3",
+    "gulp-uglify": "^1.2.0",
+    "gulp-util": "^3.0.4",
+    "karma": "^0.12.31",
+    "karma-chai": "^0.1.0",
+    "karma-mocha": "^0.1.10",
+    "karma-phantomjs-launcher": "^0.1.4",
+    "karma-webpack": "^1.5.0",
+    "mocha": "^2.2.1",
+    "webpack": "^1.7.3"
+  }
 }

README.md

 # happened
+
+[![NPM version](https://badge.fury.io/js/happened.svg)](https://npmjs.org/package/happened)
+[![GitHub version][git-tag-image]][project-url]
+[![Build Status][travis-image]][travis-url]
+[![Dependency Status][daviddm-url]][daviddm-image]
+
+`happened` is a tiny PubSub library (~700 bytes minified and gzipped). It's designed to be an easy replacement for any other PubSub library (e.g. Backbone.Events), but also because of it's tiny size, it's a good choice for any other client-side that wants to provide events without external dependencies. 
+
+## Examples
+
+`happened` tries to cover all common use cases for PubSub:
+
+### Global Event Bus
+
+Sometimes you just want a zero-hassle global event bus. `happened` provides pre-initialized global to support this use case:
+
+```js
+var happened = require('happened');
+happened.global.on('disco', function () {
+    console.log('dance');
+});
+happened.global.trigger('disco'); // "dance"
+```
+
+### Public Channels
+
+`happened` supports public channel setup by calling `happened.channel` method: 
+
+```js
+var happened = require('happened');
+var radioOne = happened.channel('radio1');
+radio1.on('morning-broadcast', function () {
+    console.log('wake up');
+});
+
+// in another place
+happened.channel('radio1').trigger('morning-broadcast', 'impossible'); // "wake up"
+
+```
+
+### Private Channels
+
+Calling `happened` without any parameters will always construct a new instance, that can be used as an event
+
+```js
+var happened = require('happened');
+var topSecretMessages = happened.create();
+topSecretMessages.on('mission', function () {
+    console.log('completed');
+});
+topSecretMessages.trigger('mission', 'impossible'); // "completed"
+```
+
+### Mixin for Objects
+
+It's a very common need to have PubSub methods directly exposed on some object, or all objects of a given class. This is usually solved by providing a mixin (e.g. Backbone.Events), which has a downside of a need to define a property on an object, that can conflict with your own properties, or even cause compiler deoptimization if it's injected dynamically by `on` method.
+
+All the methods on `happened` can be called in any context, so that means that they can be simply copied to a newly constructed instance in the constructor:
+
+```js
+var happened = require('happened');
+
+function Artist() {
+    var events = happened.create();
+    // you can choose which methods to copy from happened
+    this.on = events.on;
+    this.once = events.once;
+    this.off = events.off;
+    this.trigger = events.trigger;
+    
+    // additionally if you want to provide support to subscribe
+    // to all events it's a good idea to copy corresponding constant
+    this.ALL_EVENTS = events.ALL_EVENTS;
+}
+
+var superMetalBand = new Artist();
+superMetalBand.on('concert', function () {
+    console.log('scream');
+});
+superMetalBand.trigger('concert'); // "scream"
+```
+
+Since this is quite verbose `happened` provides a helper method for this common case:
+
+```js
+function Artist() {
+    happened.addTo(this);
+}
+```
+
+## More Good Stuff
+
+* Zero dependencies
+* Minimal interface (`on`, `once`, `off`, `trigger`), with utility methods exposed only on a global object. 
+* UMD package
+* Support for custom dispatchers.
+* Support for legacy browsers (IE6) (see [requirements](#requirements) for details)
+* Node.js support
+* all `happened` instances are [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) (immutable) if supported by environment
+
+
+
+## Requirements
+
+For synchronous usage `happened` supports any ECMAScript 5 compliant environment. This require a [shim](https://github.com/zloirock/core-js#ecmascript-5) for IE6-8 and some older Android versions.
+
+Async (setTimeout) mode is supported for all mainstream browsers and Node.js, but may not is some esoteric environments, like [Qt QML](http://doc.qt.io/qt-5/qtqml-javascript-hostenvironment.html).
+
+`happened` by default uses asynchronous event dispatching. If you want events to be dispatched faster, you can use global `setDispatcher` to inject other dispatchers, such as [setImmediate](https://github.com/YuzuJS/setImmediate) for macro-task behavior or `process.nextTick` for micro-tasks.
+
+## API
+
+This section contains reference for all public methods and properties of `happened`, to see example usage please refer to [examples section](#usage-patterns) instead.
+
+Type signatures for methods are presented using [flow](http://flowtype.org/docs/functions.html) syntax.
+
+### Top-Level Library Methods and Properties
+
+Main use case for this is to [provide events for instances of other classes](#mixin-for-objects).
+
+`happened` object exported by a library has an interface, that is a mixture of a factory and singleton patterns;
+
+#### `happened.global`
+
+This a preconstructed [instance](#instance-methods) of `happened` that can be used as a global event bus.
+
+#### `happened.create()`
+
+Constructs a new [instance](#instance-methods) of `happened`.
+
+#### `happened.channel(name : string)`
+
+Given the same name will always return the same singleton [instance](#instance-methods) of `happened`, creating it if necessary. Allows for [channel-style](#public-channels) usage.
+
+#### `happened.addTo(target : Object)`
+
+This is convenience method to create a new instance of `happened` and copy it's methods `on`, `once`, `off`, `trigger` and a constant `ALL_EVENTS` to a given `target`:
+
+```js
+happened.addTo(target : Object) => HappenedInstance
+```
+
+### Instance Methods
+
+#### `on`
+
+This method is used to subscribe for a certain event:
+
+```js
+happened.global.on(
+    name     : string,
+    callback : (...params) => void,
+    thisArg  : Object?
+) => void
+```
+
+The `callback` will receive all the parameters except for the name of the event from `trigger` as it's arguments. `thisArg` is optional context for callback.
+
+Special case here is subscribing to all events, happening on the instance. To do this you need to provide `ALL_EVENTS` constant property available on all instances.
+
+```js
+happened.global.on(
+    happened.ALL_EVENTS,
+    callback : (name : string, params : Array<any>) => void,
+    thisArg  : Object?
+) => void
+```
+
+> NOTE: `callback` for all events has a different signature to a regular one, due to a need to pass event name.
+
+#### `once`
+
+Same as [`on`](#on), but causes the `callback` to only fire once before being `off`ed.
+
+```js
+happened.global.once(
+    name     : string,
+    callback : (...params) => void,
+    thisArg  : Object?
+) => void
+```
+
+#### `off`
+
+Removes a specific `callback` for an event with a given `name`.
+
+```js
+happened.global.off(
+    name     : string?,
+    callback : Function?
+) => void
+```
+
+If called without `callback`, removes all callbacks for given `name`.
+
+If called without any arguments, remove all callbacks for all events.
+
+#### `trigger`
+
+Triggers callbacks for the given event `name`, additional `...params` to `trigger` will be passed along to the event callbacks.
+
+```js
+happened.global.trigger(
+    name      : string,
+    ...params : any
+) => void
+```
+
+## Contributing
+
+### Setting Up Development Environment
+
+To start do a fork of this repo, clone it locally and type in your terminal:
+
+```bash
+npm install
+gulp tdd
+```
+
+This will continuously run tests for nice dev experience. To run tests just once or in CI environment you can use:
+
+```bash
+gulp test
+```
+
+To build for production run:
+
+```bash
+gulp build
+```
+
+## License
+
+© 2015 Dmitriy Kubyshkin. Licensed under the MIT style license.
+
+[project-url]: https://github.com/grassator/happened
+[git-tag-image]: http://img.shields.io/github/tag/grassator/happened.svg
+[travis-url]: https://travis-ci.org/grassator/happened
+[travis-image]: https://travis-ci.org/grassator/happened.svg?branch=master
+[daviddm-url]: https://david-dm.org/grassator/happened.svg?theme=shields.io
+[daviddm-image]: https://david-dm.org/grassator/happened

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

spdx disjunction for an artifact's license information

License

spdx disjunction for an artifact's license information

Found 1 instance in 1 package

No contributors or author data

Maintenance

Package does not specify a list of contributors or an author in package.json.

Found 1 instance in 1 package

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

No License Found

License

(Experimental) License information could not be found

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

No website

Quality

Package does not have a website.

Found 1 instance in 1 package

Fixed alerts

Trivial Package

Supply chain risk

Packages less than 10 lines of code are easily copied into your own project and may not warrant the additional supply chain risk of an external dependency.

Found 1 instance in 1 package

spdx disjunction for an artifact's license information

License

spdx disjunction for an artifact's license information

Found 1 instance in 1 package

No tests

Quality

Package does not have any tests. This is a strong signal of a poorly maintained or low quality package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

75275

increased by12219.97%

Number of package files

25

increased by733.33%

Lines of code

420

increased by41900%

Number of lines in readme file

243

increased by12050%

Worsened metrics

Dev dependency count

21

increased byInfinity%

Number of low license alerts

2

increased by100%

Number of low maintenance alerts

3

increased by200%

Number of low supply chain risk alerts

1

increased byInfinity%

No dependency changes