@korvol/time

Shared UTC time primitives for Korvol TypeScript applications. Extracted from Integra's stable core; no runtime dependencies. Node 22+, ESM only. Distribution is public under the @korvol npm scope. Version 0.1.1 and later are distributed under the MIT license; see LICENSE. The source repository remains private.

import { addMs, diffMs, monotonicMs, nowUtc, plainDate, toInstant } from "@korvol/time";

const received = toInstant("2026-09-22T12:00:00Z");
const expires = addMs(received, 30_000);
const duration = diffMs(expires, received); // 30000
const businessDate = plainDate("2026-09-22"); // remains a calendar date
const current = nowUtc();
const started = monotonicMs(); // process-relative sample, never an epoch timestamp

API

| Export | Contract | |---|---| | Instant | Branded UTC string with explicit Z | | PlainDate | Branded YYYY-MM-DD calendar date | | nowUtc() | Current UTC instant with milliseconds | | toInstant(string) | Validate an exact UTC instant; throws on malformed/impossible input | | isInstant(unknown) | Nonthrowing validity predicate | | diffMs(a, b) | Signed a minus b in milliseconds | | addMs(instant, ms) | Advance by milliseconds, serialize as UTC | | isWithin(a, b, ms) | Absolute difference at most ms, inclusive | | plainDate(string) | Validate a real calendar date without converting to an instant | | monotonicMs() | performance.now sample for elapsed time in one process lifetime |

Inputs accept seconds or one to three fractional digits, with uppercase Z only. Offset strings and local timestamps are rejected. Parsing preserves the valid input representation; arithmetic emits milliseconds. Branded arguments are trusted after validation. Duration inputs retain the original arithmetic behavior: callers must supply meaningful finite budgets; this package does not implement business retry/expiry policy.

Compared with Integra's original core, 0.1.0 rejects normalized impossible dates and 24:00, and monotonicMs uses a process-relative clock rather than Date.now. Never persist a monotonic sample, compare it across processes, or use it as an epoch timestamp. Library validation errors include the rejected input; consumers own sanitization before logging. No telemetry or I/O occurs in the library.

Contributor toolchain: Node 24.12.0 and pnpm 9.12.0. Run pnpm install --frozen-lockfile, pnpm hooks:install, pnpm check, and pnpm build. Consumers do not need pnpm or contributor hooks.

See docs/DEVELOPMENT.md for release mechanics, docs/SYSTEM.md for current behavior, and docs/NOTES.md for limitations. Consumer adoption is separate from package publication.