@byloth/core 2.0.1 → 2.1.0

package/src/utils/date.ts

@@ -6,6 +6,9 @@ import { RangeException, SmartIterator } from "../models/index.js";
  * It can be used as utility to express time values in a more
  * readable way or to convert time values between different units.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * setTimeout(() => { [...] }, 5 * TimeUnit.Minute);
  * ```
@@ -59,6 +62,9 @@ export enum TimeUnit
  * An enumeration that represents the days of the week.  
  * It can be used as utility to identify the days of the week when working with dates.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const today = new Date();
  * if (today.getUTCDay() === WeekDay.Sunday)
@@ -109,6 +115,9 @@ export enum WeekDay
  * An utility function that calculates the difference between two dates.  
  * The difference can be expressed in different time units.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const start = new Date("2025-01-01");
  * const end = new Date("2025-01-31");
@@ -116,13 +125,15 @@ export enum WeekDay
  * dateDifference(start, end, TimeUnit.Minute); // 43200
  * ```
  *
+ * ---
+ *
  * @param start The start date.
  * @param end The end date.
  * @param unit The time unit to express the difference. `TimeUnit.Day` by default.
  *
  * @returns The difference between the two dates in the specified time unit.
  */
-export function dateDifference(start: string | Date, end: string | Date, unit = TimeUnit.Day): number
+export function dateDifference(start: number | string | Date, end: number | string | Date, unit = TimeUnit.Day): number
 {
     let _round: (value: number) => number;
 
@@ -139,6 +150,9 @@ export function dateDifference(start: string | Date, end: string | Date, unit =
  * An utility function that generates an iterator over a range of dates.  
  * The step between the dates can be expressed in different time units.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const start = new Date("2025-01-01");
  * const end = new Date("2025-01-31");
@@ -149,6 +163,8 @@ export function dateDifference(start: string | Date, end: string | Date, unit =
  * }
  * ```
  *
+ * ---
+ *
  * @param start The start date (included).
  * @param end
  * The end date (excluded).
@@ -159,15 +175,19 @@ export function dateDifference(start: string | Date, end: string | Date, unit =
  *
  * @returns A {@link SmartIterator} object that generates the dates in the range.
  */
-export function dateRange(start: string | Date, end: string | Date, step = TimeUnit.Day): SmartIterator<Date>
+export function dateRange(start: number | string | Date, end: number | string | Date, step = TimeUnit.Day)
+    : SmartIterator<Date>
 {
+    start = new Date(start);
+    end = new Date(end);
+
     if (start >= end) { throw new RangeException("The end date must be greater than the start date."); }
 
     return new SmartIterator<Date>(function* ()
     {
-        const endTime = new Date(end).getTime();
+        const endTime = end.getTime();
 
-        let unixTime: number = new Date(start).getTime();
+        let unixTime: number = start.getTime();
         while (unixTime < endTime)
         {
             yield new Date(unixTime);
@@ -181,12 +201,17 @@ export function dateRange(start: string | Date, end: string | Date, step = TimeU
  * An utility function that rounds a date to the nearest time unit.  
  * The rounding can be expressed in different time units.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const date = new Date("2025-01-01T12:34:56.789Z");
  *
  * dateRound(date, TimeUnit.Hour); // 2025-01-01T12:00:00.000Z
  * ```
  *
+ * ---
+ *
  * @param date The date to round.
  * @param unit
  * The time unit to express the rounding. `TimeUnit.Day` by default.
@@ -196,7 +221,7 @@ export function dateRange(start: string | Date, end: string | Date, step = TimeU
  *
  * @returns The rounded date.
  */
-export function dateRound(date: string | Date, unit = TimeUnit.Day): Date
+export function dateRound(date: number | string | Date, unit = TimeUnit.Day): Date
 {
     if (unit <= TimeUnit.Millisecond)
     {
@@ -221,18 +246,23 @@ export function dateRound(date: string | Date, unit = TimeUnit.Day): Date
  * An utility function that gets the week of a date.  
  * The first day of the week can be optionally specified.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const date = new Date("2025-01-01");
  *
  * getWeek(date, WeekDay.Monday); // 2024-12-30
  * ```
  *
+ * ---
+ *
  * @param date The date to get the week of.
  * @param firstDay The first day of the week. `WeekDay.Sunday` by default.
  *
  * @returns The first day of the week of the specified date.
  */
-export function getWeek(date: string | Date, firstDay = WeekDay.Sunday): Date
+export function getWeek(date: number | string | Date, firstDay = WeekDay.Sunday): Date
 {
     date = new Date(date);
 

package/src/utils/dom.ts

@@ -2,10 +2,15 @@
  * Appends a script element to the document body.  
  * It can be used to load external scripts dynamically.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * await loadScript("https://analytics.service/script.js?id=0123456789");
  * ```
  *
+ * ---
+ *
  * @param scriptUrl The URL of the script to load.
  * @param scriptType The type of the script to load. Default is `"text/javascript"`.
  *

package/src/utils/iterator.ts

@@ -10,6 +10,9 @@ import { RangeException, SmartIterator } from "../models/index.js";
  * This means that the original iterator won't be consumed until the
  * new one is and that consuming one of them will consume the other as well.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * for (const value of chain([1, 2, 3], [4, 5, 6], [7, 8, 9]))
  * {
@@ -17,6 +20,8 @@ import { RangeException, SmartIterator } from "../models/index.js";
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterables.
  *
  * @param iterables The list of iterables to chain.
@@ -38,13 +43,18 @@ export function chain<T>(...iterables: readonly Iterable<T>[]): SmartIterator<T>
  * An utility function that counts the number of elements in an iterable.
  *
  * Also note that:
- * - If the iterable isn't an `Array`, it will be consumed entirely in the process.
+ * - If the iterable isn't an {@link Array}, it will be consumed entirely in the process.
  * - If the iterable is an infinite generator, the function will never return.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * count([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // 10
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterable.
  *
  * @param elements The iterable to count.
@@ -72,6 +82,9 @@ export function count<T>(elements: Iterable<T>): number
  * This means that the original iterator won't be consumed until the
  * new one is and that consuming one of them will consume the other as well.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * for (const [index, value] of enumerate(["A", "M", "N", "Z"]))
  * {
@@ -79,6 +92,8 @@ export function count<T>(elements: Iterable<T>): number
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterable.
  *
  * @param elements The iterable to enumerate.
@@ -105,6 +120,9 @@ export function enumerate<T>(elements: Iterable<T>): SmartIterator<[number, T]>
  *
  * The default step between the numbers is `1`.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * for (const number of range(5))
  * {
@@ -112,6 +130,8 @@ export function enumerate<T>(elements: Iterable<T>): SmartIterator<[number, T]>
  * }
  * ```
  *
+ * ---
+ *
  * @param end
  * The end value (excluded).
  *
@@ -127,6 +147,9 @@ export function range(end: number): SmartIterator<number>;
  *
  * The step between the numbers can be specified with a custom value. Default is `1`.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * for (const number of range(2, 7))
  * {
@@ -134,6 +157,8 @@ export function range(end: number): SmartIterator<number>;
  * }
  * ```
  *
+ * ---
+ *
  * @param start
  * The start value (included).
  *
@@ -188,14 +213,19 @@ export function range(start: number, end?: number, step = 1): SmartIterator<numb
  * algorithm to shuffle the elements.
  *
  * Also note that:
- * - If the iterable is an `Array`, it won't be modified since the shuffling isn't done in-place.
- * - If the iterable isn't an `Array`, it will be consumed entirely in the process.
+ * - If the iterable is an {@link Array}, it won't be modified since the shuffling isn't done in-place.
+ * - If the iterable isn't an {@link Array}, it will be consumed entirely in the process.
  * - If the iterable is an infinite generator, the function will never return.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * shuffle([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4]
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterable.
  *
  * @param iterable The iterable to shuffle.
@@ -219,6 +249,9 @@ export function shuffle<T>(iterable: Iterable<T>): T[]
 /**
  * An utility function that filters the elements of an iterable ensuring that they are all unique.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * for (const value of unique([1, 1, 2, 3, 2, 3, 4, 5, 5, 4]))
  * {
@@ -226,6 +259,8 @@ export function shuffle<T>(iterable: Iterable<T>): T[]
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterable.
  *
  * @param elements The iterable to filter.
@@ -254,6 +289,9 @@ export function unique<T>(elements: Iterable<T>): SmartIterator<T>
  *
  * The function will stop when one of the two iterables is exhausted.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * for (const [number, char] of zip([1, 2, 3, 4], ["A", "M", "N" "Z"]))
  * {
@@ -261,6 +299,8 @@ export function unique<T>(elements: Iterable<T>): SmartIterator<T>
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the first iterable.
  * @template U The type of elements in the second iterable.
  *

package/src/utils/math.ts

@@ -5,11 +5,16 @@ import { zip } from "./iterator.js";
  * Computes the average of a given list of values.  
  * The values can be weighted using an additional list of weights.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * average([1, 2, 3, 4, 5]); // 3
  * average([6, 8.5, 4], [3, 2, 1]); // 6.5
  * ```
  *
+ * ---
+ *
  * @template T The type of the values in the list. It must be or extend a `number` object.
  *
  * @param values
@@ -73,11 +78,16 @@ export function average<T extends number>(values: Iterable<T>, weights?: Iterabl
  * {@link http://www.cse.yorku.ca/~oz/hash.html#djb2|djb2} algorithm.  
  * However, the hash is garanteed to be a 32-bit signed integer.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * hash("Hello, world!"); // -1880044555
  * hash("How are you?"); // 1761539132
  * ```
  *
+ * ---
+ *
  * @param value The string to hash.
  *
  * @returns The hash of the specified string.
@@ -99,10 +109,15 @@ export function hash(value: string): number
 /**
  * Sums all the values of a given list.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * sum([1, 2, 3, 4, 5]); // 15
  * ```
  *
+ * ---
+ *
  * @template T The type of the values in the list. It must be or extend a `number` object.
  *
  * @param values The list of values to sum.

package/src/utils/random.ts

@@ -142,6 +142,8 @@ export default class Random
     /**
      * Picks a random valid index from a given array of elements.
      *
+     * ---
+     *
      * @template T The type of the elements in the array.
      *
      * @param elements
@@ -161,6 +163,8 @@ export default class Random
     /**
      * Picks a random element from a given array of elements.
      *
+     * ---
+     *
      * @template T The type of the elements in the array.
      *
      * @param elements

package/src/utils/string.ts

@@ -1,10 +1,15 @@
 /**
  * Capitalize the first letter of a string.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * capitalize('hello'); // 'Hello'
  * ```
  *
+ * ---
+ *
  * @param value The string to capitalize.
  *
  * @returns The capitalized string.