# @push.rocks/smarttime

Handle time in smart ways — cron scheduling, extended dates, precise measurements, timers, intervals, and human-readable formatting. 🕐

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
npm install @push.rocks/smarttime
```

or with pnpm:

```bash
pnpm install @push.rocks/smarttime
```

## Usage

`@push.rocks/smarttime` is a comprehensive TypeScript-first toolkit for working with time. It covers everything from cron-based scheduling and extended date manipulation to high-resolution measurements, timers, intervals, and human-readable time formatting.

All examples below use ESM imports and TypeScript.

### ⏱️ Time Units & Calculations

Convert human-readable time durations into milliseconds using the `units` helpers and `getMilliSecondsFromUnits`:

```typescript
import { units, getMilliSecondsFromUnits } from '@push.rocks/smarttime';

// Individual unit conversions
const oneDay = units.days(1);       // 86400000
const twoHours = units.hours(2);    // 7200000
const thirtySeconds = units.seconds(30); // 30000

// Combined duration — great for timeouts, TTLs, cache expiration, etc.
const duration = getMilliSecondsFromUnits({
  years: 1,
  months: 2,
  weeks: 3,
  days: 4,
  hours: 5,
  minutes: 6,
  seconds: 7,
});

console.log(`Duration: ${duration}ms`);
```

### 🗓️ Human-Readable Time Formatting

Turn raw milliseconds into a friendly string, or get a relative "time ago" description:

```typescript
import {
  getMilliSecondsAsHumanReadableString,
  getMilliSecondsAsHumanReadableAgoTime,
} from '@push.rocks/smarttime';

// "2h 30m"
console.log(getMilliSecondsAsHumanReadableString(9_000_000));

// "5 minutes ago" style output
const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
console.log(getMilliSecondsAsHumanReadableAgoTime(fiveMinutesAgo));
```

### 🔄 CronManager — Scheduled Task Execution

The `CronManager` lets you register and run multiple cron jobs using standard 6-field cron syntax (seconds included). Powered by [croner](https://github.com/Hexagon/croner).

```typescript
import { CronManager } from '@push.rocks/smarttime';

const cronManager = new CronManager();

// Run every 10 seconds
const job1 = cronManager.addCronjob('*/10 * * * * *', async (triggerTime) => {
  console.log(`Job 1 triggered at ${new Date(triggerTime).toISOString()}`);
});

// Run every full minute
const job2 = cronManager.addCronjob('0 * * * * *', async () => {
  console.log('Full minute tick!');
});

// Start all registered jobs
cronManager.start();

// Later: remove a specific job
cronManager.removeCronjob(job1);

// Stop all jobs
cronManager.stop();
```

The `CronManager` automatically calculates the shortest sleep interval between jobs and efficiently schedules wake-ups — no polling required.

### 📅 ExtendedDate — Enhanced Date Handling

`ExtendedDate` extends the native JavaScript `Date` with factory methods for common date formats and useful inspection methods:

```typescript
import { ExtendedDate } from '@push.rocks/smarttime';

// From European format: "DD.MM.YYYY"
const date1 = ExtendedDate.fromEuropeanDate('25.12.2024');

// From European date + time with timezone context
const date2 = ExtendedDate.fromEuropeanDateAndTime('25.12.2024', '14:30:00', 'Europe/Berlin');

// From hyphenated date: "YYYY-MM-DD"
const date3 = ExtendedDate.fromHyphedDate('2024-12-25');

// From milliseconds
const date4 = ExtendedDate.fromMillis(Date.now());

// From an existing Date object
const date5 = ExtendedDate.fromDate(new Date());

// Export back to various formats
console.log(date1.exportToEuropeanDate());         // "25.12.2024"
console.log(date1.exportToHyphedSortableDate());   // "2024-12-25"

// Get structured date units
const units = date1.exportToUnits();
console.log(units.monthName);         // "December"
console.log(units.dayOfTheWeekName);  // "Wednesday"

// Custom formatting (via dayjs)
console.log(date1.format('YYYY-MM-DD HH:mm'));

// Boolean checks
console.log(date4.isToday());  // true

// Time comparison: has less than 1 hour passed since this date?
console.log(date4.lessTimePassedToNow({ hours: 1 }));  // true
console.log(date4.moreTimePassedToNow({ days: 1 }));   // false
```

### ⏱️ HrtMeasurement — High-Resolution Timing

Measure the duration of operations with precision:

```typescript
import { HrtMeasurement } from '@push.rocks/smarttime';

const measurement = new HrtMeasurement();
measurement.start();

// ... perform some operation ...

measurement.stop();
console.log(`Took ${measurement.milliSeconds}ms`);
console.log(`Took ${measurement.nanoSeconds}ns`);

// Reset and reuse
measurement.reset();
measurement.start();
// ...
```

### ⏲️ Timer — Pausable Countdown

A promise-based timer with pause, resume, and reset capabilities:

```typescript
import { Timer } from '@push.rocks/smarttime';

const timer = new Timer(5000); // 5-second countdown
timer.start();

// Await completion
await timer.completed;
console.log('Timer finished!');

// Or use pause/resume
const timer2 = new Timer(10000);
timer2.start();

// Pause after 3 seconds
setTimeout(() => timer2.pause(), 3000);

// Resume later
setTimeout(() => timer2.resume(), 6000);

await timer2.completed;

// Reset completely and start over
timer2.reset();
timer2.start();
```

Check remaining time with `timer.timeLeft`.

### 🔁 Interval — Repeating Jobs

Run functions at a fixed interval with start/stop control:

```typescript
import { Interval } from '@push.rocks/smarttime';

const interval = new Interval(2000); // Every 2 seconds

interval.addIntervalJob(() => {
  console.log('Tick!', new Date().toISOString());
});

interval.addIntervalJob(() => {
  console.log('Another parallel job');
});

interval.start();

// Stop later
setTimeout(() => interval.stop(), 10000);
```

### 🕰️ TimeStamp — Comparison & Tracking

The `TimeStamp` class captures a moment in time and provides comparison utilities:

```typescript
import { TimeStamp } from '@push.rocks/smarttime';

const stamp1 = new TimeStamp();
// ... some time passes ...
const stamp2 = new TimeStamp();

console.log(stamp1.milliSeconds);  // Unix ms
console.log(stamp1.epochtime);     // Unix seconds

// Comparison
console.log(stamp1.isOlderThan(stamp2));                  // true
console.log(stamp2.isYoungerThanOtherTimeStamp(stamp1));   // true

// Derived timestamps track change
const derived = TimeStamp.fromTimeStamp(stamp1);
console.log(`${derived.change}ms have passed since stamp1`);

// From known milliseconds
const known = TimeStamp.fromMilliSeconds(1700000000000);
```

## API Overview

| Export | Description |
|---|---|
| `CronManager` | Register and run multiple cron jobs with automatic scheduling |
| `CronJob` | Individual cron job (created via `CronManager.addCronjob()`) |
| `ExtendedDate` | Enhanced `Date` with factory methods and formatting |
| `HrtMeasurement` | High-resolution time measurement |
| `Timer` | Promise-based countdown with pause/resume/reset |
| `Interval` | Repeating job execution at fixed intervals |
| `TimeStamp` | Point-in-time capture with comparison utilities |
| `units` | Time unit conversion functions (`days()`, `hours()`, etc.) |
| `getMilliSecondsFromUnits()` | Convert combined time units to milliseconds |
| `getMilliSecondsAsHumanReadableString()` | Format ms as human-readable string |
| `getMilliSecondsAsHumanReadableAgoTime()` | Format timestamp as relative "ago" string |

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.