@ackee/create-node-app 1.0.0

package/starter/cloudrun/src/index.ts

@@ -0,0 +1,17 @@
+import { config } from './config.js'
+import { createContainer } from './container.js'
+import { createServer } from './view/server.js'
+
+const appContainer = createContainer()
+const { logger } = appContainer
+
+const server = createServer(appContainer)
+
+server.listen(config.server.port, () => {
+  logger.info(
+    { port: config.server.port },
+    `🚀 Server is running on port ${config.server.port}`
+  )
+})
+
+export default server

package/starter/cloudrun/src/test/health-check.test.ts

@@ -0,0 +1,25 @@
+import assert from 'node:assert'
+import { describe, it, before } from 'mocha'
+import { createServer } from '../view/server.js'
+import { createContainer } from '../container.js'
+import { requestTyped } from './util/openapi-test.util.js'
+
+describe('Health Check API', () => {
+  let server: ReturnType<typeof createServer>
+  let container: ReturnType<typeof createContainer>
+
+  before(() => {
+    container = createContainer()
+    server = createServer(container)
+  })
+
+  describe('GET /api/v1/healthz', () => {
+    it('should return successful health check response', async () => {
+      const response = await requestTyped(server, '/api/v1/healthz', 'get')
+        .sendTyped()
+        .expect(200)
+        .responseTyped()
+      assert.equal(response.body.status, 0)
+    })
+  })
+})

package/starter/cloudrun/src/test/util/openapi-test.util.ts

@@ -0,0 +1,71 @@
+import supertest from 'supertest'
+import {
+  OpenApiRoutePathParam,
+  OpenApiRouteQueryParam,
+  OpenApiRouteRequestBody,
+  OpenApiRouteResponseBody,
+} from '../../view/rest/util/openapi.util.js'
+import * as openapi from '../../view/rest/spec/openapi.js'
+import type { Express } from 'express'
+
+export const request = (server: Express) => supertest(server)
+
+type KeysOfUnion<T> = T extends T ? keyof T : never
+
+export type Response<TBody> = Omit<
+  Awaited<ReturnType<ReturnType<typeof request>['get']>>,
+  'body'
+> & { body: TBody }
+
+export const requestTyped = <
+  Resource extends KeysOfUnion<openapi.paths>,
+  Method extends Exclude<KeysOfUnion<openapi.paths[Resource]>, 'parameters'>,
+  Resp extends OpenApiRouteResponseBody<Openapi[Resource], Method>,
+  Openapi extends openapi.paths = openapi.paths
+>(
+  server: Express,
+  resource: Resource,
+  method: Method,
+  routeParams?: OpenApiRoutePathParam<Openapi[Resource]>,
+  queryParams?: OpenApiRouteQueryParam<Openapi[Resource]>
+) => {
+  const replacedResource = Object.keys(
+    (routeParams ?? {}) as Record<string, string>
+  ).reduce((resource, param) => {
+    return resource.replace(
+      // eslint-disable-next-line security/detect-non-literal-regexp
+      new RegExp(`{${param}}`, 'g'),
+      (routeParams as Record<string, string>)[param]
+    )
+  }, resource)
+
+  const url = new URL('https://ackee.cz')
+  Object.entries(queryParams ?? {}).forEach(([key, val]) => {
+    if (val !== undefined && val !== null) {
+      url.searchParams.set(key, val.toString())
+    }
+  })
+
+  const req = request(server)[method](
+    replacedResource + '?' + url.searchParams.toString()
+  )
+  const originalSend = req.send.bind(req)
+  const enhanced = Object.assign(req, {
+    sendTyped(
+      body?: OpenApiRouteRequestBody<Openapi[Resource], Method>,
+      headers?: Record<string, string>
+    ) {
+      if (headers) {
+        Object.entries(headers).forEach(([key, value]) => {
+          void req.set(key, value)
+        })
+      }
+      void originalSend(body as any)
+      return enhanced
+    },
+    responseTyped: () => {
+      return req as Promise<Response<Resp>>
+    },
+  })
+  return enhanced
+}

package/starter/cloudrun/src/view/cli/README.md

