@lenne.tech/nest-server 11.24.2 → 11.24.3

package/migration-guides/11.24.2-to-11.24.3.md

@@ -0,0 +1,255 @@
+# Migration Guide: 11.24.2 → 11.24.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Simplified enum API, `registerEnums()`, expanded mail transports |
+| **Bugfixes** | Optional enum fields no longer rejected as "must be an object" |
+| **Deprecations** | `enum: { enum: MyEnum, enumName: ... }` long form (still works) |
+| **Migration Effort** | ~5 min setup + find-and-replace per project |
+
+---
+
+## Quick Start (Minimum — No Code Changes Required)
+
+```bash
+pnpm install @lenne.tech/nest-server@11.24.3
+pnpm run build
+pnpm test
+```
+
+Everything works as before. You will see **deprecation warnings** for every
+`enum: { enum: ... }` usage at startup. These are informational — no behavior
+changes, no errors. Follow the steps below to migrate and silence them.
+
+---
+
+## What Changed
+
+### Bugfix: Optional Enum Validation
+
+Fields like `status?: MyEnum` were rejected with `"must be an object"`.
+Fixed — `IsEnum()` is now the authoritative validator for enum fields.
+
+### New: Simplified Enum API
+
+The `{ enum: MyEnum }` wrapper is no longer needed:
+
+```typescript
+// OLD (deprecated — still works, emits warning)
+@UnifiedField({ enum: { enum: StatusEnum, enumName: 'StatusEnum' } })
+
+// NEW (recommended)
+@UnifiedField({ enum: StatusEnum })
+```
+
+### New: `registerEnums()` Bulk Registration
+
+One-line setup per project — enables enum name auto-detection so you can
+drop `enumName` entirely:
+
+```typescript
+import * as Enums from './common/enums';
+import { registerEnums } from '@lenne.tech/nest-server';
+registerEnums(Enums);
+```
+
+### New: `isArray` Auto-Propagation
+
+Array enum fields no longer need `options: { each: true }`:
+
+```typescript
+// OLD
+@UnifiedField({ enum: { enum: X, options: { each: true } }, isArray: true, type: () => X })
+
+// NEW
+@UnifiedField({ enum: X, isArray: true, type: () => X })
+```
+
+### New: Expanded Mail Transports
+
+`email.smtp` now accepts all nodemailer transports. `{ jsonTransport: true }`
+is useful for CI/e2e tests (no SMTP server needed). A runtime guard prevents
+accidental use in production/staging.
+
+---
+
+## Migration Steps
+
+### Step 1: Set Up `registerEnums()` (1 minute)
+
+This enables auto-detection of enum names from barrel exports. After this
+step, `enumName` is no longer needed.
+
+**Prerequisite:** Your project has a barrel file that re-exports all enums
+(e.g. `src/server/common/enums/index.ts`). If not, create one.
+
+```typescript
+// src/server/common/enums/index.ts
+export { ContactStatusEnum } from './contact-status.enum';
+export { IndustryEnum } from './industry.enum';
+// ... all your enums
+```
+
+Then add one line to your module setup:
+
+```typescript
+// src/server/server.module.ts (or main.ts, before NestFactory.create)
+import * as Enums from './common/enums';
+import { registerEnums } from '@lenne.tech/nest-server';
+
+registerEnums(Enums);
+```
+
+**How it works:** `import * as Enums` creates an object where the keys are
+the export names (`{ ContactStatusEnum: {...}, IndustryEnum: {...} }`).
+`registerEnums()` iterates the entries, filters out non-enums, and registers
+each enum for both Swagger and GraphQL under its export name.
+
+**Verify:** Start your server — enum names should appear correctly in
+Swagger UI and GraphQL schema. If you see missing enum names, check that
+the enum is exported from the barrel file.
+
+### Step 2: Transform Enum Declarations (find-and-replace)
+
+Use these regex patterns to transform all `@UnifiedField` enum usages.
+Run them in order.
+
+**Pattern A — Remove `options: { each: true }` from array enums:**
+
+```
+Search:  enum: \{ enum: (\w+),\s*enumName: '[^']+',\s*options: \{ each: true \}\s*\}
+Replace: enum: $1
+```
+
+**Pattern B — Long form with enumName → shortcut:**
+
+```
+Search:  enum: \{ enum: (\w+),\s*enumName: '[^']+'\s*\}
+Replace: enum: $1
+```
+
+**Pattern C — Long form without enumName → shortcut:**
+
+```
+Search:  enum: \{ enum: (\w+)\s*\}
+Replace: enum: $1
+```
+
+**After each pattern:** Build and run tests to verify nothing broke:
+
+```bash
+pnpm run build && pnpm test
+```
+
+### Step 3: Verify (1 minute)
+
+```bash
+# Check no long-form patterns remain
+grep -rn "enum: { enum:" src/ --include="*.ts"
+
+# Start server — should have zero deprecation warnings
+pnpm start
+```
+
+---
+
+## Cheat Sheet
+
+| Before (deprecated) | After |
+|---------------------|-------|
+| `enum: { enum: X }` | `enum: X` |
+| `enum: { enum: X, enumName: 'X' }` | `enum: X` |
+| `enum: { enum: X, options: { each: true } }, isArray: true` | `enum: X, isArray: true` |
+| `enum: { enum: X, enumName: 'X', options: { each: true } }, isArray: true` | `enum: X, isArray: true` |
+
+For cases where you need explicit control:
+
+| Need | Solution |
+|------|----------|
+| Custom enum name in schema | `enum: X, enumName: 'CustomName'` |
+| Disable auto-detection | `enum: X, enumName: null` |
+| Skip all validation | `enum: X, isAny: true` |
+| Custom validator | `enum: X, validator: (opts) => [...]` |
+
+---
+
+## Compatibility Notes
+
+### Deprecation Warnings
+
+After updating, every `enum: { enum: ... }` usage emits a `console.warn`
+at class definition time (server startup). This is intentional — it helps
+you find all places that need migration. The warnings disappear once you
+complete Steps 1–3.
+
+If you need to update the package but cannot migrate immediately, the
+warnings are purely informational — no behavior changes.
+
+### Existing `options: { each: true }`
+
+Explicit `options: { each: true }` continues to work. The auto-propagation
+from `isArray` only applies when `each` is not already set. You can remove
+the explicit option at your own pace.
+
+### Custom `isAny` / `validator` Workarounds
+
+If you added `isAny: true` or a custom `validator` to work around the
+optional-enum bug, both continue to work. You can safely remove them.
+
+### SMTP Configuration
+
+All existing `email.smtp` configurations continue to work unchanged. The
+type is a strict superset of the previous type.
+
+---
+
+## Troubleshooting
+
+### "JSONTransport is not permitted in production/staging environments"
+
+This new runtime guard triggers when `email.smtp` is `{ jsonTransport: true }`
+in `NODE_ENV=production` or `NODE_ENV=staging`. JSONTransport silently
+discards all mail — use a real transport in production.
+
+### Enum name missing in Swagger/GraphQL after migration
+
+Ensure the enum is exported from your barrel file and `registerEnums()` is
+called before NestJS bootstraps. Check with:
+
+```typescript
+import { enumNameRegistry } from '@lenne.tech/nest-server';
+console.log(enumNameRegistry.get(MyEnum)); // Should print the enum name
+```
+
+### Optional enum fields still rejected
+
+Verify: (1) `enum:` is set on the field, (2) the field type is the enum
+type, (3) you're running 11.24.3+ (`pnpm list @lenne.tech/nest-server`).
+
+---
+
+## Module Documentation
+
+| Module / File | Documentation |
+|---------------|---------------|
+| `@UnifiedField` decorator | [`src/core/common/decorators/unified-field.decorator.ts`](../src/core/common/decorators/unified-field.decorator.ts) — JSDoc on `UnifiedFieldOptions.enum` and `enumName` |
+| `registerEnum` / `registerEnums` | [`src/core/common/helpers/register-enum.helper.ts`](../src/core/common/helpers/register-enum.helper.ts) — JSDoc with `@example` blocks |
+| `MailTransportOptions` type | [`src/core/common/interfaces/server-options.interface.ts`](../src/core/common/interfaces/server-options.interface.ts) — all nodemailer transport types |
+| `FRAMEWORK-API.md` | [`FRAMEWORK-API.md`](../FRAMEWORK-API.md) — auto-generated API reference (v11.24.3) |
+
+### New Public Exports (via `src/index.ts`)
+
+- `registerEnums(namespace, options?)` — bulk-register all enums from a barrel-export namespace
+- `graphqlEnumRegistry` — WeakSet tracking GraphQL-registered enums (advanced use only)
+- `MailTransportOptions` — union type of all nodemailer transport configurations
+- `RegisterEnumsOptions` — options interface for `registerEnums()`
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter)
+- [nodemailer transports](https://nodemailer.com/transports/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.24.2",
+  "version": "11.24.3",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -15,7 +15,7 @@
   "license": "MIT",
   "scripts": {
     "build": "rimraf dist && nest build && pnpm run build:copy-types && pnpm run build:copy-templates && pnpm run build:add-type-references && pnpm run build:framework-api",
-    "build:framework-api": "npx tsx scripts/generate-framework-api.ts",
+    "build:framework-api": "tsx scripts/generate-framework-api.ts",
     "build:copy-types": "mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
     "build:copy-templates": "mkdir -p dist/core/modules/migrate/templates && cp src/core/modules/migrate/templates/migration-project.template.ts dist/core/modules/migrate/templates/",
     "build:add-type-references": "node scripts/add-type-references.js",
@@ -152,6 +152,7 @@
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
+    "tsx": "4.21.0",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",

package/src/core/common/decorators/unified-field.decorator.ts

@@ -117,8 +117,47 @@ export interface UnifiedFieldOptions {
    * - undefined (default): Normal @UnifiedField behavior
    */
   exclude?: boolean;
-  /** Enum for class-validator */
-  enum?: { enum: EnumAllowedTypes; enumName?: string; options?: ValidationOptions };
+  /**
+   * Enum for class-validator.
+   *
+   * **Recommended form:**
+   * ```typescript
+   * @UnifiedField({ enum: MyEnum })
+   * @UnifiedField({ enum: MyEnum, enumName: 'MyEnum' })
+   * ```
+   *
+   * **Deprecated long form** (still works, emits a deprecation warning):
+   * ```typescript
+   * @UnifiedField({ enum: { enum: MyEnum, enumName: 'MyEnum' } })
+   * ```
+   * The long form will be removed in a future MINOR version. Use the shortcut
+   * form with the top-level `enumName` property instead.
+   *
+   * Why not auto-detect from the property type? TypeScript's `emitDecoratorMetadata`
+   * reflects enum types as their base primitive in `design:type` — required string
+   * enums become `String`, numeric enums become `Number`. Optional enum fields
+   * (`status?: MyEnum`) are reflected as `Object` because TS sees the union
+   * `MyEnum | undefined`. In all cases the original enum object reference is lost
+   * at compile time, so the decorator cannot recover it without an explicit
+   * `enum:` option.
+   */
+  enum?: EnumAllowedTypes | { enum: EnumAllowedTypes; enumName?: string; options?: ValidationOptions };
+  /**
+   * Explicit name for the enum in Swagger/GraphQL schema.
+   *
+   * When set, this name is used in the generated API schema. When omitted,
+   * the decorator auto-detects the name via `registerEnum()`, GraphQL metadata,
+   * or the enum's runtime name.
+   *
+   * Set to `null` to explicitly disable auto-detection (swagger receives `undefined`).
+   *
+   * **Note:** In the deprecated long-form, `enum: { enum: X, enumName: null }` passes
+   * `null` directly to swagger (not `undefined`). The top-level `enumName: null` normalizes
+   * to `undefined` for consistency. Both forms disable auto-detection effectively.
+   *
+   * Takes precedence over `enumName` inside a long-form `enum: { ... }` object.
+   */
+  enumName?: string | null;
   /** Example value for swagger api documentation */
   example?: any;
   /** Options for graphql */
@@ -161,10 +200,99 @@ export interface UnifiedFieldOptions {
   validator?: (opts: ValidationOptions) => PropertyDecorator[];
 }
 
+type NormalizedEnumOptions = { enum: EnumAllowedTypes; enumName?: string; options?: ValidationOptions };
+
+/**
+ * Detect whether `value` is the long-form `{ enum: MyEnum, ... }` options
+ * object. If it is not, we treat `value` itself as the enum (shortcut form).
+ *
+ * Discrimination strategy (three layers):
+ *
+ * 1. **Own `enum` key** — a plain TS keyword enum (`enum Foo { ... }`) never
+ *    has a member named `enum` (reserved keyword). Const-object enums CAN,
+ *    but it's rare.
+ *
+ * 2. **Inner value is an object** — in the long form, `value.enum` holds an
+ *    enum object (typeof 'object'). A const-object enum member named `enum`
+ *    with a primitive value (string / number) is ruled out here.
+ *
+ * 3. **Inner value looks like an enum** — all of the inner object's own
+ *    values must be strings or numbers. This guards against the theoretical
+ *    case where a const-object enum has `enum: { nested: true }` as a member
+ *    — that inner object's values are booleans, so it fails this check and
+ *    the outer object is correctly treated as the shortcut form.
+ */
+function isEnumOptionsObject(value: unknown): value is NormalizedEnumOptions {
+  if (typeof value !== 'object' || value === null) return false;
+  if (!Object.prototype.hasOwnProperty.call(value, 'enum')) return false;
+  const inner = (value as Record<string, unknown>).enum;
+  if (typeof inner !== 'object' || inner === null) return false;
+  // A valid enum object contains only string or number values (enum members).
+  // If the inner object has non-primitive values it cannot be an enum, so the
+  // outer object is the enum itself (shortcut form with a member named 'enum').
+  const vals = Object.values(inner as Record<string, unknown>);
+  return vals.length > 0 && vals.every((v) => typeof v === 'string' || typeof v === 'number');
+}
+
+/**
+ * Detect likely misconfiguration: an object with `enumName` or `options` keys
+ * but no `enum` key. This pattern looks like a long-form options object where
+ * the required `enum` property was forgotten. Without this guard the object
+ * would be silently treated as the enum itself (shortcut form), leading to
+ * incorrect validation (e.g. only accepting the string "Status" instead of
+ * actual enum members).
+ */
+function warnIfLikelyMisconfiguredEnumOptions(value: unknown, propertyHint: string): void {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return;
+  const obj = value as Record<string, unknown>;
+  if (
+    !Object.prototype.hasOwnProperty.call(obj, 'enum') &&
+    (Object.prototype.hasOwnProperty.call(obj, 'enumName') || Object.prototype.hasOwnProperty.call(obj, 'options'))
+  ) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[@UnifiedField] Probable misconfiguration on "${propertyHint}": the enum option has ` +
+        `"enumName" or "options" but no "enum" key. Did you mean { enum: MyEnum, enumName: ... }? ` +
+        `The object will be treated as the enum itself (shortcut form), which is likely wrong.`,
+    );
+  }
+}
+
 export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator {
+  // Normalize the shortcut form `enum: MyEnum` into the long form
+  // `enum: { enum: MyEnum }` so the rest of the decorator can assume a uniform
+  // object shape. Single `isEnumOptionsObject` call, result reused for both variables.
+  const isLongForm = opts.enum ? isEnumOptionsObject(opts.enum) : false;
+  const normalizedEnum: NormalizedEnumOptions | undefined = opts.enum
+    ? isLongForm
+      ? (opts.enum as NormalizedEnumOptions)
+      : { enum: opts.enum as EnumAllowedTypes }
+    : undefined;
+
+  // The original long-form object (if provided) — needed to distinguish
+  // `enum: { enum: MyEnum, enumName: undefined }` (explicit disable) from
+  // `enum: MyEnum` (shortcut: auto-detect).
+  const originalEnumOpts = isLongForm ? (opts.enum as NormalizedEnumOptions) : undefined;
+
   return (target: any, propertyKey: string | symbol) => {
     const key = String(propertyKey);
 
+    // Warn if the enum option looks like a long-form object with a missing `enum` key
+    if (opts.enum && !originalEnumOpts) {
+      warnIfLikelyMisconfiguredEnumOptions(opts.enum, `${target.constructor?.name || '?'}.${key}`);
+    }
+
+    // Deprecation warning for long-form enum: { enum: MyEnum, ... }
+    if (originalEnumOpts) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[@UnifiedField] Deprecated long-form enum on "${target.constructor?.name || '?'}.${key}": ` +
+          `enum: { enum: ... } is deprecated. Use enum: MyEnum` +
+          (originalEnumOpts.enumName ? `, enumName: '${originalEnumOpts.enumName}'` : '') +
+          ` instead. The long-form will be removed in a future version.`,
+      );
+    }
+
     if (opts.exclude === true) {
       // ── EXPLICIT EXCLUSION ──
       const excludedKeys: string[] = Reflect.getOwnMetadata(EXCLUDED_FIELD_KEYS, target) || [];
@@ -282,7 +410,7 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
 
     // Set type for swagger
     if (baseType) {
-      if (opts.enum) {
+      if (normalizedEnum) {
         swaggerOpts.type = () => String;
       } else {
         swaggerOpts.type = baseType;
@@ -300,28 +428,34 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
     }
 
     // Set enum options
-    if (opts.enum && opts.enum.enum) {
-      swaggerOpts.enum = opts.enum.enum;
-
-      // Set enumName with auto-detection:
-      // - If enumName property doesn't exist at all, auto-detect the name
-      // - If enumName is explicitly set (even to null/undefined), use that value
-      // This allows explicit opts.enum.enumName = undefined to disable auto-detection
-      if (!('enumName' in opts.enum)) {
-        // Property doesn't exist, try auto-detection
-        const autoDetectedName = getEnumName(opts.enum.enum);
+    if (normalizedEnum && normalizedEnum.enum) {
+      swaggerOpts.enum = normalizedEnum.enum;
+
+      // Resolve enumName with priority chain:
+      // 1. Top-level opts.enumName (new recommended form) — highest priority
+      //    - string → use it
+      //    - null → explicitly disable auto-detection
+      //    - undefined → fall through to next level
+      // 2. Long-form originalEnumOpts.enumName (deprecated) — backwards compat
+      //    - present (even if undefined/null) → use it (preserves old semantics)
+      //    - absent → fall through
+      // 3. Auto-detection via registerEnum / GraphQL metadata / runtime name
+      if ('enumName' in opts && opts.enumName !== undefined) {
+        // Top-level enumName: string → use, null → disable auto-detection
+        swaggerOpts.enumName = opts.enumName ?? undefined;
+      } else if (originalEnumOpts && 'enumName' in originalEnumOpts) {
+        // Deprecated long-form enumName
+        swaggerOpts.enumName = originalEnumOpts.enumName;
+      } else {
+        // Auto-detection
+        const autoDetectedName = getEnumName(normalizedEnum.enum);
         if (autoDetectedName) {
           swaggerOpts.enumName = autoDetectedName;
         }
-      } else {
-        // Property exists (even if undefined/null), use its value
-        swaggerOpts.enumName = opts.enum.enumName;
       }
-
-      IsEnum(opts.enum.enum, opts.enum.options)(target, propertyKey);
     }
 
-    // Array handling
+    // Array handling — must run BEFORE IsEnum so `each` is resolved
     if (isArrayField) {
       swaggerOpts.isArray = true;
       IsArray(valOpts)(target, propertyKey);
@@ -331,16 +465,27 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
       valOpts.each = false;
     }
 
+    // Apply IsEnum after array handling so `each` from isArray is available.
+    // Merge isArray's `each` into the enum options automatically — the user
+    // no longer needs to pass `options: { each: true }` redundantly.
+    if (normalizedEnum && normalizedEnum.enum && !opts.isAny && !opts.validator) {
+      const enumValOpts: ValidationOptions = { ...normalizedEnum.options };
+      if (isArrayField && enumValOpts.each === undefined) {
+        enumValOpts.each = true;
+      }
+      IsEnum(normalizedEnum.enum, enumValOpts)(target, propertyKey);
+    }
+
     // Type function for gql
     // We need to keep the factory pattern (calling resolvedTypeFn inside the arrow function)
     // to support circular references. But we also need to extract array item types to avoid double-nesting.
     const gqlTypeFn = isArrayField
       ? () => {
-          const resolved = opts.enum?.enum || opts.gqlType || resolvedTypeFn();
+          const resolved = normalizedEnum?.enum || opts.gqlType || resolvedTypeFn();
           // Extract item type if user provided [ItemType] syntax to avoid [[ItemType]]
           return [Array.isArray(resolved) && resolved.length === 1 ? resolved[0] : resolved];
         }
-      : () => opts.enum?.enum || opts.gqlType || resolvedTypeFn();
+      : () => normalizedEnum?.enum || opts.gqlType || resolvedTypeFn();
 
     // Gql decorator
     Field(gqlTypeFn, gqlOpts)(target, propertyKey);
@@ -356,7 +501,12 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
     // Completely skip validation if its any
     if (opts.validator) {
       opts.validator(valOpts).forEach((d) => d(target, propertyKey));
-    } else if (!opts.isAny) {
+    } else if (!opts.isAny && !normalizedEnum) {
+      // Skip the built-in validator when an enum is set: IsEnum has already been
+      // applied above and is the authoritative validator for enum values. Without this
+      // guard, fields declared as `foo?: MyEnum` emit `design:type = Object` (because
+      // `MyEnum | undefined` is not primitive), which maps to IsObject() here and
+      // rejects perfectly valid enum string values with "foo must be an object".
       const validator = getBuiltInValidator(baseType, valOpts, isArrayField, target);
       if (validator) {
         validator(target, propertyKey);
@@ -370,7 +520,7 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
         Type(() => Date)(target, propertyKey);
       }
       // Check if it's a primitive, if not apply transform
-      else if (!isPrimitive(baseType) && !opts.enum && !isGraphQLScalar(baseType)) {
+      else if (!isPrimitive(baseType) && !normalizedEnum && !isGraphQLScalar(baseType)) {
         Type(() => baseType)(target, propertyKey);
         ValidateNested({ each: isArrayField })(target, propertyKey);
 

package/src/core/common/helpers/register-enum.helper.ts

@@ -2,6 +2,18 @@ import { registerEnumType } from '@nestjs/graphql';
 
 import { enumNameRegistry } from '../decorators/unified-field.decorator';
 
+/**
+ * Tracks which enum objects have been registered for GraphQL via registerEnum/registerEnums.
+ * Used to prevent duplicate registerEnumType() calls which cause schema build errors.
+ * Separate from enumNameRegistry (Swagger) because GraphQL registration is a distinct concern.
+ *
+ * @internal Consumers should use {@link enumNameRegistry} (from unified-field.decorator) to
+ * verify Swagger/name registration. This registry is exported for advanced use cases
+ * (e.g. checking if an enum is already registered for GraphQL before calling registerEnumType
+ * directly), but most projects should not need to interact with it.
+ */
+export const graphqlEnumRegistry = new WeakSet<object>();
+
 /**
  * Interface defining options for the registerEnum helper
  */
@@ -83,11 +95,87 @@ export function registerEnum<T extends object = any>(enumRef: T, options: Regist
   }
 
   // Register for GraphQL if enabled
-  if (graphql) {
+  if (graphql && !graphqlEnumRegistry.has(enumRef)) {
     registerEnumType(enumRef, {
       description,
       name,
       valuesMap,
     });
+    graphqlEnumRegistry.add(enumRef);
+  }
+}
+
+/**
+ * Options for {@link registerEnums} bulk registration.
+ *
+ * Controls which API layers the enums are registered for (GraphQL and/or Swagger/REST).
+ * When omitted, enums are registered for both layers.
+ */
+export interface RegisterEnumsOptions {
+  /**
+   * Whether to register enums for GraphQL using registerEnumType.
+   * @default true
+   */
+  graphql?: boolean;
+
+  /**
+   * Whether to register enums in the enumNameRegistry for Swagger/REST.
+   * When enabled, enum names are auto-detected by {@link UnifiedField} decorators
+   * for the `enumName` property in Swagger/OpenAPI schemas.
+   * @default true
+   */
+  swagger?: boolean;
+}
+
+/**
+ * Bulk-register all enums from a barrel-export namespace object.
+ *
+ * Uses the **export key names** as enum names — no manual name repetition
+ * needed. Call this once per project, typically in your module setup.
+ *
+ * @example
+ * ```typescript
+ * // src/server/common/enums/index.ts (barrel file)
+ * export { ContactStatusEnum } from './contact-status.enum';
+ * export { IndustryEnum } from './industry.enum';
+ * export { NotifyViaEnum } from './notify-via.enum';
+ *
+ * // src/server/server.module.ts (one line)
+ * import * as Enums from './common/enums';
+ * registerEnums(Enums);
+ *
+ * // Result: ContactStatusEnum, IndustryEnum, NotifyViaEnum are all
+ * // registered for both GraphQL and Swagger auto-detection.
+ * ```
+ *
+ * Only plain objects with string/number values (enum-like objects) are
+ * registered. Non-enum exports (functions, classes, strings) are skipped.
+ *
+ * @param namespace - The barrel-export namespace object (`import * as X from '...'`)
+ * @param options - Optional: control GraphQL/Swagger registration
+ */
+export function registerEnums(namespace: Record<string, any>, options?: RegisterEnumsOptions): void {
+  const { graphql = true, swagger = true } = options ?? {};
+
+  for (const [name, value] of Object.entries(namespace)) {
+    // Skip non-objects (functions, strings, numbers, etc.)
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      continue;
+    }
+
+    // Skip if already registered for all requested targets
+    const alreadySwagger = !swagger || enumNameRegistry.has(value);
+    const alreadyGraphql = !graphql || graphqlEnumRegistry.has(value);
+    if (alreadySwagger && alreadyGraphql) {
+      continue;
+    }
+
+    // Verify it looks like an enum: all own values are strings or numbers
+    const vals = Object.values(value);
+    if (vals.length === 0 || !vals.every((v) => typeof v === 'string' || typeof v === 'number')) {
+      continue;
+    }
+
+    registerEnum(value, { graphql, name, swagger });
   }
 }

package/src/core/common/inputs/combined-filter.input.ts

@@ -18,7 +18,7 @@ export class CombinedFilterInput extends CoreInput {
    */
   @UnifiedField({
     description: 'Logical Operator to combine filters',
-    enum: { enum: LogicalOperatorEnum },
+    enum: LogicalOperatorEnum,
     roles: RoleEnum.S_EVERYONE,
   })
   logicalOperator: LogicalOperatorEnum = undefined;

package/src/core/common/inputs/single-filter.input.ts

@@ -58,7 +58,7 @@ export class SingleFilterInput extends CoreInput {
    */
   @UnifiedField({
     description: '[Comparison operator](https://docs.mongodb.com/manual/reference/operator/query-comparison/)',
-    enum: { enum: ComparisonOperatorEnum },
+    enum: ComparisonOperatorEnum,
     roles: RoleEnum.S_EVERYONE,
   })
   operator: ComparisonOperatorEnum = undefined;

package/src/core/common/inputs/sort.input.ts

@@ -26,7 +26,7 @@ export class SortInput extends CoreInput {
    */
   @UnifiedField({
     description: 'SortInput order of the field',
-    enum: { enum: SortOrderEnum },
+    enum: SortOrderEnum,
     roles: RoleEnum.S_EVERYONE,
   })
   order: SortOrderEnum = undefined;