From 8483ad38fa662eda7149eed3a08b73d884a6a5c1 Mon Sep 17 00:00:00 2001 From: Alisue <lambdalisue@gmail.com> Date: Thu, 8 Aug 2024 12:36:23 +0900 Subject: [PATCH 1/2] docs: update jsdoc comments --- async/chain.ts | 7 ++++--- async/compact.ts | 2 +- async/compress.ts | 2 +- async/drop.ts | 5 ++--- async/enumerate.ts | 2 +- async/first.ts | 3 +-- async/for_each.ts | 1 + async/iter.ts | 2 +- async/take.ts | 7 +++---- async/take_while.ts | 2 +- async/uniq.ts | 2 +- async/zip.ts | 3 +++ chain.ts | 7 ++++--- compact.ts | 2 +- compress.ts | 2 +- drop.ts | 5 ++--- enumerate.ts | 2 +- first.ts | 3 +-- for_each.ts | 1 + iter.ts | 2 +- range.ts | 1 + take.ts | 7 +++---- take_while.ts | 2 +- to_array.ts | 2 ++ uniq.ts | 2 +- zip.ts | 3 +++ 26 files changed, 43 insertions(+), 36 deletions(-) diff --git a/async/chain.ts b/async/chain.ts index cf9e8ad..b1938b3 100644 --- a/async/chain.ts +++ b/async/chain.ts @@ -13,9 +13,7 @@ * console.log(await toArray(iter)); // [1, 2, 3, 4] * ``` * - * It supports chaining malformed iterables. - * - * @example + * @example With malformed iterables * ```ts * import { toArray } from "@core/iterutil/async/to-array"; * import { chain } from "@core/iterutil/async/chain"; @@ -36,6 +34,9 @@ export async function* chain< } } +/** + * @inner + */ export type Chain<T> = T extends readonly [] ? never : T extends readonly [Iterable<infer U>] ? U : T extends readonly [AsyncIterable<infer U>] ? U diff --git a/async/compact.ts b/async/compact.ts index 92ec059..d47a836 100644 --- a/async/compact.ts +++ b/async/compact.ts @@ -1,5 +1,5 @@ /** - * Removes all nullish values from an iterable. + * Removes all nullish (`null` or `undefined`) values from an iterable. * * @param iterable The iterable to compact. * @returns The compacted iterable. diff --git a/async/compress.ts b/async/compress.ts index 9d75e04..09378ae 100644 --- a/async/compress.ts +++ b/async/compress.ts @@ -1,5 +1,5 @@ /** - * Compress an iterable by selecting elements using a selector iterable. + * Compresses an iterable by selecting elements using a selector iterable. * * @param iterable The iterable to compress. * @param selectors The selectors to use. diff --git a/async/drop.ts b/async/drop.ts index 35246bc..20750e9 100644 --- a/async/drop.ts +++ b/async/drop.ts @@ -1,11 +1,10 @@ /** * 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 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 `limit` is less than 0 or non safe integer. * * @example * ```ts diff --git a/async/enumerate.ts b/async/enumerate.ts index c92e9ed..13aedb5 100644 --- a/async/enumerate.ts +++ b/async/enumerate.ts @@ -1,5 +1,5 @@ /** - * Enumerate an iterable. + * Enumerates an iterable. * * @param iterable The iterable to enumerate. * @param start The starting index. diff --git a/async/first.ts b/async/first.ts index 831c8aa..b2133c6 100644 --- a/async/first.ts +++ b/async/first.ts @@ -1,6 +1,5 @@ /** - * Returns the first element of an iterable. - * If the iterable is empty, returns `undefined`. + * Returns the first element of an iterable. 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. diff --git a/async/for_each.ts b/async/for_each.ts index f652294..407d422 100644 --- a/async/for_each.ts +++ b/async/for_each.ts @@ -7,6 +7,7 @@ * @example * ```ts * import { forEach } from "@core/iterutil/async/for-each"; + * * await forEach([1, 2, 3], console.log); * // 1 * // 2 diff --git a/async/iter.ts b/async/iter.ts index 633363b..2ffb7bc 100644 --- a/async/iter.ts +++ b/async/iter.ts @@ -1,5 +1,5 @@ /** - * Convert an iterable to an iterator. + * Converts an iterable to an iterator. * * @param iterable The iterable to convert. * @returns The iterator. diff --git a/async/take.ts b/async/take.ts index 5118d85..f2cca28 100644 --- a/async/take.ts +++ b/async/take.ts @@ -1,11 +1,10 @@ /** - * Take the first `limit` items from the iterable. - * - * It throws an error if `limit` is less than 0. + * Takes the first `limit` items from the iterable. * * @param iterable The iterable to take items from. - * @param limit The number of items to take. + * @param limit The number of items to take. It must be 0 or positive safe integer. * @returns The iterable with the first `limit` items taken. + * @throws {TakeLimitError} If `limit` is less than 0 or non safe integer. * * @example * ```ts diff --git a/async/take_while.ts b/async/take_while.ts index 07bd64f..5ee4bc6 100644 --- a/async/take_while.ts +++ b/async/take_while.ts @@ -1,5 +1,5 @@ /** - * Take elements from the iterable while the predicate is true. + * Takes elements from the iterable while the predicate is true. * * @param iterable The iterable to take elements from. * @param fn The predicate to take elements with. diff --git a/async/uniq.ts b/async/uniq.ts index cc6eb15..bc42f22 100644 --- a/async/uniq.ts +++ b/async/uniq.ts @@ -14,7 +14,7 @@ * console.log(await toArray(iter)); // [1, 2, 3] * ``` * - * @example + * @example With identify function * ```ts * import { toArray } from "@core/iterutil/async/to-array"; * import { uniq } from "@core/iterutil/async/uniq"; diff --git a/async/zip.ts b/async/zip.ts index 474758e..5980bf3 100644 --- a/async/zip.ts +++ b/async/zip.ts @@ -32,6 +32,9 @@ export async function* zip< } } +/** + * @inner + */ export type Zip<T extends (Iterable<unknown> | AsyncIterable<unknown>)[]> = { [P in keyof T]: T[P] extends Iterable<infer U> ? U : T[P] extends AsyncIterable<infer U> ? U diff --git a/chain.ts b/chain.ts index 2b601a1..00c7bf2 100644 --- a/chain.ts +++ b/chain.ts @@ -12,9 +12,7 @@ * console.log([...iter]); // [1, 2, 3, 4] * ``` * - * It supports chaining malformed iterables. - * - * @example + * @example With malformed iterables * ```ts * import { chain } from "@core/iterutil/chain"; * @@ -30,6 +28,9 @@ export function* chain<T extends Iterable<unknown>[]>( } } +/** + * @inner + */ export type Chain<T> = T extends readonly [] ? never : T extends readonly [Iterable<infer U>] ? U : T extends readonly [Iterable<infer U>, ...infer R] ? U | Chain<R> diff --git a/compact.ts b/compact.ts index ec17c38..a61c2fb 100644 --- a/compact.ts +++ b/compact.ts @@ -1,5 +1,5 @@ /** - * Removes all nullish values from an iterable. + * Removes all nullish (`null` or `undefined`) values from an iterable. * * @param iterable The iterable to compact. * @returns The compacted iterable. diff --git a/compress.ts b/compress.ts index d38fa79..28f3d37 100644 --- a/compress.ts +++ b/compress.ts @@ -1,5 +1,5 @@ /** - * Compress an iterable by selecting elements using a selector iterable. + * Compresses an iterable by selecting elements using a selector iterable. * * @param iterable The iterable to compress. * @param selectors The selectors to use. diff --git a/drop.ts b/drop.ts index beb24a5..426b1b2 100644 --- a/drop.ts +++ b/drop.ts @@ -1,11 +1,10 @@ /** * 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 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 `limit` is less than 0 or non safe integer. * * @example * ```ts diff --git a/enumerate.ts b/enumerate.ts index 5231333..69fdc77 100644 --- a/enumerate.ts +++ b/enumerate.ts @@ -1,5 +1,5 @@ /** - * Enumerate an iterable. + * Enumerates an iterable. * * @param iterable The iterable to enumerate. * @param start The starting index. diff --git a/first.ts b/first.ts index 41c3c81..894d76d 100644 --- a/first.ts +++ b/first.ts @@ -1,6 +1,5 @@ /** - * Returns the first element of an iterable. - * If the iterable is empty, returns `undefined`. + * Returns the first element of an iterable. 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. diff --git a/for_each.ts b/for_each.ts index 8673811..c75014f 100644 --- a/for_each.ts +++ b/for_each.ts @@ -7,6 +7,7 @@ * @example * ```ts * import { forEach } from "@core/iterutil/for-each"; + * * forEach([1, 2, 3], console.log); * // 1 * // 2 diff --git a/iter.ts b/iter.ts index 63e500c..4ac7d22 100644 --- a/iter.ts +++ b/iter.ts @@ -1,5 +1,5 @@ /** - * Convert an iterable to an iterator. + * Converts an iterable to an iterator. * * @param iterable The iterable to convert. * @returns The iterator. diff --git a/range.ts b/range.ts index a759c1c..3eaf920 100644 --- a/range.ts +++ b/range.ts @@ -3,6 +3,7 @@ * * @param stop The end of the range. * @returns The range of numbers. + * * @example * ```ts * import { range } from "@core/iterutil/range"; diff --git a/take.ts b/take.ts index 7cdd895..bc68c3d 100644 --- a/take.ts +++ b/take.ts @@ -1,11 +1,10 @@ /** - * Take the first `limit` items from the iterable. - * - * It throws an error if `limit` is less than 0. + * Takes the first `limit` items from the iterable. * * @param iterable The iterable to take items from. - * @param limit The number of items to take. + * @param limit The number of items to take. It must be 0 or positive safe integer. * @returns The iterable with the first `limit` items taken. + * @throws {TakeLimitError} If `limit` is less than 0 or non safe integer. * * @example * ```ts diff --git a/take_while.ts b/take_while.ts index 350ccd9..a789a71 100644 --- a/take_while.ts +++ b/take_while.ts @@ -1,5 +1,5 @@ /** - * Take elements from the iterable while the predicate is true. + * Takes elements from the iterable while the predicate is true. * * @param iterable The iterable to take elements from. * @param fn The predicate to take elements with. diff --git a/to_array.ts b/to_array.ts index 2d6f5e6..3274890 100644 --- a/to_array.ts +++ b/to_array.ts @@ -1,6 +1,8 @@ /** * Converts an iterable to an array. * + * Note that users should use `Array.from` directly. This function exists for consistency with `async/to-array.toArray`. + * * @param iterable The iterable to convert. * @returns The array. * diff --git a/uniq.ts b/uniq.ts index 6ac4939..4b24e93 100644 --- a/uniq.ts +++ b/uniq.ts @@ -13,7 +13,7 @@ * console.log([...iter]); // [1, 2, 3] * ``` * - * @example + * @example With identify function * ```ts * import { uniq } from "@core/iterutil/uniq"; * diff --git a/zip.ts b/zip.ts index 7927698..04e1cce 100644 --- a/zip.ts +++ b/zip.ts @@ -25,6 +25,9 @@ export function* zip<U extends Iterable<unknown>[]>( } } +/** + * @inner + */ export type Zip<T extends Iterable<unknown>[]> = { [P in keyof T]: T[P] extends Iterable<infer U> ? U : never; }; From e66d01ecffc70b866ec8411e49345a27a7177ca4 Mon Sep 17 00:00:00 2001 From: Alisue <lambdalisue@gmail.com> Date: Thu, 8 Aug 2024 12:40:36 +0900 Subject: [PATCH 2/2] docs: update README --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7fe2222..df7ab0d 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![codecov](https://codecov.io/github/jsr-core/iterutil/graph/badge.svg?token=pfbLRGU5AM)](https://codecov.io/github/jsr-core/iterutil) Iterator / AsyncIterator utility pack for JavaScript and TypeScript. Each module -is designed to work independently, avoiding internal interdependencies as much +is designed to work independently, avoiding internal inter-dependencies as much as possible. ## Usage @@ -16,7 +16,7 @@ both synchronous and asynchronous iterables (`Iterable` and `AsyncIterable`). ### chain -Chains multiple iterables or async iterables together. +Chains multiple iterables together. ```ts import { chain } from "@core/iterutil/chain"; @@ -54,7 +54,7 @@ console.log(await toArray(iter)); // [[1, 2], [3, 4], [5]] ### compact -Removes all nullish values from an iterable. +Removes all nullish (`null` or `undefined`) values from an iterable. ```ts import { compact } from "@core/iterutil/compact"; @@ -73,7 +73,7 @@ console.log(await toArray(iter)); // [1, 2, 3] ### compress -Compress an iterable by selecting elements using a selector iterable. +Compresses an iterable by selecting elements using a selector iterable. ```ts import { compress } from "@core/iterutil/compress"; @@ -164,7 +164,7 @@ console.log(await toArray(iter)); // [3, 4, 5] ### enumerate -Enumerate an iterable. +Enumerates an iterable. ```ts import { enumerate } from "@core/iterutil/enumerate"; @@ -318,7 +318,7 @@ await forEach([1, 2, 3], console.log); ### iter -Convert an iterable to an iterator. +Converts an iterable to an iterator. ```ts import { iter } from "@core/iterutil/iter"; @@ -431,7 +431,7 @@ console.log(odd); // [1, 3, 5] ### range -Generate a range of numbers. +Generates a range of numbers. ```ts import { range } from "@core/iterutil/range"; @@ -492,7 +492,7 @@ console.log(await some([1, 3, 5], (value) => value % 2 === 0)); // false ### take -Take the first `limit` items from the iterable. +Takes the first `limit` items from the iterable. ```ts import { take } from "@core/iterutil/take"; @@ -511,7 +511,7 @@ console.log(await toArray(iter)); // [1, 2] ### takeWhile -Take elements from the iterable while the predicate is true. +Takes elements from the iterable while the predicate is true. ```ts import { takeWhile } from "@core/iterutil/take-while";