universal-common/UriBuilder.d.ts

Library that provides useful missing base class library functionality.

/**
 * A builder class for constructing and manipulating URIs (Uniform Resource Identifiers).
 * Follows the builder pattern to allow fluent chaining of operations.
 *
 * This class provides methods to:
 * - Set and manipulate URI components (scheme, host, path, query parameters, etc.)
 * - Build complete URI strings
 * - Parse existing URIs into modifiable components
 */
export default class UriBuilder {
    /**
     * Creates a new UriBuilder instance.
     *
     * @overload
     * @description Creates an empty UriBuilder
     *
     * @overload
     * @param {string} uri - An existing URI to parse and use as a starting point
     *
     * @overload
     * @param {string} scheme - The URI scheme (e.g., "http", "https")
     * @param {string} host - The hostname (e.g., "example.com")
     *
     * @overload
     * @param {string} scheme - The URI scheme
     * @param {string} host - The hostname
     * @param {number|string} port - The port number
     *
     * @throws {ArgumentError} If invalid arguments are provided
     */
    constructor(...args: any[]);
    /**
     * Sets the URI scheme.
     * @param {string} value - The scheme to set
     */
    set scheme(arg: string);
    /**
     * Gets the URI scheme.
     * @returns {string?} The scheme component
     */
    get scheme(): string;
    /**
     * Sets the hostname.
     * @param {string} value - The hostname to set
     */
    set host(arg: string);
    /**
     * Gets the hostname.
     * @returns {string?} The host component
     */
    get host(): string;
    /**
     * Sets the username for authentication.
     * @param {string} value - The username to set
     */
    set username(arg: string);
    /**
     * Gets the username for authentication.
     * @returns {string?} The username component
     */
    get username(): string;
    /**
     * Sets the password for authentication.
     * @param {string} value - The password to set
     */
    set password(arg: string);
    /**
     * Gets the password for authentication.
     * @returns {string?} The password component
     */
    get password(): string;
    /**
     * Sets the port number.
     * @param {number|string} value - The port to set
     */
    set port(arg: number);
    /**
     * Gets the port number.
     * @returns {number?} The port component
     */
    get port(): number;
    /**
     * Gets the complete path as a string.
     * @returns {string} The path component with leading and trailing slashes
     */
    get path(): string;
    /**
     * Gets the query string.
     * @returns {string} The query component as a string
     */
    get query(): string;
    /**
     * Gets a copy of the path segments array.
     * @returns {Array<string>} Array of path segments
     */
    get segments(): string[];
    /**
     * Adds a single path segment.
     * @param {string} value - The path segment to add
     * @returns {UriBuilder} This builder instance for method chaining
     */
    addSegment(value: string): UriBuilder;
    /**
     * Adds multiple path segments.
     * Accepts either an array of segments or multiple segment arguments.
     *
     * @param {...string|Array<string>} segments - Path segments to add
     * @returns {UriBuilder} This builder instance for method chaining
     *
     * Usage examples:
     *   builder.addSegments("api", "v1", "users");
     *   builder.addSegments(["api", "v1", "users"]);
     */
    addSegments(...args: (string | string[])[]): UriBuilder;
    /**
     * Adds a query parameter.
     * @param {string} name - The parameter name
     * @param {string} value - The parameter value
     * @returns {UriBuilder} This builder instance for method chaining
     */
    addQuery(name: string, value: string): UriBuilder;
    /**
     * Adds multiple query parameters from an object or Map.
     * @param {Object|Map} queries - Object or Map containing name-value pairs
     * @returns {UriBuilder} This builder instance for method chaining
     *
     * Usage examples:
     *   builder.addQueries({ page: 1, limit: 10 });
     *   builder.addQueries(new Map([["page", 1], ["limit", 10]]));
     */
    addQueries(queries: any | Map<any, any>): UriBuilder;
    /**
     * Builds and returns the complete URI string.
     * @returns {string} The complete URI
     * @throws {Error} If scheme or host are not specified
     */
    get uri(): string;
    #private;
}