@ricsam/quickjs-test-utils 1.0.19 → 1.0.21

package/dist/types/quickjs-types.d.ts

@@ -57,6 +57,14 @@ export declare const CRYPTO_TYPES = "/**\n * QuickJS Global Type Definitions for
  *
  * Includes: setTimeout, setInterval, clearTimeout, clearInterval
  */
+/**
+ * Type definitions for @ricsam/quickjs-path globals.
+ *
+ * Includes: path.join, path.normalize, path.basename, path.dirname, path.extname,
+ *           path.isAbsolute, path.parse, path.format, path.resolve, path.relative,
+ *           path.cwd, path.sep, path.delimiter
+ */
+export declare const PATH_TYPES = "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-path\n *\n * These types define the globals injected by setupPath() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * // Typecheck QuickJS code with path operations\n * const joined = path.join('/foo', 'bar', 'baz');\n * const resolved = path.resolve('relative/path');\n * const cwd = path.cwd();\n */\n\nexport {};\n\ndeclare global {\n  /**\n   * Parsed path object returned by path.parse().\n   */\n  interface ParsedPath {\n    /** The root of the path (e.g., \"/\" for absolute paths, \"\" for relative) */\n    root: string;\n    /** The directory portion of the path */\n    dir: string;\n    /** The file name including extension */\n    base: string;\n    /** The file extension (e.g., \".txt\") */\n    ext: string;\n    /** The file name without extension */\n    name: string;\n  }\n\n  /**\n   * Input object for path.format().\n   */\n  interface FormatInputPathObject {\n    root?: string;\n    dir?: string;\n    base?: string;\n    ext?: string;\n    name?: string;\n  }\n\n  /**\n   * Path utilities for POSIX paths.\n   * @see https://nodejs.org/api/path.html\n   */\n  namespace path {\n    /**\n     * Join path segments with the platform-specific separator.\n     *\n     * @param paths - Path segments to join\n     * @returns The joined path, normalized\n     *\n     * @example\n     * path.join('/foo', 'bar', 'baz'); // \"/foo/bar/baz\"\n     * path.join('foo', 'bar', '..', 'baz'); // \"foo/baz\"\n     */\n    function join(...paths: string[]): string;\n\n    /**\n     * Normalize a path, resolving '..' and '.' segments.\n     *\n     * @param p - The path to normalize\n     * @returns The normalized path\n     *\n     * @example\n     * path.normalize('/foo/bar/../baz'); // \"/foo/baz\"\n     * path.normalize('/foo//bar'); // \"/foo/bar\"\n     */\n    function normalize(p: string): string;\n\n    /**\n     * Get the last portion of a path (the file name).\n     *\n     * @param p - The path\n     * @param ext - Optional extension to remove from the result\n     * @returns The base name of the path\n     *\n     * @example\n     * path.basename('/foo/bar/baz.txt'); // \"baz.txt\"\n     * path.basename('/foo/bar/baz.txt', '.txt'); // \"baz\"\n     */\n    function basename(p: string, ext?: string): string;\n\n    /**\n     * Get the directory name of a path.\n     *\n     * @param p - The path\n     * @returns The directory portion of the path\n     *\n     * @example\n     * path.dirname('/foo/bar/baz.txt'); // \"/foo/bar\"\n     * path.dirname('/foo'); // \"/\"\n     */\n    function dirname(p: string): string;\n\n    /**\n     * Get the extension of a path.\n     *\n     * @param p - The path\n     * @returns The extension including the dot, or empty string\n     *\n     * @example\n     * path.extname('file.txt'); // \".txt\"\n     * path.extname('file.tar.gz'); // \".gz\"\n     * path.extname('.bashrc'); // \"\"\n     */\n    function extname(p: string): string;\n\n    /**\n     * Check if a path is absolute.\n     *\n     * @param p - The path to check\n     * @returns True if the path is absolute\n     *\n     * @example\n     * path.isAbsolute('/foo/bar'); // true\n     * path.isAbsolute('foo/bar'); // false\n     */\n    function isAbsolute(p: string): boolean;\n\n    /**\n     * Parse a path into its components.\n     *\n     * @param p - The path to parse\n     * @returns An object with root, dir, base, ext, and name properties\n     *\n     * @example\n     * path.parse('/foo/bar/baz.txt');\n     * // { root: \"/\", dir: \"/foo/bar\", base: \"baz.txt\", ext: \".txt\", name: \"baz\" }\n     */\n    function parse(p: string): ParsedPath;\n\n    /**\n     * Build a path from an object.\n     *\n     * @param pathObject - Object with path components\n     * @returns The formatted path string\n     *\n     * @example\n     * path.format({ dir: '/foo/bar', base: 'baz.txt' }); // \"/foo/bar/baz.txt\"\n     * path.format({ root: '/', name: 'file', ext: '.txt' }); // \"/file.txt\"\n     */\n    function format(pathObject: FormatInputPathObject): string;\n\n    /**\n     * Resolve a sequence of paths to an absolute path.\n     * Processes paths from right to left, prepending each until an absolute path is formed.\n     * Uses the configured working directory for relative paths.\n     *\n     * @param paths - Path segments to resolve\n     * @returns The resolved absolute path\n     *\n     * @example\n     * // With cwd set to \"/home/user\"\n     * path.resolve('foo/bar'); // \"/home/user/foo/bar\"\n     * path.resolve('/foo', 'bar'); // \"/foo/bar\"\n     * path.resolve('/foo', '/bar', 'baz'); // \"/bar/baz\"\n     */\n    function resolve(...paths: string[]): string;\n\n    /**\n     * Compute the relative path from one path to another.\n     *\n     * @param from - The source path\n     * @param to - The destination path\n     * @returns The relative path from 'from' to 'to'\n     *\n     * @example\n     * path.relative('/foo/bar', '/foo/baz'); // \"../baz\"\n     * path.relative('/foo', '/foo/bar/baz'); // \"bar/baz\"\n     */\n    function relative(from: string, to: string): string;\n\n    /**\n     * Get the configured working directory.\n     *\n     * @returns The current working directory\n     *\n     * @example\n     * path.cwd(); // \"/home/user\" (or whatever was configured)\n     */\n    function cwd(): string;\n\n    /**\n     * The platform-specific path segment separator.\n     * Always \"/\" for POSIX paths.\n     */\n    const sep: string;\n\n    /**\n     * The platform-specific path delimiter.\n     * Always \":\" for POSIX paths.\n     */\n    const delimiter: string;\n  }\n}\n";
 export declare const TIMERS_TYPES = "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-timers\n *\n * These types define the globals injected by setupTimers() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * const timeoutId = setTimeout(() => {\n *   console.log(\"fired!\");\n * }, 1000);\n *\n * clearTimeout(timeoutId);\n *\n * const intervalId = setInterval(() => {\n *   console.log(\"tick\");\n * }, 100);\n *\n * clearInterval(intervalId);\n */\n\nexport {};\n\ndeclare global {\n  /**\n   * Schedule a callback to execute after a delay.\n   *\n   * @param callback - The function to call after the delay\n   * @param ms - The delay in milliseconds (default: 0)\n   * @param args - Additional arguments to pass to the callback\n   * @returns A timer ID that can be passed to clearTimeout\n   *\n   * @example\n   * const id = setTimeout(() => console.log(\"done\"), 1000);\n   * setTimeout((a, b) => console.log(a, b), 100, \"hello\", \"world\");\n   */\n  function setTimeout(\n    callback: (...args: unknown[]) => void,\n    ms?: number,\n    ...args: unknown[]\n  ): number;\n\n  /**\n   * Schedule a callback to execute repeatedly at a fixed interval.\n   *\n   * @param callback - The function to call at each interval\n   * @param ms - The interval in milliseconds (minimum: 4ms)\n   * @param args - Additional arguments to pass to the callback\n   * @returns A timer ID that can be passed to clearInterval\n   *\n   * @example\n   * const id = setInterval(() => console.log(\"tick\"), 1000);\n   */\n  function setInterval(\n    callback: (...args: unknown[]) => void,\n    ms?: number,\n    ...args: unknown[]\n  ): number;\n\n  /**\n   * Cancel a timeout previously scheduled with setTimeout.\n   *\n   * @param id - The timer ID returned by setTimeout\n   *\n   * @example\n   * const id = setTimeout(() => {}, 1000);\n   * clearTimeout(id);\n   */\n  function clearTimeout(id: number | undefined): void;\n\n  /**\n   * Cancel an interval previously scheduled with setInterval.\n   *\n   * @param id - The timer ID returned by setInterval\n   *\n   * @example\n   * const id = setInterval(() => {}, 1000);\n   * clearInterval(id);\n   */\n  function clearInterval(id: number | undefined): void;\n}\n";
 /**
  * Map of package names to their type definitions.
@@ -68,6 +76,7 @@ export declare const TYPE_DEFINITIONS: {
     readonly encoding: "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-encoding\n *\n * These types define the globals injected by setupEncoding() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n */\n\nexport {};\n\ndeclare global {\n  /**\n   * Decodes a Base64-encoded string.\n   *\n   * @param encodedData - The Base64 string to decode\n   * @returns The decoded string\n   * @throws DOMException if the input is not valid Base64\n   *\n   * @example\n   * atob(\"SGVsbG8=\"); // \"Hello\"\n   */\n  function atob(encodedData: string): string;\n\n  /**\n   * Encodes a string to Base64.\n   *\n   * @param stringToEncode - The string to encode (must contain only Latin1 characters)\n   * @returns The Base64 encoded string\n   * @throws DOMException if the string contains characters outside Latin1 range (0-255)\n   *\n   * @example\n   * btoa(\"Hello\"); // \"SGVsbG8=\"\n   */\n  function btoa(stringToEncode: string): string;\n}\n";
     readonly fetch: "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-fetch\n *\n * These types define the globals injected by setupFetch() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * // Typecheck QuickJS code with serve()\n * type WebSocketData = { id: number; connectedAt: number };\n *\n * serve({\n *   fetch(request, server) {\n *     if (request.url.includes(\"/ws\")) {\n *       // server.upgrade knows data should be WebSocketData\n *       server.upgrade(request, { data: { id: 123, connectedAt: Date.now() } });\n *       return new Response(null, { status: 101 });\n *     }\n *     return new Response(\"Hello!\");\n *   },\n *   websocket: {\n *     // Type hint - specifies the type of ws.data\n *     data: {} as WebSocketData,\n *     message(ws, message) {\n *       // ws.data is typed as WebSocketData\n *       console.log(\"User\", ws.data.id, \"says:\", message);\n *       ws.send(\"Echo: \" + message);\n *     }\n *   }\n * });\n */\n\nexport {};\n\ndeclare global {\n  // ============================================\n  // Standard Fetch API (from lib.dom)\n  // ============================================\n\n  /**\n   * Headers class for HTTP headers manipulation.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/Headers\n   */\n  const Headers: typeof globalThis.Headers;\n\n  /**\n   * Request class for HTTP requests.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/Request\n   */\n  const Request: typeof globalThis.Request;\n\n  /**\n   * Response class for HTTP responses.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/Response\n   */\n  const Response: typeof globalThis.Response;\n\n  /**\n   * AbortController for cancelling fetch requests.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController\n   */\n  const AbortController: typeof globalThis.AbortController;\n\n  /**\n   * AbortSignal for listening to abort events.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal\n   */\n  const AbortSignal: typeof globalThis.AbortSignal;\n\n  /**\n   * FormData for constructing form data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/FormData\n   */\n  const FormData: typeof globalThis.FormData;\n\n  /**\n   * Fetch function for making HTTP requests.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/fetch\n   */\n  function fetch(\n    input: RequestInfo | URL,\n    init?: RequestInit\n  ): Promise<Response>;\n\n  // ============================================\n  // QuickJS-specific: serve() API\n  // ============================================\n\n  /**\n   * Server interface for handling WebSocket upgrades within serve() handlers.\n   *\n   * @typeParam T - The type of data associated with WebSocket connections\n   */\n  interface Server<T = unknown> {\n    /**\n     * Upgrade an HTTP request to a WebSocket connection.\n     *\n     * @param request - The incoming HTTP request to upgrade\n     * @param options - Optional data to associate with the WebSocket connection\n     * @returns true if upgrade will proceed, false otherwise\n     *\n     * @example\n     * serve({\n     *   fetch(request, server) {\n     *     if (server.upgrade(request, { data: { userId: 123 } })) {\n     *       return new Response(null, { status: 101 });\n     *     }\n     *     return new Response(\"Upgrade failed\", { status: 400 });\n     *   }\n     * });\n     */\n    upgrade(request: Request, options?: { data?: T }): boolean;\n  }\n\n  /**\n   * ServerWebSocket interface for WebSocket connections within serve() handlers.\n   *\n   * @typeParam T - The type of data associated with this WebSocket connection\n   */\n  interface ServerWebSocket<T = unknown> {\n    /**\n     * User data associated with this connection.\n     * Set via `server.upgrade(request, { data: ... })`.\n     */\n    readonly data: T;\n\n    /**\n     * Send a message to the client.\n     *\n     * @param message - The message to send (string, ArrayBuffer, or Uint8Array)\n     */\n    send(message: string | ArrayBuffer | Uint8Array): void;\n\n    /**\n     * Close the WebSocket connection.\n     *\n     * @param code - Optional close code (default: 1000)\n     * @param reason - Optional close reason\n     */\n    close(code?: number, reason?: string): void;\n\n    /**\n     * WebSocket ready state.\n     * - 0: CONNECTING\n     * - 1: OPEN\n     * - 2: CLOSING\n     * - 3: CLOSED\n     */\n    readonly readyState: number;\n  }\n\n  /**\n   * Options for the serve() function.\n   *\n   * @typeParam T - The type of data associated with WebSocket connections\n   */\n  interface ServeOptions<T = unknown> {\n    /**\n     * Handler for HTTP requests.\n     *\n     * @param request - The incoming HTTP request\n     * @param server - Server interface for WebSocket upgrades\n     * @returns Response or Promise resolving to Response\n     */\n    fetch(request: Request, server: Server<T>): Response | Promise<Response>;\n\n    /**\n     * WebSocket event handlers.\n     */\n    websocket?: {\n      /**\n       * Type hint for WebSocket data. The value is not used at runtime.\n       * Specifies the type of `ws.data` for all handlers and `server.upgrade()`.\n       *\n       * @example\n       * websocket: {\n       *   data: {} as { userId: string },\n       *   message(ws, message) {\n       *     // ws.data.userId is typed as string\n       *   }\n       * }\n       */\n      data?: T;\n\n      /**\n       * Called when a WebSocket connection is opened.\n       *\n       * @param ws - The WebSocket connection\n       */\n      open?(ws: ServerWebSocket<T>): void | Promise<void>;\n\n      /**\n       * Called when a message is received.\n       *\n       * @param ws - The WebSocket connection\n       * @param message - The received message (string or ArrayBuffer)\n       */\n      message?(\n        ws: ServerWebSocket<T>,\n        message: string | ArrayBuffer\n      ): void | Promise<void>;\n\n      /**\n       * Called when the connection is closed.\n       *\n       * @param ws - The WebSocket connection\n       * @param code - The close code\n       * @param reason - The close reason\n       */\n      close?(\n        ws: ServerWebSocket<T>,\n        code: number,\n        reason: string\n      ): void | Promise<void>;\n\n      /**\n       * Called when an error occurs.\n       *\n       * @param ws - The WebSocket connection\n       * @param error - The error that occurred\n       */\n      error?(ws: ServerWebSocket<T>, error: Error): void | Promise<void>;\n    };\n  }\n\n  /**\n   * Register an HTTP server handler in QuickJS.\n   *\n   * Only one serve() handler can be active at a time.\n   * Calling serve() again replaces the previous handler.\n   *\n   * @param options - Server configuration including fetch handler and optional WebSocket handlers\n   *\n   * @example\n   * type WsData = { connectedAt: number };\n   *\n   * serve({\n   *   fetch(request, server) {\n   *     const url = new URL(request.url);\n   *\n   *     if (url.pathname === \"/ws\") {\n   *       if (server.upgrade(request, { data: { connectedAt: Date.now() } })) {\n   *         return new Response(null, { status: 101 });\n   *       }\n   *     }\n   *\n   *     if (url.pathname === \"/api/hello\") {\n   *       return Response.json({ message: \"Hello!\" });\n   *     }\n   *\n   *     return new Response(\"Not Found\", { status: 404 });\n   *   },\n   *   websocket: {\n   *     data: {} as WsData,\n   *     open(ws) {\n   *       console.log(\"Connected at:\", ws.data.connectedAt);\n   *     },\n   *     message(ws, message) {\n   *       ws.send(\"Echo: \" + message);\n   *     },\n   *     close(ws, code, reason) {\n   *       console.log(\"Closed:\", code, reason);\n   *     }\n   *   }\n   * });\n   */\n  function serve<T = unknown>(options: ServeOptions<T>): void;\n}\n";
     readonly fs: "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-fs\n *\n * These types define the globals injected by setupFs() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * // Typecheck QuickJS code with file system access\n * const root = await fs.getDirectory(\"/data\");\n * const fileHandle = await root.getFileHandle(\"config.json\");\n * const file = await fileHandle.getFile();\n * const content = await file.text();\n */\n\nexport {};\n\ndeclare global {\n  // ============================================\n  // fs namespace - QuickJS-specific entry point\n  // ============================================\n\n  /**\n   * File System namespace providing access to the file system.\n   * This is the QuickJS-specific entry point (differs from browser's navigator.storage.getDirectory()).\n   */\n  namespace fs {\n    /**\n     * Get a directory handle for the given path.\n     *\n     * The host controls which paths are accessible. Invalid or unauthorized\n     * paths will throw an error.\n     *\n     * @param path - The path to request from the host\n     * @returns A promise resolving to a directory handle\n     * @throws If the path is not allowed or doesn't exist\n     *\n     * @example\n     * const root = await fs.getDirectory(\"/\");\n     * const dataDir = await fs.getDirectory(\"/data\");\n     */\n    function getDirectory(path: string): Promise<FileSystemDirectoryHandle>;\n  }\n\n  // ============================================\n  // File System Access API\n  // ============================================\n\n  /**\n   * Base interface for file system handles.\n   */\n  interface FileSystemHandle {\n    /**\n     * The kind of handle: \"file\" or \"directory\".\n     */\n    readonly kind: \"file\" | \"directory\";\n\n    /**\n     * The name of the file or directory.\n     */\n    readonly name: string;\n\n    /**\n     * Compare two handles to check if they reference the same entry.\n     *\n     * @param other - Another FileSystemHandle to compare against\n     * @returns true if both handles reference the same entry\n     */\n    isSameEntry(other: FileSystemHandle): Promise<boolean>;\n  }\n\n  /**\n   * Handle for a file in the file system.\n   */\n  interface FileSystemFileHandle extends FileSystemHandle {\n    /**\n     * Always \"file\" for file handles.\n     */\n    readonly kind: \"file\";\n\n    /**\n     * Get the file contents as a File object.\n     *\n     * @returns A promise resolving to a File object\n     *\n     * @example\n     * const file = await fileHandle.getFile();\n     * const text = await file.text();\n     */\n    getFile(): Promise<File>;\n\n    /**\n     * Create a writable stream for writing to the file.\n     *\n     * @param options - Options for the writable stream\n     * @returns A promise resolving to a writable stream\n     *\n     * @example\n     * const writable = await fileHandle.createWritable();\n     * await writable.write(\"Hello, World!\");\n     * await writable.close();\n     */\n    createWritable(options?: {\n      /**\n       * If true, keeps existing file data. Otherwise, truncates the file.\n       */\n      keepExistingData?: boolean;\n    }): Promise<FileSystemWritableFileStream>;\n  }\n\n  /**\n   * Handle for a directory in the file system.\n   */\n  interface FileSystemDirectoryHandle extends FileSystemHandle {\n    /**\n     * Always \"directory\" for directory handles.\n     */\n    readonly kind: \"directory\";\n\n    /**\n     * Get a file handle within this directory.\n     *\n     * @param name - The name of the file\n     * @param options - Options for getting the file handle\n     * @returns A promise resolving to a file handle\n     * @throws If the file doesn't exist and create is not true\n     *\n     * @example\n     * const file = await dir.getFileHandle(\"data.json\");\n     * const newFile = await dir.getFileHandle(\"output.txt\", { create: true });\n     */\n    getFileHandle(\n      name: string,\n      options?: {\n        /**\n         * If true, creates the file if it doesn't exist.\n         */\n        create?: boolean;\n      }\n    ): Promise<FileSystemFileHandle>;\n\n    /**\n     * Get a subdirectory handle within this directory.\n     *\n     * @param name - The name of the subdirectory\n     * @param options - Options for getting the directory handle\n     * @returns A promise resolving to a directory handle\n     * @throws If the directory doesn't exist and create is not true\n     *\n     * @example\n     * const subdir = await dir.getDirectoryHandle(\"logs\");\n     * const newDir = await dir.getDirectoryHandle(\"cache\", { create: true });\n     */\n    getDirectoryHandle(\n      name: string,\n      options?: {\n        /**\n         * If true, creates the directory if it doesn't exist.\n         */\n        create?: boolean;\n      }\n    ): Promise<FileSystemDirectoryHandle>;\n\n    /**\n     * Remove a file or directory within this directory.\n     *\n     * @param name - The name of the entry to remove\n     * @param options - Options for removal\n     * @throws If the entry doesn't exist or cannot be removed\n     *\n     * @example\n     * await dir.removeEntry(\"old-file.txt\");\n     * await dir.removeEntry(\"old-dir\", { recursive: true });\n     */\n    removeEntry(\n      name: string,\n      options?: {\n        /**\n         * If true, removes directories recursively.\n         */\n        recursive?: boolean;\n      }\n    ): Promise<void>;\n\n    /**\n     * Resolve the path from this directory to a descendant handle.\n     *\n     * @param possibleDescendant - A handle that may be a descendant\n     * @returns An array of path segments, or null if not a descendant\n     *\n     * @example\n     * const path = await root.resolve(nestedFile);\n     * // [\"subdir\", \"file.txt\"]\n     */\n    resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;\n\n    /**\n     * Iterate over entries in this directory.\n     *\n     * @returns An async iterator of [name, handle] pairs\n     *\n     * @example\n     * for await (const [name, handle] of dir.entries()) {\n     *   console.log(name, handle.kind);\n     * }\n     */\n    entries(): AsyncIterableIterator<[string, FileSystemHandle]>;\n\n    /**\n     * Iterate over entry names in this directory.\n     *\n     * @returns An async iterator of names\n     *\n     * @example\n     * for await (const name of dir.keys()) {\n     *   console.log(name);\n     * }\n     */\n    keys(): AsyncIterableIterator<string>;\n\n    /**\n     * Iterate over handles in this directory.\n     *\n     * @returns An async iterator of handles\n     *\n     * @example\n     * for await (const handle of dir.values()) {\n     *   console.log(handle.name, handle.kind);\n     * }\n     */\n    values(): AsyncIterableIterator<FileSystemHandle>;\n\n    /**\n     * Async iterator support for directory entries.\n     *\n     * @example\n     * for await (const [name, handle] of dir) {\n     *   console.log(name, handle.kind);\n     * }\n     */\n    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;\n  }\n\n  /**\n   * Parameters for write operations on FileSystemWritableFileStream.\n   */\n  interface WriteParams {\n    /**\n     * The type of write operation.\n     * - \"write\": Write data at the current position or specified position\n     * - \"seek\": Move the file position\n     * - \"truncate\": Truncate the file to a specific size\n     */\n    type: \"write\" | \"seek\" | \"truncate\";\n\n    /**\n     * The data to write (for \"write\" type).\n     */\n    data?: string | ArrayBuffer | Uint8Array | Blob;\n\n    /**\n     * The position to write at or seek to.\n     */\n    position?: number;\n\n    /**\n     * The size to truncate to (for \"truncate\" type).\n     */\n    size?: number;\n  }\n\n  /**\n   * Writable stream for writing to a file.\n   * Extends WritableStream with file-specific operations.\n   */\n  interface FileSystemWritableFileStream extends WritableStream<Uint8Array> {\n    /**\n     * Write data to the file.\n     *\n     * @param data - The data to write\n     * @returns A promise that resolves when the write completes\n     *\n     * @example\n     * await writable.write(\"Hello, World!\");\n     * await writable.write(new Uint8Array([1, 2, 3]));\n     * await writable.write({ type: \"write\", data: \"text\", position: 0 });\n     */\n    write(\n      data: string | ArrayBuffer | Uint8Array | Blob | WriteParams\n    ): Promise<void>;\n\n    /**\n     * Seek to a position in the file.\n     *\n     * @param position - The byte position to seek to\n     * @returns A promise that resolves when the seek completes\n     *\n     * @example\n     * await writable.seek(0); // Seek to beginning\n     * await writable.write(\"Overwrite\");\n     */\n    seek(position: number): Promise<void>;\n\n    /**\n     * Truncate the file to a specific size.\n     *\n     * @param size - The size to truncate to\n     * @returns A promise that resolves when the truncation completes\n     *\n     * @example\n     * await writable.truncate(100); // Keep only first 100 bytes\n     */\n    truncate(size: number): Promise<void>;\n  }\n}\n";
