RxJSのdebounceTimeとswitchMapの順序を通信量からレビューする

入力欄の値で候補を取得する鎖は、debounceTime と switchMap の2つで組む。この2つの順序は読み味の違いではなく、サーバーへ出る通信の本数の違いである。7文字を80ms間隔で打ち込んだときの実測を先に置く。

rxjs 7.8.2 / 250ms で返る取得を7文字ぶん打った場合
debounceTime(300) → switchMap : 発行した通信 1 / 完了 1 / 出力 ["angularの結果"]
switchMap → debounceTime(300) : 発行した通信 7 / 完了 1 / 出力 ["angularの結果"]

どちらも画面に出るのは最後の結果1つで、動作として壊れていない。違いは、下の形がサーバーへ7本を投げて6本を途中で切っている点である。レビューでこの順序を見る理由は、出力が同じなので動かして気付けないことにある。

逆順で7本が出る理由

switchMap は、新しい値が来たときに前の内部 Observable の購読を解除する。鎖の上流に switchMap を置くと、間引きの対象は通信の結果になる。打鍵ごとに switchMap が内部の取得を購読し、次の打鍵で解除する。解除は要求の送信を取り消すが、送信そのものは済んでいる。

上の実測で 完了 が1になっているのが、解除された6本である。HttpClient を Fetch 既定で使っている場合、解除は AbortController 経由で要求の中断として伝わるが、サーバーが受け取ったあとであれば処理は進む。購読解除がどこまで止めるかはRxJSのswitchMapが実際には何を止めないのかをレビューで確認するに整理した。

間引きを先に置くと、打鍵の途中の値は switchMap まで届かない。debounceTime は値を溜めてから1つだけ下流へ渡すためである。実装では、最初の値でタイマーを1つ立て、以降は値と時刻を上書きしていく。タイマーが起きたときに最後の値の時刻から 300ms 経っていなければ、差分だけ再設定する。

rxjs 7.8.2 の debounceTime(抜粋)
function emitWhenIdle(this: SchedulerAction<unknown>) {
  const targetTime = lastTime! + dueTime;
  const now = scheduler.now();
  if (now < targetTime) {
    activeTask = this.schedule(undefined, targetTime - now);
    subscriber.add(activeTask);
    return;
  }
  emit();
}

打鍵ごとにタイマーを捨てて立て直すのではなく、起きたときに残り時間ぶん先へ送り直す作りである。値を1つも落とさずに保持するのは最後の値だけなので、間引かれた打鍵は下流から見えない。

distinctUntilChangedを置く位置

間引きの前後どちらに distinctUntilChanged を置くかでも、通信の本数が変わる。1文字消して打ち直し、結果として同じ語に戻る操作で差が出る。

'n' → 'ng' → 'n' → 'ng' と打ち直した場合
debounceTime → distinctUntilChanged → switchMap : 発行した通信 1 / 出力 ["ngの結果"]
distinctUntilChanged → debounceTime → switchMap : 発行した通信 2 / 出力 ["ngの結果","ngの結果"]

下の形は、間引きの前に重複を落としている。'ng' の次に 'n' が来ているので連続した重複ではなく、どちらも通る。間引きを経た後に比べると、同じ語で2回取得することになる。打ち直しが日常的に起きる入力欄では、distinctUntilChanged を間引きの後ろに置く。

比較の既定は === である。

rxjs 7.8.2 の distinctUntilChanged(抜粋)
comparator = comparator ?? defaultCompare;
// …
function defaultCompare(a: any, b: any) {
  return a === b;
}

検索語だけを流している鎖では文字列の比較になるので問題は出ない。語とページ番号をまとめたオブジェクトを流している鎖では、毎回別の参照になるため何も落ちない。

{ q: 'ng', page: 1 } を2回流した結果
["{\"q\":\"ng\",\"page\":1}","{\"q\":\"ng\",\"page\":1}"]

オブジェクトを流す鎖には、比較関数か keySelector を渡す。どちらでも落とせるが、比較したい項目が増えたときに書き換える位置が1つになるのは keySelector の側である。

Comment
@Reviewer: この鎖は `{ q, page }` を `distinctUntilChanged()` に通していますが、既定の比較は `===` なので、毎回新しいオブジェクトになって重複が落ちません。`distinctUntilChanged((a, b) => a.q === b.q && a.page === b.page)` か、`keySelector` で比較用のキーを作る形に変えてください。

画面を離れた直後に1本だけ出る経路

debounceTime は、上流が complete したときに保留中の値を出す。実装の complete 側に emit() がある。

rxjs 7.8.2 の debounceTime(complete の扱い)
() => {
  // Source completed.
  // Emit any pending debounced values then complete
  emit();
  subscriber.complete();
},

takeUntil は通知が来た時点で下流へ complete を流すので、takeUntil を debounceTime より上流に置くと、画面を離れた瞬間に保留中の値が下流へ出る。switchMap はその値で取得を1本始める。

入力の50ms後に停止の通知を出した場合
takeUntil を先頭に置く : 発行した通信 1 / 出力 ["angの結果"]
takeUntil を末尾に置く : 発行した通信 0 / 出力 []

末尾に置いた形で0本になるのは、takeUntil が上流を購読解除するためである。解除のときに走るのは debounceTime の後片付け(lastValue = activeTask = null)で、保留中の値は捨てられる。

takeUntilDestroyed() も中身は takeUntil である。

@angular/core 22.2.1 の rxjs-interop(抜粋)
return source => {
  return source.pipe(takeUntil(destroyed$));
};

