nest-abort-controller 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ferhat Yalçın
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,375 @@
+# nestjs-abort-controller
+
+[![npm version](https://badge.fury.io/js/nestjs-abort-controller.svg)](https://badge.fury.io/js/nestjs-abort-controller)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Graceful request cancellation support for NestJS using native `AbortController`. Automatically handles client disconnections and provides easy-to-use decorators for request-scoped cancellation.
+
+## ✨ Features
+
+- 🚀 **Automatic AbortController Creation**: Creates `AbortSignal` for each incoming HTTP request
+- 🔄 **Client Disconnection Handling**: Automatically aborts long-running operations when client disconnects
+- 🎯 **Easy Integration**: Simple decorator-based approach with `@NestAbortSignal()`
+- ⚡ **Lightweight**: Zero additional dependencies (only Node >= 16)
+- 🔧 **TypeScript Support**: Full TypeScript support with proper type definitions
+- 🛡️ **Error Handling**: Built-in utilities for checking abort status
+- ⏰ **Configurable Timeout**: Set request timeout in **milliseconds** to automatically abort long-running operations
+- 📝 **Logging Support**: Optional logging for debugging abort scenarios
+
+## 📦 Installation
+
+```bash
+npm install nestjs-abort-controller
+```
+
+## 🚀 Quick Start
+
+### 1. Import the Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { AbortControllerModule } from 'nestjs-abort-controller';
+
+@Module({
+  imports: [
+    AbortControllerModule.forRoot({
+      timeout: 30000, // 30000ms = 30 seconds timeout
+      enableLogging: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Use the Decorator
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { NestAbortSignal, throwIfAborted } from 'nestjs-abort-controller';
+
+@Controller('api')
+export class ApiController {
+  @Get('long-running-operation')
+  async longRunningOperation(@NestAbortSignal() signal: AbortSignal): Promise<string> {
+    for (let i = 0; i < 100; i++) {
+      // Check if operation was aborted
+      throwIfAborted(signal);
+
+      // Your long-running work here
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+
+    return 'Operation completed successfully!';
+  }
+}
+```
+
+## 📚 API Reference
+
+### Decorators
+
+#### `@NestAbortSignal()`
+
+A parameter decorator that injects the `AbortSignal` for the current request.
+
+```typescript
+@Get()
+async handler(@NestAbortSignal() signal: AbortSignal) {
+  // signal is automatically aborted when client disconnects
+}
+```
+
+### Utility Functions
+
+#### `throwIfAborted(signal: AbortSignal, message?: string): void`
+
+Throws an `AbortError` if the signal is aborted.
+
+```typescript
+import { throwIfAborted } from 'nestjs-abort-controller';
+
+async function longRunningOperation(signal: AbortSignal) {
+  for (let i = 0; i < 1000; i++) {
+    throwIfAborted(signal); // Will throw if aborted
+
+    // Your work here
+    await someAsyncWork();
+  }
+}
+```
+
+#### `AbortError`
+
+Custom error class for abort operations.
+
+```typescript
+import { AbortError } from 'nestjs-abort-controller';
+
+try {
+  // Some operation
+} catch (error) {
+  if (error instanceof AbortError) {
+    console.log('Operation was aborted');
+  }
+}
+```
+
+### `AbortControllerModule`
+
+The main module that sets up the middleware for all routes.
+
+#### `forRoot(options?: AbortControllerOptions)`
+
+Configure the module for all routes.
+
+```typescript
+import { AbortControllerModule } from 'nestjs-abort-controller';
+
+@Module({
+  imports: [
+    AbortControllerModule.forRoot({
+      timeout: 30000, // 30000ms = 30 seconds
+      enableLogging: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### `forRoutes(routes: string | string[], options?: AbortControllerOptions)`
+
+Configure the module for specific routes.
+
+```typescript
+import { AbortControllerModule } from 'nestjs-abort-controller';
+
+@Module({
+  imports: [
+    AbortControllerModule.forRoutes(['/api/*'], {
+      timeout: 60000, // 60000ms = 60 seconds
+      enableLogging: false,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Configuration Options
+
+#### `AbortControllerOptions`
+
+```typescript
+interface AbortControllerOptions {
+  timeout?: number; // Timeout duration in milliseconds (default: 30000ms = 30 seconds)
+  enableLogging?: boolean; // Enable debug logging (default: false)
+}
+```
+
+## 🔧 Advanced Usage
+
+### Using with Services
+
+The recommended approach is to pass the `AbortSignal` from controller to service methods.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { throwIfAborted } from 'nestjs-abort-controller';
+
+@Injectable()
+export class UserService {
+  async getUsers(signal: AbortSignal) {
+    for (let i = 0; i < 100; i++) {
+      throwIfAborted(signal);
+      await someAsyncWork();
+    }
+    return users;
+  }
+}
+
+import { Controller, Get } from '@nestjs/common';
+import { NestAbortSignal } from 'nestjs-abort-controller';
+
+@Controller('users')
+export class UserController {
+  constructor(private userService: UserService) {}
+
+  @Get()
+  getUsers(@NestAbortSignal() signal: AbortSignal) {
+    // Pass signal to service
+    return this.userService.getUsers(signal);
+  }
+}
+```
+
+### Integration with External APIs
+
+```typescript
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class ExternalApiService {
+  async fetchFromExternalApi(signal: AbortSignal) {
+    const response = await fetch('https://api.example.com/data', {
+      signal, // Pass the signal to fetch
+    });
+
+    return response.json();
+  }
+}
+
+import { Controller, Get } from '@nestjs/common';
+import { NestAbortSignal } from 'nestjs-abort-controller';
+
+@Controller('api')
+export class ApiController {
+  constructor(private externalApiService: ExternalApiService) {}
+
+  @Get('external-data')
+  async getExternalData(@NestAbortSignal() signal: AbortSignal) {
+    return this.externalApiService.fetchFromExternalApi(signal);
+  }
+}
+```
+
+### Manual Abort Signal Checking
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { NestAbortSignal, throwIfAborted } from 'nestjs-abort-controller';
+
+@Controller('api')
+export class ApiController {
+  @Get('manual-check')
+  async manualCheck(@NestAbortSignal() signal: AbortSignal) {
+    for (let i = 0; i < 1000; i++) {
+      // Manual check
+      if (signal.aborted) {
+        throw new Error('Operation was cancelled');
+      }
+
+      // Or use utility function
+      throwIfAborted(signal);
+
+      await someAsyncWork();
+    }
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { NestAbortSignal, throwIfAborted, AbortError } from 'nestjs-abort-controller';
+
+@Controller('api')
+export class ApiController {
+  @Get('with-error-handling')
+  async withErrorHandling(@NestAbortSignal() signal: AbortSignal) {
+    try {
+      for (let i = 0; i < 100; i++) {
+        throwIfAborted(signal);
+        await someAsyncWork();
+      }
+      return 'Success';
+    } catch (error) {
+      if (error instanceof AbortError) {
+        // Handle abort specifically
+        return 'Operation was cancelled';
+      }
+      throw error;
+    }
+  }
+}
+```
+
+### Multiple Service Calls
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { throwIfAborted } from 'nestjs-abort-controller';
+
+@Injectable()
+export class DataService {
+  async processData(signal: AbortSignal) {
+    throwIfAborted(signal);
+    // Process data
+    return processedData;
+  }
+}
+
+@Injectable()
+export class CacheService {
+  async getFromCache(signal: AbortSignal) {
+    throwIfAborted(signal);
+    // Get from cache
+    return cachedData;
+  }
+}
+
+import { Controller, Get } from '@nestjs/common';
+import { NestAbortSignal } from 'nestjs-abort-controller';
+
+@Controller('data')
+export class DataController {
+  constructor(
+    private dataService: DataService,
+    private cacheService: CacheService
+  ) {}
+
+  @Get('process')
+  async processData(@NestAbortSignal() signal: AbortSignal) {
+    // Use same signal for multiple service calls
+    const cached = await this.cacheService.getFromCache(signal);
+    const processed = await this.dataService.processData(signal);
+
+    return { cached, processed };
+  }
+}
+```
+
+## 🧪 Testing
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { AbortControllerModule } from 'nestjs-abort-controller';
+
+describe('AbortController', () => {
+  let module: TestingModule;
+
+  beforeEach(async () => {
+    module = await Test.createTestingModule({
+      imports: [AbortControllerModule.forRoot()],
+    }).compile();
+  });
+
+  // Your tests here
+});
+```
+
+## 📋 Requirements
+
+- Node.js >= 16.0.0
+- NestJS >= 8.0.0
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built for the NestJS community
+- Inspired by the need for better request cancellation handling
+- Uses native Node.js AbortController for maximum compatibility
+
+---
+
+**Made with ❤️ for the NestJS community**

package/dist/src/abort-controller.middleware.d.ts

@@ -0,0 +1,9 @@
+import { NestMiddleware } from '@nestjs/common';
+import { Response } from 'express';
+import { AbortControllerOptions, AbortControllerRequest } from './types';
+export declare class AbortControllerMiddleware implements NestMiddleware {
+    private readonly logger;
+    private static options;
+    static setOptions(options: AbortControllerOptions): void;
+    use(req: AbortControllerRequest, res: Response, next: () => void): void;
+}

package/dist/src/abort-controller.middleware.js

@@ -0,0 +1,58 @@
+"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 AbortControllerMiddleware_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbortControllerMiddleware = void 0;
+const common_1 = require("@nestjs/common");
+const LOG_MESSAGES = {
+    CLIENT_DISCONNECTED: 'Client disconnected, aborting request',
+    REQUEST_TIMEOUT: 'Request timeout after {timeout}ms',
+    REQUEST_COMPLETED: 'Request completed successfully',
+};
+let AbortControllerMiddleware = class AbortControllerMiddleware {
+    static { AbortControllerMiddleware_1 = this; }
+    logger = new common_1.Logger(AbortControllerMiddleware_1.name);
+    static options = {};
+    static setOptions(options) {
+        AbortControllerMiddleware_1.options = options;
+    }
+    use(req, res, next) {
+        const controller = new AbortController();
+        // Timeout in milliseconds (default: 30000ms = 30 seconds)
+        const timeout = AbortControllerMiddleware_1.options.timeout ?? 30000;
+        const enableLogging = AbortControllerMiddleware_1.options.enableLogging ?? false;
+        req.abortController = controller;
+        req.abortSignal = controller.signal;
+        req.on('close', () => {
+            if (enableLogging) {
+                this.logger.debug(LOG_MESSAGES.CLIENT_DISCONNECTED);
+            }
+            controller.abort();
+        });
+        if (timeout > 0) {
+            const timeoutId = setTimeout(() => {
+                if (enableLogging) {
+                    this.logger.warn(LOG_MESSAGES.REQUEST_TIMEOUT.replace('{timeout}', timeout.toString()));
+                }
+                controller.abort();
+            }, timeout);
+            req.on('close', () => clearTimeout(timeoutId));
+            res.on('finish', () => clearTimeout(timeoutId));
+        }
+        res.on('finish', () => {
+            if (enableLogging) {
+                this.logger.debug(LOG_MESSAGES.REQUEST_COMPLETED);
+            }
+        });
+        next();
+    }
+};
+exports.AbortControllerMiddleware = AbortControllerMiddleware;
+exports.AbortControllerMiddleware = AbortControllerMiddleware = AbortControllerMiddleware_1 = __decorate([
+    (0, common_1.Injectable)()
+], AbortControllerMiddleware);

package/dist/src/abort-signal.decorator.d.ts

@@ -0,0 +1 @@
+export declare const NestAbortSignal: (...dataOrPipes: any[]) => ParameterDecorator;

package/dist/src/abort-signal.decorator.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestAbortSignal = void 0;
+const common_1 = require("@nestjs/common");
+exports.NestAbortSignal = (0, common_1.createParamDecorator)((_, ctx) => {
+    const req = ctx.switchToHttp().getRequest();
+    return req.abortSignal;
+});

package/dist/src/abort-utilities.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Utility function to throw if aborted with custom error
+ */
+export declare function throwIfAborted(signal: AbortSignal, message?: string): void;

package/dist/src/abort-utilities.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwIfAborted = throwIfAborted;
+/**
+ * Utility function to throw if aborted with custom error
+ */
+function throwIfAborted(signal, message) {
+    if (signal.aborted) {
+        throw new Error(message || 'Operation was aborted');
+    }
+}

package/dist/src/abort.module.d.ts

@@ -0,0 +1,8 @@
+import { MiddlewareConsumer, NestModule, DynamicModule } from '@nestjs/common';
+import { AbortControllerOptions } from './types';
+export declare class AbortControllerModule implements NestModule {
+    private static routes;
+    configure(consumer: MiddlewareConsumer): void;
+    static forRoot(options?: AbortControllerOptions): DynamicModule;
+    static forRoutes(routes?: string | string[], options?: AbortControllerOptions): DynamicModule;
+}

package/dist/src/abort.module.js

@@ -0,0 +1,45 @@
+"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 AbortControllerModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbortControllerModule = void 0;
+const common_1 = require("@nestjs/common");
+const abort_controller_middleware_1 = require("./abort-controller.middleware");
+let AbortControllerModule = class AbortControllerModule {
+    static { AbortControllerModule_1 = this; }
+    static routes = '*';
+    configure(consumer) {
+        const routes = AbortControllerModule_1.routes;
+        if (Array.isArray(routes)) {
+            consumer.apply(abort_controller_middleware_1.AbortControllerMiddleware).forRoutes(...routes);
+        }
+        else {
+            consumer.apply(abort_controller_middleware_1.AbortControllerMiddleware).forRoutes(routes);
+        }
+    }
+    static forRoot(options) {
+        AbortControllerModule_1.routes = '*';
+        abort_controller_middleware_1.AbortControllerMiddleware.setOptions(options || {});
+        return {
+            module: AbortControllerModule_1,
+        };
+    }
+    static forRoutes(routes = '*', options) {
+        AbortControllerModule_1.routes = routes;
+        abort_controller_middleware_1.AbortControllerMiddleware.setOptions(options || {});
+        return {
+            module: AbortControllerModule_1,
+        };
+    }
+};
+exports.AbortControllerModule = AbortControllerModule;
+exports.AbortControllerModule = AbortControllerModule = AbortControllerModule_1 = __decorate([
+    (0, common_1.Module)({
+        providers: [abort_controller_middleware_1.AbortControllerMiddleware],
+    })
+], AbortControllerModule);

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './abort-controller.middleware';
+export * from './abort-signal.decorator';
+export * from './abort.module';
+export * from './types';
+export * from './throw-if-aborted';

package/dist/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("./abort-controller.middleware"), exports);
+__exportStar(require("./abort-signal.decorator"), exports);
+__exportStar(require("./abort.module"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./throw-if-aborted"), exports);

package/dist/src/throw-if-aborted.d.ts

@@ -0,0 +1,4 @@
+export declare class AbortError extends Error {
+    constructor(message?: string);
+}
+export declare function throwIfAborted(signal: AbortSignal, message?: string): void;

package/dist/src/throw-if-aborted.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbortError = void 0;
+exports.throwIfAborted = throwIfAborted;
+class AbortError extends Error {
+    constructor(message = 'Operation was aborted') {
+        super(message);
+        this.name = 'AbortError';
+    }
+}
+exports.AbortError = AbortError;
+function throwIfAborted(signal, message) {
+    if (signal.aborted) {
+        throw new AbortError(message);
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,9 @@
+import { Request } from 'express';
+export interface AbortControllerRequest extends Request {
+    abortController?: AbortController;
+    abortSignal?: AbortSignal;
+}
+export interface AbortControllerOptions {
+    timeout?: number;
+    enableLogging?: boolean;
+}

package/dist/src/types.js

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

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "nest-abort-controller",
+  "version": "1.2.0",
+  "description": "AbortController integration for NestJS: request-scoped cancellation using AbortSignal.",
+  "keywords": [
+    "abort",
+    "abort-signal",
+    "abortcontroller",
+    "cancellation",
+    "middleware",
+    "nestjs",
+    "request-cancellation",
+    "typescript"
+  ],
+  "homepage": "https://github.com/ylcnfrht/nestjs-abort-controller#readme",
+  "bugs": {
+    "url": "https://github.com/ylcnfrht/nestjs-abort-controller/issues"
+  },
+  "license": "MIT",
+  "author": "Ferhat Yalçın",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@nestjs/testing": "^12.0.1",
+    "@types/express": "^5.0.3",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.20.2",
+    "@typescript-eslint/eslint-plugin": "^8.70.0",
+    "@typescript-eslint/parser": "^8.70.0",
+    "eslint": "^10.10.0",
+    "express": "^5.1.0",
+    "jest": "^30.5.1",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.0.0",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "format": "prettier --write src/**/*.ts",
+    "start:example": "ts-node usage/src/main.ts"
+  }
+}