ani-client 1.2.0 → 1.3.0

package/dist/index.d.mts

@@ -283,10 +283,6 @@ interface SearchStaffOptions {
     page?: number;
     perPage?: number;
 }
-interface PaginatedOptions {
-    page?: number;
-    perPage?: number;
-}
 interface PagedResult<T> {
     pageInfo: PageInfo;
     results: T[];
@@ -439,6 +435,39 @@ interface SearchStudioOptions {
     page?: number;
     perPage?: number;
 }
+/**
+ * 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 (sync). Returns -1 if unknown. */
+    readonly size: number;
+    /** Return all cache keys. */
+    keys(): IterableIterator<string> | string[] | Promise<string[]>;
+    /** Bulk-remove entries matching a pattern. Optional — the client provides a fallback. */
+    invalidate?(pattern: string | RegExp): number | Promise<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) => void;
+}
 interface AniListClientOptions {
     /** Optional AniList OAuth token for authenticated requests */
     token?: string;
@@ -453,6 +482,8 @@ interface AniListClientOptions {
         /** Set to false to disable caching entirely */
         enabled?: boolean;
     };
+    /** Custom cache adapter (e.g. RedisCache). Takes precedence over `cache`. */
+    cacheAdapter?: CacheAdapter;
     /** Rate limiter configuration (enabled by default, 85 req/min) */
     rateLimit?: {
         /** Max requests per window (default: 85) */
@@ -465,7 +496,13 @@ interface AniListClientOptions {
         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;
     };
+    /** Event hooks for logging, debugging, and monitoring */
+    hooks?: AniListHooks;
 }
 
 /**
@@ -489,13 +526,22 @@ interface AniListClientOptions {
 declare class AniListClient {
     private readonly apiUrl;
     private readonly headers;
-    private readonly cache;
+    private readonly cacheAdapter;
     private readonly rateLimiter;
+    private readonly hooks;
+    private readonly inFlight;
     constructor(options?: AniListClientOptions);
     /**
      * @internal
      */
     private request;
+    /** @internal */
+    private executeRequest;
+    /**
+     * @internal
+     * Shorthand for paginated queries that follow the `Page { pageInfo, <field>[] }` pattern.
+     */
+    private pagedRequest;
     /**
      * Fetch a single media entry by its AniList ID.
      *
@@ -729,14 +775,48 @@ declare class AniListClient {
      * ```
      */
     paginate<T>(fetchPage: (page: number) => Promise<PagedResult<T>>, maxPages?: number): AsyncGenerator<T, void, undefined>;
+    /**
+     * 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)
+     */
+    getMediaBatch(ids: number[]): Promise<Media[]>;
+    /**
+     * 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)
+     */
+    getCharacterBatch(ids: number[]): Promise<Character[]>;
+    /**
+     * 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)
+     */
+    getStaffBatch(ids: number[]): Promise<Staff[]>;
+    /** @internal */
+    private executeBatch;
+    /** @internal */
+    private chunk;
     /**
      * Clear the entire response cache.
      */
-    clearCache(): void;
+    clearCache(): Promise<void>;
     /**
-     * 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(): number;
+    /**
+     * Remove cache entries whose key matches the given pattern.
+     *
+     * @param pattern — A string (converted to RegExp) or RegExp
+     * @returns Number of entries removed
+     */
+    invalidateCache(pattern: string | RegExp): Promise<number>;
 }
 
 /**
@@ -762,7 +842,7 @@ interface CacheOptions {
     /** Disable caching entirely (default: false) */
     enabled?: boolean;
 }
-declare class MemoryCache {
+declare class MemoryCache implements CacheAdapter {
     private readonly ttl;
     private readonly maxSize;
     private readonly enabled;
@@ -780,6 +860,74 @@ declare class MemoryCache {
     clear(): void;
     /** Number of entries currently stored. */
     get size(): number;
+    /** Return an iterator over all cache keys. */
+    keys(): IterableIterator<string>;
+    /**
+     * 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: string | RegExp): number;
+}
+
+/**
+ * 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[]>;
+}
+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.
+ *
+ * @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 }),
+ * });
+ * ```
+ */
+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>;
+    clear(): Promise<void>;
+    /**
+     * Returns -1 because Redis keys can expire silently via TTL.
+     * Use `getSize()` for an accurate count.
+     */
+    get size(): number;
+    /** Get the actual number of keys with this prefix in Redis. */
+    getSize(): Promise<number>;
+    keys(): Promise<string[]>;
+    /**
+     * Remove all entries whose key matches the given glob pattern.
+     *
+     * @param pattern — A glob pattern (e.g. `"*Media*"`)
+     * @returns Number of entries removed.
+     */
+    invalidate(pattern: string): Promise<number>;
 }
 
 /**
@@ -800,6 +948,10 @@ interface RateLimitOptions {
     retryDelayMs?: number;
     /** Disable rate limiting entirely (default: false) */
     enabled?: boolean;
+    /** Timeout per request in milliseconds (default: 30 000). 0 = no timeout. */
+    timeoutMs?: number;
+    /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
+    retryOnNetworkError?: boolean;
 }
 declare class RateLimiter {
     private readonly maxRequests;
@@ -807,6 +959,8 @@ declare class RateLimiter {
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly enabled;
+    private readonly timeoutMs;
+    private readonly retryOnNetworkError;
     /** @internal */
     private timestamps;
     constructor(options?: RateLimitOptions);
@@ -815,10 +969,15 @@ declare class RateLimiter {
      */
     acquire(): Promise<void>;
     /**
-     * Execute a fetch with automatic retry on 429 responses.
+     * Execute a fetch with automatic retry on 429 responses and network errors.
      */
-    fetchWithRetry(url: string, init: RequestInit): Promise<Response>;
+    fetchWithRetry(url: string, init: RequestInit, hooks?: {
+        onRetry?: (attempt: number, reason: string, delayMs: number) => void;
+        onRateLimit?: (retryAfterMs: number) => void;
+    }): Promise<Response>;
+    /** @internal */
+    private fetchWithTimeout;
     private sleep;
 }
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterSort, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaListEntry, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type PaginatedOptions, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterSort, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaListEntry, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };

package/dist/index.d.ts

@@ -283,10 +283,6 @@ interface SearchStaffOptions {
     page?: number;
     perPage?: number;
 }
-interface PaginatedOptions {
-    page?: number;
-    perPage?: number;
-}
 interface PagedResult<T> {
     pageInfo: PageInfo;
     results: T[];
@@ -439,6 +435,39 @@ interface SearchStudioOptions {
     page?: number;
     perPage?: number;
 }
+/**
+ * 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 (sync). Returns -1 if unknown. */
+    readonly size: number;
+    /** Return all cache keys. */
+    keys(): IterableIterator<string> | string[] | Promise<string[]>;
+    /** Bulk-remove entries matching a pattern. Optional — the client provides a fallback. */
+    invalidate?(pattern: string | RegExp): number | Promise<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) => void;
+}
 interface AniListClientOptions {
     /** Optional AniList OAuth token for authenticated requests */
     token?: string;
@@ -453,6 +482,8 @@ interface AniListClientOptions {
         /** Set to false to disable caching entirely */
         enabled?: boolean;
     };
+    /** Custom cache adapter (e.g. RedisCache). Takes precedence over `cache`. */
+    cacheAdapter?: CacheAdapter;
     /** Rate limiter configuration (enabled by default, 85 req/min) */
     rateLimit?: {
         /** Max requests per window (default: 85) */
@@ -465,7 +496,13 @@ interface AniListClientOptions {
         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;
     };
+    /** Event hooks for logging, debugging, and monitoring */
+    hooks?: AniListHooks;
 }
 
 /**
@@ -489,13 +526,22 @@ interface AniListClientOptions {
 declare class AniListClient {
     private readonly apiUrl;
     private readonly headers;
-    private readonly cache;
+    private readonly cacheAdapter;
     private readonly rateLimiter;
+    private readonly hooks;
+    private readonly inFlight;
     constructor(options?: AniListClientOptions);
     /**
      * @internal
      */
     private request;
+    /** @internal */
+    private executeRequest;
+    /**
+     * @internal
+     * Shorthand for paginated queries that follow the `Page { pageInfo, <field>[] }` pattern.
+     */
+    private pagedRequest;
     /**
      * Fetch a single media entry by its AniList ID.
      *
@@ -729,14 +775,48 @@ declare class AniListClient {
      * ```
      */
     paginate<T>(fetchPage: (page: number) => Promise<PagedResult<T>>, maxPages?: number): AsyncGenerator<T, void, undefined>;
+    /**
+     * 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)
+     */
+    getMediaBatch(ids: number[]): Promise<Media[]>;
+    /**
+     * 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)
+     */
+    getCharacterBatch(ids: number[]): Promise<Character[]>;
+    /**
+     * 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)
+     */
+    getStaffBatch(ids: number[]): Promise<Staff[]>;
+    /** @internal */
+    private executeBatch;
+    /** @internal */
+    private chunk;
     /**
      * Clear the entire response cache.
      */
-    clearCache(): void;
+    clearCache(): Promise<void>;
     /**
-     * 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(): number;
+    /**
+     * Remove cache entries whose key matches the given pattern.
+     *
+     * @param pattern — A string (converted to RegExp) or RegExp
+     * @returns Number of entries removed
+     */
+    invalidateCache(pattern: string | RegExp): Promise<number>;
 }
 
 /**
@@ -762,7 +842,7 @@ interface CacheOptions {
     /** Disable caching entirely (default: false) */
     enabled?: boolean;
 }
