From ededaefe5b226553832497f92d68e912b21f4b21 Mon Sep 17 00:00:00 2001 From: Alisue Date: Thu, 8 Aug 2024 11:33:57 +0900 Subject: [PATCH] chore: WIP --- chain.ts | 5 ++--- chunked.ts | 7 ++++--- compact.ts | 7 +++++-- compress.ts | 7 +++++-- count.ts | 6 ++++-- cycle.ts | 4 +++- drop.ts | 11 +++++++---- drop_while.ts | 10 +++++++--- enumerate.ts | 8 ++++++-- every.ts | 6 ++++-- filter.ts | 9 +++++++-- find.ts | 13 ++++++++----- first.ts | 9 ++++++--- flat_map.ts | 4 ++-- take.ts | 9 ++++----- 15 files changed, 74 insertions(+), 41 deletions(-) diff --git a/chain.ts b/chain.ts index 2b601a1..f5009f6 100644 --- a/chain.ts +++ b/chain.ts @@ -1,8 +1,9 @@ /** * Chains multiple iterables together. * - * @param iterables The iterables to chain. + * @param iterables - The iterables to chain. * @returns The chained iterable. + * @see {@link module:iterutil/async/chain.chain} for the asynchronous version. * * @example * ```ts @@ -12,8 +13,6 @@ * console.log([...iter]); // [1, 2, 3, 4] * ``` * - * It supports chaining malformed iterables. - * * @example * ```ts * import { chain } from "@core/iterutil/chain"; diff --git a/chunked.ts b/chunked.ts index cc156bd..41f952d 100644 --- a/chunked.ts +++ b/chunked.ts @@ -1,9 +1,10 @@ /** * Chunks an iterable into arrays of a given size. * - * @param iterable The iterable to chunk. - * @param size The size of each chunk. - * @returns The chunked iterable. + * @param iterable - The iterable to chunk. + * @param size - The size of each chunk. + * @return The chunked iterable. + * @see {@link module:iterutil/async/chunked.chunked} for the asynchronous version. * * @example * ```ts diff --git a/compact.ts b/compact.ts index ec17c38..0278f84 100644 --- a/compact.ts +++ b/compact.ts @@ -1,8 +1,11 @@ /** - * Removes all nullish values from an iterable. + * Removes all nullish ({@codelink null} or {@codelink undefined}) values from an iterable. * - * @param iterable The iterable to compact. + * @param iterable - The iterable to compact. * @returns The compacted iterable. + * @see {@link module:iterutil/async/compact.compact} for the asynchronous version. + * @see {@link module:iterutil/compress.compress} to select elements based on a selector iterable. + * @see {@link module:iterutil/filter.filter} to remove values based on a predicate. * * @example * ```ts diff --git a/compress.ts b/compress.ts index d38fa79..08982e7 100644 --- a/compress.ts +++ b/compress.ts @@ -1,9 +1,12 @@ /** * Compress an iterable by selecting elements using a selector iterable. * - * @param iterable The iterable to compress. - * @param selectors The selectors to use. + * @param iterable - The iterable to compress. + * @param selectors - The selectors to use. * @returns The compressed iterable. + * @see {@link module:iterutil/async/compress.compress} for the asynchronous version. + * @see {@link module:iterutil/compact.compact} to remove nullish values from an iterable. + * @see {@link module:iterutil/filter.filter} to remove values based on a predicate. * * @example * ```ts diff --git a/count.ts b/count.ts index e01d18f..59adf8c 100644 --- a/count.ts +++ b/count.ts @@ -1,9 +1,11 @@ /** * Generates an infinite sequence of numbers starting from `start` with a step of `step`. * - * @param start The number to start the sequence from. - * @param step The step between each number in the sequence. + * @param - start The number to start the sequence from. + * @param - step The step between each number in the sequence. * @returns The count iterable. + * @see {@link module:iterutil/take.take} to take a specific number of elements from the iterable. + * @see {@link module:iterutil/range.range} for a finite version of this function. * * @example * ```ts diff --git a/cycle.ts b/cycle.ts index d9b3b33..c304de9 100644 --- a/cycle.ts +++ b/cycle.ts @@ -1,8 +1,10 @@ /** * Returns an infinite iterable that cycles through the given iterable. * - * @param iterable The iterable to cycle. + * @param iterable - The iterable to cycle. * @returns The cycled iterable. + * @see {@link module:iterutil/async/cycle.cycle} for the asynchronous version. + * @see {@link module:iterutil/take.take} to take a specific number of elements from the iterable. * * @example * ```ts diff --git a/drop.ts b/drop.ts index beb24a5..625c042 100644 --- a/drop.ts +++ b/drop.ts @@ -1,11 +1,14 @@ /** * Drops the first `limit` items from the iterable. * - * It throws an error if `limit` is less than 0. - * - * @param iterable The iterable to drop items from. - * @param limit The number of items to drop. + * @param iterable - The iterable to drop items from. + * @param limit - The number of items to drop. It must be 0 or positive safe integer. * @returns The iterable with the first `limit` items dropped. + * @throws {DropLimitError} If the limit is not a safe integer or is negative. + * @see {@link module:iterutil/async/drop.drop} for the asynchronous version. + * @see {@link module:iterutil/drop-while.dropWhile} to drop elements while a predicate is true. + * @see {@link module:iterutil/take.take} to take a specific number of elements from the iterable. + * @see {@link module:iterutil/take-while.takeWhile} to take elements while a predicate is true. * * @example * ```ts diff --git a/drop_while.ts b/drop_while.ts index 1a7b5a9..598697f 100644 --- a/drop_while.ts +++ b/drop_while.ts @@ -1,12 +1,16 @@ /** - * Drops elements from the iterable while the predicate returns true. + * Drops elements from the iterable while the predicate function returns true. * * The first element that does not match the predicate is included in the output. * If the predicate never returns false, the output will be an empty iterable. * - * @param iterable The iterable to drop elements from. - * @param fn The predicate function to drop elements with. + * @param iterable - The iterable to drop elements from. + * @param fn - The predicate function to drop elements with. * @returns The iterable with elements dropped while the predicate returns true. + * @see {@link module:iterutil/async/drop-while.dropWhile} for the asynchronous version. + * @see {@link module:iterutil/drop.drop} to drop a specific number of elements from the iterable. + * @see {@link module:iterutil/take.take} to take a specific number of elements from the iterable. + * @see {@link module:iterutil/take-while.takeWhile} to take elements while a predicate is true. * * @example * ```ts diff --git a/enumerate.ts b/enumerate.ts index 5231333..0f38169 100644 --- a/enumerate.ts +++ b/enumerate.ts @@ -1,9 +1,13 @@ /** * Enumerate an iterable. * - * @param iterable The iterable to enumerate. - * @param start The starting index. + * @param iterable - The iterable to enumerate. + * @param start - The starting index. * @returns An iterable of index-value pairs. + * @see {@link module:iterutil/async/enumerate.enumerate} for the asynchronous version. + * @see {@link module:iterutil/zipped.zipped} to zip multiple iterables together. + * @see {@link module:iterutil/count.count} to generate an infinite sequence of numbers. + * @see {@link module:iterutil/range.range} to generate a finite sequence of numbers. * * @example * ```ts diff --git a/every.ts b/every.ts index b3ed7e4..aefc3a9 100644 --- a/every.ts +++ b/every.ts @@ -1,9 +1,11 @@ /** * Returns true if every element in the iterable satisfies the provided testing function. * - * @param iterable The iterable to test. - * @param fn The function to test with. + * @param iterable - The iterable to test. + * @param fn - The function to test with. * @returns True if every element in the iterable satisfies the provided testing function, otherwise false. + * @see {@link module:iterutil/async/every.every} for the asynchronous version. + * @see {@link module:iterutil/some.some} to test if any element satisfies the testing function. * * @example * ```ts diff --git a/filter.ts b/filter.ts index 277f166..6bcf96e 100644 --- a/filter.ts +++ b/filter.ts @@ -1,9 +1,14 @@ /** * Filters an iterable based on a function. * - * @params iterable The iterable to filter. - * @params fn The function to filter with. + * @params iterable - The iterable to filter. + * @params fn - The function to filter with. * @returns The filtered iterable. + * @see {@link module:iterutil/async/filter.filter} for the asynchronous version. + * @see {@link module:iterutil/compact.compact} to remove nullish values. + * @see {@link module:iterutil/compress.compress} to select elements based on a selector iterable. + * @see {@link module:iterutil/map.map} to transform values. + * @see {@link module:iterutil/reduce.reduce} to reduce values. * * @example * ```ts diff --git a/find.ts b/find.ts index 643ca6d..b88a421 100644 --- a/find.ts +++ b/find.ts @@ -1,10 +1,13 @@ /** - * Returns the first element in the iterable that satisfies the provided - * testing function. Otherwise, undefined is returned. + * Returns the first element in the iterable that satisfies the provided testing function. + * Otherwise, undefined is returned. * - * @param iterable The iterable to search. - * @param fn The function to test with. - * @returns The first element that satisfies the provided testing function. + * @param iterable - The iterable to search. + * @param fn - The function to test with. + * @returns The first element that satisfies the provided testing function or undefined. + * @see {@link module:iterutil/async/find.find} for the asynchronous version. + * @see {@link module:iterutil/first.first} to get the first element of an iterable. + * @see {@link module:iterutil/last.last} to get the last element of an iterable. * * @example * ```ts diff --git a/first.ts b/first.ts index 41c3c81..3861ba9 100644 --- a/first.ts +++ b/first.ts @@ -1,9 +1,12 @@ /** * Returns the first element of an iterable. - * If the iterable is empty, returns `undefined`. + * If the iterable is empty, returns undefined. * - * @param iterable The iterable to get the first element from. - * @returns The first element of the iterable, or `undefined` if the iterable is empty. + * @param iterable - The iterable to get the first element from. + * @returns The first element of the iterable, or undefined if the iterable is empty. + * @see {@link module:iterutil/async/first.first} for the asynchronous version. + * @see {@link module:iterutil/find.find} to find the first element that satisfies a predicate. + * @see {@link module:iterutil/last.last} to get the last element of an iterable. * * @example * ```ts diff --git a/flat_map.ts b/flat_map.ts index 5d35468..6b8eba7 100644 --- a/flat_map.ts +++ b/flat_map.ts @@ -1,8 +1,8 @@ /** * Maps each value in an iterable to an iterable, then flattens the result. * - * @param iterable The iterable to flat map. - * @param fn The function to map with. + * @param iterable - The iterable to flat map. + * @param fn - The function to map with. * @returns The flat mapped iterable. * * @example diff --git a/take.ts b/take.ts index 7cdd895..203e0f6 100644 --- a/take.ts +++ b/take.ts @@ -1,11 +1,10 @@ /** - * Take the first `limit` items from the iterable. + * Takes the first `limit` items from the iterable. * - * It throws an error if `limit` is less than 0. - * - * @param iterable The iterable to take items from. - * @param limit The number of items to take. + * @param iterable - The iterable to take items from. + * @param limit - The number of items to drop. It must be 0 or positive safe integer. * @returns The iterable with the first `limit` items taken. + * @throws {TakeLimitError} If the limit is not a safe integer or is negative. * * @example * ```ts