[tcgc] continuation token feature

.chronus/changes/continuation_token-2025-1-12-17-57-14.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-Add `continuationTokenParameterSegments` and `continuationTokenResponseSegments` to `SdkPagingServiceMethodOptions` to indicate the mapping of continuation token parameter and response.
+Add `pagingMetadata.continuationTokenParameterSegments` and `pagingMetadata.continuationTokenResponseSegments` to `SdkPagingServiceMetadata` to indicate the mapping of continuation token parameter and response.

.chronus/changes/continuation_token-2025-1-12-17-58-11.md

@@ -4,4 +4,4 @@ packages:
   - "@azure-tools/typespec-client-generator-core"
 ---
 
-Deprecate `nextLinkPath` in `SdkPagingServiceMethodOptions`. Use `nextLinkSegments` instead. 
+Deprecate `__raw_paged_metadata`, `nextLinkPath` and `nextLinkOperation`  in `SdkPagingServiceMethodOptions`. Use `pagingMetadata.__raw`, `pagingMetadata.nextLinkSegments` and `pagingMetadata.nextLinkOperation` instead.

.chronus/changes/continuation_token-2025-1-18-16-47-36.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Add `SdkPagingServiceMetadata` type to store all paging related info.

packages/typespec-client-generator-core/src/interfaces.ts

@@ -14,6 +14,7 @@ import {
   ModelProperty,
   Namespace,
   Operation,
+  PagingOperation,
   Program,
   ProjectedProgram,
   Type,
@@ -784,21 +785,42 @@ export interface SdkBasicServiceMethod<TServiceOperation extends SdkServiceOpera
   kind: "basic";
 }
 
-interface SdkPagingServiceMethodOptions {
+interface SdkPagingServiceMethodOptions<TServiceOperation extends SdkServiceOperation> {
+  /**
+   * @deprecated Use `pagingMetadata.__raw` instead.
+   */
   __raw_paged_metadata?: PagedResultMetadata;
   /**
-   * @deprecated Use `nextLinkSegments` instead.
+   * @deprecated Use `pagingMetadata.nextLinkSegments` instead.
    */
   nextLinkPath?: string;
-  nextLinkSegments?: SdkModelPropertyType[];
+  /**
+   * @deprecated Use `pagingMetadata.nextLinkOperation` instead.
+   */
   nextLinkOperation?: SdkServiceOperation;
+  pagingMetadata: SdkPagingServiceMetadata<TServiceOperation>;
+}
+
+/**
+ * Paging operation metadata.
+ */
+export interface SdkPagingServiceMetadata<TServiceOperation extends SdkServiceOperation> {
+  /** Paging metadata from TypeSpec core library. */
+  __raw?: PagedResultMetadata | PagingOperation;
+
+  /** Segments to indicate how to get next page link value from response. */
+  nextLinkSegments?: SdkModelPropertyType[];
+  /** Method used to get next page. If not defined, use the initial method. */
+  nextLinkOperation?: SdkServiceMethod<TServiceOperation>;
+  /** Segments to indicate how to set continuation token for next page request. */
   continuationTokenParameterSegments?: SdkModelPropertyType[];
+  /** Segments to indicate how to get continuation token value from response. */
   continuationTokenResponseSegments?: SdkModelPropertyType[];
 }
 
 export interface SdkPagingServiceMethod<TServiceOperation extends SdkServiceOperation>
   extends SdkServiceMethodBase<TServiceOperation>,
-    SdkPagingServiceMethodOptions {
+    SdkPagingServiceMethodOptions<TServiceOperation> {
   kind: "paging";
 }
 
@@ -874,7 +896,7 @@ export interface SdkLroServiceMethod<TServiceOperation extends SdkServiceOperati
 export interface SdkLroPagingServiceMethod<TServiceOperation extends SdkServiceOperation>
   extends SdkServiceMethodBase<TServiceOperation>,
     SdkLroServiceMethodOptions,
-    SdkPagingServiceMethodOptions {
+    SdkPagingServiceMethodOptions<TServiceOperation> {
   kind: "lropaging";
 }
 

packages/typespec-client-generator-core/src/package.ts

@@ -170,6 +170,7 @@ function getSdkPagingServiceMethod<TServiceOperation extends SdkServiceOperation
       return diagnostics.wrap({
         ...baseServiceMethod,
         kind: "paging",
+        pagingMetadata: {},
       });
     }
 
@@ -233,9 +234,12 @@ function getSdkPagingServiceMethod<TServiceOperation extends SdkServiceOperation
       ...baseServiceMethod,
       kind: "paging",
       nextLinkPath,
-      nextLinkSegments,
-      continuationTokenParameterSegments,
-      continuationTokenResponseSegments,
+      pagingMetadata: {
+        __raw: pagingOperation,
+        nextLinkSegments,
+        continuationTokenParameterSegments,
+        continuationTokenResponseSegments,
+      },
     });
   }
 
