@duplojs/utils 1.4.56 → 1.4.58

package/dist/date/getters/getDayOfYear.mjs

@@ -1,18 +1,18 @@
-import { millisecondsInOneDay } from '../constants.mjs';
 import { toNative } from '../toNative.mjs';
+import { millisecondsInOneDay } from '../constants.mjs';
 
 /**
  * {@include date/getDayOfYear/index.md}
  */
 function getDayOfYear(input, timezone = "UTC") {
-    const nativeDate = toNative(input);
+    const date = toNative(input);
     let year = 0;
     let month = 0;
     let day = 0;
     if (timezone === "UTC") {
-        year = nativeDate.getUTCFullYear();
-        month = nativeDate.getUTCMonth();
-        day = nativeDate.getUTCDate();
+        year = date.getUTCFullYear();
+        month = date.getUTCMonth();
+        day = date.getUTCDate();
     }
     else {
         const parts = new Intl.DateTimeFormat("en-US", {
@@ -20,7 +20,7 @@ function getDayOfYear(input, timezone = "UTC") {
             day: "numeric",
             year: "numeric",
             month: "numeric",
-        }).formatToParts(nativeDate);
+        }).formatToParts(date);
         const partsMap = new Map(parts.map((part) => [part.type, part.value]));
         year = Number(partsMap.get("year"));
         month = Number(partsMap.get("month")) - 1;

package/dist/date/getters/getFirstDayOfMonth.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var theDate = require('../theDate.cjs');
 var toNative = require('../toNative.cjs');
 
 /**
@@ -9,9 +10,7 @@ function getFirstDayOfMonth(input) {
     const nativeDate = toNative.toNative(input);
     nativeDate.setUTCDate(1);
     nativeDate.setUTCHours(0, 0, 0, 0);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return theDate.TheDate.new(nativeDate.getTime());
 }
 
 exports.getFirstDayOfMonth = getFirstDayOfMonth;

package/dist/date/getters/getFirstDayOfMonth.d.ts

@@ -1,26 +1,32 @@
-import type { TheDate } from "../types";
+import type { SerializedTheDate } from "../types";
+import { TheDate } from "../theDate";
 /**
- * Returns the first day of month of a date.
+ * Returns the first day of the month for a date.
  * 
- * Signature: `getFirstDayOfMonth(input)` → returns a value
+ * Signature: `getFirstDayOfMonth(input)` → `TheDate`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
  * const input = D.create("2024-06-19");
- * const result = D.getFirstDayOfMonth(input);
- * // result: "date1717200000000+" (1 June 2024)
+ * const firstDay = D.getFirstDayOfMonth(input);
+ * // firstDay: TheDate
+ * 
+ * const serialized = D.serialize(firstDay);
+ * // serialized: SerializedTheDate
  * 
  * pipe(
- * 	input,
+ * 	serialized,
  * 	D.getFirstDayOfMonth,
- * ); // result: "date1717200000000+" (1 June 2024)
- * 
+ * ); // TheDate
  * ```
  * 
+ * @remarks
+ * - The returned date is normalized to `00:00:00.000` in UTC.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/getFirstDayOfMonth
  * 
  * @namespace D
  * 
  */
-export declare function getFirstDayOfMonth(input: TheDate): TheDate;
+export declare function getFirstDayOfMonth<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): TheDate;

package/dist/date/getters/getFirstDayOfMonth.mjs

