feat(csharp): add pagination helper methods to C# SDK generator

.vscode/settings.json

@@ -4,16 +4,24 @@
     "**/.yarn": true,
   },
   "eslint.nodePath": ".yarn/sdks",
-  "eslint.execArgv": ["--max_old_space_size=16384"],
-  "eslint.workingDirectories": [ "./packages", "./generators" ],
+  "eslint.execArgv": [
+    "--max_old_space_size=16384"
+  ],
+  "eslint.workingDirectories": [
+    "./packages",
+    "./generators"
+  ],
   "prettier.prettierPath": "node_modules/prettier/index.js",
   "typescript.tsdk": "node_modules/typescript/lib",
   "typescript.enablePromptUseWorkspaceTsdk": true,
-  "editor.formatOnSave": true,
-  "editor.codeActionsOnSave": ["source.fixAll", "source.sortMembers"],
+  "editor.formatOnSave": false,
+  "editor.codeActionsOnSave": [
+    "source.fixAll",
+    "source.sortMembers"
+  ],
   "editor.defaultFormatter": null,
   "[typescript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
   "python.analysis.typeCheckingMode": "basic"
-}
+}

generators/csharp/codegen/src/AsIs.ts

@@ -7,32 +7,34 @@ export const CONSTANTS_CLASS_NAME = "Constants";
 export const JSON_UTILS_CLASS_NAME = "JsonUtils";
 
 export enum AsIsFiles {
-    GitIgnore = ".gitignore.Template",
     CiYaml = "github-ci.yml",
     CollectionItemSerializer = "CollectionItemSerializer.cs",
     Constants = "Constants.cs",
+    CustomProps = "Custom.props.Template",
     DateTimeSerializer = "DateTimeSerializer.cs",
     EnumConverter = "EnumConverter.Template.cs",
+    EnumSerializer = "EnumSerializer.Template.cs",
+    EnumSerializerTests = "EnumSerializerTests.Template.cs",
+    Extensions = "Extensions.cs",
+    GitIgnore = ".gitignore.Template",
     GrpcRequestOptions = "GrpcRequestOptions.Template.cs",
     Headers = "Headers.Template.cs",
     HeaderValue = "HeaderValue.Template.cs",
     HttpMethodExtensions = "HttpMethodExtensions.cs",
     JsonConfiguration = "JsonConfiguration.cs",
     OneOfSerializer = "OneOfSerializer.cs",
+    Page = "Page.Template.cs",
+    Pager = "Pager.Template.cs",
     RawClient = "RawClient.Template.cs",
     RawClientTests = "RawClientTests.Template.cs",
     RawGrpcClient = "RawGrpcClient.Template.cs",
-    EnumSerializer = "EnumSerializer.Template.cs",
-    EnumSerializerTests = "EnumSerializerTests.Template.cs",
     StringEnum = "StringEnum.Template.cs",
     StringEnumExtensions = "StringEnumExtensions.Template.cs",
     StringEnumSerializer = "StringEnumSerializer.Template.cs",
     StringEnumSerializerTests = "StringEnumSerializerTests.Template.cs",
     TemplateCsProj = "Template.csproj",
-    TemplateTestCsProj = "Template.Test.csproj",
     TemplateTestClientCs = "TemplateTestClient.cs",
-    UsingCs = "Using.cs",
-    Extensions = "Extensions.cs",
-    CustomProps = "Custom.props.Template",
-    TestCustomProps = "Test.Custom.props.Template"
+    TemplateTestCsProj = "Template.Test.csproj",
+    TestCustomProps = "Test.Custom.props.Template",
+    UsingCs = "Using.cs"
 }

generators/csharp/codegen/src/asIs/Page.Template.cs

@@ -0,0 +1,19 @@
+namespace <%= namespace%>;
+
+/// <summary>
+/// A single <see cref="Page{TItem}"/> of items from a request that may return
+/// zero or more <see cref="Page{TItem}"/>s of items.
+/// </summary>
+/// <typeparam name="TItem">The type of items.</typeparam>
+public class Page<TItem>
+{
+    public Page(IReadOnlyList<TItem> items)
+    {
+        Items = items;
+    }
+
+    /// <summary>
+    /// Gets the items in this <see cref="Page{TItem}"/>.
+    /// </summary>
+    public IReadOnlyList<TItem> Items { get; }
+}

generators/csharp/codegen/src/asIs/Pager.Template.cs

@@ -0,0 +1,211 @@
+using System.Runtime.CompilerServices;
+
+namespace <%= namespace%>;
+
+/// <summary>
+/// A collection of values that may take multiple service requests to
+/// iterate over.
+/// </summary>
+/// <typeparam name="TItem">The type of the values.</typeparam>
+public abstract class Pager<TItem> : IAsyncEnumerable<TItem>
+{
+    /// <summary>
+    /// Enumerate the values a <see cref="Page{TItem}"/> at a time.  This may
+    /// make multiple service requests.
+    /// </summary>
+    /// <returns>
+    /// An async sequence of <see cref="Page{TItem}"/>s.
+    /// </returns>
+    public abstract IAsyncEnumerable<Page<TItem>> AsPagesAsync(
+        CancellationToken cancellationToken = default
+    );
+
+    /// <summary>
+    /// Enumerate the values in the collection asynchronously.  This may
+    /// make multiple service requests.
+    /// </summary>
+    /// <param name="cancellationToken">
+    /// The <see cref="CancellationToken"/> used for requests made while
+    /// enumerating asynchronously.
+    /// </param>
+    /// <returns>An async sequence of values.</returns>
+    public virtual async IAsyncEnumerator<TItem> GetAsyncEnumerator(
+        CancellationToken cancellationToken = default
+    )
+    {
+        await foreach (var page in AsPagesAsync(cancellationToken).ConfigureAwait(false))
+        {
+            foreach (var value in page.Items)
+            {
+                yield return value;
+            }
+        }
+    }
+}
+
+internal sealed class OffsetPager<TRequest, TRequestOptions, TResponse, TOffset, TStep, TItem>
+    : Pager<TItem>
+{
+    private TRequest _request;
+    private readonly TRequestOptions? _options;
+    private readonly GetNextPage _getNextPage;
+    private readonly GetOffset _getOffset;
+    private readonly SetOffset _setOffset;
+    private readonly GetStep? _getStep;
+    private readonly GetItems _getItems;
+    private readonly HasNextPage? _hasNextPage;
+
+    internal delegate Task<TResponse> GetNextPage(
+        TRequest request,
+        TRequestOptions? options,
+        CancellationToken cancellationToken
+    );
+
+    internal delegate TOffset GetOffset(TRequest request);
+
+    internal delegate void SetOffset(TRequest request, TOffset offset);
+
+    internal delegate TStep GetStep(TRequest request);
+
+    internal delegate IReadOnlyList<TItem>? GetItems(TResponse response);
+
+    internal delegate bool? HasNextPage(TResponse response);
+
+    internal OffsetPager(
+        TRequest request,
+        TRequestOptions? options,
+        GetNextPage getNextPage,
+        GetOffset getOffset,
+        SetOffset setOffset,
+        GetStep? getStep,
+        GetItems getItems,
+        HasNextPage? hasNextPage
+    )
+    {
+        _request = request;
+        _options = options;
+        _getNextPage = getNextPage;
+        _getOffset = getOffset;
+        _setOffset = setOffset;
+        _getStep = getStep;
+        _getItems = getItems;
+        _hasNextPage = hasNextPage;
+    }
+
+    public override async IAsyncEnumerable<Page<TItem>> AsPagesAsync(
+        [EnumeratorCancellation] CancellationToken cancellationToken = default
+    )
+    {
+        var hasStep = false;
+        if(_getStep is not null)
+        {
+            hasStep = _getStep(_request) is not null;
+        }
+        var offset = _getOffset(_request);
+        var longOffset = Convert.ToInt64(offset);
+        bool hasNextPage;
+        do
+        {
+            var response = await _getNextPage(_request, _options, cancellationToken)
+                .ConfigureAwait(false);
+            var items = _getItems(response);
+            var itemCount = items?.Count ?? 0;
+            hasNextPage = _hasNextPage?.Invoke(response) ?? itemCount > 0;
+            if (items is not null)
+            {
+                yield return new Page<TItem>(items);
+            }
+
+            // If there is a step, we need to increment the offset by the number of items
+            if (hasStep)
+            {
+                longOffset += items?.Count ?? 1;
+            }
+            else
+            {
+                longOffset++;
+            }
+
+            // ensure there's a request object to set the offset on
+            _request ??= Activator.CreateInstance<TRequest>();
+            switch (offset)
+            {
+                case int:
+                    // safely cast long to int
+                    _setOffset(_request, (TOffset)(object)(int)longOffset);
+                    break;
+                case long:
+                    _setOffset(_request, (TOffset)(object)longOffset);
+                    break;
+                default:
+                    throw new InvalidOperationException("Offset must be int or long");
+            }
+        } while (hasNextPage);
+    }
+}
+
+internal sealed class CursorPager<TRequest, TRequestOptions, TResponse, TCursor, TItem>
+    : Pager<TItem>
+{
+    private TRequest _request;
+    private readonly TRequestOptions? _options;
+    private readonly GetNextPage _getNextPage;
+    private readonly SetCursor _setCursor;
+    private readonly GetNextCursor _getNextCursor;
+    private readonly GetItems _getItems;
+
+    internal delegate Task<TResponse> GetNextPage(
+        TRequest request,
+        TRequestOptions? options,
+        CancellationToken cancellationToken
+    );
+
+    internal delegate void SetCursor(TRequest request, TCursor cursor);
+
+    internal delegate TCursor? GetNextCursor(TResponse response);
+
+    internal delegate IReadOnlyList<TItem>? GetItems(TResponse response);
+
+    internal CursorPager(
+        TRequest request,
+        TRequestOptions? options,
+        GetNextPage getNextPage,
+        SetCursor setCursor,
+        GetNextCursor getNextCursor,
+        GetItems getItems
+    )
+    {
+        _request = request;
+        _options = options;
+        _getNextPage = getNextPage;
+        _setCursor = setCursor;
+        _getNextCursor = getNextCursor;
+        _getItems = getItems;
+    }
+
+    public override async IAsyncEnumerable<Page<TItem>> AsPagesAsync(
+        [EnumeratorCancellation] CancellationToken cancellationToken = default
+    )
+    {
+        do
+        {
+            var response = await _getNextPage(_request, _options, cancellationToken)
+                .ConfigureAwait(false);
+            var items = _getItems(response);
+            var nextCursor = _getNextCursor(response);
+            if (items != null)
+            {
+                yield return new Page<TItem>(items);
+            }
+
+            if (nextCursor == null)
+            {
+                break;
+            }
+
+            // ensure there's a request object to set the cursor on
+            _request ??= Activator.CreateInstance<TRequest>();
+            _setCursor(_request, nextCursor);
+        } while (true);
+    }
+}

