ani-client 1.1.0 → 1.3.0

package/dist/index.mjs

@@ -31,6 +31,20 @@ var MEDIA_FIELDS = `
   trending
   tags { id name description category rank isMediaSpoiler }
   studios { nodes { id name isAnimationStudio siteUrl } }
+  relations {
+    edges {
+      relationType(version: 2)
+      node {
+        id
+        title { romaji english native userPreferred }
+        type
+        format
+        status
+        coverImage { large medium }
+        siteUrl
+      }
+    }
+  }
   isAdult
   siteUrl
 `;
@@ -213,16 +227,133 @@ query ($type: MediaType, $sort: [MediaSort], $page: Int, $perPage: Int) {
     }
   }
 }`;
-
-// src/errors/index.ts
-var AniListError = class extends Error {
-  constructor(message, status, errors = []) {
-    super(message);
-    this.name = "AniListError";
-    this.status = status;
-    this.errors = errors;
+var QUERY_MEDIA_BY_SEASON = `
+query ($season: MediaSeason!, $seasonYear: Int!, $type: MediaType, $sort: [MediaSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    media(season: $season, seasonYear: $seasonYear, type: $type, sort: $sort) {
+      ${MEDIA_FIELDS}
+    }
   }
-};
+}`;
+var MEDIA_LIST_FIELDS = `
+  id
+  mediaId
+  status
+  score(format: POINT_100)
+  progress
+  progressVolumes
+  repeat
+  priority
+  private
+  notes
+  startedAt { year month day }
+  completedAt { year month day }
+  updatedAt
+  createdAt
+  media {
+    ${MEDIA_FIELDS}
+  }
+`;
+var QUERY_RECOMMENDATIONS = `
+query ($mediaId: Int!, $page: Int, $perPage: Int, $sort: [RecommendationSort]) {
+  Media(id: $mediaId) {
+    recommendations(page: $page, perPage: $perPage, sort: $sort) {
+      pageInfo { total perPage currentPage lastPage hasNextPage }
+      nodes {
+        id
+        rating
+        userRating
+        mediaRecommendation {
+          id
+          idMal
+          title { romaji english native userPreferred }
+          type
+          format
+          status
+          coverImage { extraLarge large medium color }
+          bannerImage
+          genres
+          averageScore
+          meanScore
+          popularity
+          favourites
+          siteUrl
+        }
+        user {
+          id
+          name
+          avatar { large medium }
+        }
+      }
+    }
+  }
+}`;
+var QUERY_USER_MEDIA_LIST = `
+query ($userId: Int, $userName: String, $type: MediaType!, $status: MediaListStatus, $sort: [MediaListSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    mediaList(userId: $userId, userName: $userName, type: $type, status: $status, sort: $sort) {
+      ${MEDIA_LIST_FIELDS}
+    }
+  }
+}`;
+var STUDIO_FIELDS = `
+  id
+  name
+  isAnimationStudio
+  siteUrl
+  favourites
+  media(page: 1, perPage: 25, sort: POPULARITY_DESC) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    nodes {
+      id
+      title { romaji english native userPreferred }
+      type
+      format
+      coverImage { large medium }
+      siteUrl
+    }
+  }
+`;
+var QUERY_STUDIO_BY_ID = `
+query ($id: Int!) {
+  Studio(id: $id) {
+    ${STUDIO_FIELDS}
+  }
+}`;
+var QUERY_STUDIO_SEARCH = `
+query ($search: String, $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    studios(search: $search) {
+      ${STUDIO_FIELDS}
+    }
+  }
+}`;
+var QUERY_GENRES = `
+query {
+  GenreCollection
+}`;
+var QUERY_TAGS = `
+query {
+  MediaTagCollection {
+    id
+    name
+    description
+    category
+    isAdult
+  }
+}`;
+function buildBatchQuery(ids, typeName, fields, prefix) {
+  const aliases = ids.map((id, i) => `${prefix}${i}: ${typeName}(id: ${id}) { ${fields} }`).join("\n  ");
+  return `query {
+  ${aliases}
+}`;
+}
+var buildBatchMediaQuery = (ids) => buildBatchQuery(ids, "Media", MEDIA_FIELDS, "m");
+var buildBatchCharacterQuery = (ids) => buildBatchQuery(ids, "Character", CHARACTER_FIELDS, "c");
+var buildBatchStaffQuery = (ids) => buildBatchQuery(ids, "Staff", STAFF_FIELDS, "s");
 
 // src/cache/index.ts
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
@@ -235,7 +366,7 @@ var MemoryCache = class {
   }
   /** Build a deterministic cache key from a query + variables pair. */
   static key(query, variables) {
-    return query.trim() + "|" + JSON.stringify(variables, Object.keys(variables).sort());
+    return `${query.trim()}|${JSON.stringify(variables, Object.keys(variables).sort())}`;
   }
   /** Retrieve a cached value, or `undefined` if missing / expired. */
   get(key) {
@@ -246,11 +377,14 @@ var MemoryCache = class {
       this.store.delete(key);
       return void 0;
     }
+    this.store.delete(key);
+    this.store.set(key, entry);
     return entry.data;
   }
   /** Store a value in the cache. */
   set(key, data) {
     if (!this.enabled) return;
+    this.store.delete(key);
     if (this.maxSize > 0 && this.store.size >= this.maxSize) {
       const firstKey = this.store.keys().next().value;
       if (firstKey !== void 0) this.store.delete(firstKey);
@@ -269,6 +403,37 @@ var MemoryCache = class {
   get size() {
     return this.store.size;
   }
+  /** Return an iterator over all cache keys. */
+  keys() {
+    return this.store.keys();
+  }
+  /**
+   * 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) {
+    const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
+    let count = 0;
+    for (const key of [...this.store.keys()]) {
+      if (regex.test(key)) {
+        this.store.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+};
+
+// src/errors/index.ts
+var AniListError = class extends Error {
+  constructor(message, status, errors = []) {
+    super(message);
+    this.name = "AniListError";
+    this.status = status;
+    this.errors = errors;
+  }
 };
 
 // src/rate-limiter/index.ts
@@ -281,6 +446,8 @@ var RateLimiter = class {
     this.maxRetries = options.maxRetries ?? 3;
     this.retryDelayMs = options.retryDelayMs ?? 2e3;
     this.enabled = options.enabled ?? true;
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.retryOnNetworkError = options.retryOnNetworkError ?? true;
   }
   /**
    * Wait until it's safe to make a request (respects rate limit window).
@@ -298,66 +465,141 @@ var RateLimiter = class {
     this.timestamps.push(Date.now());
   }
   /**
-   * Execute a fetch with automatic retry on 429 responses.
+   * Execute a fetch with automatic retry on 429 responses and network errors.
    */
-  async fetchWithRetry(url, init) {
+  async fetchWithRetry(url, init, hooks) {
     await this.acquire();
     let lastResponse;
+    let lastError;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      const res = await fetch(url, init);
-      if (res.status !== 429) {
-        return res;
+      try {
+        const res = await this.fetchWithTimeout(url, init);
+        if (res.status !== 429) return res;
+        lastResponse = res;
+        if (attempt === this.maxRetries) break;
+        const retryAfter = res.headers.get("Retry-After");
+        const delayMs = retryAfter ? Number.parseInt(retryAfter, 10) * 1e3 : this.retryDelayMs * (attempt + 1);
+        hooks?.onRateLimit?.(delayMs);
+        hooks?.onRetry?.(attempt + 1, "HTTP 429", delayMs);
+        await this.sleep(delayMs);
+        await this.acquire();
+      } catch (err) {
+        lastError = err;
+        if (this.retryOnNetworkError && isNetworkError(err) && attempt < this.maxRetries) {
+          const delayMs = this.retryDelayMs * (attempt + 1);
+          hooks?.onRetry?.(attempt + 1, `Network error: ${err.message}`, delayMs);
+          await this.sleep(delayMs);
+          await this.acquire();
+          continue;
+        }
+        throw err;
       }
-      lastResponse = res;
-      if (attempt === this.maxRetries) break;
-      const retryAfter = res.headers.get("Retry-After");
-      const delayMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : this.retryDelayMs * (attempt + 1);
-      await this.sleep(delayMs);
-      await this.acquire();
     }
-    return lastResponse;
+    if (lastResponse) return lastResponse;
+    throw lastError;
+  }
+  /** @internal */
+  async fetchWithTimeout(url, init) {
+    if (this.timeoutMs <= 0) return fetch(url, init);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
   }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 };
+var RETRYABLE_NETWORK_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET"
+]);
+function isNetworkError(err) {
+  if (err instanceof TypeError && err.message === "fetch failed") return true;
+  const code = err?.code;
+  if (code && RETRYABLE_NETWORK_CODES.has(code)) return true;
+  const cause = err?.cause?.code;
+  if (cause && RETRYABLE_NETWORK_CODES.has(cause)) return true;
+  return false;
+}
 
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
 var AniListClient = class {
   constructor(options = {}) {
+    this.inFlight = /* @__PURE__ */ new Map();
     this.apiUrl = options.apiUrl ?? DEFAULT_API_URL;
     this.headers = {
       "Content-Type": "application/json",
       Accept: "application/json"
     };
     if (options.token) {
-      this.headers["Authorization"] = `Bearer ${options.token}`;
+      this.headers.Authorization = `Bearer ${options.token}`;
     }
-    this.cache = new MemoryCache(options.cache);
+    this.cacheAdapter = options.cacheAdapter ?? new MemoryCache(options.cache);
     this.rateLimiter = new RateLimiter(options.rateLimit);
+    this.hooks = options.hooks ?? {};
   }
   /**
    * @internal
    */
   async request(query, variables = {}) {
     const cacheKey = MemoryCache.key(query, variables);
-    const cached = this.cache.get(cacheKey);
-    if (cached !== void 0) return cached;
-    const res = await this.rateLimiter.fetchWithRetry(this.apiUrl, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({ query, variables })
-    });
+    const cached = await this.cacheAdapter.get(cacheKey);
+    if (cached !== void 0) {
+      this.hooks.onCacheHit?.(cacheKey);
+      this.hooks.onResponse?.(query, 0, true);
+      return cached;
+    }
+    const existing = this.inFlight.get(cacheKey);
+    if (existing) return existing;
+    const promise = this.executeRequest(query, variables, cacheKey);
+    this.inFlight.set(cacheKey, promise);
+    try {
+      return await promise;
+    } finally {
+      this.inFlight.delete(cacheKey);
+    }
+  }
+  /** @internal */
+  async executeRequest(query, variables, cacheKey) {
+    const start = Date.now();
+    this.hooks.onRequest?.(query, variables);
+    const res = await this.rateLimiter.fetchWithRetry(
+      this.apiUrl,
+      {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify({ query, variables })
+      },
+      { onRetry: this.hooks.onRetry, onRateLimit: this.hooks.onRateLimit }
+    );
     const json = await res.json();
     if (!res.ok || json.errors) {
       const message = json.errors?.[0]?.message ?? `AniList API error (HTTP ${res.status})`;
       throw new AniListError(message, res.status, json.errors ?? []);
     }
     const data = json.data;
-    this.cache.set(cacheKey, data);
+    await this.cacheAdapter.set(cacheKey, data);
+    this.hooks.onResponse?.(query, Date.now() - start, false);
     return data;
   }
+  /**
+   * @internal
+   * Shorthand for paginated queries that follow the `Page { pageInfo, <field>[] }` pattern.
+   */
+  async pagedRequest(query, variables, field) {
+    const data = await this.request(query, variables);
+    return { pageInfo: data.Page.pageInfo, results: data.Page[field] };
+  }
   /**
    * Fetch a single media entry by its AniList ID.
    *
@@ -384,22 +626,8 @@ var AniListClient = class {
    * ```
    */
   async searchMedia(options = {}) {
-    const variables = {
-      search: options.query,
-      type: options.type,
-      format: options.format,
-      status: options.status,
-      season: options.season,
-      seasonYear: options.seasonYear,
-      genre: options.genre,
-      tag: options.tag,
-      isAdult: options.isAdult,
-      sort: options.sort,
-      page: options.page ?? 1,
-      perPage: options.perPage ?? 20
-    };
-    const data = await this.request(QUERY_MEDIA_SEARCH, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.media };
+    const { query: search, page = 1, perPage = 20, ...filters } = options;
+    return this.pagedRequest(QUERY_MEDIA_SEARCH, { search, ...filters, page, perPage }, "media");
   }
   /**
    * Get currently trending anime or manga.
@@ -409,8 +637,7 @@ var AniListClient = class {
    * @param perPage - Results per page (default 20, max 50)
    */
   async getTrending(type = "ANIME", page = 1, perPage = 20) {
-    const data = await this.request(QUERY_TRENDING, { type, page, perPage });
-    return { pageInfo: data.Page.pageInfo, results: data.Page.media };
+    return this.pagedRequest(QUERY_TRENDING, { type, page, perPage }, "media");
   }
   /**
    * Fetch a character by AniList ID.
@@ -423,14 +650,8 @@ var AniListClient = class {
    * Search for characters by name.
    */
   async searchCharacters(options = {}) {
-    const variables = {
-      search: options.query,
-      sort: options.sort,
-      page: options.page ?? 1,
-      perPage: options.perPage ?? 20
-    };
-    const data = await this.request(QUERY_CHARACTER_SEARCH, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.characters };
+    const { query: search, page = 1, perPage = 20, ...rest } = options;
+    return this.pagedRequest(QUERY_CHARACTER_SEARCH, { search, ...rest, page, perPage }, "characters");
   }
   /**
    * Fetch a staff member by AniList ID.
@@ -443,13 +664,8 @@ var AniListClient = class {
    * Search for staff (voice actors, directors, etc.).
    */
   async searchStaff(options = {}) {
-    const variables = {
-      search: options.query,
-      page: options.page ?? 1,
-      perPage: options.perPage ?? 20
-    };
-    const data = await this.request(QUERY_STAFF_SEARCH, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.staff };
+    const { query: search, page = 1, perPage = 20 } = options;
+    return this.pagedRequest(QUERY_STAFF_SEARCH, { search, page, perPage }, "staff");
   }
   /**
    * Fetch a user by AniList ID.
@@ -500,8 +716,7 @@ var AniListClient = class {
       page: options.page ?? 1,
       perPage: options.perPage ?? 20
     };
-    const data = await this.request(QUERY_AIRING_SCHEDULE, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.airingSchedules };
+    return this.pagedRequest(QUERY_AIRING_SCHEDULE, variables, "airingSchedules");
   }
   /**
    * Get manga that are currently releasing, sorted by most recently updated.
@@ -518,12 +733,14 @@ var AniListClient = class {
    * ```
    */
   async getAiredChapters(options = {}) {
-    const variables = {
-      page: options.page ?? 1,
-      perPage: options.perPage ?? 20
-    };
-    const data = await this.request(QUERY_RECENT_CHAPTERS, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.media };
+    return this.pagedRequest(
+      QUERY_RECENT_CHAPTERS,
+      {
+        page: options.page ?? 1,
+        perPage: options.perPage ?? 20
+      },
+      "media"
+    );
   }
   /**
    * Get upcoming (not yet released) anime and/or manga, sorted by popularity.
@@ -540,26 +757,361 @@ var AniListClient = class {
    * ```
    */
   async getPlanning(options = {}) {
+    return this.pagedRequest(
+      QUERY_PLANNING,
+      {
+        type: options.type,
+        sort: options.sort ?? ["POPULARITY_DESC"],
+        page: options.page ?? 1,
+        perPage: options.perPage ?? 20
+      },
+      "media"
+    );
+  }
+  /**
+   * Get recommendations for a specific media.
+   *
+   * Returns other anime/manga that users have recommended based on the given media.
+   *
+   * @param mediaId - The AniList media ID
+   * @param options - Optional sort / pagination parameters
+   * @returns Paginated list of recommendations
+   *
+   * @example
+   * ```ts
+   * // Get recommendations for Cowboy Bebop
+   * const recs = await client.getRecommendations(1);
+   * recs.results.forEach((r) =>
+   *   console.log(`${r.mediaRecommendation.title.romaji} (rating: ${r.rating})`)
+   * );
+   * ```
+   */
+  async getRecommendations(mediaId, options = {}) {
     const variables = {
-      type: options.type,
-      sort: options.sort ?? ["POPULARITY_DESC"],
+      mediaId,
+      sort: options.sort ?? ["RATING_DESC"],
       page: options.page ?? 1,
       perPage: options.perPage ?? 20
     };
-    const data = await this.request(QUERY_PLANNING, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.media };
+    const data = await this.request(QUERY_RECOMMENDATIONS, variables);
+    return {
+      pageInfo: data.Media.recommendations.pageInfo,
+      results: data.Media.recommendations.nodes
+    };
   }
