@design-edito/tools 0.2.37 → 0.2.40

package/agnostic/misc/cast/index.d.ts

@@ -1,10 +1,81 @@
-export declare namespace Cast {
-    function toBoolean(value: unknown): boolean;
-    function toNumber(value: unknown): number;
-    function toString(value: unknown): string;
-    function toNull(_value: unknown): null;
-    function toArray(value: unknown): any[];
-    function toNumberArr(value: unknown): number[];
-    function toRecord(value: unknown): Record<string, unknown>;
-    function toError(value: unknown): Error;
-}
+/**
+ * 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 declare function toBoolean(value: unknown): boolean;
+/**
+ * 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 declare function toNumber(value: unknown): number;
+/**
+ * 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 declare function toString(value: unknown): string;
+/**
+ * Converts any value to `null`.
+ *
+ * @param {unknown} _value - The input value (ignored).
+ * @returns {null} Always returns `null`.
+ */
+export declare function toNull(_value: unknown): 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 declare function toArray(value: unknown): Array<unknown>;
+/**
+ * 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 declare function toNumberArr(value: unknown): number[];
+/**
+ * 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 declare function toRecord(value: unknown): Record<string, unknown>;
+/**
+ * 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 declare function toError(value: unknown): Error;

package/agnostic/misc/cast/index.js

@@ -1,9 +1,23 @@
 import {
-  Cast
-} from "../../../chunks/chunk-SNJJII7A.js";
+  toArray,
+  toBoolean,
+  toError,
+  toNull,
+  toNumber,
+  toNumberArr,
+  toRecord,
+  toString
+} from "../../../chunks/chunk-HOFEVF7T.js";
 import "../../../chunks/chunk-QXAJXTXV.js";
 import "../../../chunks/chunk-HC6ZOHCS.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
 export {
-  Cast
+  toArray,
+  toBoolean,
+  toError,
+  toNull,
+  toNumber,
+  toNumberArr,
+  toRecord,
+  toString
 };

package/agnostic/misc/connection/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Represents a minimal network connection object.
+ *
+ * @property {number} downlink - Estimated downlink speed in Mbps.
+ * @property {'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown'} type - Connection type.
+ * @property {'slow-2g' | '2g' | '3g' | '4g'} effectiveType - Effective connection type.
+ */
+export type MinimalConnection = {
+    downlink: number;
+    type: 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
+    effectiveType: 'slow-2g' | '2g' | '3g' | '4g';
+};
+/**
+ * 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 declare function getConnection(): MinimalConnection | undefined;
+/**
+ * Retrieves the estimated downlink speed of the current network connection.
+ *
+ * @returns {number | undefined} Downlink speed in Mbps, or `undefined` if not available.
+ */
+export declare function getCurrentDownlink(): number | undefined;

package/agnostic/misc/connection/index.js

@@ -0,0 +1,39 @@
+import {
+  get
+} from "../../../chunks/chunk-ROWPCMQY.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/misc/connection/index.ts
+function isType(unk) {
+  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";
+}
+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;
+  unk;
+  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;
+}
+function getCurrentDownlink() {
+  return getConnection()?.downlink;
+}
+export {
+  getConnection,
+  getCurrentDownlink
+};

package/agnostic/misc/crawler/index.d.ts

@@ -1,16 +1,63 @@
-export declare namespace Crawler {
-    function create<T extends any>(options: {
-        limit: number;
-        delayMs?: number | (() => number);
-        fetcher: (url: string) => Promise<T>;
-        processor: (url: string, content: T, hooks: {
-            push: (...urls: string[]) => void;
-            flush: () => void;
-        }) => any;
-        logger?: (ops: number, url: string, waitlist: string[], processed: Set<string>) => void;
-    }): {
-        crawl: (startUrl: string) => Promise<void>;
-        push: (url: string) => number;
-        flush: () => void;
-    };
-}
+/**
+ * Function that fetches content from a URL asynchronously.
+ *
+ * @template T - The type of content returned by the fetcher.
+ * @param {string} url - The URL to fetch.
+ * @returns {Promise<T>} A promise resolving to the fetched content.
+ */
+export type Fetcher<T> = (url: string) => Promise<T>;
+/**
+ * Function that processes fetched content for a given URL.
+ *
+ * @template T - The type of content provided by the fetcher.
+ * @param {string} url - The URL of the content being processed.
+ * @param {T} content - The content fetched from the URL.
+ * @param {{ push: (...urls: string[]) => void, flush: () => void }} hooks - Hooks for dynamically enqueuing or clearing URLs.
+ * @returns {any} The result of processing (ignored by the crawler).
+ */
+export type Processor<T> = (url: string, content: T, hooks: {
+    push: (...urls: string[]) => void;
+    flush: () => void;
+}) => any;
+/**
+ * Optional logging function called during crawling.
+ *
+ * @param {number} ops - Number of processed URLs so far.
+ * @param {string} url - The URL currently being processed.
+ * @param {string[]} waitlist - The current waitlist of URLs.
+ * @param {Set<string>} processed - Set of URLs already processed.
+ */
+export type Logger = (ops: number, url: string, waitlist: string[], processed: Set<string>) => void;
+/**
+ * Configuration options for the crawler.
+ *
+ * @template T - The type of content returned by the fetcher.
+ * @property {number} limit - Maximum number of URLs to process.
+ * @property {number | (() => number)} [delayMs] - Optional delay between processing URLs, in milliseconds, or a function returning the delay.
+ * @property {Fetcher<T>} fetcher - Function that fetches content for each URL.
+ * @property {Processor<T>} processor - Function that processes fetched content.
+ * @property {Logger} [logger] - Optional function for logging crawl progress.
+ */
+export type Options<T extends any> = {
+    limit: number;
+    delayMs?: number | (() => number);
+    fetcher: Fetcher<T>;
+    processor: Processor<T>;
+    logger?: Logger;
+};
+/**
+ * Creates a sequential crawler with optional logging and delay.
+ *
+ * @template T - The type of content returned by the fetcher.
+ * @param {Options<T>} options - Crawler configuration options.
+ * @returns {{
+*   crawl: (startUrl: string) => Promise<void>,
+*   push: (url: string) => void,
+*   flush: () => void
+* }} An object with methods to start crawling, enqueue URLs, and flush the waitlist.
+*/
+export declare function create<T extends any>(options: Options<T>): {
+    crawl: (startUrl: string) => Promise<void>;
+    push: (url: string) => number;
+    flush: () => void;
+};

package/agnostic/misc/crawler/index.js

@@ -1,8 +1,39 @@
 import {
-  Crawler
-} from "../../../chunks/chunk-YUP434IY.js";
-import "../../../chunks/chunk-4CIS3R7T.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+  wait
+} from "../../../chunks/chunk-4CIS3R7T.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/misc/crawler/index.ts
+function create(options) {
+  let ops = 0;
+  const waitlist = [];
+  const push = (url) => waitlist.push(url);
+  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 (options.logger !== void 0) options.logger(ops, currentUrl, waitlist, processed);
+      if (!processed.has(currentUrl)) {
+        const content = await options.fetcher(currentUrl);
+        await options.processor(currentUrl, content, { push, flush });
+      }
+      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
+  };
+}
 export {
-  Crawler
+  create
 };

package/agnostic/misc/crossenv/detect-runtime/index.d.ts

@@ -1,2 +1,12 @@
-import { Types } from '../types/index.js';
-export declare function detectRuntime(): Types.RuntimeName | null;
+import { RuntimeName } from '../types.js';
+/**
+ * Detects the current JavaScript runtime environment.
+ *
+ * Checks for Node.js, Browser, Deno, React Native, Electron,
+ * Cloudflare Workers, and AWS Lambda.
+ *
+ * @returns {RuntimeName | null}
+ * - The detected runtime as a `RuntimeName` enum value.
+ * - `null` if the runtime cannot be determined.
+ */
+export declare function detectRuntime(): RuntimeName | null;

package/agnostic/misc/crossenv/detect-runtime/index.js

@@ -1,8 +1,17 @@
-import {
-  detectRuntime
-} from "../../../../chunks/chunk-S2NMAH7K.js";
-import "../../../../chunks/chunk-LV2VMOWR.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
+import "../../../../chunks/chunk-XIIJYVJZ.js";
+import "../../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/misc/crossenv/detect-runtime/index.ts
+function detectRuntime() {
+  if (typeof process !== "undefined" && typeof process.versions !== "undefined" && typeof process.versions.node !== "undefined") return "Node.js" /* NODE */;
+  if (typeof window !== "undefined" && typeof window.document !== "undefined") return "Browser" /* BROWSER */;
+  if (typeof Deno !== "undefined") return "Deno" /* DENO */;
+  if (typeof process !== "undefined" && typeof navigator.userAgent === "string" && /ReactNative/.test(navigator.userAgent)) return "React Native" /* REACT_NATIVE */;
+  if (typeof process !== "undefined" && typeof process.versions !== "undefined" && typeof process.version.electron !== "undefined") return "Electron" /* ELECTRON */;
+  if (typeof self !== "undefined" && typeof self.addEventListener === "function" && typeof Headers !== "undefined") return "Cloudflare Workers" /* CLOUDFLARE */;
+  if (typeof AWS !== "undefined" && typeof AWS.Lambda !== "undefined") return "AWS Lambda" /* AWS_LAMBDA */;
+  return null;
+}
 export {
   detectRuntime
 };

package/agnostic/misc/crossenv/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Enum representing the possible runtime environments.
+ *
+ * - `NODE`         : Node.js
+ * - `BROWSER`      : Web browser
+ * - `DENO`         : Deno runtime
+ * - `REACT_NATIVE` : React Native
+ * - `ELECTRON`     : Electron
+ * - `CLOUDFLARE`   : Cloudflare Workers
+ * - `AWS_LAMBDA`   : AWS Lambda
+ */
+export declare enum RuntimeName {
+    NODE = "Node.js",
+    BROWSER = "Browser",
+    DENO = "Deno",
+    REACT_NATIVE = "React Native",
+    ELECTRON = "Electron",
+    CLOUDFLARE = "Cloudflare Workers",
+    AWS_LAMBDA = "AWS Lambda"
+}
+/**
+ * Minimal subset of the `window` object, sufficient to work with DOM-like APIs.
+ *
+ * Provides access to the basic constructors and the document object:
+ * - `Node`
+ * - `Element`
+ * - `Text`
+ * - `NodeList`
+ * - `Attr`
+ * - `document`
+ */
+export interface MinimalWindow {
+    Node: typeof Node;
+    Element: typeof Element;
+    Text: typeof Text;
+    NodeList: typeof NodeList;
+    Attr: typeof Attr;
+    document: Document;
+}

package/agnostic/misc/crossenv/types.js

@@ -0,0 +1,7 @@
+import {
+  RuntimeName
+} from "../../../chunks/chunk-XIIJYVJZ.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+export {
+  RuntimeName
+};

package/agnostic/misc/crossenv/window/index.d.ts

@@ -1,7 +1,28 @@
-import { Types } from '../types/index.js';
-export declare namespace Window {
-    function exists(): boolean;
-    function set(customWindow: Types.MinimalWindow | null): Types.MinimalWindow | null;
-    function unset(): Types.MinimalWindow | null;
-    function get(): Types.MinimalWindow;
-}
+import { MinimalWindow } from '../types.js';
+/**
+ * Checks whether a `window` object exists in the current environment.
+ *
+ * @returns {boolean} `true` if `window` is present, `false` otherwise.
+ */
+export declare function exists(): boolean;
+/**
+ * Sets a custom `window` object to be used internally.
+ *
+ * @param {MinimalWindow | null} customWindow - The window object to set, or `null` to unset.
+ * @returns {MinimalWindow | null} The window object that was set.
+ */
+export declare function set(customWindow: MinimalWindow | null): MinimalWindow | null;
+/**
+ * Resets the internal window reference to the global `window` if it exists,
+ * or `null` if no global `window` is available.
+ *
+ * @returns {MinimalWindow | null} The current internal window object after reset.
+ */
+export declare function unset(): MinimalWindow | null;
+/**
+ * Retrieves the currently set `window` object.
+ *
+ * @returns {MinimalWindow} The internal window object.
+ * @throws Will throw an error if no window has been set and none exists globally.
+ */
+export declare function get(): MinimalWindow;

package/agnostic/misc/crossenv/window/index.js

@@ -1,7 +1,13 @@
 import {
-  Window
-} from "../../../../chunks/chunk-RLJOYG64.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
+  exists,
+  get,
+  set,
+  unset
+} from "../../../../chunks/chunk-ROWPCMQY.js";
+import "../../../../chunks/chunk-XCBH6NLF.js";
 export {
-  Window
+  exists,
+  get,
+  set,
+  unset
 };

package/agnostic/misc/crossenv/window/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/agnostic/misc/data-size/index.d.ts

@@ -1,9 +1,4 @@
-export type BinaryUnit = 'kibibyte' | 'mebibyte' | 'gibibyte' | 'tebibyte' | 'pebibyte' | 'exbibyte';
-export type BinaryUnitShort = 'KiB' | 'MiB' | 'GiB' | 'TiB' | 'PiB' | 'EiB';
-export type DecimalUnit = 'bit' | 'byte' | 'kilobyte' | 'megabyte' | 'gigabyte' | 'terabyte' | 'petabyte' | 'exabyte';
-export type DecimalUnitShort = 'b' | 'B' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB' | 'EB';
-export type Unit = BinaryUnit | DecimalUnit;
-export type UnitShort = BinaryUnitShort | DecimalUnitShort;
+import type { Unit, UnitShort } from './types.js';
 export declare class DataSize {
     value: number;
     unit: Unit;
@@ -11,7 +6,7 @@ export declare class DataSize {
     toBits(): number;
     toBytes(): number;
     toB: () => number;
-    toKiloBytes(): number;
+    toKilobytes(): number;
     toKB: () => number;
     toMegabytes(): number;
     toMB: () => number;
@@ -38,28 +33,55 @@ export declare class DataSize {
 }
 export declare function bits(value: number): DataSize;
 export declare function bytes(value: number): DataSize;
-export declare const B: typeof bytes;
-export declare function kiloBytes(value: number): DataSize;
-export declare const KB: typeof kiloBytes;
-export declare function megaBytes(value: number): DataSize;
-export declare const MB: typeof megaBytes;
+export declare function kilobytes(value: number): DataSize;
+export declare function megabytes(value: number): DataSize;
 export declare function gigabytes(value: number): DataSize;
-export declare const GB: typeof gigabytes;
 export declare function terabytes(value: number): DataSize;
-export declare const TB: typeof terabytes;
 export declare function petabytes(value: number): DataSize;
-export declare const PB: typeof petabytes;
 export declare function exabytes(value: number): DataSize;
-export declare const EB: typeof exabytes;
 export declare function kibibytes(value: number): DataSize;
-export declare const KiB: typeof kibibytes;
 export declare function mebibytes(value: number): DataSize;
-export declare const MiB: typeof mebibytes;
 export declare function gibibytes(value: number): DataSize;
-export declare const GiB: typeof gibibytes;
 export declare function tebibytes(value: number): DataSize;
-export declare const TiB: typeof tebibytes;
 export declare function pebibytes(value: number): DataSize;
-export declare const PiB: typeof pebibytes;
 export declare function exbibytes(value: number): DataSize;
+export declare const B: typeof bytes;
+export declare const KB: typeof kilobytes;
+export declare const MB: typeof megabytes;
+export declare const GB: typeof gigabytes;
+export declare const TB: typeof terabytes;
+export declare const PB: typeof petabytes;
+export declare const EB: typeof exabytes;
+export declare const KiB: typeof kibibytes;
+export declare const MiB: typeof mebibytes;
+export declare const GiB: typeof gibibytes;
+export declare const TiB: typeof tebibytes;
+export declare const PiB: typeof pebibytes;
 export declare const EiB: typeof exbibytes;
+export declare function toBits(value: number, unit: Unit | UnitShort): number;
+export declare function toBytes(value: number, unit: Unit | UnitShort): number;
+export declare function toKilobytes(value: number, unit: Unit | UnitShort): number;
+export declare function toMegabytes(value: number, unit: Unit | UnitShort): number;
+export declare function toGigabytes(value: number, unit: Unit | UnitShort): number;
+export declare function toTerabytes(value: number, unit: Unit | UnitShort): number;
+export declare function toPetabytes(value: number, unit: Unit | UnitShort): number;
+export declare function toExabytes(value: number, unit: Unit | UnitShort): number;
+export declare function toKibibytes(value: number, unit: Unit | UnitShort): number;
+export declare function toMebibytes(value: number, unit: Unit | UnitShort): number;
+export declare function toGibibytes(value: number, unit: Unit | UnitShort): number;
+export declare function toTebibytes(value: number, unit: Unit | UnitShort): number;
+export declare function toPebibytes(value: number, unit: Unit | UnitShort): number;
+export declare function toExbibytes(value: number, unit: Unit | UnitShort): number;
+export declare const toB: typeof toBytes;
+export declare const toKB: typeof toKilobytes;
+export declare const toMB: typeof toMegabytes;
+export declare const toGB: typeof toGigabytes;
+export declare const toTB: typeof toTerabytes;
+export declare const toPB: typeof toPetabytes;
+export declare const toEB: typeof toExabytes;
+export declare const toKiB: typeof toKibibytes;
+export declare const toMiB: typeof toMebibytes;
+export declare const toGiB: typeof toGibibytes;
+export declare const toTiB: typeof toTebibytes;
+export declare const toPiB: typeof toPebibytes;
+export declare const toEiB: typeof toExbibytes;