@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/date/index.d.ts

@@ -22,4 +22,193 @@
  * SOFTWARE.
  */
 
-export * from './date.utils';
+/**
+ * Format options for the formatDate function
+ */
+interface DateFormatOptions {
+    /** Date format pattern (default: 'yyyy-MM-dd') */
+    format?: string;
+    /** Locale to use for formatting (default: system locale) */
+    locale?: string | string[];
+    /** Time zone to use (default: system time zone) */
+    timeZone?: string;
+}
+/**
+ * Format a date according to the specified format pattern.
+ *
+ * @param date - Date to format
+ * @param options - Formatting options
+ * @returns Formatted date string
+ *
+ * @example
+ * ```typescript
+ * // Format as ISO date
+ * formatDate(new Date(), { format: 'yyyy-MM-dd' }); // '2023-05-15'
+ *
+ * // Format with time
+ * formatDate(new Date(), { format: 'yyyy-MM-dd HH:mm:ss' }); // '2023-05-15 14:30:22'
+ *
+ * // Format with locale
+ * formatDate(new Date(), { format: 'PPPP', locale: 'fr-FR' }); // 'lundi 15 mai 2023'
+ * ```
+ */
+declare function formatDate(date: Date | number, options?: DateFormatOptions): string;
+/**
+ * Format a date as relative time (e.g., "5 minutes ago", "in 3 days").
+ *
+ * @param date - Date to format
+ * @param now - Reference date (default: current time)
+ * @param locale - Locale to use for formatting
+ * @returns Formatted relative time string
+ */
+declare function formatRelativeTime(date: Date | number, now?: Date | number, locale?: string | string[]): string;
+/**
+ * Parse a date string or timestamp into a Date object.
+ *
+ * @param input - Date string or timestamp to parse
+ * @param fallback - Fallback date if parsing fails
+ * @returns Parsed Date object or fallback
+ *
+ * @example
+ * ```typescript
+ * parseDate('2023-05-15'); // Date object for May 15, 2023
+ * parseDate('invalid', new Date()); // Returns current date as fallback
+ * ```
+ */
+declare function parseDate(input: string | number, fallback?: Date): Date | null;
+/**
+ * Calculate the difference between two dates in the specified unit.
+ *
+ * @param date1 - First date
+ * @param date2 - Second date (default: current time)
+ * @param unit - Unit of time for the difference
+ * @returns Difference in the specified unit
+ *
+ * @example
+ * ```typescript
+ * // Get difference in days
+ * dateDiff(new Date('2023-05-15'), new Date('2023-05-10'), 'days'); // 5
+ *
+ * // Get difference in hours
+ * dateDiff(new Date('2023-05-15T10:00:00'), new Date('2023-05-15T06:00:00'), 'hours'); // 4
+ * ```
+ */
+declare function dateDiff(date1: Date | number, date2?: Date | number, unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): number;
+/**
+ * Add a specified amount of time to a date.
+ *
+ * @param date - Base date
+ * @param amount - Amount to add (can be negative)
+ * @param unit - Unit of time to add
+ * @returns New date with the addition
+ *
+ * @example
+ * ```typescript
+ * // Add 5 days
+ * addToDate(new Date('2023-05-15'), 5, 'days'); // Date for May 20, 2023
+ *
+ * // Subtract 2 hours
+ * addToDate(new Date('2023-05-15T10:00:00'), -2, 'hours'); // Date for May 15, 2023 08:00:00
+ * ```
+ */
+declare function addToDate(date: Date | number, amount: number, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): Date;
+/**
+ * Get the start of a time period containing the specified date.
+ *
+ * @param date - Date to get the start from
+ * @param unit - Time unit
+ * @returns Date object representing the start of the time unit
+ *
+ * @example
+ * ```typescript
+ * // Get start of day (midnight)
+ * startOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 00:00:00
+ *
+ * // Get start of month
+ * startOf(new Date('2023-05-15'), 'month'); // Date for May 1, 2023
+ * ```
+ */
+declare function startOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
+/**
+ * Get the end of a time period containing the specified date.
+ *
+ * @param date - Date to get the end from
+ * @param unit - Time unit
+ * @returns Date object representing the end of the time unit
+ *
+ * @example
+ * ```typescript
+ * // Get end of day (23:59:59.999)
+ * endOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 23:59:59.999
+ *
+ * // Get end of month
+ * endOf(new Date('2023-05-15'), 'month'); // Date for May 31, 2023 23:59:59.999
+ * ```
+ */
+declare function endOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
+/**
+ * Check if a date is between two other dates.
+ *
+ * @param date - Date to check
+ * @param start - Start date of the range
+ * @param end - End date of the range
+ * @param inclusive - Whether the comparison should be inclusive of start/end
+ * @returns True if the date is within the range
+ *
+ * @example
+ * ```typescript
+ * const date = new Date('2023-05-15');
+ * const start = new Date('2023-05-10');
+ * const end = new Date('2023-05-20');
+ *
+ * isBetween(date, start, end); // true
+ * ```
+ */
+declare function isBetween(date: Date | number, start: Date | number, end: Date | number, inclusive?: boolean): boolean;
+/**
+ * Check if a year is a leap year.
+ *
+ * @param year - Year to check (or date object)
+ * @returns True if the year is a leap year
+ */
+declare function isLeapYear(year: number | Date): boolean;
+/**
+ * Get the number of days in a month.
+ *
+ * @param year - Year
+ * @param month - Month (0-11)
+ * @returns Number of days in the month
+ */
+declare function daysInMonth(year: number | Date, month?: number): number;
+/**
+ * Format a duration given in milliseconds to a human readable string.
+ * Examples: 3661000 -> "1h 1m 1s", 90061 -> "1m 30s 61ms"
+ *
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Human readable duration
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Parse a duration string or number into milliseconds.
+ * Supports formats like: 1y, 2w, 3d, 4h, 5m, 6s, 7ms, 1w2d3h, or plain milliseconds like "60000"
+ *
+ * @param value - Duration string or number
+ * @returns Milliseconds
+ */
+declare function parseDuration(value: string | number): number;
+/**
+ * Convert a duration string into a Date object representing the future time.
+ *
+ * @param input - Duration string (e.g., "5m", "2h", "1d")
+ * @returns Date object representing the future time
+ *
+ * @example
+ * ```typescript
+ * toDateFromNow("5m"); // Date object 5 minutes from now
+ * toDateFromNow("2h"); // Date object 2 hours from now
+ * ```
+ */
+declare function getDateFromDuration(input: string): Date;
+
+export { addToDate, dateDiff, daysInMonth, endOf, formatDate, formatDuration, formatRelativeTime, getDateFromDuration, isBetween, isLeapYear, parseDate, parseDuration, startOf };
+export type { DateFormatOptions };

