fix: stable ordering of files

package.json

@@ -35,11 +35,11 @@
   },
   "devDependencies": {
     "@types/graceful-fs": "^4.1.6",
-    "@types/node": "^18.15.1",
+    "@types/node": "^20.9.0",
     "ava": "^5.2.0",
     "ipjs": "^5.0.3",
     "standard": "^17.0.0",
-    "typescript": "^4.9.5",
+    "typescript": "^5.2.2",
     "unlimited": "^1.2.2"
   },
   "engines": {

src/index.js

@@ -1,18 +1,45 @@
-import fs from 'graceful-fs'
+import gracefulfs from 'graceful-fs'
 import { promisify } from 'util'
 import path from 'path'
 import { Readable } from 'stream'
 
-/** @typedef {Pick<File, 'stream'|'name'|'size'>} FileLike */
+/**
+ * @typedef {Pick<File, 'stream'|'name'|'size'>} FileLike
+ * @typedef {{
+ *   name: string
+ *   isFile: () => boolean
+ *   isDirectory: () => boolean
+ * }} Dirent
+ * @typedef {{
+ *   readdir: (path: string, options: { withFileTypes: true }) => Promise<Dirent[]>
+ * }} DirReader
+ * @typedef {{
+ *   size: number
+ *   isFile: () => boolean
+ *   isDirectory: () => boolean
+ * }} Stats
+ * @typedef {{ stat: (path: string) => Promise<Stats> }} StatGetter
+ * @typedef {{
+ *   createReadStream: (path: string) => import('node:fs').ReadStream
+ *   promises: DirReader & StatGetter
+ * }} FileSystem
+ */
 
-// https://github.com/isaacs/node-graceful-fs/issues/160
-const fsStat = promisify(fs.stat)
-const fsReaddir = promisify(fs.readdir)
+const defaultfs = {
+  createReadStream: gracefulfs.createReadStream,
+  promises: {
+    // https://github.com/isaacs/node-graceful-fs/issues/160
+    stat: promisify(gracefulfs.stat),
+    readdir: promisify(gracefulfs.readdir)
+  }
+}
 
 /**
  * @param {Iterable<string>} paths
  * @param {object} [options]
  * @param {boolean} [options.hidden]
+ * @param {boolean} [options.sort] Sort by path. Default: true.
+ * @param {FileSystem} [options.fs] Custom FileSystem implementation.
  * @returns {Promise<FileLike[]>}
  */
 export async function filesFromPaths (paths, options) {
@@ -36,18 +63,23 @@ export async function filesFromPaths (paths, options) {
     }
   }
   const commonPath = `${(commonParts ?? []).join('/')}/`
-  return files.map(f => ({ ...f, name: f.name.slice(commonPath.length) }))
+  const commonPathFiles = files.map(f => ({ ...f, name: f.name.slice(commonPath.length) }))
+  return options?.sort == null || options?.sort === true
+    ? commonPathFiles.sort((a, b) => a.name === b.name ? 0 : a.name > b.name ? 1 : -1)
+    : commonPathFiles
 }
 
 /**
  * @param {string} filepath
  * @param {object} [options]
  * @param {boolean} [options.hidden]
+ * @param {FileSystem} [options.fs] Custom FileSystem implementation.
  * @returns {AsyncIterableIterator<FileLike>}
  */
-async function * filesFromPath (filepath, options = {}) {
+async function * filesFromPath (filepath, options) {
   filepath = path.resolve(filepath)
-  const hidden = options.hidden ?? false
+  const fs = options?.fs ?? defaultfs
+  const hidden = options?.hidden ?? false
 
   /** @param {string} filepath */
   const filter = filepath => {
@@ -56,7 +88,7 @@ async function * filesFromPath (filepath, options = {}) {
   }
 
   const name = filepath
-  const stat = await fsStat(name)
+  const stat = await fs.promises.stat(name)
 
   if (!filter(name)) {
     return
@@ -66,25 +98,28 @@ async function * filesFromPath (filepath, options = {}) {
     // @ts-expect-error node web stream not type compatible with web stream
     yield { name, stream: () => Readable.toWeb(fs.createReadStream(name)), size: stat.size }
   } else if (stat.isDirectory()) {
-    yield * filesFromDir(name, filter)
+    yield * filesFromDir(name, filter, options)
   }
 }
 
 /**
  * @param {string} dir
  * @param {(name: string) => boolean} filter
+ * @param {object} [options]
+ * @param {FileSystem} [options.fs] Custom FileSystem implementation.
  * @returns {AsyncIterableIterator<FileLike>}
  */
-async function * filesFromDir (dir, filter) {
-  const entries = await fsReaddir(path.join(dir), { withFileTypes: true })
+async function * filesFromDir (dir, filter, options) {
+  const fs = options?.fs ?? defaultfs
+  const entries = await fs.promises.readdir(path.join(dir), { withFileTypes: true })
   for (const entry of entries) {
     if (!filter(entry.name)) {
       continue
     }
 
     if (entry.isFile()) {
       const name = path.join(dir, entry.name)
-      const { size } = await fsStat(name)
+      const { size } = await fs.promises.stat(name)
       // @ts-expect-error node web stream not type compatible with web stream
       yield { name, stream: () => Readable.toWeb(fs.createReadStream(name)), size }
     } else if (entry.isDirectory()) {

test/test.spec.js

@@ -63,6 +63,28 @@ test('allows read of more files than ulimit maxfiles', async t => {
   }
 })
 
+test('uses custom fs implementation', async t => {
+  // it uses graceful-fs by default so passing node:fs is legit test
+  const files = await filesFromPaths([`${process.cwd()}/test/fixtures`], { fs })
+  t.true(files.length === 3)
+})
+
+test('sorts by path', async t => {
+  const paths = ['dir/file2.txt', 'empty.car', 'file.txt']
+  /** @param {string} name */
+  const toDirEnt = name => ({ name, isFile: () => true, isDirectory: () => false })
+  const files = await filesFromPaths([`${process.cwd()}/test/fixtures`], {
+    fs: {
+      createReadStream: fs.createReadStream,
+      promises: {
+        stat: fs.promises.stat,
+        readdir: async () => [...paths].reverse().map(toDirEnt)
+      }
+    }
+  })
+  t.deepEqual(files.map(f => f.name), paths)
+})
+
 /**
  * @param {number} n
  */