API reference

@evanion/urn exports one class, two functions, two errors and four types, one heading each below. It needs Node 20 or newer and ships ESM only, which require() loads on Node 20.19, 22.12 or newer.

URN.schemeGrammar.test('baize'); // -> true
URN.nidGrammar.test('game'); // -> true
URN.nidGrammar.test('g'); // -> false
URN.isValidFormat('urn:g:azul'); // -> true
URN.nssGrammar.test('brass-birmingham'); // -> true
URN.nssGrammar.test('brass birmingham'); // -> false

const catalogue = ['urn:game:azul', 'urn:game:hive'];
catalogue.map((id) => GameURN.extractId(id)); // -> ['azul', 'hive']
 
let failure = '';
try {
  catalogue.map(GameURN.extractId);
} catch (error) {
  failure = (error as Error).name;
}
failure; // -> 'TypeError'
 
catalogue.filter(GameURN.isValidFormat); // -> []
catalogue.filter((id) => GameURN.isValidFormat(id)); // -> ['urn:game:azul', 'urn:game:hive']

export declare class URN {
    static readonly separator: string;
    static readonly urn: string;
    static readonly nid: string;
    static get schemeGrammar(): RegExp;
    static get nidGrammar(): RegExp;
    static get nssGrammar(): RegExp;
    static get rComponentGrammar(): RegExp;
    static get qComponentGrammar(): RegExp;
    static get fComponentGrammar(): RegExp;
    protected static get nidReadGrammar(): RegExp;
    private static get genericGrammar();
    private static get parsesComponents();
    private static get genericChar();
    static parse(urnString: string): ParsedURN;
    static stringify(parts: URNParts): string;
    static stringify(nss: string, nid?: string, urn?: string): string;
    static isValidFormat(urnString: string): boolean;
    static extractId(urnString: string): string;
    static sameNamespace(urn1: string, urn2: string): boolean;
    static belongsToNamespace(urnString: string, expectedNid: string, expectedUrn?: string): boolean;
    static equals(a: string, b: string): boolean;
    private static splitParts;
    private static splitComponents;
    private static assertComponents;
    private static assertComponent;
    private static stringifyComponents;
    private static sameToken;
    private static assertScheme;
    private static assertNid;
    private static assertNss;
    private static reject;
}

import { URN, InvalidError } from '@evanion/urn';
 
class GameURN extends URN {
  static override readonly nid = 'game';
}
 
const id = GameURN.stringify('brass-birmingham');
id; // -> 'urn:game:brass-birmingham'
 
let refused = '';
try {
  GameURN.stringify('brass birmingham');
} catch (error) {
  if (error instanceof InvalidError) refused = error.message;
}
refused; // -> "NSS contains invalid character ' ' in 'brass birmingham'"

URN.stringify

stringify(parts) and stringify(nss, nid?, urn?) write a URN string. nid and urn default to the calling class’s own statics. Both forms throw InvalidError when a part is empty or breaks its grammar:

GameURN.stringify('azul'); // -> 'urn:game:azul'
URN.stringify('azul', 'game'); // -> 'urn:game:azul'
URN.stringify('azul', 'game', 'baize'); // -> 'baize:game:azul'
URN.stringify({ nss: 'azul', nid: 'game' }); // -> 'urn:game:azul'
GameURN.stringify(GameURN.parse('urn:game:azul')); // -> 'urn:game:azul'

The object form’s keys match what parse returns, and only the object form writes the r-, q- and f-components. The positional arguments run in the reverse order of parse’s return, so stringify(...Object.values(parse(x))) puts the scheme where the NSS belongs. stringify writes the NSS verbatim, so it neither deduplicates nor is idempotent:

GameURN.stringify('game:azul'); // -> 'urn:game:game:azul'
GameURN.parse('urn:game:game:azul').nss; // -> 'game:azul'
GameURN.stringify(GameURN.stringify('azul')); // -> 'urn:game:urn:game:azul'

