@nwire/storage-fs 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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,65 @@
+# @nwire/storage-fs
+
+> Local filesystem adapter for `@nwire/storage` — dev / single-node only.
+
+## What it does
+
+Implements the `Storage` contract by writing files under a base directory. Keys map to relative paths under `baseDir`; paths that would escape `baseDir` are rejected (no `..` traversal). `url()` returns a `file://` URL — not presigned. For client-side fetches, proxy `/files/:key` through an HTTP wire to `fsStorage.getStream(key)`.
+
+## Install
+
+```bash
+pnpm add @nwire/storage-fs @nwire/storage
+```
+
+## Quick start
+
+```ts
+import { fsStorage } from "@nwire/storage-fs";
+import { storagePlugin } from "@nwire/storage";
+import { defineApp } from "@nwire/forge";
+
+defineApp("my-app", {
+  plugins: [
+    storagePlugin({
+      storage: fsStorage({ baseDir: "./var/uploads" }),
+    }),
+  ],
+});
+```
+
+## API surface
+
+- `fsStorage({ baseDir })` — implements `Storage`.
+
+## When to use
+
+Local development without infra, single-node deployments where local disk is fine, tests that want real I/O. Don't use on multi-node deployments — no shared storage.
+
+## Standalone use
+
+For developers using `@nwire/storage-fs` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/storage-fs";
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```
+
+## See also
+
+- [Architecture sketch §05 — Adapters tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/storage](../nwire-storage), [@nwire/storage-s3](../nwire-storage-s3)

package/dist/__tests__/storage-fs.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@nwire/storage-fs` — verifies the fs adapter against a temp dir.
+ * Same shape as the InMemoryStorage contract tests so we're checking
+ * adapter parity, not just file I/O.
+ */
+export {};
+//# sourceMappingURL=storage-fs.test.d.ts.map

package/dist/__tests__/storage-fs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-fs.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/storage-fs.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/__tests__/storage-fs.test.js

@@ -0,0 +1,79 @@
+/**
+ * `@nwire/storage-fs` — verifies the fs adapter against a temp dir.
+ * Same shape as the InMemoryStorage contract tests so we're checking
+ * adapter parity, not just file I/O.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fsStorage } from "../storage-fs";
+import { StorageObjectNotFoundError, StorageUnsupportedError } from "@nwire/storage";
+describe("fsStorage", () => {
+    let dir;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "nwire-storage-fs-"));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("put + get round-trips body + metadata via sidecar", async () => {
+        const s = fsStorage({ baseDir: dir });
+        await s.put("a/b.txt", "hello", {
+            contentType: "text/plain",
+            metadata: { uploader: "alice" },
+        });
+        const obj = await s.get("a/b.txt");
+        expect(obj.body.toString("utf-8")).toBe("hello");
+        expect(obj.contentType).toBe("text/plain");
+        expect(obj.metadata?.uploader).toBe("alice");
+    });
+    it("get throws StorageObjectNotFoundError when the file doesn't exist", async () => {
+        const s = fsStorage({ baseDir: dir });
+        await expect(s.get("nope.txt")).rejects.toBeInstanceOf(StorageObjectNotFoundError);
+    });
+    it("exists + delete round-trip", async () => {
+        const s = fsStorage({ baseDir: dir });
+        expect(await s.exists("x")).toBe(false);
+        await s.put("x", "y");
+        expect(await s.exists("x")).toBe(true);
+        await s.delete("x");
+        expect(await s.exists("x")).toBe(false);
+    });
+    it("list returns relative keys sorted", async () => {
+        const s = fsStorage({ baseDir: dir });
+        await s.put("posts/a", "1");
+        await s.put("posts/b", "2");
+        await s.put("users/x", "3");
+        const page = await s.list("posts/");
+        expect(page.entries.map((e) => e.key).sort()).toEqual(["posts/a", "posts/b"]);
+    });
+    it("getStream emits the body bytes", async () => {
+        const s = fsStorage({ baseDir: dir });
+        await s.put("stream.txt", "abc");
+        const stream = await s.getStream("stream.txt");
+        const chunks = [];
+        for await (const c of stream)
+            chunks.push(c);
+        expect(Buffer.concat(chunks).toString("utf-8")).toBe("abc");
+    });
+    it("rejects key traversal attempts", async () => {
+        const s = fsStorage({ baseDir: dir });
+        await expect(s.put("../escape.txt", "x")).rejects.toThrow(/escapes baseDir/);
+    });
+    it("url returns file:// for method=get", async () => {
+        const s = fsStorage({ baseDir: dir });
+        await s.put("a", "x");
+        const url = await s.url("a");
+        expect(url.startsWith("file://")).toBe(true);
+    });
+    it("url throws StorageUnsupportedError for method=put", async () => {
+        const s = fsStorage({ baseDir: dir });
+        await expect(s.url("a", { method: "put" })).rejects.toBeInstanceOf(StorageUnsupportedError);
+    });
+    it("healthCheck creates the base dir if missing", async () => {
+        const s = fsStorage({ baseDir: join(dir, "nested", "fresh") });
+        await expect(s.healthCheck()).resolves.toBeUndefined();
+    });
+});
+//# sourceMappingURL=storage-fs.test.js.map

package/dist/__tests__/storage-fs.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-fs.test.js","sourceRoot":"","sources":["../../src/__tests__/storage-fs.test.ts"],"names":[],"mappings":"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"}

package/dist/storage-fs.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `@nwire/storage-fs` — local filesystem adapter.
+ *
+ * Implements the Storage contract by writing files under a base
+ * directory. Keys are mapped to relative paths under `baseDir`; paths
+ * that would escape `baseDir` are rejected (no `..` traversal).
+ *
+ * Use it for:
+ *   - development without infra setup
+ *   - single-node deployments where local disk is fine
+ *   - tests that want real I/O instead of in-memory
+ *
+ * Don't use it for:
+ *   - anything that runs on more than one node (no sharing)
+ *   - large-scale uploads (no concurrency story beyond ext4)
+ *
+ *   import { fsStorage }     from "@nwire/storage-fs";
+ *   import { storagePlugin } from "@nwire/storage";
+ *
+ *   defineApp("my-app", {
+ *     plugins: [storagePlugin({
+ *       storage: fsStorage({ baseDir: "./var/uploads" }),
+ *     })],
+ *   });
+ *
+ * `url()` returns a `file://` URL. It's NOT a presigned URL — the file
+ * isn't directly fetchable by browsers from a remote host. If you need
+ * client-side fetches, run an HTTP wire that proxies `/files/:key` to
+ * `fsStorage.getStream(key)`.
+ */
+import { type Storage } from "@nwire/storage";
+export interface FsStorageOptions {
+    /** Base directory where keys are stored. Created if missing. */
+    readonly baseDir: string;
+    /**
+     * Persist content-type + metadata in a sidecar `.meta.json`?
+     * Default `true`. Set false to avoid extra files when metadata isn't used.
+     */
+    readonly persistMetadata?: boolean;
+}
+export declare function fsStorage(options: FsStorageOptions): Storage;
+//# sourceMappingURL=storage-fs.d.ts.map

