ani-client 1.6.1 → 1.8.0

package/README.md

@@ -1,39 +1,40 @@
-# 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)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/ani-client)](https://bundlephobia.com/package/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).
-
-✨ **Showcase**: [Check here](https://ani-client.js.org/showcase) to see which projects use this package!
-
-- **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!
+> A fully typed, zero-dependency client for the [AniList](https://anilist.co) GraphQL API.
 
-## 📖 Documentation
+✨ **Showcase**: [See who's using ani-client](https://ani-client.js.org/showcase)
 
-The full API reference, usage guide, and configuration examples are available on our official documentation website!
+## Highlights
 
-**[👉 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 +44,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,
+});
+
+// Cross-platform lookup by MyAnimeList ID
+const fma = await client.getMediaByMalId(5114);
+```
+
+## Features at a glance
+
+### Caching & 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
+  },
 });
-console.log(results.results.map((m) => m.title.english));
+
+// Check cache performance
+console.log(client.cacheStats);
+// { hits: 42, misses: 8, stales: 2, hitRate: 0.84 }
 ```
 
-### Fetch user favorites
+### Per-request cancellation
 
 ```ts
-const favs = await client.getUserFavorites("AniList");
+const controller = new AbortController();
+const scoped = client.withSignal(controller.signal);
+
+setTimeout(() => controller.abort(), 3_000);
+const anime = await scoped.getMedia(1);
+```
+
+### Structured logging
 
-favs.anime.forEach((a) => console.log(a.title.romaji));
-favs.characters.forEach((c) => console.log(c.name.full));
+```ts
+const client = new AniListClient({ logger: console });
+// debug: "API request"  { query: "query { Media(id: 1) { ... } }" }
+// debug: "Request complete" { durationMs: 120, status: 200 }
 ```
 
-### Monitor rate limits
+### 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
 

package/dist/index.d.mts

@@ -50,6 +50,12 @@ interface CacheOptions {
     maxSize?: number;
     /** Set to false to disable caching entirely */
     enabled?: boolean;
+    /**
+     * Stale-while-revalidate grace period in milliseconds (default: 0 = disabled).
+     * When set, expired entries are still returned within the grace window,
+     * allowing the caller to refresh in the background.
+     */
+    staleWhileRevalidateMs?: number;
 }
 /** Rate limiter configuration options. */
 interface RateLimitOptions {
@@ -111,6 +117,16 @@ interface ResponseMeta {
     /** Rate limit information from the API response headers (not present for cached responses). */
     rateLimitInfo?: RateLimitInfo;
 }
+/**
+ * Minimal logger interface for structured log output.
+ * Compatible with `console`, `pino`, `winston`, etc.
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
 interface AniListClientOptions {
     /** Optional AniList OAuth token for authenticated requests */
     token?: string;
@@ -126,6 +142,17 @@ interface AniListClientOptions {
     hooks?: AniListHooks;
     /** Optional AbortSignal to cancel all requests made by this client */
     signal?: AbortSignal;
+    /**
+     * Optional logger for structured log output.
+     * Accepts any object with `debug`, `info`, `warn`, `error` methods.
+     * Compatible with `console`, `pino`, `winston`, etc.
+     *
+     * @example
+     * ```ts
+     * const client = new AniListClient({ logger: console });
+     * ```
+     */
+    logger?: Logger;
 }
 
 declare enum StaffSort {
@@ -225,21 +252,11 @@ interface SearchStaffOptions {
     perPage?: number;
 }
 /** Compact voice actor data returned inside character edges. */
-interface VoiceActor {
-    id: number;
-    name: {
-        first: string | null;
-        middle: string | null;
-        last: string | null;
-        full: string | null;
-        native: string | null;
+interface VoiceActor extends Pick<Staff, "id" | "image" | "gender" | "primaryOccupations" | "siteUrl"> {
+    name: StaffName & {
         userPreferred: string | null;
     };
     languageV2: string | null;
-    image: StaffImage;
-    gender: string | null;
-    primaryOccupations: string[];
-    siteUrl: string | null;
 }
 
 declare enum CharacterSort {
@@ -389,11 +406,31 @@ interface Studio {
 interface StudioConnection {
     nodes: Studio[];
 }
+declare enum StudioSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    NAME = "NAME",
+    NAME_DESC = "NAME_DESC",
+    SEARCH_MATCH = "SEARCH_MATCH",
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC"
+}
 interface SearchStudioOptions {
     query?: string;
+    sort?: StudioSort[];
     page?: number;
     perPage?: number;
 }
+/**
+ * Options for controlling embedded media when fetching a single studio.
+ * Pass `{ media: { perPage: 50 } }` to fetch more media per studio.
+ */
+interface StudioIncludeOptions {
+    /** Customize the number of media returned. `true` = 25 (default), or `{ perPage }`. */
+    media?: boolean | {
+        perPage?: number;
+    };
+}
 
 declare enum UserSort {
     ID = "ID",
@@ -443,18 +480,10 @@ interface SearchUserOptions {
 }
 interface FavoriteMediaNode {
     id: number;
-    title: {
-        romaji: string | null;
-        english: string | null;
-        native: string | null;
-        userPreferred: string | null;
-    };
-    coverImage: {
-        large: string | null;
-        medium: string | null;
-    };
-    type: string | null;
-    format: string | null;
+    title: MediaTitle;
+    coverImage: Pick<MediaCoverImage, "large" | "medium">;
+    type: MediaType | null;
+    format: MediaFormat | null;
     siteUrl: string | null;
 }
 interface FavoriteCharacterNode {
@@ -493,6 +522,13 @@ interface UserFavorites {
     staff: FavoriteStaffNode[];
     studios: FavoriteStudioNode[];
 }
+/**
+ * Options for controlling the number of results when fetching user favorites.
+ */
+interface UserFavoritesOptions {
+    /** Number of items per category (default: 25, max: 50). */
+    perPage?: number;
+}
 
 declare enum MediaType {
     ANIME = "ANIME",
@@ -658,7 +694,7 @@ interface ScoreDistribution {
     amount: number;
 }
 interface StatusDistribution {
-    status: MediaListStatus | string;
+    status: MediaListStatus;
     amount: number;
 }
 interface MediaStats {
@@ -889,17 +925,9 @@ interface ThreadCategory {
 }
 interface ThreadMediaCategory {
     id: number;
-    title: {
-        romaji: string | null;
-        english: string | null;
-        native: string | null;
-        userPreferred: string | null;
-    };
-    type: string;
-    coverImage: {
-        large: string | null;
-        medium: string | null;
-    } | null;
+    title: MediaTitle;
+    type: MediaType;
+    coverImage: Pick<MediaCoverImage, "large" | "medium"> | null;
     siteUrl: string | null;
 }
 /** Sort options for thread queries. */
@@ -961,6 +989,7 @@ declare class AniListClient {
     private readonly cacheAdapter;
     private readonly rateLimiter;
     private readonly hooks;
+    private readonly logger?;
     private readonly signal?;
     private readonly inFlight;
     private _rateLimitInfo?;
@@ -1006,8 +1035,23 @@ declare class AniListClient {
     getTopRated(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
     /** Get recently aired anime episodes. */
     getAiredEpisodes(options?: GetAiringOptions): Promise<PagedResult<AiringSchedule>>;
-    /** Get currently releasing manga. */
+    /**
+     * Get currently releasing manga sorted by most recently updated.
+     *
+     * @param options - Pagination parameters
+     */
+    getRecentlyUpdatedManga(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
+    /**
+     * @deprecated Use `getRecentlyUpdatedManga` instead. This alias will be removed in v2.
+     */
     getAiredChapters(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
+    /**
+     * Fetch a media entry by its MyAnimeList (MAL) ID.
+     *
+     * @param malId - The MyAnimeList ID
+     * @param type - Optional media type to disambiguate (some MAL IDs map to both ANIME and MANGA)
+     */
+    getMediaByMalId(malId: number, type?: MediaType): Promise<Media>;
     /** Get the detailed schedule for the current week, sorted by day. */
     getWeeklySchedule(date?: Date): Promise<WeeklySchedule>;
     /** Get upcoming (not yet released) media. */
@@ -1038,17 +1082,29 @@ declare class AniListClient {
      * Fetch a user's favorite anime, manga, characters, staff, and studios.
      *
      * @param idOrName - AniList user ID (number) or username (string)
+     * @param options - Optional pagination options (perPage per category)
      * @returns The user's favorites grouped by category
      *
      * @example
      * ```typescript
      * const favs = await client.getUserFavorites("AniList");
      * favs.anime.forEach(a => console.log(a.title.romaji));
+     *
+     * // Fetch more results per category
+     * const moreResults = await client.getUserFavorites(1, { perPage: 50 });
      * ```
      */
-    getUserFavorites(idOrName: number | string): Promise<UserFavorites>;
-    /** Fetch a studio by its AniList ID. */
-    getStudio(id: number): Promise<Studio>;
+    getUserFavorites(idOrName: number | string, options?: UserFavoritesOptions): Promise<UserFavorites>;
+    /**
+     * Fetch a studio by its AniList ID.
+     * Pass `include` to customise the number of media returned.
+     *
+     * @example
+     * ```typescript
+     * const studio = await client.getStudio(21, { media: { perPage: 50 } });
+     * ```
+     */
+    getStudio(id: number, include?: StudioIncludeOptions): Promise<Studio>;
     /** Search for studios by name. */
     searchStudios(options?: SearchStudioOptions): Promise<PagedResult<Studio>>;
     /** Fetch a forum thread by its AniList ID. */
@@ -1084,6 +1140,20 @@ declare class AniListClient {
     invalidateCache(pattern: string | RegExp): Promise<number>;
     /** Clean up resources held by the client. */
     destroy(): Promise<void>;
+    /**
+     * Return a scoped view of this client where every request uses the given `AbortSignal`.
+     * The returned object shares the same cache, rate limiter, and hooks.
+     *
+     * @example
+     * ```ts
+     * const controller = new AbortController();
+     * const media = await client.withSignal(controller.signal).getMedia(1);
+     *
+     * // Cancel all in-flight requests made through the scoped view
+     * controller.abort();
+     * ```
+     */
+    withSignal(signal: AbortSignal): AniListClient;
 }
 
 /**
@@ -1097,26 +1167,59 @@ declare class AniListError extends Error {
     constructor(message: string, status: number, errors?: unknown[]);
 }
 
+/** Cache performance statistics. */
+interface CacheStats {
+    /** Total cache hits. */
+    hits: number;
+    /** Total cache misses. */
+    misses: number;
+    /** Stale entries returned (only with stale-while-revalidate). */
+    stales: number;
+    /** Hit rate as a ratio 0–1 (NaN if no requests yet). */
+    hitRate: number;
+}
 declare class MemoryCache implements CacheAdapter {
     private readonly ttl;
     private readonly maxSize;
     private readonly enabled;
+    private readonly swrMs;
     private readonly store;
+    private _hits;
+    private _misses;
+    private _stales;
     constructor(options?: CacheOptions);
     /** Build a deterministic cache key from a query + variables pair. */
     static key(query: string, variables: Record<string, unknown>): string;
-    /** Retrieve a cached value, or `undefined` if missing / expired. */
+    /**
+     * Retrieve a cached value, or `undefined` if missing / expired.
+     * With stale-while-revalidate enabled, returns stale data within the grace window
+     * and flags it so the caller can refresh in the background.
+     */
     get<T>(key: string): T | undefined;
     /** Store a value in the cache. */
     set<T>(key: string, data: T): void;
     /** Remove a specific entry. */
     delete(key: string): boolean;
-    /** Clear the entire cache. */
+    /** Clear the entire cache and reset statistics. */
     clear(): void;
     /** Number of entries currently stored. */
     get size(): number | Promise<number>;
     /** Return all cache keys. */
     keys(): string[];
+    /**
+     * Get cache performance statistics.
+     *
+     * @example
+     * ```ts
+     * const cache = new MemoryCache();
+     * // ... after some usage ...
+     * console.log(cache.stats);
+     * // { hits: 42, misses: 8, stales: 0, hitRate: 0.84 }
+     * ```
+     */
+    get stats(): CacheStats;
+    /** Reset cache statistics without clearing stored data. */
+    resetStats(): void;
     /**
      * Remove all entries whose key matches the given pattern.
      *
@@ -1245,19 +1348,6 @@ declare class RateLimiter {
     dispose(): void;
 }
 
-/**
- * Parses AniList specific markdown into standard HTML.
- * Includes formatting for spoilers, images, videos (youtube/webm), headings,
- * lists, code blocks, and standard markdown elements.
- *
- * @security This function escapes HTML entities to prevent XSS attacks.
- * However, the output is still raw HTML — consumers should always use a
- * Content Security Policy and consider additional sanitization when rendering
- * user-generated content in a browser.
- *
- * @param text The AniList markdown text to parse
- * @returns The parsed HTML string
- */
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, 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 GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, 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 ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, 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 Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, 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 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 ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, 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 };