remove logLoadedFiles and introduce an optional callback when the file is loaded

Author: ivandotv

.changeset/tricky-mice-dance.md

@@ -0,0 +1,5 @@
+---
+"puntoenv": major
+---
+
+remove `logLoadedFiles` and introduce an optional callback when the file is loaded with the info about the loaded file and data.

README.md

@@ -10,6 +10,8 @@ PuntoEnv is a simple package that enables you to load `.env` files in to `proces
 - [Motivation](#motivation)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
+  * [Custom ENV variable](#custom-env-variable)
+  * [Loaded file callback](#loaded-file-callback)
 - [How it works.](#how-it-works)
   * [Variable expansion](#variable-expansion)
 - [License](#license)
@@ -35,6 +37,7 @@ import { setupEnv } from 'puntoenv'
 
 setupEnv('/path/to/your-dir/')
 ```
+### Custom ENV variable
 
 Also note that `NODE_ENV` will be the default environment variable that will be checked, but you can use any other variable.
 ```ts
@@ -44,6 +47,21 @@ setupEnv('/path/to/your-dir/','NODE_CONTEXT')
 
 Make sure you call the function as early as possible in your code.
 
+### Loaded file callback
+
+You can pass in optional `onLoad` callback (to the options object), that will fire for every loaded file. Inside the callback there is info about the `path`, `filename` and the result of the
+`dotEnv.config` method call.
+
+```ts
+setupEnv(__dirname, {
+  onLoad: (data) => {
+    console.log('path ',data.path)
+    console.log('filename ',data.filename)
+    console.log('result ',data.result) // {error?: Error , parsed:Record<string,string>}
+  },
+})
+
+```
 ## How it works.
 
 PuntoEnv will load `.env` files in a particular order.

src/__tests__/filesystem/dev-env/dev-env.test.ts

@@ -33,5 +33,66 @@ describe("Dev Files", () => {
       expect(process.env.MY_ENV).toEqual(".env.development.local")
       expect(process.env.FROM_EXPAND).toEqual(".env.development.local")
     })
+
+    test("onLoad callback", () => {
+      process.env.NODE_CONTEXT = "DEVELOPMENT"
+      const path = "/__tests__/filesystem/dev-env"
+
+      const result: Record<string, unknown>[] = []
+      setupEnv(__dirname, {
+        envVar: "NODE_CONTEXT",
+        onLoad: (data) => {
+          result.push(data)
+        },
+      })
+
+      expect(result[0]).toEqual({
+        path: expect.stringContaining(path),
+        filename: ".env.development.local",
+        result: {
+          parsed: {
+            MY_ENV: ".env.development.local",
+            TO_EXPAND: ".env.development.local",
+            FROM_EXPAND: "$TO_EXPAND",
+          },
+        },
+      })
+
+      expect(result[1]).toEqual({
+        path: expect.stringContaining(path),
+        filename: ".env.local",
+        result: {
+          parsed: {
+            MY_ENV: ".env.local",
+            TO_EXPAND: ".env.local",
+            FROM_EXPAND: "$TO_EXPAND",
+          },
+        },
+      })
+
+      expect(result[2]).toEqual({
+        path: expect.stringContaining(path),
+        filename: ".env.development",
+        result: {
+          parsed: {
+            MY_ENV: ".env.development",
+            TO_EXPAND: ".env.development",
+            FROM_EXPAND: "$TO_EXPAND",
+          },
+        },
+      })
+
+      expect(result[3]).toEqual({
+        path: expect.stringContaining(path),
+        filename: ".env",
+        result: {
+          parsed: {
+            MY_ENV: ".env",
+            TO_EXPAND: ".env",
+            FROM_EXPAND: "$TO_EXPAND",
+          },
+        },
+      })
+    })
   })
 })

src/__tests__/setupEnv.test.ts

@@ -55,7 +55,7 @@ describe("Env", () => {
 
     fs.existsSync = vitest.fn().mockReturnValue(true)
 
-    const loaded = setupEnv(path, { logLoadedFiles: true })
+    const loaded = setupEnv(path)
 
     expect(loaded).toEqual([
       ".env.production.local",

src/index.ts

@@ -14,8 +14,19 @@ export function setupEnv(
   {
     envVar = "NODE_ENV",
     debug = false,
-    logLoadedFiles = false,
-  }: { envVar?: string; debug?: boolean; logLoadedFiles?: boolean } = {},
+    onLoad,
+  }: {
+    envVar?: string
+    debug?: boolean
+    onLoad?: (data: {
+      path: string
+      filename: string
+      result: {
+        error?: Error
+        parsed?: Record<string, string>
+      }
+    }) => void
+  } = {},
 ): string[] {
   const resolvedEnv = (process.env[envVar] || "").toLowerCase()
 
@@ -35,24 +46,21 @@ export function setupEnv(
   }
 
   const loaded = []
-  if (logLoadedFiles) {
-    console.log("loading env files:")
-  }
   for (const file of files) {
     const fullPath = path.normalize(`${rootPath}/${file}`)
 
     if (fs.existsSync(fullPath)) {
-      if (logLoadedFiles) {
-        console.log(`   - ${file}`)
-      }
-
       loaded.push(file)
 
-      dotEnv.config({
+      const result = dotEnv.config({
         path: fullPath,
         override: false,
         debug,
       })
+
+      if (onLoad) {
+        onLoad({ path: rootPath, filename: file, result })
+      }
     }
   }