dotenv-expand 11.0.7: expand

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify dotenv-expand.expand in pkg:npm/dotenv-expand@11.0.7
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/dotenv-expand@11.0.7
Demonstrate these symbols/APIs:
  - dotenv-expand.expand

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:921aaefd5e10a062dbabcc61c61754fa79e371a02a5ae6875872019af9b3840a","contract":["dotenv-expand.expand supports both named export expand and namespace export dotenvExpand.expand","dotenv-expand.expand interpolates variable references from parsed and custom processEnv","dotenv-expand.expand resolves fallback default values when variables are unset","dotenv-expand.expand handles recursive and chained variable expansion","dotenv-expand.expand preserves escaped dollar sign sequences","dotenv-expand.expand writes resolved variables back to processEnv and returns options object"],"goal":"verify dotenv-expand.expand in pkg:npm/dotenv-expand@11.0.7","kind":"HOW","packages":["pkg:npm/dotenv-expand@11.0.7"],"schemaVersion":1,"symbols":["dotenv-expand.expand"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/dotenv-expand@11.0.7"],"schemaVersion":1,"subject":"pkg:npm/dotenv-expand@11.0.7","symbols":["dotenv-expand.expand"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-dotenv-expand",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-dotenv-expand",
      "version": "1.0.0",
      "dependencies": {
        "dotenv-expand": "11.0.7"
      }
    },
    "node_modules/dotenv": {
      "version": "16.6.1",
      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
      "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=12"
      },
      "funding": {
        "url": "https://dotenvx.com"
      }
    },
    "node_modules/dotenv-expand": {
      "version": "11.0.7",
      "resolved": "https://registry.npmjs.org/dotenv-expand/-/dotenv-expand-11.0.7.tgz",
      "integrity": "sha512-zIHwmZPRshsCdpMDyVsqGmgyP0yT8GAgXUnkdAoJisxvf33k7yO6OuoKmcTGuXPWSsm8Oh88nZicRLA9Y0rUeA==",
      "license": "BSD-2-Clause",
      "dependencies": {
        "dotenv": "^16.4.5"
      },
      "engines": {
        "node": ">=12"
      },
      "funding": {
        "url": "https://dotenvx.com"
      }
    }
  }
}

{
  "name": "sample-dotenv-expand",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "Clean-room verification sample for dotenv-expand.expand in dotenv-expand 11.0.7",
  "dependencies": {
    "dotenv-expand": "11.0.7"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify dotenv-expand.expand in pkg:npm/dotenv-expand@11.0.7",
  "kind": "HOW",
  "packages": [
    "pkg:npm/dotenv-expand@11.0.7"
  ],
  "symbols": [
    "dotenv-expand.expand"
  ]
}

import assert from 'node:assert/strict';
import * as dotenvExpand from 'dotenv-expand';
import { expand } from 'dotenv-expand';

// 1. dotenv-expand.expand supports both named export expand and namespace export dotenvExpand.expand
assert.strictEqual(typeof expand, 'function');
assert.strictEqual(typeof dotenvExpand.expand, 'function');
assert.strictEqual(expand, dotenvExpand.expand);

// 2. dotenv-expand.expand interpolates variable references from parsed and custom processEnv
{
  const customEnv = { EXTERNAL_HOST: 'localhost' };
  const config = {
    processEnv: customEnv,
    parsed: {
      PORT: '9000',
      HOST_PORT: '${EXTERNAL_HOST}:${PORT}',
      BARE_VAR: '$PORT/metrics'
    }
  };
  const result = dotenvExpand.expand(config);
  assert.equal(result.parsed.HOST_PORT, 'localhost:9000');
  assert.equal(result.parsed.BARE_VAR, '9000/metrics');
}

// 3. dotenv-expand.expand resolves fallback default values when variables are unset
{
  const customEnv = { EXISTING_VAR: 'set_value' };
  const config = {
    processEnv: customEnv,
    parsed: {
      UNSET_WITH_COLON_DASH: '${UNSET_KEY:-default_colon}',
      UNSET_WITH_DASH: '${UNSET_KEY-default_dash}',
      SET_WITH_DEFAULT: '${EXISTING_VAR:-should_not_use}'
    }
  };
  const result = expand(config);
  assert.equal(result.parsed.UNSET_WITH_COLON_DASH, 'default_colon');
  assert.equal(result.parsed.UNSET_WITH_DASH, 'default_dash');
  assert.equal(result.parsed.SET_WITH_DEFAULT, 'set_value');
}

// 4. dotenv-expand.expand handles recursive and chained variable expansion
{
  const customEnv = {};
  const config = {
    processEnv: customEnv,
    parsed: {
      BASE_DIR: 'app',
      DATA_DIR: '${BASE_DIR}/data',
      CONFIG_FILE: '${DATA_DIR}/config.json',
      BACKUP_FILE: '${CONFIG_FILE}.bak'
    }
  };
  const result = expand(config);
  assert.equal(result.parsed.BASE_DIR, 'app');
  assert.equal(result.parsed.DATA_DIR, 'app/data');
  assert.equal(result.parsed.CONFIG_FILE, 'app/data/config.json');
  assert.equal(result.parsed.BACKUP_FILE, 'app/data/config.json.bak');
}

// 5. dotenv-expand.expand preserves escaped dollar sign sequences
{
  const customEnv = {};
  const config = {
    processEnv: customEnv,
    parsed: {
      ESCAPED_DOLLAR: '\\$PRESERVED_NAME',
      ESCAPED_WITH_BRACES: '\\${NOT_EXPANDED}'
    }
  };
  const result = expand(config);
  assert.equal(result.parsed.ESCAPED_DOLLAR, '$PRESERVED_NAME');
  assert.equal(result.parsed.ESCAPED_WITH_BRACES, '${NOT_EXPANDED}');
}

// 6. dotenv-expand.expand writes resolved variables back to processEnv and returns options object
{
  const customEnv = { INITIAL: 'orig' };
  const config = {
    processEnv: customEnv,
    parsed: {
      APP_NAME: 'test_app',
      APP_TITLE: '${APP_NAME}_service'
    }
  };
  const result = expand(config);
  assert.strictEqual(result, config);
  assert.equal(customEnv.APP_NAME, 'test_app');
  assert.equal(customEnv.APP_TITLE, 'test_app_service');
  assert.equal(customEnv.INITIAL, 'orig');
}

console.log('Contract assertions passed.');