@kikiutils/shared 18.0.1 → 18.1.0

package/dist/datetime.d.ts

@@ -1,83 +1,71 @@
-import { DateArg, Day, FormatOptions } from "date-fns";
+import { EnhancedDate } from "./classes/enhanced-date.js";
+import * as dateFns from "date-fns";
 //#region src/datetime.d.ts
-type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek' | 'today' | 'yesterday';
+export type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek' | 'today' | 'yesterday';
 /**
- * Formats a given date, timestamp, or date string into a specified format.
+ * Formats a date using a date-fns pattern without changing the input.
  *
- * This function is a wrapper around `date-fns/format`.
+ * @remarks
+ * Formatting uses the system time zone unless configured through date-fns options.
+ * Invalid dates and unsupported patterns propagate date-fns exceptions.
  *
- * @param {DateArg<Date>} date - The input date to format. Can be a Date object, a timestamp, or a string
- * @param {string} [format] - The target format string
- * @param {FormatOptions} [options] - Optional formatting options passed to `date-fns/format`
+ * @param date - The date, timestamp in milliseconds, or date string to format.
+ * @param format - The date-fns pattern. Defaults to `yyyy-MM-dd HH:mm:ss`.
+ * @param options - Formatting options passed to date-fns.
  *
- * @returns {string} The formatted date string
+ * @returns The formatted date string.
  *
  * @example
- * ```typescript
- * import { formatDate } from '@kikiutils/shared/datetime';
- *
- * // Format a Date object
- * console.log(formatDate(new Date(), 'yyyy-MM-dd')); // 2024-07-10
  *
- * // Format a timestamp
- * console.log(formatDate(1657814400000, 'yyyy-MM-dd')); // 2022-07-15
+ * ```ts
+ * import { formatDate } from '@kikiutils/shared/datetime';
  *
- * // Format a date string
- * console.log(formatDate('2024-07-10T00:00:00Z', 'yyyy-MM-dd')); // 2024-07-10
+ * const date = new Date(2026, 0, 15, 12);
+ * console.log(formatDate(date, 'yyyy-MM-dd')); // => '2026-01-15'
  * ```
  */
-declare function formatDate(date: DateArg<Date> & {}, format?: string, options?: FormatOptions): string;
+export declare function formatDate(date: dateFns.DateArg<Date>, format?: string, options?: dateFns.FormatOptions): string;
 /**
- * Get the date range (start and end) based on a given date and range type.
+ * Returns new start and end dates for a calendar range in the system time zone.
  *
- * Supports common range types like 'lastMonth', 'lastWeek', 'thisMonth', 'thisWeek', 'today', and 'yesterday'.
+ * @remarks
+ * The reference date is unchanged. Boundaries are inclusive by default, ending at `23:59:59.999`.
+ * When `options.setEndDateToNextDayStart` is `true`, the end is the exclusive start of the next calendar day.
+ * `options.weekStartsOn` defaults to `1` (Monday); `0` means Sunday and `6` means Saturday.
+ * Calendar ranges follow local daylight saving transitions rather than fixed 24-hour durations.
  *
- * @param {Date} date - The reference date
- * @param {DateRangeType} type - The range type to compute
- * @param {object} [options] - Optional settings
- * @param {boolean} [options.setEndDateToNextDayStart] - If true, set `endDate` to 00:00:00.000 of the next day
- * @param {Day} [options.weekStartsOn] - The start day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
+ * @param date - The reference date for the range.
+ * @param type - The current or previous day, week, or month to select.
+ * @param options - Settings for the end boundary and first day of the week.
  *
- * @returns {{ startDate: Date, endDate: Date }} An object with `startDate` and `endDate`
+ * @returns An object containing new `EnhancedDate` boundaries; the reference date is unchanged.
+ *
+ * @throws Error if the range type is unsupported at runtime.
  *
  * @example
- * ```typescript
- * import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
  *
- * // Get the date range for last month
- * const date = new Date('2023-07-01');
- * console.log(getDateRangeFromDate(date, 'lastMonth'));
- * // { startDate: 2023-06-01T00:00:00.000Z, endDate: 2023-06-30T23:59:59.999Z }
+ * ```ts
+ * import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
  *
- * // Get this week's range with Sunday as the first day
- * console.log(getDateRangeFromDate(date, 'thisWeek', { weekStartsOn: 0 }));
- * // { startDate: 2023-06-25T00:00:00.000Z, endDate: 2023-07-01T23:59:59.999Z }
+ * const range = getDateRangeFromDate(new Date(2026, 6, 15, 12), 'lastMonth');
+ * console.log(range.startDate.format('yyyy-MM-dd')); // => '2026-06-01'
+ * console.log(range.endDate.format('yyyy-MM-dd')); // => '2026-06-30'
  * ```
  */
