From cba933732a5fd7eb06acd23636f9556c50514449 Mon Sep 17 00:00:00 2001
From: suzuki3jp <suzuki3.info@gmail.com>
Date: Mon, 20 Jan 2025 08:24:18 +0900
Subject: [PATCH] docs(UseCases): Expand use cases documentation for error
 handling, pagination and playlists

---
 docs/02-usecases.md | 75 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 73 insertions(+), 2 deletions(-)

diff --git a/docs/02-usecases.md b/docs/02-usecases.md
index 5c8448f..d0c320c 100644
--- a/docs/02-usecases.md
+++ b/docs/02-usecases.md
@@ -1,2 +1,73 @@
-# Use cases
-coming soon...
\ No newline at end of file
+# Use Cases
+
+## Note
+All methods in `youtubes.js` return [`Result`](https://github.com/suzuki3jp/result4js) for safe error handling.  
+Learn more about error handling with `Result` [here](./01-introduction.md#handling-errors).
+
+## Pagination
+The YouTube Data API v3 sometimes returns paginated responses.
+For such endpoints, `youtubes.js` returns data wrapped in [`Pagination`](../src/Pagination.ts) to simplify requesting additional pages.
+
+```ts
+import { ApiClient, StaticOAuthProvider } from "youtubes.js";
+
+const oauth = new StaticOAuthProvider({
+    accessToken: "ACCESS_TOKEN",
+});
+const client = new ApiClient({ oauth });
+
+const playlists = await client.playlists.getMine(); // Result<Pagination<Playlist[]>, YouTubesJsErrors>
+console.log(playlists.data); // The first page of playlists
+
+// Get the previous page
+// Returns null if no previous page exists
+const prevPage = await playlists.prev(); // Result<Pagination<Playlist>, YouTubesJsErrors> | null
+
+// Get the next page
+// Returns null if no next page exists
+const nextPage = await playlists.next(); // Result<Pagination<Playlist>, YouTubesJsErrors> | null
+
+// Get all pages
+// **NOTE**: This method may consume unnecessary quotas, so be careful when using it in actual applications.
+// We strongly recommend fetching the next page based on user actions (e.g., scrolling).
+const allPages = await playlists.all() // Result<Playlist[], YouTubesJsErrors
+if (allPages.isErr()) return; // Handling errors
+// Returns all pages in an array. For multiple items per page, returns a 2D array.
+// Use flat() to convert to a 1D array.
+const data = allPages.data.flat();
+```
+
+## `Playlists`
+To interact with the [`playlists`](https://developers.google.com/youtube/v3/docs/playlists) endpoint, use [`PlaylistManager`](../src/managers/PlaylistManager.ts).
+
+```ts
+import { ApiClient, StaticOAuthProvider } from "youtubes.js";
+
+const oauth = new StaticOAuthProvider({
+ accessToken: "ACCESS_TOKEN",
+});
+const client = new ApiClient({ oauth });
+
+// You can access to the `PlaylistManager` here.
+client.playlists
+```
+
+### Retrieving Playlists
+You can retrieve playlists using:
+
+- [`PlaylistManager#getMine`](../src/managers/PlaylistManager.ts#L57)
+- [`PlaylistManager#getByIds`](../src/managers/PlaylistManager.ts#L109)
+- [`PlaylistManager#getByChannelId`](../src/managers/PlaylistManager.ts#L162)
+
+```ts
+import { ApiClient, StaticOAuthProvider } from "youtubes.js";
+
+const oauth = new StaticOAuthProvider({
+ accessToken: "ACCESS_TOKEN",
+});
+const client = new ApiClient({ oauth });
+
+const myPlaylists = await client.playlists.getMine(); // Result<Pagination<Playlist[]>, YouTubesJsErrors>
+const playlists = await client.playlists.getByIds(["ID1", "ID2"]); // Result<Pagination<Playlist[]>, YouTubesJsErrors>
+const channelPlaylists = await client.playlists.getByChannelId("CHANNEL_ID"); // Result<Pagination<Playlist[]>, YouTubesJsErrors>
+```
\ No newline at end of file