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

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -15,7 +15,7 @@ import * as Arr from "../../Array.ts"
 import type { Brand } from "../../Brand.ts"
 import * as Context from "../../Context.ts"
 import type { Effect } from "../../Effect.ts"
-import { identity } from "../../Function.ts"
+import { identity, memoize } from "../../Function.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
@@ -23,6 +23,7 @@ import * as AST from "../../SchemaAST.ts"
 import type * as Stream from "../../Stream.ts"
 import type { Simplify } from "../../Struct.ts"
 import type * as Types from "../../Types.ts"
+import type * as Sse from "../encoding/Sse.ts"
 import type { HttpMethod } from "../http/HttpMethod.ts"
 import * as HttpRouter from "../http/HttpRouter.ts"
 import type { HttpServerRequest } from "../http/HttpServerRequest.ts"
@@ -187,6 +188,7 @@ export interface HttpApiEndpoint<
   readonly error: ReadonlySet<Schema.Top>
   readonly annotations: Context.Context<never>
   readonly middlewares: ReadonlySet<Context.Key<Middleware, any>>
+  readonly disableCodecs: boolean
 
   /**
    * Add a prefix to the path of the endpoint.
@@ -282,10 +284,11 @@ export function getSuccessSchemas(endpoint: Top): [Schema.Top, ...Array<Schema.T
 /** @internal */
 export function getErrorSchemas(endpoint: Top): Array<Schema.Top> {
   const schemas = new Set<Schema.Top>(endpoint.error)
+  const transform = endpoint.disableCodecs ? identity : transformResponseSchema
   for (const middleware of endpoint.middlewares) {
     const key = middleware as any as HttpApiMiddleware.AnyService
     for (const schema of key.error) {
-      schemas.add(schema)
+      schemas.add(transform(schema))
     }
   }
   return Array.from(schemas)
@@ -484,9 +487,10 @@ export type RequestRaw<Endpoint> = Endpoint extends ConstraintRequest ? Endpoint
   : {}
 
 /**
- * Builds the request object accepted by a generated client method, including only
- * the params, query, headers, payload, and response mode fields required by the
- * endpoint. Multipart payloads are supplied as `FormData`.
+ * Builds the request object accepted by a generated client method, including the
+ * params, query, headers, and payload required by the endpoint, plus optional
+ * response mode and SSE decoding options. Multipart payloads are supplied as
+ * `FormData`.
  *
  * @category utility types
  * @since 4.0.0
@@ -507,8 +511,14 @@ export type ClientRequest<
         ? { readonly payload: FormData }
       : { readonly payload: Payload["Type"] }
     : { readonly payload: Payload["Type"] })
-) extends infer Req ? keyof Req extends never ? (void | { readonly responseMode?: ResponseMode }) :
-  Req & { readonly responseMode?: ResponseMode } :
+) extends infer Req ? keyof Req extends never ? (void | {
+      readonly responseMode?: ResponseMode
+      readonly sseOptions?: Sse.DecodeOptions | undefined
+    }) :
+  Req & {
+    readonly responseMode?: ResponseMode
+    readonly sseOptions?: Sse.DecodeOptions | undefined
+  } :
   void
 
 /**
@@ -833,7 +843,8 @@ const optionsFromEndpoint = (endpoint: Top) => ({
   success: endpoint.success,
   error: endpoint.error,
   annotations: endpoint.annotations,
-  middlewares: endpoint.middlewares
+  middlewares: endpoint.middlewares,
+  disableCodecs: endpoint.disableCodecs
 })
 
 function makeProto<
@@ -860,6 +871,7 @@ function makeProto<
   readonly error: ReadonlySet<Schema.Top>
   readonly annotations: Context.Context<never>
   readonly middlewares: ReadonlySet<Context.Key<Middleware, any>>
+  readonly disableCodecs: boolean
 }): HttpApiEndpoint<
   Identifier,
   Method,
@@ -1090,7 +1102,8 @@ export const make = <Method extends HttpMethod>(method: Method): {
     success: getSuccessResponse(options?.success, method, disableCodecs),
     error: getErrorResponse(options?.error, disableCodecs),
     annotations: Context.empty(),
-    middlewares: new Set()
+    middlewares: new Set(),
+    disableCodecs
   })
 }
 
@@ -1157,7 +1170,7 @@ function getSuccessResponse(
   return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
 }
 
-function transformResponseSchema(schema: Schema.Top): Schema.Top {
+const transformResponseSchema = memoize((schema: Schema.Top): Schema.Top => {
   if (HttpApiSchema.isStreamSchema(schema)) return schema
   if (HttpApiSchema.isWithHeaders(schema)) {
     const inner = HttpApiSchema.isStreamSchema(schema.schema)
@@ -1166,7 +1179,7 @@ function transformResponseSchema(schema: Schema.Top): Schema.Top {
     return HttpApiSchema.rebuildWithHeaders(schema, inner, Schema.toCodecStringTree(schema.headers))
   }
   return transformResponse(schema)
-}
+})
 
 function getErrorResponse(
   error: Schema.Top | ReadonlyArray<Schema.Top> | undefined,

package/src/unstable/httpapi/HttpApiError.ts

@@ -458,7 +458,9 @@ export class HttpApiSchemaError extends Data.TaggedClass("HttpApiSchemaError")<{
     kind: HttpApiSchemaError["kind"],
     effect: Effect.Effect<A, Schema.SchemaError, R>
   ): Effect.Effect<A, HttpApiSchemaError, R> {
-    return Effect.mapError(effect, (error) => new HttpApiSchemaError({ kind, cause: error }))
+    // Decoders return completed Exit values for synchronous results, so map
+    // eagerly and skip the error wrapper when nothing remains to run.
+    return Effect.mapErrorEager(effect, (error) => new HttpApiSchemaError({ kind, cause: error }))
   }
 
   readonly name = "HttpApiSchemaError"

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -352,17 +352,19 @@ export const Service = <
     readonly requiredForClient?: boolean | undefined
   } | undefined
 ) => {
-  const Err = globalThis.Error as any
   const limit = getStackTraceLimit()
-  setStackTraceLimit(2)
-  const creationError = new Err()
-  setStackTraceLimit(limit)
+  let creationError: globalThis.Error | undefined
+  if (limit !== 0) {
+    setStackTraceLimit(2)
+    creationError = new globalThis.Error()
+    setStackTraceLimit(limit)
+  }
 
   class Service extends Context.Service<Self, any>()(id) {}
   const self = Service as any
   Object.defineProperty(Service, "stack", {
     get() {
-      return creationError.stack
+      return creationError?.stack
     }
   })
   self[TypeId] = TypeId

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -518,6 +518,8 @@ export interface WithHeaders<S extends Schema.Top, H extends Schema.Top> extends
  * The Type of a `WithHeaders` schema: what handlers return and what the
  * client resolves to, constructed via {@link withHeaders}.
  *
+ * **Details**
+ *
  * `body` is the inner success value. For stream success schemas it is the
  * `Stream` itself, so headers are decided before the body starts streaming.
  *
@@ -539,9 +541,13 @@ const withHeadersValueSchema = Schema.declare(isWithHeadersValue)
 /**
  * Wraps a success schema with a response headers schema.
  *
+ * **Details**
+ *
  * Headers accept either a schema or a fields shorthand, mirroring the
  * request-side headers option.
  *
+ * **Example** (Adding response headers to a success schema)
+ *
  * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { HttpApiSchema } from "effect/unstable/httpapi"
@@ -587,6 +593,8 @@ export function WithHeaders(
 /**
  * Constructs a `WithHeaders` response value from a body and headers.
  *
+ * **Details**
+ *
  * The returned value is branded so servers and clients can detect it exactly,
  * including in mixed success unions. The same shape is used on both sides: a
  * value received from a client can be returned from another handler unchanged.
@@ -609,6 +617,8 @@ export const withHeaders = <A, H>(options: {
 /**
  * Returns `true` when a schema is a `WithHeaders` response schema.
  *
+ * **Example** (Detecting a response headers schema)
+ *
  * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { HttpApiSchema } from "effect/unstable/httpapi"
@@ -679,6 +689,8 @@ export interface encodeToWithHeaders<
  * defects on the client. Stream responses should use {@link WithHeaders},
  * which preserves the body stream's error channel in the generated client.
  *
+ * **Example** (Encoding an error with headers)
+ *
  * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { HttpApiSchema } from "effect/unstable/httpapi"
@@ -739,8 +751,8 @@ export function encodeToWithHeaders<
       )
     ).annotate({
       "~httpApiWithHeaders": { body, headers, headersCodec: Schema.toEncoded(headers) },
-      ...(status !== undefined ? { httpApiStatus: status } : undefined),
-      ...(encoding !== undefined ? { "~httpApiEncoding": encoding } : undefined)
+      httpApiStatus: status,
+      "~httpApiEncoding": encoding
     })
   }
 }
@@ -1000,11 +1012,6 @@ export function getResponseEncodingSchema(schema: Schema.Constraint): ResponseEn
   return getResponseEncoding(schema.ast)
 }
 
-/** @internal */
-export function getStatusStream(self: StreamSchema): number {
-  return getStatusSuccess(self.ast)
-}
-
 /** @internal */
 export function getStatusError(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 500

package/src/unstable/httpapi/HttpApiTest.ts

@@ -20,6 +20,7 @@ import type { HttpPlatform } from "../http/HttpPlatform.ts"
 import * as HttpRouter from "../http/HttpRouter.ts"
 import * as HttpServerRequest from "../http/HttpServerRequest.ts"
 import * as HttpServerResponse from "../http/HttpServerResponse.ts"
+import * as preResponseHandler from "../http/internal/preResponseHandler.ts"
 import type * as HttpApi from "./HttpApi.ts"
 import type { HandlerRuntime } from "./HttpApiBuilder.ts"
 import * as HttpApiBuilder from "./HttpApiBuilder.ts"
@@ -100,10 +101,14 @@ export const groups = Effect.fnUntraced(function*<
   const httpClient = HttpClient.make(Effect.fnUntraced(function*(request) {
     const serverRequest = HttpServerRequest.fromClientRequest(request)
     const response = yield* handler.pipe(
+      Effect.flatMap((response) => {
+        const preResponse = preResponseHandler.requestPreResponseHandlers.get(serverRequest.source)
+        return preResponse === undefined ? Effect.succeed(response) : preResponse(serverRequest, response)
+      }),
       Effect.provideService(HttpServerRequest.HttpServerRequest, serverRequest),
       Effect.orDie
     )
-    return HttpServerResponse.toClientResponse(response)
+    return HttpServerResponse.toClientResponse(response, { request })
   }, Effect.scoped))
 
   return yield* HttpApiClient.makeWith(api, {

package/src/unstable/httpapi/OpenApi.ts

@@ -14,6 +14,7 @@ import * as Context from "../../Context.ts"
 import * as Equal from "../../Equal.ts"
 import { constFalse } from "../../Function.ts"
 import * as InternalRecord from "../../internal/record.ts"
+import * as InternalToCodec from "../../internal/schema/toCodec.ts"
 import * as InternalToJsonSchemaDocument from "../../internal/schema/toJsonSchemaDocument.ts"
 import * as InternalToRepresentation from "../../internal/schema/toRepresentation.ts"
 import * as JsonPatch from "../../JsonPatch.ts"
@@ -328,6 +329,7 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
   > = []
   const pathOperations = new Set<string>()
   const operationIds = new Set<string>()
+  const finalizeOperations: Array<() => void> = []
 
   processAnnotation(api.annotations, Title, (title) => {
     spec.info.title = title
@@ -378,7 +380,7 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
       if (Context.get(mergedAnnotations, Exclude)) {
         return
       }
-      let op: OpenAPISpecOperation = {
+      const op: OpenAPISpecOperation = {
         tags: [Context.getOrElse(group.annotations, Title, () => group.identifier)],
         operationId: Context.getOrElse(
           endpoint.annotations,
@@ -422,7 +424,7 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
             content.forEach((map, encoding) => {
               map.forEach((schemas, contentType) => {
                 const asts = Array.from(schemas, SchemaAST.getAST)
-                const ast = asts.length === 1 ? asts[0] : new SchemaAST.Union(asts, "anyOf")
+                const ast = asts.length === 1 ? asts[0] : new SchemaAST.Union(asts)
 
                 pathOps.push({
                   _tag: "schema",
@@ -583,7 +585,7 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
           const content: OpenApiSpecContent = {}
           for (const [contentType, { encoding, schemas }] of schemasByContentType) {
             const asts = schemas.map(SchemaAST.getAST)
-            const ast = asts.length === 1 ? asts[0] : new SchemaAST.Union(asts, "anyOf")
+            const ast = asts.length === 1 ? asts[0] : new SchemaAST.Union(asts)
             pathOps.push({
               _tag: "schema",
               ast: toEncodingAST(ast, encoding._tag),
@@ -618,32 +620,35 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
         () => "Error"
       )
 
-      processAnnotation(endpoint.annotations, Override, (override) => {
-        // OpenAPI documents are JSON, so symbol keys are intentionally ignored.
-        for (const [key, value] of Object.entries(override)) {
-          InternalRecord.assignProperty(op as any, key, value)
-        }
-      })
-      processAnnotation(endpoint.annotations, Transform, (transformFn) => {
-        op = transformFn(op) as OpenAPISpecOperation
-      })
-
       const pathOperation = `${method} ${path.replace(/\{[^}]+\}/g, "{}")}`
       if (pathOperations.has(pathOperation)) {
         throw new globalThis.Error(`Duplicate OpenAPI operation for ${endpoint.method} ${path}`)
       }
-      const operationId = op.operationId
-      if (operationId !== undefined) {
-        if (operationIds.has(operationId)) {
-          throw new globalThis.Error(`Duplicate OpenAPI operationId: ${operationId}`)
-        }
-        operationIds.add(operationId)
-      }
       pathOperations.add(pathOperation)
       if (!Object.hasOwn(spec.paths, path)) {
         InternalRecord.assignProperty(spec.paths, path, {})
       }
       spec.paths[path][method] = op
+      finalizeOperations.push(() => {
+        let op = spec.paths[path][method]!
+        processAnnotation(endpoint.annotations, Override, (override) => {
+          // OpenAPI documents are JSON, so symbol keys are intentionally ignored.
+          for (const [key, value] of Object.entries(override)) {
+            InternalRecord.assignProperty(op as any, key, value)
+          }
+        })
+        processAnnotation(endpoint.annotations, Transform, (transformFn) => {
+          op = transformFn(op) as OpenAPISpecOperation
+        })
+        const operationId = op.operationId
+        if (operationId !== undefined) {
+          if (operationIds.has(operationId)) {
+            throw new globalThis.Error(`Duplicate OpenAPI operationId: ${operationId}`)
+          }
+          operationIds.add(operationId)
+        }
+        spec.paths[path][method] = op
+      })
     }
   })
 
@@ -672,9 +677,10 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
     const jsonSchemaMultiDocument = JsonSchema.toMultiDocumentOpenApi3_1(
       InternalToJsonSchemaDocument.toJsonSchemaMultiDocument(
         InternalToRepresentation.toRepresentations(
-          Arr.map(pathOps, (op) => Schema.toCodecJsonAST(op.ast)),
+          Arr.map(pathOps, (op) => InternalToCodec.toCodecJsonAST(op.ast)),
           options
-        )
+        ),
+        { onExcessProperty: "error" }
       )
     )
     const patchOps: Array<JsonPatch.JsonPatchOperation> = pathOps.map((op, i) => {
@@ -698,6 +704,10 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
     spec = JsonPatch.apply(patchOps, spec as any) as any
   }
 
+  for (const finalize of finalizeOperations) {
+    finalize()
+  }
+
   Object.keys(spec.components.schemas).forEach((key) => {
     if (!JsonSchema.VALID_OPEN_API_COMPONENTS_SCHEMAS_KEY_REGEXP.test(key)) {
       throw new globalThis.Error(`Invalid component schema key: ${key}`)

package/src/unstable/net/IpInterface.ts

@@ -0,0 +1,242 @@
+/**
+ * IPv4 and IPv6 interface addresses that preserve host bits alongside a prefix length.
+ *
+ * @since 4.0.0
+ */
+import * as Equal from "../../Equal.ts"
+import * as Hash from "../../Hash.ts"
+import { NodeInspectSymbol } from "../../Inspectable.ts"
+import { hasProperty } from "../../Predicate.ts"
+import * as Result from "../../Result.ts"
+import * as NetAddress from "./NetAddress.ts"
+
+const TypeId = "~effect/net/IpInterface" as const
+
+/**
+ * An IP host address and prefix length. Host bits are preserved.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface IpInterface<out A extends NetAddress.IpAddress = NetAddress.IpAddress> extends Equal.Equal, Hash.Hash {
+  readonly _tag: "IpInterface"
+  readonly address: A
+  readonly prefixLength: number
+  readonly [TypeId]: typeof TypeId
+  toString(): string
+  toJSON(): string
+}
+
+/**
+ * An IPv4 host address and prefix length.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Ipv4Interface = IpInterface<NetAddress.Ipv4Address>
+
+/**
+ * An IPv6 host address and prefix length.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Ipv6Interface = IpInterface<NetAddress.Ipv6Address>
+
+/**
+ * Companion types for parsing IP interface addresses.
+ *
+ * @since 4.0.0
+ */
+export declare namespace IpInterface {
+  /**
+   * Controls whether the input must contain an explicit prefix. Prefixes are
+   * optional by default and use the address width when omitted.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface ParseOptions {
+    readonly prefix?: "required" | "optional"
+  }
+}
+
+/**
+ * Returns `true` when a value is an IPv4 interface address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isIpv4Interface = (u: unknown): u is Ipv4Interface =>
+  isIpInterface(u) && NetAddress.isIpv4Address(u.address)
+
+/**
+ * Returns `true` when a value is an IPv6 interface address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isIpv6Interface = (u: unknown): u is Ipv6Interface =>
+  isIpInterface(u) && NetAddress.isIpv6Address(u.address)
+
+/**
+ * Returns `true` when a value is an IP interface address.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isIpInterface = (u: unknown): u is IpInterface => hasProperty(u, TypeId)
+
+const IpInterfaceProto = {
+  _tag: "IpInterface",
+  [TypeId]: TypeId,
+  [Equal.symbol](this: IpInterface, that: Equal.Equal): boolean {
+    return isIpInterface(that) &&
+      this.prefixLength === that.prefixLength &&
+      Equal.equals(this.address, that.address)
+  },
+  [Hash.symbol](this: IpInterface): number {
+    return Hash.combine(Hash.hash(this.address), Hash.number(this.prefixLength))
+  },
+  toString(this: IpInterface): string {
+    return format(this)
+  },
+  toJSON(this: IpInterface): string {
+    return this.toString()
+  },
+  [NodeInspectSymbol](this: IpInterface): string {
+    return this.toJSON()
+  }
+}
+
+const interfaceError = (input: unknown, message: string): Result.Result<never, NetAddress.NetAddressError> =>
+  Result.fail(new NetAddress.NetAddressError({ input, message }))
+
+/**
+ * Creates an interface address while preserving all address bits.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = <A extends NetAddress.IpAddress>(
+  address: A,
+  prefixLength: number
+): Result.Result<IpInterface<A>, NetAddress.NetAddressError> => {
+  const max = NetAddress.width(address)
+  if (!Number.isInteger(prefixLength) || prefixLength < 0 || prefixLength > max) {
+    return interfaceError(address, `prefix length must be an integer from 0 through ${max}`)
+  }
+  const self = Object.assign(Object.create(IpInterfaceProto), { address, prefixLength })
+  return Result.succeed(Object.freeze(self))
+}
+
+const parseAddressWithPrefix = (
+  input: string,
+  options?: IpInterface.ParseOptions
+): Result.Result<
+  { readonly address: string; readonly prefixLength: number | undefined },
+  NetAddress.NetAddressError
+> => {
+  const slash = input.indexOf("/")
+  if (slash === -1 && options?.prefix !== "required") {
+    return Result.succeed({ address: input, prefixLength: undefined })
+  }
+  if (slash <= 0 || slash !== input.lastIndexOf("/") || slash === input.length - 1) {
+    return interfaceError(input, "expected an address and prefix length separated by one slash")
+  }
+  const prefix = input.slice(slash + 1)
+  if (!/^(0|[1-9][0-9]*)$/.test(prefix)) {
+    return interfaceError(input, "prefix length must be an unpadded ASCII decimal integer")
+  }
+  return Result.succeed({ address: input.slice(0, slash), prefixLength: Number(prefix) })
+}
+
+/**
+ * Parses an IPv4 interface address while preserving host bits.
+ *
+ * **Details**
+ *
+ * A missing prefix defaults to 32. Use `prefix: "required"` to require one.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export const ipv4FromString = (
+  input: string,
+  options?: IpInterface.ParseOptions
+): Result.Result<Ipv4Interface, NetAddress.NetAddressError> =>
+  Result.flatMap(
+    parseAddressWithPrefix(input, options),
+    (parts) =>
+      Result.flatMap(NetAddress.ipv4FromString(parts.address), (address) =>
+        make(address, parts.prefixLength ?? NetAddress.width(address)))
+  )
+
+/**
+ * Parses an IPv6 interface address while preserving host bits.
+ *
+ * **Details**
+ *
+ * A missing prefix defaults to 128. Use `prefix: "required"` to require one.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export const ipv6FromString = (
+  input: string,
+  options?: IpInterface.ParseOptions
+): Result.Result<Ipv6Interface, NetAddress.NetAddressError> =>
+  Result.flatMap(
+    parseAddressWithPrefix(input, options),
+    (parts) =>
+      Result.flatMap(NetAddress.ipv6FromString(parts.address), (address) =>
+        make(address, parts.prefixLength ?? NetAddress.width(address)))
+  )
+
+/**
+ * Parses an IP interface address while preserving host bits.
+ *
+ * **Details**
+ *
+ * A missing prefix defaults to the address width. Use `prefix: "required"` to
+ * require one.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export const fromString = (
+  input: string,
+  options?: IpInterface.ParseOptions
+): Result.Result<IpInterface, NetAddress.NetAddressError> =>
+  Result.flatMap(
+    parseAddressWithPrefix(input, options),
+    (parts) =>
+      Result.flatMap(NetAddress.ipFromString(parts.address), (address) =>
+        make(address, parts.prefixLength ?? NetAddress.width(address)))
+  )
+
+/**
+ * Creates a trusted interface address, throwing when its prefix length is invalid.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export const makeUnsafe = <A extends NetAddress.IpAddress>(address: A, prefixLength: number): IpInterface<A> =>
+  Result.getOrThrow(make(address, prefixLength))
+
+/**
+ * Parses a trusted interface address, throwing on failure.
+ *
+ * @category unsafe
+ * @since 4.0.0
+ */
+export const fromStringUnsafe = (input: string, options?: IpInterface.ParseOptions): IpInterface =>
+  Result.getOrThrow(fromString(input, options))
+
+/**
+ * Formats an interface address using canonical address text and its decimal prefix length.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export const format = (self: IpInterface): string => `${NetAddress.formatIp(self.address)}/${self.prefixLength}`