-declare class MemoryCache {
+declare class MemoryCache implements CacheAdapter {
     private readonly ttl;
     private readonly maxSize;
     private readonly enabled;
@@ -780,6 +860,74 @@ declare class MemoryCache {
     clear(): void;
     /** Number of entries currently stored. */
     get size(): number;
+    /** Return an iterator over all cache keys. */
+    keys(): IterableIterator<string>;
+    /**
+     * 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: string | RegExp): number;
+}
+
+/**
+ * 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[]>;
+}
+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.
+ *
+ * @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 }),
+ * });
+ * ```
+ */
+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>;
+    clear(): Promise<void>;
+    /**
+     * Returns -1 because Redis keys can expire silently via TTL.
+     * Use `getSize()` for an accurate count.
+     */
+    get size(): number;
+    /** Get the actual number of keys with this prefix in Redis. */
+    getSize(): Promise<number>;
+    keys(): Promise<string[]>;
+    /**
+     * Remove all entries whose key matches the given glob pattern.
+     *
+     * @param pattern — A glob pattern (e.g. `"*Media*"`)
+     * @returns Number of entries removed.
+     */
+    invalidate(pattern: string): Promise<number>;
 }
 
 /**
@@ -800,6 +948,10 @@ interface RateLimitOptions {
     retryDelayMs?: number;
     /** Disable rate limiting entirely (default: false) */
     enabled?: boolean;
+    /** Timeout per request in milliseconds (default: 30 000). 0 = no timeout. */
+    timeoutMs?: number;
+    /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
+    retryOnNetworkError?: boolean;
 }
 declare class RateLimiter {
     private readonly maxRequests;
@@ -807,6 +959,8 @@ declare class RateLimiter {
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly enabled;
+    private readonly timeoutMs;
+    private readonly retryOnNetworkError;
     /** @internal */
     private timestamps;
     constructor(options?: RateLimitOptions);
@@ -815,10 +969,15 @@ declare class RateLimiter {
      */
     acquire(): Promise<void>;
     /**
-     * Execute a fetch with automatic retry on 429 responses.
+     * Execute a fetch with automatic retry on 429 responses and network errors.
      */
-    fetchWithRetry(url: string, init: RequestInit): Promise<Response>;
+    fetchWithRetry(url: string, init: RequestInit, hooks?: {
+        onRetry?: (attempt: number, reason: string, delayMs: number) => void;
+        onRateLimit?: (retryAfterMs: number) => void;
+    }): Promise<Response>;
+    /** @internal */
+    private fetchWithTimeout;
     private sleep;
 }
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterSort, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaListEntry, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type PaginatedOptions, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterSort, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaListEntry, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };