fix: add type declarations for serialize-request

.gitignore

@@ -9,7 +9,6 @@ packages/middleware-log-errors/**/*.d.*
 packages/middleware-render-error-info/**/*.d.*
 packages/opentelemetry/**/*.d.*
 packages/serialize-error/**/*.d.*
-packages/serialize-request/**/*.d.*
 coverage
 node_modules/
 resources/logos/dist

jsconfig.build.json

@@ -17,7 +17,6 @@
 		"packages/middleware-log-errors/**/*.js",
 		"packages/middleware-render-error-info/**/*.js",
 		"packages/opentelemetry/**/*.js",
-		"packages/serialize-error/**/*.js",
-		"packages/serialize-request/**/*.js"
+		"packages/serialize-error/**/*.js"
 	]
 }

packages/serialize-request/.npmignore

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

packages/serialize-request/lib/index.js

@@ -1,67 +1,3 @@
-/**
- * @typedef {import('express').Request} ExpressRequest
- */
-
-/**
- * @typedef {import('http').IncomingMessage} HttpIncomingMessage
- */
-
-/**
- * @typedef {object} BasicRequest
- * @property {Headers | {[key: string]: string} | Iterable<[string, string]>} [headers]
- *     The request HTTP headers.
- * @property {string} [method]
- *     The request HTTP method.
- * @property {string} [url]
- *     The request URL.
- */
-
-/**
- * @typedef {BasicRequest & Record<string, any> | ExpressRequest | HttpIncomingMessage & Record<string, any>} Request
- */
-
-/**
- * @typedef {object} SerializeRequestOptions
- * @property {string[]} [includeHeaders]
- *     An array of request headers to include.
- */
-
-/**
- * @typedef {{[key: string]: string}} SerializedRequestHeaders
- */
-
-/**
- * @typedef {{[key: string]: string}} SerializedRequestRouteParams
- */
-
-/**
- * @typedef {object} SerializedRequestRoute
- * @property {string} path
- *     The route path which the request object was matched by.
- * @property {SerializedRequestRouteParams} params
- *     The parameters which were matched in the request path.
- */
-
-/**
- * @typedef {object} SerializedRequest
- * @property {(string|null)} id
- *     A unique identifier for the request.
- * @property {string} method
- *     The HTTP method for the request.
- * @property {string} url
- *     The full path and querystring of the resource being requested.
- * @property {SerializedRequestHeaders} headers
- *     A subset of HTTP headers which came with the request.
- * @property {SerializedRequestRoute} [route]
- *     The express route details.
- */
-
-/**
- * The default request headers to include in the serialization.
- *
- * @public
- * @type {string[]}
- */
 const DEFAULT_INCLUDED_HEADERS = [
 	'accept',
 	'accept-encoding',
@@ -73,24 +9,15 @@ const DEFAULT_INCLUDED_HEADERS = [
 
 /**
  * The maximum length of a URL, any longer than this will be truncated.
- *
- * @private
- * @type {number}
  */
 const URL_TRUNCATION_LENGTH = 200;
 
 /**
  * Serialize a request object so that it can be consistently logged or output as JSON.
  *
- * @public
- * @param {string | Request} request
- *     The request object to serialize. Either an Express Request object, a
- *     built-in Node.js IncomingMessage object, or an object with the expected
- *     `headers`, `method`, and `url` properties.
- * @param {SerializeRequestOptions} [options]
- *     Options to configure the serialization.
- * @returns {SerializedRequest}
- *     Returns the serialized request object.
+ * @param {import('@dotcom-reliability-kit/serialize-request').Request} request
+ * @param {import('@dotcom-reliability-kit/serialize-request').SerializeRequestOptions} options
+ * @returns {import('@dotcom-reliability-kit/serialize-request').SerializedRequest}
  */
 function serializeRequest(request, options = {}) {
 	// If the request is not an object, assume it's the request
@@ -168,13 +95,9 @@ function serializeRequest(request, options = {}) {
 /**
  * Serialize request headers.
  *
- * @private
- * @param {Headers | Record<string, any> | Iterable<[string, string]>} headers
- *     The headers object to serialize.
+ * @param {import('@dotcom-reliability-kit/serialize-request').RequestHeaders} headers
  * @param {string[]} includeHeaders
- *     An array of request headers to include.
- * @returns {SerializedRequestHeaders}
- *     Returns the serialized request headers.
+ * @returns {import('@dotcom-reliability-kit/serialize-request').SerializedRequestHeaders}
  */
 function serializeHeaders(headers, includeHeaders) {
 	const headersObject = {};
@@ -199,11 +122,8 @@ function serializeHeaders(headers, includeHeaders) {
 /**
  * Create a new serialized request object.
  *
- * @private
- * @param {Record<string, any>} properties
- *     The properties of the serialized error.
- * @returns {SerializedRequest}
- *     Returns the serialized error object.
+ * @param {{[key: string]: any}} properties
+ * @returns {import('@dotcom-reliability-kit/serialize-request').SerializedRequest}
  */
 function createSerializedRequest(properties) {
 	return Object.assign(
@@ -219,16 +139,17 @@ function createSerializedRequest(properties) {
 }
 
 /**
+ * Check whether a value is an iterable request headers object.
+ *
  * @param {any} value
- *     The value to test.
  * @returns {value is Iterable<[string, string]>}
- *     Returns whether a value is iterable.
  */
 function isIterableHeadersObject(value) {
 	return value && typeof value?.[Symbol.iterator] === 'function';
 }
 
 module.exports = serializeRequest;
+module.exports.default = module.exports;
 
 // We freeze this object so that we avoid any side-effects
 // introduced by the way Node.js caches modules. If this
@@ -238,6 +159,3 @@ module.exports = serializeRequest;
 module.exports.DEFAULT_INCLUDED_HEADERS = Object.freeze([
 	...DEFAULT_INCLUDED_HEADERS
 ]);
-
-// @ts-ignore
-module.exports.default = module.exports;

packages/serialize-request/package.json

@@ -14,7 +14,8 @@
     "node": "18.x || 20.x",
     "npm": "8.x || 9.x || 10.x"
   },
-  "main": "lib",
+  "main": "lib/index.js",
+  "types": "types/index.d.ts",
   "devDependencies": {
     "@types/express": "^4.17.21"
   }

packages/serialize-request/types/index.d.ts

@@ -0,0 +1,47 @@
+declare module '@dotcom-reliability-kit/serialize-request' {
+	export type SerializeRequestOptions = {
+		includeHeaders?: string[];
+	};
+
+	export type RequestHeaders =
+		| Headers
+		| { [key: string]: string }
+		| Iterable<[string, string]>
+		| import('http').IncomingHttpHeaders;
+
+	type BasicRequest = {
+		headers?: RequestHeaders;
+		method?: string;
+		url?: string;
+	};
+	type ExpressRequest = import('express').Request;
+	type NodeHttpRequest = import('http').IncomingMessage;
+
+	export type Request =
+		| (BasicRequest & { [key: string]: any })
+		| ExpressRequest
+		| (NodeHttpRequest & { [key: string]: any });
+
+	export type SerializedRequest = {
+		id: string | null;
+		method: string;
+		url: string;
+		headers: SerializedRequestHeaders;
+		route?: SerializedRequestRoute;
+	};
+	export type SerializedRequestHeaders = { [key: string]: string };
+	export type SerializedRequestRouteParams = { [key: string]: string };
+	export type SerializedRequestRoute = {
+		path: string;
+		params: SerializedRequestRouteParams;
+	};
+
+	export default function serializeRequest(
+		request: string | Request,
+		options?: SerializeRequestOptions
+	): SerializedRequest;
+
+	export const DEFAULT_INCLUDED_HEADERS: readonly string[];
+
+	export = serializeRequest;
+}

scripts/clean-generated-types.sh

@@ -10,4 +10,3 @@ find ./packages/middleware-log-errors -name "*.d.ts*" | xargs -r rm
 find ./packages/middleware-render-error-info -name "*.d.ts*" | xargs -r rm
 find ./packages/opentelemetry -name "*.d.ts*" | xargs -r rm
 find ./packages/serialize-error -name "*.d.ts*" | xargs -r rm
-find ./packages/serialize-request -name "*.d.ts*" | xargs -r rm

test/modules/js-esm-sucrase/index.js

@@ -40,10 +40,6 @@ new Logger({
 // Test that error and request serialization works.
 // See: https://github.com/Financial-Times/cp-content-pipeline/blob/90ce06158b65742cd03cbf03f5372790906cad9e/packages/api/src/plugins/logging.ts#L1-L3
 serializeError(new Error('hi'));
-
-// @ts-ignore TODO this isn't working correctly and we'll need
-// to rethink the way we build our type definitions in order to
-// support TypeScript written as ESM properly.
 serializeRequest({ url: 'https://example.com' });
 
 console.log('OK');

test/modules/js-esm-uncompiled/index.js

@@ -40,10 +40,6 @@ new Logger({
 // Test that error and request serialization works.
 // See: https://github.com/Financial-Times/cp-content-pipeline/blob/90ce06158b65742cd03cbf03f5372790906cad9e/packages/api/src/plugins/logging.ts#L1-L3
 serializeError(new Error('hi'));
-
-// @ts-ignore TODO this isn't working correctly and we'll need
-// to rethink the way we build our type definitions in order to
-// support TypeScript written as ESM properly.
 serializeRequest({ url: 'https://example.com' });
 
 console.log('OK');

test/modules/ts-esm-interop/index.ts

@@ -38,10 +38,6 @@ new Logger({
 // Test that error and request serialization works.
 // See: https://github.com/Financial-Times/cp-content-pipeline/blob/90ce06158b65742cd03cbf03f5372790906cad9e/packages/api/src/plugins/logging.ts#L1-L3
 serializeError(new Error('hi'));
-
-// @ts-ignore TODO this isn't working correctly and we'll need
-// to rethink the way we build our type definitions in order to
-// support TypeScript written as ESM properly.
 serializeRequest({ url: 'https://example.com' });
 
 console.log('OK');

test/modules/ts-esm-nointerop/index.ts

@@ -38,10 +38,6 @@ new Logger({
 // Test that error and request serialization works.
 // See: https://github.com/Financial-Times/cp-content-pipeline/blob/90ce06158b65742cd03cbf03f5372790906cad9e/packages/api/src/plugins/logging.ts#L1-L3
 serializeError(new Error('hi'));
-
-// @ts-ignore TODO this isn't working correctly and we'll need
-// to rethink the way we build our type definitions in order to
-// support TypeScript written as ESM properly.
 serializeRequest({ url: 'https://example.com' });
 
 console.log('OK');