ani-client 2.1.2 → 2.1.3

package/dist/index.d.ts

@@ -1,170 +1,5 @@
-interface PageInfo {
-    total: number | null;
-    perPage: number;
-    currentPage: number;
-    lastPage: number;
-    hasNextPage: boolean;
-}
-interface PagedResult<T> {
-    pageInfo: PageInfo;
-    results: T[];
-}
-interface FuzzyDate {
-    year: number | null;
-    month: number | null;
-    day: number | null;
-}
-interface ExternalLink {
-    id: number;
-    url: string | null;
-    site: string;
-    type: string | null;
-    icon: string | null;
-    color: string | null;
-}
-/**
- * Interface that all cache adapters must implement.
- * Methods may return sync values or Promises — the client awaits all calls.
- */
-interface CacheAdapter {
-    /** Retrieve a cached value, or `undefined` if missing / expired. */
-    get<T>(key: string): T | undefined | Promise<T | undefined>;
-    /**
-     * Retrieve a cached value along with its stale status (for stale-while-revalidate).
-     * If implemented, the client will use this to trigger background revalidation.
-     */
-    getWithMeta?<T>(key: string): {
-        data: T;
-        stale: boolean;
-    } | undefined | Promise<{
-        data: T;
-        stale: boolean;
-    } | undefined>;
-    /** Store a value in the cache. */
-    set<T>(key: string, data: T): void | Promise<void>;
-    /** Remove a specific entry. Returns `true` if the key existed. */
-    delete(key: string): boolean | Promise<boolean>;
-    /** Clear the entire cache. */
-    clear(): void | Promise<void>;
-    /** Number of entries currently stored. */
-    readonly size: number | Promise<number>;
-    /** Return all cache keys. */
-    keys(): string[] | Promise<string[]>;
-    /** Bulk-remove entries matching a pattern. Optional — the client provides a fallback. */
-    invalidate?(pattern: string | RegExp): number | Promise<number>;
-}
-/** Cache configuration options. */
-interface CacheOptions {
-    /** Time-to-live in milliseconds (default: 86 400 000 = 24h) */
-    ttl?: number;
-    /** Maximum number of cached entries (default: 500, 0 = unlimited) */
-    maxSize?: number;
-    /** Set to false to disable caching entirely */
-    enabled?: boolean;
-    /**
-     * Stale-while-revalidate grace period in milliseconds (default: 0 = disabled).
-     * When set, expired entries are still returned within the grace window,
-     * allowing the caller to refresh in the background.
-     */
-    staleWhileRevalidateMs?: number;
-}
-/** Rate limiter configuration options. */
-interface RateLimitOptions {
-    /** Max requests per window (default: 25) */
-    maxRequests?: number;
-    /** Window size in ms (default: 60 000) */
-    windowMs?: number;
-    /** Max retries on 429 (default: 3) */
-    maxRetries?: number;
-    /** Retry delay in ms when Retry-After header is absent (default: 2000) */
-    retryDelayMs?: number;
-    /** Set to false to disable rate limiting entirely */
-    enabled?: boolean;
-    /** Timeout per request in ms (default: 30 000). 0 = no timeout. */
-    timeoutMs?: number;
-    /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
-    retryOnNetworkError?: boolean;
-    /**
-     * Custom retry delay strategy. Receives the attempt number (0-based) and the base delay,
-     * and should return the delay in ms before retrying.
-     * When omitted, the default exponential backoff with jitter is used.
-     *
-     * @example
-     * // Linear backoff: 1s, 2s, 3s, ...
-     * retryStrategy: (attempt) => (attempt + 1) * 1000
-     */
-    retryStrategy?: (attempt: number, baseDelayMs: number) => number;
-}
-/** Event hooks for logging, debugging, and monitoring. */
-interface AniListHooks {
-    /** Called before every API request. */
-    onRequest?: (query: string, variables: Record<string, unknown>) => void;
-    /** Called when a response is served from cache. */
-    onCacheHit?: (key: string) => void;
-    /** Called when the rate limiter enforces a wait (429 received). */
-    onRateLimit?: (retryAfterMs: number) => void;
-    /** Called when a request is retried (429 or network error). */
-    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 {
-    /** Maximum number of requests allowed per window. */
-    limit: number;
-    /** Remaining requests in the current window. */
-    remaining: number;
-    /** UNIX timestamp (seconds) when the rate limit window resets. */
-    reset: number;
-}
-/** Metadata about the last request, useful for debugging and monitoring. */
-interface ResponseMeta {
-    /** Duration of the request in milliseconds. */
-    durationMs: number;
-    /** Whether the response was served from cache. */
-    fromCache: boolean;
-    /** Rate limit information from the API response headers (not present for cached responses). */
-    rateLimitInfo?: RateLimitInfo;
-}
-/**
- * Minimal logger interface for structured log output.
- * Compatible with `console`, `pino`, `winston`, etc.
- */
-interface Logger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}
-interface AniListClientOptions {
-    /** Optional AniList OAuth token for authenticated requests */
-    token?: string;
-    /** Custom API endpoint (defaults to https://graphql.anilist.co) */
-    apiUrl?: string;
-    /** Cache configuration (enabled by default, 24h TTL) */
-    cache?: CacheOptions;
-    /** Custom cache adapter (e.g. RedisCache). Takes precedence over `cache`. */
-    cacheAdapter?: CacheAdapter;
-    /** Rate limiter configuration (enabled by default, 85 req/min) */
-    rateLimit?: RateLimitOptions;
-    /** Event hooks for logging, debugging, and monitoring */
-    hooks?: AniListHooks;
-    /** Optional AbortSignal to cancel all requests made by this client */
-    signal?: AbortSignal;
-    /**
-     * Optional logger for structured log output.
-     * Accepts any object with `debug`, `info`, `warn`, `error` methods.
-     * Compatible with `console`, `pino`, `winston`, etc.
-     *
-     * @example
-     * ```ts
-     * const client = new AniListClient({ logger: console });
-     * ```
-     */
-    logger?: Logger;
-}
+import { F as FuzzyDate, P as PageInfo, E as ExternalLink, C as CacheAdapter, a as CacheOptions, b as PagedResult, A as AniListClientOptions, R as RateLimitInfo, c as ResponseMeta, d as RateLimitOptions } from './redis-AFbnh0Xa.js';
+export { e as AniListHooks, L as Logger, f as RedisCache, g as RedisCacheOptions, h as RedisLikeClient } from './redis-AFbnh0Xa.js';
 
 declare enum MediaListStatus {
     CURRENT = "CURRENT",
@@ -1120,6 +955,11 @@ declare class NormalizedCache implements CacheAdapter {
         entitiesCount: number;
     };
     resetStats(): void;
+    /**
+     * 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. */
@@ -1146,13 +986,10 @@ declare class MemoryCache implements CacheAdapter {
     /** Build a deterministic cache key from a query + variables pair. */
     static key(query: string, variables: Record<string, unknown>): string;
     /**
-     * Retrieve a cached value, or `undefined` if missing / expired.
+     * Retrieve a cached value and its stale status.
      * With stale-while-revalidate enabled, returns stale data within the grace window
      * and flags it so the caller can refresh in the background.
      */
-    /**
-     * Retrieve a cached value and its stale status.
-     */
     getWithMeta<T>(key: string): {
         data: T;
         stale: boolean;
@@ -1195,77 +1032,15 @@ declare class MemoryCache implements CacheAdapter {
 }
 
 /**
- * Minimal interface representing a Redis client.
- * Compatible with both `ioredis` and `redis` (node-redis v4+).
- */
-interface RedisLikeClient {
-    get(key: string): Promise<string | null>;
-    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
-    del(...keys: (string | string[])[]): Promise<number>;
-    keys(pattern: string): Promise<string[]>;
-    /** Optional SCAN-based iteration — used when available to avoid blocking the server. */
-    scanIterator?(options: {
-        MATCH: string;
-        COUNT?: number;
-    }): AsyncIterable<string>;
-}
-interface RedisCacheOptions {
-    /** A Redis client instance (ioredis or node-redis). */
-    client: RedisLikeClient;
-    /** Key prefix to namespace ani-client entries (default: `"ani:"`) */
-    prefix?: string;
-    /** TTL in seconds (default: 86 400 = 24 h) */
-    ttl?: number;
-}
-/**
- * Redis-backed cache adapter for AniListClient.
+ * Base interface for the client context shared by all domain method modules.
+ * Exposes only the internal request methods that domain functions need.
  *
- * @example
- * ```ts
- * import Redis from "ioredis";
- * import { AniListClient, RedisCache } from "ani-client";
- *
- * const redis = new Redis();
- * const client = new AniListClient({
- *   cacheAdapter: new RedisCache({ client: redis }),
- * });
- * ```
+ * @internal
  */
-declare class RedisCache implements CacheAdapter {
-    private readonly client;
-    private readonly prefix;
-    private readonly ttl;
-    constructor(options: RedisCacheOptions);
-    private prefixedKey;
-    get<T>(key: string): Promise<T | undefined>;
-    set<T>(key: string, data: T): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    /**
-     * 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
-     */
-    private collectKeys;
-    clear(): Promise<void>;
-    /**
-     * Get the actual number of keys with this prefix in Redis.
-     */
-    get size(): Promise<number>;
-    /** @internal */
-    private getSize;
-    keys(): Promise<string[]>;
-    /**
-     * 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.
-     */
-    invalidate(pattern: string | RegExp): Promise<number>;
+interface ClientBase {
+    request<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    pagedRequest<T>(query: string, variables: Record<string, unknown>, field: string): Promise<PagedResult<T>>;
+    paginate<T>(fetchPage: (page: number) => Promise<PagedResult<T>>, maxPages?: number): AsyncGenerator<T, void, undefined>;
 }
 
 /**
@@ -1286,7 +1061,7 @@ declare class RedisCache implements CacheAdapter {
  * });
  * ```
  */
-declare class AniListClient {
+declare class AniListClient implements ClientBase {
     private readonly apiUrl;
     private readonly headers;
     private readonly cacheAdapter;
@@ -1358,7 +1133,7 @@ declare class AniListClient {
      */
     getMediaByMalId(malId: number, type?: MediaType): Promise<Media>;
     /** Get the detailed schedule for the current week, sorted by day. */
-    getWeeklySchedule(date?: Date): Promise<WeeklySchedule>;
+    getWeeklySchedule(date?: Date, idNotIn?: number[]): Promise<WeeklySchedule>;
     /** Get upcoming (not yet released) media. */
     getPlanning(options?: GetPlanningOptions): Promise<PagedResult<Media>>;
     /** Get recommendations for a specific media. */
@@ -1532,4 +1307,4 @@ declare class RateLimiter {
 
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, NormalizedCache, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type Review, ReviewSort, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchReviewOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+export { type AiringSchedule, AiringSort, AniListClient, AniListClientOptions, AniListError, CacheAdapter, CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, NormalizedCache, PageInfo, PagedResult, RateLimitInfo, RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, ResponseMeta, type Review, ReviewSort, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchReviewOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };

package/dist/index.js

@@ -247,6 +247,7 @@ var NormalizedCache = class {
     if (this.maxSize > 0 && this.queryStore.size >= this.maxSize) {
       const firstKey = this.queryStore.keys().next().value;
       if (firstKey !== void 0) this.queryStore.delete(firstKey);
+      this.gc();
     }
     this.queryStore.set(key, { data: normalizedData, expiresAt: Date.now() + this.ttl });
   }
@@ -290,6 +291,43 @@ var NormalizedCache = class {
     this._misses = 0;
     this._stales = 0;
   }
+  /**
+   * 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
@@ -315,13 +353,10 @@ var MemoryCache = class {
     return `${normalized}|${JSON.stringify(sortObjectKeys(variables))}`;
   }
   /**
-   * Retrieve a cached value, or `undefined` if missing / expired.
+   * Retrieve a cached value and its stale status.
    * With stale-while-revalidate enabled, returns stale data within the grace window
    * and flags it so the caller can refresh in the background.
    */
-  /**
-   * Retrieve a cached value and its stale status.
-   */
   getWithMeta(key) {
     if (!this.enabled) return void 0;
     const entry = this.store.get(key);
@@ -2190,7 +2225,11 @@ async function getReview(client, id) {
 }
 async function searchReviews(client, options = {}) {
   const { mediaId, userId, sort, page = 1, perPage = 20 } = options;
-  return client.pagedRequest(QUERY_REVIEWS, { mediaId, userId, sort, page, perPage }, "reviews");
+  return client.pagedRequest(
+    QUERY_REVIEWS,
+    { mediaId, userId, sort, page, perPage: clampPerPage(perPage) },
+    "reviews"
+  );
 }
 
 // src/client/staff.ts
@@ -2324,7 +2363,7 @@ function mapFavorites(fav) {
 
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
-var LIB_VERSION = "2.1.2" ;
+var LIB_VERSION = "2.1.3" ;
 var AniListClient = class {
   apiUrl;
   headers;
@@ -2537,8 +2576,8 @@ var AniListClient = class {
     return getMediaByMalId(this, malId, type);
   }
   /** Get the detailed schedule for the current week, sorted by day. */
-  async getWeeklySchedule(date) {
-    return getWeeklySchedule(this, date);
+  async getWeeklySchedule(date, idNotIn) {
+    return getWeeklySchedule(this, date, idNotIn);
   }
   /** Get upcoming (not yet released) media. */
   async getPlanning(options = {}) {