@poe-platform/safe-fs 0.1.810 → 0.1.812

package/README.md

@@ -10,6 +10,11 @@ working data. Supply `{fs, cwd, env, signal}` and an optional page-cache count
 `env.TMPDIR` or `cwd`, with conditional unlink and cleanup through `close()`.
 Providers must support those capabilities; there is no host fallback. Use an
 external backend for large data because memory filesystems retain spilled bytes.
+To bound aggregate pages across multiple live stores, pass the same
+`new PagedStorageCache(16)` as the third argument to each `PagedStorage` constructor.
+This shares a 256 KiB resident-page budget; `cache.residentBytes` reports current
+page retention. Eviction uses each store's filesystem, and each store still owns
+its `close()` cleanup. The budget excludes caller buffers and backend storage.
 `IntegerTable.entries()` replays records in unsigned key order with a fixed
 16-level node stack and batches of at most 128 records. It accepts zero-filled
 caller storage with `allocate`, `read` and `write`; mutation during traversal

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

@@ -18,4 +18,4 @@ export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
 export { readFileStream } from "./fs/read-file-stream.js";
-export { PagedStorage, IntegerTable, type PagedStorageContext } from "./storage.js";
+export { PagedStorage, PagedStorageCache, IntegerTable, type PagedStorageContext } from "./storage.js";

package/dist/safe-fs/core.js

@@ -16,4 +16,4 @@ export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
 export { readFileStream } from "./fs/read-file-stream.js";
-export { PagedStorage, IntegerTable } from "./storage.js";
+export { PagedStorage, PagedStorageCache, IntegerTable } from "./storage.js";

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

@@ -5,12 +5,31 @@ export interface PagedStorageContext {
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly signal: AbortSignal;
 }
