@ricsam/quickjs-fs 0.2.10 → 0.2.11

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/quickjs-fs",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "type": "commonjs"
 }

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/quickjs-fs",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "type": "module"
 }

package/dist/types/quickjs.d.ts

@@ -0,0 +1,314 @@
+/**
+ * QuickJS Global Type Definitions for @ricsam/quickjs-fs
+ *
+ * These types define the globals injected by setupFs() into a QuickJS context.
+ * Use these types to typecheck user code that will run inside QuickJS.
+ *
+ * @example
+ * // Typecheck QuickJS code with file system access
+ * const root = await fs.getDirectory("/data");
+ * const fileHandle = await root.getFileHandle("config.json");
+ * const file = await fileHandle.getFile();
+ * const content = await file.text();
+ */
+
+export {};
+
+declare global {
+  // ============================================
+  // fs namespace - QuickJS-specific entry point
+  // ============================================
+
+  /**
+   * File System namespace providing access to the file system.
+   * This is the QuickJS-specific entry point (differs from browser's navigator.storage.getDirectory()).
+   */
+  namespace fs {
+    /**
+     * Get a directory handle for the given path.
+     *
+     * The host controls which paths are accessible. Invalid or unauthorized
+     * paths will throw an error.
+     *
+     * @param path - The path to request from the host
+     * @returns A promise resolving to a directory handle
+     * @throws If the path is not allowed or doesn't exist
+     *
+     * @example
+     * const root = await fs.getDirectory("/");
+     * const dataDir = await fs.getDirectory("/data");
+     */
+    function getDirectory(path: string): Promise<FileSystemDirectoryHandle>;
+  }
+
+  // ============================================
+  // File System Access API
+  // ============================================
+
+  /**
+   * Base interface for file system handles.
+   */
+  interface FileSystemHandle {
+    /**
+     * The kind of handle: "file" or "directory".
+     */
+    readonly kind: "file" | "directory";
+
+    /**
+     * The name of the file or directory.
+     */
+    readonly name: string;
+
+    /**
+     * Compare two handles to check if they reference the same entry.
+     *
+     * @param other - Another FileSystemHandle to compare against
+     * @returns true if both handles reference the same entry
+     */
+    isSameEntry(other: FileSystemHandle): Promise<boolean>;
+  }
+
+  /**
+   * Handle for a file in the file system.
+   */
+  interface FileSystemFileHandle extends FileSystemHandle {
+    /**
+     * Always "file" for file handles.
+     */
+    readonly kind: "file";
+
+    /**
+     * Get the file contents as a File object.
+     *
+     * @returns A promise resolving to a File object
+     *
+     * @example
+     * const file = await fileHandle.getFile();
+     * const text = await file.text();
+     */
+    getFile(): Promise<File>;
+
+    /**
+     * Create a writable stream for writing to the file.
+     *
+     * @param options - Options for the writable stream
+     * @returns A promise resolving to a writable stream
+     *
+     * @example
+     * const writable = await fileHandle.createWritable();
+     * await writable.write("Hello, World!");
+     * await writable.close();
+     */
+    createWritable(options?: {
+      /**
+       * If true, keeps existing file data. Otherwise, truncates the file.
+       */
+      keepExistingData?: boolean;
+    }): Promise<FileSystemWritableFileStream>;
+  }
+
+  /**
+   * Handle for a directory in the file system.
+   */
+  interface FileSystemDirectoryHandle extends FileSystemHandle {
+    /**
+     * Always "directory" for directory handles.
+     */
+    readonly kind: "directory";
+
+    /**
+     * Get a file handle within this directory.
+     *
+     * @param name - The name of the file
+     * @param options - Options for getting the file handle
+     * @returns A promise resolving to a file handle
+     * @throws If the file doesn't exist and create is not true
+     *
+     * @example
+     * const file = await dir.getFileHandle("data.json");
+     * const newFile = await dir.getFileHandle("output.txt", { create: true });
+     */
+    getFileHandle(
+      name: string,
+      options?: {
+        /**
+         * If true, creates the file if it doesn't exist.
+         */
+        create?: boolean;
+      }
+    ): Promise<FileSystemFileHandle>;
+
+    /**
+     * Get a subdirectory handle within this directory.
+     *
+     * @param name - The name of the subdirectory
+     * @param options - Options for getting the directory handle
+     * @returns A promise resolving to a directory handle
+     * @throws If the directory doesn't exist and create is not true
+     *
+     * @example
+     * const subdir = await dir.getDirectoryHandle("logs");
+     * const newDir = await dir.getDirectoryHandle("cache", { create: true });
+     */
+    getDirectoryHandle(
+      name: string,
+      options?: {
+        /**
+         * If true, creates the directory if it doesn't exist.
+         */
+        create?: boolean;
+      }
+    ): Promise<FileSystemDirectoryHandle>;
+
+    /**
+     * Remove a file or directory within this directory.
+     *
+     * @param name - The name of the entry to remove
+     * @param options - Options for removal
+     * @throws If the entry doesn't exist or cannot be removed
+     *
+     * @example
+     * await dir.removeEntry("old-file.txt");
+     * await dir.removeEntry("old-dir", { recursive: true });
+     */
+    removeEntry(
+      name: string,
+      options?: {
+        /**
+         * If true, removes directories recursively.
+         */
+        recursive?: boolean;
+      }
+    ): Promise<void>;
+
+    /**
+     * Resolve the path from this directory to a descendant handle.
+     *
+     * @param possibleDescendant - A handle that may be a descendant
+     * @returns An array of path segments, or null if not a descendant
+     *
+     * @example
+     * const path = await root.resolve(nestedFile);
+     * // ["subdir", "file.txt"]
+     */
+    resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;
+
+    /**
+     * Iterate over entries in this directory.
+     *
+     * @returns An async iterator of [name, handle] pairs
+     *
+     * @example
+     * for await (const [name, handle] of dir.entries()) {
+     *   console.log(name, handle.kind);
+     * }
+     */
+    entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
+
+    /**
+     * Iterate over entry names in this directory.
+     *
+     * @returns An async iterator of names
+     *
+     * @example
+     * for await (const name of dir.keys()) {
+     *   console.log(name);
+     * }
+     */
+    keys(): AsyncIterableIterator<string>;
+
+    /**
+     * Iterate over handles in this directory.
+     *
+     * @returns An async iterator of handles
+     *
+     * @example
+     * for await (const handle of dir.values()) {
+     *   console.log(handle.name, handle.kind);
+     * }
+     */
+    values(): AsyncIterableIterator<FileSystemHandle>;
+
+    /**
+     * Async iterator support for directory entries.
+     *
+     * @example
+     * for await (const [name, handle] of dir) {
+     *   console.log(name, handle.kind);
+     * }
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;
+  }
+
+  /**
+   * Parameters for write operations on FileSystemWritableFileStream.
+   */
+  interface WriteParams {
+    /**
+     * The type of write operation.
+     * - "write": Write data at the current position or specified position
+     * - "seek": Move the file position
+     * - "truncate": Truncate the file to a specific size
+     */
+    type: "write" | "seek" | "truncate";
+
+    /**
+     * The data to write (for "write" type).
+     */
+    data?: string | ArrayBuffer | Uint8Array | Blob;
+
+    /**
+     * The position to write at or seek to.
+     */
+    position?: number;
+
+    /**
+     * The size to truncate to (for "truncate" type).
+     */
+    size?: number;
+  }
+
+  /**
+   * Writable stream for writing to a file.
+   * Extends WritableStream with file-specific operations.
+   */
+  interface FileSystemWritableFileStream extends WritableStream<Uint8Array> {
+    /**
+     * Write data to the file.
+     *
+     * @param data - The data to write
+     * @returns A promise that resolves when the write completes
+     *
+     * @example
+     * await writable.write("Hello, World!");
+     * await writable.write(new Uint8Array([1, 2, 3]));
+     * await writable.write({ type: "write", data: "text", position: 0 });
+     */
+    write(
+      data: string | ArrayBuffer | Uint8Array | Blob | WriteParams
+    ): Promise<void>;
+
+    /**
+     * Seek to a position in the file.
+     *
+     * @param position - The byte position to seek to
+     * @returns A promise that resolves when the seek completes
+     *
+     * @example
+     * await writable.seek(0); // Seek to beginning
+     * await writable.write("Overwrite");
+     */
+    seek(position: number): Promise<void>;
+
+    /**
+     * Truncate the file to a specific size.
+     *
+     * @param size - The size to truncate to
+     * @returns A promise that resolves when the truncation completes
+     *
+     * @example
+     * await writable.truncate(100); // Keep only first 100 bytes
+     */
+    truncate(size: number): Promise<void>;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/quickjs-fs",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "main": "./dist/cjs/index.cjs",
   "types": "./dist/types/index.d.ts",
   "exports": {
@@ -8,6 +8,9 @@
       "types": "./dist/types/index.d.ts",
       "require": "./dist/cjs/index.cjs",
       "import": "./dist/mjs/index.mjs"
+    },
+    "./quickjs": {
+      "types": "./dist/types/quickjs.d.ts"
     }
   },
   "scripts": {
@@ -16,7 +19,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ricsam/quickjs-core": "^0.2.10",
+    "@ricsam/quickjs-core": "^0.2.11",
     "quickjs-emscripten": "^0.31.0"
   },
   "peerDependencies": {