@gamestdio/timer - npm Package Compare versions

Comparing version 1.3.2 to 1.4.0

lib/ClockTimer.d.ts

@@ -1,2 +0,2 @@
-import Clock = require("@gamestdio/clock");
+import Clock from "@gamestdio/clock";
 import { Delayed } from "./Delayed";
@@ -7,5 +7,57 @@ export declare class ClockTimer extends Clock {
     tick(): void;
+    /**
+     * Schedule a function to be called every `time` milliseconds.
+     * This `time` minimum value will be tied to the `tick` method of the clock. This means if you use the default `autoStart` value from the constructor, the minimum value will be 16ms. Otherwise it will depend on your `tick` method call.
+     *
+     * Returns a {@link Delayed} object that can be used to clear the timeout or play around with it.
+     */
     setInterval(handler: Function, time: number, ...args: any[]): Delayed;
+    /**
+     * Schedule a function to be called after a delay.
+     *
+     * This `time` minimum value will be tied to the `tick` method of the clock. This means if you use the default `autoStart` value from the constructor, the minimum value will be 16ms. Otherwise it will depend on your `tick` method call.
+     *
+     * Returns a {@link Delayed} object that can be used to clear the timeout or play around with it.
+     */
     setTimeout(handler: Function, time: number, ...args: any[]): Delayed;
+    /**
+     * A promise that schedule a timeout that will resolves after the given time.
+     *
+     * If the {@link AsyncDelayed} is cleared before the time, the promise will be rejected.
+     *
+     * For the sake of simplicity of this API, you can only cancel a timeout scheduled with this method with {@link ClockTimer.clear} method (which clears all scheduled timeouts and intervals).
+     * If you need fine-tuned control over the timeout, use the {@link ClockTimer.setTimeout} method instead.
+     *
+     * @example **Inside an async function**
+     * ```typescript
+     * const timer = new Clock(true);
+     * await timer.duration(1000);
+     * console.log("1 second later");
+     * ```
+     *
+     * @example **Using the promise**
+     * ```typescript
+     * const timer = new Clock(true);
+     * timer.duration(1000).then(() => console.log("1 second later"));
+     * ```
+     *
+     * @example **Using the promise with error**
+     * ```typescript
+     * const timer = new Clock(true);
+     * timer.duration(1000).then(() => console.log("1 second later")).catch(() => console.log("Timer cleared"));
+     * timer.clear();
+     * ```
+     *
+     *
+     * @param ms
+     * @returns
+     */
+    duration(ms: number): Promise<void>;
+    /**
+     * Delete any scheduled timeout or interval. That will never be executed.
+     *
+     * If some of the timeouts/intervals are already executed, they will be removed from the list and callback will be garbage collected.
+     * For timeout created with {@link ClockTimer.duration}, the promise will be rejected and therefore the unused resolving callback will be garbage collected.
+     */
     clear(): void;
 }

lib/ClockTimer.js

 "use strict";
