effect 4.0.0-beta.80 → 4.0.0-beta.82

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -10,9 +10,12 @@
  * @since 4.0.0
  */
 import { constVoid, type LazyArg } from "../../Function.ts"
+import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaAST from "../../SchemaAST.ts"
 import * as SchemaTransformation from "../../SchemaTransformation.ts"
+import * as Stream from "../../Stream.ts"
+import type * as Sse from "../encoding/Sse.ts"
 import { hasBody, type HttpMethod } from "../http/HttpMethod.ts"
 import type * as Multipart_ from "../http/Multipart.ts"
 
@@ -125,6 +128,8 @@ const statusCodeByLiteral = {
   NetworkAuthenticationRequired: 511
 } as const
 
+const StreamSchemaTypeId = "~effect/httpapi/HttpApiSchema/Stream"
+
 /**
  * Common HTTP status code literals accepted by {@link status}.
  *
@@ -145,13 +150,15 @@ export type StatusLiteral = keyof typeof statusCodeByLiteral
  * @category status
  * @since 4.0.0
  */
-export function status(code: number): <S extends Schema.Top>(self: S) => S["Rebuild"]
-export function status(code: StatusLiteral): <S extends Schema.Top>(self: S) => S["Rebuild"]
+export function status(code: number): {
+  <S extends Schema.Top>(self: S): S["Rebuild"]
+}
+export function status(code: StatusLiteral): {
+  <S extends Schema.Top>(self: S): S["Rebuild"]
+}
 export function status(code: number | StatusLiteral) {
   const statusCode = typeof code === "string" ? statusCodeByLiteral[code] : code
-  return <S extends Schema.Top>(self: S): S["Rebuild"] => {
-    return self.annotate({ httpApiStatus: statusCode })
-  }
+  return <S extends Schema.Top>(self: S): S["Rebuild"] => self.annotate({ httpApiStatus: statusCode })
 }
 
 /**
@@ -251,6 +258,238 @@ export function asNoContent<S extends Schema.Top>(options: {
   }
 }
 
+type StreamMode = "sse" | "uint8array"
+
+/**
+ * Mode describing whether an SSE stream emits full events or raw data values.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type StreamSseMode = "events" | "data"
+
+/**
+ * Schema for a Server-Sent Events success response.
+ *
+ * **Details**
+ *
+ * `events` describes successful application events emitted by the stream, and
+ * `error` describes typed stream failures that will be encoded by later
+ * endpoint/server/client integrations using the reserved failure event. If
+ * `error` is omitted, it defaults to `Schema.Never`. When `StreamSse` is
+ * constructed from `data`, handlers and clients expose raw data values while
+ * the server and client still use an SSE event schema internally.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface StreamSse<
+  Events extends Sse.EventCodec,
+  Error extends Schema.Top,
+  Value = Events["Type"]
+> extends
+  Schema.Bottom<
+    Stream.Stream<Value, Error["Type"], never>,
+    Stream.Stream<Value, Error["Type"], never>,
+    Events["DecodingServices"] | Error["DecodingServices"],
+    Events["EncodingServices"] | Error["EncodingServices"],
+    SchemaAST.Declaration,
+    StreamSse<Events, Error, Value>
+  >
+{
+  readonly "Rebuild": StreamSse<Events, Error, Value>
+  readonly [StreamSchemaTypeId]: typeof StreamSchemaTypeId
+  readonly _tag: "StreamSse"
+  readonly mode: "sse"
+  readonly sseMode: StreamSseMode
+  readonly contentType: string
+  readonly events: Events
+  readonly error: Error
+  readonly "~Value"?: Value | undefined
+}
+
+/**
+ * Event schema produced when {@link StreamSse} is constructed from a JSON data schema.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface SseEventFromData<Data extends Schema.Top> extends
+  Schema.Codec<
+    {
+      readonly id: string | undefined
+      readonly event: string
+      readonly data: Data["Type"]
+    },
+    {
+      readonly id?: string | undefined
+      readonly event?: string | undefined
+      readonly data: string
+    },
+    Data["DecodingServices"],
+    Data["EncodingServices"]
+  >
+{}
+
+/**
+ * Schema for a streaming `Uint8Array` success response.
+ *
+ * **Details**
+ *
+ * This declaration stores the response content type for later endpoint,
+ * server, client, and OpenAPI integrations. It is intentionally separate from
+ * the buffered `asUint8Array` response encoding.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface StreamUint8Array extends
+  Schema.Bottom<
+    Stream.Stream<Uint8Array, unknown, never>,
+    Stream.Stream<Uint8Array, unknown, never>,
+    never,
+    never,
+    SchemaAST.Declaration,
+    StreamUint8Array
+  >
+{
+  readonly "Rebuild": StreamUint8Array
+  readonly [StreamSchemaTypeId]: typeof StreamSchemaTypeId
+  readonly _tag: "StreamUint8Array"
+  readonly mode: "uint8array"
+  readonly contentType: string
+}
+
+/** @internal */
+export type StreamSchema = StreamSse<Sse.EventCodec, Schema.Top, unknown> | StreamUint8Array
+
+/** @internal */
+export type StreamMetadata =
+  | {
+    readonly mode: "sse"
+    readonly sseMode: StreamSseMode
+    readonly contentType: string
+    readonly events: Sse.EventCodec
+    readonly error: Schema.Top
+  }
+  | {
+    readonly mode: "uint8array"
+    readonly contentType: string
+  }
+
+const streamSchema = Schema.declare(Stream.isStream)
+
+/**
+ * Creates a Server-Sent Events streaming success response schema.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const StreamSse: {
+  /**
+   * Creates a Server-Sent Events streaming success response schema.
+   *
+   * @category constructors
+   * @since 4.0.0
+   */
+  <Events extends Sse.EventCodec, Error extends Schema.Top = Schema.Never>(
+    options: {
+      readonly contentType?: string | undefined
+      readonly events: Events
+      readonly error?: Error | undefined
+    }
+  ): StreamSse<Events, Error, Events["Type"]>
+  /**
+   * Creates a Server-Sent Events streaming success response schema.
+   *
+   * @category constructors
+   * @since 4.0.0
+   */
+  <Data extends Schema.Top, Error extends Schema.Top = Schema.Never>(
+    options: {
+      readonly contentType?: string | undefined
+      readonly data: Data
+      readonly error?: Error | undefined
+    }
+  ): StreamSse<SseEventFromData<Data>, Error, Data["Type"]>
+} = (options: {
+  readonly contentType?: string | undefined
+  readonly events?: Sse.EventCodec | undefined
+  readonly data?: Schema.Top | undefined
+  readonly error?: Schema.Top | undefined
+}): StreamSse<Sse.EventCodec, Schema.Top, unknown> => {
+  const events = options.events ?? (options.data === undefined ? undefined : Schema.Struct({
+    id: Schema.UndefinedOr(Schema.String),
+    event: Schema.String,
+    data: Schema.fromJsonString(options.data)
+  }))
+  if (events === undefined) {
+    throw new Error("StreamSse requires either an events schema or a data schema")
+  }
+  return Schema.make<StreamSse<Sse.EventCodec, Schema.Top, unknown>>(streamSchema.ast, {
+    [StreamSchemaTypeId]: StreamSchemaTypeId,
+    _tag: "StreamSse",
+    mode: "sse",
+    sseMode: options.events === undefined ? "data" : "events",
+    contentType: options.contentType ?? defaultStreamContentType("sse"),
+    events,
+    error: options.error ?? Schema.Never
+  })
+}
+
+/**
+ * Creates a streaming `Uint8Array` success response schema.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const StreamUint8Array = (options?: {
+  readonly contentType?: string | undefined
+}): StreamUint8Array =>
+  Schema.make<StreamUint8Array>(streamSchema.ast, {
+    [StreamSchemaTypeId]: StreamSchemaTypeId,
+    _tag: "StreamUint8Array",
+    mode: "uint8array",
+    contentType: options?.contentType ?? defaultStreamContentType("uint8array")
+  })
+
+/** @internal */
+export const isStreamSchema = (u: unknown): u is StreamSchema =>
+  Schema.isSchema(u) && Predicate.hasProperty(u, StreamSchemaTypeId)
+
+/** @internal */
+export const isStreamSse = (u: unknown): u is StreamSse<Sse.EventCodec, Schema.Top, unknown> =>
+  isStreamSchema(u) && u._tag === "StreamSse"
+
+/** @internal */
+export const isStreamUint8Array = (u: unknown): u is StreamUint8Array =>
+  isStreamSchema(u) && u._tag === "StreamUint8Array"
+
+/** @internal */
+export function getStreamMetadata(self: StreamSchema): StreamMetadata {
+  return self._tag === "StreamSse" ?
+    {
+      mode: self.mode,
+      sseMode: self.sseMode,
+      contentType: self.contentType,
+      events: self.events,
+      error: self.error
+    } :
+    {
+      mode: self.mode,
+      contentType: self.contentType
+    }
+}
+
+function defaultStreamContentType(mode: StreamMode): string {
+  switch (mode) {
+    case "sse":
+      return "text/event-stream"
+    case "uint8array":
+      return "application/octet-stream"
+  }
+}
+
 /**
  * Runtime brand key used to mark schemas as buffered multipart payloads.
  *
@@ -487,6 +726,11 @@ export function getStatusSuccess(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 200
 }
 
+/** @internal */
+export function getStatusStream(self: StreamSchema): number {
+  return getStatusSuccess(self.ast)
+}
+
 /** @internal */
 export function getStatusError(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 500

package/src/unstable/httpapi/OpenApi.ts

@@ -367,7 +367,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
       }
 
       function processResponseBodies(bodies: ResponseBodies, defaultDescription: () => string) {
-        for (const [status, { content, descriptions }] of bodies) {
+        for (const [status, { content, descriptions, streamContent }] of bodies) {
           const description = descriptions.size > 0 ? Array.from(descriptions).join(" | ") : defaultDescription()
           op.responses[status] = {
             description
@@ -390,6 +390,67 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
               })
             })
           }
+          if (streamContent !== undefined) {
+            streamContent.forEach((stream, contentType) => {
+              op.responses[status].content ??= {}
+              if (HttpApiSchema.isStreamSse(stream)) {
+                pathOps.push({
+                  _tag: "schema",
+                  ast: SchemaAST.getAST(stream.events),
+                  path: ["paths", path, method, "responses", String(status), "content", contentType, "schema"]
+                })
+                pathOps.push({
+                  _tag: "schema",
+                  ast: SchemaAST.getAST(Schema.toCodecJson(Schema.Cause(stream.error, Schema.Defect()))),
+                  path: [
+                    "paths",
+                    path,
+                    method,
+                    "responses",
+                    String(status),
+                    "content",
+                    contentType,
+                    "x-effect-stream",
+                    "causeSchema"
+                  ]
+                })
+                pathOps.push({
+                  _tag: "schema",
+                  ast: SchemaAST.getAST(stream.error),
+                  path: [
+                    "paths",
+                    path,
+                    method,
+                    "responses",
+                    String(status),
+                    "content",
+                    contentType,
+                    "x-effect-stream",
+                    "errorSchema"
+                  ]
+                })
+                op.responses[status].content[contentType] = {
+                  schema: {},
+                  "x-effect-stream": {
+                    encoding: "sse",
+                    causeSchema: {},
+                    errorSchema: {},
+                    failureEvent: reservedStreamFailureEvent
+                  }
+                }
+              } else {
+                op.responses[status].content[contentType] = {
+                  schema: {
+                    type: "string",
+                    format: "binary"
+                  },
+                  "x-effect-stream": {
+                    encoding: "uint8array"
+                  }
+                }
+              }
+            })
+          }
         }
       }
 
