Neverending Puppy Marathon

    @innova2/url-builder
    TypeScript icon, indicating that this package has built-in type declarations

    1.5.1 • Public • Published

    Url-Builder

    Coverage

    A lightweight library with many features to easy build URLs

    📑 Features

    This library allows :

    • Create URLs most easly
    • Parse and decompose your URLs
    • Ride up in the URL tree
    • Make comparisons between URLs

    🛠️ Installation

    To import the library you just need to run this command :

    npm install @innova2/url-builder

    📝 Usage

    Create from existing URL

    const url = UrlBuilder.createFromUrl('http://localhost:8080/users');
    // or create new url with the constructor

    Handle path

    Add new path segment(s)

    const userId = '170b16cd-ad47-4c9c-86cf-7c83bd40d775';
    url.addPath(':id/comments').addParam('id', userId);
    // Or
    url.addPath(':id/comments', { id: userId });

    Add multiples parameters

    const userId = '170b16cd-ad47-4c9c-86cf-7c83bd40d775';
    const commentId = '218dd1c4-0bb0-425a-be0b-85427304e100';
    url.addPath(':userId/comments/:commentId').addParams({ userId, commentId });
    // Or
    url.addPath(':userId/comments/:commentId', { userId, commentId });

    Get the first path segment

    const rowNum = 10;
    const url = UrlBuilder.createFromUrl('http://localhost:8080/rows/:rowNum/cells').addParam('rowNum', rowNum);
    url.getFirstPath(); // Output: 'rows'

    Get the last path segment

    url.getLastPath(); // Output: 'cells'

    Handle query param

    Add new query param

    const page = 2;
    url.addQuery('page', page);

    Add multiples query params

    const page = 2;
    const order = 'DESC';
    url.addQueries({ page, order });

    Handle fragment

    Parse fragment with url

    const url = UrlBuilder.createFromUrl('http://localhost/users?page=1#foo');
    url.getRelativePath(false, true);
    // Output : /users#foo
    // The first boolean is "withQuery" and the seconde is "withFragment"
    // With query params and fragment :
    url.getRelativePath(true, true);
    // Output : /users?page=1#foo

    Define fragment without hash

    url.setFragment('bar');

    Retrieve fragment

    const fragment = url.getFragment();
    // Output : bar
    url.getRelativePath(false, true);
    // Output : /users#bar

    Merge path and query params

    It's possible to merge path and query params with another url

    const url = UrlBuilder.createFromUrl('http://localhost:3000').addPath('groups');
    
    const anotherUrl = new UrlBuilder()
        .addPath(':id/users', { id: 2 })
        .addQuery('page', 1)
    
    url.mergePathWith(anotherUrl).toString() // Get 'http://localhost:3000/groups/2/users?page=1'

    Note : This function merge only path, params and query params with current url.

    Work with parent

    Get parent URL easly.
    This function return a new instance of UrlBuilder

    const url = UrlBuilder.createFromUrl('http://localhost:8080/orders/:orderId/products/:productId');
    const parent = url.getParent(); // Get 'http://localhost:8080/orders/:orderId/products'

    Or up to the specific level

    url.getParent(3); // Get 'http://localhost:8080/orders'

    Get relative path

    Retrieve the relative path in string format

    const postId = 'a937b39e-9664-404a-ac56-f3da2b83a951';
    const url = UrlBuilder.createFromUrl('http://localhost:8080/posts/:id').addParam('id', postId);
    url.getRelativePath(); // Output: '/posts/a937b39e-9664-404a-ac56-f3da2b83a951'

    And with query params
    Don't forget to add 'true' parameter to allow query params conversion

    url.addQuery('displaySimilar', true);
    url.getRelativePath(); // Output: '/posts/a937b39e-9664-404a-ac56-f3da2b83a951'
    url.getRelativePath(true); // Output: '/posts/a937b39e-9664-404a-ac56-f3da2b83a951?displaySimilar=true'

    Get query params in string

    Retrieve the query params in string format

    const url = UrlBuilder.createFromUrl('http://localhost:8080/vehicles').addQueries({
      page: 2,
      order: 'ASC',
    });
    url.getQueryString(); // Output: '?page=2&order=ASC'

    Convert full URL to string

    Retrieve the query params in string format

    const name = 'url-builder';
    const url = UrlBuilder.createFromUrl('https://github.com/InnovA2')
            .addPath(':name/pulls')
            .addParam('name', name);
    url.toString(); // Output: 'https://github.com/InnovA2/url-builder/pulls'

    📝 Advanced

    Compare URL to another

    Compare the current URL to another URL (UrlBuilder instance)

    const id = '434f65eb-4e5f-4b29-899c-b3e159fff61c';
    const id2 = '3e972ca2-b422-4ac9-b793-e6f305c7bfb2';
    const url = UrlBuilder.createFromUrl('http://localhost:8080/users/:id').addParam('id', id);
    const url2 = UrlBuilder.createFromUrl('http://localhost:8080/users/:id').addParam('id', id);
    const url3 = UrlBuilder.createFromUrl('http://localhost:8080/users/:id').addParam('id', id2);
    url.compareTo(url2); // Output: true
    url.compareTo(url3); // Output: false

    Get word between two others

    Compare the current URL to another URL (UrlBuilder instance)

    const url = UrlBuilder.createFromUrl('http://localhost:8080/users/10/comments');
    url.getBetween2Words('users', 'comments'); // Output: 10

    Split path from string (static)

    Split path string by slash

    UrlBuilder.splitPath('/InnovA2/url-builder/pulls/'); // Output: ['InnovA2', 'url-builder', 'pulls']
    // or if you have more slashes
    UrlBuilder.splitPath('/InnovA2///url-builder/pulls/'); // Output: ['InnovA2', 'url-builder', 'pulls']

    Trim path from string (static)

    Trim path string by removing useless slashes

    UrlBuilder.trimPath('/InnovA2/url-builder/pulls/'); // Output: 'InnovA2/url-builder/pulls'
    // or if you have more slashes
    UrlBuilder.trimPath('/InnovA2///url-builder/pulls/'); // Output: 'InnovA2/url-builder/pulls'

    ⚙️ API

    static createFromUrl(baseUrl: string): UrlBuilder
    static splitPath(path: string): string[]
    static trimPath(path: string): string
    compareTo(url: UrlBuilder, relative = true): boolean
    getScheme(): Scheme
    setScheme(scheme: Scheme): UrlBuilder
    getHost(): string
    setHost(host: string): UrlBuilder
    getPort(): numbe
    setPort(port: number): UrlBuilder
    getPathSegments(): string[]
    setPathSegments(segments: string[], params: Record<string, string | number>): UrlBuilder
    addPath(path: string, params: Record<string, string | number>): UrlBuilder
    getParams(): Map<string, string | number>
    setParams(params: Map<string, string | number>): UrlBuilder
    addParam(key: string, value: string | number): UrlBuilder
    addParams(params: Record<string, string | number>): UrlBuilder
    getParams(): Map<string, string | number>
    getQuery(): Map<string, string | number>
    setQuery(query: Map<string, string | number>): UrlBuilder
    addQuery(key: string, value: string | number): UrlBuilder
    addQueries(queries: Record<string, string | number>): UrlBuilder
    getQuery(): Map<string, string | number>
    mergePathWith(url: UrlBuilder): UrlBuilder
    getFirstPath(): string
    getLastPath(): string
    getParent(n = 1): UrlBuilder
    getBetween2Words(a: string, b: string): string
    getRelativePath(query = false): string
    getQueryString(): string
    toString(): string

    Note : Only the non-static getParent() method return new instance of UrlBuilder. Others return the current instance.

    ⚖️ Licence

    MIT

    👥 Authors

    🤝 Contributors

    Do not hesitate to participate in the project! Contributors list will be displayed below.

    Install

    npm i @innova2/url-builder

    DownloadsWeekly Downloads

    7

    Version

    1.5.1

    License

    MIT

    Unpacked Size

    18.6 kB

    Total Files

    11

    Last publish

    Collaborators

    • adrienm
    • angeltouss1