@williamthorsen/toolbelt.filesystem 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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,21 @@
 
 Filesystem utilities for TypeScript and JavaScript.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.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.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -12,7 +26,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 +112,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 +255,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,6 +280,21 @@ 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;
@@ -308,3 +337,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/{1-proposed → 3-candidate}/createTempTree.d.ts

@@ -1,4 +1,7 @@
-export declare function createTempTree(entries: Record<string, string>): TempTree;
+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;
     resolve(...segments: string[]): string;

package/dist/esm/{1-proposed → 3-candidate}/createTempTree.js

@@ -1,8 +1,10 @@
 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-')));
+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)) {
             const entryPath = resolveWithinTree(dir, [entry]);
@@ -29,6 +31,14 @@ export function createTempTree(entries) {
         },
     };
 }
+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 resolveWithinTree(dir, segments) {
     const target = path.resolve(dir, ...segments);
     if (target !== dir && !target.startsWith(dir + path.sep)) {

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.5.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"