@design-edito/tools 0.4.5 → 0.4.11

package/agnostic/strings/to-alphanum/index.js

@@ -1,9 +1,24 @@
-// src/agnostic/strings/to-alphanum/index.ts
-function toAlphanum(string, replacer = "") {
-  const replaced = string.replace(/[^a-z0-9]/igm, replacer);
-  if (replacer.length === 0) return replaced;
-  return replaced.replace(new RegExp(`${replacer}+`, "igm"), replacer);
+/**
+ * Converts a string to an alphanumeric-only string.
+ *
+ * Non-alphanumeric characters are replaced with the provided `replacer`.
+ * Consecutive occurrences of the `replacer` are collapsed into a single instance.
+ *
+ * @param string - The input string to sanitize.
+ * @param replacer - The string to replace non-alphanumeric characters with. Defaults to empty string.
+ * @returns The sanitized alphanumeric string.
+ *
+ * @example
+ * toAlphanum("Hello, World!")
+ * // => "HelloWorld"
+ *
+ * @example
+ * toAlphanum("Hello, World!", "-")
+ * // => "Hello-World"
+ */
+export function toAlphanum(string, replacer = '') {
+    const replaced = string.replace(/[^a-z0-9]/igm, replacer);
+    if (replacer.length === 0)
+        return replaced;
+    return replaced.replace(new RegExp(`${replacer}+`, 'igm'), replacer);
 }
-export {
-  toAlphanum
-};

package/agnostic/strings/trim/index.js

@@ -1,11 +1,24 @@
-// src/agnostic/strings/trim/index.ts
-function trimStart(string) {
-  return string.replace(/^\s*/, "");
+/**
+ * Removes all leading whitespace characters from a string.
+ *
+ * @param string - The string to trim.
+ * @returns The input string without leading whitespace.
+ *
+ * @example
+ * trimStart("   hello") // => "hello"
+ */
+export function trimStart(string) {
+    return string.replace(/^\s*/, '');
 }
-function trimEnd(string) {
-  return string.replace(/\s*$/, "");
+/**
+ * Removes all trailing whitespace characters from a string.
+ *
+ * @param string - The string to trim.
+ * @returns The input string without trailing whitespace.
+ *
+ * @example
+ * trimEnd("hello   ") // => "hello"
+ */
+export function trimEnd(string) {
+    return string.replace(/\s*$/, '');
 }
-export {
-  trimEnd,
-  trimStart
-};

package/agnostic/time/dates/format-date/index.js

@@ -1,74 +1,142 @@
-// src/agnostic/time/dates/format-date/index.ts
-function formatDate(date, format, locale = "en") {
-  if (Intl.DateTimeFormat.supportedLocalesOf(locale).length === 0) {
-    locale = "en";
-  }
-  const day = date.getDate();
-  const dayOfWeek = date.getDay();
-  const month = date.getMonth();
-  const year = date.getFullYear();
-  const hours = date.getHours();
-  const minutes = date.getMinutes();
-  const seconds = date.getSeconds();
-  const isPM = hours >= 12;
-  const shortDateNames = [...Array(7)].map((_, i) => new Intl.DateTimeFormat(
-    locale,
-    { weekday: "short" }
-  ).format(new Date(2023, 0, i + 1)));
-  const dateNames = [...Array(7)].map((_, i) => new Intl.DateTimeFormat(
-    locale,
-    { weekday: "long" }
-  ).format(new Date(2023, 0, i + 1)));
-  const shortMonthNames = [...Array(12)].map((_, i) => new Intl.DateTimeFormat(
-    locale,
-    { month: "short" }
-  ).format(new Date(2023, i, 1)));
-  const monthNames = [...Array(12)].map((_, i) => new Intl.DateTimeFormat(
-    locale,
-    { month: "long" }
-  ).format(new Date(2023, i, 1)));
-  const replacements = {
-    "DD": () => String(day).padStart(2, "0"),
-    "D": () => String(day),
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    "dd": () => dateNames[dayOfWeek],
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    "d": () => shortDateNames[dayOfWeek],
-    "MM": () => String(month + 1).padStart(2, "0"),
-    "M": () => String(month + 1),
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    "MMMM": () => monthNames[month],
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    "MMM": () => shortMonthNames[month],
-    "YYYY": () => String(year),
-    "YY": () => String(year).slice(-2),
-    "hh": () => String(hours % 12 !== 0 ? hours % 12 : 12).padStart(2, "0"),
-    "h": () => String(hours % 12 !== 0 ? hours % 12 : 12),
-    "HH": () => String(hours).padStart(2, "0"),
-    "H": () => String(hours),
-    "mm": () => String(minutes).padStart(2, "0"),
-    "m": () => String(minutes),
-    "ss": () => String(seconds).padStart(2, "0"),
-    "s": () => String(seconds),
-    "ms": () => String(date.getMilliseconds()).padStart(3, "0"),
-    "A": () => isPM ? "PM" : "AM",
-    "a": () => isPM ? "pm" : "am",
-    "th": () => {
-      if (locale.startsWith("fr") && day === 1) return "er";
-      if (locale.startsWith("en")) {
-        const mod10 = day % 10;
-        const mod100 = day % 100;
-        if (mod10 === 1 && mod100 !== 11) return "st";
-        if (mod10 === 2 && mod100 !== 12) return "nd";
-        if (mod10 === 3 && mod100 !== 13) return "rd";
-        return "th";
-      }
-      return "";
+/**
+ * Formats a `Date` object into a string according to a custom template and locale.
+ *
+ * Supported tokens (placeholders must be wrapped in `{{...}}`):
+ *
+ * **Day**
+ * - `D` : Day of month (1–31)
+ * - `DD` : Day of month, padded (01–31)
+ * - `d` : Short weekday name (Mon, Tue, ...)
+ * - `dd` : Full weekday name (Monday, Tuesday, ...)
+ *
+ * **Month**
+ * - `M` : Month number (1–12)
+ * - `MM` : Month number, padded (01–12)
+ * - `MMM` : Short month name (Jan, Feb, ...)
+ * - `MMMM` : Full month name (January, February, ...)
+ *
+ * **Year**
+ * - `YY` : Two-digit year
+ * - `YYYY` : Four-digit year
+ *
+ * **Hours**
+ * - `H` : 24h format
+ * - `HH` : 24h format, padded
+ * - `h` : 12h format
+ * - `hh` : 12h format, padded
+ *
+ * **Minutes & Seconds**
+ * - `m` / `mm` : Minutes
+ * - `s` / `ss` : Seconds
+ *
+ * **Miliseconds**
+ * - `ms` : Miliseconds
+ *
+ * **AM/PM**
+ * - `A` : AM/PM
+ * - `a` : am/pm
+ *
+ * **Ordinal suffix**
+ * - `th` : Day ordinal suffix (`st`, `nd`, `rd`, `th` for English; `er` for French 1st)
+ *
+ * @param date - The `Date` object to format.
+ * @param format - The template string containing tokens.
+ * @param locale - Optional locale code (default: `'en'`).
+ * @returns Formatted date string.
+ *
+ * @example
+ * formatDate(new Date(2026, 0, 1, 15, 5), '{{YYYY}}-{{MM}}-{{DD}} {{hh}}:{{mm}} {{A}}')
+ * // => "2026-01-01 03:05 PM"
+ */
+export function formatDate(date, format, locale = 'en') {
+    if (Intl
+        .DateTimeFormat
+        .supportedLocalesOf(locale).length === 0) {
+        locale = 'en';
     }
-  };
-  const regexp = /{{(DD|D|dd|d|MM|M|MMMM|MMM|YYYY|YY|HH|H|hh|h|mm|m|ss|s|A|a|th|ms)}}/g;
-  return format.replace(regexp, (match, token) => replacements[token]?.() ?? match);
+    const day = date.getDate();
+    const dayOfWeek = date.getDay();
+    const month = date.getMonth();
+    const year = date.getFullYear();
+    const hours = date.getHours();
+    const minutes = date.getMinutes();
+    const seconds = date.getSeconds();
+    const isPM = hours >= 12;
+    const shortDateNames = [...Array(7)].map((_, i) => new Intl.DateTimeFormat(locale, { weekday: 'short' }).format(new Date(2023, 0, i + 1)));
+    const dateNames = [...Array(7)].map((_, i) => new Intl.DateTimeFormat(locale, { weekday: 'long' }).format(new Date(2023, 0, i + 1)));
+    const shortMonthNames = [...Array(12)].map((_, i) => new Intl.DateTimeFormat(locale, { month: 'short' }).format(new Date(2023, i, 1)));
+    const monthNames = [...Array(12)].map((_, i) => new Intl.DateTimeFormat(locale, { month: 'long' }).format(new Date(2023, i, 1)));
+    const replacements = {
+        'DD': () => String(day).padStart(2, '0'),
+        'D': () => String(day),
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'dd': () => dateNames[dayOfWeek],
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'd': () => shortDateNames[dayOfWeek],
+        'MM': () => String(month + 1).padStart(2, '0'),
+        'M': () => String(month + 1),
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'MMMM': () => monthNames[month],
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        'MMM': () => shortMonthNames[month],
+        'YYYY': () => String(year),
+        'YY': () => String(year).slice(-2),
+        'hh': () => String(hours % 12 !== 0 ? hours % 12 : 12).padStart(2, '0'),
+        'h': () => String(hours % 12 !== 0 ? hours % 12 : 12),
+        'HH': () => String(hours).padStart(2, '0'),
+        'H': () => String(hours),
+        'mm': () => String(minutes).padStart(2, '0'),
+        'm': () => String(minutes),
+        'ss': () => String(seconds).padStart(2, '0'),
+        's': () => String(seconds),
+        'ms': () => String(date.getMilliseconds()).padStart(3, '0'),
+        'A': () => (isPM ? 'PM' : 'AM'),
+        'a': () => (isPM ? 'pm' : 'am'),
+        'th': () => {
+            if (locale.startsWith('fr') && day === 1)
+                return 'er';
+            if (locale.startsWith('en')) {
+                const mod10 = day % 10;
+                const mod100 = day % 100;
+                if (mod10 === 1 && mod100 !== 11)
+                    return 'st';
+                if (mod10 === 2 && mod100 !== 12)
+                    return 'nd';
+                if (mod10 === 3 && mod100 !== 13)
+                    return 'rd';
+                return 'th';
+            }
+            return '';
+        }
+    };
+    const regexp = /{{(DD|D|dd|d|MM|M|MMMM|MMM|YYYY|YY|HH|H|hh|h|mm|m|ss|s|A|a|th|ms)}}/g;
+    return format.replace(regexp, (match, token) => replacements[token]?.() ?? match);
 }
-export {
-  formatDate
-};
+// [WIP] this was removed since JavaScript's Date object don't hold timezone data
+// those templates would only reflect the curent client's timezone, no matter what the input Date obj was
+// 'ZZ': () => {
+//   const timezoneOffset = date.getTimezoneOffset()
+//   const offsetHours = Math.floor(Math.abs(timezoneOffset) / 60)
+//   const offsetMinutes = Math.abs(timezoneOffset) % 60
+//   const sign = timezoneOffset > 0 ? '-' : '+'
+//   return `${sign}${String(offsetHours).padStart(2, '0')}:${String(offsetMinutes).padStart(2, '0')}`
+// },
+// 'Z': () => {
+//   const timezoneOffset = date.getTimezoneOffset()
+//   if (timezoneOffset === 0) return 'Z'
+//   const offsetHours = Math.floor(Math.abs(timezoneOffset) / 60)
+//   const offsetMinutes = Math.abs(timezoneOffset) % 60
+//   const sign = timezoneOffset > 0 ? '-' : '+'
+//   return `${sign}${String(offsetHours).padStart(2, '0')}:${String(offsetMinutes).padStart(2, '0')}`
+// },
+// 'z': () => {
+//   return Intl.DateTimeFormat(locale, { timeZoneName: 'short' })
+//     .formatToParts(date)
+//     .find(part => part.type === 'timeZoneName')?.value || ''
+// },
+// 'zz': () => {
+//   return Intl.DateTimeFormat(locale, { timeZoneName: 'long' })
+//     .formatToParts(date)
+//     .find(part => part.type === 'timeZoneName')?.value || ''
+// },
+// 'tz': () => Intl.DateTimeFormat().resolvedOptions().timeZone || ''

package/agnostic/time/duration/index.js

@@ -1,142 +1,108 @@
-// src/agnostic/time/duration/index.ts
-var Duration = class {
-  value;
-  type;
-  /**
-   * Creates a new Duration instance.
-   *
-   * @param value - The numeric value of the duration.
-   * @param type - The unit of the duration, either long or short form.
-   */
-  constructor(value, type) {
-    this.toMilliseconds = this.toMilliseconds.bind(this);
-    this.toSeconds = this.toSeconds.bind(this);
-    this.toMinutes = this.toMinutes.bind(this);
-    this.toHours = this.toHours.bind(this);
-    this.toDays = this.toDays.bind(this);
-    this.toWeeks = this.toWeeks.bind(this);
-    this.toMonths = this.toMonths.bind(this);
-    this.toYear = this.toYear.bind(this);
-    this.value = value;
-    if (type === "ms" || type === "milliseconds") {
-      this.type = "milliseconds";
-    } else if (type === "s" || type === "sec" || type === "seconds") {
-      this.type = "seconds";
-    } else if (type === "m" || type === "min" || type === "minutes") {
-      this.type = "minutes";
-    } else if (type === "h" || type === "hours") {
-      this.type = "hours";
-    } else if (type === "d" || type === "days") {
-      this.type = "days";
-    } else if (type === "w" || type === "weeks") {
-      this.type = "weeks";
-    } else if (type === "mo" || type === "mth" || type === "months") {
-      this.type = "months";
-    } else if (type === "y" || type === "years") {
-      this.type = "years";
-    } else {
-      this.type = "milliseconds";
+/**
+ * Represents a duration in a specific unit and allows conversion to other units.
+ */
+export class Duration {
+    value;
+    type;
+    /**
+     * Creates a new Duration instance.
+     *
+     * @param value - The numeric value of the duration.
+     * @param type - The unit of the duration, either long or short form.
+     */
+    constructor(value, type) {
+        this.toMilliseconds = this.toMilliseconds.bind(this);
+        this.toSeconds = this.toSeconds.bind(this);
+        this.toMinutes = this.toMinutes.bind(this);
+        this.toHours = this.toHours.bind(this);
+        this.toDays = this.toDays.bind(this);
+        this.toWeeks = this.toWeeks.bind(this);
+        this.toMonths = this.toMonths.bind(this);
+        this.toYear = this.toYear.bind(this);
+        this.value = value;
+        if (type === 'ms' || type === 'milliseconds') {
+            this.type = 'milliseconds';
+        }
+        else if (type === 's' || type === 'sec' || type === 'seconds') {
+            this.type = 'seconds';
+        }
+        else if (type === 'm' || type === 'min' || type === 'minutes') {
+            this.type = 'minutes';
+        }
+        else if (type === 'h' || type === 'hours') {
+            this.type = 'hours';
+        }
+        else if (type === 'd' || type === 'days') {
+            this.type = 'days';
+        }
+        else if (type === 'w' || type === 'weeks') {
+            this.type = 'weeks';
+        }
+        else if (type === 'mo' || type === 'mth' || type === 'months') {
+            this.type = 'months';
+        }
+        else if (type === 'y' || type === 'years') {
+            this.type = 'years';
+        }
+        else {
+            this.type = 'milliseconds';
+        } // defaults to milliseconds
     }
-  }
-  // [WIP] why only toMs and no other shorthands ?
-  toMilliseconds() {
-    if (this.type === "milliseconds") return this.value;
-    if (this.type === "seconds") return this.value * 1e3;
-    if (this.type === "minutes") return this.value * 1e3 * 60;
-    if (this.type === "hours") return this.value * 1e3 * 60 * 60;
-    if (this.type === "days") return this.value * 1e3 * 60 * 60 * 24;
-    if (this.type === "weeks") return this.value * 1e3 * 60 * 60 * 24 * 7;
-    if (this.type === "months") return this.value * 1e3 * 60 * 60 * 24 * 30;
-    if (this.type === "years") return this.value * 1e3 * 60 * 60 * 24 * 365;
-    return this.value;
-  }
-  toMs = this.toMilliseconds.bind(this);
-  toSeconds() {
-    return this.toMs() / 1e3;
-  }
-  toS = this.toSeconds.bind(this);
-  toSec = this.toSeconds.bind(this);
-  toMinutes() {
-    return this.toMs() / (1e3 * 60);
-  }
-  toM = this.toMinutes.bind(this);
-  toMin = this.toMinutes.bind(this);
-  toHours() {
-    return this.toMs() / (1e3 * 60 * 60);
-  }
-  toH = this.toHours.bind(this);
-  toDays() {
-    return this.toMs() / (1e3 * 60 * 60 * 24);
-  }
-  toD = this.toDays.bind(this);
-  toWeeks() {
-    return this.toMs() / (1e3 * 60 * 60 * 24 * 7);
-  }
-  toW = this.toWeeks.bind(this);
-  toMonths() {
-    return this.toMs() / (1e3 * 60 * 60 * 24 * 30);
-  }
-  toMth = this.toMonths.bind(this);
-  toYear() {
-    return this.toMs() / (1e3 * 60 * 60 * 24 * 365);
-  }
-  toY = this.toYear.bind(this);
-  toYr = this.toYear.bind(this);
-};
-function milliseconds(value) {
-  return new Duration(value, "milliseconds");
-}
-var ms = milliseconds;
-function seconds(value) {
-  return new Duration(value, "seconds");
-}
-var s = seconds;
-var sec = seconds;
-function minutes(value) {
-  return new Duration(value, "minutes");
-}
-var m = minutes;
-var min = minutes;
-function hours(value) {
-  return new Duration(value, "hours");
-}
-var h = hours;
-function days(value) {
-  return new Duration(value, "days");
-}
-var d = days;
-function weeks(value) {
-  return new Duration(value, "weeks");
-}
-var w = weeks;
-function months(value) {
-  return new Duration(value, "months");
-}
-var mth = months;
-function years(value) {
-  return new Duration(value, "years");
+    // [WIP] why only toMs and no other shorthands ?
+    toMilliseconds() {
+        if (this.type === 'milliseconds')
+            return this.value;
+        if (this.type === 'seconds')
+            return this.value * 1000;
+        if (this.type === 'minutes')
+            return this.value * 1000 * 60;
+        if (this.type === 'hours')
+            return this.value * 1000 * 60 * 60;
+        if (this.type === 'days')
+            return this.value * 1000 * 60 * 60 * 24;
+        if (this.type === 'weeks')
+            return this.value * 1000 * 60 * 60 * 24 * 7;
+        if (this.type === 'months')
+            return this.value * 1000 * 60 * 60 * 24 * 30;
+        if (this.type === 'years')
+            return this.value * 1000 * 60 * 60 * 24 * 365;
+        return this.value; // defaults to milliseconds
+    }
+    toMs = this.toMilliseconds.bind(this);
+    toSeconds() { return this.toMs() / 1000; }
+    toS = this.toSeconds.bind(this);
+    toSec = this.toSeconds.bind(this);
+    toMinutes() { return this.toMs() / (1000 * 60); }
+    toM = this.toMinutes.bind(this);
+    toMin = this.toMinutes.bind(this);
+    toHours() { return this.toMs() / (1000 * 60 * 60); }
+    toH = this.toHours.bind(this);
+    toDays() { return this.toMs() / (1000 * 60 * 60 * 24); }
+    toD = this.toDays.bind(this);
+    toWeeks() { return this.toMs() / (1000 * 60 * 60 * 24 * 7); }
+    toW = this.toWeeks.bind(this);
+    toMonths() { return this.toMs() / (1000 * 60 * 60 * 24 * 30); }
+    toMth = this.toMonths.bind(this);
+    toYear() { return this.toMs() / (1000 * 60 * 60 * 24 * 365); }
+    toY = this.toYear.bind(this);
+    toYr = this.toYear.bind(this);
 }
-var y = years;
-var yr = years;
-export {
-  Duration,
-  d,
-  days,
-  h,
-  hours,
-  m,
-  milliseconds,
-  min,
-  minutes,
-  months,
-  ms,
-  mth,
-  s,
-  sec,
-  seconds,
-  w,
-  weeks,
-  y,
-  years,
-  yr
-};
+export function milliseconds(value) { return new Duration(value, 'milliseconds'); }
+export const ms = milliseconds;
+export function seconds(value) { return new Duration(value, 'seconds'); }
+export const s = seconds;
+export const sec = seconds;
+export function minutes(value) { return new Duration(value, 'minutes'); }
+export const m = minutes;
+export const min = minutes;
+export function hours(value) { return new Duration(value, 'hours'); }
+export const h = hours;
+export function days(value) { return new Duration(value, 'days'); }
+export const d = days;
+export function weeks(value) { return new Duration(value, 'weeks'); }
+export const w = weeks;
+export function months(value) { return new Duration(value, 'months'); }
+export const mth = months;
+export function years(value) { return new Duration(value, 'years'); }
+export const y = years;
+export const yr = years;

package/agnostic/time/timeout/index.js

@@ -1,17 +1,25 @@
-// src/agnostic/time/timeout/index.ts
-async function timeout(timeoutMs, callback) {
-  let hasRejected = false;
-  return await new Promise(async (resolve, reject) => {
-    const rejectTimeout = setTimeout(() => {
-      reject(false);
-      hasRejected = true;
-    }, timeoutMs);
-    const callbackResult = await callback();
-    if (hasRejected) return;
-    clearTimeout(rejectTimeout);
-    return resolve(callbackResult);
-  });
+/**
+ * Executes a callback and rejects if it does not complete within a specified timeout.
+ *
+ * @template T - The type of the callback's return value.
+ * @param timeoutMs - Maximum time in milliseconds to wait for the callback to complete.
+ * @param callback - The function to execute. Can be synchronous or return a promise.
+ * @returns A promise that resolves with the callback result if completed in time, or rejects with `false` if timed out.
+ */
+export async function timeout(timeoutMs, callback) {
+    let hasRejected = false;
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises, no-async-promise-executor
+    return await new Promise(async (resolve, reject) => {
+        const rejectTimeout = setTimeout(() => {
+            // eslint-disable-next-line prefer-promise-reject-errors
+            reject(false);
+            hasRejected = true;
+        }, timeoutMs);
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        const callbackResult = await callback();
+        if (hasRejected)
+            return;
+        clearTimeout(rejectTimeout);
+        return resolve(callbackResult);
+    });
 }
-export {
-  timeout
-};