@@ -1,3 +1,4 @@
+import { TheDate } from '../theDate.mjs';
 import { toNative } from '../toNative.mjs';
 
 /**
@@ -7,9 +8,7 @@ function getFirstDayOfMonth(input) {
     const nativeDate = toNative(input);
     nativeDate.setUTCDate(1);
     nativeDate.setUTCHours(0, 0, 0, 0);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return TheDate.new(nativeDate.getTime());
 }
 
 export { getFirstDayOfMonth };

package/dist/date/getters/getFirstDayOfWeek.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var theDate = require('../theDate.cjs');
 var toNative = require('../toNative.cjs');
 
 /**
@@ -11,9 +12,7 @@ function getFirstDayOfWeek(input) {
     const daysToMonday = dayOfWeek === 0 ? -6 : 1 - dayOfWeek;
     nativeDate.setUTCHours(0, 0, 0, 0);
     nativeDate.setUTCDate(nativeDate.getUTCDate() + daysToMonday);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return theDate.TheDate.new(nativeDate.getTime());
 }
 
 exports.getFirstDayOfWeek = getFirstDayOfWeek;

package/dist/date/getters/getFirstDayOfWeek.d.ts

@@ -1,26 +1,33 @@
-import type { TheDate } from "../types";
+import type { SerializedTheDate } from "../types";
+import { TheDate } from "../theDate";
 /**
- * Returns the first day of week of a date.
+ * Returns the first day of the week for a date.
  * 
- * Signature: `getFirstDayOfWeek(input)` → returns a value
+ * Signature: `getFirstDayOfWeek(input)` → `TheDate`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
  * const input = D.create("2024-06-19");
- * const result = D.getFirstDayOfWeek(input);
- * // result: "date1718668800000+" (monday 17 june 2024)
+ * const firstDay = D.getFirstDayOfWeek(input);
+ * // firstDay: TheDate
+ * 
+ * const serialized = D.serialize(firstDay);
+ * // serialized: SerializedTheDate
  * 
  * pipe(
- * 	input,
+ * 	serialized,
  * 	D.getFirstDayOfWeek,
- * ); // result: "date1718668800000+" (monday 17 june 2024)
- * 
+ * ); // TheDate
  * ```
  * 
+ * @remarks
+ * - The week starts on Monday.
+ * - The returned date is normalized to `00:00:00.000` in UTC.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/getFirstDayOfWeek
  * 
  * @namespace D
  * 
  */
-export declare function getFirstDayOfWeek(input: TheDate): TheDate;
+export declare function getFirstDayOfWeek<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): TheDate;

package/dist/date/getters/getFirstDayOfWeek.mjs

@@ -1,3 +1,4 @@
+import { TheDate } from '../theDate.mjs';
 import { toNative } from '../toNative.mjs';
 
 /**
@@ -9,9 +10,7 @@ function getFirstDayOfWeek(input) {
     const daysToMonday = dayOfWeek === 0 ? -6 : 1 - dayOfWeek;
     nativeDate.setUTCHours(0, 0, 0, 0);
     nativeDate.setUTCDate(nativeDate.getUTCDate() + daysToMonday);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return TheDate.new(nativeDate.getTime());
 }
 
 export { getFirstDayOfWeek };

package/dist/date/getters/getHour.cjs

@@ -6,16 +6,16 @@ var toNative = require('../toNative.cjs');
  * {@include date/getHour/index.md}
  */
 function getHour(input, timezone = "UTC") {
-    const nativeDate = toNative.toNative(input);
+    const date = toNative.toNative(input);
     if (timezone === "UTC") {
-        return nativeDate.getUTCHours();
+        return date.getUTCHours();
     }
     const formatter = new Intl.DateTimeFormat("en-US", {
         timeZone: timezone,
         hour: "numeric",
         hour12: false,
     });
-    return Number(formatter.format(nativeDate));
+    return Number(formatter.format(date));
 }
 
 exports.getHour = getHour;

package/dist/date/getters/getHour.d.ts

@@ -1,25 +1,27 @@
-import { type TheDate, type Timezone } from "..";
+import type { SerializedTheDate } from "../types";
+import { type TheDate } from "../theDate";
+import type { Timezone } from "../timezone";
 /**
- * Returns the hour of a date.
+ * Returns the hour (`0` to `23`) for a date in a target timezone.
  * 
- * Signature: `getHour(input, timezone)` → returns a value
+ * Signature: `getHour(input, timezone?)` → `number`
  * 
- * If timezone is omitted, UTC is used.
- * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`. If `timezone` is omitted, UTC is used.
  * 
  * ```ts
- * const input = D.create("2024-06-20");
- * const result = D.getHour(input);
- * // result: 0
+ * const input = D.create("2024-06-20", {
+ * 	hour: "00",
+ * });
+ * const utcHour = D.getHour(input);
+ * // utcHour: 0
  * 
- * const result2 = D.getHour(input, "America/Los_Angeles");
- * // result2: 17
+ * const laHour = D.getHour(input, "America/Los_Angeles");
+ * // laHour: 17
  * 
  * pipe(
  * 	input,
- * 	D.getHour,
- * ); // result: 0
+ * 	(value) => D.getHour(value, "UTC"),
+ * ); // 0
  * 
  * ```
  * 
@@ -28,4 +30,4 @@ import { type TheDate, type Timezone } from "..";
  * @namespace D
  * 
  */
