From fd5a1c0c5444bd62f894a5d4b01de68e0c016f34 Mon Sep 17 00:00:00 2001 From: Nev Date: Sun, 8 Nov 2026 09:37:55 -0800 Subject: [PATCH] fix(docs): resolve all api-extractor TSDoc warnings and the unused import lint warning Fixes the 34 api-extractor warnings (ae-unresolved-link and tsdoc-*) and the remaining eslint warning. Only doc comments and one unused import change, so there is no runtime or API change. - arrIndexOfSubset / arrLastIndexOfSubset: parameter names (theArray, subset, fromIndex) were written as {@link}, which only resolves to exports; they are now code spans - arrKeys / strAt: removed the links to polyArrKeys / polyStrAt, which are not exported (like the other @group Polyfill functions), and named them as code - iterForOf, ArrToMapKeySelectorFn, ArrToMapValueSelectorFn, setMicroTaskFallbackOptions, setNextTickFallbackOptions: the links to the overloaded arrForEach / arrToMap / scheduleMicrotask / scheduleNextTick are now code spans. api-extractor requires an overload selector such as {@link (arrForEach:1)}, which TypeDoc cannot resolve, and no syntax is accepted by both - strMatchAll: replaced the link to the non-existent strMatch with String.prototype.match() - isIntInRange (number.ts): wrapped "min <= value <= max" in a code span so it is not parsed as HTML - strCount: changed the JSDoc-style "@throws {TypeError}" to the TSDoc form - strNormalizeNewlines: wrapped the "\n", "\r\n", "\r" and "\n\r" values in code spans so the backslashes are not parsed as escapes - nextTick: removed the unused getQueueMicrotask import fix(docs): resolve the remaining TypeDoc warnings - scheduleMicrotask / scheduleNextTick: give each overload its own doc comment, so the (callback, options?) signature no longer documents an args parameter it doesn't have, and the (callback, args, options?) signature gets its own parameter docs and examples - typedoc.json: remove the blockTags list, which TypeDoc ignored because tsdoc.json defines the tags (it warned that the list would be overwritten) --- lib/src/array/arrIndexOfSubset.ts | 24 +++++++++---------- lib/src/array/arrKeys.ts | 2 +- lib/src/helpers/number.ts | 2 +- lib/src/iterator/forOf.ts | 2 +- lib/src/iterator/types.ts | 4 ++-- lib/src/string/at.ts | 2 +- lib/src/string/count.ts | 2 +- lib/src/string/match_all.ts | 4 ++-- lib/src/string/normalize_newlines.ts | 2 +- lib/src/timer/microtask.ts | 26 +++++++++++++++++--- lib/src/timer/nextTick.ts | 30 +++++++++++++++++++---- typedoc.json | 36 +--------------------------- 12 files changed, 72 insertions(+), 64 deletions(-) diff --git a/lib/src/array/arrIndexOfSubset.ts b/lib/src/array/arrIndexOfSubset.ts index c0982c23..ddeda994 100644 --- a/lib/src/array/arrIndexOfSubset.ts +++ b/lib/src/array/arrIndexOfSubset.ts @@ -28,18 +28,18 @@ function _normalizeFromIndex(value: number | null | undefined, defValue: number) } /** - * The arrIndexOfSubset() method returns the index within {@link theArray} at which {@link subset} + * The arrIndexOfSubset() method returns the index within `theArray` at which `subset` * first matches contiguously, comparing elements using strict equality (the same method used by the * === or triple-equals operator). * - * Unlike a simple `arrIndexOf()` of the first element of {@link subset}, this continues searching + * Unlike a simple `arrIndexOf()` of the first element of `subset`, this continues searching * later occurrences of that first element until it finds one where the whole sequence lines up (or - * exhausts {@link theArray}), which avoids landing on the wrong occurrence when values repeat -- for + * exhausts `theArray`), which avoids landing on the wrong occurrence when values repeat -- for * example matching one stack trace against another when recursive calls repeat identical lines. * - * If {@link theArray} has fewer remaining elements than {@link subset} from a candidate position, the - * comparison is limited to just those available elements -- so a {@link subset} that "runs off the end" - * of {@link theArray} is still considered a match against its available prefix. This makes it possible + * If `theArray` has fewer remaining elements than `subset` from a candidate position, the + * comparison is limited to just those available elements -- so a `subset` that "runs off the end" + * of `theArray` is still considered a match against its available prefix. This makes it possible * to match a shorter (eg. truncated) array against a longer one, or vice-versa. * @function * @since 0.17.0 @@ -112,14 +112,14 @@ export function arrIndexOfSubset(theArray: ArrayLike, subset: ArrayLike } /** - * The arrLastIndexOfSubset() method returns the last index within {@link theArray} at which - * {@link subset} matches contiguously, comparing elements using strict equality (the same method + * The arrLastIndexOfSubset() method returns the last index within `theArray` at which + * `subset` matches contiguously, comparing elements using strict equality (the same method * used by the === or triple-equals operator). It is the mirror of {@link arrIndexOfSubset}, searching - * backwards from {@link fromIndex} (or the end of theArray) towards the start. + * backwards from `fromIndex` (or the end of theArray) towards the start. * - * As with {@link arrIndexOfSubset}, if {@link theArray} has fewer remaining elements than - * {@link subset} from a candidate position, the comparison is limited to just those available - * elements -- so a {@link subset} that "runs off the end" of {@link theArray} is still considered a + * As with {@link arrIndexOfSubset}, if `theArray` has fewer remaining elements than + * `subset` from a candidate position, the comparison is limited to just those available + * elements -- so a `subset` that "runs off the end" of `theArray` is still considered a * match against its available prefix. * @function * @since 0.17.0 diff --git a/lib/src/array/arrKeys.ts b/lib/src/array/arrKeys.ts index 579b9480..cbaf3d03 100644 --- a/lib/src/array/arrKeys.ts +++ b/lib/src/array/arrKeys.ts @@ -15,7 +15,7 @@ import { mathToInt } from "../math/to_int"; /** * Returns an iterator over all numeric keys from `0` to `length - 1`. * - * This uses `Array.prototype.keys()` when available and falls back to {@link polyArrKeys}. + * This uses `Array.prototype.keys()` when available and falls back to `polyArrKeys()`. * Unlike {@link arrIndexKeys}, this always iterates all index positions, including holes. * @since 0.14.0 * @function diff --git a/lib/src/helpers/number.ts b/lib/src/helpers/number.ts index 6f6e877d..888386a5 100644 --- a/lib/src/helpers/number.ts +++ b/lib/src/helpers/number.ts @@ -71,7 +71,7 @@ export const isInteger: (value: unknown) => value is number = (/* #__PURE__*/_pu * @param value - The value to check * @param min - The minimum inclusive integer value * @param max - The maximum inclusive integer value - * @returns True if the value is an integer and min <= value <= max, false otherwise + * @returns True if the value is an integer and `min <= value <= max`, false otherwise * @example * ```ts * isIntegerInRange(5, 0, 10); // true diff --git a/lib/src/iterator/forOf.ts b/lib/src/iterator/forOf.ts index ba820c98..bee865e4 100644 --- a/lib/src/iterator/forOf.ts +++ b/lib/src/iterator/forOf.ts @@ -17,7 +17,7 @@ let _iterSymbol: ICachedValue; /** * Calls the provided `callbackFn` function once for each element in the iterator or iterator returned by - * the iterable and processed in the same order as returned by the iterator. As with the {@link arrForEach} + * the iterable and processed in the same order as returned by the iterator. As with the `arrForEach()` * you CAN stop / break the iteration by returning -1 from the`callbackFn` function. * * The order of processing is not reset if you add or remove elements to the iterator, the actual behavior diff --git a/lib/src/iterator/types.ts b/lib/src/iterator/types.ts index 4343c2fe..584e805f 100644 --- a/lib/src/iterator/types.ts +++ b/lib/src/iterator/types.ts @@ -40,7 +40,7 @@ export type IterPredicateCallbackFn = (value: T, index: number) => unknown; export type IterReduceCallbackFn = (previousValue: T | R, currentValue: T, currentIndex: number, iter: Iterator) => R; /** - * Callback signature for key selection in {@link arrToMap}. + * Callback signature for key selection in `arrToMap()`. * @since 0.15.0 * @group Array * @example @@ -51,7 +51,7 @@ export type IterReduceCallbackFn = (previousValue: T | R, currentValue export type ArrToMapKeySelectorFn = (value: T, index: number) => string | number; /** - * Callback signature for value selection in {@link arrToMap}. + * Callback signature for value selection in `arrToMap()`. * @since 0.15.0 * @group Array * @example diff --git a/lib/src/string/at.ts b/lib/src/string/at.ts index 25c86069..b4909f70 100644 --- a/lib/src/string/at.ts +++ b/lib/src/string/at.ts @@ -18,7 +18,7 @@ import { asString } from "./as_string"; * UTF-16 code unit located at the specified offset into the string. It accepts both positive and * negative integers: negative integers count back from the last string character. * - * This is the equivalent of `String.prototype.at()` and falls back to {@link polyStrAt} in + * This is the equivalent of `String.prototype.at()` and falls back to `polyStrAt()` in * environments where the native method is unavailable. * * @function diff --git a/lib/src/string/count.ts b/lib/src/string/count.ts index f504ede0..5a88ffec 100644 --- a/lib/src/string/count.ts +++ b/lib/src/string/count.ts @@ -26,7 +26,7 @@ import { strIndexOf } from "./index_of"; * if `null` or `undefined`, it is stringified (for example, to `"null"` or `"undefined"`). If the * resulting string is empty, `0` is returned. * @returns The number of non-overlapping substring occurrences. - * @throws {TypeError} If `value` is `null` or `undefined`. + * @throws `TypeError` if `value` is `null` or `undefined`. * @example * ```ts * strCount("hello hello", "hello"); // 2 diff --git a/lib/src/string/match_all.ts b/lib/src/string/match_all.ts index 6ef5659a..551e03b9 100644 --- a/lib/src/string/match_all.ts +++ b/lib/src/string/match_all.ts @@ -19,8 +19,8 @@ import { createIterableIterator } from "../iterator/create"; /** * The `strMatchAll()` method returns an iterator of all results matching a string against a - * regular expression, including capturing groups. Unlike {@link strMatch}, it returns every - * match in the string (not just the first) and each result includes full `RegExpExecArray` + * regular expression, including capturing groups. Unlike `String.prototype.match()`, it returns + * every match in the string (not just the first) and each result includes full `RegExpExecArray` * details: matched substrings, capture groups, the match `index`, and the original `input` string. * * If `matcher` is a `RegExp` it **must** have the global (`g`) flag set; a non-global `RegExp` diff --git a/lib/src/string/normalize_newlines.ts b/lib/src/string/normalize_newlines.ts index 45b77501..9b76648b 100644 --- a/lib/src/string/normalize_newlines.ts +++ b/lib/src/string/normalize_newlines.ts @@ -20,7 +20,7 @@ const _validNewlines = ["\n", "\r\n", "\r", "\n\r"]; * @group String * @group Conversion * @param value - The value containing line endings to normalize. - * @param newlineType - Optional target line ending. Supported values are "\n", "\r\n", "\r", and "\n\r". Defaults to "\n". + * @param newlineType - Optional target line ending. Supported values are `"\n"`, `"\r\n"`, `"\r"`, and `"\n\r"`. Defaults to `"\n"`. * @returns A string with normalized line endings. * @throws TypeError If value is null or undefined, or newlineType is not a supported newline string. */ diff --git a/lib/src/timer/microtask.ts b/lib/src/timer/microtask.ts index e798e4cf..646a4c83 100644 --- a/lib/src/timer/microtask.ts +++ b/lib/src/timer/microtask.ts @@ -45,7 +45,7 @@ export interface MicroTaskOptions { } /** - * Sets the default fallback behavior for {@link scheduleMicrotask} when + * Sets the default fallback behavior for `scheduleMicrotask()` when * `queueMicrotask` is not available. * * @since 0.15.0 @@ -85,7 +85,6 @@ export function setMicroTaskFallbackOptions(options?: MicroTaskOptions): void { * @group Timer * * @param callback - The callback to execute. - * @param args - Optional callback arguments to pass when the callback executes. * @param options - Optional per-call fallback options when `queueMicrotask` is unavailable. * @returns A handler that can be used to cancel or refresh the scheduled callback. * @example @@ -114,6 +113,28 @@ export function setMicroTaskFallbackOptions(options?: MicroTaskOptions): void { * } * }); * ``` + */ +export function scheduleMicrotask(callback: () => void, options?: MicroTaskOptions): ITimerHandler; + +/** + * Schedules a callback to run in the microtask queue, passing the provided `args` to the + * callback when it executes. + * + * It uses the native `queueMicrotask` when available, otherwise falls back to + * `Promise.resolve().then(...)`, and if `Promise` is unavailable it falls back to + * `scheduleTimeout(..., 0)`. + * Unlike standard microtasks, this helper returns a cancellable `ITimerHandler` + * so scheduled callbacks can be canceled before execution. + * This provides consistent microtask scheduling behavior across all supported runtimes, + * including Node.js, browsers, and web workers. + * + * @since 0.15.0 + * @group Timer + * + * @param callback - The callback to execute. + * @param args - The callback arguments to pass when the callback executes. + * @param options - Optional per-call fallback options when `queueMicrotask` is unavailable. + * @returns A handler that can be used to cancel or refresh the scheduled callback. * @example * ```ts * // Args only @@ -129,7 +150,6 @@ export function setMicroTaskFallbackOptions(options?: MicroTaskOptions): void { * }); * ``` */ -export function scheduleMicrotask(callback: () => void, options?: MicroTaskOptions): ITimerHandler; export function scheduleMicrotask(callback: (...args: TArgs) => void, args: TArgs, options?: MicroTaskOptions): ITimerHandler; export function scheduleMicrotask(callback: (...args: TArgs) => void, argsOrOptions?: TArgs | MicroTaskOptions, options?: MicroTaskOptions): ITimerHandler { let callbackArgs: TArgs | undefined; diff --git a/lib/src/timer/nextTick.ts b/lib/src/timer/nextTick.ts index 24ecb382..2ec1086e 100644 --- a/lib/src/timer/nextTick.ts +++ b/lib/src/timer/nextTick.ts @@ -7,7 +7,7 @@ */ import { isArray, isFunction, isStrictUndefined } from "../helpers/base"; -import { _getGlobalInstFn, getInst, getQueueMicrotask, isNode } from "../helpers/environment"; +import { _getGlobalInstFn, getInst, isNode } from "../helpers/environment"; import { ITimerHandler } from "./handler"; import { _createCancellableTask } from "./microtasks/cancellableTask"; import { _getProcessNextTickFn } from "./microtasks/processNextTick"; @@ -61,7 +61,7 @@ export interface NextTickOptions { export type ProcessNextTickFn = (callback: (...args: any[]) => void, ...args: any[]) => void; /** - * Sets the default fallback behavior for {@link scheduleNextTick} when + * Sets the default fallback behavior for `scheduleNextTick()` when * `process.nextTick` is not available. * * @since 0.15.0 @@ -146,7 +146,6 @@ export function hasProcessNextTick(): boolean { * @group Timer * * @param callback - The callback to execute. - * @param args - Optional callback arguments to pass when the callback executes. * @param options - Optional fallback behavior when native `process.nextTick` is not available. * @returns A handler that can be used to cancel or refresh the scheduled callback. * @example @@ -169,6 +168,30 @@ export function hasProcessNextTick(): boolean { * } * }); * ``` + */ +export function scheduleNextTick(callback: MicrotaskFn, options?: NextTickOptions): ITimerHandler; + +/** + * Schedules a callback to run using `process.nextTick` when available and otherwise uses + * queueMicrotask, a Promise-based fallback or finally a timer-backed queue, passing the provided + * `args` to the callback when it executes. + * + * When `scheduleFn` is provided, it is used before the Promise and timer-backed fallbacks, if + * queueMicrotask is available it is used before all fallbacks. + * When `useTimeout` is `true`, the timer-backed queue is used instead of the Promise fallback only + * when native `process.nextTick` and `queueMicrotask` are unavailable. + * `maxQueuedTasks` controls the fallback queue depth limit; when omitted the fallback queue uses + * the default limit (set via `setNextTickFallbackOptions`) or a Node-compatible default of 1000. + * Setting/passing `maxQueuedTasks` to `0` disables the limit (for fallbacks only, the native + * `process.nextTick` is not affected by this limit). + * + * @since 0.15.0 + * @group Timer + * + * @param callback - The callback to execute. + * @param args - The callback arguments to pass when the callback executes. + * @param options - Optional fallback behavior when native `process.nextTick` is not available. + * @returns A handler that can be used to cancel or refresh the scheduled callback. * @example * ```ts * // Args only @@ -184,7 +207,6 @@ export function hasProcessNextTick(): boolean { * }); * ``` */ -export function scheduleNextTick(callback: MicrotaskFn, options?: NextTickOptions): ITimerHandler; export function scheduleNextTick(callback: (...args: TArgs) => void, args: TArgs, options?: NextTickOptions): ITimerHandler; export function scheduleNextTick(callback: (...args: TArgs) => void, argsOrOptions?: TArgs | NextTickOptions, options?: NextTickOptions): ITimerHandler { let callbackArgs: TArgs | undefined; diff --git a/typedoc.json b/typedoc.json index 881ec311..b3a8ef1a 100644 --- a/typedoc.json +++ b/typedoc.json @@ -24,39 +24,5 @@ "compilerOptions": { "stripInternal": true, "skipLibCheck": true - }, - "blockTags": [ - "@defaultValue", - "@deprecated", - "@example", - "@param", - "@privateRemarks", - "@remarks", - "@returns", - "@see", - "@throws", - "@typeParam", - "@author", - "@callback", - "@category", - "@categoryDescription", - "@default", - "@document", - "@function", - "@group", - "@groupDescription", - "@import", - "@inheritDoc", - "@jsx", - "@license", - "@module", - "@prop", - "@property", - "@return", - "@satisfies", - "@template", - "@type", - "@typedef", - "@since" - ], + } }