Merge branch 'main' into test/fake-timer

Author: miinhho

CHANGELOG.md

@@ -1,5 +1,21 @@
 # es-toolkit Changelog
 
+## Version v1.42.0
+
+Released on November 17th, 2025.
+
+- Added new async utilities: `filterAsync`, `flatMapAsync`, `forEachAsync`, `mapAsync`, `reduceAsync`, and `limitAsync` for handling asynchronous operations.
+- Exported `ThrottleOptions` and `DebounceOptions` interfaces for better type support.
+- Fixed `isFinite` to implement type predicate to narrow type to number.
+- Fixed `isSafeInteger` to implement type predicate to narrow type to number.
+- Fixed `omit` to prevent adding index properties to array-like objects.
+- Fixed `mergeWith` to remove unnecessary nullish coalescing for 100% branch coverage.
+- Fixed `compat/updateWith` to remove unreachable code and add prototype pollution test.
+- Updated documentation headings for consistency.
+- Improved test coverage for `compat/mergeWith`, `compat/unset`, `get`, `toMerged`, `mergeWith`, and `compat/intersectionBy` with additional edge cases and security tests.
+
+We sincerely thank @Debbl, @wo-o29, @raon0211, @Yeom-JinHo, @sukvvon, and @D-Sketon for their contributions. We appreciate your great efforts!
+
 ## Version v1.41.0
 
 Released on October 24th, 2025.

docs/ja/reference/array/filterAsync.md

@@ -0,0 +1,49 @@
+# filterAsync
+
+非同期条件関数を使用して配列をフィルタリングし、条件を満たす要素のみを含む新しい配列を返します。
+
+```typescript
+const filtered = await filterAsync(array, predicate);
+```
+
+## 参照
+
+### `filterAsync(array, predicate, options?)`
+
+API呼び出しやデータベースクエリなどの非同期操作で配列をフィルタリングする場合は、`filterAsync`を使用してください。通常の`filter`とは異なり、非同期条件関数をサポートし、`concurrency`オプションで並行実行数を制限できます。
+
+```typescript
+import { filterAsync } from 'es-toolkit/array';
+
+// APIでユーザーステータスを確認して、アクティブなユーザーのみをフィルタリングします。
+const users = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const activeUsers = await filterAsync(users, async user => {
+  return await checkUserStatus(user.id);
+});
+// 返り値：アクティブなユーザーのみを含む配列
+
+// 並行実行数を制限してサーバー負荷を軽減します。
+const numbers = [1, 2, 3, 4, 5];
+const evenNumbers = await filterAsync(numbers, async n => await isEvenAsync(n), { concurrency: 2 });
+// 最大2つの操作のみが同時に実行されます。
+```
+
+`concurrency`オプションは、外部API呼び出しを制限したり、システムリソースを効率的に管理したりするのに役立ちます。指定しない場合、すべての操作が同時に実行されます。
+
+```typescript
+import { filterAsync } from 'es-toolkit/array';
+
+// 最大3つのAPI呼び出しのみを同時に実行します。
+const items = await filterAsync(largeArray, async item => await validateItem(item), { concurrency: 3 });
+```
+
+#### パラメータ
+
+- `array` (`readonly T[]`)：フィルタリングする配列です。
+- `predicate` (`(item: T, index: number, array: readonly T[]) => Promise<boolean>`)：各要素をテストする非同期関数です。真と評価される値を返すと、その要素が結果に含まれます。
+- `options` (`FilterAsyncOptions`, オプショナル)：並行実行を制御するオプションです。
+  - `concurrency` (`number`, オプショナル)：同時に実行できる最大操作数です。指定しない場合、すべての操作が同時に実行されます。
+
+#### 戻り値
+
+(`Promise<T[]>`)：条件関数が真と評価される値を返した要素のみを含む新しい配列のPromiseを返します。

docs/ja/reference/array/flatMapAsync.md

