tessl/npm-urijs

URI.js is a Javascript library for working with URLs.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

URI.js

Name: tessl/npm-urijs
Author: tessl

URI.js is a comprehensive JavaScript library for working with URIs and URLs. It provides a chainable fluent API for parsing, manipulating, and building URIs with RFC 3986 compliance, supporting complex URI operations that would otherwise require verbose and error-prone string manipulation.

Package Information

Package Name: urijs
Package Type: npm
Language: JavaScript (UMD compatible)
Installation: npm install urijs

Core Imports

// Node.js/CommonJS
const URI = require('urijs');

// ES6 Modules
import URI from 'urijs';

// Browser global
// <script src="URI.js"></script>
// URI is available as window.URI

Basic Usage

import URI from 'urijs';

// Create and manipulate URIs
const uri = new URI('http://user:pass@example.com:8080/path/to/file.html?query=value#fragment');

// Get/set components
console.log(uri.hostname()); // 'example.com'
console.log(uri.port()); // 8080
console.log(uri.pathname()); // '/path/to/file.html'

// Chain operations
const newUri = uri
  .hostname('newhost.com')
  .port(9000)
  .addQuery('param', 'value')
  .fragment('section');

console.log(newUri.toString()); // 'http://user:pass@newhost.com:9000/path/to/file.html?query=value&param=value#section'

// Parse and build URIs
const parsed = URI.parse('https://example.com/api/users?page=1');
console.log(parsed.hostname); // 'example.com'
console.log(parsed.query); // 'page=1'

Architecture

URI.js is built around several key components:

Core URI Class: Main constructor providing chainable instance methods for all URI components
Static Parser/Builder: Low-level functions for parsing URI strings into parts and building them back
Encoding System: Configurable encoding/decoding with support for different character sets
Extension Modules: Optional modules for IPv6, Second Level Domains, URI Templates, and Punycode
Plugin Extensions: Fragment query/URI extensions and jQuery integration
UMD Pattern: Universal module support for Node.js, AMD, and browser environments

Capabilities

URI Construction and Parsing

Core functionality for creating, parsing, and building URI instances with full component access.

// Constructor
function URI(url?: string, base?: string): URI;

// Static parsing and building
URI.parse(string: string, parts?: object): object;
URI.parseHost(string: string, parts?: object): object;
URI.parseAuthority(string: string, parts?: object): object;
URI.parseUserinfo(string: string, parts?: object): object;
URI.parseQuery(string: string, escapeQuerySpace?: boolean): object;
URI.build(parts: object): string;
URI.buildHost(parts: object): string;
URI.buildAuthority(parts: object): string;
URI.buildUserinfo(parts: object): string;
URI.buildQuery(data: object, duplicateParams?: boolean, escapeQuerySpace?: boolean): string;

URI Construction

Component Access and Manipulation

Get and set individual URI components (protocol, hostname, port, path, query, fragment) with automatic URI rebuilding.

// Primary component getters/setters (return property when no args, return URI instance when setting)
protocol(value?: string, build?: boolean): string | URI;
scheme(value?: string, build?: boolean): string | URI; // alias for protocol
hostname(value?: string, build?: boolean): string | URI;
port(value?: string | number, build?: boolean): string | URI;
path(value?: string, build?: boolean): string | URI;
pathname(value?: string, build?: boolean): string | URI; // alias for path
query(value?: string | object, build?: boolean): string | URI;
search(value?: string | object, build?: boolean): string | URI; // alias for query
fragment(value?: string, build?: boolean): string | URI;
hash(value?: string, build?: boolean): string | URI; // alias for fragment

// Compound component getters/setters
href(value?: string, build?: boolean): string | URI; // complete URI
origin(value?: string, build?: boolean): string | URI; // protocol + authority
authority(value?: string, build?: boolean): string | URI; // userinfo + host
userinfo(value?: string, build?: boolean): string | URI; // username + password
host(value?: string, build?: boolean): string | URI; // hostname + port
resource(value?: string, build?: boolean): string | URI; // path + query + fragment

// Individual userinfo components
username(value?: string, build?: boolean): string | URI;
password(value?: string, build?: boolean): string | URI;

// Domain component getters/setters
subdomain(value?: string, build?: boolean): string | URI;
domain(value?: string, build?: boolean): string | URI;
tld(value?: string, build?: boolean): string | URI;

// Path component getters/setters
directory(value?: string, build?: boolean): string | URI;
filename(value?: string, build?: boolean): string | URI;
suffix(value?: string, build?: boolean): string | URI;

Component Manipulation

Query Parameter Management

Advanced query string manipulation with support for arrays, objects, and flexible parameter handling.

setQuery(name: string | object, value?: string, build?: boolean): URI;
setSearch(name: string | object, value?: string, build?: boolean): URI; // alias
addQuery(name: string | object, value?: string, build?: boolean): URI;
addSearch(name: string | object, value?: string, build?: boolean): URI; // alias
removeQuery(name: string, value?: string, build?: boolean): URI;
removeSearch(name: string, value?: string, build?: boolean): URI; // alias
hasQuery(name: string, value?: string, withinArray?: boolean): boolean;
hasSearch(name: string, value?: string, withinArray?: boolean): boolean; // alias

Query Management

Path Manipulation

Path segment manipulation, directory/filename extraction, and path normalization.

segment(segment?: number | string | string[], value?: string, build?: boolean): string | string[] | URI;
segmentCoded(segment?: number | string | string[], value?: string, build?: boolean): string | string[] | URI; // URL-decoded segments
directory(value?: string, build?: boolean): string | URI;
filename(value?: string, build?: boolean): string | URI;
suffix(value?: string, build?: boolean): string | URI;

Path Manipulation

URI Normalization and Encoding

Normalize URIs according to RFC standards, handle different encoding schemes, and ensure URI validity.

normalize(): URI;
normalizeProtocol(build?: boolean): URI;
normalizeHostname(build?: boolean): URI;
normalizePort(build?: boolean): URI;
normalizePath(build?: boolean): URI;
normalizePathname(build?: boolean): URI; // alias for normalizePath
normalizeQuery(build?: boolean): URI;
normalizeSearch(build?: boolean): URI; // alias for normalizeQuery
normalizeFragment(build?: boolean): URI;
normalizeHash(build?: boolean): URI; // alias for normalizeFragment
iso8859(): URI;
unicode(): URI;
readable(): URI;

Normalization and Encoding

URI Resolution and Comparison

Convert between relative and absolute URIs, resolve against base URIs, and compare URI equality.

absoluteTo(base: string | URI): URI;
relativeTo(base: string | URI): URI;
equals(uri: string | URI): boolean;

Resolution and Comparison

Static Utilities

Utility functions for encoding/decoding, finding URIs in text, joining paths, and configuration.

// Version and configuration properties
URI.version: string; // Library version (e.g., '1.19.11')
URI.preventInvalidHostname: boolean; // Global hostname validation control
URI.duplicateQueryParameters: boolean; // Global duplicate parameter handling
URI.escapeQuerySpace: boolean; // Global space encoding preference
URI.defaultPorts: object; // Protocol to default port mapping
URI.hostProtocols: string[]; // Protocols that require hostnames

// Encoding/decoding utilities
URI.encode(string: string): string;
URI.decode(string: string): string;
URI.encodeQuery(string: string, escapeQuerySpace?: boolean): string;
URI.decodeQuery(string: string, escapeQuerySpace?: boolean): string;
URI.encodePathSegment(string: string): string;
URI.decodePathSegment(string: string): string;
URI.encodeReserved(string: string): string;

// String processing utilities
URI.withinString(string: string, callback: function, options?: object): string;
URI.joinPaths(...paths: string[]): string;
URI.commonPath(one: string, two: string): string;

// Validation utilities
URI.ensureValidHostname(hostname: string, protocol?: string): string;
URI.ensureValidPort(port: string | number): string;
URI.getDomAttribute(node: Element): string;

// Environment utilities
URI.noConflict(removeAll?: boolean): URI; // Restore previous URI global
URI.iso8859(): void; // Set global encoding to ISO-8859-1
URI.unicode(): void; // Set global encoding to Unicode

Static Utilities

URI Utility Methods

Additional utility methods for URI manipulation and validation.

// URI type checking - returns boolean
is(what: string): boolean; // 'relative', 'absolute', 'domain', 'ip', 'ip4', 'ip6', 'idn', 'url', 'urn', 'sld', 'punycode'

// URI manipulation
clone(): URI; // create deep copy
equals(uri: string | URI): boolean; // compare URIs for equality
toString(): string; // get string representation
valueOf(): string; // get string representation
readable(): string; // get human-readable representation

// Configuration methods (chainable)
preventInvalidHostname(v?: boolean): boolean | URI;
duplicateQueryParameters(v?: boolean): boolean | URI;
escapeQuerySpace(v?: boolean): boolean | URI;

// Internal build control
build(deferBuild?: boolean): URI;

Extensions

IPv6 Support

IPv6.best(address: string): string;

IPv6 Support

Second Level Domains

SecondLevelDomains.has(domain: string): boolean;
SecondLevelDomains.is(domain: string): boolean;
SecondLevelDomains.get(domain: string): string;

Second Level Domains

URI Templates (RFC 6570)

function URITemplate(expression: string): URITemplate;
URITemplate.prototype.expand(data: object, opts?: object): string;
URI.expand(expression: string, data: object): URI;

URI Templates

Fragment Extensions

Enhanced fragment handling for query-like and URI-like fragment operations.

setFragment(name: string, value: string, build?: boolean): URI;
setHash(name: string, value: string, build?: boolean): URI; // alias
addFragment(name: string, value: string, build?: boolean): URI;
addHash(name: string, value: string, build?: boolean): URI; // alias
removeFragment(name: string, value?: string, build?: boolean): URI;
removeHash(name: string, value?: string, build?: boolean): URI; // alias

Fragment Extensions