ani-client 2.1.0 → 2.1.1

package/README.md

@@ -7,13 +7,10 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-> A fully typed, zero-dependency client for the [AniList](https://anilist.co) GraphQL API.
+> A fully typed, zero-dependency client for the [AniList](https://anilist.co) GraphQL API.  
+> Supports Node.js, Bun, Deno, and modern browsers.
 
-✨ **Showcase**: [See who's using ani-client](https://ani-client.js.org/showcase)
-
-**Support server** [Discord server](https://discord.gg/3P7twDurUD)
-
-## Highlights
+## Features
 
 - **Zero dependencies** — uses the native `fetch` API
 - **Universal** — Node.js ≥ 20, Bun, Deno, and modern browsers
@@ -21,24 +18,23 @@
 - **LRU cache** with TTL, stale-while-revalidate, and hit/miss stats
 - **Rate-limit protection** with exponential backoff, retries, and custom strategies
 - **Request deduplication** — concurrent identical queries share a single in-flight request
-- **Batch queries** — fetch up to 50 media/characters/staff in one API call
-- **Paginated media relationships** — `getMediaCharacters()` and `getMediaStaff()` support paged results for large casts and staff listings
-- **Auto-pagination** — async iterator that yields items across pages
-- **AbortSignal support** — cancel globally or per-request with `withSignal()`
+- **Batch queries** — fetch up to 50 media, characters, or staff in a single API call
+- **Auto-pagination** — async iterator that yields items across all pages
+- **AbortSignal support** — cancel globally or per-request via `withSignal()`
 - **Injectable logger** — plug in `console`, pino, winston, or any compatible logger
-- **Redis-ready** — swap the cache adapter with the built-in `RedisCache` for distributed setups
+- **Redis-ready** — swap the in-memory cache with the built-in `RedisCache` adapter
 
-## Install
+## Installation
 
 ```bash
 npm install ani-client
-# or
+# pnpm
 pnpm add ani-client
-# or
+# yarn
 yarn add ani-client
 ```
 
-## Quick start
+## Quick Start
 
 ```ts
 import { AniListClient, MediaType } from "ani-client";
@@ -57,56 +53,51 @@ const results = await client.searchMedia({
   perPage: 10,
 });
 
-// Cross-platform lookup by MyAnimeList ID
+// Lookup by MyAnimeList ID
 const fma = await client.getMediaByMalId(5114);
-
-// Paginated media relationships
-const characters = await client.getMediaCharacters(1, { page: 1, perPage: 25, voiceActors: true });
-const staff = await client.getMediaStaff(1, { page: 1, perPage: 25 });
 ```
 
-## Features at a glance
+## Usage
 
-### Caching & stale-while-revalidate
+### Caching
+
+The client caches every response in memory by default. You can tune TTL, capacity, and enable stale-while-revalidate:
 
 ```ts
 const client = new AniListClient({
   cache: {
-    ttl: 1000 * 60 * 5,               // 5 min TTL
-    maxSize: 200,                      // LRU capacity
-    staleWhileRevalidateMs: 60_000,    // serve stale for 1 min after expiry
+    ttl: 1000 * 60 * 5,            // 5 min TTL
+    maxSize: 200,                   // LRU capacity
+    staleWhileRevalidateMs: 60_000, // serve stale for 1 min after expiry
   },
 });
 
-// Check cache performance
 console.log(client.cacheStats);
 // { hits: 42, misses: 8, stales: 2, hitRate: 0.84 }
 ```
 
-### Per-request cancellation
+For distributed setups, swap to the built-in Redis adapter:
 
 ```ts
-const controller = new AbortController();
-const scoped = client.withSignal(controller.signal);
+import { AniListClient, RedisCache } from "ani-client";
+import { createClient } from "redis";
 
-setTimeout(() => controller.abort(), 3_000);
-const anime = await scoped.getMedia(1);
-```
-
-### Structured logging
+const redis = createClient();
+await redis.connect();
 
-```ts
-const client = new AniListClient({ logger: console });
-// debug: "API request"  { query: "query { Media(id: 1) { ... } }" }
-// debug: "Request complete" { durationMs: 120, status: 200 }
+const client = new AniListClient({
+  cacheAdapter: new RedisCache(redis),
+});
 ```
 
-### Rate limiting & retries
+### Rate Limiting
+
+The client is pre-configured to stay within AniList's 30 req/min limit. You can override the defaults and provide a custom retry strategy:
 
 ```ts
 const client = new AniListClient({
   rateLimit: {
-    maxRequests: 85,
+    maxRequests: 25,
     windowMs: 60_000,
     maxRetries: 3,
     retryOnNetworkError: true,
@@ -114,17 +105,26 @@ const client = new AniListClient({
   },
 });
 
+// Inspect the rate limit state after any request
 console.log(client.rateLimitInfo);
-// { remaining: 82, limit: 85, reset: 1741104000 }
+// { remaining: 22, limit: 25, reset: 1741104000 }
 ```
 
-### Batch & pagination
+### Batch Requests
+
+Fetch multiple entries in a single API call (chunks of 50):
 
 ```ts
-// Fetch 100 anime in 2 API calls (50 per batch)
-const batch = await client.getMediaBatch([1, 2, 3, /* ...up to 100 IDs */]);
+const anime = await client.getMediaBatch([1, 5, 6, 20]);
+const characters = await client.getCharacterBatch([1, 2, 3]);
+const staff = await client.getStaffBatch([95269, 95270]);
+```
+
+### Auto-Pagination
+
+Use the built-in async iterator to walk through all pages automatically:
 
-// Auto-paginate through all results
+```ts
 for await (const anime of client.paginate(
   (page) => client.searchMedia({ query: "Gundam", page, perPage: 50 }),
   5, // max 5 pages
@@ -133,32 +133,106 @@ for await (const anime of client.paginate(
 }
 ```
 
-### Users, characters, studios & more
+### Request Cancellation
+
+Scope any client instance to an `AbortSignal` for per-request cancellation:
+
+```ts
+const controller = new AbortController();
+const scoped = client.withSignal(controller.signal);
+
+setTimeout(() => controller.abort(), 3_000);
+const anime = await scoped.getMedia(1); // cancelled after 3s
+```
+
+### Logging
+
+Pass any `console`-compatible logger to trace requests and cache events:
+
+```ts
+const client = new AniListClient({ logger: console });
+// debug: "API request"    { variables: { id: 1 } }
+// debug: "Request complete" { durationMs: 120 }
+```
+
+### Media Relationships
+
+Paginated access to a media's characters and staff:
 
 ```ts
-const user = await client.getUser("AniList");
-const favs = await client.getUserFavorites("AniList", { perPage: 50 });
-const char = await client.getCharacter(1, { voiceActors: true });
-const characters = await client.getMediaCharacters(1, { page: 1, perPage: 25, voiceActors: true });
+const characters = await client.getMediaCharacters(1, {
+  page: 1,
+  perPage: 25,
+  voiceActors: true,
+});
+
 const staff = await client.getMediaStaff(1, { page: 1, perPage: 25 });
-const studio = await client.getStudio(21, { media: { perPage: 50 } });
+```
+
+### Users, Characters, Studios & More
+
+```ts
+const user     = await client.getUser("AniList");
+const favs     = await client.getUserFavorites("AniList", { perPage: 50 });
+const char     = await client.getCharacter(1, { voiceActors: true });
+const studio   = await client.getStudio(21, { media: { perPage: 50 } });
 const schedule = await client.getWeeklySchedule();
+const review   = await client.getReview(760);
+```
+
+### Error Handling
+
+All API errors throw an `AniListError` with a `status` code and the raw GraphQL `errors` array:
+
+```ts
+import { AniListError } from "ani-client";
+
+try {
+  await client.getMedia(999999999);
+} catch (e) {
+  if (e instanceof AniListError) {
+    console.error(e.message); // "Not Found"
+    console.error(e.status);  // 404
+    console.error(e.errors);  // raw GraphQL errors array
+  }
+}
 ```
 
+### Lifecycle Hooks
+
+Intercept requests, responses, cache events, and errors:
+
+```ts
+const client = new AniListClient({
+  hooks: {
+    onRequest:    (query, variables) => console.log("→", variables),
+    onResponse:   (query, durationMs, fromCache) => console.log(`← ${durationMs}ms`),
+    onCacheHit:   (key) => console.log("cache hit", key),
+    onRateLimit:  (retryAfterMs) => console.warn(`rate limited, retrying in ${retryAfterMs}ms`),
+    onError:      (error) => console.error(error.message),
+  },
+});
+```
+
+## Requirements
+
+| Runtime  | Version            |
+|----------|--------------------|
+| Node.js  | ≥ 20               |
+| Bun      | ≥ 1.0              |
+| Deno     | ≥ 1.28             |
+| Browsers | `fetch` + `AbortController` required |
+
 ## Documentation
 
-Full API reference, guides (caching, pagination, includes, hooks, etc.) and configuration examples:
+Full API reference, configuration options, and guides (caching, pagination, hooks, Redis, etc.):
 
 **[ani-client.js.org](https://ani-client.js.org)**
 
-## Requirements
+## Community
 
-| Runtime | Version |
-| --- | --- |
-| Node.js | ≥ 20 |
-| Bun | ≥ 1.0 |
-| Deno | ≥ 1.28 |
-| Browsers | Any with `fetch` + `AbortController` |
+- 💬 [Discord server](https://discord.gg/3P7twDurUD)
+- ✨ [Showcase — see who's using ani-client](https://ani-client.js.org/showcase)
 
 ## Contributing
 
@@ -166,4 +240,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards,
 
 ## License
 
-[MIT](LICENSE) © gonzyui
+[MIT](LICENSE) © [gonzyui](https://github.com/gonzyui)

package/dist/index.js

@@ -351,7 +351,7 @@ var AniListError = class _AniListError extends Error {
     this.status = status;
     this.errors = errors;
     Object.setPrototypeOf(this, _AniListError.prototype);
-    if (Error.captureStackTrace) {
+    if ("captureStackTrace" in Error) {
       Error.captureStackTrace(this, _AniListError);
     }
   }
@@ -468,18 +468,24 @@ var MEDIA_RECOMMENDATION_FIELDS = `
     title { romaji english native userPreferred }
     type
     format
-    coverImage { large medium }
+    coverImage { extraLarge large medium color }
     averageScore
     meanScore
    	episodes
    	chapters
    	volumes
-    nextAiringEpisode
+    nextAiringEpisode {
+      id
+      airingAt
+      episode
+      mediaId
+      timeUntilAiring
+    }
    	season
    	seasonYear
-   	startDate
-   	endDate
-   	studios
+   	startDate { year month day }
+    endDate { year month day }
+   	studios { nodes { id name isAnimationStudio siteUrl } }
    	genres
     siteUrl
   }
@@ -841,7 +847,7 @@ query (
       timeUntilAiring
       episode
       mediaId
-      media(isAdult: $isAdult) {
+      media {
         ${MEDIA_FIELDS_BASE}
       }
     }
@@ -2117,7 +2123,7 @@ function mapFavorites(fav) {
 
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
-var LIB_VERSION = "2.1.0" ;
+var LIB_VERSION = "2.1.1" ;
 var AniListClient = class {
   apiUrl;
   headers;