@williamthorsen/toolbelt.filesystem 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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,13 @@
 Filesystem utilities for TypeScript and JavaScript.
 
 <!-- section:release-notes -->
-## Release notes — v0.5.0 (2026-08-15)
+## Release notes — v0.6.0 (2026-08-16)
 
 ### Features
 
-- 🚨 **Breaking:** Promote createTempTree to the candidate tier with a caller-chosen prefix and binary entries (#148)
+- Add mkdir, symlink, write, and writeJson methods to `TempTree` (#176)
 
-  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.
-
-  Migration: `createTempTree` and `TempTree` are imported from `@williamthorsen/toolbelt.filesystem/candidate` rather than `/proposed`.
-
-- Add `writeAtomic`, an atomic file-write utility (#154)
-
-  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.
+  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.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -298,7 +292,11 @@ A prefix that would place the tree anywhere but directly inside the system tempo
 ```ts
 interface TempTree extends Disposable {
   readonly dir: string;
+  mkdir(entryPath: string): string;
   resolve(...segments: string[]): string;
+  symlink(linkPath: string, targetPath: string): string;
+  write(entryPath: string, contents: string | Uint8Array): string;
+  writeJson(entryPath: string, value: unknown): string;
 }
 ```
 
@@ -306,6 +304,32 @@ 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.
 
+`mkdir`, `symlink`, `write`, 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. Both of `symlink`'s paths are checked, so an escaping target is refused as well as an escaping link.
+
+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 link type is chosen from the target, which is where the one portability difference lives. A directory is linked as a junction, which Windows creates without the elevation a directory symlink needs; every other target, one that does not exist included, is linked as a file. That last case matches what Node falls back to when no type is given, and it leaves the link dangling until the target appears.
+
+```ts
+using tree = createTempTree({ 'store/kit/package.json': '{ "name": "kit" }' });
+
+tree.symlink('node_modules/kit', 'store/kit'); // a junction, so Windows needs no elevation
+```
+
+The link stores an absolute path, which a junction requires. Code under test that reads a link rather than following it therefore sees a path under the tree root, where a package manager would have written a relative one; a fixture reproducing that shape reaches for `fs.symlinkSync` directly.
+
+`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.
 
 `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,9 @@ export interface CreateTempTreeOptions {
 }
 export interface TempTree extends Disposable {
     readonly dir: string;
+    mkdir(entryPath: string): string;
     resolve(...segments: string[]): string;
+    symlink(linkPath: string, targetPath: string): string;
+    write(entryPath: string, contents: string | Uint8Array): string;
+    writeJson(entryPath: string, value: unknown): string;
 }

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

@@ -7,13 +7,11 @@ export function createTempTree(entries, options = {}) {
     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]);
             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);
             }
         }
     }
@@ -21,11 +19,41 @@ export function createTempTree(entries, options = {}) {
         fs.rmSync(dir, { force: true, recursive: true });
         throw error;
     }
+    function mkdir(entryPath) {
+        const absolutePath = resolveWithinTree(dir, [entryPath]);
+        fs.mkdirSync(absolutePath, { recursive: true });
+        return absolutePath;
+    }
+    function resolve(...segments) {
+        return resolveWithinTree(dir, segments);
+    }
+    function symlink(linkPath, targetPath) {
+        const absoluteLink = resolveWithinTree(dir, [linkPath]);
+        const absoluteTarget = resolveWithinTree(dir, [targetPath]);
+        fs.mkdirSync(path.dirname(absoluteLink), { recursive: true });
+        fs.symlinkSync(absoluteTarget, absoluteLink, chooseLinkType(absoluteTarget));
+        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 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);
-        },
+        mkdir,
+        resolve,
+        symlink,
+        write,
+        writeJson,
         [Symbol.dispose]() {
             fs.rmSync(dir, { force: true, recursive: true });
         },
@@ -39,6 +67,9 @@ function assertNamesDirectChild(prefix) {
         throw new Error(`Temporary-directory prefix "${prefix}" names no new directory`);
     }
 }
+function chooseLinkType(targetPath) {
+    return fs.statSync(targetPath, { throwIfNoEntry: false })?.isDirectory() === true ? 'junction' : 'file';
+}
 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.6.0",
   "description": "Filesystem utilities",
   "keywords": [
     "config-cascade",