ani-client 1.6.0 → 1.6.1

package/README.md

@@ -7,7 +7,7 @@
 
 > A simple, typed client to fetch anime, manga, character, staff and user data from [AniList](https://anilist.co).
 
-✨ **Showcase**: [Check here](https://gonzyuidev.xyz/projects/aniclient/showcase) to see which projects use this package!
+✨ **Showcase**: [Check here](https://ani-client.js.org/showcase) to see which projects use this package!
 
 - **Zero dependencies** — uses the native `fetch` API
 - **Universal** — Node.js ≥ 20, Bun, Deno and modern browsers
@@ -18,7 +18,7 @@
 
 The full API reference, usage guide, and configuration examples are available on our official documentation website!
 
-**[👉 View the full documentation here](https://gonzyuidev.xyz/projects/aniclient/)**
+**[👉 View the full documentation here](https://ani-client.js.org)**
 
 ## Install
 

package/dist/index.d.mts

@@ -90,6 +90,8 @@ interface AniListHooks {
     onRetry?: (attempt: number, reason: string, delayMs: number) => void;
     /** Called when a request completes. */
     onResponse?: (query: string, durationMs: number, fromCache: boolean, rateLimitInfo?: RateLimitInfo) => void;
+    /** Called when a request fails with an error. */
+    onError?: (error: Error, query: string, variables: Record<string, unknown>) => void;
 }
 /** Rate limit information parsed from AniList API response headers. */
 interface RateLimitInfo {
@@ -1077,7 +1079,7 @@ declare class AniListClient {
     /** Clear the entire response cache. */
     clearCache(): Promise<void>;
     /** Number of entries currently in the cache. */
-    get cacheSize(): number | Promise<number>;
+    cacheSize(): Promise<number>;
     /** Remove cache entries whose key matches the given pattern. */
     invalidateCache(pattern: string | RegExp): Promise<number>;
     /** Clean up resources held by the client. */
@@ -1219,6 +1221,8 @@ declare class RateLimiter {
     private readonly timestamps;
     private head;
     private count;
+    /** @internal — active sleep timers for cleanup */
+    private readonly activeTimers;
     constructor(options?: RateLimitOptions);
     /**
      * Wait until it's safe to make a request (respects rate limit window).
@@ -1237,11 +1241,19 @@ declare class RateLimiter {
     /** @internal */
     private fetchWithTimeout;
     private sleep;
+    /** Cancel all pending sleep timers and reset internal state. */
+    dispose(): void;
 }
 
 /**
  * Parses AniList specific markdown into standard HTML.
- * Includes formatting for spoilers, images, videos (youtube/webm), and standard markdown elements.
+ * Includes formatting for spoilers, images, videos (youtube/webm), headings,
+ * lists, code blocks, and standard markdown elements.
+ *
+ * @security This function escapes HTML entities to prevent XSS attacks.
+ * However, the output is still raw HTML — consumers should always use a
+ * Content Security Policy and consider additional sanitization when rendering
+ * user-generated content in a browser.
  *
  * @param text The AniList markdown text to parse
  * @returns The parsed HTML string

package/dist/index.d.ts

@@ -90,6 +90,8 @@ interface AniListHooks {
     onRetry?: (attempt: number, reason: string, delayMs: number) => void;
     /** Called when a request completes. */
     onResponse?: (query: string, durationMs: number, fromCache: boolean, rateLimitInfo?: RateLimitInfo) => void;
+    /** Called when a request fails with an error. */
+    onError?: (error: Error, query: string, variables: Record<string, unknown>) => void;
 }
 /** Rate limit information parsed from AniList API response headers. */
 interface RateLimitInfo {
@@ -1077,7 +1079,7 @@ declare class AniListClient {
     /** Clear the entire response cache. */
     clearCache(): Promise<void>;
     /** Number of entries currently in the cache. */
-    get cacheSize(): number | Promise<number>;
+    cacheSize(): Promise<number>;
     /** Remove cache entries whose key matches the given pattern. */
     invalidateCache(pattern: string | RegExp): Promise<number>;
     /** Clean up resources held by the client. */
@@ -1219,6 +1221,8 @@ declare class RateLimiter {
     private readonly timestamps;
     private head;
     private count;
+    /** @internal — active sleep timers for cleanup */
+    private readonly activeTimers;
     constructor(options?: RateLimitOptions);
     /**
      * Wait until it's safe to make a request (respects rate limit window).
@@ -1237,11 +1241,19 @@ declare class RateLimiter {
     /** @internal */
     private fetchWithTimeout;
     private sleep;
+    /** Cancel all pending sleep timers and reset internal state. */
+    dispose(): void;
 }
 
 /**
  * Parses AniList specific markdown into standard HTML.
- * Includes formatting for spoilers, images, videos (youtube/webm), and standard markdown elements.
+ * Includes formatting for spoilers, images, videos (youtube/webm), headings,
+ * lists, code blocks, and standard markdown elements.
+ *
+ * @security This function escapes HTML entities to prevent XSS attacks.
+ * However, the output is still raw HTML — consumers should always use a
+ * Content Security Policy and consider additional sanitization when rendering
+ * user-generated content in a browser.
  *
  * @param text The AniList markdown text to parse
  * @returns The parsed HTML string

package/dist/index.js

@@ -4,6 +4,11 @@
 function parseAniListMarkdown(text) {
   if (!text) return "";
   let html = text;
+  html = html.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+  html = html.replace(/```([\s\S]*?)```/g, (_match, code) => {
+    return `<pre><code>${code.trim()}</code></pre>`;
+  });
+  html = html.replace(/`([^`]+)`/g, "<code>$1</code>");
   html = html.replace(/~!(.*?)!~/gs, '<span class="anilist-spoiler">$1</span>');
   html = html.replace(/~~~(.*?)~~~/gs, '<div class="anilist-center">$1</div>');
   html = html.replace(/img(\d+)\((.*?)\)/gi, '<img src="$2" width="$1" alt="" class="anilist-image" />');
@@ -13,6 +18,12 @@ function parseAniListMarkdown(text) {
     '<iframe src="https://www.youtube.com/embed/$1" frameborder="0" allowfullscreen class="anilist-youtube"></iframe>'
   );
   html = html.replace(/webm\((.*?)\)/gi, '<video src="$1" controls class="anilist-webm"></video>');
+  html = html.replace(/^######\s+(.+)$/gm, "<h6>$1</h6>");
+  html = html.replace(/^#####\s+(.+)$/gm, "<h5>$1</h5>");
+  html = html.replace(/^####\s+(.+)$/gm, "<h4>$1</h4>");
+  html = html.replace(/^###\s+(.+)$/gm, "<h3>$1</h3>");
+  html = html.replace(/^##\s+(.+)$/gm, "<h2>$1</h2>");
+  html = html.replace(/^#\s+(.+)$/gm, "<h1>$1</h1>");
   html = html.replace(/__(.*?)__/g, "<strong>$1</strong>");
   html = html.replace(/\*\*(.*?)\*\*/g, "<strong>$1</strong>");
   html = html.replace(/_(.*?)_/g, "<em>$1</em>");
@@ -20,14 +31,46 @@ function parseAniListMarkdown(text) {
   html = html.replace(/~~(.*?)~~/g, "<del>$1</del>");
   html = html.replace(/\[(.*?)\]\((.*?)\)/g, '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>');
   html = html.replace(/\r\n/g, "\n");
+  const lines = html.split("\n");
+  const processed = [];
+  let listType = null;
+  for (const line of lines) {
+    const ulMatch = line.match(/^[\s]*[-*]\s+(.*)/);
+    const olMatch = line.match(/^[\s]*\d+\.\s+(.*)/);
+    if (ulMatch) {
+      if (listType !== "ul") {
+        if (listType) processed.push(`</${listType}>`);
+        processed.push("<ul>");
+        listType = "ul";
+      }
+      processed.push(`<li>${ulMatch[1]}</li>`);
+    } else if (olMatch) {
+      if (listType !== "ol") {
+        if (listType) processed.push(`</${listType}>`);
+        processed.push("<ol>");
+        listType = "ol";
+      }
+      processed.push(`<li>${olMatch[1]}</li>`);
+    } else {
+      if (listType) {
+        processed.push(`</${listType}>`);
+        listType = null;
+      }
+      processed.push(line);
+    }
+  }
+  if (listType) processed.push(`</${listType}>`);
+  html = processed.join("\n");
   const paragraphs = html.split(/\n{2,}/);
   html = paragraphs.map((p) => {
-    const withBr = p.replace(/\n/g, "<br />");
-    if (withBr.match(/^(<div|<iframe|<video|<img)/)) {
+    const trimmed = p.trim();
+    if (!trimmed) return "";
+    const withBr = trimmed.replace(/\n/g, "<br />");
+    if (withBr.match(/^(<div|<iframe|<video|<img|<h[1-6]|<ul|<ol|<pre)/)) {
       return withBr;
     }
     return `<p>${withBr}</p>`;
-  }).join("\n");
+  }).filter(Boolean).join("\n");
   return html;
 }
 
@@ -802,7 +845,7 @@ function buildBatchQuery(ids, typeName, fields, prefix) {
   ${aliases}
 }`;
 }
-var buildBatchMediaQuery = (ids) => buildBatchQuery(ids, "Media", MEDIA_FIELDS_BASE, "m");
+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");
 
@@ -870,6 +913,8 @@ var RateLimiter = class {
   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;
@@ -887,8 +932,7 @@ var RateLimiter = class {
     if (!this.enabled) return;
     if (this.count >= this.maxRequests) {
       const oldest = this.timestamps[this.head];
-      const now2 = Date.now();
-      const elapsed = now2 - oldest;
+      const elapsed = Date.now() - oldest;
       if (elapsed < this.windowMs) {
         const waitMs = this.windowMs - elapsed + 50;
         await this.sleep(waitMs);
@@ -952,14 +996,32 @@ var RateLimiter = class {
     if (this.timeoutMs <= 0) return fetch(url, init);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const signals = [controller.signal, init.signal].filter(Boolean);
+    const combinedSignal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
     try {
-      return await fetch(url, { ...init, signal: controller.signal });
+      return await fetch(url, { ...init, signal: combinedSignal });
     } finally {
       clearTimeout(timer);
     }
   }
   sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.activeTimers.delete(timer);
+        resolve();
+      }, ms);
+      this.activeTimers.add(timer);
+    });
+  }
+  /** Cancel all pending sleep timers and reset internal state. */
+  dispose() {
+    for (const timer of this.activeTimers) {
+      clearTimeout(timer);
+    }
+    this.activeTimers.clear();
+    this.head = 0;
+    this.count = 0;
+    this.timestamps.fill(0);
   }
 };
 var RETRYABLE_NETWORK_CODES = /* @__PURE__ */ new Set([
@@ -1333,14 +1395,12 @@ async function getWeeklySchedule(client, date = /* @__PURE__ */ new Date()) {
     Saturday: [],
     Sunday: []
   };
-  const startOfWeek = new Date(date);
-  const day = startOfWeek.getDay();
-  const diff = startOfWeek.getDate() - day + (day === 0 ? -6 : 1);
-  startOfWeek.setDate(diff);
-  startOfWeek.setHours(0, 0, 0, 0);
+  const utcDay = date.getUTCDay();
+  const diff = utcDay === 0 ? -6 : 1 - utcDay;
+  const startOfWeek = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + diff, 0, 0, 0));
   const endOfWeek = new Date(startOfWeek);
-  endOfWeek.setDate(startOfWeek.getDate() + 6);
-  endOfWeek.setHours(23, 59, 59, 999);
+  endOfWeek.setUTCDate(startOfWeek.getUTCDate() + 6);
+  endOfWeek.setUTCHours(23, 59, 59, 999);
   const startTimestamp = Math.floor(startOfWeek.getTime() / 1e3);
   const endTimestamp = Math.floor(endOfWeek.getTime() / 1e3);
   const iterator = client.paginate(
@@ -1354,7 +1414,7 @@ async function getWeeklySchedule(client, date = /* @__PURE__ */ new Date()) {
   const names = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
   for await (const episode of iterator) {
     const epDate = new Date(episode.airingAt * 1e3);
-    const dayName = names[epDate.getDay()];
+    const dayName = names[epDate.getUTCDay()];
     schedule[dayName].push(episode);
   }
   return schedule;
@@ -1477,13 +1537,15 @@ function mapFavorites(fav) {
 
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
+var LIB_VERSION = "1.6.1" ;
 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"
+      Accept: "application/json",
+      "User-Agent": `ani-client/${LIB_VERSION}`
     };
     if (options.token) {
       this.headers.Authorization = `Bearer ${options.token}`;
@@ -1507,7 +1569,6 @@ var AniListClient = class {
   get lastRequestMeta() {
     return this._lastRequestMeta;
   }
-  // ── Core infrastructure (internal) ──
   /** @internal */
   async request(query, variables = {}) {
     const cacheKey = MemoryCache.key(query, variables);
@@ -1534,20 +1595,29 @@ var AniListClient = class {
     const start = Date.now();
     this.hooks.onRequest?.(query, variables);
     const minifiedQuery = normalizeQuery(query);
-    const res = await this.rateLimiter.fetchWithRetry(
-      this.apiUrl,
-      {
-        method: "POST",
-        headers: this.headers,
-        body: JSON.stringify({ query: minifiedQuery, variables }),
-        signal: this.signal
-      },
-      { onRetry: this.hooks.onRetry, onRateLimit: this.hooks.onRateLimit }
-    );
+    let res;
+    try {
+      res = await this.rateLimiter.fetchWithRetry(
+        this.apiUrl,
+        {
+          method: "POST",
+          headers: this.headers,
+          body: JSON.stringify({ query: minifiedQuery, variables }),
+          signal: this.signal
+        },
+        { onRetry: this.hooks.onRetry, onRateLimit: this.hooks.onRateLimit }
+      );
+    } catch (err) {
+      const error = err instanceof AniListError ? err : new AniListError(err.message ?? "Network request failed", 0, [err]);
+      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})`;
-      throw new AniListError(message, res.status, json.errors ?? []);
+      const error = new AniListError(message, res.status, json.errors ?? []);
+      this.hooks.onError?.(error, query, variables);
+      throw error;
     }
     const rlLimit = res.headers.get("X-RateLimit-Limit");
     const rlRemaining = res.headers.get("X-RateLimit-Remaining");
@@ -1576,7 +1646,6 @@ var AniListClient = class {
     }
     return { pageInfo: data.Page.pageInfo, results };
   }
-  // ── Media ──
   /**
    * Fetch a single media entry by its AniList ID.
    *
@@ -1633,7 +1702,6 @@ var AniListClient = class {
   async getMediaBySeason(options) {
     return getMediaBySeason(this, options);
   }
-  // ── Characters ──
   /** Fetch a character by AniList ID. Pass `{ voiceActors: true }` to include VA data. */
   async getCharacter(id, include) {
     return getCharacter(this, id, include);
@@ -1642,7 +1710,6 @@ var AniListClient = class {
   async searchCharacters(options = {}) {
     return searchCharacters(this, options);
   }
-  // ── Staff ──
   /** Fetch a staff member by AniList ID. Pass `{ media: true }` or `{ media: { perPage } }` for media credits. */
   async getStaff(id, include) {
     return getStaff(this, id, include);
@@ -1651,7 +1718,6 @@ var AniListClient = class {
   async searchStaff(options = {}) {
     return searchStaff(this, options);
   }
-  // ── Users ──
   /**
    * Fetch a user by AniList ID or username.
    *
@@ -1683,7 +1749,6 @@ var AniListClient = class {
   async getUserFavorites(idOrName) {
     return getUserFavorites(this, idOrName);
   }
-  // ── Studios ──
   /** Fetch a studio by its AniList ID. */
   async getStudio(id) {
     return getStudio(this, id);
@@ -1692,8 +1757,6 @@ var AniListClient = class {
   async searchStudios(options = {}) {
     return searchStudios(this, options);
   }
-  // ── Metadata ──
-  // ── Threads ──
   /** Fetch a forum thread by its AniList ID. */
   async getThread(id) {
     return getThread(this, id);
@@ -1712,12 +1775,10 @@ var AniListClient = class {
     const data = await this.request(QUERY_TAGS);
     return data.MediaTagCollection;
   }
-  // ── Raw query ──
   /** Execute an arbitrary GraphQL query against the AniList API. */
   async raw(query, variables) {
     return this.request(query, variables ?? {});
   }
-  // ── Pagination ──
   /**
    * Auto-paginating async iterator. Yields individual items across all pages.
    *
@@ -1736,7 +1797,6 @@ var AniListClient = class {
       page++;
     }
   }
-  // ── Batch queries ──
   /** Fetch multiple media entries in a single API request. */
   async getMediaBatch(ids) {
     if (ids.length === 0) return [];
@@ -1770,13 +1830,12 @@ var AniListClient = class {
     );
     return chunkResults.flat();
   }
-  // ── Cache management ──
   /** Clear the entire response cache. */
   async clearCache() {
     await this.cacheAdapter.clear();
   }
   /** Number of entries currently in the cache. */
-  get cacheSize() {
+  async cacheSize() {
     return this.cacheAdapter.size;
   }
   /** Remove cache entries whose key matches the given pattern. */
@@ -1799,6 +1858,7 @@ var AniListClient = class {
   async destroy() {
     await this.cacheAdapter.clear();
     this.inFlight.clear();
+    this.rateLimiter.dispose();
   }
 };