rewire.ts

/**
 * @fileoverview Environment variable rewiring utilities for testing.
 * Uses AsyncLocalStorage for context-isolated overrides that work with concurrent tests.
 *
 * Features:
 * - Context-isolated overrides via withEnv() for advanced use cases
 * - Test-friendly setEnv/clearEnv/resetEnv that work in beforeEach/afterEach
 * - Compatible with vi.stubEnv() - reads from process.env as final fallback
 * - Thread-safe for concurrent test execution
 */

import process from 'node:process'

import { hasOwn } from '../objects'
import { envAsBoolean } from './helpers'

import { MapCtor, ObjectEntries } from '../primordials'

let _async_hooks: typeof import('node:async_hooks') | undefined
/**
 * Lazily load the async_hooks module to avoid Webpack errors.
 * @private
 */
/*@__NO_SIDE_EFFECTS__*/
function getAsyncHooks() {
  if (_async_hooks === undefined) {
    // Use non-'node:' prefixed require to avoid Webpack errors.

    _async_hooks = /*@__PURE__*/ require('node:async_hooks')
  }
  return _async_hooks as typeof import('node:async_hooks')
}

type EnvOverrides = Map<string, string | undefined>

// Isolated execution context storage for nested overrides (withEnv/withEnvSync)
// AsyncLocalStorage creates isolated contexts that don't leak between concurrent code
const { AsyncLocalStorage } = getAsyncHooks()
const isolatedOverridesStorage = new AsyncLocalStorage<EnvOverrides>()

// Shared test hook overrides (setEnv/clearEnv/resetEnv in beforeEach/afterEach)
// IMPORTANT: Use globalThis to ensure singleton across duplicate module instances
// In coverage mode, both src and dist versions of this module may be loaded,
// but they must share the same Map for rewiring to work.
// Only initialize in test environment to avoid polluting production runtime
// Vitest automatically sets VITEST=true when running tests
const sharedOverridesSymbol = Symbol.for(
  '@socketsecurity/lib/env/rewire/test-overrides',
)
const _globalThis = globalThis as Record<symbol, unknown>
const isVitestEnv = envAsBoolean(process.env['VITEST'])
if (isVitestEnv && !_globalThis[sharedOverridesSymbol]) {
  _globalThis[sharedOverridesSymbol] = new MapCtor<string, string | undefined>()
}
const sharedOverrides: Map<string, string | undefined> | undefined =
  _globalThis[sharedOverridesSymbol] as
    | Map<string, string | undefined>
    | undefined

/**
 * Clear a specific environment variable override.
 *
 * @param key - The environment variable name to clear
 *
 * @example
 * ```typescript
 * import { setEnv, clearEnv } from '@socketsecurity/lib/env/rewire'
 *
 * setEnv('CI', '1')
 * clearEnv('CI')
 * ```
 */
export function clearEnv(key: string): void {
  sharedOverrides?.delete(key)
}

/**
 * Get an environment variable value, checking overrides first.
 *
 * Resolution order:
 * 1. Isolated overrides (temporary - set via withEnv/withEnvSync)
 * 2. Shared overrides (persistent - set via setEnv in beforeEach)
 * 3. process.env (including vi.stubEnv modifications)
 *
 * @internal Used by env getters to support test rewiring
 *
 * @example
 * ```typescript
 * import { getEnvValue } from '@socketsecurity/lib/env/rewire'
 *
 * const value = getEnvValue('NODE_ENV')
 * // e.g. 'production' or undefined
 * ```
 */
export function getEnvValue(key: string): string | undefined {
  // Check isolated overrides first (highest priority - temporary via withEnv)
  const isolatedOverrides = isolatedOverridesStorage.getStore()
  if (isolatedOverrides?.has(key)) {
    return isolatedOverrides.get(key)
  }

  // Check shared overrides (persistent via setEnv in beforeEach)
  if (sharedOverrides?.has(key)) {
    return sharedOverrides.get(key)
  }

  // Fall back to process.env (works with vi.stubEnv)
  return process.env[key]
}

/**
 * Check if an environment variable has been overridden.
 *
 * @param key - The environment variable name to check
 * @returns `true` if the variable has been overridden, `false` otherwise
 *
 * @example
 * ```typescript
 * import { setEnv, hasOverride } from '@socketsecurity/lib/env/rewire'
 *
 * hasOverride('CI')  // false
 * setEnv('CI', '1')
 * hasOverride('CI')  // true
 * ```
 */
