@design-edito/tools 0.4.22 → 0.5.0

package/agnostic/html/hyper-json/types/index.d.ts

@@ -1,7 +1,7 @@
 import type * as Outcome from '../../../misc/outcome/index.js';
-import { type Tree as TreeNamespace } from '../tree/index.js';
-import { type Transformer } from '../transformer/index.js';
-import { type Method } from '../method/index.js';
+import type { Tree as TreeNamespace } from '../tree/index.js';
+import type { Transformer } from '../transformer/index.js';
+import type { Method } from '../method/index.js';
 export declare namespace Types {
     namespace Transformations {
         type FunctionMainValueFailure = {
@@ -112,22 +112,22 @@ export declare namespace Types {
         };
     }
     namespace SmartTags {
-        type SmartTag<Main extends Types.Tree.RestingValue | undefined = Types.Tree.RestingValue | undefined, Args extends Types.Tree.RestingArrayValue = Types.Tree.RestingArrayValue, Output extends Types.Tree.RestingValue = Types.Tree.RestingValue> = {
-            defaultMode: Types.Tree.Mode;
-            isolationInitType: Exclude<Types.Tree.ValueTypeName, 'transformer' | 'method'>;
-            generator: (innerValue: Types.Tree.RestingValue, mode: Types.Tree.Mode, sourceTree: TreeNamespace.Tree) => {
+        type SmartTag<Main extends Tree.RestingValue | undefined = Tree.RestingValue | undefined, Args extends Tree.RestingArrayValue = Tree.RestingArrayValue, Output extends Tree.RestingValue = Tree.RestingValue> = {
+            defaultMode: Tree.Mode;
+            isolationInitType: Exclude<Tree.ValueTypeName, 'transformer' | 'method'>;
+            generator: (innerValue: Tree.RestingValue, mode: Tree.Mode, sourceTree: TreeNamespace.Tree) => {
                 transformer: Transformer<Main, Args, Output>;
                 method: Method<Main, Args, Output>;
             };
         };
-        type Descriptor<Main extends Types.Tree.RestingValue | undefined = Types.Tree.RestingValue | undefined, Args extends Types.Tree.RestingArrayValue = Types.Tree.RestingArrayValue, Output extends Types.Tree.RestingValue = Types.Tree.RestingValue> = {
+        type Descriptor<Main extends Tree.RestingValue | undefined = Tree.RestingValue | undefined, Args extends Tree.RestingArrayValue = Tree.RestingArrayValue, Output extends Tree.RestingValue = Tree.RestingValue> = {
             name: string;
-            defaultMode: Types.Tree.Mode;
-            isolationInitType: Exclude<Types.Tree.ValueTypeName, 'transformer' | 'method'>;
+            defaultMode: Tree.Mode;
+            isolationInitType: Exclude<Tree.ValueTypeName, 'transformer' | 'method'>;
             mainValueCheck: Transformer<Main, Args, Output>['typeChecks']['mainValue'];
             argsValueCheck: Transformer<Main, Args, Output>['typeChecks']['argsValue'];
             func: Transformer<Main, Args, Output>['func'];
         };
-        type Register = Map<string, Types.SmartTags.SmartTag<any, any, any>>;
+        type Register = Map<string, SmartTag<any, any, any>>;
     }
 }

package/agnostic/html/hyper-json/utils/index.d.ts

@@ -50,8 +50,8 @@ export declare namespace Utils {
             expected: string;
             found: string;
         }>;
-        const makeMainValueError: (expected: string, found: string, details?: any) => Types.Transformations.FunctionMainValueFailure;
-        const makeArgsValueError: (expected: string, found: string, position?: number, details?: any) => Types.Transformations.FunctionArgsValueFailure;
-        const makeTransformationError: (details?: any) => Types.Transformations.FunctionTransformationFailure;
+        const makeMainValueError: (expected: string, found: string, details?: unknown) => Types.Transformations.FunctionMainValueFailure;
+        const makeArgsValueError: (expected: string, found: string, position?: number, details?: unknown) => Types.Transformations.FunctionArgsValueFailure;
+        const makeTransformationError: (details?: unknown) => Types.Transformations.FunctionTransformationFailure;
     }
 }

package/agnostic/html/hyper-json/utils/index.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines, @typescript-eslint/no-unsafe-type-assertion -- generic type params (T/K/Value) and DOM NodeList casts here can't be narrowed from a generic/runtime check at compile time; guarded by runtime typeCheck(s)/instanceof checks immediately prior */
 import * as Window from '../../../misc/crossenv/window/index.js';
 import { isRecord } from '../../../objects/is-record/index.js';
 import { recordMap } from '../../../objects/record-map/index.js';
@@ -35,6 +36,7 @@ export var Utils;
             return [...value.map(clone)];
         if (isRecord(value))
             return recordMap(value, prop => clone(prop));
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
         throw new Error(`Cannot clone value: ${value}`);
     }
     Utils.clone = clone;
@@ -45,11 +47,13 @@ export var Utils;
             const transformer = toCoalesce;
             const transformationResult = transformer.apply(currentValue);
             if (!transformationResult.success) {
+                // eslint-disable-next-line no-console
                 console.warn({ ...transformationResult.error });
                 return currentValue;
             }
             const evaluated = transformationResult.payload;
             if (transformer.mode === 'isolation') {
+                // eslint-disable-next-line no-param-reassign
                 toCoalesce = evaluated; // We set toCoalesce to the result of the evaluation, and process this result below as a non-Transformer value
             }
             else {
@@ -78,12 +82,12 @@ export var Utils;
                 return `${currentValue}${toCoalesce.textContent}`;
             if (toCoalesce instanceof Element) {
                 const frag = document.createDocumentFragment();
-                frag.append(currentValue, Utils.clone(toCoalesce));
+                frag.append(currentValue, clone(toCoalesce));
                 return frag.childNodes;
             }
             if (toCoalesce instanceof NodeList) {
                 const frag = document.createDocumentFragment();
-                frag.append(currentValue, ...Array.from(Utils.clone(toCoalesce)));
+                frag.append(currentValue, ...Array.from(clone(toCoalesce)));
                 return frag.childNodes;
             }
             return toCoalesce;
@@ -164,7 +168,7 @@ export var Utils;
         const { document, Element, Text, NodeList } = Window.get();
         if (value instanceof Text) {
             const elt = document.createElement('text');
-            elt.innerHTML = value.textContent ?? '';
+            elt.innerHTML = value.textContent;
             return elt;
         }
         if (value instanceof Element)
@@ -367,6 +371,7 @@ export var Utils;
                 return document.createElement('div');
             if (name === 'array')
                 return [];
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             if (name === 'record')
                 return {};
             throw new Error(`Unknown value type name: ${name}`);

package/agnostic/html/index.d.ts

@@ -1,5 +1,4 @@
 export * as deepSelect from './deep-select/index.js'
-export * as getNodeAncestors from './get-node-ancestors/index.js'
 export * as getPositionInsideParent from './get-position-inside-parent/index.js'
 export * as hyperJson from './hyper-json/index.js'
 export * as insertNode from './insert-node/index.js'
@@ -7,4 +6,5 @@ export * as placeholders from './placeholders/index.js'
 export * as replaceInElement from './replace-in-element/index.js'
 export * as selectorToElement from './selector-to-element/index.js'
 export * as stringToNodes from './string-to-nodes/index.js'
+export * as getNodeAncestors from './get-node-ancestors/index.js'
 export * as watchSelection from './watch-selection/index.js'

package/agnostic/html/index.js

@@ -1,5 +1,4 @@
 export * as deepSelect from './deep-select/index.js'
-export * as getNodeAncestors from './get-node-ancestors/index.js'
 export * as getPositionInsideParent from './get-position-inside-parent/index.js'
 export * as hyperJson from './hyper-json/index.js'
 export * as insertNode from './insert-node/index.js'
@@ -7,4 +6,5 @@ export * as placeholders from './placeholders/index.js'
 export * as replaceInElement from './replace-in-element/index.js'
 export * as selectorToElement from './selector-to-element/index.js'
 export * as stringToNodes from './string-to-nodes/index.js'
+export * as getNodeAncestors from './get-node-ancestors/index.js'
 export * as watchSelection from './watch-selection/index.js'

package/agnostic/html/insert-node/index.d.ts

@@ -11,9 +11,9 @@ export type InsertNodePosition = 'after' | 'before' | 'startof' | 'endof';
 /**
  * Inserts a DOM node at a specific position relative to a reference node.
  *
- * @param {Node} node - The node to insert.
- * @param {InsertNodePosition} position - The insertion position relative to the reference node.
- * @param {Node} reference - The reference node used to determine the insertion point.
- * @returns {void}
+ * @param node - The node to insert.
+ * @param position - The insertion position relative to the reference node.
+ * @param reference - The reference node used to determine the insertion point.
+ * @returns
  */
 export declare function insertNode(node: Node, position: InsertNodePosition, reference: Node): void;

package/agnostic/html/insert-node/index.js

@@ -1,10 +1,10 @@
 /**
  * Inserts a DOM node at a specific position relative to a reference node.
  *
- * @param {Node} node - The node to insert.
- * @param {InsertNodePosition} position - The insertion position relative to the reference node.
- * @param {Node} reference - The reference node used to determine the insertion point.
- * @returns {void}
+ * @param node - The node to insert.
+ * @param position - The insertion position relative to the reference node.
+ * @param reference - The reference node used to determine the insertion point.
+ * @returns
  */
 export function insertNode(node, position, reference) {
     if (position === 'after') {

package/agnostic/html/replace-in-element/index.d.ts

@@ -6,10 +6,10 @@
  * are applied. Each target node is removed after its replacement node(s)
  * are inserted in its place.
  *
- * @param {Element} inputElement - The root element within which replacements are applied.
- * @param {Map<Node, Node | NodeListOf<Node>>} replaceMap
+ * @param inputElement - The root element within which replacements are applied.
+ * @param replaceMap
  * - A map associating nodes to be replaced with either a single replacement
  *   node or a list of replacement nodes.
- * @returns {Element} The original `inputElement`, after replacements have been applied.
+ * @returns The original `inputElement`, after replacements have been applied.
  */
 export declare function replaceInElement(inputElement: Element, replaceMap: Map<Node, Node | NodeListOf<Node>>): Element;

package/agnostic/html/replace-in-element/index.js

@@ -7,11 +7,11 @@ import { getNodeAncestors } from '../get-node-ancestors/index.js';
  * are applied. Each target node is removed after its replacement node(s)
  * are inserted in its place.
  *
- * @param {Element} inputElement - The root element within which replacements are applied.
- * @param {Map<Node, Node | NodeListOf<Node>>} replaceMap
+ * @param inputElement - The root element within which replacements are applied.
+ * @param replaceMap
  * - A map associating nodes to be replaced with either a single replacement
  *   node or a list of replacement nodes.
- * @returns {Element} The original `inputElement`, after replacements have been applied.
+ * @returns The original `inputElement`, after replacements have been applied.
  */
 export function replaceInElement(inputElement, replaceMap) {
     const actualReplaceMap = new Map(Array.from(replaceMap).filter(([toReplace]) => {
@@ -24,7 +24,7 @@ export function replaceInElement(inputElement, replaceMap) {
         }
         else {
             const replacerNodes = Array.from(replacer);
-            replacerNodes.forEach(rpl => toReplace.parentNode?.insertBefore(rpl, toReplace));
+            replacerNodes.forEach(rpl => { toReplace.parentNode?.insertBefore(rpl, toReplace); });
         }
         toReplace.parentNode?.removeChild(toReplace);
     });

package/agnostic/html/selector-to-element/index.d.ts

@@ -8,8 +8,8 @@
  * - Classes (e.g., `".class1.class2"`)
  * - Attributes (e.g., `"[attr=value]"`)
  *
- * @param {string} selector - The selector string used to construct the element.
- * @returns {Element} A newly created DOM element corresponding to the selector.
+ * @param selector - The selector string used to construct the element.
+ * @returns A newly created DOM element corresponding to the selector.
  *
  * @throws Will throw an error if no document object is available for element creation.
  */

package/agnostic/html/selector-to-element/index.js

@@ -10,19 +10,19 @@ import * as Window from '../../misc/crossenv/window/index.js';
  * - Classes (e.g., `".class1.class2"`)
  * - Attributes (e.g., `"[attr=value]"`)
  *
- * @param {string} selector - The selector string used to construct the element.
- * @returns {Element} A newly created DOM element corresponding to the selector.
+ * @param selector - The selector string used to construct the element.
+ * @returns A newly created DOM element corresponding to the selector.
  *
  * @throws Will throw an error if no document object is available for element creation.
  */
 export function selectorToElement(selector) {
     // RegExps
-    const tagRegexp = /^[A-Za-z]+/;
+    const tagRegexp = /^[A-Za-z]+/v;
     // The dot is apparently a valid character but is prevented here
     // in order to be able to match class elements
-    const idRegexp = /#[A-Za-z]+[\w\-\:]*/;
-    const classRegexp = /\.[A-Za-z]+[\w\-]*/g;
-    const attributeRegexp = /\[[A-Za-z]+[\w\-]*(="[\w\-]+")?\]/g;
+    const idRegexp = /#[A-Za-z]+[\w\-\:]*/v;
+    const classRegexp = /\.[A-Za-z]+[\w\-]*/gv;
+    const attributeRegexp = /\[[A-Za-z]+[\w\-]*(="[\w\-]+")?\]/gv;
     // Matched
     const matchedTags = selector.match(tagRegexp) ?? [];
     const matchedIds = selector.match(idRegexp) ?? [];
@@ -31,12 +31,12 @@ export function selectorToElement(selector) {
     // Extracted
     const tag = matchedTags[matchedTags.length - 1] ?? 'div';
     const id = matchedIds.length > 0
-        ? matchedIds[matchedIds.length - 1]?.replace(/^#/, '') ?? null
+        ? matchedIds[matchedIds.length - 1]?.replace(/^#/v, '') ?? null
         : null;
-    const classes = matchedClasses.map(matchedClass => matchedClass.replace(/^\./, ''));
+    const classes = matchedClasses.map(matchedClass => matchedClass.replace(/^\./v, ''));
     const attributes = matchedAttrs.map(matchedAttr => matchedAttr
-        .replace(/^\[/, '')
-        .replace(/\]$/, '')
+        .replace(/^\[/v, '')
+        .replace(/\]$/v, '')
         .split('='));
     // Returning
     const element = Window.get().document.createElement(tag);
@@ -47,7 +47,7 @@ export function selectorToElement(selector) {
     attributes.forEach(([name, value = '']) => {
         if (name === undefined)
             return;
-        const cleanValue = value.replace(/^"(.*)"$/, '$1');
+        const cleanValue = value.replace(/^"(.*)"$/v, '$1');
         element.setAttribute(name, cleanValue);
     });
     return element;

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

@@ -7,8 +7,8 @@
  * 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.
+ * @param inputStr - The input string to convert into nodes.
+ * @param [options.sanitize] - Sanitization options for the input string.
+ * @returns An array of DOM nodes created from the string.
  */
 export declare function stringToNodes(inputStr: string): Node[];

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

@@ -8,9 +8,9 @@ import * as Window from '../../misc/crossenv/window/index.js';
  * 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.
+ * @param inputStr - The input string to convert into nodes.
+ * @param [options.sanitize] - Sanitization options for the input string.
+ * @returns An array of DOM nodes created from the string.
  */
 export function stringToNodes(inputStr) {
     const window = Window.get();

package/agnostic/html/watch-selection/index.d.ts

@@ -16,13 +16,12 @@ type Options = {
  *
  * Requires a browser environment with `window` and `document`.
  *
- * @param {string} selector - CSS selector passed to `deepSelect`.
- * @param {Options} options - Callbacks and polling configuration:
+ * @param selector - CSS selector passed to `deepSelect`.
+ * @param options - Callbacks and polling configuration:
  *   - `watch`: Handler for elements that enter the selection.
  *   - `unwatch`: Handler for elements that leave the selection.
  *   - `selectIntervalMs`: Delay between polls in milliseconds.
- * @returns {Promise<{ kill: () => void }>}
- * Resolves after the initial selection is processed. `kill` stops polling and calls `unwatch`
+ * @returns Resolves after the initial selection is processed. `kill` stops polling and calls `unwatch`
  * on every element still watched.
  *
  * @example
@@ -35,7 +34,7 @@ type Options = {
  * // later, when tearing down:
  * kill()
  */
-export declare const watchSelection: (selector: string, options: Options) => Promise<{
+export declare const watchSelection: (selector: string, options?: Options) => Promise<{
     kill: () => void;
 }>;
 export {};

package/agnostic/html/watch-selection/index.js

@@ -8,13 +8,12 @@ import { deepSelect } from '../deep-select/index.js';
  *
  * Requires a browser environment with `window` and `document`.
  *
- * @param {string} selector - CSS selector passed to `deepSelect`.
- * @param {Options} options - Callbacks and polling configuration:
+ * @param selector - CSS selector passed to `deepSelect`.
+ * @param options - Callbacks and polling configuration:
  *   - `watch`: Handler for elements that enter the selection.
  *   - `unwatch`: Handler for elements that leave the selection.
  *   - `selectIntervalMs`: Delay between polls in milliseconds.
- * @returns {Promise<{ kill: () => void }>}
- * Resolves after the initial selection is processed. `kill` stops polling and calls `unwatch`
+ * @returns Resolves after the initial selection is processed. `kill` stops polling and calls `unwatch`
  * on every element still watched.
  *
  * @example
@@ -28,8 +27,8 @@ import { deepSelect } from '../deep-select/index.js';
  * kill()
  */
 export const watchSelection = async (selector, options) => {
-    const watch = options?.watch ?? (() => { });
-    const unwatch = options?.unwatch ?? (() => { });
+    const watch = options?.watch ?? (() => undefined);
+    const unwatch = options?.unwatch ?? (() => undefined);
     let watched = await deepSelect(selector);
     watched.forEach(watch);
     const selectIntervalMs = options?.selectIntervalMs ?? 100;

package/agnostic/misc/assert/index.js

@@ -1,7 +1,9 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
 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  ');
+    // eslint-disable-next-line no-console
     console.info(`✅ SUCCESS:\n  ${formattedLabel}`);
 }
 function makeFailure(label) {
@@ -58,7 +60,7 @@ export async function assert(label, assertion) {
 }
 export async function assertVerbose(label, assertion) {
     const asserted = await assert(label, assertion);
-    if (asserted?.success) {
+    if (asserted.success) {
         makeSuccess(asserted.payload);
         return asserted;
     }

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

@@ -5,8 +5,8 @@
  * - 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.
+ * @param value - The value to convert.
+ * @returns The boolean representation of the input.
  */
 export declare function toBoolean(value: unknown): boolean;
 /**
@@ -16,8 +16,8 @@ export declare function toBoolean(value: unknown): boolean;
  * - Strings are parsed as floats.
  * - Other values return 0.
  *
- * @param {unknown} value - The value to convert.
- * @returns {number} The numeric representation of the input.
+ * @param value - The value to convert.
+ * @returns The numeric representation of the input.
  */
 export declare function toNumber(value: unknown): number;
 /**
@@ -26,15 +26,15 @@ export declare function toNumber(value: unknown): number;
  * - 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.
+ * @param value - The value to convert.
+ * @returns 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`.
+ * @param _value - The input value (ignored).
+ * @returns Always returns `null`.
  */
 export declare function toNull(_value: unknown): null;
 /**
@@ -44,8 +44,8 @@ export declare function toNull(_value: unknown): null;
  * - 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.
+ * @param value - The value to convert.
+ * @returns The array representation of the input.
  */
 export declare function toArray(value: unknown): unknown[];
 /**
@@ -54,8 +54,8 @@ export declare function toArray(value: unknown): unknown[];
  * - 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.
+ * @param value - The value to convert.
+ * @returns Array of numeric values.
  */
 export declare function toNumberArr(value: unknown): number[];
 /**
@@ -64,8 +64,8 @@ export declare function toNumberArr(value: unknown): number[];
  * - 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.
+ * @param value - The value to convert.
+ * @returns The object representation of the input.
  */
 export declare function toRecord(value: unknown): Record<string, unknown>;
 /**
@@ -75,7 +75,7 @@ export declare function toRecord(value: unknown): Record<string, unknown>;
  * - 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.
+ * @param value - The value to convert.
+ * @returns An `Error` instance representing the input.
  */
 export declare function toError(value: unknown): Error;

package/agnostic/misc/cast/index.js

@@ -6,8 +6,8 @@ import { isFalsy } from '../../booleans/is-falsy/index.js';
  * - 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.
+ * @param value - The value to convert.
+ * @returns The boolean representation of the input.
  */
 export function toBoolean(value) {
     if (typeof value === 'boolean')
@@ -26,8 +26,8 @@ export function toBoolean(value) {
  * - Strings are parsed as floats.
  * - Other values return 0.
  *
- * @param {unknown} value - The value to convert.
- * @returns {number} The numeric representation of the input.
+ * @param value - The value to convert.
+ * @returns The numeric representation of the input.
  */
 export function toNumber(value) {
     if (typeof value === 'number')
@@ -42,8 +42,8 @@ export function toNumber(value) {
  * - 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.
+ * @param value - The value to convert.
+ * @returns The string representation of the input.
  */
 export function toString(value) {
     if (typeof value === 'string')
@@ -53,8 +53,8 @@ export function toString(value) {
 /**
  * Converts any value to `null`.
  *
- * @param {unknown} _value - The input value (ignored).
- * @returns {null} Always returns `null`.
+ * @param _value - The input value (ignored).
+ * @returns Always returns `null`.
  */
 export function toNull(_value) {
     return null;
@@ -66,8 +66,8 @@ export function toNull(_value) {
  * - 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.
+ * @param value - The value to convert.
+ * @returns The array representation of the input.
  */
 export function toArray(value) {
     if (Array.isArray(value))
@@ -83,8 +83,8 @@ export function toArray(value) {
  * - 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.
+ * @param value - The value to convert.
+ * @returns Array of numeric values.
  */
 export function toNumberArr(value) {
     const arrValue = toArray(value);
@@ -96,16 +96,16 @@ export function toNumberArr(value) {
  * - 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.
+ * @param value - The value to convert.
+ * @returns The object representation of the input.
  */
 export function toRecord(value) {
     const record = {};
     try {
         Object
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- no runtime guard here; safety comes from the surrounding try/catch below
             .keys(value)
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- no runtime guard here; safety comes from the surrounding try/catch below
             .forEach(key => { record[key] = value[key]; });
     }
     catch (err) {
@@ -120,8 +120,8 @@ export function toRecord(value) {
  * - 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.
+ * @param value - The value to convert.
+ * @returns An `Error` instance representing the input.
  */
 export function toError(value) {
     if (value instanceof Error)

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * @property downlink - Estimated downlink speed in Mbps.
+ * @property type - Connection type.
+ * @property effectiveType - Effective connection type.
  */
 export type MinimalConnection = {
     downlink: number;
@@ -15,12 +15,12 @@ export type MinimalConnection = {
  *
  * Uses the `navigator.connection` API or vendor-prefixed alternatives.
  *
- * @returns {MinimalConnection | undefined} A minimal connection object if available, otherwise `undefined`.
+ * @returns 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.
+ * @returns Downlink speed in Mbps, or `undefined` if not available.
  */
 export declare function getCurrentDownlink(): number | undefined;

package/agnostic/misc/connection/index.js

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
 import * as Window from '../crossenv/window/index.js';
 function isType(unk) {
     return unk === 'bluetooth'
@@ -39,10 +40,11 @@ function isConnection(unk) {
  *
  * Uses the `navigator.connection` API or vendor-prefixed alternatives.
  *
- * @returns {MinimalConnection | undefined} A minimal connection object if available, otherwise `undefined`.
+ * @returns A minimal connection object if available, otherwise `undefined`.
  */
 export function getConnection() {
     const window = Window.get();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion -- MinimalWindow deliberately doesn't declare `navigator`; this is browser-only feature detection, guarded by the typeof/null check below
     const navigator = window.navigator;
     if (typeof navigator !== 'object' || navigator === null)
         return undefined;
@@ -56,7 +58,7 @@ export function getConnection() {
 /**
  * Retrieves the estimated downlink speed of the current network connection.
  *
- * @returns {number | undefined} Downlink speed in Mbps, or `undefined` if not available.
+ * @returns Downlink speed in Mbps, or `undefined` if not available.
  */
 export function getCurrentDownlink() {
     return getConnection()?.downlink;