@dotenvx/dotenvx 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.8.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.9.0...main)
+
+## [2.9.0](https://github.com/dotenvx/dotenvx/compare/v2.8.0...v2.9.0) (2026-07-14)
+
+### Changed
+
+* BREAKING: `ls` from `@dotenvx/dotenvx` is now async/await.
 
 ## [2.8.0](https://github.com/dotenvx/dotenvx/compare/v2.7.3...v2.8.0) (2026-07-14)
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.8.0",
+  "version": "2.9.0",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",

package/src/cli/actions/ls.js

@@ -1,24 +1,76 @@
 const { objectTreeify: treeify } = require('@dotenvx/tooling')
+const path = require('path')
 
 const { logger } = require('./../../shared/logger')
 
 const main = require('./../../lib/main')
 const ArrayToTree = require('./../../lib/helpers/arrayToTree')
+const catchAndLog = require('../../lib/helpers/catchAndLog')
+const createSpinner = require('../../lib/helpers/createSpinner')
 
-function ls (directory) {
+async function ls (directory) {
   // debug args
   logger.debug(`directory: ${directory}`)
 
   const options = this.opts()
+  let spinnerOptions
+  if (typeof this.optsWithGlobals === 'function') {
+    spinnerOptions = this.optsWithGlobals()
+  } else {
+    spinnerOptions = options
+  }
+  const spinner = await createSpinner({ ...spinnerOptions, ...options, text: 'traversing' })
+  const startedAt = Date.now()
+  let directoryCount = 1
   logger.debug(`options: ${JSON.stringify(options)}`)
 
-  const filepaths = main.ls(directory, options.envFile, options.excludeEnvFile)
-  logger.debug(`filepaths: ${JSON.stringify(filepaths)}`)
+  try {
+    const filepaths = await main.ls(directory, options.envFile, options.excludeEnvFile, (filepath) => {
+      directoryCount += 1
 
-  const tree = new ArrayToTree(filepaths).run()
-  logger.debug(`tree: ${JSON.stringify(tree)}`)
+      if (spinner) {
+        const elapsedSeconds = Math.floor((Date.now() - startedAt) / 1000)
+        let directoryLabel = 'directories'
+        if (directoryCount === 1) {
+          directoryLabel = 'directory'
+        }
 
-  logger.info(treeify(tree))
+        spinner.text = `traversing ${directoryCount.toLocaleString()} ${directoryLabel} (${elapsedSeconds}s) — ${filepath}`
+      }
+    })
+    logger.debug(`filepaths: ${JSON.stringify(filepaths)}`)
+
+    if (spinner) spinner.stop()
+
+    if (options.json) {
+      const cwd = path.resolve(directory || '.')
+      const absoluteFilepaths = filepaths.map(filepath => path.resolve(cwd, filepath))
+      console.log(JSON.stringify(absoluteFilepaths, null, 2))
+    } else {
+      const tree = new ArrayToTree(filepaths).run()
+      logger.debug(`tree: ${JSON.stringify(tree)}`)
+      logger.info(treeify(tree))
+    }
+
+    if (!spinnerOptions.quiet && !options.quiet) {
+      const elapsedSeconds = Math.floor((Date.now() - startedAt) / 1000)
+      const matchedDirectoryCount = new Set(filepaths.map(filepath => path.dirname(filepath))).size
+      let fileLabel = 'files'
+      if (filepaths.length === 1) {
+        fileLabel = 'file'
+      }
+      let directoryLabel = 'directories'
+      if (matchedDirectoryCount === 1) {
+        directoryLabel = 'directory'
+      }
+
+      console.error(`▣ found ${filepaths.length.toLocaleString()} .env ${fileLabel} across ${matchedDirectoryCount.toLocaleString()} ${directoryLabel} of ${directoryCount.toLocaleString()} scanned in ${elapsedSeconds}s`)
+    }
+  } catch (error) {
+    if (spinner) spinner.stop()
+    catchAndLog(error)
+    process.exit(1)
+  }
 }
 
 module.exports = ls

package/src/cli/commands/ext.js

@@ -24,6 +24,7 @@ ext.command('ls')
   .argument('[directory]', 'directory to list .env files from', '.')
   .option('-f, --env-file <filenames...>', 'path(s) to your env file(s)', '.env*')
   .option('-ef, --exclude-env-file <excludeFilenames...>', 'path(s) to exclude from your env file(s) (default: none)')
+  .option('--json', 'output a JSON array of absolute filepaths')
   .action(function (...args) {
     return require('./../actions/ls').apply(this, args)
   })

package/src/cli/dotenvx.js

@@ -176,6 +176,7 @@ program.command('ls')
   .argument('[directory]', 'directory to list .env files from', '.')
   .option('-f, --env-file <filenames...>', 'path(s) to your env file(s)', '.env*')
   .option('-ef, --exclude-env-file <excludeFilenames...>', 'path(s) to exclude from your env file(s) (default: none)')
+  .option('--json', 'output a JSON array of absolute filepaths')
   .action(function (...args) {
     return require('./actions/ls').apply(this, args)
   })

package/src/lib/main.d.ts

@@ -391,9 +391,11 @@ export function get(
  * @param directory - current working directory
  * @param envFile - glob pattern to match env files
  * @param excludeEnvFile - glob pattern to exclude env files
+ * @param onDirectory - called as each directory is traversed
  */
 export function ls(
   directory: string,
   envFile: string | string[],
-  excludeEnvFile: string | string[]
-): string[];
+  excludeEnvFile: string | string[],
+  onDirectory?: (directory: string) => void
+): Promise<string[]>;

package/src/lib/main.js

@@ -389,8 +389,8 @@ const get = async function (key, options = {}) {
 }
 
 /** @type {import('./main').ls} */
-const ls = function (directory, envFile, excludeEnvFile) {
-  return lsResolver({ directory, envFile, excludeEnvFile })
+const ls = async function (directory, envFile, excludeEnvFile, onDirectory) {
+  return await lsResolver({ directory, envFile, excludeEnvFile, onDirectory })
 }
 
 function resolveNoArmor (options = {}) {

package/src/lib/resolvers/ls.js

@@ -2,6 +2,14 @@ const { Fdir } = require('@dotenvx/tooling')
 const path = require('path')
 const { match } = require('@dotenvx/primitives')
 
+const DEFAULT_EXCLUDED_DIRECTORY_EXTENSIONS = new Set([
+  '.app',
+  '.key',
+  '.numbers',
+  '.pages',
+  '.photoslibrary'
+])
+
 function patternsFor (value) {
   if (!Array.isArray(value)) {
     return [`**/${value}`]
@@ -18,24 +26,44 @@ function excludePatternsFor (value) {
   return value.map(part => `**/${part}`)
 }
 
-function ls (options = {}) {
+function crawler (options = {}) {
   const ignore = ['node_modules/**', '**/node_modules/**', '.git/**', '**/.git/**']
   const cwd = path.resolve(options.directory || './')
   const envFile = options.envFile || ['.env*']
   const excludeEnvFile = options.excludeEnvFile || []
   const excludePatterns = excludePatternsFor(excludeEnvFile)
-  const excludes = excludePatterns.length > 0 ? ignore.concat(excludePatterns) : ignore
+  let excludes
+  if (excludePatterns.length > 0) {
+    excludes = ignore.concat(excludePatterns)
+  } else {
+    excludes = ignore
+  }
   const exclude = match(excludes, { dot: true })
   const include = match(patternsFor(envFile), {
     dot: true,
     ignore: excludes
   })
+  const onDirectory = options.onDirectory || (() => {})
 
   return new Fdir()
     .withRelativePaths()
+    .exclude((dirname, directory) => {
+      if (dirname === 'node_modules' || dirname === '.git') return true
+      if (DEFAULT_EXCLUDED_DIRECTORY_EXTENSIONS.has(path.extname(dirname).toLowerCase())) return true
+
+      onDirectory(path.relative(cwd, directory) || '.')
+      return false
+    })
     .filter((filepath) => !exclude(filepath) && include(filepath))
     .crawl(cwd)
-    .sync()
+}
+
+async function ls (options = {}) {
+  return await crawler(options).withPromise()
+}
+
+ls.sync = function (options = {}) {
+  return crawler(options).sync()
 }
 
 module.exports = ls

package/src/lib/services/prebuild.js

@@ -82,7 +82,7 @@ class Prebuild {
   }
 
   _filepaths () {
-    return ls({
+    return ls.sync({
       directory: this.directory,
       excludeEnvFile: this.excludeEnvFile
     })

package/src/lib/services/precommit.js

@@ -100,7 +100,7 @@ class Precommit {
   }
 
   _filepaths () {
-    return ls({
+    return ls.sync({
       directory: this.directory,
       excludeEnvFile: this.excludeEnvFile
     })