@provex/utils 1.0.16 → 1.2.3

package/dist/src/time.js

@@ -1,4 +1,18 @@
-/** Interval in milliseconds */
+/**
+ * @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,
@@ -15,7 +29,19 @@ const hour = intervalIn.minuteInHours * minute;
 const day = intervalIn.hourInDays * hour;
 const month = intervalIn.monthInDays * day;
 const year = intervalIn.yearInDays * month;
-/** Intervals in milliseconds */
+/**
+ * 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,
@@ -24,26 +50,36 @@ export const interval = {
     month,
     year,
 };
-/** Default display intervals */
+/**
+ * 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
- * @param timestamp - The timestamp to format
- * @param param1.anchor - The anchor date
- * @param param1.showSeconds - Whether to show seconds
- * @returns The formatted timestamp
+ * 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, { anchor = new Date(), showSeconds = false, } = {}) => {
-    const date = new Date(timestamp);
-    const diffMs = anchor.getTime() - date.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 / interval.month);
+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`;
@@ -98,6 +134,26 @@ export const formatDuration = ({ start = new Date(), until = new Date(), } = {})
     }
     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

package/dist/src/time.test.d.ts

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

package/dist/src/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
+        });
+    });
+});