ani-client 1.2.0 → 1.3.0

package/dist/index.js

@@ -347,16 +347,15 @@ query {
     isAdult
   }
 }`;
-
-// src/errors/index.ts
-var AniListError = class extends Error {
-  constructor(message, status, errors = []) {
-    super(message);
-    this.name = "AniListError";
-    this.status = status;
-    this.errors = errors;
-  }
-};
+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;
@@ -369,7 +368,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) {
@@ -380,11 +379,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);
@@ -403,6 +405,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
@@ -415,6 +448,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).
@@ -432,66 +467,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.
    *
@@ -518,22 +628,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.
@@ -543,8 +639,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.
@@ -557,14 +652,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.
@@ -577,13 +666,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.
@@ -634,8 +718,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.
@@ -652,12 +735,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.
@@ -674,14 +759,16 @@ var AniListClient = class {
    * ```
    */
   async getPlanning(options = {}) {
-    const variables = {
-      type: options.type,
-      sort: options.sort ?? ["POPULARITY_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 };
+    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.
@@ -732,16 +819,18 @@ var AniListClient = class {
    * ```
    */
   async getMediaBySeason(options) {
-    const variables = {
-      season: options.season,
-      seasonYear: options.seasonYear,
-      type: options.type ?? "ANIME",
-      sort: options.sort ?? ["POPULARITY_DESC"],
-      page: options.page ?? 1,
-      perPage: options.perPage ?? 20
-    };
-    const data = await this.request(QUERY_MEDIA_BY_SEASON, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.media };
+    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.
@@ -771,17 +860,19 @@ var AniListClient = class {
     if (!options.userId && !options.userName) {
       throw new Error("Either userId or userName must be provided");
     }
-    const variables = {
-      userId: options.userId,
-      userName: options.userName,
-      type: options.type,
-      status: options.status,
-      sort: options.sort,
-      page: options.page ?? 1,
-      perPage: options.perPage ?? 20
-    };
-    const data = await this.request(QUERY_USER_MEDIA_LIST, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.mediaList };
+    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.
@@ -806,13 +897,15 @@ var AniListClient = class {
    * ```
    */
   async searchStudios(options = {}) {
-    const variables = {
-      search: options.query,
-      page: options.page ?? 1,
-      perPage: options.perPage ?? 20
-    };
-    const data = await this.request(QUERY_STUDIO_SEARCH, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page.studios };
+    return this.pagedRequest(
+      QUERY_STUDIO_SEARCH,
+      {
+        search: options.query,
+        page: options.page ?? 1,
+        perPage: options.perPage ?? 20
+      },
+      "studios"
+    );
   }
   /**
    * Get all available genres on AniList.
@@ -860,7 +953,7 @@ var AniListClient = class {
    * }
    * ```
    */
-  async *paginate(fetchPage, maxPages = Infinity) {
+  async *paginate(fetchPage, maxPages = Number.POSITIVE_INFINITY) {
     let page = 1;
     let hasNext = true;
     while (hasNext && page <= maxPages) {
@@ -872,17 +965,155 @@ var AniListClient = class {
       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);
   }
 };
 
@@ -1039,5 +1270,6 @@ exports.MediaType = MediaType;
 exports.MemoryCache = MemoryCache;
 exports.RateLimiter = RateLimiter;
 exports.RecommendationSort = RecommendationSort;
+exports.RedisCache = RedisCache;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map