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

package/src/unstable/encoding/Sse.ts

@@ -1,4 +1,21 @@
 /**
+ * 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
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -16,8 +33,14 @@ import * as Schema from "../../Schema.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
 
 /**
- * @since 4.0.0
+ * Creates a channel that parses Server-Sent Events text chunks into `Event`
+ * values.
+ *
+ * SSE `retry` directives are emitted as `Retry` failures so callers can
+ * reconnect with the requested delay.
+ *
  * @category Decoding
+ * @since 4.0.0
  */
 export const decode = <IE, Done>(): Channel.Channel<
   NonEmptyReadonlyArray<Event>,
@@ -60,8 +83,13 @@ export const decode = <IE, Done>(): Channel.Channel<
   )
 
 /**
- * @since 4.0.0
+ * Creates an SSE decoder channel that decodes each parsed event with a schema.
+ *
+ * The schema receives the untagged event shape containing `id`, `event`, and
+ * string `data`.
+ *
  * @category Decoding
+ * @since 4.0.0
  */
 export const decodeSchema = <
   Type extends {
@@ -91,8 +119,14 @@ export const decodeSchema = <
   )
 
 /**
- * @since 4.0.0
+ * Creates an SSE decoder channel that JSON-decodes each event `data` field with
+ * a schema.
+ *
+ * The output preserves the SSE `event` name and optional `id` while replacing
+ * `data` with the decoded value.
+ *
  * @category Decoding
+ * @since 4.0.0
  */
 export const decodeDataSchema = <Type, DecodingServices, IE, Done>(
   schema: Schema.Decoder<Type, DecodingServices>
@@ -120,12 +154,13 @@ export const decodeDataSchema = <Type, DecodingServices, IE, Done>(
 }
 
 /**
- * Create a SSE parser.
+ * Creates a stateful Server-Sent Events parser.
  *
- * Adapted from https://github.com/rexxars/eventsource-parser under MIT license.
+ * Call `feed` with text chunks to parse `Event` and `Retry` values through the
+ * callback, and call `reset` to clear any buffered event state.
  *
- * @since 4.0.0
  * @category Decoding
+ * @since 4.0.0
  */
 export function makeParser(onParse: (event: AnyEvent) => void): Parser {
   // Processing state
@@ -286,8 +321,12 @@ function hasBom(buffer: string) {
 }
 
 /**
- * @since 4.0.0
+ * Stateful Server-Sent Events parser returned by `makeParser`.
+ *
+ * `feed` accepts additional text chunks and `reset` clears buffered parser state.
+ *
  * @category Decoding
+ * @since 4.0.0
  */
 export interface Parser {
   feed(chunk: string): void
@@ -295,8 +334,13 @@ export interface Parser {
 }
 
 /**
- * @since 4.0.0
+ * Creates a channel that encodes `Event` values as Server-Sent Events text.
+ *
+ * If the upstream channel fails with `Retry`, the retry directive is written and
+ * the encoder completes.
+ *
  * @category Encoding
+ * @since 4.0.0
  */
 export const encode = <IE, Done>(): Channel.Channel<
   NonEmptyReadonlyArray<string>,
@@ -322,8 +366,13 @@ export const encode = <IE, Done>(): Channel.Channel<
   )
 
 /**
- * @since 4.0.0
+ * Creates an SSE encoder channel for values accepted by a schema.
+ *
+ * Values are schema-encoded to the untagged SSE event shape, transformed to
+ * `Event`, and then written as Server-Sent Events text.
+ *
  * @category Encoding
+ * @since 4.0.0
  */
 export const encodeSchema = <
   S extends Schema.Encoder<
@@ -348,16 +397,23 @@ export const encodeSchema = <
   )
 
 /**
- * @since 4.0.0
+ * Encoder capable of rendering an `Event` or `Retry` value as Server-Sent
+ * Events text.
+ *
  * @category Encoding
+ * @since 4.0.0
  */
 export interface Encoder {
   write(event: AnyEvent): string
 }
 
 /**
- * @since 4.0.0
+ * Tagged model for a Server-Sent Events message.
+ *
+ * It contains the event name, optional event ID, and string data payload.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface Event {
   readonly _tag: "Event"
@@ -367,8 +423,12 @@ export interface Event {
 }
 
 /**
- * @since 4.0.0
+ * Schema for the untagged Server-Sent Events payload shape.
+ *
+ * The shape contains `id`, `event`, and string `data` fields.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export const EventEncoded: Schema.Struct<{
   readonly id: Schema.UndefinedOr<Schema.String>
@@ -381,8 +441,13 @@ export const EventEncoded: Schema.Struct<{
 })
 
 /**
- * @since 4.0.0
+ * Schema for the tagged Server-Sent Events message model.
+ *
+ * The schema adds `_tag: "Event"` to the event name, optional event ID, and
+ * string data payload.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export const Event: Schema.Struct<{
   readonly _tag: Schema.tag<"Event">
@@ -397,8 +462,11 @@ export const Event: Schema.Struct<{
 })
 
 /**
- * @since 4.0.0
+ * Schema transformation between the untagged SSE event shape and the tagged
+ * `Event` model.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export const transformEvent = Transformation.transform<{
   readonly id?: string | undefined
@@ -420,8 +488,12 @@ export const transformEvent = Transformation.transform<{
 })
 
 /**
- * @since 4.0.0
+ * Untagged Server-Sent Events payload shape.
+ *
+ * It contains the event name, optional event ID, and string data payload.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface EventEncoded {
   readonly event: string
@@ -432,24 +504,35 @@ export interface EventEncoded {
 const RetryTypeId = "~effect/encoding/Sse/Retry" as const
 
 /**
- * @since 4.0.0
+ * Server-Sent Events retry directive.
+ *
+ * Decoders surface this value as a failure to request reconnection after
+ * `duration`; encoders serialize an upstream `Retry` failure as a `retry:` line.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class Retry extends Data.TaggedClass("Retry")<{
   readonly duration: Duration.Duration
   readonly lastEventId: string | undefined
 }> {
   /**
+   * Marks this value as an SSE retry directive for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [RetryTypeId]: typeof RetryTypeId = RetryTypeId
   /**
+   * Returns `true` when the value is an SSE retry directive.
+   *
    * @since 4.0.0
    */
   static is(u: unknown): u is Retry {
     return hasProperty(u, RetryTypeId)
   }
   /**
+   * Separates SSE retry directives from regular event values.
+   *
    * @since 4.0.0
    */
   static filter<A>(u: A): Result.Result<Retry, Exclude<A, Retry>> {
@@ -458,14 +541,22 @@ export class Retry extends Data.TaggedClass("Retry")<{
 }
 
 /**
- * @since 4.0.0
+ * Union of SSE values that can be rendered by an `Encoder`: regular events and
+ * retry directives.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export type AnyEvent = Event | Retry
 
 /**
- * @since 4.0.0
+ * Default Server-Sent Events encoder.
+ *
+ * It renders `Event` values as `id`, `event`, and `data` lines and renders
+ * `Retry` values as `retry:` directives.
+ *
  * @category Encoding
+ * @since 4.0.0
  */
 export const encoder: Encoder = {
   write(event: AnyEvent): string {

package/src/unstable/eventlog/Event.ts

@@ -1,4 +1,20 @@
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 import { pipeArguments } from "../../Pipeable.ts"
@@ -7,28 +23,37 @@ import * as Schema from "../../Schema.ts"
 import * as Msgpack from "../encoding/Msgpack.ts"
 
 /**
- * @since 4.0.0
+ * Unique type identifier used to mark event log event definitions.
+ *
  * @category type ids
+ * @since 4.0.0
  */
 export type TypeId = "~effect/eventlog/Event"
 
 /**
- * @since 4.0.0
+ * Runtime type identifier used to mark event log event definitions.
+ *
  * @category type ids
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/eventlog/Event"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is an event log event definition.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isEvent = (u: unknown): u is Event<any, any, any, any> => Predicate.hasProperty(u, TypeId)
 
 /**
- * Represents an event in an EventLog.
+ * Definition of an event type that can be written to an `EventLog`.
+ *
+ * An event definition contains its tag, primary-key function, payload schema,
+ * MessagePack payload schema, success schema, and error schema.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Event<
   out Tag extends string,
@@ -46,8 +71,13 @@ export interface Event<
 }
 
 /**
- * @since 4.0.0
+ * Marker service associated with the handler for an event tag.
+ *
+ * `ToService` derives this service from an `Event` so handler layers can expose
+ * which events they implement.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface EventHandler<in out Tag extends string> {
   readonly _: unique symbol
@@ -55,8 +85,13 @@ export interface EventHandler<in out Tag extends string> {
 }
 
 /**
- * @since 4.0.0
+ * Type-erased event log event definition.
+ *
+ * It preserves the runtime tag, primary-key function, payload schema, success
+ * schema, and error schema without retaining the original type parameters.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: TypeId
@@ -69,14 +104,19 @@ export interface Any {
 }
 
 /**
- * @since 4.0.0
+ * Type-erased event definition with its runtime properties available
+ * structurally.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyWithProps extends Any {}
 
 /**
- * @since 4.0.0
+ * Derives the handler service marker for an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ToService<A> = A extends Event<
   infer _Tag,
@@ -87,8 +127,10 @@ export type ToService<A> = A extends Event<
   never
 
 /**
- * @since 4.0.0
+ * Extracts the tag string from an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Tag<A> = A extends Event<
   infer _Tag,
@@ -99,8 +141,10 @@ export type Tag<A> = A extends Event<
   never
 
 /**
- * @since 4.0.0
+ * Extracts the error schema from an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorSchema<A extends Any> = A extends Event<
   infer _Tag,
@@ -111,14 +155,19 @@ export type ErrorSchema<A extends Any> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * Decoded error value type for an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Error<A extends Any> = Schema.Schema.Type<ErrorSchema<A>>
 
 /**
- * @since 4.0.0
+ * Returns an event definition type whose error schema also includes the provided
+ * error schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AddError<A extends Any, Error extends Schema.Top> = A extends Event<
   infer _Tag,
@@ -129,8 +178,10 @@ export type AddError<A extends Any, Error extends Schema.Top> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the payload schema from an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PayloadSchema<A extends Any> = A extends Event<
   infer _Tag,
@@ -141,8 +192,10 @@ export type PayloadSchema<A extends Any> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the payload schema for the event in a union with the specified tag.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PayloadSchemaWithTag<A extends Any, Tag extends string> = A extends Event<
   Tag,
@@ -153,14 +206,21 @@ export type PayloadSchemaWithTag<A extends Any, Tag extends string> = A extends
   : never
 
 /**
- * @since 4.0.0
+ * Decoded payload value type for an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Payload<A extends Any> = Schema.Schema.Type<PayloadSchema<A>>
 
 /**
- * @since 4.0.0
+ * Tagged payload value for an event definition.
+ *
+ * The result contains `_tag` set to the event tag and `payload` set to the
+ * decoded payload value.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type TaggedPayload<A extends Any> = A extends Event<
   infer _Tag,
@@ -174,8 +234,10 @@ export type TaggedPayload<A extends Any> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the success schema from an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type SuccessSchema<A extends Any> = A extends Event<
   infer _Tag,
@@ -186,14 +248,21 @@ export type SuccessSchema<A extends Any> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * Decoded success value type for an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Success<A extends Any> = Schema.Schema.Type<SuccessSchema<A>>
 
 /**
- * @since 4.0.0
+ * Schema services required by a client for an event definition.
+ *
+ * This includes payload encoding services plus success and error decoding
+ * services.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ServicesClient<A> = A extends Event<
   infer _Tag,
@@ -207,8 +276,13 @@ export type ServicesClient<A> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * Schema services required by a server for an event definition.
+ *
+ * This includes payload decoding services plus success and error encoding
+ * services.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ServicesServer<A> = A extends Event<
   infer _Tag,
@@ -222,8 +296,11 @@ export type ServicesServer<A> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * All schema services required to encode and decode the payload, success, and
+ * error schemas for an event definition.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Services<A> = A extends Event<
   infer _Tag,
@@ -240,38 +317,51 @@ export type Services<A> = A extends Event<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the event definition with the specified tag from an event union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type WithTag<Events extends Any, Tag extends string> = Extract<Events, { readonly tag: Tag }>
 
 /**
- * @since 4.0.0
+ * Removes event definitions with the specified tag from an event union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ExcludeTag<Events extends Any, Tag extends string> = Exclude<Events, { readonly tag: Tag }>
 
 /**
- * @since 4.0.0
+ * Decoded payload value type for the event in a union with the specified tag.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PayloadWithTag<Events extends Any, Tag extends string> = Payload<WithTag<Events, Tag>>
 
 /**
- * @since 4.0.0
+ * Decoded success value type for the event in a union with the specified tag.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type SuccessWithTag<Events extends Any, Tag extends string> = Success<WithTag<Events, Tag>>
 
 /**
- * @since 4.0.0
+ * Decoded error value type for the event in a union with the specified tag.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorWithTag<Events extends Any, Tag extends string> = Error<WithTag<Events, Tag>>
 
 /**
- * @since 4.0.0
+ * Client-side schema services required for the event in a union with the specified
+ * tag.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ServicesClientWithTag<Events extends Any, Tag extends string> = ServicesClient<WithTag<Events, Tag>>
 
@@ -283,8 +373,14 @@ const Proto = {
 }
 
 /**
- * @since 4.0.0
+ * Creates an event log event definition.
+ *
+ * If omitted, the payload and success schemas default to `Schema.Void`, the error
+ * schema defaults to `Schema.Never`, and the MessagePack payload schema is derived
+ * from the payload schema.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export function make<
   Tag extends string,
@@ -319,8 +415,13 @@ export function make(options: {
 }
 
 /**
- * @since 4.0.0
+ * Adds another error schema to an event definition.
+ *
+ * The returned event keeps the same tag, primary key, payload, and success schema
+ * while replacing the error schema with a union of the existing and new errors.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export function addError<A extends Any, Error2 extends Schema.Top>(
   event: A,