ani-client 1.7.0 → 1.8.1

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 interface PageInfo {
     total: number | null;
-    perPage: number | null;
-    currentPage: number | null;
-    lastPage: number | null;
-    hasNextPage: boolean | null;
+    perPage: number;
+    currentPage: number;
+    lastPage: number;
+    hasNextPage: boolean;
 }
 interface PagedResult<T> {
     pageInfo: PageInfo;
@@ -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,89 @@ 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 MediaListStatus {
+    CURRENT = "CURRENT",
+    PLANNING = "PLANNING",
+    COMPLETED = "COMPLETED",
+    DROPPED = "DROPPED",
+    PAUSED = "PAUSED",
+    REPEATING = "REPEATING"
+}
+declare enum MediaListSort {
+    MEDIA_ID = "MEDIA_ID",
+    MEDIA_ID_DESC = "MEDIA_ID_DESC",
+    SCORE = "SCORE",
+    SCORE_DESC = "SCORE_DESC",
+    STATUS = "STATUS",
+    STATUS_DESC = "STATUS_DESC",
+    PROGRESS = "PROGRESS",
+    PROGRESS_DESC = "PROGRESS_DESC",
+    PROGRESS_VOLUMES = "PROGRESS_VOLUMES",
+    PROGRESS_VOLUMES_DESC = "PROGRESS_VOLUMES_DESC",
+    REPEAT = "REPEAT",
+    REPEAT_DESC = "REPEAT_DESC",
+    PRIORITY = "PRIORITY",
+    PRIORITY_DESC = "PRIORITY_DESC",
+    STARTED_ON = "STARTED_ON",
+    STARTED_ON_DESC = "STARTED_ON_DESC",
+    FINISHED_ON = "FINISHED_ON",
+    FINISHED_ON_DESC = "FINISHED_ON_DESC",
+    ADDED_TIME = "ADDED_TIME",
+    ADDED_TIME_DESC = "ADDED_TIME_DESC",
+    UPDATED_TIME = "UPDATED_TIME",
+    UPDATED_TIME_DESC = "UPDATED_TIME_DESC",
+    MEDIA_TITLE_ROMAJI = "MEDIA_TITLE_ROMAJI",
+    MEDIA_TITLE_ROMAJI_DESC = "MEDIA_TITLE_ROMAJI_DESC",
+    MEDIA_TITLE_ENGLISH = "MEDIA_TITLE_ENGLISH",
+    MEDIA_TITLE_ENGLISH_DESC = "MEDIA_TITLE_ENGLISH_DESC",
+    MEDIA_TITLE_NATIVE = "MEDIA_TITLE_NATIVE",
+    MEDIA_TITLE_NATIVE_DESC = "MEDIA_TITLE_NATIVE_DESC",
+    MEDIA_POPULARITY = "MEDIA_POPULARITY",
+    MEDIA_POPULARITY_DESC = "MEDIA_POPULARITY_DESC"
+}
+interface MediaListEntry {
+    id: number;
+    mediaId: number;
+    status: MediaListStatus;
+    score: number | null;
+    progress: number | null;
+    progressVolumes: number | null;
+    repeat: number | null;
+    priority: number | null;
+    private: boolean | null;
+    notes: string | null;
+    startedAt: FuzzyDate | null;
+    completedAt: FuzzyDate | null;
+    updatedAt: number | null;
+    createdAt: number | null;
+    media: Media;
+}
+interface GetUserMediaListOptions {
+    /** User ID (provide either userId or userName) */
+    userId?: number;
+    /** Username (provide either userId or userName) */
+    userName?: string;
+    /** ANIME or MANGA */
+    type: MediaType;
+    /** Filter by list status (CURRENT, COMPLETED, etc.) */
+    status?: MediaListStatus;
+    /** Sort order */
+    sort?: MediaListSort[];
+    page?: number;
+    perPage?: number;
 }
 
 declare enum StaffSort {
@@ -232,139 +331,6 @@ interface VoiceActor extends Pick<Staff, "id" | "image" | "gender" | "primaryOcc
     languageV2: string | null;
 }
 
-declare enum CharacterSort {
-    ID = "ID",
-    ID_DESC = "ID_DESC",
-    ROLE = "ROLE",
-    ROLE_DESC = "ROLE_DESC",
-    SEARCH_MATCH = "SEARCH_MATCH",
-    FAVOURITES = "FAVOURITES",
-    FAVOURITES_DESC = "FAVOURITES_DESC"
-}
-declare enum CharacterRole {
-    MAIN = "MAIN",
-    SUPPORTING = "SUPPORTING",
-    BACKGROUND = "BACKGROUND"
-}
-interface CharacterName {
-    first: string | null;
-    middle: string | null;
-    last: string | null;
-    full: string | null;
-    native: string | null;
-    alternative: string[];
-}
-interface CharacterImage {
-    large: string | null;
-    medium: string | null;
-}
-type CharacterMediaNode = Pick<Media, "id" | "title" | "type" | "coverImage" | "siteUrl">;
-interface CharacterMediaEdge {
-    node: CharacterMediaNode;
-    voiceActors?: VoiceActor[];
-}
-interface Character {
-    id: number;
-    name: CharacterName;
-    image: CharacterImage;
-    description: string | null;
-    gender: string | null;
-    dateOfBirth: FuzzyDate | null;
-    age: string | null;
-    bloodType: string | null;
-    favourites: number | null;
-    siteUrl: string | null;
-    media: {
-        nodes?: CharacterMediaNode[];
-        edges?: CharacterMediaEdge[];
-    } | null;
-}
-/** Options for including extra data when fetching a character. */
-interface CharacterIncludeOptions {
-    /** Include voice actors for each media the character appears in. */
-    voiceActors?: boolean;
-}
-interface SearchCharacterOptions {
-    query?: string;
-    sort?: CharacterSort[];
-    page?: number;
-    perPage?: number;
-    /** Include voice actors for each media the character appears in. */
-    voiceActors?: boolean;
-}
-
-declare enum MediaListStatus {
-    CURRENT = "CURRENT",
-    PLANNING = "PLANNING",
-    COMPLETED = "COMPLETED",
-    DROPPED = "DROPPED",
-    PAUSED = "PAUSED",
-    REPEATING = "REPEATING"
-}
-declare enum MediaListSort {
-    MEDIA_ID = "MEDIA_ID",
-    MEDIA_ID_DESC = "MEDIA_ID_DESC",
-    SCORE = "SCORE",
-    SCORE_DESC = "SCORE_DESC",
-    STATUS = "STATUS",
-    STATUS_DESC = "STATUS_DESC",
-    PROGRESS = "PROGRESS",
-    PROGRESS_DESC = "PROGRESS_DESC",
-    PROGRESS_VOLUMES = "PROGRESS_VOLUMES",
-    PROGRESS_VOLUMES_DESC = "PROGRESS_VOLUMES_DESC",
-    REPEAT = "REPEAT",
-    REPEAT_DESC = "REPEAT_DESC",
-    PRIORITY = "PRIORITY",
-    PRIORITY_DESC = "PRIORITY_DESC",
-    STARTED_ON = "STARTED_ON",
-    STARTED_ON_DESC = "STARTED_ON_DESC",
-    FINISHED_ON = "FINISHED_ON",
-    FINISHED_ON_DESC = "FINISHED_ON_DESC",
-    ADDED_TIME = "ADDED_TIME",
-    ADDED_TIME_DESC = "ADDED_TIME_DESC",
-    UPDATED_TIME = "UPDATED_TIME",
-    UPDATED_TIME_DESC = "UPDATED_TIME_DESC",
-    MEDIA_TITLE_ROMAJI = "MEDIA_TITLE_ROMAJI",
-    MEDIA_TITLE_ROMAJI_DESC = "MEDIA_TITLE_ROMAJI_DESC",
-    MEDIA_TITLE_ENGLISH = "MEDIA_TITLE_ENGLISH",
-    MEDIA_TITLE_ENGLISH_DESC = "MEDIA_TITLE_ENGLISH_DESC",
-    MEDIA_TITLE_NATIVE = "MEDIA_TITLE_NATIVE",
-    MEDIA_TITLE_NATIVE_DESC = "MEDIA_TITLE_NATIVE_DESC",
-    MEDIA_POPULARITY = "MEDIA_POPULARITY",
-    MEDIA_POPULARITY_DESC = "MEDIA_POPULARITY_DESC"
-}
-interface MediaListEntry {
-    id: number;
-    mediaId: number;
-    status: MediaListStatus;
-    score: number | null;
-    progress: number | null;
-    progressVolumes: number | null;
-    repeat: number | null;
-    priority: number | null;
-    private: boolean | null;
-    notes: string | null;
-    startedAt: FuzzyDate | null;
-    completedAt: FuzzyDate | null;
-    updatedAt: number | null;
-    createdAt: number | null;
-    media: Media;
-}
-interface GetUserMediaListOptions {
-    /** User ID (provide either userId or userName) */
-    userId?: number;
-    /** Username (provide either userId or userName) */
-    userName?: string;
-    /** ANIME or MANGA */
-    type: MediaType;
-    /** Filter by list status (CURRENT, COMPLETED, etc.) */
-    status?: MediaListStatus;
-    /** Sort order */
-    sort?: MediaListSort[];
-    page?: number;
-    perPage?: number;
-}
-
 interface Studio {
     id: number;
     name: string;
@@ -394,6 +360,16 @@ interface SearchStudioOptions {
     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",
@@ -485,6 +461,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",
@@ -600,6 +583,7 @@ interface MediaTag {
     description: string | null;
     category: string | null;
     rank: number | null;
+    isAdult: boolean | null;
     isMediaSpoiler: boolean | null;
 }
 declare enum MediaRelationType {
@@ -841,36 +825,97 @@ interface AiringSchedule {
 type DayOfWeek = "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday";
 type WeeklySchedule = Record<DayOfWeek, AiringSchedule[]>;
 
-/** Represents a forum thread on AniList. */
-interface Thread {
-    id: number;
-    title: string;
-    body: string | null;
-    userId: number;
-    replyUserId: number | null;
-    replyCommentId: number | null;
-    replyCount: number;
-    viewCount: number;
-    isLocked: boolean;
-    isSticky: boolean;
-    isSubscribed: boolean;
-    repliedAt: number | null;
-    createdAt: number;
-    updatedAt: number;
-    siteUrl: string | null;
-    user: {
-        id: number;
-        name: string;
-        avatar: UserAvatar;
-    } | null;
-    replyUser: {
-        id: number;
-        name: string;
-        avatar: UserAvatar;
-    } | null;
-    categories: ThreadCategory[] | null;
-    mediaCategories: ThreadMediaCategory[] | null;
-    likes: {
+declare enum CharacterSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    ROLE = "ROLE",
+    ROLE_DESC = "ROLE_DESC",
+    SEARCH_MATCH = "SEARCH_MATCH",
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC"
+}
+declare enum CharacterRole {
+    MAIN = "MAIN",
+    SUPPORTING = "SUPPORTING",
+    BACKGROUND = "BACKGROUND"
+}
+interface CharacterName {
+    first: string | null;
+    middle: string | null;
+    last: string | null;
+    full: string | null;
+    native: string | null;
+    alternative: string[];
+}
+interface CharacterImage {
+    large: string | null;
+    medium: string | null;
+}
+type CharacterMediaNode = Pick<Media, "id" | "title" | "type" | "coverImage" | "siteUrl">;
+interface CharacterMediaEdge {
+    node: CharacterMediaNode;
+    voiceActors?: VoiceActor[];
+}
+interface Character {
+    id: number;
+    name: CharacterName;
+    image: CharacterImage;
+    description: string | null;
+    gender: string | null;
+    dateOfBirth: FuzzyDate | null;
+    age: string | null;
+    bloodType: string | null;
+    favourites: number | null;
+    siteUrl: string | null;
+    media: {
+        nodes?: CharacterMediaNode[];
+        edges?: CharacterMediaEdge[];
+    } | null;
+}
+/** Options for including extra data when fetching a character. */
+interface CharacterIncludeOptions {
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
+}
+interface SearchCharacterOptions {
+    query?: string;
+    sort?: CharacterSort[];
+    page?: number;
+    perPage?: number;
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
+}
+
+/** Represents a forum thread on AniList. */
+interface Thread {
+    id: number;
+    title: string;
+    body: string | null;
+    userId: number;
+    replyUserId: number | null;
+    replyCommentId: number | null;
+    replyCount: number;
+    viewCount: number;
+    isLocked: boolean;
+    isSticky: boolean;
+    isSubscribed: boolean;
+    repliedAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+    siteUrl: string | null;
+    user: {
+        id: number;
+        name: string;
+        avatar: UserAvatar;
+    } | null;
+    replyUser: {
+        id: number;
+        name: string;
+        avatar: UserAvatar;
+    } | null;
+    categories: ThreadCategory[] | null;
+    mediaCategories: ThreadMediaCategory[] | null;
+    likes: {
         id: number;
         name: string;
     }[] | null;
@@ -921,6 +966,145 @@ interface SearchThreadOptions {
     perPage?: number;
 }
 
+/** 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.
+     * 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 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.
+     *
+     * - **String**: treated as a substring match (e.g. `"Media"` removes all keys containing `"Media"`).
+     * - **RegExp**: tested against each key directly.
+     *
+     * @param pattern — A string (substring match) 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>;
+    /**
+     * Get the actual number of keys with this prefix in Redis.
+     */
+    get size(): Promise<number>;
+    /** @internal */
+    private getSize;
+    keys(): Promise<string[]>;
+    /**
+     * Remove all entries whose key matches the given pattern.
+     *
+     * - **String**: treated as a substring match (e.g. `"Media"` removes all keys containing `"Media"`).
+     * - **RegExp**: tested against each key directly.
+     *
+     * @param pattern — A string (substring match) or RegExp.
+     * @returns Number of entries removed.
+     */
+    invalidate(pattern: string | RegExp): Promise<number>;
+}
+
 /**
  * Lightweight AniList GraphQL client with built-in caching and rate limiting.
  *
@@ -945,6 +1129,7 @@ declare class AniListClient {
     private readonly cacheAdapter;
     private readonly rateLimiter;
     private readonly hooks;
+    private readonly logger?;
     private readonly signal?;
     private readonly inFlight;
     private _rateLimitInfo?;
@@ -1000,6 +1185,13 @@ declare class AniListClient {
      * @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. */
@@ -1030,17 +1222,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, 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 } });
      * ```
      */
-    getUserFavorites(idOrName: number | string): Promise<UserFavorites>;
-    /** Fetch a studio by its AniList ID. */
-    getStudio(id: number): Promise<Studio>;
+    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. */
@@ -1076,6 +1280,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;
 }
 
 /**
@@ -1089,109 +1307,6 @@ declare class AniListError extends Error {
     constructor(message: string, status: number, errors?: unknown[]);
 }
 
-declare class MemoryCache implements CacheAdapter {
-    private readonly ttl;
-    private readonly maxSize;
-    private readonly enabled;
-    private readonly store;
-    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. */
-    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(): void;
-    /** Number of entries currently stored. */
-    get size(): number | Promise<number>;
-    /** Return all cache keys. */
-    keys(): string[];
-    /**
-     * Remove all entries whose key matches the given pattern.
-     *
-     * - **String**: treated as a substring match (e.g. `"Media"` removes all keys containing `"Media"`).
-     * - **RegExp**: tested against each key directly.
-     *
-     * @param pattern — A string (substring match) 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>;
-    /**
-     * Get the actual number of keys with this prefix in Redis.
-     */
-    get size(): Promise<number>;
-    /** @internal */
-    private getSize;
-    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>;
-}
-
 /**
  * Rate limiter with automatic retry for AniList API.
  *
@@ -1239,4 +1354,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 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, StudioSort, 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 };