HN 日本語サマリー

← 一覧へ戻る
プログラミング

TypeScript向けのPromise対応debounceおよびthrottleライブラリを作成しました

I made a Promise-aware debounce and throttle library for TypeScript (github.com)

7 pointsby slimy744 コメント

要約

この記事では、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 があります。保留中の作業は、コンポーネントがアンマウントされるときにキャンセルされます。

比較

temporizelodashp-* packages
非同期関数のDebounce/Throttleすべての呼び出し元が結果を取得古い結果またはundefinedp-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が必要
インストールするパッケージ11、または関数ごとに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に記載されています。パッケージには何も含まれていません。