@trap_stevo/timetide/README.md

Master the flow of time with the ultimate solution for precision scheduling, real-time synchronization, and temporal control. Designed for developers who demand flexibility and power, this system blends intuitive time parsing, dynamic countdowns, and pers

# TimeTide

Master the flow of time with the ultimate solution for precision scheduling, real-time synchronization, and temporal control. Designed for developers who demand flexibility and power, this system blends intuitive time parsing, dynamic countdowns, and persistent task handling into a seamless toolkit. Schedule events using human-readable commands, manage intervals and expiration with clarity, and broadcast real-time updates to dashboards or distributed systems. Whether you build responsive interfaces, backend automation, or temporal workflows, this API equips you to orchestrate time itself—with legendary elegance and unmatched control.

---


## Features

- ⏱️ Human-readable scheduling (e.g. "in 5 minutes", "next Monday")
- 🧠 Persistent named tasks across restarts
- 🔁 Repeating tasks and tick events
- 🎯 Countdown timers and expiration checks
- ⚙️ Real-time dashboard synchronization with `tick` and `update` events
- 🔌 Easily configurable with `initializeTimers()`

---


## Installation

```bash
npm install @trap_stevo/timetide
```

---


## Quick Start

```js
const TimeTide, { parseDate, toMilliseconds } = require("@trap_stevo/timetide");

TimeTide.initializeTimers({
     persistPath: "./.timers.json",
     disablePersistence: false
});

TimeTide.schedule("backupJob", "10s", () => {
     console.log("Backup job executed");
});

TimeTide.then("backupJob", () => {
     console.log("Backup follow-up task");
});
```

---


## Utility Methods

```js
parseDate("next Monday");  // returns ~ Date object
parseDate("in 3 days");    // returns ~ Date object

parseDuration("2h 30m");   // returns ~ Milliseconds

toMilliseconds("10s");     // returns ~ 10000

toReadable(9123456);       // returns ~ "2h 32m 3s 456ms"
```

---


## Named Tasks

```js
TimeTide.pause("backupJob");
TimeTide.resume("backupJob");
TimeTide.extend("backupJob", "2m");
TimeTide.reduce("backupJob", "30s");
```

---


## Tick Events

```js
TimeTide.startTick("1s");

TimeTide.events.on("tick:1s", () => {
     console.log("Tick every second");
});
```

---


## Get All Active Timers

```js
const timers = TimeTide.getTimers();
console.log(timers);
```

---


## Configuration

```js
TimeTide.initializeTimers({
     persistPath: "./my-timers.json",
     disablePersistence: false
});
```

---


## License

See license in [LICENSE.md](./LICENSE.md)