Skip to content
Effect Days 2026 Get your ticket

NetAddress

Pure, platform-neutral values for MAC, IP, internet socket, and Unix path addresses.

79 exports Added in v4.0.0 Source

Constants

The IPv4 broadcast address 255.255.255.255.

Signature

declare const ipv4Broadcast: Ipv4Address

ipv4Loopback

Added in v4.0.0 Source

The IPv4 loopback address 127.0.0.1.

Signature

declare const ipv4Loopback: Ipv4Address

The unspecified IPv4 address 0.0.0.0.

Signature

declare const ipv4Unspecified: Ipv4Address

ipv6Loopback

Added in v4.0.0 Source

The IPv6 loopback address ::1.

Signature

declare const ipv6Loopback: Ipv6Address

The unspecified IPv6 address ::.

Signature

declare const ipv6Unspecified: Ipv6Address

Constructors

inetAddress

Added in v4.0.0 Source

Creates a checked internet address for an IP address and port.

Signature

declare function inetAddress(address: IpAddress, port: number): Result<InetAddress, NetAddressError>

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>

Creates a checked IPv4 internet address.

Signature

declare function inetAddressV4(address: Ipv4Address, port: number): Result<InetAddressV4, NetAddressError>

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>

Creates an IPv4 address from four checked octets.

Signature

declare function ipv4FromOctets(octets: readonly [number, number, number, number]): Result<Ipv4Address, NetAddressError>

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>

Creates a MAC address from six checked octets.

Signature

declare function macAddressFromOctets(octets: readonly [number, number, number, number, number, number]): Result<MacAddress, NetAddressError>

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>

Creates a Unix-domain filesystem address without normalizing its opaque path.

Signature

declare function unixPathAddress(path: string): UnixPathAddress

Conversions

toUrl

Added in v4.0.0 Source

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

Extracts the IPv4 value from an IPv4-mapped IPv6 address.

Signature

declare function fromIpv4Mapped(self: Ipv6Address): Option<Ipv4Address>

toCanonical

Added in v4.0.0 Source

Converts an IPv4-mapped IPv6 address to IPv4, leaving all other addresses unchanged.

Signature

declare function toCanonical(self: IpAddress): IpAddress

toIpv4Mapped

Added in v4.0.0 Source

Converts an IPv4 address to its IPv4-mapped IPv6 representation.

Signature

declare function toIpv4Mapped(self: Ipv4Address): Ipv6Address

Decoding

Parses IPv4:port or [IPv6]:port without DNS resolution.

Signature

declare function inetAddressFromString(input: string): Result<InetAddress, NetAddressError>

ipFromString

Added in v4.0.0 Source

Parses a bare numeric IPv4 or IPv6 address.

Signature

declare function ipFromString(input: string): Result<IpAddress, NetAddressError>

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>

Parses an IPv6 address with optional compression and trailing embedded IPv4.

Signature

declare function ipv6FromString(input: string): Result<Ipv6Address, NetAddressError>

Parses a colon-separated MAC address containing six two-digit hexadecimal octets.

Signature

declare function macAddressFromString(input: string): Result<MacAddress, NetAddressError>

Encoding

formatInet

Added in v4.0.0 Source

Formats a resolved internet address, bracketing IPv6 around its port.

Signature

declare function formatInet(self: InetAddress): string

formatIp

Added in v4.0.0 Source

Formats an IP address in canonical numeric form.

Signature

declare function formatIp(self: IpAddress): string

Formats a MAC address as six lowercase hexadecimal octets separated by colons.

Signature

declare function formatMacAddress(self: MacAddress): string

Formats a portable socket address for human-readable output.

Signature

declare function formatSocketAddress(self: SocketAddress): string

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): string

formatUrl

Added in v4.0.0 Source

Formats 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>

Formats an IP address for use as a URL authority host.

Signature

declare function formatUrlHost(self: IpAddress): string

Formats a hostname or numeric IP address for use as a URL authority host.

Signature

declare function formatUrlHostString(host: string): string

Errors

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Returns the sixteen numeric octets of an IPv6 address in a fresh array.

Signature

declare function ipv6ToOctets(self: Ipv6Address): readonly Array<number>

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]

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]

width

Added in v4.0.0 Source

Returns the bit width of an IP address.

Signature

declare function width(address: IpAddress): 32 | 128

Guards

Returns true when a value is a resolved internet address.

Signature

declare function isInetAddress(u: unknown): u is InetAddress

Returns true when a value is a resolved IPv4 internet address.

Signature

declare function isInetAddressV4(u: unknown): u is InetAddressV4

Returns true when a value is a resolved IPv6 internet address.

Signature

declare function isInetAddressV6(u: unknown): u is InetAddressV6

isIpAddress

