@nest-extended/core 0.0.2-beta-14 → 0.0.2-beta-15

package/README.md

@@ -1,17 +1,74 @@
 # @nest-extended/core
 
-This package provides the core building blocks for NestJS applications built with the **NestExtended** ecosystem. It includes generic controllers, decorators, and configuration interfaces designed to work seamlessly with `@nest-extended/mongoose`.
+This package provides the core building blocks for NestJS applications built with the **NestExtended** ecosystem. It includes generic controllers, a dynamic configuration module, interceptors, CLS helpers, and type interfaces designed to work seamlessly with `@nest-extended/mongoose`.
 
 ## Key Features
 
-- **Generic Controller (`NestController`)**: A base controller class that handles common CRUD operations (`find`, `get`, `create`, `patch`, `delete`) by delegating to a service implementing `ServiceOptions`.
-- **Decorators**: Moved to `@nest-extended/decorators`.
-    - `@User()`
-    - `@Public()`
-    - `@ModifyBody()`
+- **Generic Controller (`NestController`)**: A base controller class that handles common CRUD operations (`find`, `get`, `create`, `patch`, `delete`) by delegating to a service implementing `ServiceOptions`. Auto-wires `@Public()`, `@ModifyBody(setCreatedBy())`, and `@User()` decorators.
+- **Dynamic Module (`NestExtendedModule`)**: A global dynamic module configured via `NestExtendedModule.forRoot(config)` that provides app-wide soft delete configuration and automatic `qs` query parser setup. Injects `NEST_EXTENDED_CONFIG` token.
+- **CLS Helpers**: Utilities for `nestjs-cls` (Continuation Local Storage):
+    - `getCurrentUser<T>()` — retrieve the authenticated user from CLS context (set by AuthGuard).
+    - `CLS_KEYS.USER` — constant for the CLS user key.
+- **Interceptors**:
+    - `NullResponseInterceptor` — throws `NotFoundException` on `null`/`undefined` GET responses.
+- **Configuration Types**:
+    - `NestExtendedConfig` — root config with `softDelete` and `queryParser` settings.
+    - `SoftDeleteConfig` — `getQuery()` and `getData(user)` for soft delete behavior.
+    - `QueryParserConfig` — `depth`, `arrayLimit`, `allowDots` for `qs` query parser.
+    - `NEST_EXTENDED_CONFIG` — injection token (`Symbol`).
+- **Type Interfaces**:
+    - `ServiceOptions<T>` — interface for `_find`, `_get`, `_create`, `_patch`, `_remove`.
+    - `NestServiceOptions` — options for `multi`, `softDelete`, `pagination`.
+    - `PaginatedResponse<D>` — typed response with `total`, `$limit`, `$skip`, `data`.
+    - `RequestBody` — re-export from `@nest-extended/decorators`.
+- **Default Options**: Configurable defaults for `deleteKey` (`'deleted'`), `defaultPagination` (`true`), `defaultLimit` (`20`), `defaultSkip` (`0`), `multi` (`false`).
+- **Constants**: `WeekDays` enum and `EachSlotDurationInMinutes` (30).
+- **Decorators**: Moved to `@nest-extended/decorators` — use `@User()`, `@Public()`, `@ModifyBody()`, `setCreatedBy()`.
 
 ## Usage
 
+### NestExtendedModule
+
+Configure soft delete behavior and query parser globally:
+
+```typescript
+import { NestExtendedModule } from '@nest-extended/core';
+
+@Module({
+  imports: [
+    NestExtendedModule.forRoot({
+      softDelete: {
+        getQuery: () => ({ deleted: { $ne: true } }),
+        getData: (user) => ({
+          deleted: true,
+          deletedBy: user?._id,
+          deletedAt: new Date(),
+        }),
+      },
+      // Query parser is enabled by default with qs (depth: 20, arrayLimit: 100)
+      // Customize or disable:
+      // queryParser: { depth: 10, arrayLimit: 50, allowDots: true },
+      // queryParser: false, // disable qs, use Express default
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### Query Parser
+
+The module automatically configures `qs` as the Express query parser on application bootstrap. This enables proper parsing of deeply nested query objects and arrays (required by `@nest-extended/mongoose` query features like `$populate`, `$sort`, etc.).
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `depth` | `number` | `20` | Maximum nesting depth for query objects |
+| `arrayLimit` | `number` | `100` | Maximum number of array elements |
+| `allowDots` | `boolean` | `false` | Allow dot notation in query keys |
+
+- **Enabled by default**: No configuration needed — just use `NestExtendedModule.forRoot()`.
+- **Custom options**: Pass a `QueryParserConfig` object to `queryParser`.
+- **Disable**: Set `queryParser: false` to use Express's default query parser.
+
 ### NestController
 
 Extend `NestController` to automatically expose standard CRUD endpoints.
@@ -28,6 +85,29 @@ export class MyController extends NestController<MyResource> {
 }
 ```
 