@@ -0,0 +1,51 @@
+# flatMapAsync
+
+非同期関数を使用して配列の各要素を変換し、結果を1レベル平坦化して新しい配列を返します。
+
+```typescript
+const result = await flatMapAsync(array, callback);
+```
+
+## 参照
+
+### `flatMapAsync(array, callback, options?)`
+
+各要素が複数の値を返す非同期変換を実行する場合は、`flatMapAsync`を使用してください。`mapAsync`を呼び出した後に`flat()`を実行するのと同等ですが、より効率的です。
+
+```typescript
+import { flatMapAsync } from 'es-toolkit/array';
+
+// 各ユーザーの投稿を取得して1つの配列に結合します。
+const users = [{ id: 1 }, { id: 2 }];
+const allPosts = await flatMapAsync(users, async user => {
+  return await fetchUserPosts(user.id);
+});
+// 返り値：[post1, post2, post3, ...]（すべてのユーザーの投稿が1つの配列に）
+
+// 並行実行数を制限します。
+const numbers = [1, 2, 3];
+const results = await flatMapAsync(numbers, async n => await fetchRelatedItems(n), { concurrency: 2 });
+// 最大2つの操作のみが同時に実行されます。
+```
+
+各コールバック関数は配列を返す必要があり、返されたすべての配列が1つの配列にマージされます。`concurrency`オプションを使用すると、並行実行を制限してサーバー負荷を管理できます。
+
+```typescript
+import { flatMapAsync } from 'es-toolkit/array';
+
+// 各カテゴリーの商品リストを取得して1つの配列にします。
+const categories = ['electronics', 'books', 'clothing'];
+const products = await flatMapAsync(categories, async category => await fetchProducts(category), { concurrency: 2 });
+// 返り値：すべてのカテゴリーの商品を含む単一の配列
+```
+
+#### パラメータ
+
+- `array` (`readonly T[]`)：変換する配列です。
+- `callback` (`(item: T, index: number, array: readonly T[]) => Promise<R[]>`)：各要素を配列に変換する非同期関数です。
+- `options` (`FlatMapAsyncOptions`, オプショナル)：並行実行を制御するオプションです。
+  - `concurrency` (`number`, オプショナル)：同時に実行できる最大操作数です。指定しない場合、すべての操作が同時に実行されます。
+
+#### 戻り値
+
+(`Promise<R[]>`)：1レベル平坦化された変換値の配列のPromiseを返します。

docs/ja/reference/array/forEachAsync.md

@@ -0,0 +1,51 @@
+# forEachAsync
+
+配列の各要素に対して非同期関数を実行します。
+
+```typescript
+await forEachAsync(array, callback);
+```
+
+## 参照
+
+### `forEachAsync(array, callback, options?)`
+
+配列の各要素に対して副作用を伴う非同期操作を実行する場合は、`forEachAsync`を使用してください。通常の`forEach`とは異なり、すべての非同期操作が完了したときに解決されるPromiseを返します。
+
+```typescript
+import { forEachAsync } from 'es-toolkit/array';
+
+// すべてのユーザー情報を更新します。
+const users = [{ id: 1 }, { id: 2 }, { id: 3 }];
+await forEachAsync(users, async user => {
+  await updateUser(user.id);
+});
+// すべてのユーザー更新が完了しました。
+
+// 並行実行数を制限します。
+const items = [1, 2, 3, 4, 5];
+await forEachAsync(items, async item => await processItem(item), { concurrency: 2 });
+// 最大2つの項目のみが同時に処理されます。
+```
+
+`concurrency`オプションを使用すると、並行実行を制限してサーバーやデータベースへの負荷を制御できます。ログ記録、ファイルアップロード、データベース更新など、値を返さない操作に便利です。
+
+```typescript
+import { forEachAsync } from 'es-toolkit/array';
+
+// ファイルを順次アップロードします。
+const files = ['file1.txt', 'file2.txt', 'file3.txt'];
+await forEachAsync(files, async file => await uploadFile(file), { concurrency: 1 });
+// 一度に1つずつアップロードされます。
+```
+
+#### パラメータ
+
+- `array` (`readonly T[]`)：反復処理する配列です。
+- `callback` (`(item: T, index: number, array: readonly T[]) => Promise<void>`)：各要素に対して実行する非同期関数です。
+- `options` (`ForEachAsyncOptions`, オプショナル)：並行実行を制御するオプションです。
+  - `concurrency` (`number`, オプショナル)：同時に実行できる最大操作数です。指定しない場合、すべての操作が同時に実行されます。
+
+#### 戻り値
+
+(`Promise<void>`)：すべての操作が完了したときに解決されるPromiseを返します。

docs/ja/reference/array/limitAsync.md

