@provex/utils 1.0.16 → 1.2.4

package/dist/time.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Time and date utilities for formatting and calculations.
+ *
+ * Provides:
+ * - Interval constants in milliseconds for time calculations
+ * - Human-readable relative time formatting ("5m ago", "2d 3h ago")
+ * - Duration formatting for time ranges
+ * - Absolute timestamp formatting
+ *
+ * @see {@link units} for blockchain timestamp conversion
+ */
+/**
+ * Time unit relationships for manual calculations.
+ * Use these when building complex time expressions.
+ */
+export const intervalIn = {
+    yearInDays: 365,
+    quarterInMonths: 3,
+    monthInDays: 30,
+    hourInDays: 24,
+    daysInWeek: 7,
+    minuteInHours: 60,
+    secondInMinutes: 60,
+    millisecondInSecond: 1000,
+};
+const second = intervalIn.millisecondInSecond;
+const minute = intervalIn.secondInMinutes * second;
+const hour = intervalIn.minuteInHours * minute;
+const day = intervalIn.hourInDays * hour;
+const month = intervalIn.monthInDays * day;
+const year = intervalIn.yearInDays * month;
+/**
+ * Common time intervals in milliseconds.
+ * Use for timeout calculations, polling intervals, and date math.
+ *
+ * @example
+ * ```ts
+ * // Set a 5 minute timeout
+ * setTimeout(callback, 5 * interval.minute)
+ *
+ * // Calculate time 1 day ago
+ * const yesterday = Date.now() - interval.day
+ * ```
+ */
+export const interval = {
+    second,
+    minute,
+    hour,
+    day,
+    month,
+    year,
+};
+/**
+ * Default number of time units to display in statistics/charts.
+ * Used for "show last N hours/days/months" UI controls.
+ */
+export const defaultDisplayInterval = {
+    hour: 7 * 24,
+    day: 6 * 30,
+    month: 60,
+};
+/**
+ * Format a timestamp as a human-readable relative time string.
+ * Produces compact strings like "5m ago", "2h 30m ago", "3d ago".
+ *
+ * @param timestamp - The timestamp to format (Date, number in ms, or date string)
+ * @param options - Optional configuration
+ * @param options.anchor - Reference date for "ago" calculation (default: now)
+ * @param options.showSeconds - Whether to show seconds for very recent times
+ * @returns Human-readable relative time string
+ *
+ * @example
+ * ```ts
+ * formatTimestamp(Date.now() - 5 * 60 * 1000)  // "5m ago"
+ * formatTimestamp(Date.now() - 2.5 * 60 * 60 * 1000)  // "2h 30m ago"
+ * formatTimestamp(Date.now() - 3 * 24 * 60 * 60 * 1000)  // "3d 0h ago"
+ * ```
+ */
+export const formatTimestamp = (timestamp, options) => {
+    const anchor = options?.anchor ?? new Date(), showSeconds = options?.showSeconds ?? false, date = new Date(timestamp);
+    const diffMs = anchor.getTime() - date.getTime(), diffMins = Math.floor(diffMs / interval.minute), diffHours = Math.floor(diffMs / interval.hour);
+    const diffDays = Math.floor(diffMs / interval.day), diffMonths = Math.floor(diffDays / intervalIn.monthInDays);
+    if (diffMonths > 0) {
+        if (diffMonths < intervalIn.quarterInMonths) {
+            return `${diffMonths}mo ${diffDays % intervalIn.monthInDays}d ago`;
+        }
+        return `${diffMonths}mo ago`;
+    }
+    if (diffMins < 1) {
+        if (showSeconds) {
+            if (diffMs < 10 * interval.second) {
+                return 'Just now';
+            }
+            return `${Math.floor(diffMs / interval.second)}s ago`;
+        }
+        return 'Just now';
+    }
+    if (diffMins < intervalIn.secondInMinutes) {
+        return `${diffMins}m ago`;
+    }
+    else if (diffHours < intervalIn.hourInDays) {
+        if (diffHours < 6) {
+            return `${diffHours}h ${diffMins % intervalIn.minuteInHours}m ago`;
+        }
+        return `${diffHours}h ago`;
+    }
+    else {
+        if (diffDays < intervalIn.daysInWeek) {
+            return `${diffDays}d ${diffHours % intervalIn.hourInDays}h ago`;
+        }
+        return `${diffDays}d ago`;
+    }
+};
+/**
+ * Format a duration
+ * @param param0.start - The start date
+ * @param param0.until - The end date
+ * @returns The formatted duration
+ */
+export const formatDuration = ({ start = new Date(), until = new Date(), } = {}) => {
+    const diffMs = until.getTime() - start.getTime();
+    const diffMins = Math.floor(diffMs / interval.minute);
+    const diffHours = Math.floor(diffMs / interval.hour);
+    const diffDays = Math.floor(diffMs / interval.day);
+    const diffMonths = Math.floor(diffDays / intervalIn.monthInDays);
+    if (diffMonths > 0) {
+        return `${diffMonths}mo ${diffDays % intervalIn.monthInDays}d`;
+    }
+    if (diffDays > 0) {
+        return `${diffDays}d ${diffHours % intervalIn.hourInDays}h`;
+    }
+    if (diffHours > 0) {
+        return `${diffHours}h ${diffMins % intervalIn.minuteInHours}m`;
+    }
+    return `${diffMins % intervalIn.minuteInHours}m`;
+};
+/**
+ * Format an absolute timestamp to a human-readable string
+ * @param timestamp - Unix timestamp in seconds or milliseconds (auto-detected)
+ * @param options - Intl.DateTimeFormatOptions for formatting
+ * @returns Formatted absolute timestamp string
+ */
+export const formatAbsoluteTimestamp = (timestamp, options) => {
+    // Auto-detect if timestamp is in seconds or milliseconds
+    // Timestamps > 10 billion are assumed to be in milliseconds (year 2286+ if seconds)
+    const timestampMs = Number(timestamp) > 10000000000 ? Number(timestamp) : Number(timestamp) * 1000;
+    const date = new Date(timestampMs);
+    return date.toLocaleString(undefined, options ?? {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit'
+    });
+};
+/**
+ * Sleep for a given number of milliseconds
+ * @param ms - The number of milliseconds to sleep
+ * @returns A promise that resolves after the given number of milliseconds
+ */
+export const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));

