effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/devtools/DevToolsClient.ts

@@ -1,4 +1,16 @@
 /**
+ * Provides the low-level client used by the unstable devtools integration to
+ * exchange telemetry with an Effect devtools server over the current `Socket`.
+ *
+ * The client speaks the devtools NDJSON protocol, publishes span starts, span
+ * events, span completions, and metric snapshots, and exposes layers for
+ * installing a tracer that mirrors the current tracer while forwarding data to
+ * devtools. Most applications should use the higher-level devtools layers
+ * instead of constructing this service directly. When using this module
+ * directly, provide a live `Socket`, keep the layer scoped so the background
+ * ping and stream fibers are finalized, and prefer `layerTracer` when the goal
+ * is to observe an application's Effect traces.
+ *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"
@@ -21,8 +33,11 @@ const RequestSchema = Schema.toCodecJson(DevToolsSchema.Request)
 const ResponseSchema = Schema.toCodecJson(DevToolsSchema.Response)
 
 /**
- * @since 4.0.0
+ * Service for sending span and span-event telemetry to the Effect devtools
+ * connection.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export class DevToolsClient extends Context.Service<
   DevToolsClient,
@@ -103,8 +118,12 @@ const toMetricsSnapshot = (
 })
 
 /**
- * @since 4.0.0
+ * Creates a devtools client over the current `Socket`, speaking the devtools
+ * NDJSON protocol, sending periodic pings, and responding to metrics snapshot
+ * requests.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make: Effect.Effect<
   DevToolsClient["Service"],
@@ -118,8 +137,10 @@ export const make: Effect.Effect<
 )
 
 /**
- * @since 4.0.0
+ * Layer that provides `DevToolsClient` using the current `Socket`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<DevToolsClient, never, Socket.Socket> = Layer.effect(DevToolsClient, make)
 
@@ -157,8 +178,11 @@ const makeTracerEffect = Effect.gen(function*() {
 })
 
 /**
- * @since 4.0.0
+ * Creates a tracer that delegates to the current tracer while sending span
+ * starts, span events, and span ends to `DevToolsClient`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeTracer: Effect.Effect<Tracer.Tracer, never, DevToolsClient> = makeTracerEffect.pipe(
   Effect.annotateLogs({
@@ -168,8 +192,11 @@ export const makeTracer: Effect.Effect<Tracer.Tracer, never, DevToolsClient> = m
 )
 
 /**
- * @since 4.0.0
+ * Layer that creates a `DevToolsClient` from the current `Socket` and installs
+ * the devtools tracer.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerTracer: Layer.Layer<never, never, Socket.Socket> = Layer.effect(Tracer.Tracer, makeTracer).pipe(
   Layer.provide(layer)

package/src/unstable/devtools/DevToolsSchema.ts

@@ -1,4 +1,21 @@
 /**
+ * Schemas and TypeScript types for the Effect devtools protocol.
+ *
+ * This module defines the wire format used by devtools clients and servers to
+ * exchange telemetry, including spans, span events, metric snapshots, fiber
+ * dumps, heartbeat messages, and request/response payloads. Use these schemas
+ * when encoding or decoding messages at the devtools boundary, validating
+ * custom transports, or building integrations that need to inspect the same
+ * protocol data as the built-in devtools implementation.
+ *
+ * The exported values describe serialized protocol payloads rather than the
+ * full in-memory runtime data structures. Some fields intentionally normalize
+ * runtime values for transport, for example ended span exits are encoded with
+ * successful values erased via `Exit.asVoid`, timestamps are represented as
+ * `bigint`s, and arbitrary attributes are accepted as unknown schema values.
+ * The module lives under `unstable`, so consumers should treat the protocol
+ * shape as experimental.
+ *
  * @since 4.0.0
  */
 import * as Exit from "../../Exit.ts"
