diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 188 |
1 files changed, 118 insertions, 70 deletions
@@ -1,29 +1,21 @@ # Nitt -> Small, functional event emitter / pubsub. +> Small functional event emitter / pubsub. -- **Small:** less than 300 bytes gzipped -- **Familiar:** similar names (on, off, once, emit) & ideas as [Node's EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) -- **Functional:** methods don't rely on `this`, unless you want to... -- **No dependency:** Nitt has no external dependencies +* **Microscopic:** weighs less than 200 bytes gzipped +* **Useful:** a wildcard `"*"` event type listens to all events +* **Familiar:** same names & ideas as [Node's EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) + +nitt was made for the browser, but works in any JavaScript runtime. It has no dependencies and supports IE9+. ## Table of Contents -- [Nitt](#nitt) - - [Table of Contents](#table-of-contents) - - [Install](#install) - - [Usage](#usage) - - [API](#api) - - [nitt](#nitt) - - [on](#on) - - [once](#once) - - [when](#when) - - [off](#off) - - [emit](#emit) - - [Caveats](#caveats) - - [Contribute](#contribute) - - [Acknowledments](#acknowledments) - - [License](#license) +* [Install](#install) +* [Usage](#usage) +* [Examples & Demos](#examples--demos) +* [API](#api) +* [Contribute](#contribute) +* [License](#license) ## Install @@ -33,107 +25,163 @@ This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go che $ npm install --save nitt ``` +Then with a module bundler like [rollup](http://rollupjs.org/) or [webpack](https://webpack.js.org/), use as you would anything else: + +```javascript +// using ES6 modules +import nitt from 'nitt' + +// using CommonJS modules +var nitt = require('nitt') +``` + +The [UMD](https://github.com/umdjs/umd) build is also available on [unpkg](https://unpkg.com): + +```html +<script src="https://unpkg.com/nitt/dist/nitt.umd.js"></script> +``` + +You can find the library on `window.nitt`. + ## Usage ```js -import nitt from 'nitt'; +import nitt from 'nitt' -const emitter = nitt(); +const emitter = nitt() // listen to an event -emitter.on('foo', e => console.log('foo', e)); +emitter.on('foo', e => console.log('foo', e) ) // listen to all events -emitter.on('*', (type, e) => console.log(type, e)); - -// listen to a single event -emitter.once('foo', e => console.log('foo', e)); +emitter.on('*', (type, e) => console.log(type, e) ) // fire an event -emitter.emit('foo', { a: 'b' }); +emitter.emit('foo', { a: 'b' }) + +// clearing all events +emitter.all.clear() // working with handler references: function onFoo() {} -emitter.on('foo', onFoo); // listen -emitter.off('foo', onFoo); // unlisten -emitter.once('foo', onFoo); // listen to a single event - -// using a promise -const promise = emitter.when('bar'); -promise.then(evt => console.log(evt)); -emitter.emit('bar', 'done'); // prints 'done' in the console +emitter.on('foo', onFoo) // listen +emitter.off('foo', onFoo) // unlisten ``` -## API +### Typescript -### nitt +Set `"strict": true` in your tsconfig.json to get improved type inference for `nitt` instance methods. -Nitt: Small (<300B) functional event emitter / pubsub. +```ts +import nitt from 'nitt'; -**Parameters** +type Events = { + foo: string; + bar?: number; +}; -- `all` **EventHandlerMap** +const emitter = nitt<Events>(); // inferred as emitter<Events> -Returns **Nitt** +emitter.on('foo', (e) => {}); // 'e' has inferred type 'string' -### on +emitter.emit('foo', 42); // Error: Argument of type 'number' is not assignable to parameter of type 'string'. (2345) +``` -Register an event handler for the given type. +Alternatively, you can use the provided `emitter` type: -**Parameters** +```ts +import nitt, { emitter } from 'nitt'; -- `type` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of event to listen for, or `"*"` for all events -- `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event +type Events = { + foo: string; + bar?: number; +}; -### once +const emitter: emitter<Events> = nitt<Events>(); +``` + +## API -Register an event handler that is executed just once. +<!-- Generated by documentation.js. Update this documentation by updating the source code. --> -**Parameters** +#### Table of Contents -- `type` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of event to listen for, or `"*"` for all events -- `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event +* [nitt](#nitt) +* [all](#all) +* [on](#on) + * [Parameters](#parameters) +* [off](#off) + * [Parameters](#parameters-1) +* [emit](#emit) + * [Parameters](#parameters-2) +* [once](#once) + * [Parameters](#parameters-3) +* [when](#when) + * [Parameters](#parameters-4) -### when +### nitt -Returns a promise for a single event +Nitt: Tiny (~200b) functional event emitter / pubsub. + +Returns **Nitt**  -**Parameters** +### all -- `type` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of event to listen for, or `"*"` for all events +A Map of event names to registered handler functions. -Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** +### on + +Register an event handler for the given type. + +#### Parameters + +* `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 +* `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event ### off Remove an event handler for the given type. +If `handler` is omitted, all handlers of the given type are removed. -**Parameters** +#### Parameters -- `type` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of event to unregister `handler` from, or `"*"` -- `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Handler function to remove +* `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 (`'*'` to remove a wildcard handler) +* `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)?** Handler function to remove ### emit Invoke all handlers for the given type. -If present, `"*"` handlers are invoked after type-matched handlers. +If present, `'*'` handlers are invoked after type-matched handlers. -**Parameters** +Note: Manually firing '\*' handlers is not supported. -- `type` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The event type to invoke -- `evt` **Any?** Any value (object is recommended and powerful), passed to each handler +#### Parameters -## Caveats +* `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 +* `evt` **Any?** Any value (object is recommended and powerful), passed to each handler -Keep in mind, due to the nature, of the once handlers that self deregister, you are currently not able to remove (off) a once / when handlers. +### once -## Contribute +Register an event handler that is executed just once for the given type. + +#### Parameters + +* `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 +* `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event + +### when -If you want to contribute, I would be happy to look in to your PRs. +Returns a promise for a single event + +#### Parameters + +* `type` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of event to listen for, or `"*"` for any event -## Acknowledments +Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<any>**  + +## Contribute -I would like to thank [Jason Miller](https://jasonformat.com/) (@developit) for developing `mitt`. `nitt` is no more than just `mitt` with a few extras. +For reporting issues and submitting patches, send an email. ## License |