Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
dot-event - npm Package Compare versions
Comparing version 3.0.29 to 3.0.30
@@ -42,2 +42,4 @@ /*global Map Promise Set*/ | ||
| emitOn(a, undefined, m, p, pr, r, s) | ||
| k.arr.forEach(function(prop) { | ||
@@ -47,4 +49,2 @@ key = key ? key + period + prop : prop | ||
| }) | ||
| emitOn(a, undefined, m, p, pr, r, s) | ||
| } | ||
@@ -93,4 +93,4 @@ | ||
| emitAny(a, k, s.any, p, pr, r, sig) | ||
| emitOn(a, k, s.on, p, pr, r, sig) | ||
| emitAny(a, k, s.any, p, pr, r, sig) | ||
@@ -97,0 +97,0 @@ var promise = Promise.all(pr) |
| { | ||
| "name": "dot-event", | ||
| "version": "3.0.29", | ||
| "version": "3.0.30", | ||
| "description": "Powerful event emitter", | ||
@@ -28,6 +28,6 @@ "keywords": [ | ||
| "eslint-plugin-prettier": "3.0.0", | ||
| "prettier": "1.15.2", | ||
| "husky": "1.2.0", | ||
| "jest": "23.6.0", | ||
| "lint-staged": "8.1.0", | ||
| "jest": "23.6.0" | ||
| "prettier": "1.15.2" | ||
| }, | ||
@@ -34,0 +34,0 @@ "operations": { |
171
README.md
@@ -7,6 +7,30 @@ # dot-event | ||
| ## Purpose | ||
| ## What is it? | ||
| Dot-event provides a succinct interface for calling events and persisting state with a tiny footprint (<1kb). | ||
| Dot-event creates interfaces for listening to and emitting events. | ||
| Dot-event listeners can be synchronous or asynchronous, accept arguments, and return values. | ||
| Dot-event has a tiny footprint (<1 kb compressed and gzipped). | ||
| ### Write less code | ||
| Event listeners may emit any event [through the `dot` argument](#listener-arguments), resulting in less `require` calls and easy access to functionality across your application. | ||
| ### Event id & props | ||
| Dot-event optionally uses [event id](#event-id) and [prop string(s)](#props) to add identifying context to an emit. Props pay off with [logging](https://github.com/dot-event/log#readme), [store updates](https://github.com/dot-event/store#readme), and even [dom element ids](https://github.com/dot-event/el#readme). | ||
| ### Dynamic composition | ||
| Dot-event uses a [composer function pattern](#composer-pattern) to add event listeners. This pattern works very well with [dynamic imports](#dynamic-imports) to create dot-event instances with dynamic functionality. | ||
| ### State | ||
| Dot-event provides basic state via the `dot.state` object. On this object we built an [immutable store](https://github.com/dot-event/store#readme) that leverages props and is only ~1 kb compressed and gzipped. | ||
| ### SSR-ready | ||
| Its simple to [wait for all dot-event listeners](#wait-for-pending-events) before rendering the final version of your server side page. | ||
| ## Setup | ||
@@ -25,81 +49,146 @@ | ||
| ## Return value | ||
| ### Return value | ||
| ```js | ||
| dot.on(() => "a") | ||
| dot() // "a" | ||
| dot.on(() => "value") | ||
| dot() // "value" | ||
| ``` | ||
| ## Async return value | ||
| ### Async return value | ||
| ```js | ||
| dot.on(async () => "a") | ||
| dot().then(result => /* [ "a" ] */) | ||
| dot.on(async () => "value") | ||
| dot().then(result => /* [ "value" ] */) | ||
| ``` | ||
| ## Event id | ||
| ### Event id | ||
| The event id is the first string argument to `dot.on` or `dot.any`. | ||
| ```js | ||
| dot.on("a", () => "b") | ||
| dot("a") // "b" | ||
| dot.on("myEvent", () => "value") | ||
| dot("myEvent") // "value" | ||
| ``` | ||
| **Event id tip:** The first string or element in an array of strings passed to `dot.on` or `dot.any` is considered the event id. | ||
| > ℹ️ The listener function receives the event id as its [fourth argument](#listener-arguments). | ||
| ## Event id & props | ||
| ## Listener arguments | ||
| No matter what is passed to the `dot` emitter, listener functions always receive five arguments: | ||
| | Argument | Description | | ||
| | ---------------------------- | --------------------------- | | ||
| | [`prop`](#props) | Array of string identifiers | | ||
| | [`arg`](#emit-argument) | Emit argument | | ||
| | [`dot`](#composer-pattern) | Dot-event instance | | ||
| | [`event`](#event-id) | Event id | | ||
| | [`signal`](#signal-argument) | Signal object | | ||
| ### Props | ||
| String arguments after the [event id](#event-id) are prop identifiers. | ||
| ```js | ||
| dot.on("a", "b", "c", prop => prop) | ||
| dot("a", "b", "c") // ["b", "c"] | ||
| dot.on("myEvent", "prop", prop => prop) | ||
| dot("myEvent", "prop") // [ "prop" ] | ||
| ``` | ||
| **Prop tip 1:** Any string or array of strings passed to `dot` after the event id are considered prop identifiers. | ||
| > ℹ️ The listener function receives the prop array as its [first argument](#listener-arguments). | ||
| **Prop tip 2:** The listener function always receives a prop array as its first argument. | ||
| ### Emit argument | ||
| ## Emit argument | ||
| The last non-prop argument becomes the emit argument (`arg`). | ||
| ```js | ||
| dot.on((prop, arg) => arg) | ||
| dot({ a: "b" }) // { a: "b" } | ||
| dot({ option: true }) // { option: true } | ||
| ``` | ||
| **Arg tip 1:** The last non-prop emit argument is considered the user-provided argument. | ||
| > ℹ️ The listener function receives the emit argument as its [second argument](#listener-arguments). | ||
| **Arg tip 2:** The listener function always receives the user-provided argument as its second argument. | ||
| ### Signal argument | ||
| ```js | ||
| dot.on((prop, arg, dot, eventId, signal) => { | ||
| signal.cancel = true | ||
| return "value" | ||
| }) | ||
| dot.on(() => "never called") | ||
| dot() // "value" | ||
| ``` | ||
| > ℹ️ There is one other signal, `signal.value`, which you can set instead of using `return` in your listener function. | ||
| ## Any | ||
| ```js | ||
| dot.any(() => "!!!") | ||
| dot("a", "b", "c") // "!!!" | ||
| dot.any(() => "!") | ||
| dot("myEvent", "prop") // "!" | ||
| ``` | ||
| ## Helper function | ||
| ### Any with event id | ||
| ```js | ||
| dot.any("a", props => props) | ||
| dot.a("b", "c") // [ "b", "c" ] | ||
| dot.any("myEvent", prop => prop) | ||
| dot("myEvent", "prop") // [ "prop" ] | ||
| dot.myEvent("prop") // <-- cool helper function! | ||
| ``` | ||
| **Helper tip:** Dot-event creates a helper function only if `dot.any` receives an event id with no props. | ||
| > ℹ️ Dot-event creates a helper function only if `dot.any` receives an event id with no props. | ||
| ## Listener arguments | ||
| ### Any with props | ||
| No matter what is passed to the `dot` emitter, listener functions always receive five arguments: | ||
| ```js | ||
| dot.any("myEvent", "prop", "prop2", props => props) | ||
| dot("myEvent") // noop | ||
| dot("myEvent", "prop") // noop | ||
| dot("myEvent", "prop", "prop2") // [ "prop", "prop2" ] | ||
| dot("myEvent", "prop", "prop2", "prop3") // [ "prop", "prop2", "prop3" ] | ||
| ``` | ||
| - `prop` — an array of string identifiers | ||
| - `arg` — a user-provided argument | ||
| - `dot` — the dot-event instance | ||
| - `event` — the event id | ||
| - `signal` — dot-event signal object (use `signal.cancel = true` for event cancellation) | ||
| ## Composer pattern | ||
| A common pattern is for composers to define listeners that respond to `any` props of a particular event id. | ||
| ```js | ||
| export default function(dot) { | ||
| dot.any("myEvent", myEvent) | ||
| } | ||
| async function myEvent(prop, arg, dot) { | ||
| prop = prop.concat(["myEvent"]) | ||
| await dot.otherEvent(prop) | ||
| } | ||
| ``` | ||
| > ℹ️ Another common pattern illustrated here is to append a prop id before passing them along to another emit. | ||
| ## Dynamic imports | ||
| ```js | ||
| dot.add(import("./myEvent")) | ||
| ``` | ||
| > ℹ️ You might need to run node with `--experimental-modules` to enable dynamic imports server side. | ||
| ## Wait for pending events | ||
| ```js | ||
| await Promise.all([...dot.state.events]) | ||
| ``` | ||
| > ℹ️ `dot.state.events` is a [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) of promises. | ||
| ## Dot composers | ||
| | Library | Description | URL | | ||
| | ------- | ------------------------------ | ----------------------------------- | | ||
| | ad | Google Publisher Tag functions | https://github.com/dot-event/ad | | ||
| | arg | CLI and URL argument handling | https://github.com/dot-event/arg | | ||
| | fetch | Universal HTTP fetch function | https://github.com/dot-event/fetch | | ||
| | log | Log functions | https://github.com/dot-event/log2 | | ||
| | store | Immutable store | https://github.com/dot-event/store2 | | ||
| | Library | Description | URL | | ||
| | ---------- | -------------------- | ---------------------------------------------- | | ||
| | ad | Google Publisher Tag | https://github.com/dot-event/ad#readme | | ||
| | arg | CLI and URL argument | https://github.com/dot-event/arg#readme | | ||
| | controller | DOM controller | https://github.com/dot-event/controller#readme | | ||
| | el | DOM elements | https://github.com/dot-event/el#readme | | ||
| | fetch | Universal HTTP fetch | https://github.com/dot-event/fetch#readme | | ||
| | log | Event logger | https://github.com/dot-event/log#readme | | ||
| | render | Server side render | https://github.com/dot-event/render#readme | | ||
| | store | Immutable store | https://github.com/dot-event/store#readme | | ||
| | view | DOM view | https://github.com/dot-event/view#readme | |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by25.32%
16389
- Number of lines in readme file
- increased by85.58%
193
No dependency changes