Make the FunctionsError class publicly exported (#8546)

* Remove FunctionsError interface * Make FunctionsError class public * Add changeset * Add instanceof check in tests * Make FunctionsError doc comment the same as the old interface * Update devsite docs * Add period to constructor doc comment * Formatting * Update API reports * update docs --------- Co-authored-by: dlarocque <[email protected]>
firebase · Oct 15, 2024 · a214691 · a214691
1 parent 813b9fa
commit a214691
Show file tree

Hide file tree

Showing 8 changed files with 57 additions and 34 deletions.
diff --git a/.changeset/tender-tips-hammer.md b/.changeset/tender-tips-hammer.md
@@ -0,0 +1,5 @@
+---
+'@firebase/functions': patch
+---
+
+Make the `FunctionsError` class publicly exported.
diff --git a/common/api-review/functions.api.md b/common/api-review/functions.api.md
@@ -18,8 +18,10 @@ export interface Functions {
 }
 
 // @public
-export interface FunctionsError extends FirebaseError {
-    readonly code: FunctionsErrorCode;
+export class FunctionsError extends FirebaseError {
+    constructor(
+    code: FunctionsErrorCodeCore, message?: string,
+    details?: unknown);
     readonly details?: unknown;
 }
 

diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md
@@ -9,36 +9,53 @@ overwritten. Changes should be made in the source code at
 https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
-# FunctionsError interface
+# FunctionsError class
 An error returned by the Firebase Functions client SDK.
 
+See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes.
+
 <b>Signature:</b>
 
 ```typescript
-export interface FunctionsError extends FirebaseError 
+export declare class FunctionsError extends FirebaseError 
 ```
 <b>Extends:</b> [FirebaseError](./util.firebaseerror.md#firebaseerror_class)
 
-## Properties
+## Constructors
 
-|  Property | Type | Description |
+|  Constructor | Modifiers | Description |
 |  --- | --- | --- |
-|  [code](./functions.functionserror.md#functionserrorcode) | [FunctionsErrorCode](./functions.md#functionserrorcode) | A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. |
-|  [details](./functions.functionserror.md#functionserrordetails) | unknown | Extra data to be converted to JSON and included in the error response. |
+|  [(constructor)(code, message, details)](./functions.functionserror.md#functionserrorconstructor) |  | Constructs a new instance of the <code>FunctionsError</code> class. |
+
+## Properties
 
-## FunctionsError.code
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [details](./functions.functionserror.md#functionserrordetails) |  | unknown | Additional details to be converted to JSON and included in the error response. |
 
-A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto.
+## FunctionsError.(constructor)
+
+Constructs a new instance of the `FunctionsError` class.
 
 <b>Signature:</b>
 
 ```typescript
-readonly code: FunctionsErrorCode;
+constructor(
+    code: FunctionsErrorCode, message?: string, 
+    details?: unknown);
 ```
 
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  code | [FunctionsErrorCode](./functions.md#functionserrorcodecore) |  |
+|  message | string |  |
+|  details | unknown |  |
+
 ## FunctionsError.details
 
-Extra data to be converted to JSON and included in the error response.
+Additional details to be converted to JSON and included in the error response.
 
 <b>Signature:</b>
 

diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md
@@ -23,12 +23,17 @@ Cloud Functions for Firebase
 |  [httpsCallable(functionsInstance, name, options)](./functions.md#httpscallable_1dd297c) | Returns a reference to the callable HTTPS trigger with the given name. |
 |  [httpsCallableFromURL(functionsInstance, url, options)](./functions.md#httpscallablefromurl_7af6987) | Returns a reference to the callable HTTPS trigger with the specified url. |
 
+## Classes
+
+|  Class | Description |
+|  --- | --- |
+|  [FunctionsError](./functions.functionserror.md#functionserror_class) | An error returned by the Firebase Functions client SDK.<!-- -->See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. |
+
 ## Interfaces
 
 |  Interface | Description |
 |  --- | --- |
 |  [Functions](./functions.functions.md#functions_interface) | A <code>Functions</code> instance. |
-|  [FunctionsError](./functions.functionserror.md#functionserror_interface) | An error returned by the Firebase Functions client SDK. |
 |  [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | An interface for metadata about how calls should be executed. |
 |  [HttpsCallableResult](./functions.httpscallableresult.md#httpscallableresult_interface) | An <code>HttpsCallableResult</code> wraps a single result from a function call. |
 

diff --git a/packages/functions/src/api.ts b/packages/functions/src/api.ts
@@ -32,6 +32,7 @@ import {
   getDefaultEmulatorHostnameAndPort
 } from '@firebase/util';
 
+export { FunctionsError } from './error';
 export * from './public-types';
 
 /**

diff --git a/packages/functions/src/callable.test.ts b/packages/functions/src/callable.test.ts
@@ -57,6 +57,7 @@ async function expectError(
     await promise;
   } catch (e) {
     failed = true;
+    expect(e).to.be.instanceOf(FunctionsError);
     const error = e as FunctionsError;
     expect(error.code).to.equal(`${FUNCTIONS_TYPE}/${code}`);
     expect(error.message).to.equal(message);

diff --git a/packages/functions/src/error.ts b/packages/functions/src/error.ts
@@ -49,10 +49,16 @@ const errorCodeMap: { [name: string]: FunctionsErrorCode } = {
 };
 
 /**
- * An explicit error that can be thrown from a handler to send an error to the
- * client that called the function.
+ * An error returned by the Firebase Functions client SDK.
+ *
+ * See {@link FunctionsErrorCode} for full documentation of codes.
+ *
+ * @public
  */
 export class FunctionsError extends FirebaseError {
+  /**
+   * Constructs a new instance of the `FunctionsError` class.
+   */
   constructor(
     /**
      * A standard error code that will be returned to the client. This also
@@ -61,11 +67,15 @@ export class FunctionsError extends FirebaseError {
     code: FunctionsErrorCode,
     message?: string,
     /**
-     * Extra data to be converted to JSON and included in the error response.
+     * Additional details to be converted to JSON and included in the error response.
      */
     readonly details?: unknown
   ) {
     super(`${FUNCTIONS_TYPE}/${code}`, message || '');
+
+    // Since the FirebaseError constructor sets the prototype of `this` to FirebaseError.prototype,
+    // we also have to do it in all subclasses to allow for correct `instanceof` checks.
+    Object.setPrototypeOf(this, FunctionsError.prototype);
   }
 }
 

diff --git a/packages/functions/src/public-types.ts b/packages/functions/src/public-types.ts
@@ -15,7 +15,6 @@
  * limitations under the License.
  */
 import { FirebaseApp } from '@firebase/app';
-import { FirebaseError } from '@firebase/util';
 
 /**
  * An `HttpsCallableResult` wraps a single result from a function call.
@@ -144,23 +143,6 @@ export type FunctionsErrorCodeCore =
  */
 export type FunctionsErrorCode = `functions/${FunctionsErrorCodeCore}`;
 
-/**
- * An error returned by the Firebase Functions client SDK.
- * @public
- */
-export interface FunctionsError extends FirebaseError {
-  /**
-   * A standard error code that will be returned to the client. This also
-   * determines the HTTP status code of the response, as defined in code.proto.
-   */
-  readonly code: FunctionsErrorCode;
-
-  /**
-   * Extra data to be converted to JSON and included in the error response.
-   */
-  readonly details?: unknown;
-}
-
 declare module '@firebase/component' {
   interface NameServiceMapping {
     'functions': Functions;