@apicircle/mock-server-core 1.0.9 → 1.1.0

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  MockServerStartError: () => MockServerStartError,
   buildRouter: () => buildRouter,
   createMockApp: () => createMockApp,
   getFreePort: () => getFreePort,
@@ -48,6 +49,7 @@ module.exports = __toCommonJS(index_exports);
 // src/parsers/openapi.ts
 var import_swagger_parser = __toESM(require("@apidevtools/swagger-parser"), 1);
 var import_js_yaml = __toESM(require("js-yaml"), 1);
+var import_shared2 = require("@apicircle/shared");
 
 // src/faker/schemaToExample.ts
 var FORMAT_DEFAULTS = {
@@ -110,6 +112,17 @@ function pickType(type) {
 }
 
 // src/parsers/buildEndpoint.ts
+var import_shared = require("@apicircle/shared");
+function paramDef(name, opts) {
+  return {
+    id: (0, import_shared.generateId)(),
+    name,
+    typeHint: opts?.typeHint,
+    required: opts?.required,
+    description: opts?.description,
+    example: opts?.example
+  };
+}
 function bodyTypeForContentType(contentType) {
   if (!contentType) return "json";
   const main = contentType.toLowerCase().split(";")[0]?.trim() ?? "";
@@ -150,7 +163,7 @@ function buildMockEndpoint(input) {
     method: input.method,
     pathPattern: input.pathPattern,
     description: input.description,
-    requestSchema: { pathParams: [], queryParams: [], headers: [], cookies: [] },
+    requestSchema: input.requestSchema ?? (0, import_shared.makeDefaultRequestSchema)(),
     requestValidation: [],
     responseRules: [],
     defaultResponse: buildMockResponse(input.response),
@@ -189,18 +202,64 @@ async function parseOpenApiToEndpoints(source, format = "json", opts = {}) {
   let endpointId = 0;
   for (const [path, ops] of Object.entries(paths)) {
     if (!ops || typeof ops !== "object") continue;
+    const pathItemParams = ops.parameters ?? [];
     for (const method of Object.keys(ops)) {
       const upper = method.toUpperCase();
       if (!SUPPORTED_METHODS.includes(upper)) continue;
       const op = ops[method];
       if (!op || typeof op !== "object") continue;
-      const built = buildEndpointFromOp(path, upper, op, opts, warnings, endpointId++);
+      const built = buildEndpointFromOp(
+        path,
+        upper,
+        op,
+        pathItemParams,
+        opts,
+        warnings,
+        endpointId++
+      );
       if (built) endpoints.push(built);
     }
   }
   return { endpoints, warnings };
 }
-function buildEndpointFromOp(path, method, op, opts, warnings, index) {
+function buildRequestSchema(pathItemParams, op) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const p of [...pathItemParams, ...op.parameters ?? []]) {
+    if (p && typeof p === "object" && typeof p.name === "string") {
+      merged.set(`${p.in ?? "query"}:${p.name}`, p);
+    }
+  }
+  const schema = (0, import_shared2.makeDefaultRequestSchema)();
+  for (const p of merged.values()) {
+    const rawType = p.schema?.type ?? p.type;
+    const typeHint = p.schema?.format ?? (Array.isArray(rawType) ? rawType[0] : rawType);
+    const exampleVal = p.example ?? p.schema?.example;
+    const def = paramDef(p.name, {
+      typeHint: typeof typeHint === "string" ? typeHint : void 0,
+      required: typeof p.required === "boolean" ? p.required : void 0,
+      description: typeof p.description === "string" ? p.description : void 0,
+      example: exampleVal === void 0 ? void 0 : typeof exampleVal === "string" ? exampleVal : JSON.stringify(exampleVal)
+    });
+    switch (p.in) {
+      case "path":
+        schema.pathParams.push(def);
+        break;
+      case "query":
+        schema.queryParams.push(def);
+        break;
+      case "header":
+        schema.headers.push(def);
+        break;
+      case "cookie":
+        schema.cookies.push(def);
+        break;
+      default:
+        break;
+    }
+  }
+  return schema;
+}
+function buildEndpointFromOp(path, method, op, pathItemParams, opts, warnings, index) {
   const responses = op.responses ?? {};
   const candidates = Object.keys(responses).filter((code) => /^2\d\d$/.test(code)).map((code) => Number(code));
   if (candidates.length === 0) {
@@ -220,6 +279,7 @@ function buildEndpointFromOp(path, method, op, opts, warnings, index) {
     method,
     pathPattern: path,
     example: exampleName,
+    requestSchema: buildRequestSchema(pathItemParams, op),
     response: { status, headers, body }
   });
 }
@@ -322,6 +382,26 @@ function safeYamlLoad(s) {
 }
 
 // src/parsers/postman.ts
+var import_shared3 = require("@apicircle/shared");
+function postmanRequestSchema(req) {
+  const schema = (0, import_shared3.makeDefaultRequestSchema)();
+  const url = req.url;
+  if (url && typeof url === "object") {
+    for (const v of url.variable ?? []) {
+      if (v?.key)
+        schema.pathParams.push(paramDef(v.key, { example: v.value, description: v.description }));
+    }
+    for (const q of url.query ?? []) {
+      if (q?.key && !q.disabled)
+        schema.queryParams.push(paramDef(q.key, { example: q.value, description: q.description }));
+    }
+  }
+  for (const h of req.header ?? []) {
+    if (h?.key && !h.disabled)
+      schema.headers.push(paramDef(h.key, { example: h.value, description: h.description }));
+  }
+  return schema;
+}
 var SUPPORTED_METHODS2 = [
   "GET",
   "POST",
@@ -353,6 +433,7 @@ function parsePostmanToEndpoints(source) {
       warnings.push(`Skipping request with no extractable path: ${item.name ?? "(unnamed)"}`);
       return;
     }
+    const requestSchema = postmanRequestSchema(item.request);
     const example = item.response?.[0];
     if (example) {
       endpoints.push(
@@ -362,6 +443,7 @@ function parsePostmanToEndpoints(source) {
           method,
           pathPattern: path,
           example: example.name,
+          requestSchema,
           response: {
             // Postman's `code` is the canonical numeric status; `status` is a
             // human-readable label that *sometimes* parses as a number. Try
@@ -379,6 +461,7 @@ function parsePostmanToEndpoints(source) {
           name: item.name,
           method,
           pathPattern: path,
+          requestSchema,
           response: {
             status: 200,
             headers: [{ key: "Content-Type", value: "application/json" }],
@@ -422,6 +505,26 @@ function slug2(s) {
 }
 
 // src/parsers/insomnia.ts
+var import_shared4 = require("@apicircle/shared");
+function extractPathSlots(path) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of path.matchAll(/[:{]([A-Za-z0-9_]+)\}?/g)) out.add(m[1]);
+  return [...out];
+}
+function insomniaRequestSchema(r, path) {
+  const schema = (0, import_shared4.makeDefaultRequestSchema)();
+  for (const slot of extractPathSlots(path))
+    schema.pathParams.push(paramDef(slot, { required: true }));
+  for (const p of r.parameters ?? []) {
+    if (p?.name && !p.disabled)
+      schema.queryParams.push(paramDef(p.name, { example: p.value, description: p.description }));
+  }
+  for (const h of r.headers ?? []) {
+    if (h?.name && !h.disabled)
+      schema.headers.push(paramDef(h.name, { example: h.value, description: h.description }));
+  }
+  return schema;
+}
 var SUPPORTED_METHODS3 = [
   "GET",
   "POST",
@@ -459,6 +562,7 @@ function parseInsomniaToEndpoints(source) {
         name: r.name,
         method,
         pathPattern: path,
+        requestSchema: insomniaRequestSchema(r, path),
         response: {
           status: 200,
           headers: [{ key: "Content-Type", value: "application/json" }],
@@ -658,12 +762,8 @@ function resolveJsonPath(body, jsonPath) {
   if (path.startsWith(".")) path = path.slice(1);
   if (path === "") return body;
   let cursor = body;
-  const re = /([^.[\]]+)|\[([^\]]+)\]/g;
-  let match;
-  while ((match = re.exec(path)) !== null) {
+  for (const key of iterJsonPathTokens(path)) {
     if (cursor === void 0 || cursor === null) return void 0;
-    const key = match[1] ?? match[2];
-    if (key === void 0) return void 0;
     if (Array.isArray(cursor)) {
       const idx = Number(key);
       if (!Number.isInteger(idx)) return void 0;
@@ -678,6 +778,32 @@ function resolveJsonPath(body, jsonPath) {
   }
   return cursor;
 }
+function* iterJsonPathTokens(path) {
+  let i = 0;
+  while (i < path.length) {
+    const ch = path[i];
+    if (ch === "." || ch === "]") {
+      i++;
+      continue;
+    }
+    if (ch === "[") {
+      const close = path.indexOf("]", i + 1);
+      if (close === -1) return;
+      const inner = path.slice(i + 1, close);
+      if (inner.length > 0) yield inner;
+      i = close + 1;
+      continue;
+    }
+    let j = i + 1;
+    while (j < path.length) {
+      const c = path[j];
+      if (c === "." || c === "[" || c === "]") break;
+      j++;
+    }
+    yield path.slice(i, j);
+    i = j;
+  }
+}
 
 // src/response/applyMultipliers.ts
 function applyMultipliers(response, ctx) {
@@ -754,21 +880,39 @@ function parsePathSegments(jsonPath) {
   if (path.startsWith(".")) path = path.slice(1);
   if (path === "") return [];
   const out = [];
-  const re = /([^.[\]]+)|\[([^\]]+)\]/g;
-  let match;
-  while ((match = re.exec(path)) !== null) {
-    if (match[1] !== void 0) {
-      if (FORBIDDEN_KEYS.has(match[1])) return [];
-      out.push({ kind: "key", name: match[1] });
-    } else if (match[2] !== void 0) {
-      const n = Number(match[2]);
-      if (Number.isInteger(n)) {
-        out.push({ kind: "index", idx: n });
-      } else {
-        if (FORBIDDEN_KEYS.has(match[2])) return [];
-        out.push({ kind: "key", name: match[2] });
+  let i = 0;
+  while (i < path.length) {
+    const ch = path[i];
+    if (ch === "." || ch === "]") {
+      i++;
+      continue;
+    }
+    if (ch === "[") {
+      const close = path.indexOf("]", i + 1);
+      if (close === -1) break;
+      const inner = path.slice(i + 1, close);
+      if (inner.length > 0) {
+        const n = Number(inner);
+        if (Number.isInteger(n)) {
+          out.push({ kind: "index", idx: n });
+        } else {
+          if (FORBIDDEN_KEYS.has(inner)) return [];
+          out.push({ kind: "key", name: inner });
+        }
       }
+      i = close + 1;
+      continue;
+    }
+    let j = i + 1;
+    while (j < path.length) {
+      const c = path[j];
+      if (c === "." || c === "[" || c === "]") break;
+      j++;
     }
+    const name = path.slice(i, j);
+    if (FORBIDDEN_KEYS.has(name)) return [];
+    out.push({ kind: "key", name });
+    i = j;
   }
   return out;
 }
@@ -965,7 +1109,23 @@ function defaultContentTypeFor(bodyType) {
   }
 }
 function openApiPathToHono(path) {
-  return path.replace(/\{([^}]+)\}/g, ":$1");
+  let out = "";
+  let i = 0;
+  while (i < path.length) {
+    if (path[i] === "{") {
+      const close = path.indexOf("}", i + 1);
+      if (close === -1) {
+        out += path.slice(i);
+        break;
+      }
+      out += ":" + path.slice(i + 1, close);
+      i = close + 1;
+    } else {
+      out += path[i];
+      i++;
+    }
+  }
+  return out;
 }
 
 // src/runtime/nodeAdapter.ts
@@ -1003,11 +1163,60 @@ async function isPortFree(port) {
 
 // src/runtime/nodeAdapter.ts
 var CLOSE_TIMEOUT_MS = 3e3;
+var MockServerStartError = class extends Error {
+  code;
+  port;
+  host;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "MockServerStartError";
+    this.code = opts.code;
+    this.port = opts.port;
+    this.host = opts.host;
+  }
+};
+function explainBindError(code, port, host) {
+  switch (code) {
+    case "EADDRINUSE":
+      return `Port ${port} on ${host} is already in use. Stop the other process or pick a different port.`;
+    case "EACCES":
+      return `Permission denied binding to port ${port} on ${host}. Ports below 1024 usually require elevated privileges \u2014 pick a port in 1024\u201365535.`;
+    case "EADDRNOTAVAIL":
+      return `Cannot bind to ${host}:${port} \u2014 that address is not available on this machine.`;
+    default:
+      return `Failed to bind ${host}:${port} (${code}).`;
+  }
+}
 async function serveOnNode(app, opts = {}) {
-  const port = opts.port && opts.port > 0 ? opts.port : await getFreePort();
   const host = opts.host ?? "127.0.0.1";
+  let port;
+  if (opts.port === void 0 || opts.port === 0) {
+    port = await getFreePort();
+  } else {
+    if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535) {
+      throw new MockServerStartError({
+        code: "INVALID_PORT",
+        port: opts.port,
+        host,
+        message: `Invalid port ${String(opts.port)} \u2014 must be an integer between 1 and 65535.`
+      });
+    }
+    port = opts.port;
+  }
   let server = null;
   await new Promise((resolve, reject) => {
+    const wrapError = (err) => {
+      const candidate = err && typeof err === "object" && "code" in err ? err.code : void 0;
+      const code = typeof candidate === "string" ? candidate : "UNKNOWN";
+      reject(
+        new MockServerStartError({
+          code,
+          port,
+          host,
+          message: explainBindError(code, port, host)
+        })
+      );
+    };
     try {
       server = (0, import_node_server.serve)(
         {
@@ -1017,9 +1226,9 @@ async function serveOnNode(app, opts = {}) {
         },
         () => resolve()
       );
-      server.on("error", reject);
+      server.on("error", wrapError);
     } catch (err) {
-      reject(err instanceof Error ? err : new Error(String(err)));
+      wrapError(err);
     }
   });
   return {
@@ -1075,6 +1284,7 @@ async function stopMockServer(handle) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MockServerStartError,
   buildRouter,
   createMockApp,
   getFreePort,