package/date/index.mjs

@@ -86,7 +86,7 @@ function parseDate(input, fallback) {
   }
   try {
     const date = new Date(input);
-    if (isNaN(date.getTime())) {
+    if (Number.isNaN(date.getTime())) {
       return fallback || null;
     }
     return date;
@@ -279,5 +279,48 @@ function formatDuration(ms) {
   return parts.join(" ");
 }
 __name(formatDuration, "formatDuration");
+function parseDuration(value) {
+  const MAX_SAFE = Number.MAX_SAFE_INTEGER;
+  if (typeof value === "number" && Number.isFinite(value)) return Math.min(value, MAX_SAFE);
+  if (typeof value !== "string" || !value.trim()) return 0;
+  if (/^\d+$/.test(value)) return Math.min(Number(value), MAX_SAFE);
+  const val = value.replace(/\s+/g, "").toLowerCase();
+  const unitMap = {
+    y: 31536e6,
+    w: 6048e5,
+    d: 864e5,
+    h: 36e5,
+    m: 6e4,
+    s: 1e3,
+    ms: 1
+  };
+  const unitKeys = Object.keys(unitMap).sort((a, b) => b.length - a.length);
+  let total = 0;
+  let i = 0;
+  while (i < val.length) {
+    const start = i;
+    while (i < val.length && /\d/.test(val[i])) i++;
+    if (start === i) {
+      throw new Error(`Invalid duration at offset ${i} in "${value}"`);
+    }
+    const num = Number(val.slice(start, i));
+    if (!Number.isSafeInteger(num)) throw new Error(`Invalid number at offset ${start} in "${value}"`);
+    const unit = unitKeys.find((u) => val.startsWith(u, i));
+    if (!unit) throw new Error(`Unknown unit at offset ${i} in "${value}"`);
+    const add = num * unitMap[unit];
+    total = Math.min(total + add, MAX_SAFE);
+    i += unit.length;
+  }
+  return total;
+}
+__name(parseDuration, "parseDuration");
+function getDateFromDuration(input) {
+  const ms = parseDuration(input);
+  if (ms <= 0) {
+    throw new Error(`Invalid duration: "${input}". Duration must be a positive value.`);
+  }
+  return new Date(Date.now() + ms);
+}
+__name(getDateFromDuration, "getDateFromDuration");
 
-export { addToDate, dateDiff, daysInMonth, endOf, formatDate, formatDuration, formatRelativeTime, isBetween, isLeapYear, parseDate, startOf };
+export { addToDate, dateDiff, daysInMonth, endOf, formatDate, formatDuration, formatRelativeTime, getDateFromDuration, isBetween, isLeapYear, parseDate, parseDuration, startOf };