Add paging support (#4470)

close #705 --------- Co-authored-by: iscai-msft <[email protected]> Co-authored-by: Mark Cowlishaw <[email protected]>
microsoft · Nov 5, 2024 · 78140e4 · 78140e4
1 parent ae07f24
commit 78140e4
Show file tree

Hide file tree

Showing 19 changed files with 1,486 additions and 75 deletions.
diff --git a/.chronus/changes/paging-2024-8-19-17-3-58.md b/.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
diff --git a/.chronus/changes/paging-2024-8-19-17-3-59.md b/.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
diff --git a/packages/astro-utils/tsconfig.json b/packages/astro-utils/tsconfig.json
@@ -2,5 +2,6 @@
   "extends": "astro/tsconfigs/strict",
   "compilerOptions": {
     "jsx": "preserve"
-  }
+  },
+  "exclude": ["dist/"]
 }
diff --git a/packages/compiler/generated-defs/TypeSpec.ts b/packages/compiler/generated-defs/TypeSpec.ts
@@ -413,18 +413,6 @@ export type MaxValueExclusiveDecorator = (
  */
 export type SecretDecorator = (context: DecoratorContext, target: Scalar | ModelProperty) => void;
 
-/**
- * Mark this operation as a `list` operation for resource types.
- *
- * @deprecated Use the `listsResource` decorator in `@typespec/rest` instead.
- * @param listedType Optional type of the items in the list.
- */
-export type ListDecorator = (
-  context: DecoratorContext,
-  target: Operation,
-  listedType?: Model,
-) => void;
-
 /**
  * Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorators can be specified to attach multiple tags to a TypeSpec element.
  *
@@ -710,6 +698,154 @@ export type WithVisibilityDecorator = (
   ...visibilities: string[]
 ) => void;
 
+/**
+ * Mark this operation as a `list` operation that returns a paginated list of items.
+ */
+export type ListDecorator = (context: DecoratorContext, target: Operation) => void;
+
+/**
+ * Pagination property defining the number of items to skip.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@offset skip: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+export type OffsetDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Pagination property defining the page index.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+export type PageIndexDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Specify the pagination parameter that controls the maximum number of items to include in a page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+export type PageSizeDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Specify the the property that contains the array of page items.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+export type PageItemsDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Pagination property defining the token to get to the next page.
+ * It MUST be specified both on the request parameter and the response.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @continuationToken continuationToken: string;
+ * }
+ * @list op listPets(@continuationToken continuationToken: string): Page<Pet>;
+ * ```
+ */
+export type ContinuationTokenDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Pagination property defining a link to the next page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+export type NextLinkDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Pagination property defining a link to the previous page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+export type PrevLinkDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Pagination property defining a link to the first page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+export type FirstLinkDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
+/**
+ * Pagination property defining a link to the last page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+export type LastLinkDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
 /**
  * A debugging decorator used to inspect a type.
  *
@@ -776,7 +912,6 @@ export type TypeSpecDecorators = {
   minValueExclusive: MinValueExclusiveDecorator;
   maxValueExclusive: MaxValueExclusiveDecorator;
   secret: SecretDecorator;
-  list: ListDecorator;
   tag: TagDecorator;
   friendlyName: FriendlyNameDecorator;
   knownValues: KnownValuesDecorator;
@@ -789,6 +924,16 @@ export type TypeSpecDecorators = {
   opExample: OpExampleDecorator;
   visibility: VisibilityDecorator;
   withVisibility: WithVisibilityDecorator;
+  list: ListDecorator;
+  offset: OffsetDecorator;
+  pageIndex: PageIndexDecorator;
+  pageSize: PageSizeDecorator;
+  pageItems: PageItemsDecorator;
+  continuationToken: ContinuationTokenDecorator;
+  nextLink: NextLinkDecorator;
+  prevLink: PrevLinkDecorator;
+  firstLink: FirstLinkDecorator;
+  lastLink: LastLinkDecorator;
   inspectType: InspectTypeDecorator;
   inspectTypeName: InspectTypeNameDecorator;
   parameterVisibility: ParameterVisibilityDecorator;

diff --git a/packages/compiler/lib/std/decorators.tsp b/packages/compiler/lib/std/decorators.tsp
@@ -277,13 +277,6 @@ extern dec maxValueExclusive(target: numeric | ModelProperty, value: valueof num
  */
 extern dec secret(target: string | ModelProperty);
 
-/**
- * Mark this operation as a `list` operation for resource types.
- * @deprecated Use the `listsResource` decorator in `@typespec/rest` instead.
- * @param listedType Optional type of the items in the list.
- */
-extern dec list(target: Operation, listedType?: Model);
-
 /**
  * Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorators can be specified to attach multiple tags to a TypeSpec element.
  * @param tag Tag value
@@ -689,6 +682,157 @@ extern dec withoutOmittedProperties(target: Model, omit: string | Union);
  */
 extern dec withPickedProperties(target: Model, pick: string | Union);
 
+//---------------------------------------------------------------------------
+// Paging
+//---------------------------------------------------------------------------
+
+/**
+ * Mark this operation as a `list` operation that returns a paginated list of items.
+ */
+extern dec list(target: Operation);
+
+/**
+ * Pagination property defining the number of items to skip.
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@offset skip: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+extern dec offset(target: ModelProperty);
+
+/**
+ * Pagination property defining the page index.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+extern dec pageIndex(target: ModelProperty);
+
+/**
+ * Specify the pagination parameter that controls the maximum number of items to include in a page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+extern dec pageSize(target: ModelProperty);
+
+/**
+ * Specify the the property that contains the array of page items.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ * }
+ * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
+ * ```
+ */
+extern dec pageItems(target: ModelProperty);
+
+/**
+ * Pagination property defining the token to get to the next page.
+ * It MUST be specified both on the request parameter and the response.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @continuationToken continuationToken: string;
+ * }
+ * @list op listPets(@continuationToken continuationToken: string): Page<Pet>;
+ * ```
+ */
+extern dec continuationToken(target: ModelProperty);
+
+/**
+ * Pagination property defining a link to the next page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+extern dec nextLink(target: ModelProperty);
+
+/**
+ * Pagination property defining a link to the previous page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+extern dec prevLink(target: ModelProperty);
+
+/**
+ * Pagination property defining a link to the first page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+extern dec firstLink(target: ModelProperty);
+
+/**
+ * Pagination property defining a link to the last page.
+ *
+ * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
+ *
+ * @example
+ * ```tsp
+ * model Page<T> {
+ *   @pageItems items: T[];
+ *   @nextLink next: url;
+ *   @prevLink prev: url;
+ *   @firstLink first: url;
+ *   @lastLink last: url;
+ * }
+ * @list op listPets(): Page<Pet>;
+ * ```
+ */
+extern dec lastLink(target: ModelProperty);
+
 //---------------------------------------------------------------------------
 // Debugging
 //---------------------------------------------------------------------------