Comparing version 0.1.3 to 0.2.0
{ | ||
"name": "evie", | ||
"version": "0.1.3", | ||
"description": "Extends EventEmitter-like classes", | ||
"main": "./evie.coffee", | ||
"files": [ | ||
"index.js", | ||
"evie.coffee", | ||
"README.md" | ||
], | ||
"devDependencies": {}, | ||
"version": "0.2.0", | ||
"description": "EventEmitter-style events with event-bubbling", | ||
"main": "./lib/index.js", | ||
"scripts": { | ||
"prepublish": "coffee -o lib/ -c src/*.coffee", | ||
"test": "coffee test/event-channel.coffee" | ||
}, | ||
"dependencies": { | ||
"fairmont": "^0.8.2", | ||
"typely": "0.0.0" | ||
}, | ||
"devDependencies": { | ||
"testify": "^0.2.9" | ||
}, | ||
"repository": "git@github.com:pandastrike/evie.git", | ||
@@ -13,0 +18,0 @@ "author": "Matthew King <automatthew@gmail.com>", |
177
README.md
# Evie | ||
Evie provides an EventEmtter-style interface, but provides support for event-bubbling. | ||
```coffee-script | ||
parent = new Evie | ||
parent.on "bam", -> console.log "Bam!" | ||
child = new Evie | ||
child.forward parent | ||
child.emit "bam" | ||
``` | ||
Evie also supports serial and concurrent execution of multiple asynchronous operations without the need for an external library, like [async][0]. You can also conveniently wrap Node-style callback functions for use with Evie. | ||
[0]:https://github.com/caolan/async | ||
```coffee-script | ||
events = new Evie | ||
events.on "error", (error) -> console.log error | ||
[read, write] = events.wrap fs.readFile, fs.writeFile | ||
do events.serially (go) -> | ||
go -> read "foo.txt", encoding: "utf8" | ||
go (text) -> write "bar.txt", text, encoding: "utf8" | ||
go -> read "bar.txt", encoding: "utf8" | ||
``` | ||
## Install | ||
@@ -7,5 +32,4 @@ | ||
## Using Evie Directly | ||
## Using the provided class | ||
```coffee | ||
@@ -17,3 +41,3 @@ {Evie} = require "evie" | ||
## Creating your own class with Evie as a mixin | ||
## Inheriting From Evie | ||
@@ -23,3 +47,3 @@ ```coffee | ||
class MyEvents extends EventEmitter | ||
class MyEvents | ||
evie(@) | ||
@@ -30,55 +54,134 @@ | ||
## What Evie can do | ||
## Evie Reference | ||
Evie (and any class that has been evied) provides several useful methods, many | ||
of which rely on following a convention for the names of emitted events. For | ||
error conditions, emit an event named "error". For successes, emit "success". | ||
Evie can be used in a similar fashion to `EventEmitter`. There are a few differences: for example, Evie doesn't throw when an `error` event is emitted and there is no handler. | ||
```coffee | ||
events = new Evie() | ||
if everything_wrong? | ||
events.emit "error", new Error "It is all wrong" | ||
else | ||
events.emit "success", {everything: "ok"} | ||
Events are also emitted using `setImmediate`, instead of invoking handlers directly. This makes it easier to define consistent interfaces without leaking details about the implementation. You can still emit an event synchronously using the `fire` method instead of `emit`: | ||
```coffee-script | ||
# using emit: | ||
events.emit "success", result | ||
# using fire | ||
events.fire event: "success", content: result | ||
``` | ||
Other event names are certainly legal, but they are not used by the | ||
`serially`, `concurrently`, and `wrap` methods. | ||
### `forward` and `source` | ||
The `forward` method relays all events from one instance to another. `source` | ||
creates a new instance and forwards all events from it to the caller. This | ||
allows events to bubble up through a tree, which can be useful in observing | ||
and handling errors at a single place in your system. | ||
Evie also supports event-bubbling, similar to the way DOM events work. To forward events to another Evie object, just use the `forward` method. | ||
```coffee | ||
base = new Evie() | ||
base.on "error", (error) -> console.error "We have a problem:", error | ||
```coffee-script | ||
parent = new Evie | ||
parent.on "bam", -> console.log "Bam!" | ||
stuff = -> | ||
base.source (events) -> | ||
number = Date.now() | ||
if number % 7 == 0 | ||
events.emit "error", new Error "Oh no, the time is divisible by seven!" | ||
else | ||
events.emit "success", number | ||
child = new Evie | ||
child.forward parent | ||
child.emit "bam" | ||
``` | ||
e1 = stuff() | ||
e1.on "success", (result) -> | ||
console.log "The time is #{result} and it is NOT divisible by 7" | ||
You can also create new channels from existing channels using the `source` method. The new channel will forward its events to the original channel. | ||
e2 = stuff() | ||
e2.on "success", (result) -> | ||
console.log "The time is STILL not divisible by 7." | ||
```coffee-script | ||
parent = new Evie | ||
parent.on "bam", -> console.log "Bam!" | ||
child = parent.source() | ||
child.forward parent | ||
child.emit "bam" | ||
``` | ||
The `source` method can also take a channel name, which will be prepended to the event originating from it. | ||
```coffee-script | ||
parent = new Evie | ||
parent.on "child.bam", -> console.log "Bam!" | ||
child = parent.source("child") | ||
child.forward parent | ||
child.emit "bam" | ||
``` | ||
The `source` method can also take a function, which is useful when you want to return the child event channel. | ||
```coffee-script | ||
parent = new Evie | ||
parent.on "read.error", (error) -> console.log error | ||
read = (path) -> | ||
parent.source "read", (events) -> | ||
fs.readFile path, encoding: "utf8", (error, content) -> | ||
unless error? | ||
event.emit "success", content | ||
else | ||
event.emit "error", error | ||
read "foo.txt" | ||
.on "success", (content) -> | ||
console.log content | ||
``` | ||
In the example above, the errors are handled in the parent, away from the call to read. This makes it possible to separate your error handling logic from the call site, which is often useful. | ||
### `success` and `error` Events | ||
Some of Evie's most useful methods are based on the convention of emitting `success` or `error` events. These include `wrap`, `serially`, and `concurrently`. | ||
### `wrap` | ||
The `wrap` method takes a function that accepts a Node-style callback as its last argument and returns a function that returns an Evie event channel, emitting either a `success` or `error` event. | ||
```coffee-script | ||
events = new Evie | ||
parent.on "error", (error) -> console.log error | ||
read = parent.wrap fs.readFile | ||
read "foo.txt", encoding: "utf8" | ||
.on "success", (content) -> console.log content | ||
``` | ||
### `serially` | ||
The `serially` method allows you to queue up a sequence of asynchronous functions that follow the Evie convention of returning an Evie event channel that will emit either a `success` or `error` event. If a `success` event is emitted, `serially` will run the next function, passing it the result of the previous function (which you are free to ignore, of course). | ||
```coffee-script | ||
events = new Evie | ||
events.on "error", (error) -> console.log error | ||
[read, write] = events.wrap fs.readFile, fs.writeFile | ||
do events.serially (go) -> | ||
go -> read "foo.txt", encoding: "utf8" | ||
go (text) -> write "bar.txt", text, encoding: "utf8" | ||
go -> read "bar.txt", encoding: "utf8" | ||
``` | ||
### `concurrently` | ||
The `concurrently` method works similarly to the `serially` method, except that all functions are run concurrently. If a name is passed to the builder method (assigned to the argument `go` in these examples), the result of the function will be added to an object using that property name. This object will be emitted by `concurrently` when all the functions have returned successful. | ||
```coffee-script | ||
events = new Evie | ||
events.on "error", (error) -> console.log error | ||
[read] = events.wrap fs.readFile | ||
do events.concurrently (go) -> | ||
for file in files | ||
go (file) -> read file, encoding: "utf8" | ||
.on "success", (cache) -> | ||
for file, content in cache | ||
console.log "File: #{file}", "\nContent: #{content}" | ||
``` | ||
# `success` and `error` methods | ||
You can do promise-style coding by using the `success` and `error` shortcuts. | ||
```coffee-script | ||
events = new Evie | ||
events.error (error) -> console.log error | ||
[read] = events.wrap fs.readFile | ||
do events.concurrently (go) -> | ||
for file in files | ||
go (file) -> read file, encoding: "utf8" | ||
.success (cache) -> | ||
for file, content in cache | ||
console.log "File: #{file}", "\nContent: #{content}" | ||
``` |
Major refactor
Supply chain riskPackage 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
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
Empty package
Supply chain riskPackage does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.
Found 1 instance in 1 package
41685
20
522
184
2
1
2
+ Addedfairmont@^0.8.2
+ Addedtypely@0.0.0
+ Addedfairmont@0.4.10.8.2(transitive)
+ Addedtypely@0.0.0(transitive)