@ricsam/quickjs-test-utils 0.0.1 → 1.0.1

package/dist/mjs/quickjs-types.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/quickjs-types.ts"],
+  "sourcesContent": [
+    "/**\n * QuickJS type definitions as string constants.\n *\n * These are the canonical source for QuickJS global type definitions.\n * The .d.ts files in each package are generated from these strings during build.\n *\n * @example\n * import { TYPE_DEFINITIONS } from \"@ricsam/quickjs-test-utils\";\n *\n * // Use with ts-morph for type checking code strings\n * project.createSourceFile(\"types.d.ts\", TYPE_DEFINITIONS.fetch);\n */\n\n/**\n * Type definitions for @ricsam/quickjs-core globals.\n *\n * Includes: ReadableStream, WritableStream, TransformStream, Blob, File, URL, URLSearchParams, DOMException\n */\nexport const CORE_TYPES = `/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-core\n *\n * These types define the globals injected by setupCore() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * // In your tsconfig.quickjs.json\n * {\n *   \"compilerOptions\": {\n *     \"lib\": [\"ESNext\", \"DOM\"]\n *   }\n * }\n *\n * // Then reference this file or use ts-morph for code strings\n */\n\nexport {};\n\ndeclare global {\n  // ============================================\n  // Web Streams API\n  // ============================================\n\n  /**\n   * A readable stream of data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream\n   */\n  const ReadableStream: typeof globalThis.ReadableStream;\n\n  /**\n   * A writable stream of data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStream\n   */\n  const WritableStream: typeof globalThis.WritableStream;\n\n  /**\n   * A transform stream that can be used to pipe data through a transformer.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/TransformStream\n   */\n  const TransformStream: typeof globalThis.TransformStream;\n\n  /**\n   * Default reader for ReadableStream\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader\n   */\n  const ReadableStreamDefaultReader: typeof globalThis.ReadableStreamDefaultReader;\n\n  /**\n   * Default writer for WritableStream\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter\n   */\n  const WritableStreamDefaultWriter: typeof globalThis.WritableStreamDefaultWriter;\n\n  // ============================================\n  // Blob and File APIs\n  // ============================================\n\n  /**\n   * A file-like object of immutable, raw data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/Blob\n   */\n  const Blob: typeof globalThis.Blob;\n\n  /**\n   * A file object representing a file.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/File\n   */\n  const File: typeof globalThis.File;\n\n  // ============================================\n  // URL APIs\n  // ============================================\n\n  /**\n   * Interface for URL manipulation.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/URL\n   */\n  const URL: typeof globalThis.URL;\n\n  /**\n   * Utility for working with URL query strings.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams\n   */\n  const URLSearchParams: typeof globalThis.URLSearchParams;\n\n  // ============================================\n  // Error Handling\n  // ============================================\n\n  /**\n   * Exception type for DOM operations.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMException\n   */\n  const DOMException: typeof globalThis.DOMException;\n}\n`;\n\n/**\n * Type definitions for @ricsam/quickjs-fetch globals.\n *\n * Includes: Headers, Request, Response, AbortController, AbortSignal, FormData, fetch, serve, Server, ServerWebSocket\n */\nexport const FETCH_TYPES = `/**\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 * serve({\n *   fetch(request, server) {\n *     if (request.url.includes(\"/ws\")) {\n *       server.upgrade(request, { data: { id: 123 } });\n *       return new Response(null, { status: 101 });\n *     }\n *     return new Response(\"Hello!\");\n *   },\n *   websocket: {\n *     message(ws, 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  interface Server {\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?: unknown }): 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): Response | Promise<Response>;\n\n    /**\n     * WebSocket event handlers.\n     */\n    websocket?: {\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   * 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   *     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`;\n\n/**\n * Type definitions for @ricsam/quickjs-fs globals.\n *\n * Includes: fs namespace, FileSystemHandle, FileSystemFileHandle, FileSystemDirectoryHandle, FileSystemWritableFileStream\n */\nexport const FS_TYPES = `/**\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`;\n\n/**\n * Map of package names to their type definitions.\n */\nexport const TYPE_DEFINITIONS = {\n  core: CORE_TYPES,\n  fetch: FETCH_TYPES,\n  fs: FS_TYPES,\n} as const;\n\n/**\n * Type for the keys of TYPE_DEFINITIONS.\n */\nexport type TypeDefinitionKey = keyof typeof TYPE_DEFINITIONS;\n"
+  ],
+  "mappings": ";;AAkBO,IAAM,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuGnB,IAAM,cAAc;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwPpB,IAAM,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+TjB,IAAM,mBAAmB;AAAA,EAC9B,MAAM;AAAA,EACN,OAAO;AAAA,EACP,IAAI;AACN;",
+  "debugId": "DB524E5F7383894464756E2164756E21",
+  "names": []
+}

package/dist/mjs/runtime-context.mjs

@@ -0,0 +1,26 @@
+// @bun
+// packages/test-utils/src/runtime-context.ts
+import { getQuickJS } from "quickjs-emscripten";
+import { clearAllInstanceState } from "@ricsam/quickjs-core";
+import {
+  setupRuntime
+} from "@ricsam/quickjs-runtime";
+async function createRuntimeTestContext(options) {
+  const QuickJS = await getQuickJS();
+  const runtime = QuickJS.newRuntime();
+  const context = runtime.newContext();
+  clearAllInstanceState();
+  const runtimeHandle = setupRuntime(context, options);
+  return { runtime, context, runtimeHandle };
+}
+function disposeRuntimeTestContext(ctx) {
+  ctx.runtimeHandle.dispose();
+  ctx.context.dispose();
+  ctx.runtime.dispose();
+}
+export {
+  disposeRuntimeTestContext,
+  createRuntimeTestContext
+};
+
+//# debugId=8B023BD3945C89FC64756E2164756E21

package/dist/mjs/runtime-context.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/runtime-context.ts"],
+  "sourcesContent": [
+    "import { getQuickJS, type QuickJSContext, type QuickJSRuntime } from \"quickjs-emscripten\";\nimport { clearAllInstanceState } from \"@ricsam/quickjs-core\";\nimport {\n  setupRuntime,\n  type RuntimeHandle,\n  type SetupRuntimeOptions,\n} from \"@ricsam/quickjs-runtime\";\n\nexport interface RuntimeTestContext {\n  runtime: QuickJSRuntime;\n  context: QuickJSContext;\n  runtimeHandle: RuntimeHandle;\n}\n\nexport async function createRuntimeTestContext(\n  options?: SetupRuntimeOptions\n): Promise<RuntimeTestContext> {\n  const QuickJS = await getQuickJS();\n  const runtime = QuickJS.newRuntime();\n  const context = runtime.newContext();\n  clearAllInstanceState();\n\n  // setupRuntime internally creates the coreHandle\n  const runtimeHandle = setupRuntime(context, options);\n\n  return { runtime, context, runtimeHandle };\n}\n\nexport function disposeRuntimeTestContext(ctx: RuntimeTestContext): void {\n  ctx.runtimeHandle.dispose();\n  ctx.context.dispose();\n  ctx.runtime.dispose();\n}\n"
+  ],
+  "mappings": ";;AAAA;AACA;AACA;AAAA;AAAA;AAYA,eAAsB,wBAAwB,CAC5C,SAC6B;AAAA,EAC7B,MAAM,UAAU,MAAM,WAAW;AAAA,EACjC,MAAM,UAAU,QAAQ,WAAW;AAAA,EACnC,MAAM,UAAU,QAAQ,WAAW;AAAA,EACnC,sBAAsB;AAAA,EAGtB,MAAM,gBAAgB,aAAa,SAAS,OAAO;AAAA,EAEnD,OAAO,EAAE,SAAS,SAAS,cAAc;AAAA;AAGpC,SAAS,yBAAyB,CAAC,KAA+B;AAAA,EACvE,IAAI,cAAc,QAAQ;AAAA,EAC1B,IAAI,QAAQ,QAAQ;AAAA,EACpB,IAAI,QAAQ,QAAQ;AAAA;",
+  "debugId": "8B023BD3945C89FC64756E2164756E21",
+  "names": []
+}

package/dist/mjs/typecheck.mjs

