For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

Install

npm install @push.rocks/smarttime

or with pnpm:

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:

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:

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.

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:

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:

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:

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:

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:

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 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.

readme.md

@push.rocks/smarttime

Issue Reporting and Security