chore(docs): add comments to API type in README (#261)

This commit fills out the API types in the README with the comments
that are present in `types.d.ts`, to add more context for every option.

Author: vados-cosmonic

README.md

@@ -212,18 +212,115 @@ object. Using the `fetchEvent` requires enabling the `http` feature.
 
 ```ts
 export function componentize(opts: {
-  sourcePath: string,
-  witPath: string,
-  worldName: string,
-  debug?: bool,
-  debugBuild?: bool,
-  engine?: string,
-  preview2Adapter?: string,
-  disableFeatures?: ('stdio' | 'random' | 'clocks' | 'http', 'fetch-event')[],
-}): {
-  component: Uint8Array,
-  imports: string[]
-}
+  /**
+   * The path to the file to componentize.
+   *
+   * This file must be a valid JavaScript module, and can import other modules using relative paths.
+   */
+  sourcePath: string;
+  /**
+   * Path to WIT file or folder
+   */
+  witPath?: string;
+  /**
+   * Target world name for componentization
+   */
+  worldName?: string;
+  /**
+   * Path to custom ComponentizeJS engine build to use
+   */
+  engine?: string;
+  /**
+   * Path to custom weval cache to use
+   */
+  aotCache?: string;
+  /**
+   * Enable AoT using weval
+   */
+  enableAot?: boolean;
+  /**
+   * Use a pre-existing path to the `weval` binary, if present
+   */
+  wevalBin?: string;
+  /**
+   * Use a pre-existing path to the `wizer` binary, if present
+   */
+  wizerBin?: string;
+  /**
+   * Path to custom Preview2 Adapter
+   */
+  preview2Adapter?: string;
+  /**
+   * Disable WASI features in the base engine
+   * Disabling all features results in a pure component with no WASI dependence
+   *
+   * - stdio: console.log(), console.error and errors are provided to stderr
+   * - random: Math.random() and crypto.randomBytes()
+   * - clocks: Date.now(), performance.now()
+   * - http: fetch() support
+   *
+   */
+  disableFeatures?: ('stdio' | 'random' | 'clocks' | 'http' | 'fetch-event')[];
+  /**
+   * Enable WASI features in the base engine
+   * (no experimental subsystems currently supported)
+   */
+  enableFeatures?: [];
+  /**
+   * Pass environment variables to the spawned Wizer or Weval Process
+   * If set to true, all host environment variables are passed
+   * To pass only a subset, provide an object with the desired variables
+   */
+  env?: boolean | Record<string, string>;
+  /**
+   * Runtime arguments to provide to the StarlingMonkey engine initialization
+   * (see https://github.com/bytecodealliance/StarlingMonkey/blob/main/include/config-parser.h)
+   */
+  runtimeArgs?: string;
+  /**
+   * Use a debug build
+   * Note that the debug build only includes the names section only for size optimization, and not DWARF
+   * debugging sections, due to a lack of support in Node.js for these debugging workflows currently.
+   */
+  debugBuild?: boolean;
+  /**
+   * Debug options
+   */
+  debug?: {
+    /**  Whether to enable bindings-specific debugging */
+    bindings?: boolean;
+    /**  Path to debug bindings to use */
+    bindingsDir?: string;
+    /**  Whether to enable binary-specific debugging */
+    binary?: boolean;
+    /**  Path    to enable binary-specific debugging */
+    binaryPath?: string;
+    /** Whether to enable wizer logging */
+    wizerLogging: false;
+  }
+}): Promise<{
+  /**
+   * Component binary
+   */
+  component: Uint8Array;
+  /**
+   * Used guest imports in JavaScript (excluding those from StarlingMonkey engine)
+   */
+  imports: [[string, string]][];
+  /**
+   * Debugging output (only present if enabled)
+   */
+  debug?: {
+    /** Whether bindings debugging was enabled */
+    bindings?: boolean;
+    /** Work directory used during processing */
+    workDir?: string;
+    /** Whether binary debugging was enabled */
+    binary?: boolean;
+    /** Path to the produced binary */
+    binaryPath?: string;
+  };
+}>
 ```
 
 Converts a JS source into a component binary.

types.d.ts

@@ -4,88 +4,108 @@ interface ComponentizeOptions {
    *
    * This file must be a valid JavaScript module, and can import other modules using relative paths.
    */
-  sourcePath: string,
+  sourcePath: string;
   /**
-   * Use a debug build
-   * Note that the debug build only includes the names section only for size optimization, and not DWARF
-   * debugging sections, due to a lack of support in Node.js for these debugging workflows currently.
+   * Path to WIT file or folder
    */
-  debugBuild?: boolean,
+  witPath?: string;
+  /**
+   * Target world name for componentization
+   */
+  worldName?: string;
   /**
    * Path to custom ComponentizeJS engine build to use
    */
-  engine?: string,
+  engine?: string;
   /**
    * Path to custom weval cache to use
    */
-  aotCache?: string,
+  aotCache?: string;
   /**
    * Enable AoT using weval
    */
-  enableAot?: boolean,
+  enableAot?: boolean;
   /**
    * Use a pre-existing path to the `weval` binary, if present
    */
-  wevalBin?: string,
+  wevalBin?: string;
   /**
    * Use a pre-existing path to the `wizer` binary, if present
    */
-  wizerBin?: string,
+  wizerBin?: string;
   /**
    * Path to custom Preview2 Adapter
    */
-  preview2Adapter?: string,
-  /**
-   * Path to WIT file or folder
-   */
-  witPath?: string,
-  /**
-   * Target world name for componentization
-   */
-  worldName?: string,
+  preview2Adapter?: string;
   /**
    * Disable WASI features in the base engine
    * Disabling all features results in a pure component with no WASI dependence
-   * 
+   *
    * - stdio: console.log(), console.error and errors are provided to stderr
    * - random: Math.random() and crypto.randomBytes()
    * - clocks: Date.now(), performance.now()
    * - http: fetch() support
-   * 
+   *
    */
-  disableFeatures?: ('stdio' | 'random' | 'clocks' | 'http')[],
+  disableFeatures?: ('stdio' | 'random' | 'clocks' | 'http' | 'fetch-event')[];
   /**
    * Enable WASI features in the base engine
    * (no experimental subsystems currently supported)
    */
-  enableFeatures?: [],
+  enableFeatures?: [];
   /**
    * Pass environment variables to the spawned Wizer or Weval Process
    * If set to true, all host environment variables are passed
    * To pass only a subset, provide an object with the desired variables
    */
-  env?: boolean | Record<string, string>,
+  env?: boolean | Record<string, string>;
   /**
    * Runtime arguments to provide to the StarlingMonkey engine initialization
    * (see https://github.com/bytecodealliance/StarlingMonkey/blob/main/include/config-parser.h)
    */
-  runtimeArgs?: string,
+  runtimeArgs?: string;
+  /**
+   * Use a debug build
+   * Note that the debug build only includes the names section only for size optimization, and not DWARF
+   * debugging sections, due to a lack of support in Node.js for these debugging workflows currently.
+   */
+  debugBuild?: boolean;
+  /**
+   * Debug options
+   */
+  debug?: {
+    /**  Whether to enable bindings-specific debugging */
+    bindings?: boolean;
+    /**  Path to debug bindings to use */
+    bindingsDir?: string;
+    /**  Whether to enable binary-specific debugging */
+    binary?: boolean;
+    /**  Path to the binary that was output */
+    binaryPath?: string;
+    /** Whether to enable wizer logging */
+    wizerLogging: false;
+  };
 }
 
 /**
  * Componentize a JavaScript module to a WebAssembly component
  *
  * @param opts Componentize options
  */
-export function componentize(opts: ComponentizeOptions): Promise<ComponentizeOutput>
+export function componentize(
+  opts: ComponentizeOptions,
+): Promise<ComponentizeOutput>;
 
 /**
  * @deprecated Use `componentize(opts)` instead
  *
  * @param source Source code of JavaScript module to componentize
  * @param opts Componentize options
  */
-export function componentize(source: string, opts: ComponentizeOptions): Promise<ComponentizeOutput>
+export function componentize(
+  source: string,
+  opts: ComponentizeOptions,
+): Promise<ComponentizeOutput>;
 
 /**
  * @deprecated Use `componentize(opts)` instead
@@ -94,20 +114,37 @@ export function componentize(source: string, opts: ComponentizeOptions): Promise
  * @param witWorld Inline WIT string to componentize to
  * @param opts Componentize options
  */
-export function componentize(source: string, witWorld: string, opts?: ComponentizeOptions): Promise<ComponentizeOutput>
+export function componentize(
+  source: string,
+  witWorld: string,
+  opts?: ComponentizeOptions,
+): Promise<ComponentizeOutput>;
 
 interface ComponentizeOutput {
   /**
    * Component binary
    */
-  component: Uint8Array,
+  component: Uint8Array;
   /**
    * Used guest imports in JavaScript (excluding those from StarlingMonkey engine)
    */
-  imports: [[string, string]][]
+  imports: [[string, string]][];
+  /**
+   * Debugging output (only present if enabled)
+   */
+  debug?: {
+    /** Whether bindings debugging was enabled */
+    bindings?: boolean;
+    /** Work directory used during processing */
+    workDir?: string;
+    /** Whether binary debugging was enabled */
+    binary?: boolean;
+    /** Path to the produced binary */
+    binaryPath?: string;
+  };
 }
 
 /**
  * ComponentizeJS version string
  */
-export const version: string
+export const version: string;