Merge pull request #17272 from afractal/sharp-timer

add timespan type definitions and documentation for sharp-timer

types/sharp-timer/index.d.ts

@@ -1,52 +1,315 @@
-// Type definitions for sharp-timer 0.3
+// Type definitions for sharp-timer library. 1.0
 // Project: https://github.com/afractal/SharpTimer
 // Definitions by: Hermes Gjini - afractal <https://github.com/afractal/>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
+/// <reference types="node" />
+
+export const millisPerSecond: 1000;
+export const millisPerMinute: 60000;
+export const millisPerHour: 3600000;
+export const millisPerDay: 86400000;
 export type ElapsedEvent = () => void;
 export type ElapsingEvent = (intervalValue: number) => void;
 
+/**
+ * Simulates the actions of a generic timer,
+ * generates elapsing and elapsed events for a specified interval.
+ */
 export class Timer {
-    private _enabled;
-    private _stopped;
-    private _interval;
-    private _intervalElapsedEvents;
-    private _intervalElapsingEvents;
+    private _enabled: boolean;
+    private _stopped: boolean;
+    private _interval: number;
+    private _intervalElapsedEvents: ElapsedEvent[];
+    private _intervalElapsingEvents: ElapsingEvent[];
+
+    /**
+     * Initializes a new instance of the Timer class,
+     * and sets all the properties to their initial values.
+     * @param interval
+     * The time, in milliseconds, in which the timer will be active.
+     * The value must be greater than zero.
+     */
     constructor(interval: number);
+
+    /**
+     * Gets a boolean value to indicate the enabled state
+     * of the current Timer instance.
+     * @readonly
+     * @default true
+     */
     readonly enabled: boolean;
+
+    /**
+     * Gets a boolean value to indicate the stopped state
+     * of the current Timer instance.
+     * @readonly
+     * @default false
+     */
     readonly stopped: boolean;
+
+    /**
+     * Gets or sets the remaining interval in milliseconds.
+     * The value must be greater than zero.
+     */
     interval: number;
+
+    /**
+     * Starts raising the Timer events
+     * by setting the enabled property to true.
+     */
     start(): void;
+
+    /**
+     * Pauses the Timer instance by setting the enabled property to false.
+     */
     pause(): void;
+
+    /**
+     * Resumes the Timer instance by setting the enabled property to true.
+     */
     resume(): void;
+
+    /**
+     * Stops raising the Timer event
+     * by setting the enabled property to false.
+     */
     stop(): void;
+
+    /**
+     * Occurs when the interval has completely elapsed.
+     * @param intervalElapsedHandler
+     * The callback which will be executed when
+     * the interval elapsed event occurs.
+     */
     onIntervalElapsed(intervalElapsedHandler: ElapsedEvent): void;
+
+    /**
+     * Occurs when the interval elapses and completely elapsed.
+     * @param intervalElapsingHandler
+     * The callback which will be executed when
+     * the interval elapsing event occurs.
+     */
     onIntervalElapsing(intervalElapsingHandler: ElapsingEvent): void;
+
+    /**
+     * Returns a string represenation of the remaining
+     * in this format: minutes:seconds.
+     * examples: 20:23, 00:04, 59:59
+     */
     toString(): string;
-    private getDoubleDigit(number);
-    private checkForValidInterval(interval);
+
+    private getDoubleDigit(number: number): string;
+
+    private checkForValidInterval(interval: number): void;
 }
 
