@naverpay/nurl

@naverpay/nurl

NURL is a powerful URL manipulation library that extends the standard URL class. It provides dynamic segment processing and flexible URL creation capabilities.

Features

• Extends and implements the URL class
• Supports various URL creation methods (string, URL object, custom options object)
• Provides a factory function NURL.create() for creating instances without the new keyword
• Dynamic segment processing functionality
• Setters behave differently from the standard URL
• Provides decoded hostname for IDN (Internationalized Domain Names) support

Usage

Basic Usage

import {NURL} from 'nurl'

// Create URL from string
const url1 = new NURL('https://example.com/users/123?name=John')

// Create URL from existing URL object
const standardUrl = new URL('https://example.com')
const url2 = new NURL(standardUrl)

// Create URL from custom options object
const url3 = new NURL({
    baseUrl: 'https://example.com',
    pathname: '/users/:id',
    query: {id: '123', name: 'John'},
})

// Create empty URL
const url4 = new NURL()

// Using the factory function
const url5 = NURL.create('https://example.com')

// The factory function also works with options object
const url6 = NURL.create({
    baseUrl: 'https://example.com',
    pathname: '/users/:id',
    query: {id: '123', name: 'John'},
})

Dynamic Segment Processing

NURL processes dynamic segments in the pathname and replaces them with values from the query object. If a dynamic segment doesn't have a corresponding query value, it remains unchanged in the pathname without any encoding:

const url = new NURL({
    baseUrl: 'https://api.example.com',
    pathname: '/users/:a/posts/[b]/[c]',
    query: {
        a: '123',
        b: '456',
        format: 'json',
    },
})

console.log(url.href)
// Output: https://api.example.com/users/123/posts/456/[c]?format=json

IDN Support

NURL automatically handles Internationalized Domain Names:

const url = new NURL('https://한글.도메인')
console.log(url.hostname) // xn--bj0bj06e.xn--hq1bm8jm9l
console.log(url.decodedHostname) // 한글.도메인 (in human-readable format)

URL Pattern Matching

NURL supports NURL.match(url, pattern) static method to match a URL path against a pattern with dynamic segments:

NURL.match('/v1/user/12345/info', '/v1/user/:userId/info')
// → { userId: '12345' }

NURL.match('/v1/friends/SENDMONEY/block/111/222', '/v1/friends/:serviceCode/block/:nidNo/:friendNidNo')
// → { serviceCode: 'SENDMONEY', nidNo: '111', friendNidNo: '222' }

NURL.match('/v1/user/12345', '/v1/admin/:id')
// → null (no match)

Masking Path Parameters

NURL provides NURL.mask(url, options) static method to mask sensitive path parameters in a URL for logging purposes:

// Default masking (**** with length 4)
NURL.mask('/v1/user/12345/info', {
    patterns: ['/v1/user/:userId/info'],
    sensitiveParams: ['userId'],
})
// → '/v1/user/****/info'

// Custom mask character and length
NURL.mask('/v1/user/12345/info', {
    patterns: ['/v1/user/[userId]/info'],
    sensitiveParams: ['userId'],
    maskChar: 'X',
    maskLength: 6,
})
// → '/v1/user/XXXXXX/info'

// Preserve original value length
NURL.mask('/v1/user/12345/info', {
    patterns: ['/v1/user/:userId/info'],
    sensitiveParams: ['userId'],
    preserveLength: true,
})
// → '/v1/user/*****/info' (5 chars, same as '12345')

// Multiple sensitive params
NURL.mask('/v1/friends/SENDMONEY/block/12345/67890', {
    patterns: ['/v1/friends/:serviceCode/block/[nidNo]/:friendNidNo'],
    sensitiveParams: ['nidNo', 'friendNidNo'],
    preserveLength: true,
})
// → '/v1/friends/SENDMONEY/block/*****/*****' (5 and 5 chars)

API

constructor(input?: string | URL | URLOptions)

• input: Can be one of the following:
  • string: Standard URL string
  • URL: Standard URL object
  • URLOptions: Custom options object that extends Partial<URL> and includes:
    • baseUrl?: string: Optional base URL string
    • query?: Record<string, string>: Optional object for query parameters
    • Can include any property from the standard URL object (e.g., pathname, protocol, etc.)

Dynamic Segments

• Supports :paramName or [paramName] format in the pathname.
• If a corresponding key exists in the query object or URLOptions, the dynamic segment is replaced with its value.
• If a corresponding key does not exist, the dynamic segment remains unchanged in the pathname without throwing an error.

Properties

NURL inherits all properties from the standard URL class:

• href, origin, protocol, username, password, host, hostname, port, pathname, search, searchParams, hash

Methods

• toString(): Returns the URL as a string
• toJSON(): Returns the URL as a JSON representation

Static Methods

• NURL.create(input?: string | URL | URLOptions): NURL
  • Factory function to create a NURL instance without the new keyword.
• NURL.canParse(url: string): boolean
  • Checks if the given string can be parsed as a valid URL.
• NURL.match(url: string, pattern: string): Record<string, string> | null
  • Matches a URL path against a pattern with dynamic segments and returns an object with extracted parameters or null if no match.
• NURL.mask(url: string, options: MaskOptions): string
  • Masks sensitive path parameters in a URL based on the provided options.
  • MaskOptions:
    • patterns: string[]: Array of URL patterns with dynamic segments.
    • sensitiveParams: string[]: Array of path parameters to be masked.
    • maskChar?: string: Character used for masking (default: '*').
    • maskLength?: number: Length of the mask (default: 4).
    • preserveLength?: boolean: If true, mask length matches original value length (overrides maskLength).

Important Notes

• NURL's setter methods behave differently from the standard URL. They are designed to consider dynamic segment and query parameter replacement functionality.
• When created with no arguments, all properties are initialized as empty strings.
• When using URLOptions, if a query value corresponding to a dynamic segment is missing, the dynamic segment remains unchanged in the pathname.
• Dynamic segments only support the :paramName or [paramName] format.

Differences from Standard URL

• Constructor Flexibility: NURL can create a URL from a string, URL object, or custom options object.
• Empty URL Creation: NURL can create an empty URL when called with no arguments.
• Dynamic Segments: NURL supports dynamic segments in the pathname.
• Setter Behavior: NURL's setter methods behave differently from the standard URL, considering dynamic segment processing and query parameter replacement.