Skip to content
Effect Days 2026 Get your ticket

NetAddress

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

99 exports Added in v4.0.0 Source

Constants

ipv4Broadcast

Added in v4.0.0 Source

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

ipv4Unspecified

Added in v4.0.0 Source

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

ipv6Unspecified

Added in v4.0.0 Source

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>

inetAddressFromIpString

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Creates a checked IPv4 internet address.

Signature

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

inetAddressV6

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Creates an IPv4 address from four checked octets.

Signature

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

ipv6FromSegments

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Creates a MAC address from six checked octets.

Signature

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

socketAddressFromInput

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

fromIpv4Mapped

Added in v4.0.0 Source

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

Signature

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

scopeIdsFromInterfaces

Added in v4.0.0 Source

Creates a map from interface names to IPv6 scope IDs using supplied interface entries.

Details

Each entry pairs an interface name with its addresses. The first IPv6 address with a positive scope ID supplies that interface's mapping. Accepts entries such as Object.entries(os.networkInterfaces()) without performing any operating-system lookup itself. Later changes to the entries do not affect the map.

See

Signature

declare function scopeIdsFromInterfaces(interfaces: Iterable<readonly [string, readonly Array<NetworkInterfaceAddress> | undefined]>): Map<string, number>

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

inetAddressFromHostString

Added in v4.0.0 Source

Parses an unbracketed numeric host and port, resolving named IPv6 zones using a supplied map of interface names to numeric scope IDs.

Details

IPv4, unscoped IPv6, and numeric IPv6 zones need no map. Named zones must have a matching map entry. This function performs no DNS or operating-system lookup.

See

Signature

declare function inetAddressFromHostString(host: string, port: number, scopeIds?: ReadonlyMap<string, number>): Result<InetAddress, NetAddressError>

inetAddressFromString

Added in v4.0.0 Source

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>

ipv4FromString

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

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

macAddressFromString

Added in v4.0.0 Source

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

Signature

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

Encoding

formatHost

Added in v4.0.0 Source

Formats the numeric host of an internet address without brackets or a port, preserving a nonzero IPv6 scope ID as a % suffix.

When to use

Use when the host and port are represented separately.

See

Signature

declare function formatHost(self: InetAddress): string

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

formatMacAddress

Added in v4.0.0 Source

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

Signature

declare function formatMacAddress(self: MacAddress): string

formatMulticastInterface

Added in v4.0.0 Source

Formats an IPv4 address or IPv6 interface index for a native multicast API.

Details

IPv4 addresses are formatted as numeric IPs. An IPv6 index of zero produces "::". Other indices produce "::%index" on "win32", or "::%name" on other platforms using the first matching interface name, falling back to the numeric index when no name matches.

Supply a scope map from scopeIdsFromInterfaces and optionally a platform string. Omitting the platform uses non-Windows behavior. This function performs no operating-system lookups.

Signature

declare function formatMulticastInterface(networkInterface: number | Ipv4Address, scopeIds: ReadonlyMap<string, number>, platform?: string): string

formatNativeHost

Added in v4.0.0 Source

Formats an internet address's host for a native socket API, without brackets or a port.

Details

On "win32", IPv6 zones remain numeric. On other platforms, the first interface name matching the scope ID is used, falling back to the numeric ID when no name matches. Unscoped IPv6 and IPv4 hosts are unchanged.

Supply a scope map from scopeIdsFromInterfaces and optionally a platform string. Omitting the platform uses non-Windows behavior. This function performs no operating-system lookups.

Signature

declare function formatNativeHost(self: InetAddress, scopeIds: ReadonlyMap<string, number>, platform?: string): string

formatSocketAddress

Added in v4.0.0 Source

Formats a portable socket address for human-readable output.

Signature

declare function formatSocketAddress(self: SocketAddress): string

formatUnixPath

Added in v4.0.0 Source

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>

formatUrlHost

Added in v4.0.0 Source

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

Signature

declare function formatUrlHost(self: IpAddress): string

formatUrlHostString

Added in v4.0.0 Source

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

Signature