+    readonly path: "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-path\n *\n * These types define the globals injected by setupPath() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * // Typecheck QuickJS code with path operations\n * const joined = path.join('/foo', 'bar', 'baz');\n * const resolved = path.resolve('relative/path');\n * const cwd = path.cwd();\n */\n\nexport {};\n\ndeclare global {\n  /**\n   * Parsed path object returned by path.parse().\n   */\n  interface ParsedPath {\n    /** The root of the path (e.g., \"/\" for absolute paths, \"\" for relative) */\n    root: string;\n    /** The directory portion of the path */\n    dir: string;\n    /** The file name including extension */\n    base: string;\n    /** The file extension (e.g., \".txt\") */\n    ext: string;\n    /** The file name without extension */\n    name: string;\n  }\n\n  /**\n   * Input object for path.format().\n   */\n  interface FormatInputPathObject {\n    root?: string;\n    dir?: string;\n    base?: string;\n    ext?: string;\n    name?: string;\n  }\n\n  /**\n   * Path utilities for POSIX paths.\n   * @see https://nodejs.org/api/path.html\n   */\n  namespace path {\n    /**\n     * Join path segments with the platform-specific separator.\n     *\n     * @param paths - Path segments to join\n     * @returns The joined path, normalized\n     *\n     * @example\n     * path.join('/foo', 'bar', 'baz'); // \"/foo/bar/baz\"\n     * path.join('foo', 'bar', '..', 'baz'); // \"foo/baz\"\n     */\n    function join(...paths: string[]): string;\n\n    /**\n     * Normalize a path, resolving '..' and '.' segments.\n     *\n     * @param p - The path to normalize\n     * @returns The normalized path\n     *\n     * @example\n     * path.normalize('/foo/bar/../baz'); // \"/foo/baz\"\n     * path.normalize('/foo//bar'); // \"/foo/bar\"\n     */\n    function normalize(p: string): string;\n\n    /**\n     * Get the last portion of a path (the file name).\n     *\n     * @param p - The path\n     * @param ext - Optional extension to remove from the result\n     * @returns The base name of the path\n     *\n     * @example\n     * path.basename('/foo/bar/baz.txt'); // \"baz.txt\"\n     * path.basename('/foo/bar/baz.txt', '.txt'); // \"baz\"\n     */\n    function basename(p: string, ext?: string): string;\n\n    /**\n     * Get the directory name of a path.\n     *\n     * @param p - The path\n     * @returns The directory portion of the path\n     *\n     * @example\n     * path.dirname('/foo/bar/baz.txt'); // \"/foo/bar\"\n     * path.dirname('/foo'); // \"/\"\n     */\n    function dirname(p: string): string;\n\n    /**\n     * Get the extension of a path.\n     *\n     * @param p - The path\n     * @returns The extension including the dot, or empty string\n     *\n     * @example\n     * path.extname('file.txt'); // \".txt\"\n     * path.extname('file.tar.gz'); // \".gz\"\n     * path.extname('.bashrc'); // \"\"\n     */\n    function extname(p: string): string;\n\n    /**\n     * Check if a path is absolute.\n     *\n     * @param p - The path to check\n     * @returns True if the path is absolute\n     *\n     * @example\n     * path.isAbsolute('/foo/bar'); // true\n     * path.isAbsolute('foo/bar'); // false\n     */\n    function isAbsolute(p: string): boolean;\n\n    /**\n     * Parse a path into its components.\n     *\n     * @param p - The path to parse\n     * @returns An object with root, dir, base, ext, and name properties\n     *\n     * @example\n     * path.parse('/foo/bar/baz.txt');\n     * // { root: \"/\", dir: \"/foo/bar\", base: \"baz.txt\", ext: \".txt\", name: \"baz\" }\n     */\n    function parse(p: string): ParsedPath;\n\n    /**\n     * Build a path from an object.\n     *\n     * @param pathObject - Object with path components\n     * @returns The formatted path string\n     *\n     * @example\n     * path.format({ dir: '/foo/bar', base: 'baz.txt' }); // \"/foo/bar/baz.txt\"\n     * path.format({ root: '/', name: 'file', ext: '.txt' }); // \"/file.txt\"\n     */\n    function format(pathObject: FormatInputPathObject): string;\n\n    /**\n     * Resolve a sequence of paths to an absolute path.\n     * Processes paths from right to left, prepending each until an absolute path is formed.\n     * Uses the configured working directory for relative paths.\n     *\n     * @param paths - Path segments to resolve\n     * @returns The resolved absolute path\n     *\n     * @example\n     * // With cwd set to \"/home/user\"\n     * path.resolve('foo/bar'); // \"/home/user/foo/bar\"\n     * path.resolve('/foo', 'bar'); // \"/foo/bar\"\n     * path.resolve('/foo', '/bar', 'baz'); // \"/bar/baz\"\n     */\n    function resolve(...paths: string[]): string;\n\n    /**\n     * Compute the relative path from one path to another.\n     *\n     * @param from - The source path\n     * @param to - The destination path\n     * @returns The relative path from 'from' to 'to'\n     *\n     * @example\n     * path.relative('/foo/bar', '/foo/baz'); // \"../baz\"\n     * path.relative('/foo', '/foo/bar/baz'); // \"bar/baz\"\n     */\n    function relative(from: string, to: string): string;\n\n    /**\n     * Get the configured working directory.\n     *\n     * @returns The current working directory\n     *\n     * @example\n     * path.cwd(); // \"/home/user\" (or whatever was configured)\n     */\n    function cwd(): string;\n\n    /**\n     * The platform-specific path segment separator.\n     * Always \"/\" for POSIX paths.\n     */\n    const sep: string;\n\n    /**\n     * The platform-specific path delimiter.\n     * Always \":\" for POSIX paths.\n     */\n    const delimiter: string;\n  }\n}\n";
     readonly testEnvironment: "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-test-environment\n *\n * These types define the globals injected by setupTestEnvironment() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * describe(\"Math operations\", () => {\n *   it(\"should add numbers\", () => {\n *     expect(1 + 1).toBe(2);\n *   });\n * });\n */\n\nexport {};\n\ndeclare global {\n  // ============================================\n  // Test Structure\n  // ============================================\n\n  /**\n   * Define a test suite.\n   *\n   * @param name - The name of the test suite\n   * @param fn - Function containing tests and nested suites\n   *\n   * @example\n   * describe(\"Calculator\", () => {\n   *   it(\"adds numbers\", () => {\n   *     expect(1 + 1).toBe(2);\n   *   });\n   * });\n   */\n  function describe(name: string, fn: () => void): void;\n\n  namespace describe {\n    /**\n     * Skip this suite and all its tests.\n     */\n    function skip(name: string, fn: () => void): void;\n\n    /**\n     * Only run this suite (and other .only suites).\n     */\n    function only(name: string, fn: () => void): void;\n\n    /**\n     * Mark suite as todo (skipped with different status).\n     */\n    function todo(name: string, fn?: () => void): void;\n  }\n\n  /**\n   * Define a test case.\n   *\n   * @param name - The name of the test\n   * @param fn - The test function (can be async)\n   *\n   * @example\n   * it(\"should work\", () => {\n   *   expect(true).toBe(true);\n   * });\n   *\n   * it(\"should work async\", async () => {\n   *   const result = await Promise.resolve(42);\n   *   expect(result).toBe(42);\n   * });\n   */\n  function it(name: string, fn: () => void | Promise<void>): void;\n\n  namespace it {\n    /**\n     * Skip this test.\n     */\n    function skip(name: string, fn?: () => void | Promise<void>): void;\n\n    /**\n     * Only run this test (and other .only tests).\n     */\n    function only(name: string, fn: () => void | Promise<void>): void;\n\n    /**\n     * Mark test as todo.\n     */\n    function todo(name: string, fn?: () => void | Promise<void>): void;\n  }\n\n  /**\n   * Alias for it().\n   */\n  function test(name: string, fn: () => void | Promise<void>): void;\n\n  namespace test {\n    /**\n     * Skip this test.\n     */\n    function skip(name: string, fn?: () => void | Promise<void>): void;\n\n    /**\n     * Only run this test (and other .only tests).\n     */\n    function only(name: string, fn: () => void | Promise<void>): void;\n\n    /**\n     * Mark test as todo.\n     */\n    function todo(name: string, fn?: () => void | Promise<void>): void;\n  }\n\n  // ============================================\n  // Lifecycle Hooks\n  // ============================================\n\n  /**\n   * Run once before all tests in the current suite.\n   *\n   * @param fn - Setup function (can be async)\n   */\n  function beforeAll(fn: () => void | Promise<void>): void;\n\n  /**\n   * Run once after all tests in the current suite.\n   *\n   * @param fn - Teardown function (can be async)\n   */\n  function afterAll(fn: () => void | Promise<void>): void;\n\n  /**\n   * Run before each test in the current suite (and nested suites).\n   *\n   * @param fn - Setup function (can be async)\n   */\n  function beforeEach(fn: () => void | Promise<void>): void;\n\n  /**\n   * Run after each test in the current suite (and nested suites).\n   *\n   * @param fn - Teardown function (can be async)\n   */\n  function afterEach(fn: () => void | Promise<void>): void;\n\n  // ============================================\n  // Assertions\n  // ============================================\n\n  /**\n   * Matchers for assertions.\n   */\n  interface Matchers<T> {\n    /**\n     * Strict equality (===).\n     */\n    toBe(expected: T): void;\n\n    /**\n     * Deep equality.\n     */\n    toEqual(expected: unknown): void;\n\n    /**\n     * Deep equality with type checking.\n     */\n    toStrictEqual(expected: unknown): void;\n\n    /**\n     * Check if value is truthy.\n     */\n    toBeTruthy(): void;\n\n    /**\n     * Check if value is falsy.\n     */\n    toBeFalsy(): void;\n\n    /**\n     * Check if value is null.\n     */\n    toBeNull(): void;\n\n    /**\n     * Check if value is undefined.\n     */\n    toBeUndefined(): void;\n\n    /**\n     * Check if value is defined (not undefined).\n     */\n    toBeDefined(): void;\n\n    /**\n     * Check if value is NaN.\n     */\n    toBeNaN(): void;\n\n    /**\n     * Check if number is greater than expected.\n     */\n    toBeGreaterThan(n: number): void;\n\n    /**\n     * Check if number is greater than or equal to expected.\n     */\n    toBeGreaterThanOrEqual(n: number): void;\n\n    /**\n     * Check if number is less than expected.\n     */\n    toBeLessThan(n: number): void;\n\n    /**\n     * Check if number is less than or equal to expected.\n     */\n    toBeLessThanOrEqual(n: number): void;\n\n    /**\n     * Check if array/string contains item/substring.\n     */\n    toContain(item: unknown): void;\n\n    /**\n     * Check length of array/string.\n     */\n    toHaveLength(length: number): void;\n\n    /**\n     * Check if object has property (optionally with value).\n     */\n    toHaveProperty(key: string, value?: unknown): void;\n\n    /**\n     * Check if function throws.\n     */\n    toThrow(expected?: string | RegExp | Error): void;\n\n    /**\n     * Check if string matches pattern.\n     */\n    toMatch(pattern: string | RegExp): void;\n\n    /**\n     * Check if object matches subset of properties.\n     */\n    toMatchObject(object: object): void;\n\n    /**\n     * Check if value is instance of class.\n     */\n    toBeInstanceOf(constructor: Function): void;\n\n    /**\n     * Negate the matcher.\n     */\n    not: Matchers<T>;\n\n    /**\n     * Await promise and check resolved value.\n     */\n    resolves: Matchers<Awaited<T>>;\n\n    /**\n     * Await promise and check rejection.\n     */\n    rejects: Matchers<unknown>;\n  }\n\n  /**\n   * Create an expectation for a value.\n   *\n   * @param actual - The value to test\n   * @returns Matchers for the value\n   *\n   * @example\n   * expect(1 + 1).toBe(2);\n   * expect({ a: 1 }).toEqual({ a: 1 });\n   * expect(() => { throw new Error(); }).toThrow();\n   * expect(promise).resolves.toBe(42);\n   */\n  function expect<T>(actual: T): Matchers<T>;\n}\n";
     readonly timers: "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-timers\n *\n * These types define the globals injected by setupTimers() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * const timeoutId = setTimeout(() => {\n *   console.log(\"fired!\");\n * }, 1000);\n *\n * clearTimeout(timeoutId);\n *\n * const intervalId = setInterval(() => {\n *   console.log(\"tick\");\n * }, 100);\n *\n * clearInterval(intervalId);\n */\n\nexport {};\n\ndeclare global {\n  /**\n   * Schedule a callback to execute after a delay.\n   *\n   * @param callback - The function to call after the delay\n   * @param ms - The delay in milliseconds (default: 0)\n   * @param args - Additional arguments to pass to the callback\n   * @returns A timer ID that can be passed to clearTimeout\n   *\n   * @example\n   * const id = setTimeout(() => console.log(\"done\"), 1000);\n   * setTimeout((a, b) => console.log(a, b), 100, \"hello\", \"world\");\n   */\n  function setTimeout(\n    callback: (...args: unknown[]) => void,\n    ms?: number,\n    ...args: unknown[]\n  ): number;\n\n  /**\n   * Schedule a callback to execute repeatedly at a fixed interval.\n   *\n   * @param callback - The function to call at each interval\n   * @param ms - The interval in milliseconds (minimum: 4ms)\n   * @param args - Additional arguments to pass to the callback\n   * @returns A timer ID that can be passed to clearInterval\n   *\n   * @example\n   * const id = setInterval(() => console.log(\"tick\"), 1000);\n   */\n  function setInterval(\n    callback: (...args: unknown[]) => void,\n    ms?: number,\n    ...args: unknown[]\n  ): number;\n\n  /**\n   * Cancel a timeout previously scheduled with setTimeout.\n   *\n   * @param id - The timer ID returned by setTimeout\n   *\n   * @example\n   * const id = setTimeout(() => {}, 1000);\n   * clearTimeout(id);\n   */\n  function clearTimeout(id: number | undefined): void;\n\n  /**\n   * Cancel an interval previously scheduled with setInterval.\n   *\n   * @param id - The timer ID returned by setInterval\n   *\n   * @example\n   * const id = setInterval(() => {}, 1000);\n   * clearInterval(id);\n   */\n  function clearInterval(id: number | undefined): void;\n}\n";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/quickjs-test-utils",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "main": "./dist/cjs/index.cjs",
   "types": "./dist/types/index.d.ts",
   "exports": {
@@ -20,11 +20,11 @@
   },
   "peerDependencies": {
     "quickjs-emscripten": "^0.31.0",
-    "@ricsam/quickjs-console": "^0.2.15",
-    "@ricsam/quickjs-core": "^0.2.15",
-    "@ricsam/quickjs-fetch": "^0.2.16",
-    "@ricsam/quickjs-fs": "^0.2.15",
-    "@ricsam/quickjs-runtime": "^0.2.18"
+    "@ricsam/quickjs-console": "^0.2.16",
+    "@ricsam/quickjs-core": "^0.2.16",
+    "@ricsam/quickjs-fetch": "^0.2.18",
+    "@ricsam/quickjs-fs": "^0.2.17",
+    "@ricsam/quickjs-runtime": "^0.2.20"
   },
   "peerDependenciesMeta": {
     "@ricsam/quickjs-console": {