-var __extends = (this && this.__extends) || (function () {
-    var extendStatics = function (d, b) {
-        extendStatics = Object.setPrototypeOf ||
-            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
-            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
-        return extendStatics(d, b);
-    };
-    return function (d, b) {
-        extendStatics(d, b);
-        function __() { this.constructor = d; }
-        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
-    };
-})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-var Clock = require("@gamestdio/clock");
-var Delayed_1 = require("./Delayed");
-var ClockTimer = /** @class */ (function (_super) {
-    __extends(ClockTimer, _super);
-    function ClockTimer(autoStart) {
-        if (autoStart === void 0) { autoStart = false; }
-        var _this = _super.call(this, autoStart) || this;
-        _this.delayed = [];
-        return _this;
+exports.ClockTimer = void 0;
+const clock_1 = __importDefault(require("@gamestdio/clock"));
+const Delayed_1 = require("./Delayed");
+class ClockTimer extends clock_1.default {
+    constructor(autoStart = false) {
+        super(autoStart);
+        this.delayed = [];
     }
-    ClockTimer.prototype.tick = function () {
-        _super.prototype.tick.call(this);
-        var delayedList = this.delayed;
-        var i = delayedList.length;
+    tick() {
+        super.tick();
+        let delayedList = this.delayed;
+        let i = delayedList.length;
         while (i--) {
-            var delayed = delayedList[i];
+            const delayed = delayedList[i];
             if (delayed.active) {
@@ -40,23 +28,74 @@ delayed.tick(this.deltaTime);
         }
-    };
-    ClockTimer.prototype.setInterval = function (handler, time) {
-        var args = [];
-        for (var _i = 2; _i < arguments.length; _i++) {
-            args[_i - 2] = arguments[_i];
-        }
-        var delayed = new Delayed_1.Delayed(handler, args, time, Delayed_1.Type.Interval);
+    }
+    /**
+     * Schedule a function to be called every `time` milliseconds.
+     * This `time` minimum value will be tied to the `tick` method of the clock. This means if you use the default `autoStart` value from the constructor, the minimum value will be 16ms. Otherwise it will depend on your `tick` method call.
+     *
+     * Returns a {@link Delayed} object that can be used to clear the timeout or play around with it.
+     */
+    setInterval(handler, time, ...args) {
+        const delayed = new Delayed_1.Delayed(handler, args, time, Delayed_1.Type.Interval);
         this.delayed.push(delayed);
         return delayed;
-    };
-    ClockTimer.prototype.setTimeout = function (handler, time) {
-        var args = [];
-        for (var _i = 2; _i < arguments.length; _i++) {
-            args[_i - 2] = arguments[_i];
-        }
-        var delayed = new Delayed_1.Delayed(handler, args, time, Delayed_1.Type.Timeout);
+    }
+    /**
+     * Schedule a function to be called after a delay.
+     *
+     * This `time` minimum value will be tied to the `tick` method of the clock. This means if you use the default `autoStart` value from the constructor, the minimum value will be 16ms. Otherwise it will depend on your `tick` method call.
+     *
+     * Returns a {@link Delayed} object that can be used to clear the timeout or play around with it.
+     */
+    setTimeout(handler, time, ...args) {
+        const delayed = new Delayed_1.Delayed(handler, args, time, Delayed_1.Type.Timeout);
         this.delayed.push(delayed);
         return delayed;
-    };
-    ClockTimer.prototype.clear = function () {
-        var i = this.delayed.length;
+    }
+    /**
+     * A promise that schedule a timeout that will resolves after the given time.
+     *
+     * If the {@link AsyncDelayed} is cleared before the time, the promise will be rejected.
+     *
+     * For the sake of simplicity of this API, you can only cancel a timeout scheduled with this method with {@link ClockTimer.clear} method (which clears all scheduled timeouts and intervals).
+     * If you need fine-tuned control over the timeout, use the {@link ClockTimer.setTimeout} method instead.
+     *
+     * @example **Inside an async function**
+     * ```typescript
+     * const timer = new Clock(true);
+     * await timer.duration(1000);
+     * console.log("1 second later");
+     * ```
+     *
+     * @example **Using the promise**
+     * ```typescript
+     * const timer = new Clock(true);
+     * timer.duration(1000).then(() => console.log("1 second later"));
+     * ```
+     *
+     * @example **Using the promise with error**
+     * ```typescript
+     * const timer = new Clock(true);
+     * timer.duration(1000).then(() => console.log("1 second later")).catch(() => console.log("Timer cleared"));
+     * timer.clear();
+     * ```
+     *
+     *
+     * @param ms
+     * @returns
+     */
+    duration(ms) {
+        return new Promise((resolve, reject) => {
+            const delayed = new Delayed_1.Delayed(resolve, [], ms, Delayed_1.Type.Async);
+            delayed.clear = reject;
+            this.delayed.push(delayed);
+            return delayed;
+        });
+    }
+    /**
+     * Delete any scheduled timeout or interval. That will never be executed.
+     *
+     * If some of the timeouts/intervals are already executed, they will be removed from the list and callback will be garbage collected.
+     * For timeout created with {@link ClockTimer.duration}, the promise will be rejected and therefore the unused resolving callback will be garbage collected.
+     */
+    clear() {
+        let i = this.delayed.length;
         while (i--) {
@@ -66,5 +105,4 @@ this.delayed[i].clear();
         this.delayed = [];
-    };
-    return ClockTimer;
-}(Clock));
+    }
+}
 exports.ClockTimer = ClockTimer;

lib/Delayed.d.ts

 export declare enum Type {
     Interval = 0,
-    Timeout = 1
+    Timeout = 1,
+    Async = 2
 }
@@ -5,0 +6,0 @@ export declare class Delayed {

lib/Delayed.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Delayed = exports.Type = void 0;
 var Type;
@@ -7,5 +8,6 @@ (function (Type) {
     Type[Type["Timeout"] = 1] = "Timeout";
-})(Type = exports.Type || (exports.Type = {}));
-var Delayed = /** @class */ (function () {
-    function Delayed(handler, args, time, type) {
+    Type[Type["Async"] = 2] = "Async";
+})(Type || (exports.Type = Type = {}));
+class Delayed {
+    constructor(handler, args, time, type) {
         this.active = true;
@@ -19,3 +21,3 @@ this.paused = false;
     }
-    Delayed.prototype.tick = function (deltaTime) {
+    tick(deltaTime) {
         if (this.paused) {
@@ -28,26 +30,27 @@ return;
         }
-    };
-    Delayed.prototype.execute = function () {
+    }
+    execute() {
         this.handler.apply(this, this.args);
-        if (this.type === Type.Timeout) {
-            this.active = false;
+        switch (this.type) {
+            case Type.Timeout:
+                this.active = false;
+                break;
+            case Type.Interval:
+                this.elapsedTime -= this.time;
+                break;
         }
-        else {
-            this.elapsedTime -= this.time;
-        }
-    };
-    Delayed.prototype.reset = function () {
+    }
+    reset() {
         this.elapsedTime = 0;
-    };
-    Delayed.prototype.pause = function () {
+    }
+    pause() {
         this.paused = true;
-    };
-    Delayed.prototype.resume = function () {
+    }
+    resume() {
         this.paused = false;
-    };
-    Delayed.prototype.clear = function () {
+    }
+    clear() {
         this.active = false;
-    };
-    return Delayed;
-}());
+    }
+}
 exports.Delayed = Delayed;

lib/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Type = exports.Delayed = void 0;
 var Delayed_1 = require("./Delayed");
-exports.Delayed = Delayed_1.Delayed;
-exports.Type = Delayed_1.Type;
-var ClockTimer_1 = require("./ClockTimer");
+Object.defineProperty(exports, "Delayed", { enumerable: true, get: function () { return Delayed_1.Delayed; } });
+Object.defineProperty(exports, "Type", { enumerable: true, get: function () { return Delayed_1.Type; } });
+const ClockTimer_1 = require("./ClockTimer");
 exports.default = ClockTimer_1.ClockTimer;

package.json

 {
   "name": "@gamestdio/timer",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Timing Events tied to @gamestdio/clock",
@@ -8,3 +8,3 @@ "main": "lib/index.js",
   "scripts": {
-    "prepublish": "tsc",
+    "prepublishOnly": "tsc",
     "test": "mocha --require ts-node/register test/**Test.ts"
@@ -14,3 +14,3 @@ },
     "type": "git",
-    "url": "git+https://github.com/gamestdio/clock-timer.js.git"
+    "url": "git+https://github.com/colyseus/timer.git"
   },
@@ -28,5 +28,5 @@ "keywords": [
   "bugs": {
-    "url": "https://github.com/gamestdio/clock-timer.js/issues"
+    "url": "https://github.com/colyseus/timer/issues"
   },
-  "homepage": "https://github.com/gamestdio/clock-timer.js#readme",
+  "homepage": "https://github.com/colyseus/timer#readme",
   "dependencies": {
@@ -36,9 +36,9 @@ "@gamestdio/clock": "^1.1.9"
   "devDependencies": {
-    "@types/mocha": "^2.2.41",
-    "assert": "^1.3.0",
-    "mocha": "^6.0.2",
-    "rimraf": "^2.5.2",
-    "ts-node": "^8.0.2",
-    "typescript": "^3.3.3333"
+    "@types/mocha": "^10.0.6",
+    "assert": "^2.1.0",
+    "mocha": "^10.3.0",
+    "rimraf": "^5.0.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
   }
 }

README.md

@@ -16,3 +16,3 @@ # @gamestdio/timer [![Build Status](https://secure.travis-ci.org/gamestdio/timer.png?branch=master)](http://travis-ci.org/gamestdio/timer)
 
-> This API does not guarantee that timers will fire exactly on schedule.  Delays
+> This API does not guarantee that timers will fire exactly on schedule. Delays
 > due to CPU load, other tasks, etc, are to be expected.
@@ -26,3 +26,4 @@
 - `setTimeout(handler, time, ...args)` -> `Delayed`
-- `clear()` - clear all intervals and timeouts.
+- `duration(ms: number)` -> `Promise<void>` - Convenience method to wait for a duration in async functions or promises. See associated JSdoc for more details.
+- `clear()` - clear all intervals and timeouts, and throw any promise created with `duration`.
 
@@ -29,0 +30,0 @@ **Delayed**

tsconfig.json

 {
   "compilerOptions": {
     "outDir": "lib",
-    "target": "ES5",
+    "target": "ES2016",
+    "esModuleInterop": true,
     "module": "commonjs",
@@ -11,10 +12,4 @@ "noImplicitAny": false,
   },
-  "include": [
-    "src/*.ts"
-  ],
-  "exclude": [
-    "node_modules",
-    "test",
-    "dist"
-  ]
+  "include": ["src/*.ts"],
+  "exclude": ["node_modules", "test", "dist"]
 }

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

13270

increased by52.07%

Lines of code

267

increased by50.85%

Number of lines in readme file

40

increased by2.56%

Worsened metrics

Number of package files

11

decreased by-8.33%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes