@buildvision/nest-sdk-generator 1.1.3

package/src/analyzer/route.ts

@@ -0,0 +1,156 @@
+/**
+ * @file Analyzer for the source API's routes in controller methods
+ */
+
+/**
+ * A single URI part
+ */
+export type RoutePart = { readonly segment: string } | { readonly param: string }
+
+/**
+ * A parsed URI path
+ */
+export interface Route {
+  /** Is this an absolute route? (routes starting with a '/') */
+  readonly isRoot: boolean
+
+  /** The route's parts */
+  readonly parts: RoutePart[]
+}
+
+/**
+ * Analyze an URI path
+ * @param uriPath The URI path to analyze
+ */
+export function analyzeUri(uriPath: string): Route | Error {
+  // Split the URI path into "parts"
+  const rawParts = uriPath.split('/')
+
+  // The parsed parts we'll return
+  const parts: RoutePart[] = []
+
+  // The current string offset in the URI path
+  // This variable is used for error display
+  let offset = 0
+
+  /**
+   * Find if a specific part of the URI path contains an invalid character
+   * @param part The part to check
+   * @param pattern The invalid characters to look for, as a regular expression
+   * @returns An error message if an invalid character is found, nothing else
+   */
+  function _findInvalid(part: string, pattern: RegExp): string | null {
+    return part.match(pattern) ? uriPath + '\n' + ' '.repeat(offset) + '^' : null
+  }
+
+  // Treat all parts of the URI path
+  for (let i = 0; i < rawParts.length; i++) {
+    const part = rawParts[i]
+
+    // Ignore empty parts (e.g. "/a///b" will be treated as "/a/b")
+    if (part === '') continue
+
+    // Ensure there is no generic character in the path as we don't support them
+    const genericErr = _findInvalid(part, /[\*\+\?]/)
+
+    if (genericErr) {
+      return new Error(
+        'Generic symbols (* + ?) are not supported as they prevent from determining the right route to use. Found in URI:\n' + genericErr
+      )
+    }
+
+    // Check if this part is an URI parameter
+    if (part.startsWith(':')) {
+      // URI parameters must follow a strict naming
+      const paramErr = _findInvalid(part, /[^a-zA-Z0-9_:]/)
+
+      if (paramErr) {
+        return new Error('Invalid character detected in named parameter in URI:\n' + paramErr)
+      }
+
+      // We got a parameter
+      parts.push({ param: part.substr(1) })
+    } else {
+      // We got a literal part
+      parts.push({ segment: part })
+    }
+
+    // Update the offset for error display
+    offset += part.length + 1
+  }
+
+  // Success!
+  return {
+    isRoot: uriPath.startsWith('/'),
+    parts,
+  }
+}
+
+/**
+ * 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[]
+}
+
+/**
+ * Convert a route back to its original string
+ * @param route
+ */
+export function unparseRoute(route: Route): string {
+  return (route.isRoot ? '/' : '') + route.parts.map((part) => ('segment' in part ? part.segment : ':' + part.param)).join('/')
+}
+
+/**
+ * Pretty-print a route
+ */
+export function debugUri(route: Route, color: (str: string) => string): string {
+  return (route.isRoot ? '/' : '') + route.parts.map((part) => ('segment' in part ? part.segment : color(':' + part.param))).join('/')
+}
+
+/**
+ * Resolve a route by providing its required parameters
+ * @param route
+ * @param params
+ */
+export function resolveRoute(route: Route, params: { [name: string]: string }): string | Error {
+  let uri: string[] = []
+
+  for (const part of route.parts) {
+    if ('segment' in part) {
+      uri.push(part.segment)
+    } else if (!params.hasOwnProperty(part.param)) {
+      return new Error('Missing route parameter ' + part.param)
+    } else {
+      uri.push(params[part.param])
+    }
+  }
+
+  return (route.isRoot ? '/' : '') + uri.join('/')
+}
+
+/**
+ * Resolve a route by providing its required parameters through a callback
+ * @param route
+ * @param paramsProvider
+ */
+export function resolveRouteWith(route: Route, paramsProvider: (param: string) => string | null): string | Error {
+  let uri: string[] = []
+
+  for (const part of route.parts) {
+    if ('segment' in part) {
+      uri.push(part.segment)
+    } else {
+      const param = paramsProvider(part.param)
+
+      if (param === null) {
+        return new Error('Missing route parameter ' + part.param)
+      } else {
+        uri.push(param)
+      }
+    }
+  }
+
+  return (route.isRoot ? '/' : '') + uri.join('/')
+}

package/src/analyzer/typedeps.ts

@@ -0,0 +1,130 @@
+/**
+ * @file Type dependencies builders from the source API
+ */
+
+import * as path from 'path'
+import { ts, Type } from 'ts-morph'
+import { unreachable } from '../logging'
+
+/**
+ * Regex to match or replace imported types
+ */
+export const IMPORTED_TYPE_REGEX = /\bimport\(['"]([^'"]+)['"]\)\.([a-zA-Z0-9_]+)\b/g
+
+/**
+ * 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
+   */
+  readonly dependencies: Map<string, string[]>
+
+  /**
+   * Non-native types that are not imported
+   * They may be either local types (declared in the same file than the one analyzed) or globally-defined types
+   */
+  readonly localTypes: string[]
+}
+
+/**
+ * Resolve the dependencies of a TS-Morph analyzed type
+ * @param type
+ * @param relativeFilePath
+ * @param absoluteSrcPath
+ * @returns
+ */
+export function resolveTypeDependencies(type: Type<ts.Type>, relativeFilePath: string, absoluteSrcPath: string): ResolvedTypeDeps {
+  /** Raw type's text (e.g. `Array<import("somefile.ts").SomeType>`) */
+  const rawType = type.getText()
+
+  if (path.isAbsolute(relativeFilePath)) {
+    unreachable(
+      'Internal error: got absolute file path in type dependencies resolver, when expecting a relative one (got {magentaBright})',
+      relativeFilePath
+    )
+  }
+
+  let dependencies: ResolvedTypeDeps['dependencies'] = new Map()
+  let localTypes: ResolvedTypeDeps['localTypes'] = []
+
+  /** Resolved type (without import statements) */
+  const resolvedType: ResolvedTypeDeps['resolvedType'] = rawType.replace(IMPORTED_TYPE_REGEX, (_, matchedFilePath, type) => {
+    const filePath = path.isAbsolute(matchedFilePath) ? path.relative(absoluteSrcPath, matchedFilePath) : matchedFilePath
+
+    const deps = dependencies.get(filePath)
+
+    if (deps) {
+      if (!deps.includes(type)) {
+        deps.push(type)
+      }
+    } else {
+      dependencies.set(filePath, [type])
+    }
+
+    return type
+  })
+
+  if (resolvedType.includes('import(')) {
+    unreachable('Internal error: resolved still contains an {magenta} statement: {green}', 'import(...)', resolvedType)
+  }
+
+  for (const depFile of dependencies.keys()) {
+    if (path.isAbsolute(depFile)) {
+      unreachable(
+        'Internal error: resolved absolute file path in type dependencies, when should have resolved a relative one\nIn type: {yellow}\nGot: {magentaBright}',
+        type.getText(),
+        depFile
+      )
+    }
+  }
+
+  return {
+    rawType,
+    relativeFilePath,
+    resolvedType,
+    dependencies,
+    localTypes,
+  }
+}
+
+/**
+ * Extract an import type's name from a TS-Morph type
+ * @example "import('dir/file').TypeName" => "TypeName"
+ * @param type
+ * @returns
+ */
+export function getImportResolvedType(type: Type<ts.Type>): string {
+  return type.getText().replace(IMPORTED_TYPE_REGEX, (_, __, typename) => typename)
+}
+
+/**
+ * Convert paths for external files
+ * @param importedFilePath
+ */
+export function normalizeExternalFilePath(importedFilePath: string): string {
+  importedFilePath = path.normalize(importedFilePath)
+
+  if (!importedFilePath.startsWith('../')) {
+    return importedFilePath
+  }
+
+  let level = 0
+
+  while (importedFilePath.startsWith('../')) {
+    level++
+    importedFilePath = importedFilePath.substr(3)
+  }
+
+  return `_external${level}/${importedFilePath}`
+}

package/src/bin.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import * as path from 'path'
+import { analyzerCli } from './analyzer'
+import { config, configPath } from './config'
+import generatorCli from './generator'
+import { println } from './logging'
+
+async function main() {
+  const started = Date.now()
+
+  process.chdir(path.dirname(path.resolve(configPath)))
+
+  switch (process.argv[3]) {
+    case '--analyze':
+      await analyzerCli(config)
+      break
+
+    case '--generate':
+    case undefined:
+      const sdkContent = await analyzerCli(config)
+      await generatorCli(config, sdkContent)
+      break
+
+    default:
+      console.error('ERROR: Unknown action provided (must be either "--analyze" or "--generate")')
+      process.exit(1)
+  }
+
+  println('{green}', '@ Done in ' + ((Date.now() - started) / 1000).toFixed(2) + 's')
+}
+
+main()

package/src/config.ts

@@ -0,0 +1,89 @@
+import chalk = require('chalk')
+import * as fs from 'fs'
+import * as path from 'path'
+
+/**
+ * The configuration file's content
+ * For details on what these options do, see the project's README
+ */
+export interface Config {
+  /** Enable verbose mode */
+  readonly verbose?: boolean
+
+  /** Disable colored output */
+  readonly noColor?: boolean
+
+  /** Path to the API's source directory */
+  readonly apiInputPath: string
+
+  /** Path to generate the SDK at */
+  readonly sdkOutput: string
+
+  /** Path to the SDK interface file */
+  readonly sdkInterfacePath: string
+
+  /** List of magic types */
+  readonly magicTypes?: MagicType[]
+
+  /** Show a JSON output */
+  readonly jsonOutput?: string
+
+  /** Prettify the JSON output */
+  readonly jsonPrettyOutput?: boolean
+
+  /** Prettify the generated files (enabled by default) */
+  readonly prettify?: boolean
+
+  /** Path to Prettier's configuration file */
+  readonly prettierConfig?: string
+
+  /** Path to custom tsconfig file */
+  readonly tsconfigFile?: string
+
+  /** If the output directory already exists, overwrite it (enabled by default) */
+  readonly overwriteOldOutputDir?: boolean
+
+  /** If the SDK interface file does not exist yet, create one automatically (enabled by default) */
+  readonly generateDefaultSdkInterface?: boolean
+
+  /** Write generation timestamp in each TypeScript file (enabled by default) */
+  readonly generateTimestamps?: boolean
+}
+
+/**
+ * Magic type used to replace a non-compatible type in the generated SDK
+ */
+export interface MagicType {
+  readonly nodeModuleFilePath: string
+  readonly typeName: string
+  readonly placeholderContent: string
+}
+
+/**
+ * Load an existing configuration file and decode it
+ * @param configPath
+ */
+function loadConfigFile(configPath: string): Config {
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('Config file was not found at path: ' + chalk.yellow(path.resolve(configPath))))
+    process.exit(4)
+  }
+
+  const text = fs.readFileSync(configPath, 'utf8')
+
+  try {
+    return JSON.parse(text)
+  } catch (e) {
+    console.error(chalk.red('Failed to parse configuration file: ' + e))
+    process.exit(3)
+  }
+}
+
+export const configPath = process.argv[2]
+
+if (!configPath) {
+  console.error(chalk.red('Please provide a path to the configuration file'))
+  process.exit(2)
+}
+
+export const config = loadConfigFile(configPath)

package/src/generator/genmodules.ts

@@ -0,0 +1,163 @@
+/**
+ * @file Generate SDK modules
+ */
+
+import * as path from 'path'
+import { SdkModules } from '../analyzer/controllers'
+import { SdkMethod } from '../analyzer/methods'
+import { SdkMethodParams } from '../analyzer/params'
+import { resolveRouteWith, unparseRoute } from '../analyzer/route'
+import { normalizeExternalFilePath, ResolvedTypeDeps } from '../analyzer/typedeps'
+import { panic } from '../logging'
+
+/**
+ * Generate the SDK's module and controllers files
+ * @param modules
+ * @returns
+ */
+export function generateSdkModules(modules: SdkModules): Map<string, string> {
+  /** Generated module files */
+  const genFiles = new Map<string, string>()
+
+  // Iterate over each module
+  for (const [moduleName, controllers] of modules) {
+    // Iterate over each of the module's controllers
+    for (const [controllerName, controller] of controllers) {
+      /** Generated controller's content */
+      const out: string[] = []
+
+      out.push('/// Parent module: ' + moduleName)
+      out.push(`/// Controller: "${controllerName}" registered as "${controller.registrationName}" (${controller.methods.length} routes)`)
+      out.push('')
+      out.push('import { request } from "../central";')
+
+      const imports = new Map<string, string[]>()
+
+      const depsToImport = new Array<ResolvedTypeDeps>()
+
+      // Iterate over each controller
+      for (const method of controller.methods.values()) {
+        const { parameters: args, query, body } = method.params
+
+        depsToImport.push(method.returnType)
+
+        if (args) {
+          depsToImport.push(...args.values())
+        }
+
+        if (query) {
+          depsToImport.push(...query.values())
+        }
+
+        if (body) {
+          if (body.full) {
+            depsToImport.push(body.type)
+          } else {
+            depsToImport.push(...body.fields.values())
+          }
+        }
+      }
+
+      // Build the imports list
+      for (const dep of depsToImport) {
+        for (const [file, types] of dep.dependencies) {
+          let imported = imports.get(file)
+
+          if (!imported) {
+            imported = []
+            imports.set(file, imported)
+          }
+
+          for (const typ of types) {
+            if (!imported.includes(typ)) {
+              imported.push(typ)
+            }
+          }
+        }
+      }
+
+      for (const [file, types] of imports) {
+        out.push(
+          `import type { ${types.join(', ')} } from "../_types/${normalizeExternalFilePath(file.replace(/\\/g, '/')).replace(/\\/g, '/')}";`
+        )
+      }
+
+      out.push('')
+      out.push(`export default {`)
+
+      for (const method of controller.methods) {
+        const ret = method.returnType.resolvedType
+        const promised = ret.startsWith('Promise<') ? ret : `Promise<${ret}>`
+
+        out.push('')
+        out.push(`  // ${method.httpMethod} @ ${unparseRoute(method.route)}`)
+        out.push(`  ${method.name}(${generateSdkMethodParams(method.params)}): ${promised} {`)
+        out.push(generateCentralRequest(method).replace(/^/gm, '    '))
+        out.push('  },')
+      }
+
+      out.push('')
+      out.push('};')
+
+      genFiles.set(path.join(moduleName, controller.camelClassName + '.ts'), out.join('\n'))
+    }
+
+    /** Generated module's content */
+    const moduleContent: string[] = []
+
+    moduleContent.push('/// Module name: ' + moduleName)
+    moduleContent.push('')
+
+    for (const controller of controllers.keys()) {
+      moduleContent.push(`export { default as ${controller} } from "./${controller}";`)
+    }
+
+    // Generate the SDK module file
+    genFiles.set(path.join(moduleName, 'index.ts'), moduleContent.join('\n'))
+  }
+
+  return genFiles
+}
+
+/**
+ * Generate the method parameters for a given SDK method
+ * @param params
+ * @returns
+ */
+export function generateSdkMethodParams(params: SdkMethodParams): string {
+  // List of parameters (e.g. `id` in `/get/:id`, analyzed from the usages of the `@Param` decorator)
+  const parameters = params.parameters ? [...params.parameters].map(([name, type]) => `${name}: ${type.resolvedType}`) : []
+
+  // List of query values (e.g. `id` in `?id=xxx`, analyzed from the usages of the `@Query` decorator)
+  const query = params.query ? [...params.query].map(([name, type]) => `${name}: ${type.resolvedType}`) : []
+
+  // Body's content (type used with the `@Body` decorator)
+  const body = params.body
+    ? params.body.full
+      ? params.body.type.resolvedType
+      : '{ ' + [...params.body.fields].map(([name, type]) => `${name}: ${type.resolvedType}`).join(', ') + ' }'
+    : null
+
+  // The ternary conditions below are made to eclipse useless parameters
+  // For instance, if we're not expecting any query nor body, these two parameters can be omitted when calling the method
+  return [
+    `params: {${' ' + parameters.join(', ') + ' '}}${parameters.length === 0 && !body && query.length === 0 ? ' = {}' : ''}`,
+    `body: ${body ?? '{}'}${!body && query.length === 0 ? ' = {}' : ''}`,
+    `query: {${' ' + query.join(', ') + ' '}}${query.length === 0 ? ' = {}' : ''}`,
+  ].join(', ')
+}
+
+/**
+ * Generate a request call to Central for the generated files
+ * @param method
+ * @returns
+ */
+export function generateCentralRequest(method: SdkMethod): string {
+  const resolvedRoute = resolveRouteWith(method.route, (param) => '${params.' + param + '}')
+
+  if (resolvedRoute instanceof Error) {
+    panic('Internal error: failed to resolve route: ' + resolvedRoute.message)
+  }
+
+  return `return request('${method.httpMethod}', \`${resolvedRoute}\`, body, query) as any`
+}

package/src/generator/gentypes.ts

@@ -0,0 +1,73 @@
+/**
+ * @file Generate type files for the SDK
+ */
+
+import * as path from 'path'
+import { TypesExtractorContent } from '../analyzer/extractor'
+import { normalizeExternalFilePath } from '../analyzer/typedeps'
+
+/**
+ * Generate the non-formatted type files which will be used by the SDK's route functions
+ * @param sdkTypes
+ * @returns
+ */
+export function generateSdkTypeFiles(sdkTypes: TypesExtractorContent): Map<string, string> {
+  /** Generated type files */
+  const genFiles = new Map<string, string>()
+
+  // While analyzing the controllers' content, all types used by their methods have been extracted
+  // The list of these types is then provided to this function as the `sdkTypes` argument, allowing us
+  //  to establish the list of all dependencies.
+  for (const [file, types] of sdkTypes) {
+    const out = []
+
+    /** List of imports in the current file */
+    const imports = new Map<string, string[]>()
+
+    // Iterate over all types in the current `file`
+    for (const extracted of types.values()) {
+      // Iterate over all of the extracted type's dependencies
+      for (const dep of extracted.dependencies) {
+        // If the dependency is from the same file, then we have nothing to do
+        if (dep.relativePath === file) {
+          continue
+        }
+
+        // Push the typename to the list of imports
+        let imported = imports.get(dep.relativePathNoExt)
+
+        if (!imported) {
+          imported = [dep.typename]
+          imports.set(dep.relativePathNoExt, imported)
+        }
+
+        if (!imported.includes(dep.typename)) {
+          imported.push(dep.typename)
+        }
+      }
+    }
+
+    // Generate an import statement for each imported type
+    out.push(
+      [...imports]
+        .map(([depFile, types]) => {
+          let depPath = path.relative(path.dirname(file), normalizeExternalFilePath(depFile)).replace(/\\/g, '/')
+          if (!depPath.includes('/')) depPath = './' + depPath
+          return `import type { ${types.join(', ')} } from "${
+            depPath.startsWith('./') || depPath.startsWith('../') ? depPath : './' + depPath
+          }"`
+        })
+        .join('\n')
+    )
+
+    // Add the extracted types' declaration, indented
+    for (const extracted of types.values()) {
+      out.push(extracted.content.replace(/^/gm, '  '))
+    }
+
+    // Generate the type file
+    genFiles.set(file, out.join('\n'))
+  }
+
+  return genFiles
+}