feat: export addToRepl function that will cause load into repl

Author: djMax

__tests__/fake-serv/src/handlers/hello.ts

@@ -1,4 +1,4 @@
-import { ServiceHandler } from '../../../../src/index';
+import { addToRepl, ServiceHandler } from '../../../../src/index';
 import { FakeServLocals } from '../index';
 
 export const get: ServiceHandler<FakeServLocals> = async (req, res) => {
@@ -8,3 +8,9 @@ export const get: ServiceHandler<FakeServLocals> = async (req, res) => {
 export const post: ServiceHandler<FakeServLocals> = async (req, res) => {
   res.sendStatus(204);
 };
+
+export function thisIsATest() {
+  return 'Yes, true';
+}
+
+addToRepl(thisIsATest);

package.json

@@ -62,25 +62,25 @@
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-prometheus": "^0.53.0",
     "@opentelemetry/instrumentation-dns": "^0.39.0",
-    "@opentelemetry/instrumentation-express": "^0.42.0",
+    "@opentelemetry/instrumentation-express": "^0.43.0",
     "@opentelemetry/instrumentation-generic-pool": "^0.39.0",
     "@opentelemetry/instrumentation-graphql": "^0.43.0",
     "@opentelemetry/instrumentation-http": "^0.53.0",
     "@opentelemetry/instrumentation-ioredis": "^0.43.0",
     "@opentelemetry/instrumentation-net": "^0.39.0",
-    "@opentelemetry/instrumentation-pg": "^0.44.0",
+    "@opentelemetry/instrumentation-pg": "^0.45.1",
     "@opentelemetry/instrumentation-pino": "^0.42.0",
     "@opentelemetry/instrumentation-undici": "^0.6.0",
-    "@opentelemetry/resource-detector-container": "^0.4.1",
-    "@opentelemetry/resource-detector-gcp": "^0.29.11",
+    "@opentelemetry/resource-detector-container": "^0.4.3",
+    "@opentelemetry/resource-detector-gcp": "^0.29.12",
     "@opentelemetry/sdk-node": "^0.53.0",
     "@opentelemetry/semantic-conventions": "^1.27.0",
     "@sesamecare-oss/confit": "^2.2.1",
     "@sesamecare-oss/opentelemetry-node-metrics": "^1.1.0",
     "ajv": "^8.17.1",
-    "cookie-parser": "^1.4.6",
+    "cookie-parser": "^1.4.7",
     "dotenv": "^16.4.5",
-    "express": "^5.0.0",
+    "express": "^5.0.1",
     "express-openapi-validator": "^5.3.7",
     "glob": "^8.1.0",
     "lodash": "^4.17.21",
@@ -95,29 +95,29 @@
     "@openapi-typescript-infra/coconfig": "^4.4.0",
     "@semantic-release/commit-analyzer": "^13.0.0",
     "@semantic-release/exec": "^6.0.3",
-    "@semantic-release/github": "^10.3.5",
+    "@semantic-release/github": "^11.0.0",
     "@semantic-release/release-notes-generator": "^14.0.1",
     "@types/cookie-parser": "^1.4.7",
-    "@types/express": "^4.17.21",
+    "@types/express": "^5.0.0",
     "@types/glob": "^8.1.0",
-    "@types/lodash": "^4.17.7",
+    "@types/lodash": "^4.17.10",
     "@types/minimist": "^1.2.5",
-    "@types/node": "^20.16.5",
+    "@types/node": "^20.16.11",
     "@types/request-ip": "^0.0.41",
     "@types/supertest": "^6.0.2",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
     "coconfig": "^1.5.2",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-import": "^2.30.0",
+    "eslint-plugin-import": "^2.31.0",
     "pino-pretty": "^11.2.2",
     "pinst": "^3.0.0",
     "supertest": "^7.0.0",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.1"
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.2"
   },
   "resolutions": {
     "qs": "^6.11.0"

src/bin/start-service.ts

@@ -19,9 +19,9 @@ const noTelemetry = (argv.repl || isDev()) && !argv.telemetry;
 bootstrap({
   ...argv,
   telemetry: !noTelemetry,
-}).then(({ app, server }) => {
+}).then(({ app, codepath, server }) => {
   if (argv.repl) {
-    serviceRepl(app, () => {
+    serviceRepl(app, codepath, () => {
       server?.close();
     });
   }

src/bootstrap.ts

@@ -129,5 +129,5 @@ export async function bootstrap<
   const { startApp, listen } = await import('./express-app/app.js');
   const app = await startApp<SLocals, RLocals>(opts);
   const server = argv?.nobind ? undefined : await listen(app);
-  return { server, app };
+  return { server, app, codepath };
 }

src/development/repl.ts

@@ -1,11 +1,15 @@
-import repl from 'repl';
+import repl, { REPLServer } from 'repl';
+import fs from 'fs';
 import path from 'path';
 
+import { glob } from 'glob';
+
 import { AnyServiceLocals, ServiceExpress, ServiceLocals } from '../types';
 import { ConfigurationSchema } from '../config/schema';
 
 export function serviceRepl<SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>>(
   app: ServiceExpress<SLocals>,
+  codepath: string | undefined,
   onExit: () => void,
 ) {
   const rl = repl.start({
@@ -25,5 +29,66 @@ export function serviceRepl<SLocals extends AnyServiceLocals = ServiceLocals<Con
     }
   });
   app.locals.service.attachRepl?.(app, rl);
+
+  loadReplFunctions(app, codepath, rl);
+
   rl.on('exit', onExit);
 }
+
+function loadReplFunctions<SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>>(
+  app: ServiceExpress<SLocals>,
+  codepath: string | undefined,
+  rl: REPLServer,
+) {
+  if (!codepath) {
+    return;
+  }
+
+  const files = glob.sync(path.join(codepath, '**/*.{js,ts}'));
+
+  files.forEach((file) => {
+    try {
+      // Read the file content as text
+      const fileContent = fs.readFileSync(file, 'utf-8');
+
+      // Check if @repl is present
+      if (/addToRepl\(/.test(fileContent)) {
+        // eslint-disable-next-line global-require, import/no-dynamic-require, @typescript-eslint/no-var-requires
+        const module = require(file); // Only require if @repl is found
+
+        // Look for functions with the __isReplFunction marker
+        Object.values(module).forEach((exported) => {
+          if (!exported) {
+            return;
+          }
+          if (typeof exported === 'function' || typeof exported === 'object') {
+            const obj = exported as Record<string, unknown>;
+            for (const key of Object.keys(obj)) {
+              if ((obj[key] as { __openApiServiceReplFunction?: boolean }).__openApiServiceReplFunction) {
+                const fn = obj[key] as (app: ServiceExpress<SLocals>, ...args: unknown[]) => unknown;
+                rl.context[key] = (...args: unknown[]) => fn(app, ...args);
+              }
+            }
+          }
+        });
+      }
+    } catch (err) {
+      console.error(`Failed to load REPL functions from ${file}:`, err);
+    }
+  });
+}
+
+/**
+ * This decorator-like function can be applied to functions and the service will load and expose
+ * the function when the repl is engaged.
+ */
+export function addToRepl<SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>>(
+  fn: (app: ServiceExpress<SLocals>, ...args: unknown[]) => unknown,
+  name?: string,
+) {
+  const functionName = name || fn.name;
+  if (!functionName) {
+    throw new Error('Function must have a name or a name must be provided.');
+  }
+  (fn as unknown as { __openApiServiceReplFunction: string }).__openApiServiceReplFunction = functionName;
+}

src/index.ts

@@ -6,3 +6,4 @@ export * from './config';
 export * from './error';
 export * from './bootstrap';
 export * from './hook';
+export { addToRepl } from './development/repl';

src/telemetry/index.ts

@@ -123,5 +123,5 @@ export async function startWithTelemetry<
     await shutdownGlobalTelemetry();
     app.locals.logger.info('OpenTelemetry shut down');
   });
-  return { app, server };
+  return { app, codepath: options.codepath, server };
 }