eternal-timer 4.3.1 → 5.0.1

package/README.md

@@ -31,14 +31,14 @@ import { JSONLTimersManager } from 'eternal-timer';
 
 async function main() {
     // By default, timers are stored in '.timers.jsonl' in the project root.
-    const manager = new JSONLTimersManager();
+    const manager = await JSONLTimersManager.create();
 
     // Create a timer (5 seconds) with a title and description
     const timerId = await manager.createTimer({length: 5000, extra: { title: 'My Timer', description: 'This is a test timer.' }});
     console.log('Timer created:', timerId);
 
     // Start monitoring for expired timers
-    const interval = await manager.checkStart();
+   await manager.checkStart();
 
     // Listen for 'expired' events
     manager.on('expired', (timer) => {
@@ -50,8 +50,8 @@ async function main() {
     console.log('Active timers:', timers);
 
     // To stop monitoring, for example after 10 seconds
-    setTimeout(() => {
-        clearInterval(interval);
+    setTimeout(async () => {
+        await manager.checkStop();
         console.log('Stopped monitoring timers.');
     }, 10000);
 }
@@ -68,14 +68,14 @@ import { PlainTextTimersManager } from 'eternal-timer';
 
 async function main() {
     // By default, timers are stored in '.timers' in the project root.
-    const manager = new PlainTextTimersManager();
+    const manager = await PlainTextTimersManager.create();
 
     // Create a timer (5 seconds)
     const timerId = await manager.createTimer(5000);
     console.log('Timer created:', timerId);
 
     // Start monitoring for expired timers
-    const interval = await manager.checkStart();
+    await manager.checkStart();
 
     // Listen for 'expired' events
     manager.on('expired', (timer) => {
@@ -87,8 +87,8 @@ async function main() {
     console.log('Active timers:', timers);
     
     // Stop monitoring after a while
-    setTimeout(() => {
-        clearInterval(interval);
+    setTimeout(async () => {
+        await manager.checkStop();
         console.log('Stopped monitoring for timers.');
     }, 10000);
 }
@@ -100,10 +100,13 @@ main();
 
 ### `JSONLTimersManager`
 
-#### `constructor(timerfiledir?: string)`
-Creates a manager for timers stored in **JSON Lines** format.
+#### `static create<Extra extends object = object>(timerfile?: string): Promise<JSONLTimersManager<Extra>>`
+Creates an instance of `JSONLTimersManager`.
 
-- **`timerfiledir`** (optional, string): Path to the timer file. Defaults to `.timers.jsonl` in the project root.
+- **`timerfile`** (optional, string): Path to the timer file. Defaults to `.timers.jsonl` in the project root.
+
+> [!NOTE]
+> The constructor is `protected`. Please use this `create` method to instantiate the manager.
 
 #### `changeExtra(id: string, newExtra: Extra): Promise<void>`
 Changes the `extra` data of an existing timer.
@@ -131,8 +134,8 @@ interface MyTimerExtra {
 }
 
 async function main() {
-    // Specify MyTimerExtra as the type argument for JSONLTimersManager
-    const manager = new JSONLTimersManager<MyTimerExtra>();
+    // Specify MyTimerExtra as the type argument for JSONLTimersManager.create
+    const manager = await JSONLTimersManager.create<MyTimerExtra>();
 
     // Create a timer with custom extra data
     const timerId = await manager.createTimer({
@@ -159,10 +162,13 @@ main();
 
 ### `PlainTextTimersManager`
 
-#### `constructor(timerfiledir?: string)`
-Creates a manager for timers stored in **plain-text** format.
+#### `static create(timerfile?: string): Promise<PlainTextTimersManager>`
+Creates an instance of `PlainTextTimersManager`.
+
+- **`timerfile`** (optional, string): Path to the timer file. Defaults to `.timers` in the project root.
 
-- **`timerfiledir`** (optional, string): Path to the timer file. Defaults to `.timers` in the project root.
+> [!NOTE]
+> The constructor is `protected`. Please use this `create` method to instantiate the manager.
 
 ---
 
@@ -187,17 +193,15 @@ Creates a new timer and saves it to the file.
 **Examples:**
 
 ```javascript
-// For PlainTextTimersManager with a custom Extra type
 import { PlainTextTimersManager } from 'eternal-timer';
 
 // For PlainTextTimersManager
-const manager = new PlainTextTimersManager();
+const manager = await PlainTextTimersManager.create();
 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';
 
 interface MyCustomExtra {
@@ -205,7 +209,7 @@ interface MyCustomExtra {
   userId: string;
 }
 
-const jsonlManager = new JSONLTimersManager<MyCustomExtra>();
+const jsonlManager = await JSONLTimersManager.create<MyCustomExtra>();
 const jsonlTimerId = await jsonlManager.createTimer({
   length: 10000, // 10 seconds
   extra: {
@@ -382,12 +386,12 @@ 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`. Improved memory efficiency due to line-by-line file reading.
+- **Pros**: Allows for storing extra properties(e.g. 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**:
   ```json
-  {"id":"...","start":1678886400000,"stop":1678886405000,"title":"My Timer","description":"..."}
+  {"id":"...","start":1678886400000,"stop":1678886405000,{"extra": { "title":"My Timer","description":"..." } }}
   ```
 
 ### 2. Plain Text (via `PlainTextTimersManager`)

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

@@ -3,16 +3,31 @@ import { JSONLTimersStore } from "../TimersStore/JSONLTimersStore.js";
 /**
  * JSONLTimersManager
  * @description
- * Manages timers stored in a  JSONL file.
- * (This is a abstract class)
+ * Manages timers stored in a JSONL file.
  *
  * - Timers are persisted in a file
  * - Expired timers are detected by polling
  */
-export declare class JSONLTimersManager<Extra extends object = object> extends TimersManager<"JSONL", Extra> {
-    protected TimersStore: JSONLTimersStore<Extra> | null;
-    protected getDefaultFilename(): string;
-    protected createTimersStore(): Promise<JSONLTimersStore<Extra>>;
+export declare class JSONLTimersManager<Extra extends object> extends TimersManager<"JSONL", Extra> {
+    static readonly defaultFilename = ".timers.jsonl";
+    /**
+     * create
+     * @param {string | undefined} timerfile optional timer file path. If not provided, the default path will be used.
+     * @description Creates an instance of JSONLTimersManager. If the timer file does not exist, an empty file is created.
+     * @throws If file access or creation fails
+     * @example
+     * const manager = await JSONLTimersManager.create(); // Uses default timer file path
+     * const manager = await JSONLTimersManager.create("/path/to/timers.jsonl"); // Uses specified timer file path
+     * @returns Promise resolving to an instance of JSONLTimersManager
+     */
+    static create<Extra extends object = object>(timerfile?: string): Promise<JSONLTimersManager<Extra>>;
+    /**
+     * constructor
+     * @param {string} timerfiledir resolved timer file path.
+     * @description Initializes the JSONLTimersManager instance.
+     */
+    protected constructor(timerfiledir: string);
+    protected TimersStore: JSONLTimersStore<Extra>;
     protected type: "JSONL";
     /**
      * changeExtra
@@ -23,7 +38,7 @@ export declare class JSONLTimersManager<Extra extends object = object> extends T
      * @throws If timer with id not found or file operation fails
      * @example
      * const timer = await manager.createTimer({ length: 1000, extra: {author: "someone"} });
-     * await changeExtra(timer, {author: "SUKEsann2000"});
+     * await manager.changeExtra(timer, {author: "SUKEsann2000"});
      * // extra is changed and author will be "SUKEsann2000" instead of "someone"
      */
     changeExtra(id: string, newExtra: Extra): Promise<void>;

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;AAGtE;;;;;;;;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":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAGtE;;;;;;;GAOG;AACH,qBAAa,kBAAkB,CAAC,KAAK,SAAS,MAAM,CAAE,SAAQ,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC;IAC1F,gBAAuB,eAAe,mBAAmB;IAEzD;;;;;;;;;OASG;WACiB,MAAM,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAkBjH;;;;OAIG;IACH,SAAS,aAAa,YAAY,EAAE,MAAM;IAK1C,UAAmB,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAExD,UAAmB,IAAI,EAAE,OAAO,CAAoB;IAEpD;;;;;;;;;;;OAWG;IACU,WAAW,CACvB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,KAAK,GACb,OAAO,CAAC,IAAI,CAAC;CAiBhB"}

package/dist/cjs/TimersManager/JSONLTimersManager.js

@@ -1,26 +1,62 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JSONLTimersManager = void 0;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const searchRoot_js_1 = __importDefault(require("../searchRoot.js"));
 const TimersManager_js_1 = require("./TimersManager.js");
 const JSONLTimersStore_js_1 = require("../TimersStore/JSONLTimersStore.js");
 const throwMessage_js_1 = require("../throwMessage.js");
 /**
  * JSONLTimersManager
  * @description
- * Manages timers stored in a  JSONL file.
- * (This is a abstract class)
+ * Manages timers stored in a JSONL file.
  *
  * - 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";
+    static defaultFilename = ".timers.jsonl";
+    /**
+     * create
+     * @param {string | undefined} timerfile optional timer file path. If not provided, the default path will be used.
+     * @description Creates an instance of JSONLTimersManager. If the timer file does not exist, an empty file is created.
+     * @throws If file access or creation fails
+     * @example
+     * const manager = await JSONLTimersManager.create(); // Uses default timer file path
+     * const manager = await JSONLTimersManager.create("/path/to/timers.jsonl"); // Uses specified timer file path
+     * @returns Promise resolving to an instance of JSONLTimersManager
+     */
+    static async create(timerfile) {
+        const rootDir = await (0, searchRoot_js_1.default)();
+        const filename = timerfile ?? this.defaultFilename;
+        const timerfiledir = path_1.default.isAbsolute(filename)
+            ? filename
+            : path_1.default.resolve(rootDir, filename);
+        if (!timerfiledir.startsWith(rootDir)) {
+            throw new Error(throwMessage_js_1.throwMessage.FilePathinvalid);
+        }
+        try {
+            await promises_1.default.access(timerfiledir);
+        }
+        catch {
+            await promises_1.default.writeFile(timerfiledir, "");
+        }
+        return new this(timerfiledir);
     }
-    async createTimersStore() {
-        return new JSONLTimersStore_js_1.JSONLTimersStore(this.timerfiledir);
+    /**
+     * constructor
+     * @param {string} timerfiledir resolved timer file path.
+     * @description Initializes the JSONLTimersManager instance.
+     */
+    constructor(timerfiledir) {
+        super(timerfiledir);
+        this.TimersStore = new JSONLTimersStore_js_1.JSONLTimersStore(this.timerfiledir);
     }
+    TimersStore;
     type = "JSONL";
     /**
      * changeExtra
@@ -31,12 +67,11 @@ class JSONLTimersManager extends TimersManager_js_1.TimersManager {
      * @throws If timer with id not found or file operation fails
      * @example
      * const timer = await manager.createTimer({ length: 1000, extra: {author: "someone"} });
-     * await changeExtra(timer, {author: "SUKEsann2000"});
+     * await manager.changeExtra(timer, {author: "SUKEsann2000"});
      * // extra is changed and author will be "SUKEsann2000" instead of "someone"
      */
     async changeExtra(id, newExtra) {
         return this.runExclusive(async () => {
-            this.TimersStore ??= await this.createTimersStore();
             try {
                 const timers = await this.TimersStore.loadTimers();
                 const index = timers?.findIndex(t => t.id === id);

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;AACtE,wDAAkD;AAElD;;;;;;;;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,8BAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC5C,CAAC;gBAED,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC;gBAC/B,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,8BAAY,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YACzD,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC;CACD;AA9CD,gDA8CC"}
+{"version":3,"file":"JSONLTimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/JSONLTimersManager.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AACxB,2DAA6B;AAE7B,qEAA0C;AAC1C,yDAAmD;AACnD,4EAAsE;AACtE,wDAAkD;AAElD;;;;;;;GAOG;AACH,MAAa,kBAAyC,SAAQ,gCAA6B;IACnF,MAAM,CAAU,eAAe,GAAG,eAAe,CAAC;IAEzD;;;;;;;;;OASG;IACI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAgC,SAAkB;QAC3E,MAAM,OAAO,GAAG,MAAM,IAAA,uBAAU,GAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC;QACnD,MAAM,YAAY,GAAG,cAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC7C,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,cAAI,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEnC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,8BAAY,CAAC,eAAe,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC;YACJ,MAAM,kBAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACR,MAAM,kBAAE,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,IAAI,CAAQ,YAAY,CAAC,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACH,YAAsB,YAAoB;QACzC,KAAK,CAAC,YAAY,CAAC,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,IAAI,sCAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC5D,CAAC;IAEkB,WAAW,CAA0B;IAErC,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;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,8BAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC5C,CAAC;gBAED,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC;gBAC/B,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,8BAAY,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YACzD,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC;;AA5EF,gDA6EC"}

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

@@ -4,15 +4,30 @@ import { PlainTextTimersStore } from "../TimersStore/PlainTextTimersStore.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", object> {
-    protected TimersStore: PlainTextTimersStore | null;
-    protected getDefaultFilename(): string;
-    protected createTimersStore(): Promise<PlainTextTimersStore>;
+    static readonly defaultFilename = ".timers";
+    /**
+     * create
+     * @param {string | undefined} timerfile optional timer file path. If not provided, the default path will be used.
+     * @description Creates an instance of PlainTextTimersManager. If the timer file does not exist, an empty file is created.
+     * @throws If file access or creation fails
+     * @example
+     * const manager = await PlainTextTimersManager.create(); // Uses default timer file path
+     * const manager = await PlainTextTimersManager.create("/path/to/.timers"); // Uses specified timer file path
+     * @returns Promise resolving to an instance of PlainTextTimersManager
+     */
+    static create(timerfile?: string): Promise<PlainTextTimersManager>;
+    /**
+     * constructor
+     * @param {string} timerfiledir resolved timer file path.
+     * @description Initializes the PlainTextTimersManager instance.
+     */
+    protected constructor(timerfiledir: string);
+    protected TimersStore: PlainTextTimersStore;
     protected type: "PlainText";
 }
 //# sourceMappingURL=PlainTextTimersManager.d.ts.map

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

@@ -1 +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;AAE9E;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7E,UAAmB,WAAW,EAAE,oBAAoB,GAAG,IAAI,CAAQ;cAEhD,kBAAkB,IAAI,MAAM;cAI/B,iBAAiB,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAIlE,UAAmB,IAAI,EAAE,WAAW,CAAwB;CAC5D"}
+{"version":3,"file":"PlainTextTimersManager.d.ts","sourceRoot":"","sources":["../../../src/TimersManager/PlainTextTimersManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAE9E;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7E,gBAAuB,eAAe,aAAa;IAEnD;;;;;;;;;OASG;WACiB,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAkB/E;;;;OAIG;IACH,SAAS,aAAa,YAAY,EAAE,MAAM;IAK1C,UAAmB,WAAW,EAAE,oBAAoB,CAAC;IAErD,UAAmB,IAAI,EAAE,WAAW,CAAwB;CAC5D"}

package/dist/cjs/TimersManager/PlainTextTimersManager.js

@@ -1,25 +1,62 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlainTextTimersManager = void 0;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const searchRoot_js_1 = __importDefault(require("../searchRoot.js"));
+const throwMessage_js_1 = require("../throwMessage.js");
 const TimersManager_js_1 = require("./TimersManager.js");
 const PlainTextTimersStore_js_1 = require("../TimersStore/PlainTextTimersStore.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
  */
 class PlainTextTimersManager extends TimersManager_js_1.TimersManager {
-    TimersStore = null;
-    getDefaultFilename() {
-        return ".timers";
+    static defaultFilename = ".timers";
+    /**
+     * create
+     * @param {string | undefined} timerfile optional timer file path. If not provided, the default path will be used.
+     * @description Creates an instance of PlainTextTimersManager. If the timer file does not exist, an empty file is created.
+     * @throws If file access or creation fails
+     * @example
+     * const manager = await PlainTextTimersManager.create(); // Uses default timer file path
+     * const manager = await PlainTextTimersManager.create("/path/to/.timers"); // Uses specified timer file path
+     * @returns Promise resolving to an instance of PlainTextTimersManager
+     */
+    static async create(timerfile) {
+        const rootDir = await (0, searchRoot_js_1.default)();
+        const filename = timerfile ?? this.defaultFilename;
+        const timerfiledir = path_1.default.isAbsolute(filename)
+            ? filename
+            : path_1.default.resolve(rootDir, filename);
+        if (!timerfiledir.startsWith(rootDir)) {
+            throw new Error(throwMessage_js_1.throwMessage.FilePathinvalid);
+        }
+        try {
+            await promises_1.default.access(timerfiledir);
+        }
+        catch {
+            await promises_1.default.writeFile(timerfiledir, "");
+        }
+        return new this(timerfiledir);
     }
-    async createTimersStore() {
-        return new PlainTextTimersStore_js_1.PlainTextTimersStore(this.timerfiledir);
+    /**
+     * constructor
+     * @param {string} timerfiledir resolved timer file path.
+     * @description Initializes the PlainTextTimersManager instance.
+     */
+    constructor(timerfiledir) {
+        super(timerfiledir);
+        this.TimersStore = new PlainTextTimersStore_js_1.PlainTextTimersStore(this.timerfiledir);
     }
+    TimersStore;
     type = "PlainText";
 }
 exports.PlainTextTimersManager = PlainTextTimersManager;

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

@@ -1 +1 @@
-{"version":3,"file":"PlainTextTimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/PlainTextTimersManager.ts"],"names":[],"mappings":";;;AAAA,yDAAmD;AACnD,oFAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAa,sBAAuB,SAAQ,gCAAkC;IAC1D,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;IAEkB,IAAI,GAAgB,WAAoB,CAAC;CAC5D;AAZD,wDAYC"}
+{"version":3,"file":"PlainTextTimersManager.js","sourceRoot":"","sources":["../../../src/TimersManager/PlainTextTimersManager.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AACxB,2DAA6B;AAE7B,qEAA0C;AAC1C,wDAAkD;AAClD,yDAAmD;AACnD,oFAA8E;AAE9E;;;;;;;GAOG;AACH,MAAa,sBAAuB,SAAQ,gCAAkC;IACtE,MAAM,CAAU,eAAe,GAAG,SAAS,CAAC;IAEnD;;;;;;;;;OASG;IACI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAkB;QAC5C,MAAM,OAAO,GAAG,MAAM,IAAA,uBAAU,GAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC;QACnD,MAAM,YAAY,GAAG,cAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC7C,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,cAAI,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEnC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,8BAAY,CAAC,eAAe,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC;YACJ,MAAM,kBAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACR,MAAM,kBAAE,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,YAAsB,YAAoB;QACzC,KAAK,CAAC,YAAY,CAAC,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,IAAI,8CAAoB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAChE,CAAC;IAEkB,WAAW,CAAuB;IAElC,IAAI,GAAgB,WAAoB,CAAC;;AA3C7D,wDA4CC"}

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

@@ -13,24 +13,21 @@ import { EventEmitter } from "../EventEmitter.js";
 export declare abstract class TimersManager<T extends StorageType, Extra extends object> extends EventEmitter<T, Extra> {
     protected readonly timerfiledir: string;
     protected checkLock: boolean;
-    protected interval: NodeJS.Timeout | undefined;
+    protected static intervals: Map<string, NodeJS.Timeout>;
     protected running: boolean;
-    protected TimersStore: TimersStore<T, Extra> | null;
+    protected abstract TimersStore: TimersStore<T, Extra>;
     private queue;
     protected runExclusive<T>(fn: () => Promise<T>): Promise<T>;
-    protected abstract getDefaultFilename(): string;
-    protected abstract createTimersStore(): Promise<TimersStore<T, Extra>>;
     protected abstract type: T;
     /**
-      * constructor
-      * @description Initializes the TimersManager instance. If the timer file does not exist, an empty file is created.
-      * @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(timerfile?: string);
+     * constructor
+     * @param {string} timerfile timer file path.
+     * @description Initializes the TimersManager instance.
+     * @deprecated This constructor is deprecated. Please use the static `create` method instead, which performs necessary asynchronous initialization. The constructor will be made private in a future release.
+     * @example
+     * const manager = new TimersManager("/path/to/timers"); // Uses specified timer file path
+     */
+    protected constructor(timerfile: string);
     /**
      * createTimer
      * @description Creates a new timer.
@@ -39,11 +36,11 @@ export declare abstract class TimersManager<T extends StorageType, Extra extends
      * @throws If length is invalid (e.g. length < 0) or file operation fails
      * @example
      * // For PlainTextTimersManager
-     * const manager = new PlainTextTimersManager();
+     * const manager = await PlainTextTimersManager.create();
      * const newTimerId = await manager.createTimer(5000); // Create a 5-second timer
      *
      * // For JSONLTimersManager
-     * const jsonlManager = new JSONLTimersManager<{ title: string }>();
+     * const jsonlManager = await JSONLTimersManager.create<{ 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>;
@@ -64,7 +61,6 @@ export declare abstract class TimersManager<T extends StorageType, Extra extends
      * @returns Promise<void> that resolves when the loop has been started
      * @throws If file operation fails during checking
      * @example
-     * const manager = new TimersManager();
      * await manager.checkStart(1000); // Check for expired timers every 1 second
      */
     checkStart(interval?: number): Promise<void>;
@@ -73,7 +69,6 @@ export declare abstract class TimersManager<T extends StorageType, Extra extends
      * @description Stops the timer checking loop.
      * @returns Promise resolving when the loop has been stopped
      * @example
-     * const manager = new TimersManager();
      * await manager.checkStart(1000);
      * // ... later, to stop checking:
      * await manager.checkStop();
@@ -90,22 +85,26 @@ export declare abstract class TimersManager<T extends StorageType, Extra extends
      */
     get isBusy(): boolean;
     /**
-        * 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
+     * adjustRemainingTime
       * @description Adjusts the remaining time of a timer.
       * @param {string} id ID of the timer to modify
       * @param {number} delay Delay in milliseconds to add/subtract from the remaining time
       * @returns Promise resolving when the operation is complete
       * @throws If file operation fails
+      * @example
+      * const timer = await manager.createTimer(10000); // Create a 10-second timer
+      * await manager.adjustRemainingTime(timer, -2000); // Subtract 2 seconds from the remaining time (now 8 seconds left)
+      * await manager.adjustRemainingTime(timer, 3000); // Add 3 seconds to the remaining time (now 11 seconds left)
       */
     adjustRemainingTime(id: string, delay: number): Promise<void>;
 }

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;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD;;;;;;;;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,QAAQ,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC;IAC/C,SAAS,CAAC,OAAO,EAAE,OAAO,CAAS;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,SAAS,CAAC,EAAE,MAAM;IAenB;;;;;;;;;;;;;;OAcM;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;;;;;;;;;OASG;IACU,UAAU,CACtB,QAAQ,GAAE,MAAY,GACpB,OAAO,CAAC,IAAI,CAAC;IAwDhB;;;;;;;;;OASG;IACU,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC;;;;;;;;OAQG;IACH,IAAW,MAAM,IAAI,OAAO,CAE3B;IAED;;;;;;;;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;CAyB1E"}
+{"version":3,"file":"TimersManager.d.ts","sourceRoot":"","sources":["../../../src/TimersManager/TimersManager.ts"],"names":[],"mappings":"AAEA,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;AAGlD;;;;;;;;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;IAGxC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAS;IAMrC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAa;IAEpE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAS;IAEnC,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAGtD,OAAO,CAAC,KAAK,CAAoC;IACjD,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAM9C,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAE3B;;;;;;;OAOG;IACH,SAAS,aAAa,SAAS,EAAE,MAAM;IAKvC;;;;;;;;;;;;;;OAcM;IACO,WAAW,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BhF;;;;;;;;OAQM;IACO,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAenD;;;;;;;;OAQG;IACU,UAAU,CACtB,QAAQ,GAAE,MAAY,GACpB,OAAO,CAAC,IAAI,CAAC;IAyDhB;;;;;;;;OAQG;IACU,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC;;;;;;;;OAQG;IACH,IAAW,MAAM,IAAI,OAAO,CAE3B;IAED;;;;;;;;OAQG;IACU,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;IAOrD;;;;;;;;;;;QAWO;IACM,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAwB1E"}