@@ -0,0 +1,51 @@
+# limitAsync
+
+非同期関数の最大並行実行数を制限する新しい関数を作成します。
+
+```typescript
+const limitedFunc = limitAsync(asyncFunc, concurrency);
+```
+
+## 参照
+
+### `limitAsync(callback, concurrency)`
+
+複数回呼び出される非同期関数の並行実行数を制限したい場合は、`limitAsync`を使用してください。指定された数だけ同時に実行され、追加の呼び出しは実行中の操作が完了するまで待機します。
+
+```typescript
+import { limitAsync } from 'es-toolkit/array';
+
+// 最大3つのリクエストのみを同時に実行するように制限します。
+const limitedFetch = limitAsync(async url => {
+  return await fetch(url);
+}, 3);
+
+const urls = ['url1', 'url2', 'url3', 'url4', 'url5'];
+await Promise.all(urls.map(url => limitedFetch(url)));
+// 最初の3つが先に実行され、完了すると残りが実行されます。
+```
+
+外部API呼び出しやデータベースクエリなど、リソースを大量に使用する操作の負荷を制御するのに便利です。レート制限のあるAPIを使用する場合やサーバー負荷を管理する必要がある場合に特に効果的です。
+
+```typescript
+import { limitAsync } from 'es-toolkit/array';
+
+// 重い計算を最大2つずつ処理します。
+const processItem = async item => {
+  return await heavyComputation(item);
+};
+
+const limitedProcess = limitAsync(processItem, 2);
+const items = [1, 2, 3, 4, 5];
+await Promise.all(items.map(item => limitedProcess(item)));
+// 最大2つの項目のみが同時に処理されます。
+```
+
+#### パラメータ
+
+- `callback` (`F extends (...args: any[]) => Promise<any>`)：並行実行数を制限する非同期関数です。
+- `concurrency` (`number`)：同時に実行できる最大操作数です。
+
+#### 戻り値
+
+(`F`)：並行実行制限が適用された新しい関数を返します。元の関数と同じインターフェースを持ちます。

docs/ja/reference/array/mapAsync.md

@@ -0,0 +1,55 @@
+# mapAsync
+
+非同期関数を使用して配列の各要素を変換し、新しい配列を返します。
+
+```typescript
+const transformed = await mapAsync(array, callback);
+```
+
+## 参照
+
+### `mapAsync(array, callback, options?)`
+
+配列の各要素に対して非同期変換操作を実行する場合は、`mapAsync`を使用してください。API呼び出しやデータベースクエリなど、各要素を非同期的に処理する必要がある場合に便利です。
+
+```typescript
+import { mapAsync } from 'es-toolkit/array';
+
+// 各ユーザーの詳細情報を取得します。
+const users = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const userDetails = await mapAsync(users, async user => {
+  return await fetchUserDetails(user.id);
+});
+// 返り値：[{ id: 1, name: '...' }, { id: 2, name: '...' }, { id: 3, name: '...' }]
+
+// 並行実行数を制限します。
+const numbers = [1, 2, 3, 4, 5];
+const results = await mapAsync(numbers, async n => await slowOperation(n), { concurrency: 2 });
+// 最大2つの操作のみが同時に実行されます。
+```
+
+`concurrency`オプションを使用すると、並行実行を制限してサーバー負荷を制御したり、APIレート制限を守ったりできます。指定しない場合、すべての操作が同時に実行されます。
+
+```typescript
+import { mapAsync } from 'es-toolkit/array';
+
+// 大量の画像を変換しますが、サーバー負荷を考慮して並行処理数を制限します。
+const imageUrls = [...]; // 多くの画像URL
+const processedImages = await mapAsync(
+  imageUrls,
+  async (url) => await processImage(url),
+  { concurrency: 5 }
+);
+// 一度に最大5つの画像のみが処理されます。
+```
+
+#### パラメータ
+
+- `array` (`readonly T[]`)：変換する配列です。
+- `callback` (`(item: T, index: number, array: readonly T[]) => Promise<R>`)：各要素を変換する非同期関数です。
+- `options` (`MapAsyncOptions`, オプショナル)：並行実行を制御するオプションです。
+  - `concurrency` (`number`, オプショナル)：同時に実行できる最大操作数です。指定しない場合、すべての操作が同時に実行されます。
+
+#### 戻り値
+
+(`Promise<R[]>`)：変換された値で構成される新しい配列のPromiseを返します。