declare function formatUrlHostString(host: string): string

Errors

NetAddressError

Added in v4.0.0 Source

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>

ipv6ToSegments

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

isInetAddress

Added in v4.0.0 Source

Returns true when a value is a resolved internet address.

Signature

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

isInetAddressV4

Added in v4.0.0 Source

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

Signature

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

isInetAddressV6

Added in v4.0.0 Source

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

isIpv4Address

Added in v4.0.0 Source

Returns true when a value is an IPv4 address.

Signature

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

isIpv6Address

Added in v4.0.0 Source

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

isSocketAddress

Added in v4.0.0 Source

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

Signature

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

isUnixPathAddress

Added in v4.0.0 Source

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

Signature

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

Models

BroadcastAddress type

Added in v4.0.0 Source

An IPv4 limited-broadcast or MAC all-ones broadcast address.

Details

MAC broadcast is also multicast because its IEEE group bit is set. IPv4 limited broadcast is not multicast. Directed IPv4 broadcast requires network prefix context and is intentionally not represented by this refinement.

Signature

type BroadcastAddress<A extends Ipv4Address | MacAddress = Ipv4Address | MacAddress> = A extends MacAddress ? Brand.Branded<MulticastAddress<A>, typeof BroadcastTypeId> : Brand.Branded<A, typeof BroadcastTypeId>

Family type

Added in v4.0.0 Source

The IPv4 or IPv6 family of an IP address or internet address type.

Details

Refinements such as MulticastAddress<A> are dropped; the result is the plain Ipv4Address or Ipv6Address for the family. Unions distribute, so Family<IpAddress> and Family<InetAddress> are both IpAddress.

Signature

type Family<A extends IpAddress | InetAddress> = A extends Ipv4Address | InetAddressV4 ? Ipv4Address : Ipv6Address

Example

(Deriving the family of an internet address)

import { NetAddress } from "effect/net"


const family: NetAddress.Family<NetAddress.InetAddressV6> = NetAddress.ipv6Loopback

Inet type

Added in v4.0.0 Source

The internet address type for an IP address family.

Details

Inet<Ipv4Address> is InetAddressV4 and Inet<Ipv6Address> is InetAddressV6. Refinements on A are dropped because the port-carrying types hold a plain family address. Inet<IpAddress> is InetAddress.

Signature

type Inet<A extends IpAddress = IpAddress> = A extends Ipv4Address ? InetAddressV4 : InetAddressV6

Example

(Selecting the internet address for a family)

import { Result } from "effect"
import { NetAddress } from "effect/net"


const endpoint: NetAddress.Inet<NetAddress.Ipv4Address> = Result.getOrThrow(
  NetAddress.inetAddressV4(NetAddress.ipv4Loopback, 8080)
)

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

LinkLocalAddress type

Added in v4.0.0 Source

An IP address proven to be link-local.

Signature

type LinkLocalAddress<A extends IpAddress = IpAddress> = Brand.Branded<A, typeof LinkLocalTypeId>

LocallyAdministeredAddress type

Added in v4.0.0 Source

A MAC address whose IEEE universal/local bit marks it as locally administered.

Signature

type LocallyAdministeredAddress<A extends MacAddress = MacAddress> = Brand.Branded<A, typeof LocallyAdministeredTypeId>

LoopbackAddress type

Added in v4.0.0 Source

An IP address proven to be loopback.

Signature

type LoopbackAddress<A extends IpAddress = IpAddress> = Brand.Branded<A, typeof LoopbackTypeId>

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

MulticastAddress type

Added in v4.0.0 Source

An IP or MAC address proven to be multicast (IPv4 224.0.0.0/4, IPv6 ff00::/8, or a MAC address with the IEEE group bit set).

Details

This is a branded refinement of the underlying address. Construction returns the same runtime value, preserving identity, equality, hashing, and formatting. The MAC all-ones broadcast address has the group bit set and is therefore multicast; use isMacBroadcast to distinguish it. The IPv4 limited broadcast address 255.255.255.255 is not multicast.

