@minnowdb/core 0.3.0 → 0.4.0

package/dist/storage/opfs/files.d.ts

@@ -6,7 +6,13 @@
  * non-leading `.` pass through, everything else becomes `%XX` per UTF-8 byte — so names
  * round-trip exactly and none can collide with or escape into another's path.
  */
-import type { SyncFileHandle } from "../toolkit/sync-file.js";
+import { type SyncFileHandle } from "../toolkit/sync-file.js";
+/** Conservative cross-browser/filesystem ceiling for one already-encoded OPFS entry name. */
+export declare const MAX_OPFS_ENCODED_SEGMENT_CHARACTERS = 240;
+/** Directory handles have no close operation, so bound retained wrappers under path churn. */
+export declare const MAX_OPFS_DIRECTORY_HANDLE_CACHE_ENTRIES = 128;
+/** Internal layouts are shallow; reject adversarial/custom paths before recursive resolution. */
+export declare const MAX_OPFS_PATH_SEGMENTS = 16;
 export declare function encodeSegment(segment: string): string;
 export declare function decodeSegment(encoded: string): string;
 export interface WriteFileOptions {
@@ -20,6 +26,8 @@ export interface ReadFileOptions {
      * default rethrows.
      */
     lockedMeansAbsent?: boolean;
+    /** Refuse before `arrayBuffer()` allocates when the file exceeds this exact byte ceiling. */
+    maxBytes?: number;
 }
 /**
  * A directory-handle cache plus the file operations the store needs. Handles are cached per
@@ -29,11 +37,15 @@ export interface ReadFileOptions {
 export declare class OpfsTree {
     #private;
     constructor(root: FileSystemDirectoryHandle);
+    /** @internal Hardening-test visibility for the cache's fixed-memory invariant. */
+    get directoryCacheSizeForTests(): number;
     getDirectory(path: readonly string[], create: boolean): Promise<FileSystemDirectoryHandle>;
     /** Drops cached handles at and under a path — call after deleting a directory. */
     invalidate(pathPrefix: readonly string[]): void;
     /** `undefined` when the file (or any parent) does not exist. */
     readFile(path: readonly string[], options?: ReadFileOptions): Promise<Uint8Array | undefined>;
+    /** File length without materializing its contents; `undefined` when the path is absent. */
+    fileSize(path: readonly string[]): Promise<number | undefined>;
     /**
      * Writes a whole file through an exclusive sync handle: truncate, write, optional flush,
      * close. Quota errors escape unwrapped. The handle is always closed, so a failed write never
@@ -52,13 +64,12 @@ export declare class OpfsTree {
     deleteFile(path: readonly string[]): Promise<boolean>;
     /** Removes a whole subtree; missing is fine. */
     deleteTree(path: readonly string[]): Promise<void>;
-    /** Names of the entries directly inside a directory; `[]` when it does not exist. */
-    listNames(path: readonly string[]): Promise<string[]>;
-    /** Every file under a directory, with sizes — the open-time block index walk. */
-    walkFiles(path: readonly string[]): Promise<Array<{
+    /** Names directly inside a directory, streamed without retaining the directory cardinality. */
+    iterateNames(path: readonly string[]): AsyncGenerator<string>;
+    /** Every file under a directory, streamed with O(path depth) retained memory. */
+    walkFiles(path: readonly string[]): AsyncGenerator<{
         path: string[];
         size: number;
-    }>>;
+    }>;
 }
 export declare function isDomError(error: unknown, name: string): boolean;
-//# sourceMappingURL=files.d.ts.map

package/dist/storage/opfs/files.js

@@ -6,38 +6,86 @@
  * non-leading `.` pass through, everything else becomes `%XX` per UTF-8 byte — so names
  * round-trip exactly and none can collide with or escape into another's path.
  */
+import { assertWellFormedString } from "../../block-format/unicode.js";
+import { writeFully } from "../toolkit/sync-file.js";
 const SAFE_SEGMENT_CHARS = /^[A-Za-z0-9._-]$/;
+const UPPERCASE_HEX_BYTE = /^[0-9A-F]{2}$/;
+const segmentTextEncoder = new TextEncoder();
+const segmentTextDecoder = new TextDecoder("utf-8", { fatal: true });
+/** Conservative cross-browser/filesystem ceiling for one already-encoded OPFS entry name. */
+export const MAX_OPFS_ENCODED_SEGMENT_CHARACTERS = 240;
+/** Directory handles have no close operation, so bound retained wrappers under path churn. */
+export const MAX_OPFS_DIRECTORY_HANDLE_CACHE_ENTRIES = 128;
+/** Internal layouts are shallow; reject adversarial/custom paths before recursive resolution. */
+export const MAX_OPFS_PATH_SEGMENTS = 16;
+function assertEncodedSegmentLength(length) {
+    if (length > MAX_OPFS_ENCODED_SEGMENT_CHARACTERS) {
+        throw new RangeError(`Encoded OPFS path segment exceeds ${String(MAX_OPFS_ENCODED_SEGMENT_CHARACTERS)} characters`);
+    }
+}
 export function encodeSegment(segment) {
+    assertWellFormedString(segment, "OPFS path segment");
     if (segment.length === 0)
         return "%";
     let encoded = "";
     for (const char of segment) {
         if (SAFE_SEGMENT_CHARS.test(char) && !(encoded.length === 0 && char === ".")) {
             encoded += char;
+            assertEncodedSegmentLength(encoded.length);
             continue;
         }
-        for (const byte of new TextEncoder().encode(char)) {
+        for (const byte of segmentTextEncoder.encode(char)) {
             encoded += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+            assertEncodedSegmentLength(encoded.length);
         }
     }
     return encoded;
 }
 export function decodeSegment(encoded) {
+    assertEncodedSegmentLength(encoded.length);
     if (encoded === "%")
         return "";
+    if (encoded.length === 0)
+        throw new Error("Invalid OPFS path segment encoding");
     const bytes = [];
     for (let index = 0; index < encoded.length;) {
         const char = encoded[index] ?? "";
         if (char === "%") {
-            bytes.push(Number.parseInt(encoded.slice(index + 1, index + 3), 16));
+            const hex = encoded.slice(index + 1, index + 3);
+            if (!UPPERCASE_HEX_BYTE.test(hex)) {
+                throw new Error("Invalid OPFS path segment encoding");
+            }
+            bytes.push(Number.parseInt(hex, 16));
             index += 3;
             continue;
         }
-        for (const byte of new TextEncoder().encode(char))
-            bytes.push(byte);
-        index += char.length;
+        if (!SAFE_SEGMENT_CHARS.test(char)) {
+            throw new Error("Invalid OPFS path segment encoding");
+        }
+        bytes.push(char.charCodeAt(0));
+        index += 1;
+    }
+    let decoded;
+    try {
+        decoded = segmentTextDecoder.decode(new Uint8Array(bytes));
+    }
+    catch {
+        throw new Error("Invalid OPFS path segment encoding");
+    }
+    if (encodeSegment(decoded) !== encoded) {
+        throw new Error("Non-canonical OPFS path segment encoding");
+    }
+    return decoded;
+}
+function validatePath(path) {
+    if (path.length > MAX_OPFS_PATH_SEGMENTS) {
+        throw new RangeError(`OPFS path exceeds ${String(MAX_OPFS_PATH_SEGMENTS)} segments`);
+    }
+    for (const segment of path) {
+        if (segment.length === 0 || segment.length > MAX_OPFS_ENCODED_SEGMENT_CHARACTERS) {
+            throw new RangeError("OPFS path contains an invalid segment");
+        }
     }
-    return new TextDecoder().decode(new Uint8Array(bytes));
 }
 /**
  * A directory-handle cache plus the file operations the store needs. Handles are cached per
@@ -50,16 +98,30 @@ export class OpfsTree {
     constructor(root) {
         this.#root = root;
     }
+    /** @internal Hardening-test visibility for the cache's fixed-memory invariant. */
+    get directoryCacheSizeForTests() {
+        return this.#directories.size;
+    }
     async getDirectory(path, create) {
+        validatePath(path);
         if (path.length === 0)
             return this.#root;
         const key = path.join("/");
         const cached = this.#directories.get(key);
-        if (cached !== undefined)
+        if (cached !== undefined) {
+            // Map insertion order is the LRU order. Refresh without retaining a second reference.
+            this.#directories.delete(key);
+            this.#directories.set(key, cached);
             return cached;
+        }
         const parent = await this.getDirectory(path.slice(0, -1), create);
         const directory = await retryTransient(() => parent.getDirectoryHandle(path[path.length - 1] ?? "", { create }));
         this.#directories.set(key, directory);
+        if (this.#directories.size > MAX_OPFS_DIRECTORY_HANDLE_CACHE_ENTRIES) {
+            const oldest = this.#directories.keys().next().value;
+            if (oldest !== undefined)
+                this.#directories.delete(oldest);
+        }
         return directory;
     }
     /** Drops cached handles at and under a path — call after deleting a directory. */
@@ -72,11 +134,19 @@ export class OpfsTree {
     }
     /** `undefined` when the file (or any parent) does not exist. */
     async readFile(path, options = {}) {
+        validatePath(path);
+        if (options.maxBytes !== undefined &&
+            (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)) {
+            throw new RangeError("OPFS read byte limit must be a non-negative safe integer");
+        }
         try {
             return await retryTransient(async () => {
                 const directory = await this.getDirectory(path.slice(0, -1), false);
                 const handle = await directory.getFileHandle(path[path.length - 1] ?? "");
                 const file = await handle.getFile();
+                if (options.maxBytes !== undefined && file.size > options.maxBytes) {
+                    throw new RangeError(`OPFS file exceeds the ${String(options.maxBytes)}-byte read limit`);
+                }
                 return new Uint8Array(await file.arrayBuffer());
             });
         }
@@ -98,17 +168,35 @@ export class OpfsTree {
             throw error;
         }
     }
+    /** File length without materializing its contents; `undefined` when the path is absent. */
+    async fileSize(path) {
+        validatePath(path);
+        try {
+            return await retryTransient(async () => {
+                const directory = await this.getDirectory(path.slice(0, -1), false);
+                const handle = await directory.getFileHandle(path[path.length - 1] ?? "");
+                return (await handle.getFile()).size;
+            });
+        }
+        catch (error) {
+            if (isDomError(error, "NotFoundError") || isDomError(error, "TypeMismatchError")) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
     /**
      * Writes a whole file through an exclusive sync handle: truncate, write, optional flush,
      * close. Quota errors escape unwrapped. The handle is always closed, so a failed write never
      * leaves the file locked — only torn, which readers detect by checksum.
      */
     async writeFile(path, bytes, options = {}) {
+        validatePath(path);
         await retryTransient(async () => {
             const handle = await this.openHandle(path, { create: true });
             try {
                 handle.truncate(0);
-                handle.write(bytes, { at: 0 });
+                writeFully(handle, bytes, 0, `writing ${path.join("/")}`);
                 if (options.flush === true)
                     handle.flush();
             }
@@ -123,6 +211,7 @@ export class OpfsTree {
      * platform-specific type lives in the WebWorker lib, which not every consumer loads.
      */
     async openHandle(path, options) {
+        validatePath(path);
         return retryTransient(async () => {
             const directory = await this.getDirectory(path.slice(0, -1), options.create);
             const handle = await directory.getFileHandle(path[path.length - 1] ?? "", {
@@ -133,6 +222,7 @@ export class OpfsTree {
     }
     /** True when the file existed. Absence is not an error — deletes are idempotent. */
     async deleteFile(path) {
+        validatePath(path);
         try {
             await retryTransient(async () => {
                 const directory = await this.getDirectory(path.slice(0, -1), false);
@@ -148,6 +238,7 @@ export class OpfsTree {
     }
     /** Removes a whole subtree; missing is fine. */
     async deleteTree(path) {
+        validatePath(path);
         try {
             await retryTransient(async () => {
                 const directory = await this.getDirectory(path.slice(0, -1), false);
@@ -160,42 +251,40 @@ export class OpfsTree {
         }
         this.invalidate(path);
     }
-    /** Names of the entries directly inside a directory; `[]` when it does not exist. */
-    async listNames(path) {
+    /** Names directly inside a directory, streamed without retaining the directory cardinality. */
+    async *iterateNames(path) {
+        validatePath(path);
+        let directory;
         try {
-            return await retryTransient(async () => {
-                const directory = await this.getDirectory(path, false);
-                const names = [];
-                for await (const name of directory.keys())
-                    names.push(name);
-                return names;
-            });
+            directory = await this.getDirectory(path, false);
         }
         catch (error) {
             if (isDomError(error, "NotFoundError") || isDomError(error, "TypeMismatchError")) {
-                return [];
+                return;
             }
             throw error;
         }
+        for await (const name of directory.keys())
+            yield name;
     }
-    /** Every file under a directory, with sizes — the open-time block index walk. */
-    async walkFiles(path) {
-        const results = [];
+    /** Every file under a directory, streamed with O(path depth) retained memory. */
+    async *walkFiles(path) {
+        validatePath(path);
         let root;
         try {
             root = await this.getDirectory(path, false);
         }
         catch (error) {
             if (isDomError(error, "NotFoundError"))
-                return results;
+                return;
             throw error;
         }
-        const walk = async (directory, prefix) => {
+        const walk = async function* (directory, prefix) {
             for await (const [name, entry] of directory) {
                 if (entry.kind === "file") {
                     try {
                         const file = await entry.getFile();
-                        results.push({ path: [...prefix, name], size: file.size });
+                        yield { path: [...prefix, name], size: file.size };
                     }
                     catch (error) {
                         // A file another instance is writing or deleting this instant is not part of any
@@ -208,12 +297,11 @@ export class OpfsTree {
                     }
                 }
                 else {
-                    await walk(entry, [...prefix, name]);
+                    yield* walk(entry, [...prefix, name]);
                 }
             }
         };
-        await walk(root, []);
-        return results;
+        yield* walk(root, []);
     }
 }
 export function isDomError(error, name) {
@@ -240,4 +328,3 @@ async function retryTransient(operation) {
         }
     }
 }
-//# sourceMappingURL=files.js.map

package/dist/storage/opfs/index.d.ts

@@ -1,3 +1,3 @@
 export { OpfsBlockStore, deleteOpfsDatabase, type OpfsBlockStoreOptions } from "./store.js";
+export { OpfsUncertainOutcomeError } from "../types.js";
 export { OpfsTree, type ReadFileOptions, type WriteFileOptions } from "./files.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/storage/opfs/index.js

@@ -1,3 +1,3 @@
 export { OpfsBlockStore, deleteOpfsDatabase } from "./store.js";
+export { OpfsUncertainOutcomeError } from "../types.js";
 export { OpfsTree } from "./files.js";
-//# sourceMappingURL=index.js.map