-declare function getDateRangeFromDate(date: Date, type: DateRangeType, options?: {
+export declare function getDateRangeFromDate(date: Date, type: DateRangeType, options?: {
   setEndDateToNextDayStart?: boolean;
-  weekStartsOn?: Day;
+  weekStartsOn?: dateFns.Day;
 }): {
-  endDate: Date;
-  startDate: Date;
+  endDate: EnhancedDate;
+  startDate: EnhancedDate;
 };
 /**
- * Returns a `Date` object set to midnight (00:00:00) of today, with an optional day offset.
- *
- * @param {number} [offsetDays] - Number of days to offset from today. Can be negative
+ * Returns a new date at local midnight with an optional calendar-day offset from today.
  *
- * @returns {Date} A `Date` object at 00:00:00 of the offset day
+ * @param offsetDays - The calendar days to add; negative values select earlier days.
  *
- * @example
- * ```typescript
- * import { getMidnightDateFromToday } from '@kikiutils/shared/datetime';
- *
- * console.log(getMidnightDateFromToday()); // today at 00:00:00
- * console.log(getMidnightDateFromToday(3)); // 3 days from today at 00:00:00
- * console.log(getMidnightDateFromToday(-1)); // yesterday at 00:00:00
- * ```
+ * @returns A new `EnhancedDate` at local midnight on the selected day.
  */
-declare function getMidnightDateFromToday(offsetDays?: number): Date;
+export declare function getMidnightDateFromToday(offsetDays?: number): EnhancedDate;
 //#endregion
-export { DateRangeType, formatDate, getDateRangeFromDate, getMidnightDateFromToday };
 //# sourceMappingURL=datetime.d.ts.map

package/dist/datetime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"datetime.d.ts","names":[],"sources":["../src/datetime.ts"],"mappings":";;KAkBY;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BI,WAAW,MAAM,QAAQ,YAAY,iBAAwC,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BvF,qBACZ,MAAM,MACN,MAAM,eACN;EACI;EACA,eAAe;;;;;;;;;;;;;;;;;;;;;iBAoEP,yBAAyB,sBAAsB"}
+{"version":3,"file":"datetime.d.ts","names":[],"sources":["../src/datetime.ts"],"mappings":";;;YAIY;;;;;;;;;;;;;;;;;;;;;;;wBAwBI,WACZ,MAAM,QAAQ,QAAQ,OACtB,iBACA,UAAU,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAkCN,qBACZ,MAAM,MACN,MAAM,eACN;EACI;EACA,eAAe,QAAQ;;;;;;;;;;;;wBA8Df,yBAAyB,sBAAsB"}

package/dist/datetime.js

@@ -1,95 +1,94 @@
-import { endOfDay, endOfMonth, endOfWeek, format, startOfDay, startOfMonth, startOfWeek, subDays, subMonths, subWeeks } from "date-fns";
+import { EnhancedDate } from "./classes/enhanced-date.js";
+import * as dateFns from "date-fns";
 //#region src/datetime.ts
 /**
-* Formats a given date, timestamp, or date string into a specified format.
+* Formats a date using a date-fns pattern without changing the input.
 *
-* This function is a wrapper around `date-fns/format`.
+* @remarks
+* Formatting uses the system time zone unless configured through date-fns options.
+* Invalid dates and unsupported patterns propagate date-fns exceptions.
 *
-* @param {DateArg<Date>} date - The input date to format. Can be a Date object, a timestamp, or a string
-* @param {string} [format] - The target format string
-* @param {FormatOptions} [options] - Optional formatting options passed to `date-fns/format`
+* @param date - The date, timestamp in milliseconds, or date string to format.
+* @param format - The date-fns pattern. Defaults to `yyyy-MM-dd HH:mm:ss`.
+* @param options - Formatting options passed to date-fns.
 *
-* @returns {string} The formatted date string
+* @returns The formatted date string.
 *
 * @example
-* ```typescript
-* import { formatDate } from '@kikiutils/shared/datetime';
-*
-* // Format a Date object
-* console.log(formatDate(new Date(), 'yyyy-MM-dd')); // 2024-07-10
 *
-* // Format a timestamp
-* console.log(formatDate(1657814400000, 'yyyy-MM-dd')); // 2022-07-15
+* ```ts
+* import { formatDate } from '@kikiutils/shared/datetime';
 *
-* // Format a date string
-* console.log(formatDate('2024-07-10T00:00:00Z', 'yyyy-MM-dd')); // 2024-07-10
+* const date = new Date(2026, 0, 15, 12);
+* console.log(formatDate(date, 'yyyy-MM-dd')); // => '2026-01-15'
 * ```
 */
-function formatDate(date, format$1 = "yyyy-MM-dd HH:mm:ss", options) {
-	return format(date, format$1, options);
+function formatDate(date, format = "yyyy-MM-dd HH:mm:ss", options) {
+	return dateFns.format(date, format, options);
 }
 /**
-* Get the date range (start and end) based on a given date and range type.
+* Returns new start and end dates for a calendar range in the system time zone.
 *
-* Supports common range types like 'lastMonth', 'lastWeek', 'thisMonth', 'thisWeek', 'today', and 'yesterday'.
+* @remarks
+* The reference date is unchanged. Boundaries are inclusive by default, ending at `23:59:59.999`.
+* When `options.setEndDateToNextDayStart` is `true`, the end is the exclusive start of the next calendar day.
+* `options.weekStartsOn` defaults to `1` (Monday); `0` means Sunday and `6` means Saturday.
+* Calendar ranges follow local daylight saving transitions rather than fixed 24-hour durations.
 *
-* @param {Date} date - The reference date
-* @param {DateRangeType} type - The range type to compute
-* @param {object} [options] - Optional settings
-* @param {boolean} [options.setEndDateToNextDayStart] - If true, set `endDate` to 00:00:00.000 of the next day
-* @param {Day} [options.weekStartsOn] - The start day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
+* @param date - The reference date for the range.
+* @param type - The current or previous day, week, or month to select.
+* @param options - Settings for the end boundary and first day of the week.
 *
-* @returns {{ startDate: Date, endDate: Date }} An object with `startDate` and `endDate`
+* @returns An object containing new `EnhancedDate` boundaries; the reference date is unchanged.
+*
+* @throws Error if the range type is unsupported at runtime.
 *
 * @example
-* ```typescript
-* import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
 *
-* // Get the date range for last month
-* const date = new Date('2023-07-01');
-* console.log(getDateRangeFromDate(date, 'lastMonth'));
-* // { startDate: 2023-06-01T00:00:00.000Z, endDate: 2023-06-30T23:59:59.999Z }
+* ```ts
+* import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
 *
-* // Get this week's range with Sunday as the first day
-* console.log(getDateRangeFromDate(date, 'thisWeek', { weekStartsOn: 0 }));
-* // { startDate: 2023-06-25T00:00:00.000Z, endDate: 2023-07-01T23:59:59.999Z }
+* const range = getDateRangeFromDate(new Date(2026, 6, 15, 12), 'lastMonth');
+* console.log(range.startDate.format('yyyy-MM-dd')); // => '2026-06-01'
+* console.log(range.endDate.format('yyyy-MM-dd')); // => '2026-06-30'
 * ```
 */
 function getDateRangeFromDate(date, type, options) {
+	const referenceDate = new EnhancedDate(date);
 	let endDate;
 	let startDate;
 	switch (type) {
 		case "lastMonth":
 			{
-				const lastMonth = subMonths(date, 1);
-				endDate = endOfMonth(lastMonth);
-				startDate = startOfMonth(lastMonth);
+				const lastMonth = referenceDate.toSubMonths(1);
+				endDate = lastMonth.toEndOfMonth();
+				startDate = lastMonth.toStartOfMonth();
 			}
 			break;
 		case "lastWeek":
 			{
-				const lastWeek = subWeeks(date, 1);
-				endDate = endOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });
-				startDate = startOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });
+				const lastWeek = referenceDate.toSubWeeks(1);
+				endDate = lastWeek.toEndOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
+				startDate = lastWeek.toStartOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
 			}
 			break;
 		case "thisMonth":
-			endDate = endOfMonth(date);
-			startDate = startOfMonth(date);
+			endDate = referenceDate.toEndOfMonth();
+			startDate = referenceDate.toStartOfMonth();
 			break;
 		case "thisWeek":
-			endDate = endOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });
-			startDate = startOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });
+			endDate = referenceDate.toEndOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
+			startDate = referenceDate.toStartOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
 			break;
 		case "today":
-			endDate = endOfDay(date);
-			startDate = startOfDay(date);
+			endDate = referenceDate.toEndOfDay();
+			startDate = referenceDate.toStartOfDay();
 			break;
 		case "yesterday":
 			{
-				const yesterday = subDays(date, 1);
-				endDate = endOfDay(yesterday);
-				startDate = startOfDay(yesterday);
+				const yesterday = referenceDate.toSubDays(1);
+				endDate = yesterday.toEndOfDay();
+				startDate = yesterday.toStartOfDay();
 			}
 			break;
 		default: throw new Error(`Unsupported date range type: ${type}`);
@@ -101,26 +100,14 @@ function getDateRangeFromDate(date, type, options) {
 	};
 }
 /**
-* Returns a `Date` object set to midnight (00:00:00) of today, with an optional day offset.
-*
-* @param {number} [offsetDays] - Number of days to offset from today. Can be negative
+* Returns a new date at local midnight with an optional calendar-day offset from today.
 *
-* @returns {Date} A `Date` object at 00:00:00 of the offset day
+* @param offsetDays - The calendar days to add; negative values select earlier days.
 *
-* @example
-* ```typescript
-* import { getMidnightDateFromToday } from '@kikiutils/shared/datetime';
-*
-* console.log(getMidnightDateFromToday()); // today at 00:00:00
-* console.log(getMidnightDateFromToday(3)); // 3 days from today at 00:00:00
-* console.log(getMidnightDateFromToday(-1)); // yesterday at 00:00:00
-* ```
+* @returns A new `EnhancedDate` at local midnight on the selected day.
 */
 function getMidnightDateFromToday(offsetDays = 0) {
-	const date = /* @__PURE__ */ new Date();
-	date.setDate(date.getDate() + offsetDays);
-	date.setHours(0, 0, 0, 0);
-	return date;
+	return new EnhancedDate().addDays(offsetDays).startOfDay();
 }
 //#endregion
 export { formatDate, getDateRangeFromDate, getMidnightDateFromToday };

package/dist/datetime.js.map