The default type argument remains IpAddress; specify MacAddress or an explicit IP/MAC union when accepting those wider address families.

Signature

type MulticastAddress<A extends IpAddress | MacAddress = IpAddress> = Brand.Branded<A, typeof MulticastTypeId>

MulticastInterface type

Added in v4.0.0 Source

A native multicast interface selector for an IP address family: an interface address for IPv4 or an interface index for IPv6. ipv4Unspecified and index 0 select the operating system default.

See

Signature

type MulticastInterface<A extends IpAddress = IpAddress> = A extends Ipv4Address ? Ipv4Address : number

Example

(Selecting multicast interfaces by family)

import { NetAddress } from "effect/net"


const ipv4Interface: NetAddress.MulticastInterface<NetAddress.Ipv4Address> =
  NetAddress.ipv4Unspecified
const ipv6Interface: NetAddress.MulticastInterface<NetAddress.Ipv6Address> = 0

NetworkInterfaceAddress interface

Added in v4.0.0 Source

Network interface address metadata used to resolve IPv6 scope IDs.

See

Signature

interface NetworkInterfaceAddress {
  readonly family: string;
  readonly scopeid?: number;
}

PrivateAddress type

Added in v4.0.0 Source

An IPv4 private-use address in an RFC 1918 range.

Signature

type PrivateAddress<A extends Ipv4Address = Ipv4Address> = Brand.Branded<A, typeof PrivateTypeId>

SocketAddress type

Added in v4.0.0 Source

A portable concrete internet or Unix-domain filesystem address.

Signature

type SocketAddress = InetAddress | UnixPathAddress

UnicastAddress type

Added in v4.0.0 Source

An IP or MAC address proven to be syntactically unicast.

Details

For IP addresses this excludes multicast, unspecified, and the IPv4 limited broadcast address. Reserved and special-purpose addresses may still satisfy this refinement, as may an IPv4 directed broadcast whose network prefix is unknown. It does not promise reachability or destination usability. For MAC addresses it means that the IEEE individual/group bit is clear.

Signature

type UnicastAddress<A extends IpAddress | MacAddress = IpAddress | MacAddress> = Brand.Branded<A, typeof UnicastTypeId>

UniqueLocalAddress type

Added in v4.0.0 Source

An IPv6 unique-local address in fc00::/7.

Signature

type UniqueLocalAddress<A extends Ipv6Address = Ipv6Address> = Brand.Branded<A, typeof UniqueLocalTypeId>

UniversallyAdministeredAddress type

Added in v4.0.0 Source

A MAC address whose IEEE universal/local bit marks it as universally administered.

Signature

type UniversallyAdministeredAddress<A extends MacAddress = MacAddress> = Brand.Branded<A, typeof UniversallyAdministeredTypeId>

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

UnspecifiedAddress type

Added in v4.0.0 Source

An all-zero IPv4 or IPv6 address.

Signature

type UnspecifiedAddress<A extends IpAddress = IpAddress> = Brand.Branded<A, typeof UnspecifiedTypeId>

Other

SocketAddress

Added in v4.0.0 Source

Companion types for constructing socket addresses.

toCanonical

Source

Signature

declare function toCanonical(self: IpAddress): IpAddress
declare function toCanonical(self: InetAddress): InetAddress

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 limited broadcast address 255.255.255.255 or the MAC all-ones broadcast address.

Details

MAC broadcast is also multicast because its IEEE group bit is set. IPv4 limited broadcast is not multicast. Directed IPv4 broadcast cannot be determined without a network prefix and is not classified here.

Signature

declare function isBroadcast<A extends MacAddress | Ipv4Address>(self: A): self is BroadcastAddress<A>

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<A extends IpAddress>(self: A): self is LinkLocalAddress<A>

isLoopback

Added in v4.0.0 Source

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

Signature

declare function isLoopback<A extends IpAddress>(self: A): self is LoopbackAddress<A>

isMacBroadcast

Added in v4.0.0 Source

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

Signature

declare function isMacBroadcast<A extends MacAddress>(self: A): self is BroadcastAddress<A>

