@naverpay/nurl 1.0.3 → 1.1.0-canary.251230-7c2e8df

package/README.md

@@ -25,7 +25,7 @@ NURL is a powerful URL manipulation library that extends the standard URL class.
 ### Basic Usage
 
 ```javascript
-import { NURL } from 'nurl'
+import {NURL} from 'nurl'
 
 // Create URL from string
 const url1 = new NURL('https://example.com/users/123?name=John')
@@ -36,9 +36,9 @@ 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' }
+    baseUrl: 'https://example.com',
+    pathname: '/users/:id',
+    query: {id: '123', name: 'John'},
 })
 
 // Create empty URL
@@ -49,9 +49,9 @@ 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' }
+    baseUrl: 'https://example.com',
+    pathname: '/users/:id',
+    query: {id: '123', name: 'John'},
 })
 ```
 
@@ -61,13 +61,13 @@ NURL processes dynamic segments in the pathname and replaces them with values fr
 
 ```javascript
 const url = new NURL({
-  baseUrl: 'https://api.example.com',
-  pathname: '/users/:a/posts/[b]/[c]',
-  query: {
-    a: '123',
-    b: '456',
-    format: 'json'
-  }
+    baseUrl: 'https://api.example.com',
+    pathname: '/users/:a/posts/[b]/[c]',
+    query: {
+        a: '123',
+        b: '456',
+        format: 'json',
+    },
 })
 
 console.log(url.href)
@@ -84,6 +84,59 @@ 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:
+
+```tsx
+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:
+
+```tsx
+// 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)`
@@ -113,6 +166,23 @@ NURL inherits all properties from the standard URL class:
 - `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
 
 1. NURL's setter methods behave differently from the standard URL. They are designed to consider dynamic segment and query parameter replacement functionality.

package/dist/cjs/index.d.ts

@@ -1,3 +1,5 @@
+import { MaskOptions } from './utils.js';
+
 type Query = Record<string, any>;
 
 interface URLOptions extends Partial<Pick<URL, 'href' | 'protocol' | 'host' | 'hostname' | 'port' | 'pathname' | 'search' | 'hash' | 'username' | 'password'>> {
@@ -72,6 +74,8 @@ declare class NURL implements URL {
     private encodeHostname;
     get decodedIDN(): string;
     get decodedHostname(): string;
+    static match(url: string, pattern: string): Record<string, string> | null;
+    static mask(url: string, options: MaskOptions): string;
 }
 
 export { NURL as default };

package/dist/cjs/nurl.js

@@ -1 +1 @@
-"use strict";const m=require("./punycode.js"),r=require("./utils.js");class i{constructor(t){if(this._href="",this._protocol="",this._host="",this._hostname="",this._port="",this._pathname="",this._search="",this._hash="",this._origin="",this._username="",this._password="",this._baseUrl="",this._searchParams=new URLSearchParams,this._basePath="",this.punycodePrefix="xn--",this._searchParams=new URLSearchParams,typeof t=="string"||t instanceof URL)this.href=t.toString();else if(t){if(t.basePath&&(this._basePath=t.basePath.startsWith("/")?t.basePath:`/${t.basePath}`),t.baseUrl&&(this.baseUrl=t.baseUrl),t.href&&(this.href=t.href),t.protocol&&(this.protocol=t.protocol),t.host&&(this.host=t.host),t.hostname&&(this.hostname=t.hostname),t.port&&(this.port=t.port),t.pathname!==void 0&&(t.pathname===""?this._pathname="":this.pathname=r.refinePathnameWithQuery(t.pathname,t.query??{})),t.search&&(this.search=t.search),t.hash&&(this.hash=t.hash),t.username&&(this.username=t.username),t.password&&(this.password=t.password),t.query){const s=r.refineQueryWithPathname(t.pathname??"",t.query);Object.keys(s).length>0&&(this.search=new URLSearchParams(r.convertQueryToArray(s)).toString())}this.updateHref()}}static withBasePath(t){return s=>typeof s=="string"||s instanceof URL?new i({href:s.toString(),basePath:t}):new i({...s,basePath:t})}static create(t){return new i(t)}static canParse(t){if(t.startsWith("/"))return/^\/[^?#]*(\?[^#]*)?(#.*)?$/.test(t);try{return new URL(t),!0}catch{return/^[^:/?#]+(\.[^:/?#]+)+(\/[^?#]*(\?[^#]*)?(#.*)?)?$/.test(t)}}get baseUrl(){return this._baseUrl}set baseUrl(t){this._baseUrl=t;try{const s=new URL(t);this._protocol=s.protocol,this._host=s.host,this._hostname=s.hostname,this._port=s.port,this._origin=s.origin,this._username=s.username,this._password=s.password,s.pathname!=="/"&&(this._pathname=s.pathname),s.search&&(this._search=s.search,this._searchParams=new URLSearchParams(s.search)),s.hash&&(this._hash=s.hash),this.updateHref()}catch(s){console.warn(`Invalid baseUrl: ${t}`,s)}}get href(){return this._href}set href(t){try{const s=new URL(t);this._href=s.href,this._protocol=s.protocol,this._host=s.host,this._hostname=s.hostname,this._port=s.port,this._pathname=s.pathname,this._search=s.search,this._hash=s.hash,this._origin=s.origin,this._username=s.username,this._password=s.password,this._searchParams=s.searchParams}catch(s){const e=i.parseStringToURLLike(t);if(!e)throw console.warn(`Can not parse ${t}`),s;this._href=e.href,this._protocol=e.protocol,this._host=e.hostname,this._hostname=e.hostname,this._port=e.port,this._pathname=e.pathname,this._search=e.search,this._hash=e.hash,this._origin=e.origin,this._username=e.username,this._password=e.password,this._searchParams=e.searchParams}}static parseStringToURLLike(t){const s=/^(?:(https?:\/\/)(?:([^:@]+)(?::([^@]+))?@)?((?:[^/:?#]+)(?::(\d+))?)?)?([/][^?#]*)?(\?[^#]*)?(#.*)?$/,e=t.match(s),[h=t,a="",n="",d="",o="",c="",p="",_="",f=""]=e||[];if(!e||a&&!o&&!p&&!_&&!f)return null;const P=a&&o?`${a}//${o}${c?`:${c}`:""}`:"";return{href:h,protocol:a,host:o,hostname:o,port:c,pathname:t?p||"/":"",search:_,hash:f,origin:P,username:n,password:d,searchParams:new URLSearchParams(_)}}get protocol(){return this._protocol}set protocol(t){this._protocol=t,this.updateHref()}get host(){return this._host}set host(t){const[s,e]=t.split(":"),h=this.encodeHostname(s);this._host=e?`${h}:${e}`:h,this._hostname=h,this._port=e||"",this.updateHref()}get hostname(){return this._hostname}set hostname(t){const s=this.encodeHostname(t);this._hostname=s,this._host=this._port?`${s}:${this._port}`:s,this.updateHref()}get port(){return this._port}set port(t){this._port=t,this._host=`${this._hostname}${t?":"+t:""}`,this.updateHref()}get pathname(){return this._pathname}set pathname(t){let s=t;if(t===""){s="/",this._pathname=s,this.updateHref();return}this._basePath&&!s.startsWith(this._basePath)&&(s=`${this._basePath}${s.startsWith("/")?"":"/"}${s}`);const e=s.split("/").map(h=>r.isDynamicPath(h)?h:encodeURI(h)).join("/");this._pathname=e.startsWith("/")?e:`/${e}`,this.updateHref()}get search(){return this._search}set search(t){this._search=t.startsWith("?")?t:`?${t}`,this._searchParams=new URLSearchParams(t),this.updateHref()}setSearchParams(t){const s=new URLSearchParams(t);this._search=s.toString()?`?${s.toString()}`:"",this._searchParams=s,this.updateHref()}appendSearchParams(t){const s=new URLSearchParams(this._searchParams),e=r.getDynamicPaths(this._pathname).map(r.extractPathKey);Object.keys(t).forEach(h=>{e.includes(h)?this._pathname=r.refinePathnameWithQuery(this._pathname,{[h]:t[h]}):s.append(h,t[h])}),this._search=s.toString()?`?${s.toString()}`:"",this._searchParams=s,this.updateHref()}removeSearchParams(...t){const s=new URLSearchParams(this._searchParams);t.forEach(e=>{s.delete(e)}),this._search=s.toString()?`?${s.toString()}`:"",this._searchParams=s,this.updateHref()}get searchParams(){return new Proxy(this._searchParams,{get:(t,s,e)=>{const h=Reflect.get(t,s,e);return typeof h=="function"?(...a)=>{const n=h.apply(t,a);return this._search=this._searchParams.toString()?`?${this._searchParams.toString()}`:"",this.updateHref(),n}:h}})}get hash(){return this._hash}set hash(t){this._hash=t.startsWith("#")?t:`#${t}`,this.updateHref()}get origin(){return this._origin}get username(){return this._username}set username(t){this._username=t,this.updateHref()}get password(){return this._password}set password(t){this._password=t,this.updateHref()}updateHref(){const t=this._pathname;if(this._baseUrl){const s=new URL(this._baseUrl);s.pathname=t,s.search=this._search,s.hash=this._hash,this._href=s.href,this._origin=s.origin}else this._href=`${this._protocol}${this._protocol&&"//"}${this._username}${this._password?":"+this._password:""}${this._username||this._password?"@":""}${this._hostname}${this._port?":"+this._port:""}${t}${this._search}${this._hash}`,this._origin=`${this._protocol}//${this._hostname}${this._port?":"+this._port:""}`}toString(){return this.href}toJSON(){return this.href}encodeHostname(t){return t.split(".").map(s=>{for(const e of s)if(r.isASCIICodeChar(e))return`${this.punycodePrefix}${m.encode(s)}`;return s}).join(".")}get decodedIDN(){let t=this._href;return this._hostname.split(".").forEach(s=>{t=t.replace(s,m.decode(s.replace(this.punycodePrefix,"")))}),t}get decodedHostname(){return this._hostname.split(".").map(t=>m.decode(t.replace(this.punycodePrefix,""))).join(".")}}module.exports=i;
+"use strict";const m=require("./punycode.js"),d=require("./utils/external.js"),r=require("./utils/internal.js");class i{constructor(t){if(this._href="",this._protocol="",this._host="",this._hostname="",this._port="",this._pathname="",this._search="",this._hash="",this._origin="",this._username="",this._password="",this._baseUrl="",this._searchParams=new URLSearchParams,this._basePath="",this.punycodePrefix="xn--",this._searchParams=new URLSearchParams,typeof t=="string"||t instanceof URL)this.href=t.toString();else if(t){if(t.basePath&&(this._basePath=t.basePath.startsWith("/")?t.basePath:`/${t.basePath}`),t.baseUrl&&(this.baseUrl=t.baseUrl),t.href&&(this.href=t.href),t.protocol&&(this.protocol=t.protocol),t.host&&(this.host=t.host),t.hostname&&(this.hostname=t.hostname),t.port&&(this.port=t.port),t.pathname!==void 0&&(t.pathname===""?this._pathname="":this.pathname=r.refinePathnameWithQuery(t.pathname,t.query??{})),t.search&&(this.search=t.search),t.hash&&(this.hash=t.hash),t.username&&(this.username=t.username),t.password&&(this.password=t.password),t.query){const s=r.refineQueryWithPathname(t.pathname??"",t.query);Object.keys(s).length>0&&(this.search=new URLSearchParams(r.convertQueryToArray(s)).toString())}this.updateHref()}}static withBasePath(t){return s=>typeof s=="string"||s instanceof URL?new i({href:s.toString(),basePath:t}):new i({...s,basePath:t})}static create(t){return new i(t)}static canParse(t){if(t.startsWith("/"))return/^\/[^?#]*(\?[^#]*)?(#.*)?$/.test(t);try{return new URL(t),!0}catch{return/^[^:/?#]+(\.[^:/?#]+)+(\/[^?#]*(\?[^#]*)?(#.*)?)?$/.test(t)}}get baseUrl(){return this._baseUrl}set baseUrl(t){this._baseUrl=t;try{const s=new URL(t);this._protocol=s.protocol,this._host=s.host,this._hostname=s.hostname,this._port=s.port,this._origin=s.origin,this._username=s.username,this._password=s.password,s.pathname!=="/"&&(this._pathname=s.pathname),s.search&&(this._search=s.search,this._searchParams=new URLSearchParams(s.search)),s.hash&&(this._hash=s.hash),this.updateHref()}catch(s){console.warn(`Invalid baseUrl: ${t}`,s)}}get href(){return this._href}set href(t){try{const s=new URL(t);this._href=s.href,this._protocol=s.protocol,this._host=s.host,this._hostname=s.hostname,this._port=s.port,this._pathname=s.pathname,this._search=s.search,this._hash=s.hash,this._origin=s.origin,this._username=s.username,this._password=s.password,this._searchParams=s.searchParams}catch(s){const e=i.parseStringToURLLike(t);if(!e)throw console.warn(`Can not parse ${t}`),s;this._href=e.href,this._protocol=e.protocol,this._host=e.hostname,this._hostname=e.hostname,this._port=e.port,this._pathname=e.pathname,this._search=e.search,this._hash=e.hash,this._origin=e.origin,this._username=e.username,this._password=e.password,this._searchParams=e.searchParams}}static parseStringToURLLike(t){const s=/^(?:(https?:\/\/)(?:([^:@]+)(?::([^@]+))?@)?((?:[^/:?#]+)(?::(\d+))?)?)?([/][^?#]*)?(\?[^#]*)?(#.*)?$/,e=t.match(s),[h=t,a="",n="",P="",o="",c="",p="",_="",f=""]=e||[];if(!e||a&&!o&&!p&&!_&&!f)return null;const l=a&&o?`${a}//${o}${c?`:${c}`:""}`:"";return{href:h,protocol:a,host:o,hostname:o,port:c,pathname:t?p||"/":"",search:_,hash:f,origin:l,username:n,password:P,searchParams:new URLSearchParams(_)}}get protocol(){return this._protocol}set protocol(t){this._protocol=t,this.updateHref()}get host(){return this._host}set host(t){const[s,e]=t.split(":"),h=this.encodeHostname(s);this._host=e?`${h}:${e}`:h,this._hostname=h,this._port=e||"",this.updateHref()}get hostname(){return this._hostname}set hostname(t){const s=this.encodeHostname(t);this._hostname=s,this._host=this._port?`${s}:${this._port}`:s,this.updateHref()}get port(){return this._port}set port(t){this._port=t,this._host=`${this._hostname}${t?":"+t:""}`,this.updateHref()}get pathname(){return this._pathname}set pathname(t){let s=t;if(t===""){s="/",this._pathname=s,this.updateHref();return}this._basePath&&!s.startsWith(this._basePath)&&(s=`${this._basePath}${s.startsWith("/")?"":"/"}${s}`);const e=s.split("/").map(h=>r.isDynamicPath(h)?h:encodeURI(h)).join("/");this._pathname=e.startsWith("/")?e:`/${e}`,this.updateHref()}get search(){return this._search}set search(t){this._search=t.startsWith("?")?t:`?${t}`,this._searchParams=new URLSearchParams(t),this.updateHref()}setSearchParams(t){const s=new URLSearchParams(t);this._search=s.toString()?`?${s.toString()}`:"",this._searchParams=s,this.updateHref()}appendSearchParams(t){const s=new URLSearchParams(this._searchParams),e=r.getDynamicPaths(this._pathname).map(r.extractPathKey);Object.keys(t).forEach(h=>{e.includes(h)?this._pathname=r.refinePathnameWithQuery(this._pathname,{[h]:t[h]}):s.append(h,t[h])}),this._search=s.toString()?`?${s.toString()}`:"",this._searchParams=s,this.updateHref()}removeSearchParams(...t){const s=new URLSearchParams(this._searchParams);t.forEach(e=>{s.delete(e)}),this._search=s.toString()?`?${s.toString()}`:"",this._searchParams=s,this.updateHref()}get searchParams(){return new Proxy(this._searchParams,{get:(t,s,e)=>{const h=Reflect.get(t,s,e);return typeof h=="function"?(...a)=>{const n=h.apply(t,a);return this._search=this._searchParams.toString()?`?${this._searchParams.toString()}`:"",this.updateHref(),n}:h}})}get hash(){return this._hash}set hash(t){this._hash=t.startsWith("#")?t:`#${t}`,this.updateHref()}get origin(){return this._origin}get username(){return this._username}set username(t){this._username=t,this.updateHref()}get password(){return this._password}set password(t){this._password=t,this.updateHref()}updateHref(){const t=this._pathname;if(this._baseUrl){const s=new URL(this._baseUrl);s.pathname=t,s.search=this._search,s.hash=this._hash,this._href=s.href,this._origin=s.origin}else this._href=`${this._protocol}${this._protocol&&"//"}${this._username}${this._password?":"+this._password:""}${this._username||this._password?"@":""}${this._hostname}${this._port?":"+this._port:""}${t}${this._search}${this._hash}`,this._origin=`${this._protocol}//${this._hostname}${this._port?":"+this._port:""}`}toString(){return this.href}toJSON(){return this.href}encodeHostname(t){return t.split(".").map(s=>{for(const e of s)if(r.isASCIICodeChar(e))return`${this.punycodePrefix}${m.encode(s)}`;return s}).join(".")}get decodedIDN(){let t=this._href;return this._hostname.split(".").forEach(s=>{t=t.replace(s,m.decode(s.replace(this.punycodePrefix,"")))}),t}get decodedHostname(){return this._hostname.split(".").map(t=>m.decode(t.replace(this.punycodePrefix,""))).join(".")}static match(t,s){return d.match(t,s)}static mask(t,s){return d.mask(t,s)}}module.exports=i;

package/dist/cjs/utils/external.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const f=require("../nurl.js"),l=require("./internal.js"),g=(r,c)=>{if(!f.canParse(r)||!f.canParse(c))return null;const i=r.split(/[?#]/)[0]?.split("/").filter(Boolean)||[],a=c.split(/[?#]/)[0]?.split("/").filter(Boolean)||[];if(i.length!==a.length)return null;const u={};for(let n=0;n<a.length;n++){const o=a[n],t=i[n];if(l.isDynamicPath(o)){const e=l.extractPathKey(o);u[e]=t}else if(o!==t)return null}return u},P=(r,{patterns:c,sensitiveParams:i,maskChar:a="*",maskLength:u=4,preserveLength:n=!1})=>{const o=[...c].sort((t,e)=>l.getPathPriority(e)>l.getPathPriority(t)?1:-1);for(const t of o){const e=f.create(r),s=g(e.pathname,t);if(s)return i.forEach(h=>{if(h in s){const m=s[h],p=n?m.length:u;s[h]=a.repeat(p)}}),e.pathname=l.refinePathnameWithQuery(t,s),e.toString()}return r};exports.mask=P;exports.match=g;

package/dist/cjs/utils/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./external.js");exports.mask=e.mask;exports.match=e.match;

package/dist/cjs/utils/internal.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const y=/^:/,P=/^\[.*\]$/;function o(t){return y.test(t)||P.test(t)}function s(t){return t.split("/").filter(o)}function a(t){return t.slice(1,y.test(t)?void 0:-1)}function h(t,r){return s(t).reduce((e,n)=>{const i=a(n),u=r[i];return u&&typeof u=="string"?e.replace(n,u):e},t)}function m(t,r){return s(t).reduce((e,n)=>{const i=a(n);if(typeof e[i]!="string")return e;const{[i]:d,...f}=e;return f},r)}const g=127;function A(t){return t.charCodeAt(0)>g}function c(t){return["string","number","boolean"].includes(typeof t)}function l(t){return Object.entries(t).flatMap(([r,e])=>c(e)?[[r,String(e)]]:Array.isArray(e)&&e.every(c)?e.map(n=>[r,String(n)]):[])}function C(t){return t.split("/").filter(Boolean).map(e=>o(e)?"1":"2").join("")}exports.convertQueryToArray=l;exports.extractPathKey=a;exports.getDynamicPaths=s;exports.getPathPriority=C;exports.isASCIICodeChar=A;exports.isDynamicPath=o;exports.refinePathnameWithQuery=h;exports.refineQueryWithPathname=m;

package/dist/cjs/utils.d.ts

@@ -0,0 +1,11 @@
+declare const match: (url: string, pattern: string) => Record<string, string> | null;
+interface MaskOptions {
+    patterns: string[];
+    sensitiveParams: string[];
+    maskChar?: string;
+    maskLength?: number;
+    preserveLength?: boolean;
+}
+declare const mask: (url: string, { patterns, sensitiveParams, maskChar, maskLength, preserveLength }: MaskOptions) => string;
+
+export { type MaskOptions, mask, match };

package/dist/esm/index.d.mts

@@ -1,3 +1,5 @@
+import { MaskOptions } from './utils.mjs';
+
 type Query = Record<string, any>;
 
 interface URLOptions extends Partial<Pick<URL, 'href' | 'protocol' | 'host' | 'hostname' | 'port' | 'pathname' | 'search' | 'hash' | 'username' | 'password'>> {
@@ -72,6 +74,8 @@ declare class NURL implements URL {
     private encodeHostname;
     get decodedIDN(): string;
     get decodedHostname(): string;
+    static match(url: string, pattern: string): Record<string, string> | null;
+    static mask(url: string, options: MaskOptions): string;
 }
 
 export { NURL as default };

package/dist/esm/nurl.mjs

@@ -1,13 +1,14 @@
 import { encode as l, decode as p } from "./punycode.mjs";
-import { refinePathnameWithQuery as f, refineQueryWithPathname as g, convertQueryToArray as $, isDynamicPath as u, getDynamicPaths as w, extractPathKey as S, isASCIICodeChar as U } from "./utils.mjs";
+import { match as g, mask as u } from "./utils/external.mjs";
+import { refinePathnameWithQuery as f, refineQueryWithPathname as $, convertQueryToArray as w, isDynamicPath as S, getDynamicPaths as U, extractPathKey as H, isASCIICodeChar as b } from "./utils/internal.mjs";
 class i {
   constructor(t) {
     if (this._href = "", this._protocol = "", this._host = "", this._hostname = "", this._port = "", this._pathname = "", this._search = "", this._hash = "", this._origin = "", this._username = "", this._password = "", this._baseUrl = "", this._searchParams = new URLSearchParams(), this._basePath = "", this.punycodePrefix = "xn--", this._searchParams = new URLSearchParams(), typeof t == "string" || t instanceof URL)
       this.href = t.toString();
     else if (t) {
       if (t.basePath && (this._basePath = t.basePath.startsWith("/") ? t.basePath : `/${t.basePath}`), t.baseUrl && (this.baseUrl = t.baseUrl), t.href && (this.href = t.href), t.protocol && (this.protocol = t.protocol), t.host && (this.host = t.host), t.hostname && (this.hostname = t.hostname), t.port && (this.port = t.port), t.pathname !== void 0 && (t.pathname === "" ? this._pathname = "" : this.pathname = f(t.pathname, t.query ?? {})), t.search && (this.search = t.search), t.hash && (this.hash = t.hash), t.username && (this.username = t.username), t.password && (this.password = t.password), t.query) {
-        const s = g(t.pathname ?? "", t.query);
-        Object.keys(s).length > 0 && (this.search = new URLSearchParams($(s)).toString());
+        const s = $(t.pathname ?? "", t.query);
+        Object.keys(s).length > 0 && (this.search = new URLSearchParams(w(s)).toString());
       }
       this.updateHref();
     }
@@ -115,7 +116,7 @@ class i {
       return;
     }
     this._basePath && !s.startsWith(this._basePath) && (s = `${this._basePath}${s.startsWith("/") ? "" : "/"}${s}`);
-    const e = s.split("/").map((h) => u(h) ? h : encodeURI(h)).join("/");
+    const e = s.split("/").map((h) => S(h) ? h : encodeURI(h)).join("/");
     this._pathname = e.startsWith("/") ? e : `/${e}`, this.updateHref();
   }
   get search() {
@@ -129,7 +130,7 @@ class i {
     this._search = s.toString() ? `?${s.toString()}` : "", this._searchParams = s, this.updateHref();
   }
   appendSearchParams(t) {
-    const s = new URLSearchParams(this._searchParams), e = w(this._pathname).map(S);
+    const s = new URLSearchParams(this._searchParams), e = U(this._pathname).map(H);
     Object.keys(t).forEach((h) => {
       e.includes(h) ? this._pathname = f(this._pathname, {
         [h]: t[h]
@@ -191,7 +192,7 @@ class i {
   encodeHostname(t) {
     return t.split(".").map((s) => {
       for (const e of s)
-        if (U(e))
+        if (b(e))
           return `${this.punycodePrefix}${l(s)}`;
       return s;
     }).join(".");
@@ -205,6 +206,12 @@ class i {
   get decodedHostname() {
     return this._hostname.split(".").map((t) => p(t.replace(this.punycodePrefix, ""))).join(".");
   }
+  static match(t, s) {
+    return g(t, s);
+  }
+  static mask(t, s) {
+    return u(t, s);
+  }
 }
 export {
   i as default

package/dist/esm/utils/external.mjs

@@ -0,0 +1,42 @@
+import h from "../nurl.mjs";
+import { isDynamicPath as g, extractPathKey as P, getPathPriority as m, refinePathnameWithQuery as y } from "./internal.mjs";
+const S = (r, l) => {
+  if (!h.canParse(r) || !h.canParse(l))
+    return null;
+  const c = r.split(/[?#]/)[0]?.split("/").filter(Boolean) || [], o = l.split(/[?#]/)[0]?.split("/").filter(Boolean) || [];
+  if (c.length !== o.length)
+    return null;
+  const i = {};
+  for (let n = 0; n < o.length; n++) {
+    const a = o[n], t = c[n];
+    if (g(a)) {
+      const e = P(a);
+      i[e] = t;
+    } else if (a !== t)
+      return null;
+  }
+  return i;
+}, x = (r, {
+  patterns: l,
+  sensitiveParams: c,
+  maskChar: o = "*",
+  maskLength: i = 4,
+  preserveLength: n = !1
+}) => {
+  const a = [...l].sort((t, e) => m(e) > m(t) ? 1 : -1);
+  for (const t of a) {
+    const e = h.create(r), s = S(e.pathname, t);
+    if (s)
+      return c.forEach((f) => {
+        if (f in s) {
+          const p = s[f], u = n ? p.length : i;
+          s[f] = o.repeat(u);
+        }
+      }), e.pathname = y(t, s), e.toString();
+  }
+  return r;
+};
+export {
+  x as mask,
+  S as match
+};

package/dist/esm/utils/index.mjs

@@ -0,0 +1,5 @@
+import { mask as o, match as r } from "./external.mjs";
+export {
+  o as mask,
+  r as match
+};

package/dist/esm/utils/internal.mjs

@@ -0,0 +1,51 @@
+const s = /^:/, A = /^\[.*\]$/;
+function c(t) {
+  return s.test(t) || A.test(t);
+}
+function f(t) {
+  return t.split("/").filter(c);
+}
+function y(t) {
+  return t.slice(1, s.test(t) ? void 0 : -1);
+}
+function l(t, r) {
+  return f(t).reduce((e, n) => {
+    const i = y(n), u = r[i];
+    return u && typeof u == "string" ? e.replace(n, u) : e;
+  }, t);
+}
+function m(t, r) {
+  return f(t).reduce((e, n) => {
+    const i = y(n);
+    if (typeof e[i] != "string")
+      return e;
+    const {
+      [i]: g,
+      ...a
+    } = e;
+    return a;
+  }, r);
+}
+const P = 127;
+function C(t) {
+  return t.charCodeAt(0) > P;
+}
+function o(t) {
+  return ["string", "number", "boolean"].includes(typeof t);
+}
+function _(t) {
+  return Object.entries(t).flatMap(([r, e]) => o(e) ? [[r, String(e)]] : Array.isArray(e) && e.every(o) ? e.map((n) => [r, String(n)]) : []);
+}
+function d(t) {
+  return t.split("/").filter(Boolean).map((e) => c(e) ? "1" : "2").join("");
+}
+export {
+  _ as convertQueryToArray,
+  y as extractPathKey,
+  f as getDynamicPaths,
+  d as getPathPriority,
+  C as isASCIICodeChar,
+  c as isDynamicPath,
+  l as refinePathnameWithQuery,
+  m as refineQueryWithPathname
+};

package/dist/esm/utils.d.mts

@@ -0,0 +1,11 @@
+declare const match: (url: string, pattern: string) => Record<string, string> | null;
+interface MaskOptions {
+    patterns: string[];
+    sensitiveParams: string[];
+    maskChar?: string;
+    maskLength?: number;
+    preserveLength?: boolean;
+}
+declare const mask: (url: string, { patterns, sensitiveParams, maskChar, maskLength, preserveLength }: MaskOptions) => string;
+
+export { type MaskOptions, mask, match };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naverpay/nurl",
-  "version": "1.0.3",
+  "version": "1.1.0-canary.251230-7c2e8df",
   "description": "URL build library",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.mjs",
@@ -16,6 +16,16 @@
         "default": "./dist/cjs/index.js"
       }
     },
+    "./utils": {
+      "import": {
+        "types": "./dist/esm/utils.d.mts",
+        "default": "./dist/esm/utils/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/utils.d.ts",
+        "default": "./dist/cjs/utils/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -56,6 +66,6 @@
     "release": "changeset publish",
     "markdownlint": "markdownlint '**/*.md' '#.changeset' '#**/CHANGELOG.md'",
     "markdownlint:fix": "markdownlint --fix '**/*.md' '#.changeset' '#**/CHANGELOG.md'",
-    "release:canary": "changeset publish --no-git-tag --directory dist"
+    "release:canary": "changeset publish --no-git-tag --tag=canary --directory dist"
   }
 }

package/dist/cjs/utils.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=/^:/,P=/^\[.*\]$/;function y(e){return c.test(e)||P.test(e)}function o(e){return e.split("/").filter(y)}function a(e){return e.slice(1,c.test(e)?void 0:-1)}function h(e,r){return o(e).reduce((t,n)=>{const i=a(n),u=r[i];return u&&typeof u=="string"?t.replace(n,u):t},e)}function A(e,r){return o(e).reduce((t,n)=>{const i=a(n);if(typeof t[i]!="string")return t;const{[i]:g,...f}=t;return f},r)}const C=127;function m(e){return e.charCodeAt(0)>C}function s(e){return["string","number","boolean"].includes(typeof e)}function d(e){return Object.entries(e).flatMap(([r,t])=>s(t)?[[r,String(t)]]:Array.isArray(t)&&t.every(s)?t.map(n=>[r,String(n)]):[])}exports.convertQueryToArray=d;exports.extractPathKey=a;exports.getDynamicPaths=o;exports.isASCIICodeChar=m;exports.isDynamicPath=y;exports.refinePathnameWithQuery=h;exports.refineQueryWithPathname=A;

package/dist/esm/utils.mjs

@@ -1,47 +0,0 @@
-const s = /^:/, a = /^\[.*\]$/;
-function A(r) {
-  return s.test(r) || a.test(r);
-}
-function c(r) {
-  return r.split("/").filter(A);
-}
-function f(r) {
-  return r.slice(1, s.test(r) ? void 0 : -1);
-}
-function _(r, e) {
-  return c(r).reduce((t, n) => {
-    const i = f(n), u = e[i];
-    return u && typeof u == "string" ? t.replace(n, u) : t;
-  }, r);
-}
-function d(r, e) {
-  return c(r).reduce((t, n) => {
-    const i = f(n);
-    if (typeof t[i] != "string")
-      return t;
-    const {
-      [i]: P,
-      ...y
-    } = t;
-    return y;
-  }, e);
-}
-const C = 127;
-function g(r) {
-  return r.charCodeAt(0) > C;
-}
-function o(r) {
-  return ["string", "number", "boolean"].includes(typeof r);
-}
-function h(r) {
-  return Object.entries(r).flatMap(([e, t]) => o(t) ? [[e, String(t)]] : Array.isArray(t) && t.every(o) ? t.map((n) => [e, String(n)]) : []);
-}
-export {
-  h as convertQueryToArray,
-  f as extractPathKey,
-  c as getDynamicPaths,
-  g as isASCIICodeChar,
-  A as isDynamicPath,
-  _ as refinePathnameWithQuery,
-  d as refineQueryWithPathname
-};