+/**
+ * Simulates the actions of a generic stopwatch.
+ */
 export class Stopwatch {
-    private _isRunning;
-    private _elapsedMilliseconds;
-    private _startedTimeInMillis;
-    private _intervalIds;
-    private static readonly millisPerSecond;
-    private static readonly millisPerMinute;
-    private static readonly millisPerHour;
+    private _isRunning: boolean;
+    private _elapsedMilliseconds: number;
+    private _startedTimeInMillis: number;
+    private _intervalIds: Array<number | NodeJS.Timer>;
+
+    /**
+     * Initializes a new instance of the Stopwatch class.
+     */
     constructor();
+
+    /**
+     * Gets the elapsed time in this format:
+     * hrs:mins:secs:ms
+     * @readonly
+     */
     readonly elapsed: string;
+
+    /**
+     * Gets the elapsed time in milliseconds.
+     * @readonly
+     */
     readonly elapsedMilliseconds: number;
+
+    /**
+     * Gets the elapsed time in seconds.
+     * @readonly
+     */
     readonly elapsedSeconds: number;
+
+    /**
+     * Gets the elapsed time in minutes.
+     * @readonly
+     */
     readonly elapsedMinutes: number;
+
+    /**
+     * Gets the elapsed hours in hours.
+     * @readonly
+     */
     readonly elapsedHours: number;
+
+    /**
+     * Gets the isRunning state of the current Stopwatch instance.
+     * @readonly
+     * @default false
+     */
     readonly isRunning: boolean;
+
+    /**
+     * Initializes a new Stopwatch instance and
+     * starts measuring elapsed time.
+     */
     static startNew(): Stopwatch;
+
+    /**
+     * Starts, or resumes the Stopwatch
+     * from measuring elapsed time.
+     */
     start(): void;
+
+    /**
+     * Stops the Stopwatch from measuring elapsed time.
+     */
     stop(): void;
+
+    /**
+     * Stops the Stopwatch and resets the elapsed time to zero.
+     */
     reset(): void;
+
+    /**
+     * Stops the Stopwatch,
+     * resets the elapsed time to zero
+     * and starts the Stopwatch for measuring elapsed time.
+     * It is a shortcut for writing
+     * reset then start.
+     */
     restart(): void;
+
+    /**
+     * Stops the Stopwatch and cleans up the intervals.
+     */
     dispose(): void;
-    private getDoubleDigit(num);
+
+    private getDoubleDigit(num: number): string;
+}
+
+/**
+ * Simulates an object that represents a time interval.
+ */
+export class Timespan {
+    private _milliseconds: number;
+    private constructor(milliseconds: number);
+
+    /**
+     * Gets the time interval in milliseconds.
+     * @readonly
+     */
+    readonly milliseconds: number;
+
+    /**
+     * Gets the time interval in seconds.
+     * @readonly
+     */
+    readonly seconds: number;
+
+    /**
+     * Gets the time interval in minutes.
+     * @readonly
+     */
+    readonly minutes: number;
+
+    /**
+     * Gets the time interval in hours.
+     * @readonly
+     */
+    readonly hours: number;
+
+    /**
+     * Gets the time interval in days.
+     * @readonly
+     */
+    readonly days: number;
+
+    /**
+     * Returns a Timespan that represents a specified number of days.
+     * @param days The number of days.
+     */
+    static fromDays(days: number): Timespan;
+
+    /**
+     * Returns a Timespan that represents a specified number of hours.
+     * @param hours The number of hours.
+     */
+    static fromHours(hours: number): Timespan;
+
+    /**
+     * Returns a Timespan that represents a specified number of minutes.
+     * @param minutes The number of minutes.
+     */
+    static fromMinutes(minutes: number): Timespan;
+
+    /**
+     * Returns a Timespan that represents a specified number of seconds.
+     * @param seconds The number of seconds.
+     */
+    static fromSeconds(seconds: number): Timespan;
+
+    /**
+     * Returns a Timespan that represents a specified number of milliseconds.
+     * @param milliseconds The number of milliseconds.
+     */
+    static fromMilliseconds(milliseconds: number): Timespan;
+
+    /**
+     * Compares two Timespan objects and
+     * returns an integer that indicates whether
+     * the first value is shorter than, equal to,
+     * or longer than the second value.
+     * @param t1 The first Timespan to compare.
+     * @param t2 The second Timespan to compare.
+     */
+    static compare(t1: Timespan, t2: Timespan): 1 | 0 | -1;
+
+    /**
+     * Returns a boolean value that indicates
+     * whether two specified instances of Timespan are equal.
+     * @param t1 The first Timespan to compare.
+     * @param t2 The second Timespan to compare.
+     */
+    static equals(t1: Timespan, t2: Timespan): boolean;
+
+    /**
+     * Adds the specified Timespan to this instance.
+     * @param timespan The Timespan to add.
+     */
+    addMutable(timespan: Timespan): void;
+
+    /**
+     * Substracts the specified Timespan from this instance.
+     * @param timespan The Timespan to substract.
+     */
+    substractMutable(timespan: Timespan): void;
+
+    /**
+     * Returns a new Timespan object whose
+     * value is the sum of the specified Timespan object and this instance.
+     * @param timespan The Timespan to add.
+     */
+    add(timespan: Timespan): Timespan;
+
+    /**
+     * Returns a new Timespan object whose
+     * value is the difference between the
+     * specified Timespan object and this instance.
+     * @param timespan The Timespan to substract.
+     */
+    substract(timespan: Timespan): Timespan;
+
+    /**
+     * Returns a new Timespan object
+     * whose value is the negated value of this instance.
+     */
+    negate(): Timespan;
 }