@@ -0,0 +1,17 @@
+# CLI
+
+Cli tool to operate scripts that can use internal services or to add development toolkit with the same interface and usage. Currently cli tool is operated using tsx tool.
+
+## 👷 Development
+
+The CLI tool is build around `yargs` library. Each command needs its own `ts` file in current folder or in subfolder. The entrypoint `Cli.ts` scans the sub folders for `ts` files and intrerprets them as a command under the module called same as the folder.
+
+For example, current [openapi folder](./openapi) creates a new module `openapi` and assigns a new command called `generate` based on contents in [generate.ts](./openapi/generate.ts) file.
+
+Each command should export only functions and variables according to `CommandDefinition` in [cli.ts file](./cli.ts).
+
+Take a look at the [generate.ts](./openapi/generate.ts) for example how to implement own command.
+
+## ⚠️ Usage in production scripts
+
+If the cli tool is used to run production scripts (CRON), make sure all dependencies are also listed in production list and build the code instead of using `tsx` (e.g. `yargs`).

package/starter/cloudrun/src/view/cli/cli.ts

@@ -0,0 +1,94 @@
+import yargs, { Argv } from 'yargs'
+import { hideBin } from 'yargs/helpers'
+import { readdir, stat } from 'fs/promises'
+import { join, extname } from 'path'
+
+interface CommandDefinition {
+  // Description of the command used for help
+  description: string
+  // Defines positional description of the command (e.g. '<filepath>' will mean it takes one positional required argument)
+  positional?: string
+  // Function that will be called when the command is executed
+  run: (argv: any) => Promise<void> | void
+  // Function that will be called to add options to the command
+  options?: (yargs: Argv) => Argv
+  // Any other properties that will be added to the command
+  [key: string]: any
+}
+
+const loadCommand = async (
+  commandName: string,
+  commandPath: string,
+  yargsInstance: Argv
+) => {
+  try {
+    const modulePath = `file://${commandPath}`
+    const commandModule = (await import(modulePath)) as CommandDefinition
+
+    if (typeof commandModule.run === 'function') {
+      yargsInstance.command(
+        commandModule.positional
+          ? `${commandName} ${commandModule.positional}`
+          : commandName,
+        commandModule.description ?? `${commandName} command`,
+        (yargs: Argv) => {
+          if (typeof commandModule.options === 'function') {
+            return commandModule.options(yargs)
+          }
+        },
+        async (argv: any) => {
+          try {
+            await commandModule.run(argv)
+          } catch (error) {
+            console.error(`Error running ${commandName}:`, error)
+            process.exit(1)
+          }
+        }
+      )
+    } else {
+      console.warn(`Warning: ${commandPath} does not export a 'run' function`)
+    }
+  } catch (error) {
+    console.error(`Error loading command from ${commandPath}:`, error)
+  }
+}
+
+const loadCommandsFromDirectory = async (
+  dirPath: string,
+  yargsInstance: Argv
+): Promise<void> => {
+  const items = await readdir(dirPath)
+
+  for (const item of items) {
+    const fullPath = join(dirPath, item)
+    const stats = await stat(fullPath)
+
+    if (stats.isDirectory()) {
+      yargsInstance.command(item, `${item} module`, (yargs: Argv) => {
+        yargs.demandCommand(1, 'You need to specify a command.')
+        yargs.help()
+        return loadCommandsFromDirectory(fullPath, yargs)
+      })
+    } else if (stats.isFile() && extname(item) === '.ts' && item !== 'cli.ts') {
+      const commandName = item.replace('.ts', '')
+      await loadCommand(commandName, fullPath, yargsInstance)
+    }
+  }
+}
+
+export const cli = async () => {
+  const yargsInstance = yargs(hideBin(process.argv))
+    .scriptName('cli')
+    .usage('Usage: $0 <command> [options]')
+    .demandCommand(1, 'You need to specify a command or module.')
+    .help()
+    .version()
+
+  await loadCommandsFromDirectory(import.meta.dirname, yargsInstance)
+
+  await yargsInstance.parse()
+
+  process.exit(0)
+}
+
+void cli()

package/starter/cloudrun/src/view/cli/openapi/generate.ts

