perma

Generate permalinks for your web project and give your visitors short urls to share!

Usage

### Install

npm install perma --save

Use in your Node Script

var perma   = require('perma');
var longurl = '/my-awesome-post-about-unicorns';
var tinyurl = perma(longurl);
console.log(tinyurl); // bCvQY

Why?

Most websites will never have more than a few dozen links, some of those links will be way too long for mortals to type! we want a way of shortening long links for sharing.

What?

A permalink (portmanteau of permanent link) is a URL that points to a specific web page, often a blog or forum entry which has passed from the front page to the archives, or the result of a search in a database. Because a permalink remains unchanged indefinitely, it is less susceptible to link rot.

Background Reading

• Wikipedia Permalink: http://en.wikipedia.org/wiki/Permalink
• PURL: http://en.wikipedia.org/wiki/Persistent_uniform_resource_locator
• A few alternatives: http://stackoverflow.com/questions/1349404/generate-a-string-of-5-random-characters-in-javascript

How?

We could just hash the url: e.g:

var hash = require('crypto').createHash('sha1');
hash.update("/my-amazing-blog-post");
console.log(hash.digest('base64')); // ExhijlsFTXLyVpfFgD3NQVwAfxU=

But the resulting string is 28 characters long (longer than the original 20 char url!)
If the length is the issue we can do what GitHub does with commit hashes in their UI (truncate them...):

Use only the first 6 characters of the hash:

var hash = require('crypto').createHash('sha512');
hash.update("/my-amazing-blog-post").digest('base64');
console.log(hash.substring(0, 6)); // Exhijl

Getting the base64 "digest" of the url means we have a 64 character population (potential characters):

A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z
a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, +, /

Which means we can have 64⁵ = 1,073,741,824 or 1 Billion possible (short) urls. (way more than most websites will ever need!)

However there are a few characters in that set which can be confusing to people trying to type the url (yes people still do type urls!):

0 (zero) can look like O (capital o) in certain fonts (so o, 0 and O) should be excluded.
I (capital i) and l (lowercase L) look identical in chrome's default font. exclude.
+ and / both have a special meaning in urls so exclude these too.

If we exclude the (potentially) "confusing" characters from our alphabet, we are left with 57 characters.
if each position in a string can be taken by one of these characters then there are 57 ⁵ 5-character strings. 601,692,057 or 601 Million
(still more than "enough" available strings)

Optional

If you want to have even shorter urls you will need to have a Datastore for links (to check for duplicates)
(we recommend using Redis for speed, but you can use which ever Datastore your project already uses e.g. Postgres, MySQL, MongoDB, CouchDB etc.)

Shorter ?

If you supply the perma method with a length parameter:

var perma   = require('perma');
var longurl = '/my-awesome-post-about-kittens';
var length  = 3;
var tinyurl = perma(longurl, length);
console.log(tinyurl); // bCv

Longer?

If you want more just ask for it! e.g:

var perma   = require('perma');
var longurl = '/my-awesome-post-about-unicorns';
var length  = 70;
var hash = perma(longurl, length);
console.log(hash); // 3ZtP18Ctj3bFMLhZww3SWEEGf15sGXczhvKcqahrcfX85ekZj7qMrqeB314MK77fjxvXfk

Practical Usage

Given that there are 57 ³ = 185,193 185k possible urls we can easily use perma as the basis for most websites, blogs or basic apps.

• Create practical http server example