@stowage/adapter-fs 0.0.0 → 0.2.0

package/dist/index.js

@@ -0,0 +1,1268 @@
+import { copyFile, lstat, mkdir, open, readdir, realpath, rename, rmdir, stat, unlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, sep } from "node:path";
+import { StorageError, invalidKeyReason, isStorageError, lastByteOf, rangeBoundsRefusal, rangeStartRefusal } from "@stowage/core";
+//#region src/body.ts
+const utf8$2 = new TextEncoder();
+/**
+* Writes the body into the open file. A stream goes chunk by chunk, so that an upload of
+* any size costs one chunk of memory rather than the object.
+*/
+async function writeBody(handle, body, signal) {
+	if (isStream(body)) {
+		await body.pipeTo(new WritableStream({ async write(chunk) {
+			await writeAll(handle, chunk);
+		} }), { signal });
+		return;
+	}
+	signal?.throwIfAborted();
+	await writeAll(handle, typeof body === "string" ? utf8$2.encode(body) : body);
+}
+/** Spec 4.2 leaves a stream at its end or canceled once `put` settled, read or not. */
+async function cancelBody(body, reason) {
+	if (!isStream(body) || body.locked) return;
+	await body.cancel(reason).catch(() => {});
+}
+function isStream(body) {
+	return typeof body !== "string" && !(body instanceof Uint8Array);
+}
+async function writeAll(handle, bytes) {
+	for (let written = 0; written < bytes.byteLength;) {
+		const { bytesWritten } = await handle.write(bytes, written, bytes.byteLength - written);
+		written += bytesWritten;
+	}
+}
+//#endregion
+//#region src/content-type.ts
+const defaultContentType = "application/octet-stream";
+/**
+* The table spec 6 has the adapter derive a content type from, kept to the types a file
+* below a root is likely to carry: nothing here reads the bytes, and no dependency comes
+* into a package that promises a runtime dependency outside `@stowage` for nothing.
+*/
+const contentTypes = /* @__PURE__ */ new Map([
+	["avif", "image/avif"],
+	["css", "text/css"],
+	["csv", "text/csv"],
+	["gif", "image/gif"],
+	["gz", "application/gzip"],
+	["htm", "text/html"],
+	["html", "text/html"],
+	["ico", "image/vnd.microsoft.icon"],
+	["jpeg", "image/jpeg"],
+	["jpg", "image/jpeg"],
+	["js", "text/javascript"],
+	["json", "application/json"],
+	["md", "text/markdown"],
+	["mjs", "text/javascript"],
+	["mp3", "audio/mpeg"],
+	["mp4", "video/mp4"],
+	["otf", "font/otf"],
+	["pdf", "application/pdf"],
+	["png", "image/png"],
+	["svg", "image/svg+xml"],
+	["tar", "application/x-tar"],
+	["ttf", "font/ttf"],
+	["txt", "text/plain"],
+	["wasm", "application/wasm"],
+	["wav", "audio/wav"],
+	["webm", "video/webm"],
+	["webp", "image/webp"],
+	["woff", "font/woff"],
+	["woff2", "font/woff2"],
+	["xml", "application/xml"],
+	["yaml", "application/yaml"],
+	["yml", "application/yaml"],
+	["zip", "application/zip"]
+]);
+/** The type the key's extension names, and `application/octet-stream` for every other key. */
+function contentTypeOf(key) {
+	const name = key.slice(key.lastIndexOf("/") + 1);
+	const dot = name.lastIndexOf(".");
+	if (dot < 1) return defaultContentType;
+	return contentTypes.get(name.slice(dot + 1).toLowerCase()) ?? "application/octet-stream";
+}
+//#endregion
+//#region src/directory-lock.ts
+const directoryMutationLocks = /* @__PURE__ */ new Map();
+const doNothing = () => {};
+async function holdDirectoryMutations(realRoot) {
+	const lock = directoryMutationLocks.get(realRoot) ?? {
+		tail: Promise.resolve(),
+		leases: 0
+	};
+	const previous = lock.tail;
+	let releaseNext = doNothing;
+	lock.tail = new Promise((resolve) => {
+		releaseNext = resolve;
+	});
+	lock.leases += 1;
+	directoryMutationLocks.set(realRoot, lock);
+	await previous;
+	let held = true;
+	return () => {
+		if (!held) return;
+		held = false;
+		lock.leases -= 1;
+		releaseNext();
+		if (lock.leases === 0 && directoryMutationLocks.get(realRoot) === lock) directoryMutationLocks.delete(realRoot);
+	};
+}
+/** Runs the step with no directory below the root created or removed by anyone else. */
+async function withDirectoryMutations(realRoot, step) {
+	const release = await holdDirectoryMutations(realRoot);
+	try {
+		return await step();
+	} finally {
+		release();
+	}
+}
+//#endregion
+//#region src/cursor.ts
+const cursorTag = "stowage-fs-1:";
+const unitDigits = 4;
+const hexPosition = new RegExp(`^(?:[\\da-f]{${unitDigits}})*$`);
+/** The key a page ended on, as the opaque string that continues from there. */
+function encodeCursor(after) {
+	return btoa(`${cursorTag}${hexOf(after)}`);
+}
+/** The key the cursor continues from, or `undefined` for one this adapter did not produce. */
+function decodeCursor(cursor) {
+	let decoded;
+	try {
+		decoded = atob(cursor);
+	} catch {
+		return;
+	}
+	if (!decoded.startsWith(cursorTag)) return void 0;
+	const position = decoded.slice(13);
+	return position.length > 0 && hexPosition.test(position) ? keyOf(position) : void 0;
+}
+function hexOf(key) {
+	const units = [];
+	for (let index = 0; index < key.length; index += 1) units.push(key.charCodeAt(index).toString(16).padStart(unitDigits, "0"));
+	return units.join("");
+}
+function keyOf(position) {
+	const units = [];
+	for (let index = 0; index < position.length; index += unitDigits) units.push(String.fromCharCode(Number.parseInt(position.slice(index, index + unitDigits), 16)));
+	return units.join("");
+}
+//#endregion
+//#region src/storage-error.ts
+/** `bucket` is the root as the storage was given it, which spec 6 names as the bucket. */
+function fsError(root, fields) {
+	return new StorageError({
+		...fields,
+		bucket: root,
+		provider: "fs"
+	});
+}
+//#endregion
+//#region src/temporary.ts
+const temporaryName = /^\.stowage-[\da-f-]{36}\.tmp$/;
+/** Where the bytes of a write land before the rename that puts them under the key. */
+function temporaryPathIn(directory) {
+	return join(directory, `.stowage-${crypto.randomUUID()}.tmp`);
+}
+function isTemporaryName(name) {
+	return temporaryName.test(name);
+}
+//#endregion
+//#region src/key.ts
+/** What a file system takes as one name, which spec 6 has the adapter refuse beyond. */
+const segmentByteLimit = 255;
+const utf8$1 = new TextEncoder();
+function requireKey(root, key, rule, operation) {
+	const reason = invalidKeyReason(key, rule) ?? temporaryNameReason(key, rule) ?? longSegmentReason(key);
+	if (reason === void 0) return;
+	throw fsError(root, {
+		code: "InvalidKey",
+		message: `The key ${JSON.stringify(key)} ${reason}`,
+		operation,
+		key,
+		attempts: 0
+	});
+}
+function temporaryNameReason(key, rule) {
+	if (rule !== "writable" || !isTemporaryName(key.slice(key.lastIndexOf("/") + 1))) return;
+	return "uses the reserved .stowage temporary-file name";
+}
+function longSegmentReason(key) {
+	for (const segment of key.split("/")) {
+		const bytes = utf8$1.encode(segment).length;
+		if (bytes > segmentByteLimit) return `holds a segment of ${bytes} UTF-8 bytes, above the limit of ${segmentByteLimit}`;
+	}
+}
+//#endregion
+//#region src/options.ts
+const operationOptionKeys = ["signal"];
+const putOptionKeys = [
+	...operationOptionKeys,
+	"contentType",
+	"userMetadata"
+];
+const getOptionKeys = [...operationOptionKeys, "range"];
+const listOptionKeys = [
+	...operationOptionKeys,
+	"prefix",
+	"delimiter",
+	"pageSize",
+	"cursor"
+];
+const adapterOptionKeys = ["root"];
+/**
+* Refuses an option key the spec does not list (spec 4.3), in a call as well as in the
+* configuration a storage is constructed from. TypeScript catches one at the call site;
+* this catches the rest.
+*/
+function requireKnownOptions(root, options, known, operation) {
+	if (options === void 0) return;
+	for (const key of Object.keys(options)) {
+		if (known.includes(key)) continue;
+		throw optionError(root, key, "is not one this storage takes", operation);
+	}
+}
+function optionError(root, option, expectation, operation) {
+	return fsError(root, {
+		code: "InvalidOption",
+		message: `The option \`${option}\` ${expectation}`,
+		operation,
+		attempts: 0
+	});
+}
+//#endregion
+//#region src/listing.ts
+const defaultPageSize = 1e3;
+const maxPageSize = 1e3;
+/** `objectsBelow` walks the tree below the prefix and hands it over sorted by key. */
+function createListing(root, objectsBelow, options) {
+	return {
+		async page() {
+			const request = read(root, options);
+			options?.signal?.throwIfAborted();
+			const slice = take(await objectsBelow(request.prefix), request);
+			return {
+				objects: slice.objects,
+				prefixes: slice.prefixes,
+				cursor: slice.after === void 0 ? void 0 : encodeCursor(slice.after)
+			};
+		},
+		async *[Symbol.asyncIterator]() {
+			const request = read(root, options);
+			options?.signal?.throwIfAborted();
+			const entries = await objectsBelow(request.prefix);
+			for (let after = request.after;;) {
+				options?.signal?.throwIfAborted();
+				const slice = take(entries, {
+					...request,
+					after
+				});
+				yield* slice.objects;
+				if (slice.after === void 0) return;
+				after = slice.after;
+			}
+		}
+	};
+}
+function read(root, options) {
+	requireKnownOptions(root, options, listOptionKeys, "list");
+	const prefix = options?.prefix ?? "";
+	requireKey(root, prefix, "prefix", "list");
+	const pageSize = options?.pageSize ?? defaultPageSize;
+	if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > maxPageSize) throw optionError(root, "pageSize", `takes a whole number from 1 to ${maxPageSize}`, "list");
+	if (options?.delimiter === "") throw optionError(root, "delimiter", "takes at least one character", "list");
+	const after = options?.cursor === void 0 ? void 0 : decodeCursor(options.cursor);
+	if (options?.cursor !== void 0 && after === void 0) throw optionError(root, "cursor", "takes a cursor this storage handed out", "list");
+	return {
+		prefix,
+		delimiter: options?.delimiter,
+		pageSize,
+		after
+	};
+}
+function take(entries, request) {
+	const objects = [];
+	const prefixes = [];
+	let after;
+	for (const entry of entries) {
+		if (request.after !== void 0 && entry.key <= request.after) continue;
+		const pseudoDirectory = pseudoDirectoryOf(entry.key, request);
+		if (pseudoDirectory !== void 0 && prefixes.at(-1) === pseudoDirectory) {
+			after = entry.key;
+			continue;
+		}
+		if (objects.length + prefixes.length === request.pageSize) return {
+			objects,
+			prefixes,
+			after
+		};
+		if (pseudoDirectory === void 0) objects.push(entry);
+		else prefixes.push(pseudoDirectory);
+		after = entry.key;
+	}
+	return {
+		objects,
+		prefixes
+	};
+}
+function pseudoDirectoryOf(key, { prefix, delimiter }) {
+	if (delimiter === void 0) return void 0;
+	const end = key.indexOf(delimiter, prefix.length);
+	return end === -1 ? void 0 : key.slice(0, end + delimiter.length);
+}
+//#endregion
+//#region src/errno.ts
+const errnoMappings = /* @__PURE__ */ new Map([
+	["ENOENT", { code: "NotFound" }],
+	["EISDIR", {
+		code: "NotFound",
+		onWrite: "InvalidRequest"
+	}],
+	["ENOTDIR", {
+		code: "NotFound",
+		onWrite: "InvalidRequest"
+	}],
+	["EACCES", { code: "AccessDenied" }],
+	["EPERM", { code: "AccessDenied" }],
+	["ENAMETOOLONG", { code: "InvalidKey" }],
+	["EILSEQ", {
+		code: "NotFound",
+		onWrite: "InvalidKey"
+	}],
+	["EMFILE", {
+		code: "ProviderError",
+		retryable: true
+	}],
+	["EBUSY", {
+		code: "ProviderError",
+		retryable: true
+	}],
+	["EAGAIN", {
+		code: "ProviderError",
+		retryable: true
+	}]
+]);
+/**
+* What the file system threw, as the error spec 6 names for it. The adapter repeats
+* nothing, so the count is the one attempt the syscall made, and `retryable` says that
+* the condition may be gone rather than that anything was sent twice (spec 4.10).
+*/
+function fsErrorFrom(thrown, failure) {
+	const errno = errnoOf(thrown);
+	const mapping = errno === void 0 ? void 0 : errnoMappings.get(errno);
+	const onWrite = failure.access === "write" ? mapping?.onWrite : void 0;
+	return fsError(failure.root, {
+		code: onWrite ?? mapping?.code ?? "ProviderError",
+		message: messageOf(thrown),
+		operation: failure.operation,
+		key: failure.key,
+		attempts: 1,
+		retryable: mapping?.retryable ?? false,
+		providerCode: errno,
+		cause: thrown
+	});
+}
+/** The `errno` string of a failed syscall, which travels on as the provider code. */
+function errnoOf(thrown) {
+	if (typeof thrown !== "object" || thrown === null) return void 0;
+	const code = Reflect.get(thrown, "code");
+	return typeof code === "string" ? code : void 0;
+}
+/** The file system refuses to create the name, as APFS refuses a noncharacter (spec 6). */
+function refusesName(thrown) {
+	return errnoOf(thrown) === "EILSEQ";
+}
+/**
+* The key names nothing this storage holds, which is what an absent file amounts to, and
+* so is a name a file system refuses on a lookup: no file can be held under it.
+*/
+function isAbsence(thrown) {
+	const errno = errnoOf(thrown);
+	return errno === "ENOENT" || errno === "ENOTDIR" || errno === "EILSEQ";
+}
+function messageOf(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+/**
+* What a failed step reaches the caller as: the runtime's `AbortError` and a refusal this
+* adapter already shaped travel as they are, and everything else is read off the table
+* above (spec 4.10).
+*/
+function asFailure(thrown, failure) {
+	if (isStorageError(thrown) || nameOf(thrown) === "AbortError") return thrown;
+	return fsErrorFrom(thrown, failure);
+}
+function nameOf(thrown) {
+	if (typeof thrown !== "object" || thrown === null) return void 0;
+	const name = Reflect.get(thrown, "name");
+	return typeof name === "string" ? name : void 0;
+}
+//#endregion
+//#region src/paths.ts
+/**
+* The root as the file system resolves it, which every path an operation reaches is held
+* against. It is read afresh per operation: construction performs no I/O, and a root
+* that is gone by the time it is used is `NotFound` rather than a path of its own (spec 6).
+*/
+async function resolveRoot(root, operation, access) {
+	try {
+		return await realpath(root);
+	} catch (thrown) {
+		throw fsErrorFrom(thrown, {
+			root,
+			operation,
+			access
+		});
+	}
+}
+/** The path the key names below the root, or `undefined` where no file can carry it. */
+function pathOf(realRoot, key) {
+	const segments = key.split("/");
+	if (segments.at(-1) === "") return void 0;
+	return join(realRoot, ...segments);
+}
+function within(realRoot, path) {
+	return path === realRoot || path.startsWith(`${realRoot}${sep}`);
+}
+/**
+* The key names nothing this storage holds, which is what a read of it answers. The count
+* is what it cost to find that out: one lookup, or none where the key names no file at
+* all (spec 4.10).
+*/
+function absent(context, attempts) {
+	return fsError(context.root, {
+		code: "NotFound",
+		message: `No object under the key ${JSON.stringify(context.key)}`,
+		operation: context.operation,
+		key: context.key,
+		attempts
+	});
+}
+/**
+* The real path of the file the key names. Spec 6 has every access resolve it and answer
+* `NotFound` where it lies outside the root, so a symbolic link leaving the root behaves
+* as an absent object rather than as a way out of the storage.
+*/
+async function resolveObject(context) {
+	const path = pathOf(context.realRoot, context.key);
+	if (path === void 0) throw absent(context, 0);
+	let resolved;
+	try {
+		resolved = await realpath(path);
+	} catch (thrown) {
+		throw fsErrorFrom(thrown, {
+			...context,
+			access: "read"
+		});
+	}
+	if (!within(context.realRoot, resolved)) throw absent(context, 1);
+	return resolved;
+}
+/**
+* The path a write lands under, with the directories above it in place. The nearest
+* existing directory is resolved before anything is created, so a link leaving the root
+* cannot cause this storage to create directories outside it. The caller holds the
+* directory lock until the write's file is in place, since a prune may otherwise remove a
+* directory this found in place before anything lies in it.
+*/
+async function prepareWrite(context) {
+	const path = pathOf(context.realRoot, context.key);
+	if (path === void 0) throw absent(context, 0);
+	const { directory, created } = await makeDirectory(dirname(path), context);
+	const abandon = async () => await removeCreated(created);
+	try {
+		const target = join(directory, basename(path));
+		if (!await resolvesWithin(context, target)) throw absent(context, 1);
+		return {
+			path: target,
+			abandon
+		};
+	} catch (thrown) {
+		await abandon();
+		throw thrown;
+	}
+}
+async function removeCreated(created) {
+	for (const directory of created.toReversed()) try {
+		await rmdir(directory);
+	} catch {
+		return;
+	}
+}
+async function resolvesWithin(context, path) {
+	try {
+		return within(context.realRoot, await realpath(path));
+	} catch (thrown) {
+		if (isAbsence(thrown)) return true;
+		throw fsErrorFrom(thrown, {
+			...context,
+			access: "write"
+		});
+	}
+}
+async function makeDirectory(directory, context) {
+	const missing = [];
+	let existing = directory;
+	for (;;) try {
+		existing = await realpath(existing);
+		break;
+	} catch (thrown) {
+		if (!isAbsence(thrown)) throw fsErrorFrom(thrown, {
+			...context,
+			access: "write"
+		});
+		missing.unshift(basename(existing));
+		existing = dirname(existing);
+	}
+	if (!within(context.realRoot, existing)) throw absent(context, 1);
+	const created = [];
+	try {
+		for (const segment of missing) {
+			const path = join(existing, segment);
+			try {
+				await mkdir(path);
+				created.push(path);
+			} catch (thrown) {
+				if (errnoOf(thrown) !== "EEXIST") throw fsErrorFrom(thrown, {
+					...context,
+					access: "write"
+				});
+			}
+			try {
+				existing = await realpath(path);
+			} catch (thrown) {
+				throw fsErrorFrom(thrown, {
+					...context,
+					access: "write"
+				});
+			}
+			if (!within(context.realRoot, existing)) throw absent(context, 1);
+		}
+	} catch (thrown) {
+		await removeCreated(created);
+		throw thrown;
+	}
+	return {
+		directory: existing,
+		created
+	};
+}
+//#endregion
+//#region src/object-file.ts
+/**
+* The file below the key, or `undefined` where the key names no object of this storage:
+* nothing at all, a directory, or a path that leaves the root (spec 6). What a listing
+* passes over is what these operations find nothing under.
+*/
+async function findObjectFile(context) {
+	const release = await holdDirectoryMutations(context.realRoot);
+	try {
+		const path = pathOf(context.realRoot, context.key);
+		if (path === void 0) {
+			release();
+			return;
+		}
+		const directory = await resolveWithin(context, dirname(path));
+		if (directory === void 0) {
+			release();
+			return;
+		}
+		const target = join(directory, basename(path));
+		const held = await describe$2(context, target);
+		if (held?.isFile() !== true) {
+			release();
+			return;
+		}
+		return {
+			path: target,
+			stats: held,
+			release
+		};
+	} catch (thrown) {
+		release();
+		throw thrown;
+	}
+}
+/** Releases the parent-directory lease after a read-only use of the found object. */
+function releaseObjectFile(file) {
+	file.release();
+}
+/**
+* Removes the file and the directories it leaves empty behind it, so that a listing with
+* a delimiter names no pseudo-directory that holds nothing (spec 6).
+*/
+async function removeObjectFile(context, file) {
+	try {
+		try {
+			await unlink(file.path);
+		} catch (thrown) {
+			if (!isAbsence(thrown)) throw fsErrorFrom(thrown, {
+				...context,
+				access: "write"
+			});
+		}
+		await pruneEmptyDirectories(context.realRoot, dirname(file.path));
+	} finally {
+		file.release();
+	}
+}
+/**
+* Moves the file to the path, which is the copy and the delete of spec 4.11 as one file
+* system performs them, and removes what the source left empty behind it.
+*/
+async function renameObjectFile(context, file, destination) {
+	try {
+		await rename(file.path, destination.path);
+	} catch (thrown) {
+		throw fsErrorFrom(thrown, {
+			...refusesName(thrown) ? destination.context : context,
+			access: "write"
+		});
+	}
+	try {
+		await pruneEmptyDirectories(context.realRoot, dirname(file.path));
+	} finally {
+		file.release();
+	}
+}
+async function pruneEmptyDirectories(realRoot, directory) {
+	for (let current = directory; current !== realRoot && within(realRoot, current); current = dirname(current)) try {
+		await rmdir(current);
+	} catch {
+		return;
+	}
+}
+/** What the path holds, or `undefined` where nothing is there or a link leaves the root. */
+async function describe$2(context, path) {
+	const held = await lookUp(context, async () => await lstat(path));
+	if (held === void 0 || !held.isSymbolicLink()) return held;
+	const resolved = await resolveWithin(context, path);
+	return resolved === void 0 ? void 0 : await lookUp(context, async () => await stat(resolved));
+}
+/** The path as the file system resolves it, where that lies below the root (spec 6). */
+async function resolveWithin(context, path) {
+	const resolved = await lookUp(context, async () => await realpath(path));
+	return resolved !== void 0 && within(context.realRoot, resolved) ? resolved : void 0;
+}
+/** A lookup whose answer for a path that is not there is that nothing is there. */
+async function lookUp(context, read) {
+	try {
+		return await read();
+	} catch (thrown) {
+		if (isAbsence(thrown)) return void 0;
+		throw fsErrorFrom(thrown, {
+			...context,
+			access: "write"
+		});
+	}
+}
+//#endregion
+//#region src/range.ts
+/** Refuses bounds the spec does not allow, before the file is opened (spec 4.3). */
+function requireRange(root, range) {
+	const refusal = rangeBoundsRefusal(range);
+	if (refusal !== void 0) throw fsError(root, {
+		...refusal,
+		operation: "get",
+		attempts: 0
+	});
+}
+/** The last byte the range names, both ends inclusive, clipped to what the file holds. */
+function lastByteToRead(root, range, size, key) {
+	if (range === void 0) return size - 1;
+	const refusal = rangeStartRefusal(range, size, key);
+	if (refusal !== void 0) throw fsError(root, {
+		...refusal,
+		operation: "get",
+		key,
+		attempts: 1
+	});
+	return lastByteOf(range, size);
+}
+//#endregion
+//#region src/stored-object.ts
+const chunkSize = 65536;
+/**
+* The object `get` hands back. The file is opened where a reader is taken rather than
+* where the object was described, so a caller reading the description alone holds no
+* open file — the rename `put` lands through is what keeps that reader off a half-written
+* object (spec 6).
+*/
+function createStoredObject(context, stat, body) {
+	let read = false;
+	const take = () => {
+		if (read) throw fsError(context.root, {
+			code: "InvalidRequest",
+			message: "The body of this stored object has already been read",
+			operation: context.operation,
+			key: context.key,
+			attempts: 0
+		});
+		read = true;
+		return body;
+	};
+	const fail = (thrown) => asFailure(thrown, {
+		...context,
+		access: "read"
+	});
+	const decoder = new TextDecoder();
+	return {
+		stat,
+		stream() {
+			let taken;
+			try {
+				taken = take();
+			} catch (error) {
+				return new ReadableStream({ start(controller) {
+					controller.error(error);
+				} });
+			}
+			return readStream(taken, fail);
+		},
+		async bytes() {
+			return await readAll(take(), fail);
+		},
+		async text() {
+			return decoder.decode(await readAll(take(), fail));
+		},
+		async json() {
+			return JSON.parse(decoder.decode(await readAll(take(), fail)));
+		}
+	};
+}
+function readStream(body, fail) {
+	let handle;
+	let position = body.start;
+	return new ReadableStream({
+		async pull(controller) {
+			const left = body.end - position + 1;
+			if (left <= 0) {
+				await close(handle);
+				controller.close();
+				return;
+			}
+			const buffer = new Uint8Array(Math.min(left, chunkSize));
+			try {
+				handle ??= await openFile(body.path, fail);
+				const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, position);
+				if (bytesRead === 0) {
+					await close(handle);
+					controller.close();
+					return;
+				}
+				position += bytesRead;
+				controller.enqueue(buffer.subarray(0, bytesRead));
+			} catch (thrown) {
+				await close(handle);
+				throw fail(thrown);
+			}
+		},
+		async cancel() {
+			await close(handle);
+		}
+	});
+}
+async function readAll(body, fail) {
+	const size = Math.max(body.end - body.start + 1, 0);
+	const bytes = new Uint8Array(size);
+	const handle = await openFile(body.path, fail);
+	let read = 0;
+	try {
+		while (read < size) {
+			const { bytesRead } = await handle.read(bytes, read, size - read, body.start + read);
+			if (bytesRead === 0) break;
+			read += bytesRead;
+		}
+	} catch (thrown) {
+		throw fail(thrown);
+	} finally {
+		await close(handle);
+	}
+	return read === size ? bytes : bytes.subarray(0, read);
+}
+async function openFile(path, fail) {
+	try {
+		return await open(path, "r");
+	} catch (thrown) {
+		throw fail(thrown);
+	}
+}
+async function close(handle) {
+	await handle?.close().catch(() => {});
+}
+//#endregion
+//#region src/walk.ts
+const utf8 = new TextEncoder();
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+/**
+* Every object below the prefix, sorted by key. A listing pages through one order, so
+* the snapshot it reads is sorted; the order itself is not promised (spec 4.6).
+*/
+async function walkObjects(context, prefix) {
+	const entries = [];
+	const directory = prefix.slice(0, prefix.lastIndexOf("/") + 1);
+	await collect({
+		context,
+		entries,
+		prefix: utf8.encode(prefix)
+	}, join(context.realRoot, ...directory.split("/")), directory);
+	return entries.filter((entry) => entry.key.startsWith(prefix)).toSorted(byKey);
+}
+async function collect(walk, directory, keyPrefix) {
+	const { context, entries } = walk;
+	let resolved;
+	let held;
+	try {
+		resolved = await realpath(directory);
+		if (!within(context.realRoot, resolved)) return;
+		held = await entriesOf(resolved);
+	} catch (thrown) {
+		if (isAbsence(thrown)) return;
+		throw failure(context, thrown);
+	}
+	for (const entry of held) {
+		if ("bytes" in entry) {
+			refuseUndecodableName(walk, keyPrefix, entry.bytes);
+			continue;
+		}
+		const path = join(resolved, entry.name);
+		const key = `${keyPrefix}${entry.name}`;
+		if (entry.directory) {
+			await collect(walk, path, `${key}/`);
+			continue;
+		}
+		if (isTemporaryName(entry.name)) continue;
+		const described = await describe$1(context, path);
+		if (described !== void 0) entries.push({
+			key,
+			size: described.size,
+			lastModified: described.mtime
+		});
+	}
+}
+/**
+* The names of one level. The runtime decodes a name that is no UTF-8 with U+FFFD in
+* place of what it cannot read, so a level holding that character reads its names again
+* as bytes to tell such a name from one that holds U+FFFD as written.
+*/
+async function entriesOf(directory) {
+	const held = await readdir(directory, { withFileTypes: true });
+	if (!held.some((entry) => entry.name.includes("�"))) return held.map((entry) => ({
+		name: entry.name,
+		directory: entry.isDirectory()
+	}));
+	const names = await readdir(directory, { encoding: "buffer" });
+	const entries = [];
+	for (const bytes of names) {
+		const name = utf8NameOf(bytes);
+		if (name === void 0) {
+			entries.push({ bytes });
+			continue;
+		}
+		try {
+			entries.push({
+				name,
+				directory: (await lstat(join(directory, name))).isDirectory()
+			});
+		} catch (thrown) {
+			if (isAbsence(thrown)) continue;
+			throw thrown;
+		}
+	}
+	return entries;
+}
+function utf8NameOf(bytes) {
+	try {
+		return strictUtf8.decode(bytes);
+	} catch {
+		return;
+	}
+}
+/**
+* A name that is no UTF-8 has no key, and a key with U+FFFD in its place would reach
+* another object or none. Passing over it would let a move of the prefix lose the file
+* in silence, so a listing it falls below fails as one whose entry arrived without a key
+* (spec 4.6); a listing beside it goes on.
+*/
+function refuseUndecodableName(walk, keyPrefix, bytes) {
+	const path = new Uint8Array([...utf8.encode(keyPrefix), ...bytes]);
+	if (!startsWith(path, walk.prefix)) return;
+	throw fsError(walk.context.root, {
+		code: "ProviderError",
+		message: `The name ${escapedBytesOf(path)} is no UTF-8, so no key names it`,
+		operation: walk.context.operation,
+		attempts: 1,
+		retryable: false
+	});
+}
+function startsWith(bytes, start) {
+	return start.length <= bytes.length && start.every((byte, index) => bytes[index] === byte);
+}
+function escapedBytesOf(bytes) {
+	return `"${Array.from(bytes, (byte) => standsAsItIs(byte) ? String.fromCharCode(byte) : `\\x${byte.toString(16).toUpperCase().padStart(2, "0")}`).join("")}"`;
+}
+/** Printable ASCII but for the quote and the backslash, which would read as an escape. */
+function standsAsItIs(byte) {
+	return byte >= 32 && byte <= 126 && byte !== 34 && byte !== 92;
+}
+/**
+* What the entry holds, or `undefined` for everything that is no object: a link leaving
+* the root, a link to a directory, a socket, and a file another writer removed between
+* the listing of the level and the reading of it.
+*/
+async function describe$1(context, path) {
+	try {
+		const resolved = await realpath(path);
+		if (!within(context.realRoot, resolved)) return void 0;
+		const described = await stat(resolved);
+		return described.isFile() ? described : void 0;
+	} catch (thrown) {
+		if (isAbsence(thrown)) return void 0;
+		throw failure(context, thrown);
+	}
+}
+function failure(context, thrown) {
+	return fsErrorFrom(thrown, {
+		root: context.root,
+		operation: context.operation,
+		access: "read"
+	});
+}
+function byKey(one, other) {
+	return one.key < other.key ? -1 : one.key > other.key ? 1 : 0;
+}
+//#endregion
+//#region src/index.ts
+function fsStorage(options) {
+	return new FileSystemStorage(options);
+}
+const fsCapabilities = Object.freeze(["rangeReads"]);
+/** A storage that does not declare `userMetadata` reads back none of it (spec 4.9). */
+const noUserMetadata = Object.freeze({});
+var FileSystemStorage = class {
+	provider = "fs";
+	bucket;
+	capabilities = fsCapabilities;
+	#root;
+	constructor(options) {
+		this.#root = readRoot(options);
+		this.bucket = this.#root;
+	}
+	async put(key, body, options) {
+		try {
+			return await this.#put(key, body, options);
+		} catch (failure) {
+			await cancelBody(body, failure);
+			throw failure;
+		}
+	}
+	async #put(key, body, options) {
+		requireKey(this.#root, key, "writable", "put");
+		requireKnownOptions(this.#root, options, putOptionKeys, "put");
+		this.#requireContentType(options?.contentType);
+		this.#requireNoUserMetadata(options?.userMetadata, key);
+		options?.signal?.throwIfAborted();
+		const context = await this.#context(key, "put", "write");
+		const reserved = await withDirectoryMutations(context.realRoot, async () => await this.#reserve(context));
+		try {
+			return await this.#write(context, reserved, body, options?.signal);
+		} catch (thrown) {
+			await withDirectoryMutations(context.realRoot, reserved.prepared.abandon);
+			throw thrown;
+		}
+	}
+	/**
+	* The directories a write needs and the file its bytes land in, created while the caller
+	* holds the directory lock: once that file is there, no prune removes the directory it
+	* lies in, so the body streams in without the lock.
+	*/
+	async #reserve(context) {
+		const prepared = await prepareWrite(context);
+		const temporary = temporaryPathIn(dirname(prepared.path));
+		return {
+			prepared,
+			temporary,
+			handle: await abandoningOnFailure(prepared, async () => await this.#openTemporary(context, temporary))
+		};
+	}
+	async #write(context, { prepared, temporary, handle }, body, signal) {
+		return await this.#land(context, prepared.path, temporary, async () => {
+			try {
+				await writeBody(handle, body, signal);
+				signal?.throwIfAborted();
+				const written = await handle.stat();
+				await handle.close();
+				return written;
+			} catch (thrown) {
+				await handle.close().catch(() => {});
+				throw thrown;
+			}
+		}, signal);
+	}
+	/**
+	* Spec 6: the bytes land in a file beside the object and are renamed into place, so a
+	* reader sees the object as it was or as it now is and never half of a write. A write
+	* that broke takes its file with it, so that no listing names what never became one.
+	*/
+	async #land(context, path, temporary, fill, signal) {
+		try {
+			const written = await fill();
+			signal?.throwIfAborted();
+			await rename(temporary, path);
+			return describe(context.key, written.size, written.mtime);
+		} catch (thrown) {
+			await unlink(temporary).catch(() => {});
+			throw asFailure(thrown, {
+				...context,
+				access: "write"
+			});
+		}
+	}
+	async get(key, options) {
+		requireKey(this.#root, key, "addressable", "get");
+		requireKnownOptions(this.#root, options, getOptionKeys, "get");
+		requireRange(this.#root, options?.range);
+		options?.signal?.throwIfAborted();
+		const context = await this.#context(key, "get", "read");
+		const found = await this.#find(context);
+		return createStoredObject(context, found.description, {
+			path: found.path,
+			start: options?.range?.start ?? 0,
+			end: lastByteToRead(this.#root, options?.range, found.description.size, key)
+		});
+	}
+	async stat(key, options) {
+		requireKey(this.#root, key, "addressable", "stat");
+		requireKnownOptions(this.#root, options, operationOptionKeys, "stat");
+		options?.signal?.throwIfAborted();
+		return (await this.#find(await this.#context(key, "stat", "read"))).description;
+	}
+	async exists(key, options) {
+		requireKey(this.#root, key, "addressable", "exists");
+		requireKnownOptions(this.#root, options, operationOptionKeys, "exists");
+		options?.signal?.throwIfAborted();
+		const context = await this.#context(key, "exists", "read");
+		try {
+			await this.#find(context);
+			return true;
+		} catch (thrown) {
+			if (isStorageError(thrown) && thrown.code === "NotFound") return false;
+			throw thrown;
+		}
+	}
+	list(options) {
+		return createListing(this.#root, async (prefix) => await walkObjects({
+			root: this.#root,
+			realRoot: await resolveRoot(this.#root, "list", "read"),
+			operation: "list"
+		}, prefix), options);
+	}
+	async delete(...keys) {
+		const context = {
+			root: this.#root,
+			realRoot: await resolveRoot(this.#root, "delete", "write"),
+			operation: "delete"
+		};
+		const failed = [];
+		for (const key of keys) {
+			const failure = await this.#remove({
+				...context,
+				key
+			});
+			if (failure !== void 0) failed.push(failure);
+		}
+		return {
+			requested: keys.length,
+			failed
+		};
+	}
+	async deleteAll(prefix, options) {
+		requireKey(this.#root, prefix, "prefix", "deleteAll");
+		requireKnownOptions(this.#root, options, operationOptionKeys, "deleteAll");
+		options?.signal?.throwIfAborted();
+		const context = {
+			root: this.#root,
+			realRoot: await resolveRoot(this.#root, "deleteAll", "write"),
+			operation: "deleteAll"
+		};
+		const entries = await walkObjects(context, prefix);
+		const failed = [];
+		for (const entry of entries) {
+			options?.signal?.throwIfAborted();
+			const failure = await this.#remove({
+				...context,
+				key: entry.key
+			});
+			if (failure !== void 0) failed.push(failure);
+		}
+		return {
+			requested: entries.length,
+			failed
+		};
+	}
+	async #remove(context) {
+		try {
+			requireKey(this.#root, context.key, "addressable", context.operation);
+			const file = await findObjectFile(context);
+			if (file !== void 0) await removeObjectFile(context, file);
+			return;
+		} catch (thrown) {
+			if (isStorageError(thrown)) return thrown;
+			throw thrown;
+		}
+	}
+	async copy(from, to, options) {
+		const ends = await this.#endpoints(from, to, "copy", options);
+		const source = await this.#requireFile(ends.from);
+		try {
+			const prepared = await prepareWrite(ends.to);
+			const temporary = temporaryPathIn(dirname(prepared.path));
+			return await abandoningOnFailure(prepared, async () => await this.#land(ends.to, prepared.path, temporary, async () => {
+				await this.#read(ends.from, source.path, temporary);
+				return await stat(temporary);
+			}, options?.signal));
+		} finally {
+			releaseObjectFile(source);
+		}
+	}
+	/** Reads the source into the file the copy lands through, and names it in a failure. */
+	async #read(context, source, temporary) {
+		try {
+			await copyFile(source, temporary);
+		} catch (thrown) {
+			throw asFailure(thrown, {
+				...context,
+				access: "read"
+			});
+		}
+	}
+	async move(from, to, options) {
+		const ends = await this.#endpoints(from, to, "move", options);
+		const source = await this.#requireFile(ends.from);
+		try {
+			const prepared = await prepareWrite(ends.to);
+			await abandoningOnFailure(prepared, async () => {
+				options?.signal?.throwIfAborted();
+				await renameObjectFile(ends.from, source, {
+					context: ends.to,
+					path: prepared.path
+				});
+			});
+			return describe(to, source.stats.size, source.stats.mtime);
+		} finally {
+			releaseObjectFile(source);
+		}
+	}
+	/** Both ends of a `copy` or a `move`, once every rule of spec 4.11 has passed. */
+	async #endpoints(from, to, operation, options) {
+		requireKey(this.#root, from, "addressable", operation);
+		requireKey(this.#root, to, "writable", operation);
+		requireKnownOptions(this.#root, options, operationOptionKeys, operation);
+		options?.signal?.throwIfAborted();
+		if (from === to) throw fsError(this.#root, {
+			code: "InvalidRequest",
+			message: `The key ${JSON.stringify(from)} is both the source and the destination`,
+			operation,
+			key: from,
+			attempts: 0
+		});
+		const realRoot = await resolveRoot(this.#root, operation, "write");
+		return {
+			from: {
+				root: this.#root,
+				realRoot,
+				key: from,
+				operation
+			},
+			to: {
+				root: this.#root,
+				realRoot,
+				key: to,
+				operation
+			}
+		};
+	}
+	/** The file the source key names, which `copy` and `move` owe a `NotFound` for. */
+	async #requireFile(context) {
+		const file = await findObjectFile(context);
+		if (file !== void 0) return file;
+		throw absent(context, context.key.endsWith("/") ? 0 : 1);
+	}
+	/** The file the key names, described as spec 4.4 has a read of one describe it. */
+	async #find(context) {
+		const path = await resolveObject(context);
+		try {
+			const described = await stat(path);
+			if (!described.isFile()) throw absent(context, 1);
+			return {
+				path,
+				description: describe(context.key, described.size, described.mtime)
+			};
+		} catch (thrown) {
+			throw asFailure(thrown, {
+				...context,
+				access: "read"
+			});
+		}
+	}
+	async #context(key, operation, access) {
+		return {
+			root: this.#root,
+			realRoot: await resolveRoot(this.#root, operation, access),
+			key,
+			operation
+		};
+	}
+	async #openTemporary(context, path) {
+		try {
+			return await open(path, "wx");
+		} catch (thrown) {
+			throw asFailure(thrown, {
+				...context,
+				access: "write"
+			});
+		}
+	}
+	/** Spec 6 validates the type `put` was given and derives the stored one from the key. */
+	#requireContentType(contentType) {
+		if (contentType === void 0 || typeof contentType === "string") return;
+		throw optionError(this.#root, "contentType", "takes a string", "put");
+	}
+	#requireNoUserMetadata(userMetadata, key) {
+		if (userMetadata === void 0 || Object.keys(userMetadata).length === 0) return;
+		throw fsError(this.#root, {
+			code: "Unsupported",
+			message: "This storage holds no user metadata",
+			operation: "put",
+			key,
+			attempts: 0,
+			capability: "userMetadata"
+		});
+	}
+};
+function readRoot(options) {
+	const root = options.root;
+	const named = typeof root === "string" ? root : "";
+	requireKnownOptions(named, options, adapterOptionKeys, "fsStorage");
+	if (typeof root !== "string" || !isAbsolute(root)) throw optionError(named, "root", "takes an absolute path to a directory", "fsStorage");
+	return root;
+}
+function describe(key, size, lastModified) {
+	return {
+		key,
+		size,
+		lastModified,
+		contentType: contentTypeOf(key),
+		userMetadata: noUserMetadata
+	};
+}
+async function abandoningOnFailure(prepared, write) {
+	try {
+		return await write();
+	} catch (thrown) {
+		await prepared.abandon();
+		throw thrown;
+	}
+}
+//#endregion
+export { fsStorage };