@lenne.tech/nest-server 11.24.1 → 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.1",
+  "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",
@@ -78,16 +78,16 @@
     "@as-integrations/express5": "1.1.2",
     "@better-auth/passkey": "1.5.5",
     "@getbrevo/brevo": "3.0.1",
-    "@nestjs/apollo": "13.2.4",
+    "@nestjs/apollo": "13.2.5",
     "@nestjs/common": "11.1.18",
     "@nestjs/core": "11.1.18",
-    "@nestjs/graphql": "13.2.4",
+    "@nestjs/graphql": "13.2.5",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
     "@nestjs/platform-express": "11.1.18",
     "@nestjs/schedule": "6.1.1",
-    "@nestjs/swagger": "11.2.6",
+    "@nestjs/swagger": "11.2.7",
     "@nestjs/terminus": "11.1.1",
     "@nestjs/websockets": "11.1.18",
     "@tus/file-store": "2.0.0",
@@ -125,7 +125,7 @@
   },
   "devDependencies": {
     "@compodoc/compodoc": "1.2.1",
-    "@nestjs/cli": "11.0.18",
+    "@nestjs/cli": "11.0.19",
     "@nestjs/schematics": "11.0.10",
     "@nestjs/testing": "11.1.18",
     "@swc/cli": "0.8.1",
@@ -136,11 +136,11 @@
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.24",
     "@types/multer": "2.1.0",
-    "@types/node": "25.5.2",
+    "@types/node": "25.6.0",
     "@types/nodemailer": "8.0.0",
     "@types/passport": "1.0.17",
-    "@vitest/coverage-v8": "4.1.3",
-    "@vitest/ui": "4.1.3",
+    "@vitest/coverage-v8": "4.1.4",
+    "@vitest/ui": "4.1.4",
     "ansi-colors": "4.1.3",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
@@ -152,13 +152,13 @@
     "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",
     "vite": "7.3.2",
     "vite-plugin-node": "7.0.0",
-    "vite-tsconfig-paths": "6.1.1",
-    "vitest": "4.1.3"
+    "vitest": "4.1.4"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -181,7 +181,27 @@
   },
   "packageManager": "pnpm@10.33.0",
   "pnpm": {
+    "//overrides": {
+      "axios@<1.15.0": "Security: SSRF via NO_PROXY bypass (GHSA-3p68-rc4w-qgx5) and unrestricted cloud metadata exfiltration (GHSA-fvcv-3m26-pcqx) - transitive via @getbrevo/brevo and node-mailjet. Remove when @getbrevo/brevo ships axios>=1.15.0",
+      "minimatch@<3.1.5": "Security: RegExp DoS (GHSA-p8p7-x288-28g6) - transitive via @getbrevo/brevo>rewire>eslint",
+      "minimatch@>=9.0.0 <9.0.9": "Security: RegExp DoS - transitive via @nestjs/cli>@swc/cli",
+      "minimatch@>=10.0.0 <10.2.5": "Security: RegExp DoS - transitive via @nestjs/apollo>ts-morph>@ts-morph/common and nodemon",
+      "ajv@<6.14.0": "Security: prototype pollution - transitive via @getbrevo/brevo>rewire>eslint",
+      "ajv@>=7.0.0-alpha.0 <8.18.0": "Security: prototype pollution - transitive via @nestjs/cli>@angular-devkit",
+      "undici@>=7.0.0 <7.24.7": "Security: various CVEs - transitive via @compodoc/compodoc>cheerio",
+      "srvx@<0.11.15": "Compatibility: @tus/server@2.3.0 requires ~0.8.2 but 0.11.15 needed for security - remove when @tus/server ships with >=0.11.15",
+      "handlebars@>=4.0.0 <4.7.9": "Security: prototype pollution (GHSA-q42p-pg8m-cqh6) - transitive via @compodoc/compodoc",
+      "brace-expansion@<1.1.13": "Security: RegExp DoS - transitive via eslint>minimatch",
+      "brace-expansion@>=4.0.0 <5.0.5": "Security: RegExp DoS - transitive via nodemon>minimatch and @ts-morph/common>minimatch",
+      "picomatch@<2.3.2": "Security: ReDoS - transitive via @nestjs/graphql>fast-glob>micromatch and @compodoc/compodoc>chokidar",
+      "picomatch@>=4.0.0 <4.0.4": "Security: ReDoS - transitive via vitest and vite",
+      "path-to-regexp@>=8.0.0 <8.4.2": "Security: ReDoS (GHSA-rhx6-c78j-4q9w) - transitive via express>router",
+      "kysely@>=0.26.0 <0.28.15": "Security: SQL injection - transitive via better-auth",
+      "lodash@>=4.0.0 <4.18.0": "Security: CVE in lodash@4.17.x - transitive via @nestjs/graphql. 4.18.1 is the latest patched version",
+      "defu@<=6.1.6": "Security: prototype pollution via __proto__ key - transitive via better-auth"
+    },
     "overrides": {
+      "axios@<1.15.0": "1.15.0",
       "minimatch@<3.1.5": "3.1.5",
       "minimatch@>=9.0.0 <9.0.9": "9.0.9",
       "minimatch@>=10.0.0 <10.2.5": "10.2.5",
@@ -197,8 +217,7 @@
       "path-to-regexp@>=8.0.0 <8.4.2": "8.4.2",
       "kysely@>=0.26.0 <0.28.15": "0.28.15",
       "lodash@>=4.0.0 <4.18.0": "4.18.1",
-      "defu@<=6.1.6": "6.1.7",
-      "vite@>=7.0.0 <7.3.2": "7.3.2"
+      "defu@<=6.1.6": "6.1.7"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

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);