@williamthorsen/toolbelt.filesystem 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.8.0 — 2026-08-24
+
+### Features
+
+- Add a recursive listFiles to createTempTree's entry API (#212)
+
+  Adds `listFiles` to the handle `createTempTree` returns in `@williamthorsen/toolbelt.filesystem/candidate`. It reports every file below a tree-relative directory, at any depth, as sorted `/`-separated paths relative to that directory, whereas `list` reaches one level and reports names alone. A symlink below that directory is neither named nor descended, so every path in the result names a file held inside the tree.
+
 ## 0.7.0 — 2026-08-21
 
 ### Features

package/README.md

@@ -3,19 +3,13 @@
 Filesystem utilities for TypeScript and JavaScript.
 
 <!-- section:release-notes -->
-## Release notes — v0.7.0 (2026-08-21)
+## Release notes — v0.8.0 (2026-08-24)
 
 ### Features
 
-- 🚨 **Breaking:** Fix createTempTree's symlink guard and disposal, and complete its entry API (#207)
+- Add a recursive listFiles to createTempTree's entry API (#212)
 
-  Fixes an issue where `TempTree.symlink` in `@williamthorsen/toolbelt.filesystem/candidate` refused a target outside the tree and rewrote a relative target to an absolute path inside it. The containment check now applies to the link path alone and the target is stored as given, so a link reads back as the string that was passed.
-
-  Separately, fixes an issue where disposing a `TempTree` left the tree on disk when one of its directories had been made read-only.
-
-  Adds six methods to `TempTree`. `writeAll` applies the constructor's map of entries to a tree already built; `exists`, `list`, `read`, `readJson`, and `rm` read the tree back and remove from it, so a suite scaffolding through the handle reads its own fixture through it rather than reaching for `node:fs`.
-
-  Migration: A caller relying on the previous absolute storage passes `tree.resolve(target)`, which is written unchanged.
+  Adds `listFiles` to the handle `createTempTree` returns in `@williamthorsen/toolbelt.filesystem/candidate`. It reports every file below a tree-relative directory, at any depth, as sorted `/`-separated paths relative to that directory, whereas `list` reaches one level and reports names alone. A symlink below that directory is neither named nor descended, so every path in the result names a file held inside the tree.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -300,6 +294,7 @@ interface TempTree extends Disposable {
   readonly dir: string;
   exists(entryPath: string): boolean;
   list(entryPath?: string): string[];
+  listFiles(entryPath?: string): string[];
   mkdir(entryPath: string): string;
   read(entryPath: string): string;
   readJson(entryPath: string): unknown;
@@ -349,19 +344,22 @@ tree.symlink('node_modules/.bin', tree.resolve('store/kit/bin')); // reads back
 
 The link type is chosen from the target, which is where the one portability difference lives. An absolute directory target is linked as a junction, which Windows creates without the elevation a directory symlink needs; a relative directory target is linked as a directory, which needs that elevation, because Node normalizes a junction's target to an absolute path and would discard the relative string. Every other target, one that does not exist included, is linked as a file, matching what Node falls back to when no type is given.
 
-`exists`, `list`, `read`, `readJson`, and `rm` read the tree back and remove from it, each through the same containment check:
+`exists`, `list`, `listFiles`, `read`, `readJson`, and `rm` read the tree back and remove from it, each through the same containment check:
 
 ```ts
 using tree = createTempTree({ 'packages/app/package.json': '{ "name": "app" }', 'packages/app/src/main.ts': 'export {};\n' });
 
 tree.list(); // ['packages'], defaulting to the tree root
 tree.list('packages/app'); // ['package.json', 'src'], sorted
+tree.listFiles('packages'); // ['app/package.json', 'app/src/main.ts'], at any depth
 tree.read('packages/app/src/main.ts'); // 'export {};\n'
 tree.readJson('packages/app/package.json'); // unknown, for the caller to narrow
 tree.exists('packages/app/tsconfig.json'); // false
 tree.rm('packages/app');
 ```
 
+`listFiles` reaches every depth and reports paths relative to the directory it was given, sorted, with `/` as the separator on every platform: a path a test asserts on is a value rather than a location, so `'app/src/main.ts'` should not vary by platform. It parts from `list` twice. A directory that is not there answers `[]` where `list` raises `ENOENT`, which is what lets a suite assert that a build emitted nothing without guarding the call; a path that exists as a file still raises `ENOTDIR`, as `list` does. And a symlink below the directory it was given is neither named nor descended, so every path in the result names a file held inside the tree, where `list` reports a link by name at its own level. The directory given as the argument is the exception, followed as `list`, `read`, and `exists` follow theirs: one naming a link out of the tree lists the target's files.
+
 `read` returns UTF-8 text, and a missing entry raises `ENOENT` rather than answering emptily -- `exists` is the check. `readJson` returns `unknown`, so a caller narrows it rather than trusting an asserted type; contents that do not parse raise an error naming the entry, which the parse error alone does not. `exists` follows a symlink, so a dangling one answers `false`. `rm` is recursive and silent on an entry that is not there.
 
 `writeJson` writes two-space-indented JSON ending in a newline, so a tree outliving a crashed run reads as a real config file would. A fixture needing exact bytes goes through `write` instead. A value `JSON.stringify` cannot represent -- `undefined`, a function, a symbol -- is refused rather than written, so an optional binding that arrived empty fails at the call that passed it instead of surfacing later as a parse error.

package/dist/esm/3-candidate/createTempTree.d.ts

@@ -6,6 +6,7 @@ export interface TempTree extends Disposable {
     readonly dir: string;
     exists(entryPath: string): boolean;
     list(entryPath?: string): string[];
+    listFiles(entryPath?: string): string[];
     mkdir(entryPath: string): string;
     read(entryPath: string): string;
     readJson(entryPath: string): unknown;

package/dist/esm/3-candidate/createTempTree.js

@@ -18,6 +18,12 @@ export function createTempTree(entries, options = {}) {
     function list(entryPath = '') {
         return fs.readdirSync(resolveWithinTree(dir, [entryPath])).toSorted();
     }
+    function listFiles(entryPath = '') {
+        const rootPath = resolveWithinTree(dir, [entryPath]);
+        if (!fs.existsSync(rootPath))
+            return [];
+        return listFilesBelow(rootPath, '').toSorted();
+    }
     function mkdir(entryPath) {
         const absolutePath = resolveWithinTree(dir, [entryPath]);
         fs.mkdirSync(absolutePath, { recursive: true });
@@ -74,6 +80,7 @@ export function createTempTree(entries, options = {}) {
         dir,
         exists,
         list,
+        listFiles,
         mkdir,
         read,
         readJson,
@@ -109,6 +116,20 @@ function chooseLinkType(absoluteLinkPath, targetPath) {
     }
     return path.isAbsolute(targetPath) ? 'junction' : 'dir';
 }
+function listFilesBelow(dir, prefix) {
+    const paths = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relativePath = `${prefix}${entry.name}`;
+        if (entry.isFile()) {
+            paths.push(relativePath);
+        }
+        else if (entry.isDirectory()) {
+            paths.push(...listFilesBelow(path.join(dir, entry.name), `${relativePath}/`));
+        }
+    }
+    return paths;
+}
 function restoreDirectoryPermissions(dir) {
     fs.chmodSync(dir, 0o700);
     const entries = fs.readdirSync(dir, { withFileTypes: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Filesystem utilities",
   "keywords": [
     "config-cascade",
@@ -44,7 +44,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.6.0"
+    "@williamthorsen/toolbelt.errors": "0.6.1"
   },
   "engines": {
     "node": ">=24.0.0"