logitar-js/dist/helpers/urlUtils.d.ts

Helper functions distributed by Logitar.

/**
 * Represents credentials to be used in an authentication system.
 */
export declare class Credentials implements ICredentials {
    private identifier;
    /**
     * Returns the identifier of the credentials, typically an username.
     * @returns The identifier of the credentials.
     */
    getIdentifier(): string;
    /**
     * Sets the identifier of the credentials, typically an username.
     * @param identifier The identifier to set.
     */
    setIdentifier(identifier: string): void;
    private secret;
    /**
     * Returns the secret of the credentials, typically a password.
     * @returns The secret of the credentials.
     */
    getSecret(): string;
    /**
     * Sets the secret of the credentials, typically a password.
     * @param secret The secret to set.
     */
    setSecret(secret: string): void;
    /**
     * Creates a new instance of the `Credentials` class.
     * @param identifier The identifier of the credentials, typically an username.
     * @param secret The secret of the credentials, typically a password.
     */
    constructor(identifier?: string, secret?: string);
    /**
     * Parses the specified credentials using the `{identifier}:{secret}` format into a new instance of the `Credentials` class.
     * @param credentials
     * @returns The created instance.
     */
    static parse(credentials?: string): Credentials | undefined;
}
/**
 * Defines credentials to be used in an authentication system.
 */
export interface ICredentials {
    /**
     * Returns the identifier of the credentials, typically an username.
     * @returns The identifier of the credentials.
     */
    getIdentifier(): string;
    /**
     * Returns the secret of the credentials, typically a password.
     * @returns The secret of the credentials.
     */
    getSecret(): string;
}
/**
 * Defines a builder class used to build URLs.
 */
export interface IUrlBuilder {
    /**
     * Returns the scheme of the URL.
     * @returns The scheme of the URL.
     */
    getScheme(): string;
    /**
     * Sets the scheme of the URL.
     * @param scheme The scheme to set.
     * @param inferPort If true, the port will be inferred from the scheme.
     * @returns The instance of the builder.
     */
    setScheme(scheme: string, inferPort?: boolean): IUrlBuilder;
    /**
     * Returns the credentials of the URL.
     * @returns The credentials of the URL.
     */
    getCredentials(): ICredentials | undefined;
    /**
     * Sets the credentials of the URL.
     * @param credentials The credentials to set.
     * @returns The instance of the builder.
     */
    setCredentials(credentials?: ICredentials): IUrlBuilder;
    /**
     * Returns the host of the URL.
     * @returns The host of the URL.
     */
    getHost(): string;
    /**
     * Sets the host of the URL. The default host will be set if the specified host is empty.
     * @param host The host of the URL.
     * @returns The instance of the builder.
     */
    setHost(host: string): IUrlBuilder;
    /**
     * Returns the port of the URL.
     * @returns The port of the URL.
     */
    getPort(): number;
    /**
     * Sets the portal of the URL.
     * @param port The port of the URL.
     * @returns The instance of the builder.
     */
    setPort(port: number): IUrlBuilder;
    /**
     * Returns the authority of the URL.
     * @returns The authority of the URL.
     */
    getAuthority(): string;
    /**
     * Sets the authority of the URL.
     * @param authority The authority of the URL.
     * @returns The instance of the builder.
     */
    setAuthority(authority: string): IUrlBuilder;
    /**
     * Returns the list of segments of the URL path.
     * @returns The segments of the URL.
     */
    getSegments(): string[];
    /**
     * Sets the segments of the URL path. Empty segments will be discarded.
     * @param segments The segments of the URL.
     * @returns The instance of the builder.
     */
    setSegments(segments: string[]): IUrlBuilder;
    /**
     * Returns the path of the URL.
     * @returns The path of the URL.
     */
    getPath(): string | undefined;
    /**
     * Sets the path of the URL.
     * @param path The path of the URL.
     * @returns The instance of the builder.
     */
    setPath(path?: string): IUrlBuilder;
    /**
     * Returns the query parameters of the URL.
     * @returns The query parameters of the URL.
     */
    getQuery(): Map<string, string[]>;
    /**
     * Returns the query string of the URL.
     * @returns The query string of the URL.
     */
    getQueryString(): string | undefined;
    /**
     * Adds a query parameter to the URL. The specified value will be appended to existing values associated to this key. Empty keys and values will be discarded.
     * @param key The key of the parameter.
     * @param values The value of the parameter.
     * @returns The instance of the builder.
     */
    addQuery(key: string, value: string): IUrlBuilder;
    /**
     * Adds a query parameter to the URL. The specified values will be appended to existing values associated to this key. Empty keys and values will be discarded.
     * @param key The key of the parameter.
     * @param values The values of the parameter.
     * @returns The instance of the builder.
     */
    addQuery(key: string, values: string[]): IUrlBuilder;
    /**
     * Sets a query parameter to the URL. The specified value will replace the existing values associated to this key. Empty keys and values will be discarded.
     * @param key The key of the parameter.
     * @param values The value of the parameter.
     * @returns The instance of the builder.
     */
    setQuery(key: string, value: string): IUrlBuilder;
    /**
     * Sets a query parameter to the URL. The specified values will replace the existing values associated to this key. Empty keys and values will be discarded.
     * @param key The key of the parameter.
     * @param values The values of the parameter.
     * @returns The instance of the builder.
     */
    setQuery(key: string, values: string[]): IUrlBuilder;
    /**
     * Sets the query string of the URL. Empty keys and values will be discarded.
     * @param queryString The query string of the URL.
     * @returns The instance of the builder.
     */
    setQueryString(queryString?: string): IUrlBuilder;
    /**
     * Returns the fragment of the URL.
     * @returns The fragment of the URL.
     */
    getFragment(): string | undefined;
    /**
     * Sets the fragment of the URL.
     * @param fragment The fragment of the URL.
     * @returns The instance of the builder.
     */
    setFragment(fragment?: string): IUrlBuilder;
    /**
     * Returns the parameters of the URL. Parameters are tokens that replace values in built URLs.
     * @returns The parameters of the URL.
     */
    getParameters(): Map<string, string>;
    /**
     * Sets a parameter of the URL. Parameters are tokens that replace values in built URLs.
     * @param key The key of the parameter.
     * @param value The value of the parameter.
     * @returns The instance of the builder.
     * @throws {Error} The key is empty.
     */
    setParameter(key: string, value?: string): IUrlBuilder;
    /**
     * Builds an URL of the specified kind.
     * @param kind The URL kind (defaults to `Absolute`).
     * @returns The built URL.
     */
    build(kind?: UriKind): string;
    /**
     * Builds an absolute URL.
     * @returns The built URL.
     */
    buildAbsolute(): string;
    /**
     * Builds a relative URL.
     * @returns The built URL.
     */
    buildRelative(): string;
}
/**
 * Defines the supported URL kinds.
 */
export type UriKind = "Absolute" | "Relative";
/**
 * Represents a builder class used to build URLs.
 */
export declare class UrlBuilder implements IUrlBuilder {
    /**
     * The default URL scheme.
     */
    static readonly DEFAULT_SCHEME = "http";
    /**
     * The default URL host.
     */
    static readonly DEFAULT_HOST = "localhost";
    private static supportedSchemes;
    /**
     * Returns the list of supported URL schemes.
     * @returns The supported URL schemes.
     */
    static getSupportedSchemes(): string[];
    /**
     * Returns a value indicating whether or not the specified scheme is supported.
     * @param scheme The scheme to check.
     * @returns True if the scheme is supported, or false otherwise.
     */
    static isSchemeSupported(scheme: string): boolean;
    private scheme;
    /**
     * Returns the scheme of the URL.
     * @returns The scheme of the URL.
     */
    getScheme(): string;
    /**
     * Sets the scheme of the URL.
     * @param scheme The scheme to set.
     * @param inferPort If true, the port will be inferred from the scheme.
     * @returns The instance of the builder.
     * @throws {Error} The scheme is not supported.
     */
    setScheme(scheme: string, inferPort?: boolean): IUrlBuilder;
    private credentials?;
    /**
     * Returns the credentials of the URL.
     * @returns The credentials of the URL.
     */
    getCredentials(): ICredentials | undefined;
    /**
     * Sets the credentials of the URL.
     * @param credentials The credentials to set.
     * @returns The instance of the builder.
     */
    setCredentials(credentials?: ICredentials): IUrlBuilder;
    private host;
    /**
     * Returns the host of the URL.
     * @returns The host of the URL.
     */
    getHost(): string;
    /**
     * Sets the host of the URL. The default host will be set if the specified host is empty.
     * @param host The host of the URL.
     * @returns The instance of the builder.
     */
    setHost(host: string): IUrlBuilder;
    private port;
    /**
     * Returns the port of the URL.
     * @returns The port of the URL.
     */
    getPort(): number;
    /**
     * Sets the portal of the URL.
     * @param port The port of the URL.
     * @returns The instance of the builder.
     * @throws {Error} The port is not a number or not within port ranges (0-65535).
     */
    setPort(port: number): IUrlBuilder;
    /**
     * Returns the authority of the URL.
     * @returns The authority of the URL.
     */
    getAuthority(): string;
    /**
     * Sets the authority of the URL.
     * @param authority The authority of the URL.
     * @returns The instance of the builder.
     * @throws {Error} The value is not a valid URL authority.
     */
    setAuthority(authority: string): IUrlBuilder;
    private segments;
    /**
     * Returns the list of segments of the URL path.
     * @returns The segments of the URL.
     */
    getSegments(): string[];
    /**
     * Sets the segments of the URL path. Empty segments will be discarded.
     * @param segments The segments of the URL.
     * @returns The instance of the builder.
     */
    setSegments(segments: string[]): IUrlBuilder;
    /**
     * Returns the path of the URL.
     * @returns The path of the URL.
     */
    getPath(): string | undefined;
    /**
     * Sets the path of the URL.
     * @param path The path of the URL.
     * @returns The instance of the builder.
     */
    setPath(path?: string): IUrlBuilder;
    private query;
    /**
     * Returns the query parameters of the URL.
     * @returns The query parameters of the URL.
     */
    getQuery(): Map<string, string[]>;
    /**
     * Returns the query string of the URL.
     * @returns The query string of the URL.
     */
    getQueryString(): string | undefined;
    /**
     * Adds a query parameter to the URL. The specified values will be appended to existing values associated to this key. Empty keys and values will be discarded.
     * @param key The key of the parameter.
     * @param values The value or the values of the parameter.
     * @returns The instance of the builder.
     */
    addQuery(key: string, values: string | string[]): IUrlBuilder;
    /**
     * Sets a query parameter to the URL. The specified values will replace the existing values associated to this key. Empty keys and values will be discarded.
     * @param key The key of the parameter.
     * @param values The value or the values of the parameter.
     * @returns The instance of the builder.
     */
    setQuery(key: string, values: string | string[]): IUrlBuilder;
    /**
     * Sets the query string of the URL. Empty keys and values will be discarded.
     * @param queryString The query string of the URL.
     * @returns The instance of the builder.
     */
    setQueryString(queryString?: string): IUrlBuilder;
    private fragment?;
    /**
     * Returns the fragment of the URL.
     * @returns The fragment of the URL.
     */
    getFragment(): string | undefined;
    /**
     * Sets the fragment of the URL.
     * @param fragment The fragment of the URL.
     * @returns The instance of the builder.
     */
    setFragment(fragment?: string): IUrlBuilder;
    private parameters;
    /**
     * Returns the parameters of the URL. Parameters are tokens that replace values in built URLs.
     * @returns The parameters of the URL.
     */
    getParameters(): Map<string, string>;
    /**
     * Sets a parameter of the URL. Parameters are tokens that replace values in built URLs.
     * @param key The key of the parameter.
     * @param value The value of the parameter.
     * @returns The instance of the builder.
     * @throws {Error} The key is empty.
     */
    setParameter(key: string, value?: string): IUrlBuilder;
    /**
     * Creates a new instance of the `UrlBuilder` class.
     * @param options The initialization options.
     */
    constructor(options?: UrlOptions);
    /**
     * Builds an URL of the specified kind.
     * @param kind The URL kind (defaults to `Absolute`).
     * @returns The built URL.
     */
    build(kind?: UriKind): string;
    /**
     * Builds an absolute URL.
     * @returns The built URL.
     */
    buildAbsolute(): string;
    /**
     * Builds a relative URL.
     * @returns The built URL.
     */
    buildRelative(): string;
    private static inferPort;
}
/**
 * The initialization options of the `UrlBuilder` class.
 */
export type UrlOptions = {
    /**
     * The scheme of the URL.
     */
    scheme?: string;
    /**
     * The host of the URL.
     */
    host?: string;
    /**
     * The port of the URL.
     */
    port?: number;
    /**
     * The path of the URL.
     */
    path?: string;
    /**
     * The query string of the URL.
     */
    queryString?: string;
    /**
     * The fragment of the URL.
     */
    fragment?: string;
    /**
     * The credentials of the URL.
     */
    credentials?: ICredentials;
};