@wener/common 2.0.2 → 2.0.5

package/src/dayjs/resolveRelativeTime.test.ts

@@ -0,0 +1,357 @@
+import dayjs from 'dayjs';
+import quarterOfYear from 'dayjs/plugin/quarterOfYear';
+import weekOfYear from 'dayjs/plugin/weekOfYear';
+import { describe, expect, it } from 'vitest';
+import { resolveRelativeTime } from './resolveRelativeTime';
+
+dayjs.extend(quarterOfYear);
+dayjs.extend(weekOfYear);
+
+describe('resolveRelativeTime', () => {
+	const fixedDate = new Date('2024-03-15T14:30:45.123Z');
+
+	describe('basic cases', () => {
+		it('should handle "now"', () => {
+			const result = resolveRelativeTime('now', fixedDate);
+			expect(result).toEqual(fixedDate);
+		});
+
+		it('should handle "now" without reference date', () => {
+			const result = resolveRelativeTime('now', undefined);
+			expect(result).toBeInstanceOf(Date);
+		});
+	});
+
+	describe('subtraction operations', () => {
+		it('should subtract seconds', () => {
+			const result = resolveRelativeTime('now-30s', fixedDate);
+			const expected = dayjs(fixedDate).subtract(30, 'second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract minutes', () => {
+			const result = resolveRelativeTime('now-15m', fixedDate);
+			const expected = dayjs(fixedDate).subtract(15, 'minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract hours', () => {
+			const result = resolveRelativeTime('now-2h', fixedDate);
+			const expected = dayjs(fixedDate).subtract(2, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract days', () => {
+			const result = resolveRelativeTime('now-7d', fixedDate);
+			const expected = dayjs(fixedDate).subtract(7, 'day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract weeks', () => {
+			const result = resolveRelativeTime('now-2w', fixedDate);
+			const expected = dayjs(fixedDate).subtract(2, 'week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract months', () => {
+			const result = resolveRelativeTime('now-1M', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract quarters', () => {
+			const result = resolveRelativeTime('now-1Q', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should subtract years', () => {
+			const result = resolveRelativeTime('now-1y', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('addition operations', () => {
+		it('should add seconds', () => {
+			const result = resolveRelativeTime('now+30s', fixedDate);
+			const expected = dayjs(fixedDate).add(30, 'second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add minutes', () => {
+			const result = resolveRelativeTime('now+15m', fixedDate);
+			const expected = dayjs(fixedDate).add(15, 'minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add hours', () => {
+			const result = resolveRelativeTime('now+3h', fixedDate);
+			const expected = dayjs(fixedDate).add(3, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add days', () => {
+			const result = resolveRelativeTime('now+5d', fixedDate);
+			const expected = dayjs(fixedDate).add(5, 'day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add weeks', () => {
+			const result = resolveRelativeTime('now+2w', fixedDate);
+			const expected = dayjs(fixedDate).add(2, 'week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add months', () => {
+			const result = resolveRelativeTime('now+2M', fixedDate);
+			const expected = dayjs(fixedDate).add(2, 'month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add quarters', () => {
+			const result = resolveRelativeTime('now+1Q', fixedDate);
+			const expected = dayjs(fixedDate).add(1, 'quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should add years', () => {
+			const result = resolveRelativeTime('now+1y', fixedDate);
+			const expected = dayjs(fixedDate).add(1, 'year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('truncation operations', () => {
+		it('should truncate to start of second', () => {
+			const result = resolveRelativeTime('now/s', fixedDate);
+			const expected = dayjs(fixedDate).startOf('second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of minute', () => {
+			const result = resolveRelativeTime('now/m', fixedDate);
+			const expected = dayjs(fixedDate).startOf('minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of hour', () => {
+			const result = resolveRelativeTime('now/h', fixedDate);
+			const expected = dayjs(fixedDate).startOf('hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of day', () => {
+			const result = resolveRelativeTime('now/d', fixedDate);
+			const expected = dayjs(fixedDate).startOf('day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of week', () => {
+			const result = resolveRelativeTime('now/w', fixedDate);
+			const expected = dayjs(fixedDate).startOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of month', () => {
+			const result = resolveRelativeTime('now/M', fixedDate);
+			const expected = dayjs(fixedDate).startOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of quarter', () => {
+			const result = resolveRelativeTime('now/Q', fixedDate);
+			const expected = dayjs(fixedDate).startOf('quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to start of year', () => {
+			const result = resolveRelativeTime('now/y', fixedDate);
+			const expected = dayjs(fixedDate).startOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('endOf truncation operations (backslash)', () => {
+		it('should truncate to end of second', () => {
+			const result = resolveRelativeTime('now\\s', fixedDate);
+			const expected = dayjs(fixedDate).endOf('second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of minute', () => {
+			const result = resolveRelativeTime('now\\m', fixedDate);
+			const expected = dayjs(fixedDate).endOf('minute').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of hour', () => {
+			const result = resolveRelativeTime('now\\h', fixedDate);
+			const expected = dayjs(fixedDate).endOf('hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of day', () => {
+			const result = resolveRelativeTime('now\\d', fixedDate);
+			const expected = dayjs(fixedDate).endOf('day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of week', () => {
+			const result = resolveRelativeTime('now\\w', fixedDate);
+			const expected = dayjs(fixedDate).endOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of month', () => {
+			const result = resolveRelativeTime('now\\M', fixedDate);
+			const expected = dayjs(fixedDate).endOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of quarter', () => {
+			const result = resolveRelativeTime('now\\Q', fixedDate);
+			const expected = dayjs(fixedDate).endOf('quarter').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should truncate to end of year', () => {
+			const result = resolveRelativeTime('now\\y', fixedDate);
+			const expected = dayjs(fixedDate).endOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('complex combinations', () => {
+		it('should handle "now-1M/M" (start of previous month)', () => {
+			const result = resolveRelativeTime('now-1M/M', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'month').startOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/d+1d-1s" (end of current day)', () => {
+			const result = resolveRelativeTime('now/d+1d-1s', fixedDate);
+			const expected = dayjs(fixedDate).startOf('day').add(1, 'day').subtract(1, 'second').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle multiple operations "now-1w+2d-3h"', () => {
+			const result = resolveRelativeTime('now-1w+2d-3h', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'week').add(2, 'day').subtract(3, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now-1M\\M" (end of previous month)', () => {
+			const result = resolveRelativeTime('now-1M\\M', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'month').endOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\d" vs "now/d+1d-1s" (both end of current day)', () => {
+			const resultBackslash = resolveRelativeTime('now\\d', fixedDate);
+			const resultAlternative = resolveRelativeTime('now/d+1d-1s', fixedDate);
+			const expectedBackslash = dayjs(fixedDate).endOf('day').toDate();
+			const expectedAlternative = dayjs(fixedDate).startOf('day').add(1, 'day').subtract(1, 'second').toDate();
+
+			expect(resultBackslash).toEqual(expectedBackslash);
+			expect(resultAlternative).toEqual(expectedAlternative);
+			// Note: endOf gives millisecond precision (.999), while alternative gives second precision (.000)
+			// Both represent end of day, but endOf is more precise
+			expect(resultBackslash.getTime()).toBeGreaterThan(resultAlternative.getTime());
+		});
+
+		it('should handle "now-1y\\y" (end of previous year)', () => {
+			const result = resolveRelativeTime('now-1y\\y', fixedDate);
+			const expected = dayjs(fixedDate).subtract(1, 'year').endOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/y+6M" (middle of current year)', () => {
+			const result = resolveRelativeTime('now/y+6M', fixedDate);
+			const expected = dayjs(fixedDate).startOf('year').add(6, 'month').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+
+	describe('error cases', () => {
+		it('should throw error for invalid format', () => {
+			expect(() => resolveRelativeTime('invalid', fixedDate)).toThrow('Invalid');
+		});
+
+		it('should throw error for non-now start', () => {
+			expect(() => resolveRelativeTime('then-1h', fixedDate)).toThrow('Invalid');
+		});
+
+		it('should throw error for invalid time unit', () => {
+			expect(() => resolveRelativeTime('now-1x', fixedDate)).toThrow('Invalid time operand');
+		});
+
+		it('should throw error for invalid operator', () => {
+			expect(() => resolveRelativeTime('now*1h', fixedDate)).toThrow('Invalid relative time format');
+		});
+
+		it('should throw error for invalid truncation unit', () => {
+			expect(() => resolveRelativeTime('now/z', fixedDate)).toThrow();
+		});
+
+		it('should throw error for incomplete operation', () => {
+			expect(() => resolveRelativeTime('now-', fixedDate)).toThrow('Invalid relative time format');
+		});
+	});
+
+	describe('Grafana examples from comments', () => {
+		it('should handle "now-24h" (last 24 hours)', () => {
+			const result = resolveRelativeTime('now-24h', fixedDate);
+			const expected = dayjs(fixedDate).subtract(24, 'hour').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/M" (start of current month)', () => {
+			const result = resolveRelativeTime('now/M', fixedDate);
+			const expected = dayjs(fixedDate).startOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now-7d" (last 7 days)', () => {
+			const result = resolveRelativeTime('now-7d', fixedDate);
+			const expected = dayjs(fixedDate).subtract(7, 'day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/y" (start of current year)', () => {
+			const result = resolveRelativeTime('now/y', fixedDate);
+			const expected = dayjs(fixedDate).startOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now/w" (start of current week)', () => {
+			const result = resolveRelativeTime('now/w', fixedDate);
+			const expected = dayjs(fixedDate).startOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\d" (end of current day)', () => {
+			const result = resolveRelativeTime('now\\d', fixedDate);
+			const expected = dayjs(fixedDate).endOf('day').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\M" (end of current month)', () => {
+			const result = resolveRelativeTime('now\\M', fixedDate);
+			const expected = dayjs(fixedDate).endOf('month').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\w" (end of current week)', () => {
+			const result = resolveRelativeTime('now\\w', fixedDate);
+			const expected = dayjs(fixedDate).endOf('week').toDate();
+			expect(result).toEqual(expected);
+		});
+
+		it('should handle "now\\y" (end of current year)', () => {
+			const result = resolveRelativeTime('now\\y', fixedDate);
+			const expected = dayjs(fixedDate).endOf('year').toDate();
+			expect(result).toEqual(expected);
+		});
+	});
+});

package/src/dayjs/resolveRelativeTime.ts

@@ -0,0 +1,164 @@
+import { parseDate, type MaybeDate } from '@wener/utils';
+import dayjs from 'dayjs';
+import duration from 'dayjs/plugin/duration';
+import quarterOfYear from 'dayjs/plugin/quarterOfYear';
+import weekOfYear from 'dayjs/plugin/weekOfYear';
+
+dayjs.extend(duration);
+dayjs.extend(quarterOfYear);
+dayjs.extend(weekOfYear);
+
+/**
+ * Resolves a Grafana-style relative time string and returns the corresponding Date.
+ *
+ * @param s - The relative time string to parse (must start with "now")
+ * @param now - Optional reference date. If undefined, uses current time
+ * @returns The calculated Date based on the relative time expression
+ *
+ * @throws {Error} When the format is invalid or contains unsupported operators/units
+ *
+ * ## Syntax
+ *
+ * All expressions must start with `now` followed by optional operations:
+ *
+ * ### Operators
+ * - `-` - Subtraction (e.g., `now-1h` for one hour ago)
+ * - `+` - Addition (e.g., `now+1d` for one day from now)
+ * - `/` - Truncation to beginning of time unit (e.g., `now/d` for start of current day)
+ * - `\` - Truncation to end of time unit (e.g., `now\d` for end of current day)
+ *
+ * ### Time Units
+ * - `s` - seconds
+ * - `m` - minutes
+ * - `h` - hours
+ * - `d` - days
+ * - `w` - weeks
+ * - `M` - months
+ * - `Q` - quarters
+ * - `y` - years
+ *
+ * ### Operations
+ * Operations are processed sequentially from left to right:
+ * - **Addition/Subtraction**: `now±{count}{unit}` (e.g., `now-24h`, `now+1d`)
+ * - **Truncation to start**: `now/{unit}` (e.g., `now/d`, `now/M`)
+ * - **Truncation to end**: `now\{unit}` (e.g., `now\d`, `now\M`)
+ * - **Complex**: Multiple operations can be chained (e.g., `now-1M/M`, `now\d`, `now-1y\y`)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * resolveRelativeTime('now')           // Current time
+ * resolveRelativeTime('now-1h')        // One hour ago
+ * resolveRelativeTime('now+1d')        // One day from now
+ * resolveRelativeTime('now/d')         // Start of current day
+ * resolveRelativeTime('now\\d')        // End of current day
+ *
+ * // Common patterns
+ * resolveRelativeTime('now-24h')       // Last 24 hours
+ * resolveRelativeTime('now-7d')        // Last 7 days
+ * resolveRelativeTime('now/M')         // Start of current month
+ * resolveRelativeTime('now\\M')        // End of current month
+ * resolveRelativeTime('now-1M/M')      // Start of previous month
+ * resolveRelativeTime('now-1M\\M')     // End of previous month
+ * resolveRelativeTime('now/w')         // Start of current week
+ * resolveRelativeTime('now\\w')        // End of current week
+ * resolveRelativeTime('now/y')         // Start of current year
+ * resolveRelativeTime('now\\y')        // End of current year
+ *
+ * // Complex expressions
+ * resolveRelativeTime('now/d+1d-1s')   // End of current day (alternative method)
+ * resolveRelativeTime('now\\d')        // End of current day (direct method)
+ * resolveRelativeTime('now-1w+2d-3h')  // 1 week ago, plus 2 days, minus 3 hours
+ *
+ * // With reference date
+ * const refDate = new Date('2024-03-15T14:30:45.123Z');
+ * resolveRelativeTime('now-1h', refDate);  // One hour before reference date
+ * resolveRelativeTime('now\\d', refDate);  // End of reference day
+ * ```
+ */
+export function resolveRelativeTime(s: string | Date | number, now?: Date | undefined): Date;
+export function resolveRelativeTime(s: MaybeDate, now?: Date | undefined): Date | undefined;
+export function resolveRelativeTime(s: MaybeDate, now?: Date | undefined): Date | undefined {
+	{
+		let out = parseDate(s);
+		if (out) {
+			return out;
+		}
+		if (s == null) {
+			return;
+		}
+	}
+
+	if (typeof s === 'string' && s.startsWith('now')) {
+		// valid
+	} else {
+		throw new Error(`Invalid relative time format: ${s}`);
+	}
+
+	let current = dayjs(now);
+	const remaining = s.slice(3); // Remove 'now'
+
+	if (!remaining) {
+		return current.toDate();
+	}
+
+	// Split by operators while keeping them in the result
+	const parts = remaining.split(/([+\-/\\])/).filter((part) => part !== '');
+
+	for (let i = 0; i < parts.length; i += 2) {
+		const operator = parts[i];
+		const operand = parts[i + 1];
+
+		if (!operator || !operand) {
+			throw new Error(`Invalid relative time format: ${s}`);
+		}
+
+		if (operator === '/') {
+			// Truncation to start operation
+			checkDurationUnit(operand);
+			current = current.startOf(operand);
+		} else if (operator === '\\') {
+			// Truncation to end operation
+			checkDurationUnit(operand);
+			current = current.endOf(operand);
+		} else {
+			// Addition or subtraction operation
+			const match = operand.match(/^(\d+)([smhdwMQy])$/);
+			if (!match) {
+				throw new Error(`Invalid time operand: ${operand}`);
+			}
+
+			const [, amountStr, unit] = match;
+			checkDurationUnit(unit);
+			const amount = parseInt(amountStr, 10);
+
+			if (operator === '+') {
+				current = current.add(amount, unit as 'w');
+			} else if (operator === '-') {
+				current = current.subtract(amount, unit as 'Q');
+			} else {
+				throw new Error(`Invalid operator: ${operator}`);
+			}
+		}
+	}
+
+	return current.toDate();
+}
+
+/** Array of all valid time units */
+export const RelativeDurationUnits = ['ms', 's', 'm', 'h', 'd', 'w', 'M', 'Q', 'y'] as const;
+
+/** Valid time units for relative time expressions */
+export type RelativeDurationUnit = (typeof RelativeDurationUnits)[number];
+
+/**
+ * Type guard to validate and assert that a string is a valid time unit.
+ *
+ * @param u - The string to check
+ * @throws {Error} When the unit is not supported
+ */
+export function checkDurationUnit(u: string): asserts u is RelativeDurationUnit {
+	if (!RelativeDurationUnits.includes(u as RelativeDurationUnit)) {
+		throw new Error(`Invalid unit: ${u}`);
+	}
+}