fix: add type declarations for errors

Author: rowanmanning

.gitignore

@@ -1,5 +1,4 @@
 .husky/_
-packages/errors/**/*.d.*
 packages/fetch-error-handler/**/*.d.*
 packages/logger/**/*.d.*
 packages/middleware-log-errors/**/*.d.*

jsconfig.build.json

@@ -8,7 +8,6 @@
 		"removeComments": true
 	},
 	"include": [
-		"packages/errors/**/*.js",
 		"packages/fetch-error-handler/**/*.js",
 		"packages/logger/**/*.js",
 		"packages/middleware-log-errors/**/*.js",

packages/errors/.npmignore

@@ -1,5 +1,3 @@
-!*.d.ts
-!*.d.ts.map
 CHANGELOG.md
 docs
 test

packages/errors/lib/base-error.js

@@ -1,15 +1,5 @@
 /**
- * @typedef {object} ErrorStrictData
- * @property {string} [code]
- *     A machine-readable error code which identifies the specific type of error.
- * @property {string} [message]
- *     A human readable message which describes the error.
- * @property {Error | null} [cause]
- *     The root cause error instance.
- */
-
-/**
- * @typedef {ErrorStrictData & Record<string, any>} ErrorData
+ * @typedef {import('@dotcom-reliability-kit/errors').BaseErrorData} ErrorData
  */
 
 /**
@@ -19,44 +9,39 @@ class BaseError extends Error {
 	/**
 	 * @override
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').BaseError['name']}
 	 */
 	name = 'BaseError';
 
 	/**
 	 * Whether the error is operational.
 	 *
 	 * @readonly
-	 * @public
-	 * @type {boolean}
+	 * @type {import('@dotcom-reliability-kit/errors').BaseError['isOperational']}
 	 */
 	isOperational = false;
 
 	/**
 	 * A machine-readable error code which identifies the specific type of error.
 	 *
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').BaseError['code']}
 	 */
 	code = BaseError.defaultCode;
 
 	/**
 	 * The root cause error instance.
 	 *
 	 * @readonly
-	 * @public
-	 * @type {Error | null}
+	 * @type {import('@dotcom-reliability-kit/errors').BaseError['cause']}
 	 */
 	cause = null;
 
 	/**
 	 * Additional error information.
 	 *
 	 * @readonly
-	 * @public
-	 * @type {{[key: string]: any}}
+	 * @type {import('@dotcom-reliability-kit/errors').BaseError['data']}
 	 */
 	data = {};
 
@@ -134,13 +119,7 @@ class BaseError extends Error {
 	static defaultMessage = 'An error occurred';
 
 	/**
-	 * Get whether an error object is marked as operational (it has a truthy `isOperational` property).
-	 *
-	 * @public
-	 * @param {Error} error
-	 *     The error object to check.
-	 * @returns {boolean}
-	 *     Returns whether the error is operational.
+	 * @type {(typeof import('@dotcom-reliability-kit/errors').BaseError)['isErrorMarkedAsOperational']}
 	 */
 	static isErrorMarkedAsOperational(error) {
 		// @ts-ignore Error.prototype.isOperational does not exist, but it's OK to check in this

packages/errors/lib/data-store-error.js

@@ -7,8 +7,7 @@ class DataStoreError extends OperationalError {
 	/**
 	 * @override
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').DataStoreError['name']}
 	 */
 	name = 'DataStoreError';
 }

packages/errors/lib/http-error.js

@@ -11,13 +11,7 @@ const OperationalError = require('./operational-error');
 const STATUS_CODES = require('http').STATUS_CODES;
 
 /**
- * @typedef {object} HttpErrorStrictData
- * @property {number} [statusCode]
- *     An HTTP status code.
- */
-
-/**
- * @typedef {HttpErrorStrictData & OperationalError.OperationalErrorData} HttpErrorData
+ * @typedef {import('@dotcom-reliability-kit/errors').HttpErrorData} ErrorData
  */
 
 /**
@@ -27,28 +21,24 @@ class HttpError extends OperationalError {
 	/**
 	 * @override
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').HttpError['name']}
 	 */
 	name = 'HttpError';
 
 	/**
 	 * @readonly
-	 * @public
-	 * @type {number}
+	 * @type {import('@dotcom-reliability-kit/errors').HttpError['statusCode']}
 	 */
 	statusCode;
 
 	/**
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').HttpError['statusMessage']}
 	 */
 	statusMessage;
 
 	/**
-	 * @public
-	 * @type {number}
+	 * @type {import('@dotcom-reliability-kit/errors').HttpError['status']}
 	 */
 	get status() {
 		return this.statusCode;
@@ -63,7 +53,7 @@ class HttpError extends OperationalError {
 	 * Create an error with error data.
 	 *
 	 * @overload
-	 * @param {HttpErrorData} data
+	 * @param {ErrorData} data
 	 *     Additional error information.
 	 */
 	/**
@@ -72,7 +62,7 @@ class HttpError extends OperationalError {
 	 * @overload
 	 * @param {string} message
 	 *     The error message.
-	 * @param {HttpErrorData} [data]
+	 * @param {ErrorData} [data]
 	 *     Additional error information.
 	 */
 	/**
@@ -81,14 +71,14 @@ class HttpError extends OperationalError {
 	 * @overload
 	 * @param {number} status
 	 *     The error HTTP status code.
-	 * @param {HttpErrorData} [data]
+	 * @param {ErrorData} [data]
 	 *     Additional error information.
 	 */
 	/**
-	 * @param {string | number | HttpErrorData} [message]
+	 * @param {string | number | ErrorData} [message]
 	 *     The error message if it's a string, the HTTP status code if it's a number, or full error
 	 *     information if an object.
-	 * @param {HttpErrorData} [data]
+	 * @param {ErrorData} [data]
 	 *     Additional error information if `message` is a string or number.
 	 */
 	constructor(message, data = {}) {

packages/errors/lib/operational-error.js

@@ -1,13 +1,7 @@
 const BaseError = require('./base-error');
 
 /**
- * @typedef {object} OperationalErrorStrictData
- * @property {string[]} [relatesToSystems]
- *     An array of FT system codes which are related to this error.
- */
-
-/**
- * @typedef {OperationalErrorStrictData & BaseError.ErrorData} OperationalErrorData
+ * @typedef {import('@dotcom-reliability-kit/errors').OperationalErrorData} ErrorData
  */
 
 /**
@@ -17,8 +11,7 @@ class OperationalError extends BaseError {
 	/**
 	 * @override
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').OperationalError['name']}
 	 */
 	name = 'OperationalError';
 
@@ -27,8 +20,7 @@ class OperationalError extends BaseError {
 	 *
 	 * @override
 	 * @readonly
-	 * @public
-	 * @type {boolean}
+	 * @type {import('@dotcom-reliability-kit/errors').OperationalError['isOperational']}
 	 */
 	isOperational = true;
 
@@ -37,8 +29,7 @@ class OperationalError extends BaseError {
 	 * If this error is caused by one or more dependencies, include their system code here.
 	 *
 	 * @readonly
-	 * @public
-	 * @type {string[]}
+	 * @type {import('@dotcom-reliability-kit/errors').OperationalError['relatesToSystems']}
 	 */
 	relatesToSystems = [];
 
@@ -51,7 +42,7 @@ class OperationalError extends BaseError {
 	 * Create an error with error data.
 	 *
 	 * @overload
-	 * @param {OperationalErrorData} data
+	 * @param {ErrorData} data
 	 *     Additional error information.
 	 */
 	/**
@@ -60,13 +51,13 @@ class OperationalError extends BaseError {
 	 * @overload
 	 * @param {string} message
 	 *     The error message.
-	 * @param {OperationalErrorData} [data]
+	 * @param {ErrorData} [data]
 	 *     Additional error information.
 	 */
 	/**
-	 * @param {string | OperationalErrorData} [message]
+	 * @param {string | ErrorData} [message]
 	 *     The error message if it's a string, or full error information if an object.
-	 * @param {OperationalErrorData} [data]
+	 * @param {ErrorData} [data]
 	 *     Additional error information if `message` is a string.
 	 */
 	constructor(message, data = {}) {

packages/errors/lib/upstream-service-error.js

@@ -7,8 +7,7 @@ class UpstreamServiceError extends HttpError {
 	/**
 	 * @override
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').UpstreamServiceError['name']}
 	 */
 	name = 'UpstreamServiceError';
 

packages/errors/lib/user-input-error.js

@@ -7,8 +7,7 @@ class UserInputError extends HttpError {
 	/**
 	 * @override
 	 * @readonly
-	 * @public
-	 * @type {string}
+	 * @type {import('@dotcom-reliability-kit/errors').UserInputError['name']}
 	 */
 	name = 'UserInputError';
 

packages/errors/package.json

@@ -14,5 +14,6 @@
     "node": "18.x || 20.x || 22.x",
     "npm": "8.x || 9.x || 10.x"
   },
-  "main": "lib"
+  "main": "lib/index.js",
+  "types": "types/index.d.ts"
 }

packages/errors/types/index.d.ts

@@ -0,0 +1,48 @@
+declare module '@dotcom-reliability-kit/errors' {
+	type BaseErrorData = {
+		code?: string;
+		message?: string;
+		cause?: Error | null;
+	} & { [key: string]: any };
+
+	type OperationalErrorData = { relatesToSystems?: string[] } & BaseErrorData;
+
+	type HttpErrorData = { statusCode?: number } & OperationalErrorData;
+
+	export class BaseError extends Error {
+		constructor();
+		constructor(data: BaseErrorData);
+		constructor(message: string, data?: BaseErrorData);
+
+		public override readonly name: string;
+		public readonly isOperational: boolean;
+		public readonly code: string;
+		public readonly cause: Error | null;
+		public readonly data: { [key: string]: any };
+
+		public static isErrorMarkedAsOperational(error: Error): boolean;
+	}
+
+	export class OperationalError extends BaseError {
+		constructor();
+		constructor(data: OperationalErrorData);
+		constructor(message: string, data?: OperationalErrorData);
+
+		public readonly relatesToSystems: string[];
+	}
+
+	export class HttpError extends OperationalError {
+		constructor();
+		constructor(data: HttpErrorData);
+		constructor(message: string, data?: HttpErrorData);
+		constructor(status: number, data?: HttpErrorData);
+
+		public readonly statusCode: number;
+		public readonly statusMessage: string;
+		public readonly status: number;
+	}
+
+	export class DataStoreError extends OperationalError {}
+	export class UpstreamServiceError extends HttpError {}
+	export class UserInputError extends HttpError {}
+}

scripts/clean-generated-types.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 
-find ./packages/errors -name "*.d.ts*" | xargs -r rm
 find ./packages/fetch-error-handler -name "*.d.ts*" | xargs -r rm
 find ./packages/logger -name "*.d.ts*" | xargs -r rm
 find ./packages/middleware-log-errors -name "*.d.ts*" | xargs -r rm