feat(core): allow debouncing signals

mmalerba · web-flow · commit b918beda323e · 2026-03-09T13:21:52.000-07:00
Adds a utility `debounced` to create a debounced version of a signal,
represented as a `Resource`. The resource's value contained the
debounced value of the signal, while its status (`resolved`, `loading`,
or `error`) indicates if the value is settled, if there is a value
currently pending debounce, or if the source signal threw an error.
diff --git a/goldens/public-api/core/errors.api.md b/goldens/public-api/core/errors.api.md
@@ -94,6 +94,8 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     INVALID_MULTI_PROVIDER = -209,
     // (undocumented)
+    INVALID_RESOURCE_CREATION_IN_PARAMS = 992,
+    // (undocumented)
     INVALID_SET_INPUT_CALL = 317,
     // (undocumented)
     INVALID_SKIP_HYDRATION_HOST = -504,
diff --git a/goldens/public-api/core/index.api.md b/goldens/public-api/core/index.api.md
@@ -499,6 +499,15 @@ export const CSP_NONCE: InjectionToken<string | null>;
 // @public
 export const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata;
 
+// @public
+export function debounced<T>(source: () => T, wait: NoInfer<number | ((value: T, lastValue: ResourceSnapshot<T>) => Promise<void> | void)>, options?: NoInfer<DebouncedOptions<T>>): Resource<T>;
+
+// @public
+export interface DebouncedOptions<T> {
+    equal?: ValueEqualityFn<T>;
+    injector?: Injector;
+}
+
 // @public (undocumented)
 export class DebugElement extends DebugNode {
     constructor(nativeNode: Element);
diff --git a/packages/core/src/errors.ts b/packages/core/src/errors.ts
@@ -157,6 +157,7 @@ export const enum RuntimeErrorCode {
   // resource() API errors
   MUST_PROVIDE_STREAM_OPTION = 990,
   RESOURCE_COMPLETED_BEFORE_PRODUCING_VALUE = 991,
+  INVALID_RESOURCE_CREATION_IN_PARAMS = 992,
 
   // Upper bounds for core runtime errors is 999
 }
diff --git a/packages/core/src/resource/api.ts b/packages/core/src/resource/api.ts
@@ -297,3 +297,11 @@ export type ResourceSnapshot<T> =
   | {readonly status: 'loading' | 'reloading'; readonly value: T}
   | {readonly status: 'resolved' | 'local'; readonly value: T}
   | {readonly status: 'error'; readonly error: Error};
+
+/** Options for `debounced`. */
+export interface DebouncedOptions<T> {
+  /** The `Injector` to use for the debounced resource. */
+  injector?: Injector;
+  /** The equality function to use for comparing values. */
+  equal?: ValueEqualityFn<T>;
+}
diff --git a/packages/core/src/resource/debounce.ts b/packages/core/src/resource/debounce.ts
@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {assertInInjectionContext, inject, Injector} from '../di';
+import {DestroyRef} from '../linker';
+import {effect} from '../render3/reactivity/effect';
+import {signal} from '../render3/reactivity/signal';
+import {untracked} from '../render3/reactivity/untracked';
+import {Resource, ResourceSnapshot, type DebouncedOptions} from './api';
+import {resourceFromSnapshots} from './from_snapshots';
+import {
+  invalidResourceCreationInParams,
+  isInParamsFunction,
+  rethrowFatalErrors,
+  setInParamsFunction,
+} from './resource';
+
+/**
+ * Creates a resource representing a debounced version of the source signal.
+ *
+ * @param source The source signal to debounce.
+ * @param wait The amount of time to wait before calling the source signal, or a function that
+ *   returns a promise that resolves when the debounced value should be updated.
+ * @param options The options to use for the debounced signal.
+ * @returns A resource representing the debounced signal.
+ * @experimental 22.0
+ */
+export function debounced<T>(
+  source: () => T,
+  wait: NoInfer<number | ((value: T, lastValue: ResourceSnapshot<T>) => Promise<void> | void)>,
+  options?: NoInfer<DebouncedOptions<T>>,
+): Resource<T> {
+  if (isInParamsFunction()) {
+    throw invalidResourceCreationInParams();
+  }
+  if (ngDevMode && !options?.injector) {
+    assertInInjectionContext(debounced);
+  }
+  const injector = options?.injector ?? inject(Injector);
+
+  const state = signal<ResourceSnapshot<T>>({
+    status: 'resolved',
+    value: untracked(() => {
+      try {
+        setInParamsFunction(true);
+        return source();
+      } finally {
+        setInParamsFunction(false);
+      }
+    }),
+  });
+
+  let active: Promise<void> | void | undefined;
+  let pendingValue: T | undefined;
+
+  injector.get(DestroyRef).onDestroy(() => {
+    active = undefined;
+  });
+
+  effect(
+    () => {
+      // Enter error state if the source throws.
+      let value: T;
+      try {
+        setInParamsFunction(true);
+        value = source();
+      } catch (err) {
+        rethrowFatalErrors(err);
+        state.set({status: 'error', error: err as Error});
+        active = pendingValue = undefined;
+        return;
+      } finally {
+        setInParamsFunction(false);
+      }
+
+      const currentState = untracked(state);
+
+      // Check if the value is the same as the previous one.
+      const equal = options?.equal ?? Object.is;
+      if (currentState.status === 'reloading') {
+        if (equal(value, pendingValue!)) return;
+      } else if (currentState.status === 'resolved') {
+        if (equal(value, currentState.value!)) return;
+      }
+
+      const waitFn =
+        typeof wait === 'number'
+          ? () => new Promise<void>((resolve) => setTimeout(resolve, wait))
+          : wait;
+
+      const result = waitFn(value, currentState);
+
+      if (result === undefined) {
+        // Synchronous case, go straight to resolved.
+        state.set({status: 'resolved', value});
+        active = pendingValue = undefined;
+      } else {
+        // Asynchronous case:
+        // If we're in error state or loading state, remain in that state.
+        // Otherwise, change to loading state but keep the current value until the new one loads.
+        if (currentState.status !== 'loading' && currentState.status !== 'error') {
+          state.set({status: 'loading', value: currentState.value});
+        }
+        active = result;
+        pendingValue = value;
+
+        // Once the promise resolves, update the state to resolved.
+        result.then(() => {
+          if (active === result) {
+            state.set({status: 'resolved', value});
+            active = pendingValue = undefined;
+          }
+        });
+      }
+    },
+    {injector},
+  );
+
+  return resourceFromSnapshots(state);
+}
diff --git a/packages/core/src/resource/index.ts b/packages/core/src/resource/index.ts
@@ -7,5 +7,6 @@
  */
 
 export * from './api';
+export {debounced} from './debounce';
 export {resourceFromSnapshots} from './from_snapshots';
 export {resource} from './resource';
diff --git a/packages/core/src/resource/resource.ts b/packages/core/src/resource/resource.ts
@@ -17,19 +17,20 @@ import {
   ResourceLoaderParams,
   ResourceOptions,
   ResourceParamsStatus,
-  ResourceRef,
   ResourceSnapshot,
   ResourceStatus,
   ResourceStreamingLoader,
   ResourceStreamItem,
   StreamingResourceOptions,
-  WritableResource,
   type ResourceParamsContext,
+  type ResourceRef,
+  type WritableResource,
 } from './api';
 
 import {assertInInjectionContext} from '../di/contextual';
 import {Injector} from '../di/injector';
 import {inject} from '../di/injector_compatibility';
+import {RuntimeError, RuntimeErrorCode} from '../errors';
 import {DestroyRef} from '../linker/destroy_ref';
 import {PendingTasks} from '../pending_tasks';
 import {linkedSignal} from '../render3/reactivity/linked_signal';
@@ -205,6 +206,10 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
     injector: Injector,
     getInitialStream?: (request: R) => Signal<ResourceStreamItem<T>> | undefined,
   ) {
+    if (isInParamsFunction()) {
+      throw invalidResourceCreationInParams();
+    }
+
     super(
       // Feed a computed signal for the value to `BaseWritableResource`, which will upgrade it to a
       // `WritableSignal` that delegates to `ResourceImpl.set`.
@@ -235,14 +240,18 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
     this.extRequest = linkedSignal<WrappedRequest>(
       () => {
         try {
+          setInParamsFunction(true);
           return {request: request(paramsContext), reload: 0};
         } catch (error) {
+          rethrowFatalErrors(error);
           if (error === ResourceParamsStatus.IDLE) {
             return {status: 'idle', reload: 0};
           } else if (error === ResourceParamsStatus.LOADING) {
             return {status: 'loading', reload: 0};
           }
           return {error: error as Error, reload: 0};
+        } finally {
+          setInParamsFunction(false);
         }
       },
       ngDevMode ? createDebugNameObject(debugName, 'extRequest') : undefined,
@@ -438,6 +447,7 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
         stream,
       });
     } catch (err) {
+      rethrowFatalErrors(err);
       if (abortSignal.aborted || untracked(this.extRequest) !== extRequest) {
         return;
       }
@@ -589,3 +599,29 @@ export const paramsContext: ResourceParamsContext = {
     return resource.value();
   },
 };