types/sharp-timer/sharp-timer-tests.ts

@@ -1,10 +1,32 @@
-import { Timer, Stopwatch } from 'sharp-timer';
+import { Timer, Stopwatch, Timespan, millisPerSecond } from 'sharp-timer';
 
+const millisecondsPerSecond = millisPerSecond;
+
+// timer test
 let timer = new Timer(10);
-
+timer.toString();
 timer.onIntervalElapsing(i => { });
 timer.onIntervalElapsed(() => {
     timer.stop();
 });
 
 timer.start();
+
+// stopwatch test
+let stopwatch = Stopwatch.startNew();
+
+const intervalId = setInterval(() => { }, 10);
+
+setTimeout(() => {
+    clearInterval(intervalId);
+    stopwatch.dispose();
+}, 100);
+
+// timespan test
+const {
+    days,
+    hours,
+    minutes,
+    seconds,
+    milliseconds
+} = Timespan.fromDays(2);

types/sharp-timer/v0/index.d.ts

@@ -0,0 +1,52 @@
+// Type definitions for sharp-timer 0.3
+// Project: https://github.com/afractal/SharpTimer
+// Definitions by: Hermes Gjini - afractal <https://github.com/afractal/>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+export type ElapsedEvent = () => void;
+export type ElapsingEvent = (intervalValue: number) => void;
+
+export class Timer {
+    private _enabled;
+    private _stopped;
+    private _interval;
+    private _intervalElapsedEvents;
+    private _intervalElapsingEvents;
+    constructor(interval: number);
+    readonly enabled: boolean;
+    readonly stopped: boolean;
+    interval: number;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    onIntervalElapsed(intervalElapsedHandler: ElapsedEvent): void;
+    onIntervalElapsing(intervalElapsingHandler: ElapsingEvent): void;
+    toString(): string;
+    private getDoubleDigit(number);
+    private checkForValidInterval(interval);
+}
+
+export class Stopwatch {
+    private _isRunning;
+    private _elapsedMilliseconds;
+    private _startedTimeInMillis;
+    private _intervalIds;
+    private static readonly millisPerSecond;
+    private static readonly millisPerMinute;
+    private static readonly millisPerHour;
+    constructor();
+    readonly elapsed: string;
+    readonly elapsedMilliseconds: number;
+    readonly elapsedSeconds: number;
+    readonly elapsedMinutes: number;
+    readonly elapsedHours: number;
+    readonly isRunning: boolean;
+    static startNew(): Stopwatch;
+    start(): void;
+    stop(): void;
+    reset(): void;
+    restart(): void;
+    dispose(): void;
+    private getDoubleDigit(num);
+}

types/sharp-timer/v0/sharp-timer-tests.ts

@@ -0,0 +1,10 @@
+import { Timer, Stopwatch } from 'sharp-timer';
+
+let timer = new Timer(10);
+
+timer.onIntervalElapsing(i => { });
+timer.onIntervalElapsed(() => {
+    timer.stop();
+});
+
+timer.start();

types/sharp-timer/v0/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": [
+      "es6"
+    ],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "baseUrl": "../../",
+    "typeRoots": [
+      "../../"
+    ],
+    "paths": {
+      "sharp-timer": [
+        "sharp-timer/v0"
+      ]
+    },
+    "types": [],
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "files": [
+    "index.d.ts",
+    "sharp-timer-tests.ts"
+  ]
+}

types/sharp-timer/v0/tslint.json

@@ -0,0 +1,3 @@
+{
+  "extends": "dtslint/dt.json"
+}