@@ -1 +1 @@
-{"version":3,"file":"datetime.js","names":["dateFnsFormat","format"],"sources":["../src/datetime.ts"],"sourcesContent":["import {\n    format as dateFnsFormat,\n    endOfDay,\n    endOfMonth,\n    endOfWeek,\n    startOfDay,\n    startOfMonth,\n    startOfWeek,\n    subDays,\n    subMonths,\n    subWeeks,\n} from 'date-fns';\nimport type {\n    DateArg,\n    Day,\n    FormatOptions,\n} from 'date-fns';\n\nexport type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek' | 'today' | 'yesterday';\n\n/**\n * Formats a given date, timestamp, or date string into a specified format.\n *\n * This function is a wrapper around `date-fns/format`.\n *\n * @param {DateArg<Date>} date - The input date to format. Can be a Date object, a timestamp, or a string\n * @param {string} [format] - The target format string\n * @param {FormatOptions} [options] - Optional formatting options passed to `date-fns/format`\n *\n * @returns {string} The formatted date string\n *\n * @example\n * ```typescript\n * import { formatDate } from '@kikiutils/shared/datetime';\n *\n * // Format a Date object\n * console.log(formatDate(new Date(), 'yyyy-MM-dd')); // 2024-07-10\n *\n * // Format a timestamp\n * console.log(formatDate(1657814400000, 'yyyy-MM-dd')); // 2022-07-15\n *\n * // Format a date string\n * console.log(formatDate('2024-07-10T00:00:00Z', 'yyyy-MM-dd')); // 2024-07-10\n * ```\n */\nexport function formatDate(date: DateArg<Date> & {}, format: string = 'yyyy-MM-dd HH:mm:ss', options?: FormatOptions) {\n    return dateFnsFormat(date, format, options);\n}\n\n/**\n * Get the date range (start and end) based on a given date and range type.\n *\n * Supports common range types like 'lastMonth', 'lastWeek', 'thisMonth', 'thisWeek', 'today', and 'yesterday'.\n *\n * @param {Date} date - The reference date\n * @param {DateRangeType} type - The range type to compute\n * @param {object} [options] - Optional settings\n * @param {boolean} [options.setEndDateToNextDayStart] - If true, set `endDate` to 00:00:00.000 of the next day\n * @param {Day} [options.weekStartsOn] - The start day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)\n *\n * @returns {{ startDate: Date, endDate: Date }} An object with `startDate` and `endDate`\n *\n * @example\n * ```typescript\n * import { getDateRangeFromDate } from '@kikiutils/shared/datetime';\n *\n * // Get the date range for last month\n * const date = new Date('2023-07-01');\n * console.log(getDateRangeFromDate(date, 'lastMonth'));\n * // { startDate: 2023-06-01T00:00:00.000Z, endDate: 2023-06-30T23:59:59.999Z }\n *\n * // Get this week's range with Sunday as the first day\n * console.log(getDateRangeFromDate(date, 'thisWeek', { weekStartsOn: 0 }));\n * // { startDate: 2023-06-25T00:00:00.000Z, endDate: 2023-07-01T23:59:59.999Z }\n * ```\n */\nexport function getDateRangeFromDate(\n    date: Date,\n    type: DateRangeType,\n    options?: {\n        setEndDateToNextDayStart?: boolean;\n        weekStartsOn?: Day;\n    },\n) {\n    let endDate: Date;\n    let startDate: Date;\n    switch (type) {\n        case 'lastMonth':\n            {\n                const lastMonth = subMonths(date, 1);\n                endDate = endOfMonth(lastMonth);\n                startDate = startOfMonth(lastMonth);\n            }\n\n            break;\n        case 'lastWeek':\n            {\n                const lastWeek = subWeeks(date, 1);\n                endDate = endOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });\n                startDate = startOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });\n            }\n\n            break;\n        case 'thisMonth':\n            endDate = endOfMonth(date);\n            startDate = startOfMonth(date);\n            break;\n        case 'thisWeek':\n            endDate = endOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });\n            startDate = startOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });\n            break;\n        case 'today':\n            endDate = endOfDay(date);\n            startDate = startOfDay(date);\n            break;\n        case 'yesterday':\n            {\n                const yesterday = subDays(date, 1);\n                endDate = endOfDay(yesterday);\n                startDate = startOfDay(yesterday);\n            }\n\n            break;\n        default: throw new Error(`Unsupported date range type: ${type}`);\n    }\n\n    if (options?.setEndDateToNextDayStart) endDate.setHours(24, 0, 0, 0);\n    return {\n        endDate,\n        startDate,\n    };\n}\n\n/**\n * Returns a `Date` object set to midnight (00:00:00) of today, with an optional day offset.\n *\n * @param {number} [offsetDays] - Number of days to offset from today. Can be negative\n *\n * @returns {Date} A `Date` object at 00:00:00 of the offset day\n *\n * @example\n * ```typescript\n * import { getMidnightDateFromToday } from '@kikiutils/shared/datetime';\n *\n * console.log(getMidnightDateFromToday()); // today at 00:00:00\n * console.log(getMidnightDateFromToday(3)); // 3 days from today at 00:00:00\n * console.log(getMidnightDateFromToday(-1)); // yesterday at 00:00:00\n * ```\n */\nexport function getMidnightDateFromToday(offsetDays: number = 0) {\n    const date = new Date();\n    date.setDate(date.getDate() + offsetDays);\n    date.setHours(0, 0, 0, 0);\n    return date;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,WAAW,MAA0B,WAAiB,uBAAuB,SAAyB;CAClH,OAAOA,OAAc,MAAMC,UAAQ,OAAO;AAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,qBACZ,MACA,MACA,SAIF;CACE,IAAI;CACJ,IAAI;CACJ,QAAQ,MAAR;EACI,KAAK;GACD;IACI,MAAM,YAAY,UAAU,MAAM,CAAC;IACnC,UAAU,WAAW,SAAS;IAC9B,YAAY,aAAa,SAAS;GACtC;GAEA;EACJ,KAAK;GACD;IACI,MAAM,WAAW,SAAS,MAAM,CAAC;IACjC,UAAU,UAAU,UAAU,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;IAC1E,YAAY,YAAY,UAAU,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;GAClF;GAEA;EACJ,KAAK;GACD,UAAU,WAAW,IAAI;GACzB,YAAY,aAAa,IAAI;GAC7B;EACJ,KAAK;GACD,UAAU,UAAU,MAAM,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;GACtE,YAAY,YAAY,MAAM,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;GAC1E;EACJ,KAAK;GACD,UAAU,SAAS,IAAI;GACvB,YAAY,WAAW,IAAI;GAC3B;EACJ,KAAK;GACD;IACI,MAAM,YAAY,QAAQ,MAAM,CAAC;IACjC,UAAU,SAAS,SAAS;IAC5B,YAAY,WAAW,SAAS;GACpC;GAEA;EACJ,SAAS,MAAM,IAAI,MAAM,gCAAgC,MAAM;CACnE;CAEA,IAAI,SAAS,0BAA0B,QAAQ,SAAS,IAAI,GAAG,GAAG,CAAC;CACnE,OAAO;EACH;EACA;CACJ;AACJ;;;;;;;;;;;;;;;;;AAkBA,SAAgB,yBAAyB,aAAqB,GAAG;CAC7D,MAAM,uBAAO,IAAI,KAAK;CACtB,KAAK,QAAQ,KAAK,QAAQ,IAAI,UAAU;CACxC,KAAK,SAAS,GAAG,GAAG,GAAG,CAAC;CACxB,OAAO;AACX"}
+{"version":3,"file":"datetime.js","names":[],"sources":["../src/datetime.ts"],"sourcesContent":["import * as dateFns from 'date-fns';\n\nimport { EnhancedDate } from './classes/enhanced-date';\n\nexport type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek' | 'today' | 'yesterday';\n\n/**\n * Formats a date using a date-fns pattern without changing the input.\n *\n * @remarks\n * Formatting uses the system time zone unless configured through date-fns options.\n * Invalid dates and unsupported patterns propagate date-fns exceptions.\n *\n * @param date - The date, timestamp in milliseconds, or date string to format.\n * @param format - The date-fns pattern. Defaults to `yyyy-MM-dd HH:mm:ss`.\n * @param options - Formatting options passed to date-fns.\n *\n * @returns The formatted date string.\n *\n * @example\n *\n * ```ts\n * import { formatDate } from '@kikiutils/shared/datetime';\n *\n * const date = new Date(2026, 0, 15, 12);\n * console.log(formatDate(date, 'yyyy-MM-dd')); // => '2026-01-15'\n * ```\n */\nexport function formatDate(\n    date: dateFns.DateArg<Date>,\n    format: string = 'yyyy-MM-dd HH:mm:ss',\n    options?: dateFns.FormatOptions,\n) {\n    return dateFns.format(date, format, options);\n}\n\n/* eslint-disable jsdoc/check-param-names -- Inline TypeScript options are documented in remarks. */\n\n/**\n * Returns new start and end dates for a calendar range in the system time zone.\n *\n * @remarks\n * The reference date is unchanged. Boundaries are inclusive by default, ending at `23:59:59.999`.\n * When `options.setEndDateToNextDayStart` is `true`, the end is the exclusive start of the next calendar day.\n * `options.weekStartsOn` defaults to `1` (Monday); `0` means Sunday and `6` means Saturday.\n * Calendar ranges follow local daylight saving transitions rather than fixed 24-hour durations.\n *\n * @param date - The reference date for the range.\n * @param type - The current or previous day, week, or month to select.\n * @param options - Settings for the end boundary and first day of the week.\n *\n * @returns An object containing new `EnhancedDate` boundaries; the reference date is unchanged.\n *\n * @throws Error if the range type is unsupported at runtime.\n *\n * @example\n *\n * ```ts\n * import { getDateRangeFromDate } from '@kikiutils/shared/datetime';\n *\n * const range = getDateRangeFromDate(new Date(2026, 6, 15, 12), 'lastMonth');\n * console.log(range.startDate.format('yyyy-MM-dd')); // => '2026-06-01'\n * console.log(range.endDate.format('yyyy-MM-dd')); // => '2026-06-30'\n * ```\n */\nexport function getDateRangeFromDate(\n    date: Date,\n    type: DateRangeType,\n    options?: {\n        setEndDateToNextDayStart?: boolean;\n        weekStartsOn?: dateFns.Day;\n    },\n) {\n    const referenceDate = new EnhancedDate(date);\n    let endDate: EnhancedDate;\n    let startDate: EnhancedDate;\n    switch (type) {\n        case 'lastMonth':\n            {\n                const lastMonth = referenceDate.toSubMonths(1);\n                endDate = lastMonth.toEndOfMonth();\n                startDate = lastMonth.toStartOfMonth();\n            }\n\n            break;\n        case 'lastWeek':\n            {\n                const lastWeek = referenceDate.toSubWeeks(1);\n                endDate = lastWeek.toEndOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });\n                startDate = lastWeek.toStartOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });\n            }\n\n            break;\n        case 'thisMonth':\n            endDate = referenceDate.toEndOfMonth();\n            startDate = referenceDate.toStartOfMonth();\n            break;\n        case 'thisWeek':\n            endDate = referenceDate.toEndOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });\n            startDate = referenceDate.toStartOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });\n            break;\n        case 'today':\n            endDate = referenceDate.toEndOfDay();\n            startDate = referenceDate.toStartOfDay();\n            break;\n        case 'yesterday':\n            {\n                const yesterday = referenceDate.toSubDays(1);\n                endDate = yesterday.toEndOfDay();\n                startDate = yesterday.toStartOfDay();\n            }\n\n            break;\n        default: throw new Error(`Unsupported date range type: ${type}`);\n    }\n\n    if (options?.setEndDateToNextDayStart) endDate.setHours(24, 0, 0, 0);\n    return {\n        endDate,\n        startDate,\n    };\n}\n\n/* eslint-enable jsdoc/check-param-names */\n\n/**\n * Returns a new date at local midnight with an optional calendar-day offset from today.\n *\n * @param offsetDays - The calendar days to add; negative values select earlier days.\n *\n * @returns A new `EnhancedDate` at local midnight on the selected day.\n */\nexport function getMidnightDateFromToday(offsetDays: number = 0) {\n    return new EnhancedDate().addDays(offsetDays).startOfDay();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,WACZ,MACA,SAAiB,uBACjB,SACF;CACE,OAAO,QAAQ,OAAO,MAAM,QAAQ,OAAO;AAC/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,qBACZ,MACA,MACA,SAIF;CACE,MAAM,gBAAgB,IAAI,aAAa,IAAI;CAC3C,IAAI;CACJ,IAAI;CACJ,QAAQ,MAAR;EACI,KAAK;GACD;IACI,MAAM,YAAY,cAAc,YAAY,CAAC;IAC7C,UAAU,UAAU,aAAa;IACjC,YAAY,UAAU,eAAe;GACzC;GAEA;EACJ,KAAK;GACD;IACI,MAAM,WAAW,cAAc,WAAW,CAAC;IAC3C,UAAU,SAAS,YAAY,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;IAC3E,YAAY,SAAS,cAAc,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;GACnF;GAEA;EACJ,KAAK;GACD,UAAU,cAAc,aAAa;GACrC,YAAY,cAAc,eAAe;GACzC;EACJ,KAAK;GACD,UAAU,cAAc,YAAY,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;GAChF,YAAY,cAAc,cAAc,EAAE,cAAc,SAAS,gBAAgB,EAAE,CAAC;GACpF;EACJ,KAAK;GACD,UAAU,cAAc,WAAW;GACnC,YAAY,cAAc,aAAa;GACvC;EACJ,KAAK;GACD;IACI,MAAM,YAAY,cAAc,UAAU,CAAC;IAC3C,UAAU,UAAU,WAAW;IAC/B,YAAY,UAAU,aAAa;GACvC;GAEA;EACJ,SAAS,MAAM,IAAI,MAAM,gCAAgC,MAAM;CACnE;CAEA,IAAI,SAAS,0BAA0B,QAAQ,SAAS,IAAI,GAAG,GAAG,CAAC;CACnE,OAAO;EACH;EACA;CACJ;AACJ;;;;;;;;AAWA,SAAgB,yBAAyB,aAAqB,GAAG;CAC7D,OAAO,IAAI,aAAa,CAAC,CAAC,QAAQ,UAAU,CAAC,CAAC,WAAW;AAC7D"}

package/dist/element-plus.d.ts

@@ -1,31 +1,30 @@
 import { RuleType } from "async-validator";
 import { FormItemRule } from "element-plus";
 //#region src/element-plus.d.ts
-type DoNotRemoveOrUseThisType = RuleType;
+export type DoNotRemoveOrUseThisType = RuleType;
 /**
- * Creates a reusable Element Plus `<el-form-item>` validation rule with sensible defaults.
+ * Creates a new Element Plus form validation rule with overridable defaults.
  *
- * This utility provides default values for `required`, `trigger`, and `type`,
- * while allowing overrides via the `options` parameter. It simplifies common
- * form validation rule creation and ensures consistency across forms.
+ * @remarks
+ * Defaults to `required: true`, `trigger: 'blur'`, and `type: 'string'`.
+ * Non-nullish options override those defaults; `null` and `undefined` use the defaults.
+ * The `message` argument takes precedence over `options.message`.
+ * The options object is unchanged.
  *
- * @param {FormItemRule['message']} message - The validation message to display when the rule fails
- * @param {FormItemRule} [options] - Optional overrides for the rule fields
- * @param {boolean} [options.required] - Whether the field is required (default: `true`)
- * @param {string | string[]} [options.trigger] - The event(s) that trigger validation (default: `'blur'`)
- * @param {RuleType} [options.type] - The expected type of the field (default: `'string'`)
+ * @param message - The validation message displayed on failure.
+ * @param options - Additional rule fields and non-nullish overrides for the defaults; `message` takes precedence.
  *
- * @returns A `FormItemRule` object that can be used in Element Plus form validation
+ * @returns A new `FormItemRule` object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { createElFormItemRuleWithDefaults } from '@kikiutils/shared/element-plus';
  *
  * const rule = createElFormItemRuleWithDefaults('This field is required');
  * const optionalRule = createElFormItemRuleWithDefaults('Optional field', { required: false });
  * ```
  */
-declare function createElFormItemRuleWithDefaults(message: FormItemRule['message'], options?: FormItemRule): FormItemRule;
+export declare function createElFormItemRuleWithDefaults(message: FormItemRule['message'], options?: FormItemRule): FormItemRule;
 //#endregion
-export { DoNotRemoveOrUseThisType, createElFormItemRuleWithDefaults };
 //# sourceMappingURL=element-plus.d.ts.map

package/dist/element-plus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"element-plus.d.ts","names":[],"sources":["../src/element-plus.ts"],"mappings":";;;KAGY,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;iBAyBvB,iCACZ,SAAS,yBACT,UAAS,eACV"}
+{"version":3,"file":"element-plus.d.ts","names":[],"sources":["../src/element-plus.ts"],"mappings":";;;YAGY,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;wBAyBvB,iCACZ,SAAS,yBACT,UAAS,eACV"}

package/dist/element-plus.js

@@ -1,21 +1,21 @@
 //#region src/element-plus.ts
 /**
-* Creates a reusable Element Plus `<el-form-item>` validation rule with sensible defaults.
+* Creates a new Element Plus form validation rule with overridable defaults.
 *
-* This utility provides default values for `required`, `trigger`, and `type`,
-* while allowing overrides via the `options` parameter. It simplifies common
-* form validation rule creation and ensures consistency across forms.
+* @remarks
+* Defaults to `required: true`, `trigger: 'blur'`, and `type: 'string'`.
+* Non-nullish options override those defaults; `null` and `undefined` use the defaults.
+* The `message` argument takes precedence over `options.message`.
+* The options object is unchanged.
 *
-* @param {FormItemRule['message']} message - The validation message to display when the rule fails
-* @param {FormItemRule} [options] - Optional overrides for the rule fields
-* @param {boolean} [options.required] - Whether the field is required (default: `true`)
-* @param {string | string[]} [options.trigger] - The event(s) that trigger validation (default: `'blur'`)
-* @param {RuleType} [options.type] - The expected type of the field (default: `'string'`)
+* @param message - The validation message displayed on failure.
+* @param options - Additional rule fields and non-nullish overrides for the defaults; `message` takes precedence.
 *
-* @returns A `FormItemRule` object that can be used in Element Plus form validation
+* @returns A new `FormItemRule` object.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { createElFormItemRuleWithDefaults } from '@kikiutils/shared/element-plus';
 *
 * const rule = createElFormItemRuleWithDefaults('This field is required');

package/dist/element-plus.js.map

@@ -1 +1 @@
-{"version":3,"file":"element-plus.js","names":[],"sources":["../src/element-plus.ts"],"sourcesContent":["import type { RuleType } from 'async-validator';\nimport type { FormItemRule } from 'element-plus';\n\nexport type DoNotRemoveOrUseThisType = RuleType;\n\n/**\n * Creates a reusable Element Plus `<el-form-item>` validation rule with sensible defaults.\n *\n * This utility provides default values for `required`, `trigger`, and `type`,\n * while allowing overrides via the `options` parameter. It simplifies common\n * form validation rule creation and ensures consistency across forms.\n *\n * @param {FormItemRule['message']} message - The validation message to display when the rule fails\n * @param {FormItemRule} [options] - Optional overrides for the rule fields\n * @param {boolean} [options.required] - Whether the field is required (default: `true`)\n * @param {string | string[]} [options.trigger] - The event(s) that trigger validation (default: `'blur'`)\n * @param {RuleType} [options.type] - The expected type of the field (default: `'string'`)\n *\n * @returns A `FormItemRule` object that can be used in Element Plus form validation\n *\n * @example\n * ```typescript\n * import { createElFormItemRuleWithDefaults } from '@kikiutils/shared/element-plus';\n *\n * const rule = createElFormItemRuleWithDefaults('This field is required');\n * const optionalRule = createElFormItemRuleWithDefaults('Optional field', { required: false });\n * ```\n */\nexport function createElFormItemRuleWithDefaults(\n    message: FormItemRule['message'],\n    options: FormItemRule = {},\n): FormItemRule {\n    return {\n        ...options,\n        message,\n        required: options.required ?? true,\n        trigger: options.trigger ?? 'blur',\n        type: options.type ?? 'string',\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iCACZ,SACA,UAAwB,CAAC,GACb;CACZ,OAAO;EACH,GAAG;EACH;EACA,UAAU,QAAQ,YAAY;EAC9B,SAAS,QAAQ,WAAW;EAC5B,MAAM,QAAQ,QAAQ;CAC1B;AACJ"}
+{"version":3,"file":"element-plus.js","names":[],"sources":["../src/element-plus.ts"],"sourcesContent":["import type { RuleType } from 'async-validator';\nimport type { FormItemRule } from 'element-plus';\n\nexport type DoNotRemoveOrUseThisType = RuleType;\n\n/**\n * Creates a new Element Plus form validation rule with overridable defaults.\n *\n * @remarks\n * Defaults to `required: true`, `trigger: 'blur'`, and `type: 'string'`.\n * Non-nullish options override those defaults; `null` and `undefined` use the defaults.\n * The `message` argument takes precedence over `options.message`.\n * The options object is unchanged.\n *\n * @param message - The validation message displayed on failure.\n * @param options - Additional rule fields and non-nullish overrides for the defaults; `message` takes precedence.\n *\n * @returns A new `FormItemRule` object.\n *\n * @example\n *\n * ```ts\n * import { createElFormItemRuleWithDefaults } from '@kikiutils/shared/element-plus';\n *\n * const rule = createElFormItemRuleWithDefaults('This field is required');\n * const optionalRule = createElFormItemRuleWithDefaults('Optional field', { required: false });\n * ```\n */\nexport function createElFormItemRuleWithDefaults(\n    message: FormItemRule['message'],\n    options: FormItemRule = {},\n): FormItemRule {\n    return {\n        ...options,\n        message,\n        required: options.required ?? true,\n        trigger: options.trigger ?? 'blur',\n        type: options.type ?? 'string',\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iCACZ,SACA,UAAwB,CAAC,GACb;CACZ,OAAO;EACH,GAAG;EACH;EACA,UAAU,QAAQ,YAAY;EAC9B,SAAS,QAAQ,WAAW;EAC5B,MAAM,QAAQ,QAAQ;CAC1B;AACJ"}

package/dist/enum.d.ts

@@ -2,98 +2,101 @@
 /**
  * Extracts only the numeric values from an enumeration-like object.
  *
- * @template T - The type of the enum object
+ * @typeParam T - The type of the enum object.
  *
- * @param {T} enumObject - The enumeration-like object to extract numeric values from,
+ * @param enumObject - The enumeration-like object to extract numeric values from,
  * the object can contain numeric values, string values, or both.
  *
- * @returns {Extract<T[keyof T], number>[]} An array of numeric values extracted from the enum object
+ * @returns An array of numeric values extracted from the enum object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { getEnumNumberValues } from '@kikiutils/shared/enum';
  *
  * enum RecordType {
- *   Receive = 0,
- *   Send = 1,
- *   Unknown = 'unknown'
+ *     Receive = 0,
+ *     Send = 1,
+ *     Unknown = 'unknown',
  * }
  *
- * console.log(getEnumNumberValues(RecordType)); // [0, 1]
+ * console.log(getEnumNumberValues(RecordType)); // => [0, 1]
  * ```
  */
-declare function getEnumNumberValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], number>[];
+export declare function getEnumNumberValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], number>[];
 /**
  * Extracts only the string values from an enumeration-like object.
  *
- * @template T - The type of the enum object
+ * @typeParam T - The type of the enum object.
  *
- * @param {T} enumObject - The enumeration-like object to extract string values from,
+ * @param enumObject - The enumeration-like object to extract string values from,
  * the object can contain numeric values, string values, or both.
  *
- * @returns {Extract<T[keyof T], string>[]} An array of string values extracted from the enum object
+ * @returns An array of string values extracted from the enum object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { getEnumStringValues } from '@kikiutils/shared/enum';
  *
  * enum RecordType {
- *   Receive = 0,
- *   Send = 1,
- *   Unknown = 'unknown'
+ *     Receive = 0,
+ *     Send = 1,
+ *     Unknown = 'unknown',
  * }
  *
- * console.log(getEnumStringValues(RecordType)); // ['unknown']
+ * console.log(getEnumStringValues(RecordType)); // => ['unknown']
  * ```
  */
-declare function getEnumStringValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], string>[];
+export declare function getEnumStringValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], string>[];
 /**
  * Extracts all values from an enumeration-like object.
  *
+ * @remarks
  * This function handles TypeScript enums correctly by accounting for the reverse mapping
  * that occurs with numeric enums. It works with pure numeric enums, pure string enums,
  * and mixed enums.
  *
- * @template T - The type of the enum object
+ * @typeParam T - The type of the enum object.
  *
- * @param {T} enumObject - The enumeration-like object to extract values from,
+ * @param enumObject - The enumeration-like object to extract values from,
  * the object can contain numeric values, string values, or both.
  *
- * @returns {(T[keyof T])[]} An array containing all the values from the enum object
+ * @returns An array containing all the values from the enum object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { getEnumValues } from '@kikiutils/shared/enum';
  *
  * // Numeric enum
  * enum Status {
- *   Active = 0,
- *   Inactive = 1,
- *   Pending = 2
+ *     Active = 0,
+ *     Inactive = 1,
+ *     Pending = 2,
  * }
  *
- * console.log(getEnumValues(Status)); // [0, 1, 2]
+ * console.log(getEnumValues(Status)); // => [0, 1, 2]
  *
  * // String enum
  * enum Color {
- *   Red = 'RED',
- *   Green = 'GREEN',
- *   Blue = 'BLUE'
+ *     Red = 'RED',
+ *     Green = 'GREEN',
+ *     Blue = 'BLUE',
  * }
  *
- * console.log(getEnumValues(Color)); // ['RED', 'GREEN', 'BLUE']
+ * console.log(getEnumValues(Color)); // => ['RED', 'GREEN', 'BLUE']
  *
  * // Mixed enum
  * enum RecordType {
- *   Receive = 0,
- *   Send = 1,
- *   Unknown = 'unknown'
+ *     Receive = 0,
+ *     Send = 1,
+ *     Unknown = 'unknown',
  * }
  *
- * console.log(getEnumValues(RecordType)); // [0, 1, 'unknown']
+ * console.log(getEnumValues(RecordType)); // => [0, 1, 'unknown']
  * ```
  */
-declare function getEnumValues<T extends Record<string, any>>(enumObject: T): (T[keyof T])[];
+export declare function getEnumValues<T extends Record<string, any>>(enumObject: T): (T[keyof T])[];
 //#endregion
-export { getEnumNumberValues, getEnumStringValues, getEnumValues };
 //# sourceMappingURL=enum.d.ts.map

package/dist/enum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enum.d.ts","names":[],"sources":["../src/enum.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;iBAuBgB,oBAAoB,UAAU,qBAAqB,YAAY,IAAI,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;iBA2BnF,oBAAoB,UAAU,qBAAqB,YAAY,IAAI,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkDnF,cAAc,UAAU,qBAAqB,YAAY,KAAK,QAAQ"}
+{"version":3,"file":"enum.d.ts","names":[],"sources":["../src/enum.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;wBAwBgB,oBAAoB,UAAU,qBAAqB,YAAY,IAAI,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;wBA4BnF,oBAAoB,UAAU,qBAAqB,YAAY,IAAI,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoDnF,cAAc,UAAU,qBAAqB,YAAY,KAAK,QAAQ"}