@@ -0,0 +1,77 @@
+// @bun
+// packages/test-utils/src/typecheck.ts
+import { Project, ts } from "ts-morph";
+import { TYPE_DEFINITIONS } from "./quickjs-types.ts";
+function getMessageText(messageText) {
+  if (typeof messageText === "string") {
+    return messageText;
+  }
+  if (messageText && typeof messageText === "object" && "getMessageText" in messageText && typeof messageText.getMessageText === "function") {
+    return messageText.getMessageText();
+  }
+  if (messageText && typeof messageText === "object" && "messageText" in messageText) {
+    return String(messageText.messageText);
+  }
+  return String(messageText);
+}
+function typecheckQuickJSCode(code, options) {
+  const include = options?.include ?? ["core", "fetch", "fs"];
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: {
+      target: ts.ScriptTarget.ESNext,
+      module: ts.ModuleKind.ESNext,
+      lib: ["lib.esnext.d.ts", "lib.dom.d.ts"],
+      strict: true,
+      noEmit: true,
+      skipLibCheck: true,
+      ...options?.compilerOptions
+    }
+  });
+  for (const pkg of include) {
+    const content = TYPE_DEFINITIONS[pkg];
+    if (content) {
+      project.createSourceFile(`${pkg}.d.ts`, content);
+    }
+  }
+  const sourceFile = project.createSourceFile("usercode.ts", code);
+  const diagnostics = sourceFile.getPreEmitDiagnostics();
+  const errors = diagnostics.map((diagnostic) => {
+    const start = diagnostic.getStart();
+    const sourceFile2 = diagnostic.getSourceFile();
+    let line;
+    let column;
+    if (start !== undefined && sourceFile2) {
+      const lineAndChar = sourceFile2.getLineAndColumnAtPos(start);
+      line = lineAndChar.line;
+      column = lineAndChar.column;
+    }
+    return {
+      message: getMessageText(diagnostic.getMessageText()),
+      line,
+      column,
+      code: diagnostic.getCode()
+    };
+  });
+  return {
+    success: errors.length === 0,
+    errors
+  };
+}
+function formatTypecheckErrors(result) {
+  if (result.success) {
+    return "No type errors found.";
+  }
+  return result.errors.map((error) => {
+    const location = error.line !== undefined ? `:${error.line}:${error.column ?? 1}` : "";
+    const code = error.code ? ` (TS${error.code})` : "";
+    return `usercode.ts${location}${code}: ${error.message}`;
+  }).join(`
+`);
+}
+export {
+  typecheckQuickJSCode,
+  formatTypecheckErrors
+};
+
+//# debugId=5D284798E24F133564756E2164756E21

package/dist/mjs/typecheck.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/typecheck.ts"],
+  "sourcesContent": [
+    "/**\n * Type-checking utility for QuickJS user code using ts-morph.\n *\n * This utility allows you to validate TypeScript code strings against\n * the QuickJS global type definitions before running them in the sandbox.\n *\n * @example\n * import { typecheckQuickJSCode } from \"@ricsam/quickjs-test-utils\";\n *\n * const result = typecheckQuickJSCode(`\n *   serve({\n *     fetch(request, server) {\n *       return new Response(\"Hello!\");\n *     }\n *   });\n * `, { include: [\"fetch\"] });\n *\n * if (!result.success) {\n *   console.error(\"Type errors:\", result.errors);\n * }\n */\n\nimport { Project, ts } from \"ts-morph\";\nimport { TYPE_DEFINITIONS, type TypeDefinitionKey } from \"./quickjs-types.ts\";\n\n/**\n * Result of type-checking QuickJS code.\n */\nexport interface TypecheckResult {\n  /**\n   * Whether the code passed type checking.\n   */\n  success: boolean;\n\n  /**\n   * Array of type errors found in the code.\n   */\n  errors: TypecheckError[];\n}\n\n/**\n * A single type-checking error.\n */\nexport interface TypecheckError {\n  /**\n   * The error message from TypeScript.\n   */\n  message: string;\n\n  /**\n   * The line number where the error occurred (1-indexed).\n   */\n  line?: number;\n\n  /**\n   * The column number where the error occurred (1-indexed).\n   */\n  column?: number;\n\n  /**\n   * The TypeScript error code.\n   */\n  code?: number;\n}\n\n/**\n * Options for type-checking QuickJS code.\n */\nexport interface TypecheckOptions {\n  /**\n   * Which package types to include.\n   * @default [\"core\", \"fetch\", \"fs\"]\n   */\n  include?: Array<\"core\" | \"fetch\" | \"fs\">;\n\n  /**\n   * Additional compiler options to pass to TypeScript.\n   */\n  compilerOptions?: Partial<ts.CompilerOptions>;\n}\n\n/**\n * Get the message text from a TypeScript diagnostic message.\n * Handles both string messages and DiagnosticMessageChain objects.\n */\nfunction getMessageText(messageText: unknown): string {\n  if (typeof messageText === \"string\") {\n    return messageText;\n  }\n\n  // Handle ts-morph DiagnosticMessageChain wrapper\n  if (\n    messageText &&\n    typeof messageText === \"object\" &&\n    \"getMessageText\" in messageText &&\n    typeof (messageText as { getMessageText: unknown }).getMessageText ===\n      \"function\"\n  ) {\n    return (messageText as { getMessageText: () => string }).getMessageText();\n  }\n\n  // Handle raw TypeScript DiagnosticMessageChain\n  if (\n    messageText &&\n    typeof messageText === \"object\" &&\n    \"messageText\" in messageText\n  ) {\n    return String((messageText as { messageText: unknown }).messageText);\n  }\n\n  return String(messageText);\n}\n\n\n/**\n * Type-check QuickJS user code against the package type definitions.\n *\n * @param code - The TypeScript/JavaScript code to check\n * @param options - Configuration options\n * @returns The result of type checking\n *\n * @example\n * // Check code that uses the fetch API\n * const result = typecheckQuickJSCode(`\n *   const response = await fetch(\"https://api.example.com/data\");\n *   const data = await response.json();\n * `, { include: [\"core\", \"fetch\"] });\n *\n * @example\n * // Check code that uses serve()\n * const result = typecheckQuickJSCode(`\n *   serve({\n *     fetch(request, server) {\n *       return new Response(\"Hello!\");\n *     }\n *   });\n * `, { include: [\"fetch\"] });\n *\n * @example\n * // Check code that uses the file system API\n * const result = typecheckQuickJSCode(`\n *   const root = await fs.getDirectory(\"/data\");\n *   const file = await root.getFileHandle(\"config.json\");\n * `, { include: [\"core\", \"fs\"] });\n */\nexport function typecheckQuickJSCode(\n  code: string,\n  options?: TypecheckOptions\n): TypecheckResult {\n  const include = options?.include ?? [\"core\", \"fetch\", \"fs\"];\n\n  // Create a project with in-memory file system\n  const project = new Project({\n    useInMemoryFileSystem: true,\n    compilerOptions: {\n      target: ts.ScriptTarget.ESNext,\n      module: ts.ModuleKind.ESNext,\n      lib: [\"lib.esnext.d.ts\", \"lib.dom.d.ts\"],\n      strict: true,\n      noEmit: true,\n      skipLibCheck: true,\n      ...options?.compilerOptions,\n    },\n  });\n\n  // Add type definition files from embedded strings\n  for (const pkg of include) {\n    const content = TYPE_DEFINITIONS[pkg as TypeDefinitionKey];\n    if (content) {\n      project.createSourceFile(`${pkg}.d.ts`, content);\n    }\n  }\n\n  // Add the user code\n  const sourceFile = project.createSourceFile(\"usercode.ts\", code);\n\n  // Get diagnostics\n  const diagnostics = sourceFile.getPreEmitDiagnostics();\n\n  // Convert diagnostics to our error format\n  const errors: TypecheckError[] = diagnostics.map((diagnostic) => {\n    const start = diagnostic.getStart();\n    const sourceFile = diagnostic.getSourceFile();\n\n    let line: number | undefined;\n    let column: number | undefined;\n\n    if (start !== undefined && sourceFile) {\n      const lineAndChar = sourceFile.getLineAndColumnAtPos(start);\n      line = lineAndChar.line;\n      column = lineAndChar.column;\n    }\n\n    return {\n      message: getMessageText(diagnostic.getMessageText()),\n      line,\n      column,\n      code: diagnostic.getCode(),\n    };\n  });\n\n  return {\n    success: errors.length === 0,\n    errors,\n  };\n}\n\n/**\n * Format type-check errors for display.\n *\n * @param result - The type-check result\n * @returns A formatted string of errors\n *\n * @example\n * const result = typecheckQuickJSCode(code);\n * if (!result.success) {\n *   console.error(formatTypecheckErrors(result));\n * }\n */\nexport function formatTypecheckErrors(result: TypecheckResult): string {\n  if (result.success) {\n    return \"No type errors found.\";\n  }\n\n  return result.errors\n    .map((error) => {\n      const location =\n        error.line !== undefined ? `:${error.line}:${error.column ?? 1}` : \"\";\n      const code = error.code ? ` (TS${error.code})` : \"\";\n      return `usercode.ts${location}${code}: ${error.message}`;\n    })\n    .join(\"\\n\");\n}\n"
+  ],
+  "mappings": ";;AAsBA;AACA;AA8DA,SAAS,cAAc,CAAC,aAA8B;AAAA,EACpD,IAAI,OAAO,gBAAgB,UAAU;AAAA,IACnC,OAAO;AAAA,EACT;AAAA,EAGA,IACE,eACA,OAAO,gBAAgB,YACvB,oBAAoB,eACpB,OAAQ,YAA4C,mBAClD,YACF;AAAA,IACA,OAAQ,YAAiD,eAAe;AAAA,EAC1E;AAAA,EAGA,IACE,eACA,OAAO,gBAAgB,YACvB,iBAAiB,aACjB;AAAA,IACA,OAAO,OAAQ,YAAyC,WAAW;AAAA,EACrE;AAAA,EAEA,OAAO,OAAO,WAAW;AAAA;AAmCpB,SAAS,oBAAoB,CAClC,MACA,SACiB;AAAA,EACjB,MAAM,UAAU,SAAS,WAAW,CAAC,QAAQ,SAAS,IAAI;AAAA,EAG1D,MAAM,UAAU,IAAI,QAAQ;AAAA,IAC1B,uBAAuB;AAAA,IACvB,iBAAiB;AAAA,MACf,QAAQ,GAAG,aAAa;AAAA,MACxB,QAAQ,GAAG,WAAW;AAAA,MACtB,KAAK,CAAC,mBAAmB,cAAc;AAAA,MACvC,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,cAAc;AAAA,SACX,SAAS;AAAA,IACd;AAAA,EACF,CAAC;AAAA,EAGD,WAAW,OAAO,SAAS;AAAA,IACzB,MAAM,UAAU,iBAAiB;AAAA,IACjC,IAAI,SAAS;AAAA,MACX,QAAQ,iBAAiB,GAAG,YAAY,OAAO;AAAA,IACjD;AAAA,EACF;AAAA,EAGA,MAAM,aAAa,QAAQ,iBAAiB,eAAe,IAAI;AAAA,EAG/D,MAAM,cAAc,WAAW,sBAAsB;AAAA,EAGrD,MAAM,SAA2B,YAAY,IAAI,CAAC,eAAe;AAAA,IAC/D,MAAM,QAAQ,WAAW,SAAS;AAAA,IAClC,MAAM,cAAa,WAAW,cAAc;AAAA,IAE5C,IAAI;AAAA,IACJ,IAAI;AAAA,IAEJ,IAAI,UAAU,aAAa,aAAY;AAAA,MACrC,MAAM,cAAc,YAAW,sBAAsB,KAAK;AAAA,MAC1D,OAAO,YAAY;AAAA,MACnB,SAAS,YAAY;AAAA,IACvB;AAAA,IAEA,OAAO;AAAA,MACL,SAAS,eAAe,WAAW,eAAe,CAAC;AAAA,MACnD;AAAA,MACA;AAAA,MACA,MAAM,WAAW,QAAQ;AAAA,IAC3B;AAAA,GACD;AAAA,EAED,OAAO;AAAA,IACL,SAAS,OAAO,WAAW;AAAA,IAC3B;AAAA,EACF;AAAA;AAeK,SAAS,qBAAqB,CAAC,QAAiC;AAAA,EACrE,IAAI,OAAO,SAAS;AAAA,IAClB,OAAO;AAAA,EACT;AAAA,EAEA,OAAO,OAAO,OACX,IAAI,CAAC,UAAU;AAAA,IACd,MAAM,WACJ,MAAM,SAAS,YAAY,IAAI,MAAM,QAAQ,MAAM,UAAU,MAAM;AAAA,IACrE,MAAM,OAAO,MAAM,OAAO,OAAO,MAAM,UAAU;AAAA,IACjD,OAAO,cAAc,WAAW,SAAS,MAAM;AAAA,GAChD,EACA,KAAK;AAAA,CAAI;AAAA;",
+  "debugId": "5D284798E24F133564756E2164756E21",
+  "names": []
+}

package/dist/types/context.d.ts

@@ -0,0 +1,35 @@
+import { type QuickJSContext, type QuickJSRuntime } from "quickjs-emscripten";
+import { type CoreHandle } from "@ricsam/quickjs-core";
+export interface TestContext {
+    runtime: QuickJSRuntime;
+    context: QuickJSContext;
+    coreHandle: CoreHandle;
+}
+export declare function createTestContext(): Promise<TestContext>;
+export declare function disposeTestContext(ctx: TestContext): void;
+/**
+ * Helper for use with beforeEach/afterEach
+ *
+ * @example
+ * const testCtx = useTestContext();
+ *
+ * beforeEach(async () => {
+ *   await testCtx.setup();
+ * });
+ *
+ * afterEach(() => {
+ *   testCtx.teardown();
+ * });
+ *
+ * test("my test", () => {
+ *   const result = evalCode(testCtx.context, `1 + 1`);
+ *   expect(result).toBe(2);
+ * });
+ */
+export declare function useTestContext(): {
+    setup(): Promise<TestContext>;
+    teardown(): void;
+    readonly context: QuickJSContext;
+    readonly runtime: QuickJSRuntime;
+    readonly coreHandle: CoreHandle;
+};

package/dist/types/eval.d.ts

@@ -0,0 +1,31 @@
+import type { QuickJSContext } from "quickjs-emscripten";
+/**
+ * Evaluate code synchronously and return the result
+ *
+ * Handles error checking and handle disposal automatically.
+ *
+ * @example
+ * const result = evalCode<number>(context, `1 + 1`);
+ * expect(result).toBe(2);
+ *
+ * @example
+ * const obj = evalCode<{ name: string }>(context, `({ name: "test" })`);
+ * expect(obj.name).toBe("test");
+ */
+export declare function evalCode<T>(context: QuickJSContext, code: string): T;
+/**
+ * Evaluate async code and return the resolved result
+ *
+ * Handles promise resolution, error checking, and handle disposal automatically.
+ * Also executes pending jobs after resolution.
+ *
+ * @example
+ * const result = await evalCodeAsync<string>(context, `
+ *   (async () => {
+ *     const blob = new Blob(["hello"]);
+ *     return await blob.text();
+ *   })()
+ * `);
+ * expect(result).toBe("hello");
+ */
+export declare function evalCodeAsync<T>(context: QuickJSContext, code: string): Promise<T>;

