@catbee/utils 0.0.6 → 0.0.7

package/build/esnext/utils/date.utils.js

@@ -0,0 +1,384 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * 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'
+ * ```
+ */
+export function formatDate(date, options = {}) {
+    const { format = 'yyyy-MM-dd', locale, timeZone } = options;
+    const d = date instanceof Date ? date : new Date(date);
+    // Custom formatter for common patterns
+    if (format === 'yyyy-MM-dd') {
+        const yyyy = d.getFullYear();
+        const mm = String(d.getMonth() + 1).padStart(2, '0');
+        const dd = String(d.getDate()).padStart(2, '0');
+        return `${yyyy}-${mm}-${dd}`;
+    }
+    if (format === 'yyyy-MM-dd HH:mm:ss') {
+        const yyyy = d.getFullYear();
+        const mm = String(d.getMonth() + 1).padStart(2, '0');
+        const dd = String(d.getDate()).padStart(2, '0');
+        const HH = String(d.getHours()).padStart(2, '0');
+        const MM = String(d.getMinutes()).padStart(2, '0');
+        const SS = String(d.getSeconds()).padStart(2, '0');
+        return `${yyyy}-${mm}-${dd} ${HH}:${MM}:${SS}`;
+    }
+    if (format === 'relative') {
+        return formatRelativeTime(date);
+    }
+    // Fallback to Intl.DateTimeFormat for other formats
+    return new Intl.DateTimeFormat(locale, {
+        timeZone,
+        year: format.includes('yyyy') || format.includes('y') ? 'numeric' : undefined,
+        month: format.includes('MM') || format.includes('M') ? 'numeric' : undefined,
+        day: format.includes('dd') || format.includes('d') ? 'numeric' : undefined,
+        hour: format.includes('HH') || format.includes('H') ? 'numeric' : undefined,
+        minute: format.includes('mm') || format.includes('m') ? 'numeric' : undefined,
+        second: format.includes('ss') || format.includes('s') ? 'numeric' : undefined,
+        hour12: !format.includes('HH') && !format.includes('H')
+    }).format(d);
+}
+/**
+ * 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
+ */
+export function formatRelativeTime(date, now = new Date(), locale) {
+    const d1 = date instanceof Date ? date : new Date(date);
+    const d2 = now instanceof Date ? now : new Date(now);
+    const diffMs = d1.getTime() - d2.getTime();
+    const diffSecs = Math.round(diffMs / 1000);
+    const diffMins = Math.round(diffSecs / 60);
+    const diffHours = Math.round(diffMins / 60);
+    const diffDays = Math.round(diffHours / 24);
+    const diffMonths = Math.round(diffDays / 30);
+    const diffYears = Math.round(diffDays / 365);
+    const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+    if (Math.abs(diffSecs) < 60)
+        return formatter.format(diffSecs, 'second');
+    if (Math.abs(diffMins) < 60)
+        return formatter.format(diffMins, 'minute');
+    if (Math.abs(diffHours) < 24)
+        return formatter.format(diffHours, 'hour');
+    if (Math.abs(diffDays) < 30)
+        return formatter.format(diffDays, 'day');
+    if (Math.abs(diffMonths) < 12)
+        return formatter.format(diffMonths, 'month');
+    return formatter.format(diffYears, 'year');
+}
+/**
+ * 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
+ * ```
+ */
+export function parseDate(input, fallback) {
+    if (typeof input === 'number') {
+        return new Date(input);
+    }
+    try {
+        const date = new Date(input);
+        // Check if date is valid
+        if (isNaN(date.getTime())) {
+            return fallback || null;
+        }
+        return date;
+    }
+    catch (_a) {
+        return fallback || 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
+ * ```
+ */
+export function dateDiff(date1, date2 = new Date(), unit = 'days') {
+    const d1 = date1 instanceof Date ? date1 : new Date(date1);
+    const d2 = date2 instanceof Date ? date2 : new Date(date2);
+    const diffMs = d1.getTime() - d2.getTime();
+    switch (unit) {
+        case 'milliseconds':
+            return diffMs;
+        case 'seconds':
+            return diffMs / 1000;
+        case 'minutes':
+            return diffMs / (1000 * 60);
+        case 'hours':
+            return diffMs / (1000 * 60 * 60);
+        case 'days':
+            return diffMs / (1000 * 60 * 60 * 24);
+        case 'months':
+            return (d1.getFullYear() - d2.getFullYear()) * 12 + d1.getMonth() - d2.getMonth();
+        case 'years':
+            return d1.getFullYear() - d2.getFullYear();
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+}
+/**
+ * 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
+ * ```
+ */
+export function addToDate(date, amount, unit) {
+    const d = date instanceof Date ? new Date(date) : new Date(date);
+    switch (unit) {
+        case 'milliseconds':
+            d.setMilliseconds(d.getMilliseconds() + amount);
+            break;
+        case 'seconds':
+            d.setSeconds(d.getSeconds() + amount);
+            break;
+        case 'minutes':
+            d.setMinutes(d.getMinutes() + amount);
+            break;
+        case 'hours':
+            d.setHours(d.getHours() + amount);
+            break;
+        case 'days':
+            d.setDate(d.getDate() + amount);
+            break;
+        case 'months': {
+            const origDate = d.getDate();
+            const origMonth = d.getMonth();
+            d.setDate(1); // Prevent overflow
+            d.setMonth(origMonth + amount);
+            const lastDay = new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();
+            d.setDate(Math.min(origDate, lastDay));
+            break;
+        }
+        case 'years':
+            d.setFullYear(d.getFullYear() + amount);
+            break;
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+    return d;
+}
+/**
+ * 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
+ * ```
+ */
+export function startOf(date, unit) {
+    const d = date instanceof Date ? new Date(date) : new Date(date);
+    switch (unit) {
+        case 'second':
+            d.setMilliseconds(0);
+            break;
+        case 'minute':
+            d.setSeconds(0, 0);
+            break;
+        case 'hour':
+            d.setMinutes(0, 0, 0);
+            break;
+        case 'day':
+            d.setHours(0, 0, 0, 0);
+            break;
+        case 'week':
+            d.setHours(0, 0, 0, 0);
+            d.setDate(d.getDate() - d.getDay());
+            break;
+        case 'month':
+            d.setDate(1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        case 'quarter':
+            d.setMonth(Math.floor(d.getMonth() / 3) * 3, 1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        case 'year':
+            d.setMonth(0, 1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+    return d;
+}
+/**
+ * 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
+ * ```
+ */
+export function endOf(date, unit) {
+    const d = date instanceof Date ? new Date(date) : new Date(date);
+    switch (unit) {
+        case 'second':
+            d.setMilliseconds(999);
+            break;
+        case 'minute':
+            d.setSeconds(59, 999);
+            break;
+        case 'hour':
+            d.setMinutes(59, 59, 999);
+            break;
+        case 'day':
+            d.setHours(23, 59, 59, 999);
+            break;
+        case 'week':
+            d.setDate(d.getDate() - d.getDay() + 6);
+            d.setHours(23, 59, 59, 999);
+            break;
+        case 'month':
+            d.setMonth(d.getMonth() + 1, 0);
+            d.setHours(23, 59, 59, 999);
+            break;
+        case 'quarter':
+            d.setMonth(Math.floor(d.getMonth() / 3) * 3 + 3, 0);
+            d.setHours(23, 59, 59, 999);
+            break;
+        case 'year':
+            d.setMonth(11, 31);
+            d.setHours(23, 59, 59, 999);
+            break;
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+    return d;
+}
+/**
+ * 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
+ * ```
+ */
+export function isBetween(date, start, end, inclusive = true) {
+    const d = date instanceof Date ? date.getTime() : date;
+    const s = start instanceof Date ? start.getTime() : start;
+    const e = end instanceof Date ? end.getTime() : end;
+    return inclusive ? d >= s && d <= e : d > s && d < e;
+}
+/**
+ * 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
+ */
+export function isLeapYear(year) {
+    const y = year instanceof Date ? year.getFullYear() : year;
+    return (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+}
+/**
+ * Get the number of days in a month.
+ *
+ * @param year - Year
+ * @param month - Month (0-11)
+ * @returns Number of days in the month
+ */
+export function daysInMonth(year, month) {
+    if (year instanceof Date) {
+        month = year.getMonth();
+        year = year.getFullYear();
+    }
+    if (month === undefined) {
+        throw new Error('Month is required when year is a number');
+    }
+    return new Date(year, month + 1, 0).getDate();
+}
+//# sourceMappingURL=date.utils.js.map

package/build/esnext/utils/date.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.utils.js","sourceRoot":"","sources":["../../../src/utils/date.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Format options for the formatDate function\n */\nexport interface DateFormatOptions {\n  /** Date format pattern (default: 'yyyy-MM-dd') */\n  format?: string;\n  /** Locale to use for formatting (default: system locale) */\n  locale?: string | string[];\n  /** Time zone to use (default: system time zone) */\n  timeZone?: string;\n}\n\n/**\n * Format a date according to the specified format pattern.\n *\n * @param date - Date to format\n * @param options - Formatting options\n * @returns Formatted date string\n *\n * @example\n * ```typescript\n * // Format as ISO date\n * formatDate(new Date(), { format: 'yyyy-MM-dd' }); // '2023-05-15'\n *\n * // Format with time\n * formatDate(new Date(), { format: 'yyyy-MM-dd HH:mm:ss' }); // '2023-05-15 14:30:22'\n *\n * // Format with locale\n * formatDate(new Date(), { format: 'PPPP', locale: 'fr-FR' }); // 'lundi 15 mai 2023'\n * ```\n */\nexport function formatDate(date: Date | number, options: DateFormatOptions = {}): string {\n  const { format = 'yyyy-MM-dd', locale, timeZone } = options;\n  const d = date instanceof Date ? date : new Date(date);\n\n  // Custom formatter for common patterns\n  if (format === 'yyyy-MM-dd') {\n    const yyyy = d.getFullYear();\n    const mm = String(d.getMonth() + 1).padStart(2, '0');\n    const dd = String(d.getDate()).padStart(2, '0');\n    return `${yyyy}-${mm}-${dd}`;\n  }\n  if (format === 'yyyy-MM-dd HH:mm:ss') {\n    const yyyy = d.getFullYear();\n    const mm = String(d.getMonth() + 1).padStart(2, '0');\n    const dd = String(d.getDate()).padStart(2, '0');\n    const HH = String(d.getHours()).padStart(2, '0');\n    const MM = String(d.getMinutes()).padStart(2, '0');\n    const SS = String(d.getSeconds()).padStart(2, '0');\n    return `${yyyy}-${mm}-${dd} ${HH}:${MM}:${SS}`;\n  }\n  if (format === 'relative') {\n    return formatRelativeTime(date);\n  }\n\n  // Fallback to Intl.DateTimeFormat for other formats\n  return new Intl.DateTimeFormat(locale, {\n    timeZone,\n    year: format.includes('yyyy') || format.includes('y') ? 'numeric' : undefined,\n    month: format.includes('MM') || format.includes('M') ? 'numeric' : undefined,\n    day: format.includes('dd') || format.includes('d') ? 'numeric' : undefined,\n    hour: format.includes('HH') || format.includes('H') ? 'numeric' : undefined,\n    minute: format.includes('mm') || format.includes('m') ? 'numeric' : undefined,\n    second: format.includes('ss') || format.includes('s') ? 'numeric' : undefined,\n    hour12: !format.includes('HH') && !format.includes('H')\n  }).format(d);\n}\n\n/**\n * Format a date as relative time (e.g., \"5 minutes ago\", \"in 3 days\").\n *\n * @param date - Date to format\n * @param now - Reference date (default: current time)\n * @param locale - Locale to use for formatting\n * @returns Formatted relative time string\n */\nexport function formatRelativeTime(\n  date: Date | number,\n  now: Date | number = new Date(),\n  locale?: string | string[]\n): string {\n  const d1 = date instanceof Date ? date : new Date(date);\n  const d2 = now instanceof Date ? now : new Date(now);\n\n  const diffMs = d1.getTime() - d2.getTime();\n  const diffSecs = Math.round(diffMs / 1000);\n  const diffMins = Math.round(diffSecs / 60);\n  const diffHours = Math.round(diffMins / 60);\n  const diffDays = Math.round(diffHours / 24);\n  const diffMonths = Math.round(diffDays / 30);\n  const diffYears = Math.round(diffDays / 365);\n\n  const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });\n\n  if (Math.abs(diffSecs) < 60) return formatter.format(diffSecs, 'second');\n  if (Math.abs(diffMins) < 60) return formatter.format(diffMins, 'minute');\n  if (Math.abs(diffHours) < 24) return formatter.format(diffHours, 'hour');\n  if (Math.abs(diffDays) < 30) return formatter.format(diffDays, 'day');\n  if (Math.abs(diffMonths) < 12) return formatter.format(diffMonths, 'month');\n  return formatter.format(diffYears, 'year');\n}\n\n/**\n * Parse a date string or timestamp into a Date object.\n *\n * @param input - Date string or timestamp to parse\n * @param fallback - Fallback date if parsing fails\n * @returns Parsed Date object or fallback\n *\n * @example\n * ```typescript\n * parseDate('2023-05-15'); // Date object for May 15, 2023\n * parseDate('invalid', new Date()); // Returns current date as fallback\n * ```\n */\nexport function parseDate(input: string | number, fallback?: Date): Date | null {\n  if (typeof input === 'number') {\n    return new Date(input);\n  }\n\n  try {\n    const date = new Date(input);\n    // Check if date is valid\n    if (isNaN(date.getTime())) {\n      return fallback || null;\n    }\n    return date;\n  } catch {\n    return fallback || null;\n  }\n}\n\n/**\n * Calculate the difference between two dates in the specified unit.\n *\n * @param date1 - First date\n * @param date2 - Second date (default: current time)\n * @param unit - Unit of time for the difference\n * @returns Difference in the specified unit\n *\n * @example\n * ```typescript\n * // Get difference in days\n * dateDiff(new Date('2023-05-15'), new Date('2023-05-10'), 'days'); // 5\n *\n * // Get difference in hours\n * dateDiff(new Date('2023-05-15T10:00:00'), new Date('2023-05-15T06:00:00'), 'hours'); // 4\n * ```\n */\nexport function dateDiff(\n  date1: Date | number,\n  date2: Date | number = new Date(),\n  unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years' = 'days'\n): number {\n  const d1 = date1 instanceof Date ? date1 : new Date(date1);\n  const d2 = date2 instanceof Date ? date2 : new Date(date2);\n\n  const diffMs = d1.getTime() - d2.getTime();\n\n  switch (unit) {\n    case 'milliseconds':\n      return diffMs;\n    case 'seconds':\n      return diffMs / 1000;\n    case 'minutes':\n      return diffMs / (1000 * 60);\n    case 'hours':\n      return diffMs / (1000 * 60 * 60);\n    case 'days':\n      return diffMs / (1000 * 60 * 60 * 24);\n    case 'months':\n      return (d1.getFullYear() - d2.getFullYear()) * 12 + d1.getMonth() - d2.getMonth();\n    case 'years':\n      return d1.getFullYear() - d2.getFullYear();\n    default:\n      throw new Error(`Unsupported unit: ${unit}`);\n  }\n}\n\n/**\n * Add a specified amount of time to a date.\n *\n * @param date - Base date\n * @param amount - Amount to add (can be negative)\n * @param unit - Unit of time to add\n * @returns New date with the addition\n *\n * @example\n * ```typescript\n * // Add 5 days\n * addToDate(new Date('2023-05-15'), 5, 'days'); // Date for May 20, 2023\n *\n * // Subtract 2 hours\n * addToDate(new Date('2023-05-15T10:00:00'), -2, 'hours'); // Date for May 15, 2023 08:00:00\n * ```\n */\nexport function addToDate(\n  date: Date | number,\n  amount: number,\n  unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'\n): Date {\n  const d = date instanceof Date ? new Date(date) : new Date(date);\n\n  switch (unit) {\n    case 'milliseconds':\n      d.setMilliseconds(d.getMilliseconds() + amount);\n      break;\n    case 'seconds':\n      d.setSeconds(d.getSeconds() + amount);\n      break;\n    case 'minutes':\n      d.setMinutes(d.getMinutes() + amount);\n      break;\n    case 'hours':\n      d.setHours(d.getHours() + amount);\n      break;\n    case 'days':\n      d.setDate(d.getDate() + amount);\n      break;\n    case 'months': {\n      const origDate = d.getDate();\n      const origMonth = d.getMonth();\n      d.setDate(1); // Prevent overflow\n      d.setMonth(origMonth + amount);\n      const lastDay = new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();\n      d.setDate(Math.min(origDate, lastDay));\n      break;\n    }\n    case 'years':\n      d.setFullYear(d.getFullYear() + amount);\n      break;\n    default:\n      throw new Error(`Unsupported unit: ${unit}`);\n  }\n\n  return d;\n}\n\n/**\n * Get the start of a time period containing the specified date.\n *\n * @param date - Date to get the start from\n * @param unit - Time unit\n * @returns Date object representing the start of the time unit\n *\n * @example\n * ```typescript\n * // Get start of day (midnight)\n * startOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 00:00:00\n *\n * // Get start of month\n * startOf(new Date('2023-05-15'), 'month'); // Date for May 1, 2023\n * ```\n */\nexport function startOf(\n  date: Date | number,\n  unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'\n): Date {\n  const d = date instanceof Date ? new Date(date) : new Date(date);\n\n  switch (unit) {\n    case 'second':\n      d.setMilliseconds(0);\n      break;\n    case 'minute':\n      d.setSeconds(0, 0);\n      break;\n    case 'hour':\n      d.setMinutes(0, 0, 0);\n      break;\n    case 'day':\n      d.setHours(0, 0, 0, 0);\n      break;\n    case 'week':\n      d.setHours(0, 0, 0, 0);\n      d.setDate(d.getDate() - d.getDay());\n      break;\n    case 'month':\n      d.setDate(1);\n      d.setHours(0, 0, 0, 0);\n      break;\n    case 'quarter':\n      d.setMonth(Math.floor(d.getMonth() / 3) * 3, 1);\n      d.setHours(0, 0, 0, 0);\n      break;\n    case 'year':\n      d.setMonth(0, 1);\n      d.setHours(0, 0, 0, 0);\n      break;\n    default:\n      throw new Error(`Unsupported unit: ${unit}`);\n  }\n\n  return d;\n}\n\n/**\n * Get the end of a time period containing the specified date.\n *\n * @param date - Date to get the end from\n * @param unit - Time unit\n * @returns Date object representing the end of the time unit\n *\n * @example\n * ```typescript\n * // Get end of day (23:59:59.999)\n * endOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 23:59:59.999\n *\n * // Get end of month\n * endOf(new Date('2023-05-15'), 'month'); // Date for May 31, 2023 23:59:59.999\n * ```\n */\nexport function endOf(\n  date: Date | number,\n  unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'\n): Date {\n  const d = date instanceof Date ? new Date(date) : new Date(date);\n\n  switch (unit) {\n    case 'second':\n      d.setMilliseconds(999);\n      break;\n    case 'minute':\n      d.setSeconds(59, 999);\n      break;\n    case 'hour':\n      d.setMinutes(59, 59, 999);\n      break;\n    case 'day':\n      d.setHours(23, 59, 59, 999);\n      break;\n    case 'week':\n      d.setDate(d.getDate() - d.getDay() + 6);\n      d.setHours(23, 59, 59, 999);\n      break;\n    case 'month':\n      d.setMonth(d.getMonth() + 1, 0);\n      d.setHours(23, 59, 59, 999);\n      break;\n    case 'quarter':\n      d.setMonth(Math.floor(d.getMonth() / 3) * 3 + 3, 0);\n      d.setHours(23, 59, 59, 999);\n      break;\n    case 'year':\n      d.setMonth(11, 31);\n      d.setHours(23, 59, 59, 999);\n      break;\n    default:\n      throw new Error(`Unsupported unit: ${unit}`);\n  }\n\n  return d;\n}\n\n/**\n * Check if a date is between two other dates.\n *\n * @param date - Date to check\n * @param start - Start date of the range\n * @param end - End date of the range\n * @param inclusive - Whether the comparison should be inclusive of start/end\n * @returns True if the date is within the range\n *\n * @example\n * ```typescript\n * const date = new Date('2023-05-15');\n * const start = new Date('2023-05-10');\n * const end = new Date('2023-05-20');\n *\n * isBetween(date, start, end); // true\n * ```\n */\nexport function isBetween(\n  date: Date | number,\n  start: Date | number,\n  end: Date | number,\n  inclusive: boolean = true\n): boolean {\n  const d = date instanceof Date ? date.getTime() : date;\n  const s = start instanceof Date ? start.getTime() : start;\n  const e = end instanceof Date ? end.getTime() : end;\n\n  return inclusive ? d >= s && d <= e : d > s && d < e;\n}\n\n/**\n * Check if a year is a leap year.\n *\n * @param year - Year to check (or date object)\n * @returns True if the year is a leap year\n */\nexport function isLeapYear(year: number | Date): boolean {\n  const y = year instanceof Date ? year.getFullYear() : year;\n  return (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;\n}\n\n/**\n * Get the number of days in a month.\n *\n * @param year - Year\n * @param month - Month (0-11)\n * @returns Number of days in the month\n */\nexport function daysInMonth(year: number | Date, month?: number): number {\n  if (year instanceof Date) {\n    month = year.getMonth();\n    year = year.getFullYear();\n  }\n\n  if (month === undefined) {\n    throw new Error('Month is required when year is a number');\n  }\n\n  return new Date(year, month + 1, 0).getDate();\n}\n"]}

package/build/esnext/utils/logger.utils.d.ts

@@ -129,16 +129,10 @@ export declare const _globalThis: typeof globalThis;
  */
 export declare function getLogger(): PinoLogger;
 /**
- * Alias for the current logger instance.
- * - Returns a request-scoped logger from AsyncLocalStorage if available
- * - Falls back to the global (singleton) logger
- * - Initializes the global logger if not created yet
- */
-export declare const logger: typeof getLogger;
-/**
- * Global logger instance.
+ * Logger instance for the global context.
+ * This logger is used for logging messages that are not tied to a specific request.
  */
-export declare const globalLogger: PinoLogger;
+export declare const logger: PinoLogger;
 /**
  * Creates a child logger with additional context.
  *

package/build/esnext/utils/logger.utils.js

@@ -251,16 +251,10 @@ export function getLogger() {
     return _global[GLOBAL_LOGGER_KEY];
 }
 /**
- * Alias for the current logger instance.
- * - Returns a request-scoped logger from AsyncLocalStorage if available
- * - Falls back to the global (singleton) logger
- * - Initializes the global logger if not created yet
- */
-export const logger = getLogger;
-/**
- * Global logger instance.
+ * Logger instance for the global context.
+ * This logger is used for logging messages that are not tied to a specific request.
  */
-export const globalLogger = getLogger();
+export const logger = getLogger();
 /**
  * Creates a child logger with additional context.
  *

package/build/esnext/utils/logger.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport pino, { LoggerOptions, stdTimeFunctions } from 'pino';\nimport type { Logger as PinoLogger } from 'pino'; // Type-only import\nimport { config } from '../config';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { Env } from './env.utils';\n\n/**\n * Symbol used to store the root logger in the Node.js global object.\n */\nconst GLOBAL_LOGGER_KEY = Symbol.for('logger');\n\n/**\n * Logger type for application-wide logging.\n */\nexport type Logger = pino.Logger;\n\n/**\n * Logger levels for application-wide logging.\n */\nexport type LoggerLevels = pino.Level;\n\n// Default sensitive fields\nexport const defaultSensitiveFields = [\n  'password',\n  'secret',\n  'token',\n  'apiKey',\n  'api_key',\n  'auth',\n  'jwt',\n  'access_token',\n  'client_secret',\n  'session_token',\n  'refresh_token'\n];\n\n/**\n * The global censor function used by the logger.\n */\nlet globalRedactCensor: (value: unknown, path: string[], sensitiveFields?: string[]) => string = (\n  value,\n  path,\n  sensitiveFields = defaultSensitiveFields\n) => {\n  if (typeof value !== 'string') return '***';\n\n  const lowerPath = path.map(p => p.toLowerCase());\n  const lowerSensitiveFields = sensitiveFields.map(f => f.toLowerCase());\n\n  if (lowerPath.some(p => lowerSensitiveFields.includes(p))) return '***';\n\n  // Redact URLs\n  if (lowerPath[0] === 'url') {\n    return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join('|')})=)[^&#]*`, 'gi'), '$1***');\n  }\n\n  if (lowerPath.some(p => p.includes('authorization') || p.includes('auth'))) {\n    return value.replace(/^(\\S+)\\s+.+$/, '$1 ***') || '***';\n  }\n\n  // Redact sensitive fields - check each path segment against each sensitive field\n  if (lowerPath.some(pathPart => lowerSensitiveFields.some(field => pathPart.includes(field)))) {\n    return '***';\n  }\n\n  if (path.length > 0 && !['req', 'res', 'headers'].includes(lowerPath[0])) {\n    return value;\n  }\n\n  return value;\n};\n\n/**\n * Sets the global redaction censor function used throughout the application for log redaction.\n *\n * Use this function to customize how sensitive data is redacted in logs. The provided function\n * will replace the default censor implementation.\n *\n * @example\n * ```typescript\n * // Custom censor that redacts only specific values\n * setRedactCensor((value, path, sensitiveFields) => {\n *   if (path.includes('password')) return '***';\n *   return value;\n * });\n * ```\n *\n * @param fn - The redaction censor function to use globally. This function receives:\n *   - value: The data value to potentially redact\n *   - path: Array of strings representing the path to the value in the object\n *   - sensitiveFields: Optional array of field names to consider sensitive\n * @returns void\n */\nexport function setRedactCensor(fn: (value: unknown, path: string[], sensitiveFields?: string[]) => string) {\n  globalRedactCensor = fn;\n}\n\n/**\n * Gets the current global redaction censor function used for log redaction.\n *\n * This function is called internally by the logger when determining how to redact\n * sensitive information. It can also be used to access the current censor implementation\n * for composition or extension.\n *\n * @example\n * ```typescript\n * const currentCensor = getRedactCensor();\n * // Create an enhanced censor that extends the current one\n * setRedactCensor((value, path, fields) => {\n *   // Add custom logic before delegating to current censor\n *   if (someCondition) return customHandling();\n *   return currentCensor(value, path, fields);\n * });\n * ```\n *\n * @returns The current redaction censor function\n */\nexport function getRedactCensor() {\n  return globalRedactCensor;\n}\n\n/**\n * Convenience function to redact sensitive data using the current global redact censor.\n *\n * This is a direct wrapper around the global censor function that simplifies usage\n * in application code without needing to access the censor function directly.\n *\n * @example\n * ```typescript\n * // Redact a potential sensitive value\n * const safeValue = redact(value, ['user', 'apiKey']);\n * ```\n *\n * @param value - The value to potentially redact\n * @param path - Array of strings representing the path to the value in the object\n * @param sensitiveFields - Optional array of field names to consider sensitive\n * @returns The redacted string value or \"***\" for redacted content\n */\nexport function redact(value: unknown, path: string[], sensitiveFields?: string[]) {\n  return globalRedactCensor(value, path, sensitiveFields);\n}\n\n/**\n * Extends the current redaction function with additional fields to redact.\n *\n * This function wraps the existing censor while adding more fields to be considered\n * sensitive without replacing the entire redaction logic.\n *\n * @example\n * ```typescript\n * // Add custom fields to be redacted in all future redaction operations\n * addRedactFields(['customerId', 'accountNumber']);\n * ```\n *\n * @param fields - Array of additional field names to redact\n */\nexport function addRedactFields(fields: string[]) {\n  const prev = globalRedactCensor;\n  globalRedactCensor = (value, path, sensitiveFields = defaultSensitiveFields) =>\n    prev(value, path, [...(sensitiveFields || []), ...fields]);\n}\n\n/**\n * Replaces the default list of sensitive fields with a new list.\n *\n * This is useful when you want complete control over what fields are considered\n * sensitive by default, rather than using the library's built-in list.\n *\n * @example\n * ```typescript\n * // Replace default sensitive fields with a custom list\n * setSensitiveFields(['password', 'ssn', 'creditCard']);\n * ```\n *\n * @param fields - Array of field names to set as the new default sensitive fields\n */\nexport function setSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);\n}\n\n/**\n * Adds additional field names to the default sensitive fields list.\n *\n * This preserves the existing sensitive fields while adding new ones for\n * application-specific sensitive data.\n *\n * @example\n * ```typescript\n * // Add domain-specific sensitive fields to the default list\n * addSensitiveFields(['socialSecurityNumber', 'medicalRecordNumber']);\n * ```\n *\n * @param fields - Array of additional field names to add to the sensitive fields list\n */\nexport function addSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.push(...fields);\n}\n\n/**\n * Use an object compatible with either modern or legacy global scopes.\n */\nexport const _globalThis = typeof globalThis === 'object' ? globalThis : global;\nconst _global = _globalThis as unknown as { [GLOBAL_LOGGER_KEY]: PinoLogger };\n\n/**\n * Initializes the global root logger according to app configuration.\n *\n * - Sets log name, level, timestamp, and redaction for sensitive fields.\n * - Uses singleton in global symbol registry.\n */\nfunction setupLogger(): void {\n  const logParams: LoggerOptions = {\n    name: config.logger.name || '@catbee/utils',\n    level: config.logger.level || 'info',\n    redact: {\n      paths: ['req.authorization', 'res.authorization', 'url', 'headers.authorization', 'headers.cookies'],\n      censor: (value, path) => redact(value, path)\n    },\n    // serializers: {\n    //   req: pino.stdSerializers.req,\n    //   request: pino.stdSerializers.req,\n    //   res: pino.stdSerializers.res,\n    //   response: pino.stdSerializers.res,\n    //   err: pino.stdSerializers.err,\n    //   error: pino.stdSerializers.err\n    // },\n    timestamp: stdTimeFunctions.isoTime\n  };\n\n  const logger =\n    config.logger.pretty && Env.isDev()\n      ? pino(\n          logParams,\n          pino.transport({\n            target: 'pino-pretty',\n            options: {\n              colorize: true,\n              translateTime: 'SYS:standard',\n              ignore: 'pid,hostname',\n              singleLine: config.logger.singleLine,\n              levelFirst: true\n            }\n          })\n        )\n      : pino(logParams);\n\n  _global[GLOBAL_LOGGER_KEY] = logger;\n  _global[GLOBAL_LOGGER_KEY]?.debug('Logger initialized');\n}\n\n/**\n * Retrieves the current logger instance:\n * - Returns a request-scoped logger from AsyncLocalStorage if available\n * - Falls back to the global (singleton) logger\n * - Initializes the global logger if not created yet\n *\n * @returns {Logger} The logger instance (request-bound or global root logger)\n */\nexport function getLogger(): PinoLogger {\n  const logger = ContextStore.get<PinoLogger>(StoreKeys.LOGGER);\n  if (logger) return logger;\n\n  if (!_global[GLOBAL_LOGGER_KEY]) {\n    setupLogger();\n  }\n\n  return _global[GLOBAL_LOGGER_KEY];\n}\n\n/**\n * Alias for the current logger instance.\n * - Returns a request-scoped logger from AsyncLocalStorage if available\n * - Falls back to the global (singleton) logger\n * - Initializes the global logger if not created yet\n */\nexport const logger = getLogger;\n\n/**\n * Global logger instance.\n */\nexport const globalLogger = getLogger();\n\n/**\n * Creates a child logger with additional context.\n *\n * @param {Record<string, any>} bindings - Properties to attach to all log records\n * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)\n * @returns {Logger} Child logger with merged context\n */\nexport function createChildLogger(bindings: Record<string, any>, parentLogger?: PinoLogger): PinoLogger {\n  const logger = parentLogger || getLogger();\n  return logger.child(bindings);\n}\n\n/**\n * Creates a request-scoped logger with request ID and stores it in context\n *\n * @param {string} requestId - Unique request identifier\n * @param {object} [additionalContext] - Additional context to include in logs\n * @returns {Logger} Request-scoped logger instance\n */\nexport function createRequestLogger(requestId: string, additionalContext: Record<string, any> = {}): PinoLogger {\n  const logger = createChildLogger({\n    requestId,\n    ...additionalContext\n  });\n\n  try {\n    ContextStore.set(StoreKeys.LOGGER, logger);\n  } catch {\n    // Context not initialized, can't store logger\n    logger.debug('Failed to store logger in context - AsyncLocalStorage not initialized');\n  }\n\n  return logger;\n}\n\n/**\n * Utility to safely log errors with proper stack trace extraction\n *\n * @param {Error|unknown} error - Error object to log\n * @param {string} [message] - Optional message to include\n * @param {Record<string, any>} [context] - Additional context properties\n */\nexport function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void {\n  const logger = getLogger();\n\n  const errObj = error instanceof Error ? error : new Error(String(error));\n  const logContext = {\n    ...context,\n    error: errObj\n  };\n\n  logger.error(logContext, message || errObj.message);\n}\n"]}
+{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport pino, { LoggerOptions, stdTimeFunctions } from 'pino';\nimport type { Logger as PinoLogger } from 'pino'; // Type-only import\nimport { config } from '../config';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { Env } from './env.utils';\n\n/**\n * Symbol used to store the root logger in the Node.js global object.\n */\nconst GLOBAL_LOGGER_KEY = Symbol.for('logger');\n\n/**\n * Logger type for application-wide logging.\n */\nexport type Logger = pino.Logger;\n\n/**\n * Logger levels for application-wide logging.\n */\nexport type LoggerLevels = pino.Level;\n\n// Default sensitive fields\nexport const defaultSensitiveFields = [\n  'password',\n  'secret',\n  'token',\n  'apiKey',\n  'api_key',\n  'auth',\n  'jwt',\n  'access_token',\n  'client_secret',\n  'session_token',\n  'refresh_token'\n];\n\n/**\n * The global censor function used by the logger.\n */\nlet globalRedactCensor: (value: unknown, path: string[], sensitiveFields?: string[]) => string = (\n  value,\n  path,\n  sensitiveFields = defaultSensitiveFields\n) => {\n  if (typeof value !== 'string') return '***';\n\n  const lowerPath = path.map(p => p.toLowerCase());\n  const lowerSensitiveFields = sensitiveFields.map(f => f.toLowerCase());\n\n  if (lowerPath.some(p => lowerSensitiveFields.includes(p))) return '***';\n\n  // Redact URLs\n  if (lowerPath[0] === 'url') {\n    return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join('|')})=)[^&#]*`, 'gi'), '$1***');\n  }\n\n  if (lowerPath.some(p => p.includes('authorization') || p.includes('auth'))) {\n    return value.replace(/^(\\S+)\\s+.+$/, '$1 ***') || '***';\n  }\n\n  // Redact sensitive fields - check each path segment against each sensitive field\n  if (lowerPath.some(pathPart => lowerSensitiveFields.some(field => pathPart.includes(field)))) {\n    return '***';\n  }\n\n  if (path.length > 0 && !['req', 'res', 'headers'].includes(lowerPath[0])) {\n    return value;\n  }\n\n  return value;\n};\n\n/**\n * Sets the global redaction censor function used throughout the application for log redaction.\n *\n * Use this function to customize how sensitive data is redacted in logs. The provided function\n * will replace the default censor implementation.\n *\n * @example\n * ```typescript\n * // Custom censor that redacts only specific values\n * setRedactCensor((value, path, sensitiveFields) => {\n *   if (path.includes('password')) return '***';\n *   return value;\n * });\n * ```\n *\n * @param fn - The redaction censor function to use globally. This function receives:\n *   - value: The data value to potentially redact\n *   - path: Array of strings representing the path to the value in the object\n *   - sensitiveFields: Optional array of field names to consider sensitive\n * @returns void\n */\nexport function setRedactCensor(fn: (value: unknown, path: string[], sensitiveFields?: string[]) => string) {\n  globalRedactCensor = fn;\n}\n\n/**\n * Gets the current global redaction censor function used for log redaction.\n *\n * This function is called internally by the logger when determining how to redact\n * sensitive information. It can also be used to access the current censor implementation\n * for composition or extension.\n *\n * @example\n * ```typescript\n * const currentCensor = getRedactCensor();\n * // Create an enhanced censor that extends the current one\n * setRedactCensor((value, path, fields) => {\n *   // Add custom logic before delegating to current censor\n *   if (someCondition) return customHandling();\n *   return currentCensor(value, path, fields);\n * });\n * ```\n *\n * @returns The current redaction censor function\n */\nexport function getRedactCensor() {\n  return globalRedactCensor;\n}\n\n/**\n * Convenience function to redact sensitive data using the current global redact censor.\n *\n * This is a direct wrapper around the global censor function that simplifies usage\n * in application code without needing to access the censor function directly.\n *\n * @example\n * ```typescript\n * // Redact a potential sensitive value\n * const safeValue = redact(value, ['user', 'apiKey']);\n * ```\n *\n * @param value - The value to potentially redact\n * @param path - Array of strings representing the path to the value in the object\n * @param sensitiveFields - Optional array of field names to consider sensitive\n * @returns The redacted string value or \"***\" for redacted content\n */\nexport function redact(value: unknown, path: string[], sensitiveFields?: string[]) {\n  return globalRedactCensor(value, path, sensitiveFields);\n}\n\n/**\n * Extends the current redaction function with additional fields to redact.\n *\n * This function wraps the existing censor while adding more fields to be considered\n * sensitive without replacing the entire redaction logic.\n *\n * @example\n * ```typescript\n * // Add custom fields to be redacted in all future redaction operations\n * addRedactFields(['customerId', 'accountNumber']);\n * ```\n *\n * @param fields - Array of additional field names to redact\n */\nexport function addRedactFields(fields: string[]) {\n  const prev = globalRedactCensor;\n  globalRedactCensor = (value, path, sensitiveFields = defaultSensitiveFields) =>\n    prev(value, path, [...(sensitiveFields || []), ...fields]);\n}\n\n/**\n * Replaces the default list of sensitive fields with a new list.\n *\n * This is useful when you want complete control over what fields are considered\n * sensitive by default, rather than using the library's built-in list.\n *\n * @example\n * ```typescript\n * // Replace default sensitive fields with a custom list\n * setSensitiveFields(['password', 'ssn', 'creditCard']);\n * ```\n *\n * @param fields - Array of field names to set as the new default sensitive fields\n */\nexport function setSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);\n}\n\n/**\n * Adds additional field names to the default sensitive fields list.\n *\n * This preserves the existing sensitive fields while adding new ones for\n * application-specific sensitive data.\n *\n * @example\n * ```typescript\n * // Add domain-specific sensitive fields to the default list\n * addSensitiveFields(['socialSecurityNumber', 'medicalRecordNumber']);\n * ```\n *\n * @param fields - Array of additional field names to add to the sensitive fields list\n */\nexport function addSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.push(...fields);\n}\n\n/**\n * Use an object compatible with either modern or legacy global scopes.\n */\nexport const _globalThis = typeof globalThis === 'object' ? globalThis : global;\nconst _global = _globalThis as unknown as { [GLOBAL_LOGGER_KEY]: PinoLogger };\n\n/**\n * Initializes the global root logger according to app configuration.\n *\n * - Sets log name, level, timestamp, and redaction for sensitive fields.\n * - Uses singleton in global symbol registry.\n */\nfunction setupLogger(): void {\n  const logParams: LoggerOptions = {\n    name: config.logger.name || '@catbee/utils',\n    level: config.logger.level || 'info',\n    redact: {\n      paths: ['req.authorization', 'res.authorization', 'url', 'headers.authorization', 'headers.cookies'],\n      censor: (value, path) => redact(value, path)\n    },\n    // serializers: {\n    //   req: pino.stdSerializers.req,\n    //   request: pino.stdSerializers.req,\n    //   res: pino.stdSerializers.res,\n    //   response: pino.stdSerializers.res,\n    //   err: pino.stdSerializers.err,\n    //   error: pino.stdSerializers.err\n    // },\n    timestamp: stdTimeFunctions.isoTime\n  };\n\n  const logger =\n    config.logger.pretty && Env.isDev()\n      ? pino(\n          logParams,\n          pino.transport({\n            target: 'pino-pretty',\n            options: {\n              colorize: true,\n              translateTime: 'SYS:standard',\n              ignore: 'pid,hostname',\n              singleLine: config.logger.singleLine,\n              levelFirst: true\n            }\n          })\n        )\n      : pino(logParams);\n\n  _global[GLOBAL_LOGGER_KEY] = logger;\n  _global[GLOBAL_LOGGER_KEY]?.debug('Logger initialized');\n}\n\n/**\n * Retrieves the current logger instance:\n * - Returns a request-scoped logger from AsyncLocalStorage if available\n * - Falls back to the global (singleton) logger\n * - Initializes the global logger if not created yet\n *\n * @returns {Logger} The logger instance (request-bound or global root logger)\n */\nexport function getLogger(): PinoLogger {\n  const logger = ContextStore.get<PinoLogger>(StoreKeys.LOGGER);\n  if (logger) return logger;\n\n  if (!_global[GLOBAL_LOGGER_KEY]) {\n    setupLogger();\n  }\n\n  return _global[GLOBAL_LOGGER_KEY];\n}\n\n/**\n * Logger instance for the global context.\n * This logger is used for logging messages that are not tied to a specific request.\n */\nexport const logger = getLogger();\n\n/**\n * Creates a child logger with additional context.\n *\n * @param {Record<string, any>} bindings - Properties to attach to all log records\n * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)\n * @returns {Logger} Child logger with merged context\n */\nexport function createChildLogger(bindings: Record<string, any>, parentLogger?: PinoLogger): PinoLogger {\n  const logger = parentLogger || getLogger();\n  return logger.child(bindings);\n}\n\n/**\n * Creates a request-scoped logger with request ID and stores it in context\n *\n * @param {string} requestId - Unique request identifier\n * @param {object} [additionalContext] - Additional context to include in logs\n * @returns {Logger} Request-scoped logger instance\n */\nexport function createRequestLogger(requestId: string, additionalContext: Record<string, any> = {}): PinoLogger {\n  const logger = createChildLogger({\n    requestId,\n    ...additionalContext\n  });\n\n  try {\n    ContextStore.set(StoreKeys.LOGGER, logger);\n  } catch {\n    // Context not initialized, can't store logger\n    logger.debug('Failed to store logger in context - AsyncLocalStorage not initialized');\n  }\n\n  return logger;\n}\n\n/**\n * Utility to safely log errors with proper stack trace extraction\n *\n * @param {Error|unknown} error - Error object to log\n * @param {string} [message] - Optional message to include\n * @param {Record<string, any>} [context] - Additional context properties\n */\nexport function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void {\n  const logger = getLogger();\n\n  const errObj = error instanceof Error ? error : new Error(String(error));\n  const logContext = {\n    ...context,\n    error: errObj\n  };\n\n  logger.error(logContext, message || errObj.message);\n}\n"]}

package/build/esnext/utils/middleware.utils.js

@@ -129,10 +129,11 @@ export function setupRequestContext(options = {}) {
                 method: req.method,
                 url: req.originalUrl || req.url
             });
+            req.logger = childLogger;
             // Store logger in context
             ContextStore.set(StoreKeys.LOGGER, childLogger);
             if (autoLog) {
-                childLogger.info('Request context initialized');
+                req.logger.info('Request context initialized');
             }
             next();
         });

package/build/esnext/utils/middleware.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { createFinalErrorResponse, ErrorResponse } from './response.utils';\nimport { getLogger } from './logger.utils';\nimport type { Request, Response, NextFunction } from 'express';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { RequestTimeoutException } from './exception.utils';\nimport { ApiErrorResponse } from '../types/api-response';\n\nexport type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;\n\n/**\n * Attaches a unique request ID to each request.\n * Useful for request tracing and correlation between logs.\n *\n * @param {object} [options] - Configuration options\n * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID\n * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response\n * @param {() => string} [options.generator] - Custom ID generator function\n * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: {\n  headerName?: string;\n  exposeHeader?: boolean;\n  generator?: () => string;\n}): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\n  const generateId = options?.generator || uuid;\n\n  return (req, res, next) => {\n    // Use existing request ID from header or generate a new one\n    const existingId = req.headers[headerName.toLowerCase()];\n    const id = (existingId as string) || generateId();\n\n    // Attach ID to request object\n    req.id = id;\n\n    // Add ID to response headers\n    if (exposeHeader) {\n      res.setHeader(headerName, id);\n    }\n\n    next();\n  };\n}\n\n/**\n * Measures request processing time and logs or adds it to response headers.\n *\n * @param {object} [options] - Configuration options\n * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header\n * @param {boolean} [options.logOnComplete=false] - Whether to log timing info\n * @returns {Middleware} Express-compatible middleware\n */\nexport function responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }) {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    const start = process.hrtime();\n\n    // Function to calculate duration\n    const getDuration = () => {\n      const diff = process.hrtime(start);\n      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);\n    };\n\n    if (addHeader) {\n      // Ensure header is set before response is sent\n      const originalWriteHead = res.writeHead;\n      res.writeHead = function (...args: any[]) {\n        res.setHeader('X-Response-Time', `${getDuration()}ms`);\n        return originalWriteHead.apply(this, args as any);\n      };\n    }\n\n    if (logOnComplete) {\n      res.on('finish', () => {\n        getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);\n      });\n    }\n\n    next();\n  };\n}\n\n/**\n * Request timeout middleware.\n * Aborts requests that take too long to process.\n *\n * @param {number} [timeoutMs=30000] - Timeout in milliseconds\n * @returns {Middleware} Express-compatible middleware\n */\nexport function timeout(timeoutMs: number = 30000): Middleware {\n  return (_req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      const response = new RequestTimeoutException('Request timed out');\n      res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);\n    }, timeoutMs);\n\n    // Clear timeout when response is sent\n    res.on('finish', () => {\n      clearTimeout(timer);\n    });\n\n    next();\n  };\n}\n\n/**\n * Creates an Express middleware that initializes a per-request context.\n *\n * @param {object} [options] - Optional configuration\n * @param {string} [options.headerName='x-request-id'] - Header to look for request ID\n * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized\n * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function\n */\nexport function setupRequestContext(options: { headerName?: string; autoLog?: boolean } = {}): Middleware {\n  const { headerName = 'x-request-id', autoLog = true } = options;\n  return (req, _res, next) => {\n    // Generate or use existing request ID\n    const requestId = (req.headers[headerName] as string) || req?.['id'] || uuid();\n\n    ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n      // Create a child logger for this request\n      const childLogger = getLogger().child({\n        requestId,\n        method: req.method,\n        url: req.originalUrl || req.url\n      });\n\n      // Store logger in context\n      ContextStore.set(StoreKeys.LOGGER, childLogger);\n\n      if (autoLog) {\n        childLogger.info('Request context initialized');\n      }\n\n      next();\n    });\n  };\n}\n\nexport interface ErrorHandlerOptions {\n  /** Whether to log errors (default: true) */\n  logErrors?: boolean;\n  /** Whether to include error details in non-production (default: false) */\n  includeDetails?: boolean;\n}\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {ErrorHandlerOptions} options - Error handler options\n * @param {boolean} [options.logErrors=true] - Whether to log errors\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns Error middleware\n *\n * @example\n * import express from 'express';\n * import { errorHandler } from '@catbee/utils';\n *\n * const app = express();\n *\n * // Your routes\n * app.get('/ping', (req, res) => {\n *   throw new Error('Something went wrong');\n * });\n *\n * // Error handler (must be last middleware)\n * app.use(errorHandler({ includeDetails: true }));\n *\n * app.listen(3000, () => {\n *   console.log('Server running on port 3000');\n * });\n */\nexport function errorHandler(options?: ErrorHandlerOptions) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n\n  return (err: any, req: Request, res: Response, _next: NextFunction) => {\n    // Determine status code\n    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;\n\n    // Log error if enabled\n    if (logErrors) {\n      getLogger().error({ err }, `${err.message || 'Unknown error'}`);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      const result: ApiErrorResponse = {\n        error: true,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err?.requestId || req?.id || uuid(),\n        status,\n        path: req.originalUrl || req.url\n      };\n\n      if (includeDetails && err?.stack) {\n        result.stack = err.stack.split('\\n').map((line: string) => line.trim());\n      }\n      return res.status(status).json(result);\n    }\n\n    // Handle any other errors\n    return res\n      .status(status)\n      .json(createFinalErrorResponse(req, status, err?.message || 'Internal Server Error', err, { includeDetails }));\n  };\n}\n"]}
+{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { createFinalErrorResponse, ErrorResponse } from './response.utils';\nimport { getLogger } from './logger.utils';\nimport type { Request, Response, NextFunction } from 'express';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { RequestTimeoutException } from './exception.utils';\nimport { ApiErrorResponse } from '../types/api-response';\n\nexport type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;\n\n/**\n * Attaches a unique request ID to each request.\n * Useful for request tracing and correlation between logs.\n *\n * @param {object} [options] - Configuration options\n * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID\n * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response\n * @param {() => string} [options.generator] - Custom ID generator function\n * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: {\n  headerName?: string;\n  exposeHeader?: boolean;\n  generator?: () => string;\n}): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\n  const generateId = options?.generator || uuid;\n\n  return (req, res, next) => {\n    // Use existing request ID from header or generate a new one\n    const existingId = req.headers[headerName.toLowerCase()];\n    const id = (existingId as string) || generateId();\n\n    // Attach ID to request object\n    req.id = id;\n\n    // Add ID to response headers\n    if (exposeHeader) {\n      res.setHeader(headerName, id);\n    }\n\n    next();\n  };\n}\n\n/**\n * Measures request processing time and logs or adds it to response headers.\n *\n * @param {object} [options] - Configuration options\n * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header\n * @param {boolean} [options.logOnComplete=false] - Whether to log timing info\n * @returns {Middleware} Express-compatible middleware\n */\nexport function responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }) {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    const start = process.hrtime();\n\n    // Function to calculate duration\n    const getDuration = () => {\n      const diff = process.hrtime(start);\n      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);\n    };\n\n    if (addHeader) {\n      // Ensure header is set before response is sent\n      const originalWriteHead = res.writeHead;\n      res.writeHead = function (...args: any[]) {\n        res.setHeader('X-Response-Time', `${getDuration()}ms`);\n        return originalWriteHead.apply(this, args as any);\n      };\n    }\n\n    if (logOnComplete) {\n      res.on('finish', () => {\n        getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);\n      });\n    }\n\n    next();\n  };\n}\n\n/**\n * Request timeout middleware.\n * Aborts requests that take too long to process.\n *\n * @param {number} [timeoutMs=30000] - Timeout in milliseconds\n * @returns {Middleware} Express-compatible middleware\n */\nexport function timeout(timeoutMs: number = 30000): Middleware {\n  return (_req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      const response = new RequestTimeoutException('Request timed out');\n      res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);\n    }, timeoutMs);\n\n    // Clear timeout when response is sent\n    res.on('finish', () => {\n      clearTimeout(timer);\n    });\n\n    next();\n  };\n}\n\n/**\n * Creates an Express middleware that initializes a per-request context.\n *\n * @param {object} [options] - Optional configuration\n * @param {string} [options.headerName='x-request-id'] - Header to look for request ID\n * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized\n * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function\n */\nexport function setupRequestContext(options: { headerName?: string; autoLog?: boolean } = {}): Middleware {\n  const { headerName = 'x-request-id', autoLog = true } = options;\n  return (req, _res, next) => {\n    // Generate or use existing request ID\n    const requestId = (req.headers[headerName] as string) || req?.['id'] || uuid();\n\n    ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n      // Create a child logger for this request\n      const childLogger = getLogger().child({\n        requestId,\n        method: req.method,\n        url: req.originalUrl || req.url\n      });\n\n      req.logger = childLogger;\n\n      // Store logger in context\n      ContextStore.set(StoreKeys.LOGGER, childLogger);\n\n      if (autoLog) {\n        req.logger.info('Request context initialized');\n      }\n\n      next();\n    });\n  };\n}\n\nexport interface ErrorHandlerOptions {\n  /** Whether to log errors (default: true) */\n  logErrors?: boolean;\n  /** Whether to include error details in non-production (default: false) */\n  includeDetails?: boolean;\n}\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {ErrorHandlerOptions} options - Error handler options\n * @param {boolean} [options.logErrors=true] - Whether to log errors\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns Error middleware\n *\n * @example\n * import express from 'express';\n * import { errorHandler } from '@catbee/utils';\n *\n * const app = express();\n *\n * // Your routes\n * app.get('/ping', (req, res) => {\n *   throw new Error('Something went wrong');\n * });\n *\n * // Error handler (must be last middleware)\n * app.use(errorHandler({ includeDetails: true }));\n *\n * app.listen(3000, () => {\n *   console.log('Server running on port 3000');\n * });\n */\nexport function errorHandler(options?: ErrorHandlerOptions) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n\n  return (err: any, req: Request, res: Response, _next: NextFunction) => {\n    // Determine status code\n    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;\n\n    // Log error if enabled\n    if (logErrors) {\n      getLogger().error({ err }, `${err.message || 'Unknown error'}`);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      const result: ApiErrorResponse = {\n        error: true,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err?.requestId || req?.id || uuid(),\n        status,\n        path: req.originalUrl || req.url\n      };\n\n      if (includeDetails && err?.stack) {\n        result.stack = err.stack.split('\\n').map((line: string) => line.trim());\n      }\n      return res.status(status).json(result);\n    }\n\n    // Handle any other errors\n    return res\n      .status(status)\n      .json(createFinalErrorResponse(req, status, err?.message || 'Internal Server Error', err, { includeDetails }));\n  };\n}\n"]}