ani-client 1.6.0 → 1.7.0

package/README.md

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

package/dist/index.d.mts

@@ -90,6 +90,8 @@ interface AniListHooks {
     onRetry?: (attempt: number, reason: string, delayMs: number) => void;
     /** Called when a request completes. */
     onResponse?: (query: string, durationMs: number, fromCache: boolean, rateLimitInfo?: RateLimitInfo) => void;
+    /** Called when a request fails with an error. */
+    onError?: (error: Error, query: string, variables: Record<string, unknown>) => void;
 }
 /** Rate limit information parsed from AniList API response headers. */
 interface RateLimitInfo {
@@ -223,21 +225,11 @@ interface SearchStaffOptions {
     perPage?: number;
 }
 /** Compact voice actor data returned inside character edges. */
-interface VoiceActor {
-    id: number;
-    name: {
-        first: string | null;
-        middle: string | null;
-        last: string | null;
-        full: string | null;
-        native: string | null;
+interface VoiceActor extends Pick<Staff, "id" | "image" | "gender" | "primaryOccupations" | "siteUrl"> {
+    name: StaffName & {
         userPreferred: string | null;
     };
     languageV2: string | null;
-    image: StaffImage;
-    gender: string | null;
-    primaryOccupations: string[];
-    siteUrl: string | null;
 }
 
 declare enum CharacterSort {
@@ -387,8 +379,18 @@ interface Studio {
 interface StudioConnection {
     nodes: Studio[];
 }
+declare enum StudioSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    NAME = "NAME",
+    NAME_DESC = "NAME_DESC",
+    SEARCH_MATCH = "SEARCH_MATCH",
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC"
+}
 interface SearchStudioOptions {
     query?: string;
+    sort?: StudioSort[];
     page?: number;
     perPage?: number;
 }
@@ -441,18 +443,10 @@ interface SearchUserOptions {
 }
 interface FavoriteMediaNode {
     id: number;
-    title: {
-        romaji: string | null;
-        english: string | null;
-        native: string | null;
-        userPreferred: string | null;
-    };
-    coverImage: {
-        large: string | null;
-        medium: string | null;
-    };
-    type: string | null;
-    format: string | null;
+    title: MediaTitle;
+    coverImage: Pick<MediaCoverImage, "large" | "medium">;
+    type: MediaType | null;
+    format: MediaFormat | null;
     siteUrl: string | null;
 }
 interface FavoriteCharacterNode {
@@ -656,7 +650,7 @@ interface ScoreDistribution {
     amount: number;
 }
 interface StatusDistribution {
-    status: MediaListStatus | string;
+    status: MediaListStatus;
     amount: number;
 }
 interface MediaStats {
@@ -887,17 +881,9 @@ interface ThreadCategory {
 }
 interface ThreadMediaCategory {
     id: number;
-    title: {
-        romaji: string | null;
-        english: string | null;
-        native: string | null;
-        userPreferred: string | null;
-    };
-    type: string;
-    coverImage: {
-        large: string | null;
-        medium: string | null;
-    } | null;
+    title: MediaTitle;
+    type: MediaType;
+    coverImage: Pick<MediaCoverImage, "large" | "medium"> | null;
     siteUrl: string | null;
 }
 /** Sort options for thread queries. */
@@ -1004,7 +990,15 @@ declare class AniListClient {
     getTopRated(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
     /** Get recently aired anime episodes. */
     getAiredEpisodes(options?: GetAiringOptions): Promise<PagedResult<AiringSchedule>>;
-    /** Get currently releasing manga. */
+    /**
+     * Get currently releasing manga sorted by most recently updated.
+     *
+     * @param options - Pagination parameters
+     */
+    getRecentlyUpdatedManga(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
+    /**
+     * @deprecated Use `getRecentlyUpdatedManga` instead. This alias will be removed in v2.
+     */
     getAiredChapters(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
     /** Get the detailed schedule for the current week, sorted by day. */
     getWeeklySchedule(date?: Date): Promise<WeeklySchedule>;
@@ -1077,7 +1071,7 @@ declare class AniListClient {
     /** Clear the entire response cache. */
     clearCache(): Promise<void>;
     /** Number of entries currently in the cache. */
-    get cacheSize(): number | Promise<number>;
+    cacheSize(): Promise<number>;
     /** Remove cache entries whose key matches the given pattern. */
     invalidateCache(pattern: string | RegExp): Promise<number>;
     /** Clean up resources held by the client. */
@@ -1219,6 +1213,8 @@ declare class RateLimiter {
     private readonly timestamps;
     private head;
     private count;
+    /** @internal — active sleep timers for cleanup */
+    private readonly activeTimers;
     constructor(options?: RateLimitOptions);
     /**
      * Wait until it's safe to make a request (respects rate limit window).
@@ -1237,15 +1233,10 @@ declare class RateLimiter {
     /** @internal */
     private fetchWithTimeout;
     private sleep;
+    /** Cancel all pending sleep timers and reset internal state. */
+    dispose(): void;
 }
 
-/**
- * Parses AniList specific markdown into standard HTML.
- * Includes formatting for spoilers, images, videos (youtube/webm), and standard markdown elements.
- *
- * @param text The AniList markdown text to parse
- * @returns The parsed HTML string
- */
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, 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 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, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, 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 Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, 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 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, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, 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, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };

package/dist/index.d.ts

@@ -90,6 +90,8 @@ interface AniListHooks {
     onRetry?: (attempt: number, reason: string, delayMs: number) => void;
     /** Called when a request completes. */
     onResponse?: (query: string, durationMs: number, fromCache: boolean, rateLimitInfo?: RateLimitInfo) => void;
+    /** Called when a request fails with an error. */
+    onError?: (error: Error, query: string, variables: Record<string, unknown>) => void;
 }
 /** Rate limit information parsed from AniList API response headers. */
 interface RateLimitInfo {
@@ -223,21 +225,11 @@ interface SearchStaffOptions {
     perPage?: number;
 }
 /** Compact voice actor data returned inside character edges. */
-interface VoiceActor {
-    id: number;
-    name: {
-        first: string | null;
-        middle: string | null;
-        last: string | null;
-        full: string | null;
-        native: string | null;
+interface VoiceActor extends Pick<Staff, "id" | "image" | "gender" | "primaryOccupations" | "siteUrl"> {
+    name: StaffName & {
         userPreferred: string | null;
     };
     languageV2: string | null;
-    image: StaffImage;
-    gender: string | null;
-    primaryOccupations: string[];
-    siteUrl: string | null;
 }
 
 declare enum CharacterSort {
@@ -387,8 +379,18 @@ interface Studio {
 interface StudioConnection {
     nodes: Studio[];
 }
+declare enum StudioSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    NAME = "NAME",
+    NAME_DESC = "NAME_DESC",
+    SEARCH_MATCH = "SEARCH_MATCH",
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC"
+}
 interface SearchStudioOptions {
     query?: string;
+    sort?: StudioSort[];
     page?: number;
     perPage?: number;
 }
@@ -441,18 +443,10 @@ interface SearchUserOptions {
 }
 interface FavoriteMediaNode {
     id: number;
-    title: {
-        romaji: string | null;
-        english: string | null;
-        native: string | null;
-        userPreferred: string | null;
-    };
-    coverImage: {
-        large: string | null;
-        medium: string | null;
-    };
-    type: string | null;
-    format: string | null;
+    title: MediaTitle;
+    coverImage: Pick<MediaCoverImage, "large" | "medium">;
+    type: MediaType | null;
+    format: MediaFormat | null;
     siteUrl: string | null;
 }
 interface FavoriteCharacterNode {
@@ -656,7 +650,7 @@ interface ScoreDistribution {
     amount: number;
 }
 interface StatusDistribution {
-    status: MediaListStatus | string;
+    status: MediaListStatus;
     amount: number;
 }
 interface MediaStats {
@@ -887,17 +881,9 @@ interface ThreadCategory {
 }
 interface ThreadMediaCategory {
     id: number;
-    title: {
-        romaji: string | null;
-        english: string | null;
-        native: string | null;
-        userPreferred: string | null;
-    };
-    type: string;
-    coverImage: {
-        large: string | null;
-        medium: string | null;
-    } | null;
+    title: MediaTitle;
+    type: MediaType;
+    coverImage: Pick<MediaCoverImage, "large" | "medium"> | null;
     siteUrl: string | null;
 }
 /** Sort options for thread queries. */
@@ -1004,7 +990,15 @@ declare class AniListClient {
     getTopRated(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
     /** Get recently aired anime episodes. */
     getAiredEpisodes(options?: GetAiringOptions): Promise<PagedResult<AiringSchedule>>;
-    /** Get currently releasing manga. */
+    /**
+     * Get currently releasing manga sorted by most recently updated.
+     *
+     * @param options - Pagination parameters
+     */
+    getRecentlyUpdatedManga(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
+    /**
+     * @deprecated Use `getRecentlyUpdatedManga` instead. This alias will be removed in v2.
+     */
     getAiredChapters(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
     /** Get the detailed schedule for the current week, sorted by day. */
     getWeeklySchedule(date?: Date): Promise<WeeklySchedule>;
@@ -1077,7 +1071,7 @@ declare class AniListClient {
     /** Clear the entire response cache. */
     clearCache(): Promise<void>;
     /** Number of entries currently in the cache. */
-    get cacheSize(): number | Promise<number>;
+    cacheSize(): Promise<number>;
     /** Remove cache entries whose key matches the given pattern. */
     invalidateCache(pattern: string | RegExp): Promise<number>;
     /** Clean up resources held by the client. */
@@ -1219,6 +1213,8 @@ declare class RateLimiter {
     private readonly timestamps;
     private head;
     private count;
+    /** @internal — active sleep timers for cleanup */
+    private readonly activeTimers;
     constructor(options?: RateLimitOptions);
     /**
      * Wait until it's safe to make a request (respects rate limit window).
@@ -1237,15 +1233,10 @@ declare class RateLimiter {
     /** @internal */
     private fetchWithTimeout;
     private sleep;
+    /** Cancel all pending sleep timers and reset internal state. */
+    dispose(): void;
 }
 
-/**
- * Parses AniList specific markdown into standard HTML.
- * Includes formatting for spoilers, images, videos (youtube/webm), and standard markdown elements.
- *
- * @param text The AniList markdown text to parse
- * @returns The parsed HTML string
- */
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, 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 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, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, 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 Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, 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 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, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, 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, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };