@diamir/nestjs-maintenance 11.0.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright 2025 WEB&SÖHNE<backend@diamir.io>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

package/README.md

@@ -0,0 +1,75 @@
+<p align="center">
+  <a href="https://webundsoehne.com" target="blank">
+    <img src="https://webundsoehne.com/wp-content/uploads/webundsoehne-logo.png" width="320" alt="Web und Söhne - Logo" />
+  </a>
+</p>
+Web & Söhne is Austria's leading expert in programming and implementing complex and large web projects.
+
+---
+
+# nestjs-maintenance
+
+<!-- TOC -->
+* [nestjs-maintenance](#nestjs-maintenance)
+  * [Description](#description)
+  * [Usage](#usage)
+    * [MaintenanceService](#maintenanceservice)
+    * [Decorator](#decorator)
+  * [Migration](#migration)
+<!-- TOC -->
+
+## Description
+
+The maintenance module gives you the possibility to generate and remove a lock file,
+as well as checking if the lock file exists and throwing a preconfigured `ServiceUnavailableException` error.
+
+You may use the maintenance module anywhere in your project, e.g. for database migrations. (But make sure to access the same lock-file in each module)
+
+## Usage
+
+Set up the `MaintenanceModule` and `MaintenanceMiddleware` in the server/application module.
+
+```typescript
+import { MiddlewareConsumer, Module, NestModule, RequestMethod } from '@nestjs/common'
+import { MaintenanceMiddleware, MaintenanceModule } from '@diamir/nestjs-maintenance'
+
+@Module({
+  imports: [
+    MaintenanceModule.forRoot({
+      application: ConfigService.get('url.basePath'), // default: Application
+      lockfilePath: ConfigService.get('misc.lockfile') // default: maintenance.lock
+    })
+  ]
+})
+class ServerModule implements NestModule {
+  async configure(consumer: MiddlewareConsumer): Promise<any> {
+    consumer.apply(MaintenanceMiddleware).forRoutes({ path: '*', method: RequestMethod.ALL })
+  }
+}
+```
+
+Now if a lockfile is present at the `lockfilePath`, the `ServiceUnavailableException` will be thrown.
+
+### MaintenanceService
+
+To create and remove the lockfile, use the `MaintenanceService` in any module.
+
+| Name           | Return  | Description                           |
+|----------------|---------|---------------------------------------|
+| enable         | void    | Create the configured lock file       |
+| disable        | void    | Remove the generated lock file        |
+| isEnabled      | Boolean | Check if there is already a lock file |
+| throwException | void    | Throw the preconfigured exception     |
+
+### Decorator
+
+Apply the `@UseMaintenanceLocker()` decorator on a method to wrap the original function inside a maintenance-lock
+1. enable lock
+2. execute method
+3. disable lock
+
+## Migration
+
+To migrate from the old `@webundsoehne/nestjs-util` to `@diamir/nestjs-maintenance`:
+- replace the imports
+- change the `MaintenanceModule` imports to use the `.forRoot` method

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@diamir/nestjs-maintenance",
+  "version": "11.0.0",
+  "description": "",
+  "author": "Backend <backend@diamir.io>",
+  "repository": "https://github.com/tailoredmedia/backend-nx-skeleton",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "main": "./src/index.js",
+  "dependencies": {},
+  "peerDependencies": {
+    "@nestjs/common": ">= 11.0.0"
+  },
+  "peerDependenciesMeta": {},
+  "engines": {
+    "node": ">= 20"
+  },
+  "types": "./src/index.d.ts",
+  "type": "commonjs"
+}

package/src/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './inject.decorator';
+export * from './locker.decorator';

package/src/decorators/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./inject.decorator"), exports);
+__exportStar(require("./locker.decorator"), exports);

package/src/decorators/inject.decorator.d.ts

@@ -0,0 +1 @@
+export declare function InjectMaintenanceService(): PropertyDecorator & ParameterDecorator;

package/src/decorators/inject.decorator.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectMaintenanceService = InjectMaintenanceService;
+const common_1 = require("@nestjs/common");
+const maintenance_service_1 = require("../maintenance.service");
+function InjectMaintenanceService() {
+    return (0, common_1.Inject)(maintenance_service_1.MaintenanceService);
+}

package/src/decorators/locker.decorator.d.ts

@@ -0,0 +1 @@
+export declare function UseMaintenanceLocker(): MethodDecorator;

package/src/decorators/locker.decorator.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseMaintenanceLocker = UseMaintenanceLocker;
+const inject_decorator_1 = require("./inject.decorator");
+function UseMaintenanceLocker() {
+    return (target, propertyKey, descriptor) => {
+        const originalFn = descriptor.value;
+        (0, inject_decorator_1.InjectMaintenanceService)()(target, 'LOCKER_MAINTENANCE_SERVICE');
+        descriptor.value = async function (...args) {
+            const service = this.LOCKER_MAINTENANCE_SERVICE;
+            await service.enable(propertyKey);
+            try {
+                const result = await originalFn.apply(this, args);
+                await service.disable(propertyKey);
+                return result;
+            }
+            catch (err) {
+                await service.disable(propertyKey);
+                throw err;
+            }
+        };
+        return descriptor;
+    };
+}

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './decorators';
+export * from './interface';
+export * from './maintenance.middleware';
+export * from './maintenance.module';
+export * from './maintenance.service';

package/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./interface"), exports);
+__exportStar(require("./maintenance.middleware"), exports);
+__exportStar(require("./maintenance.module"), exports);
+__exportStar(require("./maintenance.service"), exports);

package/src/interface/index.d.ts

@@ -0,0 +1 @@
+export * from './maintenance-options.interface';

package/src/interface/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./maintenance-options.interface"), exports);

package/src/interface/maintenance-options.interface.d.ts

@@ -0,0 +1,4 @@
+export interface MaintenanceOptions {
+    application?: string;
+    lockfilePath?: string;
+}

package/src/interface/maintenance-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/maintenance.middleware.d.ts

@@ -0,0 +1,7 @@
+import type { NestMiddleware } from '@nestjs/common';
+import { MaintenanceService } from './maintenance.service';
+export declare class MaintenanceMiddleware implements NestMiddleware {
+    private readonly service;
+    constructor(service: MaintenanceService);
+    use(_req: never, _res: never, next: (err?: any) => unknown): Promise<void>;
+}

package/src/maintenance.middleware.js

@@ -0,0 +1,34 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaintenanceMiddleware = void 0;
+const common_1 = require("@nestjs/common");
+const maintenance_service_1 = require("./maintenance.service");
+let MaintenanceMiddleware = class MaintenanceMiddleware {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    async use(_req, _res, next) {
+        if (await this.service.isEnabled()) {
+            this.service.throwException();
+        }
+        next();
+    }
+};
+exports.MaintenanceMiddleware = MaintenanceMiddleware;
+exports.MaintenanceMiddleware = MaintenanceMiddleware = __decorate([
+    __param(0, (0, common_1.Inject)(maintenance_service_1.MaintenanceService)),
+    __metadata("design:paramtypes", [maintenance_service_1.MaintenanceService])
+], MaintenanceMiddleware);

package/src/maintenance.module.d.ts

@@ -0,0 +1,5 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { MaintenanceOptions } from './interface';
+export declare class MaintenanceModule {
+    static forRoot(options?: MaintenanceOptions): DynamicModule;
+}

package/src/maintenance.module.js

@@ -0,0 +1,31 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var MaintenanceModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaintenanceModule = void 0;
+const common_1 = require("@nestjs/common");
+const maintenance_service_1 = require("./maintenance.service");
+let MaintenanceModule = MaintenanceModule_1 = class MaintenanceModule {
+    static forRoot(options) {
+        return {
+            global: true,
+            module: MaintenanceModule_1,
+            providers: [
+                {
+                    provide: maintenance_service_1.MaintenanceService,
+                    useValue: new maintenance_service_1.MaintenanceService(options)
+                }
+            ],
+            exports: [maintenance_service_1.MaintenanceService]
+        };
+    }
+};
+exports.MaintenanceModule = MaintenanceModule;
+exports.MaintenanceModule = MaintenanceModule = MaintenanceModule_1 = __decorate([
+    (0, common_1.Module)({})
+], MaintenanceModule);

package/src/maintenance.service.d.ts

@@ -0,0 +1,13 @@
+import type { MaintenanceOptions } from './interface';
+export declare class MaintenanceService {
+    static instance: MaintenanceService;
+    readonly message: string;
+    private readonly logger;
+    private readonly lockfile;
+    private readonly tasks;
+    constructor(options?: MaintenanceOptions);
+    enable(task?: string): Promise<void>;
+    disable(task?: string): Promise<void>;
+    isEnabled(): Promise<boolean>;
+    throwException(): void;
+}

package/src/maintenance.service.js

@@ -0,0 +1,78 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var MaintenanceService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaintenanceService = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const common_1 = require("@nestjs/common");
+let MaintenanceService = class MaintenanceService {
+    static { MaintenanceService_1 = this; }
+    static instance;
+    message;
+    logger = new common_1.Logger(this.constructor.name);
+    lockfile;
+    tasks = [];
+    constructor(options) {
+        if (!MaintenanceService_1.instance) {
+            this.message = `${options?.application ?? process.env.PACKAGE_NAME ?? 'Application'} is currently down for maintenance`;
+            this.lockfile = (0, node_path_1.resolve)(options?.lockfilePath ?? 'maintenance.lock');
+            MaintenanceService_1.instance = this;
+        }
+    }
+    async enable(task = 'unknown-task') {
+        this.tasks.push(task);
+        this.logger.debug(`Task added to maintenance queue: ${task}`);
+        if (!(await this.isEnabled())) {
+            this.logger.verbose(`Enabling maintenance mode (lockfile is ${this.lockfile})`);
+            await (0, promises_1.writeFile)(this.lockfile, '', { encoding: 'utf8' });
+            this.logger.log('◆◆◆ Maintenance mode enabled ◆◆◆');
+            return;
+        }
+        this.logger.verbose('Maintenance mode already enabled.');
+    }
+    async disable(task = 'unknown-task') {
+        this.tasks.splice(this.tasks.indexOf(task), 1);
+        if (this.tasks.length === 0) {
+            this.logger.verbose(`Disabling maintenance mode (lockfile is ${this.lockfile})`);
+            try {
+                await (0, promises_1.rm)(this.lockfile);
+            }
+            catch (_) {
+                this.logger.debug(`Lockfile was already missing: ${this.lockfile}`);
+            }
+            this.logger.log('◆◆◆ Maintenance mode disabled ◆◆◆');
+            return;
+        }
+        this.logger.verbose(`Not disabling maintenance mode still got running tasks: ${this.tasks.join(', ')}`);
+    }
+    async isEnabled() {
+        try {
+            await (0, promises_1.access)(this.lockfile);
+        }
+        catch (_error) {
+            return false;
+        }
+        return true;
+    }
+    throwException() {
+        throw new common_1.ServiceUnavailableException(this.message);
+    }
+};
+exports.MaintenanceService = MaintenanceService;
+exports.MaintenanceService = MaintenanceService = MaintenanceService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [Object])
+], MaintenanceService);