Add Support for Optional Environment Variables

[yasserfedsi]

Pull Request

Description

This PR adds support for optional environment variables in the validation schema. Currently, all variables defined in the schema are treated as required, which forces users to provide values for every configuration key even when they're genuinely optional in their application.

Purpose of this PR:

• Add an optional property to variable definitions that allows variables to be omitted from the environment without causing validation errors

• When a variable is marked as optional and is missing, validation passes without any error

• When a variable is marked as optional but is present, it is still validated according to its type definition

Which issues does it resolve?

• Resolves Feature: Optional Environment Variables #4

Relevant context or dependencies:

• This is a non-breaking change that maintains backward compatibility

• Existing schemas will continue to work as expected (default behavior remains "required")

• No external dependencies are introduced

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation update
• Performance improvement

How Has This Been Tested?

Unit tests

Added comprehensive unit tests covering:

• Optional string variable missing → validation passes
• Optional number variable missing → validation passes
• Optional boolean variable missing → validation passes
• Optional variable present with valid value → validation passes
• Optional variable present with invalid value → validation fails
• Required variable missing → validation fails (unchanged behavior)
• Required variable present → validation passes (unchanged behavior)
• Required variable present with invalid value → validation fails (unchanged behavior)
• Mixed required and optional variables in same schema → correct behavior for each

Integration tests

• Tested with actual environment variable loading and validation
• Verified that optional variables that are undefined don't trigger validation errors
• Confirmed that type validation still applies when optional variables are provided

Manual testing

Tested the following scenarios locally:

// Schema with mixed required and optional
const schema = {
  PORT: { type: "number" },
  API_KEY: { type: "string", optional: true },
  LOG_LEVEL: { type: "string", optional: true },
  DEBUG: { type: "boolean", optional: true }
};

// All combinations validated successfully

Test coverage results

• All existing tests pass ✓
• New tests achieve 100% coverage for the optional feature
• Test coverage remains at 95%+ overall

Checklist

• My code follows the project’s coding standards
• I have added or updated tests
• I have updated documentation
• All tests pass
• I have reviewed my code before submitting

Additional Notes

Implementation Details

The implementation extends the existing validation logic with a check for the optional property:

// In the validation function
if (definition.optional && value === undefined) {
  return; // Skip validation, variable is optional and missing
}
// Continue with normal validation

Documentation Updates

Updated the README with:

• Documentation of the optional property
• Usage examples showing required vs optional variables
• Updated API reference
• Migration guide note (not required as this is backward compatible)

Backward Compatibility

This change is fully backward compatible:

• Existing schemas without the optional property behave exactly as before (required by default)
• No changes required to existing code
• No breaking changes introduced

Example Usage

import { validateEnv } from '@yasserfedsi/envfy';

const env = validateEnv({
  // Required variables
  NODE_ENV: {
    type: "string",
    required: true // default behavior
  },
  PORT: {
    type: "number"
    // required by default
  },
  
  // Optional variables
  API_KEY: {
    type: "string",
    optional: true
  },
  LOG_LEVEL: {
    type: "string",
    optional: true
  },
  DEBUG_MODE: {
    type: "boolean",
    optional: true
  },
  REDIS_HOST: {
    type: "string",
    optional: true
  }
});

// All these will work:
// - PORT: 3000, API_KEY: missing ✓
// - PORT: 3000, API_KEY: "abc", DEBUG_MODE: missing ✓
// - PORT: 3000, API_KEY: "abc", DEBUG_MODE: true ✓

Future Considerations

Potential future enhancements:

• Add support for default values when optional variables are missing
• Support for conditional optionality based on other variables
• Validation of optional variables against a set of allowed values only when present

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[yasserfedsi]

good