Add support for defining streams (#4513)

Related: #154

---------

Co-authored-by: Christopher Radek <[email protected]>

.chronus/changes/add-streaming-2024-8-25-11-52-49.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/events"
+---
+
+Adds a new core package for describing events.

.chronus/changes/add-streaming-2024-8-25-11-53-37.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/streams"
+---
+
+Adds a new core package for describing streams and the type of data they contain.

.chronus/changes/add-streaming-2024-8-25-11-54-27.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/sse"
+---
+
+Adds a new core package to describe server-sent events.

.chronus/changes/add-streaming-2024-8-25-11-56-3.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+Adds HttpStream and JsonlStream models to to support streaming use-cases.

.chronus/changes/add-streaming-2024-8-25-11-56-36.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/compiler"
+---
+
+Fixes issue with the semantic walker where `exitTuple` was not being emitted.

docs/libraries/events/reference/decorators.md

@@ -0,0 +1,112 @@
+---
+title: "Decorators"
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+# Decorators
+
+## TypeSpec.Events
+
+### `@contentType` {#@TypeSpec.Events.contentType}
+
+Specifies the content type of the event envelope, event body, or event payload.
+When applied to an event payload, that field must also have a corresponding `@data`
+decorator.
+
+```typespec
+@TypeSpec.Events.contentType(contentType: valueof string)
+```
+
+#### Target
+
+`UnionVariant | ModelProperty`
+
+#### Parameters
+
+| Name        | Type             | Description |
+| ----------- | ---------------- | ----------- |
+| contentType | `valueof string` |             |
+
+#### Examples
+
+```typespec
+@events
+union MixedEvents {
+  @contentType("application/json")
+  message: {
+    id: string,
+    text: string,
+  },
+}
+```
+
+##### Specify the content type of the event payload.
+
+```typespec
+@events
+union MixedEvents {
+  {
+    done: true,
+  },
+  {
+    done: false,
+    @data @contentType("text/plain") value: string,
+  },
+}
+```
+
+### `@data` {#@TypeSpec.Events.data}
+
+Identifies the payload of an event.
+Only one field in an event can be marked as the payload.
+
+```typespec
+@TypeSpec.Events.data
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+
+None
+
+#### Examples
+
+```typespec
+@events
+union MixedEvents {
+  {
+    metadata: Record<string>,
+    @data payload: string,
+  },
+}
+```
+
+### `@events` {#@TypeSpec.Events.events}
+
+Specify that this union describes a set of events.
+
+```typespec
+@TypeSpec.Events.events
+```
+
+#### Target
+
+`Union`
+
+#### Parameters
+
+None
+
+#### Examples
+
+```typespec
+@events
+union MixedEvents {
+  pingEvent: string,
+  doneEvent: "done",
+}
+```

docs/libraries/events/reference/index.mdx

@@ -0,0 +1,40 @@
+---
+title: Overview
+sidebar_position: 0
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Overview
+
+TypeSpec library providing events bindings
+
+## Install
+
+<Tabs>
+<TabItem value="spec" label="In a spec" default>
+
+```bash
+npm install @typespec/events
+```
+
+</TabItem>
+<TabItem value="library" label="In a library" default>
+
+```bash
+npm install --save-peer @typespec/events
+```
+
+</TabItem>
+</Tabs>
+
+## TypeSpec.Events
+
+### Decorators
+
+- [`@contentType`](./decorators.md#@TypeSpec.Events.contentType)
+- [`@data`](./decorators.md#@TypeSpec.Events.data)
+- [`@events`](./decorators.md#@TypeSpec.Events.events)

docs/libraries/sse/reference/data-types.md

@@ -0,0 +1,71 @@
+---
+title: "Data types"
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+# Data types
+
+## TypeSpec.SSE
+
+### `SSEStream` {#TypeSpec.SSE.SSEStream}
+
+Describes a stream of server-sent events.
+
+The content-type is set to `text/event-stream`.
+
+The server-sent events are described by `Type`.
+The event type for any event can be defined by using named union variants.
+When a union variant is not named, it is considered a 'message' event.
+
+```typespec
+model TypeSpec.SSE.SSEStream<Type>
+```
+
+#### Template Parameters
+
+| Name | Description                                          |
+| ---- | ---------------------------------------------------- |
+| Type | The set of models describing the server-sent events. |
+
+#### Examples
+
+##### Mix of named union variants and terminal event
+
+```typespec
+model UserConnect {
+  username: string;
+  time: string;
+}
+
+model UserMessage {
+  username: string;
+  time: string;
+  text: string;
+}
+
+model UserDisconnect {
+  username: string;
+  time: string;
+}
+
+@TypeSpec.Events.events
+union ChannelEvents {
+  userconnect: UserConnect,
+  usermessage: UserMessage,
+  userdisconnect: UserDisconnect,
+
+  @Events.contentType("text/plain")
+  @terminalEvent
+  "[unsubscribe]",
+}
+
+op subscribeToChannel(): SSEStream<ChannelEvents>;
+```
+
+#### Properties
+
+| Name        | Type                  | Description |
+| ----------- | --------------------- | ----------- |
+| contentType | `"text/event-stream"` |             |
+| body        | `string`              |             |

docs/libraries/sse/reference/decorators.md

@@ -0,0 +1,26 @@
+---
+title: "Decorators"
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+# Decorators
+
+## TypeSpec.SSE
+
+### `@terminalEvent` {#@TypeSpec.SSE.terminalEvent}
+
+Indicates that the presence of this event is a terminal event,
+and the client should disconnect from the server.
+
+```typespec
+@TypeSpec.SSE.terminalEvent
+```
+
+#### Target
+
+`UnionVariant`
+
+#### Parameters
+
+None

docs/libraries/sse/reference/index.mdx

@@ -0,0 +1,42 @@
+---
+title: Overview
+sidebar_position: 0
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Overview
+
+TypeSpec library providing server sent events bindings
+
+## Install
+
+<Tabs>
+<TabItem value="spec" label="In a spec" default>
+
+```bash
+npm install @typespec/sse
+```
+
+</TabItem>
+<TabItem value="library" label="In a library" default>
+
+```bash
+npm install --save-peer @typespec/sse
+```
+
+</TabItem>
+</Tabs>
+
+## TypeSpec.SSE
+
+### Decorators
+
+- [`@terminalEvent`](./decorators.md#@TypeSpec.SSE.terminalEvent)
+
+### Models
+
+- [`SSEStream`](./data-types.md#TypeSpec.SSE.SSEStream)

docs/libraries/stream/reference/data-types.md

@@ -0,0 +1,31 @@
+---
+title: "Data types"
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+# Data types
+
+## TypeSpec.Streams
+
+### `Stream` {#TypeSpec.Streams.Stream}
+
+Defines a model that represents a stream protocol type whose data is described
+by `Type`.
+
+This can be useful when the underlying data type is not relevant, or to serve as
+a base type for custom streams.
+
+```typespec
+model TypeSpec.Streams.Stream<Type>
+```
+
+#### Template Parameters
+
+| Name | Description                    |
+| ---- | ------------------------------ |
+| Type | The type of the stream's data. |
+
+#### Properties
+
+None