feat(csharp): Add custom pager

fern/pages/changelogs/csharp-sdk/2025-02-28.mdx

@@ -0,0 +1,3 @@
+## 1.12.0-rc0
+**`(feat):`** Add support for custom pagination.
+

generators/csharp/codegen/package.json

@@ -30,7 +30,7 @@
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/base-generator": "workspace:*",
     "@fern-api/logging-execa": "workspace:*",
-    "@fern-fern/ir-sdk": "^55.4.0",
+    "@fern-fern/ir-sdk": "^56.0.0",
     "lodash-es": "^4.17.21",
     "zod": "^3.22.3"
   },

generators/csharp/codegen/src/AsIs.ts

@@ -18,6 +18,7 @@ export const AsIsFiles = {
     HttpMethodExtensions: "HttpMethodExtensions.cs",
     Page: "Page.Template.cs",
     Pager: "Pager.Template.cs",
+    CustomPager: "CustomPager.Template.cs",
     ProtoAnyMapper: "ProtoAnyMapper.Template.cs",
     RawClient: "RawClient.Template.cs",
     RawGrpcClient: "RawGrpcClient.Template.cs",

generators/csharp/codegen/src/FileGenerator.ts

@@ -12,10 +12,20 @@ export abstract class FileGenerator<
     constructor(protected readonly context: Context) {}
 
     public generate(): GeneratedFile {
-        this.context.logger.debug(`Generating ${this.getFilepath()}`);
+        if (this.shouldGenerate()) {
+            this.context.logger.debug(`Generating ${this.getFilepath()}`);
+        } else {
+            this.context.logger.warn(
+                `Internal warning: Generating ${this.getFilepath()} even though the file generator should not have been called.`
+            );
+        }
         return this.doGenerate();
     }
 
+    public shouldGenerate(): boolean {
+        return true;
+    }
+
     protected abstract doGenerate(): GeneratedFile;
 
     protected abstract getFilepath(): RelativeFilePath;

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

@@ -0,0 +1,153 @@
+using System.Runtime.CompilerServices;
+using global::System.Net.Http;
+
+namespace <%= namespace%>;
+
+internal static class CustomPagerFactory
+{
+    public static async Task<CustomPager<TItem>> CreateAsync<TItem>(
+        Func<HttpRequestMessage, CancellationToken,
+            Task<HttpResponseMessage>> sendRequest,
+        HttpRequestMessage initialRequest,
+        CancellationToken cancellationToken = default
+    )
+    {
+        var response = await sendRequest(initialRequest, cancellationToken).ConfigureAwait(false);
+        var (
+            nextPageRequest,
+            hasNextPage,
+            previousPageRequest,
+            hasPreviousPage,
+            page
+            ) = await CustomPager<TItem>.ParseHttpCallAsync(initialRequest, response, cancellationToken)
+            .ConfigureAwait(false);
+        return new CustomPager<TItem>(
+            sendRequest,
+            nextPageRequest,
+            hasNextPage,
+            previousPageRequest,
+            hasPreviousPage,
+            page
+        );
+    }
+}
+
+public class CustomPager<TItem> : BiPager<TItem>, IAsyncEnumerable<TItem>
+{
+    private HttpRequestMessage? _nextPageRequest;
+    private HttpRequestMessage? _previousPageRequest;
+
+    private readonly Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> _sendRequest;
+
+    public bool HasNextPage { get; private set; }
+    public bool HasPreviousPage { get; private set; }
+    public Page<TItem> CurrentPage { get; private set; }
+
+    public CustomPager(
+        Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> sendRequest,
+        HttpRequestMessage? nextPageRequest,
+        bool hasNextPage,
+        HttpRequestMessage? previousPageRequest,
+        bool hasPreviousPage,
+        Page<TItem> page
+    )
+    {
+        _sendRequest = sendRequest;
+        _nextPageRequest = nextPageRequest;
+        HasNextPage = hasNextPage;
+        _previousPageRequest = previousPageRequest;
+        HasPreviousPage = hasPreviousPage;
+        CurrentPage = page;
+    }
+
+    public async Task<Page<TItem>> GetNextPageAsync(CancellationToken cancellationToken = default)
+    {
+        if (_nextPageRequest == null)
+        {
+            return Page<TItem>.Empty;
+        }
+
+        return await SendRequestAndHandleResponse(_nextPageRequest, cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    public async Task<Page<TItem>> GetPreviousPageAsync(CancellationToken cancellationToken = default)
+    {
+        if (_previousPageRequest == null)
+        {
+            return Page<TItem>.Empty;
+        }
+
+        return await SendRequestAndHandleResponse(_previousPageRequest, cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    private async Task<Page<TItem>> SendRequestAndHandleResponse(
+        HttpRequestMessage request,
+        CancellationToken cancellationToken = default)
+    {
+        var response = await _sendRequest(request, cancellationToken).ConfigureAwait(false);
+        var (
+            nextPageRequest,
+            hasNextPage,
+            previousPageRequest,
+            hasPreviousPage,
+            page
+            ) = await ParseHttpCallAsync(request, response, cancellationToken).ConfigureAwait(false);
+        _nextPageRequest = nextPageRequest;
+        HasNextPage = hasNextPage;
+        _previousPageRequest = previousPageRequest;
+        HasPreviousPage = hasPreviousPage;
+        CurrentPage = page;
+        return page;
+    }
+
+    internal static async Task<(
+        HttpRequestMessage? nextPageRequest,
+        bool hasNextPage,
+        HttpRequestMessage? previousPageRequest,
+        bool hasPreviousPage,
+        Page<TItem> page
+        )> ParseHttpCallAsync(
+        HttpRequestMessage request,
+        HttpResponseMessage response,
+        CancellationToken cancellationToken = default
+    )
+    {
+        throw new NotImplementedException();
+    }
+
+    public async IAsyncEnumerator<TItem> GetAsyncEnumerator(CancellationToken cancellationToken = default)
+    {
+        foreach (var item in CurrentPage)
+        {
+            yield return item;
+        }
+
+        await foreach (var page in GetNextPagesAsync(cancellationToken))
+        {
+            foreach (var item in page)
+            {
+                yield return item;
+            }
+        }
+    }
+
+    public async IAsyncEnumerable<Page<TItem>> GetNextPagesAsync(
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        while (HasNextPage)
+        {
+            yield return await GetNextPageAsync(cancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    public async IAsyncEnumerable<Page<TItem>> GetPreviousPagesAsync(
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        while (HasPreviousPage)
+        {
+            yield return await GetPreviousPageAsync(cancellationToken).ConfigureAwait(false);
+        }
+    }
+}

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

@@ -1,4 +1,5 @@
 using System.Collections;
+using System.Collections.ObjectModel;
 
 namespace <%= namespace%>;
 
@@ -9,6 +10,10 @@ namespace <%= namespace%>;
 /// <typeparam name="TItem">The type of items.</typeparam>
 public class Page<TItem> : IEnumerable<TItem>
 {
+    /// <summary>
+    /// Creates a new <see cref="Page{TItem}"/> with the specified items.
+    /// </summary>
+    /// <param name="items"></param>
     public Page(IReadOnlyList<TItem> items)
     {
         Items = items;
@@ -19,7 +24,25 @@ public Page(IReadOnlyList<TItem> items)
     /// </summary>
     public IReadOnlyList<TItem> Items { get; }
 
+    /// <summary>
+    /// Enumerate the items in this <see cref="Page{TItem}"/>.
+    /// </summary>
+    /// <returns></returns>
     public IEnumerator<TItem> GetEnumerator() => Items.GetEnumerator();
 
+    /// <summary>
+    /// Enumerate the items in this <see cref="Page{TItem}"/>.
+    /// </summary>
+    /// <returns></returns>
     IEnumerator IEnumerable.GetEnumerator() => Items.GetEnumerator();
+
+    /// <summary>
+    /// An empty <see cref="Page{TItem}"/>.
+    /// </summary>
+    public static Page<TItem> Empty { get; } = new(new ReadOnlyCollection<TItem>(Array.Empty<TItem>()));
+
+    /// <summary>
+    /// Indicates whether this <see cref="Page{TItem}"/> is empty.
+    /// </summary>
+    public bool IsEmpty => Items.Count == 0;
 }

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

@@ -43,6 +43,47 @@ public virtual async IAsyncEnumerator<TItem> GetAsyncEnumerator(
     }
 }
 
+/// <summary>
+/// Interface for implementing pagination in two directions.
+/// </summary>
+/// <typeparam name="TItem">The type of the values.</typeparam>
+// ReSharper disable once InconsistentNaming
+public interface BiPager<TItem>
+{
+    /// <summary>
+    /// Get the current <see cref="Page{TItem}"/>.
+    /// </summary>
+    public Page<TItem> CurrentPage { get; }
+
+    /// <summary>
+    /// Indicates whether there is a next page.
+    /// </summary>
+    public bool HasNextPage { get; }
+
+    /// <summary>
+    /// Indicates whether there is a previous page.
+    /// </summary>
+    public bool HasPreviousPage { get; }
+
+    /// <summary>
+    /// Get the next <see cref="Page{TItem}"/>.
+    /// </summary>
+    /// <param name="cancellationToken"></param>
+    /// <returns>
+    /// The next <see cref="Page{TItem}"/>.
+    /// </returns>
+    public Task<Page<TItem>> GetNextPageAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Get the previous <see cref="Page{TItem}"/>.
+    /// </summary>
+    /// <param name="cancellationToken"></param>
+    /// <returns>
+    /// The previous <see cref="Page{TItem}"/>.
+    /// </returns>
+    public Task<Page<TItem>> GetPreviousPageAsync(CancellationToken cancellationToken = default);
+}
+
 internal sealed class OffsetPager<TRequest, TRequestOptions, TResponse, TOffset, TStep, TItem>
     : Pager<TItem>
 {
@@ -97,10 +138,11 @@ public override async IAsyncEnumerable<Page<TItem>> AsPagesAsync(
     )
     {
         var hasStep = false;
-        if(_getStep is not null)
+        if (_getStep is not null)
         {
             hasStep = _getStep(_request) is not null;
         }
+
         var offset = _getOffset(_request);
         var longOffset = Convert.ToInt64(offset);
         bool hasNextPage;
@@ -204,4 +246,4 @@ public override async IAsyncEnumerable<Page<TItem>> AsPagesAsync(
             _setCursor(_request, nextCursor);
         } while (true);
     }
-}
+}