effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/cluster/internal/hash.ts

@@ -1,3 +1,15 @@
+/**
+ * Internal hashing helpers used by cluster routing to map entity identifiers to
+ * shard numbers. The hash is intentionally small and deterministic for
+ * JavaScript strings so every node that sees the same entity id and sharding
+ * configuration derives the same destination shard.
+ *
+ * **Gotchas**
+ *
+ * - Changing this implementation changes entity-to-shard assignment.
+ * - Strings are hashed as UTF-16 code units; normalize ids before routing if
+ *   callers may produce equivalent text in different Unicode forms.
+ */
 /** @internal */
 export const hashOptimize = (n: number): number => (n & 0xbfffffff) | ((n >>> 1) & 0x40000000)
 

package/src/unstable/devtools/DevTools.ts

@@ -1,4 +1,19 @@
 /**
+ * Utilities for wiring an Effect application to the Effect devtools runtime
+ * tracer.
+ *
+ * This module is the high-level entry point for installing the devtools tracer
+ * as a `Layer`. Use it when an application should stream spans, span events,
+ * span completions, and metrics snapshots to a devtools process for local
+ * inspection. The default `layer` and `layerWebSocket` helpers connect over a
+ * WebSocket to `ws://localhost:34437`, while `layerSocket` lets integrations
+ * provide their own `Socket` transport.
+ *
+ * These layers install tracing for the scoped runtime they are provided to;
+ * they do not start a devtools server, and a compatible devtools endpoint must
+ * be reachable separately. Because this API lives under `unstable`, its
+ * protocol and surface may change between releases.
+ *
  * @since 4.0.0
  */
 import * as Layer from "../../Layer.ts"
@@ -6,14 +21,19 @@ import * as Socket from "../socket/Socket.ts"
 import * as DevToolsClient from "./DevToolsClient.ts"
 
 /**
- * @since 4.0.0
+ * Layer that installs the devtools tracer using an existing `Socket`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerSocket: Layer.Layer<never, never, Socket.Socket> = DevToolsClient.layerTracer
 
 /**
- * @since 4.0.0
+ * Layer that installs the devtools tracer over a WebSocket connection to the
+ * specified URL, defaulting to `ws://localhost:34437`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerWebSocket = (
   url = "ws://localhost:34437"
@@ -23,8 +43,11 @@ export const layerWebSocket = (
   )
 
 /**
- * @since 4.0.0
+ * Layer that installs the devtools tracer over a WebSocket connection using the
+ * global WebSocket constructor, defaulting to `ws://localhost:34437`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (url = "ws://localhost:34437"): Layer.Layer<never> =>
   layerWebSocket(url).pipe(

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" }>
 }