+### NullResponseInterceptor
+
+Register globally to auto-throw 404 on null GET responses:
+
+```typescript
+import { NullResponseInterceptor } from '@nest-extended/core';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+
+providers: [
+  { provide: APP_INTERCEPTOR, useClass: NullResponseInterceptor },
+]
+```
+
+### CLS Helper
+
+Retrieve the authenticated user from CLS context (useful in services):
+
+```typescript
+import { getCurrentUser } from '@nest-extended/core';
+
+const user = getCurrentUser();
+```
+
 ### Decorators
 
 Decorators have been moved to their own package.
@@ -35,3 +115,22 @@ Decorators have been moved to their own package.
 ```typescript
 import { User, Public, ModifyBody, setCreatedBy } from '@nest-extended/decorators';
 ```
+
+## Exported API
+
+| Export | Type | Description |
+|---|---|---|
+| `NestController` | Class | Generic CRUD controller base class |
+| `NestExtendedModule` | Module | Dynamic config module (`.forRoot()`) |
+| `options` | Object | Default options (deleteKey, pagination, limits) |
+| `getCurrentUser` | Function | Get user from CLS context |
+| `CLS_KEYS` | Const | CLS key constants |
+| `NullResponseInterceptor` | Interceptor | 404 on null GET responses |
+| `NestExtendedConfig` | Interface | Root configuration type |
+| `SoftDeleteConfig` | Interface | Soft delete config type |
+| `QueryParserConfig` | Interface | Query parser options (depth, arrayLimit, allowDots) |
+| `NEST_EXTENDED_CONFIG` | Symbol | DI injection token |
+| `ServiceOptions<T>` | Interface | Service method contract |
+| `NestServiceOptions` | Type | Service behavior options |
+| `PaginatedResponse<D>` | Interface | Paginated response type |
+| `RequestBody` | Type | Re-exported typed request body |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nest-extended/core",
-  "version": "0.0.2-beta-14",
+  "version": "0.0.2-beta-15",
   "private": false,
   "contributors": [
     {
@@ -18,6 +18,7 @@
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "dependencies": {
+    "qs": "^6.13.0",
     "tslib": "^2.3.0"
   }
 }

package/src/lib/nest-extended.module.d.ts

@@ -1,5 +1,10 @@
-import { DynamicModule } from '@nestjs/common';
+import { DynamicModule, OnApplicationBootstrap } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
 import { NestExtendedConfig } from '../types/nest-extended.config';
-export declare class NestExtendedModule {
+export declare class NestExtendedModule implements OnApplicationBootstrap {
+    private readonly config;
+    private readonly httpAdapterHost;
+    constructor(config: NestExtendedConfig, httpAdapterHost: HttpAdapterHost);
+    onApplicationBootstrap(): void;
     static forRoot(config?: NestExtendedConfig): DynamicModule;
 }

package/src/lib/nest-extended.module.js

@@ -4,8 +4,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NestExtendedModule = void 0;
 const tslib_1 = require("tslib");
 const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
 const nest_extended_config_1 = require("../types/nest-extended.config");
+const qs = require("qs");
 let NestExtendedModule = NestExtendedModule_1 = class NestExtendedModule {
+    constructor(config, httpAdapterHost) {
+        this.config = config;
+        this.httpAdapterHost = httpAdapterHost;
+    }
+    onApplicationBootstrap() {
+        var _a, _b, _c, _d;
+        const queryParserConfig = this.config.queryParser;
+        if (queryParserConfig === false)
+            return;
+        // Apply qs query parser to the Express app
+        const httpAdapter = (_a = this.httpAdapterHost) === null || _a === void 0 ? void 0 : _a.httpAdapter;
+        if (httpAdapter) {
+            const app = httpAdapter.getInstance();
+            const options = typeof queryParserConfig === 'object' ? queryParserConfig : {};
+            const depth = (_b = options.depth) !== null && _b !== void 0 ? _b : 20;
+            const arrayLimit = (_c = options.arrayLimit) !== null && _c !== void 0 ? _c : 100;
+            const allowDots = (_d = options.allowDots) !== null && _d !== void 0 ? _d : false;
+            app.set('query parser', (str) => qs.parse(str, { depth, arrayLimit, allowDots }));
+        }
+    }
     static forRoot(config = {}) {
         return {
             module: NestExtendedModule_1,
@@ -22,6 +44,8 @@ let NestExtendedModule = NestExtendedModule_1 = class NestExtendedModule {
 };
 exports.NestExtendedModule = NestExtendedModule;
 exports.NestExtendedModule = NestExtendedModule = NestExtendedModule_1 = tslib_1.__decorate([
-    (0, common_1.Module)({})
+    (0, common_1.Module)({}),
+    tslib_1.__param(0, (0, common_1.Inject)(nest_extended_config_1.NEST_EXTENDED_CONFIG)),
+    tslib_1.__metadata("design:paramtypes", [Object, core_1.HttpAdapterHost])
 ], NestExtendedModule);
 //# sourceMappingURL=nest-extended.module.js.map

package/src/lib/nest-extended.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"nest-extended.module.js","sourceRoot":"","sources":["../../../../../packages/core/src/lib/nest-extended.module.ts"],"names":[],"mappings":";;;;;AAAA,2CAAuD;AACvD,wEAAyF;AAGlF,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAC3B,MAAM,CAAC,OAAO,CAAC,SAA6B,EAAE;QAC1C,OAAO;YACH,MAAM,EAAE,oBAAkB;YAC1B,MAAM,EAAE,IAAI;YACZ,SAAS,EAAE;gBACP;oBACI,OAAO,EAAE,2CAAoB;oBAC7B,QAAQ,EAAE,MAAM;iBACnB;aACJ;YACD,OAAO,EAAE,CAAC,2CAAoB,CAAC;SAClC,CAAC;IACN,CAAC;CACJ,CAAA;AAdY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,kBAAkB,CAc9B"}
+{"version":3,"file":"nest-extended.module.js","sourceRoot":"","sources":["../../../../../packages/core/src/lib/nest-extended.module.ts"],"names":[],"mappings":";;;;;AAAA,2CAAuF;AACvF,uCAA+C;AAC/C,wEAAyF;AACzF,yBAAyB;AAGlB,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAC3B,YACmD,MAA0B,EACxD,eAAgC;QADF,WAAM,GAAN,MAAM,CAAoB;QACxD,oBAAe,GAAf,eAAe,CAAiB;IAClD,CAAC;IAEJ,sBAAsB;;QAClB,MAAM,iBAAiB,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QAClD,IAAI,iBAAiB,KAAK,KAAK;YAAE,OAAO;QAExC,2CAA2C;QAC3C,MAAM,WAAW,GAAG,MAAA,IAAI,CAAC,eAAe,0CAAE,WAAW,CAAC;QACtD,IAAI,WAAW,EAAE,CAAC;YACd,MAAM,GAAG,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;YACtC,MAAM,OAAO,GAAG,OAAO,iBAAiB,KAAK,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,MAAM,KAAK,GAAG,MAAA,OAAO,CAAC,KAAK,mCAAI,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,MAAA,OAAO,CAAC,UAAU,mCAAI,GAAG,CAAC;YAC7C,MAAM,SAAS,GAAG,MAAA,OAAO,CAAC,SAAS,mCAAI,KAAK,CAAC;YAE7C,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,GAAW,EAAE,EAAE,CACpC,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAClD,CAAC;QACN,CAAC;IACL,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,SAA6B,EAAE;QAC1C,OAAO;YACH,MAAM,EAAE,oBAAkB;YAC1B,MAAM,EAAE,IAAI;YACZ,SAAS,EAAE;gBACP;oBACI,OAAO,EAAE,2CAAoB;oBAC7B,QAAQ,EAAE,MAAM;iBACnB;aACJ;YACD,OAAO,EAAE,CAAC,2CAAoB,CAAC;SAClC,CAAC;IACN,CAAC;CACJ,CAAA;AAtCY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,eAAM,EAAC,EAAE,CAAC;IAGF,mBAAA,IAAA,eAAM,EAAC,2CAAoB,CAAC,CAAA;qDACK,sBAAe;GAH5C,kBAAkB,CAsC9B"}

package/src/types/nest-extended.config.d.ts

@@ -16,12 +16,27 @@ export interface SoftDeleteConfig {
      */
     getData: (user: any) => Record<string, any>;
 }
+export interface QueryParserConfig {
+    /** Maximum depth for nested objects. Default: 20 */
+    depth?: number;
+    /** Maximum number of array elements. Default: 100 */
+    arrayLimit?: number;
+    /** Allow dot notation in query keys. Default: false */
+    allowDots?: boolean;
+}
 export interface NestExtendedConfig {
     /**
      * Soft delete configuration.
      * If not provided, default soft delete behavior is used.
      */
     softDelete?: SoftDeleteConfig;
+    /**
+     * Query parser configuration using `qs`.
+     * - `true` or `undefined` (default): enables qs with defaults (depth: 20, arrayLimit: 100, allowDots: false)
+     * - `QueryParserConfig` object: enables qs with custom options
+     * - `false`: disables the qs query parser (uses Express default)
+     */
+    queryParser?: QueryParserConfig | boolean;
 }
 /**
  * Injection token for NestExtended configuration.

package/src/types/nest-extended.config.js.map

@@ -1 +1 @@
-{"version":3,"file":"nest-extended.config.js","sourceRoot":"","sources":["../../../../../packages/core/src/types/nest-extended.config.ts"],"names":[],"mappings":";;;AA4BA;;;GAGG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC"}
+{"version":3,"file":"nest-extended.config.js","sourceRoot":"","sources":["../../../../../packages/core/src/types/nest-extended.config.ts"],"names":[],"mappings":";;;AA6CA;;;GAGG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC"}