@servicelabsco/nestjs-utility-services 3.0.19 → 4.0.0

package/docs/upgrade-4.0.md

@@ -0,0 +1,215 @@
+# Upgrading to 4.x — NestJS 12
+
+`@servicelabsco/nestjs-utility-services` **4.0.0** moves the package to NestJS 12, Node 24.15+, Sentry 11,
+BullMQ 6 and ioredis 6. TypeORM stays on 0.3, so entities, queries and migrations do not change.
+
+It is a major release because `@nestjs/*` are regular dependencies of this package, not peers: an app that
+installs 4.x while it is still on NestJS 11 ends up with two copies of `@nestjs/core` and fails at runtime
+(DI tokens and `instanceof HttpException` stop matching). Apps on `^3` never pick up 4.x by themselves.
+
+The full list of changes is in [CHANGELOG.md](../CHANGELOG.md). This guide covers only what a consuming
+app has to do, and was checked against every repo on `^3` (October 2026).
+
+---
+
+## Upgrade order
+
+1. **`@servicelabsco/nestjs-utility-services` 4.0.0** is published.
+2. **`@servicelabsco/slabs-access-manager`** and **`@servicelabsco/slabs-utility-services`** release a
+   new major on nu 4 and NestJS 12, following this guide.
+3. **Apps.** An app that depends on `slabs-access-manager` must take its new major in the same change
+   as nu 4, or it gets two copies of NestJS.
+
+| Repo | Depends on slabs-access-manager | Can upgrade |
+| --- | --- | --- |
+| fn-kms-services | no | after step 1 |
+| fn-ar-services, fn-arc-services, fn-expense-services, fn-expense-services-processors, fn-meta-services, fn-pay-services | yes | after step 2 |
+
+Repos still on nu `^1.x` (fn-banking-services, fn-webhook-services, icici-demo-services,
+sl-webhook-consumer, sl-communication-services) are not affected.
+
+---
+
+## Required changes
+
+Without these the app fails to install, build, test or boot.
+
+### 1. NestJS 12 everywhere
+
+Move every `@nestjs/*` dependency to `^12` in the same commit as nu 4:
+
+```jsonc
+"@nestjs/common": "^12.3.2",
+"@nestjs/core": "^12.3.2",
+"@nestjs/testing": "^12.3.2",        // devDependency
+"@nestjs/cli": "^12.0.11",           // devDependency
+"@nestjs/schematics": "^12.0.12",    // devDependency
+"@nestjs/typeorm": "^12.0.2",        // if listed
+"@nestjs/websockets": "^12.3.2",     // if listed
+"@nestjs/axios": "^12.0.1",          // 4.x does not support NestJS 12
+"@nestjs/cache-manager": "^12.0.2"   // 3.x does not support NestJS 12
+```
+
+Check that nothing pulls in a second copy:
+
+```bash
+npm ls @nestjs/core @nestjs/common    # every entry should be 12.x and deduped
+```
+
+Do not import from inside a package (`@nestjs/common/dist/...`); NestJS 12 packages only expose their
+public entry points.
+
+### 2. Jest runs with `--experimental-vm-modules`
+
+NestJS 12 packages are ES modules. Jest can only load them with this flag; without it every test file
+that imports `@nestjs/*` fails with `Must use import to load ES Module`.
+
+```jsonc
+"test": "node --experimental-vm-modules --disable-warning=ExperimentalWarning node_modules/jest/bin/jest.js",
+"test:cov": "node --experimental-vm-modules --disable-warning=ExperimentalWarning node_modules/jest/bin/jest.js --coverage"
+```
+
+Keep any existing flags (`--ci`, `--runInBand`, `--forceExit`).
+
+### 3. Remove `source-map-support`
+
+`main.ts` / `worker.ts` import `source-map-support`, but apps never listed it: it came with nu, and nu 4
+no longer depends on it. Delete these lines:
+
+```ts
+import 'source-map-support/register';
+require('source-map-support').install();
+```
+
+and let Node map stack traces instead:
+
+```jsonc
+"start:prod": "node --enable-source-maps dist/main",
+"start:worker": "node --enable-source-maps dist/worker"
+```
+
+In a Dockerfile, put the flag in `CMD` (or set `NODE_OPTIONS=--enable-source-maps`).
+
+### 4. Replace the `redis` socket.io adapter (fn-expense-services, fn-expense-services-processors)
+
+`src/common/adapters/redis.io.adapter.ts` imports `createClient` from `redis`, which also only came with
+nu. Delete the file and use nu's adapter, which has the same methods and connects with ioredis using the
+app's `REDIS_*` settings:
+
+```ts
+import { RedisIoAdapter } from '@servicelabsco/nestjs-utility-services';
+
+const redisIoAdapter = new RedisIoAdapter(app);
+await redisIoAdapter.connectToRedis();
+app.useWebSocketAdapter(redisIoAdapter);
+```
+
+### 5. Node `^24.15`
+
+```jsonc
+"engines": { "node": "^24.15.0" }
+```
+
+The Docker images already qualify (`node:24.19.0-alpine`, `node:24.16.0-alpine`). Update `.nvmrc` and
+local machines: yarn refuses to install nu 4 on an older Node.
+
+---
+
+## Recommended changes
+
+These do not break the app, but it does not behave as intended until they are made.
+
+### Sentry: initialise before anything else loads
+
+Every app has an `src/instrument.ts` that imports `initSentry` from the package. Importing the package
+loads NestJS, Postgres, ioredis and BullMQ before Sentry starts, so none of them are instrumented. Make
+this the **first line** of `main.ts` and `worker.ts`, and delete `src/instrument.ts`:
+
+```ts
+import '@servicelabsco/nestjs-utility-services/dist/instrument';
+```
+
+Do not preload Sentry with `node --require`; Sentry 11 does not support it. Apps that call
+`Sentry.init` themselves must set `dataCollection` as nu does; see
+[sentry-reporting.md](sentry-reporting.md).
+
+### Middleware routes: Express 5 wildcards
+
+`forRoutes({ path: 'api/*' })` still works but logs a deprecation warning per route. Use the named
+wildcard:
+
+```ts
+consumer.apply(RestrictedMiddleware).forRoutes({ path: 'api/{*path}', method: RequestMethod.ALL });
+consumer.apply(InternalMiddleware).forRoutes({ path: 'internal/{*path}', method: RequestMethod.ALL });
+```
+
+Applies to slabs-access-manager, slabs-utility-services, fn-arc, fn-expense, fn-expense-processors,
+fn-kms and fn-meta (`api/*`, `internal/*`, `vendor/*`, `tally/*`).
+
+---
+
+## Behaviour changes to know about
+
+| Change | Effect | Action |
+| --- | --- | --- |
+| BullMQ 6 counts paused jobs as `waiting` | `QueueService.getQueueStats()` no longer returns `paused`, so the `queue` endpoints in each `app.controller.ts` lose that field | Only matters if a dashboard reads it |
+| `QueueService.pause()` returns without waiting for running jobs | The worker stops taking new jobs at once; running jobs carry on and still finish on shutdown | Call `pause(true)` to wait, never from inside a job |
+| BullMQ 6 removes legacy repeatable jobs | A `repeat` option on a job silently creates a one-off job | None found in the apps; use job schedulers if one is added |
+| ioredis 6 speaks RESP3 by default | A managed Redis or proxy that mishandles `HELLO` refuses the connection | Try each environment once, or set `protocol: 2` |
+| ioredis 6 reconnect timing | Cache calls fail after about 0.35–1 s of Redis outage | Set `retryStrategy` if the old timing is needed |
+| nodemailer 9+ verifies TLS when fetching attachment URLs | Attachments on self-signed or internal hosts fail to send; S3 / R2 are fine | Send file content instead of a URL |
+| dotenv 18 drops `.env.vault` and `dotenv_config_*` CLI arguments | Deployments that relied on either lose those values silently | Check deploy scripts |
+| NestJS 12 lifecycle hooks | Hooks in one module run one dependency level at a time instead of all at once | Only matters if a hook relied on another finishing first |
+| NestJS 12 errors | A plain `Error` with a `statusCode` property is now a 500 | Throw nu's exceptions (`OperationException`, …) |
+
+New in 4.0 and optional: `CommonDirectUploadController` / `DirectUploadService` for direct S3 / R2
+uploads (needs the `sys_upload_sessions` migration, which runs with the others),
+`BULL_QUEUE_CONCURRENCY`, and `ServicelabsUtilityService` / `CommonServicelabsCallbackController` for the
+ServiceLabs utilities API. Setting `servicelabs.api.key` moves `PdfService`, `SplitPdfService` and
+`ZipService` off the Lambda URLs with no code change; see
+[servicelabs-utilities.md](servicelabs-utilities.md).
+
+---
+
+## No change needed
+
+- **TypeScript and tsconfig.** nu 4 compiles in the apps' current setup — TypeScript 5.9,
+  `module: commonjs`, `moduleResolution: node`, target ES2021 — including NestJS 12, dotenv 18 and
+  BullMQ 6. If you raise `target` to ES2022 or later, also set `useDefineForClassFields: false`, or
+  TypeORM columns and injected properties break.
+- **TypeORM.** Still 0.3; no entity, query or migration changes.
+- **Database.** One new table, `sys_upload_sessions`, from nu's migrations.
+- **APIs the apps do not use.** `Queue#client`, repeatable jobs, `JobConsumer.setWorker`,
+  `SentryContext.enrichHttpScope`, `getSignedUploadUrl` and deep `@nestjs/*` imports changed, but no
+  app uses them.
+
+---
+
+## Per-repo checklist
+
+| Repo | NestJS 12 | Jest flag | source-map-support | redis adapter | engines | Sentry import | Wildcards |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| slabs-access-manager | ✔ (+ `@nestjs/typeorm`) | ✔ | ✔ | — | ✔ | ✔ | ✔ |
+| slabs-utility-services | ✔ (+ `@nestjs/typeorm`) | ✔ | ✔ | — | ✔ | ✔ | ✔ |
+| fn-kms-services | ✔ | ✔ | ✔ | — | ✔ | ✔ | ✔ |
+| fn-ar-services | ✔ (+ axios, cache-manager) | ✔ | ✔ | — | ✔ | ✔ | — |
+| fn-arc-services | ✔ | ✔ | ✔ | — | ✔ | ✔ | ✔ |
+| fn-expense-services | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| fn-expense-services-processors | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| fn-meta-services | ✔ | ✔ | ✔ | — | ✔ | ✔ | ✔ |
+| fn-pay-services | ✔ (+ axios, cache-manager) | ✔ | ✔ | — | ✔ | ✔ | — |
+
+✔ = change needed, — = not applicable.
+
+## Verify after upgrading
+
+```bash
+npm ls @nestjs/core          # one copy, 12.x
+yarn build
+yarn test
+yarn start:prod              # boots, routes map, no "Nest can't resolve dependencies"
+curl localhost:$PORT/health  # postgres, read replica and redis "up"
+```
+
+Then start the worker (`BULL_QUEUE_WORKER=true`), dispatch a job and confirm it is processed, and
+confirm Sentry receives a test error from both the API and the worker.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicelabsco/nestjs-utility-services",
-    "version": "3.0.19",
+    "version": "4.0.0",
     "description": "NestJS generic packages to support development",
     "author": "Hemant Kumar Sah <hemantanshu@gmail.com>",
     "license": "MIT",