package/dist/types/fetch-context.d.ts

@@ -0,0 +1,41 @@
+import { type FetchHandle, type SetupFetchOptions } from "@ricsam/quickjs-fetch";
+import { type TestContext } from "./context.ts";
+export interface FetchTestContext extends TestContext {
+    fetchHandle: FetchHandle;
+}
+export interface CreateFetchTestContextOptions {
+    /** Handler for outbound fetch() calls from QuickJS */
+    onFetch?: SetupFetchOptions["onFetch"];
+}
+export declare function createFetchTestContext(options?: CreateFetchTestContextOptions): Promise<FetchTestContext>;
+export declare function disposeFetchTestContext(ctx: FetchTestContext): void;
+/**
+ * Helper for use with beforeEach/afterEach for fetch tests
+ *
+ * @example
+ * const testCtx = useFetchTestContext();
+ *
+ * beforeEach(async () => {
+ *   await testCtx.setup();
+ * });
+ *
+ * afterEach(() => {
+ *   testCtx.teardown();
+ * });
+ *
+ * test("headers test", () => {
+ *   const result = evalCode(testCtx.context, `
+ *     const headers = new Headers({ "Content-Type": "application/json" });
+ *     headers.get("content-type");
+ *   `);
+ *   expect(result).toBe("application/json");
+ * });
+ */
+export declare function useFetchTestContext(): {
+    setup(): Promise<FetchTestContext>;
+    teardown(): void;
+    readonly context: import("quickjs-emscripten").QuickJSContext;
+    readonly runtime: import("quickjs-emscripten").QuickJSRuntime;
+    readonly coreHandle: import("@ricsam/quickjs-core").CoreHandle;
+    readonly fetchHandle: FetchHandle;
+};

package/dist/types/fs-context.d.ts

@@ -0,0 +1,12 @@
+import { type FsHandle, type HostDirectoryHandle } from "@ricsam/quickjs-fs";
+import { type TestContext } from "./context.ts";
+export interface FsTestContext extends TestContext {
+    fsHandle: FsHandle;
+    memFs: HostDirectoryHandle;
+}
+export interface CreateFsTestContextOptions {
+    /** Initial files to populate the in-memory filesystem */
+    initialFiles?: Record<string, string | Uint8Array>;
+}
+export declare function createFsTestContext(options?: CreateFsTestContextOptions): Promise<FsTestContext>;
+export declare function disposeFsTestContext(ctx: FsTestContext): void;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { createTestContext, disposeTestContext, useTestContext, type TestContext, } from "./context.ts";
+export { createFetchTestContext, disposeFetchTestContext, useFetchTestContext, type FetchTestContext, type CreateFetchTestContextOptions, } from "./fetch-context.ts";
+export { evalCode, evalCodeAsync } from "./eval.ts";
+export { startIntegrationServer, type IntegrationTestServer, type StartIntegrationServerOptions, } from "./integration-server.ts";
+export { typecheckQuickJSCode, formatTypecheckErrors, type TypecheckResult, type TypecheckError, type TypecheckOptions, } from "./typecheck.ts";
+export { CORE_TYPES, FETCH_TYPES, FS_TYPES, TYPE_DEFINITIONS, type TypeDefinitionKey, } from "./quickjs-types.ts";

package/dist/types/integration-server.d.ts

