From f3402b9c3ad985063e7d5555321ed8d07b804b53 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 26 Sep 2024 16:27:38 -0400 Subject: [PATCH 01/10] Remove FunctionsError interface --- common/api-review/functions.api.md | 7 ------- packages/functions/src/error.ts | 1 + packages/functions/src/public-types.ts | 18 ------------------ 3 files changed, 1 insertion(+), 25 deletions(-) diff --git a/common/api-review/functions.api.md b/common/api-review/functions.api.md index 0602656f88e..8ce13d974ba 100644 --- a/common/api-review/functions.api.md +++ b/common/api-review/functions.api.md @@ -5,7 +5,6 @@ ```ts import { FirebaseApp } from '@firebase/app'; -import { FirebaseError } from '@firebase/util'; // @public export function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; @@ -17,12 +16,6 @@ export interface Functions { region: string; } -// @public -export interface FunctionsError extends FirebaseError { - readonly code: FunctionsErrorCode; - readonly details?: unknown; -} - // @public export type FunctionsErrorCode = `functions/${FunctionsErrorCodeCore}`; diff --git a/packages/functions/src/error.ts b/packages/functions/src/error.ts index d6f59fd95d3..62d5ecb6a4f 100644 --- a/packages/functions/src/error.ts +++ b/packages/functions/src/error.ts @@ -66,6 +66,7 @@ export class FunctionsError extends FirebaseError { readonly details?: unknown ) { super(`${FUNCTIONS_TYPE}/${code}`, message || ''); + // TODO (dlarocque): Set this to be the root of the stack trace. } } diff --git a/packages/functions/src/public-types.ts b/packages/functions/src/public-types.ts index 0637080f83d..311493d5fda 100644 --- 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; From d1d9b0112a393eb54a4a78ba28e9f420b18d4e43 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Mon, 30 Sep 2024 12:12:26 -0400 Subject: [PATCH 02/10] Make FunctionsError class public --- common/api-review/functions.api.md | 9 ++++++ docs-devsite/functions.functionserror.md | 37 +++++++++++++++++------- docs-devsite/functions.md | 7 ++++- packages/functions/src/api.ts | 1 + packages/functions/src/error.ts | 9 +++++- 5 files changed, 51 insertions(+), 12 deletions(-) diff --git a/common/api-review/functions.api.md b/common/api-review/functions.api.md index 8ce13d974ba..6133e017f67 100644 --- a/common/api-review/functions.api.md +++ b/common/api-review/functions.api.md @@ -5,6 +5,7 @@ ```ts import { FirebaseApp } from '@firebase/app'; +import { FirebaseError } from '@firebase/util'; // @public export function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; @@ -16,6 +17,14 @@ export interface Functions { region: string; } +// @public +export class FunctionsError extends FirebaseError { + constructor( + code: FunctionsErrorCodeCore, message?: string, + details?: unknown); + readonly details?: unknown; +} + // @public export type FunctionsErrorCode = `functions/${FunctionsErrorCodeCore}`; diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md index 3be96745b4c..e30fc3f3797 100644 --- a/docs-devsite/functions.functionserror.md +++ b/docs-devsite/functions.functionserror.md @@ -9,33 +9,50 @@ overwritten. Changes should be made in the source code at https://github.com/firebase/firebase-js-sdk {% endcomment %} -# FunctionsError interface -An error returned by the Firebase Functions client SDK. +# FunctionsError class +An explicit error that can be thrown from a handler to send an error to the client that called the function. + +See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. Signature: ```typescript -export interface FunctionsError extends FirebaseError +export declare class FunctionsError extends FirebaseError ``` Extends: [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 FunctionsError class | + +## Properties -## FunctionsError.code +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [details](./functions.functionserror.md#functionserrordetails) | | unknown | Extra data 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 Signature: ```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. diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md index 8e73e1178bc..d187686e527 100644 --- 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 explicit error that can be thrown from a handler to send an error to the client that called the function.See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. | + ## Interfaces | Interface | Description | | --- | --- | | [Functions](./functions.functions.md#functions_interface) | A Functions 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 HttpsCallableResult wraps a single result from a function call. | diff --git a/packages/functions/src/api.ts b/packages/functions/src/api.ts index a0e529ef671..a7804c2f573 100644 --- 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/error.ts b/packages/functions/src/error.ts index 62d5ecb6a4f..1e1fedfa080 100644 --- a/packages/functions/src/error.ts +++ b/packages/functions/src/error.ts @@ -51,6 +51,10 @@ 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. + * + * See {@link FunctionsErrorCode} for full documentation of codes. + * + * @public */ export class FunctionsError extends FirebaseError { constructor( @@ -66,7 +70,10 @@ export class FunctionsError extends FirebaseError { readonly details?: unknown ) { super(`${FUNCTIONS_TYPE}/${code}`, message || ''); - // TODO (dlarocque): Set this to be the root of the stack trace. + + // 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); } } From 2c6084ee8a28f816375448b25f7f7212315047bf Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Mon, 30 Sep 2024 12:14:18 -0400 Subject: [PATCH 03/10] Add changeset --- .changeset/tender-tips-hammer.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/tender-tips-hammer.md diff --git a/.changeset/tender-tips-hammer.md b/.changeset/tender-tips-hammer.md new file mode 100644 index 00000000000..763d6f282f5 --- /dev/null +++ b/.changeset/tender-tips-hammer.md @@ -0,0 +1,5 @@ +--- +'@firebase/functions': patch +--- + +Make the `FunctionsError` class publicly exported. From 876e938b942eed7d0a606c47ea61b165d5eef9ab Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Mon, 30 Sep 2024 12:20:35 -0400 Subject: [PATCH 04/10] Add instanceof check in tests --- packages/functions/src/callable.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/functions/src/callable.test.ts b/packages/functions/src/callable.test.ts index a2036046f1a..439e7d4f154 100644 --- 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); From a5caf512658315fc7a8f2b5b1261bfad6f228c1f Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 3 Oct 2024 11:49:02 -0400 Subject: [PATCH 05/10] Make FunctionsError doc comment the same as the old interface --- packages/functions/src/error.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/functions/src/error.ts b/packages/functions/src/error.ts index 1e1fedfa080..188312b20b2 100644 --- a/packages/functions/src/error.ts +++ b/packages/functions/src/error.ts @@ -49,8 +49,7 @@ 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. * From f694fe19c447cc56151fb3962fcc1ee281ef83cc Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Mon, 7 Oct 2024 09:16:06 -0400 Subject: [PATCH 06/10] Update devsite docs --- docs-devsite/functions.functionserror.md | 2 +- docs-devsite/functions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md index e30fc3f3797..aca1d5fda25 100644 --- a/docs-devsite/functions.functionserror.md +++ b/docs-devsite/functions.functionserror.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # FunctionsError class -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 [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md index d187686e527..07256a1ab13 100644 --- a/docs-devsite/functions.md +++ b/docs-devsite/functions.md @@ -27,7 +27,7 @@ Cloud Functions for Firebase | Class | Description | | --- | --- | -| [FunctionsError](./functions.functionserror.md#functionserror_class) | An explicit error that can be thrown from a handler to send an error to the client that called the function.See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. | +| [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 From bae5c2eab0dbedcdb08ca472afc8dccde45b4b68 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 10 Oct 2024 10:51:44 -0400 Subject: [PATCH 07/10] Add period to constructor doc comment --- common/api-review/functions.api.md | 3 +-- docs-devsite/functions.functionserror.md | 11 +++++------ packages/functions/src/error.ts | 11 +++++++---- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/common/api-review/functions.api.md b/common/api-review/functions.api.md index 6133e017f67..d68bd2122ed 100644 --- a/common/api-review/functions.api.md +++ b/common/api-review/functions.api.md @@ -19,8 +19,7 @@ export interface Functions { // @public export class FunctionsError extends FirebaseError { - constructor( - code: FunctionsErrorCodeCore, message?: string, + constructor(code: FunctionsErrorCodeCore, message?: string, details?: unknown); readonly details?: unknown; } diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md index aca1d5fda25..500b9f439b2 100644 --- a/docs-devsite/functions.functionserror.md +++ b/docs-devsite/functions.functionserror.md @@ -25,23 +25,22 @@ export declare class FunctionsError extends FirebaseError | Constructor | Modifiers | Description | | --- | --- | --- | -| [(constructor)(code, message, details)](./functions.functionserror.md#functionserrorconstructor) | | Constructs a new instance of the FunctionsError class | +| [(constructor)(code, message, details)](./functions.functionserror.md#functionserrorconstructor) | | Constructs a new instance of the FunctionsError class. | ## Properties | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [details](./functions.functionserror.md#functionserrordetails) | | unknown | Extra data to be converted to JSON and included in the error response. | +| [details](./functions.functionserror.md#functionserrordetails) | | unknown | Additional details to be converted to JSON and included in the error response. | ## FunctionsError.(constructor) -Constructs a new instance of the `FunctionsError` class +Constructs a new instance of the `FunctionsError` class. Signature: ```typescript -constructor( - code: FunctionsErrorCode, message?: string, +constructor(code: FunctionsErrorCode, message?: string, details?: unknown); ``` @@ -55,7 +54,7 @@ constructor( ## 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. Signature: diff --git a/packages/functions/src/error.ts b/packages/functions/src/error.ts index 188312b20b2..1713f74fc56 100644 --- a/packages/functions/src/error.ts +++ b/packages/functions/src/error.ts @@ -56,15 +56,18 @@ const errorCodeMap: { [name: string]: FunctionsErrorCode } = { * @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 - * determines the HTTP status code of the response, as defined in code.proto. - */ + * 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. + */ 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 ) { From f9348238023cb7e46641c70e4ea923d7d9241da7 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 10 Oct 2024 10:53:50 -0400 Subject: [PATCH 08/10] Formatting --- packages/functions/src/error.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/functions/src/error.ts b/packages/functions/src/error.ts index 1713f74fc56..82fbf257fe3 100644 --- a/packages/functions/src/error.ts +++ b/packages/functions/src/error.ts @@ -61,9 +61,9 @@ export class FunctionsError extends FirebaseError { */ constructor( /** - * 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. - */ + * 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. + */ code: FunctionsErrorCode, message?: string, /** From 705a6c1ef8e7006ff63d8575178d21b649689d82 Mon Sep 17 00:00:00 2001 From: dlarocque Date: Thu, 10 Oct 2024 15:08:06 +0000 Subject: [PATCH 09/10] Update API reports --- common/api-review/functions.api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/common/api-review/functions.api.md b/common/api-review/functions.api.md index d68bd2122ed..6133e017f67 100644 --- a/common/api-review/functions.api.md +++ b/common/api-review/functions.api.md @@ -19,7 +19,8 @@ export interface Functions { // @public export class FunctionsError extends FirebaseError { - constructor(code: FunctionsErrorCodeCore, message?: string, + constructor( + code: FunctionsErrorCodeCore, message?: string, details?: unknown); readonly details?: unknown; } From 2aa4f34acac2495fb5cc1a66c22b6167ba955d42 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Tue, 15 Oct 2024 10:11:17 -0400 Subject: [PATCH 10/10] update docs --- docs-devsite/functions.functionserror.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md index 500b9f439b2..8c2067c4f41 100644 --- a/docs-devsite/functions.functionserror.md +++ b/docs-devsite/functions.functionserror.md @@ -40,7 +40,8 @@ Constructs a new instance of the `FunctionsError` class. Signature: ```typescript -constructor(code: FunctionsErrorCode, message?: string, +constructor( + code: FunctionsErrorCode, message?: string, details?: unknown); ```