+  /**
+   * Get anime (or manga) for a specific season and year.
+   *
+   * @param options - Season, year and optional filter / pagination parameters
+   * @returns Paginated list of media for the given season
+   *
+   * @example
+   * ```ts
+   * import { MediaSeason } from "ani-client";
+   *
+   * const winter2026 = await client.getMediaBySeason({
+   *   season: MediaSeason.WINTER,
+   *   seasonYear: 2026,
+   *   perPage: 10,
+   * });
+   * ```
+   */
+  async getMediaBySeason(options) {
+    return this.pagedRequest(
+      QUERY_MEDIA_BY_SEASON,
+      {
+        season: options.season,
+        seasonYear: options.seasonYear,
+        type: options.type ?? "ANIME",
+        sort: options.sort ?? ["POPULARITY_DESC"],
+        page: options.page ?? 1,
+        perPage: options.perPage ?? 20
+      },
+      "media"
+    );
+  }
+  /**
+   * Get a user's anime or manga list.
+   *
+   * Provide either `userId` or `userName` to identify the user.
+   * Requires `type` (ANIME or MANGA). Optionally filter by list status.
+   *
+   * @param options - User identifier, media type, and optional filters
+   * @returns Paginated list of media list entries
+   *
+   * @example
+   * ```ts
+   * import { MediaType, MediaListStatus } from "ani-client";
+   *
+   * // Get a user's completed anime list
+   * const list = await client.getUserMediaList({
+   *   userName: "AniList",
+   *   type: MediaType.ANIME,
+   *   status: MediaListStatus.COMPLETED,
+   * });
+   * list.results.forEach((entry) =>
+   *   console.log(`${entry.media.title.romaji} — ${entry.score}/100`)
+   * );
+   * ```
+   */
+  async getUserMediaList(options) {
+    if (!options.userId && !options.userName) {
+      throw new Error("Either userId or userName must be provided");
+    }
+    return this.pagedRequest(
+      QUERY_USER_MEDIA_LIST,
+      {
+        userId: options.userId,
+        userName: options.userName,
+        type: options.type,
+        status: options.status,
+        sort: options.sort,
+        page: options.page ?? 1,
+        perPage: options.perPage ?? 20
+      },
+      "mediaList"
+    );
+  }
+  /**
+   * Fetch a studio by its AniList ID.
+   *
+   * Returns studio details along with its most popular productions.
+   *
+   * @param id - The AniList studio ID
+   */
+  async getStudio(id) {
+    const data = await this.request(QUERY_STUDIO_BY_ID, { id });
+    return data.Studio;
+  }
+  /**
+   * Search for studios by name.
+   *
+   * @param options - Search / pagination parameters
+   * @returns Paginated list of studios
+   *
+   * @example
+   * ```ts
+   * const studios = await client.searchStudios({ query: "MAPPA" });
+   * ```
+   */
+  async searchStudios(options = {}) {
+    return this.pagedRequest(
+      QUERY_STUDIO_SEARCH,
+      {
+        search: options.query,
+        page: options.page ?? 1,
+        perPage: options.perPage ?? 20
+      },
+      "studios"
+    );
+  }
+  /**
+   * Get all available genres on AniList.
+   *
+   * @returns Array of genre strings (e.g. "Action", "Adventure", ...)
+   */
+  async getGenres() {
+    const data = await this.request(QUERY_GENRES);
+    return data.GenreCollection;
+  }
+  /**
+   * Get all available media tags on AniList.
+   *
+   * @returns Array of tag objects with id, name, description, category, isAdult
+   */
+  async getTags() {
+    const data = await this.request(QUERY_TAGS);
+    return data.MediaTagCollection;
+  }
+  /**
+   * Auto-paginating async iterator.
+   *
+   * Wraps any paginated method and yields individual items across all pages.
+   * Stops when `hasNextPage` is `false` or `maxPages` is reached.
+   *
+   * @param fetchPage - A function that takes a page number and returns a `PagedResult<T>`
+   * @param maxPages - Maximum number of pages to fetch (default: Infinity)
+   * @returns An async iterable iterator of individual items
+   *
+   * @example
+   * ```ts
+   * // Iterate over all search results
+   * for await (const anime of client.paginate((page) =>
+   *   client.searchMedia({ query: "Naruto", page, perPage: 10 })
+   * )) {
+   *   console.log(anime.title.romaji);
+   * }
+   *
+   * // Limit to 3 pages
+   * for await (const anime of client.paginate(
+   *   (page) => client.getTrending(MediaType.ANIME, page, 20),
+   *   3,
+   * )) {
+   *   console.log(anime.title.romaji);
+   * }
+   * ```
+   */
+  async *paginate(fetchPage, maxPages = Number.POSITIVE_INFINITY) {
+    let page = 1;
+    let hasNext = true;
+    while (hasNext && page <= maxPages) {
+      const result = await fetchPage(page);
+      for (const item of result.results) {
+        yield item;
+      }
+      hasNext = result.pageInfo.hasNextPage === true;
+      page++;
+    }
+  }
+  // ── Batch queries ──
+  /**
+   * 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)
+   */
+  async getMediaBatch(ids) {
+    if (ids.length === 0) return [];
+    if (ids.length === 1) return [await this.getMedia(ids[0])];
+    return this.executeBatch(ids, buildBatchMediaQuery, "m");
+  }
+  /**
+   * 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)
+   */
+  async getCharacterBatch(ids) {
+    if (ids.length === 0) return [];
+    if (ids.length === 1) return [await this.getCharacter(ids[0])];
+    return this.executeBatch(ids, buildBatchCharacterQuery, "c");
+  }
+  /**
+   * 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)
+   */
+  async getStaffBatch(ids) {
+    if (ids.length === 0) return [];
+    if (ids.length === 1) return [await this.getStaff(ids[0])];
+    return this.executeBatch(ids, buildBatchStaffQuery, "s");
+  }
+  /** @internal */
+  async executeBatch(ids, buildQuery, prefix) {
+    const chunks = this.chunk(ids, 50);
+    const results = [];
+    for (const chunk of chunks) {
+      const query = buildQuery(chunk);
+      const data = await this.request(query);
+      results.push(...chunk.map((_, i) => data[`${prefix}${i}`]));
+    }
+    return results;
+  }
+  /** @internal */
+  chunk(arr, size) {
+    const chunks = [];
+    for (let i = 0; i < arr.length; i += size) {
+      chunks.push(arr.slice(i, i + size));
+    }
+    return chunks;
+  }
+  // ── Cache management ──
   /**
    * Clear the entire response cache.
    */
