@lenne.tech/nest-server 11.21.0 → 11.21.2

package/README.md

@@ -1,165 +1,509 @@
 # lenne.Tech Nest Server
 
-Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB
-(or other databases).
+An enterprise-grade extension layer on top of [NestJS](https://nestjs.com/) for building secure, scalable server applications with **GraphQL**, **REST/Swagger**, and **MongoDB**.
 
-The lenne.tech nest server can be included as an npm package (`npm i @lenne.tech/nest-server`) or used directly as a
-project (`git clone https://github.com/lenneTech/nest-server.git`).
+[![License](https://img.shields.io/github/license/lenneTech/nest-server)](/LICENSE)
+[![npm version](https://img.shields.io/npm/v/@lenne.tech/nest-server)](https://www.npmjs.com/package/@lenne.tech/nest-server)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D%2020-brightgreen)](https://nodejs.org/)
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Features Overview](#features-overview)
+- [Architecture](#architecture)
+- [API-First Design](#api-first-design)
+- [Authentication](#authentication)
+- [Roles & Permissions](#roles--permissions)
+- [Multi-Tenancy](#multi-tenancy)
+- [Scalability](#scalability)
+- [API Versioning](#api-versioning)
+- [Webhook Support](#webhook-support)
+- [External System Integration](#external-system-integration)
+- [Core Modules](#core-modules)
+- [Configuration](#configuration)
+- [Development](#development)
+- [Documentation](#documentation)
+- [License](#license)
+
+## Quick Start
+
+The fastest way to get started is via the [lenne.Tech CLI](https://github.com/lenneTech/cli) with the [starter project](https://github.com/lenneTech/nest-server-starter):
 
-In combination with Angular (see [lenne.Tech Angular example](https://github.com/lenneTech/angular-example)
-incl. [ng-base](https://github.com/lenneTech/ng-base/tree/main/projects/ng-base/README.md)) the Nest Server is an ideal
-basis for your next project.
+```bash
+npm install -g @lenne.tech/cli
+lt server create <ServerName>
+cd <ServerName>
+pnpm start
+```
 
-[![License](https://img.shields.io/github/license/lenneTech/nest-server)](/LICENSE)
+Or install directly as a package:
 
-## Set up your server
+```bash
+pnpm add @lenne.tech/nest-server
+```
 
-The easiest way to set up your own server based on the lenne.Tech Nest Server is to use the
-[lenne.Tech Nest Server starter kit](https://github.com/lenneTech/nest-server-starter) via [CLI](https://github.com/lenneTech/cli):
+### Create a new module
 
+```bash
+lt server module <ModuleName>
 ```
-$ npm install -g @lenne.tech/cli
-$ lt server create <ServerName>
-$ cd <ServerName>
+
+This generates a complete module with model, inputs, resolver, controller, and service.
+
+## Features Overview
+
+| Category | Features |
+|----------|----------|
+| **API-First** | GraphQL (Apollo Server) + REST with Swagger/OpenAPI, dual API surface from single codebase |
+| **Authentication** | BetterAuth (IAM) with JWT, sessions, 2FA/TOTP, Passkey/WebAuthn, social login; Legacy JWT auth |
+| **Authorization** | Extensible role-based access control, field-level restrictions, system roles, hierarchy roles |
+| **Database** | MongoDB via Mongoose, CrudService with security pipeline, advanced filtering & pagination |
+| **Multi-Tenancy** | Header-based tenant isolation, membership management, hierarchy roles, auto-filtering |
+| **File Handling** | GridFS file storage, resumable uploads via TUS protocol (up to 50 GB) |
+| **Security** | Defense-in-depth: input validation, password hashing, role guard, audit fields, response filtering |
+| **Integration** | SCIM support, OAuth providers, multi-provider email (Mailjet/Brevo/SMTP), webhook support via lifecycle hooks |
+| **Scalability** | Stateless design, distributed migration locking, request-scoped isolation, query complexity analysis |
+| **API Versioning** | NestJS-native URI/header/media-type versioning, GraphQL schema evolution with deprecations |
+| **DevOps** | Health checks, database migrations, cron jobs, permissions reporting, system setup |
+
+## Architecture
+
+### Modular Extensibility
+
+The framework is built on a **Module Inheritance Pattern** — all core modules are designed to be extended through class inheritance in consuming projects:
+
+```typescript
+// Your project extends core classes — full control via override + super()
+export class UserService extends CoreUserService {
+  override async create(input, serviceOptions) {
+    // Custom pre-processing (validation, enrichment, ...)
+    const result = await super.create(input, serviceOptions);
+    // Custom post-processing (notifications, logging, ...)
+    return result;
+  }
+}
 ```
 
-## Description
+**Why inheritance over hooks/events:**
+- **Full control**: Override methods and precisely define what happens before/after `super()` calls
+- **Selective override**: Skip parts of the parent implementation entirely for custom logic
+- **Type safety**: TypeScript inheritance ensures proper typing and IDE support
+- **No silent failures**: No runtime event systems or hooks that can fail silently
 
-The lenne.Tech **Nest Server** is based on the [Nest](https://github.com/nestjs/nest) framework and can either be used
-and extended as a boilerplate (git clone) or integrated as a module (npm package).
+### Two-Layer Structure
 
-Since the server is based on [Nest](https://nestjs.com/), you can find all information about extending your server
-in the [documentation of Nest](https://docs.nestjs.com/).
+- `src/core/` — Reusable framework components (exported via npm, extended by projects)
+- `src/server/` — Internal test/demo implementation (not exported)
 
-We use Mongoose Module from nestjs. (https://docs.nestjs.com/techniques/mongodb)
+Every core module supports both **auto-registration** (zero-config) and **manual registration** (full customization via extended module). New modules can be added alongside existing ones without modifying the framework.
 
-To create a new Module with model, inputs, resolver and service you can use the [CLI](https://github.com/lenneTech/cli):
+### Framework Stack
 
+- [NestJS](https://nestjs.com/) — Server framework
+- [Apollo Server](https://www.apollographql.com/docs/apollo-server/) — GraphQL API (optional, disable via `graphQl: false`)
+- [Mongoose](https://mongoosejs.com/) — MongoDB ODM
+- [Swagger/OpenAPI](https://swagger.io/) — REST API documentation
+
+## API-First Design
+
+The server follows an API-first approach where API contracts are the primary interface:
+
+### Dual API Surface
+
+Both **GraphQL** and **REST** endpoints are served from the same codebase and business logic. The `@UnifiedField()` decorator generates schemas for both APIs simultaneously:
+
+```typescript
+@UnifiedField({ description: 'User email address', isOptional: false })
+email: string;
+// → Generates: GraphQL @Field() + Swagger @ApiProperty() + class-validator checks
 ```
-$ lt server module <ModuleName>
+
+### Documented API Structure
+
+- **GraphQL Introspection** — Full schema introspection for client code generation (configurable via `graphQl.introspection`)
+- **Swagger/OpenAPI** — Auto-generated REST API documentation from decorators
+- **SpectaQL** — Visual GraphQL documentation (`pnpm run docs`)
+- **Permissions Dashboard** — Interactive HTML report of all endpoints, roles, and security checks (`/permissions`)
+
+### GraphQL Features
+
+- Custom scalars: `Date`, `DateTime`, `JSON`, `Any`
+- WebSocket subscriptions with authentication
+- Query complexity analysis (DoS prevention)
+- File upload support via `graphql-upload`
+- Automatic enum registration
+
+## API Versioning
+
+NestJS provides built-in [API versioning](https://docs.nestjs.com/techniques/versioning) support with multiple strategies. Projects can enable versioning for REST endpoints:
+
+| Strategy | Example | Use Case |
+|----------|---------|----------|
+| **URI** | `/v1/users`, `/v2/users` | Most common, explicit in URL |
+| **Header** | `X-API-Version: 2` | Clean URLs, version in header |
+| **Media Type** | `Accept: application/vnd.app.v2+json` | Content negotiation |
+
+```typescript
+// main.ts — enable URI versioning
+app.enableVersioning({ type: VersioningType.URI });
+
+// controller — assign to version
+@Controller({ path: 'users', version: '2' })
+export class UsersV2Controller { ... }
+
+// or per-route
+@Get()
+@Version('2')
+async findAll() { ... }
 ```
 
-We are currently working on a documentation of the extensions and auxiliary classes that the
-[lenne.Tech Nest Server](https://github.com/lenneTech/nest-server) contains. As long as this is not yet available,
-have a look at the [source code](https://github.com/lenneTech/nest-server/tree/master/src/core).
-There you will find a lot of things that will help you to extend your server, such as:
+**GraphQL** APIs are evolved through schema additions and field deprecations (`@deprecated`) rather than versioning, following the [GraphQL best practice](https://graphql.org/learn/best-practices/#versioning) of continuous evolution.
 
-- [GraphQL scalars](https://github.com/lenneTech/nest-server/tree/master/src/core/common/scalars)
-- [Filter and pagination](https://github.com/lenneTech/nest-server/tree/master/src/core/common/args)
-- [Decorators for restrictions and roles](https://github.com/lenneTech/nest-server/tree/master/src/core/common/decorators)
-- [Authorisation handling](https://github.com/lenneTech/nest-server/tree/master/src/core/modules/auth)
-- [Ready to use user module](https://github.com/lenneTech/nest-server/tree/master/src/core/modules/user)
-- [Common helpers](https://github.com/lenneTech/nest-server/tree/master/src/core/common/helpers) and
-  [helpers for tests](https://github.com/lenneTech/nest-server/blob/master/src/test/test.helper.ts)
-- ...
+## Webhook Support
 
-## Running the server
+The framework provides webhook capabilities through two mechanisms:
 
-```bash
-# development
-$ pnpm start
+### BetterAuth Lifecycle Hooks
 
-# watch mode
-$ pnpm run start:dev
+BetterAuth supports [hooks](https://www.better-auth.com/docs/concepts/hooks) that intercept authentication lifecycle events. Projects can extend the BetterAuth service via the Module Inheritance Pattern to react to these events:
 
-# production mode
-$ pnpm run start:prod
+```typescript
+export class AuthService extends CoreBetterAuthService {
+  override async signIn(input, serviceOptions) {
+    const result = await super.signIn(input, serviceOptions);
+    // Trigger webhook after successful sign-in
+    await this.webhookService.dispatch('auth.sign-in', { userId: result.user.id });
+    return result;
+  }
+}
 ```
 
+Authentication events that can be intercepted include: sign-in, sign-up, sign-out, session creation, token refresh, email verification, 2FA verification, and more.
 
-## Test
+### Module Inheritance for Custom Webhooks
 
-```bash
-# unit tests
-$ pnpm test
+Any service method can be extended to dispatch webhooks via the Module Inheritance Pattern:
+
+```typescript
+export class ProjectService extends CoreProjectService {
+  override async create(input, serviceOptions) {
+    const project = await super.create(input, serviceOptions);
+    // Dispatch webhook on project creation
+    await this.webhookService.dispatch('project.created', project);
+    return project;
+  }
+}
+```
+
+This approach allows projects to add webhook dispatching to any CRUD operation or custom business logic without modifying the framework.
+
+## Authentication
+
+Two authentication systems are available — BetterAuth (recommended) and Legacy JWT auth:
+
+### BetterAuth (IAM) — Recommended
+
+Modern, session-based authentication with plugin architecture:
+
+| Feature | Config |
+|---------|--------|
+| **JWT tokens** | `betterAuth.jwt: true` |
+| **Two-Factor (2FA/TOTP)** | `betterAuth.twoFactor: true` |
+| **Passkey/WebAuthn** | `betterAuth.passkey: true` |
+| **Social login** (Google, GitHub, Apple, ...) | `betterAuth.socialProviders: { ... }` |
+| **Email verification** | `betterAuth.emailVerification: { ... }` |
+| **Rate limiting** | `betterAuth.rateLimit: { max: 10 }` |
+| **Cross-subdomain cookies** | `betterAuth.crossSubDomainCookies: true` |
+| **Disable sign-up** | `betterAuth.emailAndPassword.disableSignUp: true` |
+
+Three integration patterns: zero-config, config-based, or manual (`autoRegister: false`).
+
+BetterAuth provides **lifecycle hooks** for reacting to authentication events (sign-in, sign-up, session creation, etc.), enabling integration with external systems. See [Webhook Support](#webhook-support) for details.
+
+### Legacy Auth (JWT)
+
+Passport-based JWT authentication with sign-in, sign-up, refresh tokens, and rate limiting. Runs in parallel with BetterAuth during migration. Legacy endpoints can be disabled via `auth.legacyEndpoints.enabled: false`.
+
+A built-in **migration status query** (`betterAuthMigrationStatus`) tracks progress and indicates when legacy auth can be safely disabled.
+
+## Roles & Permissions
+
+The role and permission system is designed for extensibility — from simple role checks to complex multi-tenant hierarchies.
+
+### System Roles (Runtime Checks)
+
+System roles (`S_` prefix) are evaluated dynamically at runtime, never stored in the database:
+
+| Role | Purpose |
+|------|---------|
+| `S_USER` | Any authenticated user |
+| `S_VERIFIED` | Email-verified users |
+| `S_CREATOR` | Creator of the resource |
+| `S_SELF` | User accessing own data |
+| `S_EVERYONE` | Public access |
+| `S_NO_ONE` | Permanently locked |
+
+### Method & Field-Level Authorization
+
+```typescript
+// Method-level: who can call this endpoint?
+@Roles(RoleEnum.ADMIN)
+async deleteUser() { ... }
+
+// Field-level: who can see/modify this field?
+@Restricted(RoleEnum.S_SELF, RoleEnum.ADMIN)
+email: string;
+
+// Membership-based: only team members can see this field
+@Restricted({ memberOf: 'teamMembers' })
+internalNotes: string;
+```
 
-# e2e tests
-$ pnpm run test:e2e
+### Custom Role Hierarchies
 
-# test coverage
-$ pnpm run test:cov
+Projects can define custom role hierarchies beyond the built-in roles:
+
+```typescript
+// Custom hierarchy with level-based comparison
+const HR = createHierarchyRoles({ viewer: 1, editor: 2, admin: 3, owner: 4 });
+
+@Roles(HR.EDITOR) // requires level >= 2 (editor, admin, or owner)
+async editDocument() { ... }
 ```
 
-Configuration for testing:
+### Resource-Level Security
+
+Every model can override `securityCheck()` for fine-grained, context-aware access control:
+
+```typescript
+export class Project extends CorePersistenceModel {
+  override securityCheck(user: any, force?: boolean): this {
+    // Remove sensitive fields based on user context
+    if (!this.hasRole(user, RoleEnum.ADMIN)) {
+      this.budget = undefined;
+    }
+    return this;
+  }
+}
 ```
-Node interpreter: /user/local/bin/node
-Working directory: FULL_PATH_TO_PROJECT_DIR
-Test command: pnpm run test:e2e
+
+### Permissions Reporting
+
+The built-in Permissions module scans all endpoints and generates security audit reports (HTML dashboard, JSON, Markdown) showing coverage of `@Roles`, `@Restricted`, and `securityCheck()` across the entire API.
+
+## Multi-Tenancy
+
+Full multi-tenancy support with header-based tenant isolation, membership management, and automatic data filtering:
+
+```typescript
+// config.env.ts
+multiTenancy: {
+  headerName: 'x-tenant-id',
+  roleHierarchy: { member: 1, manager: 2, owner: 3 },
+  adminBypass: true,
+}
+
+// Usage in resolvers
+@Roles(DefaultHR.MANAGER)
+async updateProject(@CurrentTenant() tenantId: string) { ... }
 ```
 
-## Debugging
+- **Membership validation** — `CoreTenantGuard` validates membership on every request
+- **Hierarchy roles** — Level comparison (higher includes lower), custom via `createHierarchyRoles()`
+- **Automatic data isolation** — Mongoose tenant plugin filters all queries by tenant context
+- **Defense-in-depth** — Guard validation + Mongoose plugin Safety Net combination
+- **Multi-membership** — Users can belong to multiple tenants with different roles
+- **Status management** — ACTIVE, INVITED, SUSPENDED membership states
+- **`@SkipTenantCheck()`** — Opt out per endpoint
+- **`@CurrentTenant()`** — Parameter decorator for validated tenant ID
+
+## Scalability
+
+The architecture is designed for horizontal scalability:
+
+- **Stateless request handling** — No server-side session state required (JWT or BetterAuth sessions in MongoDB)
+- **Request-scoped isolation** — `AsyncLocalStorage`-based `RequestContext` ensures safe concurrent request processing without shared mutable state
+- **Distributed migration locking** — MongoDB-based distributed locks via `synchronizedMigration()` for safe multi-instance deployments
+- **Query complexity analysis** — Configurable complexity limits prevent expensive GraphQL queries from consuming excessive resources
+- **Connection pooling** — Managed transparently via Mongoose/MongoDB driver
+- **Configurable MongoDB** — Support for replica sets and connection options via `mongoose.uri` configuration
 
-Configuration for debugging is:
+## External System Integration
+
+### Authentication Providers
+
+BetterAuth supports OAuth integration with external identity providers (Google, GitHub, Apple, Discord, and more) via the `socialProviders` configuration.
+
+### SCIM Support
+
+Built-in [SCIM](http://www.simplecloud.info/) (System for Cross-domain Identity Management) filter parsing and MongoDB query conversion for enterprise identity management:
+
+```typescript
+scimToMongo('userName eq "Joe" and emails[type eq "work"]')
+// → MongoDB: { $and: [{ userName: 'Joe' }, { emails: { $elemMatch: { type: 'work' } } }] }
 ```
-Node interpreter: /user/local/bin/node
-Node parameters: node_modules/@nestjs/cli/bin/nest.js start --debug --watch
-Working directory: FULL_PATH_TO_PROJECT_DIR
-JavaScript file: src/main.ts
+
+Supported operators: `eq`, `co`, `sw`, `ew`, `gt`, `ge`, `lt`, `le`, `pr`, `aco`, `and`, `or`.
+
+### Email Providers
+
+Pluggable email provider abstraction with support for:
+- **Mailjet** — API-based transactional email
+- **Brevo** — API-based transactional email (formerly Sendinblue)
+- **SMTP** — Standard SMTP via Nodemailer
+
+All providers use the same `EmailService` interface with EJS template engine and locale-aware template resolution.
+
+### Extensibility
+
+The Module Inheritance Pattern ensures any core module can be extended to integrate with external systems — override service methods to add API calls, event publishing, webhook dispatching, or data synchronization without modifying the framework. See also [Webhook Support](#webhook-support).
+
+## Core Modules
+
+| Module | Purpose |
+|--------|---------|
+| **Auth** | Legacy JWT authentication with Passport strategies |
+| **BetterAuth** | Modern auth (2FA, Passkey, Social, sessions, lifecycle hooks) |
+| **User** | User management, profile, roles, verification |
+| **Tenant** | Multi-tenancy with membership and hierarchy roles |
+| **File** | File upload/download with MongoDB GridFS |
+| **Tus** | Resumable file uploads via [tus.io](https://tus.io/) protocol (up to 50 GB) |
+| **ErrorCode** | Centralized error codes with unique identifiers |
+| **HealthCheck** | REST (`/health`) and GraphQL health monitoring |
+| **Migrate** | MongoDB migration system with distributed locking for cluster deployments |
+| **Permissions** | Security audit dashboard (HTML, JSON, Markdown reports) |
+| **SystemSetup** | Initial admin creation for fresh deployments |
+
+### CrudService
+
+Abstract base service providing a complete CRUD pipeline with built-in security:
+
+```typescript
+export class ProjectService extends CrudService<Project> {
+  // Inherits: find, findOne, create, update, delete
+  // With: input validation, field selection, security checks, population
+}
 ```
-see [Debug.run.xml](.run/Debug.run.xml)
 
-### Debugging as package in a project
-Via `pnpm link` the NestJS Server can be linked into the project.
+**Advanced querying** with comparison operators (`eq`, `ne`, `gt`, `in`, `contains`, `regex`, ...), logical operators (`AND`, `OR`), pagination, sorting, and GraphQL-driven population.
 
-In NestJS Server run `pnpm run watch` to watch for changes and rebuild automatically.
-Project use following scripts (via `package.json`):
+### Security Layers
 
-- `pnpm run link:nest-server` (for `pnpm link /path/to/nest-server`)
-- `pnpm run unlink:nest-server` (for `pnpm unlink @lenne.tech/nest-server && pnpm install`)
+Defense-in-depth security architecture with three layers:
 
-## Configuration
+**Layer 1: Guards & Middleware**
+- `@Roles()` — Method-level authorization (includes JWT auth automatically)
+- `@Restricted()` — Field-level access control with process type support (INPUT/OUTPUT)
+- System roles — `S_USER`, `S_VERIFIED`, `S_CREATOR`, `S_SELF`, `S_EVERYONE`, `S_NO_ONE`
 
-The configuration of the server is done via the `src/config.env.ts` file. This file is a TypeScript file that exports 
-an object with the configuration values. It is automatically integrated into the `ConfigService` 
-(see src/core/common/services/config.service.ts).
+**Layer 2: CrudService Pipeline**
+- Input validation — MapAndValidatePipe with whitelist checking
+- `@UnifiedField()` — Single decorator for GraphQL, Swagger, and validation
+- `securityCheck()` — Resource-level security on model instances
 
-### Environment variables
+**Layer 3: Mongoose Plugins (Safety Net)**
+- Password Plugin — Automatic BCrypt hashing
+- Role Guard Plugin — Prevents unauthorized role escalation at DB level
+- Audit Fields Plugin — Automatic `createdBy`/`updatedBy` tracking
+- Tenant Isolation Plugin — Automatic tenant filtering
 
-To protect sensitive data and to avoid committing them to the repository the `.env` file can be used.
-An example `.env` file is provided in the `.env.example` file.
+**Interceptor Chain:**
+- ResponseModelInterceptor — Plain objects to CoreModel conversion
+- TranslateResponseInterceptor — Multi-language support via `Accept-Language`
+- CheckSecurityInterceptor — Executes `securityCheck()` and removes secret fields
+- CheckResponseInterceptor — Enforces `@Restricted()` field-level filtering
+
+### Email & Templates
+
+Multi-provider email service (Mailjet, Brevo, SMTP) with EJS template engine and locale-aware template resolution.
+
+## Configuration
 
-There are multiple ways to manipulate or extend the configuration via environment variables:
-1. Via "normal" integration of the environment variables into the `src/config.env.ts`
-2. Via JSON in the `NEST_SERVER_CONFIG` environment variable
-3. Via single environment variables with the prefix `NSC__` (Nest Server Config)
+Configuration is managed via `src/config.env.ts` with environment-based profiles (development, local, production):
 
-#### Normal environment variables
-Using `dotenv` (see https://www.dotenv.org/) environment variables can directly integrated into the 
-`src/config.env.ts` via `process.env`. E.g.:
 ```typescript
 export const config = {
-  development: {
-    port: process.env.PORT || 3000,
+  local: {
+    port: 3000,
+    graphQl: { driver: 'apollo' },
+    mongoose: { uri: 'mongodb://localhost/my-app' },
+    betterAuth: { secret: 'my-secret', jwt: true, twoFactor: true },
+    multiTenancy: { roleHierarchy: { member: 1, manager: 2, owner: 3 } },
   },
 };
 ```
 
-#### JSON
-The `NEST_SERVER_CONFIG` is the environment variable for the server configuration. 
-The value of `NEST_SERVER_CONFIG` must be a (multiline) JSON string that will be parsed by the server 
-(see config.env.ts). The keys will override the other configuration values via deep merge
-(see https://lodash.com/docs/4.17.15#merge, without array merging).
+### Configuration Patterns
 
-#### Single config variables
-The prefix `NSC__` (**N**est **S**erver **C**onfig) can be used to set single configuration values via environment 
-variables. The key is the name of the configuration value in uppercase and with double underscores (`__`) instead of 
-dots. Single underscores are used to separate compound terms like `DEFAULT_SENDER` for `defaultSender`.
-For example, the configuration value `email.defaultSender.name` can be set via the environment variable 
-`NSC__EMAIL_DEFAULT_SENDER_NAME`.
+- **Presence implies enabled**: `rateLimit: {}` enables with defaults, `undefined` stays disabled
+- **Boolean shorthand**: `jwt: true` enables with defaults, `{ expiresIn: '1h' }` customizes
 
-## Documentation
-The API and developer documentation can automatically be generated.
+### Environment Variables
+
+Three methods to override configuration:
+
+1. **Direct** — `process.env.PORT` in `config.env.ts`
+2. **JSON** — `NEST_SERVER_CONFIG` environment variable (deep merge)
+3. **Prefixed** — `NSC__EMAIL__DEFAULT_SENDER__NAME` for `email.defaultSender.name`
+
+## Development
+
+**Requirements:** Node.js >= 20, MongoDB, pnpm
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start in development mode
+pnpm run start:dev
+
+# Run tests (Vitest E2E)
+pnpm test
+
+# Run tests with coverage
+pnpm run vitest:cov
+
+# Lint (oxlint) & format (oxfmt)
+pnpm run lint
+pnpm run format
+
+# Build
+pnpm run build
+
+# Generate documentation
+pnpm run docs
+```
+
+### Debugging as package
+
+Link into a consuming project for local development:
 
 ```bash
-# generate and serve documentation
-$ pnpm run docs
+# In nest-server
+pnpm run watch
+
+# In your project
+pnpm run link:nest-server     # pnpm link /path/to/nest-server
+pnpm run unlink:nest-server   # pnpm unlink @lenne.tech/nest-server && pnpm install
 ```
 
+### Versioning
+
+`MAJOR.MINOR.PATCH` — MAJOR mirrors NestJS version, MINOR = breaking changes, PATCH = non-breaking improvements.
+
+## Documentation
+
+- [Request Lifecycle](docs/REQUEST-LIFECYCLE.md) — Complete request pipeline, security architecture, interceptor chain
+- [Migration Guides](migration-guides/) — Version upgrade instructions
+- [Starter Project](https://github.com/lenneTech/nest-server-starter) — Reference implementation
+- [CLI](https://github.com/lenneTech/cli) — Code generation tools
+- [NestJS Documentation](https://docs.nestjs.com/) — Framework docs
+
 ## Thanks
 
-Many thanks to the developers of [Nest](https://github.com/nestjs/nest)
+Many thanks to the developers of [NestJS](https://github.com/nestjs/nest)
 and all the developers whose packages are used here.
 
 ## License
 
-MIT - see LICENSE
+MIT - see [LICENSE](/LICENSE)

package/dist/core/common/helpers/input.helper.js

@@ -426,13 +426,16 @@ function prepareServiceOptionsForCreate(serviceOptions) {
     return serviceOptions;
 }
 function processDeep(data, func, options) {
-    const { processedObjects, specialClasses, specialFunctions, specialProperties } = {
-        processedObjects: new WeakMap(),
-        specialClasses: [],
-        specialFunctions: [],
-        specialProperties: [],
-        ...options,
+    const resolvedOptions = {
+        processedObjects: options?.processedObjects ?? new WeakMap(),
+        specialClasses: options?.specialClasses ?? [],
+        specialFunctions: options?.specialFunctions ?? [],
+        specialProperties: options?.specialProperties ?? [],
     };
+    return processDeepInternal(data, func, resolvedOptions);
+}
+function processDeepInternal(data, func, options) {
+    const { processedObjects, specialClasses, specialFunctions, specialProperties } = options;
     if (!data) {
         return func(data);
     }
@@ -443,7 +446,7 @@ function processDeep(data, func, options) {
         processedObjects.set(data, true);
     }
     if (Array.isArray(data)) {
-        return func(data.map((item) => processDeep(item, func, { processedObjects, specialClasses })));
+        return func(data.map((item) => processDeepInternal(item, func, options)));
     }
     if (typeof data === 'object') {
         if (specialFunctions.find((sF) => typeof data[sF] === 'function') ||
@@ -457,7 +460,7 @@ function processDeep(data, func, options) {
             }
         }
         for (const [key, value] of Object.entries(data)) {
-            data[key] = processDeep(value, func, { processedObjects, specialClasses });
+            data[key] = processDeepInternal(value, func, options);
         }
         return func(data);
     }