ani-client 2.1.0 → 2.1.2

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.d.mts

@@ -29,6 +29,17 @@ interface ExternalLink {
 interface CacheAdapter {
     /** Retrieve a cached value, or `undefined` if missing / expired. */
     get<T>(key: string): T | undefined | Promise<T | undefined>;
+    /**
+     * Retrieve a cached value along with its stale status (for stale-while-revalidate).
+     * If implemented, the client will use this to trigger background revalidation.
+     */
+    getWithMeta?<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined | Promise<{
+        data: T;
+        stale: boolean;
+    } | undefined>;
     /** Store a value in the cache. */
     set<T>(key: string, data: T): void | Promise<void>;
     /** Remove a specific entry. Returns `true` if the key existed. */
@@ -1070,6 +1081,47 @@ interface SearchThreadOptions {
     perPage?: number;
 }
 
+/**
+ * Normalized Cache Adapter for AniListClient.
+ *
+ * This cache intercepts GraphQL responses, extracts objects with `__typename` and `id`,
+ * and stores them flat in an entity store.
+ * This ensures data consistency across all queries (e.g., `getMedia(1)` and `searchMedia`
+ * share the exact same `Media` object).
+ */
+declare class NormalizedCache implements CacheAdapter {
+    private readonly ttl;
+    private readonly maxSize;
+    private readonly enabled;
+    private readonly swrMs;
+    private readonly queryStore;
+    private readonly entityStore;
+    private _hits;
+    private _misses;
+    private _stales;
+    constructor(options?: CacheOptions);
+    static key(query: string, variables: Record<string, unknown>): string;
+    /** Normalizes a GraphQL response, extracting entities and returning a tree of references. */
+    private normalize;
+    /** Reconstructs a GraphQL response from references. */
+    private denormalize;
+    getWithMeta<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, data: T): void;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): string[];
+    invalidate(pattern: string | RegExp): number;
+    get stats(): CacheStats & {
+        entitiesCount: number;
+    };
+    resetStats(): void;
+}
+
 /** Cache performance statistics. */
 interface CacheStats {
     /** Total cache hits. */
@@ -1098,6 +1150,13 @@ declare class MemoryCache implements CacheAdapter {
      * With stale-while-revalidate enabled, returns stale data within the grace window
      * and flags it so the caller can refresh in the background.
      */
+    /**
+     * Retrieve a cached value and its stale status.
+     */
+    getWithMeta<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined;
     get<T>(key: string): T | undefined;
     /** Store a value in the cache. */
     set<T>(key: string, data: T): void;
@@ -1473,4 +1532,4 @@ declare class RateLimiter {
 
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type Review, ReviewSort, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchReviewOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, NormalizedCache, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type Review, ReviewSort, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchReviewOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };

package/dist/index.d.ts

@@ -29,6 +29,17 @@ interface ExternalLink {
 interface CacheAdapter {
     /** Retrieve a cached value, or `undefined` if missing / expired. */
     get<T>(key: string): T | undefined | Promise<T | undefined>;
+    /**
+     * Retrieve a cached value along with its stale status (for stale-while-revalidate).
+     * If implemented, the client will use this to trigger background revalidation.
+     */
+    getWithMeta?<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined | Promise<{
+        data: T;
+        stale: boolean;
+    } | undefined>;
     /** Store a value in the cache. */
     set<T>(key: string, data: T): void | Promise<void>;
     /** Remove a specific entry. Returns `true` if the key existed. */
@@ -1070,6 +1081,47 @@ interface SearchThreadOptions {
     perPage?: number;
 }
 
+/**
+ * Normalized Cache Adapter for AniListClient.
+ *
+ * This cache intercepts GraphQL responses, extracts objects with `__typename` and `id`,
+ * and stores them flat in an entity store.
+ * This ensures data consistency across all queries (e.g., `getMedia(1)` and `searchMedia`
+ * share the exact same `Media` object).
+ */
+declare class NormalizedCache implements CacheAdapter {
+    private readonly ttl;
+    private readonly maxSize;
+    private readonly enabled;
+    private readonly swrMs;
+    private readonly queryStore;
+    private readonly entityStore;
+    private _hits;
+    private _misses;
+    private _stales;
+    constructor(options?: CacheOptions);
+    static key(query: string, variables: Record<string, unknown>): string;
+    /** Normalizes a GraphQL response, extracting entities and returning a tree of references. */
+    private normalize;
+    /** Reconstructs a GraphQL response from references. */
+    private denormalize;
+    getWithMeta<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, data: T): void;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): string[];
+    invalidate(pattern: string | RegExp): number;
+    get stats(): CacheStats & {
+        entitiesCount: number;
+    };
+    resetStats(): void;
+}
+
 /** Cache performance statistics. */
 interface CacheStats {
     /** Total cache hits. */
@@ -1098,6 +1150,13 @@ declare class MemoryCache implements CacheAdapter {
      * With stale-while-revalidate enabled, returns stale data within the grace window
      * and flags it so the caller can refresh in the background.
      */
+    /**
+     * Retrieve a cached value and its stale status.
+     */
+    getWithMeta<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined;
     get<T>(key: string): T | undefined;
     /** Store a value in the cache. */
     set<T>(key: string, data: T): void;
@@ -1473,4 +1532,4 @@ declare class RateLimiter {
 
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type Review, ReviewSort, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchReviewOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, NormalizedCache, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type Review, ReviewSort, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchReviewOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };