@stowage/adapter-fs 0.0.0 → 0.2.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,113 @@
+# @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.2.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.2.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.2.0/docs/spec.md#49-capabilities)).
+- `userMetadataTokenKeys` is not declared: without `userMetadata`, a key beyond identifiers is
+  `Unsupported` naming `userMetadata` like any other
+  ([spec 4.9](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.2.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.2.0/docs/spec.md#6-stowageadapter-fs)).
+- A name the file system refuses to create is `InvalidKey` on `put` and on the destination of
+  `copy` and `move`. APFS refuses every noncharacter, so a key holding `U+FFFE` is written on
+  Linux and refused on macOS
+  ([spec 6](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.2.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.2.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.2.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.2.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.2.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 12](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.2.0/docs/spec.md#12-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.2.0`](https://github.com/stowage-js/stowage/blob/@stowage/adapter-fs@0.2.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.2.0/CONTEXT.md)
+and the [decisions behind it](https://github.com/stowage-js/stowage/tree/@stowage/adapter-fs@0.2.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