feat(core): add ability to cache resources for SSR

JeanMeche · web-flow · commit 5a7c1e62dc2a · 2026-05-06T09:57:49.000-07:00
This commit adds a `transferCacheKey` option to enable easy caching for `resource`/ `rxResource`.
diff --git a/goldens/public-api/core/index.api.md b/goldens/public-api/core/index.api.md
@@ -189,6 +189,7 @@ export interface AttributeDecorator {
 export interface BaseResourceOptions<T, R> {
     defaultValue?: NoInfer<T>;
     equal?: ValueEqualityFn<T>;
+    id?: string;
     injector?: Injector;
     params?: (ctx: ResourceParamsContext) => R;
 }
diff --git a/packages/common/http/src/resource.ts b/packages/common/http/src/resource.ts
@@ -434,6 +434,7 @@ class HttpResourceImpl<T>
       equal,
       debugName,
       injector,
+      undefined,
       getInitialStream,
     );
     this.client = injector.get(HttpClient);
diff --git a/packages/core/rxjs-interop/test/rx_resource_spec.ts b/packages/core/rxjs-interop/test/rx_resource_spec.ts
@@ -8,11 +8,24 @@
 
 import {timeout} from '@angular/private/testing';
 import {BehaviorSubject, EMPTY, Observable, of, Subscriber, throwError} from 'rxjs';
