eternal-timer 3.0.0 → 4.0.0

package/README.md

@@ -8,7 +8,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 called when timers expire.
+- **Monitor Timers (event-driven)**: Start monitoring expired timers and react to events like `expired`, `started`, `stopped`, and `updated` through an event system.
 - **Persistence**: Save timer data to a file that persists across process restarts
 - **Choice of Format**: Choose between JSON Lines for rich data or plain text for lightweight storage.
 
@@ -37,8 +37,11 @@ async function main() {
     const timerId = await manager.createTimer({length: 5000, extra: { title: 'My Timer', description: 'This is a test timer.' }});
     console.log('Timer created:', timerId);
 
-    // Monitor timers (executes when timer expires)
-    const interval = await manager.checkTimers(async (timer) => {
+    // Start monitoring for expired timers
+    const interval = await manager.checkStart();
+
+    // Listen for 'expired' events
+    manager.on('expired', (timer) => {
         console.log('Timer expired:', timer.id, timer.extra?.title);
     });
 
@@ -71,8 +74,11 @@ async function main() {
     const timerId = await manager.createTimer(5000);
     console.log('Timer created:', timerId);
 
-    // Monitor timers
-    const interval = await manager.checkTimers(async (timer) => {
+    // Start monitoring for expired timers
+    const interval = await manager.checkStart();
+
+    // Listen for 'expired' events
+    manager.on('expired', (timer) => {
         console.log('Timer expired:', timer.id);
     });
 
@@ -83,7 +89,7 @@ async function main() {
     // Stop monitoring after a while
     setTimeout(() => {
         clearInterval(interval);
-        console.log('Stopped monitoring timers.');
+        console.log('Stopped monitoring for timers.');
     }, 10000);
 }
 
@@ -160,26 +166,55 @@ Creates a manager for timers stored in **plain-text** format.
 
 ---
 
-### `createTimer(options: CreateTimerOptions<T>): Promise<string>`
+### `createTimer(options: CreateTimerOptions<T, Extra>): Promise<string>`
 
 Creates a new timer and saves it to the file.
 
 #### Parameters
 
-- **`options`**
+- **`options`** (`CreateTimerOptions<T, Extra>`)
+  - When using `PlainTextTimersManager` (type `PlainText`):
+    - `number` — The timer's duration in milliseconds.
+  - When using `JSONLTimersManager` (type `JSONL`):
+    - `{ length: number; extra?: Extra }`
+      - `length` (number): The timer's duration in milliseconds.
+      - `extra` (optional, `Extra` object): An object containing arbitrary user-defined metadata for the timer.
 
-  When using `"PlainText"` storage:
-  - `number` — Timer duration in milliseconds.
+**Returns** A `Promise<string>` that resolves to the timer's unique ID (UUID).
 
-  When using `"JSONL"` storage:
-  - `{ length: number; extra?: Extra }`
-    - `length` (number): Timer duration in milliseconds.
-    - `extra` (optional, Extra): An object containing arbitrary user-defined metadata.
+**Throws** An error if: `length` is invalid (e.g., negative) or a file operation fails.
 
-**Returns** A `Promise<string>` that resolves to the timer's unique ID (UUID).
+**Examples:**
+
+```javascript
+// For PlainTextTimersManager with a custom Extra type
+import { PlainTextTimersManager } from 'eternal-timer';
+
+// For PlainTextTimersManager
+const manager = new PlainTextTimersManager();
+const newTimerId = await manager.createTimer(5000); // Create a 5-second timer
+console.log('Created PlainText timer with ID:', newTimerId);
+```
+
+```typescript
+// For JSONLTimersManager with a custom Extra type
+import { JSONLTimersManager } from 'eternal-timer';
 
-**Throws** An error if: `length` is invalid (e.g., negative) or a file operation fails
+interface MyCustomExtra {
+  purpose: string;
+  userId: string;
+}
 
+const jsonlManager = new JSONLTimersManager<MyCustomExtra>();
+const jsonlTimerId = await jsonlManager.createTimer({
+  length: 10000, // 10 seconds
+  extra: {
+    purpose: "Session Timeout",
+    userId: "user-123"
+  }
+});
+console.log('Created JSONL timer with ID:', jsonlTimerId);
+```
 ### `removeTimer(id: string): Promise<void>`
 
 Removes a timer by its ID.
@@ -190,22 +225,61 @@ Removes a timer by its ID.
 
 **Throws:** An error if the timer with the specified ID is not found or if a file operation fails.
 
-### `checkTimers(callback: (timer: Timer) => void | Promise<void>, interval?: number): Promise<NodeJS.Timeout>`
+### `checkStart(interval?: number): Promise<NodeJS.Timeout>`
+
+Starts the timer checking loop. This method should be called once after creating an instance of a `TimersManager` to begin detecting expired timers. Events like `expired`, `errored`, `started`, `stopped`, and `updated` are emitted, which can be listened to using the `on` method.
+
+- **`interval`** (optional, number): Polling interval in milliseconds (default: 200ms)
 
-Starts monitoring timers at the specified interval and invokes the provided
-`callback` when a timer expires.
+**Returns:** The interval ID which can be used to stop the loop with `clearInterval()`.
 
-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`.
+**Throws:** If file operation fails during checking.
 
-- **callback**: An async function invoked with the expired `timer`.
-- **interval** *(optional, number)*: Interval in milliseconds for checking timers.
-  Defaults to `200`.
+### `on<K extends keyof TimerEvents<T, Extra>>(event: K, listener: (payload: TimerEvents<T, Extra>[K]) => void | Promise<void>): void`
 
-**Returns:** A `NodeJS.Timeout` that can be passed to `clearInterval()` to stop monitoring.
+Registers an event listener for a specific timer event.
 
-**Throws:** An error if a timer storage operation fails.
+- **`event`**: The name of the event to listen for (e.g., `'expired'`, `'started'`, `'stopped'`, `'updated'`, `'errored'`).
+- **`listener`**: The callback function to execute when the event is emitted. It receives the event payload as an argument.
+
+**Returns:** `void`
+
+**Example:**
+```javascript
+manager.on('expired', (timer) => {
+    console.log(`Timer ${timer.id} expired!`);
+});
+
+manager.on('errored', (error) => {
+    console.error('Timer event error:', error);
+});
+```
+
+### `once<K extends keyof TimerEvents<T, Extra>>(event: K, listener: (payload: TimerEvents<T, Extra>[K]) => void | Promise<void>): void`
+
+Registers a one-time event listener for a specific timer event. The listener will be invoked only once for the specified event, after which it will be automatically removed.
+
+- **`event`**: The name of the event to listen for.
+- **`listener`**: The callback function to execute when the event is emitted.
+
+**Returns:** `void`
+
+### `off<K extends keyof TimerEvents<T, Extra>>(event: K, listener: (payload: TimerEvents<T, Extra>[K]) => void | Promise<void>): void`
+
+Removes a specific event listener for a given event.
+
+- **`event`**: The name of the event from which to remove the listener.
+- **`listener`**: The listener function to remove.
+
+**Returns:** `void`
+
+### `offAll<K extends keyof TimerEvents<T, Extra>>(event: K): void`
+
+Removes all event listeners for a specific event.
+
+- **`event`**: The name of the event for which to remove all listeners.
+
+**Returns:** `void`
 
 ### `showTimers(): Promise<Timer[]>`
 
@@ -226,6 +300,13 @@ Adjusts the remaining time of a specified timer. This can be used to extend or s
 
 **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.
 
+**Example:**
+```javascript
+// Assuming 'timerId' is the ID of an existing timer
+await manager.adjustRemainingTime(timerId, 60000); // Add 1 minute to the timer
+await manager.adjustRemainingTime(timerId, -30000); // Subtract 30 seconds from the timer
+```
+
 ## Type Definition
 
 The `StorageType` has the following structure:
@@ -236,16 +317,45 @@ type StorageType = "JSONL" | "PlainText"
 The `Timer` object has the following structure:
 
 ```typescript
-type Timer<T extends StorageType, Extra extends object> = {
-  id: string;
-  start: number;
-  stop: number;
-} & (T extends "JSONL"
-  ? { extra: Extra }
-  : {});
+type Timer<T extends StorageType, Extra extends object> =
+    T extends "JSONL"
+        ? {
+              id: string;
+              start: number;
+              stop: number;
+              extra: Extra
+          }
+        : {
+              id: string;
+              start: number;
+              stop: number;
+          };
+```
+`Extra` is a generic type parameter that represents an object containing arbitrary user-defined metadata for JSONL timers. By default, it's `object`. For example, it can be `{ title?: string; description?: string }`.
+
+The `CreateTimerOptions` type is used when creating new timers:
+```typescript
+type CreateTimerOptions<T extends StorageType, Extra extends object> = T extends "JSONL"
+    ? {
+          length: number;
+          extra: Extra
+      }
+    : T extends "PlainText"
+      ? number
+      : never;
 ```
-`Extra` is a generic type parameter that represents an object containing arbitrary user-defined metadata for JSONL timers. For example, it can be `{ title?: string; description?: string }`.
 
+The `TimerEvents` type defines the events emitted by `TimersManager`:
+```typescript
+type TimerEvents<T extends StorageType, Extra extends object> = {
+  expired: Timer<T, Extra>
+  errored: Error
+  interval: void
+  started: Timer<T, Extra>
+  stopped: Timer<T, Extra>
+  updated: { old: Timer<T, Extra>, new: Timer<T, Extra> }
+}
+```
 ## Scripts
 
 - `npm run build`: Compile TypeScript

package/dist/cjs/EventEmitter.d.ts

@@ -0,0 +1,12 @@
+import type { StorageType, TimerEvents } from "./types.js";
+export declare class EventEmitter<T extends StorageType, Extra extends object> {
+    protected listeners: {
+        [K in keyof TimerEvents<T, Extra>]?: ((payload: TimerEvents<T, Extra>[K]) => void | Promise<void>)[];
+    };
+    on<K extends keyof TimerEvents<T, Extra>>(event: K, listener: (payload: TimerEvents<T, Extra>[K]) => void | Promise<void>): void;
+    once<K extends keyof TimerEvents<T, Extra>>(event: K, listener: (payload: TimerEvents<T, Extra>[K]) => void | Promise<void>): void;
+    off<K extends keyof TimerEvents<T, Extra>>(event: K, listener: (payload: TimerEvents<T, Extra>[K]) => void | Promise<void>): void;
+    offAll<K extends keyof TimerEvents<T, Extra>>(event: K): void;
+    protected emit<K extends keyof TimerEvents<T, Extra>>(event: K, payload: TimerEvents<T, Extra>[K]): Promise<void>;
+}
+//# sourceMappingURL=EventEmitter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EventEmitter.d.ts","sourceRoot":"","sources":["../../src/EventEmitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3D,qBAAa,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,SAAS,MAAM;IACpE,SAAS,CAAC,SAAS,EAAE;SACb,CAAC,IAAI,MAAM,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAClC,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAChC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE;KAC/B,CAAM;IAEH,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,EAC9C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACnE,IAAI;IAOA,IAAI,CAAC,CAAC,SAAS,MAAM,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,EAChD,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACnE,IAAI;IAQA,GAAG,CAAC,CAAC,SAAS,MAAM,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,EAC/C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACnE,IAAI;IAUA,MAAM,CAAC,CAAC,SAAS,MAAM,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,EAClD,KAAK,EAAE,CAAC,GACN,IAAI;cAIS,IAAI,CAAC,CAAC,SAAS,MAAM,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,EACzD,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC;CAoBhB"}

package/dist/cjs/EventEmitter.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventEmitter = void 0;
+class EventEmitter {
+    listeners = {};
+    on(event, listener) {
+        if (!this.listeners[event]) {
+            this.listeners[event] = [];
+        }
+        this.listeners[event].push(listener);
+    }
+    once(event, listener) {
+        const wrapper = (payload) => {
+            this.off(event, wrapper);
+            return listener(payload);
+        };
+        this.on(event, wrapper);
+    }
+    off(event, listener) {
+        const listeners = this.listeners[event];
+        if (!listeners)
+            return;
+        const index = listeners.indexOf(listener);
+        if (index !== -1) {
+            listeners.splice(index, 1);
+        }
+    }
+    offAll(event) {
+        this.listeners[event] = [];
+    }
+    async emit(event, payload) {
+        const listeners = this.listeners[event];
+        if (!listeners?.length)
+            return;
+        const errors = [];
+        await Promise.all(listeners.map(async (l) => {
+            try {
+                await l(payload);
+            }
+            catch (e) {
+                errors.push(e);
+            }
+        }));
+        if (errors.length > 0) {
+            throw new AggregateError(errors, `Errors in event "${event}"`);
+        }
+    }
+}
+exports.EventEmitter = EventEmitter;
+//# sourceMappingURL=EventEmitter.js.map

package/dist/cjs/EventEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventEmitter.js","sourceRoot":"","sources":["../../src/EventEmitter.ts"],"names":[],"mappings":";;;AAEA,MAAa,YAAY;IACd,SAAS,GAIZ,EAAE,CAAC;IAEH,EAAE,CACR,KAAQ,EACR,QAAqE;QAErE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QAC5B,CAAC;QACK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAEM,IAAI,CACV,KAAQ,EACR,QAAqE;QAErE,MAAM,OAAO,GAAG,CAAC,OAAiC,EAAE,EAAE;YACrD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACzB,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC,CAAC;QACF,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IAEM,GAAG,CACT,KAAQ,EACR,QAAqE;QAErE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5B,CAAC;IACF,CAAC;IAEM,MAAM,CACZ,KAAQ;QAER,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IAC5B,CAAC;IAES,KAAK,CAAC,IAAI,CACnB,KAAQ,EACR,OAAiC;QAEjC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS,EAAE,MAAM;YAAE,OAAO;QAE/B,MAAM,MAAM,GAAc,EAAE,CAAC;QAE7B,MAAM,OAAO,CAAC,GAAG,CAChB,SAAS,CAAC,GAAG,CAAC,KAAK,EAAC,CAAC,EAAC,EAAE;YACvB,IAAI,CAAC;gBACJ,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACZ,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,CAAC;QACF,CAAC,CAAC,CACF,CAAC;QAEF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,oBAAoB,KAAK,GAAG,CAAC,CAAC;QAChE,CAAC;IACF,CAAC;CACD;AAtED,oCAsEC"}

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

@@ -1 +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;AAEtE;;;;;;;;GAQG;AACH,qBAAa,kBAAkB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC;IACnG,UAAmB,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAQ;cAEnD,kBAAkB,IAAI,MAAM;cAItB,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAI9E,UAAmB,IAAI,EAAE,OAAO,CAAoB;IAEpD;;;;;;;;;;;OAWG;IACU,WAAW,CACvB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,KAAK,GACb,OAAO,CAAC,IAAI,CAAC;CAkBhB"}
+{"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;AAEtE;;;;;;;;GAQG;AACH,qBAAa,kBAAkB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC;IACnG,UAAmB,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAQ;cAEnD,kBAAkB,IAAI,MAAM;cAItB,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAI9E,UAAmB,IAAI,EAAE,OAAO,CAAoB;IAEpD;;;;;;;;;;;OAWG;IACU,WAAW,CACvB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,KAAK,GACb,OAAO,CAAC,IAAI,CAAC;CAqBhB"}

package/dist/cjs/TimersManager/JSONLTimersManager.js

@@ -39,11 +39,13 @@ class JSONLTimersManager extends TimersManager_js_1.TimersManager {
             try {
                 const timers = await this.TimersStore.loadTimers();
                 const index = timers?.findIndex(t => t.id === id);
-                if (index === -1) {
+                if (index === -1 || timers[index] === undefined) {
                     throw new Error(`Timer with id ${id} not found`);
                 }
+                const old = { ...timers[index] };
                 timers[index].extra = newExtra;
                 await this.TimersStore.saveTimers(timers);
+                await this.emit("updated", { old, new: timers[index] });
             }
             catch (e) {
                 throw new Error(`Error when changing extra`, { cause: e });

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

@@ -1 +1 @@
-{"version":3,"file":"JSONLTimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/JSONLTimersManager.ts"],"names":[],"mappings":";;;AAAA,yDAAmD;AACnD,4EAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAa,kBAAkD,SAAQ,gCAA6B;IAChF,WAAW,GAAmC,IAAI,CAAC;IAEnD,kBAAkB;QACpC,OAAO,eAAe,CAAC;IACxB,CAAC;IAEkB,KAAK,CAAC,iBAAiB;QACzC,OAAO,IAAI,sCAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAChD,CAAC;IAEkB,IAAI,GAAY,OAAgB,CAAC;IAEpD;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,WAAW,CACvB,EAAU,EACV,QAAe;QAEf,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YACnC,IAAI,CAAC,WAAW,KAAK,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACpD,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;gBAEnD,MAAM,KAAK,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;gBAClD,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;gBAClD,CAAC;gBAED,MAAM,CAAC,KAAK,CAAE,CAAC,KAAK,GAAG,QAAQ,CAAC;gBAChC,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5D,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC;CACD;AA9CD,gDA8CC"}
+{"version":3,"file":"JSONLTimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/JSONLTimersManager.ts"],"names":[],"mappings":";;;AAAA,yDAAmD;AACnD,4EAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAa,kBAAkD,SAAQ,gCAA6B;IAChF,WAAW,GAAmC,IAAI,CAAC;IAEnD,kBAAkB;QACpC,OAAO,eAAe,CAAC;IACxB,CAAC;IAEkB,KAAK,CAAC,iBAAiB;QACzC,OAAO,IAAI,sCAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAChD,CAAC;IAEkB,IAAI,GAAY,OAAgB,CAAC;IAEpD;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,WAAW,CACvB,EAAU,EACV,QAAe;QAEf,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YACnC,IAAI,CAAC,WAAW,KAAK,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACpD,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;gBAEnD,MAAM,KAAK,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;gBAClD,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,EAAE,CAAC;oBACjD,MAAM,IAAI,KAAK,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;gBAClD,CAAC;gBAED,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAEjC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC;gBAC/B,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;gBAC1C,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACzD,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5D,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC;CACD;AAjDD,gDAiDC"}

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

@@ -1,5 +1,6 @@
 import type { CreateTimerOptions, StorageType, Timer } from "../types.js";
 import { TimersStore } from "../TimersStore/TimersStore.js";
+import { EventEmitter } from "../EventEmitter.js";
 /**
  * TimersManager
  * @description
@@ -9,9 +10,9 @@ import { TimersStore } from "../TimersStore/TimersStore.js";
  * - Timers are persisted in a file
  * - Expired timers are detected by polling
  */
-export declare abstract class TimersManager<T extends StorageType, Extra extends object> {
+export declare abstract class TimersManager<T extends StorageType, Extra extends object> extends EventEmitter<T, Extra> {
     protected readonly timerfiledir: string;
-    private checkLock;
+    protected checkLock: boolean;
     protected TimersStore: TimersStore<T, Extra> | null;
     private queue;
     protected runExclusive<T>(fn: () => Promise<T>): Promise<T>;
@@ -21,23 +22,27 @@ export declare abstract class TimersManager<T extends StorageType, Extra extends
     /**
       * constructor
       * @description Initializes the TimersManager instance. If the timer file does not exist, an empty file is created.
-      * @param {string} [options] (string, optional) Configuration timer file path and it is treated as the timer file path.
+      * @param {string} [timerfile] (string, optional) Configuration timer file path and it is treated as the timer file path.
       * @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);
+    constructor(timerfile?: string);
     /**
      * createTimer
      * @description Creates a new timer.
-     * @param {{length: number, extra: Extra} | number} options Timer duration in milliseconds and extra field(only JSONL)
+     * @param {CreateTimerOptions<T, Extra>} options Timer duration in milliseconds for PlainText or an object with length and extra for JSONL.
      * @returns Promise that resolves to the timer ID (UUID)
-     * @throws If length is invalid(e.g. length < 0) or file operation fails
+     * @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
+     * // For PlainTextTimersManager
+     * const manager = new PlainTextTimersManager();
+     * const newTimerId = await manager.createTimer(5000); // Create a 5-second timer
+     *
+     * // For JSONLTimersManager
+     * const jsonlManager = new JSONLTimersManager<{ title: string }>();
+     * const jsonlTimerId = await jsonlManager.createTimer({ length: 10000, extra: { title: "My JSONL Timer" } }); // Create a 10-second timer with extra data
      */
     createTimer(options: CreateTimerOptions<T, Extra>): Promise<string>;
     /**
@@ -51,29 +56,25 @@ export declare abstract class TimersManager<T extends StorageType, Extra extends
      */
     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 {(timer: Timer<T, Extra>) => void | Promise<void>} callback Function invoked when an expired timer is detected (called asynchronously)
-     * @param {number} [interval=200] (number, optional): Check interval in milliseconds (default: 200ms)
-     * @throws If file operation fails
-     * @returns {Promise<NodeJS.Timeout>} intervalId interval id of checkTimers
+     * checkStart
+     * @description Starts the timer checking loop. This method should be called once after creating an instance of TimersManager to detect expired timers.
+     * @param {number} [interval=200] Polling interval in milliseconds (default: 200ms)
+     * @returns The interval ID which can be used to stop the loop with clearInterval
+     * @throws If file operation fails during checking
      * @example
-     * const interval = await manager.checkTimers((timer) => {
-     *     console.log(`A timer was stopped: ${timer.id}`);
-     * });
+     * const manager = new TimersManager();
+     * manager.checkStart(1000); // Check for expired timers every 1 second
      */
-    checkTimers(callback: (timer: Timer<T, Extra>) => void | Promise<void>, interval?: number): Promise<NodeJS.Timeout>;
+    checkStart(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
+        * @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, Extra>[]>;
     /**
       * adjustRemainingTime

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

@@ -1 +1 @@
-{"version":3,"file":"TimersManager.d.ts","sourceRoot":"","sources":["../../../src/TimersManager/TimersManager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAG5D;;;;;;;;GAQG;AACH,8BAAsB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,SAAS,MAAM;IAC9E,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IACxC,OAAO,CAAC,SAAS,CAAkB;IAEnC,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,IAAI,CAAQ;IAE3D,OAAO,CAAC,KAAK,CAAoC;IACjD,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAM9C,SAAS,CAAC,QAAQ,CAAC,kBAAkB,IAAI,MAAM;IAC/C,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACtE,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAE3B;;;;;;;;QAQO;gBAEN,OAAO,CAAC,EAAE,MAAM;IAcjB;;;;;;;;;;OAUM;IACO,WAAW,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BhF;;;;;;;;OAQM;IACO,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnD;;;;;;;;;;;;;OAaM;IACO,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;IAuDrI;;;;;;;;OAQM;IACO,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;IAQrD;;;;;;;QAOO;IACM,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB1E"}
+{"version":3,"file":"TimersManager.d.ts","sourceRoot":"","sources":["../../../src/TimersManager/TimersManager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;GAQG;AACH,8BAAsB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,SAAS,MAAM,CAAE,SAAQ,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC;IAC9G,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IACxC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAS;IAErC,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,IAAI,CAAQ;IAE3D,OAAO,CAAC,KAAK,CAAoC;IACjD,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAM9C,SAAS,CAAC,QAAQ,CAAC,kBAAkB,IAAI,MAAM;IAC/C,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACtE,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAE3B;;;;;;;;QAQO;gBAEN,SAAS,CAAC,EAAE,MAAM;IAenB;;;;;;;;;;;;;;OAcM;IACO,WAAW,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAgChF;;;;;;;;OAQM;IACO,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnD;;;;;;;;;OASG;IACU,UAAU,CACtB,QAAQ,GAAE,MAAY,GACpB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;IAqD1B;;;;;;;;UAQG;IACU,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;IAQrD;;;;;;;QAOO;IACM,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAwB1E"}