NetAddress
Pure, platform-neutral values for MAC, IP, internet socket, and Unix path addresses.
Constants
ipv4Broadcast
The IPv4 broadcast address 255.255.255.255.
Signature
declare const ipv4Broadcast: Ipv4Addressipv4Loopback
The IPv4 loopback address 127.0.0.1.
Signature
declare const ipv4Loopback: Ipv4Addressipv4Unspecified
The unspecified IPv4 address 0.0.0.0.
Signature
declare const ipv4Unspecified: Ipv4Addressipv6Loopback
The IPv6 loopback address ::1.
Signature
declare const ipv6Loopback: Ipv6Addressipv6Unspecified
The unspecified IPv6 address ::.
Signature
declare const ipv6Unspecified: Ipv6AddressConstructors
inetAddress
Creates a checked internet address for an IP address and port.
Signature
declare function inetAddress(address: IpAddress, port: number): Result<InetAddress, NetAddressError>inetAddressFromIpString
Creates a checked internet address from a numeric IP string and port.
Gotchas
The address must be a numeric IPv4 or IPv6 literal. This function does not resolve hostnames or accept IPv6 brackets.
Signature
declare function inetAddressFromIpString(address: string, port: number): Result<InetAddress, NetAddressError>inetAddressV4
Creates a checked IPv4 internet address.
Signature
declare function inetAddressV4(address: Ipv4Address, port: number): Result<InetAddressV4, NetAddressError>inetAddressV6
Creates a checked IPv6 internet address with an optional scope identifier.
Signature
declare function inetAddressV6(address: Ipv6Address, port: number, options?: { readonly scopeId?: number;}): Result<InetAddressV6, NetAddressError>ipv4FromOctets
Creates an IPv4 address from four checked octets.
Signature
declare function ipv4FromOctets(octets: readonly [number, number, number, number]): Result<Ipv4Address, NetAddressError>ipv6FromSegments
Creates an IPv6 address from eight checked 16-bit segments.
Signature
declare function ipv6FromSegments(segments: readonly [number, number, number, number, number, number, number, number]): Result<Ipv6Address, NetAddressError>macAddressFromOctets
Creates a MAC address from six checked octets.
Signature
declare function macAddressFromOctets(octets: readonly [number, number, number, number, number, number]): Result<MacAddress, NetAddressError>socketAddressFromInput
Converts a SocketAddress.Input to a concrete socket address.
Details
Numeric IP strings are parsed without hostname resolution. Invalid IP
literals, ports, and input shapes return a NetAddressError.
Signature
declare function socketAddressFromInput(input: Input): Result<SocketAddress, NetAddressError>unixPathAddress
Creates a Unix-domain filesystem address without normalizing its opaque path.
Signature
declare function unixPathAddress(path: string): UnixPathAddressConversions
Converts an IP address or internet socket address to a WHATWG URL.
Details
Defaults to the HTTP scheme and uses standard URL normalization, including IPv6 brackets and omission of default ports. Bare IP addresses have no explicit port; internet socket addresses retain their port, including zero. Unspecified addresses are preserved.
Gotchas
Returns a NetAddressError for scoped IPv6 addresses or inputs that the URL
constructor rejects. Supply the scheme without a trailing colon, for example
"https".
Signature
declare function toUrl(self: IpAddress | InetAddress, scheme: string): Result<URL, NetAddressError>Converting
fromIpv4Mapped
Extracts the IPv4 value from an IPv4-mapped IPv6 address.
Signature
declare function fromIpv4Mapped(self: Ipv6Address): Option<Ipv4Address>toCanonical
Converts an IPv4-mapped IPv6 address to IPv4, leaving all other addresses unchanged.
Signature
declare function toCanonical(self: IpAddress): IpAddresstoIpv4Mapped
Converts an IPv4 address to its IPv4-mapped IPv6 representation.
Signature
declare function toIpv4Mapped(self: Ipv4Address): Ipv6AddressDecoding
inetAddressFromString
Parses IPv4:port or [IPv6]:port without DNS resolution.
Signature
declare function inetAddressFromString(input: string): Result<InetAddress, NetAddressError>ipFromString
Parses a bare numeric IPv4 or IPv6 address.
Signature
declare function ipFromString(input: string): Result<IpAddress, NetAddressError>ipv4FromString
Parses a strict dotted-decimal IPv4 address.
Details
Multi-digit octets with a leading zero are rejected to avoid octal ambiguity.
Signature
declare function ipv4FromString(input: string): Result<Ipv4Address, NetAddressError>ipv6FromString
Parses an IPv6 address with optional compression and trailing embedded IPv4.
Signature
declare function ipv6FromString(input: string): Result<Ipv6Address, NetAddressError>macAddressFromString
Parses a colon-separated MAC address containing six two-digit hexadecimal octets.
Signature
declare function macAddressFromString(input: string): Result<MacAddress, NetAddressError>Encoding
formatInet
Formats a resolved internet address, bracketing IPv6 around its port.
Signature
declare function formatInet(self: InetAddress): stringFormats an IP address in canonical numeric form.
Signature
declare function formatIp(self: IpAddress): stringformatMacAddress
Formats a MAC address as six lowercase hexadecimal octets separated by colons.
Signature
declare function formatMacAddress(self: MacAddress): stringformatSocketAddress
Formats a portable socket address for human-readable output.
Signature
declare function formatSocketAddress(self: SocketAddress): stringformatUnixPath
Formats a Unix-domain socket path as a readable unix://path display string.
Details
Preserves the raw path without URL encoding or normalization. The resulting string is intended for display.
Signature
declare function formatUnixPath(self: UnixPathAddress): stringFormats an IP or socket address as a URL display string.
Details
Defaults to HTTP, brackets IPv6 addresses, and omits default ports and the
trailing slash. Custom schemes such as "tcp" retain their scheme and host.
Unix socket addresses use formatUnixPath, preserving the raw path
with a unix:// prefix regardless of the supplied scheme.
Gotchas
Returns a NetAddressError when URL conversion fails, including for scoped
IPv6 addresses.
Signature
declare function formatUrl(self: IpAddress | SocketAddress, scheme: string): Result<string, NetAddressError>formatUrlHost
Formats an IP address for use as a URL authority host.
Signature
declare function formatUrlHost(self: IpAddress): stringformatUrlHostString
Formats a hostname or numeric IP address for use as a URL authority host.
Signature
declare function formatUrlHostString(host: string): stringErrors
NetAddressError
A checked network-address operation failure retaining the address or supplied input.
Details
Address-based operations retain the address value. Parsing and numeric
construction retain the supplied string or array. Composed operations forward
errors from the failing operation unchanged. Failures from external operations
retain the original exception in cause when available.
Signature
declare class NetAddressError extends YieldableError<this> & { readonly _tag: "NetAddressError";} & Readonly<{ readonly cause?: unknown; readonly input: unknown; readonly message: string;}> { constructor(args: { readonly cause?: unknown; readonly input: unknown; readonly message: string; });}Getters
ipv4ToOctets
Returns the four numeric octets of an IPv4 address in a fresh tuple.
Signature
declare function ipv4ToOctets(self: Ipv4Address): readonly [number, number, number, number]ipv6ToOctets
Returns the sixteen numeric octets of an IPv6 address in a fresh array.
Signature
declare function ipv6ToOctets(self: Ipv6Address): readonly Array<number>ipv6ToSegments
Returns the eight numeric segments of an IPv6 address in a fresh tuple.
Signature
declare function ipv6ToSegments(self: Ipv6Address): readonly [number, number, number, number, number, number, number, number]macAddressToOctets
Returns the six numeric octets of a MAC address in a fresh tuple.
Signature
declare function macAddressToOctets(self: MacAddress): readonly [number, number, number, number, number, number]Returns the bit width of an IP address.
Signature
declare function width(address: IpAddress): 32 | 128Guards
isInetAddress
Returns true when a value is a resolved internet address.
Signature
declare function isInetAddress(u: unknown): u is InetAddressisInetAddressV4
Returns true when a value is a resolved IPv4 internet address.
Signature
declare function isInetAddressV4(u: unknown): u is InetAddressV4isInetAddressV6
Returns true when a value is a resolved IPv6 internet address.
Signature
declare function isInetAddressV6(u: unknown): u is InetAddressV6isIpAddress
Returns true when a value is an IPv4 or IPv6 address.
Signature
declare function isIpAddress(u: unknown): u is IpAddressisIpv4Address
Returns true when a value is an IPv4 address.
Signature
declare function isIpv4Address(u: unknown): u is Ipv4AddressisIpv6Address
Returns true when a value is an IPv6 address.
Signature
declare function isIpv6Address(u: unknown): u is Ipv6AddressisMacAddress
Returns true when a value is a MAC address.
Signature
declare function isMacAddress(u: unknown): u is MacAddressisSocketAddress
Returns true when a value is a portable concrete socket address.
Signature
declare function isSocketAddress(u: unknown): u is SocketAddressisUnixPathAddress
Returns true when a value is a Unix-domain filesystem address.
Signature
declare function isUnixPathAddress(u: unknown): u is UnixPathAddressModels
InetAddress type
A resolved IPv4 or IPv6 internet address and port.
Signature
type InetAddress = InetAddressV4 | InetAddressV6InetAddressV4 interface
A resolved IPv4 internet address and port.
Signature
interface InetAddressV4 extends Equal, Hash { readonly _tag: "InetAddressV4"; readonly "~effect/net/NetAddress": "~effect/net/NetAddress"; readonly address: Ipv4Address; readonly port: number; toJSON(): string; toString(): string;}InetAddressV6 interface
A resolved IPv6 internet address, port, and scope identifier.
Signature
interface InetAddressV6 extends Equal, Hash { readonly _tag: "InetAddressV6"; readonly "~effect/net/NetAddress": "~effect/net/NetAddress"; readonly address: Ipv6Address; readonly port: number; readonly scopeId: number; toJSON(): string; toString(): string;}A numeric IPv4 or IPv6 address.
Signature
type IpAddress = Ipv4Address | Ipv6AddressIpv4Address interface
An immutable 32-bit IPv4 address.
Signature
interface Ipv4Address extends Equal, Hash { readonly _tag: "Ipv4Address"; readonly "~effect/net/NetAddress": "~effect/net/NetAddress"; toJSON(): string; toString(): string;}Ipv6Address interface
An immutable 128-bit IPv6 address without socket scope metadata.
Signature
interface Ipv6Address extends Equal, Hash { readonly _tag: "Ipv6Address"; readonly "~effect/net/NetAddress": "~effect/net/NetAddress"; toJSON(): string; toString(): string;}MacAddress interface
An immutable 48-bit IEEE 802 MAC address.
Signature
interface MacAddress extends Equal, Hash { readonly _tag: "MacAddress"; readonly "~effect/net/NetAddress": "~effect/net/NetAddress"; toJSON(): string; toString(): string;}SocketAddress type
A portable concrete internet or Unix-domain filesystem address.
Signature
type SocketAddress = InetAddress | UnixPathAddressUnixPathAddress interface
An opaque Unix-domain filesystem socket path.
Signature
interface UnixPathAddress extends Equal, Hash { readonly _tag: "UnixPathAddress"; readonly "~effect/net/NetAddress": "~effect/net/NetAddress"; readonly path: string; toJSON(): string; toString(): string;}Other
SocketAddress
Companion types for constructing socket addresses.
Pattern Matching
Folds an IP address by its numeric version.
Signature
declare const match: { <A, B>(options: { readonly onIpv4: (address: Ipv4Address) => A; readonly onIpv6: (address: Ipv6Address) => B; }): (self: IpAddress) => A | B; <A, B>(self: IpAddress, options: { readonly onIpv4: (address: Ipv4Address) => A; readonly onIpv6: (address: Ipv6Address) => B; }): A | B;}Predicates
isBroadcast
Returns true for the IPv4 broadcast address 255.255.255.255.
Signature
declare function isBroadcast(self: Ipv4Address): booleanisIpv4Mapped
Returns true when an IPv6 address is in the ::ffff:0:0/96 mapped range.
Signature
declare function isIpv4Mapped(self: Ipv6Address): booleanisLinkLocal
Returns true for IPv4 169.254.0.0/16 or IPv6 fe80::/10.
Signature
declare function isLinkLocal(self: IpAddress): booleanisLoopback
Returns true for IPv4 127.0.0.0/8 or IPv6 ::1.
Signature
declare function isLoopback(self: IpAddress): booleanisMacBroadcast
Returns true when the MAC address is the all-ones broadcast address.
Signature
declare function isMacBroadcast(self: MacAddress): booleanisMacLocallyAdministered
Returns true when the MAC address has the IEEE local-administration bit set.
Signature
declare function isMacLocallyAdministered(self: MacAddress): booleanisMacMulticast
Returns true when the MAC address has the IEEE group-address bit set.
Signature
declare function isMacMulticast(self: MacAddress): booleanisMacUnicast
Returns true when the MAC address has the IEEE group-address bit clear.
Signature
declare function isMacUnicast(self: MacAddress): booleanisMacUniversallyAdministered
Returns true when the MAC address has the IEEE local-administration bit clear.
Signature
declare function isMacUniversallyAdministered(self: MacAddress): booleanisMulticast
Returns true for IPv4 224.0.0.0/4 or IPv6 ff00::/8.
Signature
declare function isMulticast(self: IpAddress): booleanReturns true for IPv4 private-use ranges defined by RFC 1918.
Signature
declare function isPrivate(self: Ipv4Address): booleanisUniqueLocal
Returns true for IPv6 unique-local addresses in fc00::/7.
Signature
declare function isUniqueLocal(self: Ipv6Address): booleanisUnspecified
Returns true for the all-zero address of either IP version.
Signature
declare function isUnspecified(self: IpAddress): booleanUnsafe
formatUrlUnsafe
Formats an IP or socket address as a URL display string,
throwing a NetAddressError when conversion fails.
See
- formatUrl for the checked version and formatting behavior.
Signature
declare function formatUrlUnsafe(self: IpAddress | SocketAddress, scheme: string): stringinetAddressFromIpStringUnsafe
Creates an internet address from a trusted numeric IP string and port.
Gotchas
This function throws when either input is invalid. Use only when both values are already known to satisfy the checked constructor's requirements.
Signature
declare function inetAddressFromIpStringUnsafe(address: string, port: number): InetAddressinetAddressFromStringUnsafe
Parses a trusted numeric internet address and port, throwing on failure.
Signature
declare function inetAddressFromStringUnsafe(input: string): InetAddressinetAddressUnsafe
Creates an internet address from a trusted IP address and port, throwing on failure.
Signature
declare function inetAddressUnsafe(address: IpAddress, port: number): InetAddressipFromStringUnsafe
Parses a trusted bare numeric IPv4 or IPv6 address, throwing on failure.
Signature
declare function ipFromStringUnsafe(input: string): IpAddressipv4FromBytesUnsafe
Creates an IPv4 address from trusted network-order bytes without validation.
Signature
declare function ipv4FromBytesUnsafe(bytes: Uint8Array): Ipv4Addressipv6FromBytesUnsafe
Creates an IPv6 address from trusted network-order bytes without validation.
Signature
declare function ipv6FromBytesUnsafe(bytes: Uint8Array): Ipv6AddressmacAddressFromStringUnsafe
Parses a trusted colon-separated MAC address, throwing on failure.
Signature
declare function macAddressFromStringUnsafe(input: string): MacAddresssocketAddressFromInputUnsafe
Converts a trusted SocketAddress.Input to a concrete socket address,
throwing on failure.
Signature
declare function socketAddressFromInputUnsafe(input: Input): SocketAddress