@zenfs/core 2.6.2 → 2.6.4

package/dist/utils.js

@@ -51,6 +51,14 @@ export function validateFD(fd) {
         code: 'ERR_OUT_OF_RANGE',
     });
 }
+/**
+ * Whether an error means the path does not resolve to an entry. Used for `throwIfNoEntry`.
+ * @internal @hidden
+ */
+export function _isNoEntry(e) {
+    const { code } = (e ?? {});
+    return code == 'ENOENT' || code == 'ENOTDIR';
+}
 /**
  * Normalizes a time to milliseconds since the epoch.
  * Note numbers and numeric strings are seconds, like Node's `toUnixTimestamp`.
@@ -140,3 +148,12 @@ export function _tempDirName(prefix) {
     // Like Node, the prefix is a path. A relative one is resolved against the working directory, not `/tmp`.
     return `${normalizePath(prefix, true)}${Date.now()}-${Math.random().toString(36).slice(2)}`;
 }
+/**
+ * Resolves the global `Temporal`, which is not implemented by all runtimes.
+ * @internal @hidden
+ */
+export function _temporal() {
+    if ('Temporal' in globalThis && typeof globalThis.Temporal !== 'undefined')
+        return globalThis.Temporal;
+    throw withErrno('ENOTSUP', 'Temporal is not supported by this runtime');
+}

package/dist/vfs/shared.js

