System Utilities

Date Utilities (date)

Comprehensive temporal library designed for Unix timestamps, JavaScript dates, natural expression parsing, and calendar arithmetic with millisecond precision.

Technical Heuristics: Seconds vs. Milliseconds

XyPriss DateUtils automatically detects the unit of numeric timestamps to bridge XHSC (which typically uses Unix seconds) and JavaScript (milliseconds). If a number is less than 100,000,000,000 (1e11), it is automatically treated as seconds and converted to milliseconds. This heuristic remains valid until the year 2286.

Core & Current Time

Quick access to current system timestamps in your preferred unit or as native Date objects.

.now() & .nowMs()

Returns current timestamp in Unix seconds or milliseconds.

typescript

const seconds = __sys__.utils.date.now();   // e.g. 1776287197
const millis  = __sys__.utils.date.nowMs(); // e.g. 1776287197000

.today()

Returns a fresh JavaScript Date instance set to the current instant.

typescript

const currentDate: Date = __sys__.utils.date.today();

Formatting & Duration Serialization

.format(date, locale?, options?)

Primary method for localized date serialization. Auto-detects ISO strings, Date objects, and numeric timestamps.

typescript

// From a XHSC Unix timestamp (seconds)
__sys__.utils.date.format(1776287197, "fr-FR", { dateStyle: "long" });
// → "15 avril 2026"

// Standard format with default locale
__sys__.utils.date.format(new Date());

.formatDuration(value, unit?)

Converts a raw duration into a component-based string (e.g. 1d 2h 1m 1s). Zero-value components are automatically omitted.

typescript

const uptimeSec = 93661;
__sys__.utils.date.formatDuration(uptimeSec, "s");
// → "1d 2h 1m 1s"

__sys__.utils.date.formatDuration(3600000, "ms");
// → "1h"

.timeAgo(date, locale?)

Returns a localized relative time string relative to the current instant.

typescript

const lastPost = Date.now() - 1000 * 60 * 15;
__sys__.utils.date.timeAgo(lastPost);
// → "15 minutes ago"

Arithmetic & Comparisons

.add(date, value, unit) & .subtract(date, value, unit)

Performs calendar-aware arithmetic handling month-length variations and leap years automatically. Supported units: ms, s, m, h, d, w, mo, y.

typescript

const subDate = new Date("2026-01-31");
const nextBilling = __sys__.utils.date.add(subDate, 1, "mo");
// → "2026-02-28" (Clamped to end of Feb)

const pastDate = __sys__.utils.date.subtract(new Date(), 2, "w");
// → Date 2 weeks ago

.diff(dateA, dateB, unit?)

Returns the signed integer difference between two dates in the requested unit (ms, s, m, h, d, w).

typescript

const days = __sys__.utils.date.diff("2026-12-25", "2026-12-20", "d");
// → 5

Natural Language Parsing & Expression Support

.from(expression, baseDate?)

Parses natural language shorthands (e.g. "7d", "3M", "+2w", "-2h", "tomorrow", "yesterday") into a Date instance.

typescript

const expiration = __sys__.utils.date.from("7d");
// → Date 7 days from now

const pastEvent = __sys__.utils.date.from("-2h");
// → Date 2 hours ago

const target = __sys__.utils.date.from("1w 2d", "2026-01-01");
// → Date("2026-01-10")

.parseDuration(duration)

Parses a duration shorthand string and returns the total duration in milliseconds.

typescript

__sys__.utils.date.parseDuration("7d");     // → 604800000 (ms)
__sys__.utils.date.parseDuration("2h 30m"); // → 9000000 (ms)

Calendar Queries & Ranges

.dateRange(start, end)

Generates an array of Date objects for every calendar day between start and end. Capped at 3,650 days (approx. 10 years) for memory safety.

typescript

const week = __sys__.utils.date.dateRange("2026-01-01", "2026-01-07");
// Returns an array of 7 Date objects

.weekNumber(date?)

ISO 8601 week number (1–53)

.isLeapYear(year?)

Returns true if year has 366 days

.isWeekend(date?)

Returns true for Sat / Sun

.isWeekday(date?)

Returns true for Mon – Fri

.isValid(value)

Validates finite non-NaN date input

Data Utilities

Explore deep object cloning, data manipulation, and advanced array helpers.