-export declare function getHour<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;
+export declare function getHour<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getHour.mjs

@@ -4,16 +4,16 @@ import { toNative } from '../toNative.mjs';
  * {@include date/getHour/index.md}
  */
 function getHour(input, timezone = "UTC") {
-    const nativeDate = toNative(input);
+    const date = toNative(input);
     if (timezone === "UTC") {
-        return nativeDate.getUTCHours();
+        return date.getUTCHours();
     }
     const formatter = new Intl.DateTimeFormat("en-US", {
         timeZone: timezone,
         hour: "numeric",
         hour12: false,
     });
-    return Number(formatter.format(nativeDate));
+    return Number(formatter.format(date));
 }
 
 export { getHour };

package/dist/date/getters/getLastDayOfMonth.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var theDate = require('../theDate.cjs');
 var toNative = require('../toNative.cjs');
 
 /**
@@ -9,9 +10,7 @@ function getLastDayOfMonth(input) {
     const nativeDate = toNative.toNative(input);
     nativeDate.setUTCMonth(nativeDate.getUTCMonth() + 1, 0);
     nativeDate.setUTCHours(23, 59, 59, 999);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return theDate.TheDate.new(nativeDate.getTime());
 }
 
 exports.getLastDayOfMonth = getLastDayOfMonth;

package/dist/date/getters/getLastDayOfMonth.d.ts

@@ -1,26 +1,32 @@
-import type { TheDate } from "../types";
+import type { SerializedTheDate } from "../types";
+import { TheDate } from "../theDate";
 /**
- * Returns the last day of month of a date.
+ * Returns the last day of the month for a date.
  * 
- * Signature: `getLastDayOfMonth(input)` → returns a value
+ * Signature: `getLastDayOfMonth(input)` → `TheDate`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
  * const input = D.create("2024-06-19");
- * const result = D.getLastDayOfMonth(input);
- * // result: "date1719532800000+" (30 June 2024)
+ * const lastDay = D.getLastDayOfMonth(input);
+ * // lastDay: TheDate
+ * 
+ * const serialized = D.serialize(lastDay);
+ * // serialized: SerializedTheDate
  * 
  * pipe(
- * 	input,
+ * 	serialized,
  * 	D.getLastDayOfMonth,
- * ); // result: "date1719532800000+" (30 June 2024)
- * 
+ * ); // TheDate
  * ```
  * 
+ * @remarks
+ * - The returned date is normalized to `23:59:59.999` in UTC.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/getLastDayOfMonth
  * 
  * @namespace D
  * 
  */
-export declare function getLastDayOfMonth(input: TheDate): TheDate;
+export declare function getLastDayOfMonth<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): TheDate;

package/dist/date/getters/getLastDayOfMonth.mjs