したがって、takeUntilDestroyed() を debounceTime より前に書いた鎖は、コンポーネントが破棄される瞬間に取得を1本出し、その結果を購読者へ渡す。subscribe の中で signal を更新しているなら、破棄後に書き込みが走る。takeUntilDestroyed() は鎖の末尾に置く。pipe の途中に挟まっている箇所は、挟まった理由(別の目的で complete を期待している、など)を確かめる。

Comment
@Reviewer: `takeUntilDestroyed()` が `debounceTime(300)` より前にあります。この位置だと破棄のときに complete が流れて、`debounceTime` が保留中の値を1つ出すため、画面を離れた直後に取得が1本走ります(`debounceTime` は complete 時に保留値を emit する実装です)。`pipe` の末尾へ移してください。

signal側で間引く場合の違い

Angular 22 には signal を間引く debounced() がある(experimental)。返るのは Resource で、待っている間の状態が読める。

@angular/core 22.2.1 の型
declare function debounced<T>(source: () => T, wait: NoInfer<DebounceTimer<T>>, options?: NoInfer<DebouncedOptions<T>>): Resource<T>;

300ms を指定して、100ms間隔で3文字を入れた場合の状態の推移が次になる。

TestBed 上で debounced(() => q(), 300) を動かした結果
初期                       status=resolved value="" isLoading=false
a を入力した直後           status=loading  value="" isLoading=true
100ms後に an               status=loading  value="" isLoading=true
さらに100ms後に ang        status=loading  value="" isLoading=true
最後の入力から350ms後      status=resolved value="ang" isLoading=false
同じ値を入れ直した         status=resolved value="ang" isLoading=false

待っている間、value() は前の値のままである。この性質から、resource({ params: () => debouncedQuery.value() }) のように繋ぐと、取得は間引かれた値だけで起きる。RxJS の鎖で debounceTime を switchMap の前に置いた形と同じ結果になる。

鎖との違いは2つある。1つは、間引きの最中であることが isLoading() として読めることである。RxJS の鎖で同じ表示を出すには、入力のイベント側で旗を立てて結果の到着で降ろす処理を別に書く。もう1つは、破棄の扱いである。debounced() は DestroyRef.onDestroy で待機中のタイマーを捨てるので、前節の「破棄の瞬間に1本出る」経路が無い。

@angular/core 22.2.1 の debounced(破棄の扱い)
injector.get(DestroyRef).onDestroy(() => {
  cancelTimer();
  active = undefined;
});

同じ値を入れ直したときに待ち直さないのは、effect の中で待機中の値(pendingValue)と比較しているためである。比較には options.equal が使われ、既定は Object.is である。オブジェクトを間引く場合に equal を渡す判断は、RxJS 側で distinctUntilChanged に比較関数を渡す判断と同じになる。

experimental の API なので、既存の鎖を書き換える理由にはならない。新しく書く画面で、入力から取得までを signal で通すなら候補に入る。取得そのものを resource で書くか HttpClient の鎖で書くかの判断はAngularのhttpResourceとHttpClientの手組みをどちらで書くかにまとめた。

間引きの値をどう決めるか

debounceTime の引数は、打鍵の速さと取得の応答時間の両方から決まる。打鍵の間隔より短ければ毎回通信が出るので間引きにならず、長すぎれば入力を止めてから候補が出るまでの間が空く。レビューで数値そのものを議論する材料は少ないが、次の2点は差分から確かめられる。

1つは、値がどこで決まっているかである。鎖の中に直接書かれた 300 は、画面ごとに別の値へ散りやすい。取得の性質(候補の一覧か、全文検索か)ごとに定数へ寄せてあれば、後から測って変えられる。

もう1つは、待っている間の表示である。間引きの待ち時間は、利用者から見れば応答時間に足される。待ち時間ぶんは何も起きないので、入力してから候補が出るまでの間に表示が変わらない作りだと、反応していないように見える。debounced() の isLoading() か、鎖の側で立てた旗で、待機中の表示を決めてあるかを見る。

レビュー観点チェックリスト

間引きと取得の順序を確かめる項目
  • debounceTime が switchMap より上流にあるか(逆順だと打鍵ごとに通信が出る)
  • 逆順になっている鎖で、通信の本数を実測して確かめたか
  • distinctUntilChanged が debounceTime より下流にあるか(打ち直しで同じ語に戻る操作を落とせるか)
  • distinctUntilChanged にオブジェクトを流している箇所で、比較関数か keySelector を渡しているか
  • takeUntilDestroyed() が pipe の末尾にあるか(debounceTime より前だと破棄時に1本出る)
  • 破棄時に出た結果を subscribe の中で signal へ書いていないか
  • 間引きの値が鎖の中に直接書かれていないか
  • 待機中の表示(isLoading() か同等の旗)が決まっているか
  • 取得の結果を捨てる作りになっている箇所で、switchMap 以外の高階 Operator が必要でないか
  • signal で入力から取得まで通す画面で、debounced() の experimental の扱いを把握しているか
  • debounced() にオブジェクトを渡している箇所で、equal を指定しているか

おわりに

debounceTime を switchMap より上流に置けば、間引かれた打鍵の通信は起きない。逆順にすると打鍵ごとに通信が出て、結果だけが間引かれる。画面の出力は同じなので、動かして気付く種類の違いではない。

distinctUntilChanged は間引きの後ろに置く。前に置くと、打ち直して同じ語に戻る操作が重複として落ちない。既定の比較は === なので、オブジェクトを流している鎖では比較関数を渡す。

debounceTime は上流の complete で保留中の値を出す。takeUntilDestroyed() を debounceTime より前に置いた鎖は、破棄の瞬間に取得を1本出す。末尾に置けば購読解除になり、保留中の値は捨てられる。時間系 Operator の観点の全体はAngular 22のRxJS運用と購読の寿命をレビューする100観点の「時間系 Operator」の群にある。