@fluixi/utils 1.0.0-alpha.100

package/dist/lib/url/parser.cjs

@@ -0,0 +1,325 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/url/parser.ts
+var parser_exports = {};
+__export(parser_exports, {
+  addQueryParams: () => addQueryParams,
+  buildUrl: () => buildUrl,
+  extractUrls: () => extractUrls,
+  getDomain: () => getDomain,
+  getQueryParam: () => getQueryParam,
+  getQueryParams: () => getQueryParams,
+  getUrlExtension: () => getUrlExtension,
+  isAbsoluteUrl: () => isAbsoluteUrl,
+  isRelativeUrl: () => isRelativeUrl,
+  isSameOrigin: () => isSameOrigin,
+  isValidUrl: () => isValidUrl,
+  joinUrl: () => joinUrl,
+  matchesUrlPattern: () => matchesUrlPattern,
+  normalizeUrl: () => normalizeUrl,
+  parseQueryString: () => parseQueryString,
+  parseQueryStringAdvanced: () => parseQueryStringAdvanced,
+  parseUrl: () => parseUrl,
+  removeQueryParams: () => removeQueryParams,
+  sanitizeUrl: () => sanitizeUrl,
+  toAbsoluteUrl: () => toAbsoluteUrl,
+  toQueryString: () => toQueryString,
+  url_parser: () => url_parser
+});
+module.exports = __toCommonJS(parser_exports);
+var url_parser = (url) => {
+  try {
+    const p = new URL(url);
+    return {
+      hash: p.hash,
+      host: p.host,
+      hostname: p.hostname,
+      href: p.href,
+      origin: p.origin,
+      pathname: p.pathname,
+      port: p.port,
+      search: p.search,
+      searchParams: p.searchParams.toString(),
+      protocol: p.protocol
+    };
+  } catch (e) {
+    return null;
+  }
+};
+function parseUrl(url) {
+  return url_parser(url);
+}
+function isValidUrl(url) {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isAbsoluteUrl(url) {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isRelativeUrl(url) {
+  return !isAbsoluteUrl(url);
+}
+function parseQueryString(queryString) {
+  const params = {};
+  const searchParams = new URLSearchParams(queryString);
+  searchParams.forEach((value, key) => {
+    params[key] = value;
+  });
+  return params;
+}
+function parseQueryStringAdvanced(queryString) {
+  const params = {};
+  const searchParams = new URLSearchParams(queryString);
+  searchParams.forEach((value, key) => {
+    if (params[key]) {
+      if (Array.isArray(params[key])) {
+        params[key].push(value);
+      } else {
+        params[key] = [params[key], value];
+      }
+    } else {
+      params[key] = value;
+    }
+  });
+  return params;
+}
+function toQueryString(params, options = {}) {
+  const { encode = true, arrayFormat = "repeat" } = options;
+  const searchParams = new URLSearchParams();
+  Object.entries(params).forEach(([key, value]) => {
+    if (value === null || value === void 0) return;
+    if (Array.isArray(value)) {
+      value.forEach((v) => {
+        if (arrayFormat === "brackets") {
+          searchParams.append(`${key}[]`, String(v));
+        } else {
+          searchParams.append(key, String(v));
+        }
+      });
+    } else {
+      searchParams.append(key, String(value));
+    }
+  });
+  let result = searchParams.toString();
+  if (!encode) {
+    result = decodeURIComponent(result);
+  }
+  return result;
+}
+function addQueryParams(url, params) {
+  try {
+    const urlObj = new URL(url);
+    Object.entries(params).forEach(([key, value]) => {
+      if (value === null || value === void 0) {
+        urlObj.searchParams.delete(key);
+      } else if (Array.isArray(value)) {
+        urlObj.searchParams.delete(key);
+        value.forEach((v) => urlObj.searchParams.append(key, String(v)));
+      } else {
+        urlObj.searchParams.set(key, String(value));
+      }
+    });
+    return urlObj.toString();
+  } catch {
+    return url;
+  }
+}
+function removeQueryParams(url, ...keys) {
+  try {
+    const urlObj = new URL(url);
+    keys.forEach((key) => urlObj.searchParams.delete(key));
+    return urlObj.toString();
+  } catch {
+    return url;
+  }
+}
+function getQueryParam(url, key) {
+  try {
+    const urlObj = new URL(url);
+    return urlObj.searchParams.get(key);
+  } catch {
+    return null;
+  }
+}
+function getQueryParams(url, key) {
+  try {
+    const urlObj = new URL(url);
+    return urlObj.searchParams.getAll(key);
+  } catch {
+    return [];
+  }
+}
+function buildUrl(components) {
+  const {
+    protocol = "https",
+    hostname,
+    port,
+    pathname = "",
+    query,
+    hash
+  } = components;
+  let url = `${protocol}://${hostname}`;
+  if (port) {
+    url += `:${port}`;
+  }
+  if (pathname) {
+    url += pathname.startsWith("/") ? pathname : `/${pathname}`;
+  }
+  if (query && Object.keys(query).length > 0) {
+    url += `?${toQueryString(query)}`;
+  }
+  if (hash) {
+    url += hash.startsWith("#") ? hash : `#${hash}`;
+  }
+  return url;
+}
+function joinUrl(base, ...paths) {
+  try {
+    const url = new URL(base);
+    const basePath = url.pathname === "/" ? "" : url.pathname;
+    const pathParts = [basePath, ...paths].filter(Boolean).map((part) => part.replace(/^\/+|\/+$/g, ""));
+    url.pathname = "/" + pathParts.filter(Boolean).join("/");
+    return url.toString();
+  } catch {
+    const parts = [base, ...paths].filter(Boolean).map((part) => part.replace(/^\/+|\/+$/g, ""));
+    return "/" + parts.join("/");
+  }
+}
+function normalizeUrl(url, options = {}) {
+  const {
+    removeTrailingSlash = true,
+    removeDefaultPort = true,
+    sortQuery = false
+  } = options;
+  try {
+    const urlObj = new URL(url);
+    if (removeDefaultPort) {
+      if (urlObj.protocol === "http:" && urlObj.port === "80" || urlObj.protocol === "https:" && urlObj.port === "443") {
+        urlObj.port = "";
+      }
+    }
+    if (removeTrailingSlash && urlObj.pathname.endsWith("/") && urlObj.pathname !== "/") {
+      urlObj.pathname = urlObj.pathname.slice(0, -1);
+    }
+    if (sortQuery) {
+      const params = Array.from(urlObj.searchParams.entries());
+      params.sort((a, b) => a[0].localeCompare(b[0]));
+      urlObj.search = new URLSearchParams(params).toString();
+    }
+    return urlObj.toString();
+  } catch {
+    return url;
+  }
+}
+function getDomain(url, options = {}) {
+  const { includeSubdomain = false } = options;
+  try {
+    const urlObj = new URL(url);
+    const hostname = urlObj.hostname;
+    if (includeSubdomain) {
+      return hostname;
+    }
+    const parts = hostname.split(".");
+    if (parts.length >= 2) {
+      return parts.slice(-2).join(".");
+    }
+    return hostname;
+  } catch {
+    return null;
+  }
+}
+function getUrlExtension(url) {
+  try {
+    const urlObj = new URL(url);
+    const pathname = urlObj.pathname;
+    const lastDot = pathname.lastIndexOf(".");
+    const lastSlash = pathname.lastIndexOf("/");
+    if (lastDot > lastSlash && lastDot < pathname.length - 1) {
+      return pathname.slice(lastDot + 1);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function isSameOrigin(url1, url2) {
+  try {
+    const urlObj1 = new URL(url1);
+    const urlObj2 = new URL(url2);
+    return urlObj1.origin === urlObj2.origin;
+  } catch {
+    return false;
+  }
+}
+function toAbsoluteUrl(relativeUrl, baseUrl) {
+  try {
+    return new URL(relativeUrl, baseUrl).toString();
+  } catch {
+    return relativeUrl;
+  }
+}
+function sanitizeUrl(url) {
+  const dangerousProtocols = ["javascript:", "data:", "vbscript:"];
+  try {
+    const urlObj = new URL(url);
+    if (dangerousProtocols.some((proto) => urlObj.protocol === proto)) {
+      return null;
+    }
+    return url;
+  } catch {
+    const lower = url.toLowerCase().trim();
+    if (dangerousProtocols.some((proto) => lower.startsWith(proto))) {
+      return null;
+    }
+    return url;
+  }
+}
+function extractUrls(text, options = {}) {
+  const { unique = true } = options;
+  const urlRegex = /https?:\/\/[^\s<>"{}|\\^`\]]+/gi;
+  const matches = text.match(urlRegex) || [];
+  return unique ? Array.from(new Set(matches)) : matches;
+}
+function matchesUrlPattern(url, pattern) {
+  try {
+    const urlObj = new URL(url);
+    const patternObj = new URL(pattern);
+    if (patternObj.protocol !== "*:" && urlObj.protocol !== patternObj.protocol) {
+      return false;
+    }
+    if (patternObj.hostname !== "*" && urlObj.hostname !== patternObj.hostname) {
+      return false;
+    }
+    const pathPattern = patternObj.pathname.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const pathRegex = new RegExp(`^${pathPattern}$`);
+    return pathRegex.test(urlObj.pathname);
+  } catch {
+    return false;
+  }
+}

package/dist/lib/url/parser.d.ts

@@ -0,0 +1,216 @@
+import type { URL_PARSER } from './types.js';
+export declare const url_parser: (url: string) => URL_PARSER | null;
+/**
+ * Parses a URL and returns its components
+ * @param url - URL string to parse
+ * @returns Parsed URL components or null if invalid
+ * @example
+ * parseUrl('https://example.com:8080/path?q=search#hash');
+ * // { protocol: 'https:', hostname: 'example.com', port: '8080', ... }
+ */
+export declare function parseUrl(url: string): URL_PARSER | null;
+/**
+ * Checks if a string is a valid URL
+ * @param url - String to validate
+ * @returns True if valid URL
+ * @example
+ * isValidUrl('https://example.com'); // true
+ * isValidUrl('not a url'); // false
+ */
+export declare function isValidUrl(url: string): boolean;
+/**
+ * Checks if a URL is absolute
+ * @param url - URL string to check
+ * @returns True if absolute URL
+ * @example
+ * isAbsoluteUrl('https://example.com/path'); // true
+ * isAbsoluteUrl('/path'); // false
+ */
+export declare function isAbsoluteUrl(url: string): boolean;
+/**
+ * Checks if a URL is relative
+ * @param url - URL string to check
+ * @returns True if relative URL
+ * @example
+ * isRelativeUrl('/path'); // true
+ * isRelativeUrl('https://example.com'); // false
+ */
+export declare function isRelativeUrl(url: string): boolean;
+/**
+ * Parses query string into an object
+ * @param queryString - Query string (with or without leading ?)
+ * @returns Object with parsed parameters
+ * @example
+ * parseQueryString('?name=John&age=30'); // { name: 'John', age: '30' }
+ */
+export declare function parseQueryString(queryString: string): Record<string, string>;
+/**
+ * Parses query string into an object with array support
+ * @param queryString - Query string
+ * @returns Object with parsed parameters (arrays for repeated keys)
+ * @example
+ * parseQueryStringAdvanced('?tags=js&tags=ts'); // { tags: ['js', 'ts'] }
+ */
+export declare function parseQueryStringAdvanced(queryString: string): Record<string, string | string[]>;
+/**
+ * Converts an object to a query string
+ * @param params - Object with parameters
+ * @param options - Serialization options
+ * @returns Query string
+ * @example
+ * toQueryString({ name: 'John', age: 30 }); // 'name=John&age=30'
+ */
+export declare function toQueryString(params: Record<string, any>, options?: {
+    encode?: boolean;
+    arrayFormat?: 'brackets' | 'repeat';
+}): string;
+/**
+ * Adds or updates query parameters in a URL
+ * @param url - Base URL
+ * @param params - Parameters to add/update
+ * @returns URL with updated parameters
+ * @example
+ * addQueryParams('https://example.com', { q: 'search' });
+ * // 'https://example.com?q=search'
+ */
+export declare function addQueryParams(url: string, params: Record<string, any>): string;
+/**
+ * Removes query parameters from a URL
+ * @param url - URL to modify
+ * @param keys - Parameter keys to remove
+ * @returns URL without specified parameters
+ * @example
+ * removeQueryParams('https://example.com?a=1&b=2', 'a');
+ * // 'https://example.com?b=2'
+ */
+export declare function removeQueryParams(url: string, ...keys: string[]): string;
+/**
+ * Gets a specific query parameter from a URL
+ * @param url - URL to parse
+ * @param key - Parameter key
+ * @returns Parameter value or null
+ * @example
+ * getQueryParam('https://example.com?name=John', 'name'); // 'John'
+ */
+export declare function getQueryParam(url: string, key: string): string | null;
+/**
+ * Gets all values for a query parameter (for repeated parameters)
+ * @param url - URL to parse
+ * @param key - Parameter key
+ * @returns Array of parameter values
+ * @example
+ * getQueryParams('https://example.com?tags=js&tags=ts', 'tags');
+ * // ['js', 'ts']
+ */
+export declare function getQueryParams(url: string, key: string): string[];
+/**
+ * Builds a URL from components
+ * @param components - URL components
+ * @returns Built URL
+ * @example
+ * buildUrl({
+ *   protocol: 'https',
+ *   hostname: 'example.com',
+ *   pathname: '/path',
+ *   query: { q: 'search' }
+ * }); // 'https://example.com/path?q=search'
+ */
+export declare function buildUrl(components: {
+    protocol?: string;
+    hostname: string;
+    port?: string | number;
+    pathname?: string;
+    query?: Record<string, any>;
+    hash?: string;
+}): string;
+/**
+ * Joins URL paths, handling slashes correctly
+ * @param base - Base URL or path
+ * @param paths - Path segments to join
+ * @returns Joined URL
+ * @example
+ * joinUrl('https://example.com', 'api', 'users', '123');
+ * // 'https://example.com/api/users/123'
+ */
+export declare function joinUrl(base: string, ...paths: string[]): string;
+/**
+ * Normalizes a URL (removes default ports, trailing slashes, etc.)
+ * @param url - URL to normalize
+ * @param options - Normalization options
+ * @returns Normalized URL
+ * @example
+ * normalizeUrl('https://example.com:443/path/'); // 'https://example.com/path'
+ */
+export declare function normalizeUrl(url: string, options?: {
+    removeTrailingSlash?: boolean;
+    removeDefaultPort?: boolean;
+    sortQuery?: boolean;
+}): string;
+/**
+ * Extracts the domain from a URL
+ * @param url - URL to parse
+ * @param options - Extraction options
+ * @returns Domain name
+ * @example
+ * getDomain('https://subdomain.example.com/path'); // 'example.com'
+ */
+export declare function getDomain(url: string, options?: {
+    includeSubdomain?: boolean;
+}): string | null;
+/**
+ * Gets the file extension from a URL
+ * @param url - URL to parse
+ * @returns File extension (without dot) or null
+ * @example
+ * getUrlExtension('https://example.com/image.jpg'); // 'jpg'
+ */
+export declare function getUrlExtension(url: string): string | null;
+/**
+ * Checks if URLs are from the same origin
+ * @param url1 - First URL
+ * @param url2 - Second URL
+ * @returns True if same origin
+ * @example
+ * isSameOrigin('https://example.com/a', 'https://example.com/b'); // true
+ */
+export declare function isSameOrigin(url1: string, url2: string): boolean;
+/**
+ * Converts a relative URL to absolute using a base URL
+ * @param relativeUrl - Relative URL
+ * @param baseUrl - Base URL
+ * @returns Absolute URL
+ * @example
+ * toAbsoluteUrl('/path', 'https://example.com'); // 'https://example.com/path'
+ */
+export declare function toAbsoluteUrl(relativeUrl: string, baseUrl: string): string;
+/**
+ * Sanitizes a URL by removing dangerous protocols and characters
+ * @param url - URL to sanitize
+ * @returns Sanitized URL or null if dangerous
+ * @example
+ * sanitizeUrl('javascript:alert(1)'); // null
+ * sanitizeUrl('https://example.com'); // 'https://example.com'
+ */
+export declare function sanitizeUrl(url: string): string | null;
+/**
+ * Extracts all URLs from a text string
+ * @param text - Text to search
+ * @param options - Extraction options
+ * @returns Array of found URLs
+ * @example
+ * extractUrls('Check out https://example.com and http://test.com');
+ * // ['https://example.com', 'http://test.com']
+ */
+export declare function extractUrls(text: string, options?: {
+    unique?: boolean;
+}): string[];
+/**
+ * Checks if a URL matches a pattern (with wildcard support)
+ * @param url - URL to test
+ * @param pattern - Pattern with wildcards (* and **)
+ * @returns True if matches
+ * @example
+ * matchesUrlPattern('https://example.com/api/users/123', 'https://example.com/api/*'); // true
+ */
+export declare function matchesUrlPattern(url: string, pattern: string): boolean;
+//# sourceMappingURL=parser.d.ts.map

package/dist/lib/url/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/lib/url/parser.ts"],"names":[],"mappings":"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"}