counterfact 2.5.1 → 2.7.0

package/dist/server/module-tree.js

@@ -3,8 +3,8 @@ function isDirectory(test) {
 }
 export class ModuleTree {
     root = {
-        directories: {},
-        files: {},
+        directories: new Map(),
+        files: new Map(),
         isWildcard: false,
         name: "",
         rawName: "",
@@ -17,16 +17,19 @@ export class ModuleTree {
         if (remainingSegments.length === 0) {
             return directory;
         }
-        const isNewDirectory = directory.directories[segment.toLowerCase()] === undefined;
-        const nextDirectory = (directory.directories[segment.toLowerCase()] ??= {
-            directories: {},
-            files: {},
-            isWildcard: segment.startsWith("{"),
-            name: segment.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
-            rawName: segment,
-        });
+        const isNewDirectory = !directory.directories.has(segment.toLowerCase());
+        if (isNewDirectory) {
+            directory.directories.set(segment.toLowerCase(), {
+                directories: new Map(),
+                files: new Map(),
+                isWildcard: segment.startsWith("{"),
+                name: segment.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
+                rawName: segment,
+            });
+        }
+        const nextDirectory = directory.directories.get(segment.toLowerCase());
         if (isNewDirectory && segment.startsWith("{")) {
-            const ambiguousWildcardDirectories = Object.values(directory.directories).filter((subdirectory) => subdirectory.isWildcard);
+            const ambiguousWildcardDirectories = Array.from(directory.directories.values()).filter((subdirectory) => subdirectory.isWildcard);
             if (ambiguousWildcardDirectories.length > 1) {
                 process.stderr.write(`[counterfact] ERROR: Ambiguous wildcard paths detected. Multiple wildcard directories exist at the same level: ${ambiguousWildcardDirectories.map((d) => d.rawName).join(", ")}. Requests may be routed unpredictably.\n`);
             }
@@ -42,14 +45,14 @@ export class ModuleTree {
         if (filename === undefined) {
             throw new Error("The file name (the last segment of the URL) is undefined. This is theoretically impossible but TypeScript can't enforce it.");
         }
-        targetDirectory.files[filename] = {
+        targetDirectory.files.set(filename, {
             isWildcard: filename.startsWith("{"),
             module,
             name: filename.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
             rawName: filename,
-        };
+        });
         if (filename.startsWith("{")) {
-            const ambiguousWildcardFiles = Object.values(targetDirectory.files).filter((file) => file.isWildcard);
+            const ambiguousWildcardFiles = Array.from(targetDirectory.files.values()).filter((file) => file.isWildcard);
             if (ambiguousWildcardFiles.length > 1) {
                 process.stderr.write(`[counterfact] ERROR: Ambiguous wildcard paths detected. Multiple wildcard files exist at the same path level: ${ambiguousWildcardFiles.map((f) => f.rawName).join(", ")}. Requests may be routed unpredictably.\n`);
             }
@@ -67,10 +70,10 @@ export class ModuleTree {
             return;
         }
         if (remainingSegments.length === 0) {
-            delete directory.files[segment.toLowerCase()];
+            directory.files.delete(segment.toLowerCase());
             return;
         }
-        this.removeModuleFromDirectory(directory.directories[segment.toLowerCase()], remainingSegments);
+        this.removeModuleFromDirectory(directory.directories.get(segment.toLowerCase()), remainingSegments);
     }
     remove(url) {
         const segments = url.split("/").slice(1);
@@ -81,14 +84,14 @@ export class ModuleTree {
     }
     buildMatch(directory, segment, pathVariables, matchedPath, method) {
         function normalizedSegment(segment, directory) {
-            for (const file in directory.files) {
+            for (const file of directory.files.keys()) {
                 if (file.toLowerCase() === segment.toLowerCase()) {
                     return file;
                 }
             }
             return "";
         }
-        const exactMatchFile = directory.files[normalizedSegment(segment, directory)];
+        const exactMatchFile = directory.files.get(normalizedSegment(segment, directory));
         // If the URL segment literally matches a file key (e.g., requesting "/{x}"
         // as a literal URL value), exactMatchFile may be a wildcard file. In that
         // case, fall through to wildcard matching below.
@@ -99,7 +102,7 @@ export class ModuleTree {
                 pathVariables,
             };
         }
-        const wildcardFiles = Object.values(directory.files).filter((file) => file.isWildcard && this.fileModuleDefined(file, method));
+        const wildcardFiles = Array.from(directory.files.values()).filter((file) => file.isWildcard && this.fileModuleDefined(file, method));
         if (wildcardFiles.length > 1) {
             const firstWildcard = wildcardFiles[0];
             return {
@@ -144,11 +147,11 @@ export class ModuleTree {
             (remainingSegments.length === 1 && remainingSegments[0] === "")) {
             return this.buildMatch(directory, segment, pathVariables, matchedPath, method);
         }
-        const exactMatch = directory.directories[segment.toLowerCase()];
+        const exactMatch = directory.directories.get(segment.toLowerCase());
         if (isDirectory(exactMatch)) {
             return this.matchWithinDirectory(exactMatch, remainingSegments, pathVariables, `${matchedPath}/${segment}`, method);
         }
-        const wildcardDirectories = Object.values(directory.directories).filter((subdirectory) => subdirectory.isWildcard);
+        const wildcardDirectories = Array.from(directory.directories.values()).filter((subdirectory) => subdirectory.isWildcard);
         const wildcardMatches = [];
         for (const wildcardDirectory of wildcardDirectories) {
             const wildcardMatch = this.matchWithinDirectory(wildcardDirectory, remainingSegments, {
@@ -171,10 +174,10 @@ export class ModuleTree {
     get routes() {
         const routes = [];
         function traverse(directory, path) {
-            Object.values(directory.directories).forEach((subdirectory) => {
+            directory.directories.forEach((subdirectory) => {
                 traverse(subdirectory, `${path}/${subdirectory.rawName}`);
             });
-            Object.values(directory.files).forEach((file) => {
+            directory.files.forEach((file) => {
                 const methods = Object.entries(file.module).map(([method, implementation]) => [method, String(implementation)]);
                 routes.push({
                     methods: Object.fromEntries(methods),

package/dist/server/openapi-middleware.js

@@ -1,5 +1,5 @@
 import { bundle } from "@apidevtools/json-schema-ref-parser";
-import yaml from "js-yaml";
+import { dump } from "js-yaml";
 export function openapiMiddleware(openApiPath, url) {
     return async (ctx, next) => {
         if (ctx.URL.pathname === "/counterfact/openapi") {
@@ -11,7 +11,7 @@ export function openapiMiddleware(openApiPath, url) {
             });
             // OpenApi 2 support:
             openApiDocument.host = url;
-            ctx.body = yaml.dump(openApiDocument);
+            ctx.body = dump(openApiDocument);
             return;
         }
         await next();

package/dist/server/openapi-watcher.js

@@ -0,0 +1,35 @@
+import { watch } from "chokidar";
+import createDebug from "debug";
+import { waitForEvent } from "../util/wait-for-event.js";
+import { CHOKIDAR_OPTIONS } from "./constants.js";
+import { loadOpenApiDocument } from "./load-openapi-document.js";
+const debug = createDebug("counterfact:server:openapi-watcher");
+export class OpenApiWatcher {
+    openApiPath;
+    dispatcher;
+    watcher;
+    constructor(openApiPath, dispatcher) {
+        this.openApiPath = openApiPath;
+        this.dispatcher = dispatcher;
+    }
+    async watch() {
+        if (this.openApiPath === "_" || this.openApiPath.startsWith("http")) {
+            return;
+        }
+        this.watcher = watch(this.openApiPath, CHOKIDAR_OPTIONS).on("change", () => {
+            void (async () => {
+                try {
+                    this.dispatcher.openApiDocument = await loadOpenApiDocument(this.openApiPath);
+                    debug("reloaded OpenAPI document from %s", this.openApiPath);
+                }
+                catch (error) {
+                    debug("failed to reload OpenAPI document from %s: %o", this.openApiPath, error);
+                }
+            })();
+        });
+        await waitForEvent(this.watcher, "ready");
+    }
+    async stopWatching() {
+        await this.watcher?.close();
+    }
+}

package/dist/server/registry.js

@@ -26,10 +26,10 @@ function castParameter(value, type) {
     }
     return value;
 }
-function castParameters(parameters = {}, parameterTypes = {}) {
+function castParameters(parameters = {}, parameterTypes = new Map()) {
     const copy = {};
     Object.entries(parameters).forEach(([key, value]) => {
-        copy[key] = castParameter(value, parameterTypes?.[key] ?? "string");
+        copy[key] = castParameter(value, parameterTypes.get(key) ?? "string");
     });
     return copy;
 }

package/dist/server/request-validator.js

@@ -0,0 +1,57 @@
+import Ajv from "ajv";
+const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    coerceTypes: false,
+});
+function findMissingRequired(parameters, location, values) {
+    return parameters
+        .filter((p) => p.in === location && p.required === true)
+        .filter((p) => !(p.name in values) || values[p.name] === undefined)
+        .map((p) => `${location} parameter '${p.name}' is required`);
+}
+export function validateRequest(operation, request) {
+    if (!operation) {
+        return { errors: [], valid: true };
+    }
+    const errors = [];
+    const parameters = operation.parameters ?? [];
+    // For query and header parameters, HTTP always delivers values as strings.
+    // Only check that required parameters are present; type coercion is handled
+    // by the registry before the route handler is called.
+    errors.push(...findMissingRequired(parameters, "query", request.query));
+    errors.push(...findMissingRequired(parameters, "header", request.headers));
+    // Validate request body (OpenAPI 3.x requestBody)
+    if (operation.requestBody?.content !== undefined) {
+        const schema = operation.requestBody.content["application/json"]?.schema ??
+            operation.requestBody.content["application/x-www-form-urlencoded"]
+                ?.schema;
+        if (schema !== undefined) {
+            const valid = ajv.validate(schema, request.body);
+            if (!valid && ajv.errors) {
+                for (const error of ajv.errors) {
+                    const path = error.instancePath ?? "";
+                    errors.push(`body${path} ${error.message ?? "is invalid"}`);
+                }
+            }
+        }
+        else if (operation.requestBody.required === true && !request.body) {
+            errors.push("body is required");
+        }
+    }
+    // Validate request body (OpenAPI 2.x body parameter)
+    const bodyParam = parameters.find((p) => p.in === "body");
+    if (bodyParam?.schema !== undefined) {
+        const valid = ajv.validate(bodyParam.schema, request.body);
+        if (!valid && ajv.errors) {
+            for (const error of ajv.errors) {
+                const path = error.instancePath ?? "";
+                errors.push(`body${path} ${error.message ?? "is invalid"}`);
+            }
+        }
+    }
+    return {
+        errors,
+        valid: errors.length === 0,
+    };
+}

package/dist/server/response-builder.js

@@ -112,6 +112,9 @@ export function createResponseBuilder(operation, config) {
                     ],
                 };
             },
+            empty() {
+                return { ...this, content: undefined };
+            },
             example(name) {
                 if (operation.produces) {
                     return unknownStatusCodeResponse(this.status);

package/dist/server/response-validator.js

@@ -0,0 +1,58 @@
+import Ajv from "ajv";
+const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    coerceTypes: false,
+});
+export function validateResponse(operation, response) {
+    if (!operation) {
+        return { errors: [], valid: true };
+    }
+    const errors = [];
+    const statusKey = response.status !== undefined ? String(response.status) : undefined;
+    const responseSpec = (statusKey !== undefined ? operation.responses[statusKey] : undefined) ??
+        operation.responses.default;
+    if (!responseSpec) {
+        return { errors: [], valid: true };
+    }
+    const specHeaders = responseSpec.headers ?? {};
+    const actualHeaders = response.headers ?? {};
+    for (const [name, headerSpec] of Object.entries(specHeaders)) {
+        const actualValue = actualHeaders[name] ?? actualHeaders[name.toLowerCase()];
+        if (headerSpec.required === true && actualValue === undefined) {
+            errors.push(`response header '${name}' is required`);
+            continue;
+        }
+        if (actualValue !== undefined && headerSpec.schema !== undefined) {
+            const coercedValue = typeof actualValue === "string"
+                ? coerceHeaderValue(actualValue, headerSpec.schema)
+                : actualValue;
+            const valid = ajv.validate(headerSpec.schema, coercedValue);
+            if (!valid && ajv.errors) {
+                for (const error of ajv.errors) {
+                    const path = error.instancePath ?? "";
+                    errors.push(`response header '${name}'${path} ${error.message ?? "is invalid"}`);
+                }
+            }
+        }
+    }
+    return {
+        errors,
+        valid: errors.length === 0,
+    };
+}
+function coerceHeaderValue(value, schema) {
+    const type = schema.type;
+    if (type === "integer" || type === "number") {
+        const num = Number(value);
+        return Number.isNaN(num) ? value : num;
+    }
+    if (type === "boolean") {
+        if (value === "true")
+            return true;
+        if (value === "false")
+            return false;
+        return value;
+    }
+    return value;
+}

package/dist/server/scenario-registry.js

@@ -0,0 +1,29 @@
+export class ScenarioRegistry {
+    modules = new Map();
+    add(key, module) {
+        this.modules.set(key, module);
+    }
+    remove(key) {
+        this.modules.delete(key);
+    }
+    getModule(fileKey) {
+        return this.modules.get(fileKey);
+    }
+    /**
+     * Returns the names of all exported functions for the given file key.
+     * Used for tab completion.
+     */
+    getExportedFunctionNames(fileKey) {
+        const module = this.modules.get(fileKey);
+        if (!module)
+            return [];
+        return Object.keys(module).filter((k) => typeof module[k] === "function");
+    }
+    /**
+     * Returns all loaded file keys (e.g. "index", "myscript", "sub/script").
+     * Used for tab completion to enumerate available scenario files.
+     */
+    getFileKeys() {
+        return [...this.modules.keys()];
+    }
+}

package/dist/server/tools.js

@@ -8,13 +8,13 @@ export class Tools {
         return array[Math.floor(Math.random() * array.length)];
     }
     accepts(contentType) {
-        const acceptHeader = this.headers.Accept;
+        const acceptHeader = Object.entries(this.headers).find(([key]) => key.toLowerCase() === "accept")?.[1];
         if (acceptHeader === "" || acceptHeader === undefined) {
             return true;
         }
         const acceptTypes = String(acceptHeader).split(",");
         return acceptTypes.some((acceptType) => {
-            const [type, subtype] = acceptType.split("/");
+            const [type, subtype] = acceptType.trim().split("/");
             return ((type === "*" || type === contentType.split("/")[0]) &&
                 (subtype === "*" || subtype === contentType.split("/")[1]));
         });

package/dist/server/transpiler.js

@@ -67,12 +67,20 @@ export class Transpiler extends EventTarget {
     async transpileFile(eventName, sourcePath, destinationPath) {
         ensureDirectoryExists(destinationPath);
         const source = await fs.readFile(sourcePath, "utf8");
-        const result = ts.transpileModule(source, {
+        const transpileOutput = ts.transpileModule(source, {
             compilerOptions: {
                 module: ts.ModuleKind[this.moduleKind.toLowerCase() === "module" ? "ES2022" : "CommonJS"],
                 target: ts.ScriptTarget.ES2015,
             },
-        }).outputText;
+            reportDiagnostics: true,
+        });
+        if (transpileOutput.diagnostics?.length) {
+            for (const diagnostic of transpileOutput.diagnostics) {
+                const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+                debug("TypeScript diagnostic in %s: %s", sourcePath, message);
+            }
+        }
+        const result = transpileOutput.outputText;
         const fullDestination = nodePath
             .join(sourcePath
             .replace(this.sourcePath, this.destinationPath)
@@ -82,10 +90,10 @@ export class Transpiler extends EventTarget {
         try {
             await fs.writeFile(fullDestination, resultWithTransformedFileExtensions);
         }
-        catch {
-            debug("error transpiling %s", fullDestination);
+        catch (error) {
+            debug("error writing transpiled output to %s: %o", fullDestination, error);
             this.dispatchEvent(new Event("error"));
-            throw new Error("could not transpile");
+            throw new Error("could not transpile", { cause: error });
         }
         this.dispatchEvent(new Event("write"));
     }

package/dist/typescript-generator/coder.js

@@ -1,3 +1,4 @@
+import { RESERVED_WORDS } from "./reserved-words.js";
 export class Coder {
     requirement;
     constructor(requirement) {
@@ -12,6 +13,9 @@ export class Coder {
     beforeExport(_path) {
         return "";
     }
+    jsdoc() {
+        return "";
+    }
     write(script) {
         if (this.requirement.isReference) {
             return script.import(this);
@@ -32,12 +36,13 @@ export class Coder {
         const name = rawName
             .replace(/^\d/u, (digit) => `_${digit}`)
             .replaceAll(/[^\w$]/gu, "_");
-        yield name;
+        const baseName = RESERVED_WORDS.has(name) ? `${name}_` : name;
+        yield baseName;
         let index = 1;
         const MAX_NAMES_TO_GENERATE_BEFORE_GIVING_UP = 100;
         while (index < MAX_NAMES_TO_GENERATE_BEFORE_GIVING_UP) {
             index += 1;
-            yield name + index;
+            yield baseName + index;
         }
     }
     typeDeclaration(_namespace, _script) {

package/dist/typescript-generator/generate.js

@@ -60,4 +60,159 @@ export async function generate(source, destination, generateOptions, repository
     debug("telling the repository to write the files to %s", destination);
     await repository.writeFiles(destination, generateOptions);
     debug("finished writing the files");
+    if (generateOptions.types) {
+        await writeApplyContextType(destination);
+        await writeDefaultScenariosIndex(destination);
+    }
+}
+async function collectContextFiles(destination) {
+    const routesDir = nodePath.join(destination, "routes");
+    const results = [];
+    if (!existsSync(routesDir)) {
+        return results;
+    }
+    await walkForContextFiles(routesDir, routesDir, results);
+    results.sort((a, b) => b.depth - a.depth);
+    return results;
+}
+async function walkForContextFiles(routesDir, currentDir, results) {
+    let entries;
+    try {
+        entries = await fs.readdir(currentDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            await walkForContextFiles(routesDir, nodePath.join(currentDir, entry.name), results);
+        }
+        else if (entry.name === "_.context.ts") {
+            const relDir = nodePath
+                .relative(routesDir, currentDir)
+                .replaceAll("\\", "/");
+            const routePath = relDir === "" ? "/" : `/${relDir}`;
+            const depth = relDir === "" ? 0 : relDir.split("/").length;
+            const importPath = relDir === "" ? "../routes/_.context" : `../routes/${relDir}/_.context`;
+            const alias = routePathToAlias(routePath);
+            results.push({ importPath, alias, routePath, depth });
+        }
+    }
+}
+function routePathToAlias(routePath) {
+    if (routePath === "/") {
+        return "Context";
+    }
+    return (routePath
+        .split("/")
+        .filter(Boolean)
+        .map((seg) => seg
+        .replace(/\{(.+?)\}/g, (_match, name) => name.replace(/[^a-z0-9]/gi, " "))
+        .replace(/[-_\s]([a-z])/g, (_match, c) => c.toUpperCase())
+        .replace(/^[a-z]/, (c) => c.toUpperCase())
+        .replace(/[^a-z0-9]/gi, ""))
+        .join("") + "Context");
+}
+const PARAM_SEGMENT_REGEX = /^\{.+\}$/u;
+function buildLoadContextOverload(routePath, alias) {
+    if (routePath === "/") {
+        return '  loadContext(path: "/" | `/${string}`): ' + alias + ";";
+    }
+    const segments = routePath.split("/").filter(Boolean);
+    const hasParam = segments.some((seg) => PARAM_SEGMENT_REGEX.test(seg));
+    if (!hasParam) {
+        return `  loadContext(path: "${routePath}" | \`${routePath}/\${string}\`): ${alias};`;
+    }
+    const templatePath = `/${segments
+        .map((seg) => (PARAM_SEGMENT_REGEX.test(seg) ? "${string}" : seg))
+        .join("/")}`;
+    return `  loadContext(path: \`${templatePath}\`): ${alias};`;
+}
+function buildApplyContextContent(contextFiles) {
+    const rootContext = contextFiles.find((f) => f.routePath === "/");
+    const contextType = rootContext
+        ? rootContext.alias
+        : "Record<string, unknown>";
+    const importLines = contextFiles.map(({ importPath, alias }) => alias === "Context"
+        ? `import type { Context } from "${importPath}";`
+        : `import type { Context as ${alias} } from "${importPath}";`);
+    const overloadLines = contextFiles.map(({ alias, routePath }) => buildLoadContextOverload(routePath, alias));
+    const parts = [
+        "// This file is generated by Counterfact. Do not edit manually.",
+        ...importLines,
+        "",
+        "export interface ApplyContext {",
+        '  /** Root context, same as loadContext("/") */',
+        `  context: ${contextType};`,
+        "  /** Load a context object for a specific path */",
+        ...overloadLines,
+        "  loadContext(path: string): Record<string, unknown>;",
+        "  /** Named route builders stored in the REPL execution context */",
+        "  routes: Record<string, unknown>;",
+        "  /** Create a new route builder for a given path */",
+        "  route: (path: string) => unknown;",
+        "}",
+        "",
+        "/** A scenario function that receives the live REPL environment */",
+        "export type Scenario = ($: ApplyContext) => Promise<void> | void;",
+        "",
+    ];
+    return parts.join("\n");
+}
+export async function writeApplyContextType(destination) {
+    const typesDir = nodePath.join(destination, "types");
+    const filePath = nodePath.join(typesDir, "scenario-context.ts");
+    const contextFiles = await collectContextFiles(destination);
+    const content = buildApplyContextContent(contextFiles);
+    await fs.mkdir(typesDir, { recursive: true });
+    await fs.writeFile(filePath, content, "utf8");
+}
+const DEFAULT_SCENARIOS_INDEX = `import type { Scenario } from "../types/scenario-context.js";
+
+/**
+ * Scenario scripts are plain TypeScript functions that receive the live REPL
+ * environment and can read or mutate server state. Run them from the REPL with:
+ *   .apply <functionName>
+ */
+
+/**
+ * Read or mutate the root context (same object routes see as $.context):
+ *   $.context.<property> = <value>;
+ *
+ * Load a context for a specific path:
+ *   const petsCtx = $.loadContext("/pets");
+ *
+ * Store a pre-configured route builder for later use in the REPL:
+ *   $.routes.myRequest = $.route("/pets").method("get");
+ */
+
+/**
+ * An example scenario. To use it in the REPL, type:
+ *   .apply help
+ */
+export const help: Scenario = ($) => {
+  void $;
+
+  console.log(
+    [
+      "Scenarios are functions that populate the context object",
+      "and / or the REPL environment. They are intended to",
+      "populate your environment with specific data and",
+      "configurations for testing purposes.",
+    ].join("\\n"),
+  );
+
+  console.log(
+    "\\nScenarios (including this one) are defined in the ./scenarios directory.",
+  );
+};
+`;
+async function writeDefaultScenariosIndex(destination) {
+    const scenariosDir = nodePath.join(destination, "scenarios");
+    const filePath = nodePath.join(scenariosDir, "index.ts");
+    if (existsSync(filePath)) {
+        return;
+    }
+    await fs.mkdir(scenariosDir, { recursive: true });
+    await fs.writeFile(filePath, DEFAULT_SCENARIOS_INDEX, "utf8");
 }

package/dist/typescript-generator/jsdoc.js

@@ -0,0 +1,45 @@
+/**
+ * Builds a JSDoc comment string from OpenAPI schema metadata.
+ * Returns an empty string if there is no relevant metadata.
+ */
+export function buildJsDoc(data) {
+    const lines = [];
+    const description = data["description"];
+    const summary = data["summary"];
+    const example = data["example"];
+    const examples = data["examples"];
+    const defaultValue = data["default"];
+    const format = data["format"];
+    const deprecated = data["deprecated"];
+    const mainText = description ?? summary;
+    if (mainText) {
+        // Escape */ to prevent prematurely closing the JSDoc block
+        const escaped = String(mainText).replace(/\*\//gu, "* /");
+        const textLines = escaped.split("\n");
+        for (const line of textLines) {
+            lines.push(` * ${line}`);
+        }
+    }
+    if (format !== undefined) {
+        lines.push(` * @format ${format}`);
+    }
+    if (defaultValue !== undefined) {
+        lines.push(` * @default ${JSON.stringify(defaultValue)}`);
+    }
+    // Use scalar `example`, or fall back to the first value from `examples`
+    const exampleValue = example !== undefined
+        ? example
+        : examples !== undefined
+            ? Object.values(examples)[0]?.value
+            : undefined;
+    if (exampleValue !== undefined) {
+        lines.push(` * @example ${JSON.stringify(exampleValue)}`);
+    }
+    if (deprecated === true) {
+        lines.push(` * @deprecated`);
+    }
+    if (lines.length === 0) {
+        return "";
+    }
+    return `/**\n${lines.join("\n")}\n */\n`;
+}

package/dist/typescript-generator/operation-coder.js

@@ -22,7 +22,7 @@ export class OperationCoder extends Coder {
         if (firstResponse === undefined ||
             !("content" in firstResponse || "schema" in firstResponse)) {
             return `async ($) => {
-        return $.response[${firstStatusCode === "default" ? 200 : firstStatusCode}];
+        return $.response[${firstStatusCode === "default" ? 200 : firstStatusCode}].empty();
       }`;
         }
         return `async ($) => {