@gzl10/ts-helpers 4.2.1

package/dist/types/dates-hTiE0Z11.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Date manipulation and formatting utilities
+ * Consolidated from specialized/date module
+ */
+
+/**
+ * Formats current date with specified format
+ */
+declare const formatNow: (formatStr?: string) => string;
+/**
+ * Formats date with specified format string (Spanish locale by default)
+ *
+ * Flexible date formatter with special support for week-of-year formats.
+ * Uses dayjs Spanish locale for month/day names.
+ *
+ * @param value - Date value to format (Date, string, timestamp, dayjs)
+ * @param formatStr - Format string (default: 'DD/MM/YYYY' for Spanish dates)
+ * @returns Formatted date string, empty string if value is null/undefined
+ *
+ * @example
+ * ```typescript
+ * const date = new Date('2024-03-15')
+ *
+ * format(date)                    // '15/03/2024' (Spanish default)
+ * format(date, 'DD-MM-YYYY')      // '15-03-2024'
+ * format(date, 'YYYY/MM/DD')      // '2024/03/15'
+ * format(date, 'DD MMM YYYY')     // '15 mar 2024' (Spanish month)
+ * format(date, 'dddd, DD MMMM')   // 'viernes, 15 marzo' (Spanish)
+ * format(date, 'gg')              // '11' (week of year)
+ * format(date, 'gggg')            // '2411' (year + week)
+ * ```
+ *
+ * @see {@link longString} for localized long format
+ * @see {@link formatNow} for current date formatting
+ */
+declare const format: (value: any, formatStr?: string) => string;
+/**
+ * Converts date to localized long string format (Spanish)
+ *
+ * Formats date as human-readable string with full month name in Spanish locale.
+ * Uses dayjs 'LL' format: "15 de marzo de 2024"
+ *
+ * @param value - Date value to format (null returns empty string)
+ * @returns Localized long format date string (e.g., "15 de marzo de 2024")
+ *
+ * @example
+ * ```typescript
+ * longString(new Date('2024-03-15'))  // "15 de marzo de 2024"
+ * longString('2024-12-25')            // "25 de diciembre de 2024"
+ * longString(null)                    // ""
+ *
+ * // Real-world: Document headers
+ * const reportDate = longString(new Date())
+ * console.log(`Informe generado el ${reportDate}`)
+ * // "Informe generado el 15 de marzo de 2024"
+ * ```
+ *
+ * @see {@link format} for custom format strings
+ */
+declare const longString: (value?: any) => string;
+/**
+ * Converts value to native JavaScript Date object
+ */
+declare const toDate: (value: any, isUtc?: boolean) => Date;
+type DateStringFormat = 'DD/MM/YYYY' | 'YYYY-MM-DD' | 'MM/DD/YYYY' | 'YYYY/MM/DD' | 'DD-MM-YYYY' | 'MM-DD-YYYY' | 'YYYYMMDD' | 'DDMMYYYY' | 'MMDDYYYY' | 'YYYY.MM.DD' | 'DD.MM.YYYY' | 'MM.DD.YYYY';
+/**
+ * Parses date string with specific format to native Date object
+ *
+ * Strict parser that validates format and creates Date from structured date strings.
+ * Supports 12 common date formats with validation.
+ *
+ * @param dateString - Date string to parse
+ * @param format - Expected format (DD/MM/YYYY, YYYY-MM-DD, etc.)
+ * @returns Date object or null if invalid
+ *
+ * @example
+ * ```typescript
+ * toDateFromString('15/03/2024', 'DD/MM/YYYY')  // Date object
+ * toDateFromString('2024-03-15', 'YYYY-MM-DD')  // Date object
+ * toDateFromString('invalid', 'DD/MM/YYYY')     // null
+ * ```
+ *
+ * @see {@link format} for formatting dates
+ */
+declare const toDateFromString: (dateString: string, format: DateStringFormat) => Date | null;
+/**
+ * Returns current date
+ */
+declare const now: () => Date;
+/**
+ * Checks if date is considered "new" based on days threshold
+ */
+declare const isNew: (value: any, daysnew?: number) => boolean;
+/**
+ * Converts date to ISO 8601 string (YYYY-MM-DDTHH:mm:ss.sssZ)
+ *
+ * Standard ISO format for API communication and storage.
+ *
+ * @param value - Date to convert (null = now)
+ * @param isUtc - Force UTC timezone (default: false, uses local)
+ * @returns ISO 8601 formatted string
+ *
+ * @example
+ * ```typescript
+ * toISO()  // "2024-03-15T10:30:00.000+01:00" (now, local time)
+ * toISO(new Date('2024-03-15'))  // "2024-03-15T00:00:00.000+01:00"
+ * toISO(new Date('2024-03-15'), true)  // "2024-03-14T23:00:00.000Z" (UTC)
+ * ```
+ */
+declare const toISO: (value?: any, isUtc?: boolean) => string;
+/**
+ * Returns relative time from now in Spanish (e.g., "hace 2 horas")
+ *
+ * @param value - Date to compare with now
+ * @returns Relative time string in Spanish
+ *
+ * @example
+ * ```typescript
+ * const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000)
+ * fromNow(twoHoursAgo)  // "hace 2 horas"
+ * ```
+ */
+declare const fromNow: (value: any) => string;
+/**
+ * Returns day of week (0-6, Sunday is 0)
+ */
+declare const dayOfWeek: (value?: any) => string;
+/**
+ * Returns week of year with zero padding
+ */
+declare const weekOfYear: (value?: any) => string;
+/**
+ * Calculates difference in days between two dates
+ */
+declare const diffDays: (start: any, end?: any, precise?: boolean) => number;
+/**
+ * Calculates difference in business days (weekdays only, excludes weekends)
+ *
+ * Counts Mon-Fri between two dates, excluding Saturdays and Sundays.
+ * Does NOT account for holidays.
+ *
+ * @param start - Start date
+ * @param end - End date (null = now)
+ * @param precise - Include fractional days (default: false)
+ * @returns Number of business days (Mon-Fri)
+ *
+ * @example
+ * ```typescript
+ * // Monday to Friday (same week)
+ * diffBusinessDays('2024-03-11', '2024-03-15')  // 4 business days
+ *
+ * // Including weekend (skip Sat/Sun)
+ * diffBusinessDays('2024-03-15', '2024-03-18')  // 1 (Fri to Mon)
+ *
+ * // Real-world: SLA calculation
+ * const ticketCreated = new Date('2024-03-11')
+ * const businessDays = diffBusinessDays(ticketCreated)
+ * if (businessDays > 5) {
+ *   console.log('⚠️ SLA violation: > 5 business days')
+ * }
+ * ```
+ */
+declare const diffBusinessDays: (start: any, end?: any, precise?: boolean) => number;
+/**
+ * Calculates difference in months between two dates
+ */
+declare const diffMonths: (value: any, valueRefOrNow?: any, precise?: boolean) => number;
+/**
+ * Calculates difference in years between two dates
+ */
+declare const diffYears: (value: any, valueRefOrNow?: any, precise?: boolean) => number;
+/**
+ * Calculates difference in milliseconds between two dates
+ */
+declare const diffMilliSeconds: (value: any, valueRefOrNow?: any) => number;
+/**
+ * Adds days to a date
+ */
+declare const addDays: (value: any, nDays?: number) => Date;
+/**
+ * Adds seconds to a date
+ */
+declare const addSeconds: (value: any, nSeconds?: number) => Date;
+/**
+ * Compares two dates with ± 2 seconds tolerance
+ */
+declare const areDatesEqualWithTolerance: (date1: Date, date2: Date) => boolean;
+/**
+ * Adds days to current date
+ */
+declare const addNowDays: (nDays?: number) => Date;
+/**
+ * Adds seconds to current date
+ */
+declare const addNowSeconds: (nSeconds?: number) => Date;
+/**
+ * Adds months to a date
+ */
+declare const addMonths: (value: any, nMonths?: number) => Date;
+/**
+ * Adds months to current date
+ */
+declare const addNowMonths: (nMonths?: number) => Date;
+/**
+ * Adds years to a date
+ */
+declare const addYears: (value: any, nYears?: number) => Date;
+/**
+ * Adds years to current date
+ */
+declare const addNowYears: (nYears?: number) => Date;
+/**
+ * Converts Excel serial number to Date
+ * JavaScript dates can be constructed by passing milliseconds since Unix epoch
+ */
+declare const excelToDate: (value: any) => Date | null;
+/**
+ * Detects if a variable contains a valid date
+ */
+declare const isDateTime: (value: any) => boolean;
+/**
+ * Compares dates by day
+ */
+declare const isEqualsDateTimeByDay: (value1: any, value2: any) => boolean;
+/**
+ * Checks if a date has expired relative to current time
+ */
+declare const isExpired: (value: any, valueRefOrNow?: any) => boolean;
+/**
+ * Formats date for MySQL database
+ */
+declare const formatForMysql: (fecha: Date | null) => string | null;
+/**
+ * Gets first workday of month
+ */
+declare const getFirstWorkdayOfMonth: (month?: number) => Date;
+/**
+ * Gets last workday of month
+ */
+declare const getLastWorkdayOfMonth: (month?: number) => Date;
+/**
+ * Gets first workday after adding specified months
+ */
+declare const getFirstWorkdayAfterMonths: (initialDate: Date, n: number) => Date;
+/**
+ * Gets first day of current year
+ */
+declare const getFirstDayOfYear: () => Date;
+/**
+ * Gets last day of current year
+ */
+declare const getLastDayOfYear: () => Date;
+/**
+ * Checks if date is a weekday (not Saturday or Sunday)
+ */
+declare const isWeekday: (date: any) => boolean;
+
+declare const dates_addDays: typeof addDays;
+declare const dates_addMonths: typeof addMonths;
+declare const dates_addNowDays: typeof addNowDays;
+declare const dates_addNowMonths: typeof addNowMonths;
+declare const dates_addNowSeconds: typeof addNowSeconds;
+declare const dates_addNowYears: typeof addNowYears;
+declare const dates_addSeconds: typeof addSeconds;
+declare const dates_addYears: typeof addYears;
+declare const dates_areDatesEqualWithTolerance: typeof areDatesEqualWithTolerance;
+declare const dates_dayOfWeek: typeof dayOfWeek;
+declare const dates_diffBusinessDays: typeof diffBusinessDays;
+declare const dates_diffDays: typeof diffDays;
+declare const dates_diffMilliSeconds: typeof diffMilliSeconds;
+declare const dates_diffMonths: typeof diffMonths;
+declare const dates_diffYears: typeof diffYears;
+declare const dates_excelToDate: typeof excelToDate;
+declare const dates_format: typeof format;
+declare const dates_formatForMysql: typeof formatForMysql;
+declare const dates_formatNow: typeof formatNow;
+declare const dates_fromNow: typeof fromNow;
+declare const dates_getFirstDayOfYear: typeof getFirstDayOfYear;
+declare const dates_getFirstWorkdayAfterMonths: typeof getFirstWorkdayAfterMonths;
+declare const dates_getFirstWorkdayOfMonth: typeof getFirstWorkdayOfMonth;
+declare const dates_getLastDayOfYear: typeof getLastDayOfYear;
+declare const dates_getLastWorkdayOfMonth: typeof getLastWorkdayOfMonth;
+declare const dates_isDateTime: typeof isDateTime;
+declare const dates_isEqualsDateTimeByDay: typeof isEqualsDateTimeByDay;
+declare const dates_isExpired: typeof isExpired;
+declare const dates_isNew: typeof isNew;
+declare const dates_isWeekday: typeof isWeekday;
+declare const dates_longString: typeof longString;
+declare const dates_now: typeof now;
+declare const dates_toDate: typeof toDate;
+declare const dates_toDateFromString: typeof toDateFromString;
+declare const dates_toISO: typeof toISO;
+declare const dates_weekOfYear: typeof weekOfYear;
+declare namespace dates {
+  export { dates_addDays as addDays, dates_addMonths as addMonths, dates_addNowDays as addNowDays, dates_addNowMonths as addNowMonths, dates_addNowSeconds as addNowSeconds, dates_addNowYears as addNowYears, dates_addSeconds as addSeconds, dates_addYears as addYears, dates_areDatesEqualWithTolerance as areDatesEqualWithTolerance, dates_dayOfWeek as dayOfWeek, dates_diffBusinessDays as diffBusinessDays, dates_diffDays as diffDays, dates_diffMilliSeconds as diffMilliSeconds, dates_diffMonths as diffMonths, dates_diffYears as diffYears, dates_excelToDate as excelToDate, dates_format as format, dates_formatForMysql as formatForMysql, dates_formatNow as formatNow, dates_fromNow as fromNow, dates_getFirstDayOfYear as getFirstDayOfYear, dates_getFirstWorkdayAfterMonths as getFirstWorkdayAfterMonths, dates_getFirstWorkdayOfMonth as getFirstWorkdayOfMonth, dates_getLastDayOfYear as getLastDayOfYear, dates_getLastWorkdayOfMonth as getLastWorkdayOfMonth, dates_isDateTime as isDateTime, dates_isEqualsDateTimeByDay as isEqualsDateTimeByDay, dates_isExpired as isExpired, dates_isNew as isNew, dates_isWeekday as isWeekday, dates_longString as longString, dates_now as now, dates_toDate as toDate, dates_toDateFromString as toDateFromString, dates_toISO as toISO, dates_weekOfYear as weekOfYear };
+}
+
+export { excelToDate as A, isDateTime as B, isEqualsDateTimeByDay as C, isExpired as D, formatForMysql as E, getFirstWorkdayOfMonth as F, getLastWorkdayOfMonth as G, getFirstWorkdayAfterMonths as H, getFirstDayOfYear as I, getLastDayOfYear as J, isWeekday as K, format as a, toDateFromString as b, toISO as c, dates as d, fromNow as e, formatNow as f, dayOfWeek as g, diffDays as h, isNew as i, diffBusinessDays as j, diffMonths as k, longString as l, diffYears as m, now as n, diffMilliSeconds as o, addDays as p, addSeconds as q, areDatesEqualWithTolerance as r, addNowDays as s, toDate as t, addNowSeconds as u, addMonths as v, weekOfYear as w, addNowMonths as x, addYears as y, addNowYears as z };

package/dist/types/dates.d.ts

@@ -0,0 +1 @@
+export { p as addDays, v as addMonths, s as addNowDays, x as addNowMonths, u as addNowSeconds, z as addNowYears, q as addSeconds, y as addYears, r as areDatesEqualWithTolerance, g as dayOfWeek, j as diffBusinessDays, h as diffDays, o as diffMilliSeconds, k as diffMonths, m as diffYears, A as excelToDate, a as format, E as formatForMysql, f as formatNow, e as fromNow, I as getFirstDayOfYear, H as getFirstWorkdayAfterMonths, F as getFirstWorkdayOfMonth, J as getLastDayOfYear, G as getLastWorkdayOfMonth, B as isDateTime, C as isEqualsDateTimeByDay, D as isExpired, i as isNew, K as isWeekday, l as longString, n as now, t as toDate, b as toDateFromString, c as toISO, w as weekOfYear } from './dates-hTiE0Z11.js';