@design-edito/tools 0.4.5 → 0.4.11

package/agnostic/html/string-to-nodes/index.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { stringToNodes } from './index.js';
+import { JSDOM } from 'jsdom';
+import * as Window from '../../misc/crossenv/window/index.js';
+describe('stringToNodes', () => {
+    beforeEach(() => Window.set(new JSDOM().window));
+    afterEach(() => Window.unset());
+    it('converts simple HTML string to nodes', () => {
+        const { Node } = Window.get();
+        const result = stringToNodes('<div>test</div>');
+        expect(result).toHaveLength(1);
+        expect(result[0]?.nodeType).toBe(Node.ELEMENT_NODE);
+        expect(result[0].tagName).toBe('DIV');
+    });
+    it('converts multiple elements', () => {
+        const result = stringToNodes('<div>1</div><span>2</span>');
+        expect(result).toHaveLength(2);
+        expect(result[0].tagName).toBe('DIV');
+        expect(result[1].tagName).toBe('SPAN');
+    });
+    it('includes text nodes', () => {
+        const { Node } = Window.get();
+        const result = stringToNodes('plain text');
+        expect(result).toHaveLength(1);
+        expect(result[0]?.nodeType).toBe(Node.TEXT_NODE);
+        expect(result[0]?.textContent).toBe('plain text');
+    });
+    it('includes both element and text nodes', () => {
+        const { Node } = Window.get();
+        const result = stringToNodes('<div>test</div>more text');
+        expect(result.length).toBeGreaterThan(1);
+        const hasElement = result.some(node => node.nodeType === Node.ELEMENT_NODE);
+        const hasText = result.some(node => node.nodeType === Node.TEXT_NODE);
+        expect(hasElement).toBe(true);
+        expect(hasText).toBe(true);
+    });
+    it('filters out comment nodes', () => {
+        const { Node } = Window.get();
+        const result = stringToNodes('<!-- comment --><div>test</div>');
+        const commentNodes = result.filter(node => node.nodeType === Node.COMMENT_NODE);
+        expect(commentNodes).toHaveLength(0);
+    });
+    it('returns empty array for empty string', () => {
+        const result = stringToNodes('');
+        expect(result).toHaveLength(0);
+    });
+    it('handles nested elements', () => {
+        const result = stringToNodes('<div><span>nested</span></div>');
+        expect(result).toHaveLength(1);
+        const div = result[0];
+        expect(div.children.length).toBe(1);
+        expect(div.children[0]?.tagName).toBe('SPAN');
+    });
+});

package/agnostic/index.d.ts

@@ -1,16 +1,16 @@
 export * as booleans from './booleans/index.js'
-export * as arrays from './arrays/index.js'
 export * as colors from './colors/index.js'
 export * as css from './css/index.js'
-export * as html from './html/index.js'
 export * as errors from './errors/index.js'
+export * as html from './html/index.js'
 export * as numbers from './numbers/index.js'
 export * as misc from './misc/index.js'
+export * as arrays from './arrays/index.js'
+export * as objects from './objects/index.js'
 export * as optim from './optim/index.js'
+export * as random from './random/index.js'
 export * as regexps from './regexps/index.js'
 export * as sanitization from './sanitization/index.js'
 export * as strings from './strings/index.js'
 export * as time from './time/index.js'
 export * as typescript from './typescript/index.js'
-export * as objects from './objects/index.js'
-export * as random from './random/index.js'

package/agnostic/index.js

@@ -1,16 +1,16 @@
 export * as booleans from './booleans/index.js'
-export * as arrays from './arrays/index.js'
 export * as colors from './colors/index.js'
 export * as css from './css/index.js'
-export * as html from './html/index.js'
 export * as errors from './errors/index.js'
+export * as html from './html/index.js'
 export * as numbers from './numbers/index.js'
 export * as misc from './misc/index.js'
+export * as arrays from './arrays/index.js'
+export * as objects from './objects/index.js'
 export * as optim from './optim/index.js'
