ivan-kleshnin / urlz

Functional utils for URLs

Urlz

Functional toolkit for URLs. Drop-in url and querystring replacement. Originally built for a static site generator where URL transformations are common, but use-cases are really unlimited.

Features

• High-level URL manipulations
• Curried composable API
• Crossplatform: works in NodeJS and all modern browsers
• Extensive test suite

Dependencies:

• pathz

Peer dependencies:

• url
• querystring
• @paqmind/ramda (temp. until basic Ramda)

Usage

$ npm install urlz

let U = require("urlz")

// The following snippets also use shortcuts for:
let R = require("ramdax")
let UU = require("url")

Glossary

1. http://foo.com/bar/baz – absolute URL
2. foo.com/bar/baz – invalid URL, may occur in human text (*)
3. /bar/baz – root-relative URL (not absolute!)
4. bar/baz – relative URL

• – should be specially handled with libs like normalize-url. We don't provide normalization heuristics here (yet).

Motivation

1. Original format / parse provide limited, low-level, mutable API

There is also newer WHATWG URL API but it doesn't support relative URLs. Which basically makes it unusable for many scenarios. So while NodeJS renders url as deprecated it's still much better than WHATWG version (unsurprisingly).

2. urlz is trailing slash aware

Trailing slash is significant in some cases. It may affect backend routing AND it affects relative URLs:

• Link-1
• Link-2

urlz doesn't assume anything and keeps trailing slash untouched for all operations where it's possible.

3. urlz respects "relativeness" and "absoluteness" of urls

console.log(U.addLeftDir("bar", "/foo.txt"))  // "/bar/foo.txt" (+)
console.log(UU.join("bar", "/foo.txt"))       // "bar/foo.txt"  (-) naive

console.log(U.addRightDir("bar", "/foo.txt")) // "/bar/foo.txt" (+)
console.log(UU.join("/foo.txt", "bar"))       // "/foo.txt/bar" (-) naive

4. urlz is composition friendly

let R = require("ramdax")

let src = "content/team/about.md"
let dst = R.pipe(
  U.withLeftDir("public"),
  U.addRightDir(P.name(src)),
  U.withBase("index.html")
)(src)

console.log(dst) // "public/team/about/index.html"
                 // corresponding to "/team/about/" URL

5. urlz is like CRUD for path fragments

// GET
console.log(U.leftDir("/foo/bar/baz.txt"))  // "foo"
console.log(U.rightDir("/foo/bar/baz.txt")) // "bar"

// UPDATE
console.log(U.withLeftDir ("qux", "/foo/bar/baz.txt")) // "/qux/bar/baz.txt"
console.log(U.withRightDir("qux", "/foo/bar/baz.txt")) // "/foo/qux/baz.txt"

// DELETE
console.log(U.dropLeftDir ("/foo/bar/baz.txt")) // "/bar/baz.txt"
console.log(U.dropRightDir("/foo/bar/baz.txt")) // "/foo/baz.txt"

// ...

6. urlz provides extra utils

TODO: describe

API

TODO: describe

urlz's Issues

Use qs.parse result in U.parse

Add withOrigin

Add an ability to reset hash

I tried this:
U.withHash("", url)

but it returned the URL with # at the end, and I don't need it

Hash without hasmark sign?!

Why withHash uses non-hashmarked string while parse returns hashmarked string?!

Add the `equals` function

let equals = (url1, url2) => {
  let u1 = U.parse(url1)
  let u2 = U.parse(url2)
  let q1 = QS.parse(u1.query)
  let q2 = QS.parse(u2.query)
  return u1.hostname == u2.hostname
    && (u1.port || 80) == (u2.port || 80)
    && u1.pathname == u2.pathname
    && R.equals(q1, q2)
}

withPort adds trailing slash

> U.withPort(8080, "http://123.32.34.234")
'http://123.32.34.234:8080/'