generators/csharp/codegen/src/ast/Class.ts

@@ -170,6 +170,10 @@ export class Class extends AstNode {
         this.methods.push(method);
     }
 
+    public addMethods(methods: Method[]): void {
+        methods.forEach((method) => this.addMethod(method));
+    }
+
     public addNestedClass(subClass: Class): void {
         this.nestedClasses.push(subClass);
     }

generators/csharp/sdk/src/SdkGeneratorContext.ts

@@ -148,6 +148,10 @@
         if (this.hasGrpcEndpoints()) {
             files.push(AsIsFiles.RawGrpcClient);
         }
+        if (this.hasPagination()) {
+            files.push(AsIsFiles.Page);
+            files.push(AsIsFiles.Pager);
+        }
         if (this.customConfig["experimental-enable-forward-compatible-enums"] ?? false) {
             files.push(AsIsFiles.StringEnum);
             files.push(AsIsFiles.StringEnumExtensions);
@@ -158,6 +162,10 @@
         return files;
     }
 
+    public hasPagination() {
+        return this.config.generatePaginatedClients && this.ir.sdkConfig.hasPaginatedEndpoints;
+    }
+
     public getCoreTestAsIsFiles(): string[] {
         const files = [AsIsFiles.RawClientTests];
         if (this.customConfig["experimental-enable-forward-compatible-enums"] ?? false) {
@@ -492,6 +500,56 @@
         return undefined;
     }
 
+    public getPagerClassReference({ itemType }: { itemType: csharp.Type }): csharp.ClassReference {
+        return csharp.classReference({
+            namespace: this.getCoreNamespace(),
+            name: "Pager",
+            generics: [itemType]
+        });
+    }
+
+    public getOffsetPagerClassReference({
+        requestType,
+        requestOptionsType,
+        responseType,
+        offsetType,
+        stepType,
+        itemType
+    }: {
+        requestType: csharp.Type;
+        requestOptionsType: csharp.Type;
+        responseType: csharp.Type;
+        offsetType: csharp.Type;
+        stepType: csharp.Type;
+        itemType: csharp.Type;
+    }): csharp.ClassReference {
+        return csharp.classReference({
+            namespace: this.getCoreNamespace(),
+            name: "OffsetPager",
+            generics: [requestType, requestOptionsType, responseType, offsetType, stepType, itemType]
+        });
+    }
+
+    public getCursorPagerClassReference({
+        requestType,
+        requestOptionsType,
+        responseType,
+        cursorType,
+        itemType
+    }: {
+        requestType: csharp.Type;
+        requestOptionsType: csharp.Type;
+        responseType: csharp.Type;
+        cursorType: csharp.Type;
+        itemType: csharp.Type;
+    }): csharp.ClassReference {
+        return csharp.classReference({
+            namespace: this.getCoreNamespace(),
+            name: "CursorPager",
+            generics: [requestType, requestOptionsType, responseType, cursorType, itemType]
+        });
+    }
+
     public resolveEndpointOrThrow(service: HttpService, endpointId: EndpointId): HttpEndpoint {
         const httpEndpoint = service.endpoints.find((endpoint) => endpoint.id === endpointId);
         if (httpEndpoint == null) {