eternal-timer 2.2.1 → 2.4.0

package/README.md

@@ -33,11 +33,11 @@ async function main() {
     const manager = new JSONLTimersManager();
 
     // Create a timer (5 seconds) with a title and description
-    const timerId = await manager.createTimer(5000, 'My Timer', 'This is a test timer.');
+    const timerId = await manager.createTimer({length: 5000, title: 'My Timer', description: 'This is a test timer.'});
     console.log('Timer created:', timerId);
 
     // Monitor timers (executes when timer expires)
-    const interval = manager.checkTimers(async (timer) => {
+    const interval = await manager.checkTimers(async (timer) => {
         console.log('Timer expired:', timer.id, timer.title);
     });
 
@@ -45,8 +45,11 @@ async function main() {
     const timers = await manager.showTimers();
     console.log('Active timers:', timers);
 
-    // Remove a timer
-    await manager.removeTimer(timerId);
+    // To stop monitoring, for example after 10 seconds
+    setTimeout(() => {
+        clearInterval(interval);
+        console.log('Stopped monitoring timers.');
+    }, 10000);
 }
 
 main();
@@ -68,9 +71,19 @@ async function main() {
     console.log('Timer created:', timerId);
 
     // Monitor timers
-    const interval = manager.checkTimers(async (timer) => {
+    const interval = await manager.checkTimers(async (timer) => {
         console.log('Timer expired:', timer.id);
     });
+
+    // Display all timers
+    const timers = await manager.showTimers();
+    console.log('Active timers:', timers);
+    
+    // Stop monitoring after a while
+    setTimeout(() => {
+        clearInterval(interval);
+        console.log('Stopped monitoring timers.');
+    }, 10000);
 }
 
 main();
@@ -78,79 +91,109 @@ main();
 
 ## API
 
-### `new JSONLTimersManager(timerfiledir?: string)`
+### `JSONLTimersManager`
 
-Creates a manager for timers stored in the **JSON Lines** format.
+#### `constructor(timerfiledir?: string)`
+Creates a manager for timers stored in **JSON Lines** format.
 
-**Parameters:**
-- `timerfiledir` (string, optional): The path to the timer file. If omitted, the default is `.timers.jsonl` in the project root.
+- **`timerfiledir`** (optional, string): Path to the timer file. Defaults to `.timers.jsonl` in the project root.
 
-### `new PlainTextTimersManager(timerfiledir?: string)`
+### `PlainTextTimersManager`
 
-Creates a manager for timers stored in the **plain-text** format.
+#### `constructor(timerfiledir?: string)`
+Creates a manager for timers stored in **plain-text** format.
 
-**Parameters:**
-- `timerfiledir` (string, optional): The path to the timer file. If omitted, the default is `.timers` in the project root.
+- **`timerfiledir`** (optional, string): Path to the timer file. Defaults to `.timers` in the project root.
 
 ---
 
-### `createTimer(length: number, title?: string, description?: string): Promise<string>`
+### `createTimer(options: CreateTimerOptions<T>): Promise<string>`
+
+Creates a new timer and saves it to the file.
 
-Creates a new timer.
+#### Parameters
 
-**Parameters:**
-- `length` (number): Timer duration in milliseconds
-- `title` (string, optional): A title for the timer. **Only available for `JSONLTimersManager`**.
-- `description` (string, optional): A description for the timer. **Only available for `JSONLTimersManager`**.
+- **`options`**
 
-**Returns:** Promise that resolves to the timer ID (UUID)
+  When using `"PlainText"` storage:
+  - `number` — Timer duration in milliseconds.
 
-**Throws:** If length is invalid(e.g. length < 0) or file operation fails
+  When using `"JSONL"` storage:
+  - `{ length: number; title?: string; description?: string }`
+    - `length` (number): Timer duration in milliseconds.
+    - `title` (optional, string): A title for the timer.
+    - `description` (optional, string): A description for the timer.
+
+  - `number` — Timer duration in milliseconds.  
+    ⚠ Not recommended. See [Storage Formats](#storage-formats).
+
+**Returns** A `Promise<string>` that resolves to the timer's unique ID (UUID).
+
+**Throws** An error if: `length` is invalid (e.g., negative) or a file operation fails
 
 ### `removeTimer(id: string): Promise<void>`
 
-Removes a timer by ID.
+Removes a timer by its ID.
 
-**Parameters:**
-- `id` (string): ID of the timer to remove
+- **`id`**: The ID of the timer to remove.
 
-**Returns:** void
+**Returns:** A `Promise` that resolves when the timer is removed.
 
-**Throws:** If the timer with the specified ID is not found or if a file operation fails.
+**Throws:** An error 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<NodeJS.Timeout>`
+### `checkTimers(callback: (timer: Timer) => void | Promise<void>, interval?: number): Promise<NodeJS.Timeout>`
 
-Starts monitoring expired timers and returns immediately.
+Starts monitoring timers at the specified interval and invokes the provided
+`callback` 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.
+For each expired timer, the `callback` is awaited before processing continues.
+Monitoring runs periodically in the background and can be stopped using the
+returned `NodeJS.Timeout`.
 
-**Parameters:**
-- `callback`: Function invoked when an expired timer is detected (called during periodic checks and awaited)
-- `interval` (number, optional): Check interval in milliseconds (default: 200ms)
+- **callback**: An async function invoked with the expired `timer`.
+- **interval** *(optional, number)*: Interval in milliseconds for checking timers.
+  Defaults to `200`.
 
-**Returns:** interval id of checkTimers
+**Returns:** A `NodeJS.Timeout` that can be passed to `clearInterval()` to stop monitoring.
 
-**Throws:** If file operation fails
+**Throws:** An error if a timer storage operation fails.
 
 ### `showTimers(): Promise<Timer[]>`
 
 Retrieves all active timers.
 
-**Returns:** Array of `Timer` objects
+**Returns:** A `Promise` that resolves to an array of `Timer` objects.
+
+**Throws:** An error if a file operation fails.
 
-**Throws:** If file operation fails
+### `adjustRemainingTime(id: string, delay: number): Promise<void>`
+
+Adjusts the remaining time of a specified timer. This can be used to extend or shorten a timer's duration.
+
+- **`id`**: The ID of the timer to modify.
+- **`delay`**: The amount of time in milliseconds to add to (if positive) or subtract from (if negative) the timer's remaining duration.
+
+**Returns:** A `Promise<void>` that resolves when the timer's remaining time has been adjusted.
+
+**Throws:** An error if: the timer with the specified ID is not found, the resulting remaining time would be negative, or a file operation fails.
 
 ## Type Definition
 
+The `StorageType` has the following structure:
 ```typescript
-type Timer = {
-    id: string;      // Unique timer identifier (UUID)
-    start: number;   // Timer start timestamp
-    stop: number;    // Timer end timestamp
-    title?: string;
-    description?: string;
-}
+type StorageType = "JSONL" | "PlainText"
+```
+
+The `Timer` object has the following structure:
+
+```typescript
+type Timer<T extends StorageType> = {
+  id: string;
+  start: number;
+  stop: number;
+} & (T extends "JSONL"
+  ? { title?: string; description?: string }
+  : {});
 ```
 
 ## Scripts
@@ -168,7 +211,7 @@ You can choose between two storage formats by selecting the appropriate manager
 ### 1. JSON Lines (via `JSONLTimersManager`)
 This is the recommended format for storing rich metadata.
 
-- **Pros**: Allows for storing `title` and `description`.
+- **Pros**: Allows for storing `title` and `description`. Improved memory efficiency due to line-by-line file reading.
 - **Cons**: Involves JSON parsing, which may have a minor performance overhead.
 - **Default File**: `.timers.jsonl`
 - **Format**:
@@ -179,7 +222,7 @@ This is the recommended format for storing rich metadata.
 ### 2. Plain Text (via `PlainTextTimersManager`)
 This format is more lightweight and slightly faster.
 
-- **Pros**: Simple and efficient.
+- **Pros**: Simple and efficient. Improved memory efficiency due to line-by-line file reading.
 - **Cons**: Cannot store additional data like `title` or `description`.
 - **Default File**: `.timers`
 - **Format**:

package/dist/cjs/Log.cjs

@@ -58,25 +58,4 @@ class Log {
     }
 }
 exports.Log = Log;
-/*
-let logger: Logger | null = null;
-let initPromise: Promise<void> | null = null;
-
-export async function ensureLogger() {
-    if (logger) return;
-    if (!initPromise) {
-        initPromise = (async () => {
-            try {
-                const logtape = await import("@logtape/logtape");
-                logger = logtape.getLogger(["eternal-timer"]);
-            } catch {
-                console.info(
-                    "Tip: Install the optional package '@logtape/logtape' to customize logging behavior.",
-                );
-            }
-        })();
-    }
-    await initPromise;
-}
-*/ 
 //# sourceMappingURL=Log.js.map

package/dist/cjs/{Log.js.map → Log.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"Log.js","sourceRoot":"","sources":["../../src/Log.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,MAAa,GAAG;IACP,MAAM,CAAC,MAAM,GAAkB,IAAI,CAAC;IACpC,MAAM,CAAC,WAAW,GAAyB,IAAI,CAAC;IAEjD,MAAM,CAAC,KAAK,CAAC,YAAY;QAC/B,IAAI,GAAG,CAAC,MAAM;YAAE,OAAO;QACvB,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;YACtB,GAAG,CAAC,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC7B,IAAI,CAAC;oBACJ,MAAM,OAAO,GAAG,wDAAa,kBAAkB,GAAC,CAAC;oBACjD,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;gBACnD,CAAC;gBAAC,MAAM,CAAC;oBACR,OAAO,CAAC,IAAI,CACX,qFAAqF,CACrF,CAAC;gBACH,CAAC;YACF,CAAC,CAAC,EAAE,CAAC;QACN,CAAC;QACD,MAAM,GAAG,CAAC,WAAW,CAAC;IACvB,CAAC;IAEM,MAAM,KAAK,cAAc;QAC/B,OAAO,GAAG,CAAC,MAAM,CAAC;IACnB,CAAC;;AAvBF,kBAwBC;AAED;;;;;;;;;;;;;;;;;;;;EAoBE"}
+{"version":3,"file":"Log.js","sourceRoot":"","sources":["../../src/Log.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,MAAa,GAAG;IACP,MAAM,CAAC,MAAM,GAAkB,IAAI,CAAC;IACpC,MAAM,CAAC,WAAW,GAAyB,IAAI,CAAC;IAEjD,MAAM,CAAC,KAAK,CAAC,YAAY;QAC/B,IAAI,GAAG,CAAC,MAAM;YAAE,OAAO;QACvB,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;YACtB,GAAG,CAAC,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC7B,IAAI,CAAC;oBACJ,MAAM,OAAO,GAAG,wDAAa,kBAAkB,GAAC,CAAC;oBACjD,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;gBACnD,CAAC;gBAAC,MAAM,CAAC;oBACR,OAAO,CAAC,IAAI,CACX,qFAAqF,CACrF,CAAC;gBACH,CAAC;YACF,CAAC,CAAC,EAAE,CAAC;QACN,CAAC;QACD,MAAM,GAAG,CAAC,WAAW,CAAC;IACvB,CAAC;IAEM,MAAM,KAAK,cAAc;QAC/B,OAAO,GAAG,CAAC,MAAM,CAAC;IACnB,CAAC;;AAvBF,kBAwBC"}

package/dist/cjs/TimersManager/JSONLTimersManager.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSONLTimersManager = void 0;
+const TimersManager_js_1 = require("./TimersManager.cjs");
+const JSONLTimersStore_js_1 = require("../TimersStore/JSONLTimersStore.cjs");
+/**
+ * JSONLTimersManager
+ * @description
+ * Manages timers stored in a  JSONL file.
+ * (This is a abstract class)
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
+ */
+class JSONLTimersManager extends TimersManager_js_1.TimersManager {
+    TimersStore = null;
+    getDefaultFilename() {
+        return ".timers.jsonl";
+    }
+    async createTimersStore() {
+        return new JSONLTimersStore_js_1.JSONLTimersStore(this.timerfiledir);
+    }
+}
+exports.JSONLTimersManager = JSONLTimersManager;
+//# sourceMappingURL=JSONLTimersManager.js.map

package/dist/cjs/TimersManager/JSONLTimersManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONLTimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/JSONLTimersManager.ts"],"names":[],"mappings":";;;AAAA,yDAAmD;AACnD,4EAAsE;AAGtE;;;;;;;;GAQG;AACH,MAAa,kBAAmB,SAAQ,gCAAsB;IAC1C,WAAW,GAA4B,IAAI,CAAC;IAE5C,kBAAkB;QACpC,OAAO,eAAe,CAAC;IACxB,CAAC;IAEkB,KAAK,CAAC,iBAAiB;QACzC,OAAO,IAAI,sCAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAChD,CAAC;CACD;AAVD,gDAUC"}

package/dist/cjs/TimersManager/JSONLTimersManager.d.ts

@@ -0,0 +1,18 @@
+import { TimersManager } from "./TimersManager.js";
+import { JSONLTimersStore } from "../TimersStore/JSONLTimersStore.js";
+import type { TimersStore } from "src/TimersStore/TimersStore.js";
+/**
+ * JSONLTimersManager
+ * @description
+ * Manages timers stored in a  JSONL file.
+ * (This is a abstract class)
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
+ */
+export declare class JSONLTimersManager extends TimersManager<"JSONL"> {
+    protected TimersStore: JSONLTimersStore | null;
+    protected getDefaultFilename(): string;
+    protected createTimersStore(): Promise<TimersStore<"JSONL">>;
+}
+//# sourceMappingURL=JSONLTimersManager.d.ts.map

package/dist/cjs/TimersManager/JSONLTimersManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONLTimersManager.d.ts","sourceRoot":"","sources":["../../../src/TimersManager/JSONLTimersManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAElE;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,aAAa,CAAC,OAAO,CAAC;IAC7D,UAAmB,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAQ;cAE5C,kBAAkB,IAAI,MAAM;cAItB,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;CAG3E"}

package/dist/cjs/TimersManager/PlainTextTimersManager.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlainTextTimersManager = void 0;
+const TimersManager_js_1 = require("./TimersManager.cjs");
+const PlainTextTimersStore_js_1 = require("../TimersStore/PlainTextTimersStore.cjs");
+/**
+ * PlainTextTimersManager
+ * @description
+ * Manages timers stored in a PlainText file.
+ * (This is a abstract class)
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
+ */
+class PlainTextTimersManager extends TimersManager_js_1.TimersManager {
+    TimersStore = null;
+    getDefaultFilename() {
+        return ".timers";
+    }
+    async createTimersStore() {
+        return new PlainTextTimersStore_js_1.PlainTextTimersStore(this.timerfiledir);
+    }
+}
+exports.PlainTextTimersManager = PlainTextTimersManager;
+//# sourceMappingURL=PlainTextTimersManager.js.map

package/dist/cjs/TimersManager/PlainTextTimersManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlainTextTimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/PlainTextTimersManager.ts"],"names":[],"mappings":";;;AAAA,yDAAmD;AACnD,oFAA8E;AAG9E;;;;;;;;GAQG;AACH,MAAa,sBAAuB,SAAQ,gCAA0B;IAClD,WAAW,GAAgC,IAAI,CAAC;IAEhD,kBAAkB;QACpC,OAAO,SAAS,CAAC;IAClB,CAAC;IAES,KAAK,CAAC,iBAAiB;QAChC,OAAO,IAAI,8CAAoB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC;CACD;AAVD,wDAUC"}

package/dist/cjs/TimersManager/PlainTextTimersManager.d.ts

@@ -0,0 +1,18 @@
+import { TimersManager } from "./TimersManager.js";
+import { PlainTextTimersStore } from "../TimersStore/PlainTextTimersStore.js";
+import type { TimersStore } from "src/TimersStore/TimersStore.js";
+/**
+ * PlainTextTimersManager
+ * @description
+ * Manages timers stored in a PlainText file.
+ * (This is a abstract class)
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
+ */
+export declare class PlainTextTimersManager extends TimersManager<"PlainText"> {
+    protected TimersStore: PlainTextTimersStore | null;
+    protected getDefaultFilename(): string;
+    protected createTimersStore(): Promise<TimersStore<"PlainText">>;
+}
+//# sourceMappingURL=PlainTextTimersManager.d.ts.map

package/dist/cjs/TimersManager/PlainTextTimersManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlainTextTimersManager.d.ts","sourceRoot":"","sources":["../../../src/TimersManager/PlainTextTimersManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAElE;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,aAAa,CAAC,WAAW,CAAC;IACrE,UAAmB,WAAW,EAAE,oBAAoB,GAAG,IAAI,CAAQ;cAEhD,kBAAkB,IAAI,MAAM;cAI/B,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;CAGtE"}

package/dist/cjs/TimersManager/TimersManager.cjs

@@ -0,0 +1,211 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimersManager = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const uuid_1 = require("uuid");
+const searchRoot_js_1 = __importDefault(require("../searchRoot.cjs"));
+const Log_js_1 = require("../Log.cjs");
+/**
+ * TimersManager
+ * @description
+ * Manages timers stored in a file.
+ * (This is a abstract class)
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
+ */
+class TimersManager {
+    timerfiledir;
+    checkLock = false;
+    TimersStore = null;
+    queue = Promise.resolve();
+    runExclusive(fn) {
+        const p = this.queue.then(fn);
+        this.queue = p.then(() => { }, () => { });
+        return p;
+    }
+    /**
+      * constructor
+      * @description Initializes the TimersManager instance. If the timer file does not exist, an empty file is created.
+      * @param options (TimersManagerOptions | string, optional) Configuration object or timer file path. If a string is provided, it is treated as the timer file path. If an object is provided, `timerfiledir` can be specified.
+      * @throws If file access or creation fails
+      * @example
+      * const manager = new TimersManager(); // Uses default timer file path
+      * const manager = new TimersManager("/path/to/timers.txt"); // Uses specified timer file path
+      */
+    constructor(options) {
+        const rootDir = (0, searchRoot_js_1.default)();
+        this.timerfiledir = path_1.default.resolve(rootDir, options ?? this.getDefaultFilename());
+        if (!this.timerfiledir.startsWith(rootDir)) {
+            throw new Error(`Timer file path must be within the project directory`);
+        }
+        try {
+            fs_1.default.accessSync(this.timerfiledir);
+        }
+        catch {
+            fs_1.default.writeFileSync(this.timerfiledir, "");
+        }
+    }
+    /**
+     * 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(options) {
+        return this.runExclusive(async () => {
+            this.TimersStore ??= await this.createTimersStore();
+            let length = typeof options === "object" ? options.length : options;
+            if (length < 0)
+                throw new Error(`Invalid length: ${length}`);
+            length = Math.trunc(length);
+            const id = (0, uuid_1.v4)();
+            const now = Date.now();
+            const stopTime = now + Math.max(1, length);
+            const newTimerData = {
+                id,
+                start: now,
+                stop: stopTime,
+                ...(typeof options === "object" && options.title !== undefined && { title: options.title }),
+                ...(typeof options === "object" && options.description !== undefined && { description: options.description }),
+            };
+            await this.TimersStore.appendTimer(newTimerData);
+            return id;
+        });
+    }
+    /**
+     * 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) {
+        return this.runExclusive(async () => {
+            this.TimersStore ??= await this.createTimersStore();
+            const timers = await this.TimersStore.loadTimers();
+            const index = timers.findIndex(t => t.id === id);
+            if (index === -1) {
+                throw new Error(`Timer with id ${id} not found`);
+            }
+            timers.splice(index, 1);
+            await this.TimersStore.saveTimers(timers);
+            return;
+        });
+    }
+    /**
+     * checkTimers
+     * @description Starts monitoring timers at the specified interval.
+     * When a timer expires, the provided `callback` is invoked with the timer.
+     * The callback is awaited before the next processing cycle continues.
+     * @param callback Function invoked when an expired timer is detected (called asynchronously)
+     * @param interval (number, optional): Check interval in milliseconds (default: 200ms)
+     * @throws If file operation fails
+     * @returns (Promise<NodeJS.Timeout>) intervalId interval id of checkTimers
+     * @example
+     * const interval = await manager.checkTimers((timer) => {
+     *     console.log(`A timer was stopped: ${timer.id}`);
+     * });
+     */
+    async checkTimers(callback, interval = 200) {
+        this.TimersStore ??= await this.createTimersStore();
+        const loop = async () => {
+            if (this.checkLock) {
+                return;
+            }
+            this.checkLock = true;
+            try {
+                const expiredTimers = await this.runExclusive(async () => {
+                    const allTimers = await this.TimersStore.loadTimers();
+                    const now = Date.now();
+                    const expired = [];
+                    const active = [];
+                    for (const timer of allTimers) {
+                        if (timer.stop <= now) {
+                            expired.push(timer);
+                        }
+                        else {
+                            active.push(timer);
+                        }
+                    }
+                    if (expired.length > 0) {
+                        await this.TimersStore.saveTimers(active);
+                    }
+                    return expired;
+                });
+                for (const timerData of expiredTimers) {
+                    try {
+                        await callback(timerData);
+                    }
+                    catch (e) {
+                        await Log_js_1.Log.ensureLogger();
+                        Log_js_1.Log.loggerInstance?.error(`Error in callback of checkTimers: ${e}`);
+                    }
+                }
+            }
+            catch (e) {
+                await Log_js_1.Log.ensureLogger();
+                Log_js_1.Log.loggerInstance?.error(`Error when checking timer: ${e}`);
+            }
+            finally {
+                this.checkLock = false;
+            }
+        };
+        return setInterval(loop, interval);
+    }
+    /**
+     * 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() {
+        return this.runExclusive(async () => {
+            this.TimersStore ??= await this.createTimersStore();
+            const timersData = await this.TimersStore.loadTimers();
+            return timersData;
+        });
+    }
+    /**
+      * adjustRemainingTime
+      * @description Adjusts the remaining time of a timer.
+      * @param id ID of the timer to modify
+      * @param delay Delay in milliseconds to add/subtract from the remaining time
+      * @returns Promise resolving when the operation is complete
+      * @throws If file operation fails
+      */
+    async adjustRemainingTime(id, delay) {
+        return this.runExclusive(async () => {
+            this.TimersStore ??= await this.createTimersStore();
+            const timers = await this.TimersStore.loadTimers();
+            const index = timers.findIndex(t => t.id === id);
+            if (index === -1) {
+                throw new Error(`Timer with id ${id} not found`);
+            }
+            const now = Date.now();
+            const timer = timers[index];
+            const remaining = Math.max(0, timer.stop - now);
+            const newRemaining = Math.max(0, remaining + delay);
+            timer.stop = now + newRemaining;
+            timers[index] = timer;
+            await this.TimersStore.saveTimers(timers);
+            return;
+        });
+    }
+}
+exports.TimersManager = TimersManager;
+//# sourceMappingURL=TimersManager.js.map

package/dist/cjs/TimersManager/TimersManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/TimersManager.ts"],"names":[],"mappings":"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"}

package/dist/cjs/TimersManager/TimersManager.d.ts

@@ -0,0 +1,87 @@
+import type { CreateTimerOptions, StorageType, Timer } from "../types.js";
+import { TimersStore } from "../TimersStore/TimersStore.js";
+/**
+ * TimersManager
+ * @description
+ * Manages timers stored in a file.
+ * (This is a abstract class)
+ *
+ * - Timers are persisted in a file
+ * - Expired timers are detected by polling
+ */
+export declare abstract class TimersManager<T extends StorageType> {
+    protected readonly timerfiledir: string;
+    private checkLock;
+    protected TimersStore: TimersStore<T> | null;
+    private queue;
+    private runExclusive;
+    protected abstract getDefaultFilename(): string;
+    protected abstract createTimersStore(): Promise<TimersStore<T>>;
+    /**
+      * constructor
+      * @description Initializes the TimersManager instance. If the timer file does not exist, an empty file is created.
+      * @param options (TimersManagerOptions | string, optional) Configuration object or timer file path. If a string is provided, it is treated as the timer file path. If an object is provided, `timerfiledir` can be specified.
+      * @throws If file access or creation fails
+      * @example
+      * const manager = new TimersManager(); // Uses default timer file path
+      * const manager = new TimersManager("/path/to/timers.txt"); // Uses specified timer file path
+      */
+    constructor(options?: string);
+    /**
+     * 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(options: CreateTimerOptions<T>): 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>;
+    /**
+     * checkTimers
+     * @description Starts monitoring timers at the specified interval.
+     * When a timer expires, the provided `callback` is invoked with the timer.
+     * The callback is awaited before the next processing cycle continues.
+     * @param callback Function invoked when an expired timer is detected (called asynchronously)
+     * @param interval (number, optional): Check interval in milliseconds (default: 200ms)
+     * @throws If file operation fails
+     * @returns (Promise<NodeJS.Timeout>) intervalId interval id of checkTimers
+     * @example
+     * const interval = await manager.checkTimers((timer) => {
+     *     console.log(`A timer was stopped: ${timer.id}`);
+     * });
+     */
+    checkTimers(callback: (timer: Timer<T>) => void | Promise<void>, interval?: number): Promise<NodeJS.Timeout>;
+    /**
+     * 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<T>[]>;
+    /**
+      * adjustRemainingTime
+      * @description Adjusts the remaining time of a timer.
+      * @param id ID of the timer to modify
+      * @param delay Delay in milliseconds to add/subtract from the remaining time
+      * @returns Promise resolving when the operation is complete
+      * @throws If file operation fails
+      */
+    adjustRemainingTime(id: string, delay: number): Promise<void>;
+}
+//# sourceMappingURL=TimersManager.d.ts.map