effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/unstable/devtools/index.ts

@@ -5,21 +5,79 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * 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
  */
 export * as DevTools from "./DevTools.ts"
 
 /**
+ * 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
  */
 export * as DevToolsClient from "./DevToolsClient.ts"
 
 /**
+ * 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
  */
 export * as DevToolsSchema from "./DevToolsSchema.ts"
 
 /**
+ * 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
  */
 export * as DevToolsServer from "./DevToolsServer.ts"

package/src/unstable/encoding/Sse.ts

@@ -39,7 +39,7 @@ import * as Transformation from "../../SchemaTransformation.ts"
  * SSE `retry` directives are emitted as `Retry` failures so callers can
  * reconnect with the requested delay.
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
 export const decode = <IE, Done>(): Channel.Channel<
@@ -88,7 +88,7 @@ export const decode = <IE, Done>(): Channel.Channel<
  * The schema receives the untagged event shape containing `id`, `event`, and
  * string `data`.
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeSchema = <
@@ -125,7 +125,7 @@ export const decodeSchema = <
  * The output preserves the SSE `event` name and optional `id` while replacing
  * `data` with the decoded value.
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeDataSchema = <Type, DecodingServices, IE, Done>(
@@ -159,7 +159,7 @@ export const decodeDataSchema = <Type, DecodingServices, IE, Done>(
  * Call `feed` with text chunks to parse `Event` and `Retry` values through the
  * callback, and call `reset` to clear any buffered event state.
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
 export function makeParser(onParse: (event: AnyEvent) => void): Parser {
@@ -325,7 +325,7 @@ function hasBom(buffer: string) {
  *
  * `feed` accepts additional text chunks and `reset` clears buffered parser state.
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
 export interface Parser {
@@ -339,7 +339,7 @@ export interface Parser {
  * If the upstream channel fails with `Retry`, the retry directive is written and
  * the encoder completes.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export const encode = <IE, Done>(): Channel.Channel<
@@ -371,7 +371,7 @@ export const encode = <IE, Done>(): Channel.Channel<
  * Values are schema-encoded to the untagged SSE event shape, transformed to
  * `Event`, and then written as Server-Sent Events text.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeSchema = <
@@ -400,7 +400,7 @@ export const encodeSchema = <
  * Encoder capable of rendering an `Event` or `Retry` value as Server-Sent
  * Events text.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export interface Encoder {
@@ -412,7 +412,7 @@ export interface Encoder {
  *
  * It contains the event name, optional event ID, and string data payload.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Event {
@@ -427,7 +427,7 @@ export interface Event {
  *
  * The shape contains `id`, `event`, and string `data` fields.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export const EventEncoded: Schema.Struct<{
@@ -446,7 +446,7 @@ export const EventEncoded: Schema.Struct<{
  * The schema adds `_tag: "Event"` to the event name, optional event ID, and
  * string data payload.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export const Event: Schema.Struct<{
@@ -465,7 +465,7 @@ export const Event: Schema.Struct<{
  * Schema transformation between the untagged SSE event shape and the tagged
  * `Event` model.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export const transformEvent = Transformation.transform<{
@@ -492,7 +492,7 @@ export const transformEvent = Transformation.transform<{
  *
  * It contains the event name, optional event ID, and string data payload.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface EventEncoded {
@@ -509,7 +509,7 @@ const RetryTypeId = "~effect/encoding/Sse/Retry" as const
  * Decoders surface this value as a failure to request reconnection after
  * `duration`; encoders serialize an upstream `Retry` failure as a `retry:` line.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export class Retry extends Data.TaggedClass("Retry")<{
@@ -544,7 +544,7 @@ export class Retry extends Data.TaggedClass("Retry")<{
  * Union of SSE values that can be rendered by an `Encoder`: regular events and
  * retry directives.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type AnyEvent = Event | Retry
@@ -555,7 +555,7 @@ export type AnyEvent = Event | Retry
  * It renders `Event` values as `id`, `event`, and `data` lines and renders
  * `Retry` values as `retry:` directives.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export const encoder: Encoder = {

package/src/unstable/encoding/index.ts

@@ -5,16 +5,65 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * Utilities for encoding Effect channel payloads and schema values as
+ * MessagePack bytes.
+ *
+ * This module is useful when a protocol or storage layer expects compact binary
+ * frames instead of JSON text, such as RPC transports, socket streams, caches,
+ * or database columns that carry typed Effect data. Use the raw channel helpers
+ * when both sides already agree on the MessagePack value shape, and use the
+ * schema-aware helpers when values should be validated, transformed, or decoded
+ * into domain types at the boundary.
+ *
+ * MessagePack preserves binary data and common JavaScript collection shapes, but
+ * it is still a data format rather than an Effect schema. Schema encoders run
+ * before packing and schema decoders run after unpacking, so unsupported runtime
+ * values, lossy schema encodings, or mismatched schemas surface as either
+ * `MsgPackError` or `SchemaError` depending on where the failure occurs.
+ *
  * @since 4.0.0
  */
 export * as Msgpack from "./Msgpack.ts"
 
 /**
+ * Utilities for encoding Effect channel payloads and schema values as
+ * newline-delimited JSON.
+ *
+ * NDJSON represents a stream as one complete JSON value per line, making this
+ * module useful for log pipelines, long-lived HTTP responses, socket protocols,
+ * and file formats where records should be processed incrementally instead of
+ * buffering a whole JSON array. Use the byte helpers at transport boundaries
+ * that speak UTF-8, the string helpers when text framing is already handled,
+ * and the schema-aware helpers when each record should be validated or
+ * transformed at the boundary.
+ *
+ * Encoders append a trailing newline after each emitted chunk, and decoders
+ * tolerate records split across input chunks. Empty lines are only skipped when
+ * `ignoreEmptyLines` is enabled; otherwise they are passed to `JSON.parse` and
+ * fail like any other invalid JSON record.
+ *
  * @since 4.0.0
  */
 export * as Ndjson from "./Ndjson.ts"
 
 /**
+ * Utilities for parsing and rendering Server-Sent Events text streams.
+ *
+ * This module is useful at HTTP streaming boundaries that speak the EventSource
+ * wire format, such as live updates, notifications, progress feeds, and other
+ * unidirectional server-to-client event streams. It provides low-level parser
+ * and encoder primitives, channel combinators for streaming chunks through
+ * Effect pipelines, and schema-aware helpers for validating or transforming the
+ * `id`, `event`, and string `data` fields at the edge of an application.
+ *
+ * SSE is line-oriented text rather than a framed binary protocol. Incoming
+ * chunks may split fields across arbitrary boundaries, events are dispatched by
+ * a blank line, repeated `data:` lines are joined with newlines, and `retry:`
+ * directives are control messages rather than regular events. The decoder
+ * handles UTF-8 byte order marks, CRLF and LF line endings, default `message`
+ * events, and retry directives so callers can reconnect with the requested
+ * delay while preserving the last event ID when available.
+ *
  * @since 4.0.0
  */
 export * as Sse from "./Sse.ts"

package/src/unstable/eventlog/Event.ts

@@ -25,7 +25,7 @@ import * as Msgpack from "../encoding/Msgpack.ts"
 /**
  * Unique type identifier used to mark event log event definitions.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/eventlog/Event"
@@ -33,7 +33,7 @@ export type TypeId = "~effect/eventlog/Event"
 /**
  * Runtime type identifier used to mark event log event definitions.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/eventlog/Event"

package/src/unstable/eventlog/EventGroup.ts

@@ -25,7 +25,7 @@ import * as Event from "./Event.ts"
 /**
  * Unique type identifier used to mark event log event groups.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/eventlog/EventGroup"
@@ -33,7 +33,7 @@ export type TypeId = "~effect/eventlog/EventGroup"
 /**
  * Runtime type identifier used to mark event log event groups.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/eventlog/EventGroup"

package/src/unstable/eventlog/EventLog.ts

@@ -189,7 +189,7 @@ export class Identity extends Context.Service<Identity, {
 /**
  * Type-level identifier used to brand `EventLogSchema` values.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export type SchemaTypeId = "~effect/eventlog/EventLog/Schema"
@@ -197,7 +197,7 @@ export type SchemaTypeId = "~effect/eventlog/EventLog/Schema"
 /**
  * Runtime property key used to identify `EventLogSchema` values.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const SchemaTypeId: SchemaTypeId = "~effect/eventlog/EventLog/Schema"
@@ -205,7 +205,7 @@ export const SchemaTypeId: SchemaTypeId = "~effect/eventlog/EventLog/Schema"
 /**
  * Returns `true` when a value carries the `EventLogSchema` marker.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const isEventLogSchema = (u: unknown): u is EventLogSchema<EventGroup.Any> =>
@@ -214,7 +214,7 @@ export const isEventLogSchema = (u: unknown): u is EventLogSchema<EventGroup.Any
 /**
  * Schema describing the event groups that can be written through an `EventLog`.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export interface EventLogSchema<Groups extends EventGroup.Any> {
@@ -225,7 +225,7 @@ export interface EventLogSchema<Groups extends EventGroup.Any> {
 /**
  * Creates an `EventLogSchema` from one or more event groups.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schema = <Groups extends ReadonlyArray<EventGroup.Any>>(
@@ -299,7 +299,6 @@ export interface Handlers<
  * Namespace containing helper types for `Handlers` values and handler-producing
  * layers.
  *
- * @category handlers
  * @since 4.0.0
  */
 export declare namespace Handlers {
@@ -423,7 +422,7 @@ const RedactedUint8Array = Schema.Uint8ArrayFromBase64.pipe(
  * Schema for an event-log identity with a string public key and redacted
  * base64-encoded private key bytes.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const IdentitySchema = Schema.Struct({

package/src/unstable/eventlog/EventLogRemote.ts

@@ -346,7 +346,7 @@ export const makeUnencrypted: Effect.Effect<
  * Provides an encrypted `EventLogRemote` using the remote RPC client and the
  * default Web Crypto encryption layer.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerEncrypted: Layer.Layer<
@@ -361,7 +361,7 @@ export const layerEncrypted: Layer.Layer<
 /**
  * Provides an unencrypted `EventLogRemote` using the remote RPC client.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerUnencrypted: Layer.Layer<

package/src/unstable/eventlog/EventLogServer.ts

@@ -50,7 +50,7 @@ import * as EventLogSessionAuth from "./EventLogSessionAuth.ts"
  *
  * Requests without an identity fail with a forbidden `EventLogProtocolError`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerAuthMiddleware: Layer.Layer<
@@ -75,7 +75,7 @@ export const layerAuthMiddleware: Layer.Layer<
  * chunked writes, delegates write and change handling to the supplied callbacks,
  * and frames large change payloads into chunks.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerRpcHandlers = (options: {

package/src/unstable/eventlog/EventLogServerEncrypted.ts

@@ -45,7 +45,7 @@ import * as EventLogServer from "./EventLogServer.ts"
  * change streams read encrypted entries from storage and encode them for the
  * remote protocol.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerRpcHandlers = Layer.unwrap(Effect.gen(function*() {
@@ -99,7 +99,7 @@ export const layerRpcHandlers = Layer.unwrap(Effect.gen(function*() {
  * Provides an encrypted event-log RPC server using `EventLogRemoteRpcs` and the
  * encrypted server RPC handlers.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layer: Layer.Layer<never, never, RpcServer.Protocol | Storage> = RpcServer.layer(EventLogRemoteRpcs).pipe(

package/src/unstable/eventlog/EventLogServerUnencrypted.ts

@@ -103,7 +103,7 @@ export const makeWrite = <Groups extends EventGroup.Any>(
  * for conflicts, run through registered handlers, and persisted; change streams
  * include compacted backlog entries when compactors are registered.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerRpcHandlers: Layer.Layer<

package/src/unstable/eventlog/EventLogSessionAuth.ts

@@ -72,7 +72,7 @@ export const SessionAuthChallengeTimeToLiveMillis = 30_000
  * Payload fields that are canonicalized and signed during session
  * authentication.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface SessionAuthPayload {