ani-client 1.7.0 → 1.8.1

package/dist/index.mjs

@@ -125,28 +125,52 @@ function sortObjectKeys(obj) {
 // src/cache/index.ts
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
 var MemoryCache = class {
+  ttl;
+  maxSize;
+  enabled;
+  swrMs;
+  store = /* @__PURE__ */ new Map();
+  _hits = 0;
+  _misses = 0;
+  _stales = 0;
   constructor(options = {}) {
-    this.store = /* @__PURE__ */ new Map();
     this.ttl = options.ttl ?? ONE_DAY_MS;
     this.maxSize = options.maxSize ?? 500;
     this.enabled = options.enabled ?? true;
+    this.swrMs = options.staleWhileRevalidateMs ?? 0;
   }
   /** Build a deterministic cache key from a query + variables pair. */
   static key(query, variables) {
     const normalized = normalizeQuery(query);
     return `${normalized}|${JSON.stringify(sortObjectKeys(variables))}`;
   }
-  /** 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(key) {
     if (!this.enabled) return void 0;
     const entry = this.store.get(key);
-    if (!entry) return void 0;
-    if (Date.now() > entry.expiresAt) {
+    if (!entry) {
+      this._misses++;
+      return void 0;
+    }
+    const now = Date.now();
+    if (now > entry.expiresAt) {
+      if (this.swrMs > 0 && now <= entry.expiresAt + this.swrMs) {
+        this.store.delete(key);
+        this.store.set(key, entry);
+        this._stales++;
+        return entry.data;
+      }
       this.store.delete(key);
+      this._misses++;
       return void 0;
     }
     this.store.delete(key);
     this.store.set(key, entry);
+    this._hits++;
     return entry.data;
   }
   /** Store a value in the cache. */
@@ -163,9 +187,12 @@ var MemoryCache = class {
   delete(key) {
     return this.store.delete(key);
   }
-  /** Clear the entire cache. */
+  /** Clear the entire cache and reset statistics. */
   clear() {
     this.store.clear();
+    this._hits = 0;
+    this._misses = 0;
+    this._stales = 0;
   }
   /** Number of entries currently stored. */
   get size() {
@@ -175,6 +202,32 @@ var MemoryCache = class {
   keys() {
     return [...this.store.keys()];
   }
+  /**
+   * 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() {
+    const total = this._hits + this._misses + this._stales;
+    return {
+      hits: this._hits,
+      misses: this._misses,
+      stales: this._stales,
+      hitRate: total === 0 ? Number.NaN : this._hits / total
+    };
+  }
+  /** Reset cache statistics without clearing stored data. */
+  resetStats() {
+    this._hits = 0;
+    this._misses = 0;
+    this._stales = 0;
+  }
   /**
    * Remove all entries whose key matches the given pattern.
    *
@@ -195,8 +248,101 @@ var MemoryCache = class {
   }
 };
 
+// src/cache/redis.ts
+var RedisCache = class {
+  client;
+  prefix;
+  ttl;
+  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;
+  }
+  /**
+   * 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
+   */
+  async collectKeys(pattern) {
+    if (this.client.scanIterator) {
+      const keys = [];
+      for await (const key of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {
+        keys.push(key);
+      }
+      return keys;
+    }
+    return this.client.keys(pattern);
+  }
+  async clear() {
+    const keys = await this.collectKeys(`${this.prefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+  /**
+   * Get the actual number of keys with this prefix in Redis.
+   */
+  get size() {
+    return this.getSize();
+  }
+  /** @internal */
+  async getSize() {
+    const keys = await this.collectKeys(`${this.prefix}*`);
+    return keys.length;
+  }
+  async keys() {
+    const raw = await this.collectKeys(`${this.prefix}*`);
+    return raw.map((k) => k.slice(this.prefix.length));
+  }
+  /**
+   * 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.
+   */
+  async invalidate(pattern) {
+    if (typeof pattern === "string") {
+      const keys = await this.collectKeys(`${this.prefix}*${pattern}*`);
+      if (keys.length === 0) return 0;
+      return this.client.del(...keys);
+    }
+    const allKeys = await this.collectKeys(`${this.prefix}*`);
+    const matching = allKeys.filter((k) => pattern.test(k.slice(this.prefix.length)));
+    if (matching.length === 0) return 0;
+    return this.client.del(...matching);
+  }
+};
+
 // src/errors/index.ts
 var AniListError = class _AniListError extends Error {
+  /** HTTP status code returned by the API */
+  status;
+  /** Raw error body from the API response */
+  errors;
   constructor(message, status, errors = []) {
     super(message);
     this.name = "AniListError";
@@ -210,6 +356,32 @@ var AniListError = class _AniListError extends Error {
 };
 
 // src/queries/fragments.ts
+var MEDIA_FIELDS_LIGHT = `
+  id
+  idMal
+  title { romaji english native userPreferred }
+  type
+  format
+  status
+  coverImage { large medium color }
+  bannerImage
+  genres
+  averageScore
+  popularity
+  favourites
+  isAdult
+  siteUrl
+  season
+  seasonYear
+  episodes
+  chapters
+  nextAiringEpisode {
+    id
+    airingAt
+    episode
+    timeUntilAiring
+  }
+`;
 var MEDIA_FIELDS_BASE = `
   id
   idMal
@@ -629,6 +801,12 @@ query ($season: MediaSeason!, $seasonYear: Int!, $type: MediaType, $sort: [Media
     }
   }
 }`;
+var QUERY_MEDIA_BY_MAL_ID = `
+query ($idMal: Int!, $type: MediaType) {
+  Media(idMal: $idMal, type: $type) {
+    ${MEDIA_FIELDS}
+  }
+}`;
 var QUERY_RECOMMENDATIONS = `
 query ($mediaId: Int!, $page: Int, $perPage: Int, $sort: [RecommendationSort]) {
   Media(id: $mediaId) {
@@ -664,143 +842,6 @@ query ($mediaId: Int!, $page: Int, $perPage: Int, $sort: [RecommendationSort]) {
   }
 }`;
 
-// src/queries/character.ts
-var QUERY_CHARACTER_BY_ID = `
-query ($id: Int!) {
-  Character(id: $id) {
-    ${CHARACTER_FIELDS}
-  }
-}`;
-var QUERY_CHARACTER_BY_ID_WITH_VA = `
-query ($id: Int!) {
-  Character(id: $id) {
-    ${CHARACTER_FIELDS_WITH_VA}
-  }
-}`;
-var QUERY_CHARACTER_SEARCH = `
-query ($search: String, $sort: [CharacterSort], $page: Int, $perPage: Int) {
-  Page(page: $page, perPage: $perPage) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    characters(search: $search, sort: $sort) {
-      ${CHARACTER_FIELDS}
-    }
-  }
-}`;
-var QUERY_CHARACTER_SEARCH_WITH_VA = `
-query ($search: String, $sort: [CharacterSort], $page: Int, $perPage: Int) {
-  Page(page: $page, perPage: $perPage) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    characters(search: $search, sort: $sort) {
-      ${CHARACTER_FIELDS_WITH_VA}
-    }
-  }
-}`;
-
-// src/queries/staff.ts
-var QUERY_STAFF_BY_ID = `
-query ($id: Int!) {
-  Staff(id: $id) {
-    ${STAFF_FIELDS}
-  }
-}`;
-var QUERY_STAFF_BY_ID_WITH_MEDIA = `
-query ($id: Int!, $perPage: Int) {
-  Staff(id: $id) {
-    ${STAFF_FIELDS}
-    ${STAFF_MEDIA_FIELDS}
-  }
-}`;
-var QUERY_STAFF_SEARCH = `
-query ($search: String, $sort: [StaffSort], $page: Int, $perPage: Int) {
-  Page(page: $page, perPage: $perPage) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    staff(search: $search, sort: $sort) {
-      ${STAFF_FIELDS}
-    }
-  }
-}`;
-
-// src/queries/user.ts
-var QUERY_USER_BY_ID = `
-query ($id: Int!) {
-  User(id: $id) {
-    ${USER_FIELDS}
-  }
-}`;
-var QUERY_USER_BY_NAME = `
-query ($name: String!) {
-  User(name: $name) {
-    ${USER_FIELDS}
-  }
-}`;
-var QUERY_USER_SEARCH = `
-query ($search: String, $sort: [UserSort], $page: Int, $perPage: Int) {
-  Page(page: $page, perPage: $perPage) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    users(search: $search, sort: $sort) {
-      ${USER_FIELDS}
-    }
-  }
-}`;
-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 QUERY_USER_FAVORITES_BY_ID = `
-query ($id: Int!) {
-  User(id: $id) {
-    id
-    name
-    ${USER_FAVORITES_FIELDS}
-  }
-}`;
-var QUERY_USER_FAVORITES_BY_NAME = `
-query ($name: String!) {
-  User(name: $name) {
-    id
-    name
-    ${USER_FAVORITES_FIELDS}
-  }
-}`;
-
-// src/queries/studio.ts
-var QUERY_STUDIO_BY_ID = `
-query ($id: Int!) {
-  Studio(id: $id) {
-    ${STUDIO_FIELDS}
-  }
-}`;
-var QUERY_STUDIO_SEARCH = `
-query ($search: String, $sort: [StudioSort], $page: Int, $perPage: Int) {
-  Page(page: $page, perPage: $perPage) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    studios(search: $search, sort: $sort) {
-      ${STUDIO_FIELDS}
-    }
-  }
-}`;
-
-// src/queries/metadata.ts
-var QUERY_GENRES = `
-query {
-  GenreCollection
-}`;
-var QUERY_TAGS = `
-query {
-  MediaTagCollection {
-    id
-    name
-    description
-    category
-    isAdult
-  }
-}`;
-
 // src/queries/builders.ts
 function buildMediaByIdQuery(include) {
   if (!include) return QUERY_MEDIA_BY_ID;
@@ -906,6 +947,115 @@ var buildBatchMediaQuery = (ids) => buildBatchQuery(ids, "Media", MEDIA_FIELDS,
 var buildBatchCharacterQuery = (ids) => buildBatchQuery(ids, "Character", CHARACTER_FIELDS, "c");
 var buildBatchStaffQuery = (ids) => buildBatchQuery(ids, "Staff", STAFF_FIELDS, "s");
 
+// src/queries/character.ts
+var QUERY_CHARACTER_BY_ID = `
+query ($id: Int!) {
+  Character(id: $id) {
+    ${CHARACTER_FIELDS}
+  }
+}`;
+var QUERY_CHARACTER_BY_ID_WITH_VA = `
+query ($id: Int!) {
+  Character(id: $id) {
+    ${CHARACTER_FIELDS_WITH_VA}
+  }
+}`;
+var QUERY_CHARACTER_SEARCH = `
+query ($search: String, $sort: [CharacterSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    characters(search: $search, sort: $sort) {
+      ${CHARACTER_FIELDS}
+    }
+  }
+}`;
+var QUERY_CHARACTER_SEARCH_WITH_VA = `
+query ($search: String, $sort: [CharacterSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    characters(search: $search, sort: $sort) {
+      ${CHARACTER_FIELDS_WITH_VA}
+    }
+  }
+}`;
+
+// src/queries/metadata.ts
+var QUERY_GENRES = `
+query {
+  GenreCollection
+}`;
+var QUERY_TAGS = `
+query {
+  MediaTagCollection {
+    id
+    name
+    description
+    category
+    isAdult
+  }
+}`;
+
+// src/queries/staff.ts
+var QUERY_STAFF_BY_ID = `
+query ($id: Int!) {
+  Staff(id: $id) {
+    ${STAFF_FIELDS}
+  }
+}`;
+var QUERY_STAFF_BY_ID_WITH_MEDIA = `
+query ($id: Int!, $perPage: Int) {
+  Staff(id: $id) {
+    ${STAFF_FIELDS}
+    ${STAFF_MEDIA_FIELDS}
+  }
+}`;
+var QUERY_STAFF_SEARCH = `
+query ($search: String, $sort: [StaffSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    staff(search: $search, sort: $sort) {
+      ${STAFF_FIELDS}
+    }
+  }
+}`;
+
+// src/queries/studio.ts
+var QUERY_STUDIO_BY_ID = `
+query ($id: Int!) {
+  Studio(id: $id) {
+    ${STUDIO_FIELDS}
+  }
+}`;
+function buildStudioByIdQuery(mediaPerPage) {
+  if (mediaPerPage === void 0) return QUERY_STUDIO_BY_ID;
+  const pp = clampPerPage(mediaPerPage);
+  return `
+query ($id: Int!) {
+  Studio(id: $id) {
+    id
+    name
+    isAnimationStudio
+    siteUrl
+    favourites
+    media(page: 1, perPage: ${pp}, sort: POPULARITY_DESC) {
+      pageInfo { total perPage currentPage lastPage hasNextPage }
+      nodes {
+        ${MEDIA_FIELDS_LIGHT}
+      }
+    }
+  }
+}`;
+}
+var QUERY_STUDIO_SEARCH = `
+query ($search: String, $sort: [StudioSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    studios(search: $search, sort: $sort) {
+      ${STUDIO_FIELDS}
+    }
+  }
+}`;
+
 // src/queries/thread.ts
 var QUERY_THREAD_BY_ID = `
 query ($id: Int!) {
@@ -923,13 +1073,128 @@ query ($search: String, $mediaCategoryId: Int, $categoryId: Int, $sort: [ThreadS
   }
 }`;
 
+// src/queries/user.ts
+var QUERY_USER_BY_ID = `
+query ($id: Int!) {
+  User(id: $id) {
+    ${USER_FIELDS}
+  }
+}`;
+var QUERY_USER_BY_NAME = `
+query ($name: String!) {
+  User(name: $name) {
+    ${USER_FIELDS}
+  }
+}`;
+var QUERY_USER_SEARCH = `
+query ($search: String, $sort: [UserSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    users(search: $search, sort: $sort) {
+      ${USER_FIELDS}
+    }
+  }
+}`;
+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 QUERY_USER_FAVORITES_BY_ID = `
+query ($id: Int!) {
+  User(id: $id) {
+    id
+    name
+    ${USER_FAVORITES_FIELDS}
+  }
+}`;
+var QUERY_USER_FAVORITES_BY_NAME = `
+query ($name: String!) {
+  User(name: $name) {
+    id
+    name
+    ${USER_FAVORITES_FIELDS}
+  }
+}`;
+function buildUserFavoritesQuery(idOrName, perPage = 25) {
+  const pp = clampPerPage(perPage);
+  const varDecl = idOrName === "id" ? "$id: Int!" : "$name: String!";
+  const selector = idOrName === "id" ? "id: $id" : "name: $name";
+  return `
+query (${varDecl}) {
+  User(${selector}) {
+    id
+    name
+    favourites {
+      anime(perPage: ${pp}) {
+        nodes {
+          id
+          title { romaji english native userPreferred }
+          coverImage { large medium }
+          type
+          format
+          siteUrl
+        }
+      }
+      manga(perPage: ${pp}) {
+        nodes {
+          id
+          title { romaji english native userPreferred }
+          coverImage { large medium }
+          type
+          format
+          siteUrl
+        }
+      }
+      characters(perPage: ${pp}) {
+        nodes {
+          id
+          name { full native }
+          image { large medium }
+          siteUrl
+        }
+      }
+      staff(perPage: ${pp}) {
+        nodes {
+          id
+          name { full native }
+          image { large medium }
+          siteUrl
+        }
+      }
+      studios(perPage: ${pp}) {
+        nodes {
+          id
+          name
+          siteUrl
+        }
+      }
+    }
+  }
+}`;
+}
+
 // src/rate-limiter/index.ts
 var RateLimiter = class {
+  maxRequests;
+  windowMs;
+  maxRetries;
+  retryDelayMs;
+  enabled;
+  timeoutMs;
+  retryOnNetworkError;
+  retryStrategy;
+  /** @internal — sliding window: circular buffer of timestamps */
+  timestamps;
+  head = 0;
+  count = 0;
+  /** @internal — active sleep timers for cleanup */
+  activeTimers = /* @__PURE__ */ new Set();
   constructor(options = {}) {
-    this.head = 0;
-    this.count = 0;
-    /** @internal — active sleep timers for cleanup */
-    this.activeTimers = /* @__PURE__ */ new Set();
     this.maxRequests = options.maxRequests ?? 85;
     this.windowMs = options.windowMs ?? 6e4;
     this.maxRetries = options.maxRetries ?? 3;
@@ -995,7 +1260,7 @@ var RateLimiter = class {
       }
     }
     if (lastResponse) return lastResponse;
-    throw lastError;
+    throw lastError ?? new Error(`Request failed after ${this.maxRetries} retries`);
   }
   /** @internal — Exponential backoff with jitter, capped at 30s (or custom strategy) */
   exponentialDelay(attempt) {
@@ -1070,6 +1335,68 @@ async function searchCharacters(client, options = {}) {
   return client.pagedRequest(gqlQuery, { search, sort, page, perPage: clampPerPage(perPage) }, "characters");
 }
 
+// src/types/character.ts
+var CharacterSort = /* @__PURE__ */ ((CharacterSort2) => {
+  CharacterSort2["ID"] = "ID";
+  CharacterSort2["ID_DESC"] = "ID_DESC";
+  CharacterSort2["ROLE"] = "ROLE";
+  CharacterSort2["ROLE_DESC"] = "ROLE_DESC";
+  CharacterSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
+  CharacterSort2["FAVOURITES"] = "FAVOURITES";
+  CharacterSort2["FAVOURITES_DESC"] = "FAVOURITES_DESC";
+  return CharacterSort2;
+})(CharacterSort || {});
+var CharacterRole = /* @__PURE__ */ ((CharacterRole2) => {
+  CharacterRole2["MAIN"] = "MAIN";
+  CharacterRole2["SUPPORTING"] = "SUPPORTING";
+  CharacterRole2["BACKGROUND"] = "BACKGROUND";
+  return CharacterRole2;
+})(CharacterRole || {});
+
+// src/types/lists.ts
+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 || {});
+
 // src/types/media.ts
 var MediaType = /* @__PURE__ */ ((MediaType2) => {
   MediaType2["ANIME"] = "ANIME";
@@ -1193,24 +1520,6 @@ var RecommendationSort = /* @__PURE__ */ ((RecommendationSort2) => {
   return RecommendationSort2;
 })(RecommendationSort || {});
 
-// src/types/character.ts
-var CharacterSort = /* @__PURE__ */ ((CharacterSort2) => {
-  CharacterSort2["ID"] = "ID";
-  CharacterSort2["ID_DESC"] = "ID_DESC";
-  CharacterSort2["ROLE"] = "ROLE";
-  CharacterSort2["ROLE_DESC"] = "ROLE_DESC";
-  CharacterSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
-  CharacterSort2["FAVOURITES"] = "FAVOURITES";
-  CharacterSort2["FAVOURITES_DESC"] = "FAVOURITES_DESC";
-  return CharacterSort2;
-})(CharacterSort || {});
-var CharacterRole = /* @__PURE__ */ ((CharacterRole2) => {
-  CharacterRole2["MAIN"] = "MAIN";
-  CharacterRole2["SUPPORTING"] = "SUPPORTING";
-  CharacterRole2["BACKGROUND"] = "BACKGROUND";
-  return CharacterRole2;
-})(CharacterRole || {});
-
 // src/types/staff.ts
 var StaffSort = /* @__PURE__ */ ((StaffSort2) => {
   StaffSort2["ID"] = "ID";
@@ -1226,20 +1535,6 @@ var StaffSort = /* @__PURE__ */ ((StaffSort2) => {
   return StaffSort2;
 })(StaffSort || {});
 
-// src/types/user.ts
-var UserSort = /* @__PURE__ */ ((UserSort2) => {
-  UserSort2["ID"] = "ID";
-  UserSort2["ID_DESC"] = "ID_DESC";
-  UserSort2["USERNAME"] = "USERNAME";
-  UserSort2["USERNAME_DESC"] = "USERNAME_DESC";
-  UserSort2["WATCHED_TIME"] = "WATCHED_TIME";
-  UserSort2["WATCHED_TIME_DESC"] = "WATCHED_TIME_DESC";
-  UserSort2["CHAPTERS_READ"] = "CHAPTERS_READ";
-  UserSort2["CHAPTERS_READ_DESC"] = "CHAPTERS_READ_DESC";
-  UserSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
-  return UserSort2;
-})(UserSort || {});
-
 // src/types/studio.ts
 var StudioSort = /* @__PURE__ */ ((StudioSort2) => {
   StudioSort2["ID"] = "ID";
@@ -1252,50 +1547,6 @@ var StudioSort = /* @__PURE__ */ ((StudioSort2) => {
   return StudioSort2;
 })(StudioSort || {});
 
-// src/types/lists.ts
-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 || {});
-
 // src/types/thread.ts
 var ThreadSort = /* @__PURE__ */ ((ThreadSort2) => {
   ThreadSort2["ID"] = "ID";
@@ -1317,6 +1568,20 @@ var ThreadSort = /* @__PURE__ */ ((ThreadSort2) => {
   return ThreadSort2;
 })(ThreadSort || {});
 
+// src/types/user.ts
+var UserSort = /* @__PURE__ */ ((UserSort2) => {
+  UserSort2["ID"] = "ID";
+  UserSort2["ID_DESC"] = "ID_DESC";
+  UserSort2["USERNAME"] = "USERNAME";
+  UserSort2["USERNAME_DESC"] = "USERNAME_DESC";
+  UserSort2["WATCHED_TIME"] = "WATCHED_TIME";
+  UserSort2["WATCHED_TIME_DESC"] = "WATCHED_TIME_DESC";
+  UserSort2["CHAPTERS_READ"] = "CHAPTERS_READ";
+  UserSort2["CHAPTERS_READ_DESC"] = "CHAPTERS_READ_DESC";
+  UserSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
+  return UserSort2;
+})(UserSort || {});
+
 // src/client/media.ts
 async function getMedia(client, id, include) {
   validateId(id, "mediaId");
@@ -1324,6 +1589,14 @@ async function getMedia(client, id, include) {
   const data = await client.request(query, { id });
   return data.Media;
 }
+async function getMediaByMalId(client, malId, type) {
+  validateId(malId, "malId");
+  const data = await client.request(QUERY_MEDIA_BY_MAL_ID, {
+    idMal: malId,
+    type
+  });
+  return data.Media;
+}
 async function searchMedia(client, options = {}) {
   const { query: search, page = 1, perPage = 20, genres, tags, genresExclude, tagsExclude, ...filters } = options;
   return client.pagedRequest(
@@ -1444,7 +1717,7 @@ async function getWeeklySchedule(client, date = /* @__PURE__ */ new Date()) {
   for await (const episode of iterator) {
     const epDate = new Date(episode.airingAt * 1e3);
     const dayName = names[epDate.getUTCDay()];
-    schedule[dayName].push(episode);
+    if (dayName) schedule[dayName].push(episode);
   }
   return schedule;
 }
@@ -1470,8 +1743,14 @@ async function searchStaff(client, options = {}) {
 }
 
 // src/client/studio.ts
-async function getStudio(client, id) {
+async function getStudio(client, id, include) {
   validateId(id, "studioId");
+  if (include?.media) {
+    const perPage = typeof include.media === "object" ? include.media.perPage : void 0;
+    const query = buildStudioByIdQuery(perPage);
+    const data2 = await client.request(query, { id });
+    return data2.Studio;
+  }
   const data = await client.request(QUERY_STUDIO_BY_ID, { id });
   return data.Studio;
 }
@@ -1527,7 +1806,7 @@ async function searchUsers(client, options = {}) {
 }
 async function getUserMediaList(client, options) {
   if (!options.userId && !options.userName) {
-    throw new AniListError("getUserMediaList requires either userId or userName", 0, []);
+    throw new TypeError("getUserMediaList requires either userId or userName");
   }
   if (options.userId) {
     validateId(options.userId, "userId");
@@ -1546,15 +1825,18 @@ async function getUserMediaList(client, options) {
     "mediaList"
   );
 }
-async function getUserFavorites(client, idOrName) {
+async function getUserFavorites(client, idOrName, options) {
+  const useBuilder = options?.perPage !== void 0;
   if (typeof idOrName === "number") {
     validateId(idOrName, "userId");
-    const data2 = await client.request(QUERY_USER_FAVORITES_BY_ID, {
+    const query2 = useBuilder ? buildUserFavoritesQuery("id", options.perPage) : QUERY_USER_FAVORITES_BY_ID;
+    const data2 = await client.request(query2, {
       id: idOrName
     });
     return mapFavorites(data2.User.favourites);
   }
-  const data = await client.request(QUERY_USER_FAVORITES_BY_NAME, {
+  const query = useBuilder ? buildUserFavoritesQuery("name", options.perPage) : QUERY_USER_FAVORITES_BY_NAME;
+  const data = await client.request(query, {
     name: idOrName
   });
   return mapFavorites(data.User.favourites);
@@ -1571,10 +1853,19 @@ function mapFavorites(fav) {
 
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
-var LIB_VERSION = "1.7.0" ;
+var LIB_VERSION = "1.8.1" ;
 var AniListClient = class {
+  apiUrl;
+  headers;
+  cacheAdapter;
+  rateLimiter;
+  hooks;
+  logger;
+  signal;
+  inFlight = /* @__PURE__ */ new Map();
+  _rateLimitInfo;
+  _lastRequestMeta;
   constructor(options = {}) {
-    this.inFlight = /* @__PURE__ */ new Map();
     this.apiUrl = options.apiUrl ?? DEFAULT_API_URL;
     this.headers = {
       "Content-Type": "application/json",
@@ -1587,6 +1878,7 @@ var AniListClient = class {
     this.cacheAdapter = options.cacheAdapter ?? new MemoryCache(options.cache);
     this.rateLimiter = new RateLimiter(options.rateLimit);
     this.hooks = options.hooks ?? {};
+    this.logger = options.logger;
     this.signal = options.signal;
   }
   /**
@@ -1609,6 +1901,7 @@ var AniListClient = class {
     const cached = await this.cacheAdapter.get(cacheKey);
     if (cached !== void 0) {
       this.hooks.onCacheHit?.(cacheKey);
+      this.logger?.debug("Cache hit", { cacheKey });
       const meta = { durationMs: 0, fromCache: true };
       this._lastRequestMeta = meta;
       this.hooks.onResponse?.(query, 0, true);
@@ -1628,6 +1921,7 @@ var AniListClient = class {
   async executeRequest(query, variables, cacheKey) {
     const start = Date.now();
     this.hooks.onRequest?.(query, variables);
+    this.logger?.debug("API request", { variables });
     const minifiedQuery = normalizeQuery(query);
     let res;
     try {
@@ -1643,13 +1937,23 @@ var AniListClient = class {
       );
     } catch (err) {
       const error = err instanceof AniListError ? err : new AniListError(err.message ?? "Network request failed", 0, [err]);
+      this.logger?.error("Request failed", { error: error.message, status: error.status });
+      this.hooks.onError?.(error, query, variables);
+      throw error;
+    }
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      const error = new AniListError(`Non-JSON response from AniList (HTTP ${res.status})`, res.status, []);
+      this.logger?.error("Request failed", { error: error.message, status: error.status });
       this.hooks.onError?.(error, query, variables);
       throw error;
     }
-    const json = await res.json();
     if (!res.ok || json.errors) {
       const message = json.errors?.[0]?.message ?? `AniList API error (HTTP ${res.status})`;
       const error = new AniListError(message, res.status, json.errors ?? []);
+      this.logger?.error("Request failed", { error: error.message, status: error.status });
       this.hooks.onError?.(error, query, variables);
       throw error;
     }
@@ -1668,6 +1972,7 @@ var AniListClient = class {
     await this.cacheAdapter.set(cacheKey, data);
     const meta = { durationMs, fromCache: false, rateLimitInfo: this._rateLimitInfo };
     this._lastRequestMeta = meta;
+    this.logger?.debug("Request complete", { durationMs, rateLimitInfo: this._rateLimitInfo });
     this.hooks.onResponse?.(query, durationMs, false, this._rateLimitInfo);
     return data;
   }
@@ -1730,6 +2035,15 @@ var AniListClient = class {
   async getAiredChapters(options = {}) {
     return this.getRecentlyUpdatedManga(options);
   }
+  /**
+   * 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)
+   */
+  async getMediaByMalId(malId, type) {
+    return getMediaByMalId(this, malId, type);
+  }
   /** Get the detailed schedule for the current week, sorted by day. */
   async getWeeklySchedule(date) {
     return getWeeklySchedule(this, date);
@@ -1782,20 +2096,32 @@ var AniListClient = class {
    * 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 });
    * ```
    */
-  async getUserFavorites(idOrName) {
-    return getUserFavorites(this, idOrName);
+  async getUserFavorites(idOrName, options) {
+    return getUserFavorites(this, idOrName, options);
   }
-  /** Fetch a studio by its AniList ID. */
-  async getStudio(id) {
-    return getStudio(this, id);
+  /**
+   * 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 } });
+   * ```
+   */
+  async getStudio(id, include) {
+    return getStudio(this, id, include);
   }
   /** Search for studios by name. */
   async searchStudios(options = {}) {
@@ -1845,21 +2171,24 @@ var AniListClient = class {
   async getMediaBatch(ids) {
     if (ids.length === 0) return [];
     validateIds(ids, "mediaId");
-    if (ids.length === 1) return [await this.getMedia(ids[0])];
+    const [singleMediaId] = ids;
+    if (ids.length === 1 && singleMediaId !== void 0) return [await this.getMedia(singleMediaId)];
     return this.executeBatch(ids, buildBatchMediaQuery, "m");
   }
   /** Fetch multiple characters in a single API request. */
   async getCharacterBatch(ids) {
     if (ids.length === 0) return [];
     validateIds(ids, "characterId");
-    if (ids.length === 1) return [await this.getCharacter(ids[0])];
+    const [singleCharId] = ids;
+    if (ids.length === 1 && singleCharId !== void 0) return [await this.getCharacter(singleCharId)];
     return this.executeBatch(ids, buildBatchCharacterQuery, "c");
   }
   /** Fetch multiple staff members in a single API request. */
   async getStaffBatch(ids) {
     if (ids.length === 0) return [];
     validateIds(ids, "staffId");
-    if (ids.length === 1) return [await this.getStaff(ids[0])];
+    const [singleStaffId] = ids;
+    if (ids.length === 1 && singleStaffId !== void 0) return [await this.getStaff(singleStaffId)];
     return this.executeBatch(ids, buildBatchStaffQuery, "s");
   }
   /** @internal */
@@ -1904,88 +2233,23 @@ var AniListClient = class {
     this.inFlight.clear();
     this.rateLimiter.dispose();
   }
-};
-
-// 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;
-  }
   /**
-   * Collect keys matching a pattern. Uses SCAN when available, falls back to KEYS.
+   * 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.
    *
-   * **Warning:** The `KEYS` fallback is O(N) and blocks the Redis server.
-   * Provide a client with `scanIterator` support for production use.
-   * @internal
-   */
-  async collectKeys(pattern) {
-    if (this.client.scanIterator) {
-      const keys = [];
-      for await (const key of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {
-        keys.push(key);
-      }
-      return keys;
-    }
-    return this.client.keys(pattern);
-  }
-  async clear() {
-    const keys = await this.collectKeys(`${this.prefix}*`);
-    if (keys.length > 0) {
-      await this.client.del(...keys);
-    }
-  }
-  /**
-   * Get the actual number of keys with this prefix in Redis.
-   */
-  get size() {
-    return this.getSize();
-  }
-  /** @internal */
-  async getSize() {
-    const keys = await this.collectKeys(`${this.prefix}*`);
-    return keys.length;
-  }
-  async keys() {
-    const raw = await this.collectKeys(`${this.prefix}*`);
-    return raw.map((k) => k.slice(this.prefix.length));
-  }
-  /**
-   * Remove all entries whose key matches the given glob pattern.
+   * @example
+   * ```ts
+   * const controller = new AbortController();
+   * const media = await client.withSignal(controller.signal).getMedia(1);
    *
-   * @param pattern — A glob pattern (e.g. `"*Media*"`)
-   * @returns Number of entries removed.
+   * // Cancel all in-flight requests made through the scoped view
+   * controller.abort();
+   * ```
    */
-  async invalidate(pattern) {
-    if (typeof pattern === "string") {
-      const keys = await this.collectKeys(`${this.prefix}${pattern}`);
-      if (keys.length === 0) return 0;
-      return this.client.del(...keys);
-    }
-    const allKeys = await this.collectKeys(`${this.prefix}*`);
-    const matching = allKeys.filter((k) => pattern.test(k.slice(this.prefix.length)));
-    if (matching.length === 0) return 0;
-    return this.client.del(...matching);
+  withSignal(signal) {
+    const scoped = Object.create(this);
+    Object.defineProperty(scoped, "signal", { value: signal, configurable: true });
+    return scoped;
   }
 };