ani-client 1.2.0 → 1.4.0

package/dist/index.d.mts

@@ -29,21 +29,37 @@ declare enum MediaSeason {
 }
 declare enum MediaSort {
     ID = "ID",
+    ID_DESC = "ID_DESC",
     TITLE_ROMAJI = "TITLE_ROMAJI",
+    TITLE_ROMAJI_DESC = "TITLE_ROMAJI_DESC",
     TITLE_ENGLISH = "TITLE_ENGLISH",
+    TITLE_ENGLISH_DESC = "TITLE_ENGLISH_DESC",
     TITLE_NATIVE = "TITLE_NATIVE",
+    TITLE_NATIVE_DESC = "TITLE_NATIVE_DESC",
     TYPE = "TYPE",
+    TYPE_DESC = "TYPE_DESC",
     FORMAT = "FORMAT",
+    FORMAT_DESC = "FORMAT_DESC",
     START_DATE = "START_DATE",
+    START_DATE_DESC = "START_DATE_DESC",
     END_DATE = "END_DATE",
+    END_DATE_DESC = "END_DATE_DESC",
     SCORE = "SCORE",
+    SCORE_DESC = "SCORE_DESC",
     POPULARITY = "POPULARITY",
+    POPULARITY_DESC = "POPULARITY_DESC",
     TRENDING = "TRENDING",
+    TRENDING_DESC = "TRENDING_DESC",
     EPISODES = "EPISODES",
+    EPISODES_DESC = "EPISODES_DESC",
     DURATION = "DURATION",
+    DURATION_DESC = "DURATION_DESC",
     STATUS = "STATUS",
+    STATUS_DESC = "STATUS_DESC",
     FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC",
     UPDATED_AT = "UPDATED_AT",
+    UPDATED_AT_DESC = "UPDATED_AT_DESC",
     SEARCH_MATCH = "SEARCH_MATCH"
 }
 declare enum AiringSort {
@@ -58,9 +74,17 @@ declare enum AiringSort {
 }
 declare enum CharacterSort {
     ID = "ID",
+    ID_DESC = "ID_DESC",
     ROLE = "ROLE",
+    ROLE_DESC = "ROLE_DESC",
     SEARCH_MATCH = "SEARCH_MATCH",
-    FAVOURITES = "FAVOURITES"
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC"
+}
+declare enum CharacterRole {
+    MAIN = "MAIN",
+    SUPPORTING = "SUPPORTING",
+    BACKGROUND = "BACKGROUND"
 }
 interface MediaTitle {
     romaji: string | null;
@@ -135,6 +159,51 @@ interface CharacterImage {
     large: string | null;
     medium: string | null;
 }
+interface MediaCharacterEdge {
+    role: CharacterRole;
+    node: Omit<Character, "media">;
+}
+interface MediaCharacterConnection {
+    edges: MediaCharacterEdge[];
+}
+interface MediaStaffEdge {
+    role: string;
+    node: Staff;
+}
+interface MediaStaffConnection {
+    edges: MediaStaffEdge[];
+}
+interface StreamingEpisode {
+    title: string | null;
+    thumbnail: string | null;
+    url: string | null;
+    site: string | null;
+}
+interface ExternalLink {
+    id: number;
+    url: string | null;
+    site: string;
+    type: string | null;
+    icon: string | null;
+    color: string | null;
+}
+interface ScoreDistribution {
+    score: number;
+    amount: number;
+}
+interface StatusDistribution {
+    status: MediaListStatus | string;
+    amount: number;
+}
+interface MediaStats {
+    scoreDistribution: ScoreDistribution[];
+    statusDistribution: StatusDistribution[];
+}
+interface MediaRecommendationNode {
+    id: number;
+    rating: number | null;
+    mediaRecommendation: Pick<Media, "id" | "title" | "type" | "format" | "coverImage" | "averageScore" | "siteUrl">;
+}
 interface Media {
     id: number;
     idMal: number | null;
@@ -168,6 +237,14 @@ interface Media {
     tags: MediaTag[];
     studios: StudioConnection;
     relations: MediaConnection | null;
+    characters?: MediaCharacterConnection;
+    staff?: MediaStaffConnection;
+    streamingEpisodes?: StreamingEpisode[];
+    externalLinks?: ExternalLink[];
+    stats?: MediaStats;
+    recommendations?: {
+        nodes: MediaRecommendationNode[];
+    };
     isAdult: boolean | null;
     siteUrl: string | null;
 }
@@ -207,7 +284,7 @@ interface Staff {
     gender: string | null;
     dateOfBirth: FuzzyDate | null;
     dateOfDeath: FuzzyDate | null;
-    age: number | null;
+    age: string | null;
     yearsActive: number[];
     homeTown: string | null;
     bloodType: string | null;
@@ -280,10 +357,7 @@ interface SearchCharacterOptions {
 }
 interface SearchStaffOptions {
     query?: string;
-    page?: number;
-    perPage?: number;
-}
-interface PaginatedOptions {
+    sort?: CharacterSort[];
     page?: number;
     perPage?: number;
 }
@@ -439,33 +513,108 @@ interface SearchStudioOptions {
     page?: number;
     perPage?: number;
 }
+/**
+ * Options to include additional related data when fetching a media entry.
+ * Pass `true` to include with defaults, or an object to customize.
+ */
+interface MediaIncludeOptions {
+    /** Include characters with their roles (MAIN, SUPPORTING, BACKGROUND).
+     *  `true` = 25 results sorted by role. Object form to customize. */
+    characters?: boolean | {
+        perPage?: number;
+        sort?: boolean;
+    };
+    /** Include staff members with their roles.
+     *  `true` = 25 results sorted by relevance. Object form to customize. */
+    staff?: boolean | {
+        perPage?: number;
+        sort?: boolean;
+    };
+    /** Include relations (default: `true` for backward compat). Set to `false` to exclude. */
+    relations?: boolean;
+    /** Include streaming episode links (Crunchyroll, Funimation, etc.) */
+    streamingEpisodes?: boolean;
+    /** Include external links (MAL, official site, etc.) */
+    externalLinks?: boolean;
+    /** Include score & status distribution stats */
+    stats?: boolean;
+    /** Include user recommendations. `true` = 10 results, or customize with `{ perPage }`. */
+    recommendations?: boolean | {
+        perPage?: number;
+    };
+}
+/**
+ * Interface that all cache adapters must implement.
+ * Methods may return sync values or Promises — the client awaits all calls.
+ */
+interface CacheAdapter {
+    /** Retrieve a cached value, or `undefined` if missing / expired. */
+    get<T>(key: string): T | undefined | Promise<T | 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. */
+    delete(key: string): boolean | Promise<boolean>;
+    /** Clear the entire cache. */
+    clear(): void | Promise<void>;
+    /** Number of entries currently stored (sync). Returns -1 if unknown. */
+    readonly size: number;
+    /** Return all cache keys. */
+    keys(): string[] | Promise<string[]>;
+    /** Bulk-remove entries matching a pattern. Optional — the client provides a fallback. */
+    invalidate?(pattern: string | RegExp): number | Promise<number>;
+}
+/** Cache configuration options. */
+interface CacheOptions {
+    /** Time-to-live in milliseconds (default: 86 400 000 = 24h) */
+    ttl?: number;
+    /** Maximum number of cached entries (default: 500, 0 = unlimited) */
+    maxSize?: number;
+    /** Set to false to disable caching entirely */
+    enabled?: boolean;
+}
+/** Rate limiter configuration options. */
+interface RateLimitOptions {
+    /** Max requests per window (default: 85) */
+    maxRequests?: number;
+    /** Window size in ms (default: 60 000) */
+    windowMs?: number;
+    /** Max retries on 429 (default: 3) */
+    maxRetries?: number;
+    /** Retry delay in ms when Retry-After header is absent (default: 2000) */
+    retryDelayMs?: number;
+    /** Set to false to disable rate limiting entirely */
+    enabled?: boolean;
+    /** Timeout per request in ms (default: 30 000). 0 = no timeout. */
+    timeoutMs?: number;
+    /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
+    retryOnNetworkError?: boolean;
+}
+/** Event hooks for logging, debugging, and monitoring. */
+interface AniListHooks {
+    /** Called before every API request. */
+    onRequest?: (query: string, variables: Record<string, unknown>) => void;
+    /** Called when a response is served from cache. */
+    onCacheHit?: (key: string) => void;
+    /** Called when the rate limiter enforces a wait (429 received). */
+    onRateLimit?: (retryAfterMs: number) => void;
+    /** Called when a request is retried (429 or network error). */
+    onRetry?: (attempt: number, reason: string, delayMs: number) => void;
+    /** Called when a request completes. */
+    onResponse?: (query: string, durationMs: number, fromCache: boolean) => void;
+}
 interface AniListClientOptions {
     /** Optional AniList OAuth token for authenticated requests */
     token?: string;
     /** Custom API endpoint (defaults to https://graphql.anilist.co) */
     apiUrl?: string;
     /** Cache configuration (enabled by default, 24h TTL) */
-    cache?: {
-        /** Time-to-live in milliseconds (default: 86 400 000 = 24h) */
-        ttl?: number;
-        /** Maximum number of cached entries (default: 500, 0 = unlimited) */
-        maxSize?: number;
-        /** Set to false to disable caching entirely */
-        enabled?: boolean;
-    };
+    cache?: CacheOptions;
+    /** Custom cache adapter (e.g. RedisCache). Takes precedence over `cache`. */
+    cacheAdapter?: CacheAdapter;
     /** Rate limiter configuration (enabled by default, 85 req/min) */
-    rateLimit?: {
-        /** Max requests per window (default: 85) */
-        maxRequests?: number;
-        /** Window size in ms (default: 60 000) */
-        windowMs?: number;
-        /** Max retries on 429 (default: 3) */
-        maxRetries?: number;
-        /** Retry delay in ms when Retry-After header is absent (default: 2000) */
-        retryDelayMs?: number;
-        /** Set to false to disable rate limiting entirely */
-        enabled?: boolean;
-    };
+    rateLimit?: RateLimitOptions;
+    /** Event hooks for logging, debugging, and monitoring */
+    hooks?: AniListHooks;
 }
 
 /**
@@ -489,20 +638,60 @@ interface AniListClientOptions {
 declare class AniListClient {
     private readonly apiUrl;
     private readonly headers;
-    private readonly cache;
+    private readonly cacheAdapter;
     private readonly rateLimiter;
+    private readonly hooks;
+    private readonly inFlight;
     constructor(options?: AniListClientOptions);
     /**
      * @internal
      */
     private request;
+    /** @internal */
+    private executeRequest;
+    /**
+     * @internal
+     * Shorthand for paginated queries that follow the `Page { pageInfo, <field>[] }` pattern.
+     */
+    private pagedRequest;
+    /**
+     * @internal
+     * Clamp perPage to AniList's maximum of 50.
+     */
+    private clampPerPage;
     /**
      * Fetch a single media entry by its AniList ID.
      *
+     * Optionally include related data (characters, staff, relations, etc.) via the `include` parameter.
+     *
      * @param id - The AniList media ID
+     * @param include - Optional related data to include
      * @returns The media object
+     *
+     * @example
+     * ```ts
+     * // Basic usage — same as before (includes relations by default)
+     * const anime = await client.getMedia(1);
+     *
+     * // Include characters sorted by role, 25 results
+     * const anime = await client.getMedia(1, { characters: true });
+     *
+     * // Full control
+     * const anime = await client.getMedia(1, {
+     *   characters: { perPage: 50, sort: true },
+     *   staff: true,
+     *   relations: true,
+     *   streamingEpisodes: true,
+     *   externalLinks: true,
+     *   stats: true,
+     *   recommendations: { perPage: 5 },
+     * });
+     *
+     * // Exclude relations for a lighter response
+     * const anime = await client.getMedia(1, { characters: true, relations: false });
+     * ```
      */
-    getMedia(id: number): Promise<Media>;
+    getMedia(id: number, include?: MediaIncludeOptions): Promise<Media>;
     /**
      * Search for anime or manga.
      *
@@ -529,26 +718,78 @@ declare class AniListClient {
     getTrending(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
     /**
      * Fetch a character by AniList ID.
+     *
+     * @param id - The AniList character ID
+     * @returns The character object
+     *
+     * @example
+     * ```ts
+     * const spike = await client.getCharacter(1);
+     * console.log(spike.name.full); // "Spike Spiegel"
+     * ```
      */
     getCharacter(id: number): Promise<Character>;
     /**
      * Search for characters by name.
+     *
+     * @param options - Search / pagination parameters
+     * @returns Paginated results with matching characters
+     *
+     * @example
+     * ```ts
+     * const result = await client.searchCharacters({ query: "Luffy", perPage: 5 });
+     * ```
      */
     searchCharacters(options?: SearchCharacterOptions): Promise<PagedResult<Character>>;
     /**
      * Fetch a staff member by AniList ID.
+     *
+     * @param id - The AniList staff ID
+     * @returns The staff object
+     *
+     * @example
+     * ```ts
+     * const staff = await client.getStaff(95001);
+     * console.log(staff.name.full);
+     * ```
      */
     getStaff(id: number): Promise<Staff>;
     /**
      * Search for staff (voice actors, directors, etc.).
+     *
+     * @param options - Search / pagination parameters
+     * @returns Paginated results with matching staff
+     *
+     * @example
+     * ```ts
+     * const result = await client.searchStaff({ query: "Miyazaki", perPage: 5 });
+     * ```
      */
     searchStaff(options?: SearchStaffOptions): Promise<PagedResult<Staff>>;
     /**
      * Fetch a user by AniList ID.
+     *
+     * @param id - The AniList user ID
+     * @returns The user object
+     *
+     * @example
+     * ```ts
+     * const user = await client.getUser(1);
+     * console.log(user.name);
+     * ```
      */
     getUser(id: number): Promise<User>;
     /**
      * Fetch a user by username.
+     *
+     * @param name - The AniList username
+     * @returns The user object
+     *
+     * @example
+     * ```ts
+     * const user = await client.getUserByName("AniList");
+     * console.log(user.statistics);
+     * ```
      */
     getUserByName(name: string): Promise<User>;
     /**
@@ -729,14 +970,48 @@ declare class AniListClient {
      * ```
      */
     paginate<T>(fetchPage: (page: number) => Promise<PagedResult<T>>, maxPages?: number): AsyncGenerator<T, void, undefined>;
+    /**
+     * Fetch multiple media entries in a single API request.
+     * Uses GraphQL aliases to batch up to 50 IDs per call.
+     *
+     * @param ids - Array of AniList media IDs
+     * @returns Array of media objects (same order as input IDs)
+     */
+    getMediaBatch(ids: number[]): Promise<Media[]>;
+    /**
+     * Fetch multiple characters in a single API request.
+     *
+     * @param ids - Array of AniList character IDs
+     * @returns Array of character objects (same order as input IDs)
+     */
+    getCharacterBatch(ids: number[]): Promise<Character[]>;
+    /**
+     * Fetch multiple staff members in a single API request.
+     *
+     * @param ids - Array of AniList staff IDs
+     * @returns Array of staff objects (same order as input IDs)
+     */
+    getStaffBatch(ids: number[]): Promise<Staff[]>;
+    /** @internal */
+    private executeBatch;
+    /** @internal */
+    private chunk;
     /**
      * Clear the entire response cache.
      */
-    clearCache(): void;
+    clearCache(): Promise<void>;
     /**
-     * Number of entries currently in the cache.
+     * Number of entries currently in the cache (sync).
+     * For async adapters like Redis, this may be approximate.
      */
     get cacheSize(): number;
+    /**
+     * Remove cache entries whose key matches the given pattern.
+     *
+     * @param pattern — A string (converted to RegExp) or RegExp
+     * @returns Number of entries removed
+     */
+    invalidateCache(pattern: string | RegExp): Promise<number>;
 }
 
 /**
@@ -750,19 +1025,7 @@ declare class AniListError extends Error {
     constructor(message: string, status: number, errors?: unknown[]);
 }
 
-/**
- * Simple in-memory cache with configurable TTL.
- * Used internally by AniListClient to avoid redundant API calls.
- */
-interface CacheOptions {
-    /** Time-to-live in milliseconds (default: 24 hours) */
-    ttl?: number;
-    /** Maximum number of entries to keep (default: 500, 0 = unlimited) */
-    maxSize?: number;
-    /** Disable caching entirely (default: false) */
-    enabled?: boolean;
-}
-declare class MemoryCache {
+declare class MemoryCache implements CacheAdapter {
     private readonly ttl;
     private readonly maxSize;
     private readonly enabled;
@@ -780,6 +1043,87 @@ declare class MemoryCache {
     clear(): void;
     /** Number of entries currently stored. */
     get size(): number;
+    /** Return all cache keys. */
+    keys(): string[];
+    /**
+     * Remove all entries whose key matches the given pattern.
+     *
+     * @param pattern — A string (converted to RegExp) or RegExp.
+     * @returns Number of entries removed.
+     */
+    invalidate(pattern: string | RegExp): number;
+}
+
+/**
+ * Minimal interface representing a Redis client.
+ * Compatible with both `ioredis` and `redis` (node-redis v4+).
+ */
+interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    del(...keys: (string | string[])[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    /** Optional SCAN-based iteration — used when available to avoid blocking the server. */
+    scanIterator?(options: {
+        MATCH: string;
+        COUNT?: number;
+    }): AsyncIterable<string>;
+}
+interface RedisCacheOptions {
+    /** A Redis client instance (ioredis or node-redis). */
+    client: RedisLikeClient;
+    /** Key prefix to namespace ani-client entries (default: `"ani:"`) */
+    prefix?: string;
+    /** TTL in seconds (default: 86 400 = 24 h) */
+    ttl?: number;
+}
+/**
+ * Redis-backed cache adapter for AniListClient.
+ *
+ * @example
+ * ```ts
+ * import Redis from "ioredis";
+ * import { AniListClient, RedisCache } from "ani-client";
+ *
+ * const redis = new Redis();
+ * const client = new AniListClient({
+ *   cacheAdapter: new RedisCache({ client: redis }),
+ * });
+ * ```
+ */
+declare class RedisCache implements CacheAdapter {
+    private readonly client;
+    private readonly prefix;
+    private readonly ttl;
+    constructor(options: RedisCacheOptions);
+    private prefixedKey;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, data: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /**
+     * Collect keys matching a pattern. Uses SCAN when available, falls back to KEYS.
+     *
+     * **Warning:** The `KEYS` fallback is O(N) and blocks the Redis server.
+     * Provide a client with `scanIterator` support for production use.
+     * @internal
+     */
+    private collectKeys;
+    clear(): Promise<void>;
+    /**
+     * Returns -1 because Redis keys can expire silently via TTL.
+     * Use `getSize()` for an accurate count.
+     */
+    get size(): number;
+    /** Get the actual number of keys with this prefix in Redis. */
+    getSize(): Promise<number>;
+    keys(): Promise<string[]>;
+    /**
+     * Remove all entries whose key matches the given glob pattern.
+     *
+     * @param pattern — A glob pattern (e.g. `"*Media*"`)
+     * @returns Number of entries removed.
+     */
+    invalidate(pattern: string | RegExp): Promise<number>;
 }
 
 /**
@@ -789,24 +1133,15 @@ declare class MemoryCache {
  * When a 429 (Too Many Requests) is received, the client
  * waits for the Retry-After header and retries automatically.
  */
-interface RateLimitOptions {
-    /** Max requests per window (default: 85, conservative under AniList's 90/min) */
-    maxRequests?: number;
-    /** Window size in milliseconds (default: 60 000 = 1 minute) */
-    windowMs?: number;
-    /** Max number of retries on 429 responses (default: 3) */
-    maxRetries?: number;
-    /** Default retry delay in ms when Retry-After header is missing (default: 2000) */
-    retryDelayMs?: number;
-    /** Disable rate limiting entirely (default: false) */
-    enabled?: boolean;
-}
+
 declare class RateLimiter {
     private readonly maxRequests;
     private readonly windowMs;
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly enabled;
+    private readonly timeoutMs;
+    private readonly retryOnNetworkError;
     /** @internal */
     private timestamps;
     constructor(options?: RateLimitOptions);
@@ -815,10 +1150,15 @@ declare class RateLimiter {
      */
     acquire(): Promise<void>;
     /**
-     * Execute a fetch with automatic retry on 429 responses.
+     * Execute a fetch with automatic retry on 429 responses and network errors.
      */
-    fetchWithRetry(url: string, init: RequestInit): Promise<Response>;
+    fetchWithRetry(url: string, init: RequestInit, hooks?: {
+        onRetry?: (attempt: number, reason: string, delayMs: number) => void;
+        onRateLimit?: (retryAfterMs: number) => void;
+    }): Promise<Response>;
+    /** @internal */
+    private fetchWithTimeout;
     private sleep;
 }
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterSort, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaListEntry, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type PaginatedOptions, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterRole, CharacterSort, type ExternalLink, 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, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };