@ricsam/quickjs-test-utils 0.0.1 → 1.0.1

package/dist/mjs/quickjs-types.mjs

@@ -0,0 +1,669 @@
+// @bun
+// packages/test-utils/src/quickjs-types.ts
+var CORE_TYPES = `/**
+ * QuickJS Global Type Definitions for @ricsam/quickjs-core
+ *
+ * These types define the globals injected by setupCore() into a QuickJS context.
+ * Use these types to typecheck user code that will run inside QuickJS.
+ *
+ * @example
+ * // In your tsconfig.quickjs.json
+ * {
+ *   "compilerOptions": {
+ *     "lib": ["ESNext", "DOM"]
+ *   }
+ * }
+ *
+ * // Then reference this file or use ts-morph for code strings
+ */
+
+export {};
+
+declare global {
+  // ============================================
+  // Web Streams API
+  // ============================================
+
+  /**
+   * A readable stream of data.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream
+   */
+  const ReadableStream: typeof globalThis.ReadableStream;
+
+  /**
+   * A writable stream of data.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStream
+   */
+  const WritableStream: typeof globalThis.WritableStream;
+
+  /**
+   * A transform stream that can be used to pipe data through a transformer.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/TransformStream
+   */
+  const TransformStream: typeof globalThis.TransformStream;
+
+  /**
+   * Default reader for ReadableStream
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader
+   */
+  const ReadableStreamDefaultReader: typeof globalThis.ReadableStreamDefaultReader;
+
+  /**
+   * Default writer for WritableStream
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter
+   */
+  const WritableStreamDefaultWriter: typeof globalThis.WritableStreamDefaultWriter;
+
+  // ============================================
+  // Blob and File APIs
+  // ============================================
+
+  /**
+   * A file-like object of immutable, raw data.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Blob
+   */
+  const Blob: typeof globalThis.Blob;
+
+  /**
+   * A file object representing a file.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/File
+   */
+  const File: typeof globalThis.File;
+
+  // ============================================
+  // URL APIs
+  // ============================================
+
+  /**
+   * Interface for URL manipulation.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/URL
+   */
+  const URL: typeof globalThis.URL;
+
+  /**
+   * Utility for working with URL query strings.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
+   */
+  const URLSearchParams: typeof globalThis.URLSearchParams;
+
+  // ============================================
+  // Error Handling
+  // ============================================
+
+  /**
+   * Exception type for DOM operations.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMException
+   */
+  const DOMException: typeof globalThis.DOMException;
+}
+`;
+var FETCH_TYPES = `/**
+ * QuickJS Global Type Definitions for @ricsam/quickjs-fetch
+ *
+ * These types define the globals injected by setupFetch() into a QuickJS context.
+ * Use these types to typecheck user code that will run inside QuickJS.
+ *
+ * @example
+ * // Typecheck QuickJS code with serve()
+ * serve({
+ *   fetch(request, server) {
+ *     if (request.url.includes("/ws")) {
+ *       server.upgrade(request, { data: { id: 123 } });
+ *       return new Response(null, { status: 101 });
+ *     }
+ *     return new Response("Hello!");
+ *   },
+ *   websocket: {
+ *     message(ws, message) {
+ *       ws.send("Echo: " + message);
+ *     }
+ *   }
+ * });
+ */
+
+export {};
+
+declare global {
+  // ============================================
+  // Standard Fetch API (from lib.dom)
+  // ============================================
+
+  /**
+   * Headers class for HTTP headers manipulation.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Headers
+   */
+  const Headers: typeof globalThis.Headers;
+
+  /**
+   * Request class for HTTP requests.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Request
+   */
+  const Request: typeof globalThis.Request;
+
+  /**
+   * Response class for HTTP responses.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Response
+   */
+  const Response: typeof globalThis.Response;
+
+  /**
+   * AbortController for cancelling fetch requests.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController
+   */
+  const AbortController: typeof globalThis.AbortController;
+
+  /**
+   * AbortSignal for listening to abort events.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+   */
+  const AbortSignal: typeof globalThis.AbortSignal;
+
+  /**
+   * FormData for constructing form data.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/FormData
+   */
+  const FormData: typeof globalThis.FormData;
+
+  /**
+   * Fetch function for making HTTP requests.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/fetch
+   */
+  function fetch(
+    input: RequestInfo | URL,
+    init?: RequestInit
+  ): Promise<Response>;
+
+  // ============================================
+  // QuickJS-specific: serve() API
+  // ============================================
+
+  /**
+   * Server interface for handling WebSocket upgrades within serve() handlers.
+   */
+  interface Server {
+    /**
+     * Upgrade an HTTP request to a WebSocket connection.
+     *
+     * @param request - The incoming HTTP request to upgrade
+     * @param options - Optional data to associate with the WebSocket connection
+     * @returns true if upgrade will proceed, false otherwise
+     *
+     * @example
+     * serve({
+     *   fetch(request, server) {
+     *     if (server.upgrade(request, { data: { userId: 123 } })) {
+     *       return new Response(null, { status: 101 });
+     *     }
+     *     return new Response("Upgrade failed", { status: 400 });
+     *   }
+     * });
+     */
+    upgrade(request: Request, options?: { data?: unknown }): boolean;
+  }
+
+  /**
+   * ServerWebSocket interface for WebSocket connections within serve() handlers.
+   *
+   * @typeParam T - The type of data associated with this WebSocket connection
+   */
+  interface ServerWebSocket<T = unknown> {
+    /**
+     * User data associated with this connection.
+     * Set via \`server.upgrade(request, { data: ... })\`.
+     */
+    readonly data: T;
+
+    /**
+     * Send a message to the client.
+     *
+     * @param message - The message to send (string, ArrayBuffer, or Uint8Array)
+     */
+    send(message: string | ArrayBuffer | Uint8Array): void;
+
+    /**
+     * Close the WebSocket connection.
+     *
+     * @param code - Optional close code (default: 1000)
+     * @param reason - Optional close reason
+     */
+    close(code?: number, reason?: string): void;
+
+    /**
+     * WebSocket ready state.
+     * - 0: CONNECTING
+     * - 1: OPEN
+     * - 2: CLOSING
+     * - 3: CLOSED
+     */
+    readonly readyState: number;
+  }
+
+  /**
+   * Options for the serve() function.
+   *
+   * @typeParam T - The type of data associated with WebSocket connections
+   */
+  interface ServeOptions<T = unknown> {
+    /**
+     * Handler for HTTP requests.
+     *
+     * @param request - The incoming HTTP request
+     * @param server - Server interface for WebSocket upgrades
+     * @returns Response or Promise resolving to Response
+     */
+    fetch(request: Request, server: Server): Response | Promise<Response>;
+
+    /**
+     * WebSocket event handlers.
+     */
+    websocket?: {
+      /**
+       * Called when a WebSocket connection is opened.
+       *
+       * @param ws - The WebSocket connection
+       */
+      open?(ws: ServerWebSocket<T>): void | Promise<void>;
+
+      /**
+       * Called when a message is received.
+       *
+       * @param ws - The WebSocket connection
+       * @param message - The received message (string or ArrayBuffer)
+       */
+      message?(
+        ws: ServerWebSocket<T>,
+        message: string | ArrayBuffer
+      ): void | Promise<void>;
+
+      /**
+       * Called when the connection is closed.
+       *
+       * @param ws - The WebSocket connection
+       * @param code - The close code
+       * @param reason - The close reason
+       */
+      close?(
+        ws: ServerWebSocket<T>,
+        code: number,
+        reason: string
+      ): void | Promise<void>;
+
+      /**
+       * Called when an error occurs.
+       *
+       * @param ws - The WebSocket connection
+       * @param error - The error that occurred
+       */
+      error?(ws: ServerWebSocket<T>, error: Error): void | Promise<void>;
+    };
+  }
+
+  /**
+   * Register an HTTP server handler in QuickJS.
+   *
+   * Only one serve() handler can be active at a time.
+   * Calling serve() again replaces the previous handler.
+   *
+   * @param options - Server configuration including fetch handler and optional WebSocket handlers
+   *
+   * @example
+   * serve({
+   *   fetch(request, server) {
+   *     const url = new URL(request.url);
+   *
+   *     if (url.pathname === "/ws") {
+   *       if (server.upgrade(request, { data: { connectedAt: Date.now() } })) {
+   *         return new Response(null, { status: 101 });
+   *       }
+   *     }
+   *
+   *     if (url.pathname === "/api/hello") {
+   *       return Response.json({ message: "Hello!" });
+   *     }
+   *
+   *     return new Response("Not Found", { status: 404 });
+   *   },
+   *   websocket: {
+   *     open(ws) {
+   *       console.log("Connected at:", ws.data.connectedAt);
+   *     },
+   *     message(ws, message) {
+   *       ws.send("Echo: " + message);
+   *     },
+   *     close(ws, code, reason) {
+   *       console.log("Closed:", code, reason);
+   *     }
+   *   }
+   * });
+   */
+  function serve<T = unknown>(options: ServeOptions<T>): void;
+}
+`;
+var FS_TYPES = `/**
+ * QuickJS Global Type Definitions for @ricsam/quickjs-fs
+ *
+ * These types define the globals injected by setupFs() into a QuickJS context.
+ * Use these types to typecheck user code that will run inside QuickJS.
+ *
+ * @example
+ * // Typecheck QuickJS code with file system access
+ * const root = await fs.getDirectory("/data");
+ * const fileHandle = await root.getFileHandle("config.json");
+ * const file = await fileHandle.getFile();
+ * const content = await file.text();
+ */
+
+export {};
+
+declare global {
+  // ============================================
+  // fs namespace - QuickJS-specific entry point
+  // ============================================
+
+  /**
+   * File System namespace providing access to the file system.
+   * This is the QuickJS-specific entry point (differs from browser's navigator.storage.getDirectory()).
+   */
+  namespace fs {
+    /**
+     * Get a directory handle for the given path.
+     *
+     * The host controls which paths are accessible. Invalid or unauthorized
+     * paths will throw an error.
+     *
+     * @param path - The path to request from the host
+     * @returns A promise resolving to a directory handle
+     * @throws If the path is not allowed or doesn't exist
+     *
+     * @example
+     * const root = await fs.getDirectory("/");
+     * const dataDir = await fs.getDirectory("/data");
+     */
+    function getDirectory(path: string): Promise<FileSystemDirectoryHandle>;
+  }
+
+  // ============================================
+  // File System Access API
+  // ============================================
+
+  /**
+   * Base interface for file system handles.
+   */
+  interface FileSystemHandle {
+    /**
+     * The kind of handle: "file" or "directory".
+     */
+    readonly kind: "file" | "directory";
+
+    /**
+     * The name of the file or directory.
+     */
+    readonly name: string;
+
+    /**
+     * Compare two handles to check if they reference the same entry.
+     *
+     * @param other - Another FileSystemHandle to compare against
+     * @returns true if both handles reference the same entry
+     */
+    isSameEntry(other: FileSystemHandle): Promise<boolean>;
+  }
+
+  /**
+   * Handle for a file in the file system.
+   */
+  interface FileSystemFileHandle extends FileSystemHandle {
+    /**
+     * Always "file" for file handles.
+     */
+    readonly kind: "file";
+
+    /**
+     * Get the file contents as a File object.
+     *
+     * @returns A promise resolving to a File object
+     *
+     * @example
+     * const file = await fileHandle.getFile();
+     * const text = await file.text();
+     */
+    getFile(): Promise<File>;
+
+    /**
+     * Create a writable stream for writing to the file.
+     *
+     * @param options - Options for the writable stream
+     * @returns A promise resolving to a writable stream
+     *
+     * @example
+     * const writable = await fileHandle.createWritable();
+     * await writable.write("Hello, World!");
+     * await writable.close();
+     */
+    createWritable(options?: {
+      /**
+       * If true, keeps existing file data. Otherwise, truncates the file.
+       */
+      keepExistingData?: boolean;
+    }): Promise<FileSystemWritableFileStream>;
+  }
+
+  /**
+   * Handle for a directory in the file system.
+   */
+  interface FileSystemDirectoryHandle extends FileSystemHandle {
+    /**
+     * Always "directory" for directory handles.
+     */
+    readonly kind: "directory";
+
+    /**
+     * Get a file handle within this directory.
+     *
+     * @param name - The name of the file
+     * @param options - Options for getting the file handle
+     * @returns A promise resolving to a file handle
+     * @throws If the file doesn't exist and create is not true
+     *
+     * @example
+     * const file = await dir.getFileHandle("data.json");
+     * const newFile = await dir.getFileHandle("output.txt", { create: true });
+     */
+    getFileHandle(
+      name: string,
+      options?: {
+        /**
+         * If true, creates the file if it doesn't exist.
+         */
+        create?: boolean;
+      }
+    ): Promise<FileSystemFileHandle>;
+
+    /**
+     * Get a subdirectory handle within this directory.
+     *
+     * @param name - The name of the subdirectory
+     * @param options - Options for getting the directory handle
+     * @returns A promise resolving to a directory handle
+     * @throws If the directory doesn't exist and create is not true
+     *
+     * @example
+     * const subdir = await dir.getDirectoryHandle("logs");
+     * const newDir = await dir.getDirectoryHandle("cache", { create: true });
+     */
+    getDirectoryHandle(
+      name: string,
+      options?: {
+        /**
+         * If true, creates the directory if it doesn't exist.
+         */
+        create?: boolean;
+      }
+    ): Promise<FileSystemDirectoryHandle>;
+
+    /**
+     * Remove a file or directory within this directory.
+     *
+     * @param name - The name of the entry to remove
+     * @param options - Options for removal
+     * @throws If the entry doesn't exist or cannot be removed
+     *
+     * @example
+     * await dir.removeEntry("old-file.txt");
+     * await dir.removeEntry("old-dir", { recursive: true });
+     */
+    removeEntry(
+      name: string,
+      options?: {
+        /**
+         * If true, removes directories recursively.
+         */
+        recursive?: boolean;
+      }
+    ): Promise<void>;
+
+    /**
+     * Resolve the path from this directory to a descendant handle.
+     *
+     * @param possibleDescendant - A handle that may be a descendant
+     * @returns An array of path segments, or null if not a descendant
+     *
+     * @example
+     * const path = await root.resolve(nestedFile);
+     * // ["subdir", "file.txt"]
+     */
+    resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;
+
+    /**
+     * Iterate over entries in this directory.
+     *
+     * @returns An async iterator of [name, handle] pairs
+     *
+     * @example
+     * for await (const [name, handle] of dir.entries()) {
+     *   console.log(name, handle.kind);
+     * }
+     */
+    entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
+
+    /**
+     * Iterate over entry names in this directory.
+     *
+     * @returns An async iterator of names
+     *
+     * @example
+     * for await (const name of dir.keys()) {
+     *   console.log(name);
+     * }
+     */
+    keys(): AsyncIterableIterator<string>;
+
+    /**
+     * Iterate over handles in this directory.
+     *
+     * @returns An async iterator of handles
+     *
+     * @example
+     * for await (const handle of dir.values()) {
+     *   console.log(handle.name, handle.kind);
+     * }
+     */
+    values(): AsyncIterableIterator<FileSystemHandle>;
+
+    /**
+     * Async iterator support for directory entries.
+     *
+     * @example
+     * for await (const [name, handle] of dir) {
+     *   console.log(name, handle.kind);
+     * }
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;
+  }
+
+  /**
+   * Parameters for write operations on FileSystemWritableFileStream.
+   */
+  interface WriteParams {
+    /**
+     * The type of write operation.
+     * - "write": Write data at the current position or specified position
+     * - "seek": Move the file position
+     * - "truncate": Truncate the file to a specific size
+     */
+    type: "write" | "seek" | "truncate";
+
+    /**
+     * The data to write (for "write" type).
+     */
+    data?: string | ArrayBuffer | Uint8Array | Blob;
+
+    /**
+     * The position to write at or seek to.
+     */
+    position?: number;
+
+    /**
+     * The size to truncate to (for "truncate" type).
+     */
+    size?: number;
+  }
+
+  /**
+   * Writable stream for writing to a file.
+   * Extends WritableStream with file-specific operations.
+   */
+  interface FileSystemWritableFileStream extends WritableStream<Uint8Array> {
+    /**
+     * Write data to the file.
+     *
+     * @param data - The data to write
+     * @returns A promise that resolves when the write completes
+     *
+     * @example
+     * await writable.write("Hello, World!");
+     * await writable.write(new Uint8Array([1, 2, 3]));
+     * await writable.write({ type: "write", data: "text", position: 0 });
+     */
+    write(
+      data: string | ArrayBuffer | Uint8Array | Blob | WriteParams
+    ): Promise<void>;
+
+    /**
+     * Seek to a position in the file.
+     *
+     * @param position - The byte position to seek to
+     * @returns A promise that resolves when the seek completes
+     *
+     * @example
+     * await writable.seek(0); // Seek to beginning
+     * await writable.write("Overwrite");
+     */
+    seek(position: number): Promise<void>;
+
+    /**
+     * Truncate the file to a specific size.
+     *
+     * @param size - The size to truncate to
+     * @returns A promise that resolves when the truncation completes
+     *
+     * @example
+     * await writable.truncate(100); // Keep only first 100 bytes
+     */
+    truncate(size: number): Promise<void>;
+  }
+}
+`;
+var TYPE_DEFINITIONS = {
+  core: CORE_TYPES,
+  fetch: FETCH_TYPES,
+  fs: FS_TYPES
+};
+export {
+  TYPE_DEFINITIONS,
+  FS_TYPES,
+  FETCH_TYPES,
+  CORE_TYPES
+};
+
+//# debugId=DB524E5F7383894464756E2164756E21