@@ -8,8 +25,11 @@ import * as Schema from "../../Schema.ts"
 import * as SchemaTransformation from "../../SchemaTransformation.ts"
 
 /**
- * @since 4.0.0
+ * Schema for a span status representing a span that has started but not yet
+ * ended.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const SpanStatusStarted = Schema.Struct({
   _tag: Schema.tag("Started"),
@@ -17,14 +37,20 @@ export const SpanStatusStarted = Schema.Struct({
 })
 
 /**
- * @since 4.0.0
+ * Type of a span status representing a span that has started but not yet ended.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type SpanStatusStarted = Schema.Schema.Type<typeof SpanStatusStarted>
 
 /**
- * @since 4.0.0
+ * Schema for a span status representing an ended span, including start time,
+ * end time, and encoded exit status. Encoding drops success values with
+ * `Exit.asVoid`.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const SpanStatusEnded = Schema.Struct({
   _tag: Schema.tag("Ended"),
@@ -42,26 +68,36 @@ export const SpanStatusEnded = Schema.Struct({
 })
 
 /**
- * @since 4.0.0
+ * Type of a span status representing an ended span with start time, end time,
+ * and exit status.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type SpanStatusEnded = Schema.Schema.Type<typeof SpanStatusEnded>
 
 /**
- * @since 4.0.0
+ * Schema for devtools span status, either started or ended.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const SpanStatus = Schema.Union([SpanStatusStarted, SpanStatusEnded])
 
 /**
- * @since 4.0.0
+ * Type of a devtools span status, either started or ended.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type SpanStatus = Schema.Schema.Type<typeof SpanStatus>
 
 /**
- * @since 4.0.0
+ * Serialized parent span context for a span created outside the current
+ * devtools span tree.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export interface ExternalSpan {
   readonly _tag: "ExternalSpan"
@@ -71,8 +107,11 @@ export interface ExternalSpan {
 }
 
 /**
- * @since 4.0.0
+ * Schema for an external parent span context containing span id, trace id, and
+ * sampling flag.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const ExternalSpan: Schema.Codec<ExternalSpan> = Schema.Struct({
   _tag: Schema.tag("ExternalSpan"),
@@ -82,8 +121,11 @@ export const ExternalSpan: Schema.Codec<ExternalSpan> = Schema.Struct({
 })
 
 /**
- * @since 4.0.0
+ * Telemetry payload for an Effect span sent to devtools, including identity,
+ * attributes, status, sampling flag, and optional parent span.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export interface Span {
   readonly _tag: "Span"
@@ -97,8 +139,10 @@ export interface Span {
 }
 
 /**
- * @since 4.0.0
+ * Schema for an Effect span telemetry payload sent to devtools.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Span: Schema.Codec<Span> = Schema.Struct({
   _tag: Schema.tag("Span"),
@@ -112,8 +156,11 @@ export const Span: Schema.Codec<Span> = Schema.Struct({
 })
 
 /**
- * @since 4.0.0
+ * Schema for a named event emitted by a span, including trace id, span id,
+ * start time, and optional attributes.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const SpanEvent = Schema.Struct({
   _tag: Schema.tag("SpanEvent"),
@@ -125,68 +172,90 @@ export const SpanEvent = Schema.Struct({
 })
 
 /**
- * @since 4.0.0
+ * Type of a named event emitted by a span and sent to devtools.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type SpanEvent = Schema.Schema.Type<typeof SpanEvent>
 
 /**
- * @since 4.0.0
+ * Type of a span parent, represented either by a devtools `Span` payload or an
+ * `ExternalSpan` context.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type ParentSpan = Span | ExternalSpan
 
 /**
- * @since 4.0.0
+ * Schema for a span parent, either a full devtools `Span` payload or an
+ * `ExternalSpan` context.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const ParentSpan = Schema.Union([Span, ExternalSpan])
 
 /**
- * @since 4.0.0
+ * Schema for the devtools heartbeat request sent by the client.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Ping = Schema.Struct({
   _tag: Schema.tag("Ping")
 })
 
 /**
- * @since 4.0.0
+ * Type of the devtools heartbeat request sent by the client.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Ping = Schema.Schema.Type<typeof Ping>
 
 /**
- * @since 4.0.0
+ * Schema for the devtools heartbeat response.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Pong = Schema.Struct({
   _tag: Schema.tag("Pong")
 })
 
 /**
- * @since 4.0.0
+ * Type of the devtools heartbeat response.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Pong = Schema.Schema.Type<typeof Pong>
 
 /**
- * @since 4.0.0
+ * Schema for a devtools request asking the client to send a metrics snapshot.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const MetricsRequest = Schema.Struct({
   _tag: Schema.tag("MetricsRequest")
 })
 
 /**
- * @since 4.0.0
+ * Type of a devtools request asking the client to send a metrics snapshot.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type MetricsRequest = Schema.Schema.Type<typeof MetricsRequest>
 
 /**
- * @since 4.0.0
+ * Schema for a metric label key/value pair in a devtools metrics snapshot.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const MetricLabel = Schema.Struct({
   key: Schema.String,
@@ -194,8 +263,10 @@ export const MetricLabel = Schema.Struct({
 })
 
 /**
- * @since 4.0.0
+ * Type of a metric label key/value pair in a devtools metrics snapshot.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type MetricLabel = Schema.Schema.Type<typeof MetricLabel>
 
@@ -209,8 +280,11 @@ const metric = <Type extends string, State extends Schema.Top>(type: Type, state
   })
 
 /**
- * @since 4.0.0
+ * Schema for a counter metric snapshot, including the count and whether updates
+ * are incremental.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Counter = metric(
   "Counter",
@@ -221,14 +295,23 @@ export const Counter = metric(
 )
 
 /**
- * @since 4.0.0
+ * Type of a devtools counter metric snapshot.
+ *
+ * The state contains the current count and whether the counter reports
+ * incremental updates.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Counter = Schema.Schema.Type<typeof Counter>
 
 /**
- * @since 4.0.0
+ * Schema for a devtools frequency metric snapshot.
+ *
+ * The metric state records occurrence counts by string key.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Frequency = metric(
   "Frequency",
@@ -238,14 +321,22 @@ export const Frequency = metric(
 )
 
 /**
- * @since 4.0.0
+ * Type of a devtools frequency metric snapshot.
+ *
+ * The state maps observed string values to occurrence counts.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Frequency = Schema.Schema.Type<typeof Frequency>
 
 /**
- * @since 4.0.0
+ * Schema for a devtools gauge metric snapshot.
+ *
+ * The metric state contains the current numeric or bigint value.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Gauge = metric(
   "Gauge",
@@ -255,14 +346,23 @@ export const Gauge = metric(
 )
 
 /**
- * @since 4.0.0
+ * Type of a devtools gauge metric snapshot.
+ *
+ * The state contains the current numeric or bigint value.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Gauge = Schema.Schema.Type<typeof Gauge>
 
 /**
- * @since 4.0.0
+ * Schema for a devtools histogram metric snapshot.
+ *
+ * The metric state includes bucket counts plus the total count, minimum,
+ * maximum, and sum.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Histogram = metric(
   "Histogram",
@@ -276,14 +376,24 @@ export const Histogram = metric(
 )
 
 /**
- * @since 4.0.0
+ * Type of a devtools histogram metric snapshot.
+ *
+ * The state includes bucket counts plus the total count, minimum, maximum, and
+ * sum.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Histogram = Schema.Schema.Type<typeof Histogram>
 
 /**
- * @since 4.0.0
+ * Schema for a devtools summary metric snapshot.
+ *
+ * The metric state contains quantile values plus the total count, minimum,
+ * maximum, and sum.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Summary = metric(
   "Summary",
@@ -297,26 +407,43 @@ export const Summary = metric(
 )
 
 /**
- * @since 4.0.0
+ * Type of a devtools summary metric snapshot.
+ *
+ * The state contains quantile values plus the total count, minimum, maximum,
+ * and sum.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Summary = Schema.Schema.Type<typeof Summary>
 
 /**
- * @since 4.0.0
+ * Schema for any devtools metric snapshot.
+ *
+ * Accepted metric kinds are counters, frequencies, gauges, histograms, and
+ * summaries.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Metric = Schema.Union([Counter, Frequency, Gauge, Histogram, Summary])
 
 /**
- * @since 4.0.0
+ * Type of any devtools metric snapshot.
+ *
+ * The union covers counters, frequencies, gauges, histograms, and summaries.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Metric = Schema.Schema.Type<typeof Metric>
 
 /**
- * @since 4.0.0
+ * Schema for a devtools protocol message containing the current metric
+ * snapshots.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const MetricsSnapshot = Schema.Struct({
   _tag: Schema.tag("MetricsSnapshot"),
@@ -324,55 +451,85 @@ export const MetricsSnapshot = Schema.Struct({
 })
 
 /**
- * @since 4.0.0
+ * Type of a devtools protocol message containing the current metric snapshots.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type MetricsSnapshot = Schema.Schema.Type<typeof MetricsSnapshot>
 
 /**
- * @since 4.0.0
+ * Schema for devtools protocol requests accepted by the server.
+ *
+ * Requests include heartbeat pings, spans, span events, and metric snapshots.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Request = Schema.Union([Ping, Span, SpanEvent, MetricsSnapshot])
 
 /**
- * @since 4.0.0
+ * Type of devtools protocol requests accepted by the server.
+ *
+ * Requests include heartbeat pings, spans, span events, and metric snapshots.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Request = Schema.Schema.Type<typeof Request>
 
 /**
+ * Namespace containing helper types for devtools protocol requests.
+ *
  * @since 4.0.0
- * @category schemas
  */
 export declare namespace Request {
   /**
-   * @since 4.0.0
+   * Devtools request messages excluding heartbeat pings.
+   *
+   * `DevToolsServer` handles `Ping` internally and exposes only these requests
+   * to client handlers.
+   *
    * @category schemas
+   * @since 4.0.0
    */
   export type WithoutPing = Exclude<Request, { readonly _tag: "Ping" }>
 }
 
 /**
- * @since 4.0.0
+ * Schema for devtools protocol responses sent by the server.
+ *
+ * Responses include heartbeat pongs and requests for metric snapshots.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Response = Schema.Union([Pong, MetricsRequest])
 
 /**
- * @since 4.0.0
+ * Type of devtools protocol responses sent by the server.
+ *
+ * Responses include heartbeat pongs and requests for metric snapshots.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Response = Schema.Schema.Type<typeof Response>
 
 /**
+ * Namespace containing helper types for devtools protocol responses.
+ *
  * @since 4.0.0
- * @category schemas
  */
 export declare namespace Response {
   /**
-   * @since 4.0.0
+   * Devtools response messages excluding heartbeat pongs.
+   *
+   * `DevToolsServer` sends `Pong` internally and accepts only these responses
+   * from client handlers.
+   *
    * @category schemas
+   * @since 4.0.0
    */
   export type WithoutPong = Exclude<Response, { readonly _tag: "Pong" }>
 }

