effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/devtools/DevTools.ts

@@ -1,18 +1,28 @@
 /**
- * Utilities for wiring an Effect application to the Effect devtools runtime
+ * High-level layers for connecting an Effect runtime to the unstable devtools
  * 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.
+ * `DevTools` is the application-facing entry point for installing a tracer that
+ * mirrors the current tracer and streams spans, span events, span completions,
+ * and metric snapshots to an external devtools process. Lower-level socket
+ * protocol details live in `DevToolsClient`.
  *
- * 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.
+ * **Common tasks**
+ *
+ * - Use {@link layer} when the runtime provides a global `WebSocket`
+ * - Use {@link layerWebSocket} when the environment should provide the
+ *   `WebSocketConstructor`
+ * - Use {@link layerSocket} when an integration already has a `Socket`
+ *   transport
+ *
+ * **Gotchas**
+ *
+ * - The WebSocket helpers default to `ws://localhost:34437`.
+ * - These layers install only the client-side tracer; start or connect the
+ *   devtools server separately.
+ * - The tracer is scoped to the runtime or layer graph that receives the layer.
+ * - This module is under `unstable`, so the transport protocol and exports may
+ *   change between releases.
  *
  * @since 4.0.0
  */
@@ -46,6 +56,26 @@ export const layerWebSocket = (
  * Layer that installs the devtools tracer over a WebSocket connection using the
  * global WebSocket constructor, defaulting to `ws://localhost:34437`.
  *
+ * **When to use**
+ *
+ * Use to stream Effect tracing and metrics telemetry to a devtools process when
+ * the runtime environment already provides a global `WebSocket` constructor.
+ *
+ * **Details**
+ *
+ * This is a convenience wrapper around `layerWebSocket(url)` that provides
+ * `Socket.layerWebSocketConstructorGlobal`, so the resulting layer has no
+ * remaining requirements.
+ *
+ * **Gotchas**
+ *
+ * This layer only installs the client-side tracer; it does not start a devtools
+ * server, so the configured WebSocket endpoint must already be reachable. It
+ * relies on `globalThis.WebSocket` being available in the runtime.
+ *
+ * @see {@link layerWebSocket} for installing the devtools tracer with an explicit `WebSocketConstructor` requirement
+ * @see {@link layerSocket} for installing the devtools tracer over an existing `Socket` transport
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/devtools/DevToolsClient.ts

@@ -1,15 +1,34 @@
 /**
- * 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.
+ * Low-level devtools client and tracer wiring over the current `Socket`.
+ *
+ * `DevToolsClient` speaks the devtools NDJSON protocol used by the unstable
+ * devtools integration. It sends span starts, span events, span completions,
+ * ping messages, and metric snapshots through a socket, then exposes tracer
+ * layers that forward telemetry while preserving the current tracer's behavior.
+ *
+ * **Mental model**
+ *
+ * {@link make} creates the scoped client service over the provided `Socket`;
+ * {@link makeTracer} wraps the current tracer and sends each span update
+ * through that client; {@link layerTracer} combines both steps for integrations
+ * that already have a socket transport. The higher-level `DevTools` module
+ * provides WebSocket defaults for applications.
+ *
+ * **Common tasks**
+ *
+ * - Build the client service directly with {@link make} or {@link layer}
+ * - Install only the forwarding tracer with {@link makeTracer}
+ * - Create the client and tracer together with {@link layerTracer}
+ * - Send custom span or span-event messages through `DevToolsClient.sendUnsafe`
+ *
+ * **Gotchas**
+ *
+ * - The client is scoped because it starts background fibers for the socket
+ *   stream and heartbeat.
+ * - `sendUnsafe` enqueues telemetry without back pressure and should stay on
+ *   the tracer hot path.
+ * - This module does not create a socket transport; provide `Socket` yourself
+ *   or use the higher-level `DevTools` module.
  *
  * @since 4.0.0
  */
@@ -122,6 +141,24 @@ const toMetricsSnapshot = (
  * NDJSON protocol, sending periodic pings, and responding to metrics snapshot
  * requests.
  *
+ * **When to use**
+ *
+ * Use when you already have a `Socket` and need the low-level `DevToolsClient`
+ * service to exchange devtools telemetry directly.
+ *
+ * **Details**
+ *
+ * The effect requires `Scope` because it starts background fibers for the socket
+ * stream and heartbeat.
+ *
+ * **Gotchas**
+ *
+ * `make` creates only the client service; tracing is installed separately.
+ *
+ * @see {@link layer} for providing the client as a layer
+ * @see {@link makeTracer} for creating a tracer after a `DevToolsClient` is available
+ * @see {@link layerTracer} for creating the client from the current `Socket` and installing the tracer as a layer
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -139,6 +176,26 @@ export const make: Effect.Effect<
 /**
  * Layer that provides `DevToolsClient` using the current `Socket`.
  *
+ * **When to use**
+ *
+ * Use to provide the low-level `DevToolsClient` service over an existing
+ * `Socket` for custom devtools integrations that send telemetry through the
+ * client directly.
+ *
+ * **Details**
+ *
+ * It delegates to `make`, so it speaks the devtools NDJSON protocol over the
+ * provided `Socket`, sends periodic pings, responds to metrics snapshot
+ * requests, and finalizes its background fibers when the layer scope closes.
+ *
+ * **Gotchas**
+ *
+ * This layer only provides the client. It does not install the devtools tracer
+ * by itself.
+ *
+ * @see {@link make} for constructing the client as a scoped effect instead of a layer
+ * @see {@link layerTracer} for a higher-level layer that creates the client and installs the devtools tracer
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/devtools/DevToolsSchema.ts

@@ -1,20 +1,28 @@
 /**
- * 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.
+ * Defines the experimental wire schema used by the Effect devtools protocol.
+ *
+ * The module contains the serialized message shapes exchanged between devtools
+ * clients and servers: span snapshots, span events, metric snapshots,
+ * heartbeats, and request/response unions. Use these schemas at protocol
+ * boundaries to encode, decode, or validate custom transports that need to
+ * interoperate with the built-in unstable devtools client and server.
+ *
+ * **Mental model**
+ *
+ * `Request` messages flow from the runtime-side devtools client to the server:
+ * `Ping`, `Span`, `SpanEvent`, and `MetricsSnapshot`. `Response` messages flow
+ * back from the server: `Pong` and `MetricsRequest`. The `WithoutPing` and
+ * `WithoutPong` helper types match the server behavior, where heartbeat
+ * messages are handled internally and user handlers see only application-level
+ * protocol messages.
+ *
+ * **Gotchas**
+ *
+ * These schemas describe transport payloads, not the full in-memory tracer or
+ * metric data structures. Ended span exits erase successful values with
+ * `Exit.asVoid`, timestamps are represented as `bigint`s, and attributes remain
+ * intentionally open-ended. Because this module lives under `unstable`, the
+ * protocol shape may change between releases.
  *
  * @since 4.0.0
  */

package/src/unstable/devtools/DevToolsServer.ts

@@ -1,17 +1,24 @@
 /**
- * Server-side helpers for exposing the Effect devtools protocol over a socket.
+ * Runs the server side of the unstable Effect devtools socket protocol.
  *
- * 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`.
+ * Use this module when an integration needs to accept devtools clients over a
+ * `SocketServer`, decode newline-delimited JSON messages, and handle each
+ * connection with application-specific logic. It does not interpret spans or
+ * metrics itself; it gives handlers a typed surface for the 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.
+ * **Mental model**
+ *
+ * Each accepted socket becomes one `Client`. Incoming `Ping` requests are
+ * answered internally with `Pong`, while all other decoded requests are offered
+ * to the client's queue. Handler code reads that queue and sends non-pong
+ * responses such as `MetricsRequest` through `Client.send`.
+ *
+ * **Gotchas**
+ *
+ * The client queue is scoped to the socket-processing fiber and is shut down
+ * when that fiber terminates. Treat it as per-connection state, not as a
+ * process-wide telemetry bus.
  *
  * @since 4.0.0
  */

package/src/unstable/devtools/index.ts

@@ -5,79 +5,21 @@
 // @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/Msgpack.ts

@@ -1,19 +1,34 @@
 /**
- * Utilities for encoding Effect channel payloads and schema values as
- * MessagePack bytes.
+ * Encode and decode MessagePack frames in Effect channels.
+ *
+ * MessagePack is a compact binary serialization format for protocols and
+ * storage layers that expect bytes rather than JSON text, such as RPC
+ * transports, socket streams, caches, or database columns. This module provides
+ * raw channel helpers for already-agreed value shapes and schema helpers for
+ * validating, transforming, or decoding domain values at the boundary.
+ *
+ * **Mental model**
+ *
+ * - Each input value passed to {@link encode} becomes one MessagePack byte array
+ * - {@link decode} can receive arbitrary byte chunks; incomplete frames are
+ *   buffered until enough bytes arrive
+ * - Schema helpers run Effect schema encoding before packing and schema decoding
+ *   after unpacking
  *
- * 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.
+ * **Common tasks**
  *
- * 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.
+ * - Pack values into bytes: {@link encode}
+ * - Unpack byte chunks into values: {@link decode}
+ * - Encode or decode domain values with schemas: {@link encodeSchema}, {@link decodeSchema}
+ *
+ * **Gotchas**
+ *
+ * - MessagePack preserves binary data better than JSON, but it is not a schema;
+ *   use schema helpers when runtime validation matters
+ * - Packing failures surface as {@link MsgPackError}; schema failures surface as
+ *   `SchemaError` before or after the binary boundary
+ * - Decoding expects complete MessagePack documents over time, not arbitrary
+ *   byte payloads with out-of-band framing
  *
  * @since 4.0.0
  */
@@ -362,7 +377,8 @@ export const duplexSchema: {
 export interface schema<S extends Schema.Top> extends Schema.decodeTo<S, Schema.instanceOf<Uint8Array<ArrayBuffer>>> {}
 
 /**
- * Schema transformation between MessagePack bytes and decoded values.
+ * Schema for decoding MessagePack bytes into values and encoding values back to
+ * MessagePack bytes.
  *
  * **Details**
  *

package/src/unstable/encoding/Ndjson.ts

@@ -1,19 +1,33 @@
 /**
- * Utilities for encoding Effect channel payloads and schema values as
- * newline-delimited JSON.
+ * Encode and decode newline-delimited JSON streams in Effect channels.
+ *
+ * NDJSON represents a stream as one complete JSON value per line. This module
+ * keeps that framing explicit for streaming boundaries: byte helpers handle
+ * UTF-8 transport chunks, string helpers handle already-decoded text, and
+ * schema helpers validate or transform each record at the edge of the pipeline.
+ *
+ * **Mental model**
+ *
+ * - Encoders receive non-empty chunks of values and emit one NDJSON chunk ending
+ *   with a newline
+ * - Decoders accumulate partial lines across input chunks and emit parsed JSON
+ *   records as soon as complete lines are available
+ * - Schema helpers compose channel encoding and decoding with the plain NDJSON
+ *   framing helpers
+ *
+ * **Common tasks**
+ *
+ * - Encode values to UTF-8 bytes: {@link encode}
+ * - Encode values to strings: {@link encodeString}
+ * - Decode UTF-8 bytes or strings: {@link decode}, {@link decodeString}
+ * - Add schema validation at the boundary: {@link encodeSchema}, {@link decodeSchema}
+ *
+ * **Gotchas**
  *
- * 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.
+ * - Records must be valid JSON values, not JavaScript expressions
+ * - Empty lines are ignored only when `ignoreEmptyLines` is enabled
+ * - Encoders append a trailing newline, so downstream consumers should treat it
+ *   as record framing rather than as an extra record
  *
  * @since 4.0.0
  */

package/src/unstable/encoding/Sse.ts

@@ -1,20 +1,41 @@
 /**
  * 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.
+ * SSE is the EventSource wire format used by live updates, notifications,
+ * progress feeds, and other unidirectional server-to-client HTTP streams. This
+ * module provides low-level parser and encoder primitives, channel combinators
+ * for streaming text 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.
+ *
+ * **Mental model**
+ *
+ * - SSE is line-oriented text, not a framed binary protocol.
+ * - Incoming chunks may split fields across arbitrary boundaries, so decoders
+ *   buffer incomplete lines until a full event is available.
+ * - A blank line dispatches an event; repeated `data:` lines are joined with
+ *   newlines.
+ * - `retry:` directives are control messages. Decoders surface them as
+ *   {@link Retry} failures so callers can reconnect with the requested delay.
+ *
+ * **Common tasks**
+ *
+ * - Parse string chunks into {@link Event} values: {@link decode}
+ * - Decode events with a schema: {@link decodeSchema}
+ * - JSON-decode each event `data` field with a schema:
+ *   {@link decodeDataSchema}
+ * - Feed a stateful parser manually: {@link makeParser}
+ * - Encode {@link Event} values as SSE text: {@link encode}, {@link encoder}
+ * - Schema-encode domain values before writing SSE text: {@link encodeSchema}
+ *
+ * **Gotchas**
+ *
+ * - Event `data` is text. Use {@link decodeDataSchema} when the data field
+ *   contains JSON that should be decoded into a domain value.
+ * - The default event name is `message`; the encoder omits the `event:` line
+ *   for that default.
+ * - The decoder handles UTF-8 byte order marks, CRLF and LF line endings, and
+ *   retry directives while preserving the last event ID when available.
  *
  * @since 4.0.0
  */
@@ -467,8 +488,8 @@ export const Event: Schema.Struct<{
 })
 
 /**
- * Schema transformation between the untagged SSE event shape and the tagged
- * `Event` model.
+ * Schema for transforming untagged SSE event payloads into tagged `Event`
+ * models.
  *
  * @category models
  * @since 4.0.0
@@ -507,7 +528,7 @@ export interface EventEncoded {
 const RetryTypeId = "~effect/encoding/Sse/Retry" as const
 
 /**
- * Server-Sent Events retry directive.
+ * Represents a Server-Sent Events retry directive.
  *
  * **Details**
  *

package/src/unstable/encoding/index.ts

@@ -5,65 +5,16 @@
 // @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

@@ -1,19 +1,34 @@
 /**
- * Defines typed event-log events for use with `EventLog` and event groups.
- *
- * An event definition names a durable domain event with a tag, derives the
- * aggregate or entity primary key from the payload, and records the schemas used
- * to encode the payload and decode handler success or failure values. These
- * definitions are the shared contract between clients that write events and
- * servers that register handlers, so they are useful for command-style writes,
- * replicated logs, audit trails, and workflows that need replayable domain
- * facts.
- *
- * Payloads are serialized with MessagePack, while success and error values are
- * described separately for the handler result. Keep payload schemas stable once
- * events have been persisted or replicated, prefer explicit versioned event tags
- * or backward-compatible schemas for changes, and make primary keys deterministic
- * so related entries are grouped consistently across stores and remotes.
+ * Typed event definitions for the unstable event-log system.
+ *
+ * An `Event` is the durable contract shared by writers, handlers, journals, and
+ * replicas. It gives an event a stable tag, derives the aggregate or entity
+ * primary key from the decoded payload, and records the schemas used for the
+ * payload and handler result. The payload schema also derives the MessagePack
+ * schema used when entries are written to an event journal or sent to a remote
+ * replica.
+ *
+ * **Mental model**
+ *
+ * The tag names the event kind, the primary key chooses the partition or entity
+ * affected by the event, the payload schema describes the persisted fact, and
+ * the success and error schemas describe the handler boundary. Type helpers in
+ * this module derive payload, success, error, and service types from either a
+ * single event definition or a union selected by tag.
+ *
+ * **Common tasks**
+ *
+ * Use `make` to define a single event, `addError` to add a shared handler error
+ * to an existing definition, and the tag-based helper types when a client or
+ * server API needs the payload, success, or error type for one event in a group.
+ *
+ * **Gotchas**
+ *
+ * Persisted tags and payload schemas should remain stable. Prefer a new tag or a
+ * backward-compatible schema when an event shape changes, and keep
+ * `primaryKey` deterministic so related entries group consistently across
+ * local journals and remote replicas. Omitted payload and success schemas
+ * default to `Schema.Void`; omitted error schemas default to `Schema.Never`.
  *
  * @since 4.0.0
  */