ani-client 2.1.1 → 2.1.3

package/README.md

@@ -236,7 +236,13 @@ Full API reference, configuration options, and guides (caching, pagination, hook
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and PR guidelines.
+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.
 
 ## License
 

package/dist/cache/redis.d.mts

@@ -0,0 +1 @@
+export { f as RedisCache, g as RedisCacheOptions, h as RedisLikeClient } from '../redis-AFbnh0Xa.mjs';

package/dist/cache/redis.d.ts

@@ -0,0 +1 @@
+export { f as RedisCache, g as RedisCacheOptions, h as RedisLikeClient } from '../redis-AFbnh0Xa.js';

package/dist/cache/redis.js

@@ -0,0 +1,94 @@
+'use strict';
+
+// src/cache/redis.ts
+var RedisCache = class {
+  client;
+  prefix;
+  ttl;
+  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;
+  }
+  /**
+   * 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
+   */
+  async collectKeys(pattern) {
+    if (this.client.scanIterator) {
+      const keys = [];
+      for await (const key of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {
+        keys.push(key);
+      }
+      return keys;
+    }
+    return this.client.keys(pattern);
+  }
+  async clear() {
+    const keys = await this.collectKeys(`${this.prefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+  /**
+   * Get the actual number of keys with this prefix in Redis.
+   */
+  get size() {
+    return this.getSize();
+  }
+  /** @internal */
+  async getSize() {
+    const keys = await this.collectKeys(`${this.prefix}*`);
+    return keys.length;
+  }
+  async keys() {
+    const raw = await this.collectKeys(`${this.prefix}*`);
+    return raw.map((k) => k.slice(this.prefix.length));
+  }
+  /**
+   * 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.
+   */
+  async invalidate(pattern) {
+    if (typeof pattern === "string") {
+      const keys = await this.collectKeys(`${this.prefix}*${pattern}*`);
+      if (keys.length === 0) return 0;
+      return this.client.del(...keys);
+    }
+    const allKeys = await this.collectKeys(`${this.prefix}*`);
+    const matching = allKeys.filter((k) => pattern.test(k.slice(this.prefix.length)));
+    if (matching.length === 0) return 0;
+    return this.client.del(...matching);
+  }
+};
+
+exports.RedisCache = RedisCache;
+//# sourceMappingURL=redis.js.map
+//# sourceMappingURL=redis.js.map

package/dist/cache/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cache/redis.ts"],"names":[],"mappings":"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","file":"redis.js","sourcesContent":["import type { CacheAdapter } from \"../types\";\n\n/**\n * Minimal interface representing a Redis client.\n * Compatible with both `ioredis` and `redis` (node-redis v4+).\n */\nexport interface RedisLikeClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(...keys: (string | string[])[]): Promise<number>;\n  keys(pattern: string): Promise<string[]>;\n  /** Optional SCAN-based iteration — used when available to avoid blocking the server. */\n  scanIterator?(options: { MATCH: string; COUNT?: number }): AsyncIterable<string>;\n}\n\nexport interface RedisCacheOptions {\n  /** A Redis client instance (ioredis or node-redis). */\n  client: RedisLikeClient;\n  /** Key prefix to namespace ani-client entries (default: `\"ani:\"`) */\n  prefix?: string;\n  /** TTL in seconds (default: 86 400 = 24 h) */\n  ttl?: number;\n}\n\n/**\n * Redis-backed cache adapter for AniListClient.\n *\n * @example\n * ```ts\n * import Redis from \"ioredis\";\n * import { AniListClient, RedisCache } from \"ani-client\";\n *\n * const redis = new Redis();\n * const client = new AniListClient({\n *   cacheAdapter: new RedisCache({ client: redis }),\n * });\n * ```\n */\nexport class RedisCache implements CacheAdapter {\n  private readonly client: RedisLikeClient;\n  private readonly prefix: string;\n  private readonly ttl: number;\n\n  constructor(options: RedisCacheOptions) {\n    this.client = options.client;\n    this.prefix = options.prefix ?? \"ani:\";\n    this.ttl = options.ttl ?? 86_400;\n  }\n\n  private prefixedKey(key: string): string {\n    return `${this.prefix}${key}`;\n  }\n\n  async get<T>(key: string): Promise<T | undefined> {\n    const raw = await this.client.get(this.prefixedKey(key));\n    if (raw === null) return undefined;\n    try {\n      return JSON.parse(raw) as T;\n    } catch {\n      return undefined;\n    }\n  }\n\n  async set<T>(key: string, data: T): Promise<void> {\n    await this.client.set(this.prefixedKey(key), JSON.stringify(data), \"EX\", this.ttl);\n  }\n\n  async delete(key: string): Promise<boolean> {\n    const count = await this.client.del(this.prefixedKey(key));\n    return count > 0;\n  }\n\n  /**\n   * Collect keys matching a pattern. Uses SCAN when available, falls back to KEYS.\n   *\n   * **Warning:** The `KEYS` fallback is O(N) and blocks the Redis server.\n   * Provide a client with `scanIterator` support for production use.\n   * @internal\n   */\n  private async collectKeys(pattern: string): Promise<string[]> {\n    if (this.client.scanIterator) {\n      const keys: string[] = [];\n      for await (const key of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {\n        keys.push(key);\n      }\n      return keys;\n    }\n    return this.client.keys(pattern);\n  }\n\n  async clear(): Promise<void> {\n    const keys = await this.collectKeys(`${this.prefix}*`);\n    if (keys.length > 0) {\n      await this.client.del(...keys);\n    }\n  }\n\n  /**\n   * Get the actual number of keys with this prefix in Redis.\n   */\n  get size(): Promise<number> {\n    return this.getSize();\n  }\n\n  /** @internal */\n  private async getSize(): Promise<number> {\n    const keys = await this.collectKeys(`${this.prefix}*`);\n    return keys.length;\n  }\n\n  async keys(): Promise<string[]> {\n    const raw = await this.collectKeys(`${this.prefix}*`);\n    return raw.map((k) => k.slice(this.prefix.length));\n  }\n\n  /**\n   * Remove all entries whose key matches the given pattern.\n   *\n   * - **String**: treated as a substring match (e.g. `\"Media\"` removes all keys containing `\"Media\"`).\n   * - **RegExp**: tested against each key directly.\n   *\n   * @param pattern — A string (substring match) or RegExp.\n   * @returns Number of entries removed.\n   */\n  async invalidate(pattern: string | RegExp): Promise<number> {\n    if (typeof pattern === \"string\") {\n      const keys = await this.collectKeys(`${this.prefix}*${pattern}*`);\n      if (keys.length === 0) return 0;\n      return this.client.del(...keys);\n    }\n\n    const allKeys = await this.collectKeys(`${this.prefix}*`);\n    const matching = allKeys.filter((k) => pattern.test(k.slice(this.prefix.length)));\n    if (matching.length === 0) return 0;\n    return this.client.del(...matching);\n  }\n}\n"]}

package/dist/cache/redis.mjs

@@ -0,0 +1,92 @@
+// src/cache/redis.ts
+var RedisCache = class {
+  client;
+  prefix;
+  ttl;
+  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;
+  }
+  /**
+   * 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
+   */
+  async collectKeys(pattern) {
+    if (this.client.scanIterator) {
+      const keys = [];
+      for await (const key of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {
+        keys.push(key);
+      }
+      return keys;
+    }
+    return this.client.keys(pattern);
+  }
+  async clear() {
+    const keys = await this.collectKeys(`${this.prefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+  /**
+   * Get the actual number of keys with this prefix in Redis.
+   */
+  get size() {
+    return this.getSize();
+  }
+  /** @internal */
+  async getSize() {
+    const keys = await this.collectKeys(`${this.prefix}*`);
+    return keys.length;
+  }
+  async keys() {
+    const raw = await this.collectKeys(`${this.prefix}*`);
+    return raw.map((k) => k.slice(this.prefix.length));
+  }
+  /**
+   * 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.
+   */
+  async invalidate(pattern) {
+    if (typeof pattern === "string") {
+      const keys = await this.collectKeys(`${this.prefix}*${pattern}*`);
+      if (keys.length === 0) return 0;
+      return this.client.del(...keys);
+    }
+    const allKeys = await this.collectKeys(`${this.prefix}*`);
+    const matching = allKeys.filter((k) => pattern.test(k.slice(this.prefix.length)));
+    if (matching.length === 0) return 0;
+    return this.client.del(...matching);
+  }
+};
+
+export { RedisCache };
+//# sourceMappingURL=redis.mjs.map
+//# sourceMappingURL=redis.mjs.map

package/dist/cache/redis.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cache/redis.ts"],"names":[],"mappings":"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","file":"redis.mjs","sourcesContent":["import type { CacheAdapter } from \"../types\";\n\n/**\n * Minimal interface representing a Redis client.\n * Compatible with both `ioredis` and `redis` (node-redis v4+).\n */\nexport interface RedisLikeClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(...keys: (string | string[])[]): Promise<number>;\n  keys(pattern: string): Promise<string[]>;\n  /** Optional SCAN-based iteration — used when available to avoid blocking the server. */\n  scanIterator?(options: { MATCH: string; COUNT?: number }): AsyncIterable<string>;\n}\n\nexport interface RedisCacheOptions {\n  /** A Redis client instance (ioredis or node-redis). */\n  client: RedisLikeClient;\n  /** Key prefix to namespace ani-client entries (default: `\"ani:\"`) */\n  prefix?: string;\n  /** TTL in seconds (default: 86 400 = 24 h) */\n  ttl?: number;\n}\n\n/**\n * Redis-backed cache adapter for AniListClient.\n *\n * @example\n * ```ts\n * import Redis from \"ioredis\";\n * import { AniListClient, RedisCache } from \"ani-client\";\n *\n * const redis = new Redis();\n * const client = new AniListClient({\n *   cacheAdapter: new RedisCache({ client: redis }),\n * });\n * ```\n */\nexport class RedisCache implements CacheAdapter {\n  private readonly client: RedisLikeClient;\n  private readonly prefix: string;\n  private readonly ttl: number;\n\n  constructor(options: RedisCacheOptions) {\n    this.client = options.client;\n    this.prefix = options.prefix ?? \"ani:\";\n    this.ttl = options.ttl ?? 86_400;\n  }\n\n  private prefixedKey(key: string): string {\n    return `${this.prefix}${key}`;\n  }\n\n  async get<T>(key: string): Promise<T | undefined> {\n    const raw = await this.client.get(this.prefixedKey(key));\n    if (raw === null) return undefined;\n    try {\n      return JSON.parse(raw) as T;\n    } catch {\n      return undefined;\n    }\n  }\n\n  async set<T>(key: string, data: T): Promise<void> {\n    await this.client.set(this.prefixedKey(key), JSON.stringify(data), \"EX\", this.ttl);\n  }\n\n  async delete(key: string): Promise<boolean> {\n    const count = await this.client.del(this.prefixedKey(key));\n    return count > 0;\n  }\n\n  /**\n   * Collect keys matching a pattern. Uses SCAN when available, falls back to KEYS.\n   *\n   * **Warning:** The `KEYS` fallback is O(N) and blocks the Redis server.\n   * Provide a client with `scanIterator` support for production use.\n   * @internal\n   */\n  private async collectKeys(pattern: string): Promise<string[]> {\n    if (this.client.scanIterator) {\n      const keys: string[] = [];\n      for await (const key of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {\n        keys.push(key);\n      }\n      return keys;\n    }\n    return this.client.keys(pattern);\n  }\n\n  async clear(): Promise<void> {\n    const keys = await this.collectKeys(`${this.prefix}*`);\n    if (keys.length > 0) {\n      await this.client.del(...keys);\n    }\n  }\n\n  /**\n   * Get the actual number of keys with this prefix in Redis.\n   */\n  get size(): Promise<number> {\n    return this.getSize();\n  }\n\n  /** @internal */\n  private async getSize(): Promise<number> {\n    const keys = await this.collectKeys(`${this.prefix}*`);\n    return keys.length;\n  }\n\n  async keys(): Promise<string[]> {\n    const raw = await this.collectKeys(`${this.prefix}*`);\n    return raw.map((k) => k.slice(this.prefix.length));\n  }\n\n  /**\n   * Remove all entries whose key matches the given pattern.\n   *\n   * - **String**: treated as a substring match (e.g. `\"Media\"` removes all keys containing `\"Media\"`).\n   * - **RegExp**: tested against each key directly.\n   *\n   * @param pattern — A string (substring match) or RegExp.\n   * @returns Number of entries removed.\n   */\n  async invalidate(pattern: string | RegExp): Promise<number> {\n    if (typeof pattern === \"string\") {\n      const keys = await this.collectKeys(`${this.prefix}*${pattern}*`);\n      if (keys.length === 0) return 0;\n      return this.client.del(...keys);\n    }\n\n    const allKeys = await this.collectKeys(`${this.prefix}*`);\n    const matching = allKeys.filter((k) => pattern.test(k.slice(this.prefix.length)));\n    if (matching.length === 0) return 0;\n    return this.client.del(...matching);\n  }\n}\n"]}

package/dist/index.d.mts

@@ -1,159 +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>;
-    /** 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.mjs';
+export { e as AniListHooks, L as Logger, f as RedisCache, g as RedisCacheOptions, h as RedisLikeClient } from './redis-AFbnh0Xa.mjs';
 
 declare enum MediaListStatus {
     CURRENT = "CURRENT",
@@ -1070,6 +916,52 @@ interface SearchThreadOptions {
     perPage?: number;
 }
 
+/**
+ * Normalized Cache Adapter for AniListClient.
+ *
+ * This cache intercepts GraphQL responses, extracts objects with `__typename` and `id`,
+ * and stores them flat in an entity store.
+ * This ensures data consistency across all queries (e.g., `getMedia(1)` and `searchMedia`
+ * share the exact same `Media` object).
+ */
+declare class NormalizedCache implements CacheAdapter {
+    private readonly ttl;
+    private readonly maxSize;
+    private readonly enabled;
+    private readonly swrMs;
+    private readonly queryStore;
+    private readonly entityStore;
+    private _hits;
+    private _misses;
+    private _stales;
+    constructor(options?: CacheOptions);
+    static key(query: string, variables: Record<string, unknown>): string;
+    /** Normalizes a GraphQL response, extracting entities and returning a tree of references. */
+    private normalize;
+    /** Reconstructs a GraphQL response from references. */
+    private denormalize;
+    getWithMeta<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, data: T): void;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): string[];
+    invalidate(pattern: string | RegExp): number;
+    get stats(): CacheStats & {
+        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. */
 interface CacheStats {
     /** Total cache hits. */
@@ -1094,10 +986,14 @@ 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.
      */
+    getWithMeta<T>(key: string): {
+        data: T;
+        stale: boolean;
+    } | undefined;
     get<T>(key: string): T | undefined;
     /** Store a value in the cache. */
     set<T>(key: string, data: T): void;
@@ -1136,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>;
 }
 
 /**
@@ -1227,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;
@@ -1299,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. */
@@ -1473,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, 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 };