@design-edito/tools 0.2.39 → 0.2.41

package/agnostic/html/string-to-nodes/index.d.ts

@@ -1,7 +1,14 @@
-import { Sanitize } from '../../html/sanitize/index.js';
-type Options = {
-    sanitize?: Sanitize.Options;
-    documentObj?: Document;
-};
-export declare function stringToNodes(dirtyStr: string, options?: Options): Node[];
-export {};
+/**
+ * Converts a string into an array of DOM nodes.
+ *
+ * If sanitization options are provided, the string is first sanitized
+ * using `Sanitize.sanitize`.
+ *
+ * Only element and text nodes are included in the returned array; comment
+ * and other node types are ignored.
+ *
+ * @param {string} inputStr - The input string to convert into nodes.
+ * @param {SanitizeHtmlOptions} [options.sanitize] - Sanitization options for the input string.
+ * @returns {Node[]} An array of DOM nodes created from the string.
+ */
+export declare function stringToNodes(inputStr: string): Node[];

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

@@ -1,16 +1,20 @@
 import {
-  stringToNodes
-} from "../../../chunks/chunk-ZBBU2P4D.js";
-import "../../../chunks/chunk-XB3EGDBI.js";
-import "../../../chunks/chunk-TIER4TF4.js";
-import "../../../chunks/chunk-FR5H2OCV.js";
-import "../../../chunks/chunk-S2NMAH7K.js";
-import "../../../chunks/chunk-LV2VMOWR.js";
-import "../../../chunks/chunk-RLJOYG64.js";
-import "../../../chunks/chunk-WH6BPDAC.js";
-import "../../../chunks/chunk-QHLQVR3E.js";
-import "../../../chunks/chunk-FENXVJYO.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+  get
+} from "../../../chunks/chunk-ROWPCMQY.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// src/agnostic/html/string-to-nodes/index.ts
+function stringToNodes(inputStr) {
+  const window = get();
+  const { document, Node } = window;
+  const wrapperDiv = document.createElement("div");
+  wrapperDiv.innerHTML = inputStr;
+  const nodes = Array.from(wrapperDiv.childNodes).filter((node) => {
+    const allowedNodeTypes = [Node.ELEMENT_NODE, Node.TEXT_NODE];
+    return allowedNodeTypes.includes(node.nodeType);
+  });
+  return nodes;
+}
 export {
   stringToNodes
 };

package/agnostic/html/string-to-nodes/index.test.d.ts

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

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

@@ -1,7 +1,5 @@
-import { Outcome } from '../outcome/index.js';
-export declare namespace Assert {
-    type Assertion = (() => boolean) | (() => Promise<boolean>) | boolean;
-    export function assert(label: string, assertion: Assertion | Array<Assertion> | Map<string, Assertion> | Record<string, Assertion>): Promise<Outcome.Either<string, string>>;
-    export function assertVerbose(label: string, assertion: Assertion | Array<Assertion> | Map<string, Assertion>): Promise<void | Outcome.Success<string>>;
-    export {};
-}
+import * as Outcome from '../outcome/index.js';
+type Assertion = (() => boolean) | (() => Promise<boolean>) | boolean;
+export declare function assert(label: string, assertion: Assertion | Array<Assertion> | Map<string, Assertion> | Record<string, Assertion>): Promise<Outcome.Either<string, string>>;
+export declare function assertVerbose(label: string, assertion: Assertion | Array<Assertion> | Map<string, Assertion>): Promise<void | Outcome.Success<string>>;
+export {};

package/agnostic/misc/assert/index.js

@@ -1,11 +1,64 @@
 import {
-  Assert
-} from "../../../chunks/chunk-WAMSK4A3.js";
-import "../../../chunks/chunk-JMU5PDBD.js";
-import "../../../chunks/chunk-WH6BPDAC.js";
-import "../../../chunks/chunk-QHLQVR3E.js";
-import "../../../chunks/chunk-FENXVJYO.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
+  makeFailure,
+  makeSuccess
+} from "../../../chunks/chunk-QEKI6WGQ.js";
+import {
+  unknownToString
+} from "../../../chunks/chunk-FENXVJYO.js";
+import "../../../chunks/chunk-XCBH6NLF.js";
+
+// 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 === false) return makeFailure(label);
+      else return makeSuccess(label);
+    } catch (err) {
+      const errStr = unknownToString(err);
+      return makeFailure(`${label} / ${errStr}`);
+    }
+  } 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(([innerLabel, innerAssertion]) => {
+      const fullLabel = `${label} / ${innerLabel}`;
+      const asserted = assert(fullLabel, innerAssertion);
+      return 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 === false);
+    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 {
-  Assert
+  assert,
+  assertVerbose
 };

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-YWSXCFYY.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/cast/index.test.d.ts

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

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/connection/index.test.d.ts

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

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) => void;
+    flush: () => void;
+};

package/agnostic/misc/crawler/index.js

@@ -1,8 +1,35 @@
 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/crawler/index.test.d.ts

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

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/detect-runtime/index.test.d.ts

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

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

@@ -0,0 +1,40 @@
+/**
+ * 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;
+    ShadowRoot: typeof ShadowRoot;
+    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 {};