nuxt-api-contract 0.1.0 → 0.3.0

package/dist/testing.mjs

@@ -1,8 +1,72 @@
-import { A as ApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
-import { v as validateContractInput, a as validateContractResponse } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import { l as listRegisteredContracts, A as ApiError, B as BUILT_IN_ERROR_CODES } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
+import { v as validateContractInput, a as validateContractResponse } from './shared/nuxt-api-contract.CAIOgncy.mjs';
 import 'zod';
 import './shared/nuxt-api-contract.DCAU2j7t.mjs';
 
+const state = { active: false, entries: /* @__PURE__ */ new Map() };
+function entryKey(contract) {
+  return contract.name ?? `${contract.method} ${contract.path}`;
+}
+function startContractCoverage() {
+  state.active = true;
+  state.entries.clear();
+}
+function stopContractCoverage() {
+  state.active = false;
+  return getContractCoverage();
+}
+function resetContractCoverage() {
+  state.entries.clear();
+}
+function recordCoverageCall(contract, success) {
+  if (!state.active) return;
+  const key = entryKey(contract);
+  const entry = state.entries.get(key) ?? {
+    key,
+    name: contract.name,
+    method: contract.method,
+    path: contract.path,
+    calls: 0,
+    failures: 0
+  };
+  entry.calls++;
+  if (!success) entry.failures++;
+  state.entries.set(key, entry);
+}
+function getContractCoverage() {
+  const covered = [...state.entries.values()].sort((a, b) => a.key.localeCompare(b.key));
+  const coveredKeys = new Set(covered.map((entry) => entry.key));
+  const uncovered = listRegisteredContracts().filter((contract) => contract.name && !coveredKeys.has(contract.name)).map((contract) => ({ name: contract.name, method: contract.method, path: contract.path }));
+  const total = uncovered.length + covered.length;
+  return {
+    total,
+    coveredCount: covered.length,
+    percent: total === 0 ? 100 : Math.round(covered.length / total * 100),
+    covered,
+    uncovered
+  };
+}
+function formatContractCoverage(report) {
+  const lines = [
+    "Contract coverage",
+    `  ${report.coveredCount}/${report.total} contracts covered (${report.percent}%)`
+  ];
+  if (report.covered.length > 0) {
+    lines.push("Covered:");
+    for (const entry of report.covered) {
+      const status = entry.failures > 0 ? `${entry.calls - entry.failures}/${entry.calls} ok` : `${entry.calls} ok`;
+      lines.push(`  \u2713 ${entry.method.padEnd(6)} ${entry.path.padEnd(32)} ${status}${entry.failures > 0 ? ` (${entry.failures} failed)` : ""}`);
+    }
+  }
+  if (report.uncovered.length > 0) {
+    lines.push("Uncovered:");
+    for (const entry of report.uncovered) {
+      lines.push(`  \u2717 ${entry.method.padEnd(6)} ${entry.path}${entry.name ? `  (${entry.name})` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 const CONTRACT_HANDLER_META = Symbol.for("nuxt-api-contract.contractHandlerMeta");
 async function callContract(contract, handler, input = {}) {
   const runHandler = extractHandler(contract, handler);
@@ -14,8 +78,10 @@ async function callContract(contract, handler, input = {}) {
     const event = createFakeEvent(headers);
     const rawResponse = await runHandler({ params, query, body, headers, event });
     const data = contract.response ? validateContractResponse(contract, contract.response, rawResponse) : rawResponse;
+    recordCoverageCall(contract, true);
     return { data, error: null };
   } catch (error) {
+    recordCoverageCall(contract, false);
     return {
       data: null,
       error: error instanceof ApiError ? error : new ApiError({ code: "INTERNAL_ERROR", message: String(error) })
@@ -46,4 +112,95 @@ function createFakeEvent(headers) {
 }
 const contractHandlerMetaKey = CONTRACT_HANDLER_META;
 
-export { callContract, contractHandlerMetaKey };
+class ContractAssertionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractAssertionError";
+  }
+}
+function describeCall(contract) {
+  return `${contract.method} ${contract.path}`;
+}
+function testContract(contract, handler) {
+  const suite = {
+    async call(input) {
+      return callContract(contract, handler, input);
+    },
+    async expectSuccess(input) {
+      const { data, error } = await callContract(contract, handler, input);
+      if (error) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected success for ${describeCall(contract)}, got ${error.code} (${error.statusCode}): ${error.message}`
+        );
+      }
+      return data;
+    },
+    async expectError(input, code, statusCode) {
+      const { data, error } = await callContract(contract, handler, input);
+      if (!error) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected an error for ${describeCall(contract)}, but the call succeeded with: ${JSON.stringify(data)}`
+        );
+      }
+      if (code && error.code !== code) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected error code "${code}" for ${describeCall(contract)}, got "${error.code}" (${error.message})`
+        );
+      }
+      if (statusCode !== void 0 && error.statusCode !== statusCode) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected status ${statusCode} for ${describeCall(contract)}, got ${error.statusCode}`
+        );
+      }
+      return error;
+    },
+    async expectValidationError(input, issuePaths) {
+      const error = await suite.expectError(input, BUILT_IN_ERROR_CODES.validation, 400);
+      if (issuePaths && issuePaths.length > 0) {
+        const actual = new Set((error.issues ?? []).map((issue) => issue.path));
+        const missing = issuePaths.filter((path) => {
+          for (const actualPath of actual) {
+            if (actualPath === path || actualPath.endsWith(`.${path}`) || path.endsWith(`.${actualPath}`) || actualPath.startsWith(`${path}.`)) return false;
+          }
+          return true;
+        });
+        if (missing.length > 0) {
+          throw new ContractAssertionError(
+            `[nuxt-api-contract] Expected validation issues for ${[...missing].join(", ")} on ${describeCall(contract)}, got: ${(error.issues ?? []).map((issue) => issue.path).join(", ") || "(none)"}`
+          );
+        }
+      }
+      return error;
+    },
+    async expectResponseValidationError(input, badResponse) {
+      const raw = badResponse;
+      const badHandler = typeof raw === "function" ? raw : ((_ctx) => raw);
+      const { error } = await callContract(contract, badHandler, input);
+      if (!error) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected a response validation failure for ${describeCall(contract)}, but the call succeeded`
+        );
+      }
+      if (error.code !== BUILT_IN_ERROR_CODES.responseValidation) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected "${BUILT_IN_ERROR_CODES.responseValidation}" for ${describeCall(contract)}, got "${error.code}" (${error.message})`
+        );
+      }
+      return error;
+    },
+    validateResponse(value) {
+      if (!contract.response) return;
+      try {
+        validateContractResponse(contract, contract.response, value);
+      } catch (error) {
+        if (error instanceof ApiError) {
+          throw new ContractAssertionError(`[nuxt-api-contract] Response validation failed: ${error.message}`);
+        }
+        throw error;
+      }
+    }
+  };
+  return suite;
+}
+
+export { ContractAssertionError, callContract, contractHandlerMetaKey, formatContractCoverage, getContractCoverage, resetContractCoverage, startContractCoverage, stopContractCoverage, testContract };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-api-contract",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Type-safe API contracts between Nitro server routes and the Nuxt client.",
   "type": "module",
   "license": "MIT",
@@ -56,6 +56,10 @@
       "types": "./dist/openapi.d.mts",
       "import": "./dist/openapi.mjs"
     },
+    "./mock": {
+      "types": "./dist/mock.d.mts",
+      "import": "./dist/mock.mjs"
+    },
     "./package.json": "./package.json"
   },
   "bin": {

package/dist/shared/nuxt-api-contract.QDGSGaVY.mjs

@@ -1,117 +0,0 @@
-const API_CONTRACT_KIND = "api-contract";
-
-const REGISTRY_KEY = Symbol.for("nuxt-api-contract.registry");
-function getStore() {
-  const globalThis_ = globalThis;
-  if (!globalThis_[REGISTRY_KEY]) {
-    globalThis_[REGISTRY_KEY] = { contracts: /* @__PURE__ */ new Map() };
-  }
-  return globalThis_[REGISTRY_KEY];
-}
-function registerContract(contract) {
-  if (!contract.name) return;
-  const store = getStore();
-  const existing = store.contracts.get(contract.name);
-  if (existing && existing !== contract) {
-    console.warn(
-      `[nuxt-api-contract] Duplicate contract name "${contract.name}" registered. The latest definition wins.`
-    );
-  }
-  store.contracts.set(contract.name, contract);
-}
-function getContractByName(name) {
-  return getStore().contracts.get(name);
-}
-function listRegisteredContracts() {
-  return [...getStore().contracts.values()];
-}
-function clearContractRegistry() {
-  getStore().contracts.clear();
-}
-const MOCK_STORE_KEY = Symbol.for("nuxt-api-contract.mocks");
-const mockStore = globalThis[MOCK_STORE_KEY] ??= /* @__PURE__ */ new Map();
-function mockContract(contract, mock) {
-  mockStore.set(contract, mock);
-}
-function getContractMock(contract) {
-  return mockStore.get(contract);
-}
-function defineApiContract(definition) {
-  const contract = {
-    kind: API_CONTRACT_KIND,
-    name: definition.name,
-    version: definition.version,
-    method: definition.method,
-    path: definition.path,
-    params: definition.params,
-    query: definition.query,
-    body: definition.body,
-    headers: definition.headers,
-    response: definition.response,
-    errors: definition.errors ? Object.freeze({ ...definition.errors }) : void 0,
-    summary: definition.summary,
-    description: definition.description,
-    tags: definition.tags ? Object.freeze([...definition.tags]) : void 0,
-    auth: definition.auth,
-    metadata: definition.metadata ? Object.freeze({ ...definition.metadata }) : void 0
-  };
-  Object.freeze(contract);
-  if (definition.name) {
-    registerContract(contract);
-  }
-  return contract;
-}
-function isApiContract(value) {
-  return typeof value === "object" && value !== null && value.kind === API_CONTRACT_KIND;
-}
-function buildRequestPath(path, params) {
-  let url = path;
-  for (const match of path.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
-    const name = match[1];
-    const value = params?.[name];
-    if (value === void 0 || value === null) {
-      throw new Error(`[nuxt-api-contract] Missing path parameter ":${name}" for ${path}`);
-    }
-    url = url.replace(`:${name}`, encodeURIComponent(String(value)));
-  }
-  return url;
-}
-
-function serializeQueryValue(value) {
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "bigint") return value.toString();
-  if (Array.isArray(value)) return value.map((item) => serializePrimitive(item));
-  if (value === void 0 || value === null) return "";
-  if (typeof value === "object") return JSON.stringify(value);
-  return value;
-}
-function serializePrimitive(value) {
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "bigint") return value.toString();
-  if (value === void 0 || value === null || typeof value === "object") return JSON.stringify(value) ?? "";
-  return value;
-}
-function serializeQuery(query) {
-  if (!query) return void 0;
-  const result = {};
-  for (const [key, value] of Object.entries(query)) {
-    if (value === void 0) continue;
-    result[key] = serializeQueryValue(value);
-  }
-  return result;
-}
-function stableStringify(value) {
-  return JSON.stringify(sortValue(value));
-}
-function sortValue(value) {
-  if (Array.isArray(value)) return value.map((item) => sortValue(item));
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "bigint") return value.toString();
-  if (value !== null && typeof value === "object") {
-    const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-    return Object.fromEntries(entries.map(([key, item]) => [key, sortValue(item)]));
-  }
-  return value;
-}
-
-export { getContractMock as a, buildRequestPath as b, clearContractRegistry as c, defineApiContract as d, serializeQueryValue as e, stableStringify as f, getContractByName as g, isApiContract as i, listRegisteredContracts as l, mockContract as m, registerContract as r, serializeQuery as s };

package/dist/shared/nuxt-api-contract.obS6uV8A.mjs

@@ -1,73 +0,0 @@
-class ApiError extends Error {
-  code;
-  statusCode;
-  details;
-  issues;
-  constructor(options) {
-    super(options.message);
-    this.name = "ApiError";
-    this.code = options.code;
-    this.statusCode = options.statusCode ?? 500;
-    this.details = options.details;
-    this.issues = options.issues;
-  }
-  toJSON() {
-    return serializeApiError(this);
-  }
-}
-function createApiError(codeOrOptions, message, statusCode, details) {
-  if (typeof codeOrOptions === "string") {
-    return new ApiError({ code: codeOrOptions, message: message ?? codeOrOptions, statusCode, details });
-  }
-  return new ApiError({
-    code: codeOrOptions.code,
-    message: codeOrOptions.message ?? codeOrOptions.code,
-    statusCode: codeOrOptions.statusCode,
-    details: codeOrOptions.details,
-    issues: codeOrOptions.issues
-  });
-}
-function isApiError(value) {
-  return value instanceof ApiError || typeof value === "object" && value !== null && value.name === "ApiError" && typeof value.code === "string";
-}
-function serializeApiError(error) {
-  return {
-    error: {
-      code: error.code,
-      message: error.message,
-      statusCode: error.statusCode,
-      details: error.details,
-      issues: error.issues
-    }
-  };
-}
-function parseApiErrorPayload(value) {
-  if (typeof value !== "object" || value === null) return void 0;
-  const error = value.error;
-  if (typeof error !== "object" || error === null) return void 0;
-  const { code, message, statusCode, details, issues } = error;
-  if (typeof code !== "string" || typeof message !== "string") return void 0;
-  return {
-    code,
-    message,
-    statusCode: typeof statusCode === "number" ? statusCode : void 0,
-    details,
-    issues: Array.isArray(issues) ? issues : void 0
-  };
-}
-function toApiError(value, fallbackMessage = "Internal server error") {
-  if (isApiError(value)) return value;
-  if (value instanceof Error) {
-    return new ApiError({ code: "INTERNAL_ERROR", message: value.message || fallbackMessage, statusCode: 500 });
-  }
-  return new ApiError({ code: "INTERNAL_ERROR", message: fallbackMessage, statusCode: 500 });
-}
-const BUILT_IN_ERROR_CODES = {
-  validation: "VALIDATION_ERROR",
-  responseValidation: "API_CONTRACT_RESPONSE_VALIDATION_ERROR",
-  internal: "INTERNAL_ERROR",
-  notFound: "NOT_FOUND",
-  methodNotAllowed: "METHOD_NOT_ALLOWED"
-};
-
-export { ApiError as A, BUILT_IN_ERROR_CODES as B, createApiError as c, isApiError as i, parseApiErrorPayload as p, serializeApiError as s, toApiError as t };