@stowage/adapter-fs 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Kaufmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @stowage/adapter-fs
+
+A storage rooted in one directory of the local file system.
+
+## Install
+
+```sh
+npm install @stowage/adapter-fs
+```
+
+## Example
+
+```ts
+import { fsStorage } from "@stowage/adapter-fs";
+
+const storage = fsStorage({ root: "/var/lib/my-app/storage" });
+
+await storage.put("reports/2026/q3.csv", "region,revenue\n");
+
+for await (const entry of storage.list({ prefix: "reports/" })) {
+  console.log(entry.key, entry.size, entry.lastModified);
+}
+```
+
+## Runtimes
+
+Node 24 and later, Bun and Deno, on Linux and macOS. `workerd` and Windows are not promised. CI last ran green on Bun 1.4.2 and Deno 2.9.6.
+
+The bundle measures 5.7 kB minified and gzipped, `@stowage/core` included.
+
+## Limits
+
+- `keyBytesPreserved` is not declared: a key comes back Unicode-equivalent to what was written
+  ([spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#49-capabilities)).
+- `presignedUrls` is not declared: `FsStorage` has neither `presignGet` nor `presignPut`
+  ([spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#49-capabilities)).
+- `userMetadata` is not declared: `put` with a non-empty `userMetadata` is `Unsupported`, and reads
+  return `{}`
+  ([spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#49-capabilities)).
+- A key segment longer than 255 bytes is `InvalidKey`, and so is a key whose whole path is longer
+  than the file system holds. macOS bounds one path at 1024 bytes with the root counted in
+  ([spec 6](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#6-stowageadapter-fs)).
+- APFS keeps a name in the Unicode form it was written in, and folds the forms when it looks a name
+  up, so a key in NFD reaches the object its NFC form wrote. A case-insensitive file system collides
+  keys that differ in case alone. Nothing repairs either
+  ([spec 6](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#6-stowageadapter-fs)).
+- The content type is derived from the key's extension, and is `application/octet-stream` where the
+  extension is unknown or absent. The `contentType` handed to `put` is not stored, so `stat` may
+  report another one
+  ([spec 6](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#6-stowageadapter-fs)).
+- No `etag` is set
+  ([spec 4.4](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#44-object-descriptions)).
+
+## Notes
+
+`put` takes no `Blob`. A caller holding one passes its stream
+([spec 4.2](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#42-bodies)):
+
+```ts
+import { fsStorage } from "@stowage/adapter-fs";
+
+const storage = fsStorage({ root: "/var/lib/my-app/storage" });
+const blob = new Blob(["region,revenue\n"], { type: "text/csv" });
+
+await storage.put("reports/2026/q4.csv", blob.stream());
+```
+
+stowage reports no progress
+([spec 11](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#11-non-goals)).
+A caller who wants it counts the bytes on their way into `put`:
+
+```ts
+import { fsStorage } from "@stowage/adapter-fs";
+
+const storage = fsStorage({ root: "/var/lib/my-app/storage" });
+
+function countBytes(report: (bytes: number) => void): TransformStream<Uint8Array, Uint8Array> {
+  let bytes = 0;
+
+  return new TransformStream({
+    transform(chunk, controller) {
+      bytes += chunk.byteLength;
+      report(bytes);
+      controller.enqueue(chunk);
+    },
+  });
+}
+
+const response = await fetch("https://example.com/video.mp4");
+
+if (response.body === null) throw new Error("The response carries no body");
+
+await storage.put("videos/intro.mp4", response.body.pipeThrough(countBytes(console.log)));
+```
+
+## Specification
+
+[`docs/spec.md` at `@stowage/adapter-fs@0.1.0`](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/docs/spec.md#6-stowageadapter-fs)
+is the contract: a caller may rely on what it states and on nothing else this package happens to
+export. The [terms it uses](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.1.0/CONTEXT.md)
+and the [decisions behind it](https://github.com/stowage-js/stowage/tree/@stowage/adapter-fs@0.1.0/docs/adr)
+are at the same tag.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { Storage } from "@stowage/core";
+//#region src/index.d.ts
+export interface FsAdapterOptions {
+  /**
+   * An absolute path to an existing directory. Construction performs no I/O, so an operation
+   * against a root that does not exist rejects with `NotFound`.
+   */
+  root: string;
+}
+export interface FsStorage extends Storage {
+  readonly provider: "fs";
+}
+export declare function fsStorage(options: FsAdapterOptions): FsStorage;
+//#endregion

package/dist/index.js

@@ -0,0 +1,1111 @@
+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 } from "@stowage/core";
+//#region src/body.ts
+const utf8$1 = 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$1.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/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 = 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.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" }],
+	["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 key names nothing this storage holds, which is what an absent file amounts to. */
+function isAbsence(thrown) {
+	const errno = errnoOf(thrown);
+	return errno === "ENOENT" || errno === "ENOTDIR";
+}
+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.
+*/
+async function prepareWrite(context) {
+	const path = pathOf(context.realRoot, context.key);
+	if (path === void 0) throw absent(context, 0);
+	const directory = await makeDirectory(dirname(path), context);
+	const target = join(directory, basename(path));
+	if (!await resolvesWithin(context, target)) throw absent(context, 1);
+	return target;
+}
+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);
+	for (const segment of missing) {
+		const path = join(existing, segment);
+		try {
+			await mkdir(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);
+	}
+	return existing;
+}
+//#endregion
+//#region src/object-file.ts
+const directoryMutationLocks = /* @__PURE__ */ new Map();
+const doNothing = () => {};
+/**
+* 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, path) {
+	try {
+		try {
+			await rename(file.path, path);
+		} catch (thrown) {
+			throw fsErrorFrom(thrown, {
+				...context,
+				access: "write"
+			});
+		}
+		await pruneEmptyDirectories(context.realRoot, dirname(file.path));
+	} finally {
+		file.release();
+	}
+}
+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);
+	};
+}
+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) {
+	if (range === void 0) return;
+	const { start, end } = range;
+	if (!isOffset(start) || end !== void 0 && (!isOffset(end) || end < start)) throw optionError(root, "range", "takes two whole numbers from zero up, `start` at most `end`", "get");
+}
+/** The last byte the range names, both ends inclusive, clipped to what the file holds. */
+function lastByteOf(root, range, size, key) {
+	if (range === void 0) return size - 1;
+	if (range.start >= size) throw fsError(root, {
+		code: "InvalidRequest",
+		message: `The range starts beyond the ${size} bytes under the key ${JSON.stringify(key)}`,
+		operation: "get",
+		key,
+		attempts: 1
+	});
+	return Math.min(range.end ?? size - 1, size - 1);
+}
+function isOffset(value) {
+	return Number.isInteger(value) && value >= 0;
+}
+//#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
+/**
+* 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, join(context.realRoot, ...directory.split("/")), directory);
+	return entries.filter((entry) => entry.key.startsWith(prefix)).toSorted(byKey);
+}
+async function collect(context, entries, directory, keyPrefix) {
+	let resolved;
+	let held;
+	try {
+		resolved = await realpath(directory);
+		if (!within(context.realRoot, resolved)) return;
+		held = await readdir(resolved, { withFileTypes: true });
+	} catch (thrown) {
+		if (isAbsence(thrown)) return;
+		throw failure(context, thrown);
+	}
+	for (const entry of held) {
+		const path = join(resolved, entry.name);
+		const key = `${keyPrefix}${entry.name}`;
+		if (entry.isDirectory()) {
+			await collect(context, entries, 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
+		});
+	}
+}
+/**
+* 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 path = await prepareWrite(context);
+		return await this.#write(context, path, body, options?.signal);
+	}
+	async #write(context, path, body, signal) {
+		return await this.#land(context, path, async (temporary) => {
+			const handle = await this.#openTemporary(context, temporary);
+			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, fill, signal) {
+		const temporary = temporaryPathIn(dirname(path));
+		try {
+			const written = await fill(temporary);
+			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: lastByteOf(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 path = await prepareWrite(ends.to);
+			return await this.#land(ends.to, path, async (temporary) => {
+				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 path = await prepareWrite(ends.to);
+			options?.signal?.throwIfAborted();
+			await renameObjectFile(ends.from, source, 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
+	};
+}
+//#endregion
+export { fsStorage };

package/package.json

@@ -1 +1,41 @@
-{"name":"@stowage/adapter-fs","version":"0.0.0","description":"Placeholder that reserves the name for trusted publishing; the first release is 0.1.0.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/stowage-js/stowage.git","directory":"packages/adapter-fs"}}
+{
+  "name": "@stowage/adapter-fs",
+  "version": "0.1.0",
+  "description": "stowage adapter rooting a storage in one directory of the local file system.",
+  "keywords": [
+    "adapter",
+    "filesystem",
+    "fs",
+    "object-storage",
+    "storage",
+    "stowage"
+  ],
+  "homepage": "https://github.com/stowage-js/stowage/tree/main/packages/adapter-fs#readme",
+  "bugs": "https://github.com/stowage-js/stowage/issues",
+  "license": "MIT",
+  "author": "Alexander Kaufmann",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stowage-js/stowage.git",
+    "directory": "packages/adapter-fs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@stowage/core": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}