@@ -0,0 +1,39 @@
+import { type QuickJSContext, type QuickJSRuntime } from "quickjs-emscripten";
+import { type FetchHandle, type SetupFetchOptions } from "@ricsam/quickjs-fetch";
+import { type CoreHandle } from "@ricsam/quickjs-core";
+export interface IntegrationTestServer {
+    baseURL: string;
+    wsURL: string;
+    port: number;
+    fetchHandle: FetchHandle;
+    context: QuickJSContext;
+    runtime: QuickJSRuntime;
+    coreHandle: CoreHandle;
+    stop(): Promise<void>;
+}
+export interface StartIntegrationServerOptions {
+    /** Handler for outbound fetch() calls from QuickJS */
+    onFetch?: SetupFetchOptions["onFetch"];
+}
+/**
+ * Start a real HTTP server that dispatches requests to a QuickJS serve() handler.
+ *
+ * @param quickJSCode - JavaScript code to run in QuickJS, should call serve()
+ * @param options - Optional configuration
+ * @returns Server info including baseURL, wsURL, and stop function
+ *
+ * @example
+ * const server = await startIntegrationServer(`
+ *   serve({
+ *     fetch(request) {
+ *       return new Response("Hello!");
+ *     }
+ *   });
+ * `);
+ *
+ * const response = await fetch(\`\${server.baseURL}/test\`);
+ * expect(await response.text()).toBe("Hello!");
+ *
+ * await server.stop();
+ */
+export declare function startIntegrationServer(quickJSCode: string, options?: StartIntegrationServerOptions): Promise<IntegrationTestServer>;

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

