ani-client 1.7.0 → 1.8.1

package/README.md

@@ -1,39 +1,38 @@
-# ani-client 
+# ani-client
 
-![ani-client logo](docs/public/assets/logo.png)
 [![CI](https://github.com/gonzyui/ani-client/actions/workflows/ci.yml/badge.svg)](https://github.com/gonzyui/ani-client/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/ani-client)](https://www.npmjs.com/package/ani-client)
+[![npm version](https://img.shields.io/npm/v/ani-client)](https://www.npmjs.com/package/ani-client)
+[![npm downloads](https://img.shields.io/npm/dm/ani-client)](https://www.npmjs.com/package/ani-client)
+[![codecov](https://codecov.io/gh/gonzyui/ani-client/graph/badge.svg)](https://codecov.io/gh/gonzyui/ani-client)
+[![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 simple, typed client to fetch anime, manga, character, staff and user data from [AniList](https://anilist.co).
+> A fully typed, zero-dependency client for the [AniList](https://anilist.co) GraphQL API.
 
-✨ **Showcase**: [Check here](https://ani-client.js.org/showcase) to see which projects use this package!
+✨ **Showcase**: [See who's using ani-client](https://ani-client.js.org/showcase)
 
-- **Zero dependencies** — uses the native `fetch` API
-- **Universal** — Node.js ≥ 20, Bun, Deno and modern browsers
-- **Dual format** — ships ESM + CJS with full TypeScript declarations
-- **Reliable** — Built-in caching, Rate-limit protections with exponential backoff, automatic retries & request deduplication!
-
-## 📖 Documentation
+## Highlights
 
-The full API reference, usage guide, and configuration examples are available on our official documentation website!
-
-**[👉 View the full documentation here](https://ani-client.js.org)**
+- **Zero dependencies** — uses the native `fetch` API
+- **Universal** — Node.js ≥ 20, Bun, Deno, and modern browsers
+- **Dual format** — ships ESM + CJS with full `.d.ts` declarations
+- **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
+- **Auto-pagination** — async iterator that yields items across pages
+- **AbortSignal support** — cancel globally or per-request with `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
 
 ## Install
 
 ```bash
-# npm
 npm install ani-client
-
-# pnpm
+# or
 pnpm add ani-client
-
-# yarn
+# or
 yarn add ani-client
-
-# bun
-bun add ani-client
 ```
 
 ## Quick start
@@ -43,59 +42,118 @@ import { AniListClient, MediaType } from "ani-client";
 
 const client = new AniListClient();
 
-// Get an anime by ID
-const cowboyBebop = await client.getMedia(1);
-console.log(cowboyBebop.title.romaji); // "Cowboy Bebop"
+// Fetch an anime by AniList ID
+const bebop = await client.getMedia(1);
+console.log(bebop.title.romaji); // "Cowboy Bebop"
 
-// Search for anime
+// Search with filters
 const results = await client.searchMedia({
   query: "Naruto",
   type: MediaType.ANIME,
-  perPage: 5,
+  genres: ["Action"],
+  perPage: 10,
 });
-console.log(results.results.map((m) => m.title.english));
+
+// Cross-platform lookup by MyAnimeList ID
+const fma = await client.getMediaByMalId(5114);
 ```
 
-### Fetch user favorites
+## Features at a glance
+
+### Caching & stale-while-revalidate
 
 ```ts
-const favs = await client.getUserFavorites("AniList");
+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
+  },
+});
 
-favs.anime.forEach((a) => console.log(a.title.romaji));
-favs.characters.forEach((c) => console.log(c.name.full));
+// Check cache performance
+console.log(client.cacheStats);
+// { hits: 42, misses: 8, stales: 2, hitRate: 0.84 }
 ```
 
-### Monitor rate limits
+### 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);
+```
+
+### Structured logging
+
+```ts
+const client = new AniListClient({ logger: console });
+// debug: "API request"  { query: "query { Media(id: 1) { ... } }" }
+// debug: "Request complete" { durationMs: 120, status: 200 }
+```
+
+### Rate limiting & retries
 
 ```ts
 const client = new AniListClient({
   rateLimit: {
+    maxRequests: 85,
+    windowMs: 60_000,
+    maxRetries: 3,
+    retryOnNetworkError: true,
     retryStrategy: (attempt) => (attempt + 1) * 1000, // linear backoff
   },
 });
 
-await client.getMedia(1);
+console.log(client.rateLimitInfo);
+// { remaining: 82, limit: 85, reset: 1741104000 }
+```
 
-const info = client.rateLimitInfo;
-console.log(`${info?.remaining}/${info?.limit} requests remaining`);
+### Batch & pagination
 
-const meta = client.lastRequestMeta;
-console.log(`${meta?.durationMs}ms, cache: ${meta?.fromCache}`);
+```ts
+// Fetch 100 anime in 2 API calls (50 per batch)
+const batch = await client.getMediaBatch([1, 2, 3, /* ...up to 100 IDs */]);
+
+// Auto-paginate through all results
+for await (const anime of client.paginate(
+  (page) => client.searchMedia({ query: "Gundam", page, perPage: 50 }),
+  5, // max 5 pages
+)) {
+  console.log(anime.title.romaji);
+}
 ```
 
-### Cancel requests
+### Users, characters, studios & more
 
 ```ts
-const controller = new AbortController();
-const client = new AniListClient({ signal: controller.signal });
-
-setTimeout(() => controller.abort(), 5_000);
-await client.getMedia(1); // aborted after 5s
+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();
 ```
 
+## Documentation
+
+Full API reference, guides (caching, pagination, includes, hooks, etc.) and configuration examples:
+
+**[ani-client.js.org](https://ani-client.js.org)**
+
+## Requirements
+
+| Runtime | Version |
+| --- | --- |
+| Node.js | ≥ 20 |
+| Bun | ≥ 1.0 |
+| Deno | ≥ 1.28 |
+| Browsers | Any with `fetch` + `AbortController` |
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to submit changes.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and PR guidelines.
 
 ## License