Nobody Packages More

    url-composer

    1.15.0 • Public • Published

    url-composer

    JavaScript Style Guide Build Status bitHound Overall Score npm

    Small lib for parsing and building dynamic URLs

    Install

    You can install the lib via npm

    npm install --save url-composer

    or bower

    bower install --save url-composer

    Usage

    The library is very simple to use

    import url from 'url-composer'
     
    url.build({
      host: 'https://github.com',
      path: '/:username',
      params: { username: 'RasCarlito' },
      query: { tab: 'repositories' },
      hash: 'your-repos-filter'
    })
    // "https://github.com/RasCarlito?tab=repositories#your-repos-filter"

    Everything is optional. So calling url.build() without any parameters would just generate an empty String.

    Note: Path and query parameters are encoded using encodeURIComponent

    Path options

    The path option has an advanced syntax to handle injection of parameters.

    Named parameters

    Like in the first example

    import url from 'url-composer'
     
    url.build({
      path: '/users/:id',
      params: { id: 42 }
    })
    // "/users/42"

    Optional parameters

    With optional parameters you can make a portion of the path optional using parentheses. Depending on the params passed that portion will be included or left out.

    import url from 'url-composer'
     
    const path = '/users/:id(/edit/:section)'
     
    url.build({
      path,
      params: { id: 42 }
    })
    // "/users/42"
     
    url.build({
      path,
      params: { id: 42, section: 'profile' }
    })
    // "/users/42/edit/profile"

    Testing a path

    You can test a path to validate that it corresponds to a given schema

    import url from 'url-composer'
     
    const path = '/users/:id(/edit/:section)'
     
    // Testing path directly
    url.test({ path, url: '/users/42' }) // true
    url.test({ path, url: '/something/different' }) // false
     
    // Getting the regex instead
    const re = url.regex(path)
     
    re.test('/users/42/edit/profile') // true

    Parsing a path

    You can parse a path to extract the dynamic parts into an Array or an Object.

    It will also extract the search query if it is present and place it as the last item in the resulting Array or in a query key in the resulting Object.

    Missing optional parameters will result to null in the extracted values.

    Lets look at some code to actually see how it works:

    import url from 'url-composer'
     
    // Parsing dynamic parts into an Array
    url.parse({
      path: '/users/42/edit/profile',
      definition: '/users/:id(/edit/:section)'
    })
    // ['42', 'profile', null]
     
    // Parsing dynamic parts into an Object
    url.parse({
      path: '/users/42/edit/profile',
      definition: '/users/:id(/edit/:section)',
      object: true
    })
    // { id: '42', section: 'profile', query: null }
     
    // Parsing a path with a search query
    url.parse({
      path: '/users/42/edit/profile?expand=true',
      definition: '/users/:id(/edit/:section)'
    })
    // ['42', 'profile', 'expand=true']
     
    // Parsing dynamic parts into an Object
    url.parse({
      path: '/users/42/edit/profile?expand=true',
      definition: '/users/:id(/edit/:section)',
      object: true
    })
    // { id: '42', section: 'profile', query: 'expand=true' }

    License

    MIT

    Install

    npm i url-composer

    DownloadsWeekly Downloads

    89

    Version

    1.15.0

    License

    MIT

    Unpacked Size

    34.2 kB

    Total Files

    5

    Last publish

    Collaborators

    • rascarlito