TypeScript向けのPromise対応debounceおよびthrottleライブラリを作成しました
I made a Promise-aware debounce and throttle library for TypeScript (github.com)
要約
この記事では、TypeScript向けの新しいタイミングおよび並行処理ユーティリティライブラリ「temporize」を紹介しています。このライブラリは、debouncing、throttling、batching、retries、idle schedulingなどの機能を提供し、すべてのスケジューリングされた呼び出しが実際の関数の結果に対するPromiseを返すことが特徴です。ランタイム依存がなく、ESMとCommonJSの両方で利用可能です。
全文翻訳
タイトル: I made a Promise-aware debounce and throttle library for TypeScript
URL: https://github.com/nyvexis1/temporize
本文:
[画像: npm version] [画像: npm downloads] [画像: CI] [画像: bundle size]
Promiseを本当に理解するDebounce、Throttle、Retry、Timeout、Polling、およびConcurrency Limits。
p-debounce、p-limit、p-retry、p-timeoutを同じプロジェクトにインストールしたことがあるなら、temporizeはそれらすべてを1つのパッケージにまとめたものです。すべての関数は型を保持し、awaitできるPromiseを返し、キャンセル可能です。それぞれgzip圧縮後1kB未満で、依存関係はなく、importとrequireの両方で動作します。
npm install @alsoftworks/temporize
解決する問題
lodash.debounceは、Promiseが普及する前に書かれました。非同期関数をラップすると、結果を失います。
import debounce from "lodash.debounce";
const search = debounce(fetchResults, 300);
const results = await search("cats"); // undefined、または以前の呼び出しからの古い結果
temporizeを使用すると、各呼び出しは実際に実行された呼び出しの結果を取得し、エラーは期待どおりに拒否されます。
import { debounce } from "@alsoftworks/temporize";
const search = debounce(fetchResults, 300);
const results = await search("cats"); // fetchResultsが返すものとして型付けされる
内容物
| 関数 |
| --- | --- | --- |
| debounce | 呼び出しが停止するまで待ってから、一度実行する | 732 B |
| debounceAsync | デバウンスし、遅い呼び出しが重複した場合に何が起こるかを決定する | 984 B |
| throttle | ウィンドウごとに最大1回実行する | 769 B |
| throttlePromise | すべての呼び出しをキューに入れ、ウィンドウごとに1つ開始する(レート制限) | 588 B |
| rafThrottle | アニメーションフレームごとに最大1回実行する | 236 B |
| sample | 固定クロックで最新の値をレンダリングする | 332 B |
| batch | 呼び出しを収集し、1つのリクエストとして送信する | 541 B |
| concurrencyLimit | 同時に最大N個まで実行し、残りをキューに入れる | 525 B |
| retry | 指数バックオフとジッターで失敗をリトライする | 702 B |
| timeout | 時間のかかりすぎる呼び出しを諦める | 523 B |
| poll | 条件が真になるまで繰り返し呼び出す | 775 B |
| once | すべての呼び出し元間で1つの初期化を共有する | 491 B |
| idle | ブラウザがアイドル状態になるまで緊急でない作業を延期する | 242 B |
サイズは最小化およびgzip圧縮後で、ツリーシェイクされた場合の関数ごとに測定されます。また、ReactフックとVueコンポーザブルもあります。
クイックツアー
古いリクエストをキャンセルする。 新しい検索が開始されたら、進行中のリクエストを中止して、古い応答が新しい応答を上書きできないようにします。AbortSignalは自動的に渡され、呼び出す関数からは除外されます。
import { debounceAsync } from "@alsoftworks/temporize";
const loadUser = debounceAsync(
async (id: string, signal: AbortSignal) => {
const response = await fetch(`/api/users/${id}`, { signal });
return response.json() as Promise<User>;
},
200,
{ overlap: "cancel-previous" },
);
const user = await loadUser("user_123");
不安定なAPIをリトライするが、自己修正しないエラーの場合はすぐに停止します。
import { retry } from "@alsoftworks/temporize";
const getReport = retry(fetchReport, {
attempts: 4,
baseDelay: 250,
shouldRetry: (error) => !(error instanceof NotFoundError),
});
100個のファイルを一度に3つずつアップロードする:
import { concurrencyLimit } from "@alsoftworks/temporize";
const upload = concurrencyLimit(uploadFile, 3);
await Promise.all(files.map(upload));
2秒後に諦める、そして実際にリクエストを停止する:
import { timeout } from "@alsoftworks/temporize";
const fetchWithin2s = timeout(
(url: string, signal?: AbortSignal) => fetch(url, { signal }),
2_000,
);
バックグラウンドジョブの完了を待つ:
import { poll } from "@alsoftworks/temporize";
const waitForJob = poll(getJob, 500, {
until: (job) => job.status === "done",
timeout: 30_000,
});
多数の小さな呼び出しを1つのリクエストにまとめる:
import { batch } from "@alsoftworks/temporize";
const markRead = batch(async (calls: Array<[id: string]>) => {
await api.markRead(calls.map(([id]) => id));
}, 50);
markRead("a");
markRead("b"); // 両方とも単一の api.markRead(["a", "b"]) に集約される
待機するものはすべて .cancel() または AbortSignal でキャンセルでき、キャンセルされた呼び出しは TemporizeAbortError で拒否されるため、何も永遠にハングしません。 完全なAPIドキュメントにはすべてのオプションが記載されています。
ReactとVue
オプションのアダプターは独自のentry pointに配置されているため、コアはReactやVueのコードをロードしません。
import { useEffect, useState } from "react";
import { useDebouncedValue } from "@alsoftworks/temporize/react";
function Search() {
const [query, setQuery] = useState("");
const debouncedQuery = useDebouncedValue(query, 300);
useEffect(() => {
if (debouncedQuery) void fetch(`/api/search?q=${debouncedQuery}`);
}, [debouncedQuery]);
return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}
<script setup lang="ts">
import { ref } from "vue";
import { useDebouncedRef } from "@alsoftworks/temporize/vue";
const query = ref("");
const debouncedQuery = useDebouncedRef(query, 300);
</script>
両方のアダプターは useDebounce、useThrottle、useRafThrottle をエクスポートします。Reactには useDebouncedValue があり、Vueには useDebouncedRef があります。保留中の作業は、コンポーネントがアンマウントされるときにキャンセルされます。
比較
| temporize | lodash | p-* packages | |
|---|---|---|---|
| 非同期関数のDebounce/Throttle | すべての呼び出し元が結果を取得 | 古い結果またはundefined | p-debounce、p-throttle |
| 同時実行制限 | concurrencyLimit | — | p-limit |
| バックオフ付きリトライ | retry | — | p-retry |
| タイムアウト | timeout | — | p-timeout |
| 準備完了までポーリング | poll | — | p-wait-for |
| キャンセル | .cancel()とAbortSignal | .cancel() | パッケージによる |
importとrequire | 両方 | 両方 | importのみ。最新バージョンはNode 20または22が必要 |
| インストールするパッケージ | 1 | 1、または関数ごとに1 | 関数ごとに1 |
代替手段に公平を期すために:
- lodashは、結果が必要ない場合はより高速です。 temporizeは呼び出しごとにPromiseを作成します。スクロールハンドラのようなホットパスでは、
rafThrottleはそうせず、通常のlodash.throttleも問題ありません。 p-throttleは、間隔ごとにN回の呼び出しを許可できます。throttlePromiseは、ウィンドウごとに1回の呼び出しを開始します。p-retryとp-limitにはより多くの設定があります(各失敗試行時のフックや実行時の制限変更など)。temporizeはAPIを小さく保ちます。- DataLoaderは、各呼び出し元に独自の結果を与えます。 temporizeの
batchでは、バッチ内のすべての呼び出し元が同じ結果を取得します。
スコープ
temporizeは、コードがいつ、どのくらいの頻度で、どのくらいの時間実行されるかだけを扱います。配列、オブジェクト、文字列ヘルパーを拡張することはありません。これは意図的です。
貢献
バグレポートとプルリクエストを歓迎します。セットアップとチェックについてはCONTRIBUTING.mdを、各リリースでの変更点についてはCHANGELOG.mdを参照してください。
ライセンス
MIT。 LICENSEを参照してください。開発およびベンチマークの参照はTHIRD_PARTY_NOTICES.mdに記載されています。パッケージには何も含まれていません。