@x12i/helpers 1.0.0 → 1.0.1

package/README.md

@@ -33,6 +33,45 @@ You can also import the mapper directly:
 const { mapObject } = require("@x12i/helpers/objects-mapper");
 ```
 
+### HTTP tools (request ⇄ curl, base URLs)
+
+```js
+const {
+  requestToCurl,
+  curlToRequest,
+  buildUrl,
+  createBaseUrlClient,
+} = require("@x12i/helpers");
+
+const curl = requestToCurl({
+  method: "POST",
+  url: "https://api.example.com/v1/users",
+  headers: { authorization: "Bearer TOKEN" },
+  body: { name: "Jane" },
+});
+
+// curl -X POST -H 'authorization: Bearer TOKEN' -H 'content-type: application/json' --data-raw '{"name":"Jane"}' 'https://api.example.com/v1/users'
+console.log(curl);
+
+const req = curlToRequest(curl);
+// { method: 'POST', url: 'https://api.example.com/v1/users', headers: { authorization: 'Bearer TOKEN', 'content-type': 'application/json' }, body: '{"name":"Jane"}' }
+console.log(req);
+
+console.log(buildUrl("https://api.example.com/", "/v1/users", { limit: 10, tags: ["a", "b"] }));
+// https://api.example.com/v1/users?limit=10&tags=a&tags=b
+
+const api = createBaseUrlClient("https://api.example.com/", {
+  headers: { authorization: "Bearer TOKEN" },
+});
+console.log(api.curl("/v1/health"));
+```
+
+Direct import:
+
+```js
+const { requestToCurl } = require("@x12i/helpers/http-tools");
+```
+
 ## API
 
 - `mapObject(source, mapping, opts)`
@@ -40,4 +79,8 @@ const { mapObject } = require("@x12i/helpers/objects-mapper");
 - `mapArray(sourceArray, mapping, opts)`
 - `deepGet(obj, path)`
 - `deepSet(obj, path, value)`
+- `requestToCurl(req)`
+- `curlToRequest(curlCommand)`
+- `buildUrl(baseUrl, pathOrUrl, query)`
+- `createBaseUrlClient(baseUrl, defaults)`
 

package/index.js

@@ -1,4 +1,5 @@
 module.exports = {
   ...require("./src/helpers/objectsMapper.js"),
+  ...require("./src/helpers/httpTools.js"),
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/helpers",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Small helper utilities for x12i projects.",
   "license": "MIT",
   "author": "x12i",
@@ -20,7 +20,8 @@
   "main": "./index.js",
   "exports": {
     ".": "./index.js",
-    "./objects-mapper": "./src/helpers/objectsMapper.js"
+    "./objects-mapper": "./src/helpers/objectsMapper.js",
+    "./http-tools": "./src/helpers/httpTools.js"
   },
   "files": [
     "index.js",
@@ -32,4 +33,3 @@
     "test": "node --test"
   }
 }
-

package/src/helpers/httpTools.js

@@ -0,0 +1,215 @@
+function shellEscapeSingleQuotes(s) {
+  // Wrap in single quotes, escape existing single quotes for POSIX shells.
+  // abc'def -> 'abc'"'"'def'
+  return `'${String(s).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function normalizeHeaders(headers) {
+  if (!headers) return {};
+  if (Array.isArray(headers)) {
+    // [ [k,v], ... ]
+    return Object.fromEntries(headers);
+  }
+  if (headers instanceof Map) {
+    return Object.fromEntries(headers.entries());
+  }
+  return { ...headers };
+}
+
+/**
+ * Build a fully-qualified URL from base + path + query.
+ *
+ * - If `pathOrUrl` is already absolute (http:// or https://), it is used as-is.
+ * - Query values can be strings/numbers/booleans/arrays; null/undefined are skipped.
+ */
+function buildUrl(baseUrl, pathOrUrl = "", query) {
+  const raw = String(pathOrUrl || "");
+  const isAbsolute = /^https?:\/\//i.test(raw);
+
+  const base = isAbsolute ? new URL(raw) : new URL(raw.replace(/^\//, ""), String(baseUrl || ""));
+
+  if (query && typeof query === "object") {
+    for (const [k, v] of Object.entries(query)) {
+      if (v == null) continue;
+      if (Array.isArray(v)) {
+        for (const item of v) {
+          if (item == null) continue;
+          base.searchParams.append(k, String(item));
+        }
+      } else {
+        base.searchParams.set(k, String(v));
+      }
+    }
+  }
+
+  return base.toString();
+}
+
+/**
+ * Convert a request description into a curl command.
+ *
+ * @param {object} req
+ * @param {string} req.url
+ * @param {string} [req.method]
+ * @param {object} [req.headers]
+ * @param {any}    [req.body] - string/object/buffer-ish; objects are JSON.stringified
+ */
+function requestToCurl(req) {
+  if (!req || typeof req !== "object") throw new TypeError("requestToCurl: req must be an object");
+  if (!req.url) throw new TypeError("requestToCurl: req.url is required");
+
+  const method = String(req.method || "GET").toUpperCase();
+  const headers = normalizeHeaders(req.headers);
+
+  const parts = ["curl"];
+
+  if (method !== "GET") {
+    parts.push("-X", method);
+  }
+
+  for (const [k, v] of Object.entries(headers)) {
+    if (v == null) continue;
+    parts.push("-H", shellEscapeSingleQuotes(`${k}: ${v}`));
+  }
+
+  if (req.body !== undefined) {
+    let body = req.body;
+    if (body && typeof body === "object" && !Buffer.isBuffer(body)) {
+      body = JSON.stringify(body);
+      // Add content-type if caller didn't set it.
+      const hasCt = Object.keys(headers).some((h) => h.toLowerCase() === "content-type");
+      if (!hasCt) parts.push("-H", shellEscapeSingleQuotes("content-type: application/json"));
+    }
+    parts.push("--data-raw", shellEscapeSingleQuotes(body));
+  }
+
+  parts.push(shellEscapeSingleQuotes(req.url));
+  return parts.join(" ");
+}
+
+function unquote(s) {
+  const str = String(s);
+  if ((str.startsWith("'") && str.endsWith("'")) || (str.startsWith('"') && str.endsWith('"'))) {
+    return str.slice(1, -1);
+  }
+  return str;
+}
+
+function tokenizeCurl(cmd) {
+  const s = String(cmd).trim();
+  const tokens = [];
+  let i = 0;
+  while (i < s.length) {
+    while (s[i] === " " || s[i] === "\t" || s[i] === "\n") i++;
+    if (i >= s.length) break;
+
+    const q = s[i];
+    if (q === "'" || q === '"') {
+      let j = i + 1;
+      let out = "";
+      while (j < s.length) {
+        const ch = s[j];
+        if (ch === q) break;
+        if (q === '"' && ch === "\\" && j + 1 < s.length) {
+          out += s[j + 1];
+          j += 2;
+          continue;
+        }
+        out += ch;
+        j++;
+      }
+      tokens.push(out);
+      i = j + 1;
+    } else {
+      let j = i;
+      while (j < s.length && !/\s/.test(s[j])) j++;
+      tokens.push(s.slice(i, j));
+      i = j;
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Parse a curl command into a request-like object.
+ *
+ * Supports: -X/--request, -H/--header, -d/--data/--data-raw, and a URL token.
+ */
+function curlToRequest(curlCommand) {
+  const tokens = tokenizeCurl(curlCommand);
+  if (!tokens.length || tokens[0] !== "curl") throw new TypeError("curlToRequest: command must start with curl");
+
+  let method = "GET";
+  let url;
+  const headers = {};
+  let body;
+
+  for (let i = 1; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === "-X" || t === "--request") {
+      method = String(tokens[++i] || "").toUpperCase();
+      continue;
+    }
+    if (t === "-H" || t === "--header") {
+      const hv = tokens[++i];
+      const raw = unquote(hv);
+      const idx = raw.indexOf(":");
+      if (idx !== -1) {
+        const k = raw.slice(0, idx).trim();
+        const v = raw.slice(idx + 1).trim();
+        headers[k] = v;
+      }
+      continue;
+    }
+    if (t === "-d" || t === "--data" || t === "--data-raw" || t === "--data-binary") {
+      body = unquote(tokens[++i]);
+      if (method === "GET") method = "POST";
+      continue;
+    }
+    if (!t.startsWith("-") && !url) {
+      url = unquote(t);
+      continue;
+    }
+  }
+
+  if (!url) throw new TypeError("curlToRequest: URL not found");
+
+  return { method, url, headers, body };
+}
+
+/**
+ * Create a small request builder around a base URL.
+ */
+function createBaseUrlClient(baseUrl, defaults = {}) {
+  const defaultHeaders = normalizeHeaders(defaults.headers);
+
+  return {
+    buildUrl: (pathOrUrl, query) => buildUrl(baseUrl, pathOrUrl, query),
+    request: (pathOrUrl, options = {}) => {
+      const url = buildUrl(baseUrl, pathOrUrl, options.query);
+      const headers = { ...defaultHeaders, ...normalizeHeaders(options.headers) };
+      return {
+        method: (options.method || "GET").toUpperCase(),
+        url,
+        headers,
+        body: options.body,
+      };
+    },
+    curl: (pathOrUrl, options = {}) => requestToCurl(
+      {
+        ...defaults,
+        ...options,
+        url: buildUrl(baseUrl, pathOrUrl, options.query),
+        headers: { ...defaultHeaders, ...normalizeHeaders(options.headers) },
+      }
+    ),
+  };
+}
+
+module.exports = {
+  buildUrl,
+  requestToCurl,
+  curlToRequest,
+  createBaseUrlClient,
+};
+