@resk/core/build/utils/uri/index.d.ts

An innovative TypeScript framework that empowers developers to build applications with a fully decorator-based architecture for efficient resource management. By combining the power of decorators with a resource-oriented design, DecorRes enhances code cla

import { IParseBaseOptions, IStringifyBaseOptions } from "qs";
import { IDict } from "../../types";
/**
 * Returns the query string from a given URL.
 *
 * This function takes a URL and an optional flag as input.
 * It parses the URL to extract the query string, which is the part of the URL after the `?` character.
 * If the `addQuestionSeparator` flag is true, the query string is returned with a leading `?` character.
 *
 * @param uri The URL to extract the query string from.
 * @param addQuestionSeparator Whether to include the `?` character in the returned query string (default: true).
 * @returns The query string associated with the given URL.
 * @example
 * ```typescript
 * const url = 'https://example.com/path?a=1&b=2';
 * console.log(extractQueryString(url)); // Output: "?a=1&b=2"
 * console.log(extractQueryString(url, false)); // Output: "a=1&b=2"
 * ```
 */
export declare const extractQueryString: (uri?: string, addQuestionSeparator?: boolean) => string;
/**
 * Returns the query parameters from a given URL as an object.
 *
 * This function takes a URL and an optional options object as input.
 * It extracts the query string from the URL using the `extractQueryString` function and then parses it into an object using the `queryString.parse` method.
 * The `queryString.parse` method is configured to allow sparse arrays and to merge the provided options with the default options.
 *
 * @param uri The URL to extract the query parameters from.
 * @param queryStringOpts Options for the `queryString.parse` method (default: {}).
 * @returns An object containing the query parameters.
 * @example
 * ```typescript
 * const url = 'https://example.com/path?a=1&b=2&c[]=3&c[]=4';
 * console.log(getQueryParams(url)); // Output: { a: '1', b: '2', c: [ '3', '4' ] }
 * ```
 */
export declare const getQueryParams: (uri: string | null | undefined, queryStringOpts?: IParseBaseOptions) => IDict;
/**
 * Removes the query string from a given URL and returns the resulting URL.
 *
 * This function takes a URL and an optional flag as input.
 * It removes the query string and any fragment identifier from the URL using regular expressions.
 * If the `_decodeURIComponent` flag is true, the resulting URL is decoded using the `decodeURIComponent` function.
 *
 * @param uri The URL to remove the query string from.
 * @param _decodeURIComponent Whether to decode the resulting URL using `decodeURIComponent` (default: false).
 * @returns The URL with the query string removed.
 * @example
 * ```typescript
 * const url = 'https://example.com/path?a=1&b=2#fragment';
 * console.log(removeQueryString(url)); // Output: "https://example.com/path"
 * console.log(removeQueryString(url, true)); // Output: "https://example.com/path" (decoded)
 * ```
 */
export declare const removeQueryString: (uri: string | undefined | null, _decodeURIComponent?: boolean) => string;
/**
 * Adds query parameters to a given URL.
 *
 * This function takes a URL, a key-value pair or an object of key-value pairs, and optional options as input.
 * It removes any existing query string from the URL, merges the new query parameters with the existing ones, and then appends the resulting query string to the URL.
 *
 * @param url The URL to add query parameters to.
 * @param key A string key or an object of key-value pairs to add to the query string.
 * @param value The value associated with the key, only applicable when key is a string.
 * @param options Options for the `queryString.stringify` method (default: {}).
 * @returns The URL with the query parameters added.
 * @example
 * ```typescript
 * const url = 'https://example.com/path';
 * console.log(setQueryParams(url, 'a', 1)); // Output: "https://example.com/path?a=1"
 * console.log(setQueryParams(url, { a: 1, b: 2 })); // Output: "https://example.com/path?a=1&b=2"
 * ```
 */
export declare function setQueryParams(url: string | undefined | null, key: any, value?: any, options?: IStringifyBaseOptions): string;
/**
 * Converts an object to a query string.
 *
 * This function takes an object and an optional flag as input.
 * It recursively iterates through the object's properties and converts them to a query string format.
 * If the `encodeURI` flag is true, the values are encoded using the `encodeURIComponent` function.
 *
 * @param o The object to convert to a query string.
 * @param encodeURI Whether to encode the values using `encodeURIComponent` (default: false).
 * @returns The object converted to a query string.
 * @example
 * ```typescript
 * const obj = { a: 1, b: 2, c: { d: 3, e: 4 } };
 * console.log(objectToQueryString(obj)); // Output: "a=1&b=2&c[d]=3&c[e]=4"
 * console.log(objectToQueryString(obj, true)); // Output: "a=1&b=2&c%5Bd%5D=3&c%5Be%5D=4"
 * ```
 */
