@williamthorsen/toolbelt.filesystem 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.7.0 — 2026-08-21
+
+### Features
+
+- 🚨 **Breaking:** Fix createTempTree's symlink guard and disposal, and complete its entry API (#207)
+
+  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.
+
+## 0.6.0 — 2026-08-16
+
+### Features
+
+- Add mkdir, symlink, write, and writeJson methods to `TempTree` (#176)
+
+  Adds four write methods to `TempTree` in `@williamthorsen/toolbelt.filesystem`: `mkdir`, `symlink`, `write`, and `writeJson`. Each takes a tree-relative path, creates the parent directories it needs, resolves through the same containment check `resolve` applies, and returns the absolute path, so a suite writing into a built temporary tree reaches it through the handle rather than through `node:fs`. `symlink` accepts a link path and a target, and picks the link type from the target.
+
+### Tests
+
+- Drop expect-type in favor of expectTypeOf (#175)
+
+  Replaces all imports of `expectTypeOf` from `expect-type` with the same import from `vitest`. Previously there had been imports from both libraries. `expect-type` is removed as a dependency.
+
 ## 0.5.0 — 2026-08-15
 
 ### Features

package/README.md

@@ -3,19 +3,19 @@
 Filesystem utilities for TypeScript and JavaScript.
 
 <!-- section:release-notes -->
-## Release notes — v0.5.0 (2026-08-15)
+## Release notes — v0.7.0 (2026-08-21)
 
 ### Features
 
-- 🚨 **Breaking:** Promote createTempTree to the candidate tier with a caller-chosen prefix and binary entries (#148)
+- 🚨 **Breaking:** Fix createTempTree's symlink guard and disposal, and complete its entry API (#207)
 
-  Promotes `createTempTree` and `TempTree` to `@williamthorsen/toolbelt.filesystem/candidate`, adding two capabilities as they move: a caller-chosen prefix for the temporary directory's name, and file contents given as bytes. A prefix that would place the tree anywhere but directly inside the system temporary directory is rejected before anything is created.
+  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.
 
-  Migration: `createTempTree` and `TempTree` are imported from `@williamthorsen/toolbelt.filesystem/candidate` rather than `/proposed`.
+  Separately, fixes an issue where disposing a `TempTree` left the tree on disk when one of its directories had been made read-only.
 
-- Add `writeAtomic`, an atomic file-write utility (#154)
+  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`.
 
-  Adds `writeAtomic` to `@williamthorsen/toolbelt.filesystem`, exported from the `/proposed` subpath. It stages content in a temp file beside the target and renames over it, so a concurrent reader sees either the previous file or the complete new one.
+  Migration: A caller relying on the previous absolute storage passes `tree.resolve(target)`, which is written unchanged.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -298,7 +298,17 @@ A prefix that would place the tree anywhere but directly inside the system tempo
 ```ts
 interface TempTree extends Disposable {
   readonly dir: string;
+  exists(entryPath: string): boolean;
+  list(entryPath?: string): string[];
+  mkdir(entryPath: string): string;
+  read(entryPath: string): string;
+  readJson(entryPath: string): unknown;
   resolve(...segments: string[]): string;
+  rm(entryPath: string): void;
+  symlink(linkPath: string, targetPath: string): string;
+  write(entryPath: string, contents: string | Uint8Array): string;
+  writeAll(entries: Record<string, string | Uint8Array>): void;
+  writeJson(entryPath: string, value: unknown): string;
 }
 ```
 
@@ -306,7 +316,57 @@ interface TempTree extends Disposable {
 
 `resolve` joins `segments` against the root and throws when the result would fall outside it, so a stray `..` fails loudly rather than reaching into the enclosing directory. An absolute segment landing inside the root is returned unchanged. The containment test is lexical, so it does not follow a symlink inside the tree that points out of it.
 
-Disposal is idempotent.
+`mkdir`, `symlink`, `write`, `writeAll`, and `writeJson` write into the tree after it is built, for a fixture that varies per test or a file created to trigger a re-read:
+
+```ts
+using tree = createTempTree({ 'packages/app/package.json': '{ "name": "app" }' });
+
+tree.write('packages/app/src/main.ts', 'export {};\n'); // '/private/var/folders/.../packages/app/src/main.ts'
+tree.writeJson('tsconfig.json', { include: ['src'] });
+tree.mkdir('packages/empty');
+```
+
+Each creates the parent directories it needs, resolves through the same containment check as `resolve`, and returns the absolute path of what it wrote. `symlink`'s link path is checked; its target is not, being a string the link holds rather than a location the tree writes to.
+
+`writeAll` takes the same map the constructor takes, `/`-suffix convention included, so a fixture built in one call can be added to in one call:
+
+```ts
+tree.writeAll({ 'packages/empty/': '', 'packages/app/src/main.ts': 'export {};\n' });
+```
+
+It returns nothing, there being no single path to return, and unlike the constructor it is not atomic: a failure part-way leaves the entries already written in place, there being no whole tree to discard.
+
+They part company on an entry that already exists: `write` replaces it, `mkdir` leaves it and its contents alone, and `symlink` raises `EEXIST`.
+
+`symlink` takes the link first and the target second, inverting `fs.symlinkSync`, so that it reads like the other methods: the path being created leads. The target is stored verbatim, so it may be absolute or relative, name something outside the tree, or dangle until the target appears; a relative one resolves against the link's own directory, as POSIX resolves it. Code under test that reads a link rather than following it therefore sees the string that was passed, which is what a consumer hashing a link's target depends on.
+
+```ts
+using tree = createTempTree({ 'store/kit/package.json': '{ "name": "kit" }' });
+
+tree.symlink('node_modules/kit', '../store/kit'); // reads back as '../store/kit'
+tree.symlink('node_modules/.bin', tree.resolve('store/kit/bin')); // reads back absolute
+```
+
+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:
+
+```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.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');
+```
+
+`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.
+
+Disposal is idempotent, and it removes a tree that has been made unwritable: unlinking an entry needs write permission on the directory containing it, so disposal restores permission across the tree and retries once before giving up. A suite that chmods a directory to exercise a write-failure path therefore needs no wrapper to chmod it back.
 
 `Disposable` is declared in `lib.esnext.disposable.d.ts` alone, so consuming this export requires `ESNext.Disposable` in your `lib`.
 

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

@@ -4,5 +4,15 @@ export interface CreateTempTreeOptions {
 }
 export interface TempTree extends Disposable {
     readonly dir: string;
+    exists(entryPath: string): boolean;
+    list(entryPath?: string): string[];
+    mkdir(entryPath: string): string;
+    read(entryPath: string): string;
+    readJson(entryPath: string): unknown;
     resolve(...segments: string[]): string;
+    rm(entryPath: string): void;
+    symlink(linkPath: string, targetPath: string): string;
+    write(entryPath: string, contents: string | Uint8Array): string;
+    writeAll(entries: Record<string, string | Uint8Array>): void;
+    writeJson(entryPath: string, value: unknown): string;
 }

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

@@ -6,28 +6,91 @@ export function createTempTree(entries, options = {}) {
     assertNamesDirectChild(prefix);
     const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
     try {
-        for (const [entry, contents] of Object.entries(entries)) {
-            const entryPath = resolveWithinTree(dir, [entry]);
+        writeAll(entries);
+    }
+    catch (error) {
+        fs.rmSync(dir, { force: true, recursive: true });
+        throw error;
+    }
+    function exists(entryPath) {
+        return fs.existsSync(resolveWithinTree(dir, [entryPath]));
+    }
+    function list(entryPath = '') {
+        return fs.readdirSync(resolveWithinTree(dir, [entryPath])).toSorted();
+    }
+    function mkdir(entryPath) {
+        const absolutePath = resolveWithinTree(dir, [entryPath]);
+        fs.mkdirSync(absolutePath, { recursive: true });
+        return absolutePath;
+    }
+    function read(entryPath) {
+        return fs.readFileSync(resolveWithinTree(dir, [entryPath]), 'utf8');
+    }
+    function readJson(entryPath) {
+        const contents = read(entryPath);
+        try {
+            return JSON.parse(contents);
+        }
+        catch (error) {
+            throw new Error(`Entry "${entryPath}" is not readable as JSON`, { cause: error });
+        }
+    }
+    function resolve(...segments) {
+        return resolveWithinTree(dir, segments);
+    }
+    function rm(entryPath) {
+        fs.rmSync(resolveWithinTree(dir, [entryPath]), { force: true, recursive: true });
+    }
+    function symlink(linkPath, targetPath) {
+        const absoluteLink = resolveWithinTree(dir, [linkPath]);
+        fs.mkdirSync(path.dirname(absoluteLink), { recursive: true });
+        fs.symlinkSync(targetPath, absoluteLink, chooseLinkType(absoluteLink, targetPath));
+        return absoluteLink;
+    }
+    function write(entryPath, contents) {
+        const absolutePath = resolveWithinTree(dir, [entryPath]);
+        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        fs.writeFileSync(absolutePath, contents);
+        return absolutePath;
+    }
+    function writeAll(newEntries) {
+        for (const [entry, contents] of Object.entries(newEntries)) {
             if (entry.endsWith('/')) {
-                fs.mkdirSync(entryPath, { recursive: true });
+                mkdir(entry);
             }
             else {
-                fs.mkdirSync(path.dirname(entryPath), { recursive: true });
-                fs.writeFileSync(entryPath, contents);
+                write(entry, contents);
             }
         }
     }
-    catch (error) {
-        fs.rmSync(dir, { force: true, recursive: true });
-        throw error;
+    function writeJson(entryPath, value) {
+        const json = JSON.stringify(value, null, 2);
+        if (json === undefined) {
+            throw new Error(`Value of type "${typeof value}" for "${entryPath}" has no JSON representation`);
+        }
+        return write(entryPath, `${json}\n`);
     }
     return {
         dir,
-        resolve(...segments) {
-            return resolveWithinTree(dir, segments);
-        },
+        exists,
+        list,
+        mkdir,
+        read,
+        readJson,
+        resolve,
+        rm,
+        symlink,
+        write,
+        writeAll,
+        writeJson,
         [Symbol.dispose]() {
-            fs.rmSync(dir, { force: true, recursive: true });
+            try {
+                fs.rmSync(dir, { force: true, recursive: true });
+            }
+            catch {
+                restoreDirectoryPermissions(dir);
+                fs.rmSync(dir, { force: true, recursive: true });
+            }
         },
     };
 }
@@ -39,6 +102,22 @@ function assertNamesDirectChild(prefix) {
         throw new Error(`Temporary-directory prefix "${prefix}" names no new directory`);
     }
 }
+function chooseLinkType(absoluteLinkPath, targetPath) {
+    const resolvedTarget = path.resolve(path.dirname(absoluteLinkPath), targetPath);
+    if (fs.statSync(resolvedTarget, { throwIfNoEntry: false })?.isDirectory() !== true) {
+        return 'file';
+    }
+    return path.isAbsolute(targetPath) ? 'junction' : 'dir';
+}
+function restoreDirectoryPermissions(dir) {
+    fs.chmodSync(dir, 0o700);
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            restoreDirectoryPermissions(path.join(dir, entry.name));
+        }
+    }
+}
 function resolveWithinTree(dir, segments) {
     const target = path.resolve(dir, ...segments);
     if (target !== dir && !target.startsWith(dir + path.sep)) {

package/package.json

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