eternal-timer 1.4.2 → 2.0.0

package/README.md

@@ -4,7 +4,7 @@ A simple and persistent timer library for Node.js. Timers are saved to a file an
 
 ## Features
 
-- **Monitor Timers (asynchronous)**: Start monitoring expired timers asynchronously; the function returns immediately and the callback is invoked when timers expire.
+- **Monitor Timers (asynchronous)**: Start monitoring expired timers asynchronously; the function returns immediately and the callback is called when timers expire.
 - **Persistence**: Save timer data to a file that persists across process restarts
 
 ## Installation
@@ -18,29 +18,40 @@ npm install eternal-timer
 ### Basic Example
 
 ```typescript
-import { createTimer, checkTimers, removeTimer, showTimers } from 'eternal-timer';
+import { TimersManager } from 'eternal-timer';
 
 async function main() {
-  // Create a timer (5 seconds)
-  const timerId = await createTimer(5000);
-  console.log('Timer created:', timerId);
+    const manager = new TimersManager();
 
-  // Monitor timers (executes when timer expires)
-  checkTimers((timer) => {
-    console.log('Timer expired:', timer.id);
-  });
+    // Create a timer (5 seconds)
+    const timerId = await manager.createTimer(5000);
+    console.log('Timer created:', timerId);
 
-  // Display all timers
-  const timers = await showTimers();
-  console.log('Active timers:', timers);
+    // Monitor timers (executes when timer expires)
+    manager.checkTimers(async (timer) => {
+        console.log('Timer expired:', timer.id);
+    });
 
-  // Remove a timer
-  await removeTimer(timerId);
+    // Display all timers
+    const timers = await manager.showTimers();
+    console.log('Active timers:', timers);
+
+    // Remove a timer
+    await manager.removeTimer(timerId);
 }
+
+main();
 ```
 
 ## API
 
+### `new TimersManager(timerfiledir?: string)`
+
+Creates a new `TimersManager` instance.
+
+**Parameters:**
+- `timerfiledir` (string, optional): The path to the directory where the timer file is stored. If omitted, `.timers` under the project root is used.
+
 ### `createTimer(length: number): Promise<string>`
 
 Creates a new timer.
@@ -52,7 +63,7 @@ Creates a new timer.
 
 **Throws:** If length is invalid(e.g. length < 0) or file operation fails
 
-### `removeTimer(id: string): Promise<boolean>`
+### `removeTimer(id: string): Promise<void>`
 
 Removes a timer by ID.
 
@@ -61,12 +72,17 @@ Removes a timer by ID.
 
 **Returns:** void
 
-### `checkTimers(callback: (timer: Timer) => void, interval?: number): Promise<void>`
+**Throws:** If the timer with the specified ID is not found or if a file operation fails.
+
+### `checkTimers(callback: (timer: Timer) => Promise<void>, interval?: number): Promise<void>`
+
+Starts monitoring expired timers and returns immediately.
 
-Starts monitoring expired timers asynchronously and returns immediately. The callback is invoked asynchronously when a timer expires.
+The callback is invoked when a timer expires during periodic checks.
+The callback is awaited before the next timer check continues.
 
 **Parameters:**
-- `callback`: Function invoked when an expired timer is detected (called asynchronously)
+- `callback`: Function invoked when an expired timer is detected (called during periodic checks and awaited)
 - `interval` (number, optional): Check interval in milliseconds (default: 50ms)
 
 **Throws:** If file operation fails
@@ -84,8 +100,8 @@ Retrieves all active timers.
 ```typescript
 type Timer = {
     id: string;      // Unique timer identifier (UUID)
-    start: string;   // Timer start timestamp
-    stop: string;    // Timer end timestamp
+    start: number;   // Timer start timestamp
+    stop: number;    // Timer end timestamp
 }
 ```
 
@@ -111,4 +127,4 @@ Licensed under the Apache License, Version 2.0. See the `LICENSE` file for detai
 
 ## Repository
 
-https://github.com/SUKEsann2000/eternal-timer
+https://github.com/SUKEsann2000/eternal-timer

package/dist/cjs/index.cjs

@@ -3,214 +3,203 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTimer = createTimer;
-exports.removeTimer = removeTimer;
-exports.checkTimers = checkTimers;
-exports.showTimers = showTimers;
-exports.getRemainingTimer = getRemainingTimer;
+exports.TimersManager = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const searchRoot_js_1 = __importDefault(require("./searchRoot.js"));
 const uuid_1 = require("uuid");
