@duplojs/utils 1.4.32 → 1.4.34

package/dist/date/each.d.ts

@@ -1,4 +1,36 @@
 import type { TheDate, Unit } from "./types";
+/**
+ * Iterates over a date range.
+ * 
+ * Signature: `each(range, unit)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = {
+ * 	start: D.create("2024-06-01"),
+ * 	end: D.create("2024-06-03"),
+ * } as const;
+ * 
+ * const iterator = D.each(input);
+ * const result = A.from(iterator);
+ * // result: ["date1717200000000+", "date1717286400000+", "date1717372800000+"]
+ * 
+ * pipe(
+ * 	input,
+ * 	D.each,
+ * ); // result: ["date1717200000000+", "date1717286400000+", "date1717372800000+"]
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Includes the end date when it falls on a step boundary.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/each
+ * 
+ * @namespace D
+ * 
+ */
 export declare function each(range: {
     start: TheDate;
     end: TheDate;

package/dist/date/each.mjs

@@ -20,6 +20,9 @@ const stepMapper = {
         return date.getTime();
     },
 };
+/**
+ * {@include date/each/index.md}
+ */
 function each(range, unit = "day") {
     const startTimestamp = toTimestamp(range.start);
     const endTimestamp = toTimestamp(range.end);

package/dist/date/format.cjs

@@ -2,6 +2,7 @@
 
 var toNative = require('./toNative.cjs');
 
+const formatStringRegex = /YYYY|YY|MM|DD|HH|mm|ss|SSS|ZZ/g;
 function format(...args) {
     if (args.length === 2) {
         const [formatString, timezone] = args;
@@ -31,7 +32,7 @@ function format(...args) {
         SSS: date.getMilliseconds().toString(),
         ZZ: timezone,
     };
-    return formatString.replace(/YYYY|YY|MM|DD|HH|mm|ss|SSS|ZZ/g, (token) => tokens[token]);
+    return formatString.replace(formatStringRegex, (token) => tokens[token]);
 }
 
 exports.format = format;

package/dist/date/format.d.ts

@@ -1,4 +1,33 @@
 import type { TheDate } from "./types";
 import type { Timezone } from "./timezone";
+/**
+ * Formats a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `format(input, formatString, timezone)` → returns a value
+ * - Curried: `format(formatString, timezone)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const theDate = D.createOrThrow(1704067200123);
+ * const fullFormat = D.format(theDate, "YYYY-MM-DD HH:mm:ss.SSS ZZ", "UTC");
+ * // fullFormat: "2024-01-01 00:00:00.123 UTC"
+ * 
+ * pipe(
+ * 	theDate,
+ * 	D.format("YYYY-MM-DD HH:mm:ss.SSS ZZ", "UTC"),
+ * ); // fullFormat: "2024-01-01 00:00:00.123 UTC"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Supports tokens: YYYY, YY, MM, DD, HH, mm, ss, SSS, ZZ.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/format
+ * 
+ * @namespace D
+ * 
+ */
 export declare function format<GenericInput extends TheDate, GenericFormat extends string, GenericTimezone extends Timezone>(formatString: GenericFormat, timezone: GenericTimezone): (input: GenericInput) => string;
 export declare function format<GenericInput extends TheDate, GenericFormat extends string, GenericTimezone extends Timezone>(input: GenericInput, formatString: GenericFormat, timezone: GenericTimezone): string;

package/dist/date/format.mjs

@@ -1,5 +1,6 @@
 import { toNative } from './toNative.mjs';
 
+const formatStringRegex = /YYYY|YY|MM|DD|HH|mm|ss|SSS|ZZ/g;
 function format(...args) {
     if (args.length === 2) {
         const [formatString, timezone] = args;
@@ -29,7 +30,7 @@ function format(...args) {
         SSS: date.getMilliseconds().toString(),
         ZZ: timezone,
     };
-    return formatString.replace(/YYYY|YY|MM|DD|HH|mm|ss|SSS|ZZ/g, (token) => tokens[token]);
+    return formatString.replace(formatStringRegex, (token) => tokens[token]);
 }
 
 export { format };

package/dist/date/formatTime.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+var constants = require('./constants.cjs');
+var toTimeValue = require('./toTimeValue.cjs');
+
+const formatStringRegex = /WW|DD|HH|mm|ss|SSS/g;
+function formatTime(...args) {
+    if (args.length === 1) {
+        const [formatString] = args;
+        return (input) => formatTime(input, formatString);
+    }
+    const [input, formatString] = args;
+    const timeValue = toTimeValue.toTimeValue(input);
+    const isNegative = timeValue < 0;
+    let remaining = Math.abs(timeValue);
+    const weeks = Math.floor(remaining / constants.millisecondInOneWeek);
+    remaining -= weeks * constants.millisecondInOneWeek;
+    const days = Math.floor(remaining / constants.millisecondsInOneDay);
+    remaining -= days * constants.millisecondsInOneDay;
+    const hours = Math.floor(remaining / constants.millisecondInOneHour);
+    remaining -= hours * constants.millisecondInOneHour;
+    const minutes = Math.floor(remaining / constants.millisecondInOneMinute);
+    remaining -= minutes * constants.millisecondInOneMinute;
+    const seconds = Math.floor(remaining / constants.millisecondsInOneSecond);
+    remaining -= seconds * constants.millisecondsInOneSecond;
+    const tokens = {
+        WW: weeks.toString().padStart(2, "0"),
+        DD: days.toString().padStart(2, "0"),
+        HH: hours.toString().padStart(2, "0"),
+        mm: minutes.toString().padStart(2, "0"),
+        ss: seconds.toString().padStart(2, "0"),
+        SSS: remaining.toString().padStart(3, "0"),
+    };
+    const formatted = formatString.replace(formatStringRegex, (token) => tokens[token]);
+    return isNegative ? `-${formatted}` : formatted;
+}
+
+exports.formatTime = formatTime;

package/dist/date/formatTime.d.ts

@@ -0,0 +1,35 @@
+import type { TheTime } from "./types";
+/**
+ * Formats a time.
+ * 
+ * **Supported call styles:**
+ * - Classic: `formatTime(input, formatString)` → returns a value
+ * - Curried: `formatTime(formatString)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const theTime = D.createTheTime(788_645_006);
+ * const fullFormat = D.formatTime(theTime, "WW DD HH:mm:ss.SSS");
+ * // fullFormat: "01 02 03:04:05.006"
+ * 
+ * pipe(
+ * 	theTime,
+ * 	D.formatTime("HH:mm"),
+ * ); // result: "03:04"
+ * 
+ * const negativeTime = D.createTheTime(-5_000);
+ * const shortFormat = D.formatTime(negativeTime, "ss.SSS");
+ * // shortFormat: "-05.000"
+ * ```
+ * 
+ * @remarks
+ * - Supports tokens: WW, DD, HH, mm, ss, SSS.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/formatTime
+ * 
+ * @namespace D
+ * 
+ */
+export declare function formatTime<GenericInput extends TheTime, GenericFormat extends string>(formatString: GenericFormat): (input: GenericInput) => string;
+export declare function formatTime<GenericInput extends TheTime, GenericFormat extends string>(input: GenericInput, formatString: GenericFormat): string;

package/dist/date/formatTime.mjs

@@ -0,0 +1,36 @@
+import { millisecondsInOneSecond, millisecondInOneMinute, millisecondInOneHour, millisecondsInOneDay, millisecondInOneWeek } from './constants.mjs';
+import { toTimeValue } from './toTimeValue.mjs';
+
+const formatStringRegex = /WW|DD|HH|mm|ss|SSS/g;
+function formatTime(...args) {
+    if (args.length === 1) {
+        const [formatString] = args;
+        return (input) => formatTime(input, formatString);
+    }
+    const [input, formatString] = args;
+    const timeValue = toTimeValue(input);
+    const isNegative = timeValue < 0;
+    let remaining = Math.abs(timeValue);
+    const weeks = Math.floor(remaining / millisecondInOneWeek);
+    remaining -= weeks * millisecondInOneWeek;
+    const days = Math.floor(remaining / millisecondsInOneDay);
+    remaining -= days * millisecondsInOneDay;
+    const hours = Math.floor(remaining / millisecondInOneHour);
+    remaining -= hours * millisecondInOneHour;
+    const minutes = Math.floor(remaining / millisecondInOneMinute);
+    remaining -= minutes * millisecondInOneMinute;
+    const seconds = Math.floor(remaining / millisecondsInOneSecond);
+    remaining -= seconds * millisecondsInOneSecond;
+    const tokens = {
+        WW: weeks.toString().padStart(2, "0"),
+        DD: days.toString().padStart(2, "0"),
+        HH: hours.toString().padStart(2, "0"),
+        mm: minutes.toString().padStart(2, "0"),
+        ss: seconds.toString().padStart(2, "0"),
+        SSS: remaining.toString().padStart(3, "0"),
+    };
+    const formatted = formatString.replace(formatStringRegex, (token) => tokens[token]);
+    return isNegative ? `-${formatted}` : formatted;
+}
+
+export { formatTime };

package/dist/date/getTimezoneOffset.d.ts

@@ -1,4 +1,33 @@
 import { type Timezone } from "./timezone";
 import { type TheDate } from "./types";
+/**
+ * Returns the timezone offset of a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `getTimezoneOffset(timeZone)` → returns a value
+ * - Curried: `getTimezoneOffset(theDate, timeZone)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const theDate = D.createOrThrow(1704067200000);
+ * const offset = D.getTimezoneOffset(theDate, "America/New_York");
+ * // offset: -18000000
+ * 
+ * pipe(
+ * 	theDate,
+ * 	D.getTimezoneOffset("America/New_York"),
+ * ); // offset: -18000000
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns the offset in milliseconds for the given timezone.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getTimezoneOffset
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getTimezoneOffset(timeZone: Timezone): (theDate: TheDate) => number;
 export declare function getTimezoneOffset(theDate: TheDate, timeZone: Timezone): number;

package/dist/date/getters/getDayOfMonth.cjs

@@ -2,6 +2,9 @@
 
 var toNative = require('../toNative.cjs');
 
+/**
+ * {@include date/getDayOfMonth/index.md}
+ */
 function getDayOfMonth(input, timezone = "UTC") {
     const nativeDate = toNative.toNative(input);
     if (timezone === "UTC") {

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

@@ -1,2 +1,31 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the day of month of a date.
+ * 
+ * Signature: `getDayOfMonth(input, timezone)` → returns a value
+ * 
+ * If timezone is omitted, UTC is used.
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-01");
+ * const result = D.getDayOfMonth(input);
+ * // result: 1
+ * 
+ * const result2 = D.getDayOfMonth(input, "America/New_York");
+ * // result2: 1
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getDayOfMonth,
+ * ); // result: 1
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getDayOfMonth
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getDayOfMonth<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getDayOfMonth.mjs

@@ -1,5 +1,8 @@
 import { toNative } from '../toNative.mjs';
 
+/**
+ * {@include date/getDayOfMonth/index.md}
+ */
 function getDayOfMonth(input, timezone = "UTC") {
     const nativeDate = toNative(input);
     if (timezone === "UTC") {

package/dist/date/getters/getDayOfWeek.cjs

@@ -11,6 +11,9 @@ const weekdayMapper = {
     Friday: 5,
     Saturday: 6,
 };
+/**
+ * {@include date/getDayOfWeek/index.md}
+ */
 function getDayOfWeek(input, timezone = "UTC") {
     const nativeDate = toNative.toNative(input);
     if (timezone === "UTC") {

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

@@ -1,2 +1,31 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the day of week of a date.
+ * 
+ * Signature: `getDayOfWeek(input, timezone)` → returns a value
+ * 
+ * If timezone is omitted, UTC is used.
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-17");
+ * const result = D.getDayOfWeek(input);
+ * // result: 1
+ * 
+ * const result2 = D.getDayOfWeek(input, "Europe/London");
+ * // result2: 1
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getDayOfWeek,
+ * ); // result: 1
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getDayOfWeek
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getDayOfWeek<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getDayOfWeek.mjs

@@ -9,6 +9,9 @@ const weekdayMapper = {
     Friday: 5,
     Saturday: 6,
 };
+/**
+ * {@include date/getDayOfWeek/index.md}
+ */
 function getDayOfWeek(input, timezone = "UTC") {
     const nativeDate = toNative(input);
     if (timezone === "UTC") {

package/dist/date/getters/getDayOfYear.cjs

@@ -3,6 +3,9 @@
 var constants = require('../constants.cjs');
 var toNative = require('../toNative.cjs');
 
+/**
+ * {@include date/getDayOfYear/index.md}
+ */
 function getDayOfYear(input, timezone = "UTC") {
     const nativeDate = toNative.toNative(input);
     let year = 0;

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

@@ -1,2 +1,28 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the day of year of a date.
+ * 
+ * Signature: `getDayOfYear(input, timezone)` → returns a value
+ * 
+ * If timezone is omitted, UTC is used.
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-12-31");
+ * const result = D.getDayOfYear(input, "Australia/Sydney");
+ * // result: 366
+ * 
+ * pipe(
+ * 	input,
+ * 	(value) => D.getDayOfYear(value, "Australia/Sydney"),
+ * ); // result: 366
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getDayOfYear
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getDayOfYear<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getDayOfYear.mjs

@@ -1,6 +1,9 @@
 import { millisecondsInOneDay } from '../constants.mjs';
 import { toNative } from '../toNative.mjs';
 
+/**
+ * {@include date/getDayOfYear/index.md}
+ */
 function getDayOfYear(input, timezone = "UTC") {
     const nativeDate = toNative(input);
     let year = 0;

package/dist/date/getters/getFirstDayOfMonth.cjs

@@ -2,6 +2,9 @@
 
 var toNative = require('../toNative.cjs');
 
+/**
+ * {@include date/getFirstDayOfMonth/index.md}
+ */
 function getFirstDayOfMonth(input) {
     const nativeDate = toNative.toNative(input);
     nativeDate.setUTCDate(1);

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

@@ -1,2 +1,26 @@
 import type { TheDate } from "../types";
+/**
+ * Returns the first day of month of a date.
+ * 
+ * Signature: `getFirstDayOfMonth(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-19");
+ * const result = D.getFirstDayOfMonth(input);
+ * // result: "date1717200000000+" (1 June 2024)
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getFirstDayOfMonth,
+ * ); // result: "date1717200000000+" (1 June 2024)
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getFirstDayOfMonth
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getFirstDayOfMonth(input: TheDate): TheDate;

package/dist/date/getters/getFirstDayOfMonth.mjs

@@ -1,5 +1,8 @@
 import { toNative } from '../toNative.mjs';
 
+/**
+ * {@include date/getFirstDayOfMonth/index.md}
+ */
 function getFirstDayOfMonth(input) {
     const nativeDate = toNative(input);
     nativeDate.setUTCDate(1);

package/dist/date/getters/getFirstDayOfWeek.cjs

@@ -2,6 +2,9 @@
 
 var toNative = require('../toNative.cjs');
 
+/**
+ * {@include date/getFirstDayOfWeek/index.md}
+ */
 function getFirstDayOfWeek(input) {
     const nativeDate = toNative.toNative(input);
     const dayOfWeek = nativeDate.getUTCDay();

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

@@ -1,2 +1,26 @@
 import type { TheDate } from "../types";
+/**
+ * Returns the first day of week of a date.
+ * 
+ * Signature: `getFirstDayOfWeek(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-19");
+ * const result = D.getFirstDayOfWeek(input);
+ * // result: "date1718668800000+" (monday 17 june 2024)
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getFirstDayOfWeek,
+ * ); // result: "date1718668800000+" (monday 17 june 2024)
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getFirstDayOfWeek
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getFirstDayOfWeek(input: TheDate): TheDate;

package/dist/date/getters/getFirstDayOfWeek.mjs

@@ -1,5 +1,8 @@
 import { toNative } from '../toNative.mjs';
 
+/**
+ * {@include date/getFirstDayOfWeek/index.md}
+ */
 function getFirstDayOfWeek(input) {
     const nativeDate = toNative(input);
     const dayOfWeek = nativeDate.getUTCDay();

package/dist/date/getters/getHour.cjs

@@ -2,6 +2,9 @@
 
 var toNative = require('../toNative.cjs');
 
+/**
+ * {@include date/getHour/index.md}
+ */
 function getHour(input, timezone = "UTC") {
     const nativeDate = toNative.toNative(input);
     if (timezone === "UTC") {

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

@@ -1,2 +1,31 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the hour of a date.
+ * 
+ * Signature: `getHour(input, timezone)` → returns a value
+ * 
+ * If timezone is omitted, UTC is used.
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20");
+ * const result = D.getHour(input);
+ * // result: 0
+ * 
+ * const result2 = D.getHour(input, "America/Los_Angeles");
+ * // result2: 17
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getHour,
+ * ); // result: 0
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getHour
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getHour<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getHour.mjs

@@ -1,5 +1,8 @@
 import { toNative } from '../toNative.mjs';
 
+/**
+ * {@include date/getHour/index.md}
+ */
 function getHour(input, timezone = "UTC") {
     const nativeDate = toNative(input);
     if (timezone === "UTC") {

package/dist/date/getters/getLastDayOfMonth.cjs

@@ -2,6 +2,9 @@
 
 var toNative = require('../toNative.cjs');
 
+/**
+ * {@include date/getLastDayOfMonth/index.md}
+ */
 function getLastDayOfMonth(input) {
     const nativeDate = toNative.toNative(input);
     nativeDate.setUTCMonth(nativeDate.getUTCMonth() + 1, 0);

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

@@ -1,2 +1,26 @@
 import type { TheDate } from "../types";
+/**
+ * Returns the last day of month of a date.
+ * 
+ * Signature: `getLastDayOfMonth(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-19");
+ * const result = D.getLastDayOfMonth(input);
+ * // result: "date1719532800000+" (30 June 2024)
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getLastDayOfMonth,
+ * ); // result: "date1719532800000+" (30 June 2024)
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getLastDayOfMonth
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getLastDayOfMonth(input: TheDate): TheDate;

package/dist/date/getters/getLastDayOfMonth.mjs

@@ -1,5 +1,8 @@
 import { toNative } from '../toNative.mjs';
 
+/**
+ * {@include date/getLastDayOfMonth/index.md}
+ */
 function getLastDayOfMonth(input) {
     const nativeDate = toNative(input);
     nativeDate.setUTCMonth(nativeDate.getUTCMonth() + 1, 0);

package/dist/date/getters/getLastDayOfWeek.cjs

@@ -2,6 +2,9 @@
 
 var toNative = require('../toNative.cjs');
 
+/**
+ * {@include date/getLastDayOfWeek/index.md}
+ */
 function getLastDayOfWeek(input) {
     const nativeDate = toNative.toNative(input);
     const dayOfWeek = nativeDate.getUTCDay();

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

@@ -1,2 +1,26 @@
 import type { TheDate } from "../types";
+/**
+ * Returns the last day of week of a date.
+ * 
+ * Signature: `getLastDayOfWeek(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-19");
+ * const result = D.getLastDayOfWeek(input);
+ * // result: "date1719187200000+" (Sunday 23 june 2024)
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getLastDayOfWeek,
+ * ); // result: "date1719187200000+" (Sunday 23 june 2024)
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getLastDayOfWeek
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getLastDayOfWeek(input: TheDate): TheDate;

package/dist/date/getters/getLastDayOfWeek.mjs

@@ -1,5 +1,8 @@
 import { toNative } from '../toNative.mjs';
 
+/**
+ * {@include date/getLastDayOfWeek/index.md}
+ */
 function getLastDayOfWeek(input) {
     const nativeDate = toNative(input);
     const dayOfWeek = nativeDate.getUTCDay();