docs/ja/reference/array/reduceAsync.md

@@ -0,0 +1,78 @@
+# reduceAsync
+
+非同期リデューサー関数を使用して配列を単一の値に縮約します。
+
+```typescript
+const result = await reduceAsync(array, reducer, initialValue);
+```
+
+## 参照
+
+### `reduceAsync(array, reducer, initialValue)`
+
+各要素を順次処理して配列を1つの値に縮約する場合は、`reduceAsync`を使用してください。リデューサー関数は左から右へ各要素に順次適用され、前の呼び出しの累積結果を次の呼び出しに渡します。
+
+```typescript
+import { reduceAsync } from 'es-toolkit/array';
+
+// 各数値の非同期値を取得して合計します。
+const numbers = [1, 2, 3, 4, 5];
+const sum = await reduceAsync(numbers, async (acc, n) => acc + (await fetchValue(n)), 0);
+// 返り値：すべての取得値の合計
+
+// 配列をオブジェクトに変換します。
+const users = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const userMap = await reduceAsync(
+  users,
+  async (acc, user) => {
+    const details = await fetchUserDetails(user.id);
+    acc[user.id] = details;
+    return acc;
+  },
+  {} as Record<number, any>
+);
+// 返り値：{ 1: {...}, 2: {...}, 3: {...} }
+```
+
+他の非同期配列メソッドとは異なり、`reduceAsync`は各要素を順次処理する必要があるため、並行実行をサポートしていません。前のステップの結果が次のステップに必要だからです。
+
+#### パラメータ
+
+- `array` (`readonly T[]`)：縮約する配列です。
+- `reducer` (`(accumulator: U, currentValue: T, currentIndex: number, array: readonly T[]) => Promise<U>`)：各要素を処理する非同期関数です。累積値と現在の値を受け取り、新しい累積値を返します。
+- `initialValue` (`U`)：アキュムレーターの初期値です。
+
+#### 戻り値
+
+(`Promise<U>`)：最終的な累積値のPromiseを返します。
+
+---
+
+### `reduceAsync(array, reducer)`
+
+初期値なしで配列を縮約する場合、最初の要素が初期値として使用され、2番目の要素からリデューサー関数が適用されます。
+
+```typescript
+import { reduceAsync } from 'es-toolkit/array';
+
+// 初期値なしで合計を計算します。
+const numbers = [1, 2, 3, 4, 5];
+const sum = await reduceAsync(numbers, async (acc, n) => acc + n);
+// 返り値：15 (1 + 2 + 3 + 4 + 5)
+
+// 空の配列はundefinedを返します。
+const emptyArray: number[] = [];
+const result = await reduceAsync(emptyArray, async (acc, n) => acc + n);
+// 返り値：undefined
+```
+
+初期値なしで空の配列に対して`reduceAsync`を呼び出すと、`undefined`を返します。
+
+#### パラメータ
+
+- `array` (`readonly T[]`)：縮約する配列です。
+- `reducer` (`(accumulator: T, currentValue: T, currentIndex: number, array: readonly T[]) => Promise<T>`)：各要素を処理する非同期関数です。累積値と現在の値を受け取り、新しい累積値を返します。
+
+#### 戻り値
+
+(`Promise<T | undefined>`)：最終的な累積値のPromiseを返します。配列が空の場合は`undefined`を返します。

docs/ja/reference/error/AbortError.md

@@ -50,6 +50,6 @@ await fetchData(controller.signal); // AbortErrorをスロー
 
 - `message` (`string`, オプション): エラーメッセージです。デフォルト値は`'The operation was aborted'`です。
 
-### 戻り値
+#### 戻り値
 
 (`AbortError`): 中断された操作を表すエラーインスタンスを返します。`Error`を継承しており、`name`プロパティは`'AbortError'`です。

docs/ja/reference/error/TimeoutError.md

@@ -49,6 +49,6 @@ await fetchWithTimeout('https://example.com/api/slow');
 
 - `message` (`string`, オプション): エラーメッセージです。デフォルト値は`'The operation was timed out'`です。
 
-### 戻り値
+#### 戻り値
 
 (`TimeoutError`): タイムアウトした操作を表すエラーインスタンスを返します。`Error`を継承しており、`name`プロパティは`'TimeoutError'`です。