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" - ], + } }