Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

IpNetwork unstable

Pure, canonical IPv4 and IPv6 network prefixes using CIDR notation.

30 exports Since v4.0.0 Source

Constructors

fromAddress

unstable
Since v4.0.0

Creates the canonical network containing an address by clearing its host bits.

Gotchas

The returned network's address can differ from the input address. Its type therefore retains the IPv4 or IPv6 family but not refinements on the input address. Revalidate the derived address to recover a refinement.

Signature

declare function fromAddress<A extends IpAddress>(address: A, prefixLength: number): Result<IpNetwork<Family<A>>, NetAddressError>

fromInput

unstable
Since v4.0.0

Converts an IpNetworkInput to a network prefix, parsing strings like fromString, converting parts like make, and returning network prefixes unchanged.

Gotchas

Like make, an address with host bits set is rejected rather than truncated.

Signature

declare function fromInput(input: IpNetworkInput): Result<IpNetwork<IpAddress>, NetAddressError>

ipv4FromInput

unstable
Since v4.0.0

Converts an Ipv4NetworkInput to an IPv4 network prefix, parsing strings like ipv4FromString, converting parts like make, and returning network prefixes unchanged.

Signature

declare function ipv4FromInput(input: Ipv4NetworkInput): Result<Ipv4Network, NetAddressError>

ipv6FromInput

unstable
Since v4.0.0

Converts an Ipv6NetworkInput to an IPv6 network prefix, parsing strings like ipv6FromString, converting parts like make, and returning network prefixes unchanged.

Signature

declare function ipv6FromInput(input: Ipv6NetworkInput): Result<Ipv6Network, NetAddressError>

make

unstable
Since v4.0.0

Creates a network prefix when the address has no host bits set.

Gotchas

Use fromAddress when a host address should be truncated to its containing network.

Signature

declare function make<A extends IpAddress>(address: A, prefixLength: number): Result<IpNetwork<A>, NetAddressError>

Conversions

fromInterface

unstable
Since v4.0.0

Returns the canonical network containing an interface address. The derived address retains its IPv4 or IPv6 family but not refinements on the input.

Signature

declare function fromInterface<A extends IpAddress>(self: IpInterface<A>): IpNetwork<Family<A>>

Decoding

fromString

unstable
Since v4.0.0

Parses a strict IPv4 or IPv6 network prefix in CIDR notation.

Signature

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

ipv4FromString

unstable
Since v4.0.0

Parses a strict IPv4 network prefix in CIDR notation.

Signature

declare function ipv4FromString(input: string): Result<Ipv4Network, NetAddressError>

ipv6FromString

unstable
Since v4.0.0

Parses a strict IPv6 network prefix in CIDR notation.

Signature

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

Encoding

format

unstable
Since v4.0.0

Formats a network prefix using canonical address text and its decimal prefix length.

Signature

declare function format(self: IpNetwork): string

Getters

addressCount

unstable
Since v4.0.0

Returns the exact number of addresses in a network prefix.

Signature

declare function addressCount(self: IpNetwork): bigint

firstAddress

unstable
Since v4.0.0

Returns the lowest address in a network prefix.

Signature

declare function firstAddress<A extends IpAddress>(self: IpNetwork<A>): A

lastAddress

unstable
Since v4.0.0

Returns the numerically greatest address in a network prefix. The derived address retains its IPv4 or IPv6 family but not refinements on the network address.

Signature

declare function lastAddress<A extends IpAddress>(self: IpNetwork<A>): Family<A>

Guards

isIpNetwork

unstable
Since v4.0.0

Returns true when a value is an IPv4 or IPv6 network prefix.

Signature

declare function isIpNetwork(u: unknown): u is IpNetwork<IpAddress>

isIpv4Network

unstable
Since v4.0.0

Returns true when a value is an IPv4 network prefix.

Signature

declare function isIpv4Network(u: unknown): u is Ipv4Network

isIpv6Network

unstable
Since v4.0.0

Returns true when a value is an IPv6 network prefix.