-import {ApplicationRef, Injector, signal} from '../../src/core';
+import {
+  ApplicationRef,
+  ɵCACHE_ACTIVE as CACHE_ACTIVE,
+  Injector,
+  makeStateKey,
+  signal,
+  TransferState,
+} from '../../src/core';
 import {TestBed} from '../../testing';
 import {rxResource} from '../src';
 
 describe('rxResource()', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [{provide: CACHE_ACTIVE, useValue: {isActive: true}}],
+    });
+  });
+
   it('should fetch data using an observable loader', async () => {
     const injector = TestBed.inject(Injector);
     const res = rxResource({
@@ -176,10 +189,110 @@ describe('rxResource()', () => {
     expect(res.error()).toBeInstanceOf(Error);
     expect(() => res.value()).toThrowError(/bad news/);
   });
+
+  describe('with TransferState', () => {
+    let transferState: TransferState;
+
+    beforeEach(() => {
+      TestBed.configureTestingModule({providers: [TransferState]});
+      transferState = TestBed.inject(TransferState);
+    });
+
+    afterEach(() => {
+      (globalThis as any).ngServerMode = undefined;
+    });
+
+    it('should read from TransferState if a key is present', async () => {
+      const key = makeStateKey<number>('test-key');
+      transferState.set(key, 123);
+
+      const injector = TestBed.inject(Injector);
+      const testResource = rxResource({
+        stream: () => of(456),
+        id: key,
+        injector,
+      });
+
+      // Should be synchronously resolved from cache
+      expect(testResource.status()).toBe('resolved');
+      expect(testResource.value()).toBe(123);
+
+      // Should prevent loader from running
+      await flushMicrotasks();
+      expect(testResource.value()).toBe(123);
+    });
+
+    it('should write to TransferState on server when resolved (sync)', async () => {
+      (globalThis as any).ngServerMode = true;
+      const key = makeStateKey<number>('server-key');
+
+      const injector = TestBed.inject(Injector);
+      const testResource = rxResource({
+        stream: () => of(789),
+        id: key,
+        injector,
+      });
+
+      expect(testResource.status()).toBe('loading');
+
+      await flushMicrotasks();
+
+      expect(testResource.status()).toBe('resolved');
+      expect(testResource.value()).toBe(789);
+      expect(transferState.get(key, null!)).toBe(789);
+    });
+
+    it('should write to TransferState on server when resolved (async)', async () => {
+      (globalThis as any).ngServerMode = true;
+      const key = makeStateKey<number>('server-async-key');
+
+      const injector = TestBed.inject(Injector);
+      const testResource = rxResource({
+        stream: () =>
+          new Observable<number>((sub) => {
+            Promise.resolve().then(() => {
+              sub.next(101112);
+              sub.complete();
+            });
+          }),
+        id: key,
+        injector,
+      });
+
+      expect(testResource.status()).toBe('loading');
+
+      await waitFor(() => testResource.status() === 'resolved');
+
+      expect(testResource.value()).toBe(101112);
+      expect(transferState.get(key, null!)).toBe(101112);
+    });
+
+    it('should not write to TransferState on client when resolved', async () => {
+      (globalThis as any).ngServerMode = false;
+      const key = makeStateKey<number>('client-key');
+
+      const injector = TestBed.inject(Injector);
+      const testResource = rxResource({
+        stream: () => of(131415),
+        id: key,
+        injector,
+      });
+
+      await flushMicrotasks();
+
+      expect(testResource.status()).toBe('resolved');
+      expect(testResource.value()).toBe(131415);
+      expect(transferState.hasKey(key)).toBeFalse();
+    });
+  });
 });
 
 async function waitFor(fn: () => boolean): Promise<void> {
   while (!fn()) {
     await timeout(1);
   }
 }
+
+function flushMicrotasks(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
diff --git a/packages/core/src/core_private_export.ts b/packages/core/src/core_private_export.ts
@@ -95,6 +95,7 @@ export {
   withI18nSupport as ɵwithI18nSupport,
   withIncrementalHydration as ɵwithIncrementalHydration,
 } from './hydration/api';
+export {CACHE_ACTIVE as ɵCACHE_ACTIVE} from './hydration/cache';
 export {withEventReplay as ɵwithEventReplay} from './hydration/event_replay';
 export {
   EVENT_REPLAY_QUEUE as ɵEVENT_REPLAY_QUEUE,
diff --git a/packages/core/src/hydration/cache.ts b/packages/core/src/hydration/cache.ts
@@ -0,0 +1,16 @@
+/**
+ * @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 {InjectionToken} from '../di';
+
+/**
+ * Token used to the determine if the transfer cache should be used, for example for resources.
+ */
+export const CACHE_ACTIVE = new InjectionToken<{isActive: boolean}>(
+  typeof ngDevMode !== 'undefined' && ngDevMode ? 'STATE_CACHE_ACTIVE' : '',
+);
diff --git a/packages/core/src/resource/api.ts b/packages/core/src/resource/api.ts
@@ -231,6 +231,12 @@ export interface BaseResourceOptions<T, R> {
    * Overrides the `Injector` used by `resource`.
    */
   injector?: Injector;
+
+  /**
+   * Identifier used to cache the resource data in the `TransferState` during server-side rendering and to retrieve it on the client side.
+   * This value value needs to be identical for both the client and server.
+   */
+  id?: string;
 }
 
 /**
diff --git a/packages/core/src/resource/resource.ts b/packages/core/src/resource/resource.ts
@@ -30,9 +30,11 @@ import {assertInInjectionContext} from '../di/contextual';
 import {Injector} from '../di/injector';
 import {inject} from '../di/injector_compatibility';
 import {RuntimeError, RuntimeErrorCode} from '../errors';
+import {CACHE_ACTIVE} from '../hydration/cache';
 import {DestroyRef} from '../linker/destroy_ref';
 import {PendingTasks} from '../pending_tasks';
 import {linkedSignal} from '../render3/reactivity/linked_signal';
+import {StateKey, TransferState} from '../transfer_state';
 
 /**
  * Constructs a `Resource` that projects a reactive request to an asynchronous operation defined by
@@ -78,6 +80,7 @@ export function resource<T, R>(options: ResourceOptions<T, R>): ResourceRef<T |
     options.equal ? wrapEqualityFn(options.equal) : undefined,
     options.debugName,
     options.injector ?? inject(Injector),
+    options.id as StateKey<T>,
   );
 }
 
@@ -195,6 +198,7 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
 
   override readonly status: Signal<ResourceStatus>;
   override readonly error: Signal<Error | undefined>;
+  private readonly transferState: TransferState | undefined;
 
   constructor(
     request: (ctx: ResourceParamsContext) => R,
@@ -203,6 +207,7 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
     private readonly equal: ValueEqualityFn<T> | undefined,
     private readonly debugName: string | undefined,
     injector: Injector,
+    private transferCacheKey: StateKey<T> | undefined,
     getInitialStream?: (request: R) => Signal<ResourceStreamItem<T>> | undefined,
   ) {
     if (isInParamsFunction()) {
@@ -236,6 +241,10 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
       debugName,
     );
 
+    const cacheState = injector.get(CACHE_ACTIVE, undefined, {optional: true}) ?? {isActive: false};
+
+    this.transferState = injector.get(TransferState, undefined, {optional: true}) ?? undefined;
+
     this.extRequest = linkedSignal<WrappedRequest>(
       () => {
         try {
@@ -274,7 +283,21 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
           );
         } else if (!status) {
           if (!previous) {
-            stream = getInitialStream?.(extRequest.request as R);
+            const transferState = this.transferState;
+            const cacheKey = this.transferCacheKey;
+            if (cacheState.isActive && cacheKey && transferState && request !== undefined) {
+              const key = this.transferCacheKey;
+              if (transferState.hasKey(cacheKey)) {
+                stream = signal(
+                  {value: transferState.get(cacheKey, defaultValue)},
+                  ngDevMode ? createDebugNameObject(this.debugName, 'stream') : undefined,
+                );
+              }
+            }
+
+            if (!stream) {
+              stream = getInitialStream?.(extRequest.request as R);
+            }
             // Clear getInitialStream so it doesn't hold onto memory
             getInitialStream = undefined;
             status = request === undefined ? 'idle' : stream ? 'resolved' : 'loading';
@@ -446,6 +469,11 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
           previousStatus: 'resolved',
           stream,
         });
+
+        const result = untracked(stream);
+        if (typeof ngServerMode !== 'undefined' && ngServerMode) {
+          saveToTransferState(result, this.transferCacheKey, this.transferState);
+        }
       } else {
         const resolvedStream = await stream;
         if (shouldDiscard()) {
@@ -458,6 +486,12 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
           previousStatus: 'resolved',
           stream: resolvedStream,
         });
+
+        // Use a local variable for the result so TypeScript can narrow `resolvedStream` correctly.
+        const result = resolvedStream ? untracked(resolvedStream) : undefined;
+        if (typeof ngServerMode !== 'undefined' && ngServerMode) {
+          saveToTransferState(result, this.transferCacheKey, this.transferState);
+        }
       }
     } catch (err) {
       rethrowFatalErrors(err);
@@ -491,6 +525,16 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
   }
 }
 
+function saveToTransferState<R, T>(
+  result: ResourceStreamItem<T> | undefined,
+  transferCacheKey: StateKey<T> | undefined,
+  transferState: TransferState | undefined,
+): void {
+  if (transferCacheKey && transferState && result && isResolved(result)) {
+    transferState.set(transferCacheKey, result.value);
+  }
+}
+
 /**
  * Wraps an equality function to handle either value being `undefined`.
  */
diff --git a/packages/core/test/bundling/hydration/bundle.golden_symbols.json b/packages/core/test/bundling/hydration/bundle.golden_symbols.json
@@ -29,6 +29,7 @@
       "BUBBLE_EVENT_TYPES",
       "BehaviorSubject",
       "BrowserDomAdapter",
+      "CACHE_ACTIVE",
       "CACHE_OPTIONS",
       "CAPTURE_EVENT_TYPES",
       "CHILD_HEAD",
diff --git a/packages/core/test/resource/resource_spec.ts b/packages/core/test/resource/resource_spec.ts
diff --git a/packages/platform-browser/src/hydration.ts b/packages/platform-browser/src/hydration.ts

Original file line number	Diff line number	Diff line change
`@@ -189,6 +189,7 @@ export interface AttributeDecorator {`
`189`	`189`	`export interface BaseResourceOptions<T, R> {`
`190`	`190`	`defaultValue?: NoInfer<T>;`
`191`	`191`	`equal?: ValueEqualityFn<T>;`
	`192`	`+ id?: string;`
`192`	`193`	`injector?: Injector;`
`193`	`194`	`params?: (ctx: ResourceParamsContext) => R;`
`194`	`195`	`}`