Feat: Handling deprecation events by actual logger (#2035)

`express` uses `depd` for deprecating things.

This library emits a special event on process, and when there is a
listener of that event, it can be handled other way than `stderr`.

https://www.npmjs.com/package/depd#processondeprecation-fn


```
2024-09-13T19:34:38.556Z warn: DeprecationError (express): res.location("back"): use res.location(req.get("Referrer") || "/") and refer to https://dub.sh/security-redirect for best practices [
  '    at file://.../example/config.ts:1:649',
  '    at Layer.handle [as handle_request] (.../node_modules/express/lib/router/layer.js:95:5)',
  '    at next (/.../node_modules/express/lib/router/route.js:149:13)',
  '    at Route.dispatch (/.../node_modules/express/lib/router/route.js:119:3)',
  '    at Layer.handle [as handle_request] (/.../node_modules/express/lib/router/layer.js:95:5)'
]
```

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Version 20
 
+### v20.11.0
+
+- Feat: Handling deprecation events by actual logger
+  - `express` uses `depd` for emitting `deprecation` events when a certain deprecated approach used;
+  - This version installs a listener of that event and delegates it to the `warn` method of your actual logger.
+
 ### v20.10.0
 
 - Feat: Supporting Express 5

package.json

@@ -121,6 +121,7 @@
     "@tsconfig/node18": "^18.2.1",
     "@types/compression": "^1.7.5",
     "@types/cors": "^2.8.14",
+    "@types/depd": "^1.1.36",
     "@types/eslint": "^9.6.0",
     "@types/express": "^4.17.17",
     "@types/express-fileupload": "^1.5.0",

src/server-helpers.ts

@@ -156,3 +156,11 @@ export const makeChildLoggerExtractor =
   (fallback: ActualLogger): ChildLoggerExtractor =>
   (request) =>
     (request as EquippedRequest).res?.locals[metaSymbol]?.logger || fallback;
+
+export const installDeprecationListener = (logger: ActualLogger) =>
+  process.on("deprecation", ({ message, namespace, name, stack }) =>
+    logger.warn(
+      `${name} (${namespace}): ${message}`,
+      stack.split("\n").slice(1),
+    ),
+  );

src/server.ts

@@ -14,19 +14,19 @@ import {
   createParserFailureHandler,
   createUploadParsers,
   makeChildLoggerExtractor,
+  installDeprecationListener,
   moveRaw,
 } from "./server-helpers";
 import { getStartupLogo } from "./startup-logo";
 
 const makeCommonEntities = (config: CommonConfig) => {
-  if (config.startupLogo !== false) {
-    console.log(getStartupLogo());
-  }
+  if (config.startupLogo !== false) console.log(getStartupLogo());
   const errorHandler = config.errorHandler || defaultResultHandler;
   const rootLogger = isLoggerInstance(config.logger)
     ? config.logger
     : new BuiltinLogger(config.logger);
   rootLogger.debug("Running", process.env.TSUP_BUILD || "from sources");
+  installDeprecationListener(rootLogger);
   const loggingMiddleware = createLoggingMiddleware({ rootLogger, config });
   const getChildLogger = makeChildLoggerExtractor(rootLogger);
   const commons = { getChildLogger, errorHandler };
@@ -95,10 +95,7 @@ export const createServer = async (config: ServerConfig, routing: Routing) => {
   const starter = <T extends http.Server | https.Server>(
     server: T,
     subject: typeof config.server.listen,
-  ) =>
-    server.listen(subject, () => {
-      rootLogger.info("Listening", subject);
-    }) as T;
+  ) => server.listen(subject, () => rootLogger.info("Listening", subject)) as T;
 
   const servers = {
     httpServer: starter(http.createServer(app), config.server.listen),

tests/system/system.spec.ts

@@ -1,17 +1,21 @@
 import cors from "cors";
+import depd from "depd";
 import { z } from "zod";
 import {
   EndpointsFactory,
   Method,
   createServer,
   defaultResultHandler,
   ResultHandler,
+  BuiltinLogger,
 } from "../../src";
 import { givePort } from "../helpers";
 
 describe("App", async () => {
   const port = givePort();
 
+  const logger = new BuiltinLogger({ level: "silent" });
+  const warnMethod = vi.spyOn(logger, "warn");
   const routing = {
     v1: {
       corsed: new EndpointsFactory(defaultResultHandler)
@@ -117,14 +121,15 @@ describe("App", async () => {
         }),
     },
   };
-  vi.spyOn(global.console, "log").mockImplementation(vi.fn());
+  vi.spyOn(console, "log").mockImplementation(vi.fn()); // mutes logo output
   const server = (
     await createServer(
       {
         server: {
           listen: port,
           compression: { threshold: 1 },
           beforeRouting: ({ app, getChildLogger }) => {
+            depd("express")("Sample deprecation message");
             app.use((req, {}, next) => {
               const childLogger = getChildLogger(req);
               assert("isChild" in childLogger && childLogger.isChild);
@@ -134,7 +139,7 @@ describe("App", async () => {
         },
         cors: false,
         startupLogo: true,
-        logger: { level: "silent" },
+        logger,
         childLoggerProvider: ({ parent }) =>
           Object.defineProperty(parent, "isChild", { value: true }),
         inputSources: {
@@ -145,6 +150,10 @@ describe("App", async () => {
     )
   ).httpServer;
   await vi.waitFor(() => assert(server.listening), { timeout: 1e4 });
+  expect(warnMethod).toHaveBeenCalledWith(
+    "DeprecationError (express): Sample deprecation message",
+    expect.any(Array), // stack
+  );
 
   afterAll(async () => {
     server.close();
@@ -231,7 +240,6 @@ describe("App", async () => {
         },
       );
       expect(response.status).toBe(200);
-      console.log(response.headers);
       expect(response.headers.get("Content-Encoding")).toBe("gzip");
       const json = await response.json();
       expect(json).toMatchSnapshot();

yarn.lock

@@ -702,6 +702,13 @@
   dependencies:
     "@types/node" "*"
 
+"@types/depd@^1.1.36":
+  version "1.1.36"
+  resolved "https://registry.npmjs.org/@types/depd/-/depd-1.1.36.tgz#7633366ce394e6aa046cedb55e70143e9bca67cd"
+  integrity sha512-+apvfj5Bn6ORfud9XrgoIu6H6s2pTN+X8rQ2LgkA3YUXY+PiXkCJjizh8qxv8CrLtXlxw3NCmYrNbbeckVOQrA==
+  dependencies:
+    "@types/node" "*"
+
 "@types/eslint@^9.6.0":
   version "9.6.1"
   resolved "https://registry.yarnpkg.com/@types/eslint/-/eslint-9.6.1.tgz#d5795ad732ce81715f27f75da913004a56751584"