@typespec/http-server-js 0.58.0-alpha.10-dev.3

package/generated-defs/helpers/multipart.ts

@@ -0,0 +1,256 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Module } from "../../src/ctx.js";
+
+export let module: Module = undefined as any;
+
+// prettier-ignore
+const lines = [
+  "// Copyright (c) Microsoft Corporation",
+  "// Licensed under the MIT license.",
+  "",
+  "import type * as http from \"node:http\";",
+  "",
+  "export interface HttpPart {",
+  "  headers: { [k: string]: string | undefined };",
+  "  body: ReadableStream<Buffer>;",
+  "}",
+  "",
+  "/**",
+  " * Consumes a stream of incoming data and splits it into individual streams for each part of a multipart request, using",
+  " * the provided `boundary` value.",
+  " */",
+  "function MultipartBoundaryTransformStream(",
+  "  boundary: string,",
+  "): ReadableWritablePair<ReadableStream<Buffer>, Buffer> {",
+  "  let buffer: Buffer = Buffer.alloc(0);",
+  "  // Initialize subcontroller to an object that does nothing. Multipart bodies may contain a preamble before the first",
+  "  // boundary, so this dummy controller will discard it.",
+  "  let subController: { enqueue(chunk: Buffer): void; close(): void } | null = {",
+  "    enqueue() {},",
+  "    close() {},",
+  "  };",
+  "",
+  "  let boundarySplit = Buffer.from(`--${boundary}`);",
+  "  let initialized = false;",
+  "",
+  "  // We need to keep at least the length of the boundary split plus room for CRLFCRLF in the buffer to detect the boundaries.",
+  "  // We subtract one from this length because if the whole thing were in the buffer, we would detect it and move past it.",
+  "  const bufferKeepLength = boundarySplit.length + BUF_CRLFCRLF.length - 1;",
+  "  let _readableController: ReadableStreamDefaultController<ReadableStream<Buffer>> = null as any;",
+  "",
+  "  const readable = new ReadableStream<ReadableStream<Buffer>>({",
+  "    start(controller) {",
+  "      _readableController = controller;",
+  "    },",
+  "  });",
+  "",
+  "  const readableController = _readableController;",
+  "",
+  "  const writable = new WritableStream<Buffer>({",
+  "    write: async (chunk) => {",
+  "      buffer = Buffer.concat([buffer, chunk]);",
+  "",
+  "      let index: number;",
+  "",
+  "      while ((index = buffer.indexOf(boundarySplit)) !== -1) {",
+  "        // We found a boundary, emit everything before it and initialize a new stream for the next part.",
+  "",
+  "        // We are initialized if we have found the boundary at least once.",
+  "        //",
+  "        // Cases",
+  "        // 1. If the index is zero and we aren't initialized, there was no preamble.",
+  "        // 2. If the index is zero and we are initialized, then we had to have found \\r\\n--boundary, nothing special to do.",
+  "        // 3. If the index is not zero, and we are initialized, then we found \\r\\n--boundary somewhere in the middle,",
+  "        //    nothing special to do.",
+  "        // 4. If the index is not zero and we aren't initialized, then we need to check that boundarySplit was preceded",
+  "        //    by \\r\\n for validity, because the preamble must end with \\r\\n.",
+  "",
+  "        if (index > 0) {",
+  "          if (!initialized) {",
+  "            if (!buffer.subarray(index - 2, index).equals(Buffer.from(\"\\r\\n\"))) {",
+  "              readableController.error(new Error(\"Invalid preamble in multipart body.\"));",
+  "            } else {",
+  "              await enqueueSub(buffer.subarray(0, index - 2));",
+  "            }",
+  "          } else {",
+  "            await enqueueSub(buffer.subarray(0, index));",
+  "          }",
+  "        }",
+  "",
+  "        // We enqueued everything before the boundary, so we clear the buffer past the boundary",
+  "        buffer = buffer.subarray(index + boundarySplit.length);",
+  "",
+  "        // We're done with the current part, so close the stream. If this is the opening boundary, there won't be a",
+  "        // subcontroller yet.",
+  "        subController?.close();",
+  "        subController = null;",
+  "",
+  "        if (!initialized) {",
+  "          initialized = true;",
+  "          boundarySplit = Buffer.from(`\\r\\n${boundarySplit}`);",
+  "        }",
+  "      }",
+  "",
+  "      if (buffer.length > bufferKeepLength) {",
+  "        await enqueueSub(buffer.subarray(0, -bufferKeepLength));",
+  "        buffer = buffer.subarray(-bufferKeepLength);",
+  "      }",
+  "    },",
+  "    close() {",
+  "      if (!/--(\\r\\n)?/.test(buffer.toString(\"utf-8\"))) {",
+  "        readableController.error(new Error(\"Unexpected characters after final boundary.\"));",
+  "      }",
+  "",
+  "      subController?.close();",
+  "",
+  "      readableController.close();",
+  "    },",
+  "  });",
+  "",
+  "  async function enqueueSub(s: Buffer) {",
+  "    subController ??= await new Promise<ReadableStreamDefaultController>((resolve) => {",
+  "      readableController.enqueue(",
+  "        new ReadableStream<Buffer>({",
+  "          start: (controller) => resolve(controller),",
+  "        }),",
+  "      );",
+  "    });",
+  "",
+  "    subController.enqueue(s);",
+  "  }",
+  "",
+  "  return { readable, writable };",
+  "}",
+  "",
+  "const BUF_CRLFCRLF = Buffer.from(\"\\r\\n\\r\\n\");",
+  "",
+  "/**",
+  " * Consumes a stream of the contents of a single part of a multipart request and emits an `HttpPart` object for each part.",
+  " * This consumes just enough of the stream to read the headers, and then forwards the rest of the stream as the body.",
+  " */",
+  "class HttpPartTransform extends TransformStream<ReadableStream<Buffer>, HttpPart> {",
+  "  constructor() {",
+  "    super({",
+  "      transform: async (partRaw, controller) => {",
+  "        const reader = partRaw.getReader();",
+  "",
+  "        let buf = Buffer.alloc(0);",
+  "        let idx;",
+  "",
+  "        while ((idx = buf.indexOf(BUF_CRLFCRLF)) === -1) {",
+  "          const { done, value } = await reader.read();",
+  "          if (done) {",
+  "            throw new Error(\"Unexpected end of part.\");",
+  "          }",
+  "          buf = Buffer.concat([buf, value]);",
+  "        }",
+  "",
+  "        const headerText = buf.subarray(0, idx).toString(\"utf-8\").trim();",
+  "",
+  "        const headers = Object.fromEntries(",
+  "          headerText.split(\"\\r\\n\").map((line) => {",
+  "            const [name, value] = line.split(\": \", 2);",
+  "",
+  "            return [name.toLowerCase(), value];",
+  "          }),",
+  "        ) as { [k: string]: string };",
+  "",
+  "        const body = new ReadableStream<Buffer>({",
+  "          start(controller) {",
+  "            controller.enqueue(buf.subarray(idx + BUF_CRLFCRLF.length));",
+  "          },",
+  "          async pull(controller) {",
+  "            const { done, value } = await reader.read();",
+  "",
+  "            if (done) {",
+  "              controller.close();",
+  "            } else {",
+  "              controller.enqueue(value);",
+  "            }",
+  "          },",
+  "        });",
+  "",
+  "        controller.enqueue({ headers, body });",
+  "      },",
+  "    });",
+  "  }",
+  "}",
+  "",
+  "/**",
+  " * Processes a request as a multipart request, returning a stream of `HttpPart` objects, each representing an individual",
+  " * part in the multipart request.",
+  " *",
+  " * Only call this function if you have already validated the content type of the request and confirmed that it is a",
+  " * multipart request.",
+  " *",
+  " * @throws Error if the content-type header is missing or does not contain a boundary field.",
+  " *",
+  " * @param request - the incoming request to parse as multipart",
+  " * @returns a stream of HttpPart objects, each representing an individual part in the multipart request",
+  " */",
+  "export function createMultipartReadable(request: http.IncomingMessage): ReadableStream<HttpPart> {",
+  "  const boundary = request.headers[\"content-type\"]",
+  "    ?.split(\";\")",
+  "    .find((s) => s.includes(\"boundary=\"))",
+  "    ?.split(\"=\", 2)[1];",
+  "  if (!boundary) {",
+  "    throw new Error(\"Invalid request: missing boundary in content-type.\");",
+  "  }",
+  "",
+  "  const bodyStream = new ReadableStream<Uint8Array>({",
+  "    start(controller) {",
+  "      request.on(\"data\", (chunk: Buffer) => {",
+  "        controller.enqueue(chunk);",
+  "      });",
+  "      request.on(\"end\", () => controller.close());",
+  "    },",
+  "  });",
+  "",
+  "  return bodyStream",
+  "    .pipeThrough(MultipartBoundaryTransformStream(boundary))",
+  "    .pipeThrough(new HttpPartTransform());",
+  "}",
+  "",
+  "// Gross polyfill because Safari doesn't support this yet.",
+  "//",
+  "// https://bugs.webkit.org/show_bug.cgi?id=194379",
+  "// https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream#browser_compatibility",
+  "(ReadableStream.prototype as any)[Symbol.asyncIterator] ??= async function* () {",
+  "  const reader = this.getReader();",
+  "  try {",
+  "    while (true) {",
+  "      const { done, value } = await reader.read();",
+  "      if (done) return value;",
+  "      yield value;",
+  "    }",
+  "  } finally {",
+  "    reader.releaseLock();",
+  "  }",
+  "};",
+  "",
+  "declare global {",
+  "  interface ReadableStream<R> {",
+  "    [Symbol.asyncIterator](): AsyncIterableIterator<R>;",
+  "  }",
+  "}",
+  "",
+];
+
+export async function createModule(parent: Module): Promise<Module> {
+  if (module) return module;
+
+  module = {
+    name: "multipart",
+    cursor: parent.cursor.enter("multipart"),
+    imports: [],
+    declarations: [],
+  };
+
+  module.declarations.push(lines);
+
+  parent.declarations.push(module);
+
+  return module;
+}

