@x12i/helpers 1.0.1 → 1.0.2

package/src/helpers/apiMapper.js

@@ -0,0 +1,459 @@
+/**
+ * ╔══════════════════════════════════════════════════════════════╗
+ * ║                     API MAPPER                              ║
+ * ╠══════════════════════════════════════════════════════════════╣
+ * ║  Translates API calls between two contracts/protocols.      ║
+ * ║  REST ↔ GraphQL ↔ JSON-RPC ↔ SOAP ↔ Custom                ║
+ * ║                                                              ║
+ * ║  Uses json-mapper.js for deep property mapping of both      ║
+ * ║  request params and response bodies.                        ║
+ * ╚══════════════════════════════════════════════════════════════╝
+ *
+ * BRIDGE CONFIG:
+ * ┌──────────────────────────────────────────────────────────────┐
+ * │ {                                                            │
+ * │   source:          Contract,   // caller's view              │
+ * │   target:          Contract,   // actual API                 │
+ * │   requestMapping:  [...],      // json-mapper: src → tgt     │
+ * │   responseMapping: [...],      // json-mapper: tgt → src     │
+ * │   beforeRequest:   fn,         // middleware                  │
+ * │   afterResponse:   fn,         // middleware                  │
+ * │   errorMapping:    {...},      // status→handler             │
+ * │   retry:           {...},      // attempts/backoff           │
+ * │   credentials:     {...},      // per-side auth              │
+ * │ }                                                            │
+ * └──────────────────────────────────────────────────────────────┘
+ */
+
+const { mapObject } = require("./json-mapper.js");
+const { defineContract } = require("./api-contracts.js");
+
+// ═══════════════════════════════════════════════════════════════
+//  HELPERS
+// ═══════════════════════════════════════════════════════════════
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function buildUrl(base, query = {}) {
+  const qs = Object.entries(query)
+    .filter(([, v]) => v != null)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+  return qs ? `${base}?${qs}` : base;
+}
+
+function resolveContract(ref, registry) {
+  if (typeof ref === "string") {
+    if (!registry) throw new Error(`String contract "${ref}" needs a registry`);
+    return registry.get(ref);
+  }
+  return ref._protocol ? ref : defineContract(ref);
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  DEFAULT HTTP CLIENT  (Node 18+ / browser fetch)
+// ═══════════════════════════════════════════════════════════════
+
+async function defaultHttpClient(req) {
+  const url = buildUrl(req.url, req.query);
+  const opts = { method: req.method, headers: req.headers || {} };
+  if (req.body !== undefined) {
+    opts.body = typeof req.body === "string" ? req.body : JSON.stringify(req.body);
+  }
+  const res = await fetch(url, opts);
+  let body;
+  const ct = res.headers.get("content-type") || "";
+  if (ct.includes("json"))                              body = await res.json();
+  else if (ct.includes("xml") || ct.includes("text"))   body = await res.text();
+  else { try { body = await res.json(); } catch { body = await res.text(); } }
+
+  return {
+    status: res.status,
+    statusText: res.statusText,
+    headers: Object.fromEntries(res.headers.entries()),
+    body,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  RETRY
+// ═══════════════════════════════════════════════════════════════
+
+async function executeWithRetry(executor, request, cfg) {
+  const {
+    attempts = 3,
+    delay = 1000,
+    backoff = "exponential",
+    retryOn = (r) => r.status >= 500,
+  } = cfg;
+
+  let last;
+  for (let i = 0; i < attempts; i++) {
+    last = await executor(request);
+    if (!retryOn(last)) return last;
+    if (i < attempts - 1) {
+      const wait =
+        backoff === "exponential" ? delay * 2 ** i :
+        backoff === "linear"      ? delay * (i + 1) : delay;
+      await sleep(wait);
+    }
+  }
+  return last;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  CORE: createBridge
+// ═══════════════════════════════════════════════════════════════
+
+function createBridge(config) {
+  const {
+    requestMapping  = [],
+    responseMapping = [],
+    beforeRequest,
+    afterResponse,
+    errorMapping = {},
+    retry: retryConfig,
+    credentials = {},
+    registry,
+    httpClient,
+  } = config;
+
+  const source = resolveContract(config.source, registry);
+  const target = resolveContract(config.target, registry);
+
+  async function call(sourceParams, opts = {}) {
+    const creds = { ...credentials, ...opts.credentials };
+
+    // 1 — validate source params
+    const sv = source.validateRequest(sourceParams);
+    if (!sv.valid) {
+      return { ok: false, error: "Source validation failed", validationErrors: sv.errors, data: null };
+    }
+
+    // 2 — map source params → target params
+    let targetParams = requestMapping.length
+      ? mapObject(sourceParams, requestMapping)
+      : { ...sourceParams };
+
+    // 3 — build normalized HTTP request via target protocol
+    let targetReq = target.buildRequest(targetParams, creds.target);
+
+    // 4 — middleware: beforeRequest
+    if (beforeRequest) targetReq = beforeRequest(targetReq, sourceParams) || targetReq;
+    if (opts.beforeRequest) targetReq = opts.beforeRequest(targetReq, sourceParams) || targetReq;
+
+    // 5 — dry-run: return translated request without calling
+    if (opts.dryRun) {
+      return {
+        ok: true, dryRun: true,
+        sourceContract: source.name, targetContract: target.name,
+        sourceParams, targetParams, targetRequest: targetReq, data: null,
+      };
+    }
+
+    // 6 — execute
+    const exec = httpClient || opts.httpClient || defaultHttpClient;
+    const rawRes = retryConfig
+      ? await executeWithRetry(exec, targetReq, retryConfig)
+      : await exec(targetReq);
+
+    // 7 — parse via target protocol
+    const parsed = target.parseResponse(rawRes);
+
+    // 8 — error mapping
+    if (parsed.error) {
+      const h = errorMapping[String(rawRes.status)] || errorMapping["*"];
+      const err = h ? h(parsed.error, rawRes) : parsed.error;
+      return { ok: false, error: err, status: parsed.status, data: null, raw: parsed };
+    }
+
+    // 9 — map response data → source shape
+    let data = parsed.data;
+    if (responseMapping.length && data && typeof data === "object") {
+      data = mapObject(data, responseMapping);
+    }
+
+    // 10 — validate response
+    const rv = source.validateResponse(data);
+
+    // 11 — middleware: afterResponse
+    if (afterResponse)     data = afterResponse(data, parsed)     || data;
+    if (opts.afterResponse) data = opts.afterResponse(data, parsed) || data;
+
+    return {
+      ok: true, status: parsed.status, data,
+      headers: parsed.headers, raw: parsed,
+      ...(rv.valid ? {} : { responseWarnings: rv.errors }),
+    };
+  }
+
+  function explain() {
+    return {
+      from: { name: source.name, protocol: source.protocol },
+      to:   { name: target.name, protocol: target.protocol },
+      requestMappingRules: requestMapping.length,
+      responseMappingRules: responseMapping.length,
+      hasMiddleware: !!(beforeRequest || afterResponse),
+      hasRetry: !!retryConfig,
+      hasErrorMapping: Object.keys(errorMapping).length > 0,
+    };
+  }
+
+  return { call, explain, source, target };
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  BATCH
+// ═══════════════════════════════════════════════════════════════
+
+async function batchCall(bridge, paramsList, opts = {}) {
+  const { concurrency = 5, onProgress } = opts;
+
+  if (concurrency >= paramsList.length) {
+    return Promise.all(
+      paramsList.map((p, i) =>
+        bridge.call(p, opts).then((r) => { if (onProgress) onProgress(i, r); return r; })
+      )
+    );
+  }
+  const results = new Array(paramsList.length);
+  let cursor = 0;
+  async function worker() {
+    while (cursor < paramsList.length) {
+      const idx = cursor++;
+      results[idx] = await bridge.call(paramsList[idx], opts);
+      if (onProgress) onProgress(idx, results[idx]);
+    }
+  }
+  await Promise.all(Array.from({ length: concurrency }, worker));
+  return results;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  CHAIN  (pipe: A→B→C)
+// ═══════════════════════════════════════════════════════════════
+
+function chainBridges(...bridges) {
+  return {
+    async call(sourceParams, opts = {}) {
+      let current = sourceParams;
+      const trace = [];
+      for (const b of bridges) {
+        const r = await b.call(current, opts);
+        trace.push({ from: b.source.name, to: b.target.name, ok: r.ok, status: r.status });
+        if (!r.ok) return { ...r, trace };
+        current = r.data;
+      }
+      return { ok: true, data: current, trace };
+    },
+    explain: () => bridges.map((b) => b.explain()),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════
+
+module.exports = { createBridge, batchCall, chainBridges, defaultHttpClient };
+
+// ══════════════════════════════════════════════════════════════════
+//  DEMO — node api-mapper.js
+// ══════════════════════════════════════════════════════════════════
+
+if (require.main === module) {
+  const { defineContract } = require("./api-contracts.js");
+
+  // ── Mock HTTP (no real network) ──
+  function mockHttp(req) {
+    console.log(`\n  ┌─ TARGET HTTP REQUEST ─────────────────────`);
+    console.log(`  │ ${req.method} ${buildUrl(req.url, req.query)}`);
+    console.log(`  │ Content-Type: ${req.headers["Content-Type"]}`);
+    if (req.headers.Authorization) console.log(`  │ Auth: ${req.headers.Authorization}`);
+    if (req.headers.SOAPAction)    console.log(`  │ SOAPAction: ${req.headers.SOAPAction}`);
+    if (req.body) {
+      const preview = typeof req.body === "string"
+        ? req.body.substring(0, 200)
+        : JSON.stringify(req.body, null, 2);
+      preview.split("\n").forEach((l) => console.log(`  │ ${l}`));
+    }
+    console.log(`  └─────────────────────────────────────────────`);
+
+    const ct = req.headers?.["Content-Type"] || "";
+    if (ct.includes("xml")) {
+      return Promise.resolve({ status: 200, headers: { "content-type": "text/xml" },
+        body: `<GetStockPriceResponse><Price>182.63</Price><Currency>USD</Currency></GetStockPriceResponse>` });
+    }
+    if (req.body?.jsonrpc) {
+      return Promise.resolve({ status: 200, headers: { "content-type": "application/json" },
+        body: { jsonrpc: "2.0", id: req.body.id, result: { balance: "3.14159", unit: "ETH" } } });
+    }
+    if (req.body?.query) {
+      return Promise.resolve({ status: 200, headers: { "content-type": "application/json" },
+        body: { data: { user: { id: "42", fullName: "Jane Doe", emailAddress: "jane@example.com", role: "ADMIN" } } } });
+    }
+    return Promise.resolve({ status: 200, headers: { "content-type": "application/json" },
+      body: { id: 42, name: "Jane Doe", email: "jane@example.com", role: "admin" } });
+  }
+
+  async function demo() {
+
+    // ═════════════════════════════════════════
+    //  1:  REST  →  GraphQL
+    // ═════════════════════════════════════════
+    console.log("\n╔═══════════════════════════════════════════════════╗");
+    console.log("║  1 — REST caller  →  GraphQL backend              ║");
+    console.log("╚═══════════════════════════════════════════════════╝");
+
+    const restGetUser = defineContract({
+      name: "restGetUser", protocol: "rest",
+      endpoint: "/api/users/{id}", method: "GET",
+      auth: { type: "bearer" },
+      requestSchema: {
+        pathParams: { type: "object", required: true,
+          properties: { id: { type: "string", required: true } } },
+      },
+    });
+
+    const gqlGetUser = defineContract({
+      name: "gqlGetUser", protocol: "graphql",
+      endpoint: "https://api.example.com/graphql",
+      query: `query GetUser($userId: ID!) { user(id: $userId) { id fullName emailAddress role } }`,
+      auth: { type: "bearer" },
+    });
+
+    const bridge1 = createBridge({
+      source: restGetUser,
+      target: gqlGetUser,
+      requestMapping: [
+        { from: "pathParams.id", to: "variables.userId" },
+      ],
+      responseMapping: [
+        "user.id",
+        "user.fullName    -> user.name",
+        "user.emailAddress -> user.email",
+        { from: "user.role", to: "user.role", transform: (v) => v?.toLowerCase() },
+      ],
+      credentials: { target: { token: "gql-token-abc" } },
+    });
+
+    const r1 = await bridge1.call({ pathParams: { id: "42" } }, { httpClient: mockHttp });
+    console.log("\n  ✅ MAPPED RESPONSE (REST shape):", JSON.stringify(r1.data, null, 4));
+
+    // ═════════════════════════════════════════
+    //  2:  REST  →  JSON-RPC
+    // ═════════════════════════════════════════
+    console.log("\n╔═══════════════════════════════════════════════════╗");
+    console.log("║  2 — REST caller  →  JSON-RPC backend             ║");
+    console.log("╚═══════════════════════════════════════════════════╝");
+
+    const restBalance = defineContract({
+      name: "restGetBalance", protocol: "rest",
+      endpoint: "/api/wallets/{address}/balance", method: "GET",
+    });
+    const rpcBalance = defineContract({
+      name: "rpcGetBalance", protocol: "jsonrpc",
+      endpoint: "https://rpc.example.com",
+      rpcMethod: "eth_getBalance", paramsAsArray: true,
+    });
+
+    const bridge2 = createBridge({
+      source: restBalance,
+      target: rpcBalance,
+      requestMapping: [
+        { from: "pathParams.address", to: "rpcParams.address" },
+        { compute: () => "latest",    to: "rpcParams.block" },
+      ],
+      responseMapping: [
+        { from: "balance", to: "balance" },
+        { from: "unit",    to: "currency" },
+      ],
+    });
+
+    const r2 = await bridge2.call({ pathParams: { address: "0xABC123" } }, { httpClient: mockHttp });
+    console.log("\n  ✅ MAPPED RESPONSE:", JSON.stringify(r2.data, null, 4));
+
+    // ═════════════════════════════════════════
+    //  3:  REST  →  SOAP
+    // ═════════════════════════════════════════
+    console.log("\n╔═══════════════════════════════════════════════════╗");
+    console.log("║  3 — REST caller  →  SOAP backend                 ║");
+    console.log("╚═══════════════════════════════════════════════════╝");
+
+    const restStock = defineContract({
+      name: "restGetStock", protocol: "rest",
+      endpoint: "/api/stocks/{symbol}", method: "GET",
+    });
+    const soapStock = defineContract({
+      name: "soapGetStock", protocol: "soap",
+      endpoint: "https://legacy.example.com/StockService",
+      operation: "GetStockPrice",
+      namespace: "http://example.com/stocks",
+      soapAction: "http://example.com/stocks/GetStockPrice",
+      responseExtractor: (xml) => {
+        const price    = xml.match(/<Price>(.*?)<\/Price>/)?.[1];
+        const currency = xml.match(/<Currency>(.*?)<\/Currency>/)?.[1];
+        return { price: parseFloat(price), currency };
+      },
+    });
+
+    const bridge3 = createBridge({
+      source: restStock,
+      target: soapStock,
+      requestMapping: [
+        { from: "pathParams.symbol", to: "soapBody.StockSymbol" },
+      ],
+      responseMapping: [
+        { from: "price",    to: "price" },
+        { from: "currency", to: "currency" },
+      ],
+    });
+
+    const r3 = await bridge3.call({ pathParams: { symbol: "AAPL" } }, { httpClient: mockHttp });
+    console.log("\n  ✅ MAPPED RESPONSE:", JSON.stringify(r3.data, null, 4));
+
+    // ═════════════════════════════════════════
+    //  4:  DRY RUN
+    // ═════════════════════════════════════════
+    console.log("\n╔═══════════════════════════════════════════════════╗");
+    console.log("║  4 — Dry-run (inspect without calling)            ║");
+    console.log("╚═══════════════════════════════════════════════════╝");
+
+    const dry = await bridge1.call({ pathParams: { id: "99" } }, { dryRun: true });
+    console.log(JSON.stringify(dry, null, 2));
+
+    // ═════════════════════════════════════════
+    //  5:  CHAIN (REST → GQL → JSON-RPC)
+    // ═════════════════════════════════════════
+    console.log("\n╔═══════════════════════════════════════════════════╗");
+    console.log("║  5 — Chain: REST → GraphQL → JSON-RPC             ║");
+    console.log("╚═══════════════════════════════════════════════════╝");
+
+    const enrichBridge = createBridge({
+      source: gqlGetUser,
+      target: rpcBalance,
+      requestMapping: [
+        { from: "user.id",          to: "rpcParams.address" },
+        { compute: () => "latest",  to: "rpcParams.block" },
+      ],
+      responseMapping: [
+        { from: "balance", to: "walletBalance" },
+        { from: "unit",    to: "walletCurrency" },
+      ],
+    });
+
+    const chain = chainBridges(bridge1, enrichBridge);
+    const cr = await chain.call({ pathParams: { id: "42" } }, { httpClient: mockHttp });
+    console.log("\n  ✅ CHAIN RESULT:", JSON.stringify(cr, null, 2));
+
+    // ═════════════════════════════════════════
+    //  EXPLAIN
+    // ═════════════════════════════════════════
+    console.log("\n╔═══════════════════════════════════════════════════╗");
+    console.log("║  Bridge Introspection                              ║");
+    console.log("╚═══════════════════════════════════════════════════╝");
+    [bridge1, bridge2, bridge3].forEach((b) => {
+      const e = b.explain();
+      console.log(`  ${e.from.name} (${e.from.protocol}) → ${e.to.name} (${e.to.protocol})  [${e.requestMappingRules} req, ${e.responseMappingRules} res rules]`);
+    });
+  }
+
+  demo().catch(console.error);
+}