-  clearCache() {
-    this.cache.clear();
+  async clearCache() {
+    await this.cacheAdapter.clear();
   }
   /**
-   * 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() {
-    return this.cache.size;
+    return this.cacheAdapter.size;
+  }
+  /**
+   * Remove cache entries whose key matches the given pattern.
+   *
+   * @param pattern — A string (converted to RegExp) or RegExp
+   * @returns Number of entries removed
+   */
+  async invalidateCache(pattern) {
+    if (this.cacheAdapter.invalidate) {
+      return this.cacheAdapter.invalidate(pattern);
+    }
+    const allKeys = await this.cacheAdapter.keys();
+    const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
+    let count = 0;
+    for (const key of allKeys) {
+      if (regex.test(key)) {
+        await this.cacheAdapter.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+};
+
+// src/cache/redis.ts
+var RedisCache = class {
+  constructor(options) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "ani:";
+    this.ttl = options.ttl ?? 86400;
+  }
+  prefixedKey(key) {
+    return `${this.prefix}${key}`;
+  }
+  async get(key) {
+    const raw = await this.client.get(this.prefixedKey(key));
+    if (raw === null) return void 0;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+  async set(key, data) {
+    await this.client.set(this.prefixedKey(key), JSON.stringify(data), "EX", this.ttl);
+  }
+  async delete(key) {
+    const count = await this.client.del(this.prefixedKey(key));
+    return count > 0;
+  }
+  async clear() {
+    const keys = await this.client.keys(`${this.prefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+  /**
+   * Returns -1 because Redis keys can expire silently via TTL.
+   * Use `getSize()` for an accurate count.
+   */
+  get size() {
+    return -1;
+  }
+  /** Get the actual number of keys with this prefix in Redis. */
+  async getSize() {
+    const keys = await this.client.keys(`${this.prefix}*`);
+    return keys.length;
+  }
+  async keys() {
+    const raw = await this.client.keys(`${this.prefix}*`);
+    return raw.map((k) => k.slice(this.prefix.length));
+  }
+  /**
+   * Remove all entries whose key matches the given glob pattern.
+   *
+   * @param pattern — A glob pattern (e.g. `"*Media*"`)
+   * @returns Number of entries removed.
+   */
+  async invalidate(pattern) {
+    const keys = await this.client.keys(`${this.prefix}${pattern}`);
+    if (keys.length === 0) return 0;
+    return this.client.del(...keys);
   }
 };
 
@@ -635,7 +1187,72 @@ var CharacterSort = /* @__PURE__ */ ((CharacterSort2) => {
   CharacterSort2["FAVOURITES"] = "FAVOURITES";
   return CharacterSort2;
 })(CharacterSort || {});
+var MediaRelationType = /* @__PURE__ */ ((MediaRelationType2) => {
+  MediaRelationType2["ADAPTATION"] = "ADAPTATION";
+  MediaRelationType2["PREQUEL"] = "PREQUEL";
+  MediaRelationType2["SEQUEL"] = "SEQUEL";
+  MediaRelationType2["PARENT"] = "PARENT";
+  MediaRelationType2["SIDE_STORY"] = "SIDE_STORY";
+  MediaRelationType2["CHARACTER"] = "CHARACTER";
+  MediaRelationType2["SUMMARY"] = "SUMMARY";
+  MediaRelationType2["ALTERNATIVE"] = "ALTERNATIVE";
+  MediaRelationType2["SPIN_OFF"] = "SPIN_OFF";
+  MediaRelationType2["OTHER"] = "OTHER";
+  MediaRelationType2["SOURCE"] = "SOURCE";
+  MediaRelationType2["COMPILATION"] = "COMPILATION";
+  MediaRelationType2["CONTAINS"] = "CONTAINS";
+  return MediaRelationType2;
+})(MediaRelationType || {});
+var RecommendationSort = /* @__PURE__ */ ((RecommendationSort2) => {
+  RecommendationSort2["ID"] = "ID";
+  RecommendationSort2["ID_DESC"] = "ID_DESC";
+  RecommendationSort2["RATING"] = "RATING";
+  RecommendationSort2["RATING_DESC"] = "RATING_DESC";
+  return RecommendationSort2;
+})(RecommendationSort || {});
+var MediaListStatus = /* @__PURE__ */ ((MediaListStatus2) => {
+  MediaListStatus2["CURRENT"] = "CURRENT";
+  MediaListStatus2["PLANNING"] = "PLANNING";
+  MediaListStatus2["COMPLETED"] = "COMPLETED";
+  MediaListStatus2["DROPPED"] = "DROPPED";
+  MediaListStatus2["PAUSED"] = "PAUSED";
+  MediaListStatus2["REPEATING"] = "REPEATING";
+  return MediaListStatus2;
+})(MediaListStatus || {});
+var MediaListSort = /* @__PURE__ */ ((MediaListSort2) => {
+  MediaListSort2["MEDIA_ID"] = "MEDIA_ID";
+  MediaListSort2["MEDIA_ID_DESC"] = "MEDIA_ID_DESC";
+  MediaListSort2["SCORE"] = "SCORE";
+  MediaListSort2["SCORE_DESC"] = "SCORE_DESC";
+  MediaListSort2["STATUS"] = "STATUS";
+  MediaListSort2["STATUS_DESC"] = "STATUS_DESC";
+  MediaListSort2["PROGRESS"] = "PROGRESS";
+  MediaListSort2["PROGRESS_DESC"] = "PROGRESS_DESC";
+  MediaListSort2["PROGRESS_VOLUMES"] = "PROGRESS_VOLUMES";
+  MediaListSort2["PROGRESS_VOLUMES_DESC"] = "PROGRESS_VOLUMES_DESC";
+  MediaListSort2["REPEAT"] = "REPEAT";
+  MediaListSort2["REPEAT_DESC"] = "REPEAT_DESC";
+  MediaListSort2["PRIORITY"] = "PRIORITY";
+  MediaListSort2["PRIORITY_DESC"] = "PRIORITY_DESC";
+  MediaListSort2["STARTED_ON"] = "STARTED_ON";
+  MediaListSort2["STARTED_ON_DESC"] = "STARTED_ON_DESC";
+  MediaListSort2["FINISHED_ON"] = "FINISHED_ON";
+  MediaListSort2["FINISHED_ON_DESC"] = "FINISHED_ON_DESC";
+  MediaListSort2["ADDED_TIME"] = "ADDED_TIME";
+  MediaListSort2["ADDED_TIME_DESC"] = "ADDED_TIME_DESC";
+  MediaListSort2["UPDATED_TIME"] = "UPDATED_TIME";
+  MediaListSort2["UPDATED_TIME_DESC"] = "UPDATED_TIME_DESC";
+  MediaListSort2["MEDIA_TITLE_ROMAJI"] = "MEDIA_TITLE_ROMAJI";
+  MediaListSort2["MEDIA_TITLE_ROMAJI_DESC"] = "MEDIA_TITLE_ROMAJI_DESC";
+  MediaListSort2["MEDIA_TITLE_ENGLISH"] = "MEDIA_TITLE_ENGLISH";
+  MediaListSort2["MEDIA_TITLE_ENGLISH_DESC"] = "MEDIA_TITLE_ENGLISH_DESC";
+  MediaListSort2["MEDIA_TITLE_NATIVE"] = "MEDIA_TITLE_NATIVE";
+  MediaListSort2["MEDIA_TITLE_NATIVE_DESC"] = "MEDIA_TITLE_NATIVE_DESC";
+  MediaListSort2["MEDIA_POPULARITY"] = "MEDIA_POPULARITY";
+  MediaListSort2["MEDIA_POPULARITY_DESC"] = "MEDIA_POPULARITY_DESC";
+  return MediaListSort2;
+})(MediaListSort || {});
 
-export { AiringSort, AniListClient, AniListError, CharacterSort, MediaFormat, MediaSeason, MediaSort, MediaStatus, MediaType, MemoryCache, RateLimiter };
+export { AiringSort, AniListClient, AniListError, CharacterSort, MediaFormat, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaStatus, MediaType, MemoryCache, RateLimiter, RecommendationSort, RedisCache };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map