Urlz NPM | npm.io

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

http://foo.com/bar/baz – absolute URL
foo.com/bar/baz – invalid URL, may occur in human text (*)
/bar/baz – root-relative URL (not absolute!)
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:

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"

// ...