@ricsam/isolate-fs 0.0.1 → 0.1.2

package/dist/types/isolate.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Global Type Definitions for @ricsam/isolate-fs
+ *
+ * These types define the globals injected by setupFs() into an isolated-vm context.
+ * Use these types to typecheck user code that will run inside the V8 isolate.
+ *
+ * @example
+ * // Typecheck isolate code with file system access
+ * const root = await getDirectory("/data");
+ * const fileHandle = await root.getFileHandle("config.json");
+ * const file = await fileHandle.getFile();
+ * const content = await file.text();
+ */
+
+export {};
+
+declare global {
+  // ============================================
+  // getDirectory - Isolate-specific entry point
+  // ============================================
+
+  /**
+   * 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 getDirectory("/");
+   * const dataDir = await 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/dist/types/node-adapter.d.ts

@@ -0,0 +1,24 @@
+import * as nodeFs from "node:fs";
+import type { FileSystemHandler } from "./index.ts";
+export interface NodeFileSystemHandlerOptions {
+    /** Custom fs module (e.g., memfs for testing). Defaults to Node.js fs */
+    fs?: typeof nodeFs;
+}
+/**
+ * Create a FileSystemHandler backed by the Node.js filesystem
+ *
+ * @param rootPath - Absolute path to the root directory for the sandbox
+ * @param options - Optional configuration
+ * @returns FileSystemHandler implementation
+ *
+ * @example
+ * import { createNodeFileSystemHandler } from "@ricsam/isolate-fs";
+ *
+ * const handler = createNodeFileSystemHandler("/tmp/sandbox");
+ *
+ * // Use with createRuntime
+ * const runtime = await createRuntime({
+ *   fs: { handler }
+ * });
+ */
+export declare function createNodeFileSystemHandler(rootPath: string, options?: NodeFileSystemHandlerOptions): FileSystemHandler;

package/package.json

@@ -1,10 +1,59 @@
 {
   "name": "@ricsam/isolate-fs",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @ricsam/isolate-fs",
+  "version": "0.1.2",
+  "main": "./dist/cjs/index.cjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "import": "./dist/mjs/index.mjs"
+    },
+    "./isolate": {
+      "types": "./dist/types/isolate.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test --experimental-strip-types 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ricsam/isolate-core": "*",
+    "isolated-vm": "^6",
+    "mime-types": "^3.0.2"
+  },
+  "peerDependencies": {
+    "isolated-vm": "^6"
+  },
+  "author": "Richard Samuelsson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/isolate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ricsam/isolate/issues"
+  },
+  "homepage": "https://github.com/ricsam/isolate#readme",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
+    "isolated-vm",
+    "sandbox",
+    "javascript",
+    "runtime",
+    "fetch",
+    "filesystem",
+    "streams",
+    "v8",
+    "isolate"
+  ],
+  "description": "File system API implementation for isolated-vm V8 sandbox",
+  "module": "./dist/mjs/index.mjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
   ]
-}
+}