fix(core): narrow error type for resources API (angular#61441)

`Resource.error` used to return `unknown`. Now it's `Error | undefined`.
For non-`Error` types they are encapsulated with the `Error` type.

PR Close angular#61441

Author: Humberd

goldens/public-api/core/index.api.md

@@ -1607,7 +1607,7 @@ export function resolveForwardRef<T>(type: T): T;
 
 // @public
 export interface Resource<T> {
-    readonly error: Signal<unknown>;
+    readonly error: Signal<Error | undefined>;
     hasValue(): this is Resource<Exclude<T, undefined>>;
     readonly isLoading: Signal<boolean>;
     readonly status: Signal<ResourceStatus>;
@@ -1657,7 +1657,7 @@ export type ResourceStreamingLoader<T, R> = (param: ResourceLoaderParams<R>) =>
 export type ResourceStreamItem<T> = {
     value: T;
 } | {
-    error: unknown;
+    error: Error;
 };
 
 // @public

packages/common/http/src/resource.ts

@@ -19,6 +19,7 @@ import {
   type ValueEqualityFn,
   ɵRuntimeError,
   ɵRuntimeErrorCode,
+  ɵencapsulateResourceError as encapsulateResourceError,
 } from '@angular/core';
 import type {Subscription} from 'rxjs';
 
@@ -344,7 +345,7 @@ class HttpResourceImpl<T>
                 try {
                   send({value: parse ? parse(event.body) : (event.body as T)});
                 } catch (error) {
-                  send({error});
+                  send({error: encapsulateResourceError(error)});
                 }
                 break;
               case HttpEventType.DownloadProgress:

packages/core/rxjs-interop/src/rx_resource.ts

@@ -18,6 +18,7 @@ import {
   ɵRuntimeErrorCode,
 } from '../../src/core';
 import {Observable, Subscription} from 'rxjs';
+import {encapsulateResourceError} from '../../src/resource/resource';
 
 /**
  * Like `ResourceOptions` but uses an RxJS-based `loader`.
@@ -61,11 +62,11 @@ export function rxResource<T, R>(opts: RxResourceOptions<T, R>): ResourceRef<T |
       params.abortSignal.addEventListener('abort', onAbort);
 
       // Start off stream as undefined.
-      const stream = signal<{value: T} | {error: unknown}>({value: undefined as T});
-      let resolve: ((value: Signal<{value: T} | {error: unknown}>) => void) | undefined;
-      const promise = new Promise<Signal<{value: T} | {error: unknown}>>((r) => (resolve = r));
+      const stream = signal<{value: T} | {error: Error}>({value: undefined as T});
+      let resolve: ((value: Signal<{value: T} | {error: Error}>) => void) | undefined;
+      const promise = new Promise<Signal<{value: T} | {error: Error}>>((r) => (resolve = r));
 
-      function send(value: {value: T} | {error: unknown}): void {
+      function send(value: {value: T} | {error: Error}): void {
         stream.set(value);
         resolve?.(stream);
         resolve = undefined;
@@ -82,8 +83,8 @@ export function rxResource<T, R>(opts: RxResourceOptions<T, R>): ResourceRef<T |
 
       sub = streamFn(params).subscribe({
         next: (value) => send({value}),
-        error: (error) => {
-          send({error});
+        error: (error: unknown) => {
+          send({error: encapsulateResourceError(error)});
           params.abortSignal.removeEventListener('abort', onAbort);
         },
         complete: () => {

packages/core/rxjs-interop/test/rx_resource_spec.ts

@@ -74,7 +74,8 @@ describe('rxResource()', () => {
     expect(res.value()).toBe(3);
 
     response.error('fail');
-    expect(res.error()).toBe('fail');
+    expect(res.error()).toEqual(jasmine.objectContaining({cause: 'fail'}));
+    expect(res.error()!.message).toContain('Resource');
   });
 });
 

packages/core/src/core_private_export.ts

@@ -162,6 +162,9 @@ export {
   disableProfiling as ɵdisableProfiling,
 } from './profiler';
 
-export {ResourceImpl as ɵResourceImpl} from './resource/resource';
+export {
+  ResourceImpl as ɵResourceImpl,
+  encapsulateResourceError as ɵencapsulateResourceError,
+} from './resource/resource';
 
 export {getClosestComponentName as ɵgetClosestComponentName} from './internal/get_closest_component_name';

packages/core/src/resource/api.ts

@@ -59,7 +59,7 @@ export interface Resource<T> {
   /**
    * When in the `error` state, this returns the last known error from the `Resource`.
    */
-  readonly error: Signal<unknown>;
+  readonly error: Signal<Error | undefined>;
 
   /**
    * Whether this resource is loading a new value (or reloading the existing one).
@@ -225,4 +225,4 @@ export type ResourceOptions<T, R> = PromiseResourceOptions<T, R> | StreamingReso
 /**
  * @experimental
  */
-export type ResourceStreamItem<T> = {value: T} | {error: unknown};
+export type ResourceStreamItem<T> = {value: T} | {error: Error};

packages/core/src/resource/resource.ts

@@ -101,7 +101,8 @@ type WrappedRequest = {request: unknown; reload: number};
 abstract class BaseWritableResource<T> implements WritableResource<T> {
   readonly value: WritableSignal<T>;
   abstract readonly status: Signal<ResourceStatus>;
-  abstract readonly error: Signal<unknown>;
+  abstract readonly error: Signal<Error | undefined>;
+
   abstract reload(): boolean;
 
   constructor(value: Signal<T>) {
@@ -346,7 +347,7 @@ export class ResourceImpl<T, R> extends BaseWritableResource<T> implements Resou
         extRequest,
         status: 'resolved',
         previousStatus: 'error',
-        stream: signal({error: err}),
+        stream: signal({error: encapsulateResourceError(err)}),
       });
     } finally {
       // Resolve the pending task now that the resource has a value.
@@ -381,7 +382,7 @@ function getLoader<T, R>(options: ResourceOptions<T, R>): ResourceStreamingLoade
     try {
       return signal({value: await options.loader(params)});
     } catch (err) {
-      return signal({error: err});
+      return signal({error: encapsulateResourceError(err)});
     }
   };
 }
