counterfact 2.6.0 → 2.7.0

package/dist/server/json-to-xml.js

@@ -50,5 +50,5 @@ export function jsonToXml(json, schema, keyName = "root") {
     if (typeof json === "object" && json !== null) {
         return objectToXml(json, schema, name);
     }
-    return `<${name}>${String(json)}</${name}>`;
+    return `<${name}>${xmlEscape(String(json))}</${name}>`;
 }

package/dist/server/koa-middleware.js

@@ -49,7 +49,7 @@ export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
             return await next();
         }
         const auth = getAuthObject(ctx);
-        const { body, headers, query } = ctx.request;
+        const { body, headers, query, rawBody } = ctx.request;
         const path = ctx.request.path.slice(routePrefix.length);
         const method = ctx.request.method;
         if (isProxyEnabledForPath(path, config) && proxyUrl) {
@@ -69,6 +69,7 @@ export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
             path,
             /* @ts-expect-error the value of a querystring item can be an array and we don't have a solution for that yet */
             query,
+            rawBody: method === "HEAD" || method === "GET" ? undefined : rawBody,
             req: { path: "", ...ctx.req },
         });
         ctx.body = response.body;
@@ -88,6 +89,11 @@ export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
                 }
             }
         }
+        if (response.appendedHeaders) {
+            for (const [key, value] of response.appendedHeaders) {
+                ctx.res.appendHeader(key, value);
+            }
+        }
         ctx.status = response.status ?? HTTP_STATUS_CODE_OK;
         return undefined;
     };

package/dist/server/load-openapi-document.js