@@ -260,6 +264,7 @@ function getSdkPagingServiceMethod<TServiceOperation extends SdkServiceOperation
     return diagnostics.wrap({
       ...baseServiceMethod,
       kind: "paging",
+      pagingMetadata: {},
     });
   }
 
@@ -309,7 +314,19 @@ function getSdkPagingServiceMethod<TServiceOperation extends SdkServiceOperation
           ),
         )
       : undefined,
-    nextLinkSegments,
+    pagingMetadata: {
+      __raw: pagedMetadata,
+      nextLinkSegments,
+      nextLinkOperation: pagedMetadata?.nextLinkOperation
+        ? diagnostics.pipe(
+            getSdkServiceMethod<TServiceOperation>(
+              context,
+              pagedMetadata.nextLinkOperation,
+              client,
+            ),
+          )
+        : undefined,
+    },
   });
 }
 

packages/typespec-client-generator-core/test/packages/paged-operation.test.ts

@@ -42,8 +42,8 @@ describe("typespec-client-generator-core: paged operation", () => {
     strictEqual(method.name, "test");
     strictEqual(method.kind, "paging");
     strictEqual(method.nextLinkPath, "nextLink");
-    strictEqual(method.nextLinkSegments?.length, 1);
-    strictEqual(method.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
+    strictEqual(method.pagingMetadata.nextLinkSegments?.length, 1);
+    strictEqual(method.pagingMetadata.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
 
     const response = method.response;
     strictEqual(response.kind, "method");
@@ -71,8 +71,8 @@ describe("typespec-client-generator-core: paged operation", () => {
     strictEqual(method.name, "test");
     strictEqual(method.kind, "paging");
     strictEqual(method.nextLinkPath, "next");
-    strictEqual(method.nextLinkSegments?.length, 1);
-    strictEqual(method.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
+    strictEqual(method.pagingMetadata.nextLinkSegments?.length, 1);
+    strictEqual(method.pagingMetadata.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
 
     const response = method.response;
     strictEqual(response.kind, "method");
@@ -100,8 +100,8 @@ describe("typespec-client-generator-core: paged operation", () => {
     strictEqual(method.name, "test");
     strictEqual(method.kind, "paging");
     strictEqual(method.nextLinkPath, "next");
-    strictEqual(method.nextLinkSegments?.length, 1);
-    strictEqual(method.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
+    strictEqual(method.pagingMetadata.nextLinkSegments?.length, 1);
+    strictEqual(method.pagingMetadata.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
 
     const response = method.response;
     strictEqual(response.kind, "method");
@@ -131,8 +131,8 @@ describe("typespec-client-generator-core: paged operation", () => {
     strictEqual(method.name, "test");
     strictEqual(method.kind, "paging");
     strictEqual(method.nextLinkPath, "nextLink");
-    strictEqual(method.nextLinkSegments?.length, 1);
-    strictEqual(method.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
+    strictEqual(method.pagingMetadata.nextLinkSegments?.length, 1);
+    strictEqual(method.pagingMetadata.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
 
     const response = method.response;
     strictEqual(response.kind, "method");
@@ -165,10 +165,13 @@ describe("typespec-client-generator-core: paged operation", () => {
     strictEqual(method.name, "test");
     strictEqual(method.kind, "paging");
     strictEqual(method.nextLinkPath, "pagination.nextLink");
-    strictEqual(method.nextLinkSegments?.length, 2);
-    strictEqual(method.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
+    strictEqual(method.pagingMetadata.nextLinkSegments?.length, 2);
+    strictEqual(method.pagingMetadata.nextLinkSegments[0], sdkPackage.models[0].properties[1]);
     strictEqual(sdkPackage.models[0].properties[1].type.kind, "model");
-    strictEqual(method.nextLinkSegments[1], sdkPackage.models[0].properties[1].type.properties[0]);
+    strictEqual(
+      method.pagingMetadata.nextLinkSegments[1],
+      sdkPackage.models[0].properties[1].type.properties[0],
+    );
 
     const response = method.response;
     strictEqual(response.kind, "method");
@@ -231,8 +234,8 @@ describe("typespec-client-generator-core: paged operation", () => {
     strictEqual(method.name, "test");
     strictEqual(method.kind, "paging");
     strictEqual(method.nextLinkPath, "nextLink");
-    strictEqual(method.nextLinkSegments?.length, 1);
-    strictEqual(method.nextLinkSegments[0], sdkPackage.models[1].properties[1]);
+    strictEqual(method.pagingMetadata.nextLinkSegments?.length, 1);
+    strictEqual(method.pagingMetadata.nextLinkSegments[0], sdkPackage.models[1].properties[1]);
 
     const response = method.response;
     strictEqual(response.kind, "method");
@@ -260,16 +263,19 @@ describe("typespec-client-generator-core: paged operation", () => {
       const method = getServiceMethodOfClient(sdkPackage);
       strictEqual(method.name, "test");
       strictEqual(method.kind, "paging");
-      strictEqual(method.continuationTokenParameterSegments?.length, 1);
-      strictEqual(method.continuationTokenParameterSegments?.[0], method.parameters[0]);
+      strictEqual(method.pagingMetadata.continuationTokenParameterSegments?.length, 1);
+      strictEqual(
+        method.pagingMetadata.continuationTokenParameterSegments?.[0],
+        method.parameters[0],
+      );
       strictEqual(
         method.operation.parameters[0].correspondingMethodParams[0],
         method.parameters[0],
       );
-      strictEqual(method.continuationTokenResponseSegments?.length, 1);
+      strictEqual(method.pagingMetadata.continuationTokenResponseSegments?.length, 1);
       strictEqual(method.operation.responses[0].type?.kind, "model");
       strictEqual(
-        method.continuationTokenResponseSegments?.[0],
+        method.pagingMetadata.continuationTokenResponseSegments?.[0],
         method.operation.responses[0].type.properties[1],
       );
     });
@@ -292,12 +298,15 @@ describe("typespec-client-generator-core: paged operation", () => {
       const method = getServiceMethodOfClient(sdkPackage);
       strictEqual(method.name, "test");
       strictEqual(method.kind, "paging");
-      strictEqual(method.continuationTokenParameterSegments?.length, 1);
-      strictEqual(method.continuationTokenParameterSegments?.[0], method.parameters[0]);
-      strictEqual(method.continuationTokenResponseSegments?.length, 1);
+      strictEqual(method.pagingMetadata.continuationTokenParameterSegments?.length, 1);
+      strictEqual(
+        method.pagingMetadata.continuationTokenParameterSegments?.[0],
+        method.parameters[0],
+      );
+      strictEqual(method.pagingMetadata.continuationTokenResponseSegments?.length, 1);
       strictEqual(method.operation.responses[0].type?.kind, "model");
       strictEqual(
-        method.continuationTokenResponseSegments?.[0],
+        method.pagingMetadata.continuationTokenResponseSegments?.[0],
         method.operation.responses[0].type.properties[1],
       );
     });
@@ -320,12 +329,15 @@ describe("typespec-client-generator-core: paged operation", () => {
       const method = getServiceMethodOfClient(sdkPackage);
       strictEqual(method.name, "test");
       strictEqual(method.kind, "paging");
-      strictEqual(method.continuationTokenParameterSegments?.length, 1);
-      strictEqual(method.continuationTokenParameterSegments?.[0], method.parameters[0]);
-      strictEqual(method.continuationTokenResponseSegments?.length, 1);
+      strictEqual(method.pagingMetadata.continuationTokenParameterSegments?.length, 1);
+      strictEqual(
+        method.pagingMetadata.continuationTokenParameterSegments?.[0],
+        method.parameters[0],
+      );
+      strictEqual(method.pagingMetadata.continuationTokenResponseSegments?.length, 1);
       strictEqual(method.operation.responses[0].type?.kind, "model");
       strictEqual(
-        method.continuationTokenResponseSegments?.[0],
+        method.pagingMetadata.continuationTokenResponseSegments?.[0],
         method.operation.responses[0].type.properties[1],
       );
     });
@@ -349,12 +361,15 @@ describe("typespec-client-generator-core: paged operation", () => {
       const method = getServiceMethodOfClient(sdkPackage);
       strictEqual(method.name, "test");
       strictEqual(method.kind, "paging");
-      strictEqual(method.continuationTokenParameterSegments?.length, 1);
-      strictEqual(method.continuationTokenParameterSegments?.[0], method.parameters[0]);
-      strictEqual(method.continuationTokenResponseSegments?.length, 1);
+      strictEqual(method.pagingMetadata.continuationTokenParameterSegments?.length, 1);
+      strictEqual(
+        method.pagingMetadata.continuationTokenParameterSegments?.[0],
+        method.parameters[0],
+      );
+      strictEqual(method.pagingMetadata.continuationTokenResponseSegments?.length, 1);
       strictEqual(method.operation.responses[0].type?.kind, "model");
       strictEqual(
-        method.continuationTokenResponseSegments?.[0],
+        method.pagingMetadata.continuationTokenResponseSegments?.[0],
         method.operation.responses[0].headers[0],
       );
     });
@@ -378,12 +393,15 @@ describe("typespec-client-generator-core: paged operation", () => {
       const method = getServiceMethodOfClient(sdkPackage);
       strictEqual(method.name, "test");
       strictEqual(method.kind, "paging");
-      strictEqual(method.continuationTokenParameterSegments?.length, 1);
-      strictEqual(method.continuationTokenParameterSegments?.[0], method.parameters[0]);
-      strictEqual(method.continuationTokenResponseSegments?.length, 1);
+      strictEqual(method.pagingMetadata.continuationTokenParameterSegments?.length, 1);
+      strictEqual(
+        method.pagingMetadata.continuationTokenParameterSegments?.[0],
+        method.parameters[0],
+      );
+      strictEqual(method.pagingMetadata.continuationTokenResponseSegments?.length, 1);
       strictEqual(method.operation.responses[0].type?.kind, "model");
       strictEqual(
-        method.continuationTokenResponseSegments?.[0],
+        method.pagingMetadata.continuationTokenResponseSegments?.[0],
         method.operation.responses[0].headers[0],
       );
     });
@@ -407,12 +425,15 @@ describe("typespec-client-generator-core: paged operation", () => {
       const method = getServiceMethodOfClient(sdkPackage);
       strictEqual(method.name, "test");
       strictEqual(method.kind, "paging");
-      strictEqual(method.continuationTokenParameterSegments?.length, 1);
-      strictEqual(method.continuationTokenParameterSegments?.[0], method.parameters[0]);
-      strictEqual(method.continuationTokenResponseSegments?.length, 1);
+      strictEqual(method.pagingMetadata.continuationTokenParameterSegments?.length, 1);
+      strictEqual(
+        method.pagingMetadata.continuationTokenParameterSegments?.[0],
+        method.parameters[0],
+      );
+      strictEqual(method.pagingMetadata.continuationTokenResponseSegments?.length, 1);
       strictEqual(method.operation.responses[0].type?.kind, "model");
       strictEqual(
-        method.continuationTokenResponseSegments?.[0],
+        method.pagingMetadata.continuationTokenResponseSegments?.[0],
         method.operation.responses[0].headers[0],
       );
     });
@@ -446,21 +467,24 @@ describe("typespec-client-generator-core: paged operation", () => {
       const method = getServiceMethodOfClient(sdkPackage);
       strictEqual(method.name, "test");
       strictEqual(method.kind, "paging");
-      strictEqual(method.continuationTokenParameterSegments?.length, 2);
-      strictEqual(method.continuationTokenParameterSegments?.[0], method.parameters[0]);
+      strictEqual(method.pagingMetadata.continuationTokenParameterSegments?.length, 2);
+      strictEqual(
+        method.pagingMetadata.continuationTokenParameterSegments?.[0],
+        method.parameters[0],
+      );
       strictEqual(method.parameters[0].type.kind, "model");
       strictEqual(
-        method.continuationTokenParameterSegments?.[1],
+        method.pagingMetadata.continuationTokenParameterSegments?.[1],
         method.parameters[0].type.properties[0],
       );
       strictEqual(
         method.operation.parameters[0].correspondingMethodParams[0],
         method.parameters[0].type.properties[0],
       );
-      strictEqual(method.continuationTokenResponseSegments?.length, 1);
+      strictEqual(method.pagingMetadata.continuationTokenResponseSegments?.length, 1);
       strictEqual(method.operation.responses[0].type?.kind, "model");
       strictEqual(
-        method.continuationTokenResponseSegments?.[0],
+        method.pagingMetadata.continuationTokenResponseSegments?.[0],
         method.operation.responses[0].type.properties[1],
       );
     });