@@ -0,0 +1,42 @@
+/**
+ * QuickJS type definitions as string constants.
+ *
+ * These are the canonical source for QuickJS global type definitions.
+ * The .d.ts files in each package are generated from these strings during build.
+ *
+ * @example
+ * import { TYPE_DEFINITIONS } from "@ricsam/quickjs-test-utils";
+ *
+ * // Use with ts-morph for type checking code strings
+ * project.createSourceFile("types.d.ts", TYPE_DEFINITIONS.fetch);
+ */
+/**
+ * Type definitions for @ricsam/quickjs-core globals.
+ *
+ * Includes: ReadableStream, WritableStream, TransformStream, Blob, File, URL, URLSearchParams, DOMException
+ */
+export declare const CORE_TYPES = "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-core\n *\n * These types define the globals injected by setupCore() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * // In your tsconfig.quickjs.json\n * {\n *   \"compilerOptions\": {\n *     \"lib\": [\"ESNext\", \"DOM\"]\n *   }\n * }\n *\n * // Then reference this file or use ts-morph for code strings\n */\n\nexport {};\n\ndeclare global {\n  // ============================================\n  // Web Streams API\n  // ============================================\n\n  /**\n   * A readable stream of data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream\n   */\n  const ReadableStream: typeof globalThis.ReadableStream;\n\n  /**\n   * A writable stream of data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStream\n   */\n  const WritableStream: typeof globalThis.WritableStream;\n\n  /**\n   * A transform stream that can be used to pipe data through a transformer.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/TransformStream\n   */\n  const TransformStream: typeof globalThis.TransformStream;\n\n  /**\n   * Default reader for ReadableStream\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader\n   */\n  const ReadableStreamDefaultReader: typeof globalThis.ReadableStreamDefaultReader;\n\n  /**\n   * Default writer for WritableStream\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter\n   */\n  const WritableStreamDefaultWriter: typeof globalThis.WritableStreamDefaultWriter;\n\n  // ============================================\n  // Blob and File APIs\n  // ============================================\n\n  /**\n   * A file-like object of immutable, raw data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/Blob\n   */\n  const Blob: typeof globalThis.Blob;\n\n  /**\n   * A file object representing a file.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/File\n   */\n  const File: typeof globalThis.File;\n\n  // ============================================\n  // URL APIs\n  // ============================================\n\n  /**\n   * Interface for URL manipulation.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/URL\n   */\n  const URL: typeof globalThis.URL;\n\n  /**\n   * Utility for working with URL query strings.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams\n   */\n  const URLSearchParams: typeof globalThis.URLSearchParams;\n\n  // ============================================\n  // Error Handling\n  // ============================================\n\n  /**\n   * Exception type for DOM operations.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMException\n   */\n  const DOMException: typeof globalThis.DOMException;\n}\n";
+/**
+ * Type definitions for @ricsam/quickjs-fetch globals.
+ *
+ * Includes: Headers, Request, Response, AbortController, AbortSignal, FormData, fetch, serve, Server, ServerWebSocket
+ */
+export declare const FETCH_TYPES = "/**\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 * serve({\n *   fetch(request, server) {\n *     if (request.url.includes(\"/ws\")) {\n *       server.upgrade(request, { data: { id: 123 } });\n *       return new Response(null, { status: 101 });\n *     }\n *     return new Response(\"Hello!\");\n *   },\n *   websocket: {\n *     message(ws, 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  interface Server {\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?: unknown }): 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): Response | Promise<Response>;\n\n    /**\n     * WebSocket event handlers.\n     */\n    websocket?: {\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   * 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   *     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";
+/**
+ * Type definitions for @ricsam/quickjs-fs globals.
+ *
+ * Includes: fs namespace, FileSystemHandle, FileSystemFileHandle, FileSystemDirectoryHandle, FileSystemWritableFileStream
+ */
+export declare const FS_TYPES = "/**\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";
+/**
+ * Map of package names to their type definitions.
+ */
+export declare const TYPE_DEFINITIONS: {
+    readonly core: "/**\n * QuickJS Global Type Definitions for @ricsam/quickjs-core\n *\n * These types define the globals injected by setupCore() into a QuickJS context.\n * Use these types to typecheck user code that will run inside QuickJS.\n *\n * @example\n * // In your tsconfig.quickjs.json\n * {\n *   \"compilerOptions\": {\n *     \"lib\": [\"ESNext\", \"DOM\"]\n *   }\n * }\n *\n * // Then reference this file or use ts-morph for code strings\n */\n\nexport {};\n\ndeclare global {\n  // ============================================\n  // Web Streams API\n  // ============================================\n\n  /**\n   * A readable stream of data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream\n   */\n  const ReadableStream: typeof globalThis.ReadableStream;\n\n  /**\n   * A writable stream of data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStream\n   */\n  const WritableStream: typeof globalThis.WritableStream;\n\n  /**\n   * A transform stream that can be used to pipe data through a transformer.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/TransformStream\n   */\n  const TransformStream: typeof globalThis.TransformStream;\n\n  /**\n   * Default reader for ReadableStream\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader\n   */\n  const ReadableStreamDefaultReader: typeof globalThis.ReadableStreamDefaultReader;\n\n  /**\n   * Default writer for WritableStream\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter\n   */\n  const WritableStreamDefaultWriter: typeof globalThis.WritableStreamDefaultWriter;\n\n  // ============================================\n  // Blob and File APIs\n  // ============================================\n\n  /**\n   * A file-like object of immutable, raw data.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/Blob\n   */\n  const Blob: typeof globalThis.Blob;\n\n  /**\n   * A file object representing a file.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/File\n   */\n  const File: typeof globalThis.File;\n\n  // ============================================\n  // URL APIs\n  // ============================================\n\n  /**\n   * Interface for URL manipulation.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/URL\n   */\n  const URL: typeof globalThis.URL;\n\n  /**\n   * Utility for working with URL query strings.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams\n   */\n  const URLSearchParams: typeof globalThis.URLSearchParams;\n\n  // ============================================\n  // Error Handling\n  // ============================================\n\n  /**\n   * Exception type for DOM operations.\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMException\n   */\n  const DOMException: typeof globalThis.DOMException;\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 * serve({\n *   fetch(request, server) {\n *     if (request.url.includes(\"/ws\")) {\n *       server.upgrade(request, { data: { id: 123 } });\n *       return new Response(null, { status: 101 });\n *     }\n *     return new Response(\"Hello!\");\n *   },\n *   websocket: {\n *     message(ws, 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  interface Server {\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?: unknown }): 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): Response | Promise<Response>;\n\n    /**\n     * WebSocket event handlers.\n     */\n    websocket?: {\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   * 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   *     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";
+};
+/**
+ * Type for the keys of TYPE_DEFINITIONS.
+ */
+export type TypeDefinitionKey = keyof typeof TYPE_DEFINITIONS;

package/dist/types/runtime-context.d.ts

@@ -0,0 +1,9 @@
+import { type QuickJSContext, type QuickJSRuntime } from "quickjs-emscripten";
+import { type RuntimeHandle, type SetupRuntimeOptions } from "@ricsam/quickjs-runtime";
+export interface RuntimeTestContext {
+    runtime: QuickJSRuntime;
+    context: QuickJSContext;
+    runtimeHandle: RuntimeHandle;
+}
+export declare function createRuntimeTestContext(options?: SetupRuntimeOptions): Promise<RuntimeTestContext>;
+export declare function disposeRuntimeTestContext(ctx: RuntimeTestContext): void;