@design-edito/tools 0.4.4 → 0.4.6

package/agnostic/misc/cast/index.js

@@ -1,23 +1,132 @@
-import {
-  toArray,
-  toBoolean,
-  toError,
-  toNull,
-  toNumber,
-  toNumberArr,
-  toRecord,
-  toString
-} from "../../../chunks/chunk-YWSXCFYY.js";
-import "../../../chunks/chunk-QXAJXTXV.js";
-import "../../../chunks/chunk-HC6ZOHCS.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  toArray,
-  toBoolean,
-  toError,
-  toNull,
-  toNumber,
-  toNumberArr,
-  toRecord,
-  toString
-};
+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);
+}
+/**
+ * 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;
+}
+/**
+ * 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);
+}
+/**
+ * Converts any value to `null`.
+ *
+ * @param {unknown} _value - The input value (ignored).
+ * @returns {null} Always returns `null`.
+ */
+export 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];
+}
+// [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));
+}
+/**
+ * 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;
+}
+/**
+ * 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));
+}

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,38 +1,63 @@
-import {
-  get
-} from "../../../chunks/chunk-57YKZBJR.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// 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
-};

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

@@ -0,0 +1,143 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { getConnection, getCurrentDownlink } from './index.js';
+import * as Window from '../crossenv/window/index.js';
+import { JSDOM } from 'jsdom';
+describe('getConnection', () => {
+    beforeEach(() => Window.set(new JSDOM().window));
+    afterEach(() => Window.unset());
+    it('returns undefined when navigator is not available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        Object.defineProperty(window, 'navigator', {
+            value: null,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getConnection()).toBeUndefined();
+    });
+    it('returns undefined when navigator exists but has no connection', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const navigator = {};
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getConnection()).toBeUndefined();
+    });
+    it('returns connection when available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const connection = {
+            downlink: 10,
+            type: 'wifi',
+            effectiveType: '4g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'connection', {
+            value: connection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        const result = getConnection();
+        expect(result).toEqual({
+            downlink: 10,
+            type: 'wifi',
+            effectiveType: '4g'
+        });
+    });
+    it('uses mozConnection as fallback', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const mozConnection = {
+            downlink: 5,
+            type: 'cellular',
+            effectiveType: '3g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'mozConnection', {
+            value: mozConnection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        const result = getConnection();
+        expect(result?.type).toBe('cellular');
+    });
+    it('uses webkitConnection as fallback', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const webkitConnection = {
+            downlink: 7.5,
+            type: 'ethernet',
+            effectiveType: '4g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'webkitConnection', {
+            value: webkitConnection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        const result = getConnection();
+        expect(result?.type).toBe('ethernet');
+    });
+});
+describe('getCurrentDownlink', () => {
+    beforeEach(() => Window.set(new JSDOM().window));
+    afterEach(() => Window.unset());
+    it('returns downlink when connection is available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const connection = {
+            downlink: 10,
+            type: 'wifi',
+            effectiveType: '4g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'connection', {
+            value: connection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getCurrentDownlink()).toBe(10);
+    });
+    it('returns undefined when connection is not available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const navigator = {};
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getCurrentDownlink()).toBeUndefined();
+    });
+});

package/agnostic/misc/crawler/index.js

@@ -1,45 +1,69 @@
-import {
-  wait
-} from "../../../chunks/chunk-I6ZP5T5V.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/agnostic/misc/crawler/index.ts
-function create(options) {
-  let ops = 0;
-  const waitlist = [];
-  const push = (...urls) => waitlist.push(...urls);
-  const flush = () => {
-    waitlist.length = 0;
-  };
-  const processed = /* @__PURE__ */ new Set();
-  const crawl = async (startUrl) => {
-    push(startUrl);
-    while (waitlist.length > 0 && ops < options.limit) {
-      ops++;
-      const currentUrl = waitlist[0];
-      if (!processed.has(currentUrl) || options.allowDuplicates === true) {
-        const content = await options.fetcher(currentUrl);
-        await options.processor(currentUrl, content, {
-          push,
-          flush,
-          processed: new Set(processed),
-          waitlist: [...waitlist]
-        });
-      }
-      waitlist.shift();
-      processed.add(currentUrl);
-      const delayMs = typeof options.delayMs === "function" ? options.delayMs() : typeof options.delayMs === "number" ? options.delayMs : 0;
-      if (delayMs !== 0) await wait(delayMs);
-    }
-  };
-  return {
-    crawl,
-    push,
-    flush,
-    processed,
-    waitlist
-  };
+import { wait } from '../../time/wait/index.js';
+/**
+ * Creates a sequential crawler with optional delay.
+ *
+ * @template T - The type of content returned by the fetcher.
+ * @param {Options<T>} options - Crawler configuration options.
+ * @param {number} options.limit - Maximum number of URLs to process.
+ * @param {number | (() => number)} [options.delayMs] - Optional delay between processing URLs, in milliseconds, or a function returning the delay.
+ * @param {boolean} [options.allowDuplicates] - Optional, allows fetching and processing a URL that has already been seen.
+ * @param {Fetcher<T>} options.fetcher - Function that fetches content for each URL.
+ * @param {Processor<T>} options.processor - Function that processes fetched content.
+ * @returns {Crawler} An object with methods to start crawling, enqueue URLs, flush the waitlist, and access crawler state.
+ *
+ * @example
+ * ```typescript
+ * const crawler = create({
+ *   limit: 100,
+ *   delayMs: 1000,
+ *   fetcher: async (url) => fetch(url).then(r => r.text()),
+ *   processor: (url, content, { push, processed, waitlist }) => {
+ *     console.log(`Processed ${url}`);
+ *     console.log(`Remaining: ${waitlist.length}, Done: ${processed.size}`);
+ *     // Optionally push more URLs
+ *   }
+ * });
+ *
+ * await crawler.crawl('https://example.com');
+ * console.log('Total processed:', crawler.processed.size);
+ * ```
+ */
+export function create(options) {
+    let ops = 0;
+    const waitlist = [];
+    const push = (...urls) => waitlist.push(...urls);
+    const flush = () => { waitlist.length = 0; };
+    const processed = new Set();
+    const crawl = async (startUrl) => {
+        push(startUrl);
+        while (waitlist.length > 0 && ops < options.limit) {
+            ops++;
+            const currentUrl = waitlist[0];
+            if (!processed.has(currentUrl) || options.allowDuplicates === true) {
+                const content = await options.fetcher(currentUrl);
+                await options.processor(currentUrl, content, {
+                    push,
+                    flush,
+                    processed: new Set(processed),
+                    waitlist: [...waitlist]
+                });
+            }
+            waitlist.shift();
+            processed.add(currentUrl);
+            const delayMs = typeof options.delayMs === 'function'
+                ? options.delayMs()
+                : typeof options.delayMs === 'number'
+                    ? options.delayMs
+                    : 0;
+            if (delayMs !== 0)
+                await wait(delayMs);
+        }
+    };
+    return {
+        crawl,
+        push,
+        flush,
+        processed,
+        waitlist
+    };
 }
-export {
-  create
-};