From 456e79c35dcadd7b48977bf128934fcb9e402b89 Mon Sep 17 00:00:00 2001
From: blaumeise20 <62756994+blaumeise20@users.noreply.github.com>
Date: Fri, 5 Feb 2021 15:40:27 +0100
Subject: [PATCH] Add better documentation
---
README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 71 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index 006bce5..b8d778e 100644
--- a/README.md
+++ b/README.md
@@ -25,8 +25,77 @@ import "date-timeout-interval/global"; // TypeScript
```
This will add `Timeout` and `Interval` to `Date`.
+## Timeout Documentation
-## Documentation
+The Timeout class is basically a wrapper for the vanilla JavaScript `setTimeout` function. It has a great [API](#api-reference).
+
+The first step is always creating the instance of `Timeout`:
+```ts
+import { Timeout } from "date-timeout-interval";
+
+const timeout = new Timeout(() => { /* executed function */ }, 1000);
+```
+In the following scripts the import statement will be omitted, but don't forget to import it in your project!
+If you want the timeout to start after creating it, you pass a third parameter to the constructor, set it to `true`. Something like this:
+```ts
+const timeout = new Timeout(() => { /* executed function */ }, 1000, true);
+```
+You can use timeout.restart as a helper function for auto complete lists. It will reset the timer to zero and start it again. The callback will fire if the user doesn't enter some text for 200 ms.
+```ts
+import { Timeout } from "date-timeout-interval";
+
+const text = document.getElementById("myText");
+const timeout = new Timeout(() => {
+ // do something...
+}, 200);
+
+text.oninput = () => {
+ timeout.restart();
+};
+```
+The pause method is self-explaining. In the following script the callback will fire after 5 seconds. The timeout is set to 3 seconds, but after one second has passed, the timeout will be paused for 2 seconds, then the remaining 2 seconds will still be waited, which makes a total of 5 seconds. Note the restart using `start`, not `restart` mentioned before. You can use this for message banners that will disappear after a short time, but when the user hovers over them, the countdown will be paused.
+```ts
+const timeout = new Timeout(() => { console.log("Fired") }, 3000, true);
+setTimeout(timeout.pause, 1000);
+setTimeout(timeout.start, 3000);
+```
+Of course there is also a `stop` method, which does nothing else than `clearTimeout` with JavaScript timeouts does. The callback will never be executed, but when using the [async](#asyncTimeout) version it will reject the timeout.
+```ts
+const timeout = new Timeout(() => { console.log("Will never print :-)") }, 3000, true);
+setTimeout(timeout.stop, 1000);
+```
+When having event listeners which should only work for a little time (only an example), the `state` property is really useful. It has an enum value, representing the current state of the timeout. This example will check if the timeout is not over. Note omitting the callback, it is not necessary.
+```ts
+const timeout = new Timeout(10000, true); // will have state TimerState.Running for 10 seconds
+eventEmitter.on("someEvent", () => {
+ if (timeout.state != TimerState.Running) return; // you have to import TimerState to use it here!!
+ // 10 seconds have not passed yet, do something
+});
+```
+This also shows the usefulness of the `start` method called after the timeout is over. You could simply call the method in another event handler and make a button on a website, which when clicked, allows some other interaction on the site for 10 seconds.
+Another thing is async timeout. You can omit the callback in the timeout constructor and await the timeout somewhere else, making a very useful `sleep` function:
+```ts
+async function yourFunction() {
+ //do something
+ console.log("hello");
+ await new Timeout(3000, true);
+ console.log("goodbye");
+}
+```
+When the timeout is stopped (canceled) before it finished, await will throw an error. If you define a global timeout, await it somewhere, and maybe stop it somewhere else, always make sure to try/catch it:
+```ts
+try {
+ await new Timeout(3000, true);
+}
+catch (e) { console.log(e); }
+```
+
+## Interval Documentation
+
+There is currently no descriptional documentation for `Interval`, please take a look at the [API Reference for `Interval`](#intervalApi).
+
+
+## API Reference
### `new Timeout(callback: () => void, timeMS: number, autoStart: boolean = false)`
`callback: () => void` - Function to execute when time is over. `Timeout` instance will be applied as `this`.
@@ -53,17 +122,6 @@ This will add `Timeout` and `Interval` to `Date`.
Restarts the timer from zero, without firing any callback. Useful for autocomplete lists.
- ```ts
- import { Timeout } from "date-timeout-interval";
- const text = document.getElementById("myText");
- const timeout = new Timeout(() => {
- // do something...
- }, 200);
- text.oninput = () => {
- timeout.restart();
- };
- ```
-
* `await timeout`
The Timeout class implements the awaitable pattern, so you can await the timeout. It will throw an error if the timeout is stopped before finishing.
@@ -86,7 +144,7 @@ This will add `Timeout` and `Interval` to `Date`.
This will return the time left for the timer to end. **Warning: This will call a getter which will calculate the time, don't use this too often.**
-### `new Interval(callback: () => void, timeMS: number, autoStart)`
+### `new Interval(callback: () => void, timeMS: number, autoStart)`
`callback` - Function to execute in specific intervals. `Interval` instance will be applied as `this`.
`timeMS` - Interval time in milliseconds.
`autoStart: boolean` - If the timer should automatically start. This will call `start` internally.