Checking URN input

isValidFormat in @evanion/urn screens a URN from outside the shop before parse reads it, ensuring your application doesn’t crash on malformed input.

The Problem: Untrusted Input

When receiving URNs from external sources—API requests, URL parameters, or user input—you cannot assume they are well-formed. Attempting to parse a string that isn’t a URN will throw an error, which, if uncaught, can crash your request handler.

Checking every input with a try...catch block is verbose and computationally expensive for high-volume endpoints.

Solution: Pre-screening with isValidFormat

isValidFormat allows you to screen input without the overhead of exception handling. It internally calls parse but returns a boolean instead of throwing, ensuring that your validation logic and parsing logic never disagree.

GameURN screens a URN from outside the shop before reading it:

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' }

In this example, urnOrNull returns null for the space in spirit island, and for hive, which lacks both a scheme and a NID. It returns the order URN, because isValidFormat checks the shape and not the namespace.

Avoiding the “Unbound Static” Pitfall

A common JavaScript error occurs when passing static methods as callbacks. Every static method of an @evanion/urn class reads this to determine the current namespace. If you pass a static method as a bare callback, it loses its class binding.

stringify, parse and extractId will throw a TypeError in this scenario. However, isValidFormat, sameNamespace and equals are designed to fail gracefully and return false instead.

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']

catalogue.filter(GameURN.isValidFormat) returns an empty list because the binding is lost. To fix this, wrap the call in an arrow function to preserve the class context, as the first map and the last filter do.

Distinguishing Malformed URNs from Bad Parts

@evanion/urn provides two distinct error classes to help you provide better feedback to your users.

• ValidationError: The string is not a URN at all (e.g., it is missing the urn: scheme or the NID).
• InvalidError: The string is a URN, but a specific part (like the NSS) broke its grammar.

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'

Every InvalidError is also a ValidationError. An InvalidError carries detailed fields to explain exactly what failed:

Minting Batches Safely

Since stringify throws an InvalidError on a part that breaks its grammar, you should catch these errors when processing a batch of IDs. This ensures one bad slug doesn’t stop the entire process:

import { URN, InvalidError } from '@evanion/urn';
 
function mint(slugs: string[]): { minted: string[]; skipped: string[] } {
  const minted: string[] = [];
  const skipped: string[] = [];
 
  for (const slug of slugs) {
    try {
      minted.push(URN.stringify({ nss: slug, nid: 'game' }));
    } catch (error) {
      if (!(error instanceof InvalidError)) throw error;
      skipped.push(slug);
    }
  }
 
  return { minted, skipped };
}
 
mint(['azul', 'spirit island', 'wingspan']); // -> { minted: ['urn:game:azul', 'urn:game:wingspan'], skipped: ['spirit island'] }

URN Part Grammars

@evanion/urn validates each part against specific grammars: the NID and the NSS against RFC 8141, and the scheme against RFC 3986, so a scheme other than urn passes:

• Scheme: A letter, followed by letters, digits, +, - and ..
• NID: Letters, digits and interior hyphens. stringify requires 2-32 characters; parse accepts 1-32.
• NSS: Letters, digits, -._~!$&'()*+,;=:@, percent-encoded characters, and / after the first character. Spaces, ? and # are prohibited.

schemeGrammar, nidGrammar and nssGrammar hold the patterns stringify checks. Note that the NID is the only part read and written differently: parse accepts a one-character NID (per RFC 2141), while stringify refuses to write it.

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

Next steps: Adding metadata

A URN that isValidFormat accepts has passed each @evanion/urn grammar. r-, q- and f-components shows how to add an edition and a section of the rules to urn:game:brass-birmingham, and reads both back with parse.