@duplojs/utils 1.3.32 → 1.4.33

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();

package/dist/date/getters/getMilliseconds.cjs

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

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

@@ -1,2 +1,31 @@
 import { type TheDate } from "..";
+/**
+ * Returns the milliseconds of a date.
+ * 
+ * Signature: `getMilliseconds(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20", {
+ * 	hour: "12",
+ * 	minute: "34",
+ * 	second: "56",
+ * 	millisecond: "789",
+ * });
+ * const result = D.getMilliseconds(input);
+ * // result: 789
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getMilliseconds,
+ * ); // result: 789
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getMilliseconds
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getMilliseconds<GenericInput extends TheDate>(input: GenericInput): number;

package/dist/date/getters/getMilliseconds.mjs

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

package/dist/date/getters/getMinute.cjs

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

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

@@ -1,2 +1,31 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the minute of a date.
+ * 
+ * Signature: `getMinute(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.getMinute(input);
+ * // result: 0
+ * 
+ * const result2 = D.getMinute(input, "Europe/Madrid");
+ * // result2: 0
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getMinute,
+ * ); // result: 0
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getMinute
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getMinute<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getMinute.mjs

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

package/dist/date/getters/getMonth.cjs

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

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

@@ -1,2 +1,31 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the month of a date.
+ * 
+ * Signature: `getMonth(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.getMonth(input);
+ * // result: 12
+ * 
+ * const result2 = D.getMonth(input, "Asia/Tokyo");
+ * // result2: 12
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getMonth,
+ * ); // result: 12
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getMonth
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getMonth<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getMonth.mjs

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

package/dist/date/getters/getSecond.cjs

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

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

@@ -1,2 +1,31 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the second of a date.
+ * 
+ * Signature: `getSecond(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.getSecond(input);
+ * // result: 0
+ * 
+ * const result2 = D.getSecond(input, "Asia/Seoul");
+ * // result2: 0
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getSecond,
+ * ); // result: 0
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getSecond
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getSecond<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getSecond.mjs

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

package/dist/date/getters/getWeekOfYear.cjs

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

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

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

package/dist/date/getters/getWeekOfYear.mjs

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

package/dist/date/getters/getYear.cjs

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

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

@@ -1,2 +1,31 @@
 import { type TheDate, type Timezone } from "..";
+/**
+ * Returns the year of a date.
+ * 
+ * Signature: `getYear(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.getYear(input);
+ * // result: 2024
+ * 
+ * const result2 = D.getYear(input, "Europe/Paris");
+ * // result2: 2024
+ * 
+ * pipe(
+ * 	input,
+ * 	D.getYear,
+ * ); // result: 2024
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getYear
+ * 
+ * @namespace D
+ * 
+ */
 export declare function getYear<GenericInput extends TheDate>(input: GenericInput, timezone?: Timezone): number;

package/dist/date/getters/getYear.mjs

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

package/dist/date/index.cjs

@@ -28,11 +28,13 @@ var timezone = require('./timezone.cjs');
 var getTimezoneOffset = require('./getTimezoneOffset.cjs');
 var applyTimezone = require('./applyTimezone.cjs');
 var format = require('./format.cjs');
+var formatTime = require('./formatTime.cjs');
 var makeSafeTimestamp = require('./makeSafeTimestamp.cjs');
 var createTheDate = require('./createTheDate.cjs');
 var createTheTime = require('./createTheTime.cjs');
 var createTime = require('./createTime.cjs');
 var createTimeOrThrow = require('./createTimeOrThrow.cjs');
+var makeSafeTimeValue = require('./makeSafeTimeValue.cjs');
 var getDayOfMonth = require('./getters/getDayOfMonth.cjs');
 var getDayOfWeek = require('./getters/getDayOfWeek.cjs');
 var getFirstDayOfWeek = require('./getters/getFirstDayOfWeek.cjs');
@@ -78,7 +80,9 @@ var lessThan = require('./operators/lessThan.cjs');
 var lessThanTime = require('./operators/lessThanTime.cjs');
 var lessTime = require('./operators/lessTime.cjs');
 
-
+/**
+ * {@include date/index.md}
+ */
 
 exports.daysInOneWeek = constants.daysInOneWeek;
 exports.hoursInOneDay = constants.hoursInOneDay;
@@ -126,12 +130,14 @@ exports.timezone = timezone.timezone;
 exports.getTimezoneOffset = getTimezoneOffset.getTimezoneOffset;
 exports.applyTimezone = applyTimezone.applyTimezone;
 exports.format = format.format;
+exports.formatTime = formatTime.formatTime;
 exports.makeSafeTimestamp = makeSafeTimestamp.makeSafeTimestamp;
 exports.createTheDate = createTheDate.createTheDate;
 exports.createTheTime = createTheTime.createTheTime;
 exports.createTime = createTime.createTime;
 exports.CreateTheTimeError = createTimeOrThrow.CreateTheTimeError;
 exports.createTimeOrThrow = createTimeOrThrow.createTimeOrThrow;
+exports.makeSafeTimeValue = makeSafeTimeValue.makeSafeTimeValue;
 exports.getDayOfMonth = getDayOfMonth.getDayOfMonth;
 exports.getDayOfWeek = getDayOfWeek.getDayOfWeek;
 exports.getFirstDayOfWeek = getFirstDayOfWeek.getFirstDayOfWeek;