+
+let inParamsFunction = false;
+
+export function isInParamsFunction() {
+  return inParamsFunction;
+}
+
+export function setInParamsFunction(value: boolean) {
+  inParamsFunction = value;
+}
+
+export function invalidResourceCreationInParams(): Error {
+  return new RuntimeError(
+    RuntimeErrorCode.INVALID_RESOURCE_CREATION_IN_PARAMS,
+    ngDevMode && `Cannot create a resource inside the \`params\` of another resource`,
+  );
+}
+
+export function rethrowFatalErrors(error: unknown) {
+  if (
+    error instanceof RuntimeError &&
+    error.code === RuntimeErrorCode.INVALID_RESOURCE_CREATION_IN_PARAMS
+  ) {
+    throw error;
+  }
+}
diff --git a/packages/core/test/resource/debounce_spec.ts b/packages/core/test/resource/debounce_spec.ts

Original file line number	Diff line number	Diff line change
`@@ -157,6 +157,7 @@ export const enum RuntimeErrorCode {`
`157`	`157`	`// resource() API errors`
`158`	`158`	`MUST_PROVIDE_STREAM_OPTION = 990,`
`159`	`159`	`RESOURCE_COMPLETED_BEFORE_PRODUCING_VALUE = 991,`
	`160`	`+ INVALID_RESOURCE_CREATION_IN_PARAMS = 992,`
`160`	`161`
`161`	`162`	`// Upper bounds for core runtime errors is 999`
`162`	`163`	`}`