package/dist/storage-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-fs.d.ts","sourceRoot":"","sources":["../src/storage-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,EAGL,KAAK,OAAO,EASb,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAE5D"}

package/dist/storage-fs.js

@@ -0,0 +1,203 @@
+/**
+ * `@nwire/storage-fs` — local filesystem adapter.
+ *
+ * Implements the Storage contract by writing files under a base
+ * directory. Keys are mapped to relative paths under `baseDir`; paths
+ * that would escape `baseDir` are rejected (no `..` traversal).
+ *
+ * Use it for:
+ *   - development without infra setup
+ *   - single-node deployments where local disk is fine
+ *   - tests that want real I/O instead of in-memory
+ *
+ * Don't use it for:
+ *   - anything that runs on more than one node (no sharing)
+ *   - large-scale uploads (no concurrency story beyond ext4)
+ *
+ *   import { fsStorage }     from "@nwire/storage-fs";
+ *   import { storagePlugin } from "@nwire/storage";
+ *
+ *   defineApp("my-app", {
+ *     plugins: [storagePlugin({
+ *       storage: fsStorage({ baseDir: "./var/uploads" }),
+ *     })],
+ *   });
+ *
+ * `url()` returns a `file://` URL. It's NOT a presigned URL — the file
+ * isn't directly fetchable by browsers from a remote host. If you need
+ * client-side fetches, run an HTTP wire that proxies `/files/:key` to
+ * `fsStorage.getStream(key)`.
+ */
+import { promises as fs, createReadStream } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { StorageObjectNotFoundError, StorageUnsupportedError, } from "@nwire/storage";
+export function fsStorage(options) {
+    return new FsStorage(resolve(options.baseDir), options.persistMetadata ?? true);
+}
+class FsStorage {
+    baseDir;
+    persistMetadata;
+    constructor(baseDir, persistMetadata) {
+        this.baseDir = baseDir;
+        this.persistMetadata = persistMetadata;
+    }
+    /**
+     * Resolve a key to an absolute path UNDER baseDir. Rejects traversal
+     * via `..` segments or any other route that lands outside the base.
+     */
+    path(key) {
+        const full = resolve(this.baseDir, key);
+        if (full !== this.baseDir && !full.startsWith(this.baseDir + sep)) {
+            throw new Error(`Refusing key that escapes baseDir: ${key}`);
+        }
+        return full;
+    }
+    metaPath(key) {
+        return this.path(key) + ".meta.json";
+    }
+    async put(key, body, opts) {
+        const target = this.path(key);
+        await fs.mkdir(dirname(target), { recursive: true });
+        const buf = toBuffer(body);
+        await fs.writeFile(target, buf);
+        if (this.persistMetadata && (opts?.contentType || opts?.cacheControl || opts?.metadata)) {
+            const sidecar = {
+                contentType: opts?.contentType,
+                cacheControl: opts?.cacheControl,
+                metadata: opts?.metadata ? { ...opts.metadata } : undefined,
+            };
+            await fs.writeFile(this.metaPath(key), JSON.stringify(sidecar));
+        }
+        return { key, size: buf.byteLength };
+    }
+    async get(key) {
+        const target = this.path(key);
+        let body;
+        try {
+            body = await fs.readFile(target);
+        }
+        catch (err) {
+            throw translateError(err, key);
+        }
+        const meta = await this.readMetadata(key);
+        const stats = await fs.stat(target);
+        return {
+            key,
+            body,
+            contentType: meta?.contentType,
+            size: stats.size,
+            metadata: meta?.metadata,
+        };
+    }
+    async getStream(key) {
+        const target = this.path(key);
+        try {
+            await fs.access(target);
+        }
+        catch (err) {
+            throw translateError(err, key);
+        }
+        return createReadStream(target);
+    }
+    async delete(key) {
+        const target = this.path(key);
+        await fs.rm(target, { force: true });
+        if (this.persistMetadata)
+            await fs.rm(this.metaPath(key), { force: true });
+    }
+    async exists(key) {
+        try {
+            await fs.access(this.path(key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async list(prefix, opts) {
+        const root = prefix ? this.path(prefix) : this.baseDir;
+        const limit = opts?.limit ?? 1000;
+        const cursor = opts?.cursor;
+        const keys = [];
+        await walk(root, async (full) => {
+            if (full.endsWith(".meta.json"))
+                return;
+            const rel = full.slice(this.baseDir.length + 1).split(sep).join("/");
+            // The `prefix` argument is a prefix-match on keys; honor it when
+            // root is the base dir (caller passed an unanchored prefix).
+            if (prefix && !rel.startsWith(prefix))
+                return;
+            keys.push(rel);
+        });
+        keys.sort();
+        const startAt = cursor ? keys.findIndex((k) => k > cursor) : 0;
+        const slice = keys.slice(Math.max(0, startAt), Math.max(0, startAt) + limit);
+        const entries = await Promise.all(slice.map(async (k) => {
+            const stats = await fs.stat(this.path(k));
+            return { key: k, size: stats.size, modifiedAt: stats.mtime };
+        }));
+        const last = entries.at(-1)?.key;
+        const more = last && keys.indexOf(last) < keys.length - 1;
+        return { entries, nextCursor: more ? last : undefined };
+    }
+    /**
+     * fs doesn't speak presigned URLs. We return `file://` for completeness
+     * (useful for tests and local tooling), but for `method: "put"` we
+     * throw — there's no sane "client uploads directly here" story over fs.
+     */
+    async url(key, opts) {
+        if ((opts?.method ?? "get") === "put") {
+            throw new StorageUnsupportedError("fsStorage doesn't support presigned PUT URLs — clients can't upload " +
+                "directly to a server file path. Mount a real HTTP upload endpoint instead.");
+        }
+        return pathToFileURL(this.path(key)).toString();
+    }
+    async healthCheck() {
+        await fs.mkdir(this.baseDir, { recursive: true });
+        await fs.access(this.baseDir);
+    }
+    async readMetadata(key) {
+        if (!this.persistMetadata)
+            return undefined;
+        try {
+            const raw = await fs.readFile(this.metaPath(key), "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function toBuffer(body) {
+    if (Buffer.isBuffer(body))
+        return body;
+    if (typeof body === "string")
+        return Buffer.from(body, "utf-8");
+    return Buffer.from(body);
+}
+function translateError(err, key) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+        return new StorageObjectNotFoundError(key);
+    }
+    return err;
+}
+async function walk(root, onFile) {
+    let entries;
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return; // missing root counts as empty
+    }
+    for (const ent of entries) {
+        const full = join(root, ent.name);
+        if (ent.isDirectory()) {
+            await walk(full, onFile);
+        }
+        else if (ent.isFile()) {
+            await onFile(full);
+        }
+    }
+}
+//# sourceMappingURL=storage-fs.js.map

package/dist/storage-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-fs.js","sourceRoot":"","sources":["../src/storage-fs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nwire/storage-fs",
+  "version": "0.7.0",
+  "description": "Nwire — local filesystem storage adapter. Implements the Storage contract against a base directory. Suitable for development, single-node deployments, and tests.",
+  "keywords": [
+    "adapter",
+    "filesystem",
+    "fs",
+    "nwire",
+    "storage"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/storage-fs.js",
+  "types": "./dist/storage-fs.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/storage-fs.js",
+      "types": "./dist/storage-fs.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/storage": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}