@jescrich/urn

URN Utility (@jescrich/urn)

Author: José Escrich https://joseescrich.com

Overview

A powerful, extensible utility for working with Uniform Resource Names (URNs).

This package allows you to compose, validate, parse, transform, and manipulate URNs efficiently. It supports attribute management, UUID generation, normalization, and extensibility for custom namespace validation.

Installation

npm install @jescrich/urn

or using Yarn:

yarn add @jescrich/urn

Usage

URNs follow the format:

urn:<entity>:<id>[:<key>:<value>]*

Examples

urn:customer:[e-mail]
urn:customer:6e8bc430-9c3a-11d9-9669-0800200c9a66
urn:order:12345:vendor:amazon:status:shipped
urn:document:abc123:type:pdf:author:john_doe
urn:isbn:0-486-27557-4
urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
urn:nbn:de:bvb:19-146642

API Reference

1. Create a URN with a UUID

import { Urn } from "@jescrich/urn";

const urn = Urn.createUUID("order");
console.log(urn);
// Output: urn:order:550e8400-e29b-41d4-a716-446655440000

2. Compose a URN

const urn = Urn.compose({ entity: "order", id: "12345", attributes: { vendor: "amazon", status: "shipped" } });
console.log(urn);
// Output: urn:order:12345:vendor:amazon:status:shipped

3. Parse a URN

const parsed = Urn.parse("urn:document:abc123:type:pdf:author:john_doe");
console.log(parsed);
/* Output:
{
  entity: "document",
  id: "abc123",
  attributes: { type: "pdf", author: "john_doe" }
}
*/

4. Extract Information

console.log(Urn.entity("urn:order:12345")); // Output: order
console.log(Urn.id("urn:order:12345")); // Output: 12345
console.log(Urn.value("urn:order:12345:vendor:amazon", "vendor")); // Output: amazon

5. Attribute Management

// Add or update an attribute
const updatedUrn = Urn.addAttribute("urn:order:12345", "status", "shipped");
console.log(updatedUrn);
// Output: urn:order:12345:status:shipped

// Remove an attribute
const removedUrn = Urn.removeAttribute("urn:order:12345:status:shipped", "status");
console.log(removedUrn);
// Output: urn:order:12345

6. Validation

console.log(Urn.isValid("urn:order:12345")); // Output: true
console.log(Urn.isValid("invalid-string")); // Output: false

7. Normalization

console.log(Urn.normalize("URN:Order:12345:Vendor:Amazon"));
// Output: urn:order:12345:vendor:amazon

URN Specifications

• Globally Unique & Persistent: URNs provide stable, location-independent identifiers.
• Case-Insensitive Prefix & Namespace: The urn: prefix and namespace identifiers are case-insensitive.
• RFC Compliance: Namespace identifiers should follow IANA registered URNs.
• Max Length: URNs have a maximum length of 255 characters.

Roadmap & Extensibility Considerations

The future development of @jescrich/urn aims to further enhance its capabilities, including:

• Namespace-Specific Validation:

  • Allow registering custom validation rules per namespace.
  • Example: Enforce UUID format for urn:uuid:<id>.

• Support for Query (?+, ?=) and Fragment (#) Components:

  • Extend parsing to handle optional query/fragment parts as per RFC 8141.

• Object-Oriented Extension:

  • Introduce an extensible URN class to support subclassing.

• Typed Namespace Handling:

  • Define stricter TypeScript types for common URN formats.

• Improved Error Handling:

  • Implement an InvalidUrnError custom class to provide more descriptive error reporting.

License

This project is licensed under the MIT License.