Feat/config scope json support

package.json

@@ -37,7 +37,8 @@
   "dependencies": {
     "pino": "^8.17.1",
     "undici": "^6.0.1",
-    "undici-retry": "^5.0.2"
+    "undici-retry": "^5.0.2",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
     "@types/node": "^20.10.4",
@@ -53,7 +54,6 @@
     "prettier": "^3.1.1",
     "typescript": "^5.3.3",
     "vitest": "^0.34.6",
-    "zod": "^3.22.4",
     "vite": "4.5.0"
   }
 }

src/config/ConfigScope.spec.ts

@@ -1,3 +1,6 @@
+import { expect } from 'vitest'
+import { z } from 'zod'
+
 import { ConfigScope } from './ConfigScope'
 import { ensureClosingSlashTransformer } from './configTransformers'
 import type { EnvValueValidator } from './configTypes'
@@ -600,6 +603,201 @@ describe('ConfigScope', () => {
     })
   })
 
+  describe('getMandatoryJsonObject', () => {
+    it('empty env value throws error', () => {
+      const configScope = new ConfigScope()
+      const schema = z.object({ a: z.string() })
+
+      expect(() => configScope.getMandatoryJsonObject('emptyObjectValue', schema)).toThrow(
+        /Missing mandatory configuration parameter/,
+      )
+    })
+
+    it('env value not meeting schema throws error', () => {
+      process.env.objectValue = JSON.stringify({ b: 1 })
+      const configScope = new ConfigScope()
+
+      const schema = z.object({ a: z.string() })
+      expect(() => configScope.getMandatoryJsonObject('objectValue', schema)).toThrow(
+        /Configuration parameter objectValue must be a valid JSON meeting the given schema, but was {"b":1}/,
+      )
+    })
+
+    it('transform simple objects', () => {
+      process.env.objectValue = JSON.stringify({ a: 'a', b: 1 })
+      const configScope = new ConfigScope()
+
+      const schema = z.object({
+        a: z.string(),
+        b: z.number(),
+      })
+      const result = configScope.getMandatoryJsonObject('objectValue', schema)
+
+      expect(result).toEqual({ a: 'a', b: 1 })
+    })
+
+    it('transform array', () => {
+      process.env.objectValue = JSON.stringify([
+        { a: 'a1', b: 1 },
+        { a: 'a2', b: 2 },
+      ])
+      const configScope = new ConfigScope()
+
+      const schema = z.array(
+        z.object({
+          a: z.string(),
+          b: z.number(),
+        }),
+      )
+      const result = configScope.getMandatoryJsonObject('objectValue', schema)
+
+      expect(result).toEqual([
+        { a: 'a1', b: 1 },
+        { a: 'a2', b: 2 },
+      ])
+    })
+  })
+
+  describe('getOptionalJsonObject', () => {
+    it('empty env value returns default', () => {
+      const configScope = new ConfigScope()
+      const schema = z.object({ a: z.string() })
+
+      const result = configScope.getOptionalJsonObject('emptyObjectValue', schema, { a: 'a' })
+      expect(result).toEqual({ a: 'a' })
+    })
+
+    it('env value not meeting schema throws error', () => {
+      process.env.objectValue = JSON.stringify({ b: 1 })
+      const configScope = new ConfigScope()
+
+      const schema = z.object({ a: z.string() })
+
+      expect(() => configScope.getOptionalJsonObject('objectValue', schema, { a: 'a' })).toThrow(
+        /Configuration parameter objectValue must be a valid JSON meeting the given schema, but was {"b":1}/,
+      )
+    })
+
+    it('transform simple objects', () => {
+      process.env.objectValue = JSON.stringify({ a: 'a', b: 1 })
+      const configScope = new ConfigScope()
+
+      const schema = z.object({
+        a: z.string(),
+        b: z.number(),
+      })
+      const result = configScope.getOptionalJsonObject('objectValue', schema, { a: 'fake', b: -1 })
+
+      expect(result).toMatchObject({ a: 'a', b: 1 })
+    })
+
+    it('transform array', () => {
+      process.env.objectValue = JSON.stringify([
+        { a: 'a1', b: 1 },
+        { a: 'a2', b: 2 },
+      ])
+      const configScope = new ConfigScope()
+
+      const schema = z.array(
+        z.object({
+          a: z.string(),
+          b: z.number(),
+        }),
+      )
+      const result = configScope.getOptionalJsonObject('objectValue', schema, [
+        { a: 'fake', b: -1 },
+      ])
+
+      expect(result).toMatchObject([
+        { a: 'a1', b: 1 },
+        { a: 'a2', b: 2 },
+      ])
+    })
+  })
+
+  describe('getOptionalNullableJsonObject', () => {
+    it('empty env value returns default', () => {
+      const configScope = new ConfigScope()
+      const schema = z.object({ a: z.string() })
+
+      const result = configScope.getOptionalNullableJsonObject(
+        'emptyObjectValue',
+        schema,
+        undefined,
+      )
+      expect(result).toEqual(undefined)
+
+      const result2 = configScope.getOptionalNullableJsonObject('emptyObjectValue', schema, null)
+      expect(result2).toEqual(null)
+
+      const result3 = configScope.getOptionalNullableJsonObject('emptyObjectValue', schema, {
+        a: 'a',
+      })
+      expect(result3).toEqual({ a: 'a' })
+    })
+
+    it('env value not meeting schema returns default', () => {
+      process.env.objectValue = JSON.stringify({ b: 1 })
+      const configScope = new ConfigScope()
+      const schema = z.object({ a: z.string() })
+
+      expect(() =>
+        configScope.getOptionalNullableJsonObject('objectValue', schema, { a: 'a' }),
+      ).toThrow(
+        /Configuration parameter objectValue must be a valid JSON meeting the given schema, but was {"b":1}/,
+      )
+
+      expect(() => configScope.getOptionalNullableJsonObject('objectValue', schema, null)).toThrow(
+        /Configuration parameter objectValue must be a valid JSON meeting the given schema, but was {"b":1}/,
+      )
+
+      expect(() =>
+        configScope.getOptionalNullableJsonObject('objectValue', schema, undefined),
+      ).toThrow(
+        /Configuration parameter objectValue must be a valid JSON meeting the given schema, but was {"b":1}/,
+      )
+    })
+
+    it('transform simple objects', () => {
+      process.env.objectValue = JSON.stringify({ a: 'a', b: 1 })
+      const configScope = new ConfigScope()
+
+      const schema = z.object({
+        a: z.string(),
+        b: z.number(),
+      })
+      const result = configScope.getOptionalNullableJsonObject('objectValue', schema, {
+        a: 'fake',
+        b: -1,
+      })
+
+      expect(result).toMatchObject({ a: 'a', b: 1 })
+    })
+
+    it('transform array', () => {
+      process.env.objectValue = JSON.stringify([
+        { a: 'a1', b: 1 },
+        { a: 'a2', b: 2 },
+      ])
+      const configScope = new ConfigScope()
+
+      const schema = z.array(
+        z.object({
+          a: z.string(),
+          b: z.number(),
+        }),
+      )
+      const result = configScope.getOptionalNullableJsonObject('objectValue', schema, [
+        { a: 'fake', b: -1 },
+      ])
+
+      expect(result).toMatchObject([
+        { a: 'a1', b: 1 },
+        { a: 'a2', b: 2 },
+      ])
+    })
+  })
+
   describe('updateEnv', () => {
     it('updates cached env', () => {
       process.env.value = '123'

src/config/ConfigScope.ts

@@ -1,3 +1,5 @@
+import type { ZodSchema } from 'zod'
+
 import { InternalError } from '../errors/InternalError'
 
 import type { EnvValueValidator } from './configTypes'
@@ -180,6 +182,36 @@ export class ConfigScope {
     return rawValue === 'true'
   }
 
+  getMandatoryJsonObject<T extends object>(param: string, schema: ZodSchema<T>): T {
+    const rawValue = this.getMandatory(param)
+    return this.validateSchema(
+      JSON.parse(rawValue),
+      schema,
+      `Configuration parameter ${param} must be a valid JSON meeting the given schema, but was ${rawValue}`,
+    )
+  }
+
+  getOptionalNullableJsonObject<T extends object, Z extends T | null | undefined>(
+    param: string,
+    schema: ZodSchema<T>,
+    defaultValue: Z,
+  ): Z {
+    const rawValue = this.getOptionalNullable(param, undefined)
+    if (!rawValue) {
+      return defaultValue
+    }
+
+    return this.validateSchema(
+      JSON.parse(rawValue),
+      schema,
+      `Configuration parameter ${param} must be a valid JSON meeting the given schema, but was ${rawValue}`,
+    ) as Z
+  }
+
+  getOptionalJsonObject<T extends object>(param: string, schema: ZodSchema<T>, defaultValue: T): T {
+    return this.getOptionalNullableJsonObject(param, schema, defaultValue)
+  }
+
   isProduction(): boolean {
     return this.env.NODE_ENV === 'production'
   }
@@ -191,6 +223,23 @@ export class ConfigScope {
   isTest(): boolean {
     return this.env.NODE_ENV === 'test'
   }
+
+  private validateSchema<T extends object>(
+    value: unknown,
+    schema: ZodSchema<T>,
+    errorMessage: string,
+  ): T {
+    const parsedValue = schema.safeParse(value)
+    if (!parsedValue.success) {
+      throw new InternalError({
+        message: errorMessage,
+        errorCode: 'CONFIGURATION_ERROR',
+        details: parsedValue.error,
+      })
+    }
+
+    return parsedValue.data
+  }
 }
 
 export function validateOneOf<const T>(