effect 4.0.2 → 4.0.4

package/src/net/NetAddress.ts

@@ -9,10 +9,11 @@ import * as Data from "../Data.ts"
 import * as Equal from "../Equal.ts"
 import { dual } from "../Function.ts"
 import * as Hash from "../Hash.ts"
-import { NodeInspectSymbol } from "../Inspectable.ts"
+import * as Inspectable from "../Inspectable.ts"
 import * as Option from "../Option.ts"
-import { hasProperty } from "../Predicate.ts"
+import { hasProperty, isTupleOf } from "../Predicate.ts"
 import * as Result from "../Result.ts"
+import type { TupleOf } from "../Types.ts"
 
 const TypeId = "~effect/net/NetAddress" as const
 
@@ -23,11 +24,9 @@ const TypeId = "~effect/net/NetAddress" as const
  * @category models
  * @since 4.0.0
  */
-export interface Ipv4Address extends Equal.Equal, Hash.Hash {
+export interface Ipv4Address extends Equal.Equal, Hash.Hash, Inspectable.Inspectable {
   readonly _tag: "Ipv4Address"
   readonly [TypeId]: typeof TypeId
-  toString(): string
-  toJSON(): string
 }
 
 /**
@@ -37,11 +36,9 @@ export interface Ipv4Address extends Equal.Equal, Hash.Hash {
  * @category models
  * @since 4.0.0
  */
-export interface Ipv6Address extends Equal.Equal, Hash.Hash {
+export interface Ipv6Address extends Equal.Equal, Hash.Hash, Inspectable.Inspectable {
   readonly _tag: "Ipv6Address"
   readonly [TypeId]: typeof TypeId
-  toString(): string
-  toJSON(): string
 }
 
 /**
@@ -53,6 +50,89 @@ export interface Ipv6Address extends Equal.Equal, Hash.Hash {
  */
 export type IpAddress = Ipv4Address | Ipv6Address
 
+/**
+ * The four octets of an IPv4 address in network order.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Ipv4Octets = Readonly<TupleOf<4, number>>
+
+/**
+ * The eight 16-bit segments of an IPv6 address in network order.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Ipv6Segments = Readonly<TupleOf<8, number>>
+
+/**
+ * The six octets of a MAC address in transmission order.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type MacAddressOctets = Readonly<TupleOf<6, number>>
+
+/**
+ * An IPv4 address, or a string, four octets, or four network-order bytes to
+ * convert to one.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Ipv4AddressInput = Ipv4Address | string | Ipv4Octets | Uint8Array
+
+/**
+ * An IPv6 address, or a string, eight 16-bit segments, or sixteen
+ * network-order bytes to convert to one.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Ipv6AddressInput = Ipv6Address | string | Ipv6Segments | Uint8Array
+
+/**
+ * An IP address, or any `Ipv4AddressInput` or `Ipv6AddressInput` to convert to
+ * one.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type IpAddressInput = Ipv4AddressInput | Ipv6AddressInput
+
+/**
+ * An IPv6 literal with a zone, such as `fe80::1%eth0` or `fe80::1%3`.
+ *
+ * **Details**
+ *
+ * Named zones are kept as written because mapping an interface name to a
+ * numeric scope ID requires the operating system's interface table. Numeric
+ * zones must be unsigned 32-bit integers and are stored without leading zeros,
+ * and the address part is stored in canonical form.
+ *
+ * @see {@link scopedIpv6LiteralFromString} for parsing scoped IPv6 literals
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export type ScopedIpv6Literal = Brand.Branded<string, "~effect/net/NetAddress/ScopedIpv6Literal">
+
+/**
+ * A scoped IPv6 literal or a string to parse as one.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export type ScopedIpv6LiteralInput = ScopedIpv6Literal | string
+
 /**
  * An immutable 48-bit IEEE 802 MAC address.
  *
@@ -60,13 +140,20 @@ export type IpAddress = Ipv4Address | Ipv6Address
  * @category models
  * @since 4.0.0
  */
-export interface MacAddress extends Equal.Equal, Hash.Hash {
+export interface MacAddress extends Equal.Equal, Hash.Hash, Inspectable.Inspectable {
   readonly _tag: "MacAddress"
   readonly [TypeId]: typeof TypeId
-  toString(): string
-  toJSON(): string
 }
 
+/**
+ * A MAC address, or a string or six octets to convert to one.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type MacAddressInput = MacAddress | string | MacAddressOctets
+
 const MulticastTypeId = "~effect/net/NetAddress/MulticastAddress" as const
 const UnicastTypeId = "~effect/net/NetAddress/UnicastAddress" as const
 const BroadcastTypeId = "~effect/net/NetAddress/BroadcastAddress" as const
@@ -228,13 +315,11 @@ const getMacBytes = (self: MacAddress): Uint8Array => (self as any).bytes
  * @category models
  * @since 4.0.0
  */
-export interface InetAddressV4 extends Equal.Equal, Hash.Hash {
+export interface InetAddressV4 extends Equal.Equal, Hash.Hash, Inspectable.Inspectable {
   readonly _tag: "InetAddressV4"
   readonly address: Ipv4Address
   readonly port: number
   readonly [TypeId]: typeof TypeId
-  toString(): string
-  toJSON(): string
 }
 
 /**
@@ -244,14 +329,12 @@ export interface InetAddressV4 extends Equal.Equal, Hash.Hash {
  * @category models
  * @since 4.0.0
  */
-export interface InetAddressV6 extends Equal.Equal, Hash.Hash {
+export interface InetAddressV6 extends Equal.Equal, Hash.Hash, Inspectable.Inspectable {
   readonly _tag: "InetAddressV6"
   readonly address: Ipv6Address
   readonly port: number
   readonly scopeId: number
   readonly [TypeId]: typeof TypeId
-  toString(): string
-  toJSON(): string
 }
 
 /**
@@ -263,6 +346,32 @@ export interface InetAddressV6 extends Equal.Equal, Hash.Hash {
  */
 export type InetAddress = InetAddressV4 | InetAddressV6
 
+/**
+ * The address, port, and optional IPv6 scope identifier of an internet address.
+ *
+ * **Details**
+ *
+ * A nonzero `scopeId` is only valid with an IPv6 address.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface InetAddressParts<A extends IpAddressInput = IpAddressInput> {
+  readonly address: A
+  readonly port: number
+  readonly scopeId?: number | undefined
+}
+
+/**
+ * An internet address and port, or a string or parts to convert to one.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type InetAddressInput = InetAddress | string | InetAddressParts
+
 /**
  * An opaque Unix-domain filesystem socket path.
  *
@@ -270,12 +379,10 @@ export type InetAddress = InetAddressV4 | InetAddressV6
  * @category models
  * @since 4.0.0
  */
-export interface UnixPathAddress extends Equal.Equal, Hash.Hash {
+export interface UnixPathAddress extends Equal.Equal, Hash.Hash, Inspectable.Inspectable {
   readonly _tag: "UnixPathAddress"
   readonly path: string
   readonly [TypeId]: typeof TypeId
-  toString(): string
-  toJSON(): string
 }
 
 /**
@@ -287,6 +394,17 @@ export interface UnixPathAddress extends Equal.Equal, Hash.Hash {
  */
 export type SocketAddress = InetAddress | UnixPathAddress
 
+/**
+ * The path of a Unix-domain socket address.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface UnixPathAddressParts {
+  readonly path: string
+}
+
 /**
  * Companion types for constructing socket addresses.
  *
@@ -300,18 +418,14 @@ export declare namespace SocketAddress {
    *
    * **Details**
    *
-   * String inputs must use `IPv4:port` or `[IPv6]:port` notation. Address
-   * properties must be numeric IPv4 or IPv6 literals.
+   * Accepts any `InetAddressInput` or a Unix path. String inputs must use
+   * `IPv4:port` or `[IPv6]:port` notation.
    *
    * @stability unstable
    * @category models
    * @since 4.0.0
    */
-  export type Input =
-    | SocketAddress
-    | string
-    | { readonly address: IpAddress | string; readonly port: number }
-    | { readonly path: string }
+  export type Input = SocketAddress | InetAddressInput | UnixPathAddressParts
 }
 
 /**
@@ -338,6 +452,29 @@ export declare namespace SocketAddress {
 export type Family<A extends IpAddress | InetAddress> = A extends Ipv4Address | InetAddressV4 ? Ipv4Address
   : Ipv6Address
 
+/**
+ * The name of an IP address family, spelled as in `os.networkInterfaces()` and
+ * socket address information on Node.js, Deno, and Bun.
+ *
+ * @see {@link familyOf} for reading the family of an address
+ * @see {@link FamilyAddress} for the address type of a family
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export type IpFamily = "IPv4" | "IPv6"
+
+/**
+ * The IP address type for an IP address family name. `FamilyAddress<IpFamily>`
+ * is `IpAddress`.
+ *
+ * @see {@link Family} for the inverse mapping from an address type
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export type FamilyAddress<F extends IpFamily> = F extends "IPv4" ? Ipv4Address : Ipv6Address
+
 /**
  * The internet address type for an IP address family.
  *
@@ -444,6 +581,93 @@ export const isIpAddress = (u: unknown): u is IpAddress => isIpv4Address(u) || i
  */
 export const width = (address: IpAddress): 32 | 128 => isIpv4Address(address) ? 32 : 128
 
+/**
+ * Returns the family of an IP address or internet address.
+ *
+ * **Example** (Reading address families)
+ *
+ * ```ts import.meta.vitest
+ * import { NetAddress } from "effect/net"
+ *
+ * NetAddress.familyOf(NetAddress.ipv4Loopback) // => "IPv4"
+ * NetAddress.familyOf(NetAddress.inetAddressFromStringUnsafe("[::1]:80")) // => "IPv6"
+ * ```
+ *
+ * @stability experimental
+ * @category getters
+ * @since 4.0.0
+ */
+export const familyOf = (self: IpAddress | InetAddress): IpFamily =>
+  isIpv4Address(self) || isInetAddressV4(self) ? "IPv4" : "IPv6"
+
+/**
+ * Returns `true` when an IP address or internet address belongs to a family,
+ * narrowing it to that family.
+ *
+ * @stability experimental
+ * @category predicates
+ * @since 4.0.0
+ */
+export const isFamily: {
+  /**
+   * Returns `true` when an IP address or internet address belongs to a family,
+   * narrowing it to that family.
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (family: "IPv4"): <A extends IpAddress | InetAddress>(self: A) => self is Extract<A, Ipv4Address | InetAddressV4>
+  /**
+   * Returns `true` when an IP address or internet address belongs to a family,
+   * narrowing it to that family.
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (family: "IPv6"): <A extends IpAddress | InetAddress>(self: A) => self is Extract<A, Ipv6Address | InetAddressV6>
+  /**
+   * Returns `true` when an IP address or internet address belongs to a family,
+   * narrowing it to that family.
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (family: IpFamily): (self: IpAddress | InetAddress) => boolean
+  /**
+   * Returns `true` when an IP address or internet address belongs to a family,
+   * narrowing it to that family.
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  <A extends IpAddress | InetAddress>(self: A, family: "IPv4"): self is Extract<A, Ipv4Address | InetAddressV4>
+  /**
+   * Returns `true` when an IP address or internet address belongs to a family,
+   * narrowing it to that family.
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  <A extends IpAddress | InetAddress>(self: A, family: "IPv6"): self is Extract<A, Ipv6Address | InetAddressV6>
+  /**
+   * Returns `true` when an IP address or internet address belongs to a family,
+   * narrowing it to that family.
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (self: IpAddress | InetAddress, family: IpFamily): boolean
+} = dual(
+  2,
+  <A extends IpAddress | InetAddress>(self: A, family: IpFamily): self is A => familyOf(self) === family
+)
+
 /**
  * Returns `true` when a value is a MAC address.
  *
@@ -499,6 +723,7 @@ export const isUnixPathAddress = (u: unknown): u is UnixPathAddress => isAddress
 export const isSocketAddress = (u: unknown): u is SocketAddress => isInetAddress(u) || isUnixPathAddress(u)
 
 const Ipv4Proto = {
+  ...Inspectable.BaseProto,
   _tag: "Ipv4Address",
   [TypeId]: TypeId,
   [Equal.symbol](this: Ipv4Address, that: Equal.Equal): boolean {
@@ -512,13 +737,11 @@ const Ipv4Proto = {
   },
   toJSON(this: Ipv4Address): string {
     return this.toString()
-  },
-  [NodeInspectSymbol](this: Ipv4Address): string {
-    return this.toJSON()
   }
 }
 
 const Ipv6Proto = {
+  ...Inspectable.BaseProto,
   _tag: "Ipv6Address",
   [TypeId]: TypeId,
   [Equal.symbol](this: Ipv6Address, that: Equal.Equal): boolean {
@@ -539,13 +762,11 @@ const Ipv6Proto = {
   },
   toJSON(this: Ipv6Address): string {
     return this.toString()
-  },
-  [NodeInspectSymbol](this: Ipv6Address): string {
-    return this.toJSON()
   }
 }
 
 const MacProto = {
+  ...Inspectable.BaseProto,
   _tag: "MacAddress",
   [TypeId]: TypeId,
   [Equal.symbol](this: MacAddress, that: Equal.Equal): boolean {
@@ -559,9 +780,6 @@ const MacProto = {
   },
   toJSON(this: MacAddress): string {
     return this.toString()
-  },
-  [NodeInspectSymbol](this: MacAddress): string {
-    return this.toJSON()
   }
 }
 
@@ -597,7 +815,7 @@ const packOctets = (a: number, b: number, c: number, d: number): number => ((a <
 const packBytes = (bytes: Uint8Array, offset: number): number =>
   packOctets(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3])
 
-const wordToOctets = (word: number): readonly [number, number, number, number] => [
+const wordToOctets = (word: number): Ipv4Octets => [
   word >>> 24,
   (word >>> 16) & 0xff,
   (word >>> 8) & 0xff,
@@ -646,6 +864,15 @@ export const ipv4Loopback: Ipv4Address = makeIpv4(0x7f000001)
  */
 export const ipv6Loopback: Ipv6Address = makeIpv6(0, 0, 0, 1)
 
+/**
+ * The loopback addresses `127.0.0.1` and `::1`.
+ *
+ * @stability unstable
+ * @category constants
+ * @since 4.0.0
+ */
+export const loopbackAddresses: readonly [Ipv4Address, Ipv6Address] = [ipv4Loopback, ipv6Loopback]
+
 /**
  * The unspecified IPv4 address `0.0.0.0`.
  *
@@ -676,6 +903,15 @@ export const ipv4Broadcast: Ipv4Address = makeIpv4(0xffffffff)
 const addressError = (input: unknown, message: string): Result.Result<never, NetAddressError> =>
   Result.fail(new NetAddressError({ input, message }))
 
+// Checks by index because `every` skips holes in sparse arrays.
+const allIntegersInRange = (values: ReadonlyArray<number>, max: number): boolean => {
+  for (let i = 0; i < values.length; i++) {
+    const n = values[i]
+    if (!Number.isInteger(n) || n < 0 || n > max) return false
+  }
+  return true
+}
+
 /**
  * Creates an IPv4 address from four checked octets.
  *
@@ -684,9 +920,9 @@ const addressError = (input: unknown, message: string): Result.Result<never, Net
  * @since 4.0.0
  */
 export const ipv4FromOctets = (
-  octets: readonly [number, number, number, number]
+  octets: Ipv4Octets
 ): Result.Result<Ipv4Address, NetAddressError> => {
-  if (!octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
+  if (!allIntegersInRange(octets, 255)) {
     return addressError(octets, "octets must be integers from 0 through 255")
   }
   return Result.succeed(makeIpv4(packOctets(octets[0], octets[1], octets[2], octets[3])))
@@ -700,9 +936,9 @@ export const ipv4FromOctets = (
  * @since 4.0.0
  */
 export const ipv6FromSegments = (
-  segments: readonly [number, number, number, number, number, number, number, number]
+  segments: Ipv6Segments
 ): Result.Result<Ipv6Address, NetAddressError> => {
-  if (!segments.every((n) => Number.isInteger(n) && n >= 0 && n <= 0xffff)) {
+  if (!allIntegersInRange(segments, 0xffff)) {
     return addressError(segments, "segments must be integers from 0 through 65535")
   }
   return Result.succeed(makeIpv6(
@@ -721,9 +957,9 @@ export const ipv6FromSegments = (
  * @since 4.0.0
  */
 export const macAddressFromOctets = (
-  octets: readonly [number, number, number, number, number, number]
+  octets: MacAddressOctets
 ): Result.Result<MacAddress, NetAddressError> => {
-  if (!octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
+  if (!allIntegersInRange(octets, 255)) {
     return addressError(octets, "octets must be integers from 0 through 255")
   }
   return Result.succeed(makeMac(new Uint8Array(octets)))
@@ -752,6 +988,32 @@ export const macAddressFromString = (input: string): Result.Result<MacAddress, N
  */
 export const macAddressFromStringUnsafe = (input: string): MacAddress => Result.getOrThrow(macAddressFromString(input))
 
+/**
+ * Converts a `MacAddressInput` to a MAC address, parsing strings like
+ * `macAddressFromString`, checking octets like `macAddressFromOctets`, and
+ * returning MAC addresses unchanged.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const macAddressFromInput = (input: MacAddressInput): Result.Result<MacAddress, NetAddressError> => {
+  if (isMacAddress(input)) return Result.succeed(input)
+  if (typeof input === "string") return macAddressFromString(input)
+  if (Array.isArray(input) && isTupleOf(input, 6)) return macAddressFromOctets(input)
+  return addressError(input, "expected a MAC address, string, or 6 octets")
+}
+
+/**
+ * Converts a trusted `MacAddressInput` to a MAC address, throwing on failure.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export const macAddressFromInputUnsafe = (input: MacAddressInput): MacAddress =>
+  Result.getOrThrow(macAddressFromInput(input))
+
 /**
  * Parses a strict dotted-decimal IPv4 address.
  *
@@ -875,6 +1137,141 @@ export const ipFromString = (input: string): Result.Result<IpAddress, NetAddress
  */
 export const ipFromStringUnsafe = (input: string): IpAddress => Result.getOrThrow(ipFromString(input))
 
+/**
+ * Converts an `IpAddressInput` to an IP address, returning IP addresses
+ * unchanged.
+ *
+ * **Details**
+ *
+ * Strings are parsed like `ipFromString`. Four octets or bytes make an IPv4
+ * address, and eight segments or sixteen bytes make an IPv6 address.
+ *
+ * **Example** (Converting IP address inputs)
+ *
+ * ```ts import.meta.vitest
+ * import { Result } from "effect"
+ * import { NetAddress } from "effect/net"
+ *
+ * const address = Result.getOrThrow(NetAddress.ipFromInput("192.0.2.1"))
+ * NetAddress.formatIp(address) // => "192.0.2.1"
+ * Result.getOrThrow(NetAddress.ipFromInput(address)) === address // => true
+ * NetAddress.formatIp(Result.getOrThrow(NetAddress.ipFromInput([192, 0, 2, 1]))) // => "192.0.2.1"
+ * Result.isFailure(NetAddress.ipFromInput("example.com")) // => true
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const ipFromInput = (input: IpAddressInput): Result.Result<IpAddress, NetAddressError> => {
+  if (isIpAddress(input)) return Result.succeed(input)
+  if (typeof input === "string") return ipFromString(input)
+  if (input instanceof Uint8Array && input.length === 4) return Result.succeed(ipv4FromBytesUnsafe(input))
+  if (input instanceof Uint8Array && input.length === 16) return Result.succeed(ipv6FromBytesUnsafe(input))
+  if (Array.isArray(input) && isTupleOf(input, 4)) return ipv4FromOctets(input)
+  if (Array.isArray(input) && isTupleOf(input, 8)) return ipv6FromSegments(input)
+  return addressError(input, "expected an IP address, string, 4 octets, 8 segments, or 4 or 16 bytes")
+}
+
+/**
+ * Converts a trusted `IpAddressInput` to an IP address, throwing on failure.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export const ipFromInputUnsafe = (input: IpAddressInput): IpAddress => Result.getOrThrow(ipFromInput(input))
+
+/**
+ * Converts an `Ipv4AddressInput` to an IPv4 address, parsing strings like
+ * `ipv4FromString`, checking octets like `ipv4FromOctets`, and returning IPv4
+ * addresses unchanged.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const ipv4FromInput = (input: Ipv4AddressInput): Result.Result<Ipv4Address, NetAddressError> => {
+  if (isIpv4Address(input)) return Result.succeed(input)
+  if (typeof input === "string") return ipv4FromString(input)
+  if (input instanceof Uint8Array && input.length === 4) return Result.succeed(ipv4FromBytesUnsafe(input))
+  if (Array.isArray(input) && isTupleOf(input, 4)) return ipv4FromOctets(input)
+  return addressError(input, "expected an IPv4 address, string, 4 octets, or 4 bytes")
+}
+
+/**
+ * Converts an `Ipv6AddressInput` to an IPv6 address, parsing strings like
+ * `ipv6FromString`, checking segments like `ipv6FromSegments`, and returning
+ * IPv6 addresses unchanged.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const ipv6FromInput = (input: Ipv6AddressInput): Result.Result<Ipv6Address, NetAddressError> => {
+  if (isIpv6Address(input)) return Result.succeed(input)
+  if (typeof input === "string") return ipv6FromString(input)
+  if (input instanceof Uint8Array && input.length === 16) return Result.succeed(ipv6FromBytesUnsafe(input))
+  if (Array.isArray(input) && isTupleOf(input, 8)) return ipv6FromSegments(input)
+  return addressError(input, "expected an IPv6 address, string, 8 segments, or 16 bytes")
+}
+
+/**
+ * Returns `true` when a value is a canonical scoped IPv6 literal.
+ *
+ * @stability experimental
+ * @category guards
+ * @since 4.0.0
+ */
+export const isScopedIpv6Literal = (u: unknown): u is ScopedIpv6Literal => {
+  if (typeof u !== "string" || !u.includes("%")) return false
+  const result = scopedIpv6LiteralFromString(u)
+  return Result.isSuccess(result) && result.success === u
+}
+
+/**
+ * Parses an IPv6 literal with a numeric or named zone, such as `fe80::1%eth0`.
+ *
+ * @stability experimental
+ * @category decoding
+ * @since 4.0.0
+ */
+export const scopedIpv6LiteralFromString = (
+  input: string
+): Result.Result<ScopedIpv6Literal, NetAddressError> => {
+  const separator = input.indexOf("%")
+  if (separator === -1) return addressError(input, "expected an IPv6 zone")
+  let zone = input.slice(separator + 1)
+  if (zone.length === 0 || /[%[\]/\s\p{Cc}]/u.test(zone)) {
+    return addressError(input, "invalid IPv6 scope identifier")
+  }
+  if (/^\d+$/.test(zone)) {
+    const scopeId = Number(zone)
+    if (scopeId > 0xffffffff) return addressError(input, "scope identifier must be an unsigned 32-bit integer")
+    zone = String(scopeId)
+  }
+  return Result.map(
+    ipv6FromString(input.slice(0, separator)),
+    (address) => `${formatIp(address)}%${zone}` as ScopedIpv6Literal
+  )
+}
+
+/**
+ * Converts a `ScopedIpv6LiteralInput` to a scoped IPv6 literal, parsing it
+ * like `scopedIpv6LiteralFromString`.
+ *
+ * **Details**
+ *
+ * Scoped IPv6 literals are strings, so every input is parsed.
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.0.0
+ */
+export const scopedIpv6LiteralFromInput = (
+  input: ScopedIpv6LiteralInput
+): Result.Result<ScopedIpv6Literal, NetAddressError> => scopedIpv6LiteralFromString(input)
+
 /**
  * Returns the four numeric octets of an IPv4 address in a fresh tuple.
  *
@@ -882,8 +1279,7 @@ export const ipFromStringUnsafe = (input: string): IpAddress => Result.getOrThro
  * @category getters
  * @since 4.0.0
  */
-export const ipv4ToOctets = (self: Ipv4Address): readonly [number, number, number, number] =>
-  wordToOctets(ipv4Value(self))
+export const ipv4ToOctets = (self: Ipv4Address): Ipv4Octets => wordToOctets(ipv4Value(self))
 
 /**
  * Returns the eight numeric segments of an IPv6 address in a fresh tuple.
@@ -892,9 +1288,7 @@ export const ipv4ToOctets = (self: Ipv4Address): readonly [number, number, numbe
  * @category getters
  * @since 4.0.0
  */
-export const ipv6ToSegments = (
-  self: Ipv6Address
-): readonly [number, number, number, number, number, number, number, number] => {
+export const ipv6ToSegments = (self: Ipv6Address): Ipv6Segments => {
   const { w0, w1, w2, w3 } = ipv6Words(self)
   return [w0 >>> 16, w0 & 0xffff, w1 >>> 16, w1 & 0xffff, w2 >>> 16, w2 & 0xffff, w3 >>> 16, w3 & 0xffff]
 }
@@ -920,9 +1314,7 @@ export const ipv6ToOctets = (
  * @category getters
  * @since 4.0.0
  */
-export const macAddressToOctets = (
-  self: MacAddress
-): readonly [number, number, number, number, number, number] => {
+export const macAddressToOctets = (self: MacAddress): MacAddressOctets => {
   const bytes = getMacBytes(self)
   return [bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5]]
 }
@@ -1254,6 +1646,7 @@ export function toCanonical(self: IpAddress | InetAddress): IpAddress | InetAddr
 }
 
 const InetV4Proto = {
+  ...Inspectable.BaseProto,
   _tag: "InetAddressV4",
   [TypeId]: TypeId,
   [Equal.symbol](this: InetAddressV4, that: Equal.Equal): boolean {
@@ -1267,13 +1660,11 @@ const InetV4Proto = {
   },
   toJSON(this: InetAddressV4): string {
     return this.toString()
-  },
-  [NodeInspectSymbol](this: InetAddressV4): string {
-    return this.toJSON()
   }
 }
 
 const InetV6Proto = {
+  ...Inspectable.BaseProto,
   _tag: "InetAddressV6",
   [TypeId]: TypeId,
   [Equal.symbol](this: InetAddressV6, that: Equal.Equal): boolean {
@@ -1291,9 +1682,6 @@ const InetV6Proto = {
   },
   toJSON(this: InetAddressV6): string {
     return this.toString()
-  },
-  [NodeInspectSymbol](this: InetAddressV6): string {
-    return this.toJSON()
   }
 }
 
@@ -1396,6 +1784,112 @@ export const inetAddressFromIpString = (
 export const inetAddressFromIpStringUnsafe = (address: string, port: number): InetAddress =>
   Result.getOrThrow(inetAddressFromIpString(address, port))
 
+/**
+ * Creates an internet address from a trusted native numeric host and port.
+ * Named IPv6 zones are resolved using the supplied interface-to-scope map.
+ * Use only for runtime-supplied socket addresses: this skips input validation,
+ * so malformed strings or ports may silently produce incorrect values. An
+ * unknown named IPv6 zone throws rather than losing its scope.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export const inetAddressFromNativeUnsafe = (
+  host: string,
+  port: number,
+  scopeIds?: ReadonlyMap<string, number>
+): InetAddress => {
+  const zoneStart = host.indexOf("%")
+  const end = zoneStart === -1 ? host.length : zoneStart
+  if (host.indexOf(":") === -1) {
+    const self = Object.create(InetV4Proto)
+    self.address = makeIpv4(parseNativeIpv4(host, 0, end))
+    self.port = port
+    return Object.freeze(self)
+  }
+
+  let scopeId = 0
+  if (zoneStart !== -1) {
+    const zone = host.slice(zoneStart + 1)
+    const resolved = numericZone.test(zone) ? Number(zone) : scopeIds?.get(zone)
+    if (resolved === undefined) throw new Error(`unknown IPv6 interface: ${zone}`)
+    scopeId = resolved
+  }
+
+  let w0 = 0
+  let w1 = 0
+  let w2 = 0
+  let w3 = 0
+  let segment = 0
+  let i = 0
+  while (i < end) {
+    if (host.charCodeAt(i) === 58) {
+      // The rest of a compressed address is anchored at the last segment.
+      i += 2
+      if (i === end) break
+      let remaining = 1
+      for (let j = i; j < end; j++) {
+        if (host.charCodeAt(j) === 58) remaining++
+      }
+      const dot = host.indexOf(".", i)
+      if (dot !== -1 && dot < end) remaining++
+      segment = 8 - remaining
+    }
+    const start = i
+    let value = 0
+    while (i < end) {
+      const ch = host.charCodeAt(i)
+      if (ch === 58 || ch === 46) break
+      value = (value << 4) | (ch <= 57 ? ch - 48 : (ch & 0x5f) - 55)
+      i++
+    }
+    if (i < end && host.charCodeAt(i) === 46) {
+      w3 = parseNativeIpv4(host, start, end)
+      break
+    }
+    // even segments fill the high half of their 32-bit word
+    const shifted = value << ((1 - (segment & 1)) * 16)
+    switch (segment >>> 1) {
+      case 0:
+        w0 |= shifted
+        break
+      case 1:
+        w1 |= shifted
+        break
+      case 2:
+        w2 |= shifted
+        break
+      default:
+        w3 |= shifted
+    }
+    segment++
+    if (i < end && host.charCodeAt(i + 1) !== 58) i++
+  }
+  const self = Object.create(InetV6Proto)
+  self.address = makeIpv6(w0, w1, w2, w3)
+  self.port = port
+  self.scopeId = scopeId
+  return Object.freeze(self)
+}
+
+const numericZone = /^\d+$/
+
+const parseNativeIpv4 = (host: string, start: number, end: number): number => {
+  let value = 0
+  let octet = 0
+  for (let i = start; i < end; i++) {
+    const ch = host.charCodeAt(i)
+    if (ch === 46) {
+      value = (value << 8) | octet
+      octet = 0
+    } else {
+      octet = octet * 10 + ch - 48
+    }
+  }
+  return ((value << 8) | octet) >>> 0
+}
+
 /**
  * Parses an unbracketed numeric host and port, resolving named IPv6 zones using
  * a supplied map of interface names to numeric scope IDs.
@@ -1443,7 +1937,33 @@ export const inetAddressFromHostString = (
  */
 export interface NetworkInterfaceAddress {
   readonly family: string
-  readonly scopeid?: number | undefined
+  readonly scopeid?: number | null | undefined
+}
+
+/**
+ * Returns the IPv6 scope ID of a network interface from its addresses.
+ *
+ * **Details**
+ *
+ * The first IPv6 address with a positive scope ID supplies the result. Accepts
+ * the addresses of one interface, such as `os.networkInterfaces()[name]` or the
+ * entries of `Deno.networkInterfaces()` with that name, without performing any
+ * operating-system lookup itself.
+ *
+ * @see {@link scopeIdsFromInterfaces} for mapping every interface at once
+ * @stability experimental
+ * @category converting
+ * @since 4.0.0
+ */
+export const scopeIdFromInterface = (
+  addresses: ReadonlyArray<NetworkInterfaceAddress> | undefined
+): Option.Option<number> => {
+  for (const address of addresses ?? []) {
+    if (address.family === "IPv6" && typeof address.scopeid === "number" && address.scopeid > 0) {
+      return Option.some(address.scopeid)
+    }
+  }
+  return Option.none()
 }
 
 /**
@@ -1468,8 +1988,8 @@ export const scopeIdsFromInterfaces = (
 ): Map<string, number> => {
   const scopeIds = new Map<string, number>()
   for (const [name, addresses] of interfaces) {
-    const address = addresses?.find((address) => address.family === "IPv6" && (address.scopeid ?? 0) > 0)
-    if (address?.scopeid !== undefined) scopeIds.set(name, address.scopeid)
+    const scopeId = scopeIdFromInterface(addresses)
+    if (Option.isSome(scopeId)) scopeIds.set(name, scopeId.value)
   }
   return scopeIds
 }
@@ -1539,6 +2059,40 @@ export const inetAddressFromString = (input: string): Result.Result<InetAddress,
 export const inetAddressFromStringUnsafe = (input: string): InetAddress =>
   Result.getOrThrow(inetAddressFromString(input))
 
+/**
+ * Converts an `InetAddressInput` to an internet address, parsing strings like
+ * `inetAddressFromString`, converting parts like `inetAddressV4` and
+ * `inetAddressV6`, and returning internet addresses unchanged.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const inetAddressFromInput = (input: InetAddressInput): Result.Result<InetAddress, NetAddressError> => {
+  if (isInetAddress(input)) return Result.succeed(input)
+  if (typeof input === "string") return inetAddressFromString(input)
+  if (!hasProperty(input, "address") || !hasProperty(input, "port")) {
+    return addressError(input, "expected an address and port")
+  }
+  const { port, scopeId } = input
+  return Result.flatMap(ipFromInput(input.address), (address): Result.Result<InetAddress, NetAddressError> => {
+    if (isIpv6Address(address)) return inetAddressV6(address, port, { scopeId })
+    return (scopeId ?? 0) === 0
+      ? inetAddressV4(address, port)
+      : addressError(input, "scopeId requires an IPv6 address")
+  })
+}
+
+/**
+ * Converts a trusted `InetAddressInput` to an internet address, throwing on failure.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export const inetAddressFromInputUnsafe = (input: InetAddressInput): InetAddress =>
+  Result.getOrThrow(inetAddressFromInput(input))
+
 /**
  * Formats the numeric host of an internet address without brackets or a port,
  * preserving a nonzero IPv6 scope ID as a `%` suffix.
@@ -1722,6 +2276,7 @@ export const formatUrlHostString = (host: string): string =>
   host.includes(":") && !host.startsWith("[") ? `[${host}]` : host
 
 const UnixPathProto = {
+  ...Inspectable.BaseProto,
   _tag: "UnixPathAddress",
   [TypeId]: TypeId,
   [Equal.symbol](this: UnixPathAddress, that: Equal.Equal): boolean {
@@ -1735,9 +2290,6 @@ const UnixPathProto = {
   },
   toJSON(this: UnixPathAddress): string {
     return this.toString()
-  },
-  [NodeInspectSymbol](this: UnixPathAddress): string {
-    return this.toJSON()
   }
 }
 
@@ -1773,8 +2325,9 @@ export const formatUnixPath = (self: UnixPathAddress): string => `unix://${self.
  *
  * **Details**
  *
- * Numeric IP strings are parsed without hostname resolution. Invalid IP
- * literals, ports, and input shapes return a `NetAddressError`.
+ * Internet addresses are converted like `inetAddressFromInput`, without
+ * hostname resolution. Invalid IP literals, ports, and input shapes return a
+ * `NetAddressError`.
  *
  * @stability unstable
  * @category constructors
@@ -1783,22 +2336,13 @@ export const formatUnixPath = (self: UnixPathAddress): string => `unix://${self.
 export const socketAddressFromInput = (
   input: SocketAddress.Input
 ): Result.Result<SocketAddress, NetAddressError> => {
-  if (isSocketAddress(input)) return Result.succeed(input)
-  if (typeof input === "string") return inetAddressFromString(input)
+  if (isUnixPathAddress(input)) return Result.succeed(input)
   if (hasProperty(input, "path")) {
     return typeof input.path === "string"
       ? Result.succeed(unixPathAddress(input.path))
       : addressError(input, "path must be a string")
   }
-  if (!hasProperty(input, "address") || !hasProperty(input, "port")) {
-    return addressError(input, "expected an address and port or a Unix path")
-  }
-  const address = typeof input.address === "string"
-    ? ipFromString(input.address)
-    : isIpAddress(input.address)
-    ? Result.succeed(input.address)
-    : addressError(input, "address must be an IP address or numeric IP string")
-  return Result.flatMap(address, (address) => inetAddress(address, input.port as number))
+  return inetAddressFromInput(input)
 }
 
 /**