@@ -0,0 +1,13 @@
+import { dereference } from "@apidevtools/json-schema-ref-parser";
+import createDebug from "debug";
+const debug = createDebug("counterfact:server:load-openapi-document");
+export async function loadOpenApiDocument(source) {
+    try {
+        return (await dereference(source));
+    }
+    catch (error) {
+        debug("could not load OpenAPI document from %s: %o", source, error);
+        const details = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not load the OpenAPI spec from "${source}".\n${details}`, { cause: error });
+    }
+}

package/dist/server/module-loader.js

@@ -17,17 +17,22 @@ export class ModuleLoader extends EventTarget {
     basePath;
     registry;
     watcher;
+    scenariosWatcher;
     contextRegistry;
+    scenariosPath;
+    scenarioRegistry;
     dependencyGraph = new ModuleDependencyGraph();
     fileDiscovery;
     uncachedImport = async function (moduleName) {
         throw new Error(`uncachedImport not set up; importing ${moduleName}`);
     };
-    constructor(basePath, registry, contextRegistry = new ContextRegistry()) {
+    constructor(basePath, registry, contextRegistry = new ContextRegistry(), scenariosPath, scenarioRegistry) {
         super();
         this.basePath = basePath.replaceAll("\\", "/");
         this.registry = registry;
         this.contextRegistry = contextRegistry;
+        this.scenariosPath = scenariosPath?.replaceAll("\\", "/");
+        this.scenarioRegistry = scenarioRegistry;
         this.fileDiscovery = new FileDiscovery(this.basePath);
     }
     async watch() {
@@ -37,7 +42,7 @@ export class ModuleLoader extends EventTarget {
                 return;
             const pathName = pathNameOriginal.replaceAll("\\", "/");
             if (pathName.includes("$.context") && eventName === "add") {
-                process.stdout.write(`\n\n!!! The file at ${pathName} needs a minor update.\n    See https://github.com/pmcelhaney/counterfact/blob/main/docs/context-change.md\n\n\n`);
+                process.stdout.write(`\n\n!!! The file at ${pathName} needs a minor update.\n    See https://github.com/pmcelhaney/counterfact/blob/main/docs/faq.md\n\n\n`);
                 return;
             }
             if (!["add", "change", "unlink"].includes(eventName)) {
@@ -50,6 +55,9 @@ export class ModuleLoader extends EventTarget {
             if (eventName === "unlink") {
                 this.registry.remove(url);
                 this.dispatchEvent(new Event("remove"));
+                if (this.isContextFile(pathName)) {
+                    this.contextRegistry.remove(unescapePathForWindows(parts.dir).replaceAll("\\", "/") || "/");
+                }
                 return;
             }
             const dependencies = this.dependencyGraph.dependentsOf(pathName);
@@ -59,13 +67,78 @@ export class ModuleLoader extends EventTarget {
             }
         });
         await once(this.watcher, "ready");
+        if (this.scenariosPath && this.scenarioRegistry) {
+            const JS_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
+            const scenariosPath = this.scenariosPath;
+            this.scenariosWatcher = watch(scenariosPath, CHOKIDAR_OPTIONS).on("all", (eventName, pathNameOriginal) => {
+                if (!JS_EXTENSIONS.some((ext) => pathNameOriginal.endsWith(`.${ext}`)))
+                    return;
+                if (!["add", "change", "unlink"].includes(eventName))
+                    return;
+                const pathName = pathNameOriginal.replaceAll("\\", "/");
+                if (eventName === "unlink") {
+                    const fileKey = this.scenarioFileKey(pathName);
+                    this.scenarioRegistry?.remove(fileKey);
+                    return;
+                }
+                void this.loadScenarioFile(pathName);
+            });
+            await once(this.scenariosWatcher, "ready");
+        }
     }
     async stopWatching() {
         await this.watcher?.close();
+        await this.scenariosWatcher?.close();
+    }
+    isContextFile(pathName) {
+        return basename(pathName).startsWith("_.context.");
     }
     async load(directory = "") {
         const files = await this.fileDiscovery.findFiles(directory);
         await Promise.all(files.map((file) => this.loadEndpoint(file)));
+        await this.loadScenarios();
+    }
+    shouldLoadScenarioFile(pathName) {
+        return !pathName.endsWith(".d.ts") && !pathName.endsWith(".map");
+    }
+    async loadScenarios() {
+        if (!this.scenariosPath || !this.scenarioRegistry)
+            return;
+        try {
+            const fileDiscovery = new FileDiscovery(this.scenariosPath);
+            const files = await fileDiscovery.findFiles();
+            const loadableFiles = files.filter((file) => this.shouldLoadScenarioFile(file));
+            await Promise.all(loadableFiles.map((file) => this.loadScenarioFile(file)));
+        }
+        catch {
+            // Scenarios directory does not exist yet — that's fine.
+        }
+    }
+    scenarioFileKey(pathName) {
+        const normalizedScenariosPath = (this.scenariosPath ?? "").replaceAll("\\", "/");
+        const directory = dirname(pathName.slice(normalizedScenariosPath.length)).replaceAll("\\", "/");
+        const name = nodePath.parse(basename(pathName)).name;
+        const url = unescapePathForWindows(`/${nodePath.join(directory, name)}`
+            .replaceAll("\\", "/")
+            .replaceAll(/\/+/gu, "/"));
+        return url.slice(1); // strip leading "/"
+    }
+    async loadScenarioFile(pathName) {
+        if (!this.scenariosPath || !this.scenarioRegistry)
+            return;
+        const fileKey = this.scenarioFileKey(pathName);
+        try {
+            const doImport = (await determineModuleKind(pathName)) === "commonjs"
+                ? uncachedRequire
+                : uncachedImport;
+            const module = await doImport(pathName);
+            if (module) {
+                this.scenarioRegistry.add(fileKey, module);
+            }
+        }
+        catch (error) {
+            process.stdout.write(`\nError loading scenario ${pathName}:\n${String(error)}\n`);
+        }
     }
     async loadEndpoint(pathName) {
         debug("importing module: %s", pathName);
@@ -113,8 +186,7 @@ export class ModuleLoader extends EventTarget {
                 return;
             }
             this.dispatchEvent(new Event("add"));
-            if (basename(pathName).startsWith("_.context.") &&
-                isContextModule(endpoint)) {
+            if (this.isContextFile(pathName) && isContextModule(endpoint)) {
                 const loadContext = (path) => this.contextRegistry.find(path);
                 const contextDir = nodePath.dirname(unescapePathForWindows(pathName));
                 const readJson = async (relativePath) => {

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/request-validator.js

@@ -1,7 +1,7 @@
 import Ajv from "ajv";
 const ajv = new Ajv({
     allErrors: true,
-    unknownFormats: "ignore",
+    strict: false,
     coerceTypes: false,
 });
 function findMissingRequired(parameters, location, values) {
@@ -30,9 +30,7 @@ export function validateRequest(operation, request) {
             const valid = ajv.validate(schema, request.body);
             if (!valid && ajv.errors) {
                 for (const error of ajv.errors) {
-                    const path = error.instancePath ??
-                        error.dataPath ??
-                        "";
+                    const path = error.instancePath ?? "";
                     errors.push(`body${path} ${error.message ?? "is invalid"}`);
                 }
             }
@@ -47,9 +45,7 @@ export function validateRequest(operation, request) {
         const valid = ajv.validate(bodyParam.schema, request.body);
         if (!valid && ajv.errors) {
             for (const error of ajv.errors) {
-                const path = error.instancePath ??
-                    error.dataPath ??
-                    "";
+                const path = error.instancePath ?? "";
                 errors.push(`body${path} ${error.message ?? "is invalid"}`);
             }
         }

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/typescript-generator/coder.js

@@ -1,3 +1,4 @@
+import { RESERVED_WORDS } from "./reserved-words.js";
 export class Coder {
     requirement;
     constructor(requirement) {
@@ -35,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/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 ($) => {

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

@@ -4,59 +4,11 @@ import { buildJsDoc } from "./jsdoc.js";
 import { ParameterExportTypeCoder } from "./parameter-export-type-coder.js";
 import { ParametersTypeCoder } from "./parameters-type-coder.js";
 import { READ_ONLY_COMMENTS } from "./read-only-comments.js";
+import { RESERVED_WORDS } from "./reserved-words.js";
 import { ResponsesTypeCoder } from "./responses-type-coder.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
-const RESERVED_WORDS = new Set([
-    "break",
-    "case",
-    "catch",
-    "class",
-    "const",
-    "continue",
-    "debugger",
-    "default",
-    "delete",
-    "do",
-    "else",
-    "export",
-    "extends",
-    "false",
-    "finally",
-    "for",
-    "function",
-    "if",
-    "import",
-    "in",
-    "instanceof",
-    "new",
-    "null",
-    "return",
-    "static",
-    "super",
-    "switch",
-    "this",
-    "throw",
-    "true",
-    "try",
-    "typeof",
-    "var",
-    "void",
-    "while",
-    "with",
-    "yield",
-    "await",
-    "enum",
-    "implements",
-    "interface",
-    "let",
-    "package",
-    "private",
-    "protected",
-    "public",
-    "type",
-]);
 function sanitizeIdentifier(value) {
     // Treat any run of non-identifier characters as a camelCase separator
     let result = value.replaceAll(/[^\w$]+(?<next>.)/gu, (_, char) => char.toUpperCase());

package/dist/typescript-generator/read-only-comments.js

@@ -1,5 +1,5 @@
 export const READ_ONLY_COMMENTS = [
     "This code was automatically generated from an OpenAPI description.",
     "Do not edit this file. Edit the OpenAPI file instead.",
-    "For more information, see https://github.com/pmcelhaney/counterfact/blob/main/docs/faq-generated-code.md",
+    "For more information, see https://github.com/pmcelhaney/counterfact/blob/main/docs/faq.md",
 ];

package/dist/typescript-generator/requirement.js

@@ -36,7 +36,14 @@ export class Requirement {
             // Unescape URL encoded characters (e.g. %20 -> " ")
             // Technically we should not be unescaping, but it came up in https://github.com/pmcelhaney/counterfact/issues/1083
             // and I can't think of a reason anyone would intentionally put a % in a key name.
-            .map(unescape);
+            .map((part) => {
+            try {
+                return decodeURIComponent(part);
+            }
+            catch {
+                return part;
+            }
+        });
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         let result = this;
         for (const part of parts) {