@@ -409,3 +410,22 @@ function projectStatusOfState(state: ResourceState<unknown>): ResourceStatus {
 function isResolved<T>(state: ResourceStreamItem<T>): state is {value: T} {
   return (state as {error: unknown}).error === undefined;
 }
+
+export function encapsulateResourceError(error: unknown): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  return new ResourceWrappedError(error);
+}
+
+class ResourceWrappedError extends Error {
+  constructor(error: unknown) {
+    super(
+      ngDevMode
+        ? `Resource returned an error that's not an Error instance: ${String(error)}. Check this error's .cause for the actual error.`
+        : String(error),
+      {cause: error},
+    );
+  }
+}

packages/core/test/resource/resource_spec.ts

@@ -71,6 +71,7 @@ class MockEchoBackend<T> extends MockBackend<T, T> {
 
 class MockResponseCountingBackend extends MockBackend<number, string> {
   counter = 0;
+
   override prepareResponse(request: number) {
     return request + ':' + this.counter++;
   }
@@ -145,7 +146,10 @@ describe('resource', () => {
     expect(echoResource.isLoading()).toBeFalse();
     expect(echoResource.hasValue()).toBeFalse();
     expect(echoResource.value()).toEqual(undefined);
-    expect(echoResource.error()).toBe('Something went wrong....');
+    expect(echoResource.error()).toEqual(
+      jasmine.objectContaining({cause: 'Something went wrong....'}),
+    ),
+      expect(echoResource.error()!.message).toContain('Resource');
   });
 
   it('should expose errors on reload', async () => {
@@ -608,18 +612,18 @@ describe('resource', () => {
   it('should error via error()', async () => {
     const appRef = TestBed.inject(ApplicationRef);
     const res = resource({
-      stream: async () => signal({error: 'fail'}),
+      stream: async () => signal({error: new Error('fail')}),
       injector: TestBed.inject(Injector),
     });
 
     await appRef.whenStable();
     expect(res.status()).toBe('error');
-    expect(res.error()).toBe('fail');
+    expect(res.error()).toEqual(new Error('fail'));
   });
 
   it('should transition across streamed states', async () => {
     const appRef = TestBed.inject(ApplicationRef);
-    const stream = signal<{value: number} | {error: unknown}>({value: 1});
+    const stream = signal<{value: number} | {error: Error}>({value: 1});
 
     const res = resource({
       stream: async () => stream,
@@ -633,16 +637,16 @@ describe('resource', () => {
     stream.set({value: 3});
     expect(res.value()).toBe(3);
 
-    stream.set({error: 'fail'});
-    expect(res.error()).toBe('fail');
+    stream.set({error: new Error('fail')});
+    expect(res.error()).toEqual(new Error('fail'));
 
     stream.set({value: 4});
     expect(res.value()).toBe(4);
   });
 
   it('should not accept new values/errors after a request is cancelled', async () => {
     const appRef = TestBed.inject(ApplicationRef);
-    const stream = signal<{value: number} | {error: unknown}>({value: 0});
+    const stream = signal<{value: number} | {error: Error}>({value: 0});
     const request = signal(1);
     const res = resource({
       params: request,
@@ -666,7 +670,7 @@ describe('resource', () => {
     // The previous set/error functions should no longer result in changes to the resource.
     stream.set({value: 2});
     expect(res.value()).toBe(undefined);
-    stream.set({error: 'fail'});
+    stream.set({error: new Error('fail')});
     expect(res.value()).toBe(undefined);
   });