package/src/unstable/devtools/DevToolsServer.ts

@@ -1,4 +1,18 @@
 /**
+ * Server-side helpers for exposing the Effect devtools protocol over a socket.
+ *
+ * This module is used by runtime integrations that want to accept devtools
+ * clients, decode newline-delimited JSON protocol messages, and hand each
+ * connected client to application-specific handling logic. It is most useful
+ * for building a devtools endpoint that can inspect running fibers, spans, and
+ * other telemetry described by `DevToolsSchema`.
+ *
+ * The server automatically responds to protocol `Ping` requests with `Pong`
+ * responses. All other requests are delivered through the connected `Client`
+ * queue, while responses should be written with `Client.send`. The queue is
+ * shut down when the socket processing fiber terminates, so handlers should
+ * treat it as connection-scoped state rather than a long-lived global channel.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -14,8 +28,13 @@ const RequestSchema = Schema.toCodecJson(DevToolsSchema.Request)
 const ResponseSchema = Schema.toCodecJson(DevToolsSchema.Response)
 
 /**
- * @since 4.0.0
+ * Handle for a connected devtools client.
+ *
+ * It exposes a queue of non-ping requests received from the socket and a
+ * `send` function for non-pong responses.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Client {
   readonly queue: Queue.Dequeue<DevToolsSchema.Request.WithoutPing>
@@ -23,8 +42,14 @@ export interface Client {
 }
 
 /**
- * @since 4.0.0
+ * Runs the devtools socket server.
+ *
+ * Each connection is decoded as NDJSON devtools protocol messages, `Ping`
+ * requests are answered with `Pong`, and all other requests are delivered
+ * through the `Client` passed to the handler.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const run: <_, E, R>(
   handle: (client: Client) => Effect.Effect<_, E, R>