package/dist/date/index.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Date utilities for immutable, type-safe date manipulation. Functions preserve the
+ * original value and return new values.
+ * 
+ * This namespace introduces a dedicated `TheDate` (`date{number}{'-'|'+'}`) type, different from the native `Date`.
+ * It is universal and exchange-friendly, based on UTC timestamps to avoid timezone pitfalls.
+ * Conversion helpers let you move between `TheDate` and other date formats when needed.
+ * 
+ * **How to import:**
+ * - From the main entry (namespace style)
+ * - Via direct import for tree-shaking
+ * 
+ * ```ts
+ * import { DDate, D } from "@duplojs/utils";
+ * import * as DDate from "@duplojs/utils/date";
+ * import * as D from "@duplojs/utils/date";
+ * ```
+ * 
+ * What you will find in this namespace:
+ * - creation and conversion (`D.create`, `D.createOrThrow`, `D.toNative`, `D.toTimestamp`, `D.toISOString`)
+ * - relative dates (`D.now`, `D.today`, `D.yesterday`, `D.tomorrow`)
+ * - formatting and timezone (`D.format`, `D.timezone`, `D.applyTimezone`, `D.getTimezoneOffset`)
+ * - collections and ordering (`D.min`, `D.max`, `D.sort`, `D.closestTo`)
+ * - iteration and rounding (`D.each`, `D.round`)
+ * - checks (`D.is`, `D.isSafeTimestamp`)
+ * - constants and types (`D.constants`, `D.types`)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date
+ * 
+ * @namespace D
+ * 
+ */
 export * from "./types";
 export * from "./constants";
 export * from "./create";
@@ -30,8 +62,10 @@ export * from "./timezone";
 export * from "./getTimezoneOffset";
 export * from "./applyTimezone";
 export * from "./format";
+export * from "./formatTime";
 export * from "./makeSafeTimestamp";
 export * from "./createTheDate";
 export * from "./createTheTime";
 export * from "./createTime";
 export * from "./createTimeOrThrow";
+export * from "./makeSafeTimeValue";

package/dist/date/index.mjs

@@ -26,11 +26,13 @@ export { timezone } from './timezone.mjs';
 export { getTimezoneOffset } from './getTimezoneOffset.mjs';
 export { applyTimezone } from './applyTimezone.mjs';
 export { format } from './format.mjs';
+export { formatTime } from './formatTime.mjs';
 export { makeSafeTimestamp } from './makeSafeTimestamp.mjs';
 export { createTheDate } from './createTheDate.mjs';
 export { createTheTime } from './createTheTime.mjs';
 export { createTime } from './createTime.mjs';
 export { CreateTheTimeError, createTimeOrThrow } from './createTimeOrThrow.mjs';
+export { makeSafeTimeValue } from './makeSafeTimeValue.mjs';
 export { getDayOfMonth } from './getters/getDayOfMonth.mjs';
 export { getDayOfWeek } from './getters/getDayOfWeek.mjs';
 export { getFirstDayOfWeek } from './getters/getFirstDayOfWeek.mjs';
@@ -75,3 +77,7 @@ export { less } from './operators/less.mjs';
 export { lessThan } from './operators/lessThan.mjs';
 export { lessThanTime } from './operators/lessThanTime.mjs';
 export { lessTime } from './operators/lessTime.mjs';
+
+/**
+ * {@include date/index.md}
+ */

package/dist/date/is.cjs

@@ -3,6 +3,9 @@
 var constants = require('./constants.cjs');
 var isSafeTimestamp = require('./isSafeTimestamp.cjs');
 
+/**
+ * {@include date/is/index.md}
+ */
 function is(input) {
     const theDateMatch = input.match(constants.theDateRegex);
     if (theDateMatch) {

package/dist/date/is.d.ts

@@ -1,2 +1,32 @@
 import { type TheDate } from "./types";
+/**
+ * Checks whether a value is a TheDate.
+ * 
+ * Signature: `is(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.now() as string;
+ * 
+ * if (D.is(input)) {
+ * 	// input is TheDate
+ * }
+ * 
+ * pipe(
+ * 	input,
+ * 	when(
+ * 		D.is,
+ * 		(value) => {
+ * 			// value is TheDate
+ * 		},
+ * 	),
+ * );
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/is
+ * 
+ * @namespace D
+ * 
+ */
 export declare function is(input: string): input is TheDate;

package/dist/date/is.mjs

@@ -1,6 +1,9 @@
 import { theDateRegex } from './constants.mjs';
 import { isSafeTimestamp } from './isSafeTimestamp.mjs';
 
+/**
+ * {@include date/is/index.md}
+ */
 function is(input) {
     const theDateMatch = input.match(theDateRegex);
     if (theDateMatch) {

package/dist/date/isSafeTimeValue.cjs

@@ -2,6 +2,9 @@
 
 var constants = require('./constants.cjs');
 
+/**
+ * {@include date/isSafeTimeValue/index.md}
+ */
 function isSafeTimeValue(timeValue) {
     if (!Number.isSafeInteger(timeValue)) {
         return false;

package/dist/date/isSafeTimeValue.d.ts

@@ -1 +1,27 @@
+/**
+ * Checks whether a time value is safe.
+ * 
+ * Signature: `isSafeTimeValue(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = D.isSafeTimeValue(1_500);
+ * // result: true
+ * 
+ * const result2 = D.isSafeTimeValue(Number.NaN);
+ * // result2: false
+ * 
+ * const result3 = D.isSafeTimeValue(9_007_199_254_740_992);
+ * // result3: false
+ * ```
+ * 
+ * @remarks
+ * - Checks for safe integers within the supported time range.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/isSafeTimeValue
+ * 
+ * @namespace D
+ * 
+ */
 export declare function isSafeTimeValue(timeValue: number): boolean;