core-services-sdk 1.3.73 → 1.3.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.73",
+  "version": "1.3.75",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",
@@ -45,7 +45,8 @@
     "pino": "^9.7.0",
     "ulid": "^3.0.1",
     "uuid": "^11.1.0",
-    "xml2js": "^0.6.2"
+    "xml2js": "^0.6.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^3.2.4",

package/src/env/env-validation.js

@@ -0,0 +1,309 @@
+import { z } from 'zod'
+import { mask as defaultMask } from '../util/mask-sensitive.js'
+
+/**
+ * Converts a single field definition into a Zod schema.
+ *
+ * @param {Object} def
+ * @param {'string'|'number'|'boolean'} def.type
+ *
+ * @param {boolean} [def.required]
+ *   Whether the value is required. Defaults to false.
+ *
+ * @param {*} [def.default]
+ *   Default value if the variable is missing.
+ *
+ * @param {boolean} [def.secret]
+ *   Marks the variable as secret (used only for masking/logging).
+ *
+ * // string options
+ * @param {number} [def.minLength]
+ * @param {number} [def.maxLength]
+ * @param {string} [def.pattern]
+ * @param {string[]} [def.enum]
+ * @param {'email'|'url'} [def.format]
+ *
+ * // number options
+ * @param {number} [def.min]
+ * @param {number} [def.max]
+ * @param {boolean} [def.int]
+ * @param {boolean} [def.positive]
+ * @param {boolean} [def.negative]
+ *
+ * @returns {import('zod').ZodTypeAny}
+ */
+export function defToZod(def) {
+  let schema
+
+  switch (def.type) {
+    case 'string': {
+      schema = z.string()
+
+      if (def.minLength !== undefined) {
+        schema = schema.min(def.minLength)
+      }
+
+      if (def.maxLength !== undefined) {
+        schema = schema.max(def.maxLength)
+      }
+
+      if (def.pattern) {
+        schema = schema.regex(new RegExp(def.pattern))
+      }
+
+      if (def.enum) {
+        schema = z.enum(def.enum)
+      }
+
+      if (def.format === 'email') {
+        schema = schema.email()
+      }
+
+      if (def.format === 'url') {
+        schema = schema.url()
+      }
+
+      break
+    }
+
+    case 'number': {
+      schema = z.coerce.number()
+
+      if (def.int) {
+        schema = schema.int()
+      }
+
+      if (def.min !== undefined) {
+        schema = schema.min(def.min)
+      }
+
+      if (def.max !== undefined) {
+        schema = schema.max(def.max)
+      }
+
+      if (def.positive) {
+        schema = schema.positive()
+      }
+
+      if (def.negative) {
+        schema = schema.negative()
+      }
+
+      break
+    }
+
+    case 'boolean': {
+      schema = z.preprocess((val) => {
+        if (val === undefined) {
+          return val
+        }
+
+        if (typeof val === 'boolean') {
+          return val
+        }
+
+        if (typeof val === 'string') {
+          const normalized = val.toLowerCase().trim()
+
+          if (normalized === 'true') {
+            return true
+          }
+          if (normalized === 'false') {
+            return false
+          }
+          if (normalized === '1') {
+            return true
+          }
+          if (normalized === '0') {
+            return false
+          }
+        }
+
+        return val
+      }, z.boolean())
+
+      break
+    }
+
+    default: {
+      throw new Error(`Unsupported type: ${def.type}`)
+    }
+  }
+
+  if (def.default !== undefined) {
+    schema = schema.default(def.default)
+  }
+
+  if (!def.required) {
+    schema = schema.optional()
+  }
+
+  return schema
+}
+
+/**
+ * Builds a Zod object schema from a JSON definition map.
+ *
+ * @param {Record<string, Object>} definition
+ *   Map of environment variable names to field definitions.
+ *
+ * @returns {import('zod').ZodObject<any>}
+ */
+export function createZodSchema(definition) {
+  const shape = Object.entries(definition).reduce((shape, [key, def]) => {
+    return {
+      ...shape,
+      [key]: defToZod(def),
+    }
+  }, {})
+
+  return z.object(shape)
+}
+
+/**
+ * Validates values using a JSON definition and Zod.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ *
+ * @returns {{
+ *   success: true,
+ *   data: Record<string, any>
+ * } | {
+ *   success: false,
+ *   summary: Record<string, string[]>
+ * }}
+ */
+export function validateEnv(definition, values) {
+  const schema = createZodSchema(definition)
+  const result = schema.safeParse(values)
+
+  if (result.success) {
+    return {
+      success: true,
+      data: result.data,
+    }
+  }
+
+  const summary = result.error.issues.reduce((acc, issue) => {
+    const key = issue.path[0] || 'root'
+    acc[key] = acc[key] || []
+    acc[key].push(issue.message)
+    return acc
+  }, {})
+
+  return {
+    success: false,
+    summary,
+  }
+}
+
+/**
+ * Builds a structured environment validation report.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ *   Raw input values (e.g. process.env)
+ *
+ * @param {{
+ *   success: boolean,
+ *   data?: Record<string, any>,
+ *   summary?: Record<string, string[]>
+ * }} validationResult
+ *
+ * @param {(value: any) => string} mask
+ *
+ * @returns {{
+ *   success: boolean,
+ *   params: Array<{
+ *     key: string,
+ *     value: any,
+ *     displayValue: string,
+ *     secret: boolean,
+ *     valid: boolean,
+ *     errors?: string[]
+ *   }>
+ * }}
+ */
+export function buildEnvReport(definition, values, validationResult, mask) {
+  const maskValue = typeof mask === 'function' ? mask : defaultMask
+
+  const params = Object.keys(definition).map((key) => {
+    const def = definition[key]
+    const isSecret = Boolean(def.secret)
+
+    // value precedence:
+    // 1. validated & parsed value
+    // 2. raw input value
+    const rawValue = values[key]
+    const value = validationResult.success
+      ? validationResult.data[key]
+      : rawValue
+
+    const displayValue = isSecret ? maskValue(value) : String(value)
+
+    const errors = validationResult.success
+      ? undefined
+      : validationResult.summary?.[key]
+
+    return {
+      key,
+      value,
+      displayValue,
+      secret: isSecret,
+      valid: !errors,
+      errors,
+    }
+  })
+
+  return {
+    success: validationResult.success,
+    params,
+  }
+}
+
+/**
+ * Formats an environment validation report into a readable table.
+ *
+ * @param {{
+ *   success: boolean,
+ *   params: Array<{
+ *     key: string,
+ *     displayValue: string,
+ *     secret: boolean,
+ *     valid: boolean,
+ *     errors?: string[]
+ *   }>
+ * }} report
+ *
+ * @returns {string}
+ */
+export function formatEnvReport(report) {
+  const headers = ['STATUS', 'KEY', 'VALUE', 'NOTES']
+
+  const rows = report.params.map((p) => {
+    const status = p.valid ? 'OK' : 'ERROR'
+    const notes = p.errors?.join('; ') || ''
+
+    return [status, p.key, p.displayValue, notes]
+  })
+
+  const allRows = [headers, ...rows]
+
+  const colWidths = headers.map((_, i) =>
+    Math.max(...allRows.map((row) => row[i].length)),
+  )
+
+  const formatRow = (row) =>
+    row.map((cell, i) => cell.padEnd(colWidths[i])).join('  ')
+
+  const lines = allRows.map(formatRow)
+
+  return [
+    'Environment variables',
+    '',
+    ...lines,
+    '',
+    report.success ? 'All variables are valid.' : 'Some variables are invalid.',
+  ].join('\n')
+}

package/src/index.js

@@ -11,3 +11,5 @@ export * from './templates/index.js'
 export * from './util/index.js'
 export * from './instant-messages/index.js'
 export * from './postgresql/index.js'
+export * from './env/env-validation.js'
+export * from './json/load-json.js'

package/src/json/load-json.js

@@ -0,0 +1,15 @@
+import fs from 'node:fs'
+
+/**
+ * Loads and parses a JSON file relative to a module URL.
+ *
+ * @param {string|URL} moduleUrl
+ * @param {string} relativePath
+ * @returns {any}
+ */
+export function loadJson(moduleUrl, relativePath) {
+  const fileUrl = new URL(relativePath, moduleUrl)
+  const raw = fs.readFileSync(fileUrl, 'utf8')
+
+  return JSON.parse(raw)
+}

package/tests/env/build-env-report.test.js

@@ -0,0 +1,132 @@
+// @ts-nocheck
+import { describe, it, expect } from 'vitest'
+import { buildEnvReport } from '../../src/env/env-validation.js'
+
+const mask = (v) => `***${String(v).slice(-2)}`
+
+describe('buildEnvReport', () => {
+  it('builds report for successful validation', () => {
+    const definition = {
+      PORT: { type: 'number' },
+      API_KEY: { type: 'string', secret: true },
+      DEBUG: { type: 'boolean' },
+    }
+
+    const values = {
+      PORT: 3000,
+      API_KEY: 'secret123',
+      DEBUG: false,
+    }
+
+    const validationResult = {
+      success: true,
+      data: values,
+    }
+
+    const report = buildEnvReport(definition, values, validationResult, mask)
+
+    expect(report.success).toBe(true)
+    expect(report.params).toHaveLength(3)
+
+    const apiKey = report.params.find((p) => p.key === 'API_KEY')
+    expect(apiKey.secret).toBe(true)
+    expect(apiKey.displayValue).toBe('***23')
+    expect(apiKey.valid).toBe(true)
+  })
+
+  it('builds report for failed validation with errors', () => {
+    const definition = {
+      PORT: { type: 'number' },
+      DEBUG: { type: 'boolean' },
+    }
+
+    const values = {
+      PORT: 0,
+      DEBUG: false,
+    }
+
+    const validationResult = {
+      success: false,
+      summary: {
+        PORT: ['Invalid number'],
+      },
+    }
+
+    const report = buildEnvReport(definition, values, validationResult, mask)
+
+    expect(report.success).toBe(false)
+
+    const port = report.params.find((p) => p.key === 'PORT')
+    expect(port.valid).toBe(false)
+    expect(port.errors).toEqual(['Invalid number'])
+    expect(port.displayValue).toBe('0')
+  })
+
+  it('marks parameter as invalid when errors exist', () => {
+    const definition = {
+      PORT: { type: 'number' },
+    }
+
+    const values = {
+      PORT: 'x',
+    }
+
+    const validationResult = {
+      success: false,
+      summary: {
+        PORT: ['Invalid number'],
+      },
+    }
+
+    const report = buildEnvReport(definition, values, validationResult, mask)
+
+    const port = report.params[0]
+    expect(port.valid).toBe(false)
+    expect(port.errors).toEqual(['Invalid number'])
+  })
+
+  it('uses defaultMask when mask is not a function', () => {
+    const definition = {
+      API_KEY: { type: 'string', secret: true },
+    }
+
+    const values = {
+      API_KEY: 'secret123',
+    }
+
+    const validationResult = {
+      success: true,
+      data: values,
+    }
+
+    const report = buildEnvReport(definition, values, validationResult, null)
+
+    const apiKey = report.params[0]
+    expect(apiKey.secret).toBe(true)
+    expect(typeof apiKey.displayValue).toBe('string')
+    expect(apiKey.displayValue).not.toBe('secret123')
+  })
+
+  it('keeps params order as definition order', () => {
+    const definition = {
+      A: { type: 'string' },
+      B: { type: 'string' },
+      C: { type: 'string' },
+    }
+
+    const values = {
+      A: '1',
+      B: '2',
+      C: '3',
+    }
+
+    const validationResult = {
+      success: true,
+      data: values,
+    }
+
+    const report = buildEnvReport(definition, values, validationResult, mask)
+
+    expect(report.params.map((p) => p.key)).toEqual(['A', 'B', 'C'])
+  })
+})

package/tests/env/create-zod-schema.test.js

@@ -0,0 +1,175 @@
+import { describe, it, expect } from 'vitest'
+import { z } from 'zod'
+
+import { createZodSchema } from '../../src/env/env-validation.js'
+
+describe('createZodSchema', () => {
+  it('creates a Zod object schema from definition', () => {
+    const definition = {
+      PORT: { type: 'number', required: true },
+      DEBUG: { type: 'boolean' },
+    }
+
+    const schema = createZodSchema(definition)
+
+    expect(schema).toBeInstanceOf(z.ZodObject)
+  })
+
+  it('parses valid values successfully', () => {
+    const definition = {
+      PORT: { type: 'number', required: true, min: 1 },
+      DEBUG: { type: 'boolean', default: false },
+    }
+
+    const schema = createZodSchema(definition)
+
+    const result = schema.parse({
+      PORT: '3000',
+    })
+
+    expect(result).toEqual({
+      PORT: 3000,
+      DEBUG: false,
+    })
+  })
+
+  it('throws error when required field is missing', () => {
+    const definition = {
+      PORT: { type: 'number', required: true },
+      DEBUG: { type: 'boolean' },
+    }
+
+    const schema = createZodSchema(definition)
+
+    expect(() => {
+      schema.parse({
+        DEBUG: true,
+      })
+    }).toThrow()
+  })
+
+  it('allows optional fields to be missing', () => {
+    const definition = {
+      PORT: { type: 'number', required: true },
+      DEBUG: { type: 'boolean' },
+    }
+
+    const schema = createZodSchema(definition)
+
+    const result = schema.parse({
+      PORT: 8080,
+    })
+
+    expect(result).toEqual({
+      PORT: 8080,
+    })
+  })
+
+  it('applies string constraints correctly', () => {
+    const definition = {
+      NODE_ENV: {
+        type: 'string',
+        required: true,
+        enum: ['development', 'production'],
+      },
+    }
+
+    const schema = createZodSchema(definition)
+
+    expect(() => {
+      schema.parse({ NODE_ENV: 'prod' })
+    }).toThrow()
+
+    const result = schema.parse({ NODE_ENV: 'production' })
+    expect(result.NODE_ENV).toBe('production')
+  })
+
+  it('applies number constraints correctly', () => {
+    const definition = {
+      PORT: {
+        type: 'number',
+        required: true,
+        int: true,
+        min: 1,
+        max: 65535,
+      },
+    }
+
+    const schema = createZodSchema(definition)
+
+    expect(() => {
+      schema.parse({ PORT: 0 })
+    }).toThrow()
+
+    expect(() => {
+      schema.parse({ PORT: 70000 })
+    }).toThrow()
+
+    const result = schema.parse({ PORT: '3000' })
+    expect(result.PORT).toBe(3000)
+  })
+
+  it('validates string formats', () => {
+    const definition = {
+      DATABASE_URL: {
+        type: 'string',
+        required: true,
+        format: 'url',
+      },
+    }
+
+    const schema = createZodSchema(definition)
+
+    expect(() => {
+      schema.parse({ DATABASE_URL: 'not-a-url' })
+    }).toThrow()
+
+    const result = schema.parse({
+      DATABASE_URL: 'https://example.com',
+    })
+
+    expect(result.DATABASE_URL).toBe('https://example.com')
+  })
+
+  it('collects multiple validation errors', () => {
+    const definition = {
+      PORT: { type: 'number', required: true, min: 1 },
+      NODE_ENV: {
+        type: 'string',
+        required: true,
+        enum: ['development', 'production'],
+      },
+    }
+
+    const schema = createZodSchema(definition)
+
+    try {
+      schema.parse({
+        PORT: 0,
+        NODE_ENV: 'prod',
+      })
+    } catch (error) {
+      // @ts-ignore
+      expect(error.issues).toHaveLength(2)
+
+      // @ts-ignore
+      const paths = error.issues.map((i) => i.path[0])
+      expect(paths).toContain('PORT')
+      expect(paths).toContain('NODE_ENV')
+    }
+  })
+
+  it('coerces boolean values correctly', () => {
+    const definition = {
+      DEBUG: { type: 'boolean', required: true },
+    }
+
+    const schema = createZodSchema(definition)
+
+    const result = schema.parse({
+      DEBUG: 'true',
+    })
+
+    expect(result.DEBUG).toBe(true)
+  })
+})

package/tests/env/env-demo.js

@@ -0,0 +1,154 @@
+// @ts-nocheck
+import {
+  validateEnv,
+  buildEnvReport,
+  formatEnvReport,
+} from '../../src/env/env-validation.js'
+
+// mask example
+const mask = (value) => {
+  if (value == null) {
+    return '******'
+  }
+
+  const str = String(value)
+  if (str.length <= 4) {
+    return '****'
+  }
+
+  return `${str.slice(0, 2)}****${str.slice(-2)}`
+}
+
+/**
+ * Definitions
+ */
+const definition = {
+  PORT: {
+    type: 'number',
+    required: true,
+    int: true,
+    min: 1,
+    max: 65535,
+  },
+
+  TIMEOUT: {
+    type: 'number',
+    min: 100,
+    max: 10000,
+  },
+
+  RETRIES: {
+    type: 'number',
+    int: true,
+    min: 0,
+  },
+
+  DEBUG: {
+    type: 'boolean',
+  },
+
+  MODE: {
+    type: 'string',
+    enum: ['development', 'production'],
+  },
+
+  API_KEY: {
+    type: 'string',
+    secret: true,
+  },
+}
+
+/**
+ * Values scenarios
+ */
+const scenarios = [
+  {
+    title: '✅ All valid values',
+    values: {
+      PORT: 3000,
+      TIMEOUT: 500,
+      RETRIES: 3,
+      DEBUG: false,
+      MODE: 'development',
+      API_KEY: 'secret123',
+    },
+  },
+
+  {
+    title: '❌ Number too small (PORT)',
+    values: {
+      PORT: 0,
+      TIMEOUT: 500,
+      RETRIES: 3,
+      DEBUG: true,
+      MODE: 'production',
+      API_KEY: 'secret123',
+    },
+  },
+
+  {
+    title: '❌ Number too large (TIMEOUT)',
+    values: {
+      PORT: 3000,
+      TIMEOUT: 20000,
+      RETRIES: 1,
+      DEBUG: false,
+      MODE: 'development',
+      API_KEY: 'secret123',
+    },
+  },
+
+  {
+    title: '❌ Invalid number (string)',
+    values: {
+      PORT: 'abc',
+      TIMEOUT: 500,
+      RETRIES: 2,
+      DEBUG: false,
+      MODE: 'development',
+      API_KEY: 'secret123',
+    },
+  },
+
+  {
+    title: '❌ Invalid enum (MODE)',
+    values: {
+      PORT: 3000,
+      TIMEOUT: 500,
+      RETRIES: 2,
+      DEBUG: false,
+      MODE: 'prod',
+      API_KEY: 'secret123',
+    },
+  },
+
+  {
+    title: '✅ Boolean coercion + missing secret',
+    values: {
+      PORT: '8080',
+      TIMEOUT: '1000',
+      RETRIES: '0',
+      DEBUG: 'true',
+      MODE: 'production',
+    },
+  },
+]
+
+/**
+ * Run scenarios
+ */
+for (const scenario of scenarios) {
+  console.log('\n===================================================')
+  console.log(scenario.title)
+  console.log('===================================================\n')
+
+  const validationResult = validateEnv(definition, scenario.values)
+  const report = buildEnvReport(
+    definition,
+    scenario.values,
+    validationResult,
+    mask,
+  )
+
+  console.log(formatEnvReport(report))
+}

