glip

//// Glip provides a standard representation for IP addresses
//// on Gleam for Erlang and node/bun on JavaScript.
//// The intent is to have a minimal representation in memory,
//// and avoid unnecessary conversions for common operations.
//// Glip is designed for server-oriented usage,
//// which is why it doesn't have a browser-compatible implementation,
//// and only wraps functionality in the runtimes.
//// (Feel free to open an issue if you have a valid browser use case).

pub type AddressFamily {
  Ipv4
  Ipv6
}

/// An IP address to be passed to external functions.
/// NOTE: You can return IpAddress directly from external functions,
/// as long as they follow the correct types, which are
/// `inet:ip_address()` on Erlang and `String` on JavaScript.
/// Note that the external function is responsible for 
/// the string being a valid IP address on JavaScript!
pub type ExternalIpAddress

/// An IP address that has been validated
/// and may contain extra information: 
/// a string representation on Erlang, address family on JS.
/// This type can be directly returned from external functions,
/// as long as they follow the same type rules as `ExternalIpAddress`.
pub type IpAddress

/// Tries to parse an IP address from a string.
/// In IPv4, leading zeros or short forms are not allowed.
/// This is in order to keep the behavior constant across targets.
@external(erlang, "glip_ffi", "parse_ip")
@external(javascript, "./glip_ffi.mjs", "parse_ip")
pub fn parse_ip(address: String) -> Result(IpAddress, Nil)

/// Tires to parse an IP address from a string,
/// and on Erlang, preserves the original format.
/// This will also be more efficient if the IP needs to be
/// represented as a string often on Erlang.
/// On JavaScript, this is equivalent to `parse_ip`.
@external(erlang, "glip_ffi", "parse_ip_preserving_string")
@external(javascript, "./glip_ffi.mjs", "parse_ip")
pub fn parse_ip_preserving_string(address: String) -> Result(IpAddress, Nil)

/// Gets the target-specific external representation of an IP address.
@external(erlang, "glip_ffi", "to_external_ip")
@external(javascript, "./glip_ffi.mjs", "to_string")
pub fn to_external_ip(ip: IpAddress) -> ExternalIpAddress

/// Gets the address family of an IP address.
@external(erlang, "glip_ffi", "address_family")
@external(javascript, "./glip_ffi.mjs", "address_family")
pub fn address_family(ip: IpAddress) -> AddressFamily

/// Converts an IP address to a string.
@external(erlang, "glip_ffi", "to_string")
@external(javascript, "./glip_ffi.mjs", "to_string")
pub fn ip_to_string(ip: IpAddress) -> String

/// Adds missing information to partial representations for repeated access.
/// On Erlang, fills in the string for addresses coming from external functions or `prase_ip`.
/// One JavaScript, resolves the address family for addresses returned from external functions.
/// If no information is missing, does nothing.
@external(erlang, "glip_ffi", "enrich")
@external(javascript, "./glip_ffi.mjs", "enrich")
pub fn enrich(ip: IpAddress) -> IpAddress