@@ -12,7 +12,9 @@
         "CHANGELOG.md",
         "LICENSE",
         "docs/sentry-reporting.md",
+        "docs/servicelabs-utilities.md",
         "docs/upgrade-3.0-backward-compatibility.md",
+        "docs/upgrade-4.0.md",
         "docs/subscribe-for.md"
     ],
     "types": "dist/index.d.ts",
@@ -22,19 +24,20 @@
         "start": "nest start",
         "start:dev": "nest start --watch",
         "start:debug": "nest start --debug --watch",
-        "start:prod": "node dist/main",
+        "start:prod": "node --enable-source-maps dist/main",
         "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
         "lint:codebase": "ts-node --project scripts/tsconfig.json scripts/lint-codebase.ts",
-        "test": "jest",
-        "test:watch": "jest --watch",
-        "test:cov": "jest --coverage",
-        "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
-        "test:e2e": "jest --config ./test/jest-e2e.json",
+        "test": "node --experimental-vm-modules --disable-warning=ExperimentalWarning node_modules/jest/bin/jest.js",
+        "test:watch": "node --experimental-vm-modules --disable-warning=ExperimentalWarning node_modules/jest/bin/jest.js --watch",
+        "test:cov": "node --experimental-vm-modules --disable-warning=ExperimentalWarning node_modules/jest/bin/jest.js --coverage",
+        "test:debug": "node --inspect-brk --experimental-vm-modules --disable-warning=ExperimentalWarning node_modules/jest/bin/jest.js --runInBand",
+        "test:e2e": "node --experimental-vm-modules --disable-warning=ExperimentalWarning node_modules/jest/bin/jest.js --config ./test/jest-e2e.json",
         "typeorm": "typeorm-ts-node-commonjs --config src/config/orm.config.ts",
         "m:g": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:generate -d src/config/orm.config.ts",
         "m:r": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:run -d src/config/orm.config.ts",
         "m:rd": "./node_modules/.bin/typeorm migration:run -d dist/config/orm.config.js",
