@poe-platform/safe-fs 0.1.41 → 0.1.43

package/README.md

@@ -77,6 +77,7 @@ All required methods must exist, but a backend may reject an operation with `FsE
 | `createReadOnlyFileSystem(filesystem)` | Rejecting writes through one view of an existing filesystem |
 | `createMountFileSystem({ root, mounts })` | Routing absolute virtual mount paths to different filesystems |
 | `createOverlayFileSystem({ upper, lower })` | Reading through to a lower layer and writing changes to an upper layer |
+| `withFileSystemQuota(filesystem, { maxBytes })` | Enforcing a cumulative logical-byte ceiling across every write path |
 
 `createNodeFsBridge` offers a promises-shaped subset, including recursive `cp` and `mkdtemp`. The portable `createFsBridge` from `@poe-platform/safe-fs/core` instead requires a caller-supplied text codec and returns `Uint8Array` values.
 
@@ -201,6 +202,7 @@ There are no package environment variables, implicit credentials, or automatic `
 | Real | Required `root`: existing absolute host directory; the constructor/factory also accepts the root string directly. |
 | Mount | Required `root`: fallback filesystem. `mounts` defaults to `{}` and maps absolute virtual paths to filesystems. |
 | Overlay | Required `upper` and `lower`; `maxBufferBytes` defaults to 64 MiB. |
+| Quota | `withFileSystemQuota` requires a nonnegative safe-integer `maxBytes`. It serializes mutations and counts files, symlinks, copies, hard links, truncation, and streaming writes. |
 | Node bridge | `cwd` defaults to `/`, must be an absolute virtual path; optional lifetime `signal`. |
 | Portable bridge | Same `cwd` and `signal`, plus required `codec` with `isEncoding`, `encode`, and `decode` functions. |
 | Catalog example | Required `files`: a plain record of single-component filenames to text strings; no other options. |

package/dist/safe-fs/core.d.ts

@@ -7,6 +7,7 @@ export * from "./fs/memory/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
+export * from "./fs/quota/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";

package/dist/safe-fs/core.js

@@ -7,6 +7,7 @@ export * from "./fs/memory/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
+export * from "./fs/quota/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";

package/dist/safe-fs/fs/quota/index.d.ts

@@ -0,0 +1,9 @@
+import type { FileSystem } from "../../contracts/filesystem.js";
+export interface FileSystemQuotaOptions {
+    readonly maxBytes: number;
+}
+export declare class FileSystemQuotaError extends Error {
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+export declare function withFileSystemQuota(fs: FileSystem, options: FileSystemQuotaOptions): FileSystem;

package/dist/safe-fs/fs/quota/index.js

@@ -0,0 +1,109 @@
+export class FileSystemQuotaError extends Error {
+    maxBytes;
+    constructor(maxBytes) {
+        super(`Filesystem quota exceeded (${maxBytes} bytes)`);
+        this.maxBytes = maxBytes;
+        this.name = "FileSystemQuotaError";
+    }
+}
+async function usedBytes(fs, options) {
+    let total = 0;
+    const pending = ["/"];
+    while (pending.length) {
+        const directory = pending.pop();
+        for (const entry of await fs.readdir(directory, options)) {
+            const path = `${directory === "/" ? "" : directory}/${entry.name}`;
+            if (entry.type === "directory")
+                pending.push(path);
+            else
+                total += (await fs.lstat(path, options)).size;
+        }
+    }
+    return total;
+}
+async function existingBytes(fs, path, options) {
+    try {
+        const stat = await fs.lstat(path, options);
+        return stat.type === "directory" ? 0 : stat.size;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+}
+export function withFileSystemQuota(fs, options) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)
+        throw new RangeError("maxBytes must be a nonnegative safe integer");
+    let queue = Promise.resolve();
+    const mutate = (operation) => {
+        const result = queue.then(operation);
+        queue = result.catch(() => undefined);
+        return result;
+    };
+    const assertDelta = async (path, nextBytes, fsOptions) => {
+        const current = await existingBytes(fs, path, fsOptions);
+        if (await usedBytes(fs, fsOptions) - current + nextBytes > options.maxBytes)
+            throw new FileSystemQuotaError(options.maxBytes);
+    };
+    const mutations = {
+        writeFile(path, data, writeOptions) {
+            return mutate(async () => {
+                const append = writeOptions?.flag === "a" || writeOptions?.flag === "ax";
+                const current = append ? await existingBytes(fs, path, writeOptions) : 0;
+                await assertDelta(path, current + data.length, writeOptions);
+                await fs.writeFile(path, data, writeOptions);
+            });
+        },
+        appendFile(path, data, appendOptions) {
+            return mutate(async () => {
+                await assertDelta(path, await existingBytes(fs, path, appendOptions) + data.length, appendOptions);
+                await fs.appendFile(path, data, appendOptions);
+            });
+        },
+        copyFile(source, destination, copyOptions) {
+            return mutate(async () => {
+                await assertDelta(destination, (await fs.stat(source, copyOptions)).size, copyOptions);
+                await fs.copyFile(source, destination, copyOptions);
+            });
+        },
+        truncate(path, length = 0, truncateOptions) {
+            return mutate(async () => {
+                await assertDelta(path, length, truncateOptions);
+                await fs.truncate(path, length, truncateOptions);
+            });
+        },
+        link(source, destination, linkOptions) {
+            return mutate(async () => {
+                await assertDelta(destination, (await fs.stat(source, linkOptions)).size, linkOptions);
+                await fs.link(source, destination, linkOptions);
+            });
+        },
+        symlink(target, path, linkOptions) {
+            return mutate(async () => {
+                await assertDelta(path, new TextEncoder().encode(target).length, linkOptions);
+                await fs.symlink(target, path, linkOptions);
+            });
+        },
+        writeStream(path, source, writeOptions) {
+            return mutate(async () => {
+                const append = writeOptions?.flag === "a" || writeOptions?.flag === "ax";
+                if (!append)
+                    await fs.writeFile(path, new Uint8Array(), writeOptions);
+                for await (const chunk of source) {
+                    await assertDelta(path, await existingBytes(fs, path, writeOptions) + chunk.length, writeOptions);
+                    await fs.appendFile(path, chunk, writeOptions);
+                }
+            });
+        },
+    };
+    return new Proxy(fs, {
+        get(target, property) {
+            const replacement = Reflect.get(mutations, property);
+            if (typeof replacement === "function")
+                return replacement;
+            const original = Reflect.get(target, property);
+            return typeof original === "function" ? original.bind(target) : original;
+        },
+    });
+}

package/dist/safe-fs/index.d.ts

@@ -8,6 +8,7 @@ export * from "./fs/webdav/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
+export * from "./fs/quota/index.js";
 export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";

package/dist/safe-fs/index.js

@@ -7,6 +7,7 @@ export * from "./fs/webdav/index.js";
 export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
+export * from "./fs/quota/index.js";
 export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createNodeFileSystemAdapterRegistry } from "./config.node.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",
@@ -82,6 +82,10 @@
     "./fs/overlay": {
       "types": "./dist/safe-fs/fs/overlay/index.d.ts",
       "import": "./dist/safe-fs/fs/overlay/index.js"
+    },
+    "./fs/quota": {
+      "types": "./dist/safe-fs/fs/quota/index.d.ts",
+      "import": "./dist/safe-fs/fs/quota/index.js"
     }
   },
   "repository": {