fix(types): allow undefined values in populate output

lib/main.d.ts

@@ -7,7 +7,7 @@ export interface DotenvParseOutput {
 }
 
 export interface DotenvPopulateOutput {
-  [name: string]: string;
+  [name: string]: string | undefined;
 }
 
 export interface DotenvParseOptions {

tests/test-populate.js

@@ -30,6 +30,18 @@ t.test('takes processEnv and check if all keys applied to processEnv', ct => {
   ct.same(parsed, processEnv)
 })
 
+t.test('preserves undefined input values in the target and returned object', ct => {
+  for (const processEnv of [{}, { OPTIONAL: 'existing' }]) {
+    const populated = dotenv.populate(processEnv, { OPTIONAL: undefined }, { override: true })
+
+    ct.same(processEnv, { OPTIONAL: undefined })
+    ct.same(populated, { OPTIONAL: undefined })
+    ct.ok(Object.prototype.hasOwnProperty.call(processEnv, 'OPTIONAL'))
+    ct.ok(Object.prototype.hasOwnProperty.call(populated, 'OPTIONAL'))
+  }
+  ct.end()
+})
+
 t.test('does not write over keys already in processEnv', ct => {
   ct.plan(1)
 

tests/types/test.ts

@@ -36,6 +36,15 @@ populate(target, { DB_HOST: "localhost" }, { debug: true });
 populate(target, { DB_HOST: "localhost" }, { override: true });
 populate(target, { DB_HOST: "localhost" }, { debug: true, override: false });
 
+// populate() preserves undefined values from DotenvPopulateInput in its result.
+const populated = populate({}, { OPTIONAL: undefined });
+const optionalValue: string | undefined = populated["OPTIONAL"];
+// @ts-expect-error A populated value is not guaranteed to be a string.
+const requiredValue: string = populated["OPTIONAL"];
+if (optionalValue !== undefined) {
+  optionalValue.trim();
+}
+
 // config() reports a missing .env file by returning the ENOENT that fs threw,
 // so comparing error.code against it must type-check
 if (env.error?.code === "ENOENT") {