core-services-sdk 1.3.75 → 1.3.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.75",
+  "version": "1.3.76",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",

package/src/env/env-validation.js

@@ -307,3 +307,57 @@ export function formatEnvReport(report) {
     report.success ? 'All variables are valid.' : 'Some variables are invalid.',
   ].join('\n')
 }
+
+/**
+ * Validates environment variables end-to-end and builds a full report.
+ *
+ * This function:
+ * - validates values using the schema definition
+ * - builds a structured report (including masking secrets)
+ * - formats a printable output
+ *
+ * @param {Record<string, Object>} definition
+ *   Environment schema definition.
+ *
+ * @param {Record<string, any>} values
+ *   Raw environment values (e.g. process.env).
+ *
+ * @param {{
+ *   mask?: (value: any) => string
+ * }} [options]
+ *
+ * @returns {{
+ *   success: boolean,
+ *   validation: {
+ *     success: boolean,
+ *     data?: Record<string, any>,
+ *     summary?: Record<string, string[]>
+ *   },
+ *   report: {
+ *     success: boolean,
+ *     params: Array<{
+ *       key: string,
+ *       value: any,
+ *       displayValue: string,
+ *       secret: boolean,
+ *       valid: boolean,
+ *       errors?: string[]
+ *     }>
+ *   },
+ *   output: string
+ * }}
+ */
+export function validateAndReportEnv(definition, values, options = {}) {
+  const { mask } = options
+
+  const validation = validateEnv(definition, values)
+  const report = buildEnvReport(definition, values, validation, mask)
+  const output = formatEnvReport(report)
+
+  return {
+    success: validation.success,
+    validation,
+    report,
+    output,
+  }
+}

package/tests/env/build-and-print-demo.js

@@ -0,0 +1,139 @@
+// @ts-nocheck
+import { validateAndReportEnv } 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 result = validateAndReportEnv(definition, scenario.values, { mask })
+
+  console.log(result.output)
+}

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

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest'
+import { validateAndReportEnv } from '../../src/env/env-validation.js'
+
+describe('validateAndReportEnv', () => {
+  const schema = {
+    FOO: {
+      type: 'string',
+      required: true,
+    },
+    BAR: {
+      type: 'number',
+      required: true,
+      int: true,
+    },
+    SECRET: {
+      type: 'string',
+      required: true,
+      secret: true,
+    },
+    OPTIONAL: {
+      type: 'string',
+      required: false,
+      default: 'hello',
+    },
+  }
+
+  it('returns success result when all variables are valid', () => {
+    const env = {
+      FOO: 'test',
+      BAR: '42',
+      SECRET: 'super-secret',
+    }
+
+    const result = validateAndReportEnv(schema, env)
+
+    expect(result.success).toBe(true)
+
+    expect(result.validation.success).toBe(true)
+    expect(result.validation.data).toEqual({
+      FOO: 'test',
+      BAR: 42,
+      SECRET: 'super-secret',
+      OPTIONAL: 'hello',
+    })
+
+    expect(result.report.success).toBe(true)
+    expect(result.report.params).toHaveLength(4)
+
+    expect(result.output).toContain('Environment variables')
+    expect(result.output).toContain('OK')
+  })
+
+  it('returns failure result when required variable is missing', () => {
+    const env = {
+      BAR: '10',
+      SECRET: 'x',
+    }
+
+    const result = validateAndReportEnv(schema, env)
+
+    expect(result.success).toBe(false)
+
+    expect(result.validation.success).toBe(false)
+    expect(result.validation.summary).toHaveProperty('FOO')
+
+    const fooParam = result.report.params.find((p) => p.key === 'FOO')
+    expect(fooParam.valid).toBe(false)
+    expect(fooParam.errors.length).toBeGreaterThan(0)
+
+    expect(result.output).toContain('ERROR')
+    expect(result.output).toContain('FOO')
+  })
+
+  it('masks secret values in output', () => {
+    const env = {
+      FOO: 'test',
+      BAR: '1',
+      SECRET: 'dont-print-me',
+    }
+
+    const mask = () => '***'
+
+    const result = validateAndReportEnv(schema, env, { mask })
+
+    const secretParam = result.report.params.find((p) => p.key === 'SECRET')
+
+    expect(secretParam.displayValue).toBe('***')
+    expect(result.output).toContain('***')
+    expect(result.output).not.toContain('dont-print-me')
+  })
+
+  it('coerces and validates types correctly', () => {
+    const env = {
+      FOO: 'abc',
+      BAR: '5',
+      SECRET: 'x',
+    }
+
+    const result = validateAndReportEnv(schema, env)
+
+    expect(result.success).toBe(true)
+    expect(result.validation.data.BAR).toBe(5)
+  })
+})

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

@@ -155,3 +155,68 @@ export function formatEnvReport(report: {
     errors?: string[]
   }>
 }): string
+/**
+ * Validates environment variables end-to-end and builds a full report.
+ *
+ * This function:
+ * - validates values using the schema definition
+ * - builds a structured report (including masking secrets)
+ * - formats a printable output
+ *
+ * @param {Record<string, Object>} definition
+ *   Environment schema definition.
+ *
+ * @param {Record<string, any>} values
+ *   Raw environment values (e.g. process.env).
+ *
+ * @param {{
+ *   mask?: (value: any) => string
+ * }} [options]
+ *
+ * @returns {{
+ *   success: boolean,
+ *   validation: {
+ *     success: boolean,
+ *     data?: Record<string, any>,
+ *     summary?: Record<string, string[]>
+ *   },
+ *   report: {
+ *     success: boolean,
+ *     params: Array<{
+ *       key: string,
+ *       value: any,
+ *       displayValue: string,
+ *       secret: boolean,
+ *       valid: boolean,
+ *       errors?: string[]
+ *     }>
+ *   },
+ *   output: string
+ * }}
+ */
+export function validateAndReportEnv(
+  definition: Record<string, any>,
+  values: Record<string, any>,
+  options?: {
+    mask?: (value: any) => string
+  },
+): {
+  success: boolean
+  validation: {
+    success: boolean
+    data?: Record<string, any>
+    summary?: Record<string, string[]>
+  }
+  report: {
+    success: boolean
+    params: Array<{
+      key: string
+      value: any
+      displayValue: string
+      secret: boolean
+      valid: boolean
+      errors?: string[]
+    }>
+  }
+  output: string
+}