effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -125,7 +125,7 @@ export interface HttpApiMiddlewareClient<_E, CE, R> {
 /**
  * Client-side service marker required when a middleware declares `requiredForClient`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface ForClient<Id> {
@@ -136,7 +136,7 @@ export interface ForClient<Id> {
 /**
  * Base service key shape for HTTP API middleware services, including provided services, declared error schemas, and client requirements.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AnyService extends Context.Key<any, any> {
@@ -150,7 +150,7 @@ export interface AnyService extends Context.Key<any, any> {
 /**
  * Middleware service key shape for security middleware, including the security schemes handled by the service.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AnyServiceSecurity extends AnyService {
@@ -161,7 +161,7 @@ export interface AnyServiceSecurity extends AnyService {
 /**
  * Type-level identifier carried by middleware services to track provided services, required services, errors, client errors, and client requirements.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface AnyId {
@@ -177,7 +177,7 @@ export interface AnyId {
 /**
  * Extracts the services provided by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: infer P } } ? P : never
@@ -185,7 +185,7 @@ export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: in
 /**
  * Extracts the services required to run a middleware implementation.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: infer R } } ? R : never
@@ -193,7 +193,7 @@ export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: in
 /**
  * Applies a middleware's service changes to an existing requirement type by removing services it provides and adding services it requires.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requires<A>
@@ -201,7 +201,7 @@ export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requir
 /**
  * Extracts the schema or schema union used for errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: infer E } } ? ErrorSchemaFromConstraint<E>
@@ -210,7 +210,7 @@ export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: in
 /**
  * Extracts the decoded error type declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Error<A> = ErrorSchema<A>["Type"]
@@ -218,7 +218,7 @@ export type Error<A> = ErrorSchema<A>["Type"]
 /**
  * Extracts the client-side error type for middleware that is required on generated clients.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ClientError<A> = A extends {
@@ -232,7 +232,7 @@ export type ClientError<A> = A extends {
 /**
  * Computes the client-side service marker required for middleware that must also run in generated clients.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareClient<A> = A extends {
@@ -245,7 +245,7 @@ export type MiddlewareClient<A> = A extends {
 /**
  * Extracts the schema services required to encode errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
@@ -253,7 +253,7 @@ export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
 /**
  * Extracts the schema services required to decode errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
@@ -266,7 +266,7 @@ export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
  * It combines a `Context.Service` class with the middleware metadata used by
  * endpoints, builders, and generated clients.
  *
- * @category schemas
+ * @category services
  * @since 4.0.0
  */
 export type ServiceClass<
@@ -314,7 +314,7 @@ export type ServiceClass<
  * required services, provided services, typed error schemas, security schemes,
  * client errors, or a matching client middleware requirement.
  *
- * @category schemas
+ * @category constructors
  * @since 4.0.0
  */
 export const Service = <
@@ -394,26 +394,73 @@ function getError(error: ErrorConstraint | undefined): ReadonlySet<Schema.Top> {
  *
  * **Example** (Mapping schema errors to custom errors)
  *
- * ```ts
- * import { Effect, Schema } from "effect"
- * import { HttpApiMiddleware } from "effect/unstable/httpapi"
+ * ```ts import.meta.vitest
+ * import { Effect, Schema, type Types } from "effect"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
+ * import {
+ *   HttpApiEndpoint,
+ *   HttpApiError,
+ *   HttpApiGroup,
+ *   HttpApiMiddleware
+ * } from "effect/unstable/httpapi"
  *
- * export class CustomError extends Schema.TaggedErrorClass<CustomError>()("CustomError", {}) {}
+ * class CustomError extends Schema.TaggedErrorClass<CustomError>()("CustomError", {}) {}
  *
- * export class ErrorHandler extends HttpApiMiddleware.Service<ErrorHandler>()("api/ErrorHandler", {
+ * class ErrorHandler extends HttpApiMiddleware.Service<ErrorHandler>()("api/ErrorHandler", {
  *   error: CustomError
  * }) {}
  *
- * export const ErrorHandlerLayer = HttpApiMiddleware.layerSchemaErrorTransform(
+ * const messages: Array<string> = []
+ * const ErrorHandlerLayer = HttpApiMiddleware.layerSchemaErrorTransform(
  *   ErrorHandler,
  *   (schemaError) =>
- *     Effect.log("Got SchemaError", schemaError).pipe(
+ *     Effect.sync(() => messages.push(`Mapping ${schemaError.kind} schema error`)).pipe(
  *       Effect.andThen(Effect.fail(new CustomError()))
  *     )
  * )
+ *
+ * const endpoint = HttpApiEndpoint.get("example", "/")
+ * const group = HttpApiGroup.make("examples").add(endpoint)
+ * const middlewareContext = {
+ *   endpoint: endpoint as unknown as HttpApiEndpoint.Top,
+ *   group: group as unknown as HttpApiGroup.Top
+ * }
+ * const Routes = HttpRouter.add(
+ *   "GET",
+ *   "/",
+ *   Effect.gen(function*() {
+ *     const applySchemaErrorTransform = yield* ErrorHandler
+ *     const schemaError = yield* HttpApiError.HttpApiSchemaError.wrap(
+ *       "Body",
+ *       Schema.decodeUnknownEffect(Schema.String)(42)
+ *     ).pipe(Effect.flip)
+ *     const failingResponse = Effect.fail(schemaError as unknown as Types.unhandled)
+ *     const result = yield* applySchemaErrorTransform(failingResponse, middlewareContext).pipe(
+ *       Effect.match({
+ *         onFailure: (error) => error instanceof CustomError ? error._tag : "UnexpectedError",
+ *         onSuccess: () => "Success"
+ *       })
+ *     )
+ *     return HttpServerResponse.text(result)
+ *   })
+ * ).pipe(HttpRouter.provideRequest(ErrorHandlerLayer))
+ *
+ * const program = Effect.acquireUseRelease(
+ *   Effect.sync(() => HttpRouter.toWebHandler(Routes, { disableLogger: true })),
+ *   ({ handler }) =>
+ *     Effect.gen(function*() {
+ *       const response = yield* Effect.promise(() => handler(new Request("http://localhost/")))
+ *       const body = yield* Effect.promise(() => response.text())
+ *       return body
+ *     }),
+ *   ({ dispose }) => Effect.promise(dispose)
+ * )
+ *
+ * const body = await Effect.runPromise(program)
+ * const result = [messages, body] // => [["Mapping Body schema error"], "CustomError"]
  * ```
  *
- * @category SchemaError transform
+ * @category layers
  * @since 4.0.0
  */
 export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Requires>(
@@ -451,7 +498,7 @@ export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Require
  * The layer captures the surrounding services and makes the middleware available
  * through the `ForClient` service marker used by HTTP API clients.
  *
- * @category client
+ * @category layers
  * @since 4.0.0
  */
 export const layerClient = <Id extends AnyId, S, R, EX = never, RX = never>(

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -87,12 +87,6 @@ export type ScalarConfig = {
   /**
    * Path to a favicon image.
    *
-   * **Example** (Setting a relative favicon)
-   *
-   * ```ts
-   * const favicon = "/favicon.svg"
-   * ```
-   *
    * @default undefined
    */
   favicon?: string
@@ -107,12 +101,6 @@ export type ScalarConfig = {
    * Browsers can derive the origin from `window.location.origin`; server
    * rendering needs this value supplied explicitly.
    *
-   * **Example** (Setting a local server URL)
-   *
-   * ```ts
-   * const baseServerURL = "http://localhost:3000"
-   * ```
-   *
    * @default undefined
    */
   baseServerURL?: string

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -140,7 +140,7 @@ const StreamSchemaTypeId = "~effect/httpapi/HttpApiSchema/Stream"
 /**
  * Common HTTP status code literals accepted by {@link status}.
  *
- * @category status
+ * @category models
  * @since 4.0.0
  */
 export type StatusLiteral = keyof typeof statusCodeByLiteral
@@ -154,7 +154,7 @@ export type StatusLiteral = keyof typeof statusCodeByLiteral
  * schema. You can pass either a numeric status code (for example, `201`) or a
  * common literal name (for example, `"Created"`).
  *
- * @category status
+ * @category schemas
  * @since 4.0.0
  */
 export function status(code: number): {
@@ -174,7 +174,7 @@ export function status(code: number | StatusLiteral) {
  *
  * @see {@link NoContent} for the predefined 204 no content schema.
  *
- * @category Empty
+ * @category constructors
  * @since 4.0.0
  */
 export const Empty = (code: number): Schema.Void => Schema.Void.pipe(status(code))
@@ -190,7 +190,7 @@ export interface NoContent extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 204.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const NoContent: NoContent = Empty(204)
@@ -206,7 +206,7 @@ export interface Created extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 201.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const Created: Created = Empty(201)
@@ -222,7 +222,7 @@ export interface Accepted extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 202.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const Accepted: Accepted = Empty(202)

package/src/unstable/httpapi/OpenApi.ts

@@ -33,7 +33,7 @@ import type { HttpApiSecurity } from "./HttpApiSecurity.ts"
 /**
  * OpenAPI annotation for overriding generated identifiers, including operation ids.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Identifier extends Context.Service<Identifier, string>()("effect/httpapi/OpenApi/Identifier") {}
@@ -41,7 +41,7 @@ export class Identifier extends Context.Service<Identifier, string>()("effect/ht
 /**
  * OpenAPI annotation for setting the API title or group tag name.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Title extends Context.Service<Title, string>()("effect/httpapi/OpenApi/Title") {}
@@ -49,7 +49,7 @@ export class Title extends Context.Service<Title, string>()("effect/httpapi/Open
 /**
  * OpenAPI annotation for setting the generated API version.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Version extends Context.Service<Version, string>()("effect/httpapi/OpenApi/Version") {}
@@ -57,7 +57,7 @@ export class Version extends Context.Service<Version, string>()("effect/httpapi/
 /**
  * OpenAPI annotation for setting generated descriptions on APIs, groups, endpoints, or security schemes.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Description extends Context.Service<Description, string>()("effect/httpapi/OpenApi/Description") {}
@@ -65,7 +65,7 @@ export class Description extends Context.Service<Description, string>()("effect/
 /**
  * OpenAPI annotation for setting the generated API license metadata.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class License extends Context.Service<License, OpenAPISpecLicense>()("effect/httpapi/OpenApi/License") {}
@@ -73,7 +73,7 @@ export class License extends Context.Service<License, OpenAPISpecLicense>()("eff
 /**
  * OpenAPI annotation for adding external documentation metadata to groups or endpoints.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class ExternalDocs
@@ -83,7 +83,7 @@ export class ExternalDocs
 /**
  * OpenAPI annotation for setting the generated API server list.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Servers
@@ -93,7 +93,7 @@ export class Servers
 /**
  * OpenAPI annotation for setting the format metadata, such as a bearer token format on security schemes.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Format extends Context.Service<Format, string>()("effect/httpapi/OpenApi/Format") {}
@@ -101,7 +101,7 @@ export class Format extends Context.Service<Format, string>()("effect/httpapi/Op
 /**
  * OpenAPI annotation for setting generated summary text.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Summary extends Context.Service<Summary, string>()("effect/httpapi/OpenApi/Summary") {}
@@ -109,7 +109,7 @@ export class Summary extends Context.Service<Summary, string>()("effect/httpapi/
 /**
  * OpenAPI annotation for marking a generated endpoint operation as deprecated.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Deprecated extends Context.Service<Deprecated, boolean>()("effect/httpapi/OpenApi/Deprecated") {}
@@ -117,7 +117,7 @@ export class Deprecated extends Context.Service<Deprecated, boolean>()("effect/h
 /**
  * OpenAPI annotation for shallowly merging additional fields into a generated OpenAPI object.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Override extends Context.Service<Override, Record<string, unknown>>()("effect/httpapi/OpenApi/Override") {}
@@ -131,7 +131,7 @@ export class Override extends Context.Service<Override, Record<string, unknown>>
  * Use to hide internal, experimental, or otherwise undocumented HTTP API groups
  * and endpoints from generated OpenAPI output.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Exclude = Context.Reference<boolean>("effect/httpapi/OpenApi/Exclude", {
@@ -146,7 +146,7 @@ export const Exclude = Context.Reference<boolean>("effect/httpapi/OpenApi/Exclud
  * The function is applied during generation to the annotated API, group tag, or
  * endpoint operation.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Transform extends Context.Service<

package/src/unstable/observability/OtlpExporter.ts

@@ -26,6 +26,24 @@ import * as HttpClientError from "../../unstable/http/HttpClientError.ts"
 import * as HttpClientRequest from "../../unstable/http/HttpClientRequest.ts"
 import type { HttpBody } from "../http/HttpBody.ts"
 
+const retryAfterDelay = (value: string | undefined): Effect.Effect<Duration.Duration> => {
+  const seconds = Option.fromUndefinedOr(value).pipe(Option.flatMap(Num.parse))
+  if (Option.isSome(seconds)) {
+    return Effect.succeed(Duration.seconds(seconds.value))
+  }
+  if (value === undefined) {
+    return Effect.succeed(Duration.seconds(5))
+  }
+  const timestamp = Date.parse(value)
+  if (Number.isNaN(timestamp)) {
+    return Effect.succeed(Duration.seconds(5))
+  }
+  return Effect.map(
+    Clock,
+    (clock) => Duration.millis(Math.max(timestamp - clock.currentTimeMillisUnsafe(), 1))
+  )
+}
+
 const policy = Schedule.forever.pipe(
   Schedule.passthrough,
   Schedule.addDelay(({ output: error }) => {
@@ -34,11 +52,7 @@ const policy = Schedule.forever.pipe(
       && error.reason._tag === "StatusCodeError"
       && error.reason.response.status === 429
     ) {
-      const retryAfter = Option.fromUndefinedOr(error.reason.response.headers["retry-after"]).pipe(
-        Option.flatMap(Num.parse),
-        Option.getOrElse(() => 5)
-      )
-      return Effect.succeed(Duration.seconds(retryAfter))
+      return retryAfterDelay(error.reason.response.headers["retry-after"])
     }
     return Effect.succeed(Duration.seconds(1))
   })
@@ -56,7 +70,7 @@ const policy = Schedule.forever.pipe(
  * exporter's temporary-disable window. Wrap it with `Effect.timeoutOption` to
  * bound its duration at the call site.
  *
- * @category flushing
+ * @category services
  * @since 4.0.0
  */
 export class Flusher extends Context.Service<Flusher, {
@@ -68,21 +82,19 @@ export class Flusher extends Context.Service<Flusher, {
    * There is no built-in timeout; use `Effect.timeoutOption` to bound the
    * operation. Exporters in their 60-second `disabledUntil` window are skipped.
    *
-   * **Example** (Flushing from a Cloudflare Worker)
+   * **Example** (Flushing exporters)
    *
-   * ```ts
-   * import { Effect, ManagedRuntime } from "effect"
-   * import { OtlpExporter, OtlpTracer } from "effect/unstable/observability"
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   * import { OtlpExporter } from "effect/unstable/observability"
    *
-   * const layer = OtlpTracer.layerFromConfig()
-   * const runtime = ManagedRuntime.make(layer)
+   * const program = Effect.gen(function*() {
+   *   const flusher = yield* OtlpExporter.Flusher
+   *   yield* flusher.flush
+   *   return "flushed"
+   * }).pipe(Effect.provide(OtlpExporter.layerFlusher))
    *
-   * // In the request handler:
-   * ctx.waitUntil(
-   *   runtime.runPromise(
-   *     Effect.flatMap(OtlpExporter.Flusher, (flusher) => flusher.flush)
-   *   )
-   * )
+   * await Effect.runPromise(program) // => "flushed"
    * ```
    */
   readonly flush: Effect.Effect<void>
@@ -109,7 +121,7 @@ export class Flusher extends Context.Service<Flusher, {
  * was called (for example one started by the export interval); it only waits
  * for the exports it initiates.
  *
- * @category flushing
+ * @category layers
  * @since 4.0.0
  */
 export const layerFlusher: Layer.Layer<Flusher> = Layer.sync(Flusher, () => {

package/src/unstable/observability/OtlpMetrics.ts

@@ -40,7 +40,8 @@ import { OtlpSerialization } from "./OtlpSerialization.ts"
  *
  * **Example** (Configuring aggregation temporality)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Layer } from "effect"
  * import { OtlpMetrics } from "effect/unstable/observability"
  *
  * // Use delta temporality for backends that prefer it (e.g., Datadog, Dynatrace)
@@ -54,6 +55,8 @@ import { OtlpSerialization } from "./OtlpSerialization.ts"
  *   url: "http://localhost:4318/v1/metrics",
  *   temporality: "cumulative" // This is the default
  * })
+ *
+ * const result = [Layer.isLayer(metricsLayer), Layer.isLayer(cumulativeLayer)] // => [true, true]
  * ```
  *
  * @category models

package/src/unstable/observability/OtlpResource.ts

@@ -70,11 +70,20 @@ export const make = (options: {
  * Creates an OTLP resource from explicit options and OpenTelemetry
  * configuration.
  *
+ * **When to use**
+ *
+ * Use when resource metadata may be configured in code or by the deployment
+ * environment. To let operators set the service identity, omit `serviceName`,
+ * `serviceVersion`, and their matching attributes, then use
+ * `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`.
+ *
  * **Details**
  *
- * `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
- * `OTEL_SERVICE_VERSION` override explicit options; missing required
- * configuration is converted to a defect.
+ * Explicit `serviceName` and `serviceVersion` options take precedence over
+ * matching explicit attributes. Explicit attributes take precedence over
+ * environment variables. `OTEL_SERVICE_NAME` and `OTEL_SERVICE_VERSION` take
+ * precedence over matching attributes in `OTEL_RESOURCE_ATTRIBUTES`. Missing
+ * required configuration is converted to a defect.
  *
  * @category constructors
  * @since 4.0.0
@@ -91,24 +100,24 @@ export const fromConfig: (
   readonly attributes?: Record<string, unknown> | undefined
 }) {
   const env = yield* Config.schema(
-    Schema.UndefinedOr(Config.Record(Schema.String, Schema.String)),
+    Schema.UndefinedOr(Config.Record(Schema.StringFromUriComponent, Schema.StringFromUriComponent)),
     "OTEL_RESOURCE_ATTRIBUTES"
   )
 
-  const serviceName = (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_NAME"))
-    ?? env?.["service.name"] as string | undefined
+  const serviceName = options?.serviceName
     ?? options?.attributes?.["service.name"] as string | undefined
-    ?? options?.serviceName
+    ?? (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_NAME"))
+    ?? env?.["service.name"] as string | undefined
     ?? (yield* Config.string("OTEL_SERVICE_NAME"))
 
-  const serviceVersion = (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_VERSION"))
-    ?? env?.["service.version"] as string | undefined
+  const serviceVersion = options?.serviceVersion
     ?? options?.attributes?.["service.version"] as string | undefined
-    ?? options?.serviceVersion
+    ?? (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_VERSION"))
+    ?? env?.["service.version"] as string | undefined
 
   const attributes = {
-    ...options?.attributes,
-    ...env
+    ...env,
+    ...options?.attributes
   }
 
   delete attributes["service.name"]
@@ -133,7 +142,7 @@ export const fromConfig: (
  *
  * Throws if the resource does not contain a string `service.name` attribute.
  *
- * @category Attributes
+ * @category attributes
  * @since 4.0.0
  */
 export const serviceNameUnsafe = (resource: Resource): string => {
@@ -149,7 +158,7 @@ export const serviceNameUnsafe = (resource: Resource): string => {
 /**
  * Converts key/value entries into OTLP `KeyValue` attributes.
  *
- * @category Attributes
+ * @category attributes
  * @since 4.0.0
  */
 export const entriesToAttributes = (entries: Iterable<[string, unknown]>): Array<KeyValue> => {
@@ -171,7 +180,7 @@ export const entriesToAttributes = (entries: Iterable<[string, unknown]>): Array
  * Arrays are converted recursively, primitive values use their matching OTLP
  * fields, and unsupported values are formatted as strings.
  *
- * @category Attributes
+ * @category attributes
  * @since 4.0.0
  */
 export const unknownToAttributeValue = (value: unknown): AnyValue => {
@@ -189,7 +198,7 @@ export const unknownToAttributeValue = (value: unknown): AnyValue => {
       }
     case "bigint":
       return {
-        intValue: Number(value)
+        intValue: String(value)
       }
     case "number":
       return Number.isInteger(value)
@@ -235,7 +244,7 @@ export interface AnyValue {
   /** AnyValue boolValue */
   boolValue?: boolean | null
   /** AnyValue intValue */
-  intValue?: number | null
+  intValue?: string | number | null
   /** AnyValue doubleValue */
   doubleValue?: number | null
   /** AnyValue arrayValue */

package/src/unstable/observability/PrometheusMetrics.ts

@@ -19,12 +19,14 @@ import * as HttpServerResponse from "../http/HttpServerResponse.ts"
  *
  * **Example** (Mapping metric names)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { PrometheusMetrics } from "effect/unstable/observability"
  *
  * // Convert camelCase to snake_case
  * const mapper: PrometheusMetrics.MetricNameMapper = (name) =>
  *   name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()
+ *
+ * mapper("httpRequests") // => "http_requests"
  * ```
  *
  * @category models
@@ -68,7 +70,7 @@ export interface HttpOptions extends FormatOptions {
  *
  * **Example** (Formatting metrics)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Metric } from "effect"
  * import { PrometheusMetrics } from "effect/unstable/observability"
  *
@@ -88,7 +90,11 @@ export interface HttpOptions extends FormatOptions {
  *
  *   // Format with prefix
  *   const output2 = yield* PrometheusMetrics.format({ prefix: "myapp" })
+ *
+ *   return [output1.includes("api_requests_total"), output2.includes("myapp_active_connections")]
  * })
+ *
+ * Effect.runSync(program) // => [true, true]
  * ```
  *
  * @category formatting
@@ -156,7 +162,8 @@ export const formatUnsafe = (
  *
  * **Example** (Serving metrics over HTTP)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Layer } from "effect"
  * import { PrometheusMetrics } from "effect/unstable/observability"
  *
  * // Create a layer that adds /metrics endpoint to the router
@@ -167,9 +174,11 @@ export const formatUnsafe = (
  *   path: "/prometheus/metrics",
  *   prefix: "myapp"
  * })
+ *
+ * const result = [Layer.isLayer(PrometheusLayer), Layer.isLayer(CustomPrometheusLayer)] // => [true, true]
  * ```
  *
- * @category Http
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttp = (