1 | <p align="center">
|
2 | <img src="https://i.imgur.com/BqsX9NT.png" width="300" height="300" alt="mitt">
|
3 | <br>
|
4 | <a href="https://www.npmjs.org/package/mitt"><img src="https://img.shields.io/npm/v/mitt.svg" alt="npm"></a>
|
5 | <img src="https://github.com/developit/mitt/workflows/CI/badge.svg" alt="build status">
|
6 | <a href="https://unpkg.com/mitt/dist/mitt.js"><img src="https://img.badgesize.io/https://unpkg.com/mitt/dist/mitt.js?compression=gzip" alt="gzip size"></a>
|
7 | </p>
|
8 |
|
9 | # Mitt
|
10 |
|
11 | > Tiny 200b functional event emitter / pubsub.
|
12 |
|
13 | - **Microscopic:** weighs less than 200 bytes gzipped
|
14 | - **Useful:** a wildcard `"*"` event type listens to all events
|
15 | - **Familiar:** same names & ideas as [Node's EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
|
16 | - **Functional:** methods don't rely on `this`
|
17 | - **Great Name:** somehow [mitt](https://npm.im/mitt) wasn't taken
|
18 |
|
19 | Mitt was made for the browser, but works in any JavaScript runtime. It has no dependencies and supports IE9+.
|
20 |
|
21 | ## Table of Contents
|
22 |
|
23 | - [Install](#install)
|
24 | - [Usage](#usage)
|
25 | - [Examples & Demos](#examples--demos)
|
26 | - [API](#api)
|
27 | - [Contribute](#contribute)
|
28 | - [License](#license)
|
29 |
|
30 | ## Install
|
31 |
|
32 | This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed.
|
33 |
|
34 | ```sh
|
35 | $ npm install --save mitt
|
36 | ```
|
37 |
|
38 | Then with a module bundler like [rollup](http://rollupjs.org/) or [webpack](https://webpack.js.org/), use as you would anything else:
|
39 |
|
40 | ```javascript
|
41 | // using ES6 modules
|
42 | import mitt from 'mitt'
|
43 |
|
44 | // using CommonJS modules
|
45 | var mitt = require('mitt')
|
46 | ```
|
47 |
|
48 | The [UMD](https://github.com/umdjs/umd) build is also available on [unpkg](https://unpkg.com):
|
49 |
|
50 | ```html
|
51 | <script src="https://unpkg.com/mitt/dist/mitt.umd.js"></script>
|
52 | ```
|
53 |
|
54 | You can find the library on `window.mitt`.
|
55 |
|
56 | ## Usage
|
57 |
|
58 | ```js
|
59 | import mitt from 'mitt'
|
60 |
|
61 | const emitter = mitt()
|
62 |
|
63 | // listen to an event
|
64 | emitter.on('foo', e => console.log('foo', e) )
|
65 |
|
66 | // listen to all events
|
67 | emitter.on('*', (type, e) => console.log(type, e) )
|
68 |
|
69 | // fire an event
|
70 | emitter.emit('foo', { a: 'b' })
|
71 |
|
72 | // clearing all events
|
73 | emitter.all.clear()
|
74 |
|
75 | // working with handler references:
|
76 | function onFoo() {}
|
77 | emitter.on('foo', onFoo) // listen
|
78 | emitter.off('foo', onFoo) // unlisten
|
79 | ```
|
80 |
|
81 | ### Typescript
|
82 |
|
83 | Set `"strict": true` in your tsconfig.json to get improved type inference for `mitt` instance methods.
|
84 |
|
85 | ```ts
|
86 | import mitt from 'mitt';
|
87 |
|
88 | type Events = {
|
89 | foo: string;
|
90 | bar?: number;
|
91 | };
|
92 |
|
93 | const emitter = mitt<Events>(); // inferred as Emitter<Events>
|
94 |
|
95 | emitter.on('foo', (e) => {}); // 'e' has inferred type 'string'
|
96 |
|
97 | emitter.emit('foo', 42); // Error: Argument of type 'number' is not assignable to parameter of type 'string'. (2345)
|
98 | ```
|
99 |
|
100 | Alternatively, you can use the provided `Emitter` type:
|
101 |
|
102 | ```ts
|
103 | import mitt, { Emitter } from 'mitt';
|
104 |
|
105 | type Events = {
|
106 | foo: string;
|
107 | bar?: number;
|
108 | };
|
109 |
|
110 | const emitter: Emitter<Events> = mitt<Events>();
|
111 | ```
|
112 |
|
113 | ## Examples & Demos
|
114 |
|
115 | <a href="http://codepen.io/developit/pen/rjMEwW?editors=0110">
|
116 | <b>Preact + Mitt Codepen Demo</b>
|
117 | <br>
|
118 | <img src="https://i.imgur.com/CjBgOfJ.png" width="278" alt="preact + mitt preview">
|
119 | </a>
|
120 |
|
121 | * * *
|
122 |
|
123 | ## API
|
124 |
|
125 |
|
126 |
|
127 | #### Table of Contents
|
128 |
|
129 | - [mitt](#mitt)
|
130 | - [all](#all)
|
131 | - [on](#on)
|
132 | - [Parameters](#parameters)
|
133 | - [off](#off)
|
134 | - [Parameters](#parameters-1)
|
135 | - [emit](#emit)
|
136 | - [Parameters](#parameters-2)
|
137 |
|
138 | ### mitt
|
139 |
|
140 | Mitt: Tiny (~200b) functional event emitter / pubsub.
|
141 |
|
142 | Returns **Mitt**
|
143 |
|
144 | ### all
|
145 |
|
146 | A Map of event names to registered handler functions.
|
147 |
|
148 | ### on
|
149 |
|
150 | Register an event handler for the given type.
|
151 |
|
152 | #### Parameters
|
153 |
|
154 | - `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** Type of event to listen for, or `'*'` for all events
|
155 | - `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event
|
156 |
|
157 | ### off
|
158 |
|
159 | Remove an event handler for the given type.
|
160 | If `handler` is omitted, all handlers of the given type are removed.
|
161 |
|
162 | #### Parameters
|
163 |
|
164 | - `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** Type of event to unregister `handler` from, or `'*'`
|
165 | - `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)?** Handler function to remove
|
166 |
|
167 | ### emit
|
168 |
|
169 | Invoke all handlers for the given type.
|
170 | If present, `'*'` handlers are invoked after type-matched handlers.
|
171 |
|
172 | Note: Manually firing '\*' handlers is not supported.
|
173 |
|
174 | #### Parameters
|
175 |
|
176 | - `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** The event type to invoke
|
177 | - `evt` **Any?** Any value (object is recommended and powerful), passed to each handler
|
178 |
|
179 | ## Contribute
|
180 |
|
181 | First off, thanks for taking the time to contribute!
|
182 | Now, take a moment to be sure your contributions make sense to everyone else.
|
183 |
|
184 | ### Reporting Issues
|
185 |
|
186 | Found a problem? Want a new feature? First of all see if your issue or idea has [already been reported](../../issues).
|
187 | If don't, just open a [new clear and descriptive issue](../../issues/new).
|
188 |
|
189 | ### Submitting pull requests
|
190 |
|
191 | Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits.
|
192 |
|
193 | - Fork it!
|
194 | - Clone your fork: `git clone https://github.com/<your-username>/mitt`
|
195 | - Navigate to the newly cloned directory: `cd mitt`
|
196 | - Create a new branch for the new feature: `git checkout -b my-new-feature`
|
197 | - Install the tools necessary for development: `npm install`
|
198 | - Make your changes.
|
199 | - Commit your changes: `git commit -am 'Add some feature'`
|
200 | - Push to the branch: `git push origin my-new-feature`
|
201 | - Submit a pull request with full remarks documenting your changes.
|
202 |
|
203 | ## License
|
204 |
|
205 | [MIT License](https://opensource.org/licenses/MIT) © [Jason Miller](https://jasonformat.com/)
|