Added better Pagination support via IAsyncEnumerable

.editorconfig

@@ -13,6 +13,7 @@ dotnet_diagnostic.CA1056.severity = none
 dotnet_diagnostic.CA1034.severity = none
 dotnet_diagnostic.CA1054.severity = none
 dotnet_diagnostic.CA2227.severity = none
+dotnet_diagnostic.CA1308.severity = none
 # Sort using and Import directives with System.* appearing first
 dotnet_sort_system_directives_first = true
 dotnet_style_require_accessibility_modifiers = always:warning

SpotifyAPI.Docs/docs/configuration.md

@@ -1,4 +0,0 @@
----
-id: configuration
-title: Configuration
----

SpotifyAPI.Docs/docs/getting_started.md

@@ -0,0 +1,4 @@
+---
+id: getting_started
+title: Getting Started
+---

SpotifyAPI.Docs/docusaurus.config.js

@@ -26,7 +26,7 @@ module.exports = {
           items: [
             {
               label: 'Latest/Next',
-              to: 'docs/next/home',
+              to: 'docs/next/introduction',
             },
             {
               label: versions[0],

SpotifyAPI.Docs/sidebars.js

@@ -3,7 +3,7 @@ module.exports = {
     'Spotify-API': [
       'introduction',
       'installation',
-      'configuration',
+      'getting_started',
       {
         type: 'category',
         label: 'Guides',
@@ -11,6 +11,11 @@ module.exports = {
           'pagination',
         ]
       },
+      {
+        type: 'category',
+        label: 'Examples',
+        items: []
+      },
     ]
   }
 };

SpotifyAPI.Docs/src/pages/index.js

@@ -16,9 +16,12 @@ const exampleCode =
 var me = await spotify.UserProfile.Current();
 Console.WriteLine($"Hello there {me.DisplayName}");
 
-var playlists = await spotify.Paginate(() => spotify.Playlists.CurrentUsers());
+await foreach(var playlist in spotify.Paginate(
-Console.WriteLine($"You got {playlists.Count} playlists 🚀");
+  () => spotify.Playlists.CurrentUsers()
-`;
+))
+{
+  Console.WriteLine(playlist.Name);
+}`;
 
 const installCodeNuget =
   `# Core Package
@@ -108,7 +111,7 @@ function Home() {
                     'button button--outline button--secondary button--lg',
                     styles.getStarted,
                   )}
-                  to={useBaseUrl('docs/next/home')}>
+                  to={useBaseUrl('docs/next/introduction')}>
                   Get Started
                 </Link>
               </div>

SpotifyAPI.Web.Examples/Example.CLI.PersistentConfig/Program.cs

@@ -53,7 +53,7 @@ namespace Example.CLI.PersistentConfig
       var me = await spotify.UserProfile.Current();
       Console.WriteLine($"Welcome {me.DisplayName} ({me.Id}), your authenticated!");
 
-      var playlists = await spotify.Paginate(await spotify.Playlists.CurrentUsers());
+      var playlists = await spotify.PaginateAll(() => spotify.Playlists.CurrentUsers());
       Console.WriteLine($"Total Playlists in your Account: {playlists.Count}");
 
       Environment.Exit(0);

SpotifyAPI.Web.Examples/Example.UWP/ViewModels/PlaylistsListViewModel.cs

@@ -16,7 +16,8 @@ namespace Example.UWP.ViewModels
     private SpotifyClient _spotify;
 
     private List<SimplePlaylist> _playlists;
-    public List<SimplePlaylist> Playlists {
+    public List<SimplePlaylist> Playlists
+    {
       get => _playlists ?? (_playlists = new List<SimplePlaylist>());
       set => SetProperty(ref _playlists, value);
     }
@@ -30,7 +31,7 @@ namespace Example.UWP.ViewModels
     {
       await base.Initialize();
 
-      Playlists = await _spotify.Paginate(() => _spotify.Playlists.CurrentUsers());
+      Playlists = await _spotify.PaginateAll(() => _spotify.Playlists.CurrentUsers());
     }
   }
 }

SpotifyAPI.Web/Clients/Interfaces/IPaginator.cs

@@ -1,3 +1,4 @@
+using System.Threading;
 using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
@@ -7,10 +8,21 @@ namespace SpotifyAPI.Web
 {
   public interface IPaginator
   {
-    Task<List<T>> Paginate<T>(Paging<T> firstPage, IAPIConnector connector);
+    Task<List<T>> PaginateAll<T>(Paging<T> firstPage, IAPIConnector connector);
-    Task<List<T>> Paginate<T>(Func<Task<Paging<T>>> getFirstPage, IAPIConnector connector);
+    Task<List<T>> PaginateAll<T, TNext>(
+      Paging<T, TNext> firstPage,
+      Func<TNext, Paging<T, TNext>> mapper,
+      IAPIConnector connector
+    );
 
-    Task<List<T>> Paginate<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper, IAPIConnector connector);
+#if NETSTANDARD2_1
-    Task<List<T>> Paginate<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper, IAPIConnector connector);
+    IAsyncEnumerable<T> Paginate<T>(Paging<T> firstPage, IAPIConnector connector, CancellationToken cancel = default);
+    IAsyncEnumerable<T> Paginate<T, TNext>(
+      Paging<T, TNext> firstPage,
+      Func<TNext, Paging<T, TNext>> mapper,
+      IAPIConnector connector,
+      CancellationToken cancel = default
+    );
+#endif
   }
 }

SpotifyAPI.Web/Clients/Interfaces/ISpotifyClient.cs

@@ -34,11 +34,26 @@ namespace SpotifyAPI.Web
 
     ILibraryClient Library { get; }
 
-    Task<List<T>> Paginate<T>(Paging<T> firstPage);
+    Task<List<T>> PaginateAll<T>(Paging<T> firstPage);
-    Task<List<T>> Paginate<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper);
+    Task<List<T>> PaginateAll<T>(Paging<T> firstPage, IPaginator paginator);
-    Task<List<T>> Paginate<T>(Func<Task<Paging<T>>> getFirstPage);
+    Task<List<T>> PaginateAll<T>(Func<Task<Paging<T>>> getFirstPage);
-    Task<List<T>> Paginate<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper);
+    Task<List<T>> PaginateAll<T>(Func<Task<Paging<T>>> getFirstPage, IPaginator paginator);
-    Task<List<T>> Paginate<T>(Paging<T> firstPage, IPaginator paginator);
+
-    Task<List<T>> Paginate<T>(Func<Task<Paging<T>>> getFirstPage, IPaginator paginator);
+    Task<List<T>> PaginateAll<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper);
+    Task<List<T>> PaginateAll<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper, IPaginator paginator);
+    Task<List<T>> PaginateAll<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper);
+    Task<List<T>> PaginateAll<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper, IPaginator paginator);
+
+#if NETSTANDARD2_1
+    IAsyncEnumerable<T> Paginate<T>(Paging<T> firstPage);
+    IAsyncEnumerable<T> Paginate<T>(Paging<T> firstPage, IPaginator paginator);
+    IAsyncEnumerable<T> Paginate<T>(Func<Task<Paging<T>>> getFirstPage);
+    IAsyncEnumerable<T> Paginate<T>(Func<Task<Paging<T>>> getFirstPage, IPaginator paginator);
+
+    IAsyncEnumerable<T> Paginate<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper);
+    IAsyncEnumerable<T> Paginate<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper, IPaginator paginator);
+    IAsyncEnumerable<T> Paginate<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper);
+    IAsyncEnumerable<T> Paginate<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper, IPaginator paginator);
+#endif
   }
 }

SpotifyAPI.Web/Clients/SimplePaginator.cs

@@ -1,7 +1,9 @@
+using System.Threading;
 using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 using SpotifyAPI.Web.Http;
+using System.Runtime.CompilerServices;
 
 namespace SpotifyAPI.Web
 {
@@ -16,7 +18,7 @@ namespace SpotifyAPI.Web
       return Task.FromResult(true);
     }
 
-    public async Task<List<T>> Paginate<T>(Paging<T> firstPage, IAPIConnector connector)
+    public async Task<List<T>> PaginateAll<T>(Paging<T> firstPage, IAPIConnector connector)
     {
       Ensure.ArgumentNotNull(firstPage, nameof(firstPage));
       Ensure.ArgumentNotNull(connector, nameof(connector));
@@ -33,15 +35,7 @@ namespace SpotifyAPI.Web
       return results;
     }
 
-    public async Task<List<T>> Paginate<T>(Func<Task<Paging<T>>> getFirstPage, IAPIConnector connector)
+    public async Task<List<T>> PaginateAll<T, TNext>(
-    {
-      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
-
-      var firstPage = await getFirstPage().ConfigureAwait(false);
-      return await Paginate(firstPage, connector).ConfigureAwait(false);
-    }
-
-    public async Task<List<T>> Paginate<T, TNext>(
       Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper, IAPIConnector connector
     )
     {
@@ -62,12 +56,55 @@ namespace SpotifyAPI.Web
       return results;
     }
 
-    public async Task<List<T>> Paginate<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper, IAPIConnector connector)
+#if NETSTANDARD2_1
+    public async IAsyncEnumerable<T> Paginate<T>(
+      Paging<T> firstPage,
+      IAPIConnector connector,
+      [EnumeratorCancellation] CancellationToken cancel = default)
     {
-      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+      Ensure.ArgumentNotNull(firstPage, nameof(firstPage));
+      Ensure.ArgumentNotNull(connector, nameof(connector));
 
-      var firstPage = await getFirstPage().ConfigureAwait(false);
+      var page = firstPage;
-      return await Paginate(firstPage, mapper, connector).ConfigureAwait(false);
+      foreach (var item in page.Items)
+      {
+        yield return item;
+      }
+      while (page.Next != null)
+      {
+        page = await connector.Get<Paging<T>>(new Uri(page.Next, UriKind.Absolute)).ConfigureAwait(false);
+        foreach (var item in page.Items)
+        {
+          yield return item;
+        }
+      }
     }
+
+    public async IAsyncEnumerable<T> Paginate<T, TNext>(
+      Paging<T, TNext> firstPage,
+      Func<TNext, Paging<T, TNext>> mapper,
+      IAPIConnector connector,
+      [EnumeratorCancellation] CancellationToken cancel = default)
+    {
+      Ensure.ArgumentNotNull(firstPage, nameof(firstPage));
+      Ensure.ArgumentNotNull(mapper, nameof(mapper));
+      Ensure.ArgumentNotNull(connector, nameof(connector));
+
+      var page = firstPage;
+      foreach (var item in page.Items)
+      {
+        yield return item;
+      }
+      while (page.Next != null)
+      {
+        var next = await connector.Get<TNext>(new Uri(page.Next, UriKind.Absolute)).ConfigureAwait(false);
+        page = mapper(next);
+        foreach (var item in page.Items)
+        {
+          yield return item;
+        }
+      }
+    }
+#endif
   }
 }

SpotifyAPI.Web/Clients/SpotifyClient.cs

@@ -73,38 +73,161 @@ namespace SpotifyAPI.Web
 
     public ILibraryClient Library { get; }
 
-    public Task<List<T>> Paginate<T>(Paging<T> firstPage)
+    public Task<List<T>> PaginateAll<T>(Paging<T> firstPage)
+    {
+      return DefaultPaginator.PaginateAll(firstPage, _apiConnector);
+    }
+
+    public Task<List<T>> PaginateAll<T>(Paging<T> firstPage, IPaginator paginator)
+    {
+      Ensure.ArgumentNotNull(paginator, nameof(paginator));
+
+      return paginator.PaginateAll(firstPage, _apiConnector);
+    }
+
+    public async Task<List<T>> PaginateAll<T>(Func<Task<Paging<T>>> getFirstPage)
+    {
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+
+      return await DefaultPaginator.PaginateAll(
+        await getFirstPage().ConfigureAwait(false), _apiConnector
+      ).ConfigureAwait(false);
+    }
+
+    public async Task<List<T>> PaginateAll<T>(Func<Task<Paging<T>>> getFirstPage, IPaginator paginator)
+    {
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+      Ensure.ArgumentNotNull(paginator, nameof(paginator));
+
+      return await paginator.PaginateAll(
+        await getFirstPage().ConfigureAwait(false), _apiConnector
+      ).ConfigureAwait(false);
+    }
+
+    public Task<List<T>> PaginateAll<T, TNext>(
+      Paging<T, TNext> firstPage,
+      Func<TNext, Paging<T, TNext>> mapper
+    )
+    {
+      return DefaultPaginator.PaginateAll(firstPage, mapper, _apiConnector);
+    }
+
+    public async Task<List<T>> PaginateAll<T, TNext>(
+      Func<Task<Paging<T, TNext>>> getFirstPage,
+      Func<TNext, Paging<T, TNext>> mapper
+    )
+    {
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+
+      return await DefaultPaginator.PaginateAll(await getFirstPage().ConfigureAwait(false), mapper, _apiConnector).ConfigureAwait(false);
+    }
+
+    public Task<List<T>> PaginateAll<T, TNext>(
+      Paging<T, TNext> firstPage,
+      Func<TNext, Paging<T, TNext>> mapper,
+      IPaginator paginator)
+    {
+      Ensure.ArgumentNotNull(paginator, nameof(paginator));
+
+      return paginator.PaginateAll(firstPage, mapper, _apiConnector);
+    }
+
+    public async Task<List<T>> PaginateAll<T, TNext>(
+      Func<Task<Paging<T, TNext>>> getFirstPage,
+      Func<TNext, Paging<T, TNext>> mapper,
+      IPaginator paginator
+    )
+    {
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+      Ensure.ArgumentNotNull(paginator, nameof(paginator));
+
+      return await paginator.PaginateAll(
+        await getFirstPage().ConfigureAwait(false), mapper, _apiConnector
+      ).ConfigureAwait(false);
+    }
+
+
+#if NETSTANDARD2_1
+    public IAsyncEnumerable<T> Paginate<T>(Paging<T> firstPage)
     {
       return DefaultPaginator.Paginate(firstPage, _apiConnector);
     }
 
-    public Task<List<T>> Paginate<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper)
+    public IAsyncEnumerable<T> Paginate<T>(Paging<T> firstPage, IPaginator paginator)
-    {
-      return DefaultPaginator.Paginate(firstPage, mapper, _apiConnector);
-    }
-
-    public Task<List<T>> Paginate<T>(Paging<T> firstPage, IPaginator paginator)
     {
       Ensure.ArgumentNotNull(paginator, nameof(paginator));
 
       return paginator.Paginate(firstPage, _apiConnector);
     }
 
-    public Task<List<T>> Paginate<T>(Func<Task<Paging<T>>> getFirstPage)
+    public async IAsyncEnumerable<T> Paginate<T>(Func<Task<Paging<T>>> getFirstPage)
     {
-      return DefaultPaginator.Paginate(getFirstPage, _apiConnector);
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+
+      var firstPage = await getFirstPage().ConfigureAwait(false);
+      await foreach (var item in DefaultPaginator.Paginate(firstPage, _apiConnector))
+      {
+        yield return item;
+      }
     }
 
-    public Task<List<T>> Paginate<T, TNext>(Func<Task<Paging<T, TNext>>> getFirstPage, Func<TNext, Paging<T, TNext>> mapper)
+    public async IAsyncEnumerable<T> Paginate<T>(Func<Task<Paging<T>>> getFirstPage, IPaginator paginator)
     {
-      return DefaultPaginator.Paginate(getFirstPage, mapper, _apiConnector);
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+      Ensure.ArgumentNotNull(paginator, nameof(paginator));
+
+      var firstPage = await getFirstPage().ConfigureAwait(false);
+      await foreach (var item in DefaultPaginator.Paginate(firstPage, _apiConnector))
+      {
+        yield return item;
+      }
     }
 
-    public Task<List<T>> Paginate<T>(Func<Task<Paging<T>>> getFirstPage, IPaginator paginator)
+    public IAsyncEnumerable<T> Paginate<T, TNext>(Paging<T, TNext> firstPage, Func<TNext, Paging<T, TNext>> mapper)
+    {
+      return DefaultPaginator.Paginate(firstPage, mapper, _apiConnector);
+    }
+
+    public IAsyncEnumerable<T> Paginate<T, TNext>(
+      Paging<T, TNext> firstPage,
+      Func<TNext, Paging<T, TNext>> mapper,
+      IPaginator paginator
+    )
     {
       Ensure.ArgumentNotNull(paginator, nameof(paginator));
 
-      return paginator.Paginate(getFirstPage, _apiConnector);
+      return paginator.Paginate(firstPage, mapper, _apiConnector);
     }
+
+    public async IAsyncEnumerable<T> Paginate<T, TNext>(
+      Func<Task<Paging<T, TNext>>> getFirstPage,
+      Func<TNext, Paging<T, TNext>> mapper
+    )
+    {
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+
+      var firstPage = await getFirstPage().ConfigureAwait(false);
+      await foreach (var item in DefaultPaginator.Paginate(firstPage, mapper, _apiConnector))
+      {
+        yield return item;
+      }
+    }
+
+    public async IAsyncEnumerable<T> Paginate<T, TNext>(
+      Func<Task<Paging<T, TNext>>> getFirstPage,
+      Func<TNext, Paging<T, TNext>> mapper,
+      IPaginator paginator
+    )
+    {
+      Ensure.ArgumentNotNull(getFirstPage, nameof(getFirstPage));
+      Ensure.ArgumentNotNull(paginator, nameof(paginator));
+
+      var firstPage = await getFirstPage().ConfigureAwait(false);
+      await foreach (var item in paginator.Paginate(firstPage, mapper, _apiConnector))
+      {
+        yield return item;
+      }
+    }
+#endif
   }
 }

SpotifyAPI.Web/Models/Request/LoginRequest.cs

@@ -1,3 +1,4 @@
+using System.Globalization;
 using System;
 using System.Collections.Generic;
 using System.Text;
@@ -28,7 +29,7 @@ namespace SpotifyAPI.Web
     {
       StringBuilder builder = new StringBuilder(SpotifyUrls.Authorize.ToString());
       builder.Append($"?client_id={ClientId}");
-      builder.Append($"&response_type={ResponseTypeParam.ToString().ToLower()}");
+      builder.Append($"&response_type={ResponseTypeParam.ToString().ToLower(CultureInfo.InvariantCulture)}");
       builder.Append($"&redirect_uri={HttpUtility.UrlEncode(RedirectUri.ToString())}");
       if (!string.IsNullOrEmpty(State))
       {