@lindorm/date

A lindorm-flavoured wrapper around date-fns that parses human-readable time strings ("10 minutes", "2h", "25 years"), exposes calendar-correct expiry helpers, and ships TTL-aware Map / Set containers.

Installation

npm install @lindorm/date

This package is ESM-only. It cannot be require()'d from CommonJS.

Features

• ReadableTime parser covering long, abbreviated, and short unit forms (case-insensitive, whitespace-optional).
• Calendar-correct expiry helpers (expiresAt, expiresIn, expires) backed by date-fns add() — real calendar days for year and month units.
• Estimation helpers (ms, sec, duration) that convert in either direction without a reference date, using a Gregorian-year average for year and month units.
• TtlMap<K, V> and TtlSet<T> — lazy-expiring container types with per-entry TTL overrides.
• isReadableTime type guard.
• cronNext / isCron — resolve the next fire time for a cron expression (timezone-aware, via croner), and guard a cron string.
• Re-exports the entire date-fns API from the same module entry point.

Quick start

import { duration, expiresAt, ms } from "@lindorm/date";

const deadline = expiresAt("25 years");

ms("2 hours");
ms(5000);

duration("6mo");

ReadableTime format

A ReadableTime is a single <integer><unit> token, optionally separated by one space. The full unit table:

| Unit | Long form | Abbreviated | Short | | ------------ | ------------------------- | ----------- | ----- | | Years | years, year | yrs, yr | y | | Months | months, month | — | mo | | Weeks | weeks, week | — | w | | Days | days, day | — | d | | Hours | hours, hour | hrs, hr | h | | Minutes | minutes, minute | mins, min | m | | Seconds | seconds, second | secs, sec | s | | Milliseconds | milliseconds, millisecond | msecs, msec | ms |

Unit forms are case-insensitive. Examples that all parse equivalently:

"5s";
"5 s";
"5 seconds";
"5 SECONDS";
"5 Seconds";

A ReadableTime describes one unit-quantity pair — "1d 2h" and other compound forms are not accepted by the public string-parsing helpers and will throw. isReadableTime only accepts integer values; 1.5h is not a valid ReadableTime.

Calendar vs estimation

The package resolves ReadableTime two different ways, depending on whether a reference date is available:

• Calendar-correct (expiresAt, expiresIn, expires): year and month units delegate to date-fns add(). "1 year" lands on the same calendar day next year regardless of leap years; "1 month" lands on the same day-of-month next month, snapping back when the target month is shorter (e.g. Jan 31 + 1 month → Feb 29 in a leap year).
• Estimation (ms, sec, duration): no reference date, so year and month units are computed from a Gregorian-year average of 365.2425 days per year (year / 12 per month). Smaller units are exact.

When you have a reference date and need correctness against the real calendar, prefer the expiry helpers. When you only need a millisecond or second count for a timeout or TTL, the estimation helpers are sufficient.

The estimation inverse (ms(number), duration(number)) uses coarse matching: values within a tolerance of an integer multiple of a larger unit are normalised to that unit, so feeding ms("25y") back through ms() returns "25y" instead of an ms-suffixed residual.

API

Time conversion

ms(value)

Convert between a ReadableTime and a millisecond count.

ms("2s");
ms("5 minutes");
ms("1 day");
ms(60000);
ms(3600000);

Signatures: ms(readable: ReadableTime): number and ms(milliseconds: number): ReadableTime.

sec(value)

Convert between a ReadableTime and a second count.

sec("30s");
sec("5 minutes");
sec(60);
sec(86400);

Signatures: sec(readable: ReadableTime): number and sec(seconds: number): ReadableTime.

duration(value)

Convert between a ReadableTime and a DurationDict (a Record<DurationString, number> covering years, months, weeks, days, hours, minutes, seconds, milliseconds).

duration("6mo");
duration(93784000);

Signatures: duration(readable: ReadableTime): DurationDict and duration(milliseconds: number): DurationDict.

Expiration

expiresAt(expiry, from?)

