@ricsam/quickjs-fetch 0.2.11 → 0.2.12

package/dist/cjs/package.json

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

package/dist/mjs/package.json

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

package/dist/types/quickjs.d.ts

@@ -0,0 +1,241 @@
+/**
+ * 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;
+}

package/package.json

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