test: add Nub loader recipe

Author: colinhacks

examples/using-pm2-and-transpilers/README.md

@@ -13,6 +13,32 @@ $ pm2 install typescript
 $ pm2 start http.ts
 ```
 
+### Node with `@nubjs/loader`
+
+Install the loader in the application. Keep PM2 on its normal Node interpreter. The loader needs Node.js 18.19 or later. PM2's daemon and cluster workers use that Node executable.
+
+```sh
+npm install --save-dev @nubjs/loader@0.8.3
+```
+
+Configure `node_args` as an array so PM2 preloads the loader before its fork and cluster containers start:
+
+```js
+module.exports = {
+  apps: [{
+    name: 'api',
+    script: './src/server.ts',
+    interpreter: 'node',
+    node_args: ['--import', '@nubjs/loader'],
+    instances: 2,
+    exec_mode: 'cluster',
+    wait_ready: true,
+  }],
+};
+```
+
+Start the ecosystem file with `pm2 start ecosystem.config.cjs`. PM2 keeps its Node process containers, IPC readiness, reload behavior, and cluster support. The loader does not provision or select a Node version. Retain the application's TypeScript type-check in CI. Do not set `interpreter` to a launcher executable. PM2 treats it as an arbitrary interpreter instead of using its Node containers.
+
 ## Livescript
 
 

package.json

@@ -148,6 +148,7 @@
     "debug": "4.4.3"
   },
   "devDependencies": {
+    "@nubjs/loader": "0.8.3",
     "express": "^4.21.0",
     "mocha": "^11.7.0",
     "should": "^13.2.3"

test/e2e.sh

@@ -17,6 +17,7 @@ runTest ./test/e2e/cli/start-app.sh
 runTest ./test/e2e/cli/operate-regex.sh
 #runTest ./test/e2e/cli/bun.sh
 runTest ./test/e2e/cli/typescript.sh
+runTest ./test/e2e/cli/nub-loader.sh
 runTest ./test/e2e/cli/app-configuration.sh
 runTest ./test/e2e/cli/binary.sh
 runTest ./test/e2e/cli/startOrX.sh

test/e2e/cli/nub-loader.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+
+SRC=$(cd $(dirname "$0"); pwd)
+source "${SRC}/../include.sh"
+
+fixture="$file_path/nub-loader"
+log_file="$fixture/loader.log"
+
+cleanup() {
+  $pm2 delete all >/dev/null 2>&1 || true
+  $pm2 kill >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+pids_for() {
+  $pm2 jlist | $node -e '
+    let input = "";
+    process.stdin.on("data", (chunk) => input += chunk);
+    process.stdin.on("end", () => {
+      console.log(JSON.parse(input)
+        .filter((app) => app.name === "nub-loader-cluster")
+        .map((app) => app.pid)
+        .sort((left, right) => left - right)
+        .join(" "));
+    });
+  '
+}
+
+cd "$fixture"
+> "$log_file"
+
+$pm2 start ecosystem.config.cjs
+should 'should start the TypeScript fork and cluster apps' 'online' 3
+
+expected_node=$($node -p 'process.versions.node')
+grep -F '"mode":"pm2"' "$log_file"
+spec 'Should transform non-erasable TypeScript syntax'
+grep -F "\"cwd\":\"$fixture\"" "$log_file"
+spec 'Should resolve the loader from the application cwd'
+grep -F "\"node\":\"$expected_node\"" "$log_file"
+spec 'Should run workers on the daemon Node version'
+grep -F 'service.ts' "$log_file"
+spec 'Should preserve TypeScript source maps'
+
+old_cluster_pids=$(pids_for)
+[ "$(echo "$old_cluster_pids" | wc -w)" -eq 2 ]
+spec 'Should record both cluster worker PIDs before reload'
+
+PM2_BIN="$pm2" $node <<'NODE'
+const { spawn } = require('child_process');
+const http = require('http');
+
+let failures = 0;
+let pending = 0;
+
+function request() {
+  pending += 1;
+  const request = http.get('http://127.0.0.1:45678', (response) => {
+    if (response.statusCode !== 200)
+      failures += 1;
+    response.resume();
+    response.once('end', () => pending -= 1);
+  });
+  request.setTimeout(1000, () => request.destroy());
+  request.once('error', () => {
+    failures += 1;
+    pending -= 1;
+  });
+}
+
+request();
+const reload = spawn(process.env.PM2_BIN, ['reload', 'nub-loader-cluster'], { stdio: 'inherit' });
+const probes = setInterval(request, 10);
+
+reload.once('close', (code) => {
+  clearInterval(probes);
+  setTimeout(() => {
+    if (code !== 0 || failures > 0 || pending !== 0)
+      process.exit(1);
+  }, 100);
+});
+NODE
+spec 'Should serve requests without interruption during cluster reload'
+
+should 'should keep both TypeScript cluster workers online after reload' 'online' 3
+
+new_cluster_pids=$(pids_for)
+[ "$old_cluster_pids" != "$new_cluster_pids" ]
+spec 'Should replace cluster workers after readiness reload'
+grep -F '"event":"shutdown"' "$log_file"
+spec 'Should deliver graceful shutdown to replaced workers'
+
+$pm2 delete all
+sleep 1
+for pid in $old_cluster_pids $new_cluster_pids; do
+  ! kill -0 "$pid" 2>/dev/null
+done
+spec 'Should not leave replaced cluster workers running'

test/fixtures/nub-loader/ecosystem.config.cjs

@@ -0,0 +1,31 @@
+const path = require('path');
+
+const app = {
+  script: './service.ts',
+  cwd: __dirname,
+  interpreter: 'node',
+  node_args: ['--import', '@nubjs/loader'],
+  wait_ready: true,
+  listen_timeout: 5000,
+  kill_timeout: 1000,
+  env: {
+    PORT: 45678,
+  },
+  merge_logs: true,
+  log_file: path.join(__dirname, 'loader.log'),
+};
+
+module.exports = {
+  apps: [
+    {
+      ...app,
+      name: 'nub-loader-fork',
+    },
+    {
+      ...app,
+      name: 'nub-loader-cluster',
+      instances: 2,
+      exec_mode: 'cluster',
+    },
+  ],
+};

test/fixtures/nub-loader/service.ts

@@ -0,0 +1,26 @@
+const { createServer } = require('node:http');
+
+enum ContainerMode {
+  Pm2 = 'pm2',
+}
+
+const sourceMapFrame = new Error('source map check').stack?.split('\n')[1]?.trim();
+
+console.log(JSON.stringify({
+  event: 'ready',
+  mode: ContainerMode.Pm2,
+  cwd: process.cwd(),
+  node: process.versions.node,
+  sourceMapFrame,
+}));
+
+const server = createServer((_request, response) => {
+  response.end('ok');
+});
+
+process.on('SIGINT', () => {
+  console.log(JSON.stringify({ event: 'shutdown', pid: process.pid }));
+  server.close(() => process.exit(0));
+});
+
+server.listen(Number(process.env.PORT), () => process.send?.('ready'));