package/dist/time.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/time.test.js

@@ -0,0 +1,231 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { interval, intervalIn, formatTimestamp, formatDuration, formatAbsoluteTimestamp, sleep, defaultDisplayInterval, } from './time.js';
+describe('time', () => {
+    describe('formatTimestamp', () => {
+        const anchor = new Date('2025-01-05T12:00:00Z');
+        it('should return "Just now" for very recent timestamps', () => {
+            const recent = new Date(anchor.getTime() - 5 * 1000); // 5 seconds ago
+            assert.equal(formatTimestamp(recent, { anchor }), 'Just now');
+        });
+        it('should show seconds when enabled', () => {
+            const recent = new Date(anchor.getTime() - 30 * 1000); // 30 seconds ago
+            assert.equal(formatTimestamp(recent, { anchor, showSeconds: true }), '30s ago');
+        });
+        it('should format minutes correctly', () => {
+            const mins = new Date(anchor.getTime() - 15 * 60 * 1000); // 15 minutes ago
+            assert.equal(formatTimestamp(mins, { anchor }), '15m ago');
+        });
+        it('should format hours with minutes for recent hours', () => {
+            const hours = new Date(anchor.getTime() - 3 * 60 * 60 * 1000 - 30 * 60 * 1000); // 3h 30m ago
+            assert.equal(formatTimestamp(hours, { anchor }), '3h 30m ago');
+        });
+        it('should format hours only for older hours', () => {
+            const hours = new Date(anchor.getTime() - 8 * 60 * 60 * 1000); // 8 hours ago
+            assert.equal(formatTimestamp(hours, { anchor }), '8h ago');
+        });
+        it('should format days with hours for recent days', () => {
+            const days = new Date(anchor.getTime() - 2 * 24 * 60 * 60 * 1000 - 5 * 60 * 60 * 1000); // 2d 5h ago
+            assert.equal(formatTimestamp(days, { anchor }), '2d 5h ago');
+        });
+        it('should format days only for older days', () => {
+            const days = new Date(anchor.getTime() - 10 * 24 * 60 * 60 * 1000); // 10 days ago
+            assert.equal(formatTimestamp(days, { anchor }), '10d ago');
+        });
+        it('should format months with days for recent months', () => {
+            const twoMonthsAgo = new Date(anchor.getTime() - 60 * 24 * 60 * 60 * 1000); // 60 days = 2 months
+            const result = formatTimestamp(twoMonthsAgo, { anchor });
+            // 2 months is less than a quarter, so shows "2mo 0d ago"
+            assert.equal(result, '2mo 0d ago');
+        });
+        it('should format months only for older months', () => {
+            const fourMonthsAgo = new Date(anchor.getTime() - 120 * 24 * 60 * 60 * 1000); // 120 days = 4 months
+            const result = formatTimestamp(fourMonthsAgo, { anchor });
+            // 4 months is >= a quarter (3 months), so shows just "4mo ago"
+            assert.equal(result, '4mo ago');
+        });
+        it('should handle Date objects', () => {
+            const date = new Date(anchor.getTime() - 5 * 60 * 1000);
+            assert.equal(formatTimestamp(date, { anchor }), '5m ago');
+        });
+        it('should handle timestamp numbers', () => {
+            const timestamp = anchor.getTime() - 5 * 60 * 1000;
+            assert.equal(formatTimestamp(timestamp, { anchor }), '5m ago');
+        });
+        it('should handle ISO strings', () => {
+            const isoString = new Date(anchor.getTime() - 5 * 60 * 1000).toISOString();
+            assert.equal(formatTimestamp(isoString, { anchor }), '5m ago');
+        });
+    });
+    describe('formatDuration', () => {
+        it('should format minute durations', () => {
+            const start = new Date('2025-01-05T12:00:00Z');
+            const until = new Date('2025-01-05T12:15:00Z');
+            assert.equal(formatDuration({ start, until }), '15m');
+        });
+        it('should format hour durations with minutes', () => {
+            const start = new Date('2025-01-05T12:00:00Z');
+            const until = new Date('2025-01-05T15:30:00Z');
+            assert.equal(formatDuration({ start, until }), '3h 30m');
+        });
+        it('should format day durations with hours', () => {
+            const start = new Date('2025-01-05T12:00:00Z');
+            const until = new Date('2025-01-07T18:00:00Z');
+            assert.equal(formatDuration({ start, until }), '2d 6h');
+        });
+        it('should format month durations with days', () => {
+            const start = new Date('2025-01-05T12:00:00Z');
+            const until = new Date('2025-02-20T12:00:00Z');
+            const result = formatDuration({ start, until });
+            assert.ok(result.includes('mo'));
+            assert.ok(result.includes('d'));
+        });
+        it('should handle zero duration', () => {
+            const date = new Date('2025-01-05T12:00:00Z');
+            assert.equal(formatDuration({ start: date, until: date }), '0m');
+        });
+        it('should default to current time if no dates provided', () => {
+            const result = formatDuration();
+            assert.equal(result, '0m');
+        });
+        it('should handle only start date', () => {
+            const start = new Date(Date.now() - 5 * 60 * 1000);
+            const result = formatDuration({ start });
+            assert.ok(result.includes('m'));
+        });
+        it('should handle only until date', () => {
+            const until = new Date(Date.now() + 5 * 60 * 1000);
+            const result = formatDuration({ until });
+            assert.ok(result.includes('m'));
+        });
+    });
+    describe('sleep', () => {
+        it('should resolve after specified milliseconds', async () => {
+            const start = Date.now();
+            await sleep(100);
+            const elapsed = Date.now() - start;
+            assert.ok(elapsed >= 100, `Expected at least 100ms, got ${elapsed}ms`);
+            // Allow generous upper bound for CI environments with high load
+            assert.ok(elapsed < 1000, `Expected less than 1000ms, got ${elapsed}ms`);
+        });
+        it('should return a promise', () => {
+            const result = sleep(1);
+            assert.ok(result instanceof Promise);
+        });
+        it('should resolve immediately for 0ms', async () => {
+            const start = Date.now();
+            await sleep(0);
+            const elapsed = Date.now() - start;
+            assert.ok(elapsed < 10, `Expected less than 10ms, got ${elapsed}ms`);
+        });
+    });
+    describe('formatAbsoluteTimestamp', () => {
+        it('should format timestamp in seconds', () => {
+            // Unix timestamp for 2024-01-01 00:00:00 UTC
+            const timestamp = 1704067200;
+            const result = formatAbsoluteTimestamp(timestamp);
+            // Result format varies by timezone, just check it's a valid date string
+            assert.ok(result.length > 0);
+            assert.ok(typeof result === 'string');
+        });
+        it('should format timestamp in milliseconds', () => {
+            // Unix timestamp in ms for 2024-01-01 00:00:00 UTC
+            const timestamp = 1704067200000;
+            const result = formatAbsoluteTimestamp(timestamp);
+            assert.ok(result.length > 0);
+            assert.ok(typeof result === 'string');
+        });
+        it('should handle bigint timestamps', () => {
+            const timestamp = 1704067200n;
+            const result = formatAbsoluteTimestamp(timestamp);
+            assert.ok(result.length > 0);
+        });
+        it('should accept custom format options', () => {
+            const timestamp = 1704067200;
+            const result = formatAbsoluteTimestamp(timestamp, {
+                year: 'numeric',
+                month: 'numeric',
+                day: 'numeric',
+                timeZone: 'UTC', // Use UTC to get consistent results
+            });
+            assert.ok(result.includes('2024') || result.includes('1/1')); // Different locales format differently
+        });
+        it('should auto-detect milliseconds for large numbers', () => {
+            // Timestamp > 10 billion should be treated as milliseconds
+            const timestampMs = 1704067200000;
+            const timestampSec = 1704067200;
+            const resultMs = formatAbsoluteTimestamp(timestampMs);
+            const resultSec = formatAbsoluteTimestamp(timestampSec);
+            // Both should produce the same date
+            assert.equal(resultMs, resultSec);
+        });
+    });
+    describe('interval constants', () => {
+        it('should have correct second value', () => {
+            assert.equal(interval.second, 1000);
+        });
+        it('should have correct minute value', () => {
+            assert.equal(interval.minute, 60 * 1000);
+        });
+        it('should have correct hour value', () => {
+            assert.equal(interval.hour, 60 * 60 * 1000);
+        });
+        it('should have correct day value', () => {
+            assert.equal(interval.day, 24 * 60 * 60 * 1000);
+        });
+    });
+    describe('intervalIn constants', () => {
+        it('should have correct values', () => {
+            assert.equal(intervalIn.yearInDays, 365);
+            assert.equal(intervalIn.quarterInMonths, 3);
+            assert.equal(intervalIn.monthInDays, 30);
+            assert.equal(intervalIn.hourInDays, 24);
+            assert.equal(intervalIn.daysInWeek, 7);
+            assert.equal(intervalIn.minuteInHours, 60);
+            assert.equal(intervalIn.secondInMinutes, 60);
+            assert.equal(intervalIn.millisecondInSecond, 1000);
+        });
+    });
+    describe('defaultDisplayInterval', () => {
+        it('should have correct default values', () => {
+            assert.equal(defaultDisplayInterval.hour, 7 * 24);
+            assert.equal(defaultDisplayInterval.day, 6 * 30);
+            assert.equal(defaultDisplayInterval.month, 60);
+        });
+    });
+    describe('formatTimestamp edge cases', () => {
+        const anchor = new Date('2025-01-05T12:00:00Z');
+        it('should show "Just now" for showSeconds with very recent timestamp', () => {
+            const recent = new Date(anchor.getTime() - 5 * 1000); // 5 seconds ago
+            assert.equal(formatTimestamp(recent, { anchor, showSeconds: true }), 'Just now');
+        });
+        it('should show seconds for 10-59 seconds ago', () => {
+            const recent = new Date(anchor.getTime() - 15 * 1000); // 15 seconds ago
+            const result = formatTimestamp(recent, { anchor, showSeconds: true });
+            assert.equal(result, '15s ago');
+        });
+        it('should use default anchor and showSeconds when no options provided', () => {
+            // Test calling with no options object to cover default parameter initialization
+            const recent = new Date(Date.now() - 5 * 60 * 1000); // 5 minutes ago
+            const result = formatTimestamp(recent);
+            assert.ok(result.includes('m ago'));
+        });
+        it('should use defaults when empty options object provided', () => {
+            // Test calling with empty options to cover default parameter values
+            const recent = new Date(Date.now() - 10 * 60 * 1000); // 10 minutes ago
+            const result = formatTimestamp(recent, {});
+            assert.ok(result.includes('m ago'));
+        });
+        it('should use default anchor when only showSeconds provided', () => {
+            const recent = new Date(Date.now() - 30 * 1000); // 30 seconds ago
+            const result = formatTimestamp(recent, { showSeconds: true });
+            assert.ok(result.includes('s ago'));
+        });
+        it('should use default showSeconds when only anchor provided', () => {
+            const anchor = new Date('2025-01-05T12:00:00Z');
+            const recent = new Date(anchor.getTime() - 5 * 1000); // 5 seconds ago
+            const result = formatTimestamp(recent, { anchor });
+            assert.equal(result, 'Just now'); // showSeconds defaults to false
+        });
+    });
+});