nesties 1.1.20 → 1.1.22

package/README.md

@@ -492,7 +492,7 @@ By composing multiple middlewares (dictionaries, database lookups, remote APIs),
 
 ### 8. ParamResolver
 
-`ParamResolver` and `CombinedParamResolver` provide a small, composable abstraction over headers and query parameters. They are used internally by `TokenGuard`, the i18n utilities, and can also be used directly in controllers, pipes, and guards.
+`ParamResolver` provide a small, composable abstraction over headers and query parameters. They are used internally by `TokenGuard`, the i18n utilities, and can also be used directly in controllers, pipes, and guards.
 
 #### Static header / query resolvers
 
@@ -635,6 +635,119 @@ When used as a decorator, the combined resolver:
 - Returns a typed object where each key corresponds to the original resolver
 - Emits merged Swagger metadata for all headers / queries involved
 
+#### Transforming resolved values with `TransformParamResolver`
+
+Sometimes reading a header or query parameter is only the first step. You often want to **normalize**, **validate**, or **enrich** that value before it reaches your handler—especially when the transformation needs access to request-scoped dependencies via `ModuleRef`.
+
+`TransformParamResolver` is a thin wrapper around any `ParamResolverBase<T>` that applies a function `T -> U`:
+
+- It **reuses** the base resolver’s extraction logic (header/query/dynamic).
+- It runs a **transform function** that can be sync or async.
+- It receives `(value, moduleRef, req)` so you can:
+  - normalize formats (`'zh-hant' -> 'zh-Hant'`)
+  - parse primitives (`string -> number/boolean/date`)
+  - validate and throw `HttpException` / `BlankReturnMessageDto`
+  - hydrate values (e.g., `token -> user`) by resolving services from DI
+- Swagger metadata is **inherited** from the base resolver, so the API contract stays accurate and not duplicated.
+
+##### Basic example: normalize a header value
+
+```ts
+import { Controller, Get } from '@nestjs/common';
+import { ParamResolver, TransformParamResolver } from 'nesties';
+
+const rawLang = new ParamResolver({
+  paramType: 'header',
+  paramName: 'accept-language',
+});
+
+const normalizedLang = new TransformParamResolver(
+  rawLang,
+  (value) => {
+    if (!value) return undefined;
+    const v = value.split(',')[0]?.trim() ?? value;
+    const lower = v.toLowerCase();
+    if (lower === 'zh-hant' || lower === 'zh-tw') return 'zh-Hant';
+    if (lower === 'en-us') return 'en-US';
+    return v;
+  },
+);
+
+const Lang = normalizedLang.toParamDecorator();
+
+@Controller()
+export class LocaleController {
+  @Get('lang')
+  getLang(@Lang() lang: string | undefined) {
+    return { lang };
+  }
+}
+```
+
+##### Advanced example: resolve a request-scoped service inside the transform
+
+Because `TransformParamResolver` receives `ModuleRef` and `req`, you can resolve request-scoped providers using `ContextIdFactory.getByRequest(req)`.
+
+```ts
+import { Injectable, Scope } from '@nestjs/common';
+import { ContextIdFactory, ModuleRef } from '@nestjs/core';
+import { ParamResolver, TransformParamResolver } from 'nesties';
+
+@Injectable({ scope: Scope.REQUEST })
+class LocaleService {
+  normalize(input?: string) {
+    if (!input) return undefined;
+    const lower = input.toLowerCase();
+    if (lower === 'zh-hant') return 'zh-Hant';
+    return input;
+  }
+}
+
+const rawLocale = new ParamResolver({
+  paramType: 'query',
+  paramName: 'locale',
+});
+
+const localeWithService = new TransformParamResolver(
+  rawLocale,
+  async (value, ref: ModuleRef, req) => {
+    const ctxId = ContextIdFactory.getByRequest(req);
+    const svc = await ref.resolve(LocaleService, ctxId, { strict: false });
+    return svc.normalize(value);
+  },
+);
+```
+
+##### Composing multiple transforms (nesting)
+
+`TransformParamResolver` can be used as the base resolver of another `TransformParamResolver`, forming a pipeline of transformations.
+
+```ts
+import { TransformParamResolver } from 'nesties';
+
+// rawLocale: ParamResolverBase<string | undefined>
+
+// Step 1: normalize
+const normalized = new TransformParamResolver(rawLocale, (v) =>
+  v ? v.trim() : undefined,
+);
+
+// Step 2: validate / coerce
+const validated = new TransformParamResolver(normalized, (v) => {
+  if (!v) return 'en-US';
+  return v;
+});
+
+// validated resolves to string
+const Locale = validated.toParamDecorator();
+```
+
+##### Notes
+
+- `TransformParamResolver` does **not** change where the parameter comes from—only how the resolved value is shaped.
+- Swagger decorators are inherited from the base resolver, so documentation remains consistent even when you compose multiple transforms.
+- For multi-field inputs, you can first use `CombinedParamResolver`, then transform the combined object into a richer type (e.g., `{ lang, token } -> { locale, user }`).
+
 #### Request-scoped providers from resolvers
 
 Sometimes you want to treat the resolved value itself as an injectable request-scoped provider. You can derive such a provider from any `ParamResolver` or `CombinedParamResolver` using `toRequestScopedProvider()`:

package/dist/index.cjs