Resolve an Expiry (a ReadableTime string or a Date) to an absolute Date. When expiry is a Date, it is returned unchanged after a future-date assertion. Calendar-correct for year and month units.

const at = expiresAt("30 minutes");
const fixed = expiresAt(new Date("2099-01-01"));

Throws Error("Invalid expiry: Expiry is before current date") when a Date expiry is not strictly after from. Throws Error("Invalid expiry: Expiry is not of type [ string | Date ]") for any other input.

expiresIn(expiry, from?)

Seconds from from (default new Date()) until the resolved Expiry. Calendar-correct.

expiresIn("10 minutes");
expiresIn("1 hour");

expires(expiry, from?)

Full expiry bundle:

const exp = expires("30 minutes");
// {
//   expiresAt: Date,
//   expiresIn: number,        // seconds from `from` to `expiresAt`
//   expiresOn: number,        // unix seconds of `expiresAt`
//   from: Date,
//   fromUnix: number,         // unix seconds of `from`
// }

Type guard

isReadableTime(value)

Returns true for an integer ReadableTime token, false otherwise.

isReadableTime("10 minutes");
isReadableTime("2h");
isReadableTime("invalid");

isCron(value)

Returns true when value is a valid cron expression, false otherwise.

isCron("0 0 * * *"); // true
isCron("not a cron"); // false

Cron

cronNext(expression, from, timezone?)

Resolves the next fire time strictly after from, evaluated in timezone (IANA name, defaults to "UTC"). Returns null when the expression has no future match. Guard with isCron first — an invalid expression throws. Standard 5-field expressions plus optional seconds (6 fields) and year (7 fields).

cronNext("0 0 * * *", new Date(), "Europe/Stockholm");

Containers

TtlMap<K, V>

A Map-like container where every entry has its own expiry timestamp. Entries are evicted lazily — the next read after the entry's TTL elapses removes it. Construct with a default ReadableTime TTL applied to inserts that do not pass an override.

import { TtlMap } from "@lindorm/date";

const cache = new TtlMap<string, number>("5m");

cache.set("a", 1);
cache.set("b", 2, "30s");

cache.get("a");
cache.has("b");
cache.delete("a");
cache.cleanup();
cache.clear();

for (const [key, value] of cache) {
  // ...
}

Methods: set(key, value, ttl?), get(key), has(key), delete(key), clear(), cleanup(), forEach(cb, thisArg?), keys(), values(), entries(), [Symbol.iterator](). The size getter calls cleanup() first so it returns the live count. set returns this for chaining. Per-entry ttl accepts the full Expiry type — a ReadableTime string or an absolute Date.

TtlSet<T>

Set-shaped equivalent of TtlMap — members expire after their TTL.

import { TtlSet } from "@lindorm/date";

const seen = new TtlSet<string>("1h");

seen.add("nonce");
seen.has("nonce");
seen.delete("nonce");

Methods: add(value, ttl?), has(value), delete(value), clear(), cleanup(), forEach(cb, thisArg?), keys(), values(), entries(), [Symbol.iterator](). Same lazy-eviction and size semantics as TtlMap.

Types

| Name | Description | | ---------------- | -------------------------------------------------------------------------------------------------- | | ReadableTime | Template-literal type for <integer><unit> and <integer> <unit> tokens. | | ReadableUnit | Union of every accepted unit form. | | Expiry | ReadableTime \| Date — the input type accepted by all expiry helpers. | | DurationDict | Record<DurationString, number> — the shape returned by duration(). | | DurationString | "years" \| "months" \| "weeks" \| "days" \| "hours" \| "minutes" \| "seconds" \| "milliseconds". |

The constants UNIT_LONG, UNIT_SHORT, and UNIT_ANY_CASE (the union backing ReadableUnit) are also exported.

date-fns re-export

The package re-exports the entire date-fns surface, so lindorm helpers and raw date-fns can be imported from one module:

import { addDays, expiresAt, format, parseISO } from "@lindorm/date";

License

AGPL-3.0-or-later