ani-client 2.2.1 → 2.3.0

package/README.md

@@ -8,12 +8,12 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 > A fully typed, zero-dependency client for the [AniList](https://anilist.co) GraphQL API.  
-> Supports Node.js, Bun, Deno, and modern browsers.
+> Supports Node.js and modern browsers.
 
 ## Features
 
 - **Zero dependencies** — uses the native `fetch` API
-- **Universal** — Node.js ≥ 20, Bun, Deno, and modern browsers
+- **Universal** — Node.js ≥ 20, and modern browsers
 - **Dual format** — ships ESM + CJS with full `.d.ts` declarations
 - **LRU cache** with TTL, stale-while-revalidate, and hit/miss stats
 - **Rate-limit protection** with exponential backoff, retries, and custom strategies
@@ -52,180 +52,21 @@ const results = await client.searchMedia({
   genres: ["Action"],
   perPage: 10,
 });
-
-// Lookup by MyAnimeList ID
-const fma = await client.getMediaByMalId(5114);
-```
-
-## Usage
-
-### Caching
-
-The client caches every response in memory by default. You can tune TTL, capacity, and enable stale-while-revalidate:
-
-```ts
-const client = new AniListClient({
-  cache: {
-    ttl: 1000 * 60 * 5,            // 5 min TTL
-    maxSize: 200,                   // LRU capacity
-    staleWhileRevalidateMs: 60_000, // serve stale for 1 min after expiry
-  },
-});
-```
-
-For distributed setups, swap to the built-in Redis adapter:
-
-```ts
-import { AniListClient, RedisCache } from "ani-client";
-import { createClient } from "redis";
-
-const redis = createClient();
-await redis.connect();
-
-const client = new AniListClient({
-  cacheAdapter: new RedisCache(redis),
-});
 ```
 
-### Rate Limiting
-
-The client is pre-configured to stay within AniList's 30 req/min limit. You can override the defaults and provide a custom retry strategy:
-
-```ts
-const client = new AniListClient({
-  rateLimit: {
-    maxRequests: 25,
-    windowMs: 60_000,
-    maxRetries: 3,
-    retryOnNetworkError: true,
-    retryStrategy: (attempt) => (attempt + 1) * 1000, // linear backoff
-  },
-});
-
-// Inspect the rate limit state after any request
-console.log(client.rateLimitInfo);
-// { remaining: 22, limit: 25, reset: 1741104000 }
-```
-
-### Batch Requests
-
-Fetch multiple entries in a single API call (chunks of 50):
-
-```ts
-const anime = await client.getMediaBatch([1, 5, 6, 20]);
-const characters = await client.getCharacterBatch([1, 2, 3]);
-const staff = await client.getStaffBatch([95269, 95270]);
-```
-
-### Auto-Pagination
-
-Use the built-in async iterator to walk through all pages automatically:
-
-```ts
-for await (const anime of client.paginate(
-  (page) => client.searchMedia({ query: "Gundam", page, perPage: 50 }),
-  5, // max 5 pages
-)) {
-  console.log(anime.title.romaji);
-}
-```
-
-### Request Cancellation
-
-Scope any client instance to an `AbortSignal` for per-request cancellation:
-
-```ts
-const controller = new AbortController();
-const scoped = client.withSignal(controller.signal);
-
-setTimeout(() => controller.abort(), 3_000);
-const anime = await scoped.getMedia(1); // cancelled after 3s
-```
-
-### Logging
-
-Pass any `console`-compatible logger to trace requests and cache events:
-
-```ts
-const client = new AniListClient({ logger: console });
-// debug: "API request"    { variables: { id: 1 } }
-// debug: "Request complete" { durationMs: 120 }
-```
-
-### Media Relationships
-
-Paginated access to a media's characters and staff:
-
-```ts
-const characters = await client.getMediaCharacters(1, {
-  page: 1,
-  perPage: 25,
-  voiceActors: true,
-});
-
-const staff = await client.getMediaStaff(1, { page: 1, perPage: 25 });
-```
-
-### Users, Characters, Studios & More
-
-```ts
-const user     = await client.getUser("AniList");
-const favs     = await client.getUserFavorites("AniList", { perPage: 50 });
-const char     = await client.getCharacter(1, { voiceActors: true });
-const studio   = await client.getStudio(21, { media: { perPage: 50 } });
-const schedule = await client.getWeeklySchedule();
-const review   = await client.getReview(760);
-```
-
-### Error Handling
-
-All API errors throw an `AniListError` with a `status` code and the raw GraphQL `errors` array:
-
-```ts
-import { AniListError } from "ani-client";
-
-try {
-  await client.getMedia(999999999);
-} catch (e) {
-  if (e instanceof AniListError) {
-    console.error(e.message); // "Not Found"
-    console.error(e.status);  // 404
-    console.error(e.errors);  // raw GraphQL errors array
-  }
-}
-```
-
-### Lifecycle Hooks
+## Documentation
 
-Intercept requests, responses, cache events, and errors:
+For full API reference, configuration options, caching, rate limiting, and advanced usage guides, please visit the official documentation:
 
-```ts
-const client = new AniListClient({
-  hooks: {
-    onRequest:    (query, variables) => console.log("→", variables),
-    onResponse:   (query, durationMs, fromCache) => console.log(`← ${durationMs}ms`),
-    onCacheHit:   (key) => console.log("cache hit", key),
-    onRateLimit:  (retryAfterMs) => console.warn(`rate limited, retrying in ${retryAfterMs}ms`),
-    onError:      (error) => console.error(error.message),
-  },
-});
-```
+**[📚 ani-client.js.org](https://ani-client.js.org)**
 
 ## Requirements
 
 | Runtime  | Version            |
 |----------|--------------------|
 | Node.js  | ≥ 22.13.0          |
-| Bun      | ≥ 1.0              |
-| Deno     | ≥ 1.28             |
 | Browsers | `fetch` + `AbortController` required |
 
-## Documentation
-
-Full API reference, configuration options, and guides (caching, pagination, hooks, Redis, etc.):
-
-**[ani-client.js.org](https://ani-client.js.org)**
-
 ## Community
 
 - 💬 [Discord server](https://discord.gg/3P7twDurUD)
@@ -233,34 +74,10 @@ Full API reference, configuration options, and guides (caching, pagination, hook
 
 ## Contributing
 
-Contributions are welcome.
-
-Before opening an issue or a pull request, please read:
+Contributions are welcome! Before opening an issue or a pull request, please read:
 - [CONTRIBUTING.md](CONTRIBUTING.md)
 - [SECURITY.md](SECURITY.md)
 
-This repository also includes GitHub issue templates and a pull request template to help keep reports and contributions consistent.
-
-## Development
-
-Quick commands for local development and CI checks:
-
-```bash
-pnpm install
-pnpm run build       # build dist
-pnpm run typecheck   # TypeScript strict checks
-pnpm run lint        # lint the codebase
-pnpm test            # run unit + integration tests
-pnpm run docs:dev    # run documentation site locally
-```
-
-Notes:
-- `tsconfig.json` has `strict: true` enabled to enforce stricter TypeScript checks.
-- Dependabot is configured to open weekly dependency PRs — you will review and merge them manually.
-- CI should validate `build`, `typecheck`, `lint`, and `test` before merging PRs.
-
-This repository also includes GitHub issue templates and a pull request template to help keep reports and contributions consistent.
-
 ## License
 
-[MIT](LICENSE) © [gonzyui](https://github.com/gonzyui)
+[MIT](LICENSE) © [gonzyui](https://gonzyuidev.xyz)

package/dist/index.d.mts

@@ -931,10 +931,10 @@ declare class NormalizedCache implements CacheAdapter {
     private readonly swrMs;
     private readonly queryStore;
     private readonly entityStore;
+    private readonly refCount;
     private _hits;
     private _misses;
     private _stales;
-    private gcTimeout?;
     constructor(options?: CacheOptions);
     static key(query: string, variables: Record<string, unknown>): string;
     /** Normalizes a GraphQL response, extracting entities and returning a tree of references. */
@@ -947,6 +947,7 @@ declare class NormalizedCache implements CacheAdapter {
     } | undefined;
     get<T>(key: string): T | undefined;
     set<T>(key: string, data: T): void;
+    private deleteQueryEntry;
     delete(key: string): boolean;
     clear(): void;
     get size(): number;
@@ -956,12 +957,6 @@ declare class NormalizedCache implements CacheAdapter {
         entitiesCount: number;
     };
     resetStats(): void;
-    private scheduleGc;
-    /**
-     * Garbage-collect orphaned entities that are no longer referenced by any query.
-     * Called automatically on LRU eviction to prevent unbounded entity store growth.
-     */
-    gc(): number;
 }
 
 /** Cache performance statistics. */

package/dist/index.d.ts

@@ -931,10 +931,10 @@ declare class NormalizedCache implements CacheAdapter {
     private readonly swrMs;
     private readonly queryStore;
     private readonly entityStore;
+    private readonly refCount;
     private _hits;
     private _misses;
     private _stales;
-    private gcTimeout?;
     constructor(options?: CacheOptions);
     static key(query: string, variables: Record<string, unknown>): string;
     /** Normalizes a GraphQL response, extracting entities and returning a tree of references. */
@@ -947,6 +947,7 @@ declare class NormalizedCache implements CacheAdapter {
     } | undefined;
     get<T>(key: string): T | undefined;
     set<T>(key: string, data: T): void;
+    private deleteQueryEntry;
     delete(key: string): boolean;
     clear(): void;
     get size(): number;
@@ -956,12 +957,6 @@ declare class NormalizedCache implements CacheAdapter {
         entitiesCount: number;
     };
     resetStats(): void;
-    private scheduleGc;
-    /**
-     * Garbage-collect orphaned entities that are no longer referenced by any query.
-     * Called automatically on LRU eviction to prevent unbounded entity store growth.
-     */
-    gc(): number;
 }
 
 /** Cache performance statistics. */

package/dist/index.js

@@ -117,8 +117,17 @@ function validateIds(ids, label = "id") {
 function sortObjectKeys(obj) {
   if (obj === null || typeof obj !== "object") return obj;
   if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+  const keys = Object.keys(obj);
+  if (keys.length === 0) return obj;
+  if (keys.length === 1) {
+    const key = keys[0];
+    const val = obj[key];
+    const sortedVal = sortObjectKeys(val);
+    if (val === sortedVal) return obj;
+    return { [key]: sortedVal };
+  }
   const sorted = {};
-  for (const key of Object.keys(obj).sort()) {
+  for (const key of keys.sort()) {
     sorted[key] = sortObjectKeys(obj[key]);
   }
   return sorted;
@@ -132,10 +141,10 @@ var NormalizedCache = class {
   swrMs;
   queryStore = /* @__PURE__ */ new Map();
   entityStore = /* @__PURE__ */ new Map();
+  refCount = /* @__PURE__ */ new Map();
   _hits = 0;
   _misses = 0;
   _stales = 0;
-  gcTimeout;
   constructor(options = {}) {
     this.ttl = options.ttl ?? 24 * 60 * 60 * 1e3;
     this.maxSize = options.maxSize ?? 500;
@@ -147,11 +156,11 @@ var NormalizedCache = class {
     return `${normalized}|${JSON.stringify(sortObjectKeys(variables))}`;
   }
   /** Normalizes a GraphQL response, extracting entities and returning a tree of references. */
-  normalize(data, seen = /* @__PURE__ */ new WeakSet()) {
+  normalize(data, refsOut, seen = /* @__PURE__ */ new WeakSet()) {
     if (Array.isArray(data)) {
       if (seen.has(data)) return null;
       seen.add(data);
-      return data.map((item) => this.normalize(item, seen));
+      return data.map((item) => this.normalize(item, refsOut, seen));
     }
     if (data !== null && typeof data === "object") {
       if (seen.has(data)) return null;
@@ -159,17 +168,22 @@ var NormalizedCache = class {
       const obj = data;
       if (typeof obj.__typename === "string" && (typeof obj.id === "number" || typeof obj.id === "string")) {
         const ref = `${obj.__typename}:${obj.id}`;
+        refsOut.add(ref);
         const normalizedObj = {};
-        for (const [k, v] of Object.entries(obj)) {
-          normalizedObj[k] = this.normalize(v, seen);
+        for (const k in obj) {
+          if (Object.hasOwn(obj, k)) {
+            normalizedObj[k] = this.normalize(obj[k], refsOut, seen);
+          }
         }
         const existing = this.entityStore.get(ref) || {};
         this.entityStore.set(ref, { ...existing, ...normalizedObj });
         return { __ref: ref };
       }
       const result = {};
-      for (const [k, v] of Object.entries(obj)) {
-        result[k] = this.normalize(v, seen);
+      for (const k in obj) {
+        if (Object.hasOwn(obj, k)) {
+          result[k] = this.normalize(obj[k], refsOut, seen);
+        }
       }
       return result;
     }
@@ -195,10 +209,12 @@ var NormalizedCache = class {
         return result2;
       }
       const result = {};
-      for (const [k, v] of Object.entries(obj)) {
-        const denormalized = this.denormalize(v, seen);
-        if (denormalized === void 0) return void 0;
-        result[k] = denormalized;
+      for (const k in obj) {
+        if (Object.hasOwn(obj, k)) {
+          const denormalized = this.denormalize(obj[k], seen);
+          if (denormalized === void 0) return void 0;
+          result[k] = denormalized;
+        }
       }
       return result;
     }
@@ -217,14 +233,14 @@ var NormalizedCache = class {
       if (this.swrMs > 0 && now <= entry.expiresAt + this.swrMs) {
         isStale = true;
       } else {
-        this.queryStore.delete(key);
+        this.deleteQueryEntry(key, entry);
         this._misses++;
         return void 0;
       }
     }
     const denormalized = this.denormalize(entry.data);
     if (denormalized === void 0) {
-      this.queryStore.delete(key);
+      this.deleteQueryEntry(key, entry);
       this._misses++;
       return void 0;
     }
@@ -243,27 +259,46 @@ var NormalizedCache = class {
   }
   set(key, data) {
     if (!this.enabled) return;
-    const normalizedData = this.normalize(data);
-    this.queryStore.delete(key);
+    const refs = /* @__PURE__ */ new Set();
+    const normalizedData = this.normalize(data, refs);
+    const existing = this.queryStore.get(key);
+    if (existing) {
+      this.deleteQueryEntry(key, existing);
+    }
     if (this.maxSize > 0 && this.queryStore.size >= this.maxSize) {
       const firstKey = this.queryStore.keys().next().value;
       if (firstKey !== void 0) {
-        this.queryStore.delete(firstKey);
+        const firstEntry = this.queryStore.get(firstKey);
+        if (firstEntry) this.deleteQueryEntry(firstKey, firstEntry);
+      }
+    }
+    for (const ref of refs) {
+      this.refCount.set(ref, (this.refCount.get(ref) ?? 0) + 1);
+    }
+    this.queryStore.set(key, { data: normalizedData, refs, expiresAt: Date.now() + this.ttl });
+  }
+  deleteQueryEntry(key, entry) {
+    this.queryStore.delete(key);
+    for (const ref of entry.refs) {
+      const count = (this.refCount.get(ref) ?? 0) - 1;
+      if (count <= 0) {
+        this.refCount.delete(ref);
+        this.entityStore.delete(ref);
+      } else {
+        this.refCount.set(ref, count);
       }
-      this.scheduleGc();
     }
-    this.queryStore.set(key, { data: normalizedData, expiresAt: Date.now() + this.ttl });
   }
   delete(key) {
-    return this.queryStore.delete(key);
+    const entry = this.queryStore.get(key);
+    if (!entry) return false;
+    this.deleteQueryEntry(key, entry);
+    return true;
   }
   clear() {
-    if (this.gcTimeout) {
-      clearTimeout(this.gcTimeout);
-      this.gcTimeout = void 0;
-    }
     this.queryStore.clear();
     this.entityStore.clear();
+    this.refCount.clear();
     this._hits = 0;
     this._misses = 0;
     this._stales = 0;
@@ -280,7 +315,9 @@ var NormalizedCache = class {
     for (const key of this.queryStore.keys()) {
       if (test(key)) toDelete.push(key);
     }
-    for (const key of toDelete) this.queryStore.delete(key);
+    for (const key of toDelete) {
+      this.delete(key);
+    }
     return toDelete.length;
   }
   get stats() {
@@ -298,53 +335,6 @@ var NormalizedCache = class {
     this._misses = 0;
     this._stales = 0;
   }
-  scheduleGc() {
-    if (this.gcTimeout) return;
-    this.gcTimeout = setTimeout(() => {
-      this.gc();
-      this.gcTimeout = void 0;
-    }, 500);
-    if (typeof this.gcTimeout.unref === "function") {
-      this.gcTimeout.unref();
-    }
-  }
-  /**
-   * Garbage-collect orphaned entities that are no longer referenced by any query.
-   * Called automatically on LRU eviction to prevent unbounded entity store growth.
-   */
-  gc() {
-    const referencedRefs = /* @__PURE__ */ new Set();
-    const collectRefs = (data) => {
-      if (Array.isArray(data)) {
-        for (const item of data) collectRefs(item);
-        return;
-      }
-      if (data !== null && typeof data === "object") {
-        const obj = data;
-        if (typeof obj.__ref === "string") {
-          referencedRefs.add(obj.__ref);
-          const entity = this.entityStore.get(obj.__ref);
-          if (entity && !referencedRefs.has(`_visited:${obj.__ref}`)) {
-            referencedRefs.add(`_visited:${obj.__ref}`);
-            collectRefs(entity);
-          }
-          return;
-        }
-        for (const v of Object.values(obj)) collectRefs(v);
-      }
-    };
-    for (const entry of this.queryStore.values()) {
-      collectRefs(entry.data);
-    }
-    let removed = 0;
-    for (const ref of this.entityStore.keys()) {
-      if (!referencedRefs.has(ref)) {
-        this.entityStore.delete(ref);
-        removed++;
-      }
-    }
-    return removed;
-  }
 };
 
 // src/cache/index.ts
@@ -2541,7 +2531,7 @@ function mapFavorites(fav) {
 
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
-var LIB_VERSION = "2.2.1" ;
+var LIB_VERSION = "2.3.0" ;
 var AniListClient = class {
   apiUrl;
   headers;