@catbee/utils 1.1.0 → 2.0.0-next.1

package/types/index.mjs

@@ -0,0 +1,32 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+// src/types/api-response.ts
+var SortDirection = /* @__PURE__ */ (function(SortDirection2) {
+  SortDirection2["ASC"] = "asc";
+  SortDirection2["DESC"] = "desc";
+  return SortDirection2;
+})({});
+
+export { SortDirection };

package/url/index.cjs

@@ -0,0 +1,199 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+'use strict';
+
+var url = require('url');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function appendQueryParams(url$1, params) {
+  const urlObj = new url.URL(url$1);
+  for (const [key, value] of Object.entries(params)) {
+    urlObj.searchParams.set(key, value.toString());
+  }
+  return urlObj.toString();
+}
+__name(appendQueryParams, "appendQueryParams");
+function parseQueryString(query) {
+  const cleanQuery = query.startsWith("?") ? query.slice(1) : query;
+  return Object.fromEntries(new url.URLSearchParams(cleanQuery));
+}
+__name(parseQueryString, "parseQueryString");
+function isValidUrl(url$1, requireHttps = false) {
+  try {
+    const parsedUrl = new url.URL(url$1);
+    if (!parsedUrl.protocol || !parsedUrl.hostname) return false;
+    if (requireHttps && parsedUrl.protocol !== "https:") return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isValidUrl, "isValidUrl");
+function getDomain(url$1, removeSubdomains = false) {
+  try {
+    const { hostname } = new url.URL(url$1);
+    if (!removeSubdomains) {
+      return hostname;
+    }
+    const parts = hostname.split(".");
+    if (parts.length <= 2) return hostname;
+    const secondLevelDomains = [
+      "co",
+      "com",
+      "org",
+      "net",
+      "gov",
+      "edu",
+      "ac"
+    ];
+    const sld = parts[parts.length - 2];
+    if (secondLevelDomains.includes(sld) && parts.length > 2) {
+      return parts.slice(-3).join(".");
+    }
+    return parts.slice(-2).join(".");
+  } catch {
+    return "";
+  }
+}
+__name(getDomain, "getDomain");
+function joinPaths(...segments) {
+  let result = segments.filter((s) => s !== void 0 && s !== null).map((segment, index) => {
+    if (index === 0) return segment.replace(/\/+$/, "");
+    return segment.replace(/^\/+|\/+$/g, "");
+  }).filter(Boolean).join("/");
+  if (segments[0] === "" && !result.startsWith("/")) result = "/" + result;
+  return result;
+}
+__name(joinPaths, "joinPaths");
+function normalizeUrl(url$1, base) {
+  try {
+    let normalized = url$1.startsWith("//") ? `https:${url$1}` : url$1;
+    const parsedUrl = base ? new url.URL(normalized, base) : new url.URL(normalized);
+    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+/g, "/");
+    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "");
+    parsedUrl.hostname = parsedUrl.hostname.toLowerCase();
+    return parsedUrl.toString();
+  } catch {
+    return url$1;
+  }
+}
+__name(normalizeUrl, "normalizeUrl");
+function createUrlBuilder(baseUrl) {
+  return {
+    /**
+    * Creates a full URL with the given path and query parameters.
+    *
+    * @param {string} path - The path to append to the base URL.
+    * @param {Record<string, any>} [params] - Query parameters to add.
+    * @returns {string} The complete URL.
+    */
+    path(path, params) {
+      const url = joinPaths(baseUrl, path);
+      return params ? appendQueryParams(url, params) : url;
+    },
+    /**
+    * Creates a full URL with query parameters but no additional path.
+    *
+    * @param {Record<string, any>} params - Query parameters to add.
+    * @returns {string} The complete URL with query parameters.
+    */
+    query(params) {
+      return appendQueryParams(baseUrl, params);
+    }
+  };
+}
+__name(createUrlBuilder, "createUrlBuilder");
+function extractQueryParams(url$1, paramNames) {
+  try {
+    const parsedUrl = new url.URL(url$1);
+    const result = {};
+    for (const name of paramNames) {
+      const value = parsedUrl.searchParams.get(name);
+      if (value !== null) {
+        result[name] = value;
+      }
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+__name(extractQueryParams, "extractQueryParams");
+function removeQueryParams(url$1, paramsToRemove) {
+  try {
+    const parsedUrl = new url.URL(url$1);
+    for (const param of paramsToRemove) {
+      parsedUrl.searchParams.delete(param);
+    }
+    return parsedUrl.toString();
+  } catch {
+    return url$1;
+  }
+}
+__name(removeQueryParams, "removeQueryParams");
+function getExtension(url$1) {
+  try {
+    const { pathname } = new url.URL(url$1);
+    const match = pathname.match(/\.([^./\\?#]+)$/);
+    return match ? match[1].toLowerCase() : "";
+  } catch {
+    const match = url$1.match(/\.([^./\\?#]+)$/);
+    return match ? match[1].toLowerCase() : "";
+  }
+}
+__name(getExtension, "getExtension");
+function parseTypedQueryParams(url$1, converters) {
+  try {
+    const { searchParams } = new url.URL(url$1);
+    const result = {};
+    for (const [key, value] of searchParams.entries()) {
+      if (converters && key in converters) {
+        try {
+          result[key] = converters[key](value);
+        } catch {
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+__name(parseTypedQueryParams, "parseTypedQueryParams");
+
+exports.appendQueryParams = appendQueryParams;
+exports.createUrlBuilder = createUrlBuilder;
+exports.extractQueryParams = extractQueryParams;
+exports.getDomain = getDomain;
+exports.getExtension = getExtension;
+exports.isValidUrl = isValidUrl;
+exports.joinPaths = joinPaths;
+exports.normalizeUrl = normalizeUrl;
+exports.parseQueryString = parseQueryString;
+exports.parseTypedQueryParams = parseTypedQueryParams;
+exports.removeQueryParams = removeQueryParams;

package/url/index.d.ts

@@ -0,0 +1,166 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Appends query parameters to a given URL.
+ *
+ * @param {string} url - The base URL to which query parameters will be appended.
+ * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.
+ * @returns {string} The new URL string with query parameters appended.
+ *
+ * @example
+ * appendQueryParams('https://example.com', { page: 1, limit: 10 });
+ * // -> 'https://example.com/?page=1&limit=10'
+ */
+declare function appendQueryParams(url: string, params: Record<string, string | number>): string;
+/**
+ * Parses a query string into a key-value object.
+ *
+ * @param {string} query - The query string (with or without leading '?').
+ * @returns {Record<string, string>} Object representing parsed query parameters.
+ *
+ * @example
+ * parseQueryString('?page=1&limit=10');
+ * // -> { page: '1', limit: '10' }
+ */
+declare function parseQueryString(query: string): Record<string, string>;
+/**
+ * Validates if a string is a valid URL.
+ *
+ * @param {string} url - The URL string to validate.
+ * @param {boolean} [requireHttps=false] - If true, requires the URL to use HTTPS.
+ * @returns {boolean} True if the URL is valid, false otherwise.
+ */
+declare function isValidUrl(url: string, requireHttps?: boolean): boolean;
+/**
+ * Extracts the domain name from a URL.
+ *
+ * @param {string} url - The URL to extract the domain from.
+ * @param {boolean} [removeSubdomains=false] - If true, removes subdomains (returns root domain only).
+ * @returns {string} The domain name.
+ *
+ * @example
+ * getDomain('https://api.example.com/path');
+ * // -> 'api.example.com'
+ *
+ * getDomain('https://api.example.com/path', true);
+ * // -> 'example.com'
+ */
+declare function getDomain(url: string, removeSubdomains?: boolean): string;
+/**
+ * Joins URL paths properly handling slashes.
+ *
+ * @param {...string[]} segments - URL path segments to join.
+ * @returns {string} Joined URL path.
+ *
+ * @example
+ * joinPaths('https://example.com/', '/api/', '/users');
+ * // -> 'https://example.com/api/users'
+ */
+declare function joinPaths(...segments: string[]): string;
+/**
+ * Normalizes a URL by resolving relative paths, handling protocol-relative URLs, etc.
+ *
+ * @param {string} url - The URL to normalize.
+ * @param {string} [base] - Optional base URL for resolving relative URLs.
+ * @returns {string} Normalized URL.
+ *
+ * @example
+ * normalizeUrl('HTTP://Example.COM/foo/../bar');
+ * // -> 'http://example.com/bar'
+ */
+declare function normalizeUrl(url: string, base?: string): string;
+/**
+ * Creates a URL builder for constructing URLs with a base URL.
+ *
+ * @param {string} baseUrl - The base URL to build upon.
+ * @returns {Object} URL builder methods.
+ *
+ * @example
+ * const api = createUrlBuilder('https://api.example.com');
+ * api.path('/users', { active: true });
+ * // -> 'https://api.example.com/users?active=true'
+ */
+declare function createUrlBuilder(baseUrl: string): {
+    /**
+     * Creates a full URL with the given path and query parameters.
+     *
+     * @param {string} path - The path to append to the base URL.
+     * @param {Record<string, any>} [params] - Query parameters to add.
+     * @returns {string} The complete URL.
+     */
+    path(path: string, params?: Record<string, any>): string;
+    /**
+     * Creates a full URL with query parameters but no additional path.
+     *
+     * @param {Record<string, any>} params - Query parameters to add.
+     * @returns {string} The complete URL with query parameters.
+     */
+    query(params: Record<string, any>): string;
+};
+/**
+ * Extracts specific query parameters from a URL.
+ *
+ * @param {string} url - The URL to extract parameters from.
+ * @param {string[]} paramNames - Names of parameters to extract.
+ * @returns {Record<string, string>} Object containing the extracted parameters.
+ */
+declare function extractQueryParams(url: string, paramNames: string[]): Record<string, string>;
+/**
+ * Removes specified query parameters from a URL.
+ *
+ * @param {string} url - The URL to modify.
+ * @param {string[]} paramsToRemove - Names of parameters to remove.
+ * @returns {string} URL with parameters removed.
+ */
+declare function removeQueryParams(url: string, paramsToRemove: string[]): string;
+/**
+ * Gets the file extension from a URL path.
+ *
+ * @param {string} url - The URL to examine.
+ * @returns {string} The file extension (without dot) or empty string if none found.
+ *
+ * @example
+ * getExtension('https://example.com/document.pdf?v=1');
+ * // -> 'pdf'
+ */
+declare function getExtension(url: string): string;
+/**
+ * Parses URL query parameters into a strongly-typed object.
+ *
+ * @template T Expected type of the query parameters
+ * @param {string} url - The URL to parse.
+ * @param {Record<keyof T, (val: string) => any>} [converters] - Type converters for params.
+ * @returns {Partial<T>} Typed query parameters.
+ *
+ * @example
+ * parseTypedQueryParams<{page: number, q: string}>('https://example.com?page=2&q=test', {
+ *   page: Number,
+ *   q: String
+ * });
+ * // -> { page: 2, q: 'test' }
+ */
+declare function parseTypedQueryParams<T extends Record<string, any>>(url: string, converters?: Record<keyof T, (val: string) => any>): Partial<T>;
+
+export { appendQueryParams, createUrlBuilder, extractQueryParams, getDomain, getExtension, isValidUrl, joinPaths, normalizeUrl, parseQueryString, parseTypedQueryParams, removeQueryParams };

package/url/index.mjs

@@ -0,0 +1,187 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { URL, URLSearchParams } from 'url';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function appendQueryParams(url, params) {
+  const urlObj = new URL(url);
+  for (const [key, value] of Object.entries(params)) {
+    urlObj.searchParams.set(key, value.toString());
+  }
+  return urlObj.toString();
+}
+__name(appendQueryParams, "appendQueryParams");
+function parseQueryString(query) {
+  const cleanQuery = query.startsWith("?") ? query.slice(1) : query;
+  return Object.fromEntries(new URLSearchParams(cleanQuery));
+}
+__name(parseQueryString, "parseQueryString");
+function isValidUrl(url, requireHttps = false) {
+  try {
+    const parsedUrl = new URL(url);
+    if (!parsedUrl.protocol || !parsedUrl.hostname) return false;
+    if (requireHttps && parsedUrl.protocol !== "https:") return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isValidUrl, "isValidUrl");
+function getDomain(url, removeSubdomains = false) {
+  try {
+    const { hostname } = new URL(url);
+    if (!removeSubdomains) {
+      return hostname;
+    }
+    const parts = hostname.split(".");
+    if (parts.length <= 2) return hostname;
+    const secondLevelDomains = [
+      "co",
+      "com",
+      "org",
+      "net",
+      "gov",
+      "edu",
+      "ac"
+    ];
+    const sld = parts[parts.length - 2];
+    if (secondLevelDomains.includes(sld) && parts.length > 2) {
+      return parts.slice(-3).join(".");
+    }
+    return parts.slice(-2).join(".");
+  } catch {
+    return "";
+  }
+}
+__name(getDomain, "getDomain");
+function joinPaths(...segments) {
+  let result = segments.filter((s) => s !== void 0 && s !== null).map((segment, index) => {
+    if (index === 0) return segment.replace(/\/+$/, "");
+    return segment.replace(/^\/+|\/+$/g, "");
+  }).filter(Boolean).join("/");
+  if (segments[0] === "" && !result.startsWith("/")) result = "/" + result;
+  return result;
+}
+__name(joinPaths, "joinPaths");
+function normalizeUrl(url, base) {
+  try {
+    let normalized = url.startsWith("//") ? `https:${url}` : url;
+    const parsedUrl = base ? new URL(normalized, base) : new URL(normalized);
+    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+/g, "/");
+    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "");
+    parsedUrl.hostname = parsedUrl.hostname.toLowerCase();
+    return parsedUrl.toString();
+  } catch {
+    return url;
+  }
+}
+__name(normalizeUrl, "normalizeUrl");
+function createUrlBuilder(baseUrl) {
+  return {
+    /**
+    * Creates a full URL with the given path and query parameters.
+    *
+    * @param {string} path - The path to append to the base URL.
+    * @param {Record<string, any>} [params] - Query parameters to add.
+    * @returns {string} The complete URL.
+    */
+    path(path, params) {
+      const url = joinPaths(baseUrl, path);
+      return params ? appendQueryParams(url, params) : url;
+    },
+    /**
+    * Creates a full URL with query parameters but no additional path.
+    *
+    * @param {Record<string, any>} params - Query parameters to add.
+    * @returns {string} The complete URL with query parameters.
+    */
+    query(params) {
+      return appendQueryParams(baseUrl, params);
+    }
+  };
+}
+__name(createUrlBuilder, "createUrlBuilder");
+function extractQueryParams(url, paramNames) {
+  try {
+    const parsedUrl = new URL(url);
+    const result = {};
+    for (const name of paramNames) {
+      const value = parsedUrl.searchParams.get(name);
+      if (value !== null) {
+        result[name] = value;
+      }
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+__name(extractQueryParams, "extractQueryParams");
+function removeQueryParams(url, paramsToRemove) {
+  try {
+    const parsedUrl = new URL(url);
+    for (const param of paramsToRemove) {
+      parsedUrl.searchParams.delete(param);
+    }
+    return parsedUrl.toString();
+  } catch {
+    return url;
+  }
+}
+__name(removeQueryParams, "removeQueryParams");
+function getExtension(url) {
+  try {
+    const { pathname } = new URL(url);
+    const match = pathname.match(/\.([^./\\?#]+)$/);
+    return match ? match[1].toLowerCase() : "";
+  } catch {
+    const match = url.match(/\.([^./\\?#]+)$/);
+    return match ? match[1].toLowerCase() : "";
+  }
+}
+__name(getExtension, "getExtension");
+function parseTypedQueryParams(url, converters) {
+  try {
+    const { searchParams } = new URL(url);
+    const result = {};
+    for (const [key, value] of searchParams.entries()) {
+      if (converters && key in converters) {
+        try {
+          result[key] = converters[key](value);
+        } catch {
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+__name(parseTypedQueryParams, "parseTypedQueryParams");
+
+export { appendQueryParams, createUrlBuilder, extractQueryParams, getDomain, getExtension, isValidUrl, joinPaths, normalizeUrl, parseQueryString, parseTypedQueryParams, removeQueryParams };