ani-client 1.7.0 → 1.8.0

package/dist/index.js

@@ -127,28 +127,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. */
@@ -165,9 +189,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() {
@@ -177,6 +204,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.
    *
@@ -199,6 +252,10 @@ var MemoryCache = class {
 
 // 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";
@@ -212,6 +269,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
@@ -631,6 +714,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) {
@@ -769,6 +858,63 @@ query ($name: String!) {
     ${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/queries/studio.ts
 var QUERY_STUDIO_BY_ID = `
@@ -777,6 +923,26 @@ query ($id: Int!) {
     ${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) {
@@ -927,11 +1093,21 @@ query ($search: String, $mediaCategoryId: Int, $categoryId: Int, $sort: [ThreadS
 
 // 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;
@@ -1326,6 +1502,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(
@@ -1446,7 +1630,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;
 }
@@ -1472,8 +1656,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;
 }
@@ -1548,15 +1738,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);
@@ -1573,10 +1766,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.0" ;
 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",
@@ -1589,6 +1791,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;
   }
   /**
@@ -1611,6 +1814,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);
@@ -1630,6 +1834,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 {
@@ -1645,6 +1850,7 @@ 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;
     }
@@ -1652,6 +1858,7 @@ var AniListClient = class {
     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;
     }
@@ -1670,6 +1877,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;
   }
@@ -1732,6 +1940,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);
@@ -1784,20 +2001,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 = {}) {
@@ -1847,21 +2076,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 */
@@ -1906,10 +2138,31 @@ var AniListClient = class {
     this.inFlight.clear();
     this.rateLimiter.dispose();
   }
+  /**
+   * 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) {
+    const scoped = Object.create(this);
+    Object.defineProperty(scoped, "signal", { value: signal, configurable: true });
+    return scoped;
+  }
 };
 
 // src/cache/redis.ts
 var RedisCache = class {
+  client;
+  prefix;
+  ttl;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "ani:";