@poe-platform/safe-fs 0.1.670 → 0.1.671

package/README.md

@@ -68,6 +68,8 @@ cause. Preserve cancellation/control exceptions separately. Cross-family
 
 All required methods must exist, but a backend may reject an operation with `FsError`, such as `EROFS` for a write or `ENOTSUP` for unsupported semantics. Check optional methods and `capabilities` rather than assuming every backend behaves like a local disk. Errors expose `code` and may include `syscall`, `path`, `dest`, and `cause`.
 
+`createDeviceFileSystem(fs)` adds portable `/dev/null` whole-file, stream, and descriptor I/O. Descriptor reads return EOF and writes discard bytes; stat remains a zero-size character device and descriptor position remains zero. Truncating opens are accepted, exclusive creation fails with `EEXIST`, and descriptor resizing and synchronization are unsupported. Access modes, cancellation, and closed handles use the normal descriptor checks. With an authoritative object store, use `createDeviceFileSystem(withObjectFileDescriptors(fs, store))` so null-device I/O never acquires or publishes an object version; ordinary files retain conditional publication. The device wrapper must be outermost for this composition.
+
 | Backend or wrapper | Use it for |
 | --- | --- |
 | `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams |

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

@@ -3,9 +3,10 @@ import { finishCleanup } from "../../contracts/cleanup.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "../mount/comparison.js";
 import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
-import { deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
+import { createDeviceYield, deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
 import { openRetainedReadFile, openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabilities, requireOwnedMutation } from "../capabilities.js";
 import { pathNamespace } from "../path-namespace.js";
+import { openFileDescriptor } from "../descriptor.js";
 const views = new WeakMap();
 const deviceCapabilities = Object.freeze({
     readOnly: false, read: true, stat: true, realpath: true, access: true, readdir: false,
@@ -14,7 +15,7 @@ const deviceCapabilities = Object.freeze({
     remove: false, removeDirectory: false, recursiveRemove: false, rename: false,
     mkdir: false, recursiveMkdir: false, symlinks: false, hardlinks: false, readlink: false,
     permissions: false, timestamps: false, truncate: false, randomAccessWrite: false,
-    open: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
+    open: true, atomicFileMutation: false, atomicEntryRemoval: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
     atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true, atomicResize: false,
 });
 function globalCapabilities(filesystem) {
@@ -125,7 +126,7 @@ export class DeviceFileSystem {
         if (resolved === nullPath)
             return deviceCapabilities;
         if (resolved === deviceDirectory)
-            return { ...deviceCapabilities, readdir: true, write: false, append: false,
+            return { ...deviceCapabilities, open: false, readdir: true, write: false, append: false,
                 exclusiveCreate: false, streamingWrite: false, streamingAppend: false, independentWriteStreams: false, descriptorWriteStream: false,
                 retainedRead: false, retainedResize: false, streamingRead: false, copy: false, exclusiveCopy: false };
         const query = this.#filesystem.capabilitiesFor;
@@ -239,7 +240,29 @@ export class DeviceFileSystem {
             throw new FsError("EINVAL", { syscall: "open", path });
         const resolved = await this.#resolve(path, options, options.creation !== "exclusive");
         options.signal?.throwIfAborted();
-        if (resolved === nullPath || resolved === deviceDirectory)
+        if (resolved === nullPath)
+            return openFileDescriptor(path, options, {
+                position: true, positionedRead: true, positionedWrite: true, positionedAppendWrite: true,
+                openTruncate: true, delegateZeroLengthWrite: true, truncate: false, synchronization: "none",
+            }, async (admitted) => {
+                if (admitted.creation === "exclusive")
+                    throw new FsError("EEXIST", { syscall: "open", path });
+                const yieldAfterWrite = createDeviceYield();
+                return {
+                    resource: this.#nullStat,
+                    getPosition: async () => 0,
+                    stat: async (stat) => ({ ...stat }),
+                    read: async () => 0,
+                    write: async (_stat, buffer, _position, forwarded) => {
+                        await yieldAfterWrite(buffer.byteLength, forwarded.signal);
+                        return buffer.byteLength;
+                    },
+                    truncate: async () => { throw new FsError("ENOTSUP", { syscall: "ftruncate", path }); },
+                    sync: async () => { throw new FsError("ENOTSUP", { syscall: "fsync", path }); },
+                    close: async () => { },
+                };
+            });
+        if (resolved === deviceDirectory)
             throw new FsError("ENOTSUP", { syscall: "open", path });
         const query = this.#filesystem.capabilitiesFor;
         options.signal?.throwIfAborted();

package/dist/safe-fs/fs/devices/stream.d.ts

@@ -2,4 +2,5 @@ import type { ByteSource } from "../../contracts/io.js";
 import type { FileReadHandle } from "../../contracts/filesystem.js";
 export declare function deviceReadStream(open: () => Promise<ByteSource>, signal?: AbortSignal): ByteSource;
 export declare function drainDeviceFile(handle: FileReadHandle, signal?: AbortSignal): Promise<void>;
+export declare function createDeviceYield(): (length: number, signal?: AbortSignal) => Promise<void>;
 export declare function drainDeviceInput(source: ByteSource, signal?: AbortSignal): Promise<void>;

package/dist/safe-fs/fs/devices/stream.js

@@ -86,12 +86,24 @@ function nextChunk(iterator, signal) {
         }
     });
 }
+export function createDeviceYield() {
+    let bytes = 0;
+    let pulls = 0;
+    return async (length, signal) => {
+        bytes += length;
+        if (++pulls >= 64 || bytes >= 65536) {
+            await new Promise(resolve => setTimeout(resolve, 0));
+            signal?.throwIfAborted();
+            bytes = 0;
+            pulls = 0;
+        }
+    };
+}
 export async function drainDeviceInput(source, signal) {
     signal?.throwIfAborted();
     const iterator = source[Symbol.asyncIterator]();
     let failed = false;
-    let bytes = 0;
-    let pulls = 0;
+    const yieldAfterWrite = createDeviceYield();
     try {
         for (;;) {
             const result = await nextChunk(iterator, signal);
@@ -100,13 +112,7 @@ export async function drainDeviceInput(source, signal) {
                 break;
             if (!(result.value instanceof Uint8Array))
                 throw new TypeError("Byte sources must yield Uint8Array chunks");
-            bytes += result.value.byteLength;
-            if (++pulls >= 64 || bytes >= 65536) {
-                await new Promise(resolve => setTimeout(resolve, 0));
-                signal?.throwIfAborted();
-                bytes = 0;
-                pulls = 0;
-            }
+            await yieldAfterWrite(result.value.byteLength, signal);
         }
     }
     catch (error) {

package/package.json

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