Add paging support

.chronus/changes/paging-2024-8-19-17-3-58.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Add support for paginated operations

.chronus/changes/paging-2024-8-19-17-3-59.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+Add new `LinkHeader` pagination type

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

@@ -294,6 +294,20 @@ model TypeSpec.Http.ImplicitFlow
 | refreshUrl?      | `string`                                | the refresh URL                   |
 | scopes?          | `string[]`                              | list of scopes for the credential |
 
+### `Link` {#TypeSpec.Http.Link}
+
+```typespec
+model TypeSpec.Http.Link
+```
+
+#### Properties
+
+| Name        | Type              | Description |
+| ----------- | ----------------- | ----------- |
+| target      | `url`             |             |
+| rel         | `string`          |             |
+| attributes? | `Record<unknown>` |             |
+
 ### `LocationHeader` {#TypeSpec.Http.LocationHeader}
 
 The Location header contains the URL where the status of the long running operation can be checked.
@@ -594,3 +608,9 @@ enum TypeSpec.Http.OAuth2FlowType
 | implicit          |       | implicit flow           |
 | password          |       | password flow           |
 | clientCredentials |       | client credential flow  |
+
+### `LinkHeader` {#TypeSpec.Http.LinkHeader}
+
+```typespec
+scalar TypeSpec.Http.LinkHeader
+```

docs/libraries/http/reference/index.mdx

@@ -73,6 +73,7 @@ npm install --save-peer @typespec/http
 - [`HttpPart`](./data-types.md#TypeSpec.Http.HttpPart)
 - [`HttpPartOptions`](./data-types.md#TypeSpec.Http.HttpPartOptions)
 - [`ImplicitFlow`](./data-types.md#TypeSpec.Http.ImplicitFlow)
+- [`Link`](./data-types.md#TypeSpec.Http.Link)
 - [`LocationHeader`](./data-types.md#TypeSpec.Http.LocationHeader)
 - [`MovedResponse`](./data-types.md#TypeSpec.Http.MovedResponse)
 - [`NoAuth`](./data-types.md#TypeSpec.Http.NoAuth)

docs/standard-library/built-in-decorators.md

@@ -5,6 +5,32 @@ toc_max_heading_level: 3
 ---
 # Built-in Decorators
 ## TypeSpec
+### `@continuationToken` {#@continuationToken}
+
+Pagination property defining the token to get to the next page.
+It MUST be specified both on the request parameter and the response.
+```typespec
+@continuationToken
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+  @continuationToken continuationToken: string;
+}
+@list op listPets(@continuationToken continuationToken: string): Page<Pet>;
+```
+
+
 ### `@deprecated` {#@deprecated}
 :::warning
 **Deprecated**: @deprecated decorator is deprecated. Use the `#deprecated` directive instead.
@@ -254,6 +280,36 @@ model Pet {
 ```
 
 
+### `@firstLink` {#@firstLink}
+
+Pagination property defining a link to the first page.
+
+It is expected that the navigating to the link will return the same set of response as the operation that returned the current page.
+```typespec
+@firstLink
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+  @nextLink next: url;
+  @prevLink prev: url;
+  @firstLink first: url;
+  @lastLink last: url;
+}
+@list op listPets(): Page<Pet>;
+```
+
+
 ### `@format` {#@format}
 
 Specify a known data format hint for this string type. For example `uuid`, `uri`, etc.
@@ -401,21 +457,49 @@ enum KnownErrorCode {
 ```
 
 
+### `@lastLink` {#@lastLink}
+
+Pagination property defining a link to the last page.
+
+It is expected that the navigating to the link will return the same set of response as the operation that returned the current page.
+```typespec
+@lastLink
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+  @nextLink next: url;
+  @prevLink prev: url;
+  @firstLink first: url;
+  @lastLink last: url;
+}
+@list op listPets(): Page<Pet>;
+```
+
+
 ### `@list` {#@list}
 
-Mark this operation as a `list` operation for resource types.
+Mark this operation as a `list` operation that returns a paginated list of items.
 ```typespec
-@list(listedType?: Model)
+@list
 ```
 
 #### Target
 
 `Operation`
 
 #### Parameters
-| Name | Type | Description |
-|------|------|-------------|
-| listedType | `Model` | Optional type of the items in the list. |
+None
 
 
 
@@ -613,6 +697,60 @@ scalar distance is float64;
 ```
 
 
+### `@nextLink` {#@nextLink}
+
+Pagination property defining a link to the next page.
+
+It is expected that the navigating to the link will return the same set of response as the operation that returned the current page.
+```typespec
+@nextLink
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+  @nextLink next: url;
+  @prevLink prev: url;
+  @firstLink first: url;
+  @lastLink last: url;
+}
+@list op listPets(): Page<Pet>;
+```
+
+
+### `@offset` {#@offset}
+
+Pagination property defining the number of items to skip.
+```typespec
+@offset
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+}
+@list op listPets(@offset skip: int32, @pageSize pageSize: int8): Page<Pet>;
+```
+
+
 ### `@opExample` {#@opExample}
 
 Provide example values for an operation's parameters and corresponding return type.
@@ -665,6 +803,78 @@ op uploadBytes(data: bytes, @header contentType: "application/octet-stream"): vo
 ```
 
 
+### `@pageIndex` {#@pageIndex}
+
+Pagination property defining the page index.
+```typespec
+@pageIndex
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+}
+@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+```
+
+
+### `@pageItems` {#@pageItems}
+
+Specify the the property that contains the array of page items.
+```typespec
+@pageItems
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+}
+@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+```
+
+
+### `@pageSize` {#@pageSize}
+
+Specify the pagination parameter that controls the maximum number of items to include in a page.
+```typespec
+@pageSize
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+}
+@list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+```
+
+
 ### `@parameterVisibility` {#@parameterVisibility}
 
 Sets which visibilities apply to parameters for the given operation.
@@ -715,6 +925,36 @@ scalar LowerAlpha extends string;
 ```
 
 
+### `@prevLink` {#@prevLink}
+
+Pagination property defining a link to the previous page.
+
+It is expected that the navigating to the link will return the same set of response as the operation that returned the current page.
+```typespec
+@prevLink
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+None
+
+#### Examples
+
+```tsp
+model Page<T> {
+  @pageItems items: T[];
+  @nextLink next: url;
+  @prevLink prev: url;
+  @firstLink first: url;
+  @lastLink last: url;
+}
+@list op listPets(): Page<Pet>;
+```
+
+
 ### `@projectedName` {#@projectedName}
 :::warning
 **Deprecated**: Use `@encodedName` instead for changing the name over the wire.