Added in v4.0.0 Source

Returns true when a value is an IPv4 or IPv6 address.

Signature

declare function isIpAddress(u: unknown): u is IpAddress

Returns true when a value is an IPv4 address.

Signature

declare function isIpv4Address(u: unknown): u is Ipv4Address

Returns true when a value is an IPv6 address.

Signature

declare function isIpv6Address(u: unknown): u is Ipv6Address

isMacAddress

Added in v4.0.0 Source

Returns true when a value is a MAC address.

Signature

declare function isMacAddress(u: unknown): u is MacAddress

Returns true when a value is a portable concrete socket address.

Signature

declare function isSocketAddress(u: unknown): u is SocketAddress

Returns true when a value is a Unix-domain filesystem address.

Signature

declare function isUnixPathAddress(u: unknown): u is UnixPathAddress

Models

InetAddress type

Added in v4.0.0 Source

A resolved IPv4 or IPv6 internet address and port.

Signature

type InetAddress = InetAddressV4 | InetAddressV6

InetAddressV4 interface

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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;
}

IpAddress type

Added in v4.0.0 Source

A numeric IPv4 or IPv6 address.

Signature

type IpAddress = Ipv4Address | Ipv6Address

Ipv4Address interface

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

A portable concrete internet or Unix-domain filesystem address.

Signature

type SocketAddress = InetAddress | UnixPathAddress

UnixPathAddress interface

Added in v4.0.0 Source

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

Companion types for constructing socket addresses.

Pattern Matching

match

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Returns true for the IPv4 broadcast address 255.255.255.255.

Signature

declare function isBroadcast(self: Ipv4Address): boolean

isIpv4Mapped

Added in v4.0.0 Source

Returns true when an IPv6 address is in the ::ffff:0:0/96 mapped range.

Signature

declare function isIpv4Mapped(self: Ipv6Address): boolean

isLinkLocal

Added in v4.0.0 Source

Returns true for IPv4 169.254.0.0/16 or IPv6 fe80::/10.

Signature

declare function isLinkLocal(self: IpAddress): boolean

isLoopback

Added in v4.0.0 Source

Returns true for IPv4 127.0.0.0/8 or IPv6 ::1.

Signature

declare function isLoopback(self: IpAddress): boolean

Returns true when the MAC address is the all-ones broadcast address.

Signature

declare function isMacBroadcast(self: MacAddress): boolean

Returns true when the MAC address has the IEEE local-administration bit set.

Signature

declare function isMacLocallyAdministered(self: MacAddress): boolean

Returns true when the MAC address has the IEEE group-address bit set.

Signature

declare function isMacMulticast(self: MacAddress): boolean

isMacUnicast

Added in v4.0.0 Source

Returns true when the MAC address has the IEEE group-address bit clear.

Signature

declare function isMacUnicast(self: MacAddress): boolean

Returns true when the MAC address has the IEEE local-administration bit clear.

Signature

declare function isMacUniversallyAdministered(self: MacAddress): boolean

isMulticast

Added in v4.0.0 Source

Returns true for IPv4 224.0.0.0/4 or IPv6 ff00::/8.

Signature

declare function isMulticast(self: IpAddress): boolean

isPrivate

Added in v4.0.0 Source

Returns true for IPv4 private-use ranges defined by RFC 1918.

Signature

declare function isPrivate(self: Ipv4Address): boolean

Returns true for IPv6 unique-local addresses in fc00::/7.

Signature

declare function isUniqueLocal(self: Ipv6Address): boolean

Returns true for the all-zero address of either IP version.

Signature

declare function isUnspecified(self: IpAddress): boolean

Unsafe

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): string

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): InetAddress

Parses a trusted numeric internet address and port, throwing on failure.

Signature

declare function inetAddressFromStringUnsafe(input: string): InetAddress

Creates an internet address from a trusted IP address and port, throwing on failure.

Signature

declare function inetAddressUnsafe(address: IpAddress, port: number): InetAddress

Parses a trusted bare numeric IPv4 or IPv6 address, throwing on failure.

Signature

declare function ipFromStringUnsafe(input: string): IpAddress

Creates an IPv4 address from trusted network-order bytes without validation.

Signature

declare function ipv4FromBytesUnsafe(bytes: Uint8Array): Ipv4Address

Creates an IPv6 address from trusted network-order bytes without validation.

Signature

declare function ipv6FromBytesUnsafe(bytes: Uint8Array): Ipv6Address

Parses a trusted colon-separated MAC address, throwing on failure.

Signature

declare function macAddressFromStringUnsafe(input: string): MacAddress

Converts a trusted SocketAddress.Input to a concrete socket address, throwing on failure.

Signature

declare function socketAddressFromInputUnsafe(input: Input): SocketAddress