export function hasOverride(key: string): boolean {
  const isolatedOverrides = isolatedOverridesStorage.getStore()
  return !!(isolatedOverrides?.has(key) || sharedOverrides?.has(key))
}

/**
 * Check if an environment variable exists (has a key), checking overrides first.
 *
 * Resolution order:
 * 1. Isolated overrides (temporary - set via withEnv/withEnvSync)
 * 2. Shared overrides (persistent - set via setEnv in beforeEach)
 * 3. process.env (including vi.stubEnv modifications)
 *
 * @internal Used by env getters to check for key presence (not value truthiness)
 *
 * @example
 * ```typescript
 * import { isInEnv } from '@socketsecurity/lib/env/rewire'
 *
 * isInEnv('PATH')     // true (usually set)
 * isInEnv('MISSING')  // false
 * ```
 */
export function isInEnv(key: string): boolean {
  // Check isolated overrides first (highest priority - temporary via withEnv)
  const isolatedOverrides = isolatedOverridesStorage.getStore()
  if (isolatedOverrides?.has(key)) {
    return true
  }

  // Check shared overrides (persistent via setEnv in beforeEach)
  if (sharedOverrides?.has(key)) {
    return true
  }

  // Fall back to process.env (works with vi.stubEnv)
  return hasOwn(process.env, key)
}

/**
 * Clear all environment variable overrides.
 * Useful in afterEach hooks to ensure clean test state.
 *
 * @example
 * ```typescript
 * import { resetEnv } from './rewire'
 *
 * afterEach(() => {
 *   resetEnv()
 * })
 * ```
 */
export function resetEnv(): void {
  sharedOverrides?.clear()
}

/**
 * Set an environment variable override for testing.
 * This does not modify process.env, only affects env getters.
 *
 * Works in test hooks (beforeEach) without needing AsyncLocalStorage context.
 * Vitest's module isolation ensures each test file has independent overrides.
 *
 * @example
 * ```typescript
 * import { setEnv, resetEnv } from './rewire'
 * import { getCI } from './ci'
 *
 * beforeEach(() => {
 *   setEnv('CI', '1')
 * })
 *
 * afterEach(() => {
 *   resetEnv()
 * })
 *
 * it('should detect CI environment', () => {
 *   expect(getCI()).toBe(true)
 * })
 * ```
 */
export function setEnv(key: string, value: string | undefined): void {
  sharedOverrides?.set(key, value)
}

/**
 * Run code with environment overrides in an isolated AsyncLocalStorage context.
 * Creates true context isolation - overrides don't leak to concurrent code.
 *
 * Useful for tests that need temporary overrides without affecting other tests
 * or for nested override scenarios.
 *
 * @example
 * ```typescript
 * import { withEnv } from './rewire'
 * import { getCI } from './ci'
 *
 * // Temporary override in isolated context
 * await withEnv({ CI: '1' }, async () => {
 *   expect(getCI()).toBe(true)
 * })
 * expect(getCI()).toBe(false) // Override is gone
 * ```
 *
 * @example
 * ```typescript
 * // Nested overrides work correctly
 * setEnv('CI', '1') // Shared override (persistent)
 *
 * await withEnv({ CI: '0' }, async () => {
 *   expect(getCI()).toBe(false) // Isolated override takes precedence
 * })
 *
 * expect(getCI()).toBe(true) // Back to shared override
 * ```
 */
export async function withEnv<T>(
  overrides: Record<string, string | undefined>,
  fn: () => T | Promise<T>,
): Promise<T> {
  const map = new MapCtor(ObjectEntries(overrides))
  return await isolatedOverridesStorage.run(map, fn)
}

/**
 * Synchronous version of withEnv for non-async code.
 *
 * @example
 * ```typescript
 * import { withEnvSync } from './rewire'
 * import { getCI } from './ci'
 *
 * const result = withEnvSync({ CI: '1' }, () => {
 *   return getCI()
 * })
 * expect(result).toBe(true)
 * ```
 */
export function withEnvSync<T>(
  overrides: Record<string, string | undefined>,
  fn: () => T,
): T {
  const map = new MapCtor(ObjectEntries(overrides))
  return isolatedOverridesStorage.run(map, fn)
}