core-services-sdk 1.3.76 → 1.3.78

package/package.json

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

package/src/env/env-validation.js

@@ -361,3 +361,130 @@ export function validateAndReportEnv(definition, values, options = {}) {
     output,
   }
 }
+
+/**
+ * Validates environment variables and prepares
+ * a printable table output.
+ *
+ * No side effects. Does NOT print.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ * @param {{
+ *   mask?: (value: any) => string
+ * }} [options]
+ *
+ * @returns {{
+ *   success: boolean,
+ *   table: string,
+ *   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[]
+ *     }>
+ *   }
+ * }}
+ */
+export function prepareEnvValidation(definition, values, options = {}) {
+  const { mask } = options
+
+  const validation = validateEnv(definition, values)
+  const report = buildEnvReport(definition, values, validation, mask)
+  const table = formatEnvReport(report)
+
+  return {
+    success: validation.success,
+    table,
+    validation,
+    report,
+  }
+}
+
+/**
+ * Builds a console-ready table output for environment validation.
+ *
+ * Always includes all variables.
+ * NOTES column always has a value:
+ * - 'OK' for valid variables
+ * - error message(s) for invalid variables
+ *
+ * @param {{
+ *   params: Array<{
+ *     key: string,
+ *     displayValue: string,
+ *     valid: boolean,
+ *     errors?: string[]
+ *   }>
+ * }} report
+ *
+ * @returns {string}
+ */
+export function buildConsoleOutput(report) {
+  const headers = ['STATUS', 'KEY', 'VALUE', 'NOTES']
+
+  const rows = report.params.map((p) => {
+    const status = p.valid ? 'OK' : 'ERROR'
+    const notes = p.valid ? 'OK' : p.errors?.join('; ') || 'Invalid value'
+
+    return [status, p.key, p.displayValue, notes]
+  })
+
+  const allRows = [headers, ...rows]
+
+  const colWidths = headers.map((_, i) =>
+    Math.max(...allRows.map((row) => String(row[i]).length)),
+  )
+
+  const formatRow = (row) =>
+    row.map((cell, i) => String(cell).padEnd(colWidths[i])).join('  ')
+
+  return [
+    'Environment variables',
+    '',
+    ...allRows.map(formatRow),
+    '',
+    report.params.every((p) => p.valid)
+      ? 'All variables are valid.'
+      : 'Some variables are invalid.',
+  ].join('\n')
+}
+
+/**
+ * Validates environment variables and prepares
+ * a fully printable console output.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ * @param {{
+ *   mask?: (value: any) => string
+ * }} [options]
+ *
+ * @returns {{
+ *   success: boolean,
+ *   output: string,
+ *   report: any
+ * }}
+ */
+export function validateEnvForConsole(definition, values, options = {}) {
+  const { mask } = options
+
+  const validation = validateEnv(definition, values)
+  const report = buildEnvReport(definition, values, validation, mask)
+  const output = buildConsoleOutput(report)
+
+  return {
+    output,
+    report,
+    success: validation.success,
+  }
+}

package/tests/env/env-validation.demo.js

@@ -0,0 +1,86 @@
+// @ts-nocheck
+import { prepareEnvValidation } from '../../src/env/env-validation.js'
+
+const mask = (value) => {
+  if (value == null) {
+    return '******'
+  }
+
+  const str = String(value)
+  if (str.length <= 4) {
+    return '****'
+  }
+
+  return `${str.slice(0, 2)}****${str.slice(-2)}`
+}
+
+const definition = {
+  PORT: {
+    type: 'number',
+    required: true,
+    int: true,
+    min: 1,
+    max: 65535,
+  },
+  TIMEOUT: {
+    type: 'number',
+    min: 100,
+    max: 10000,
+  },
+  DEBUG: {
+    type: 'boolean',
+  },
+  MODE: {
+    type: 'string',
+    enum: ['development', 'production'],
+  },
+  API_KEY: {
+    type: 'string',
+    secret: true,
+  },
+}
+
+const scenarios = [
+  {
+    title: '✅ All valid values',
+    values: {
+      PORT: 3000,
+      TIMEOUT: 500,
+      DEBUG: false,
+      MODE: 'development',
+      API_KEY: 'secret123',
+    },
+  },
+  {
+    title: '❌ Invalid port',
+    values: {
+      PORT: 0,
+      TIMEOUT: 500,
+      MODE: 'production',
+    },
+  },
+  {
+    title: '❌ Invalid enum',
+    values: {
+      PORT: 3000,
+      TIMEOUT: 500,
+      MODE: 'prod',
+      API_KEY: 'secret123',
+    },
+  },
+]
+
+for (const scenario of scenarios) {
+  console.log('\n===================================================')
+  console.log(scenario.title)
+  console.log('===================================================\n')
+
+  const result = prepareEnvValidation(definition, scenario.values, { mask })
+
+  // פה הבחירה שלך מה לעשות עם זה
+  console.log(result.table)
+
+  if (!result.success) {
+    console.log('⚠️  Scenario failed validation')
+  }
+}

package/tests/env/prepare-env-validation.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest'
+import { prepareEnvValidation } from '../../src/env/env-validation.js'
+
+describe('prepareEnvValidation', () => {
+  const mask = () => '****'
+
+  const definition = {
+    PORT: {
+      type: 'number',
+      required: true,
+      int: true,
+      min: 1,
+      max: 65535,
+    },
+    MODE: {
+      type: 'string',
+      enum: ['development', 'production'],
+      required: true,
+    },
+    API_KEY: {
+      type: 'string',
+      secret: true,
+    },
+  }
+
+  it('returns success and a printable table when values are valid', () => {
+    const values = {
+      PORT: '3000',
+      MODE: 'development',
+      API_KEY: 'secret',
+    }
+
+    const result = prepareEnvValidation(definition, values, { mask })
+
+    expect(result.success).toBe(true)
+    expect(result.table).toContain('Environment variables')
+    expect(result.table).toContain('PORT')
+    expect(result.table).toContain('OK')
+    expect(result.table).toContain('****')
+    expect(result.table).not.toContain('secret')
+  })
+
+  it('returns failure and error table when required value is missing', () => {
+    const values = {
+      MODE: 'production',
+    }
+
+    const result = prepareEnvValidation(definition, values)
+
+    expect(result.success).toBe(false)
+    expect(result.validation.success).toBe(false)
+
+    expect(result.table).toContain('ERROR')
+    expect(result.table).toContain('PORT')
+  })
+
+  it('coerces number values correctly', () => {
+    const values = {
+      PORT: '8080',
+      MODE: 'production',
+      API_KEY: 'x',
+    }
+
+    const result = prepareEnvValidation(definition, values)
+
+    expect(result.success).toBe(true)
+    expect(result.validation.data.PORT).toBe(8080)
+  })
+
+  it('returns a table string even on failure', () => {
+    const values = {
+      PORT: 0,
+      MODE: 'development',
+    }
+
+    const result = prepareEnvValidation(definition, values)
+
+    expect(typeof result.table).toBe('string')
+    expect(result.table.length).toBeGreaterThan(0)
+  })
+})

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

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest'
+import { validateEnvForConsole } from '../../src/env/env-validation.js'
+
+describe('validateEnvForConsole', () => {
+  const definition = {
+    PORT: {
+      type: 'number',
+      required: true,
+      int: true,
+      min: 1,
+      max: 65535,
+    },
+    MODE: {
+      type: 'string',
+      enum: ['development', 'production'],
+      required: true,
+    },
+    API_KEY: {
+      type: 'string',
+      secret: true,
+    },
+  }
+
+  const mask = () => '****'
+
+  it('returns a printable table with all variables and OK notes when valid', () => {
+    const values = {
+      PORT: '3000',
+      MODE: 'development',
+      API_KEY: 'secret',
+    }
+
+    const result = validateEnvForConsole(definition, values, { mask })
+
+    expect(result.success).toBe(true)
+    expect(typeof result.output).toBe('string')
+
+    // header
+    expect(result.output).toContain('Environment variables')
+    expect(result.output).toContain('STATUS')
+    expect(result.output).toContain('KEY')
+    expect(result.output).toContain('VALUE')
+    expect(result.output).toContain('NOTES')
+
+    // rows
+    expect(result.output).toContain('PORT')
+    expect(result.output).toContain('MODE')
+    expect(result.output).toContain('API_KEY')
+
+    // notes always present
+    expect(result.output).toContain('OK      PORT')
+    expect(result.output).toContain('OK      MODE')
+    expect(result.output).toContain('OK      API_KEY')
+
+    // masking
+    expect(result.output).toContain('****')
+    expect(result.output).not.toContain('secret')
+  })
+
+  it('returns a printable table with ERROR notes when invalid', () => {
+    const values = {
+      PORT: '0',
+      MODE: 'prod',
+      API_KEY: 'secret',
+    }
+
+    const result = validateEnvForConsole(definition, values, { mask })
+
+    expect(result.success).toBe(false)
+    expect(typeof result.output).toBe('string')
+
+    // all variables still appear
+    expect(result.output).toContain('PORT')
+    expect(result.output).toContain('MODE')
+    expect(result.output).toContain('API_KEY')
+
+    // error rows
+    expect(result.output).toContain('ERROR   PORT')
+    expect(result.output).toContain('ERROR   MODE')
+
+    // notes are NOT empty
+    expect(result.output).toMatch(/PORT\s+0\s+.+/)
+    expect(result.output).toMatch(/MODE\s+prod\s+.+/)
+
+    // summary line
+    expect(result.output).toContain('Some variables are invalid.')
+  })
+
+  it('always sets NOTES to OK for valid variables even if others fail', () => {
+    const values = {
+      PORT: '3000',
+      MODE: 'prod', // invalid
+      API_KEY: 'secret',
+    }
+
+    const result = validateEnvForConsole(definition, values, { mask })
+
+    // PORT and API_KEY are valid → NOTES = OK
+    expect(result.output).toMatch(/OK\s+PORT\s+3000\s+OK/)
+    expect(result.output).toMatch(/OK\s+API_KEY\s+\*\*\*\*\s+OK/)
+
+    // MODE is invalid → NOTES = error message
+    expect(result.output).toMatch(/ERROR\s+MODE\s+prod\s+.+/)
+  })
+
+  it('always returns output even if multiple errors exist', () => {
+    const values = {
+      MODE: 'prod',
+    }
+
+    const result = validateEnvForConsole(definition, values)
+
+    expect(result.success).toBe(false)
+    expect(typeof result.output).toBe('string')
+    expect(result.output.length).toBeGreaterThan(0)
+
+    // all keys still listed
+    expect(result.output).toContain('PORT')
+    expect(result.output).toContain('MODE')
+    expect(result.output).toContain('API_KEY')
+  })
+})

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

