urn
A URN Library that makes it easier to work with more meaningful identifiers. The API is inspired by, and designed to be as simple as the JSON class.
import { URN } from '@Evanion/urn';
// You can easily extend the base class to create your own base schema
class TRN extends URN {
static readonly urn = 'trn';
}
// Then you can generate a URN using the stringify method
TRN.stringify('foo', 'bar'); // -> 'trn:bar:foo'
What is a URN?
URN stands for Universal Resource Name
and is part of the URI spec in RFC8141. And you might have seen it in use at some major companies like AWS (strings that start with ARN:...
). It's used to identify resources with a more descriptive string, than just a plain identifier, by also adding a namespace and schema.
Why should you use a URN
How many times have you seen a random DocumentID being thrown around in a conversation,
and you wonder what type of DocumentID it is? Is it a product
or productCategory
ID?
A URN will help, by always include information about the namespace that the ID is referring to.
Philosophy
The idea with this library to make it as easy to work with URNs as it is to work with JSON
.
And the libraries API is inspired by the JSON
API.
Declare namespace
You can easily create a namespace specific class
// You can create namespace specific URN classes
class UserTRN extends TRN {
static readonly nid = 'user';
}
// That will automatically create a URN with the proper namespace
UserTRN.stringify('1337'); // -> 'trn:user:1337'
Parse urn
Parsing a URN will decode it in to it's constituent parts
const parsed = UserTRN.parse('trn:user:1337');
console.log(parsed); // -> {urn:'trn', nid: 'user', nss: '1337'}
If you parse a URN from another namespace ID, it will retain the namespace ID in the NSS. This way, each namespace should only work with plain ids when it's inside it's own namespace, and retain the namespace information if it's from another namespace ID
const parsed = UserTRN.parse('trn:order:42');
console.log(parsed); // -> {urn: 'trn', nid: 'order', nss: 'order:42'}
Validation
The library will attempt to validate the URN and NIDs to only contain valid characters (a-z 0-9 case insensitive)
UserTRN.stringify('1337', 'f?o'); // -> will throw a NID ValidationError
UserTRN.stringify('1337', 'foo', 'b!r'); // -> will throw a URN ValidationError
It will won't add a namespace if it already exists
UserTRN.stringify('user:1337'); // -> 'trn:user:1337'
Caveats
Since classes aren't aware of sibling classes, strignifying a NSS
that contains another namespace
will cause duplication of namespaces
UserTRN.stringify('order:42'); // -> 'trn:user:order:42'
so the recommended solution is to set the namespace to what you expect
UserTRN.stringify('order:42', 'order'); // -> 'trn:order:42'