export declare function objectToQueryString(o: any, encodeURI?: boolean): string;
/**
 * Parses a URI and returns the parsed object.
 *
 * This function takes a URI as input and returns an object containing the parsed components of the URI.
 * The object includes properties for the hash, host, hostname, href, origin, pathname, port, protocol, search, username, and password.
 *
 * @param uri The URI to parse.
 * @returns The parsed URI object.
 * @example
 * ```typescript
 * const uri = 'http://username:password@localhost:257/deploy/?asd=asd#asd';
 * console.log(parseURI(uri));
 * // Output:
 * // {
 * //   hash: "#asd",
 * //   host: "localhost:257",
 * //   hostname: "localhost",
 * //   href: "http://username:password@localhost:257/deploy/?asd=asd#asd",
 * //   origin: "http://username:password@localhost:257",
 * //   pathname: "/deploy/",
 * //   port: "257",
 * //   protocol: "http:",
 * //   search: "?asd=asd",
 * //   username: "username",
 * //   password: "password"
 * // }
 * ```
 */
export declare const parseURI: (uri: string | null | undefined) => {
    hash?: string;
    host?: string;
    hostname?: string;
    href?: string;
    origin?: string;
    pathname?: string;
    port?: string;
    protocol?: string;
    search?: string;
    username?: string;
    password?: string;
};
/**
 * Checks if the provided value is a valid URL/URI.
 *
 * This function determines whether the string passed as the parameter
 * `uri` is a valid URL or URI. It performs the following checks:
 *
 * 1. **Non-null String Check**: The function uses `isNonNullString` to
 *    ensure that `uri` is a non-null string.
 *
 * 2. **URL/URI Validation**: The function then tests the string against
 *    a regular expression that checks if the string has the structure
 *    of a valid URL. The regular expression verifies the following:
 *    - An optional scheme (like `http://` or `https://`).
 *    - A domain name that can either be a fully qualified domain name
 *      or `localhost`.
 *    - An optional port and other URL components.
 *
 * The function returns `true` if the provided string is a valid URL/URI;
 * otherwise, it returns `false`.
 *
 * @param {any} uri - The string to check as a valid URL/URI.
 * @returns {boolean} - Returns `true` if the string is a valid URL/URI,
 *                      `false` otherwise.
 *
 * @example
 * // Valid URLs
 * console.log(isValidUrl('http://example.com')); // true
 * console.log(isValidUrl('https://localhost:3000')); // true
 * console.log(isValidUrl('ftp://files.example.com')); // true
 *
 * // Invalid URLs
 * console.log(isValidUrl(null)); // false
 * console.log(isValidUrl('')); // false
 * console.log(isValidUrl('not-a-valid-url')); // false
 * console.log(isValidUrl('http://256.256.256.256')); // false (invalid IP address)
 */
export declare const isValidUrl: (uri: any) => boolean;
/**
 * Detects if a URL string has been encoded using encodeURIComponent.
 *
 * This function uses multiple heuristics to determine if a string has been
 * encoded with encodeURIComponent. It checks for:
 * 1. Presence of valid encoded character sequences (%XX where XX are hex digits)
 * 2. Whether decoding changes the string (indicating encoded content)
 * 3. Handles mixed encoded/unencoded content properly
 *
 * @param {any} str - The string to check for encoding
 * @returns {boolean} - Returns true if the string appears to be encoded, false otherwise
 *
 * @example
 * console.log(isUriEncoded('hello%20world')); // true
 * console.log(isUriEncoded('hello world')); // false
 * console.log(isUriEncoded('hello%2Bworld')); // true
 * console.log(isUriEncoded('hello+world')); // false
 * console.log(isUriEncoded('https%3A%2F%2Fexample.com')); // true
 * console.log(isUriEncoded('https://example.com')); // false
 * console.log(isUriEncoded('hello%20world%21normal')); // true (mixed)
 */
export declare const isUriEncoded: (str: any) => boolean;