package/tests/env/validate-env.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest'
+import { validateEnv } from '../../src/env/env-validation.js'
+
+describe('validateEnv', () => {
+  it('returns success result when values are valid', () => {
+    const definition = {
+      PORT: { type: 'number', required: true, min: 1 },
+      DEBUG: { type: 'boolean', default: false },
+    }
+
+    const values = {
+      PORT: '3000',
+    }
+
+    const result = validateEnv(definition, values)
+
+    expect(result.success).toBe(true)
+    // @ts-ignore
+    expect(result.data).toEqual({
+      PORT: 3000,
+      DEBUG: false,
+    })
+  })
+
+  it('returns error result with summary when required field is missing', () => {
+    const definition = {
+      PORT: { type: 'number', required: true },
+      DEBUG: { type: 'boolean' },
+    }
+
+    const values = {
+      DEBUG: true,
+    }
+
+    const result = validateEnv(definition, values)
+
+    expect(result.success).toBe(false)
+    // @ts-ignore
+    expect(result.summary).toBeDefined()
+    // @ts-ignore
+    expect(result.summary).toHaveProperty('PORT')
+    // @ts-ignore
+    expect(result.summary.PORT.length).toBeGreaterThan(0)
+  })
+
+  it('returns summary with errors for the field when value is invalid', () => {
+    const definition = {
+      PORT: {
+        type: 'number',
+        required: true,
+        int: true,
+        min: 10,
+      },
+    }
+
+    const values = {
+      PORT: '5.5',
+    }
+
+    const result = validateEnv(definition, values)
+
+    expect(result.success).toBe(false)
+    // @ts-ignore
+    expect(result.summary).toHaveProperty('PORT')
+    // @ts-ignore
+    expect(result.summary.PORT.length).toBeGreaterThan(0)
+  })
+
+  it('returns summary with errors from multiple fields', () => {
+    const definition = {
+      PORT: { type: 'number', required: true, min: 1 },
+      NODE_ENV: {
+        type: 'string',
+        required: true,
+        enum: ['development', 'production'],
+      },
+    }
+
+    const values = {
+      PORT: 0,
+      NODE_ENV: 'prod',
+    }
+
+    const result = validateEnv(definition, values)
+
+    expect(result.success).toBe(false)
+    // @ts-ignore
+    expect(result.summary).toHaveProperty('PORT')
+    // @ts-ignore
+    expect(result.summary).toHaveProperty('NODE_ENV')
+  })
+
+  it('does not include summary when validation succeeds', () => {
+    const definition = {
+      PORT: { type: 'number', required: true },
+    }
+
+    const values = {
+      PORT: 8080,
+    }
+
+    const result = validateEnv(definition, values)
+
+    expect(result.success).toBe(true)
+    // @ts-ignore
+    expect(result.summary).toBeUndefined()
+  })
+})

package/tests/json/fixtures/invalid.json

@@ -0,0 +1,2 @@
+{
+    "foo": "bar"

package/tests/json/fixtures/valid.json

@@ -0,0 +1,4 @@
+{
+  "foo": "bar",
+  "answer": 42
+}

package/tests/json/load-json.test.js

@@ -0,0 +1,37 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, it, expect } from 'vitest'
+
+import { loadJson } from '../../src/json/load-json.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+describe('loadJson', () => {
+  it('loads and parses a JSON file relative to module URL', () => {
+    const moduleUrl = new URL(`file://${__dirname}/dummy.js`)
+
+    const result = loadJson(moduleUrl, './fixtures/valid.json')
+
+    expect(result).toEqual({
+      foo: 'bar',
+      answer: 42,
+    })
+  })
+
+  it('throws if file does not exist', () => {
+    const moduleUrl = new URL(`file://${__dirname}/dummy.js`)
+
+    expect(() => {
+      loadJson(moduleUrl, './fixtures/missing.json')
+    }).toThrow()
+  })
+
+  it('throws if JSON is invalid', () => {
+    const moduleUrl = new URL(`file://${__dirname}/dummy.js`)
+
+    expect(() => {
+      loadJson(moduleUrl, './fixtures/invalid.json')
+    }).toThrow(SyntaxError)
+  })
+})

package/types/env/env-validation.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Converts a single field definition into a Zod schema.
+ *
+ * @param {Object} def
+ * @param {'string'|'number'|'boolean'} def.type
+ *
+ * @param {boolean} [def.required]
+ *   Whether the value is required. Defaults to false.
+ *
+ * @param {*} [def.default]
+ *   Default value if the variable is missing.
+ *
+ * @param {boolean} [def.secret]
+ *   Marks the variable as secret (used only for masking/logging).
+ *
+ * // string options
+ * @param {number} [def.minLength]
+ * @param {number} [def.maxLength]
+ * @param {string} [def.pattern]
+ * @param {string[]} [def.enum]
+ * @param {'email'|'url'} [def.format]
+ *
+ * // number options
+ * @param {number} [def.min]
+ * @param {number} [def.max]
+ * @param {boolean} [def.int]
+ * @param {boolean} [def.positive]
+ * @param {boolean} [def.negative]
+ *
+ * @returns {import('zod').ZodTypeAny}
+ */
+export function defToZod(def: {
+  type: 'string' | 'number' | 'boolean'
+  required?: boolean
+  default?: any
+  secret?: boolean
+  minLength?: number
+  maxLength?: number
+  pattern?: string
+  enum?: string[]
+  format?: 'email' | 'url'
+  min?: number
+  max?: number
+  int?: boolean
+  positive?: boolean
+  negative?: boolean
+}): import('zod').ZodTypeAny
+/**
+ * Builds a Zod object schema from a JSON definition map.
+ *
+ * @param {Record<string, Object>} definition
+ *   Map of environment variable names to field definitions.
+ *
+ * @returns {import('zod').ZodObject<any>}
+ */
+export function createZodSchema(
+  definition: Record<string, any>,
+): import('zod').ZodObject<any>
+/**
+ * Validates values using a JSON definition and Zod.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ *
+ * @returns {{
+ *   success: true,
+ *   data: Record<string, any>
+ * } | {
+ *   success: false,
+ *   summary: Record<string, string[]>
+ * }}
+ */
+export function validateEnv(
+  definition: Record<string, any>,
+  values: Record<string, any>,
+):
+  | {
+      success: true
+      data: Record<string, any>
+    }
+  | {
+      success: false
+      summary: Record<string, string[]>
+    }
+/**
+ * Builds a structured environment validation report.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ *   Raw input values (e.g. process.env)
+ *
+ * @param {{
+ *   success: boolean,
+ *   data?: Record<string, any>,
+ *   summary?: Record<string, string[]>
+ * }} validationResult
+ *
+ * @param {(value: any) => string} mask
+ *
+ * @returns {{
+ *   success: boolean,
+ *   params: Array<{
+ *     key: string,
+ *     value: any,
+ *     displayValue: string,
+ *     secret: boolean,
+ *     valid: boolean,
+ *     errors?: string[]
+ *   }>
+ * }}
+ */
+export function buildEnvReport(
+  definition: Record<string, any>,
+  values: Record<string, any>,
+  validationResult: {
+    success: boolean
+    data?: Record<string, any>
+    summary?: Record<string, string[]>
+  },
+  mask: (value: any) => string,
+): {
+  success: boolean
+  params: Array<{
+    key: string
+    value: any
+    displayValue: string
+    secret: boolean
+    valid: boolean
+    errors?: string[]
+  }>
+}
+/**
+ * Formats an environment validation report into a readable table.
+ *
+ * @param {{
+ *   success: boolean,
+ *   params: Array<{
+ *     key: string,
+ *     displayValue: string,
+ *     secret: boolean,
+ *     valid: boolean,
+ *     errors?: string[]
+ *   }>
+ * }} report
+ *
+ * @returns {string}
+ */
+export function formatEnvReport(report: {
+  success: boolean
+  params: Array<{
+    key: string
+    displayValue: string
+    secret: boolean
+    valid: boolean
+    errors?: string[]
+  }>
+}): string

package/types/index.d.ts

@@ -11,3 +11,5 @@ export * from './templates/index.js'
 export * from './util/index.js'
 export * from './instant-messages/index.js'
 export * from './postgresql/index.js'
+export * from './env/env-validation.js'
+export * from './json/load-json.js'

package/types/json/load-json.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Loads and parses a JSON file relative to a module URL.
+ *
+ * @param {string|URL} moduleUrl
+ * @param {string} relativePath
+ * @returns {any}
+ */
+export function loadJson(moduleUrl: string | URL, relativePath: string): any

package/types/postgresql/modifiers/apply-order-by.d.ts

@@ -1,17 +1,28 @@
 /**
- * Applies ORDER BY clause.
+ * Applies ORDER BY clause(s) to a Knex query builder.
+ *
+ * Supports a single orderBy object or an array of orderBy objects.
+ * Validates order direction to prevent invalid SQL.
  *
  * @param {Object} params
- * @param {import('knex').Knex.QueryBuilder} params.query
- * @param {{ column: string, direction?: 'asc'|'desc' }} params.orderBy
+ * @param {import('knex').Knex.QueryBuilder} params.query - Knex query builder instance
+ * @param {OrderByItem | OrderByItem[]} params.orderBy - Order by definition(s)
+ * @returns {import('knex').Knex.QueryBuilder} The modified query builder
  */
 export function applyOrderBy({
   query,
   orderBy,
 }: {
   query: import('knex').Knex.QueryBuilder
-  orderBy: {
-    column: string
-    direction?: 'asc' | 'desc'
-  }
-}): import('knex').Knex.QueryBuilder<any, any>
+  orderBy: OrderByItem | OrderByItem[]
+}): import('knex').Knex.QueryBuilder
+export type OrderByItem = {
+  /**
+   * - Column name to order by
+   */
+  column: string
+  /**
+   * - Order direction
+   */
+  direction?: 'asc' | 'desc'
+}