@@ -1,3 +1,4 @@
+import { TheDate } from '../theDate.mjs';
 import { toNative } from '../toNative.mjs';
 
 /**
@@ -7,9 +8,7 @@ function getLastDayOfMonth(input) {
     const nativeDate = toNative(input);
     nativeDate.setUTCMonth(nativeDate.getUTCMonth() + 1, 0);
     nativeDate.setUTCHours(23, 59, 59, 999);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return TheDate.new(nativeDate.getTime());
 }
 
 export { getLastDayOfMonth };

package/dist/date/getters/getLastDayOfWeek.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var theDate = require('../theDate.cjs');
 var toNative = require('../toNative.cjs');
 
 /**
@@ -11,9 +12,7 @@ function getLastDayOfWeek(input) {
     const daysToSunday = dayOfWeek === 0 ? 0 : 7 - dayOfWeek;
     nativeDate.setUTCDate(nativeDate.getUTCDate() + daysToSunday);
     nativeDate.setUTCHours(23, 59, 59, 999);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return theDate.TheDate.new(nativeDate.getTime());
 }
 
 exports.getLastDayOfWeek = getLastDayOfWeek;

package/dist/date/getters/getLastDayOfWeek.d.ts

@@ -1,26 +1,33 @@
-import type { TheDate } from "../types";
+import type { SerializedTheDate } from "../types";
+import { TheDate } from "../theDate";
 /**
- * Returns the last day of week of a date.
+ * Returns the last day of the week for a date.
  * 
- * Signature: `getLastDayOfWeek(input)` → returns a value
+ * Signature: `getLastDayOfWeek(input)` → `TheDate`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
  * const input = D.create("2024-06-19");
- * const result = D.getLastDayOfWeek(input);
- * // result: "date1719187200000+" (Sunday 23 june 2024)
+ * const lastDay = D.getLastDayOfWeek(input);
+ * // lastDay: TheDate
+ * 
+ * const serialized = D.serialize(lastDay);
+ * // serialized: SerializedTheDate
  * 
  * pipe(
- * 	input,
+ * 	serialized,
  * 	D.getLastDayOfWeek,
- * ); // result: "date1719187200000+" (Sunday 23 june 2024)
- * 
+ * ); // TheDate
  * ```
  * 
+ * @remarks
+ * - The week ends on Sunday.
+ * - The returned date is normalized to `23:59:59.999` in UTC.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/getLastDayOfWeek
  * 
  * @namespace D
  * 
  */
-export declare function getLastDayOfWeek(input: TheDate): TheDate;
+export declare function getLastDayOfWeek<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): TheDate;

package/dist/date/getters/getLastDayOfWeek.mjs

@@ -1,3 +1,4 @@
+import { TheDate } from '../theDate.mjs';
 import { toNative } from '../toNative.mjs';
 
 /**
@@ -9,9 +10,7 @@ function getLastDayOfWeek(input) {
     const daysToSunday = dayOfWeek === 0 ? 0 : 7 - dayOfWeek;
     nativeDate.setUTCDate(nativeDate.getUTCDate() + daysToSunday);
     nativeDate.setUTCHours(23, 59, 59, 999);
-    const timestamp = nativeDate.getTime();
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return TheDate.new(nativeDate.getTime());
 }
 
 export { getLastDayOfWeek };

package/dist/date/getters/getMilliseconds.cjs

@@ -6,8 +6,8 @@ var toNative = require('../toNative.cjs');
  * {@include date/getMilliseconds/index.md}
  */
 function getMilliseconds(input) {
-    const nativeDate = toNative.toNative(input);
-    return nativeDate.getUTCMilliseconds();
+    const date = toNative.toNative(input);
+    return date.getUTCMilliseconds();
 }
 
 exports.getMilliseconds = getMilliseconds;

package/dist/date/getters/getMilliseconds.d.ts

@@ -1,10 +1,11 @@
-import { type TheDate } from "..";
+import type { SerializedTheDate } from "../types";
+import { type TheDate } from "../theDate";
 /**
- * Returns the milliseconds of a date.
+ * Returns the milliseconds part (`0` to `999`) of a date.
  * 
- * Signature: `getMilliseconds(input)` → returns a value
+ * Signature: `getMilliseconds(input)` → `number`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
  * const input = D.create("2024-06-20", {
@@ -13,19 +14,20 @@ import { type TheDate } from "..";
  * 	second: "56",
  * 	millisecond: "789",
  * });
- * const result = D.getMilliseconds(input);
- * // result: 789
+ * const milliseconds = D.getMilliseconds(input);
+ * // milliseconds: 789
  * 
  * pipe(
  * 	input,
  * 	D.getMilliseconds,
- * ); // result: 789
- * 
  * ```
  * 
+ * @remarks
+ * - Value is always read in UTC.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/getMilliseconds
  * 
  * @namespace D
  * 
  */
-export declare function getMilliseconds<GenericInput extends TheDate>(input: GenericInput): number;
+export declare function getMilliseconds<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): number;