@@ -97,14 +97,16 @@ export function resolveMount(path, ctx, extra) {
 export function _statfs(fs, bigint) {
     const md = fs.usage();
     const bs = md.blockSize || 4096;
+    const type = bigint ? BigInt : Number;
     return {
-        type: (bigint ? BigInt : Number)(fs.type),
-        bsize: (bigint ? BigInt : Number)(bs),
-        ffree: (bigint ? BigInt : Number)(md.freeNodes || size_max),
-        files: (bigint ? BigInt : Number)(md.totalNodes || size_max),
-        bavail: (bigint ? BigInt : Number)(md.freeSpace / bs),
-        bfree: (bigint ? BigInt : Number)(md.freeSpace / bs),
-        blocks: (bigint ? BigInt : Number)(md.totalSpace / bs),
+        type: type(fs.type),
+        bsize: type(bs),
+        frsize: type(bs),
+        ffree: type(md.freeNodes || size_max),
+        files: type(md.totalNodes || size_max),
+        bavail: type(md.freeSpace / bs),
+        bfree: type(md.freeSpace / bs),
+        blocks: type(md.totalSpace / bs),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.6.2",
+	"version": "2.6.4",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -11,7 +11,9 @@
 	"keywords": [
 		"filesystem",
 		"node",
-		"storage"
+		"storage",
+		"fs",
+		"browser"
 	],
 	"bin": {
 		"make-index": "scripts/make-index.js",
@@ -44,14 +46,15 @@
 	},
 	"exports": {
 		".": "./dist/index.js",
-		"./*": "./dist/*",
+		"./*.js": "./dist/*.js",
+		"./*": "./dist/*.js",
 		"./emulation/*": "./dist/node/*",
 		"./promises": "./dist/node/promises.js",
 		"./readline": "./dist/node/readline.js",
-		"./constants": "./dist/constants.js",
-		"./path": "./dist/path.js",
 		"./eslint": "./eslint.shared.js",
-		"./tests/*": "./tests/*",
+		"./tests/*.ts": "./tests/*.ts",
+		"./tests/*.js": "./tests/*.js",
+		"./tests/*": "./tests/*.js",
 		"./types/*": "./types/*"
 	},
 	"publishConfig": {
@@ -64,25 +67,26 @@
 		"spdx:check": "npx lice -a src tests/*.ts tests/**/*.test.ts",
 		"spdx:fix": "npx lice -aw src tests/*.ts tests/**/*.test.ts",
 		"lint": "eslint src tests",
-		"test": "npx --silent zenfs-test --clean; npx --silent zenfs-test -abcp; tests/fetch/run.sh; npx --silent zenfs-test --report",
+		"test": "npx -s zenfs-test --clean; npx -s zenfs-test -abcpn; tests/fetch/run.sh; npx -s zenfs-test --report-only",
+		"test:native": "npx -s zenfs-test tests/native-setup.ts --verbose",
 		"build": "tsc -p tsconfig.json",
 		"build:docs": "typedoc",
 		"dev": "tsc -p tsconfig.json --watch",
 		"prepublishOnly": "npm run build"
 	},
 	"dependencies": {
-		"@types/node": "^25.2.0",
+		"@types/node": "^26.0.0",
 		"buffer": "^6.0.3",
 		"eventemitter3": "^5.0.1",
 		"kerium": "^1.4.2",
-		"memium": "^0.4.0",
+		"memium": "^1.0.0",
 		"readable-stream": "^4.5.2",
 		"utilium": "^3.0.0"
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
 		"@octokit/action": "^8.0.4",
-		"c8": "^11.0.0",
+		"c8": "^12.0.0",
 		"eslint": "^10.1.0",
 		"globals": "^17.3.0",
 		"prettier": "^3.2.5",

package/scripts/test.js

@@ -26,11 +26,14 @@ const { values: options, positionals } = parseArgs({
 		skip: { short: 's', type: 'string', multiple: true, default: [] },
 		'exit-on-fail': { short: 'e', type: 'boolean' },
 		runs: { short: 'r', type: 'string', default: '1' },
+		// @todo [breaking] make using node the default and remove tsx completely
+		node: { short: 'n', type: 'boolean', default: false },
 
 		// Coverage and performance
 		coverage: { type: 'string', default: 'tests/.coverage' },
 		preserve: { short: 'p', type: 'boolean' },
 		report: { type: 'boolean', default: false },
+		'report-only': { type: 'boolean', default: false },
 		clean: { type: 'boolean', default: false },
 		profile: { type: 'boolean', default: false },
 	},
@@ -42,7 +45,8 @@ const { values: options, positionals } = parseArgs({
  * @param  {...any} args
  */
 function debug(...args) {
-	if (options.debug) console.debug(styleText('dim', '[debug]'), ...args.map(a => (typeof a === 'string' ? styleText('dim', a) : a)));
+	if (options.debug || process.env.DEBUG)
+		console.debug(styleText('dim', '[debug]'), ...args.map(a => (typeof a === 'string' ? styleText('dim', a) : a)));
 }
 
 if (options.help) {
@@ -61,6 +65,7 @@ Behavior:
     -I, --inspect         Use the inspector for debugging
     -s, --skip <pattern>  Skip tests with names matching the given pattern. Can be specified multiple times.
     -d, --debug           Output debug messages from the test runner
+    -n, --node            Use plain node instead of tsx. Requires use of erasable TS syntax only
 
 Output:
     -h, --help            Outputs this help message
@@ -74,9 +79,10 @@ Output:
 Coverage:
     --coverage <dir>      Override the default coverage data directory
     -p, --preserve        Do not delete or report coverage data
-    --report              ONLY report coverage
+    --report              Report coverage along with test results
+    --report-only         ONLY report coverage
     --clean               ONLY clean up coverage directory
-	--profile             Record performance profiles`);
+    --profile             Record performance profiles`);
 	process.exit();
 }
 
@@ -105,12 +111,13 @@ function report() {
 	}
 }
 
-if (options.report) {
+if (options['report-only']) {
 	report();
 	process.exit();
 }
 
-const nRuns = Number.isSafeInteger(parseInt(options.runs)) ? parseInt(options.runs) : 1;
+const nRuns = Number.isSafeInteger(parseInt(options.runs)) ? parseInt(options.runs) : 1,
+	nodeCommand = options.node ? 'node' : 'tsx';
 
 /** @type {typeof import('./ci.js')} */
 let ci;
@@ -175,7 +182,7 @@ function makeCommand(profileName, ...rest) {
 	]
 		.filter(v => v)
 		.filter(v => typeof v == 'string');
-	if (!options.quiet) debug('command: tsx', command.join(' '));
+	if (!options.quiet) debug('command: ' + nodeCommand, command.join(' '));
 
 	return command;
 }
@@ -235,7 +242,7 @@ async function runTests(config) {
 		}
 
 		try {
-			execFileSync('tsx', command, {
+			execFileSync(nodeCommand, command, {
 				stdio: ['ignore', options.verbose ? 'inherit' : 'ignore', 'inherit'],
 			});
 			if (!options.quiet) console.log(`${styleText('green', 'passed')}${identText} ${time()}`);
@@ -283,4 +290,4 @@ for (const setupFile of positionals) {
 	});
 }
 
-if (!options.preserve) report();
+if (!options.preserve && options.report) report();

package/tests/backend/single-buffer-rotate.worker.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { parentPort, workerData } from 'node:worker_threads';
+import { SuperBlock } from '../../dist/backends/single_buffer.js';
+import { setupLogs } from '../logs.js';
+
+setupLogs('<worker>');
+
+const { buffer, gate, rotations } = workerData;
+
+const superblock = new SuperBlock(buffer);
+
+parentPort.postMessage('ready');
+
+Atomics.wait(gate, 0, 0, 1000);
+
+const offsets = [];
+for (let i = 0; i < rotations; i++) offsets.push(superblock.rotateMetadata().byteOffset);
+
+parentPort.postMessage(offsets);

package/tests/backend/single-buffer.test.ts

@@ -3,7 +3,9 @@ import assert from 'node:assert';
 import { randomBytes } from 'node:crypto';
 import { suite, test } from 'node:test';
 import { Worker } from 'worker_threads';
+import { sizeof } from 'memium';
 import { fs, mount, resolveMountConfig, SingleBuffer, vfs } from '@zenfs/core';
+import { MetadataBlock, SuperBlock } from '@zenfs/core/backends/single_buffer';
 import { setupLogs } from '../logs.js';
 
 setupLogs();
@@ -53,6 +55,88 @@ await suite('SingleBuffer', () => {
 		assert(fs.existsSync('/shared/worker-file.ts'));
 	});
 
+	test('aligns metadata when used_bytes is unaligned #309', () => {
+		// Writers reserve data of any length, so used_bytes can sit at any remainder when the metadata block is rotated.
+		for (const used of [8192n, 8193n, 8194n, 8195n]) {
+			const superblock = new SuperBlock(new ArrayBuffer(0x100000));
+			superblock.used_bytes = used;
+
+			const metadata = superblock.rotateMetadata();
+			const expected = Number((used + 3n) & ~3n);
+
+			assert.strictEqual(metadata.byteOffset, expected, `metadata offset for used_bytes ${used}`);
+			assert.strictEqual(superblock.used_bytes, BigInt(expected + sizeof(MetadataBlock)), `used_bytes after rotating from ${used}`);
+		}
+	});
+
+	test('refuses to rotate metadata past the end of the filesystem', () => {
+		const exhausted = new SuperBlock(new ArrayBuffer(sizeof(SuperBlock) + sizeof(MetadataBlock) + 4));
+		const exhaustedUsed = exhausted.used_bytes;
+
+		assert.throws(() => exhausted.rotateMetadata(), { code: 'ENOSPC' }, 'rotating without room should fail with ENOSPC');
+		assert.strictEqual(exhausted.used_bytes, exhaustedUsed, 'a failed rotation must not consume space');
+
+		const constrained = new SuperBlock(new ArrayBuffer(0x100000));
+		constrained.total_bytes = BigInt(sizeof(SuperBlock) + sizeof(MetadataBlock) + 4);
+		const constrainedUsed = constrained.used_bytes;
+
+		assert.throws(() => constrained.rotateMetadata(), { code: 'ENOSPC' }, 'rotating past total_bytes should fail with ENOSPC');
+		assert.strictEqual(constrained.used_bytes, constrainedUsed, 'a failed rotation must not consume space');
+		assert(constrained.used_bytes <= constrained.total_bytes, 'used_bytes must never exceed total_bytes');
+	});
+
+	test('concurrent rotation keeps every metadata block reachable', async () => {
+		const rotations = 100;
+		const buffer = new SharedArrayBuffer(0x200000);
+		const gate = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+
+		const superblock = new SuperBlock(buffer);
+		const original = superblock.metadata_offset;
+
+		const worker = new Worker(import.meta.dirname + '/single-buffer-rotate.worker.js', { workerData: { buffer, gate, rotations } });
+
+		const ready = Promise.withResolvers<void>();
+		const finished = Promise.withResolvers<number[]>();
+		const expired = setTimeout(() => {
+			const error = new Error('the worker did not finish rotating');
+			ready.reject(error);
+			finished.reject(error);
+		}, 1000);
+
+		worker.on('error', error => {
+			ready.reject(error);
+			finished.reject(error);
+		});
+		worker.on('message', message => (message === 'ready' ? ready.resolve() : finished.resolve(message as number[])));
+
+		try {
+			await ready.promise;
+
+			Atomics.store(gate, 0, 1);
+			Atomics.notify(gate, 0);
+
+			const mine: number[] = [];
+			for (let i = 0; i < rotations; i++) mine.push(superblock.rotateMetadata().byteOffset);
+
+			const theirs = await finished.promise;
+
+			const chain = new Set<number>();
+			for (let block: MetadataBlock | undefined = new SuperBlock(buffer).metadata; block; block = block.previous) {
+				if (chain.has(block.byteOffset)) break;
+				chain.add(block.byteOffset);
+			}
+
+			assert.strictEqual(new Set([...mine, ...theirs]).size, rotations * 2, 'two rotations reserved the same offset');
+			assert.strictEqual(chain.size, rotations * 2 + 1, 'blocks are missing from the chain');
+
+			for (const offset of [original, ...mine, ...theirs]) assert(chain.has(offset), `the block at ${offset} is not in the chain`);
+		} finally {
+			clearTimeout(expired);
+			await worker.terminate();
+			worker.unref();
+		}
+	});
+
 	test('reliability across varied file sizes', async () => {
 		const mountPoint = '/sbfs-reliability';
 		const verifyMountPoint = '/sbfs-verify';
@@ -98,4 +182,26 @@ await suite('SingleBuffer', () => {
 			vfs.umount(mountPoint);
 		}
 	});
+
+	test('keeps metadata aligned when files have uneven sizes #309', async () => {
+		const mountPoint = '/sbfs-rotation';
+		const buffer = new ArrayBuffer(0x400000);
+		const writable = await resolveMountConfig({ backend: SingleBuffer, buffer, label: 'rotation' });
+		mount(mountPoint, writable);
+
+		// Uneven writes leave used_bytes between alignment boundaries when the metadata block fills up.
+		const sizes = [1, 17, 257, 3, 5, 13, 1023, 4095, 7, 9];
+		try {
+			for (let i = 0; i < 400; i++) {
+				const content = Buffer.alloc(sizes[i % sizes.length], i & 0xff);
+				fs.writeFileSync(`${mountPoint}/f${i}.txt`, content);
+			}
+			for (let i = 0; i < 400; i += 37) {
+				const expected = Buffer.alloc(sizes[i % sizes.length], i & 0xff);
+				assert.deepStrictEqual(fs.readFileSync(`${mountPoint}/f${i}.txt`), expected, `content mismatch at f${i}.txt`);
+			}
+		} finally {
+			vfs.umount(mountPoint);
+		}
+	});
 });

package/tests/common/context.test.ts

@@ -79,6 +79,44 @@ suite('Context', () => {
 		assert.equal(ctx.realpathSync('.'), '/test');
 	});
 
+	test('globSync should keep the context', () => {
+		ctx.mkdirSync('/globbed');
+		ctx.writeFileSync('/globbed/inside.txt', 'in the context');
+
+		fs.mkdirSync('/globbed');
+		fs.writeFileSync('/globbed/outside.txt', 'not in the context');
+
+		const results = ctx.globSync('**/*.txt', { cwd: '/' });
+		assert(results.includes('globbed/inside.txt'), 'should match files in the context root');
+		assert(!results.includes('globbed/outside.txt'), 'should not match files outside the context root');
+	});
+
+	test('glob should keep the context', async () => {
+		const results = await Array.fromAsync(ctx.promises.glob('**/*.txt', { cwd: '/' }));
+
+		assert(results.includes('globbed/inside.txt'));
+		assert(!results.includes('globbed/outside.txt'), 'should not match files outside the context root');
+	});
+
+	test('glob resolves a relative cwd against the context', () => {
+		const { pwd } = context;
+		context.pwd = '/';
+
+		assert.deepEqual(ctx.globSync('*', { cwd: '/globbed' }), ['inside.txt']);
+		assert.deepEqual(ctx.globSync('*', { cwd: 'globbed' }), ['inside.txt']);
+
+		context.pwd = pwd;
+	});
+
+	test('glob defaults cwd to the working directory of the context', () => {
+		const { pwd } = context;
+		context.pwd = '/globbed';
+
+		assert.deepEqual(ctx.globSync('*'), ['inside.txt']);
+
+		context.pwd = pwd;
+	});
+
 	test('copyFileSync should keep the context #307', () => {
 		ctx.writeFileSync('/source.txt', 'not in real root!');
 		ctx.copyFileSync('/source.txt', '/copy.txt');

package/tests/common/glob.test.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
-import { fs } from '../common.js';
+import { fs } from '../common.ts';
 
 // Set up a directory structure for glob tests
 fs.mkdirSync('/glob');
@@ -13,6 +13,8 @@ fs.writeFileSync('/glob/c.js', 'c');
 fs.writeFileSync('/glob/sub/d.txt', 'd');
 fs.writeFileSync('/glob/sub/e.js', 'e');
 fs.writeFileSync('/glob/sub/deep/f.txt', 'f');
+fs.symlinkSync('sub', '/glob/link');
+fs.symlinkSync('/glob/nowhere', '/glob/dangling');
 
 suite('globSync', () => {
 	test('wildcard in root', () => {
@@ -82,6 +84,66 @@ suite('globSync', () => {
 		assert(!results.includes('glob/c.js'), 'should exclude .js files');
 		assert(results.includes('glob/a.txt'), 'should still include .txt files');
 	});
+
+	test('cwd option', () => {
+		const results = fs.globSync('*', { cwd: '/glob' });
+		assert(results.includes('a.txt'), 'results should be relative to cwd');
+		assert(results.includes('sub'));
+		assert(!results.includes('glob/a.txt'), 'results should not be relative to the root');
+	});
+
+	test('patterns are relative to cwd', () => {
+		assert.deepEqual(fs.globSync('*.txt', { cwd: '/glob/sub' }), ['d.txt']);
+		assert.deepEqual(fs.globSync('deep/*.txt', { cwd: '/glob/sub' }), ['deep/f.txt']);
+	});
+
+	test('absolute patterns are relative to cwd', () => {
+		assert.deepEqual(fs.globSync('/glob/sub/*.txt', { cwd: '/glob' }), ['sub/d.txt']);
+		assert.deepEqual(fs.globSync('/glob/sub/*.txt', { cwd: '/glob/sub' }), ['d.txt']);
+	});
+
+	test('exclude receives paths relative to cwd', () => {
+		const seen: string[] = [];
+		fs.globSync('*', {
+			cwd: '/glob',
+			exclude: path => {
+				seen.push(path);
+				return false;
+			},
+		});
+		assert(seen.includes('a.txt'), 'should be given cwd-relative paths');
+		assert(!seen.some(p => p.startsWith('/')), 'should not be given absolute paths');
+	});
+
+	test('globstar does not follow symlinks by default', () => {
+		const results = fs.globSync('/glob/**/*.txt');
+		assert(results.includes('glob/sub/d.txt'), 'should include the real directory');
+		assert(!results.includes('glob/link/d.txt'), 'should not descend into a symlinked directory');
+	});
+
+	test('followSymlinks option', () => {
+		const results = fs.globSync('/glob/**/*.txt', { followSymlinks: true });
+		assert(results.includes('glob/link/d.txt'), 'should descend into a symlinked directory');
+		assert(results.includes('glob/link/deep/f.txt'), 'should descend recursively');
+		assert(results.includes('glob/sub/d.txt'), 'should still include the real directory');
+	});
+
+	test('a symlink named by the pattern is always descended into', () => {
+		const results = fs.globSync('/glob/link/*.txt');
+		assert(results.includes('glob/link/d.txt'), 'should not need followSymlinks when the pattern names the link');
+	});
+
+	test('the symlink itself is still matched', () => {
+		for (const followSymlinks of [false, true]) {
+			const results = fs.globSync('/glob/*', { followSymlinks });
+			assert(results.includes('glob/link'), `should match the link itself (followSymlinks: ${followSymlinks})`);
+		}
+	});
+
+	test('dangling symlinks do not throw', () => {
+		const results = fs.globSync('/glob/**', { followSymlinks: true });
+		assert(results.includes('glob/dangling'), 'should match a dangling link without following it');
+	});
 });
 
 await suite('promises.glob', () => {
@@ -132,4 +194,27 @@ await suite('promises.glob', () => {
 		const results = await Array.fromAsync(fs.promises.glob('/glob/*.xyz'));
 		assert.equal(results.length, 0);
 	});
+
+	test('globstar does not follow symlinks by default', async () => {
+		const results = await Array.fromAsync(fs.promises.glob('/glob/**/*.txt'));
+		assert(results.includes('glob/sub/d.txt'));
+		assert(!results.includes('glob/link/d.txt'), 'should not descend into a symlinked directory');
+	});
+
+	test('followSymlinks option', async () => {
+		const results = await Array.fromAsync(fs.promises.glob('/glob/**/*.txt', { followSymlinks: true }));
+		assert(results.includes('glob/link/d.txt'));
+		assert(results.includes('glob/link/deep/f.txt'));
+		assert(results.includes('glob/sub/d.txt'));
+	});
+
+	test('a symlink named by the pattern is always descended into', async () => {
+		const results = await Array.fromAsync(fs.promises.glob('/glob/link/*.txt'));
+		assert(results.includes('glob/link/d.txt'));
+	});
+
+	test('dangling symlinks do not throw', async () => {
+		const results = await Array.fromAsync(fs.promises.glob('/glob/**', { followSymlinks: true }));
+		assert(results.includes('glob/dangling'));
+	});
 });

package/tests/common/utf8stream.test.ts

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { Buffer } from 'buffer';
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+import { config, fs } from '../common.ts';
+
+suite('Utf8Stream', config('write'), () => {
+	test('writes synchronously', config('sync'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-sync.log', sync: true });
+
+		assert.equal(stream.write('hello '), true);
+		assert.equal(stream.write('wörld\n'), true);
+		assert.equal(fs.readFileSync('u8-sync.log', 'utf8'), 'hello wörld\n');
+
+		stream.destroy();
+	});
+
+	test('exposes its options', config('sync'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-props.log', sync: true, minLength: 16, maxLength: 32 });
+
+		assert.equal(stream.file, 'u8-props.log');
+		assert.equal(stream.contentMode, 'utf8');
+		assert.equal(stream.sync, true);
+		assert.equal(stream.append, true);
+		assert.equal(stream.minLength, 16);
+		assert.equal(stream.maxLength, 32);
+		assert.equal(stream.periodicFlush, 0);
+		assert.equal(stream.mkdir, false);
+		assert.ok(stream.fd > 0);
+
+		stream.destroy();
+	});
+
+	test('buffers until minLength, then flushes', config('sync'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-buffered.log', sync: true, minLength: 4096 });
+
+		stream.write('buffered');
+		assert.equal(fs.readFileSync('u8-buffered.log', 'utf8'), '');
+
+		stream.flushSync();
+		assert.equal(fs.readFileSync('u8-buffered.log', 'utf8'), 'buffered');
+
+		stream.destroy();
+	});
+
+	test('truncates when append is false', config('sync'), () => {
+		fs.writeFileSync('u8-append.log', 'existing\n');
+
+		const stream = new fs.Utf8Stream({ dest: 'u8-append.log', sync: true, append: false });
+		stream.write('replaced');
+		assert.equal(fs.readFileSync('u8-append.log', 'utf8'), 'replaced');
+
+		stream.destroy();
+	});
+
+	test('writes buffers when contentMode is buffer', config('sync'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-buffer.log', sync: true, contentMode: 'buffer' });
+
+		assert.equal(stream.contentMode, 'buffer');
+		assert.throws(() => stream.write('not a buffer'), { code: 'ERR_INVALID_ARG_TYPE' });
+		stream.write(Buffer.from('hi '));
+		stream.write(Buffer.from('there'));
+		assert.equal(fs.readFileSync('u8-buffer.log', 'utf8'), 'hi there');
+
+		stream.destroy();
+	});
+
+	test('drops writes over maxLength', config('sync'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-drop.log', sync: true, maxLength: 4 });
+
+		const dropped: string[] = [];
+		stream.on('drop', data => dropped.push(data.toString()));
+
+		stream.write('12345');
+		stream.write('12');
+
+		assert.deepEqual(dropped, ['12345']);
+		assert.equal(fs.readFileSync('u8-drop.log', 'utf8'), '12');
+
+		stream.destroy();
+	});
+
+	test('reopen switches files', config('sync'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-rotate.log', sync: true, minLength: 4096 });
+
+		stream.write('before');
+		stream.flushSync();
+		stream.reopen('u8-rotated.log');
+		assert.equal(stream.file, 'u8-rotated.log');
+
+		stream.write('after');
+		stream.flushSync();
+
+		assert.equal(fs.readFileSync('u8-rotate.log', 'utf8'), 'before');
+		assert.equal(fs.readFileSync('u8-rotated.log', 'utf8'), 'after');
+
+		stream.destroy();
+	});
+
+	test('creates missing directories when mkdir is set', config('sync', 'directories'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-deep/dir/out.log', sync: true, mkdir: true });
+
+		stream.write('made it');
+		assert.equal(fs.readFileSync('u8-deep/dir/out.log', 'utf8'), 'made it');
+
+		stream.destroy();
+	});
+
+	test('writes to an existing descriptor', config('sync'), () => {
+		const fd = fs.openSync('u8-fd.log', 'w');
+		const stream = new fs.Utf8Stream({ fd, sync: true });
+
+		assert.equal(stream.fd, fd);
+		stream.write('via fd');
+		assert.equal(fs.readFileSync('u8-fd.log', 'utf8'), 'via fd');
+
+		stream.destroy();
+	});
+
+	test('throws after being destroyed', config('sync'), () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-destroyed.log', sync: true });
+		stream.destroy();
+
+		assert.throws(() => stream.write('x'), { code: 'ERR_INVALID_STATE' });
+		assert.throws(() => stream.flushSync(), { code: 'ERR_INVALID_STATE' });
+		assert.throws(() => stream.end(), { code: 'ERR_INVALID_STATE' });
+		stream.destroy(); // A second destroy is a no-op
+	});
+
+	test('validates its options', () => {
+		assert.throws(() => new fs.Utf8Stream(), { code: 'ERR_INVALID_ARG_TYPE' });
+		assert.throws(() => new fs.Utf8Stream({ dest: 'u8-invalid.log', contentMode: 'ascii' as 'utf8' }), { code: 'ERR_INVALID_ARG_VALUE' });
+		assert.throws(() => new fs.Utf8Stream({ dest: 'u8-invalid.log', minLength: 100, maxWrite: 50 }), { code: 'ERR_INVALID_ARG_VALUE' });
+		assert.throws(() => new fs.Utf8Stream({ dest: 'u8-invalid.log', sync: 'yes' as unknown as boolean }), { code: 'ERR_INVALID_ARG_TYPE' });
+		assert.throws(() => new fs.Utf8Stream({ dest: 'u8-invalid.log', fs: { write: 5 } }), { code: 'ERR_INVALID_ARG_TYPE' });
+	});
+
+	test('writes asynchronously and emits events', config('async'), async () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-async.log' });
+
+		const events: string[] = [];
+		for (const event of ['ready', 'write', 'finish', 'close'] as const) stream.on(event, () => events.push(event));
+
+		assert.equal(stream.write('async hello\n'), true);
+		stream.end();
+		await new Promise<void>(resolve => stream.on('close', () => resolve()));
+
+		assert.deepEqual(events, ['ready', 'write', 'finish', 'close']);
+		assert.equal(fs.readFileSync('u8-async.log', 'utf8'), 'async hello\n');
+	});
+
+	test('flush invokes its callback once written', config('async'), async () => {
+		const stream = new fs.Utf8Stream({ dest: 'u8-flush.log', minLength: 4096 });
+		await new Promise<void>(resolve => stream.on('ready', () => resolve()));
+
+		stream.write('flushed');
+		assert.equal(fs.readFileSync('u8-flush.log', 'utf8'), '');
+
+		await new Promise<void>((resolve, reject) => stream.flush(err => (err ? reject(err) : resolve())));
+		assert.equal(fs.readFileSync('u8-flush.log', 'utf8'), 'flushed');
+
+		stream.destroy();
+	});
+});