@@ -1166,6 +1166,7 @@ __export(index_exports, {
   ReturnMessageDto: () => ReturnMessageDto,
   StringReturnMessageDto: () => StringReturnMessageDto,
   TokenGuard: () => TokenGuard,
+  TransformParamResolver: () => TransformParamResolver,
   abortableToken: () => abortableToken,
   createAbortableProvider: () => createAbortableProvider,
   createI18n: () => createI18n,
@@ -1445,6 +1446,20 @@ var createProvider = (options, factory) => {
 // src/utility/resolver-swagger-map.ts
 var ResolverSwaggerMap = /* @__PURE__ */ new Map();
 
+// src/utility/uniq-by.ts
+var uniqBy = (arr, fn) => {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of arr) {
+    const key = fn(item);
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(item);
+    }
+  }
+  return result;
+};
+
 // src/resolver.ts
 var ParamResolverCopiedFieldsFromSwagger = [
   "required",
@@ -1510,8 +1525,22 @@ ParamResolverPipe = __decorateClass([
 ], ParamResolverPipe);
 var usedParamResolverTokens = /* @__PURE__ */ new Set();
 var ParamResolverBase = class {
+  constructor() {
+    this.extraSwagger = [];
+  }
+  addExtraDecorator(dec, token = Math.random().toString(36)) {
+    this.extraSwagger.push({
+      token,
+      swagger: dec
+    });
+    return this;
+  }
+  // for override
+  toSwaggerInfo(extras = []) {
+    return uniqBy([...this.extraSwagger, ...extras], (info) => info.token);
+  }
   toApiPropertyDecorator(extras = {}) {
-    const swaggerInfo = this.toSwaggerInfo();
+    const swaggerInfo = uniqBy(this.toSwaggerInfo(), (info) => info.token);
     return (extras2 = {}) => MergeClassOrMethodDecorators(
       swaggerInfo.map((info) => info.swagger({ ...extras, ...extras2 }))
     );
@@ -1570,6 +1599,15 @@ var ParamResolver = class extends ParamResolverBase {
       }
     }
   }
+  handleResolveValue(v) {
+    if (this.info?.required && v == null) {
+      throw new BlankReturnMessageDto(
+        400,
+        `Required parameter '${this.info.paramName}' in ${this.info.paramType} is missing`
+      ).toException();
+    }
+    return v;
+  }
   resolve(req, ref) {
     if (this.info) {
       if (this.info.paramType === "header") {
@@ -1577,10 +1615,10 @@ var ParamResolver = class extends ParamResolverBase {
         let raw = getHeader(req, name);
         if (name === "accept-language")
           raw = pickPrimaryFromAcceptLanguage(raw);
-        return raw;
+        return this.handleResolveValue(raw);
       }
       if (this.info.paramType === "query") {
-        return getQueryValue(req, this.info.paramName);
+        return this.handleResolveValue(getQueryValue(req, this.info.paramName));
       }
       throw new Error(`Unsupported paramType: ${this.info.paramType}`);
     } else if (this.dynamic) {
@@ -1591,7 +1629,7 @@ var ParamResolver = class extends ParamResolverBase {
     const suffix = this.info ? `${this.info.paramType.toUpperCase()}_${this.info.paramName}` : `DYNAMIC`;
     return `ParamResolver_${suffix}`;
   }
-  toSwaggerInfo() {
+  toSwaggerInfo(extras = []) {
     const swagger = (extras2 = {}) => {
       if (this.info) {
         const paramType = this.info.paramType;
@@ -1612,12 +1650,19 @@ var ParamResolver = class extends ParamResolverBase {
       return () => {
       };
     };
-    return [
+    return super.toSwaggerInfo([
       {
         swagger,
         token: this.toString()
-      }
-    ];
+      },
+      ...this.info?.required ? [
+        {
+          swagger: () => ApiError(400, "Invalid request parameters"),
+          token: `__missing_required_400__`
+        }
+      ] : [],
+      ...extras
+    ]);
   }
 };
 var CombinedParamResolver = class extends ParamResolverBase {
@@ -1641,10 +1686,28 @@ var CombinedParamResolver = class extends ParamResolverBase {
     const suffix = Object.entries(this.resolvers).map(([key, resolver]) => `${key.toString()}_${resolver.toString()}`).join("__");
     return `CombinedParamResolver_${suffix}`;
   }
-  toSwaggerInfo() {
-    return Object.values(this.resolvers).flatMap(
+  toSwaggerInfo(extras = []) {
+    const combined = Object.values(this.resolvers).flatMap(
       (resolver) => resolver.toSwaggerInfo()
     );
+    return super.toSwaggerInfo([...combined, ...extras]);
+  }
+};
+var TransformParamResolver = class extends ParamResolverBase {
+  constructor(baseResolver, transformFn) {
+    super();
+    this.baseResolver = baseResolver;
+    this.transformFn = transformFn;
+  }
+  async resolve(req, ref) {
+    const baseValue = await this.baseResolver.resolve(req, ref);
+    return this.transformFn(baseValue, ref, req);
+  }
+  toString() {
+    return `Transform_${this.baseResolver.toString()}`;
+  }
+  toSwaggerInfo(extras = []) {
+    return this.baseResolver.toSwaggerInfo(extras);
   }
 };
 var getParamResolver = (input) => {
@@ -2098,6 +2161,7 @@ var I18nLookupMiddleware = (0, import_nfkit3.createI18nLookupMiddleware)();
   ReturnMessageDto,
   StringReturnMessageDto,
   TokenGuard,
+  TransformParamResolver,
   abortableToken,
   createAbortableProvider,
   createI18n,