-// search root folder of project
-const rootdir = (0, searchRoot_js_1.default)();
-const timerfiledir = path_1.default.join(rootdir, ".timers");
 /**
- * createFile
- * @description create `.timers` file
- * @returns void
- * @throws If file operation fails
- * @example
- * await createFile();
+ * TimersManager
+ * @description
+ * Manages timers stored in a file.
+ * Each timer is stored as: `id start stop`.
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
  */
-async function createFile() {
-    if (!fs_1.default.existsSync(timerfiledir)) {
-        fs_1.default.writeFile(timerfiledir, "", (data) => {
-            console.log("The file was created in ", timerfiledir);
-        });
+class TimersManager {
+    timerfiledir;
+    /**
+     * constructor
+     * @param timerfiledir(string, optional)
+     * If omitted, `.timers` under the project root is used.
+     */
+    constructor(timerfiledir) {
+        this.timerfiledir =
+            timerfiledir ?? path_1.default.join((0, searchRoot_js_1.default)(), ".timers");
     }
-    return;
-}
-/**
- * createTimer
- * @description Creates a new timer.
- * @param length Timer duration in milliseconds
- * @returns Promise that resolves to the timer ID (UUID)
- * @throws If length is invalid(e.g. length < 0) or file operation fails
- * @example
- * const newTimer = await createTimer(5000);
- * // newTimer will be id of the timer
- */
-async function createTimer(length) {
-    try {
-        await createFile();
-        if (length < 0) {
-            throw new Error(`Invailed length: ${length}`);
+    /**
+     * createFile
+     * @description create `.timers` file
+     * @returns void
+     * @throws If file operation fails
+     */
+    async createFile() {
+        try {
+            await fs_1.default.promises.access(this.timerfiledir);
+        }
+        catch {
+            await fs_1.default.promises.writeFile(this.timerfiledir, "");
         }
-        length = Math.trunc(length);
-        // uuid, start, end
-        const id = (0, uuid_1.v4)();
-        const now = Date.now();
-        const newTimerData = `${id} ${now.toString()} ${(now + length).toString()}`;
-        await fs_1.default.promises.appendFile(timerfiledir, newTimerData + "\n");
-        return id;
-    }
-    catch (e) {
-        throw new Error(`Error when creating timer: ${e}`);
     }
-}
-/**
- * removeTimer
- * @description Removes a timer by ID.
- * @param id ID of the timer to remove
- * @returns void
- * @throws If file operation fails
- * @example
- * await removeTimer(id);
- */
-async function removeTimer(id) {
-    try {
-        const timersRaw = fs_1.default.readFileSync(timerfiledir, "utf-8");
-        const timersData = timersRaw.split(/\r?\n/);
-        let newTimersData = "";
-        let found = false;
-        for (const timerData of timersData) {
-            if (!timerData.trim()) {
-                found = true;
-                continue;
+    /**
+     * createTimer
+     * @description Creates a new timer.
+     * @param length Timer duration in milliseconds
+     * @returns Promise that resolves to the timer ID (UUID)
+     * @throws If length is invalid(e.g. length < 0) or file operation fails
+     * @example
+     * const manager = new TimersManager();
+     * const newTimer = await manager.createTimer(5000);
+     * // newTimer will be id of the timer
+     */
+    async createTimer(length) {
+        try {
+            await this.createFile();
+            if (length < 0) {
+                throw new Error(`Invailed length: ${length}`);
             }
-            const [timerId] = timerData.split(" ");
-            if (timerId !== id) {
+            length = Math.trunc(length);
+            // uuid, start, end
+            const id = (0, uuid_1.v4)();
+            const now = Date.now();
+            const newTimerData = `${id} ${now.toString()} ${(now + length).toString()}`;
+            await fs_1.default.promises.appendFile(this.timerfiledir, newTimerData + "\n");
+            return id;
+        }
+        catch (e) {
+            throw new Error(`Error when creating timer: ${e}`);
+        }
+    }
+    /**
+     * removeTimer
+     * @description Removes a timer by ID.
+     * @param id ID of the timer to remove
+     * @returns void
+     * @throws If file operation fails
+     * @example
+     * await manager.removeTimer(id);
+     */
+    async removeTimer(id) {
+        try {
+            const timersRaw = fs_1.default.readFileSync(this.timerfiledir, "utf-8");
+            const timersData = timersRaw.split(/\r?\n/);
+            let newTimersData = "";
+            let found = false;
+            for (const timerData of timersData) {
+                if (!timerData.trim())
+                    continue;
+                const [timerId] = timerData.split(" ");
+                if (timerId === id) {
+                    found = true;
+                    continue;
+                }
                 newTimersData += timerData + "\n";
             }
+            if (!found) {
+                throw new Error(`Timer with id ${id} not found`);
+            }
+            await fs_1.default.promises.writeFile(this.timerfiledir, newTimersData, "utf-8");
+            return;
         }
-        if (!found) {
-            throw new Error(`Timer with id ${id} not found`);
+        catch (e) {
+            throw new Error(`Error when removing timer: ${e}`);
         }
-        await fs_1.default.promises.writeFile(timerfiledir, newTimersData, "utf-8");
-        return;
     }
-    catch (e) {
-        throw new Error(`Error when removing timer: ${e}`);
+    /**
+     * @description Starts monitoring expired timers asynchronously and returns immediately. The callback is invoked asynchronously when a timer expires.
+     * The callback is awaited before continuing.
+     * @param callback Function invoked when an expired timer is detected (called asynchronously)
+     * @param interval (number, optional): Check interval in milliseconds (default: 50ms)
+     * @throws If file operation fails
+     * @example
+     * manager.checkTimers((timer) => {
+     *     console.log(`A timer was stopped: ${timer.id}`);
+     * });
+     */
+    async checkTimers(callback, interval = 50) {
+        try {
+            await this.createFile();
+            setInterval(async () => {
+                const timersDataRaw = await fs_1.default.promises.readFile(this.timerfiledir, "utf-8");
+                const timersData = timersDataRaw.split(/\r?\n/);
+                const timersSet = new Set();
+                await this.checkTimerfileSyntax(timersDataRaw);
+                for (const timerData of timersData) {
+                    if (!timerData.trim())
+                        continue;
+                    const [id, startStr, stopStr] = timerData.split(" ");
+                    timersSet.add({
+                        id: id,
+                        start: Number(startStr),
+                        stop: Number(stopStr),
+                    });
+                }
+                const now = Date.now();
+                for (const timer of timersSet) {
+                    if (Number(timer.stop) <= now) {
+                        await this.removeTimer(timer.id);
+                        await callback(timer);
+                    }
+                }
+            }, interval);
+        }
+        catch (e) {
+            throw new Error(`Error when checking alarm: ${e}`);
+        }
     }
-}
-/**
- * @description Starts monitoring expired timers asynchronously and returns immediately. The callback is invoked asynchronously when a timer expires.
- * @param callback Function invoked when an expired timer is detected (called asynchronously)
- * @param interval (number, optional): Check interval in milliseconds (default: 50ms)
- * @throws If file operation fails
- * @example
- * checkTimers((timer) => {
- *     console.log(`A timer was stopped: ${timer.id}`);
- * });
- */
-async function checkTimers(callback, interval = 50) {
-    try {
-        await createFile();
-        setInterval(() => {
-            const timersDataRaw = fs_1.default.readFileSync(timerfiledir, "utf-8");
-            const timersData = timersDataRaw.split(/\r?\n/);
-            const timersSet = new Set();
-            checkTimerfileSyntax(timersDataRaw);
+    /**
+     * showTimers
+     * @description Retrieves all active timers.
+     * @returns Array of `Timer` objects
+     * @throws If file operation fails
+     * @example
+     * const timers = await manager.showTimers();
+     * console.log(JSON.stringify(timers))
+     */
+    async showTimers() {
+        try {
+            await this.createFile();
+            const timersRaw = fs_1.default.readFileSync(this.timerfiledir, "utf-8");
+            const timersData = timersRaw.split(/\r?\n/);
+            const timersJSON = [];
             for (const timerData of timersData) {
+                const splitedTimerData = timerData.split(" ");
                 if (!timerData.trim())
                     continue;
-                const [id, startStr, stopStr] = timerData.split(" ");
-                timersSet.add({
-                    id: id,
-                    start: startStr,
-                    stop: stopStr
+                timersJSON.push({
+                    id: splitedTimerData[0],
+                    start: Number(splitedTimerData[1]),
+                    stop: Number(splitedTimerData[2]),
                 });
             }
-            const now = Date.now();
-            for (const timer of timersSet) {
-                if (Number(timer.stop) <= now) {
-                    removeTimer(timer.id);
-                    callback(timer);
-                }
-            }
-        }, interval);
-    }
-    catch (e) {
-        throw new Error(`Error when checking alarm: ${e}`);
-    }
-}
-/**
- * showTimers
- * @description Retrieves all active timers.
- * @returns Array of `Timer` objects
- * @throws If file operation fails
- * @example
- * const timers = await showTimers();
- * console.log(JSON.stringify(timers))
- */
-async function showTimers() {
-    try {
-        await createFile();
-        const timersRaw = fs_1.default.readFileSync(timerfiledir, "utf-8");
-        const timersData = timersRaw.split(/\r?\n/);
-        let timersJSON = [];
-        for (const timerData of timersData) {
-            const splitedTimerData = timerData.split(" ");
-            timersJSON.push({
-                id: splitedTimerData[0],
-                start: splitedTimerData[1],
-                stop: splitedTimerData[2]
-            });
+            return timersJSON;
+        }
+        catch (e) {
+            throw new Error(`Error when showing timers: ${e}`);
         }
-        return timersJSON;
-    }
-    catch (e) {
-        throw new Error(`Error when showing timers: ${e}`);
     }
-}
-/**
- * getRemainingTimer
- * @description Retrieves the remaining time of a timer by ID.
- * @param id timer's id you want to get remaining time(ms)
- * @returns Remaining time of the timer(ms)
- * @throws If timer with the specified ID is not found or file operation fails
- * @example
- * const remaining: number = await getRemainingTimer(id);
- * console.log(`Remaining time: ${remaining} ms`);
- */
-async function getRemainingTimer(id) {
-    try {
-        const timersRaw = fs_1.default.readFileSync(timerfiledir, "utf-8");
-        const timersData = timersRaw.split(/\r?\n/);
+    async checkTimerfileSyntax(fileData) {
+        const throwing = () => {
+            throw new Error(`Timer file's syntax is wrong`);
+        };
+        const timersData = fileData
+            .split('\n')
+            .map(l => l.trim())
+            .filter(l => l !== "");
         for (const timerData of timersData) {
-            const splitedTimerData = timerData.split(" ");
-            if (splitedTimerData[0] === id) {
-                const now = Date.now();
-                const stop = Number(splitedTimerData[2]);
-                return Math.max(0, stop - now);
-            }
+            const timerArray = timerData.split(/\s+/);
+            if (timerArray.length !== 3)
+                throwing();
+            if (timerArray[0]?.length !== 36)
+                throwing();
+            if (timerArray[1].trim() === "")
+                throwing();
+            if (timerArray[2].trim() === "")
+                throwing();
         }
-        throw new Error(`Timer with id ${id} not found`);
-    }
-    catch (e) {
-        throw new Error(`Error when getting remaining timer: ${e}`);
-    }
-}
-async function checkTimerfileSyntax(fileData) {
-    const throwing = () => {
-        throw new Error(`Timer file's syntax is wrong`);
-    };
-    const timersData = fileData
-        .split('\n')
-        .map(l => l.trim())
-        .filter(l => l !== "");
-    for (const timerData of timersData) {
-        const timerArray = timerData.split(/\s+/);
-        if (timerArray.length !== 3)
-            throwing();
-        if (timerArray[0]?.length !== 36)
-            throwing();
-        if (timerArray[1].trim() === "")
-            throwing();
-        if (timerArray[2].trim() === "")
-            throwing();
+        return;
     }
-    return;
 }
+exports.TimersManager = TimersManager;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.d.ts

@@ -1,59 +1,76 @@
 export type Timer = {
     id: string;
-    start: string;
-    stop: string;
+    start: number;
+    stop: number;
 };
 /**
- * createTimer
- * @description Creates a new timer.
- * @param length Timer duration in milliseconds
- * @returns Promise that resolves to the timer ID (UUID)
- * @throws If length is invalid(e.g. length < 0) or file operation fails
- * @example
- * const newTimer = await createTimer(5000);
- * // newTimer will be id of the timer
+ * TimersManager
+ * @description
+ * Manages timers stored in a file.
+ * Each timer is stored as: `id start stop`.
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
  */
-export declare function createTimer(length: number): Promise<string>;
-/**
- * removeTimer
- * @description Removes a timer by ID.
- * @param id ID of the timer to remove
- * @returns void
- * @throws If file operation fails
- * @example
- * await removeTimer(id);
- */
-export declare function removeTimer(id: string): Promise<void>;
-/**
- * @description Starts monitoring expired timers asynchronously and returns immediately. The callback is invoked asynchronously when a timer expires.
- * @param callback Function invoked when an expired timer is detected (called asynchronously)
- * @param interval (number, optional): Check interval in milliseconds (default: 50ms)
- * @throws If file operation fails
- * @example
- * checkTimers((timer) => {
- *     console.log(`A timer was stopped: ${timer.id}`);
- * });
- */
-export declare function checkTimers(callback: (timer: Timer) => void, interval?: number): Promise<void>;
-/**
- * showTimers
- * @description Retrieves all active timers.
- * @returns Array of `Timer` objects
- * @throws If file operation fails
- * @example
- * const timers = await showTimers();
- * console.log(JSON.stringify(timers))
- */
-export declare function showTimers(): Promise<Timer[]>;
-/**
- * getRemainingTimer
- * @description Retrieves the remaining time of a timer by ID.
- * @param id timer's id you want to get remaining time(ms)
- * @returns Remaining time of the timer(ms)
- * @throws If timer with the specified ID is not found or file operation fails
- * @example
- * const remaining: number = await getRemainingTimer(id);
- * console.log(`Remaining time: ${remaining} ms`);
- */
-export declare function getRemainingTimer(id: string): Promise<number>;
+export declare class TimersManager {
+    private readonly timerfiledir;
+    /**
+     * constructor
+     * @param timerfiledir(string, optional)
+     * If omitted, `.timers` under the project root is used.
+     */
+    constructor(timerfiledir?: string);
+    /**
+     * createFile
+     * @description create `.timers` file
+     * @returns void
+     * @throws If file operation fails
+     */
+    private createFile;
+    /**
+     * createTimer
+     * @description Creates a new timer.
+     * @param length Timer duration in milliseconds
+     * @returns Promise that resolves to the timer ID (UUID)
+     * @throws If length is invalid(e.g. length < 0) or file operation fails
+     * @example
+     * const manager = new TimersManager();
+     * const newTimer = await manager.createTimer(5000);
+     * // newTimer will be id of the timer
+     */
+    createTimer(length: number): Promise<string>;
+    /**
+     * removeTimer
+     * @description Removes a timer by ID.
+     * @param id ID of the timer to remove
+     * @returns void
+     * @throws If file operation fails
+     * @example
+     * await manager.removeTimer(id);
+     */
+    removeTimer(id: string): Promise<void>;
+    /**
+     * @description Starts monitoring expired timers asynchronously and returns immediately. The callback is invoked asynchronously when a timer expires.
+     * The callback is awaited before continuing.
+     * @param callback Function invoked when an expired timer is detected (called asynchronously)
+     * @param interval (number, optional): Check interval in milliseconds (default: 50ms)
+     * @throws If file operation fails
+     * @example
+     * manager.checkTimers((timer) => {
+     *     console.log(`A timer was stopped: ${timer.id}`);
+     * });
+     */
+    checkTimers(callback: (timer: Timer) => Promise<void>, interval?: number): Promise<void>;
+    /**
+     * showTimers
+     * @description Retrieves all active timers.
+     * @returns Array of `Timer` objects
+     * @throws If file operation fails
+     * @example
+     * const timers = await manager.showTimers();
+     * console.log(JSON.stringify(timers))
+     */
+    showTimers(): Promise<Timer[]>;
+    private checkTimerfileSyntax;
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,KAAK,GAAG;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAA;CACf,CAAA;AAuBD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBjE;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3D;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAAE,QAAQ,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCxG;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAmBnD;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBnE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,KAAK,GAAG;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;OAIM;gBAEL,YAAY,CAAC,EAAE,MAAM;IAMtB;;;;;OAKM;YACQ,UAAU;IAQxB;;;;;;;;;;OAUM;IACO,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBzD;;;;;;;;OAQM;IACO,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BnD;;;;;;;;;;OAUM;IACO,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCzG;;;;;;;;OAQM;IACO,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAsB7B,oBAAoB;CAiBlC"}