+type Page = {
+    bytes: Uint8Array;
+    dirty: boolean;
+};
+/** Shares one resident-page limit across stores, retaining each store's caller
+ * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
+export declare class PagedStorageCache {
+    private readonly maxPages;
+    private readonly pages;
+    private active;
+    constructor(maxPages: number);
+    get residentBytes(): number;
+    run<T>(action: () => Promise<T>): Promise<T>;
+    acquire(): Promise<Page>;
+    retain(page: Page, release: () => Promise<void>): void;
+    touch(page: Page): void;
+    forget(page: Page): void;
+}
 /** A bounded page cache backed only by the caller filesystem. The default is
  * one MiB; callers own close() on every outcome. Memory filesystems still retain
  * spilled data in RAM, so large workloads require an external backing provider. */
 export declare class PagedStorage {
     private readonly context;
     private readonly maxPages;
+    private readonly cache?;
     private readonly pages;
     private readonly controller;
     private readonly signal;
@@ -23,7 +42,7 @@ export declare class PagedStorage {
     private end;
     private active;
     private closing;
-    constructor(context: PagedStorageContext, maxPages?: number);
+    constructor(context: PagedStorageContext, maxPages?: number, cache?: PagedStorageCache | undefined);
     allocate(length: number): number;
     private operation;
     private spill;
@@ -55,3 +74,4 @@ export declare class IntegerTable {
     private lookup;
     private persist;
 }
+export {};

package/dist/safe-fs/storage.js

@@ -1,12 +1,50 @@
 import { FsError, isFsError } from "./contracts/errors.js";
 const pageBytes = 16 * 1024;
 let serial = 0;
+/** Shares one resident-page limit across stores, retaining each store's caller
+ * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
+export class PagedStorageCache {
+    maxPages;
+    pages = new Map();
+    active = Promise.resolve();
+    constructor(maxPages) {
+        this.maxPages = maxPages;
+        if (!Number.isSafeInteger(maxPages) || maxPages < 1)
+            throw new RangeError("Invalid storage page cache size");
+    }
+    get residentBytes() { return this.pages.size * pageBytes; }
+    run(action) {
+        const work = this.active.then(action);
+        this.active = work.then(() => undefined, () => undefined);
+        return work;
+    }
+    async acquire() {
+        if (this.pages.size < this.maxPages)
+            return { bytes: new Uint8Array(pageBytes), dirty: false };
+        const [page, release] = this.pages.entries().next().value;
+        await release();
+        this.pages.delete(page);
+        page.bytes.fill(0);
+        return page;
+    }
+    retain(page, release) {
+        this.pages.delete(page);
+        this.pages.set(page, release);
+    }
+    touch(page) {
+        const release = this.pages.get(page);
+        this.pages.delete(page);
+        this.pages.set(page, release);
+    }
+    forget(page) { this.pages.delete(page); }
+}
 /** A bounded page cache backed only by the caller filesystem. The default is
  * one MiB; callers own close() on every outcome. Memory filesystems still retain
  * spilled data in RAM, so large workloads require an external backing provider. */
 export class PagedStorage {
     context;
     maxPages;
+    cache;
     pages = new Map();
     controller = new AbortController();
     signal;
@@ -19,9 +57,10 @@ export class PagedStorage {
     end = 8; // Zero is the absent-pointer sentinel.
     active = Promise.resolve();
     closing;
-    constructor(context, maxPages = 64) {
+    constructor(context, maxPages = 64, cache) {
         this.context = context;
         this.maxPages = maxPages;
+        this.cache = cache;
         if (!Number.isSafeInteger(maxPages) || maxPages < 1)
             throw new RangeError("Invalid storage page cache size");
         this.signal = AbortSignal.any([context.signal, this.controller.signal]);
@@ -36,10 +75,11 @@ export class PagedStorage {
     }
     operation(action) {
         this.signal.throwIfAborted();
-        const work = this.active.then(() => {
+        const execute = () => {
             this.signal.throwIfAborted();
             return action();
-        });
+        };
+        const work = this.active.then(() => this.cache ? this.cache.run(execute) : execute());
         this.active = work.then(() => undefined, () => undefined);
         return work;
     }
@@ -101,6 +141,7 @@ export class PagedStorage {
         if (cached) {
             this.pages.delete(number);
             this.pages.set(number, cached);
+            this.cache?.touch(cached);
             return cached;
         }
         let reusable;
@@ -110,11 +151,14 @@ export class PagedStorage {
             const [oldNumber, oldPage] = this.pages.entries().next().value;
             await this.flush(oldNumber, oldPage);
             this.pages.delete(oldNumber);
+            this.cache?.forget(oldPage);
             reusable = oldPage;
         }
         // Flush owns the bytes until its awaited write completes. Reuse only then;
         // zero new/unwritten ranges so the previous page cannot leak into them.
-        const page = reusable ?? { bytes: new Uint8Array(pageBytes), dirty: false };
+        const page = reusable ?? (this.cache ? await this.cache.acquire() : { bytes: new Uint8Array(pageBytes), dirty: false });
+        // Shared eviction may await IO owned by a different, still-live signal.
+        this.signal.throwIfAborted();
         if (reusable)
             page.bytes.fill(0);
         if (number * pageBytes < this.diskLength) {
@@ -128,6 +172,12 @@ export class PagedStorage {
             }
         }
         this.pages.set(number, page);
+        this.cache?.retain(page, async () => {
+            if (!this.descriptor)
+                await this.spill();
+            await this.flush(number, page);
+            this.pages.delete(number);
+        });
         return page;
     }
     write(position, bytes) {
@@ -168,28 +218,33 @@ export class PagedStorage {
         this.controller.abort(new FsError("ECANCELED"));
         return this.closing ??= (async () => {
             await this.active.catch(() => { });
-            this.pages.clear();
-            const descriptor = this.descriptor;
-            if (!descriptor)
-                return;
-            const cancellation = new FsError("ECANCELED");
-            try {
-                if (!this.unlinked) {
-                    const expected = this.initial ?? await descriptor.stat();
-                    await this.context.fs.removeFileConditional(this.path, { parent: this.parent, expected }).catch(error => {
-                        if (!isFsError(error) || error.code !== "ENOENT")
+            const retire = async () => {
+                for (const page of this.pages.values())
+                    this.cache?.forget(page);
+                this.pages.clear();
+                const descriptor = this.descriptor;
+                if (!descriptor)
+                    return;
+                const cancellation = new FsError("ECANCELED");
+                try {
+                    if (!this.unlinked) {
+                        const expected = this.initial ?? await descriptor.stat();
+                        await this.context.fs.removeFileConditional(this.path, { parent: this.parent, expected }).catch(error => {
+                            if (!isFsError(error) || error.code !== "ENOENT")
+                                throw error;
+                        });
+                    }
+                }
+                finally {
+                    // Conditional descriptors must discard their private staged writes, not
+                    // publish the scratch data when the command retires its handle.
+                    await descriptor.close({ signal: AbortSignal.abort(cancellation) }).catch(error => {
+                        if (error !== cancellation)
                             throw error;
                     });
                 }
-            }
-            finally {
-                // Conditional descriptors must discard their private staged writes, not
-                // publish the scratch data when the command retires its handle.
-                await descriptor.close({ signal: AbortSignal.abort(cancellation) }).catch(error => {
-                    if (error !== cancellation)
-                        throw error;
-                });
-            }
+            };
+            await (this.cache ? this.cache.run(retire) : retire());
         })();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.810",
+  "version": "0.1.812",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",