https://github.com/elijah-bodden/know
Plug-and-play, faster-than-native promise/callback event emitter
https://github.com/elijah-bodden/know
async emitters event-management events javascript js mit-license node node-module node-modules nodejs npm-module npm-package open-source opensource promise
Last synced: 4 months ago
JSON representation
Plug-and-play, faster-than-native promise/callback event emitter
- Host: GitHub
- URL: https://github.com/elijah-bodden/know
- Owner: Elijah-Bodden
- License: mit
- Created: 2022-08-12T03:50:21.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2022-08-22T11:45:41.000Z (almost 3 years ago)
- Last Synced: 2025-03-04T18:41:13.788Z (4 months ago)
- Topics: async, emitters, event-management, events, javascript, js, mit-license, node, node-module, node-modules, nodejs, npm-module, npm-package, open-source, opensource, promise
- Language: JavaScript
- Homepage:
- Size: 176 KB
- Stars: 26
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
kNow
Blazing-fast callback/promise-based events with a tiny footprint
## What is this?
With kNow (pronounced "*now*"—the k's silent), JavaScript event management has never been more intuitive—or lighter-weight. Want to append custom actions to functions on-the-fly? To use awaitable timers to pause and resume execution at any time? To create large numbers of listeners without worrying about performance degradation? If so, you want kNow.
| 
|
|:--:|
|
Via https://jsben.ch/ZESbj (Avg. over 25 runs)
|
Originally developed for use in [Membrane](https://github.com/Elijah-Bodden/Membrane), kNow is a fully functional, if lightweight, native event-management utility for any use-case.
## Getting Started
### Node.js + npm
#### Installation:
To install in the root of your node project:
```bash
npm i @elijah-bodden/know
```
Or else globally:
```bash
npm i @elijah-bodden/know -g
```
#### Use in-script
To import the module into your node script, simply paste the following line at the very top:
```JavaScript
const kNow = require('@elijah-bodden/know')
```
Then, to create a usable intance, add `const someVariable = new kNow()` anywhere, where 'someVariable' is the name you wish to access it by.
### HTML `script` tag
#### Inclusion
To include the script in your HTML, add the following tag to the top of your document:
```HTML
```
#### Use in-script
Just as with node, simply drop in `const someVariable = new kNow()` anywhere in your script, changing 'someVariable' to the name you want to reference the instance with.
## Examples
### Pause function execution for n milliseconds
```JavaScript
const kNow = require("@elijah-bodden/know");
const know = new kNow()
async function test() {
console.log("foo")
console.log("bar")
//Creates and awaits a promise that resolves in 3000ms or 3 seconds
await know.in(3000)
console.log("baz")
}
test()
/* Expected Output:
1. "foo"
2. "bar"
*Three-second pause*
3. "baz"
*/
```
### Track changes to a variable
```JavaScript
const kNow = require("@elijah-bodden/know");
const know = new kNow()
var variable
function setVariable(newVal) {
variable = newVal
know.dispatch("variableChanged", variable)
}
setInterval(() => setVariable(Math.random()), 1000)
//Listener callbacks can be created and destroyed at any time, on-the-fly.
const changeListener = know.when("variableChanged", (newVal) => console.log(`Variable "variable" was changed to ${newVal}.`))
setTimeout(() => know.clearWhen(changeListener), 5000)
/* Expected Output:
*1 second pause* "Variable was changed to (some value)" x 4
*/
```
### Call function X next time Y completes
```JavaScript
const kNow = require("@elijah-bodden/know");
const know = new kNow()
function unpredictableFunction() {
for (let i = 0; i < 10000000; i++) {
//Doing some valuable operations
}
console.log("Alerting that task was completed.")
know.dispatch("taskCompleted")
setTimeout(unpredictableFunction, Math.floor(Math.random()*10000))
}
setTimeout(unpredictableFunction, Math.floor(Math.random()*10000))
know.next("taskCompleted").then(() => console.log("Task completed!"))
/* Expected Output:
*Indefinite pause*
1. "Alerting that task was completed."
2. "Task completed!"
*/
```
## Methods
Use any of the following functions on a kNow instance to implement powerful, high-speed event handling in a snap.
| Command | Description |
| --- | --- |
| **constructor**(number) | When you initialize kNow, you can optionally pass a single argument, the length of time, in milliseconds, after which each `next` listener automatically expires. |
| **when**(number \| string, function) | Automatically attatches a callback, its second argument, which will run every time the first argument's value is `dispatched`. The function returns an `instanceID` object which can be passed into `clearWhen` to destroy the listener. |
| **clearWhen**(object \| string \| number \| undefined) | Accepts either a string or a number, an `instanceID` object, or no value. If it recieves a string or a number, kNow will unregister all `when` callbacks bound to that dispatch value; if it instead gets an `instanceID` created by `when`, only the callback created by this call will be destroyed. Otherwise, if the value is `undefined`, all callbacks registered to all `ID`'s will be destroyed simultaneously. |
| **dispatch**(number \| string, any) | Immediately resolves all promises bound through `next` to the first parameter, and invokes all callbacks attatched to it by `when`. All promises will resolve to the second argument, which will also be passed to all callback functions.|
| **forceReject**(number \| string, any) | `forceReject` does the exact opposite of `dispatch`, batch-rejecting all promises attatched to the first argument and setting the `reason`s to the second. |
| **next**(number \| string, number \| undefined) | `next` returns a promise which may either be resolved by `dispatching` the value provided as the first parameter, or rejected through `clearNext` or `forceReject`. Optionally, a second argument, a timeout, may be specified, after which to automatically reject to promise. If this argument is omited, it will default to the value provided to the constructor, and if this too is undefined, there will be no timeout. |
| **clearnext**(...string \| number \| undefined) | Accepts a list of dispatch ID's; if none are provided, it defaults to every registered ID. Each promise registered to each of these ID's is `forceReject`ed with the reason "flushed". |
| **in**(number) | Returns a promise which will resolve to `undefined` in the specified number of milliseconds. |
| **clearIn**() | Immediately `forceReject`s every promise created by `in` |
## License
kNow is distributed under the MIT license. See the `LICENSE` file for more information.
## Contributing
Any and all contributions are greatly appreciated. If you want to see this project grow as much as I do, there are several ways to help. Firstly, if you see something you think you can improve within the code, please `fork` the repository and make a `pull` request once you have made any changes you'd like to see. If you just have an idea, or spot a bug, that's great too! In this case, please file an `issue` with a corresponding `bug` or `enhancement` tag. Oh, and if you like what you see here, please feel free to leave a star on the project, it would mean a ton to me.
## Contact
Elijah Bodden - [email protected]
Project - https://github.com/Elijah-Bodden/kNow
npm - https://www.npmjs.com/package/@elijah-bodden/know