@@ -0,0 +1,64 @@
+import { spawn } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import yaml from 'yaml'
+
+export const description = 'Generate OpenAPI types and validate the spec'
+export const positional = '<filepath>'
+
+export const run = async (argv: any): Promise<void> => {
+  console.log('Generating OpenAPI types and validate the spec...')
+  const yamlFilePath = argv.filepath
+  const tsFilePath = path.join(
+    path.dirname(argv.filepath),
+    `${path.basename(argv.filepath, path.extname(argv.filepath))}.ts`
+  )
+
+  await new Promise((resolve, reject) => {
+    const process = spawn(
+      'npx',
+      ['openapi-typescript', yamlFilePath, '--output', tsFilePath],
+      { stdio: 'inherit' }
+    )
+    process.on('exit', resolve)
+    process.on('error', reject)
+  })
+
+  console.log('Generating path mappings...')
+
+  const types = readFileSync(tsFilePath)
+  const spec = yaml.parse(readFileSync(yamlFilePath).toString())
+
+  const pathsWithOperationIds = Object.keys(spec.paths).reduce((acc, path) => {
+    const pathSpec = spec.paths[path]
+    Object.keys(pathSpec).forEach(method => {
+      if (pathSpec[method]?.operationId) {
+        acc[pathSpec[method].operationId] = {
+          method,
+          path,
+        }
+      }
+    })
+    return acc
+  }, {} as any)
+
+  const finalSpec =
+    `/* eslint-disable sonarjs/no-duplicate-string */\n` +
+    `/* eslint-disable sonarjs/use-type-alias */\n` +
+    types.toString('utf8').replaceAll('requestBody?:', 'requestBody:') +
+    `export const operationPaths = ${JSON.stringify(
+      pathsWithOperationIds
+    )} as const\n`
+
+  writeFileSync(tsFilePath, finalSpec)
+
+  console.log('Done 🎉')
+}
+
+export const options = (yargs: any) => {
+  return yargs.positional('filepath', {
+    required: true,
+    type: 'string',
+    description: 'Input OpenAPI specification file',
+  })
+}

package/starter/cloudrun/src/view/rest/controller/health-check.controller.ts

@@ -0,0 +1,33 @@
+import { Result } from 'node-healthz'
+import { components } from '../spec/openapi.js'
+import { ctrl } from '../util/openapi.util.js'
+
+export enum Status {
+  Healthy,
+  Unhealthy,
+}
+
+const mapHealthCheckToApi = (
+  healthCheck: Result
+): components['schemas']['HealthCheckResponse'] => {
+  return {
+    status: healthCheck.status,
+    checks: healthCheck.checks.map(check => ({
+      id: check.id,
+      status: check.status,
+      output: String(check.output),
+      required: check.required,
+      latency: check.latency,
+      latencyStatus: check.latencyStatus,
+    })),
+  }
+}
+
+export const healthCheckController = ctrl.createRestController({
+  healthz: async ctx => {
+    const { healthCheckService } = ctx.container
+
+    const healthCheck = await healthCheckService.check()
+    return mapHealthCheckToApi(healthCheck)
+  },
+})

package/starter/cloudrun/src/view/rest/middleware/context-middleware.ts

@@ -0,0 +1,28 @@
+import { NextFunction, Request, Response } from 'express'
+import { RequestContextFactory } from '../../../context.js'
+import { Container } from '../../../container.js'
+
+const createContextFromHttpRequestFactory =
+  (): RequestContextFactory<[Request, Response]> =>
+  async (container, _req, _res) => {
+    return {
+      type: 'api-user',
+      container,
+      user: null, // Implement Authentication if needed (Auth header, cookie, ...)
+    }
+  }
+
+export const createContextMiddleware =
+  (container: Container) =>
+  async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    try {
+      req.context = await createContextFromHttpRequestFactory()(
+        container,
+        req,
+        res
+      )
+      next()
+    } catch (err) {
+      next(err)
+    }
+  }

package/starter/cloudrun/src/view/rest/middleware/error-handler.ts

@@ -0,0 +1,60 @@
+import { ErrorCode } from '../../../domain/errors/codes.js'
+import { DomainError } from '../../../domain/errors/errors.js'
+import express from 'express'
+
+export interface ErrorHandlerConfig {
+  enableProductionHttpErrorResponses: boolean
+}
+
+const ERROR_DOMAIN_CODE_TO_HTTP_STATUS: Record<ErrorCode, number> = {
+  [ErrorCode.UNKNOWN]: 500,
+  [ErrorCode.VALIDATION]: 422,
+}
+
+const errorToProductionObject = <T extends Error>(error: T) => {
+  if (error instanceof DomainError) {
+    return {
+      ...error.data,
+      code: error.code,
+    }
+  }
+  return {}
+}
+
+const errorToDevObject = <T extends Error>(error: T) => {
+  if (error instanceof DomainError) {
+    return {
+      ...error.data,
+      code: error.code,
+      message: error.message,
+      stack: error.stack,
+    }
+  }
+  return {
+    message: error.message,
+    stack: error.stack,
+  }
+}
+
+export function createErrorHandler(
+  config: ErrorHandlerConfig
+): express.ErrorRequestHandler {
+  return (error, _req, res, _next) => {
+    const statusCode =
+      error instanceof DomainError
+        ? ERROR_DOMAIN_CODE_TO_HTTP_STATUS[error.code] ?? 500
+        : 500
+
+    ;(res as any).error = errorToDevObject(error)
+
+    const mappedError = config.enableProductionHttpErrorResponses
+      ? errorToProductionObject(error)
+      : errorToDevObject(error)
+
+    res.status(statusCode)
+    if (mappedError) {
+      ;(res as any).out = mappedError
+      res.json(mappedError)
+    }
+  }
+}