-        "m:c": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:create -d src/config/orm.config.ts",
+        "m:c": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:create",
         "m:rev": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:revert -d src/config/orm.config.ts",
         "runtime-check": "curl -s http://localhost:${SERVER_PORT:-4000}/health/runtime-check | jq . 2>/dev/null || curl -s http://localhost:${SERVER_PORT:-4000}/health/runtime-check",
         "verify:publish": "node scripts/verify-publish-artifacts.js",
@@ -48,7 +51,7 @@
         "nestjs"
     ],
     "engines": {
-        "node": "^24.11.0"
+        "node": "^24.15.0"
     },
     "publishConfig": {
         "access": "public"
@@ -59,81 +62,72 @@
     },
     "bugs": "https://github.com/servicelabsco/nestjs-utility-services",
     "dependencies": {
-        "@aws-sdk/client-dynamodb": "^3.971.0",
-        "@aws-sdk/client-s3": "^3.971.0",
-        "@aws-sdk/client-secrets-manager": "^3.971.0",
-        "@aws-sdk/client-ses": "^3.971.0",
-        "@aws-sdk/client-sqs": "^3.971.0",
-        "@aws-sdk/lib-storage": "^3.971.0",
-        "@aws-sdk/s3-request-presigner": "^3.971.0",
-        "@aws-sdk/util-dynamodb": "^3.971.0",
-        "@nestjs-modules/ioredis": "^2.0.2",
-        "@nestjs/bullmq": "^11.0.0",
-        "@nestjs/common": "^11.0.0",
-        "@nestjs/config": "^4.0.2",
-        "@nestjs/core": "^11.0.0",
-        "@nestjs/jwt": "^11.0.0",
-        "@nestjs/platform-express": "^11.0.0",
-        "@nestjs/platform-socket.io": "^11.0.0",
-        "@nestjs/terminus": "^11.0.0",
-        "@nestjs/typeorm": "^11.0.0",
-        "@nestjs/websockets": "^11.0.0",
-        "@sentry/core": "^10.34.0",
-        "@sentry/nestjs": "^10.34.0",
-        "@sentry/node": "^10.34.0",
-        "@socket.io/redis-adapter": "^8.2.1",
-        "axios": "^1.7.9",
+        "@aws-sdk/client-dynamodb": "^3.1160.0",
+        "@aws-sdk/client-s3": "^3.1160.0",
+        "@aws-sdk/client-secrets-manager": "^3.1160.0",
+        "@aws-sdk/client-ses": "^3.1160.0",
+        "@aws-sdk/client-sqs": "^3.1160.0",
+        "@aws-sdk/lib-storage": "^3.1160.0",
+        "@aws-sdk/s3-request-presigner": "^3.1160.0",
+        "@aws-sdk/util-dynamodb": "^3.996.9",
+        "@nestjs-modules/ioredis": "^2.3.1",
+        "@nestjs/bullmq": "^12.0.0",
+        "@nestjs/common": "^12.3.2",
+        "@nestjs/config": "^12.0.1",
+        "@nestjs/core": "^12.3.2",
+        "@nestjs/jwt": "^12.0.3",
+        "@nestjs/platform-express": "^12.3.2",
+        "@nestjs/platform-socket.io": "^12.3.2",
+        "@nestjs/terminus": "^12.1.0",
+        "@nestjs/typeorm": "^12.0.2",
+        "@nestjs/websockets": "^12.3.2",
+        "@sentry/nestjs": "^11.10.0",
+        "@socket.io/redis-adapter": "^8.3.0",
+        "axios": "^1.21.0",
         "bcryptjs": "^3.0.3",
-        "bullmq": "^5.66.5",
+        "bullmq": "^6.5.1",
         "class-transformer": "^0.5.1",
         "class-validator": "^0.15.1",
-        "cron-parser": "^5.5.0",
-        "date-fns": "^4.1.0",
+        "cron-parser": "^5.10.2",
+        "date-fns": "^4.4.0",
         "decimal.js": "^10.6.0",
-        "dotenv": "^17.2.3",
+        "dotenv": "^18.0.9",
         "exceljs": "^4.4.0",
+        "express": "^5.2.1",
         "express-http-context2": "^1.0.0",
-        "express-rate-limit": "^8.2.1",
-        "handlebars": "^4.7.8",
-        "helmet": "^8.1.0",
-        "html-to-text": "^10.0.0",
-        "ioredis": "^5.9.2",
-        "mongodb": "^7.1.0",
-        "nodemailer": "^8.0.2",
-        "pg": "^8.17.1",
-        "redis": "^5.10.0",
+        "express-rate-limit": "^8.7.2",
+        "handlebars": "^4.7.10",
+        "helmet": "^8.3.0",
+        "html-to-text": "^10.0.1",
+        "ioredis": "^6.0.0",
+        "mongodb": "^7.7.0",
+        "nodemailer": "^10.3.1",
+        "pg": "^8.23.1",
         "reflect-metadata": "^0.2.2",
-        "rxjs": "^7.8.1",
-        "socket.io": "^4.8.3",
-        "source-map-support": "^0.5.21",
-        "typeorm": "^0.3.28",
+        "rxjs": "^7.8.2",
+        "socket.io-adapter": "~2.5.8",
+        "typeorm": "^0.3.31",
         "typeorm-naming-strategies": "^4.1.0",
         "xxhash-wasm": "^1.1.0"
     },
     "devDependencies": {
-        "@nestjs/cli": "^11.0.0",
-        "@nestjs/schematics": "^11.0.0",
-        "@nestjs/testing": "^11.0.0",
-        "@types/express": "^5.0.0",
+        "@nestjs/cli": "^12.0.11",
+        "@nestjs/schematics": "^12.0.12",
+        "@nestjs/testing": "^12.3.2",
+        "@types/express": "^5.0.6",
         "@types/html-to-text": "^9.0.4",
         "@types/jest": "^30.0.0",
-        "@types/multer": "^2.0.0",
-        "@types/node": "^24.11.0",
-        "@types/supertest": "^7.2.0",
-        "@typescript-eslint/eslint-plugin": "^8.53.0",
-        "@typescript-eslint/parser": "^8.53.0",
-        "eslint": "^10.4.0",
+        "@types/node": "^24.19.2",
+        "@typescript-eslint/eslint-plugin": "^8.72.1",
+        "@typescript-eslint/parser": "^8.72.1",
+        "eslint": "^10.13.0",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-prettier": "^5.5.5",
-        "jest": "^30.2.0",
-        "js-yaml": "^4.1.1",
-        "prettier": "^3.8.0",
-        "supertest": "^7.2.2",
-        "ts-jest": "^29.4.6",
-        "ts-loader": "^9.4.3",
-        "ts-node": "^10.9.1",
-        "tsconfig-paths": "^4.2.0",
-        "typescript": "^6.0.3"
+        "eslint-plugin-prettier": "^5.5.7",
+        "jest": "^30.5.2",
+        "prettier": "^3.9.10",
+        "ts-jest": "^29.4.15",
+        "ts-node": "^10.9.2",
+        "typescript": "~6.0.3"
     },
     "jest": {
         "moduleFileExtensions": [
@@ -144,15 +138,17 @@
         "rootDir": "src",
         "testRegex": ".*\\.spec\\.ts$",
         "transform": {
-            "^.+\\.(t|j)s$": "ts-jest"
+            "^.+\\.(t|j)s$": [
+                "ts-jest",
+                {
+                    "tsconfig": "<rootDir>/../tsconfig.spec.json"
+                }
+            ]
         },
         "collectCoverageFrom": [
             "**/*.(t|j)s"
         ],
         "coverageDirectory": "../coverage",
         "testEnvironment": "node"
-    },
-    "resolutions": {
-        "js-yaml": "^4.1.1"
     }
 }