effect 4.0.0-rc.112 → 4.0.0-rc.113

package/dist/unstable/net/NetAddress.d.ts

@@ -0,0 +1,705 @@
+import * as Equal from "../../Equal.ts";
+import * as Hash from "../../Hash.ts";
+import * as Option from "../../Option.ts";
+import * as Result from "../../Result.ts";
+declare const TypeId: "~effect/net/NetAddress";
+/**
+ * An immutable 32-bit IPv4 address.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Ipv4Address extends Equal.Equal, Hash.Hash {
+    readonly _tag: "Ipv4Address";
+    readonly [TypeId]: typeof TypeId;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * An immutable 128-bit IPv6 address without socket scope metadata.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Ipv6Address extends Equal.Equal, Hash.Hash {
+    readonly _tag: "Ipv6Address";
+    readonly [TypeId]: typeof TypeId;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A numeric IPv4 or IPv6 address.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type IpAddress = Ipv4Address | Ipv6Address;
+/**
+ * An immutable 48-bit IEEE 802 MAC address.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface MacAddress extends Equal.Equal, Hash.Hash {
+    readonly _tag: "MacAddress";
+    readonly [TypeId]: typeof TypeId;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A resolved IPv4 internet address and port.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface InetAddressV4 extends Equal.Equal, Hash.Hash {
+    readonly _tag: "InetAddressV4";
+    readonly address: Ipv4Address;
+    readonly port: number;
+    readonly [TypeId]: typeof TypeId;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A resolved IPv6 internet address, port, and scope identifier.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface InetAddressV6 extends Equal.Equal, Hash.Hash {
+    readonly _tag: "InetAddressV6";
+    readonly address: Ipv6Address;
+    readonly port: number;
+    readonly scopeId: number;
+    readonly [TypeId]: typeof TypeId;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A resolved IPv4 or IPv6 internet address and port.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type InetAddress = InetAddressV4 | InetAddressV6;
+/**
+ * An opaque Unix-domain filesystem socket path.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface UnixPathAddress extends Equal.Equal, Hash.Hash {
+    readonly _tag: "UnixPathAddress";
+    readonly path: string;
+    readonly [TypeId]: typeof TypeId;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A portable concrete internet or Unix-domain filesystem address.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type SocketAddress = InetAddress | UnixPathAddress;
+/**
+ * Companion types for constructing socket addresses.
+ *
+ * @since 4.0.0
+ */
+export declare namespace SocketAddress {
+    /**
+     * Input that can be converted to a concrete `SocketAddress` without hostname
+     * resolution.
+     *
+     * **Details**
+     *
+     * String inputs must use `IPv4:port` or `[IPv6]:port` notation. Address
+     * properties must be numeric IPv4 or IPv6 literals.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    type Input = SocketAddress | string | {
+        readonly address: IpAddress | string;
+        readonly port: number;
+    } | {
+        readonly path: string;
+    };
+}
+declare const NetAddressError_base: new <A extends Record<string, any> = {}>(args: import("../../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../../Cause.ts").YieldableError & {
+    readonly _tag: "NetAddressError";
+} & Readonly<A>;
+/**
+ * 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.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export declare class NetAddressError extends NetAddressError_base<{
+    readonly message: string;
+    readonly input: unknown;
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * Returns `true` when a value is an IPv4 address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isIpv4Address: (u: unknown) => u is Ipv4Address;
+/**
+ * Returns `true` when a value is an IPv6 address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isIpv6Address: (u: unknown) => u is Ipv6Address;
+/**
+ * Returns `true` when a value is an IPv4 or IPv6 address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isIpAddress: (u: unknown) => u is IpAddress;
+/**
+ * Returns the bit width of an IP address.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const width: (address: IpAddress) => 32 | 128;
+/**
+ * Returns `true` when a value is a MAC address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isMacAddress: (u: unknown) => u is MacAddress;
+/**
+ * Returns `true` when a value is a resolved IPv4 internet address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isInetAddressV4: (u: unknown) => u is InetAddressV4;
+/**
+ * Returns `true` when a value is a resolved IPv6 internet address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isInetAddressV6: (u: unknown) => u is InetAddressV6;
+/**
+ * Returns `true` when a value is a resolved internet address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isInetAddress: (u: unknown) => u is InetAddress;
+/**
+ * Returns `true` when a value is a Unix-domain filesystem address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isUnixPathAddress: (u: unknown) => u is UnixPathAddress;
+/**
+ * Returns `true` when a value is a portable concrete socket address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isSocketAddress: (u: unknown) => u is SocketAddress;
+/**
+ * Creates an IPv4 address from trusted network-order bytes without validation.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const ipv4FromBytesUnsafe: (bytes: Uint8Array) => Ipv4Address;
+/**
+ * Creates an IPv6 address from trusted network-order bytes without validation.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const ipv6FromBytesUnsafe: (bytes: Uint8Array) => Ipv6Address;
+/**
+ * The IPv4 loopback address `127.0.0.1`.
+ *
+ * @category constants
+ * @since 4.0.0
+ */
+export declare const ipv4Loopback: Ipv4Address;
+/**
+ * The IPv6 loopback address `::1`.
+ *
+ * @category constants
+ * @since 4.0.0
+ */
+export declare const ipv6Loopback: Ipv6Address;
+/**
+ * The unspecified IPv4 address `0.0.0.0`.
+ *
+ * @category constants
+ * @since 4.0.0
+ */
+export declare const ipv4Unspecified: Ipv4Address;
+/**
+ * The unspecified IPv6 address `::`.
+ *
+ * @category constants
+ * @since 4.0.0
+ */
+export declare const ipv6Unspecified: Ipv6Address;
+/**
+ * The IPv4 broadcast address `255.255.255.255`.
+ *
+ * @category constants
+ * @since 4.0.0
+ */
+export declare const ipv4Broadcast: Ipv4Address;
+/**
+ * Creates an IPv4 address from four checked octets.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const ipv4FromOctets: (octets: readonly [number, number, number, number]) => Result.Result<Ipv4Address, NetAddressError>;
+/**
+ * Creates an IPv6 address from eight checked 16-bit segments.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const ipv6FromSegments: (segments: readonly [number, number, number, number, number, number, number, number]) => Result.Result<Ipv6Address, NetAddressError>;
+/**
+ * Creates a MAC address from six checked octets.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const macAddressFromOctets: (octets: readonly [number, number, number, number, number, number]) => Result.Result<MacAddress, NetAddressError>;
+/**
+ * Parses a colon-separated MAC address containing six two-digit hexadecimal octets.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const macAddressFromString: (input: string) => Result.Result<MacAddress, NetAddressError>;
+/**
+ * Parses a trusted colon-separated MAC address, throwing on failure.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const macAddressFromStringUnsafe: (input: string) => MacAddress;
+/**
+ * Parses a strict dotted-decimal IPv4 address.
+ *
+ * **Details**
+ *
+ * Multi-digit octets with a leading zero are rejected to avoid octal ambiguity.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const ipv4FromString: (input: string) => Result.Result<Ipv4Address, NetAddressError>;
+/**
+ * Parses an IPv6 address with optional compression and trailing embedded IPv4.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const ipv6FromString: (input: string) => Result.Result<Ipv6Address, NetAddressError>;
+/**
+ * Parses a bare numeric IPv4 or IPv6 address.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const ipFromString: (input: string) => Result.Result<IpAddress, NetAddressError>;
+/**
+ * Parses a trusted bare numeric IPv4 or IPv6 address, throwing on failure.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const ipFromStringUnsafe: (input: string) => IpAddress;
+/**
+ * Returns the four numeric octets of an IPv4 address in a fresh tuple.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const ipv4ToOctets: (self: Ipv4Address) => readonly [number, number, number, number];
+/**
+ * Returns the eight numeric segments of an IPv6 address in a fresh tuple.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const ipv6ToSegments: (self: Ipv6Address) => readonly [number, number, number, number, number, number, number, number];
+/**
+ * Returns the sixteen numeric octets of an IPv6 address in a fresh array.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const ipv6ToOctets: (self: Ipv6Address) => ReadonlyArray<number>;
+/**
+ * Returns the six numeric octets of a MAC address in a fresh tuple.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export declare const macAddressToOctets: (self: MacAddress) => readonly [number, number, number, number, number, number];
+/**
+ * Formats a MAC address as six lowercase hexadecimal octets separated by colons.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatMacAddress: (self: MacAddress) => string;
+/**
+ * Returns `true` when the MAC address is the all-ones broadcast address.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isMacBroadcast: (self: MacAddress) => boolean;
+/**
+ * Returns `true` when the MAC address has the IEEE group-address bit set.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isMacMulticast: (self: MacAddress) => boolean;
+/**
+ * Returns `true` when the MAC address has the IEEE group-address bit clear.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isMacUnicast: (self: MacAddress) => boolean;
+/**
+ * Returns `true` when the MAC address has the IEEE local-administration bit set.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isMacLocallyAdministered: (self: MacAddress) => boolean;
+/**
+ * Returns `true` when the MAC address has the IEEE local-administration bit clear.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isMacUniversallyAdministered: (self: MacAddress) => boolean;
+/**
+ * Folds an IP address by its numeric version.
+ *
+ * @category pattern matching
+ * @since 4.0.0
+ */
+export declare const match: {
+    /**
+     * Folds an IP address by its numeric version.
+     *
+     * @category pattern matching
+     * @since 4.0.0
+     */
+    <A, B>(options: {
+        readonly onIpv4: (address: Ipv4Address) => A;
+        readonly onIpv6: (address: Ipv6Address) => B;
+    }): (self: IpAddress) => A | B;
+    /**
+     * Folds an IP address by its numeric version.
+     *
+     * @category pattern matching
+     * @since 4.0.0
+     */
+    <A, B>(self: IpAddress, options: {
+        readonly onIpv4: (address: Ipv4Address) => A;
+        readonly onIpv6: (address: Ipv6Address) => B;
+    }): A | B;
+};
+/**
+ * Formats an IP address in canonical numeric form.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatIp: (self: IpAddress) => string;
+/**
+ * Returns `true` for the all-zero address of either IP version.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isUnspecified: (self: IpAddress) => boolean;
+/**
+ * Returns `true` for IPv4 `127.0.0.0/8` or IPv6 `::1`.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isLoopback: (self: IpAddress) => boolean;
+/**
+ * Returns `true` for IPv4 `224.0.0.0/4` or IPv6 `ff00::/8`.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isMulticast: (self: IpAddress) => boolean;
+/**
+ * Returns `true` for the IPv4 broadcast address `255.255.255.255`.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isBroadcast: (self: Ipv4Address) => boolean;
+/**
+ * Returns `true` for IPv4 `169.254.0.0/16` or IPv6 `fe80::/10`.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isLinkLocal: (self: IpAddress) => boolean;
+/**
+ * Returns `true` for IPv4 private-use ranges defined by RFC 1918.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isPrivate: (self: Ipv4Address) => boolean;
+/**
+ * Returns `true` for IPv6 unique-local addresses in `fc00::/7`.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isUniqueLocal: (self: Ipv6Address) => boolean;
+/**
+ * Returns `true` when an IPv6 address is in the `::ffff:0:0/96` mapped range.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export declare const isIpv4Mapped: (self: Ipv6Address) => boolean;
+/**
+ * Converts an IPv4 address to its IPv4-mapped IPv6 representation.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
+export declare const toIpv4Mapped: (self: Ipv4Address) => Ipv6Address;
+/**
+ * Extracts the IPv4 value from an IPv4-mapped IPv6 address.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
+export declare const fromIpv4Mapped: (self: Ipv6Address) => Option.Option<Ipv4Address>;
+/**
+ * Converts an IPv4-mapped IPv6 address to IPv4, leaving all other addresses unchanged.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
+export declare const toCanonical: (self: IpAddress) => IpAddress;
+/**
+ * Creates a checked IPv4 internet address.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const inetAddressV4: (address: Ipv4Address, port: number) => Result.Result<InetAddressV4, NetAddressError>;
+/**
+ * Creates a checked IPv6 internet address with an optional scope identifier.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const inetAddressV6: (address: Ipv6Address, port: number, options?: {
+    readonly scopeId?: number | undefined;
+}) => Result.Result<InetAddressV6, NetAddressError>;
+/**
+ * Creates a checked internet address for an IP address and port.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const inetAddress: (address: IpAddress, port: number) => Result.Result<InetAddress, NetAddressError>;
+/**
+ * Creates an internet address from a trusted IP address and port, throwing on failure.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const inetAddressUnsafe: (address: IpAddress, port: number) => InetAddress;
+/**
+ * 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.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const inetAddressFromIpString: (address: string, port: number) => Result.Result<InetAddress, NetAddressError>;
+/**
+ * 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.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const inetAddressFromIpStringUnsafe: (address: string, port: number) => InetAddress;
+/**
+ * Parses `IPv4:port` or `[IPv6]:port` without DNS resolution.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const inetAddressFromString: (input: string) => Result.Result<InetAddress, NetAddressError>;
+/**
+ * Parses a trusted numeric internet address and port, throwing on failure.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const inetAddressFromStringUnsafe: (input: string) => InetAddress;
+/**
+ * Formats a resolved internet address, bracketing IPv6 around its port.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatInet: (self: InetAddress) => string;
+/**
+ * Formats an IP address for use as a URL authority host.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatUrlHost: (self: IpAddress) => string;
+/**
+ * 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"`.
+ *
+ * @category conversions
+ * @since 4.0.0
+ */
+export declare const toUrl: (self: IpAddress | InetAddress, scheme?: string) => Result.Result<URL, NetAddressError>;
+/**
+ * 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 {@link 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.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatUrl: (self: IpAddress | SocketAddress, scheme?: string) => Result.Result<string, NetAddressError>;
+/**
+ * Formats an IP or socket address as a URL display string,
+ * throwing a `NetAddressError` when conversion fails.
+ *
+ * @see {@link formatUrl} for the checked version and formatting behavior.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const formatUrlUnsafe: (self: IpAddress | SocketAddress, scheme?: string) => string;
+/**
+ * Formats a hostname or numeric IP address for use as a URL authority host.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatUrlHostString: (host: string) => string;
+/**
+ * Creates a Unix-domain filesystem address without normalizing its opaque path.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const unixPathAddress: (path: string) => UnixPathAddress;
+/**
+ * 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.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatUnixPath: (self: UnixPathAddress) => string;
+/**
+ * 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`.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const socketAddressFromInput: (input: SocketAddress.Input) => Result.Result<SocketAddress, NetAddressError>;
+/**
+ * Converts a trusted `SocketAddress.Input` to a concrete socket address,
+ * throwing on failure.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const socketAddressFromInputUnsafe: (input: SocketAddress.Input) => SocketAddress;
+/**
+ * Formats a portable socket address for human-readable output.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const formatSocketAddress: (self: SocketAddress) => string;
+export {};
+//# sourceMappingURL=NetAddress.d.ts.map