1 | # event-kit
|
2 |
|
3 | This is a simple library for implementing event subscription APIs.
|
4 |
|
5 | ## Implementing Event Subscription APIs
|
6 |
|
7 | ```coffee
|
8 | {Emitter} = require 'event-kit'
|
9 |
|
10 | class User
|
11 | constructor: ->
|
12 | @emitter = new Emitter
|
13 |
|
14 | onDidChangeName: (callback) ->
|
15 | @emitter.on 'did-change-name', callback
|
16 |
|
17 | setName: (name) ->
|
18 | if name isnt @name
|
19 | @name = name
|
20 | @emitter.emit 'did-change-name', name
|
21 | @name
|
22 |
|
23 | destroy: ->
|
24 | @emitter.dispose()
|
25 | ```
|
26 |
|
27 | In the example above, we implement `::onDidChangeName` on the user object, which
|
28 | will register callbacks to be invoked whenever the user's name changes. To do
|
29 | so, we make use of an internal `Emitter` instance. We use `::on` to subscribe
|
30 | the given callback in `::onDidChangeName`, and `::emit` in `::setName` to notify
|
31 | subscribers. Finally, when the `User` instance is destroyed we call `::dispose`
|
32 | on the emitter to unsubscribe all subscribers.
|
33 |
|
34 | ## Consuming Event Subscription APIs
|
35 |
|
36 | `Emitter::on` returns a `Disposable` instance, which has a `::dispose` method.
|
37 | To unsubscribe, simply call dispose on the returned object.
|
38 |
|
39 | ```coffee
|
40 | subscription = user.onDidChangeName (name) -> console.log("My name is #{name}")
|
41 | # Later, to unsubscribe...
|
42 | subscription.dispose()
|
43 | ```
|
44 |
|
45 | You can also use `CompositeDisposable` to combine disposable instances together.
|
46 |
|
47 | ```coffee
|
48 | {CompositeDisposable} = require 'event-kit'
|
49 |
|
50 | subscriptions = new CompositeDisposable
|
51 | subscriptions.add user1.onDidChangeName (name) -> console.log("User 1: #{name}")
|
52 | subscriptions.add user2.onDidChangeName (name) -> console.log("User 2: #{name}")
|
53 |
|
54 | # Later, to unsubscribe from *both*...
|
55 | subscriptions.dispose()
|
56 | ```
|
57 |
|
58 | ## Creating Your Own Disposables
|
59 |
|
60 | Disposables are convenient ways to represent a resource you will no longer
|
61 | need at some point. You can instantiate a disposable with an action to take when
|
62 | no longer needed.
|
63 |
|
64 | ```coffee
|
65 | {Disposable} = require 'event-kit'
|
66 |
|
67 | disposable = new Disposable => @destroyResource()
|
68 | ```
|