@poe-platform/safe-fs 0.1.807 → 0.1.809

package/dist/safe-fs/testing/object-io-metrics.js

@@ -48,6 +48,7 @@ export function measureObjectIoStore(store, metrics) {
     const publish = store.publish;
     const createStaging = store.createStaging;
     return {
+        ...(store.noFollow === undefined ? {} : { noFollow: store.noFollow }),
         async acquire(...args) {
             const head = await metrics.measure("store", "acquire", () => store.acquire(...args));
             return head && version(head);

package/dist/xml-ast/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class XmlLimitError extends SyntaxError {
+    readonly limit: string;
+    constructor(limit: string, message: string);
+}

package/dist/xml-ast/errors.js

@@ -0,0 +1,7 @@
+export class XmlLimitError extends SyntaxError {
+    limit;
+    constructor(limit, message) {
+        super(message);
+        this.limit = limit;
+    }
+}

package/dist/xml-ast/index.d.ts

@@ -1,3 +1,4 @@
+export { XmlLimitError } from "./errors.js";
 export interface XmlName {
     readonly name: string;
     readonly namespace: string;
@@ -39,9 +40,6 @@ export interface XmlLimits {
     readonly maxTextLength?: number;
     readonly onElement?: (element: XmlName, parent: XmlName | undefined, depth: number) => void;
 }
-export declare class XmlLimitError extends SyntaxError {
-    readonly limit: string;
-    constructor(limit: string, message: string);
-}
 export declare function parseXmlSteps(input: string, limits?: XmlLimits): Generator<number, XmlElement, void>;
 export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
+export { parseXmlStream, type XmlStreamLimits, type XmlStreamEvent } from "./stream.js";

package/dist/xml-ast/index.js

@@ -1,10 +1,5 @@
-export class XmlLimitError extends SyntaxError {
-    limit;
-    constructor(limit, message) {
-        super(message);
-        this.limit = limit;
-    }
-}
+import { XmlLimitError } from "./errors.js";
+export { XmlLimitError } from "./errors.js";
 function* find(source, needle, start) {
     const found = source.indexOf(needle, start);
     const end = found < 0 ? source.length : found;
@@ -633,3 +628,4 @@ export function parseXml(input, limits = {}) {
         result = parser.next();
     return result.value;
 }
+export { parseXmlStream } from "./stream.js";

package/dist/xml-ast/stream.d.ts

@@ -0,0 +1,31 @@
+import type { XmlContent, XmlElement, XmlLimits, XmlName } from "./index.js";
+export type XmlStreamEvent = {
+    readonly type: "open" | "close";
+    readonly element: XmlElement;
+    readonly parent: XmlElement | undefined;
+} | {
+    readonly type: "content";
+    readonly content: Exclude<XmlContent, XmlElement>;
+    readonly parent: XmlElement | undefined;
+};
+export interface XmlStreamLimits extends XmlLimits {
+    /** Validate the full document but return only its root name, without a retained tree. */
+    readonly retainTree?: boolean;
+    /** Ordered node events, awaited after each parser window. Requires retainTree:
+     * false; elements carry metadata without child/content arrays. Individual XML
+     * tokens remain resident until the underlying parser completes them. */
+    readonly events?: (event: XmlStreamEvent) => void | Promise<void>;
+    /** Detach selected non-root subtrees and await their consumer before parsing
+     * the next 512-unit window. By default nested matches belong to the selected ancestor. */
+    readonly streamElements?: {
+        /** Also detach preceding sibling content when selecting a subtree, before
+         * the parser advances. The final trailing content remains in the parent. */
+        readonly captureBefore?: boolean;
+        /** Detach nested matches too, consuming descendants before their ancestors. */
+        readonly includeNested?: boolean;
+        readonly matches: (element: XmlName, parent: XmlName | undefined, depth: number) => boolean;
+        readonly consume: (element: XmlElement, parent: XmlElement, before?: readonly XmlContent[]) => void | Promise<void>;
+    };
+}
+/** Incremental source consumption. Individual XML tokens and optional trees remain resident. */
+export declare function parseXmlStream(source: AsyncIterable<string> | Iterable<string>, limits?: XmlStreamLimits, checkpoint?: (units: number) => void | Promise<void>): Promise<XmlElement>;

package/dist/xml-ast/stream.js

@@ -0,0 +1,179 @@
+import { SaxesParser } from "saxes/saxes.js";
+import { XmlLimitError } from "./errors.js";
+/** Incremental source consumption. Individual XML tokens and optional trees remain resident. */
+export async function parseXmlStream(source, limits = {}, checkpoint) {
+    if (limits.recover)
+        throw new TypeError("XML stream recovery is unsupported; use parseXmlSteps");
+    for (const key of ["maxDepth", "maxNodes", "maxAttributes", "maxAttributesPerElement", "maxNamespaces", "maxContentNodes", "maxTextLength"]) {
+        const value = limits[key];
+        if (value !== undefined && value !== Infinity && (!Number.isSafeInteger(value) || value < 1))
+            throw new RangeError("XML limits must be positive integers");
+    }
+    const counters = { maxNodes: 0, maxAttributes: 0, maxContentNodes: 0, maxTextLength: 0 };
+    function bound(key, value) {
+        if (value > (limits[key] ?? Infinity))
+            throw new XmlLimitError(key, "XML resource limit exceeded");
+    }
+    function charge(key, value = 1) { counters[key] += value; bound(key, counters[key]); }
+    const retainContent = limits.retainContent !== false, tree = limits.retainTree !== false, retain = tree && retainContent;
+    const events = limits.events;
+    if (events && tree)
+        throw new TypeError("XML events require retainTree: false");
+    const describe = retain || !!events;
+    const queued = [];
+    const streaming = limits.streamElements;
+    if (streaming && !retain)
+        throw new TypeError("XML subtree streaming requires retained content and tree mode");
+    let selectedCount = 0;
+    const completed = [];
+    const stack = [];
+    const prolog = [], epilog = [];
+    const emptyNamespaces = new Map();
+    let root, declaration;
+    const parser = new SaxesParser({ xmlns: true, defaultXMLVersion: "1.0", forceXMLVersion: true });
+    parser.on("error", error => { throw new SyntaxError(`Invalid XML: ${error.message}`); });
+    parser.on("doctype", () => { throw new SyntaxError("Invalid XML: DTD and entity declarations are forbidden"); });
+    let prefix = "", capturing = describe;
+    parser.on("xmldecl", value => {
+        const encoding = value.encoding?.toUpperCase();
+        if (value.version !== "1.0" || encoding !== undefined &&
+            (!["UTF-8", "UTF-16", "UTF-16LE", "UTF-16BE"].includes(encoding) ||
+                limits.expectedEncoding !== undefined && encoding !== limits.expectedEncoding &&
+                    !(encoding === "UTF-16" && ["UTF-16LE", "UTF-16BE"].includes(limits.expectedEncoding))))
+            throw new SyntaxError("Invalid XML: unsupported XML declaration");
+        if (describe)
+            declaration = prefix.slice(0, prefix.indexOf("?>") + 2);
+        prefix = "";
+        capturing = false;
+    });
+    parser.on("opentag", tag => {
+        charge("maxNodes");
+        bound("maxDepth", stack.length + 1);
+        const attrs = Object.values(tag.attributes);
+        charge("maxAttributes", attrs.length);
+        bound("maxAttributesPerElement", attrs.length);
+        const parent = stack.at(-1);
+        let namespaces = parent?.namespaces ?? new Map([["xml", "http://www.w3.org/XML/1998/namespace"]]);
+        const bindings = Object.entries(tag.ns);
+        if (bindings.length) {
+            namespaces = new Map(namespaces);
+            for (const [name, uri] of bindings)
+                namespaces.set(name, uri);
+            bound("maxNamespaces", namespaces.size);
+        }
+        for (const attr of attrs)
+            charge("maxTextLength", attr.value.length);
+        const name = { name: tag.name, namespace: tag.uri, localName: tag.local };
+        limits.onElement?.(name, parent?.element, stack.length + 1);
+        const selected = (!selectedCount || streaming?.includeNested === true) && !!streaming?.matches(name, parent?.element, stack.length + 1);
+        if (selected && !parent)
+            throw new TypeError("XML subtree streaming cannot select the root");
+        let before = [];
+        if (selected) {
+            selectedCount++;
+            if (streaming?.captureBefore) {
+                before = parent.element.content.splice(0);
+                parent.element.children.length = 0;
+                parent.element.text = '';
+            }
+        }
+        charge("maxContentNodes", 1 + (retainContent || events ? attrs.length : 0));
+        const element = { kind: "element", ...name, children: [], content: [], text: "",
+            attributes: describe ? attrs.map(attr => ({ name: attr.name, localName: attr.local, namespace: attr.uri, value: attr.value })) : [],
+            namespaces: describe ? namespaces : emptyNamespaces,
+            ...(!root && describe ? { prolog, epilog, ...(declaration === undefined ? {} : { declaration }) } : {}) };
+        if (parent && tree && !selected) {
+            parent.element.children.push(element);
+            if (retain)
+                parent.element.content.push(element);
+        }
+        else if (!parent)
+            root = element;
+        stack.push({ element, namespaces, selected, before });
+        if (events)
+            queued.push({ type: "open", element, parent: parent?.element });
+    });
+    parser.on("closetag", () => {
+        const frame = stack.pop();
+        if (events)
+            queued.push({ type: "close", element: frame.element, parent: stack.at(-1)?.element });
+        if (frame.selected) {
+            completed.push({ element: frame.element, parent: stack.at(-1).element, before: frame.before });
+            selectedCount--;
+        }
+    });
+    async function drain() {
+        for (const entry of completed) {
+            await checkpoint?.(0);
+            await streaming.consume(entry.element, entry.parent, entry.before);
+        }
+        completed.length = 0;
+        for (const event of queued) {
+            await checkpoint?.(0);
+            await events(event);
+        }
+        queued.length = 0;
+    }
+    function append(content) {
+        charge("maxTextLength", content.text.length);
+        charge("maxContentNodes");
+        const parent = stack.at(-1)?.element;
+        if (events)
+            queued.push({ type: "content", content, parent });
+        if (tree && parent && (content.kind === "text" || content.kind === "cdata"))
+            parent.text += content.text;
+        if (retain)
+            (parent ? parent.content : root ? epilog : prolog).push(content);
+    }
+    parser.on("text", text => { if (text.length)
+        append({ kind: "text", text }); });
+    parser.on("cdata", text => append({ kind: "cdata", text }));
+    parser.on("comment", text => append({ kind: "comment", text }));
+    parser.on("processinginstruction", value => append({ kind: "processing-instruction", target: value.target, text: value.body }));
+    let cr = false, first = true;
+    function write(text) {
+        if (!text)
+            return;
+        if (first) {
+            first = false;
+            if (text.charCodeAt(0) === 0xfeff) {
+                parser.write(text[0]);
+                text = text.slice(1);
+            }
+        }
+        if (cr) {
+            if (text.startsWith("\n"))
+                text = text.slice(1);
+            cr = false;
+        }
+        cr = text.endsWith("\r");
+        text = text.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+        if (capturing) {
+            prefix += text;
+            if (prefix.length >= 6 && !(prefix.startsWith("<?xml") && " \t\n".includes(prefix[5]))) {
+                prefix = "";
+                capturing = false;
+            }
+        }
+        parser.write(text);
+    }
+    await checkpoint?.(0);
+    for await (const text of source) {
+        if (typeof text !== "string")
+            throw new TypeError("XML producer must yield strings");
+        for (let i = 0; i < text.length; i += 512) {
+            await checkpoint?.(0);
+            write(text.slice(i, i + 512));
+            if (completed.length || queued.length)
+                await drain();
+            await checkpoint?.(Math.min(512, text.length - i));
+        }
+    }
+    await checkpoint?.(0);
+    parser.close();
+    if (completed.length || queued.length)
+        await drain();
+    if (!root)
+        throw new SyntaxError("Invalid XML: incomplete document");
+    return root;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.807",
+  "version": "0.1.809",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",
@@ -88,11 +88,7 @@
       "import": "./dist/safe-fs/fs/real/index.js"
     },
     "./fs/s3/http": {
-      "types": {
-        "browser": "./dist/safe-fs/node-unavailable.d.ts",
-        "default": "./dist/safe-fs/fs/s3/http/index.d.ts"
-      },
-      "browser": null,
+      "types": "./dist/safe-fs/fs/s3/http/index.d.ts",
       "import": "./dist/safe-fs/fs/s3/http/index.js"
     },
     "./fs/s3": {
@@ -134,6 +130,13 @@
     "./bridge": {
       "types": "./dist/safe-fs/bridge/index.d.ts",
       "import": "./dist/safe-fs/bridge/index.js"
+    },
+    "./storage": {
+      "types": "./dist/safe-fs/storage.d.ts",
+      "workerd": "./dist/safe-fs/storage.js",
+      "browser": "./dist/safe-fs/storage.js",
+      "worker": "./dist/safe-fs/storage.js",
+      "import": "./dist/safe-fs/storage.js"
     }
   },
   "repository": {
@@ -145,6 +148,7 @@
     "access": "public"
   },
   "dependencies": {
+    "saxes": "^6.0.0",
     "@types/node": "^25.2.2",
     "@noble/hashes": "2.4.0"
   },