package/generated-defs/helpers/router.ts

@@ -0,0 +1,266 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Module } from "../../src/ctx.js";
+
+export let module: Module = undefined as any;
+
+// prettier-ignore
+const lines = [
+  "// Copyright (c) Microsoft Corporation",
+  "// Licensed under the MIT license.",
+  "",
+  "import type * as http from \"node:http\";",
+  "",
+  "/** A policy that can be applied to a route or a set of routes. */",
+  "export interface Policy {",
+  "  /** Optional policy name. */",
+  "  name?: string;",
+  "",
+  "  /**",
+  "   * Applies the policy to the request.",
+  "   *",
+  "   * Policies _MUST_ call `next()` to pass the request to the next policy _OR_ call `response.end()` to terminate,",
+  "   * and _MUST NOT_ do both.",
+  "   *",
+  "   * If the policy passes a `request` object to `next()`, that request object will be used instead of the original",
+  "   * request object for the remainder of the policy chain. If the policy does _not_ pass a request object to `next()`,",
+  "   * the same object that was passed to this policy will be forwarded to the next policy automatically.",
+  "   *",
+  "   * @param request - The incoming HTTP request.",
+  "   * @param response - The outgoing HTTP response.",
+  "   * @param next - Calls the next policy in the chain.",
+  "   */",
+  "  (ctx: HttpContext, next: (request?: http.IncomingMessage) => void): void;",
+  "}",
+  "",
+  "/**",
+  " * Create a function from a chain of policies.",
+  " *",
+  " * This returns a single function that will apply the policy chain and eventually call the provided `next()` function.",
+  " *",
+  " * @param name - The name to give to the policy chain function.",
+  " * @param policies - The policies to apply to the request.",
+  " * @param out - The function to call after the policies have been applied.",
+  " */",
+  "export function createPolicyChain<Out extends (ctx: HttpContext, ...rest: any[]) => void>(",
+  "  name: string,",
+  "  policies: Policy[],",
+  "  out: Out,",
+  "): Out {",
+  "  let outParams: any[];",
+  "  if (policies.length === 0) {",
+  "    return out;",
+  "  }",
+  "",
+  "  function applyPolicy(ctx: HttpContext, index: number) {",
+  "    if (index >= policies.length) {",
+  "      return out(ctx, ...outParams);",
+  "    }",
+  "",
+  "    policies[index](ctx, function nextPolicy(nextRequest) {",
+  "      applyPolicy(",
+  "        {",
+  "          ...ctx,",
+  "          request: nextRequest ?? ctx.request,",
+  "        },",
+  "        index + 1,",
+  "      );",
+  "    });",
+  "  }",
+  "",
+  "  return {",
+  "    [name](ctx: HttpContext, ...params: any[]) {",
+  "      outParams = params;",
+  "      applyPolicy(ctx, 0);",
+  "    },",
+  "  }[name] as Out;",
+  "}",
+  "",
+  "/**",
+  " * The type of an error encountered during request validation.",
+  " */",
+  "export type ValidationError = string;",
+  "",
+  "/**",
+  " * An object specifying the policies for a given route configuration.",
+  " */",
+  "export type RoutePolicies<RouteConfig extends { [k: string]: object }> = {",
+  "  [Interface in keyof RouteConfig]?: {",
+  "    before?: Policy[];",
+  "    after?: Policy[];",
+  "    methodPolicies?: {",
+  "      [Method in keyof RouteConfig[Interface]]?: Policy[];",
+  "    };",
+  "  };",
+  "};",
+  "",
+  "/**",
+  " * Create a policy chain for a given route.",
+  " *",
+  " * This function calls `createPolicyChain` internally and orders the policies based on the route configuration.",
+  " *",
+  " * Interface-level `before` policies run first, then method-level policies, then Interface-level `after` policies.",
+  " *",
+  " * @param name - The name to give to the policy chain function.",
+  " * @param routePolicies - The policies to apply to the routes (part of the route configuration).",
+  " * @param interfaceName - The name of the interface that the route belongs to.",
+  " * @param methodName - The name of the method that the route corresponds to.",
+  " * @param out - The function to call after the policies have been applied.",
+  " */",
+  "export function createPolicyChainForRoute<",
+  "  RouteConfig extends { [k: string]: object },",
+  "  InterfaceName extends keyof RouteConfig,",
+  "  Out extends (ctx: HttpContext, ...rest: any[]) => void,",
+  ">(",
+  "  name: string,",
+  "  routePolicies: RoutePolicies<RouteConfig>,",
+  "  interfaceName: InterfaceName,",
+  "  methodName: keyof RouteConfig[InterfaceName],",
+  "  out: Out,",
+  "): Out {",
+  "  return createPolicyChain(",
+  "    name,",
+  "    [",
+  "      ...(routePolicies[interfaceName]?.before ?? []),",
+  "      ...(routePolicies[interfaceName]?.methodPolicies?.[methodName] ?? []),",
+  "      ...(routePolicies[interfaceName]?.after ?? []),",
+  "    ],",
+  "    out,",
+  "  );",
+  "}",
+  "",
+  "/**",
+  " * Options for configuring a router with additional functionality.",
+  " */",
+  "export interface RouterOptions<",
+  "  RouteConfig extends { [k: string]: object } = { [k: string]: object },",
+  "> {",
+  "  /**",
+  "   * The base path of the router.",
+  "   *",
+  "   * This should include any leading slashes, but not a trailing slash, and should not include any component",
+  "   * of the URL authority (e.g. the scheme, host, or port).",
+  "   *",
+  "   * Defaults to \"\".",
+  "   */",
+  "  basePath?: string;",
+  "",
+  "  /**",
+  "   * A list of policies to apply to all routes _before_ routing.",
+  "   *",
+  "   * Policies are applied in the order they are listed.",
+  "   *",
+  "   * By default, the policy list is empty.",
+  "   *",
+  "   * Policies _MUST_ call `next()` to pass the request to the next policy _OR_ call `response.end()` to terminate",
+  "   * the response and _MUST NOT_ do both.",
+  "   */",
+  "  policies?: Policy[];",
+  "",
+  "  /**",
+  "   * A record of policies that apply to specific routes.",
+  "   *",
+  "   * The policies are provided as a nested record where the keys are the business-logic interface names, and the values",
+  "   * are records of the method names in the given interface and the policies that apply to them.",
+  "   *",
+  "   * By default, no additional policies are applied to the routes.",
+  "   *",
+  "   * Policies _MUST_ call `next()` to pass the request to the next policy _OR_ call `response.end()` to terminate",
+  "   * the response and _MUST NOT_ do both.",
+  "   */",
+  "  routePolicies?: RoutePolicies<RouteConfig>;",
+  "",
+  "  /**",
+  "   * A handler for requests where the resource is not found.",
+  "   *",
+  "   * The router will call this function when no route matches the incoming request.",
+  "   *",
+  "   * If this handler is not provided, a 404 Not Found response with a text body will be returned.",
+  "   *",
+  "   * You _MUST_ call `response.end()` to terminate the response.",
+  "   *",
+  "   * This handler is unreachable when using the Express middleware, as it will forward non-matching requests to the",
+  "   * next middleware layer in the stack.",
+  "   *",
+  "   * @param ctx - The HTTP context for the request.",
+  "   */",
+  "  onRequestNotFound?: (ctx: HttpContext) => void;",
+  "",
+  "  /**",
+  "   * A handler for requests that fail to validate inputs.",
+  "   *",
+  "   * If this handler is not provided, a 400 Bad Request response with a JSON body containing some basic information",
+  "   * about the error will be returned to the client.",
+  "   *",
+  "   * You _MUST_ call `response.end()` to terminate the response.",
+  "   *",
+  "   * @param ctx - The HTTP context for the request.",
+  "   * @param route - The route that was matched.",
+  "   * @param error - The validation error that was thrown.",
+  "   */",
+  "  onInvalidRequest?: (ctx: HttpContext, route: string, error: ValidationError) => void;",
+  "",
+  "  /**",
+  "   * A handler for requests that throw an error during processing.",
+  "   *",
+  "   * If this handler is not provided, a 500 Internal Server Error response with a text body and no error details will be",
+  "   * returned to the client.",
+  "   *",
+  "   * You _MUST_ call `response.end()` to terminate the response.",
+  "   *",
+  "   * If this handler itself throws an Error, the router will respond with a 500 Internal Server Error",
+  "   *",
+  "   * @param ctx - The HTTP context for the request.",
+  "   * @param error - The error that was thrown.",
+  "   */",
+  "  onInternalError?(ctx: HttpContext, error: Error): void;",
+  "}",
+  "",
+  "/** Context information for operations carried over the HTTP protocol. */",
+  "export interface HttpContext {",
+  "  /** The incoming request to the server. */",
+  "  request: http.IncomingMessage;",
+  "  /** The outgoing response object. */",
+  "  response: http.ServerResponse;",
+  "",
+  "  /**",
+  "   * Error handling functions provided by the HTTP router. Service implementations may call these methods in case a",
+  "   * resource is not found, a request is invalid, or an internal error occurs.",
+  "   *",
+  "   * These methods will respond to the client with the appropriate status code and message.",
+  "   */",
+  "  errorHandlers: {",
+  "    /**",
+  "     * Signals that the requested resource was not found.",
+  "     */",
+  "    onRequestNotFound: Exclude<RouterOptions[\"onRequestNotFound\"], undefined>;",
+  "    /**",
+  "     * Signals that the request was invalid.",
+  "     */",
+  "    onInvalidRequest: Exclude<RouterOptions[\"onInvalidRequest\"], undefined>;",
+  "    /**",
+  "     * Signals that an internal error occurred.",
+  "     */",
+  "    onInternalError: Exclude<RouterOptions[\"onInternalError\"], undefined>;",
+  "  };",
+  "}",
+  "",
+];
+
+export async function createModule(parent: Module): Promise<Module> {
+  if (module) return module;
+
+  module = {
+    name: "router",
+    cursor: parent.cursor.enter("router"),
+    imports: [],
+    declarations: [],
+  };
+
+  module.declarations.push(lines);
+
+  parent.declarations.push(module);
+
+  return module;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@typespec/http-server-js",
+  "version": "0.58.0-alpha.10-dev.3",
+  "author": "Microsoft Corporation",
+  "description": "TypeSpec HTTP server code generator for JavaScript",
+  "homepage": "https://github.com/microsoft/typespec",
+  "readme": "https://github.com/microsoft/typespec/blob/main/packages/http-server-js/README.md",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/typespec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/microsoft/typespec/issues"
+  },
+  "keywords": [
+    "typespec",
+    "http",
+    "server",
+    "javascript",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "dist/src/index.js",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./testing": "./dist/src/testing/index.js"
+  },
+  "bin": {
+    "hsj-scaffold": "./dist/src/scripts/scaffold/bin.mjs"
+  },
+  "peerDependencies": {
+    "@typespec/compiler": "~0.65.3 || >=0.66.0-dev <0.66.0",
+    "@typespec/http": "~0.65.0 || >=0.66.0-dev <0.66.0",
+    "@typespec/openapi3": "~0.65.0 || >=0.66.0-dev <0.66.0"
+  },
+  "peerDependenciesMeta": {
+    "@typespec/openapi3": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "prettier": "~3.4.2",
+    "yaml": "~2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "~22.10.10",
+    "@typespec/compiler": "~0.65.3 || >=0.66.0-dev <0.66.0",
+    "@typespec/http": "~0.65.0 || >=0.66.0-dev <0.66.0",
+    "@typespec/openapi3": "~0.65.0 || >=0.66.0-dev <0.66.0",
+    "@vitest/coverage-v8": "^3.0.4",
+    "@vitest/ui": "^3.0.3",
+    "tsx": "^4.19.2",
+    "typescript": "~5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "clean": "rimraf ./dist ./temp",
+    "build": "npm run build:helpers && npm run build:src",
+    "build:src": "tsc -p ./tsconfig.json",
+    "build:helpers": "tsx ./build-helpers.ts",
+    "watch": "tsc -p . --watch",
+    "test": "vitest run",
+    "test:watch": "vitest -w",
+    "test:ui": "vitest --ui",
+    "test:ci": "vitest run --coverage --reporter=junit --reporter=default",
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix",
+    "regen-docs": "echo Doc generation disabled for this package."
+  }
+}

package/src/common/declaration.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { DeclarationType, JsContext, Module } from "../ctx.js";
+import { emitEnum } from "./enum.js";
+import { emitInterface } from "./interface.js";
+import { emitModel } from "./model.js";
+import { emitScalar } from "./scalar.js";
+import { emitUnion } from "./union.js";
+
+/**
+ * Emit a declaration for a module based on its type.
+ *
+ * The altName is optional and is only used for unnamed models and unions.
+ *
+ * @param ctx - The emitter context.
+ * @param type - The type to emit.
+ * @param module - The module that this declaration is written into.
+ * @param altName - An alternative name to use for the declaration if it is not named.
+ */
+export function* emitDeclaration(
+  ctx: JsContext,
+  type: DeclarationType,
+  module: Module,
+  altName?: string,
+): Iterable<string> {
+  switch (type.kind) {
+    case "Model": {
+      yield* emitModel(ctx, type, module, altName);
+      break;
+    }
+    case "Enum": {
+      yield* emitEnum(ctx, type);
+      break;
+    }
+    case "Union": {
+      yield* emitUnion(ctx, type, module, altName);
+      break;
+    }
+    case "Interface": {
+      yield* emitInterface(ctx, type, module);
+      break;
+    }
+    case "Scalar": {
+      yield emitScalar(ctx, type);
+      break;
+    }
+    default: {
+      throw new Error(`UNREACHABLE: Unhandled type kind: ${(type satisfies never as any).kind}`);
+    }
+  }
+}

package/src/common/documentation.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Type, getDoc } from "@typespec/compiler";
+import { JsContext } from "../ctx.js";
+import { indent } from "../util/iter.js";
+
+/**
+ * Emit the documentation for a type in JSDoc format.
+ *
+ * This assumes that the documentation may include Markdown formatting.
+ *
+ * @param ctx - The emitter context.
+ * @param type - The type to emit documentation for.
+ */
+export function* emitDocumentation(ctx: JsContext, type: Type): Iterable<string> {
+  const doc = getDoc(ctx.program, type);
+
+  if (doc === undefined) return;
+
+  yield `/**`;
+
+  yield* indent(doc.trim().split(/\r?\n/g), " * ");
+
+  yield ` */`;
+}