@@ -461,11 +522,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
       processParameters(endpoint.query, "query")
 
       processResponseBodies(
-        extractResponseBodies(
-          HttpApiEndpoint.getSuccessSchemas(endpoint),
-          HttpApiSchema.getStatusSuccess,
-          resolveDescriptionOrIdentifier
-        ),
+        extractSuccessResponseBodies(endpoint),
         () => "Success"
       )
       processResponseBodies(
@@ -564,9 +621,20 @@ type ResponseBodies = Map<
   {
     descriptions: Set<string>
     content: Content | undefined // undefined means no content
+    streamContent: StreamContent | undefined
   }
 >
 
+const reservedStreamFailureEvent = "effect/httpapi/stream/failure"
+
+function extractSuccessResponseBodies(endpoint: HttpApiEndpoint.AnyWithProps): ResponseBodies {
+  return extractResponseBodies(
+    HttpApiEndpoint.getSuccessSchemas(endpoint),
+    HttpApiSchema.getStatusSuccess,
+    resolveDescriptionOrIdentifier
+  )
+}
+
 function extractResponseBodies(
   schemas: Array<Schema.Top>,
   getStatus: (ast: SchemaAST.AST) => number,
@@ -575,6 +643,7 @@ function extractResponseBodies(
   const map = new Map<number, {
     descriptions: Set<string>
     content: Content | undefined
+    streamContent: StreamContent | undefined
   }>()
 
   schemas.forEach(process)
@@ -582,6 +651,10 @@ function extractResponseBodies(
   return map
 
   function process(schema: Schema.Top) {
+    if (HttpApiSchema.isStreamSchema(schema)) {
+      addStreamContent(schema)
+      return
+    }
     const ast = schema.ast
     const status = getStatus(ast)
     if (HttpApiSchema.isNoContent(ast)) {
@@ -596,7 +669,8 @@ function extractResponseBodies(
     if (statusMap === undefined) {
       map.set(status, {
         descriptions: new Set([description]),
-        content: undefined
+        content: undefined,
+        streamContent: undefined
       })
     } else {
       if (description !== undefined) {
@@ -612,22 +686,25 @@ function extractResponseBodies(
     if (statusMap === undefined) {
       map.set(status, {
         descriptions: new Set(description !== undefined ? [description] : []),
-        content: new Map([[_tag, new Map([[contentType, new Set([schema])]])]])
+        content: new Map([[_tag, new Map([[contentType, new Set([schema])]])]]),
+        streamContent: undefined
       })
     } else {
-      if (statusMap.content !== undefined) {
-        // concat descriptions
-        if (description !== undefined) {
-          statusMap.descriptions.add(description)
-        }
+      // concat descriptions
+      if (description !== undefined) {
+        statusMap.descriptions.add(description)
+      }
 
-        const contentTypeMap = statusMap.content.get(_tag)
-        if (contentTypeMap === undefined) {
+      if (statusMap.content === undefined) {
+        statusMap.content = new Map([[_tag, new Map([[contentType, new Set([schema])]])]])
+      } else {
+        const schemasByContentType = statusMap.content.get(_tag)
+        if (schemasByContentType === undefined) {
           statusMap.content.set(_tag, new Map([[contentType, new Set([schema])]]))
         } else {
-          const set = contentTypeMap.get(contentType)
+          const set = schemasByContentType.get(contentType)
           if (set === undefined) {
-            contentTypeMap.set(contentType, new Set([schema]))
+            schemasByContentType.set(contentType, new Set([schema]))
           } else {
             set.add(schema)
           }
@@ -635,6 +712,22 @@ function extractResponseBodies(
       }
     }
   }
+
+  function addStreamContent(stream: HttpApiSchema.StreamSchema) {
+    const status = HttpApiSchema.getStatusStream(stream)
+    const statusMap = map.get(status)
+    if (statusMap === undefined) {
+      map.set(status, {
+        descriptions: new Set(),
+        content: undefined,
+        streamContent: new Map([[stream.contentType, stream]])
+      })
+    } else if (statusMap.streamContent === undefined) {
+      statusMap.streamContent = new Map([[stream.contentType, stream]])
+    } else {
+      statusMap.streamContent.set(stream.contentType, stream)
+    }
+  }
 }
 
 function resolveDescriptionOrIdentifier(ast: SchemaAST.AST): string | undefined {
@@ -649,6 +742,8 @@ type Content = Map<
   >
 >
 
+type StreamContent = Map<string, HttpApiSchema.StreamSchema>
+
 const Uint8ArrayEncoding = Schema.String.annotate({
   format: "binary"
 })
@@ -895,8 +990,26 @@ export interface OpenApiSpecResponse {
  */
 export interface OpenApiSpecMediaType {
   schema: JsonSchema.JsonSchema
+  "x-effect-stream"?: OpenApiSpecEffectStream
 }
 
+/**
+ * Effect-specific metadata for generated streaming response media types.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type OpenApiSpecEffectStream =
+  | {
+    encoding: "sse"
+    causeSchema: JsonSchema.JsonSchema
+    errorSchema: JsonSchema.JsonSchema
+    failureEvent: "effect/httpapi/stream/failure"
+  }
+  | {
+    encoding: "uint8array"
+  }
+
 /**
  * Generated OpenAPI request body object for endpoint payloads.
  *

package/src/unstable/reactivity/AtomHttpApi.ts

@@ -82,7 +82,7 @@ export interface AtomHttpApiClient<Self, Id extends string, Groups extends HttpA
           readonly reactivityKeys?: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>> | undefined
         }
       >,
-      ResponseByMode<_Success["Type"], ResponseMode>,
+      ResponseByMode<Extract<_Success, Schema.Top>["Type"], ResponseMode>,
       ErrorByMode<_Error, _Middleware, ResponseMode>
     >
     : never
@@ -140,7 +140,7 @@ export interface AtomHttpApiClient<Self, Id extends string, Groups extends HttpA
     >
   ] ? Atom.Atom<
       AsyncResult.AsyncResult<
-        ResponseByMode<_Success["Type"], ResponseMode>,
+        ResponseByMode<Extract<_Success, Schema.Top>["Type"], ResponseMode>,
         ErrorByMode<_Error, _Middleware, ResponseMode>
       >
     >