onUpdate and better doc

fedeghe · Mar 28, 2023 · 520b8ce · 520b8ce
1 parent dcbffda
commit 520b8ce
Show file tree

Hide file tree

Showing 8 changed files with 146 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,11 @@
 [![Coverage Status](https://coveralls.io/repos/github/fedeghe/countdown/badge.svg?branch=master)](https://coveralls.io/github/fedeghe/countdown?branch=master)
 
-# countdown
+# countdown <sub><small>(v. 0.0.5)</small></sub>
 
-A really simple function to provide an extented pausable/resumable version of `setTimeout`
+A really simple function to provide and extended version of `[native] setTimeout` which can be
+- paused / resumed
+- updated while running
+- have a ticking function
 
 ``` js
 countdown(function () {
@@ -17,8 +20,6 @@ countdown(function () {
 .run(() => {
     console.log(`STARTED: ${+new Date()}`)
 });
-
-
 ```
 will produce
 ```
@@ -35,7 +36,7 @@ tick 8 :  99 901 1679957709908
 tick 9 :  -2 1002 1679957710009
 END:  1679957710035
 ```
-on longer runs the stability of the ticking function si anyway quite good since internally it is dinamically changing, thus trying with 60 seconds for example one gets:
+on longer runs the stability of the ticking function is anyway quite good since internally it is dinamically changing, thus trying with 60 seconds for example one gets:
 ```
 ticking: 59898 102 1679868459589
 ticking: 59800 200 1679868459686
@@ -53,22 +54,35 @@ END: 1679868519487
 
 
 ### _API_
-the `countdown` function expects:  
+the `countdown` function expects as parameters:  
 - **a function** : meant to be executed when the countdown is over 
-- **an integer**: number of milliseconds for the coundown to finish  
+- **an integer**: the _"event horizont"_; number of milliseconds for the coundown to complete 
 
 returns an instance of a simple object where the following methods are available:  
 
-- **run(ƒn)** to start it, optionally accepts a function that will be called once started passing the countdown instance
-- **end()** to stop it
-- **update(exp)** to update the event horizont in milliseconds, valid values are `1000`, `"+1000"`, `"-1000"`, `"*2*"`, `"/2*"`.
+- **`run(ƒn)`** to start it, optionally accepts a function that will be called once started receiving the countdown instance
+
+- **`onTick(fn, tickInterval)`** to pass a function that will be called with a tick interval passing an object `{cycle, remaining, elapsed}` 
+- **`update(exp)`** to update the event horizont in milliseconds, it can be used to add subtract time to the horizont and to divide and multiply it:  
+
+    | exp | effect |
+    |-----|--------|
+    | 1000 | add 1000 ms |
+    | "+1000" | add 1000 ms |
+    | "-1000" | subtract 1000 ms |
+    | "*2" | double the current horizont |
+    | "/2" | halve the current horizont |
+
+    Notice: the update will happen only if the result ∈ ℝ
+
 
-- **onErr(fn)** to pass a function that will handle any thrown err
-- **onEnd(fn)** to pass a function that will be called additionally when `end` will be called
-- **onTick(fn, tickInterval)** to pass a function that will be called with a tick interval passing an object `{cycle, remaining, elapsed}` 
-- **onPause(fn)** to pass a function that will be called when `pause` will be called  
-- **pause()** to pause it manually
-- **onResume(fn)** to pass a function that will be called when `resume` will be called  
-- **resume()** to resume it manually
+- **`onUpdate(fn)`** to pass a function that will be invoked when update is called `fn` will be invoked receiving the instance 
+- **`onErr(fn)`** to pass a function that will handle any thrown err; fn will be invoked receiving the error and the instance 
+- **`end()`** to stop it
+- **`onEnd(fn)`** to pass a function that will be called additionally when `end` will be called; fn will be invoked receiving the instance 
+- **`pause()`** to pause it manually
+- **`onPause(fn)`** to pass a function that will be called when `pause` will be called; fn will be invoked receiving the instance   
+- **`resume()`** to resume it manually
+- **`onResume(fn)`** to pass a function that will be called when `resume` will be called; fn will be invoked receiving the instance   
 
 
diff --git a/dist/index.js b/dist/index.js
diff --git a/source/README.md b/source/README.md
@@ -0,0 +1,88 @@
+[![Coverage Status](https://coveralls.io/repos/github/fedeghe/countdown/badge.svg?branch=master)](https://coveralls.io/github/fedeghe/countdown?branch=master)
+
+# countdown <sub><small>(v. $PACKAGE.version$)</small></sub>
+
+A really simple function to provide and extended version of `[native] setTimeout` which can be
+- paused / resumed
+- updated while running
+- have a ticking function
+
+``` js
+countdown(function () {
+    // this will be called when the countdown is over
+    console.log('END: ', +new Date());
+}, 1000)
+// onTick is optional
+.onTick(({ remaining, elapsed, cycle }) => {
+    console.log(`tick ${cycle} : `, remaining, elapsed, +new Date());
+}, 100)
+// run is not, if we want to start the countdown
+.run(() => {
+    console.log(`STARTED: ${+new Date()}`)
+});
+```
+will produce
+```
+STARTED: 1679957709007
+tick 0 :  899 101 1679957709109
+tick 1 :  799 201 1679957709208
+tick 2 :  697 303 1679957709310
+tick 3 :  593 407 1679957709414
+tick 4 :  496 504 1679957709511
+tick 5 :  399 601 1679957709608
+tick 6 :  298 702 1679957709709
+tick 7 :  199 801 1679957709808
+tick 8 :  99 901 1679957709908
+tick 9 :  -2 1002 1679957710009
+END:  1679957710035
+```
+on longer runs the stability of the ticking function is anyway quite good since internally it is dinamically changing, thus trying with 60 seconds for example one gets:
+```
+ticking: 59898 102 1679868459589
+ticking: 59800 200 1679868459686
+ticking: 59699 301 1679868459787
+...
+...
+...
+ticking: 299 59701 1679868519187
+ticking: 198 59802 1679868519288
+ticking: 100 59900 1679868519386
+END: 1679868519487
+```
+
+
+
+
+### _API_
+the `countdown` function expects as parameters:  
+- **a function** : meant to be executed when the countdown is over 
+- **an integer**: the _"event horizont"_; number of milliseconds for the coundown to complete 
+
+returns an instance of a simple object where the following methods are available:  
+
+- **`run(ƒn)`** to start it, optionally accepts a function that will be called once started receiving the countdown instance
+
+- **`onTick(fn, tickInterval)`** to pass a function that will be called with a tick interval passing an object `{cycle, remaining, elapsed}` 
+- **`update(exp)`** to update the event horizont in milliseconds, it can be used to add subtract time to the horizont and to divide and multiply it:  
+
+    | exp | effect |
+    |-----|--------|
+    | 1000 | add 1000 ms |
+    | "+1000" | add 1000 ms |
+    | "-1000" | subtract 1000 ms |
+    | "*2" | double the current horizont |
+    | "/2" | halve the current horizont |
+
+    Notice: the update will happen only if the result ∈ ℝ
+
+
+- **`onUpdate(fn)`** to pass a function that will be invoked when update is called `fn` will be invoked receiving the instance 
+- **`onErr(fn)`** to pass a function that will handle any thrown err; fn will be invoked receiving the error and the instance 
+- **`end()`** to stop it
+- **`onEnd(fn)`** to pass a function that will be called additionally when `end` will be called; fn will be invoked receiving the instance 
+- **`pause()`** to pause it manually
+- **`onPause(fn)`** to pass a function that will be called when `pause` will be called; fn will be invoked receiving the instance   
+- **`resume()`** to resume it manually
+- **`onResume(fn)`** to pass a function that will be called when `resume` will be called; fn will be invoked receiving the instance   
+
+
diff --git a/source/build.json b/source/build.json
@@ -4,5 +4,6 @@
         "mkdir dist test"
     ],
     "#source/index.js": "dist -plugins=malta-js-uglify...malta-header-comment[name:\"source/header.txt\"]",
-    "#source/test/unit.js": "test"
+    "#source/test/unit.js": "test",
+    "#source/README.md": "."
 }
diff --git a/source/builddev.json b/source/builddev.json
@@ -4,5 +4,6 @@
         "mkdir dist test"
     ],
     "source/index.js": "dist -plugins=malta-js-uglify...malta-header-comment[name:\"source/header.txt\"]...malta-mocha",
-    "source/test/unit.js": "test -plugins=malta-mocha"
+    "source/test/unit.js": "test -plugins=malta-mocha",
+    "source/README.md": "."
 }
diff --git a/source/index.js b/source/index.js
@@ -27,9 +27,12 @@ const interval = require('@fedeghe/interval'),
             this.startPause = 0;
             this.pauseSpan = 0;
             this.updates = 0;
+
+            this._onUpdate = null;
+            this._update = null;
             this._onPause = null;
-            this._onResume = null;
             this._pause = null;
+            this._onResume = null;
             this._resume = null;
         }
         Countdown.prototype.end = function () {
@@ -40,23 +43,20 @@ const interval = require('@fedeghe/interval'),
             return this;
         };
         Countdown.prototype.onEnd = function (f) {
-            if (isFunction(f)) {
-                this._onEnd = f;
-            }
-            return this;
+            if (isFunction(f)) { this._onEnd = f; } return this;
         };
         Countdown.prototype.onErr = function (f) {
-            if (isFunction(f)) {
-                this._onErr = f;
-            }
-            return this;
+            if (isFunction(f)) { this._onErr = f; } return this;
         };
         Countdown.prototype.onPause = function (f) {
             if (isFunction(f)) { this._onPause = f; } return this;
         };
         Countdown.prototype.onResume = function (f) {
             if (isFunction(f)) { this._onResume = f; } return this;
         };
+        Countdown.prototype.onUpdate = function (f) {
+            if (isFunction(f)) { this._onUpdate = f; } return this;
+        };
         Countdown.prototype.pause = function () {
             this.paused = true;
             this._onPause && this._onPause(this);
@@ -88,7 +88,7 @@ const interval = require('@fedeghe/interval'),
                     self.ticker && self.ticker.end();
                 } catch (e) {
                     self._onErr &&
-                        self._onErr(e);
+                        self._onErr(e, self);
                     self.active = false;
                 }
             }, this.horizont);
@@ -102,7 +102,8 @@ const interval = require('@fedeghe/interval'),
                 elapsed = now - this.startTime - this.pauseSpan,
                 remaining = this.horizont - elapsed,
                 newHorizont = checkop(String(amount), remaining);
-            if (newHorizont) {
+            if (newHorizont && newHorizont > 0) {
+                this._onUpdate && this._onUpdate(this);
                 this.horizont = newHorizont;
                 this.to && clearTimeout(this.to);
                 this.run();

diff --git a/source/test/unit.js b/source/test/unit.js
@@ -98,18 +98,22 @@ describe('basic operations', () => {
             after = 1e3,
             start,
             end,
+            updated = false,
             cd = countdown(function () {
                 end = + new Date;
             }, horizont).run(() => {
                 start = + new Date;
+            }).onUpdate(() => {
+                updated = true;
             });
         setTimeout(function (){
             cd.update(up);
         }, after);
 
         setTimeout(function () {
             var e = end - start;
-            assert.equal(e < (horizont+up)*(1+tolerance), true);
+            assert.equal(e < (horizont + up) * (1 + tolerance), true);
+            assert.ok(updated);
             done();
         }, horizont + up + 10);
     }).timeout(8000);

diff --git a/yarn.lock b/yarn.lock
@@ -104,10 +104,10 @@
     "@babel/helper-validator-identifier" "^7.19.1"
     to-fast-properties "^2.0.0"
 
-"@fedeghe/interval@^1.0.17":
-  version "1.0.17"
-  resolved "https://registry.yarnpkg.com/@fedeghe/interval/-/interval-1.0.17.tgz#c22d6c110dd35cbb49f589cfebc0fec6983cabdb"
-  integrity sha512-CHYy9ZX8xIBmfxsRFu6K4PircNszzxvzoBYCeWkHlvs9cLXc0i+wjM+VbLixyoNzPW+iUNBegIQKYFpRbmxErw==
+"@fedeghe/interval@^1.0.18":
+  version "1.0.18"
+  resolved "https://registry.yarnpkg.com/@fedeghe/interval/-/interval-1.0.18.tgz#5e7837681ed6a0893e26317315910f98ca0380d0"
+  integrity sha512-koeJwiYoYQyY3+LJKMMWbpD1/QAv6CaBW8IIfCpSUwRbR8nGjy+xveiC5j3Z+TKF683gWcFbLpIqMQWiqzi2RA==
 
 "@jridgewell/gen-mapping@^0.3.2":
   version "0.3.2"