@buildvision/nest-sdk-generator 1.2.2 → 2.1.0

package/src/analyzer/methods.ts

@@ -4,8 +4,10 @@
 
 import { blue } from 'chalk'
 import { ClassDeclaration, MethodDeclaration, Node } from 'ts-morph'
+
 import { debug, format } from '../logging'
-import { analyzeParams, SdkMethodParams } from './params'
+
+import { extractParams, SdkMethodParams } from './params'
 import { analyzeUri, debugUri, Route } from './route'
 import { ResolvedTypeDeps, resolveTypeDependencies } from './typedeps'
 
@@ -13,11 +15,14 @@ import { ResolvedTypeDeps, resolveTypeDependencies } from './typedeps'
  * SDK interface for a single controller's method
  */
 export interface SdkMethod {
+  /** Method's HTTP method (e.g. GET / POST) */
+  readonly httpMethod: SdkHttpMethod
+
   /** Method's name */
   readonly name: string
 
-  /** Method's HTTP method (e.g. GET / POST) */
-  readonly httpMethod: SdkHttpMethod
+  /** Method's parameters */
+  readonly params: SdkMethodParams
 
   /** Method's return type with resolved dependencies */
   readonly returnType: ResolvedTypeDeps
@@ -27,20 +32,17 @@ export interface SdkMethod {
 
   /** Method's URI path */
   readonly uriPath: string
-
-  /** Method's parameters */
-  readonly params: SdkMethodParams
 }
 
 /**
  * HTTP method of a controller's method
  */
 export enum SdkHttpMethod {
+  Delete = 'DELETE',
   Get = 'GET',
+  Patch = 'PATCH',
   Post = 'POST',
   Put = 'PUT',
-  Patch = 'PATCH',
-  Delete = 'DELETE',
 }
 
 /**
@@ -85,8 +87,7 @@ export function analyzeMethods(
     // Get the HTTP decorator
     const dec = decorators[0]
 
-    // We need to put a '@ts-ignore' here because TypeScript doesn't like indexing an enumeration with a string key, although this works fine
-    // @ts-ignore
+    // @ts-expect-error TypeScript doesn't like indexing an enumeration with a string key, although this works fine
     const httpMethod = SdkHttpMethod[dec.getName()]
 
     debug('├─── Detected HTTP method: {magentaBright}', httpMethod.toLocaleUpperCase())
@@ -141,9 +142,7 @@ export function analyzeMethods(
 
     // Analyze the method's arguments
     debug('├─── Analyzing arguments...')
-    const params = analyzeParams(httpMethod, route, method.getParameters(), filePath, absoluteSrcPath)
-
-    if (params instanceof Error) return params
+    const params = extractParams({ controllerClass, httpMethod, route, method, filePath, absoluteSrcPath })
 
     // Get the method's return type
     debug('├─── Resolving return type...')

package/src/analyzer/module.ts

@@ -3,7 +3,9 @@
  */
 
 import * as path from 'path'
+
 import { Node, Project } from 'ts-morph'
+
 import { format, panic } from '../logging'
 
 /**
@@ -36,16 +38,8 @@ export function getModuleName(project: Project, modulePath: string, sourcePath:
   const moduleDecorator = decorators.find((dec) => dec.getName() === 'Module')
 
   if (!moduleDecorator) {
-    panic(
-      format(
-        `Module class {yellow} is missing {yellow} decorator\nModule path is: {yellow}`,
-        moduleName,
-        '@Module',
-        modulePath
-      )
-    )
+    panic(format(`Module class {yellow} is missing {yellow} decorator\nModule path is: {yellow}`, moduleName, '@Module', modulePath))
   }
 
-
-  return moduleName.substr(0, 1).toLocaleLowerCase() + moduleName.substr(1)
+  return moduleName
 }

package/src/analyzer/params.ts

@@ -2,31 +2,89 @@
  * @file Analyzer for the source API's controllers' methods' parameters
  */
 
-import { ParameterDeclaration } from 'ts-morph'
-import { debug, format, warn } from '../logging'
-import { expectSingleStrLitDecorator } from './decorator'
+import { ClassDeclaration, Decorator, MethodDeclaration, Node, ParameterDeclaration, Type } from 'ts-morph'
+
+import { debug, panic } from '../logging'
+
 import { SdkHttpMethod } from './methods'
-import { paramsOfRoute, Route } from './route'
+import { paramsFromRoute, Route } from './route'
 import { ResolvedTypeDeps, resolveTypeDependencies } from './typedeps'
 
 /**
- * SDK interface for a controller's method's parameters
+ * Type of a parameter that must be passed to an SDK method: Body, Query or Route Param
+ * Supports accessing parameters individually by key or as a whole object
+ *
+ * EXAMPLE
+ *
+ * Controller Method:
+ *
+ * getStuff(@Query('email') email: string, @Query('companyId'): CompanyId)
+ *
+ * SDK Method Param:
+ * { email: string, companyId: CompanyId }
+ *
+ * OR
+ *
+ * Controller Method:
+ * type EmailAndCompanyId = { email: string, companyId: CompanyId }
+ * getStuff(@Query(): EmailAndCompanyId)
+ *
+ * SDK Method Param:
+ * EmailAndCompanyId
  */
-export interface SdkMethodParams {
-  /** Route parameters */
-  parameters: Map<string, ResolvedTypeDeps> | null
 
-  /** Query parameters */
-  query: Map<string, ResolvedTypeDeps> | null
+export type SdkMethodParam = SdkMethodParamMap | ResolvedTypeDeps | null
+export type SdkMethodParamMap = { [key: string]: ResolvedTypeDeps }
 
-  /** Body parameters */
-  body: SdkMethodBodyParam | null
+export const isParamResolvedType = (param: SdkMethodParam): param is ResolvedTypeDeps => {
+  if (param === null) {
+    return false
+  }
+  return 'rawType' in param && 'resolvedType' in param && 'relativeFilePath' in param && 'dependencies' in param && 'localTypes' in param
+}
+
+export const getParamResolvedTypes = (param: SdkMethodParam): ResolvedTypeDeps[] => {
+  if (param === null) {
+    return []
+  }
+  if (isParamResolvedType(param)) {
+    return [param]
+  }
+  return Object.values(param)
 }
 
 /**
- * Single body parameter in a SDK's method
+ * SDK interface for a controller's method's parameters
  */
-export type SdkMethodBodyParam = { full: true; type: ResolvedTypeDeps } | { full: false; fields: Map<string, ResolvedTypeDeps> }
+export interface SdkMethodParams {
+  bodyParams: SdkMethodParam
+  context: MethodContext
+  queryParams: SdkMethodParam
+  routeParams: SdkMethodParam
+}
+
+export type MethodContext = {
+  absoluteSrcPath: string
+  controllerClass: ClassDeclaration
+  filePath: string
+  httpMethod: SdkHttpMethod
+  method: MethodDeclaration
+  route: Route
+}
+
+export enum ArgDecorator {
+  Body = 'Body',
+  Param = 'Param',
+  Query = 'Query',
+}
+
+export type DecoratedArg = {
+  arg: ParameterDeclaration
+  argParamKey: string | null
+  context: MethodContext
+  decorator: Decorator
+  decoratorType: ArgDecorator
+}
 
 /**
  * Generate a SDK interface for a controller's method's parameters
@@ -37,205 +95,177 @@ export type SdkMethodBodyParam = { full: true; type: ResolvedTypeDeps } | { full
  * @param absoluteSrcPath Absolute path to the source directory
  * @returns A SDK interface for the method's parameters
  */
-export function analyzeParams(
-  httpMethod: SdkHttpMethod,
-  route: Route,
-  args: ParameterDeclaration[],
-  filePath: string,
-  absoluteSrcPath: string
-): SdkMethodParams | Error {
-  // The collected informations we will return
-  const collected: SdkMethodParams = {
-    parameters: null,
-    query: null,
-    body: null,
+export function extractParams(context: MethodContext): SdkMethodParams {
+  const { httpMethod, route } = context
+  const { Body, Param, Query } = extractDecoratedArgs(context)
+  const resolvedParams: SdkMethodParams = {
+    routeParams: mergeDecoratedArgs(Param),
+    queryParams: mergeDecoratedArgs(Query),
+    bodyParams: mergeDecoratedArgs(Body),
+    context,
   }
 
-  // Get the named parameters of the route
-  const routeParams = paramsOfRoute(route)
+  /**
+   * Validate Body Params are not used in GET requests
+   */
+  if (httpMethod === SdkHttpMethod.Get && resolvedParams.bodyParams) {
+    panicWithContext(`${httpMethod} request should not have @Body params, use @Query params instead`, context)
+  }
+
+  /**
+   * Validate Query Params are not used in non-GET requests
+   */
+  if (httpMethod !== SdkHttpMethod.Get && resolvedParams.queryParams) {
+    panicWithContext(`${httpMethod} request should not have @Query params, use @Body params instead`, context)
+  }
+
+  /**
+   * Validate Route Params exist in route URL
+   */
+  const { routeParams } = resolvedParams
+  if (routeParams) {
+    const allowedRouteParams = new Set(paramsFromRoute(route))
+    const usedRouteParams =
+      routeParams instanceof Type
+        ? // If routeParams was resolved to a single type, assume there's only one decorated argument
+          Param[0].arg
+            .getType()
+            .getProperties()
+            .map((prop) => prop.getName())
+        : // If routeParams was resolved to a map, assume the keys are the route params
+          Object.keys(routeParams)
+
+    for (const usedParam of usedRouteParams) {
+      if (!allowedRouteParams.has(usedParam)) {
+        panicWithContext(`Route param ${usedParam} does not appear in route URL`, context)
+      }
+    }
+  }
+
+  return resolvedParams
+}
+
+export function extractDecoratedArgs(context: MethodContext): Record<ArgDecorator, DecoratedArg[]> {
+  const decoratedArgs = {
+    [ArgDecorator.Param]: [] as DecoratedArg[],
+    [ArgDecorator.Query]: [] as DecoratedArg[],
+    [ArgDecorator.Body]: [] as DecoratedArg[],
+  }
+
+  const { controllerClass, method } = context
+  const args = method.getParameters()
 
-  // Treat all arguments (to not confuse with the route's parameters)
   for (const arg of args) {
-    const name = arg.getName()
+    const argName = arg.getName()
 
-    debug('├───── Detected argument: {yellow}', name)
+    debug('├───── Detected argument: {yellow}', argName)
 
     // Arguments are collected as soon as they have a decorator like @Query() or @Body()
-    const decs = arg.getDecorators()
+    const argDecorators = arg.getDecorators().filter((dec) => (Object.values(ArgDecorator) as string[]).includes(dec.getName()))
 
-    if (decs.length === 0) {
+    if (argDecorators.length === 0) {
       // If we have no argument, this is not an argument we are interested in, so we just skip it
       debug('├───── Skipping this argument as it does not have a decorator')
       continue
-    } else if (decs.length > 1) {
-      // If we have more than one decorator, this could mean we have for instance an @NotEmpty() @Query() or something like this,
-      //  which is currently not supported.
-      return new Error('Skipping this argument as it has multiple decorators, which is currently not supported')
+    } else if (argDecorators.length > 1) {
+      panic(
+        `${controllerClass.getName()} ${method.getName()} has multiple decorators on argument ${argName} ${argDecorators.map((dec) => dec.getName()).join(', ')}`
+      )
     }
-
     // Get the only decrator
-    const dec = decs[0]
-    const decName = dec.getName()
+    const decorator = argDecorators[0]
+    const decoratorType = decorator.getName() as ArgDecorator
+    const argParamKey = extractArgParamKey({ ...context, arg, decorator })
+    const argType = arg.getType()
+
+    if (!argParamKey && !argType.isObject()) {
+      panic(
+        `${controllerClass.getName()} ${method.getName()} generic controller argument ${decoratorType}() ${argName} must be an object type`
+      )
+    }
 
-    // Treat the @Param() decorator
-    if (decName === 'Param') {
-      debug('├───── Detected decorator {blue}', '@Param')
+    decoratedArgs[decoratorType].push({
+      arg,
+      argParamKey,
+      decorator,
+      decoratorType,
+      context,
+    })
+  }
 
-      // We expect a single string argument for this decorator,
-      // which is the route parameter's name
-      const paramName = expectSingleStrLitDecorator(dec)
+  return decoratedArgs
+}
 
-      if (paramName instanceof Error) return paramName
+export function extractArgParamKey(
+  context: MethodContext & {
+    arg: ParameterDeclaration
+    decorator: Decorator
+  }
+): string | null {
+  const { arg, controllerClass, decorator, method } = context
+  const decoratorArgs = decorator.getArguments()
+
+  if (decoratorArgs.length > 1) {
+    panic(
+      `${controllerClass.getName()} ${method.getName()} ${decorator.getName()}() ${arg.getName()} argument decorator has multiple parameters`
+    )
+  } else if (decoratorArgs.length === 0) {
+    return null
+  }
 
-      // If there is no argument, this argument is a global receiver which maps the full set of parameters
-      // We theorically *could* extract the type informations from this object type, but this would be insanely complex
-      // So, we just skip it as it's a lot more simple, and is not commonly used anyway as it has a set of downsides
-      if (paramName === null) {
-        warn('├───── Skipping this argument as it is a generic parameters receiver, which is currently not supported')
-        continue
-      }
+  const decoratorArg = decoratorArgs[0]
 
-      // Ensure the specified parameter appears in the method's route
-      if (!routeParams.includes(paramName)) return new Error(format('├───── Cannot map unknown parameter {yellow}', paramName))
+  if (!Node.isStringLiteral(decoratorArg)) {
+    panic('The argument provided to the decorator is not a string literal:\n>>> {cyan}', arg.getText())
+  }
 
-      debug('├───── Mapping argument to parameter: {yellow}', paramName)
+  const paramKey = decoratorArg.getLiteralText()
+  if (paramKey in {}) {
+    panicWithContext(`${decorator.getName()}('${paramKey}') param name collides with JavaScript native object property`, context)
+  }
 
-      // Get the route parameter's type
-      const typ = resolveTypeDependencies(arg.getType(), filePath, absoluteSrcPath)
+  return paramKey
+}
 
-      debug('├───── Detected parameter type: {yellow} ({magentaBright} dependencies)', typ.resolvedType, typ.dependencies.size)
+export function mergeDecoratedArgs(decoratedArgs: DecoratedArg[]): SdkMethodParam {
+  let genericParam: SdkMethodParam | null = null
+  const paramMap: SdkMethodParamMap = {}
 
-      // Update the method's route parameters
+  for (const decoratedArg of decoratedArgs) {
+    const { arg, argParamKey, context, decoratorType } = decoratedArg
+    const resolvedType = resolveTypeDependencies(arg.getType(), context.filePath, context.absoluteSrcPath)
 
-      if (paramName in {}) {
-        return new Error(
-          format(`Detected @Param() field whose name {yellow} collides with a JavaScript's native object property`, paramName)
-        )
+    if (argParamKey) {
+      if (paramMap[argParamKey]) {
+        panicWithContext(`${decoratorType}('${argParamKey}') used twice in controller method`, decoratedArg.context)
       }
 
-      collected.parameters ??= new Map()
-      collected.parameters.set(paramName, typ)
-    }
-
-    // Treat the @Query() decorator
-    else if (decName === 'Query') {
-      debug('├───── Detected decorator {blue}', '@Query')
-
-      // We expect a single string argument for this decorator,
-      // which is the query parameter's name
-      const queryName = expectSingleStrLitDecorator(dec)
-
-      if (queryName instanceof Error) return queryName
-
-      // If there is no argument, this argument is a global receiver which maps the full set of parameters
-      // We theorically *could* extract the type informations from this object type, but this would be insanely complex
-      // So, we just skip it as it's a lot more simple, and is not commonly used anyway as it has a set of downsides
-      if (queryName === null) {
-        warn('├───── Skipping this argument as it is a generic query receiver')
-        continue
+      paramMap[argParamKey] = resolvedType
+    } else {
+      if (genericParam) {
+        panicWithContext(`${decoratorType}() used twice in controller method`, decoratedArg.context)
       }
 
-      debug('├───── Mapping argument to query: {yellow}', queryName)
-
-      // Get the parameter's type
-      const typ = resolveTypeDependencies(arg.getType(), filePath, absoluteSrcPath)
-
-      debug(`├───── Detected query type: {yellow} ({magentaBright} dependencies)`, typ.resolvedType, typ.dependencies.size)
-
-      // Update the method's query parameter
-
-      if (queryName in {}) {
-        return new Error(
-          format(`Detected @Query() field whose name {yellow} collides with a JavaScript's native object property`, queryName)
-        )
-      }
-
-      collected.query ??= new Map()
-      collected.query.set(queryName, typ)
+      genericParam = resolvedType
     }
+  }
 
-    // Treat the @Body() decorator
-    else if (decName === 'Body') {
-      debug('├───── Detected decorator {blue}', '@Body')
-
-      // GET requests cannot have a BODY
-      if (httpMethod === SdkHttpMethod.Get) {
-        return new Error('GET requests cannot have a BODY!')
-      }
-
-      // We expect a single string argument for this decorator,
-      // which is the body field's name
-      const fieldName = expectSingleStrLitDecorator(dec)
-
-      if (fieldName instanceof Error) return fieldName
-
-      // Get the field's type
-      const typ = resolveTypeDependencies(arg.getType(), filePath, absoluteSrcPath)
+  const hasArgsByKey = Object.keys(paramMap).length > 0
 
-      const depsCount = typ.dependencies.size
+  if (genericParam && hasArgsByKey) {
+    panicWithContext(`Cannot mix generic and specific ${decoratedArgs[0].decoratorType}()`, decoratedArgs[0].context)
+  }
 
-      debug(
-        `├───── Detected BODY type: {cyan} ({magentaBright} ${
-          depsCount === 0 ? 'no dependency' : depsCount > 1 ? 'dependencies' : 'dependency'
-        })`,
-        typ.resolvedType,
-        depsCount
-      )
+  return hasArgsByKey ? paramMap : genericParam
+}
 
-      // If there no name was provided to the decorator, then the decorator is a generic receiver which means it maps to the full body type
-      // This also means we can map the BODY type to this argument's type
-      if (fieldName === null) {
-        const body = collected.body
-
-        // If we previously had an @Body(<name>) decorator on another argument, we have an important risk of mistyping
-        // => e.g. `@Body("a") a: string, @Body() body: { a: number }` is invalid as the type for the `a` field mismatches
-        // => It's easy to make an error as the @Body() type is often hidden behind a DTO
-        // But that's extremely complex to check automatically, so we just display a warning instead
-        // Also, that's not the kind of thing we make on purpose very often, so it's more likely it's an error, which makes it even more important
-        //  to display a warning here.
-        if (body?.full === false)
-          warn('├───── Detected full @Body() decorator after a single parameter. This is considered a bad practice, avoid it if you can!')
-        // Having two generic @Body() decorators is meaningless and will likey lead to errors, so we return a precise error here
-        else if (body?.full) {
-          return new Error(
-            format(
-              `Detected two @Body() decorators: found {yellow} previously, while method argument {yellow} indicates type {yellow}`,
-              body.type.resolvedType,
-              name,
-              typ.resolvedType
-            )
-          )
-        }
-
-        debug("├───── Mapping argument to full request's body")
-
-        // Update the whole BODY type
-        collected.body = { full: true, type: typ }
-      } else {
-        // Here we have an @Body(<string>) decorator
-
-        // If we previously had an @Body() decorator, this can lead to several types of errors (see the big comment above for more informations)
-        if (collected.body?.full) {
-          warn('├───── Detected single @Body() decorator after a full parameter. This is considered a bad practice, avoid it if you can!')
-        } else {
-          debug('├───── Mapping argument to BODY field: {yellow}', fieldName)
-
-          // Update the BODY type by adding the current field to it
-
-          if (fieldName in {}) {
-            return new Error(
-              format(`Detected @Body() field whose name {yellow} collides with a JavaScript's native object property`, fieldName)
-            )
-          }
-
-          collected.body ??= { full: false, fields: new Map() }
-
-          collected.body.fields.set(fieldName, typ)
-        }
-      }
-    }
+const panicWithContext = (message: string, context: MethodContext) => {
+  const { controllerClass, filePath, httpMethod, method } = context
+  const ctx = {
+    controller: controllerClass.getName(),
+    method: method.getName(),
+    httpMethod,
+    filePath,
   }
-
-  // Success!
-  return collected
+  panic(`${message}\n${JSON.stringify(ctx, null, 2)}`)
 }

package/src/analyzer/route.ts

@@ -51,6 +51,7 @@ export function analyzeUri(uriPath: string): Route | Error {
     if (part === '') continue
 
     // Ensure there is no generic character in the path as we don't support them
+    // eslint-disable-next-line no-useless-escape
     const genericErr = _findInvalid(part, /[\*\+\?]/)
 
     if (genericErr) {
@@ -90,8 +91,12 @@ export function analyzeUri(uriPath: string): Route | Error {
  * Get the named parameters of a parsed route
  * @param route
  */
-export function paramsOfRoute(route: Route): string[] {
-  return route.parts.map((part) => ('param' in part ? part.param : null)).filter((e) => e !== null) as string[]
+export function routePartIsParam(part: RoutePart): part is { readonly param: string } {
+  return 'param' in part
+}
+
+export function paramsFromRoute(route: Route): string[] {
+  return route.parts.filter(routePartIsParam).map((part) => part.param)
 }
 
 /**
@@ -115,11 +120,12 @@ export function debugUri(route: Route, color: (str: string) => string): string {
  * @param params
  */
 export function resolveRoute(route: Route, params: { [name: string]: string }): string | Error {
-  let uri: string[] = []
+  const uri: string[] = []
 
   for (const part of route.parts) {
     if ('segment' in part) {
       uri.push(part.segment)
+      // eslint-disable-next-line no-prototype-builtins
     } else if (!params.hasOwnProperty(part.param)) {
       return new Error('Missing route parameter ' + part.param)
     } else {
@@ -136,7 +142,7 @@ export function resolveRoute(route: Route, params: { [name: string]: string }):
  * @param paramsProvider
  */
 export function resolveRouteWith(route: Route, paramsProvider: (param: string) => string | null): string | Error {
-  let uri: string[] = []
+  const uri: string[] = []
 
   for (const part of route.parts) {
     if ('segment' in part) {

package/src/analyzer/typedeps.ts

@@ -3,7 +3,9 @@
  */
 
 import * as path from 'path'
+
 import { ts, Type } from 'ts-morph'
+
 import { unreachable } from '../logging'
 
 /**
@@ -15,15 +17,6 @@ export const IMPORTED_TYPE_REGEX = /\bimport\(['"]([^'"]+)['"]\)\.([a-zA-Z0-9_]+
  * Type with resolved level 1 dependencies (does not look for dependencies' own dependencies!)
  */
 export interface ResolvedTypeDeps {
-  /** The original raw type, with import("...") expressions */
-  readonly rawType: string
-
-  /** The resolved type, without imports */
-  readonly resolvedType: string
-
-  /** File from which the type originates */
-  readonly relativeFilePath: string
-
   /**
    * The type dependencies used by the resolved type
    * A collection of scripts' relative paths mapped with the list of types imported from them
@@ -35,6 +28,15 @@ export interface ResolvedTypeDeps {
    * They may be either local types (declared in the same file than the one analyzed) or globally-defined types
    */
   readonly localTypes: string[]
+
+  /** The original raw type, with import("...") expressions */
+  readonly rawType: string
+
+  /** File from which the type originates */
+  readonly relativeFilePath: string
+
+  /** The resolved type, without imports */
+  readonly resolvedType: string
 }
 
 /**
@@ -55,8 +57,8 @@ export function resolveTypeDependencies(type: Type<ts.Type>, relativeFilePath: s
     )
   }
 
-  let dependencies: ResolvedTypeDeps['dependencies'] = new Map()
-  let localTypes: ResolvedTypeDeps['localTypes'] = []
+  const dependencies: ResolvedTypeDeps['dependencies'] = new Map()
+  const localTypes: ResolvedTypeDeps['localTypes'] = []
 
   /** Resolved type (without import statements) */
   const resolvedType: ResolvedTypeDeps['resolvedType'] = rawType.replace(IMPORTED_TYPE_REGEX, (_, matchedFilePath, type) => {