URN Library

An earlier release

These pages document @evanion/urn 1.1.1. npm install @evanion/urn gives you 2.1.1, documented here. Values on this page were produced by running 1.1.1 in CI at c2979ea and are not re-executed.

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.

What is a URN?

URN stands for Universal Resource Name and is part of the URI spec in RFC8141 . 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 is to make it as easy to work with URNs as it is to work with JSON. And the library’s API is inspired by the JSON API.

Features

Simple API: JSON-inspired API for easy adoption
URN Parsing: Parse URN strings into structured components
URN Stringifying: Create URN strings from components
Custom Schemes: Support for custom URN schemes beyond the standard urn:
Namespace Support: Handle custom namespaces and identifiers
Class Inheritance: Extend the base URN class for domain-specific implementations
TypeScript Support: Full TypeScript support with comprehensive type definitions
Validation: Built-in validation for URN components (a-z, 0-9, case insensitive)

Installation


npm install @evanion/urn

Quick Start


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'
 
// Parse a URN to get its constituent parts
const parsed = TRN.parse('trn:bar:foo');
console.log(parsed); // -> {urn:'trn', nid: 'bar', nss: 'foo'}

Basic Usage

Creating URNs


import { URN } from '@evanion/urn';
 
// Create a basic URN (nss, nid, urn)
const basicUrn = URN.stringify('resource-id', 'my-namespace');
// Result: "urn:my-namespace:resource-id"
 
// Create a URN with custom scheme (nss, nid, urn)
const customUrn = URN.stringify('resource-id', 'my-namespace', 'custom-scheme');
// Result: "custom-scheme:my-namespace:resource-id"

Parsing URNs


import { URN } from '@evanion/urn';
 
// Parse a standard URN
const parsed = URN.parse('urn:my-namespace:resource-id');
console.log(parsed);
// {
//   urn: 'urn',
//   nid: 'my-namespace',
//   nss: 'resource-id'
// }
 
// Parse a URN with different namespace - retains namespace info in NSS
const parsed2 = URN.parse('urn:other-namespace:resource-id');
console.log(parsed2);
// {
//   urn: 'urn',
//   nid: 'other-namespace',
//   nss: 'other-namespace:resource-id'
// }

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'

Advanced Usage

Custom URN Classes

You can extend the base URN class to create domain-specific URN implementations:


import { URN } from '@evanion/urn';
 
// Create a custom URN class for your domain
class MyResourceURN extends URN {
  static readonly urn = 'my-resource';
  static readonly separator = '-';
}
 
// Use the custom class
const myUrn = MyResourceURN.stringify('resource-id', 'namespace');
console.log(myUrn); // "my-resource-namespace-resource-id"
 
// Parse with the custom class
const parsed = MyResourceURN.parse('my-resource-namespace-resource-id');
console.log(parsed);
// {
//   urn: 'my-resource',
//   nid: 'namespace',
//   nss: 'resource-id'
// }

Namespace-Specific URN Classes

For even more control, you can create namespace-specific URN classes:


import { URN } from '@evanion/urn';
 
class MyResourceURN extends URN {
  static readonly urn = 'my-resource';
}
 
class UserURN extends MyResourceURN {
  static readonly nid = 'user';
}
 
// Use the namespace-specific class
const userUrn = UserURN.stringify('123');
console.log(userUrn); // "my-resource:user:123"
 
// Parse with the namespace-specific class
const parsed = UserURN.parse('my-resource:user:123');
console.log(parsed);
// {
//   urn: 'my-resource',
//   nid: 'user',
//   nss: '123'
// }

API Reference

Static Methods

`URN.stringify(nss, nid?, urn?)`

Creates a URN string from its components.

Parameters:

nss (string): The namespace-specific string (required)
nid (string): The namespace identifier (optional, defaults to ‘nid’)
urn (string): The URN scheme (optional, defaults to ‘urn’)

Returns: string - The formatted URN string

Example:


URN.stringify('example', 'my-namespace'); // "urn:my-namespace:example"
URN.stringify('example', 'my-namespace', 'custom'); // "custom:my-namespace:example"

`URN.parse(urnString)`

Parses a URN string into its components.

Parameters:

urnString (string): The URN string to parse

Returns: object - An object containing:

urn (string): The URN scheme
nid (string): The namespace identifier
nss (string): The namespace-specific string

Example:


URN.parse('urn:my-namespace:example');
// Returns: { urn: 'urn', nid: 'my-namespace', nss: 'example' }

Class Properties

`static urn: string`

The URN scheme for the class. Defaults to 'urn'.

`static separator: string`

The separator used between URN components. Defaults to ':'.

`static nid: string`

The namespace identifier for the class. Optional.

Validation

The library will attempt to validate the URN and NIDs to only contain valid characters (a-z 0-9 case insensitive):


import { URN, InvalidError } from '@evanion/urn';
 
// This will throw an InvalidError for invalid NID
UserTRN.stringify('1337', 'f?o'); // -> will throw a NID ValidationError
 
// This will throw an InvalidError for invalid URN
UserTRN.stringify('1337', 'foo', 'b!r'); // -> will throw a URN ValidationError

It 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, stringifying 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'

Common Use Cases

Resource Identification


class ResourceURN extends URN {
  static readonly urn = 'resource';
}
 
// Identify different types of resources
const userUrn = ResourceURN.stringify('123', 'user');
const productUrn = ResourceURN.stringify('456', 'product');
const orderUrn = ResourceURN.stringify('789', 'order');

Database Entity References


class DatabaseURN extends URN {
  static readonly urn = 'db';
}
 
// Reference database entities
const tableUrn = DatabaseURN.stringify('users', 'table');
const recordUrn = DatabaseURN.stringify('123', 'record');

Microservice Communication


class ServiceURN extends URN {
  static readonly urn = 'service';
}
 
// Identify services and their resources
const userServiceUrn = ServiceURN.stringify('user-service', 'service');
const userResourceUrn = ServiceURN.stringify('123', 'user-service');

Testing

The library includes comprehensive test coverage with Vitest:


npm test

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests for any improvements.

License

This project is licensed under the MIT License - see the LICENSE file for details.