effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/encoding/Sse.ts

@@ -22,6 +22,72 @@ import * as Result from "../../Result.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaTransformation from "../../SchemaTransformation.ts"
 
+const SseErrorTypeId = "~effect/encoding/Sse/SseError"
+
+/**
+ * Error reason raised when pending Server-Sent Events state exceeds the
+ * configured maximum size.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export class EventTooLarge extends Data.TaggedError("EventTooLarge")<{
+  readonly maxEventSize: number
+}> {
+  override get message() {
+    return `Pending SSE event exceeded the maximum size of ${this.maxEventSize}`
+  }
+}
+
+/**
+ * Union of Server-Sent Events decoding error reasons.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export type SseErrorReason = EventTooLarge
+
+/**
+ * Error raised when decoding a Server-Sent Events stream fails.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export class SseError extends Data.TaggedError("SseError")<{
+  readonly reason: SseErrorReason
+}> {
+  /**
+   * Marks this value as an SSE decoding error.
+   *
+   * @since 4.0.0
+   */
+  readonly [SseErrorTypeId] = SseErrorTypeId
+
+  /**
+   * Delegates the public message to the underlying SSE error reason.
+   *
+   * @since 4.0.0
+   */
+  override get message() {
+    return this.reason.message
+  }
+}
+
+/**
+ * Options for decoding Server-Sent Events streams.
+ *
+ * @category decoding
+ * @since 4.0.0
+ */
+export interface DecodeOptions {
+  /**
+   * Maximum number of string code units retained for a pending event. The default is 10 MiB.
+   */
+  readonly maxEventSize?: number | undefined
+}
+
+const defaultMaxEventSize = 10 * 1024 * 1024
+
 /**
  * Creates a channel that parses Server-Sent Events text chunks into `Event` values.
  *
@@ -33,9 +99,9 @@ import * as SchemaTransformation from "../../SchemaTransformation.ts"
  * @category decoding
  * @since 4.0.0
  */
-export const decode = <IE, Done>(): Channel.Channel<
+export const decode = <IE, Done>(options?: DecodeOptions): Channel.Channel<
   NonEmptyReadonlyArray<Event>,
-  IE | Retry,
+  IE | Retry | SseError,
   Done,
   NonEmptyReadonlyArray<string>,
   IE,
@@ -51,16 +117,19 @@ export const decode = <IE, Done>(): Channel.Channel<
         } else {
           buffer.push(event)
         }
-      })
+      }, options)
 
       const pump = Effect.flatMap(upstream, (arr) => {
         for (let i = 0; i < arr.length; i++) {
-          parser.feed(arr[i])
+          const error = parser.feed(arr[i])
+          if (error !== undefined) {
+            return Effect.fail(error)
+          }
         }
         return Effect.void
       })
 
-      return Effect.suspend(function loop(): Pull.Pull<NonEmptyReadonlyArray<Event>, IE | Retry, Done> {
+      return Effect.suspend(function loop(): Pull.Pull<NonEmptyReadonlyArray<Event>, IE | Retry | SseError, Done> {
         if (Arr.isArrayNonEmpty(buffer)) {
           const out = buffer
           buffer = []
@@ -108,10 +177,11 @@ export const decodeSchema = <
   IE,
   Done
 >(
-  schema: S
+  schema: S,
+  options?: DecodeOptions
 ): Channel.Channel<
   NonEmptyReadonlyArray<S["Type"]>,
-  IE | Retry | Schema.SchemaError,
+  IE | Retry | SseError | Schema.SchemaError,
   Done,
   NonEmptyReadonlyArray<string>,
   IE,
@@ -119,7 +189,7 @@ export const decodeSchema = <
   S["DecodingServices"]
 > =>
   Channel.pipeTo(
-    decode<IE, Done>(),
+    decode<IE, Done>(options),
     ChannelSchema.decode(EventEncoded.pipe(
       Schema.decodeTo(schema)
     ))()
@@ -137,14 +207,15 @@ export const decodeSchema = <
  * @since 4.0.0
  */
 export const decodeDataSchema = <Type, DecodingServices, IE, Done>(
-  schema: Schema.ConstraintDecoder<Type, DecodingServices>
+  schema: Schema.ConstraintDecoder<Type, DecodingServices>,
+  options?: DecodeOptions
 ): Channel.Channel<
   NonEmptyReadonlyArray<{
     readonly event: string
     readonly id: string | undefined
     readonly data: Type
   }>,
-  IE | Retry | Schema.SchemaError,
+  IE | Retry | SseError | Schema.SchemaError,
   Done,
   NonEmptyReadonlyArray<string>,
   IE,
@@ -156,7 +227,7 @@ export const decodeDataSchema = <Type, DecodingServices, IE, Done>(
     data: Schema.fromJsonString(schema)
   })
   return Channel.pipeTo(
-    decode<IE, Done>(),
+    decode<IE, Done>(options),
     Channel.map(
       ChannelSchema.decode(eventSchema)(),
       Arr.map((event) => ({ ...event, id: event.id }))
@@ -170,12 +241,15 @@ export const decodeDataSchema = <Type, DecodingServices, IE, Done>(
  * **Details**
  *
  * Call `feed` with text chunks to parse `Event` and `Retry` values through the
- * callback, and call `reset` to clear any buffered event state.
+ * callback, and call `reset` to clear any buffered event state. `feed` returns
+ * an `SseError` if the pending event exceeds `maxEventSize`.
  *
  * @category decoding
  * @since 4.0.0
  */
-export function makeParser(onParse: (event: AnyEvent) => void): Parser {
+export function makeParser(onParse: (event: AnyEvent) => void, options?: DecodeOptions): Parser {
+  const maxEventSize = options?.maxEventSize ?? defaultMaxEventSize
+
   // Processing state
   let isFirstChunk: boolean
   let buffer: string
@@ -202,7 +276,7 @@ export function makeParser(onParse: (event: AnyEvent) => void): Parser {
     data = ""
   }
 
-  function feed(chunk: string): void {
+  function feed(chunk: string): SseError | undefined {
     buffer = buffer ? buffer + chunk : chunk
 
     // Strip any UTF8 byte order mark (BOM) at the start of the stream.
@@ -271,6 +345,12 @@ export function makeParser(onParse: (event: AnyEvent) => void): Parser {
       // portion of the buffer only
       buffer = buffer.slice(position)
     }
+
+    if (buffer.length + data.length > maxEventSize) {
+      const error = new SseError({ reason: new EventTooLarge({ maxEventSize }) })
+      reset()
+      return error
+    }
   }
 
   function parseEventStreamLine(
@@ -338,13 +418,15 @@ function hasBom(buffer: string) {
  *
  * **Details**
  *
- * `feed` accepts additional text chunks and `reset` clears buffered parser state.
+ * `feed` accepts additional text chunks and returns an `SseError` when the
+ * configured pending event size is exceeded. `reset` clears buffered parser
+ * state.
  *
  * @category decoding
  * @since 4.0.0
  */
 export interface Parser {
-  feed(chunk: string): void
+  feed(chunk: string): SseError | undefined
   reset(): void
 }
 

package/src/unstable/eventlog/Event.ts

@@ -114,7 +114,7 @@ export interface AnyWithProps extends Any {}
 /**
  * Derives the handler service marker for an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ToService<A> = A extends Event<
@@ -128,7 +128,7 @@ export type ToService<A> = A extends Event<
 /**
  * Extracts the tag string from an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Tag<A> = A extends Event<
@@ -142,7 +142,7 @@ export type Tag<A> = A extends Event<
 /**
  * Extracts the error schema from an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorSchema<A extends Any> = A extends Event<
@@ -156,7 +156,7 @@ export type ErrorSchema<A extends Any> = A extends Event<
 /**
  * Decoded error value type for an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Error<A extends Any> = Schema.Schema.Type<ErrorSchema<A>>
@@ -165,7 +165,7 @@ export type Error<A extends Any> = Schema.Schema.Type<ErrorSchema<A>>
  * Returns an event definition type whose error schema also includes the provided
  * error schema.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type AddError<A extends Any, Error extends Schema.Top> = A extends Event<
@@ -179,7 +179,7 @@ export type AddError<A extends Any, Error extends Schema.Top> = A extends Event<
 /**
  * Extracts the payload schema from an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type PayloadSchema<A extends Any> = A extends Event<
@@ -193,7 +193,7 @@ export type PayloadSchema<A extends Any> = A extends Event<
 /**
  * Extracts the payload schema for the event in a union with the specified tag.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type PayloadSchemaWithTag<A extends Any, Tag extends string> = A extends Event<
@@ -207,7 +207,7 @@ export type PayloadSchemaWithTag<A extends Any, Tag extends string> = A extends
 /**
  * Decoded payload value type for an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Payload<A extends Any> = Schema.Schema.Type<PayloadSchema<A>>
@@ -220,7 +220,7 @@ export type Payload<A extends Any> = Schema.Schema.Type<PayloadSchema<A>>
  * The result contains `_tag` set to the event tag and `payload` set to the
  * decoded payload value.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type TaggedPayload<A extends Any> = A extends Event<
@@ -237,7 +237,7 @@ export type TaggedPayload<A extends Any> = A extends Event<
 /**
  * Extracts the success schema from an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type SuccessSchema<A extends Any> = A extends Event<
@@ -251,7 +251,7 @@ export type SuccessSchema<A extends Any> = A extends Event<
 /**
  * Decoded success value type for an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Success<A extends Any> = Schema.Schema.Type<SuccessSchema<A>>
@@ -264,7 +264,7 @@ export type Success<A extends Any> = Schema.Schema.Type<SuccessSchema<A>>
  * This includes payload encoding services plus success and error decoding
  * services.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ServicesClient<A> = A extends Event<
@@ -286,7 +286,7 @@ export type ServicesClient<A> = A extends Event<
  * This includes payload decoding services plus success and error encoding
  * services.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ServicesServer<A> = A extends Event<
@@ -304,7 +304,7 @@ export type ServicesServer<A> = A extends Event<
  * All schema services required to encode and decode the payload, success, and
  * error schemas for an event definition.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Services<A> = A extends Event<
@@ -324,7 +324,7 @@ export type Services<A> = A extends Event<
 /**
  * Extracts the event definition with the specified tag from an event union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type WithTag<Events extends Any, Tag extends string> = Extract<Events, { readonly tag: Tag }>
@@ -332,7 +332,7 @@ export type WithTag<Events extends Any, Tag extends string> = Extract<Events, {
 /**
  * Removes event definitions with the specified tag from an event union.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ExcludeTag<Events extends Any, Tag extends string> = Exclude<Events, { readonly tag: Tag }>
@@ -340,7 +340,7 @@ export type ExcludeTag<Events extends Any, Tag extends string> = Exclude<Events,
 /**
  * Decoded payload value type for the event in a union with the specified tag.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type PayloadWithTag<Events extends Any, Tag extends string> = Payload<WithTag<Events, Tag>>
@@ -348,7 +348,7 @@ export type PayloadWithTag<Events extends Any, Tag extends string> = Payload<Wit
 /**
  * Decoded success value type for the event in a union with the specified tag.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type SuccessWithTag<Events extends Any, Tag extends string> = Success<WithTag<Events, Tag>>
@@ -356,7 +356,7 @@ export type SuccessWithTag<Events extends Any, Tag extends string> = Success<Wit
 /**
  * Decoded error value type for the event in a union with the specified tag.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorWithTag<Events extends Any, Tag extends string> = Error<WithTag<Events, Tag>>
@@ -365,7 +365,7 @@ export type ErrorWithTag<Events extends Any, Tag extends string> = Error<WithTag
  * Client-side schema services required for the event in a union with the specified
  * tag.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ServicesClientWithTag<Events extends Any, Tag extends string> = ServicesClient<WithTag<Events, Tag>>

package/src/unstable/eventlog/EventGroup.ts

@@ -100,7 +100,7 @@ export type AnyWithProps = EventGroup<Event.Any>
 /**
  * Derives the handler service markers required for all events in an event group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ToService<A> = A extends EventGroup<infer _Events> ? Event.ToService<_Events>
@@ -109,7 +109,7 @@ export type ToService<A> = A extends EventGroup<infer _Events> ? Event.ToService
 /**
  * Extracts the union of event definitions contained in an event group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Events<Group> = Group extends EventGroup<infer _Events> ? _Events
@@ -118,7 +118,7 @@ export type Events<Group> = Group extends EventGroup<infer _Events> ? _Events
 /**
  * Client-side schema services required by all events in an event group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ServicesClient<Group> = Event.ServicesClient<Events<Group>>
@@ -126,7 +126,7 @@ export type ServicesClient<Group> = Event.ServicesClient<Events<Group>>
 /**
  * Server-side schema services required by all events in an event group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ServicesServer<Group> = Event.ServicesServer<Events<Group>>

package/src/unstable/eventlog/EventJournal.ts

@@ -34,7 +34,7 @@ import type { StoreId } from "./EventLogMessage.ts"
  * The service writes local entries, imports entries from remote journals, exposes
  * a stream of local changes, and provides per-store locking.
  *
- * @category context
+ * @category services
  * @since 4.0.0
  */
 export class EventJournal extends Context.Service<EventJournal, {
@@ -149,7 +149,7 @@ export const RemoteIdTypeId: RemoteIdTypeId = "effect/eventlog/EventJournal/Remo
 /**
  * Branded byte identifier for a remote event journal source.
  *
- * @category remote
+ * @category models
  * @since 4.0.0
  */
 export type RemoteId = Uint8Array & Brand<RemoteIdTypeId>
@@ -157,7 +157,7 @@ export type RemoteId = Uint8Array & Brand<RemoteIdTypeId>
 /**
  * Schema for branded remote event journal identifiers.
  *
- * @category remote
+ * @category schemas
  * @since 4.0.0
  */
 export const RemoteId = Schema.Uint8Array.pipe(Schema.brand(RemoteIdTypeId))
@@ -175,7 +175,7 @@ export const RemoteId = Schema.Uint8Array.pipe(Schema.brand(RemoteIdTypeId))
  * This is unsafe because the generated UUID bytes are cast to the brand without
  * schema validation.
  *
- * @category remote
+ * @category unsafe
  * @since 4.0.0
  */
 export const makeRemoteIdUnsafe = (): RemoteId => Uuid.v4({}, new globalThis.Uint8Array(16)) as RemoteId
@@ -199,7 +199,7 @@ export type EntryIdTypeId = "effect/eventlog/EventJournal/EntryId"
 /**
  * Branded byte identifier for an event journal entry.
  *
- * @category entry
+ * @category models
  * @since 4.0.0
  */
 export type EntryId = Uint8Array<ArrayBuffer> & Brand<EntryIdTypeId>
@@ -207,7 +207,7 @@ export type EntryId = Uint8Array<ArrayBuffer> & Brand<EntryIdTypeId>
 /**
  * Schema for branded event journal entry identifiers.
  *
- * @category entry
+ * @category schemas
  * @since 4.0.0
  */
 export const EntryId = (Schema.Uint8Array as Schema.instanceOf<Uint8Array<ArrayBuffer>>).pipe(
@@ -217,7 +217,7 @@ export const EntryId = (Schema.Uint8Array as Schema.instanceOf<Uint8Array<ArrayB
 /**
  * Provides an Ordering instance for entry identifiers based on their raw UUID bytes.
  *
- * @category entry
+ * @category ordering
  * @since 4.0.0
  */
 export const EntryIdOrder = Order.make<EntryId>((a, b) => {
@@ -243,7 +243,7 @@ export const EntryIdOrder = Order.make<EntryId>((a, b) => {
  * This is unsafe because the generated UUID bytes are cast to the brand without
  * schema validation.
  *
- * @category entry
+ * @category unsafe
  * @since 4.0.0
  */
 export const makeEntryIdUnsafe = (options: { msecs?: number } = {}): EntryId =>
@@ -252,7 +252,7 @@ export const makeEntryIdUnsafe = (options: { msecs?: number } = {}): EntryId =>
 /**
  * Extracts the millisecond timestamp encoded in a UUID v7 `EntryId`.
  *
- * @category entry
+ * @category getters
  * @since 4.0.0
  */
 export const entryIdMillis = (entryId: EntryId): number => {
@@ -269,7 +269,7 @@ export const entryIdMillis = (entryId: EntryId): number => {
  * An entry records its ID, event tag, primary key, and MessagePack-encoded
  * payload, with helpers for array MessagePack encoding and creation timestamps.
  *
- * @category entry
+ * @category schemas
  * @since 4.0.0
  */
 export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Entry")({
@@ -341,7 +341,7 @@ export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Ent
  *
  * It pairs the remote sequence number with the journal entry payload.
  *
- * @category entry
+ * @category schemas
  * @since 4.0.0
  */
 export class RemoteEntry extends Schema.Class<RemoteEntry>("effect/eventlog/EventJournal/RemoteEntry")({
@@ -357,7 +357,7 @@ export class RemoteEntry extends Schema.Class<RemoteEntry>("effect/eventlog/Even
  * Entries, remote tracking state, and locks live only in the current process and
  * are lost when the service is discarded.
  *
- * @category memory
+ * @category constructors
  * @since 4.0.0
  */
 export const makeMemory: Effect.Effect<EventJournal["Service"]> = Effect.gen(function*() {
@@ -497,7 +497,7 @@ export const makeMemory: Effect.Effect<EventJournal["Service"]> = Effect.gen(fun
  * All journal data is stored in process memory and is not persisted across layer
  * lifetimes.
  *
- * @category memory
+ * @category layers
  * @since 4.0.0
  */
 export const layerMemory: Layer.Layer<EventJournal> = Layer.effect(EventJournal, makeMemory)
@@ -511,7 +511,7 @@ export const layerMemory: Layer.Layer<EventJournal> = Layer.effect(EventJournal,
  * browser database, publishes local changes, and requires `Scope` so the database
  * connection can be closed when the scope ends.
  *
- * @category indexed db
+ * @category constructors
  * @since 4.0.0
  */
 export const makeIndexedDb = (options?: {
@@ -772,7 +772,7 @@ const decodeEntryIdbArray = Schema.decodeUnknownEffect(EntryIdbArray)
  * Provides `EventJournal` using the IndexedDB-backed implementation created by
  * `makeIndexedDb`.
  *
- * @category indexed db
+ * @category layers
  * @since 4.0.0
  */
 export const layerIndexedDb = (options?: {

package/src/unstable/eventlog/EventLog.ts

@@ -205,7 +205,7 @@ export const SchemaTypeId: SchemaTypeId = "~effect/eventlog/EventLog/Schema"
 /**
  * Returns `true` when a value carries the `EventLogSchema` marker.
  *
- * @category schemas
+ * @category guards
  * @since 4.0.0
  */
 export const isEventLogSchema = (u: unknown): u is EventLogSchema<EventGroup.Any> =>
@@ -410,7 +410,7 @@ export declare namespace Handlers {
  *
  * Defaults to the branded store id `"default"`.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export class CurrentStoreId extends Context.Reference<StoreId>("effect/eventlog/EventLog/CurrentStoreId", {
@@ -1012,7 +1012,7 @@ export const layer = <Groups extends EventGroup.Any, E, R>(
  * The returned function delegates to the `EventLog` service and preserves each
  * event's success and error types.
  *
- * @category client
+ * @category constructors
  * @since 4.0.0
  */
 export const makeClient = <Groups extends EventGroup.Any>(

package/src/unstable/eventlog/EventLogEncryption.ts

@@ -160,7 +160,7 @@ export const makeEncryptionSubtle = (crypto: Crypto): Effect.Effect<EventLogEncr
 /**
  * Provides `EventLogEncryption` using `globalThis.crypto`.
  *
- * @category encryption
+ * @category layers
  * @since 4.0.0
  */
 export const layerSubtle: Layer.Layer<EventLogEncryption> = Layer.effect(

package/src/unstable/eventlog/EventLogMessage.ts

@@ -39,7 +39,7 @@ export const StoreIdTypeId: StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
 /**
  * Branded string identifying a logical event-log store.
  *
- * @category StoreId
+ * @category models
  * @since 4.0.0
  */
 export type StoreId = string & Brand<StoreIdTypeId>
@@ -47,7 +47,7 @@ export type StoreId = string & Brand<StoreIdTypeId>
 /**
  * Schema for branded event-log store ids.
  *
- * @category StoreId
+ * @category schemas
  * @since 4.0.0
  */
 export const StoreId = Schema.String.pipe(Schema.brand(StoreIdTypeId))

package/src/unstable/eventlog/EventLogRemote.ts

@@ -119,7 +119,7 @@ const makeAuthenticate = Effect.fnUntraced(function*(options: {
  * Use to provide the RPC client used by remote event-log replicas to
  * authenticate, write entries, and subscribe to changes.
  *
- * @category RPC client
+ * @category services
  * @since 4.0.0
  */
 export class EventLogRemoteClient extends Context.Service<