Signature

declare function isIpv6Network(u: unknown): u is Ipv6Network

Models

IpNetwork

interface unstable
Since v4.0.0

An immutable canonical IP network prefix. Constructors that retain the exact input address also retain its verified refinements. Operations that derive a different address return only its IPv4 or IPv6 family; revalidate the result before treating it as refined.

Signature

interface IpNetwork<out A extends NetAddress.IpAddress = NetAddress.IpAddress> extends Equal, Hash, Inspectable {
  readonly _tag: "IpNetwork";
  readonly "~effect/net/IpNetwork": "~effect/net/IpNetwork";
  readonly address: A;
  readonly prefixLength: number;
}

IpNetworkInput

type unstable
Since v4.0.0

An IP network prefix, or a CIDR string or parts to convert to one.

Signature

type IpNetworkInput = IpNetwork | string | IpNetworkParts

IpNetworkParts

type unstable
Since v4.0.0

A network address and prefix length, generic over the accepted address input. The address must have no host bits set.

See

  • make for the checked constructor

Signature

type IpNetworkParts<A extends NetAddress.IpAddressInput = NetAddress.IpAddressInput> = IpInterface.IpInterfaceParts<A>

Ipv4Network

type unstable
Since v4.0.0

An immutable canonical IPv4 network prefix.

Signature

type Ipv4Network = IpNetwork<NetAddress.Ipv4Address>

Ipv4NetworkInput

type unstable
Since v4.0.0

An IPv4 network prefix, or a CIDR string or parts to convert to one.

Signature

type Ipv4NetworkInput = Ipv4Network | string | IpNetworkParts<NetAddress.Ipv4AddressInput>

Ipv6Network

type unstable
Since v4.0.0

An immutable canonical IPv6 network prefix.

Signature

type Ipv6Network = IpNetwork<NetAddress.Ipv6Address>

Ipv6NetworkInput

type unstable
Since v4.0.0

An IPv6 network prefix, or a CIDR string or parts to convert to one.

Signature

type Ipv6NetworkInput = Ipv6Network | string | IpNetworkParts<NetAddress.Ipv6AddressInput>

Predicates

contains

unstable
Since v4.0.0

Returns true when a network prefix contains an IP address.

Signature

declare const contains: {
  (address: IpAddress): (self: IpNetwork) => boolean;
  (self: IpNetwork, address: IpAddress): boolean;
}

containsNetwork

unstable
Since v4.0.0

Returns true when a network prefix contains every address in another network prefix.

Signature

declare const containsNetwork: {
  (other: IpNetwork): (self: IpNetwork) => boolean;
  (self: IpNetwork, other: IpNetwork): boolean;
}

overlaps

unstable
Since v4.0.0

Returns true when two network prefixes contain at least one common address.

Signature

declare const overlaps: {
  (other: IpNetwork): (self: IpNetwork) => boolean;
  (self: IpNetwork, other: IpNetwork): boolean;
}

Unsafe

fromAddressUnsafe

unstable
Since v4.0.0

Creates the network containing a trusted address, throwing when its prefix is invalid. The derived address retains its IPv4 or IPv6 family but not refinements on the input address.

Signature

declare function fromAddressUnsafe<A extends IpAddress>(address: A, prefixLength: number): IpNetwork<Family<A>>

fromInputUnsafe

unstable
Since v4.0.0

Converts a trusted IpNetworkInput to a network prefix, throwing on failure.

Signature

declare function fromInputUnsafe(input: IpNetworkInput): IpNetwork

fromStringUnsafe

unstable
Since v4.0.0

Parses a trusted network prefix in CIDR notation, throwing on failure.

Signature

declare function fromStringUnsafe(input: string): IpNetwork

makeUnsafe

unstable
Since v4.0.0

Creates a trusted network prefix, throwing when its address or prefix is invalid.

Signature

declare function makeUnsafe<A extends IpAddress>(address: A, prefixLength: number): IpNetwork<A>