+export * as random from './random/index.js'
 export * as regexps from './regexps/index.js'
 export * as sanitization from './sanitization/index.js'
 export * as strings from './strings/index.js'
 export * as time from './time/index.js'
 export * as typescript from './typescript/index.js'
-export * as objects from './objects/index.js'
-export * as random from './random/index.js'

package/agnostic/misc/assert/index.js

@@ -1,72 +1,66 @@
-// src/agnostic/errors/unknown-to-string/index.ts
-function unknownToString(unk, encoding) {
-  if (unk instanceof Error) return unk.message;
-  if (unk instanceof Buffer) return unk.toString(encoding ?? "utf-8");
-  if (typeof unk === "string") return unk;
-  if (typeof unk === "object" && unk !== null) return JSON.stringify(unk);
-  return `${unk}`;
+import { unknownToString } from '../../errors/unknown-to-string/index.js';
+import * as Outcome from '../outcome/index.js';
+function makeSuccess(label) {
+    const formattedLabel = label.split('\n').join('\n  ');
+    console.info(`✅ SUCCESS:\n  ${formattedLabel}`);
 }
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
+function makeFailure(label) {
+    const formattedLabel = label.split('\n').join('\n  ');
+    throw new Error(`🚫 FAILURE:\n  ${formattedLabel}`);
 }
-function makeFailure(error) {
-  return { success: false, error };
-}
-
-// src/agnostic/misc/assert/index.ts
-function makeSuccess2(label) {
-  const formattedLabel = label.split("\n").join("\n  ");
-  console.info(`\u2705 SUCCESS:
-  ${formattedLabel}`);
-}
-function makeFailure2(label) {
-  const formattedLabel = label.split("\n").join("\n  ");
-  throw new Error(`\u{1F6AB} FAILURE:
-  ${formattedLabel}`);
-}
-async function assert(label, assertion) {
-  if (typeof assertion === "boolean") return assertion ? makeSuccess(label) : makeFailure(label);
-  else if (typeof assertion === "function") {
-    try {
-      const result = await assertion();
-      if (!result) return makeFailure(label);
-      else return makeSuccess(label);
-    } catch (err) {
-      const errStr = unknownToString(err);
-      return makeFailure(`${label} / ${errStr}`);
+/**
+ * @deprecated
+ */
+export async function assert(label, assertion) {
+    // Assertion is boolean ?
+    if (typeof assertion === 'boolean')
+        return assertion
+            ? Outcome.makeSuccess(label)
+            : Outcome.makeFailure(label);
+    // Assertion is function ?
+    else if (typeof assertion === 'function') {
+        try {
+            const result = await assertion();
+            if (!result)
+                return Outcome.makeFailure(label);
+            else
+                return Outcome.makeSuccess(label);
+        }
+        catch (err) {
+            const errStr = unknownToString(err);
+            return Outcome.makeFailure(`${label} / ${errStr}`);
+        }
+        // Then assertion is Array, Map or Record
     }
-  } else {
-    let assertions;
-    if (Array.isArray(assertion)) {
-      assertions = [...assertion].map((a, p) => [`${p}`, a]);
-    } else if (assertion instanceof Map) {
-      assertions = Array.from(assertion);
-    } else {
-      assertions = Object.entries(assertion);
+    else {
+        let assertions;
+        if (Array.isArray(assertion)) {
+            assertions = [...assertion].map((a, p) => [`${p}`, a]);
+        }
+        else if (assertion instanceof Map) {
+            assertions = Array.from(assertion);
+        }
+        else {
+            assertions = Object.entries(assertion);
+        }
+        const allAsserted = await Promise.all(assertions.map(async ([innerLabel, innerAssertion]) => {
+            const fullLabel = `${label} / ${innerLabel}`;
+            const asserted = assert(fullLabel, innerAssertion);
+            return await asserted;
+        }));
+        const allSuccess = allAsserted.every((asserted) => asserted.success);
+        if (allSuccess)
+            return Outcome.makeSuccess(allAsserted.map(e => e.payload).join('\n'));
+        const failures = allAsserted.filter((asserted) => !asserted.success);
+        const failuresStr = failures.map(failure => failure.error).join('\n  ');
+        return Outcome.makeFailure(failuresStr);
     }
-    const allAsserted = await Promise.all(assertions.map(async ([innerLabel, innerAssertion]) => {
-      const fullLabel = `${label} / ${innerLabel}`;
-      const asserted = assert(fullLabel, innerAssertion);
-      return await asserted;
-    }));
-    const allSuccess = allAsserted.every((asserted) => asserted.success);
-    if (allSuccess) return makeSuccess(allAsserted.map((e) => e.payload).join("\n"));
-    const failures = allAsserted.filter((asserted) => !asserted.success);
-    const failuresStr = failures.map((failure) => failure.error).join("\n  ");
-    return makeFailure(failuresStr);
-  }
 }
-async function assertVerbose(label, assertion) {
-  const asserted = await assert(label, assertion);
-  if (asserted?.success) {
-    makeSuccess2(asserted.payload);
-    return asserted;
-  }
-  return makeFailure2(asserted.error);
+export async function assertVerbose(label, assertion) {
+    const asserted = await assert(label, assertion);
+    if (asserted?.success) {
+        makeSuccess(asserted.payload);
+        return asserted;
+    }
+    return makeFailure(asserted.error);
 }
-export {
-  assert,
-  assertVerbose
-};

package/agnostic/misc/cast/index.js

@@ -1,66 +1,132 @@
-// src/agnostic/misc/is-nullish/index.ts
-var nullishValues = [null, void 0];
-
-// src/agnostic/booleans/is-falsy/index.ts
-var falsyValues = [...nullishValues, false, "", 0, -0, NaN];
-if (typeof BigInt === "function") falsyValues.push(BigInt(0));
-function isFalsy(val) {
-  return falsyValues.includes(val);
+import { isFalsy } from '../../booleans/is-falsy/index.js';
+/**
+ * Converts a value to a boolean.
+ *
+ * - Booleans are returned as-is.
+ * - Strings equal to `"true"` (case-insensitive, trimmed) are `true`, others `false`.
+ * - Other values are coerced using `!isFalsy`.
+ *
+ * @param {unknown} value - The value to convert.
+ * @returns {boolean} The boolean representation of the input.
+ */
+export function toBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        if (value.toLowerCase().trim() === 'true')
+            return true;
+        return false;
+    }
+    return !isFalsy(value);
 }
-
-// src/agnostic/misc/cast/index.ts
-function toBoolean(value) {
-  if (typeof value === "boolean") return value;
-  if (typeof value === "string") {
-    if (value.toLowerCase().trim() === "true") return true;
-    return false;
-  }
-  return !isFalsy(value);
+/**
+ * Converts a value to a number.
+ *
+ * - Numbers are returned as-is.
+ * - Strings are parsed as floats.
+ * - Other values return 0.
+ *
+ * @param {unknown} value - The value to convert.
+ * @returns {number} The numeric representation of the input.
+ */
+export function toNumber(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string')
+        return parseFloat(value);
+    return 0;
 }
-function toNumber(value) {
-  if (typeof value === "number") return value;
-  if (typeof value === "string") return parseFloat(value);
-  return 0;
+/**
+ * Converts a value to a string.
+ *
+ * - Strings are returned as-is.
+ * - Other values are converted using `String()`.
+ *
+ * @param {unknown} value - The value to convert.
+ * @returns {string} The string representation of the input.
+ */
+export function toString(value) {
+    if (typeof value === 'string')
+        return value;
+    return String(value);
 }
-function toString(value) {
-  if (typeof value === "string") return value;
-  return String(value);
+/**
+ * Converts any value to `null`.
+ *
+ * @param {unknown} _value - The input value (ignored).
+ * @returns {null} Always returns `null`.
+ */
+export function toNull(_value) {
+    return null;
 }
-function toNull(_value) {
-  return null;
+/**
+ * Converts a value to an array.
+ *
+ * - Arrays are returned as-is.
+ * - Objects are converted to an array of `[key, value]` pairs.
+ * - Other values are wrapped in a single-element array.
+ *
+ * @param {unknown} value - The value to convert.
+ * @returns {Array<unknown>} The array representation of the input.
+ */
+export function toArray(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === 'object' && value !== null)
+        return Object.entries(value);
+    return [value];
 }
-function toArray(value) {
-  if (Array.isArray(value)) return value;
-  if (typeof value === "object" && value !== null) return Object.entries(value);
-  return [value];
+// [WIP] not so sure about this one
+/**
+ * Converts a value to an array of numbers.
+ *
+ * - Uses `toArray` to ensure an array.
+ * - Each element is converted to a number using `toNumber`.
+ *
+ * @param {unknown} value - The value to convert.
+ * @returns {number[]} Array of numeric values.
+ */
+export function toNumberArr(value) {
+    const arrValue = toArray(value);
+    return arrValue.map(val => toNumber(val));
 }
-function toNumberArr(value) {
-  const arrValue = toArray(value);
-  return arrValue.map((val) => toNumber(val));
-}
-function toRecord(value) {
-  const record = {};
-  try {
-    Object.keys(value).forEach((key) => {
-      record[key] = value[key];
-    });
-  } catch (err) {
+/**
+ * Converts a value to a plain object (record).
+ *
+ * - Keys and values of objects are copied.
+ * - Non-object values return an empty object.
+ *
+ * @param {unknown} value - The value to convert.
+ * @returns {Record<string, unknown>} The object representation of the input.
+ */
+export function toRecord(value) {
+    const record = {};
+    try {
+        Object
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            .keys(value)
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            .forEach(key => { record[key] = value[key]; });
+    }
+    catch (err) {
+        return record;
+    }
     return record;
-  }
-  return record;
 }
-function toError(value) {
-  if (value instanceof Error) return value;
-  if (typeof value === "string") return new Error(value);
-  return new Error(toString(value));
+/**
+ * Converts a value to an `Error` object.
+ *
+ * - Returns the value if it is already an `Error`.
+ * - Strings are used as the error message.
+ * - Other values are converted to string and used as the error message.
+ *
+ * @param {unknown} value - The value to convert.
+ * @returns {Error} An `Error` instance representing the input.
+ */
+export function toError(value) {
+    if (value instanceof Error)
+        return value;
+    if (typeof value === 'string')
+        return new Error(value);
+    return new Error(toString(value));
 }
-export {
-  toArray,
-  toBoolean,
-  toError,
-  toNull,
-  toNumber,
-  toNumberArr,
-  toRecord,
-  toString
-};

package/agnostic/misc/cast/index.test.js

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest';
+import { toBoolean, toNumber, toString, toNull, toArray, toNumberArr, toRecord, toError } from './index.js';
+describe('toBoolean', () => {
+    it('returns boolean values as-is', () => {
+        expect(toBoolean(true)).toBe(true);
+        expect(toBoolean(false)).toBe(false);
+    });
+    it('returns true for string "true" (case-insensitive, trimmed)', () => {
+        expect(toBoolean('true')).toBe(true);
+        expect(toBoolean('TRUE')).toBe(true);
+        expect(toBoolean('  true  ')).toBe(true);
+    });
+    it('returns false for other strings', () => {
+        expect(toBoolean('false')).toBe(false);
+        expect(toBoolean('yes')).toBe(false);
+        expect(toBoolean('')).toBe(false);
+    });
+    it('returns true for truthy values', () => {
+        expect(toBoolean(1)).toBe(true);
+        expect(toBoolean({})).toBe(true);
+        expect(toBoolean([])).toBe(true);
+    });
+    it('returns false for falsy values', () => {
+        expect(toBoolean(0)).toBe(false);
+        expect(toBoolean(null)).toBe(false);
+        expect(toBoolean(undefined)).toBe(false);
+    });
+});
+describe('toNumber', () => {
+    it('returns numbers as-is', () => {
+        expect(toNumber(42)).toBe(42);
+        expect(toNumber(0)).toBe(0);
+        expect(toNumber(-123)).toBe(-123);
+    });
+    it('parses string numbers', () => {
+        expect(toNumber('42')).toBe(42);
+        expect(toNumber('3.14')).toBe(3.14);
+        expect(toNumber('-123')).toBe(-123);
+    });
+    it('returns 0 for non-numeric strings', () => {
+        expect(toNumber('abc')).toBeNaN();
+        expect(toNumber('')).toBeNaN();
+    });
+    it('returns 0 for non-string, non-number values', () => {
+        expect(toNumber(null)).toBe(0);
+        expect(toNumber(undefined)).toBe(0);
+        expect(toNumber({})).toBe(0);
+    });
+});
+describe('toString', () => {
+    it('returns strings as-is', () => {
+        expect(toString('test')).toBe('test');
+        expect(toString('')).toBe('');
+    });
+    it('converts numbers to strings', () => {
+        expect(toString(42)).toBe('42');
+        expect(toString(0)).toBe('0');
+    });
+    it('converts other values using String()', () => {
+        expect(toString(null)).toBe('null');
+        expect(toString(undefined)).toBe('undefined');
+        expect(toString(true)).toBe('true');
+    });
+});
+describe('toNull', () => {
+    it('always returns null', () => {
+        expect(toNull(42)).toBe(null);
+        expect(toNull('test')).toBe(null);
+        expect(toNull(null)).toBe(null);
+        expect(toNull(undefined)).toBe(null);
+    });
+});
+describe('toArray', () => {
+    it('returns arrays as-is', () => {
+        const arr = [1, 2, 3];
+        expect(toArray(arr)).toBe(arr);
+    });
+    it('converts objects to key-value pairs', () => {
+        const result = toArray({ a: 1, b: 2 });
+        expect(result).toHaveLength(2);
+        expect(result[0]).toEqual(['a', 1]);
+        expect(result[1]).toEqual(['b', 2]);
+    });
+    it('wraps other values in array', () => {
+        expect(toArray(42)).toEqual([42]);
+        expect(toArray('test')).toEqual(['test']);
+        expect(toArray(null)).toEqual([null]);
+    });
+});
+describe('toNumberArr', () => {
+    it('converts array to number array', () => {
+        expect(toNumberArr([1, 2, 3])).toEqual([1, 2, 3]);
+        expect(toNumberArr(['1', '2', '3'])).toEqual([1, 2, 3]);
+    });
+    it('converts object to number array', () => {
+        const result = toNumberArr({ a: '1', b: '2' });
+        expect(result).toHaveLength(2);
+        expect(result[0]).toBe(0);
+        expect(result[1]).toBe(0);
+    });
+    it('wraps single value and converts to number', () => {
+        expect(toNumberArr(42)).toEqual([42]);
+        expect(toNumberArr('123')).toEqual([123]);
+    });
+});
+describe('toRecord', () => {
+    it('copies object keys and values', () => {
+        const obj = { a: 1, b: 'test' };
+        const result = toRecord(obj);
+        expect(result).toEqual({ a: 1, b: 'test' });
+        expect(result).not.toBe(obj);
+    });
+    it('returns empty object for non-objects', () => {
+        expect(toRecord(42)).toEqual({});
+        expect(toRecord('test')).toEqual({ '0': 't', '1': 'e', '2': 's', '3': 't' });
+        expect(toRecord(null)).toEqual({});
+    });
+});
+describe('toError', () => {
+    it('returns Error instances as-is', () => {
+        const error = new Error('test');
+        expect(toError(error)).toBe(error);
+    });
+    it('creates Error from string', () => {
+        const error = toError('test message');
+        expect(error).toBeInstanceOf(Error);
+        expect(error.message).toBe('test message');
+    });
+    it('creates Error from other values', () => {
+        const error = toError(42);
+        expect(error).toBeInstanceOf(Error);
+        expect(error.message).toBe('42');
+    });
+});

package/agnostic/misc/connection/index.js

@@ -1,44 +1,63 @@
-// src/agnostic/misc/crossenv/window/index.ts
-function exists() {
-  return typeof globalThis !== "undefined" && "window" in globalThis;
-}
-var _window = exists() ? globalThis.window ?? null : null;
-function get() {
-  if (_window !== null) return _window;
-  const message = "window is undefined. Please call Window.setWindow(windowObj) before using Window.get.";
-  throw new Error(message);
-}
-
-// src/agnostic/misc/connection/index.ts
+import * as Window from '../crossenv/window/index.js';
 function isType(unk) {
-  return unk === "bluetooth" || unk === "cellular" || unk === "ethernet" || unk === "none" || unk === "wifi" || unk === "wimax" || unk === "other" || unk === "unknown";
+    return unk === 'bluetooth'
+        || unk === 'cellular'
+        || unk === 'ethernet'
+        || unk === 'none'
+        || unk === 'wifi'
+        || unk === 'wimax'
+        || unk === 'other'
+        || unk === 'unknown';
 }
 function isEffectiveType(unk) {
-  return unk === "slow-2g" || unk === "2g" || unk === "3g" || unk === "4g";
+    return unk === 'slow-2g'
+        || unk === '2g'
+        || unk === '3g'
+        || unk === '4g';
 }
 function isConnection(unk) {
-  if (typeof unk !== "object") return false;
-  if (unk === null) return false;
-  if (!("downlink" in unk)) return false;
-  if (typeof unk.downlink !== "number") return false;
-  if (!("type" in unk)) return false;
-  if (!isType(unk.type)) return false;
-  if (!("effectiveType" in unk)) return false;
-  if (!isEffectiveType(unk.effectiveType)) return false;
-  return true;
+    if (typeof unk !== 'object')
+        return false;
+    if (unk === null)
+        return false;
+    if (!('downlink' in unk))
+        return false;
+    if (typeof unk.downlink !== 'number')
+        return false;
+    if (!('type' in unk))
+        return false;
+    if (!isType(unk.type))
+        return false;
+    if (!('effectiveType' in unk))
+        return false;
+    if (!isEffectiveType(unk.effectiveType))
+        return false;
+    return true;
 }
-function getConnection() {
-  const window = get();
-  const navigator = window.navigator;
-  if (typeof navigator !== "object" || navigator === null) return void 0;
-  const connection = navigator.connection ?? navigator.mozConnection ?? navigator.webkitConnection;
-  if (!isConnection(connection)) return void 0;
-  return connection;
+/**
+ * Retrieves the current network connection information from the environment.
+ *
+ * Uses the `navigator.connection` API or vendor-prefixed alternatives.
+ *
+ * @returns {MinimalConnection | undefined} A minimal connection object if available, otherwise `undefined`.
+ */
+export function getConnection() {
+    const window = Window.get();
+    const navigator = window.navigator;
+    if (typeof navigator !== 'object' || navigator === null)
+        return undefined;
+    const connection = navigator.connection
+        ?? navigator.mozConnection
+        ?? navigator.webkitConnection;
+    if (!isConnection(connection))
+        return undefined;
+    return connection;
 }
-function getCurrentDownlink() {
-  return getConnection()?.downlink;
+/**
+ * Retrieves the estimated downlink speed of the current network connection.
+ *
+ * @returns {number | undefined} Downlink speed in Mbps, or `undefined` if not available.
+ */
+export function getCurrentDownlink() {
+    return getConnection()?.downlink;
 }
-export {
-  getConnection,
-  getCurrentDownlink
-};