isMacLocallyAdministered

Added in v4.0.0 Source

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

Signature

declare function isMacLocallyAdministered<A extends MacAddress>(self: A): self is LocallyAdministeredAddress<A>

isMacMulticast

Added in v4.0.0 Source

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

Signature

declare function isMacMulticast<A extends MacAddress>(self: A): self is MulticastAddress<A>

isMacUnicast

Added in v4.0.0 Source

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

Signature

declare function isMacUnicast<A extends MacAddress>(self: A): self is UnicastAddress<A>

isMacUniversallyAdministered

Added in v4.0.0 Source

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

Signature

declare function isMacUniversallyAdministered<A extends MacAddress>(self: A): self is UniversallyAdministeredAddress<A>

isMulticast

Added in v4.0.0 Source

Returns true for IPv4 224.0.0.0/4, IPv6 ff00::/8, or a MAC address with the IEEE group bit set, refining the value while preserving its address type.

Details

The MAC all-ones broadcast address has the group bit set and is multicast; the IPv4 limited broadcast address 255.255.255.255 is not. Use isMacBroadcast or isBroadcast to distinguish broadcast.

Signature

declare function isMulticast<A extends MacAddress | IpAddress>(self: A): self is MulticastAddress<A>

Example

(Classifying IP and MAC group addresses)

import { assert } from "@effect/vitest"
import { NetAddress } from "effect/net"


const ip = NetAddress.ipFromStringUnsafe("239.255.0.1")
const mac = NetAddress.macAddressFromStringUnsafe("ff:ff:ff:ff:ff:ff")


assert.isTrue(NetAddress.isMulticast(ip))
assert.isTrue(NetAddress.isMulticast(mac))
assert.isTrue(NetAddress.isBroadcast(mac))
assert.isFalse(NetAddress.isMulticast(NetAddress.ipv4Broadcast))

isPrivate

Added in v4.0.0 Source

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

Signature

declare function isPrivate<A extends Ipv4Address>(self: A): self is PrivateAddress<A>

isUnicast

Added in v4.0.0 Source

Returns true when an address is syntactically unicast.

Details

IP addresses exclude multicast, unspecified, and IPv4 limited broadcast. This does not exclude reserved ranges, prefix-relative directed broadcast, or addresses that are unusable or unreachable in a particular deployment. MAC addresses are unicast when their IEEE individual/group bit is clear.

Signature

declare function isUnicast<A extends MacAddress | IpAddress>(self: A): self is UnicastAddress<A>

isUniqueLocal

Added in v4.0.0 Source

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

Signature

declare function isUniqueLocal<A extends Ipv6Address>(self: A): self is UniqueLocalAddress<A>

isUnspecified

Added in v4.0.0 Source

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

Signature

declare function isUnspecified<A extends IpAddress>(self: A): self is UnspecifiedAddress<A>

Unsafe

formatUrlUnsafe

Added in v4.0.0 Source

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

inetAddressFromIpStringUnsafe

Added in v4.0.0 Source

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

inetAddressFromStringUnsafe

Added in v4.0.0 Source

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

Signature

declare function inetAddressFromStringUnsafe(input: string): InetAddress

inetAddressUnsafe

Added in v4.0.0 Source

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

Signature

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

ipFromStringUnsafe

Added in v4.0.0 Source

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

Signature

declare function ipFromStringUnsafe(input: string): IpAddress

ipv4FromBytesUnsafe

Added in v4.0.0 Source

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

Signature

declare function ipv4FromBytesUnsafe(bytes: Uint8Array): Ipv4Address

ipv6FromBytesUnsafe

Added in v4.0.0 Source

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

Signature

declare function ipv6FromBytesUnsafe(bytes: Uint8Array): Ipv6Address

macAddressFromStringUnsafe

Added in v4.0.0 Source

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

Signature

declare function macAddressFromStringUnsafe(input: string): MacAddress

socketAddressFromInputUnsafe

Added in v4.0.0 Source

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

Signature

declare function socketAddressFromInputUnsafe(input: Input): SocketAddress