@ackee/create-node-app 1.0.1 → 2.0.0

package/starter/_base/README.md

@@ -0,0 +1,53 @@
+# Create-Node-App Project
+
+Node.js application bootstrapped with [create-node-app](https://github.com/AckeeCZ/create-node-app)
+
+## 🏗️ Architecture
+
+All domain logic should live inside the [domain folder](src/domain) and should be accessed only via [container](src/container.ts). Each external dependency should be referenced by its own port inside the [domain/port](src/domain/ports) folder. These ports are also part of the container and can be implemented by any external dependency inside the [adapters](src/adapters/) folder.
+
+The application should be accessed through the [view](src/view/) layer of the application. All UI and interfaces should be defined there. The main entrypoint is defined in the [index.ts](src/index.ts) file.
+
+Each domain service should always accept [RequestContext](src/context.ts) as the first parameter. Part of the context is also the container with all of the application dependencies.
+
+## 👷 Development
+
+Application configuration is handled by [Configuru](https://github.com/AckeeCZ/configuru). All env options that can be changed or need to be set up are described in [.env.jsonc](.env.jsonc).
+
+The whole codebase is checked and improved using lint and prettier, run `lint:fix` and `prettier:fix` before committing changes to git.
+
+```bash
+npm run lint:fix
+npm run prettier:fix
+```
+
+## ✅ Tests
+
+Test are written using [mocha](https://github.com/mochajs/mocha). They are maintained in two ways:
+
+- **unit tests** should be next to the tested file with `test.ts` suffix,
+- **integration tests** should be located inside the [test](src/test/) folder.
+
+Use mocked container during integration tests.
+
+If you need any prerequisites during tests, use the [setup.ts](src/test/setup.ts) file.
+
+To run tests use the test command:
+
+```bash
+npm run test
+```
+
+## 🚀 Quick start
+
+1. Build the code
+
+```bash
+npm run build
+```
+
+2. Start the entrypoint / server
+
+```bash
+npm run start
+```

package/starter/_base/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "app",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "mocha",
+    "build": "tsc",
+    "start": "node -r source-map-support/register dist/index.js",
+    "ci-test:no-coverage": "npm run test -- --parallel=false -R mocha-multi-reporters --reporter-options configFile=.mocha-junit-config.json",
+    "ci-test": "nyc -a -r cobertura --report-dir output npm run ci-test:no-coverage",
+    "prettier": "prettier --check --write '**/*.{ts,js,json,jsonc,md}'",
+    "lint": "eslint '**/*.ts' -f codeframe --fix",
+    "codestyle": "npm run lint && npm run prettier",
+    "ci-lint": "npm run lint -- -f checkstyle -o ./output/checkstyle-result.xml",
+    "cli": "tsx ./src/view/cli/cli.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "configuru": "^1.0.0",
+    "pino": "^9.0.0",
+    "source-map-support": "^0.5.0"
+  },
+  "devDependencies": {
+    "@ackee/styleguide-backend-config": "^1.0.1",
+    "@istanbuljs/nyc-config-typescript": "^1.0.0",
+    "@types/mocha": "^10.0.0",
+    "@types/node": "^24.0.0",
+    "eslint": "^8.0.0",
+    "eslint-formatter-gitlab": "^5.0.0",
+    "mocha": "^11.0.0",
+    "mocha-junit-reporter": "^2.0.0",
+    "mocha-multi-reporters": "^1.0.0",
+    "nyc": "^17.0.0",
+    "pino-pretty": "^13.0.0",
+    "prettier": "^3.0.0",
+    "ts-node": "^10.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "yargs": "^18.0.0"
+  },
+  "type": "module"
+}

package/starter/{cloudrun → _base}/src/adapters/pino.logger.ts

@@ -1,4 +1,4 @@
-import { pino as pinoLogger } from 'pino'
+import pinoLogger from 'pino'
 import { LoggerFactoryPort } from '../domain/ports/logger.d.js'
 
 // https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity

package/starter/_base/src/config.ts

@@ -0,0 +1,16 @@
+import { createLoader, maskedValues, values } from 'configuru'
+import { Level } from 'pino'
+
+const loader = createLoader({
+  defaultConfigPath: '.env.jsonc',
+})
+
+const configSchema = {
+  logger: {
+    defaultLevel: loader.custom(x => x as Level)('LOGGER_DEFAULT_LEVEL'),
+    pretty: loader.bool('LOGGER_PRETTY'),
+  },
+}
+
+export const config = values(configSchema)
+export const safeConfig = maskedValues(configSchema)

package/starter/{cloudrun-graphql → _base}/src/container.ts

@@ -6,7 +6,9 @@ export interface Container {
   logger: LoggerPort
 }
 
-export const createContainer = (): Container => {
+export type ContainerFactory = () => Promise<Container>
+
+export const createContainer: ContainerFactory = async () => {
   const logger = pinoLoggerFactory.create(config.logger)
 
   return {

package/starter/_base/src/index.ts

@@ -0,0 +1,14 @@
+import { createContainer } from './container.js'
+import { RequestContext } from './context.js'
+
+const entrypoint = async () => {
+  const ctx: RequestContext = {
+    container: await createContainer(),
+    type: 'api-user',
+    user: null,
+  }
+
+  ctx.container.logger.info('Hello World! 🎉')
+}
+
+void entrypoint()

package/starter/{cloudrun → _base}/src/view/cli/README.md

@@ -4,13 +4,9 @@ Cli tool to operate scripts that can use internal services or to add development
 
 ## 👷 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.
+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. Each command should export only functions and variables according to `CommandDefinition` in [cli.ts file](./cli.ts).
 
-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.
+For example, if you add `openapi` folder, it will creates a new module `openapi`. If you add a new command called `generate.ts`, it will also assign a new generate command to this module.
 
 ## ⚠️ Usage in production scripts
 

package/starter/api/graphql/.env.jsonc

@@ -0,0 +1,8 @@
+{
+  // Server will run on this port
+  "SERVER_PORT": 3000,
+  // Response development errors for debugging
+  "SERVER_ALLOW_RESPONSE_ERRORS": false,
+  // Enable GraphQL introspection
+  "SERVER_ENABLE_INTROSPECTION": true
+}

package/starter/{cloudrun-graphql → api/graphql}/.eslintrc.cjs

@@ -5,7 +5,7 @@ const defaultConfig = {
 
 module.exports = {
   root: true,
-  ignorePatterns: ['dist', 'docs', 'src/generated'],
+  ignorePatterns: ['dist', 'src/openapi', 'docs', 'knexfile.ts'],
   overrides: [
     {
       ...omit(defaultConfig, ['ignorePatterns']),
@@ -14,10 +14,9 @@ module.exports = {
         project: '.eslint.tsconfig.json',
       },
       rules: {
-        ...defaultConfig['rules'],
-        '@typescript-eslint/strict-boolean-expressions': 0,
-        '@typescript-eslint/no-misused-promises': 'warn',
-      },
+        ...defaultConfig.rules,
+        '@typescript-eslint/no-empty-object-type': 0,
+      }
     },
     {
       files: ['**/*.graphql'],

package/starter/api/graphql/node-app.jsonc

@@ -0,0 +1,6 @@
+{
+  "module": "API",
+  "id": "graphql",
+  "name": "GraphQL",
+  "prebuild": ["generate:api"]
+}

package/starter/api/graphql/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "app-api-graphql",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "generate:api": "graphql-codegen --config codegen.yml && npm run codestyle",
+    "build:copy-schema": "mkdir -p ./dist/view/graphql/schema && cp -r ./src/view/graphql/schema ./dist/view/graphql/schema",
+    "build": "npm run build:copy-schema && tsc"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@as-integrations/express5": "^1.1.2",
+    "@apollo/server": "^4.1.0",
+    "@graphql-tools/load-files": "^7.0.0",
+    "@graphql-tools/merge": "^9.0.0",
+    "@graphql-tools/schema": "^10.0.0",
+    "lodash-es": "^4.17.21",
+    "express": "^5.0.0",
+    "graphql": "^16.0.0",
+    "node-healthz": "^2.0.0",
+    "pino-http": "^10.0.0"
+  },
+  "devDependencies": {
+    "@graphql-codegen/cli": "^5.0.0",
+    "@graphql-codegen/typescript": "^4.0.0",
+    "@graphql-codegen/typescript-resolvers": "^4.0.0",
+    "@graphql-eslint/eslint-plugin": "^4.4.0",
+    "@types/express": "^5.0.0",
+    "@types/supertest": "^6.0.0",
+    "supertest": "^7.0.0"
+  },
+  "type": "module"
+}

package/starter/{cloudrun-graphql → api/graphql}/src/config.ts

@@ -11,10 +11,6 @@ const configSchema = {
     allowResponseErrors: loader.bool('SERVER_ALLOW_RESPONSE_ERRORS'),
     enableIntrospection: loader.bool('SERVER_ENABLE_INTROSPECTION'),
   },
-  logger: {
-    defaultLevel: loader.custom(x => x as any as Level)('LOGGER_DEFAULT_LEVEL'),
-    pretty: loader.bool('LOGGER_PRETTY'),
-  },
 }
 
 export const config = values(configSchema)

package/starter/api/graphql/src/index.ts

@@ -0,0 +1,11 @@
+import { config, safeConfig } from './config.js'
+import { createAppServer, startServer } from './view/server.js'
+import { pinoLoggerFactory } from './adapters/pino.logger.js'
+import { createContainer } from './container.js'
+
+const logger = pinoLoggerFactory.create(config.logger)
+
+logger.info({ config: safeConfig }, 'Loaded config')
+
+const appServer = createAppServer()
+void startServer({ ...appServer, logger, containerFactory: createContainer })

package/starter/{cloudrun-graphql → api/graphql}/src/test/helloWorld.test.ts

@@ -1,16 +1,27 @@
 import assert from 'node:assert'
-import { describe, it } from 'mocha'
+import { describe, before, test } from 'mocha'
 import { createAppServer } from '../view/server.js'
 import { gql } from 'graphql-tag'
+import { ApolloServer } from '@apollo/server'
 
 describe('Hello world', () => {
-  it('should return greeting', async () => {
+  let server: ApolloServer
+
+  before(async () => {
+    const { server: appServer } = createAppServer()
+    server = appServer
+  })
+
+  after(async () => {
+    await server.stop()
+  })
+
+  test('should return greeting', async () => {
     const query = gql`
       query Hello {
         greeting
       }
     `
-    const { server } = createAppServer()
     const res = await server.executeOperation({ query })
 
     assert(res.body.kind === 'single')

package/starter/api/graphql/src/view/graphql/context-factory.ts

@@ -0,0 +1,13 @@
+import { RequestContext } from '../../context.js'
+import { ContainerFactory } from '../../container.js'
+
+export const contextFactory = async (
+  containerFactory: ContainerFactory
+): Promise<RequestContext> => {
+  const container = await containerFactory()
+  return {
+    type: 'api-user',
+    container,
+    user: null, // Add UserContext if Auth is implemented
+  }
+}

package/starter/{cloudrun-graphql → api/graphql}/src/view/server.ts

@@ -6,7 +6,9 @@ import { schema } from './graphql/schema.js'
 import express from 'express'
 import { ctrl } from './controller.js'
 import { expressMiddleware } from '@as-integrations/express5'
-import { Container } from '../container.js'
+import { LoggerPort } from '../domain/ports/logger.d.js'
+import { ContainerFactory } from '../container.js'
+import { contextFactory } from './graphql/context-factory.js'
 
 export const clientSchema = makeExecutableSchema({
   typeDefs: schema,
@@ -29,13 +31,21 @@ export const createAppServer = () => {
 export async function startServer({
   app,
   server,
-  container,
-}: ReturnType<typeof createAppServer> & { container: Container }) {
-  const { logger } = container
-
+  logger,
+  containerFactory,
+}: ReturnType<typeof createAppServer> & {
+  logger: LoggerPort
+  containerFactory: ContainerFactory
+}) {
   await server.start()
 
-  app.use('/api/graphql', ctrl.json, expressMiddleware(server))
+  app.use(
+    '/api/graphql',
+    ctrl.json,
+    expressMiddleware(server, {
+      context: () => contextFactory(containerFactory),
+    })
+  )
 
   app.listen({ port: config.server.port }, () =>
     logger.info({}, `Server started, port=${config.server.port}`)

package/starter/api/rest/.env.jsonc

@@ -0,0 +1,6 @@
+{
+  // API server listening port.
+  "SERVER_PORT": 3000,
+  // Boolean to remove sensitive info from http error responses
+  "ENABLE_PRODUCTION_HTTP_ERROR_RESPONSES": false
+}

package/starter/api/rest/.eslintrc.cjs

@@ -0,0 +1,8 @@
+module.exports = {
+  ...require('@ackee/styleguide-backend-config/eslint'),
+  root: true,
+  ignorePatterns: ['dist', 'src/openapi', 'docs', 'knexfile.ts'],
+  parserOptions: {
+    project: '.eslint.tsconfig.json',
+  },
+}

package/starter/api/rest/node-app.jsonc

@@ -0,0 +1,6 @@
+{
+  "module": "API",
+  "id": "rest",
+  "name": "RESTful",
+  "prebuild": ["generate:api"]
+}

package/starter/api/rest/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "app-api-rest",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "generate:api": "npm run cli openapi generate src/view/rest/spec/openapi.yml && npm run codestyle"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "express": "^5.0.0",
+    "node-healthz": "^2.0.0",
+    "pino-http": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/supertest": "^6.0.0",
+    "openapi-typescript": "^7.0.0",
+    "supertest": "^7.0.0",
+    "yaml": "^2.0.0"
+  },
+  "type": "module"
+}

package/starter/{cloudrun → api/rest}/src/config.ts

@@ -1,15 +1,10 @@
 import { createLoader, maskedValues, values } from 'configuru'
-import { Level } from 'pino'
 
 const loader = createLoader({
   defaultConfigPath: '.env.jsonc',
 })
 
 const configSchema = {
-  logger: {
-    defaultLevel: loader.custom(x => x as Level)('LOGGER_DEFAULT_LEVEL'),
-    pretty: loader.bool('LOGGER_PRETTY'),
-  },
   server: {
     port: loader.number('SERVER_PORT'),
     enableProductionHttpErrorResponses: loader.bool(

package/starter/api/rest/src/container.ts

@@ -0,0 +1,13 @@
+import { healthCheckService } from './domain/health-check.service.js'
+
+export interface Container {
+  healthCheckService: typeof healthCheckService
+}
+
+export type ContainerFactory = () => Promise<Container>
+
+export const createContainer: ContainerFactory = async () => {
+  return {
+    healthCheckService,
+  }
+}

package/starter/{cloudrun → api/rest}/src/index.ts

@@ -1,11 +1,11 @@
 import { config } from './config.js'
-import { createContainer } from './container.js'
 import { createServer } from './view/server.js'
+import { pinoLoggerFactory } from './adapters/pino.logger.js'
+import { createContainer } from './container.js'
 
-const appContainer = createContainer()
-const { logger } = appContainer
+const logger = pinoLoggerFactory.create(config.logger)
 
-const server = createServer(appContainer)
+const server = await createServer(createContainer)
 
 server.listen(config.server.port, () => {
   logger.info(

package/starter/{cloudrun → api/rest}/src/test/health-check.test.ts

@@ -5,12 +5,10 @@ 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>
+  let server: Awaited<ReturnType<typeof createServer>>
 
-  before(() => {
-    container = createContainer()
-    server = createServer(container)
+  before(async () => {
+    server = await createServer(createContainer)
   })
 
   describe('GET /api/v1/healthz', () => {

package/starter/{cloudrun → api/rest}/src/test/util/openapi-test.util.ts

@@ -21,7 +21,7 @@ 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
+  Openapi extends openapi.paths = openapi.paths,
 >(
   server: Express,
   resource: Resource,
@@ -57,10 +57,10 @@ export const requestTyped = <
     ) {
       if (headers) {
         Object.entries(headers).forEach(([key, value]) => {
-          void req.set(key, value)
+          req.set(key, value)
         })
       }
-      void originalSend(body as any)
+      originalSend(body as any)
       return enhanced
     },
     responseTyped: () => {

package/starter/{cloudrun → api/rest}/src/view/rest/middleware/error-handler.ts

@@ -42,7 +42,7 @@ export function createErrorHandler(
   return (error, _req, res, _next) => {
     const statusCode =
       error instanceof DomainError
-        ? ERROR_DOMAIN_CODE_TO_HTTP_STATUS[error.code] ?? 500
+        ? (ERROR_DOMAIN_CODE_TO_HTTP_STATUS[error.code] ?? 500)
         : 500
 
     ;(res as any).error = errorToDevObject(error)

package/starter/{cloudrun → api/rest}/src/view/rest/routes.ts

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

package/starter/{cloudrun → api/rest}/src/view/rest/util/openapi.util.ts

@@ -6,7 +6,7 @@ import { RequestContext } from '../../../context.js'
 export type OpenApiRouteResponseBodyMethod<
   T,
   TMethod extends string = 'get',
-  TDefault = unknown
+  TDefault = unknown,
 > = T extends {
   [key in TMethod]: {
     responses: { 200: { content: { 'application/json': infer U } } }
@@ -17,7 +17,7 @@ export type OpenApiRouteResponseBodyMethod<
 
 export type OpenApiRouteResponseBody<
   T,
-  TMethod extends string = 'get'
+  TMethod extends string = 'get',
 > = OpenApiRouteResponseBodyMethod<
   T,
   TMethod,
@@ -41,18 +41,18 @@ export type OpenApiRoutePathParam<T> = T extends {
 }
   ? U
   : T extends { post: { parameters: { path: infer U } } }
-  ? U
-  : T extends { put: { parameters: { path: infer U } } }
-  ? U
-  : unknown
+    ? U
+    : T extends { put: { parameters: { path: infer U } } }
+      ? U
+      : unknown
 
 export type OpenApiRouteQueryParam<T> = T extends {
   get: { parameters: { query: infer U } }
 }
   ? U
   : T extends { post: { parameters: { query: infer U } } }
-  ? U
-  : unknown
+    ? U
+    : unknown
 
 export type OpenApiRouteHeaderParam<T> = T extends {
   get: {
@@ -63,14 +63,14 @@ export type OpenApiRouteHeaderParam<T> = T extends {
 }
   ? LowercaseKeys<U>
   : T extends {
-      post: {
-        parameters: {
-          header: infer U extends Record<string | number | symbol, any>
+        post: {
+          parameters: {
+            header: infer U extends Record<string | number | symbol, any>
+          }
         }
       }
-    }
-  ? LowercaseKeys<U>
-  : unknown
+    ? LowercaseKeys<U>
+    : unknown
 
 export type OpenApiRouteParam<T> = OpenApiRoutePathParam<T> &
   OpenApiRouteQueryParam<T> &
@@ -79,7 +79,7 @@ export type OpenApiRouteParam<T> = OpenApiRoutePathParam<T> &
 export type OpenApiRouteRequestBodyMethod<
   T,
   TMethod extends string = 'post',
-  TDefault = unknown
+  TDefault = unknown,
 > = T extends {
   [key in TMethod]: {
     requestBody: {
@@ -94,7 +94,7 @@ export type OpenApiRouteRequestBodyMethod<
 
 export type OpenApiRouteRequestBody<
   T,
-  TMethod extends string = 'post'
+  TMethod extends string = 'post',
 > = OpenApiRouteRequestBodyMethod<
   T,
   TMethod,
@@ -150,7 +150,7 @@ type MimeContent<MimeType extends string> = {
 
 type MimeContentValue<
   MimeType extends ApiMimeTypes,
-  T extends MimeContent<MimeType>
+  T extends MimeContent<MimeType>,
 > = {
   [K in keyof T['content']]: T['content'][K]
 }[keyof T['content']]
@@ -194,7 +194,7 @@ type RouteHandlers<SubsetOperationIds extends OperationIds> = {
 }
 
 export type RestApiController<
-  SubsetOperationIds extends OperationIds = OperationIds
+  SubsetOperationIds extends OperationIds = OperationIds,
 > = {
   [Key in SubsetOperationIds]: OpenApiHandler<Key>
 }
@@ -225,7 +225,7 @@ export const openApiRouter = (
   route: <
     Method extends keyof paths[Path],
     Path extends keyof paths,
-    OperationId extends OperationIds
+    OperationId extends OperationIds,
   >(
     method: Method,
     path: Path,

package/starter/{cloudrun → api/rest}/src/view/server.ts

@@ -1,18 +1,20 @@
 import express from 'express'
 import { createRequestLogger } from './rest/middleware/request-logger.js'
-import { Container } from '../container.js'
 import { config } from '../config.js'
 import { createErrorHandler } from './rest/middleware/error-handler.js'
 import { routes } from './rest/routes.js'
 import { createContextMiddleware } from './rest/middleware/context-middleware.js'
+import { ContainerFactory } from '../container.js'
 
-export const createServer = (appContainer: Container) => {
-  const { logger } = appContainer
+export const createServer = async (containerFactory: ContainerFactory) => {
+  const container = await containerFactory()
+  const { logger } = container
 
   const server = express()
+
   const errorHandler = createErrorHandler(config.server)
   const requestLogger = createRequestLogger(logger)
-  const contextMiddleware = createContextMiddleware(appContainer)
+  const contextMiddleware = createContextMiddleware(container)
 
   server.disable('x-powered-by')
 

package/starter/infra/postgresql-knex/.env.jsonc

@@ -0,0 +1,5 @@
+{
+  // DATABASE
+  /// Application PostgreSQL database connection props
+  "DB_CONNECTION_STRING": "postgres://{{PROJECT_NAME}}_docker:{{PROJECT_NAME}}_docker@localhost:5432/postgres"
+}