@@ -220,3 +220,116 @@ export function validateAndReportEnv(
   }
   output: string
 }
+/**
+ * Validates environment variables and prepares
+ * a printable table output.
+ *
+ * No side effects. Does NOT print.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ * @param {{
+ *   mask?: (value: any) => string
+ * }} [options]
+ *
+ * @returns {{
+ *   success: boolean,
+ *   table: string,
+ *   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[]
+ *     }>
+ *   }
+ * }}
+ */
+export function prepareEnvValidation(
+  definition: Record<string, any>,
+  values: Record<string, any>,
+  options?: {
+    mask?: (value: any) => string
+  },
+): {
+  success: boolean
+  table: string
+  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[]
+    }>
+  }
+}
+/**
+ * Builds a console-ready table output for environment validation.
+ *
+ * Always includes all variables.
+ * NOTES column always has a value:
+ * - 'OK' for valid variables
+ * - error message(s) for invalid variables
+ *
+ * @param {{
+ *   params: Array<{
+ *     key: string,
+ *     displayValue: string,
+ *     valid: boolean,
+ *     errors?: string[]
+ *   }>
+ * }} report
+ *
+ * @returns {string}
+ */
+export function buildConsoleOutput(report: {
+  params: Array<{
+    key: string
+    displayValue: string
+    valid: boolean
+    errors?: string[]
+  }>
+}): string
+/**
+ * Validates environment variables and prepares
+ * a fully printable console output.
+ *
+ * @param {Record<string, Object>} definition
+ * @param {Record<string, any>} values
+ * @param {{
+ *   mask?: (value: any) => string
+ * }} [options]
+ *
+ * @returns {{
+ *   success: boolean,
+ *   output: string,
+ *   report: any
+ * }}
+ */
+export function validateEnvForConsole(
+  definition: Record<string, any>,
+  values: Record<string, any>,
+  options?: {
+    mask?: (value: any) => string
+  },
+): {
+  success: boolean
+  output: string
+  report: any
+}