package/dist/date/getters/getMilliseconds.mjs

@@ -4,8 +4,8 @@ import { toNative } from '../toNative.mjs';
  * {@include date/getMilliseconds/index.md}
  */
 function getMilliseconds(input) {
-    const nativeDate = toNative(input);
-    return nativeDate.getUTCMilliseconds();
+    const date = toNative(input);
+    return date.getUTCMilliseconds();
 }
 
 export { getMilliseconds };

package/dist/date/getters/getMinute.cjs

@@ -6,15 +6,15 @@ var toNative = require('../toNative.cjs');
  * {@include date/getMinute/index.md}
  */
 function getMinute(input, timezone = "UTC") {
-    const nativeDate = toNative.toNative(input);
+    const date = toNative.toNative(input);
     if (timezone === "UTC") {
-        return nativeDate.getUTCMinutes();
+        return date.getUTCMinutes();
     }
     const formatter = new Intl.DateTimeFormat("en-US", {
         timeZone: timezone,
         minute: "numeric",
     });
-    return Number(formatter.format(nativeDate));
+    return Number(formatter.format(date));
 }
 
 exports.getMinute = getMinute;

package/dist/date/getters/getMinute.d.ts

@@ -1,26 +1,28 @@
-import { type TheDate, type Timezone } from "..";
+import type { SerializedTheDate } from "../types";
+import { type TheDate } from "../theDate";
+import { type Timezone } from "../timezone";
 /**
- * Returns the minute of a date.
+ * Returns the minute (`0` to `59`) for a date in a target timezone.
  * 
- * Signature: `getMinute(input, timezone)` → returns a value
+ * Signature: `getMinute(input, timezone?)` → `number`
  * 
- * If timezone is omitted, UTC is used.
- * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`. If `timezone` is omitted, UTC is used.
  * 
  * ```ts
- * const input = D.create("2024-06-20");
- * const result = D.getMinute(input);
- * // result: 0
+ * const input = D.create("2024-06-20", {
+ * 	hour: "00",
+ * 	minute: "30",
+ * });
+ * const utcMinute = D.getMinute(input);
+ * // utcMinute: 30
  * 
- * const result2 = D.getMinute(input, "Europe/Madrid");
- * // result2: 0
+ * const tokyoMinute = D.getMinute(input, "Asia/Tokyo");
+ * // tokyoMinute: 30
  * 
  * pipe(
  * 	input,
- * 	D.getMinute,
- * ); // result: 0
- * 
+ * 	(value) => D.getMinute(value, "UTC"),
+ * ); // 30
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/getMinute
@@ -28,4 +30,4 @@ import { type TheDate, type Timezone } from "..";
  * @namespace D
  * 
  */
-export declare function getMinute<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;
+export declare function getMinute<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getMinute.mjs

@@ -4,15 +4,15 @@ import { toNative } from '../toNative.mjs';
  * {@include date/getMinute/index.md}
  */
 function getMinute(input, timezone = "UTC") {
-    const nativeDate = toNative(input);
+    const date = toNative(input);
     if (timezone === "UTC") {
-        return nativeDate.getUTCMinutes();
+        return date.getUTCMinutes();
     }
     const formatter = new Intl.DateTimeFormat("en-US", {
         timeZone: timezone,
         minute: "numeric",
     });
-    return Number(formatter.format(nativeDate));
+    return Number(formatter.format(date));
 }
 
 export { getMinute };

package/dist/date/getters/getMonth.cjs

@@ -6,15 +6,15 @@ var toNative = require('../toNative.cjs');
  * {@include date/getMonth/index.md}
  */
 function getMonth(input, timezone = "UTC") {
-    const nativeDate = toNative.toNative(input);
+    const date = toNative.toNative(input);
     if (timezone === "UTC") {
-        return nativeDate.getUTCMonth() + 1;
+        return date.getUTCMonth() + 1;
     }
     const formatter = new Intl.DateTimeFormat("en-US", {
         timeZone: timezone,
         month: "numeric",
     });
-    return Number(formatter.format(nativeDate));
+    return Number(formatter.format(date));
 }
 
 exports.getMonth = getMonth;