@wener/common 2.0.1 → 2.0.3

package/src/dayjs/parseRelativeTime.ts

@@ -0,0 +1,115 @@
+import dayjs from 'dayjs';
+import type { Duration } from 'dayjs/plugin/duration';
+import { checkDurationUnit, RelativeDurationUnits, type RelativeDurationUnit } from './resolveRelativeTime';
+
+export type TimeOperation =
+	| {
+			operator: '+' | '-';
+			duration: Duration;
+	  }
+	| {
+			operator: '/' | '\\';
+			unit: RelativeDurationUnit;
+	  };
+
+/**
+ * Parses a relative time string and returns an array of operations.
+ *
+ * @param s - The relative time string to parse (must start with "now")
+ * @returns Array of operations that can be applied sequentially
+ * @throws {Error} When the format is invalid
+ *
+ * @example
+ * ```typescript
+ * parseRelativeTime('now-1h+30m')    // [{ operator: '-', duration: dayjs.duration(1, 'h') }, { operator: '+', duration: dayjs.duration(30, 'm') }]
+ * parseRelativeTime('now+1d6h')      // [{ operator: '+', duration: dayjs.duration({ days: 1, hours: 6 }) }]
+ * parseRelativeTime('now/d')         // [{ operator: '/', unit: 'd' }]
+ * parseRelativeTime('now\\M')        // [{ operator: '\\', unit: 'M' }]
+ * parseRelativeTime('now-1M/M')      // [{ operator: '-', duration: dayjs.duration(1, 'M') }, { operator: '/', unit: 'M' }]
+ * parseRelativeTime('now+500ms')     // [{ operator: '+', duration: dayjs.duration(500, 'ms') }]
+ * ```
+ */
+export function parseRelativeTime(s: string): TimeOperation[] {
+	if (typeof s !== 'string' || !s.startsWith('now')) {
+		throw new Error(`Invalid relative time format: ${s}`);
+	}
+
+	const remaining = s.slice(3); // Remove 'now'
+
+	if (!remaining) {
+		return [];
+	}
+
+	const operations: TimeOperation[] = [];
+
+	// Single regex to match all operations: <op><duration_spec> or <op><unit>
+	// Where duration_spec can be: 1h, 1d6h, 500ms, etc.
+	const operationRegex = /([+\-/\\])([^+\-/\\]+)/g;
+	let match: RegExpExecArray | null;
+	let lastIndex = 0;
+
+	while ((match = operationRegex.exec(remaining)) !== null) {
+		const [, operator, operand] = match;
+
+		if (operator === '/' || operator === '\\') {
+			// Truncation operation - single unit only
+			checkDurationUnit(operand.trim());
+			operations.push({
+				operator: operator as '/' | '\\',
+				unit: operand.trim() as RelativeDurationUnit,
+			});
+		} else {
+			// Addition or subtraction operation - parse complex duration
+			const parsedDuration = parseDurationSpec(operand.trim());
+			operations.push({
+				operator: operator as '+' | '-',
+				duration: parsedDuration,
+			});
+		}
+		lastIndex = operationRegex.lastIndex;
+	}
+
+	// Check if we parsed the entire remaining string
+	if (lastIndex < remaining.length) {
+		throw new Error(`Invalid relative time format: ${s}`);
+	}
+
+	return operations;
+}
+
+/**
+ * Parses a duration specification like "1h", "1d6h", "500ms" into a dayjs Duration.
+ * Supports multiple units in a single specification.
+ */
+function parseDurationSpec(spec: string): Duration {
+	// Match all number+unit pairs: 1d, 6h, 30m, 500ms, etc.
+	const durationRegex = /(\d+)(ms|[smhdwMQy])/g;
+	const durationObj: Record<string, number> = {};
+	let match: RegExpExecArray | null;
+	let hasMatch = false;
+
+	while ((match = durationRegex.exec(spec)) !== null) {
+		const [, amountStr, unit] = match;
+		checkDurationUnit(unit);
+		const amount = parseInt(amountStr, 10);
+
+		// Dayjs duration supports unit strings directly
+		durationObj[unit] = (durationObj[unit] || 0) + amount;
+		hasMatch = true;
+	}
+
+	if (!hasMatch) {
+		// Check if there are invalid units by looking for number+invalid_unit patterns
+		const invalidUnitRegex = /\d+([a-zA-Z]+)/g;
+		let invalidMatch: RegExpExecArray | null;
+		while ((invalidMatch = invalidUnitRegex.exec(spec)) !== null) {
+			const [, unit] = invalidMatch;
+			if (!RelativeDurationUnits.includes(unit as RelativeDurationUnit)) {
+				throw new Error(`Invalid unit: ${unit}`);
+			}
+		}
+		throw new Error(`Invalid duration specification: ${spec}`);
+	}
+
+	return dayjs.duration(durationObj);
+}

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,167 @@
+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 {
+	{
+		let out: Date | undefined;
+		if (!s) {
+		} else if (s instanceof Date) {
+			out = s;
+		} else if (typeof s === 'number') {
+			out = new Date(s);
+		} else if (!s.startsWith('now')) {
+			out = new Date(s);
+		}
+		if (out) {
+			if (isNaN(out.getTime())) {
+				throw new Error(`Invalid date: ${s}`);
+			}
+			return out;
+		}
+	}
+
+	if (typeof s !== 'string' || !s.startsWith('now')) {
+		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}`);
+	}
+}

package/src/decimal/index.ts

@@ -0,0 +1 @@
+export { parseDecimal } from './parseDecimal';

package/src/decimal/parseDecimal.ts

@@ -0,0 +1,16 @@
+import Decimal from 'decimal.js';
+
+export function parseDecimal(v: string | number | Decimal): Decimal;
+export function parseDecimal(v: string | number | Decimal | undefined | null): Decimal | undefined;
+export function parseDecimal(v: string | number | Decimal | undefined | null): Decimal | undefined {
+	switch (v) {
+		case '':
+		case undefined:
+		case null:
+			return undefined;
+	}
+	if (Decimal.isDecimal(v)) {
+		return v;
+	}
+	return new Decimal(v);
+}

package/src/emittery/emitter.ts

@@ -0,0 +1,9 @@
+import Emittery, { type EventName } from 'emittery';
+
+export function createEmitter<EventData = Record<EventName, any>>(name: string) {
+	return new Emittery<EventData>({
+		debug: {
+			name,
+		},
+	});
+}

package/src/emittery/index.ts

@@ -0,0 +1 @@
+export { createEmitter } from './emitter';

package/src/foundation/schema/SexType.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod/v4';
+import type { EnumValues } from '../../resource/schema';
+
+// Sex 指的是生理性别/生物性别，通常由出生时的生物特征决定
+export const SexType = Object.freeze({
+	__proto__: null,
+	Male: 'Male',
+	Female: 'Female',
+});
+export type SexType = EnumValues<typeof SexType>;
+
+export const SexTypeSchema = z
+	.union([
+		//
+		z.literal(SexType.Male).describe('男'),
+		z.literal(SexType.Female).describe('女'),
+	])
+	.describe('性别')
+	.meta({
+		title: 'SexType',
+	});