package/starter/cloudrun/src/view/rest/middleware/request-logger.ts

@@ -0,0 +1,37 @@
+import { pinoHttp, Options } from 'pino-http'
+import { LoggerPort } from '../../../domain/ports/logger.d.js'
+
+export function createRequestLogger(innerLogger: LoggerPort) {
+  const options: Options = {
+    logger: innerLogger as any,
+    serializers: {
+      res: res => {
+        res.error = res.raw.error
+        res.out = res.raw.out
+        return res
+      },
+      req: req => {
+        req.body = req.raw.body
+        return req
+      },
+    },
+    customReceivedMessage: (req, _res) =>
+      `--- ${String(req.method)} ${String(req.url)} - Request accepted`,
+    customSuccessMessage: (req, res) =>
+      `${res.statusCode} ${String(req.method)} ${String(
+        req.url
+      )} - Standard output`,
+    customErrorMessage: (req, res, _error) =>
+      `${res.statusCode} ${String(req.method)} ${String(req.url)} - ${
+        res.statusMessage
+      }`,
+    customErrorObject: (_req, res, _error, val) => ({
+      ...val,
+      error: (res as any).error,
+    }),
+    customAttributeKeys: {
+      err: 'error',
+    },
+  }
+  return pinoHttp(options)
+}

package/starter/cloudrun/src/view/rest/request.d.ts

@@ -0,0 +1,9 @@
+import { RequestContext } from '../../context.js'
+
+declare global {
+  namespace Express {
+    export interface Request {
+      context: RequestContext
+    }
+  }
+}

package/starter/cloudrun/src/view/rest/routes.ts

@@ -0,0 +1,15 @@
+import express from 'express'
+import { openApiRouter, registerOpenApiRoutes } from './util/openapi.util.js'
+import { healthCheckController } from './controller/health-check.controller.js'
+
+const apiRouter = openApiRouter(express.Router(), {
+  removePrefix: '/api/v1',
+})
+
+registerOpenApiRoutes(apiRouter, {
+  ...healthCheckController,
+})
+
+export const routes = {
+  api: apiRouter.express,
+}

package/starter/cloudrun/src/view/rest/spec/openapi.yml

@@ -0,0 +1,65 @@
+openapi: '3.0.3'
+info:
+  title: Node App API
+  version: '0.0.1'
+
+paths:
+  /api/v1/healthz:
+    get:
+      operationId: healthz
+      summary: Health check
+      tags:
+        - healthz
+      responses:
+        '200':
+          description: Health check response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthCheckResponse'
+
+components:
+  schemas:
+    HealthCheckResponse:
+      type: object
+      properties:
+        checks:
+          type: array
+          description: List of component health checks
+          items:
+            $ref: '#/components/schemas/HealthCheck'
+        status:
+          type: integer
+          description: Overall status (0=healthy, 1=error)
+          enum: [0, 1]
+      required:
+        - checks
+        - status
+    HealthCheck:
+          type: object
+          properties:
+            id:
+              type: string
+              description: Unique identifier of the checked component
+              example: 'postgres'
+            latency:
+              type: integer
+              description: Response time in milliseconds
+              example: 1
+            latencyStatus:
+              type: integer
+              description: Status of the latency check (0=good, 1=error, 2=timeout)
+              enum: [0, 1, 2]
+              example: 0
+            output:
+              type: string
+              description: Additional output information
+              example: '<masked>'
+            required:
+              type: boolean
+              description: Whether this component is required for the system to function
+              example: true
+            status:
+              type: integer
+              description: Status of the component (0=Low, 1=Medium, 2=High)
+              enum: [0, 1, 2]