@ricsam/quickjs-test-utils 0.0.1 → 1.0.0

package/README.md

@@ -1,45 +1,99 @@
 # @ricsam/quickjs-test-utils
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ricsam/quickjs-test-utils`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Testing utilities including type checking for QuickJS user code.
+
+```bash
+bun add @ricsam/quickjs-test-utils
+```
+
+#### Type Checking QuickJS Code
+
+Validate TypeScript/JavaScript code that will run inside QuickJS before execution using `ts-morph`:
+
+```typescript
+import { typecheckQuickJSCode } from "@ricsam/quickjs-test-utils";
+
+const result = typecheckQuickJSCode(`
+  serve({
+    fetch(request, server) {
+      const url = new URL(request.url);
+
+      if (url.pathname === "/ws") {
+        server.upgrade(request, { data: { userId: 123 } });
+        return new Response(null, { status: 101 });
+      }
+
+      return Response.json({ message: "Hello!" });
+    },
+    websocket: {
+      message(ws, message) {
+        ws.send("Echo: " + message);
+      }
+    }
+  });
+`, { include: ["core", "fetch"] });
+
+if (!result.success) {
+  console.error("Type errors found:");
+  for (const error of result.errors) {
+    console.error(`  Line ${error.line}: ${error.message}`);
+  }
+}
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `include` | Which package types to include: `"core"`, `"fetch"`, `"fs"` (default: all) |
+| `compilerOptions` | Additional TypeScript compiler options |
+
+**Using with tests:**
+
+```typescript
+import { describe, expect, test } from "bun:test";
+import { typecheckQuickJSCode } from "@ricsam/quickjs-test-utils";
+
+describe("QuickJS code validation", () => {
+  test("server code is type-safe", () => {
+    const result = typecheckQuickJSCode(userProvidedCode, {
+      include: ["fetch"]
+    });
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+#### Type Definition Strings
+
+The type definitions are also exported as strings for custom use cases:
+
+```typescript
+import {
+  CORE_TYPES,   // ReadableStream, Blob, File, URL, etc.
+  FETCH_TYPES,  // fetch, Request, Response, serve, etc.
+  FS_TYPES,     // fs.getDirectory, FileSystemHandle, etc.
+  TYPE_DEFINITIONS  // All types as { core, fetch, fs }
+} from "@ricsam/quickjs-test-utils";
+
+// Use with your own ts-morph project
+project.createSourceFile("quickjs-globals.d.ts", FETCH_TYPES);
+```
+
+#### Type Definition Files
+
+Each package also exports `.d.ts` files for use with `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"]
+  },
+  "include": ["quickjs-code/**/*.ts"],
+  "references": [
+    { "path": "./node_modules/@ricsam/quickjs-core/src/quickjs.d.ts" },
+    { "path": "./node_modules/@ricsam/quickjs-fetch/src/quickjs.d.ts" },
+    { "path": "./node_modules/@ricsam/quickjs-fs/src/quickjs.d.ts" }
+  ]
+}
+```

package/dist/cjs/index.cjs

@@ -0,0 +1,58 @@
+// @bun @bun-cjs
+(function(exports, require, module, __filename, __dirname) {var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// packages/test-utils/src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  useTestContext: () => import_context.useTestContext,
+  useFetchTestContext: () => import_fetch_context.useFetchTestContext,
+  typecheckQuickJSCode: () => import_typecheck.typecheckQuickJSCode,
+  startIntegrationServer: () => import_integration_server.startIntegrationServer,
+  formatTypecheckErrors: () => import_typecheck.formatTypecheckErrors,
+  evalCodeAsync: () => import_eval.evalCodeAsync,
+  evalCode: () => import_eval.evalCode,
+  disposeTestContext: () => import_context.disposeTestContext,
+  disposeFetchTestContext: () => import_fetch_context.disposeFetchTestContext,
+  createTestContext: () => import_context.createTestContext,
+  createFetchTestContext: () => import_fetch_context.createFetchTestContext,
+  TYPE_DEFINITIONS: () => import_quickjs_types.TYPE_DEFINITIONS,
+  FS_TYPES: () => import_quickjs_types.FS_TYPES,
+  FETCH_TYPES: () => import_quickjs_types.FETCH_TYPES,
+  CORE_TYPES: () => import_quickjs_types.CORE_TYPES
+});
+module.exports = __toCommonJS(exports_src);
+var import_context = require("./context.ts");
+var import_fetch_context = require("./fetch-context.ts");
+var import_eval = require("./eval.ts");
+var import_integration_server = require("./integration-server.ts");
+var import_typecheck = require("./typecheck.ts");
+var import_quickjs_types = require("./quickjs-types.ts");
+})
+
+//# debugId=6163F5C604565B7564756E2164756E21

package/dist/cjs/index.cjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/index.ts"],
+  "sourcesContent": [
+    "export {\n  createTestContext,\n  disposeTestContext,\n  useTestContext,\n  type TestContext,\n} from \"./context.ts\";\n\nexport {\n  createFetchTestContext,\n  disposeFetchTestContext,\n  useFetchTestContext,\n  type FetchTestContext,\n  type CreateFetchTestContextOptions,\n} from \"./fetch-context.ts\";\n\nexport { evalCode, evalCodeAsync } from \"./eval.ts\";\n\nexport {\n  startIntegrationServer,\n  type IntegrationTestServer,\n  type StartIntegrationServerOptions,\n} from \"./integration-server.ts\";\n\nexport {\n  typecheckQuickJSCode,\n  formatTypecheckErrors,\n  type TypecheckResult,\n  type TypecheckError,\n  type TypecheckOptions,\n} from \"./typecheck.ts\";\n\nexport {\n  CORE_TYPES,\n  FETCH_TYPES,\n  FS_TYPES,\n  TYPE_DEFINITIONS,\n  type TypeDefinitionKey,\n} from \"./quickjs-types.ts\";\n\n// For fs and runtime contexts, import from subpaths:\n// import { createFsTestContext } from \"@ricsam/quickjs-test-utils/fs\";\n// import { createRuntimeTestContext } from \"@ricsam/quickjs-test-utils/runtime\";\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKO,IALP;AAaO,IANP;AAQwC,IAAxC;AAMO,IAJP;AAYO,IANP;AAcO,IANP;",
+  "debugId": "6163F5C604565B7564756E2164756E21",
+  "names": []
+}

package/dist/cjs/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@ricsam/quickjs-test-utils",
+  "version": "1.0.0",
+  "type": "commonjs"
+}

package/dist/mjs/index.mjs

@@ -0,0 +1,45 @@
+// @bun
+// packages/test-utils/src/index.ts
+import {
+  createTestContext,
+  disposeTestContext,
+  useTestContext
+} from "./context.ts";
+import {
+  createFetchTestContext,
+  disposeFetchTestContext,
+  useFetchTestContext
+} from "./fetch-context.ts";
+import { evalCode, evalCodeAsync } from "./eval.ts";
+import {
+  startIntegrationServer
+} from "./integration-server.ts";
+import {
+  typecheckQuickJSCode,
+  formatTypecheckErrors
+} from "./typecheck.ts";
+import {
+  CORE_TYPES,
+  FETCH_TYPES,
+  FS_TYPES,
+  TYPE_DEFINITIONS
+} from "./quickjs-types.ts";
+export {
+  useTestContext,
+  useFetchTestContext,
+  typecheckQuickJSCode,
+  startIntegrationServer,
+  formatTypecheckErrors,
+  evalCodeAsync,
+  evalCode,
+  disposeTestContext,
+  disposeFetchTestContext,
+  createTestContext,
+  createFetchTestContext,
+  TYPE_DEFINITIONS,
+  FS_TYPES,
+  FETCH_TYPES,
+  CORE_TYPES
+};
+
+//# debugId=FD8F45F39BD927E164756E2164756E21

package/dist/mjs/index.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/index.ts"],
+  "sourcesContent": [
+    "export {\n  createTestContext,\n  disposeTestContext,\n  useTestContext,\n  type TestContext,\n} from \"./context.ts\";\n\nexport {\n  createFetchTestContext,\n  disposeFetchTestContext,\n  useFetchTestContext,\n  type FetchTestContext,\n  type CreateFetchTestContextOptions,\n} from \"./fetch-context.ts\";\n\nexport { evalCode, evalCodeAsync } from \"./eval.ts\";\n\nexport {\n  startIntegrationServer,\n  type IntegrationTestServer,\n  type StartIntegrationServerOptions,\n} from \"./integration-server.ts\";\n\nexport {\n  typecheckQuickJSCode,\n  formatTypecheckErrors,\n  type TypecheckResult,\n  type TypecheckError,\n  type TypecheckOptions,\n} from \"./typecheck.ts\";\n\nexport {\n  CORE_TYPES,\n  FETCH_TYPES,\n  FS_TYPES,\n  TYPE_DEFINITIONS,\n  type TypeDefinitionKey,\n} from \"./quickjs-types.ts\";\n\n// For fs and runtime contexts, import from subpaths:\n// import { createFsTestContext } from \"@ricsam/quickjs-test-utils/fs\";\n// import { createRuntimeTestContext } from \"@ricsam/quickjs-test-utils/runtime\";\n"
+  ],
+  "mappings": ";;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA;AAAA;AAAA;AAAA;AAAA;AAQA;AAEA;AAAA;AAAA;AAMA;AAAA;AAAA;AAAA;AAQA;AAAA;AAAA;AAAA;AAAA;AAAA;",
+  "debugId": "FD8F45F39BD927E164756E2164756E21",
+  "names": []
+}

package/dist/mjs/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@ricsam/quickjs-test-utils",
+  "version": "1.0.0",
+  "type": "module"
+}

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;

package/dist/types/typecheck.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Type-checking utility for QuickJS user code using ts-morph.
+ *
+ * This utility allows you to validate TypeScript code strings against
+ * the QuickJS global type definitions before running them in the sandbox.
+ *
+ * @example
+ * import { typecheckQuickJSCode } from "@ricsam/quickjs-test-utils";
+ *
+ * const result = typecheckQuickJSCode(`
+ *   serve({
+ *     fetch(request, server) {
+ *       return new Response("Hello!");
+ *     }
+ *   });
+ * `, { include: ["fetch"] });
+ *
+ * if (!result.success) {
+ *   console.error("Type errors:", result.errors);
+ * }
+ */
+import { ts } from "ts-morph";
+/**
+ * Result of type-checking QuickJS code.
+ */
+export interface TypecheckResult {
+    /**
+     * Whether the code passed type checking.
+     */
+    success: boolean;
+    /**
+     * Array of type errors found in the code.
+     */
+    errors: TypecheckError[];
+}
+/**
+ * A single type-checking error.
+ */
+export interface TypecheckError {
+    /**
+     * The error message from TypeScript.
+     */
+    message: string;
+    /**
+     * The line number where the error occurred (1-indexed).
+     */
+    line?: number;
+    /**
+     * The column number where the error occurred (1-indexed).
+     */
+    column?: number;
+    /**
+     * The TypeScript error code.
+     */
+    code?: number;
+}
+/**
+ * Options for type-checking QuickJS code.
+ */
+export interface TypecheckOptions {
+    /**
+     * Which package types to include.
+     * @default ["core", "fetch", "fs"]
+     */
+    include?: Array<"core" | "fetch" | "fs">;
+    /**
+     * Additional compiler options to pass to TypeScript.
+     */
+    compilerOptions?: Partial<ts.CompilerOptions>;
+}
+/**
+ * Type-check QuickJS user code against the package type definitions.
+ *
+ * @param code - The TypeScript/JavaScript code to check
+ * @param options - Configuration options
+ * @returns The result of type checking
+ *
+ * @example
+ * // Check code that uses the fetch API
+ * const result = typecheckQuickJSCode(`
+ *   const response = await fetch("https://api.example.com/data");
+ *   const data = await response.json();
+ * `, { include: ["core", "fetch"] });
+ *
+ * @example
+ * // Check code that uses serve()
+ * const result = typecheckQuickJSCode(`
+ *   serve({
+ *     fetch(request, server) {
+ *       return new Response("Hello!");
+ *     }
+ *   });
+ * `, { include: ["fetch"] });
+ *
+ * @example
+ * // Check code that uses the file system API
+ * const result = typecheckQuickJSCode(`
+ *   const root = await fs.getDirectory("/data");
+ *   const file = await root.getFileHandle("config.json");
+ * `, { include: ["core", "fs"] });
+ */
+export declare function typecheckQuickJSCode(code: string, options?: TypecheckOptions): TypecheckResult;
+/**
+ * Format type-check errors for display.
+ *
+ * @param result - The type-check result
+ * @returns A formatted string of errors
+ *
+ * @example
+ * const result = typecheckQuickJSCode(code);
+ * if (!result.success) {
+ *   console.error(formatTypecheckErrors(result));
+ * }
+ */
+export declare function formatTypecheckErrors(result: TypecheckResult): string;

package/package.json

@@ -1,10 +1,66 @@
 {
   "name": "@ricsam/quickjs-test-utils",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @ricsam/quickjs-test-utils",
+  "version": "1.0.0",
+  "main": "./dist/cjs/index.cjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "import": "./dist/mjs/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ts-morph": "^24.0.0"
+  },
+  "peerDependencies": {
+    "quickjs-emscripten": "^0.31.0",
+    "@ricsam/quickjs-core": "^0.2.0",
+    "@ricsam/quickjs-fetch": "^0.2.0",
+    "@ricsam/quickjs-fs": "^0.2.0",
+    "@ricsam/quickjs-runtime": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@ricsam/quickjs-fs": {
+      "optional": true
+    },
+    "@ricsam/quickjs-runtime": {
+      "optional": true
+    }
+  },
+  "author": "Richard Samuelsson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/richie-qjs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ricsam/richie-qjs/issues"
+  },
+  "homepage": "https://github.com/ricsam/richie-qjs#readme",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
+    "quickjs",
+    "sandbox",
+    "javascript",
+    "runtime",
+    "fetch",
+    "filesystem",
+    "streams",
+    "wasm",
+    "emscripten"
+  ],
+  "description": "Testing utilities for QuickJS runtime",
+  "module": "./dist/mjs/index.mjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
   ]
-}
+}