@byloth/core 2.0.0-rc.8 → 2.0.0

package/src/utils/async.ts

@@ -1,13 +1,56 @@
+/**
+ * Returns a promise that resolves after a certain number of milliseconds.  
+ * It can be used to pause or delay the execution of an asynchronous function.
+ *
+ * ```ts
+ * doSomething();
+ * await delay(1_000);
+ * doSomethingElse();
+ * ```
+ *
+ * @param milliseconds The number of milliseconds to wait before resolving the promise.
+ *
+ * @returns A {@link Promise} that resolves after the specified number of milliseconds.
+ */
 export function delay(milliseconds: number): Promise<void>
 {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
+/**
+ * Returns a promise that resolves on the next animation frame.  
+ * It can be used to synchronize operations with the browser's rendering cycle.
+ *
+ * ```ts
+ * const $el = document.querySelector(".element");
+ *
+ * $el.classList.add("animate");
+ * await nextAnimationFrame();
+ * $el.style.opacity = "1";
+ * ```
+ *
+ * @returns A {@link Promise} that resolves on the next animation frame.
+ */
 export function nextAnimationFrame(): Promise<void>
 {
     return new Promise((resolve) => requestAnimationFrame(() => resolve()));
 }
 
+/**
+ * Returns a promise that resolves on the next microtask.  
+ * It can be used to yield to the event loop in long-running operations to prevent blocking the main thread.
+ *
+ * ```ts
+ * for (let i = 0; i < 100_000_000; i += 1)
+ * {
+ *     doSomething(i);
+ *
+ *     if (i % 100 === 0) await yieldToEventLoop();
+ * }
+ * ```
+ *
+ * @returns A {@link Promise} that resolves on the next microtask.
+ */
 export function yieldToEventLoop(): Promise<void>
 {
     return new Promise((resolve) => setTimeout(resolve));

package/src/utils/curve.ts

@@ -0,0 +1,75 @@
+import { SmartIterator, ValueException } from "../models/index.js";
+
+/**
+ * A utility class that provides a set of methods to generate sequences of numbers following specific curves.  
+ * It can be used to generate sequences of values that can be
+ * used in animations, transitions and other different scenarios.
+ *
+ * It cannot be instantiated directly.
+ */
+export default class Curve
+{
+    /**
+     * Generates a given number of values following a linear curve.  
+     * The values are equally spaced and normalized between 0 and 1.
+     *
+     * ```ts
+     * for (const value of Curve.Linear(5))
+     * {
+     *     console.log(value); // 0, 0.25, 0.5, 0.75, 1
+     * }
+     * ```
+     *
+     * @param values The number of values to generate.
+     *
+     * @returns A {@link SmartIterator} object that generates the values following a linear curve.
+     */
+    public static Linear(values: number): SmartIterator<number>
+    {
+        const steps = (values - 1);
+
+        return new SmartIterator<number>(function* ()
+        {
+            for (let index = 0; index < values; index += 1) { yield index / steps; }
+        });
+    }
+
+    /**
+     * Generates a given number of values following an exponential curve.  
+     * The values are equally spaced and normalized between 0 and 1.
+     *
+     * ```ts
+     * for (const value of Curve.Exponential(6))
+     * {
+     *     console.log(value); // 0, 0.04, 0.16, 0.36, 0.64, 1
+     * }
+     * ```
+     *
+     * @param values The number of values to generate.
+     * @param base
+     * The base of the exponential curve. Default is `2`.
+     *
+     * Also note that:
+     * - If it's equal to `1`, the curve will be linear.
+     * - If it's included between `0` and `1`, the curve will be logarithmic.
+     *
+     * The base cannot be negative. If so, a {@link ValueException} will be thrown.
+     *
+     * @returns A {@link SmartIterator} object that generates the values following an exponential curve.
+     */
+    public static Exponential(values: number, base = 2): SmartIterator<number>
+    {
+        if (base < 0) { throw new ValueException("The base of the exponential curve cannot be negative."); }
+
+        const steps = (values - 1);
+
+        return new SmartIterator<number>(function* ()
+        {
+            for (let index = 0; index < values; index += 1) { yield Math.pow(index / steps, base); }
+        });
+    }
+
+    private constructor() { /* ... */ }
+
+    public readonly [Symbol.toStringTag]: string = "Curve";
+}

package/src/utils/date.ts

@@ -1,50 +1,244 @@
 
-import { SmartIterator } from "../models/index.js";
+import { RangeException, SmartIterator } from "../models/index.js";
 
+/**
+ * An enumeration that represents the time units and their conversion factors.  
+ * It can be used as utility to express time values in a more
+ * readable way or to convert time values between different units.
+ *
+ * ```ts
+ * setTimeout(() => { [...] }, 5 * TimeUnit.Minute);
+ * ```
+ */
 export enum TimeUnit
 {
     /* eslint-disable @typescript-eslint/prefer-literal-enum-member */
 
+    /**
+     * A millisecond: the base time unit.
+     */
     Millisecond = 1,
-    Second = 1000,
+
+    /**
+     * A second: 1000 milliseconds.
+     */
+    Second = 1_000,
+
+    /**
+     * A minute: 60 seconds.
+     */
     Minute = 60 * Second,
+
+    /**
+     * An hour: 60 minutes.
+     */
     Hour = 60 * Minute,
+
+    /**
+     * A day: 24 hours.
+     */
     Day = 24 * Hour,
+
+    /**
+     * A week: 7 days.
+     */
     Week = 7 * Day,
+
+    /**
+     * A month: 30 days.
+     */
     Month = 30 * Day,
+
+    /**
+     * A year: 365 days.
+     */
     Year = 365 * Day
 }
 
+/**
+ * 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.
+ *
+ * ```ts
+ * const today = new Date();
+ * if (today.getUTCDay() === WeekDay.Sunday)
+ * {
+ *     // Today is Sunday. Do something...
+ * }
+ * ```
+ */
+export enum WeekDay
+{
+    /**
+     * Sunday
+     */
+    Sunday = 0,
+
+    /**
+     * Monday
+     */
+    Monday = 1,
+
+    /**
+     * Tuesday
+     */
+    Tuesday = 2,
+
+    /**
+     * Wednesday
+     */
+    Wednesday = 3,
+
+    /**
+     * Thursday
+     */
+    Thursday = 4,
+
+    /**
+     * Friday
+     */
+    Friday = 5,
+
+    /**
+     * Saturday
+     */
+    Saturday = 6
+}
+
+/**
+ * An utility function that calculates the difference between two dates.  
+ * The difference can be expressed in different time units.
+ *
+ * ```ts
+ * const start = new Date("2025-01-01");
+ * const end = new Date("2025-01-31");
+ *
+ * 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
 {
+    let _round: (value: number) => number;
+
     start = new Date(start);
     end = new Date(end);
 
-    return Math.floor((end.getTime() - start.getTime()) / unit);
+    if (start < end) { _round = Math.floor; }
+    else { _round = Math.ceil; }
+
+    return _round((end.getTime() - start.getTime()) / unit);
 }
 
-export function dateRange(start: string | Date, end: string | Date, offset = TimeUnit.Day): SmartIterator<Date>
+/**
+ * An utility function that generates an iterator over a range of dates.  
+ * The step between the dates can be expressed in different time units.
+ *
+ * ```ts
+ * const start = new Date("2025-01-01");
+ * const end = new Date("2025-01-31");
+ *
+ * for (const date of dateRange(start, end, TimeUnit.Week))
+ * {
+ *     date.toISOString().slice(8, 10); // "01", "08", "15", "22", "29"
+ * }
+ * ```
+ *
+ * @param start The start date (included).
+ * @param end
+ * The end date (excluded).
+ *
+ * Must be greater than the start date. Otherwise, a {@link RangeException} will be thrown.
+ *
+ * @param step The time unit to express the step between the dates. `TimeUnit.Day` by default.
+ *
+ * @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>
 {
-    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 = end.getTime();
+        const endTime = new Date(end).getTime();
 
-        let unixTime: number = start.getTime();
+        let unixTime: number = new Date(start).getTime();
         while (unixTime < endTime)
         {
             yield new Date(unixTime);
 
-            unixTime += offset;
+            unixTime += step;
         }
     });
 }
 
+/**
+ * An utility function that rounds a date to the nearest time unit.  
+ * The rounding can be expressed in different time units.
+ *
+ * ```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.
+ *
+ * Must be greater than a millisecond and less than or equal to a day.  
+ * Otherwise, a {@link RangeException} will be thrown.
+ *
+ * @returns The rounded date.
+ */
 export function dateRound(date: string | Date, unit = TimeUnit.Day): Date
 {
-    date = new Date(date);
+    if (unit <= TimeUnit.Millisecond)
+    {
+        throw new RangeException(
+            "Rounding a timestamp by milliseconds or less makes no sense." +
+            "Use the timestamp value directly instead."
+        );
+    }
+    if (unit > TimeUnit.Day)
+    {
+        throw new RangeException(
+            "Rounding by more than a day leads to unexpected results. " +
+            "Consider using other methods to round dates by weeks, months or years."
+        );
+    }
 
+    date = new Date(date);
     return new Date(Math.floor(date.getTime() / unit) * unit);
 }
+
+/**
+ * An utility function that gets the week of a date.  
+ * The first day of the week can be optionally specified.
+ *
+ * ```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
+{
+    date = new Date(date);
+
+    const startCorrector = 7 - firstDay;
+    const weekDayIndex = (date.getUTCDay() + startCorrector) % 7;
+    const firstDayTime = date.getTime() - (TimeUnit.Day * weekDayIndex);
+
+    return dateRound(new Date(firstDayTime));
+}

package/src/utils/dom.ts

@@ -1,3 +1,17 @@
+/**
+ * Appends a script element to the document body.  
+ * It can be used to load external scripts dynamically.
+ *
+ * ```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"`.
+ *
+ * @returns
+ * A {@link Promise} that resolves when the script has been loaded successfully or rejects if an error occurs.
+ */
 export function loadScript(scriptUrl: string, scriptType = "text/javascript"): Promise<void>
 {
     return new Promise<void>((resolve, reject) =>
@@ -9,8 +23,8 @@ export function loadScript(scriptUrl: string, scriptType = "text/javascript"): P
         script.src = scriptUrl;
         script.type = scriptType;
 
-        script.onload = () => resolve();
-        script.onerror = () => reject();
+        script.onload = (evt) => resolve();
+        script.onerror = (reason) => reject(reason);
 
         document.body.appendChild(script);
     });

package/src/utils/index.ts

@@ -1,10 +1,11 @@
+import Curve from "./curve.js";
 import Random from "./random.js";
 
 export { delay, nextAnimationFrame, yieldToEventLoop } from "./async.js";
-export { dateDifference, dateRange, dateRound, TimeUnit } from "./date.js";
+export { dateDifference, dateRange, dateRound, getWeek, TimeUnit, WeekDay } from "./date.js";
 export { loadScript } from "./dom.js";
 export { chain, count, enumerate, range, shuffle, unique, zip } from "./iterator.js";
 export { average, hash, sum } from "./math.js";
 export { capitalize } from "./string.js";
 
-export { Random };
+export { Curve, Random };