URN.parse

parse(urnString) returns a ParsedURN, with every part in the case it was written in and every percent-encoded character intact. A scheme or NID that differs from the class’s own, compared without regard to case, stays in the nss:

GameURN.parse('urn:game:azul'); // -> { urn: 'urn', nid: 'game', nss: 'azul' }
GameURN.parse('URN:GAME:azul'); // -> { urn: 'URN', nid: 'GAME', nss: 'azul' }
GameURN.parse('urn:order:order-2026-0042'); // -> { urn: 'urn', nid: 'order', nss: 'order:order-2026-0042' }
GameURN.parse('baize:game:azul'); // -> { urn: 'baize', nid: 'game', nss: 'baize:game:azul' }

parse throws ValidationError for a string that is not a URN, and InvalidError for a part that breaks its grammar.

URN.isValidFormat

isValidFormat(urnString) returns true when parse would succeed. It calls parse, so the two cannot disagree, and it never throws:

function urnOrNull(input: string) {
  return GameURN.isValidFormat(input) ? GameURN.parse(input) : null;
}
 
urnOrNull('urn:game:hive'); // -> { urn: 'urn', nid: 'game', nss: 'hive' }
urnOrNull('urn:game:spirit island'); // -> null
urnOrNull('hive'); // -> null
urnOrNull('urn:order:order-2026-0042'); // -> { urn: 'urn', nid: 'order', nss: 'order:order-2026-0042' }

URN.extractId

extractId(urnString) returns everything after the scheme and the NID, with any r-, q- or f-component dropped. On a foreign namespace it differs from parse(urnString).nss, which keeps the NID. The base URN class’s own NID is 'nid', so game is foreign to it:

URN.parse('urn:game:azul').nss; // -> 'game:azul'
URN.parse('urn:game:azul').nid; // -> 'game'
URN.extractId('urn:game:azul'); // -> 'azul'

extractId throws ValidationError on malformed input.

URN.sameNamespace

sameNamespace(a, b) returns true when both URNs have the same scheme and the same NID, compared case-folded. Malformed input returns false:

URN.sameNamespace('urn:game:azul', 'URN:Game:hive'); // -> true
URN.sameNamespace('urn:game:azul', 'urn:order:order-2026-0042'); // -> false
URN.sameNamespace('azul', 'azul'); // -> false

URN.belongsToNamespace

belongsToNamespace(urnString, nid, urn?) returns true when the URN is in the named namespace. urn defaults to the calling class’s own scheme. Malformed input returns false:

GameURN.belongsToNamespace('urn:game:azul', 'game'); // -> true
GameURN.belongsToNamespace('baize:game:azul', 'game'); // -> false
GameURN.belongsToNamespace('baize:game:azul', 'game', 'baize'); // -> true

URN.equals

equals(a, b) is RFC 8141 §3.1 equivalence. The scheme and the NID fold case. The NSS compares character for character, except that the hex digits of a percent-triplet fold to uppercase. A percent-encoded octet is never decoded, and the r-, q- and f-components are ignored. Malformed input returns false:

URN.equals('URN:GAME:azul', 'urn:game:azul'); // -> true
URN.equals('urn:game:Brass%3a%20Birmingham', 'urn:game:Brass%3A%20Birmingham'); // -> true
URN.equals('urn:game:Brass%3A%20Birmingham', 'urn:game:Brass:%20Birmingham'); // -> false
URN.equals('urn:game:Azul', 'urn:game:azul'); // -> false

function encodeNss(raw: string): string;
 

import { URN, encodeNss, decodeNss } from '@evanion/urn';
 
URN.isValidFormat('urn:game:Brass: Birmingham'); // -> false
 
const nss = encodeNss('Brass: Birmingham');
nss; // -> 'Brass%3A%20Birmingham'
 
