@williamthorsen/toolbelt.filesystem 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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
+
+- 🚨 **Breaking:** Promote createTempTree to the candidate tier with a caller-chosen prefix and binary entries (#148)
+
+  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.
+
 ## 0.4.1 — 2026-08-13
 
 ### Tooling

package/README.md

@@ -2,7 +2,15 @@
 
 Filesystem utilities for TypeScript and JavaScript.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.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.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -12,7 +20,7 @@ pnpm add @williamthorsen/toolbelt.filesystem
 
 ## Runtime requirements
 
-`createTempTree`, `findDirectoryChainMatch`, `listDirectoryChainMatches`, `loadConfigCascade`, `reconcileFile`, and `reconcileFileFromFile` reach the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem. `listDirectoryChain` and `replaceFileExtension` touch no filesystem, so an edge runtime that exposes none runs them; they still import `node:path`, which a browser bundle has to supply.
+`createTempTree`, `findDirectoryChainMatch`, `listDirectoryChainMatches`, `loadConfigCascade`, `reconcileFile`, `reconcileFileFromFile`, and `writeAtomic` reach the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem. `listDirectoryChain` and `replaceFileExtension` touch no filesystem, so an edge runtime that exposes none runs them; they still import `node:path`, which a browser bundle has to supply.
 
 `loadConfigCascade` imports each config through the host runtime, so a `.ts` config is subject to whatever that runtime does with TypeScript. Node strips types rather than compiling them, which admits erasable syntax alone: an `enum`, a `namespace`, or a parameter property in a config file fails to parse. A `.mjs` or `.js` config sidesteps the question.
 
@@ -98,7 +106,7 @@ findDirectoryChainMatch('/home/dev/app/src', ['.git']);
 // { dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }
 ```
 
-Probing stops at the first level that matches, so no level beyond it is touched — the reason to reach for this rather than read element zero off `listDirectoryChainMatches`, which probes to the ceiling regardless. The nullable return type is the other reason: a result that may be absent says so, where an array leaves the caller to narrow.
+Probing stops at the first level that matches, so no level beyond it is touched -- the reason to reach for this rather than read element zero off `listDirectoryChainMatches`, which probes to the ceiling regardless. The nullable return type is the other reason: a result that may be absent says so, where an array leaves the caller to narrow.
 
 ## `loadConfigCascade`
 
@@ -241,16 +249,16 @@ The source is read even under `isDryRun`, because the outcome depends on compari
 
 ## `createTempTree`
 
-Proposed tier: imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
+Candidate tier: imported from `@williamthorsen/toolbelt.filesystem/candidate` rather than the package root, and subject to change.
 
 ```ts
-createTempTree(entries: Record<string, string>): TempTree;
+createTempTree(entries: Record<string, string | Uint8Array>, options?: { prefix?: string }): TempTree;
 ```
 
 Builds a throwaway directory tree and returns a handle that removes it when the binding leaves scope:
 
 ```ts
-import { createTempTree } from '@williamthorsen/toolbelt.filesystem/proposed';
+import { createTempTree } from '@williamthorsen/toolbelt.filesystem/candidate';
 
 {
   using tree = createTempTree({
@@ -266,10 +274,29 @@ import { createTempTree } from '@williamthorsen/toolbelt.filesystem/proposed';
 
 Each key of `entries` is a path relative to the tree root. One ending in `/` becomes a directory; any other becomes a file holding the mapped contents, with its intermediate directories created for it. A key resolving outside the root is rejected, and a call that throws leaves nothing on disk.
 
+A value is text or the bytes themselves, so a body no UTF-8 round trip survives is as writable as a string:
+
+```ts
+using tree = createTempTree({ 'logo.png': pngBytes });
+```
+
+`prefix` names the directory built under the system temporary directory, defaulting to `toolbelt-`. Set it to whatever is doing the building, so a tree outliving a crashed run says what made it:
+
+```ts
+using tree = createTempTree({}, { prefix: 'rdy-tsconfig-' });
+tree.dir; // '/private/var/folders/.../rdy-tsconfig-a1b2c3'
+```
+
+A prefix that would place the tree anywhere but directly inside the system temporary directory is rejected before anything is created. `mkdtemp` appends its random suffix to the joined path as given, so a prefix holding `/` or `\` targets a nested directory that has to already exist, or, where it ascends, a directory outside the temporary one; and a prefix that normalizes away (`''`, `'.'`, or `'..'`) lands the suffix beside the temporary directory rather than within it.
+
 ```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;
 }
 ```
 
@@ -277,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`.
@@ -308,3 +361,31 @@ replaceFileExtension('src/main.d.ts', '.js', { oldExtension: '.d.ts' }); // 'src
 Which extension is meant is genuinely ambiguous, since `archive.tar.gz` could reasonably end in `.gz` or in `.tar.gz`, so the caller declares it rather than the function guessing.
 
 Two inputs throw rather than returning a path that would quietly be wrong: a `filePath` ending in a separator, which names a directory rather than a file, and a `filePath` that does not end with a declared `oldExtension`.
+
+## `writeAtomic`
+
+Proposed tier: imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
+
+```ts
+writeAtomic(filePath: string, content: string | Uint8Array): Promise<void>;
+```
+
+Writes `content` to `filePath` through a temp file and a rename, so a concurrent reader sees either the previous file or the complete new one, never a partial write:
+
+```ts
+import { writeAtomic } from '@williamthorsen/toolbelt.filesystem/proposed';
+
+await writeAtomic('.agents/manifest.json', `${JSON.stringify(manifest, null, 2)}\n`);
+```
+
+The temp file is a sibling of the target, which is the part a hand-rolled copy most often gets wrong: `rename` is atomic only within one filesystem, so a temp file staged under the system temporary directory fails with `EXDEV` the moment the target lives on another volume. Its name is dot-prefixed and carries a random component, so it stays out of `*` globs and two processes writing the same target do not collide.
+
+Missing parent directories are created, as they are for [`reconcileFile`](#reconcilefile).
+
+An existing target's permission bits are carried onto the replacement. A plain `writeFile` truncates the file in place and so preserves its mode, while a rename replaces the inode and would otherwise reset it to the platform default; without this, swapping a plain write for an atomic one would silently widen a `0o600` file to world-readable. A target that does not exist yet gets the platform default, exactly as a plain write would.
+
+Three behaviors are worth knowing before they surprise you:
+
+- Nothing is fsynced. "Atomic" here means no torn reads, not survives-power-loss: a write this function has returned from can still be lost to a power failure. A durability option is additive if a caller ever needs one.
+- A symlink at `filePath` is replaced by a regular file rather than written through, because the rename replaces the target's directory entry. The link's former target is left untouched.
+- A failure removes the temp file best-effort and rethrows the error that caused it, never the cleanup's own. Where the cleanup also fails, the temp file survives beside the target under its dot-prefixed name ending in `.tmp`, which is where to look for one.

package/dist/esm/1-proposed/index.d.ts

@@ -1,2 +1,2 @@
-export { createTempTree, type TempTree } from './createTempTree.js';
 export { replaceFileExtension, type ReplaceFileExtensionOptions } from './replaceFileExtension.js';
+export { writeAtomic } from './writeAtomic.js';

package/dist/esm/1-proposed/index.js

@@ -1,2 +1,2 @@
-export { createTempTree } from "./createTempTree.js";
 export { replaceFileExtension } from "./replaceFileExtension.js";
+export { writeAtomic } from "./writeAtomic.js";

package/dist/esm/1-proposed/writeAtomic.d.ts

@@ -0,0 +1 @@
+export declare function writeAtomic(filePath: string, content: string | Uint8Array): Promise<void>;

package/dist/esm/1-proposed/writeAtomic.js

@@ -0,0 +1,32 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function writeAtomic(filePath, content) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const mode = await findFileMode(filePath);
+    const tempPath = path.join(dir, `.${path.basename(filePath)}.${randomBytes(8).toString('hex')}.tmp`);
+    try {
+        await fs.writeFile(tempPath, content, { mode });
+        if (mode !== undefined)
+            await fs.chmod(tempPath, mode);
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            await fs.rm(tempPath, { force: true });
+        }
+        catch {
+        }
+        throw error;
+    }
+}
+async function findFileMode(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.mode & 0o777;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,12 @@
+export declare function createTempTree(entries: Record<string, string | Uint8Array>, options?: CreateTempTreeOptions): TempTree;
+export interface CreateTempTreeOptions {
+    prefix?: string;
+}
+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

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function createTempTree(entries, options = {}) {
+    const { prefix = 'toolbelt-' } = options;
+    assertNamesDirectChild(prefix);
+    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+    try {
+        for (const [entry, contents] of Object.entries(entries)) {
+            if (entry.endsWith('/')) {
+                mkdir(entry);
+            }
+            else {
+                write(entry, contents);
+            }
+        }
+    }
+    catch (error) {
+        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,
+        mkdir,
+        resolve,
+        symlink,
+        write,
+        writeJson,
+        [Symbol.dispose]() {
+            fs.rmSync(dir, { force: true, recursive: true });
+        },
+    };
+}
+function assertNamesDirectChild(prefix) {
+    if (prefix.includes('/') || prefix.includes('\\')) {
+        throw new Error(`Temporary-directory prefix "${prefix}" contains a path separator`);
+    }
+    if (['', '.', '..'].includes(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)) {
+        throw new Error(`Path "${target}" falls outside the temporary tree at "${dir}"`);
+    }
+    return target;
+}

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

@@ -1 +1 @@
-export {};
+export { createTempTree, type CreateTempTreeOptions, type TempTree } from './createTempTree.js';

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

@@ -1 +1 @@
-export {};
+export { createTempTree } from "./createTempTree.js";

package/package.json

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

package/dist/esm/1-proposed/createTempTree.d.ts

@@ -1,5 +0,0 @@
-export declare function createTempTree(entries: Record<string, string>): TempTree;
-export interface TempTree extends Disposable {
-    readonly dir: string;
-    resolve(...segments: string[]): string;
-}

package/dist/esm/1-proposed/createTempTree.js

@@ -1,38 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-export function createTempTree(entries) {
-    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'toolbelt-')));
-    try {
-        for (const [entry, contents] of Object.entries(entries)) {
-            const entryPath = resolveWithinTree(dir, [entry]);
-            if (entry.endsWith('/')) {
-                fs.mkdirSync(entryPath, { recursive: true });
-            }
-            else {
-                fs.mkdirSync(path.dirname(entryPath), { recursive: true });
-                fs.writeFileSync(entryPath, contents);
-            }
-        }
-    }
-    catch (error) {
-        fs.rmSync(dir, { force: true, recursive: true });
-        throw error;
-    }
-    return {
-        dir,
-        resolve(...segments) {
-            return resolveWithinTree(dir, segments);
-        },
-        [Symbol.dispose]() {
-            fs.rmSync(dir, { force: true, recursive: true });
-        },
-    };
-}
-function resolveWithinTree(dir, segments) {
-    const target = path.resolve(dir, ...segments);
-    if (target !== dir && !target.startsWith(dir + path.sep)) {
-        throw new Error(`Path "${target}" falls outside the temporary tree at "${dir}"`);
-    }
-    return target;
-}