const id = URN.stringify(nss, 'game');
id; // -> 'urn:game:Brass%3A%20Birmingham'
decodeNss(URN.extractId(id)); // -> 'Brass: Birmingham'

function decodeNss(encoded: string): string;
 

import { decodeNss, ValidationError } from '@evanion/urn';
 
decodeNss('Brass%3A%20Birmingham'); // -> 'Brass: Birmingham'
 
let refused = '';
try {
  decodeNss('Brass%3');
} catch (error) {
  if (error instanceof ValidationError) refused = error.message;
}
refused; // -> "Malformed percent-encoding in 'Brass%3': '%' must be followed by two hex digits."

export declare class ValidationError extends Error {
    constructor(message: string);
}

import { URN, InvalidError, ValidationError } from '@evanion/urn';
 
function problemWith(input: string): string {
  try {
    URN.parse(input);
    return 'none';
  } catch (error) {
    if (error instanceof InvalidError) return `bad ${error.property}`;
    if (error instanceof ValidationError) return 'not a URN';
    throw error;
  }
}
 
problemWith('urn:game:azul'); // -> 'none'
problemWith('urn:game:spirit island'); // -> 'bad NSS'
problemWith('azul'); // -> 'not a URN'

export declare class InvalidError extends ValidationError {
    constructor(property: string, value: string, invalidChar?: string, reason?: string);
    private static buildMessage;
    readonly property: string;
    readonly value: string;
    readonly invalidChar?: string;
    readonly reason?: string;
}

import { URN, InvalidError } from '@evanion/urn';
 
function rejection(nss: string, nid: string): InvalidError | undefined {
  try {
    URN.stringify(nss, nid);
    return undefined;
  } catch (error) {
    if (error instanceof InvalidError) return error;
    throw error;
  }
}
 
const space = rejection('spirit island', 'game');
space?.property; // -> 'NSS'
space?.invalidChar; // -> ' '
space?.message; // -> "NSS contains invalid character ' ' in 'spirit island'"
 
const short = rejection('spirit-island', 'g');
short?.property; // -> 'NID'
short?.reason; // -> 'must be at least 2 characters long'

interface ParsedURN extends URNComponents {
    urn: string;
    nid: string;
    nss: string;
}
 

GameURN.parse('urn:game:brass-birmingham?=edition=2018#setup'); // -> { urn: 'urn', nid: 'game', nss: 'brass-birmingham', fComponent: 'setup', qComponent: 'edition=2018' }

interface URNParts extends URNComponents {
    urn?: string;
    nid?: string;
    nss: string;
}
 

import type { ParsedURN, URNParts } from '@evanion/urn';
 
class GameURN extends URN {
  static override readonly nid = 'game';
}
 
const parsed: ParsedURN = GameURN.parse('urn:game:azul#setup');
const scoring: URNParts = { ...parsed, fComponent: 'scoring' };
GameURN.stringify(scoring); // -> 'urn:game:azul#scoring'
 
const bare: URNParts = { nss: 'hive' };
GameURN.stringify(bare); // -> 'urn:game:hive'

interface URNComponents {
    rComponent?: string;
    qComponent?: string;
    fComponent?: string;
}
 

function tail({ qComponent, fComponent }: URNComponents): string {
  return [qComponent, fComponent].filter(Boolean).join(' / ');
}
 
tail(GameURN.parse('urn:game:azul?=edition=2017#scoring')); // -> 'edition=2017 / scoring'
'qComponent' in GameURN.parse('urn:game:azul'); // -> false

export type IFullURN<URN extends string, NID extends string, NSS extends string> = `${URN}:${NID}:${NSS}`;

import type { IFullURN } from '@evanion/urn';
 
type GameId = IFullURN<'urn', 'game', string>;
 
const azul: GameId = 'urn:game:azul';
URN.extractId(azul); // -> 'azul'
 
// @ts-expect-error: an order URN is not a GameId
const order: GameId = 'urn:order:order-2026-0042';
URN.isValidFormat(order); // -> true