mirror of
https://github.com/Shineii86/AniKotoAPI.git
synced 2026-10-22 10:55:10 +00:00
v1.5.0: Complete documentation rewrite - 50+ files with AlisaReactionBot style
- Box-style header comments (Project, Author, License) on every file - Section headers using double-line box decorators - Feature markers (// ---- FEATURE: XYZ ----) before every major function - JSDoc comments for EVERY function with @param, @returns, @example - Inline notes (NOTE, WARNING, TIP) for non-obvious logic - Footer END markers on every module - Matched code style to AlisaReactionBot repository - All files now searchable by feature name via grep Author: Shinei Nouzen <157171073+Shineii86@users.noreply.github.com>
This commit is contained in:
Sʜɪɴᴇɪ Nᴏᴜᴢᴇɴ
@@ -1,6 +1,65 @@
|
||||
/*
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
* AniKatoAPI — cache.helper.js
|
||||
* Repository: https://github.com/Shineii86/AniKatoAPI
|
||||
*
|
||||
* @description
|
||||
* In-memory caching utility for storing and retrieving API responses.
|
||||
* Implements TTL-based cache invalidation to prevent stale data
|
||||
* while reducing unnecessary requests to the source site.
|
||||
*
|
||||
* @exports
|
||||
* getCache, setCache, clearCache
|
||||
*
|
||||
* @author Shinei Nouzen
|
||||
* @license MIT
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
*/
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// CACHE STORAGE & CONFIGURATION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: In-memory Map-based cache storage ----
|
||||
/**
|
||||
* Internal cache storage using JavaScript Map object.
|
||||
* Stores data with timestamps for TTL-based expiration.
|
||||
*
|
||||
* @type {Map<string, {data: any, timestamp: number}>}
|
||||
*/
|
||||
const cache = new Map();
|
||||
|
||||
// ---- FEATURE: Cache time-to-live configuration (5 minutes) ----
|
||||
/**
|
||||
* Cache TTL (Time-To-Live) in milliseconds.
|
||||
* Default: 5 minutes (300,000 ms).
|
||||
* After this duration, cached items are considered stale
|
||||
* and will be removed on next access.
|
||||
*
|
||||
* @type {number}
|
||||
* @default 300000
|
||||
*/
|
||||
const CACHE_TTL = 5 * 60 * 1000;
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// CACHE OPERATIONS
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Retrieve cached data by key with TTL validation ----
|
||||
/**
|
||||
* Retrieves data from cache if it exists and hasn't expired.
|
||||
* Automatically removes stale entries on access.
|
||||
*
|
||||
* @param {string} key - The cache key to lookup
|
||||
* @returns {any|null} Cached data if valid, null if expired or missing
|
||||
*
|
||||
* @example
|
||||
* // Get cached anime list
|
||||
* const data = getCache("anime-list-action");
|
||||
* if (data) {
|
||||
* // Use cached data
|
||||
* }
|
||||
*/
|
||||
const getCache = (key) => {
|
||||
const item = cache.get(key);
|
||||
if (item && Date.now() - item.timestamp < CACHE_TTL) {
|
||||
@@ -10,12 +69,39 @@ const getCache = (key) => {
|
||||
return null;
|
||||
};
|
||||
|
||||
// ---- FEATURE: Store data in cache with current timestamp ----
|
||||
/**
|
||||
* Stores data in cache with current timestamp for TTL tracking.
|
||||
* Overwrites any existing data for the same key.
|
||||
*
|
||||
* @param {string} key - The cache key to store under
|
||||
* @param {any} data - The data to cache (any serializable type)
|
||||
* @returns {void}
|
||||
*
|
||||
* @example
|
||||
* // Cache anime search results
|
||||
* setCache("search-one-piece", animeResults);
|
||||
*/
|
||||
const setCache = (key, data) => {
|
||||
cache.set(key, { data, timestamp: Date.now() });
|
||||
};
|
||||
|
||||
// ---- FEATURE: Clear all cached entries from memory ----
|
||||
/**
|
||||
* Clears all entries from the cache. Use when:
|
||||
* - Memory cleanup is needed
|
||||
* - Force-refreshing all data
|
||||
* - Application restart/reset
|
||||
*
|
||||
* @returns {void}
|
||||
*
|
||||
* @example
|
||||
* // Force refresh all cached data
|
||||
* clearCache();
|
||||
*/
|
||||
const clearCache = () => {
|
||||
cache.clear();
|
||||
};
|
||||
|
||||
export { getCache, setCache, clearCache };
|
||||
export { getCache, setCache, clearCache };
|
||||
// ══════════════════════════════════════════════════════════════ END: cache.helper.js
|
||||
@@ -1,3 +1,44 @@
|
||||
/*
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
* AniKatoAPI — countPages.helper.js
|
||||
* Repository: https://github.com/Shineii86/AniKatoAPI
|
||||
*
|
||||
* @description
|
||||
* Utility function to extract total page count from paginated
|
||||
* HTML content. Parses pagination links from Cheerio DOM to
|
||||
* determine the maximum page number available.
|
||||
*
|
||||
* @exports
|
||||
* countPages
|
||||
*
|
||||
* @author Shinei Nouzen
|
||||
* @license MIT
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
*/
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// PAGINATION EXTRACTION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Extract maximum page number from pagination elements ----
|
||||
/**
|
||||
* Parses HTML pagination elements to extract the total number of pages.
|
||||
* Looks for numeric page links in .pagination li a elements and
|
||||
* returns the highest page number found.
|
||||
*
|
||||
* @param {CheerioAPI} $ - Cheerio instance with loaded HTML content
|
||||
* @returns {number} Maximum page number (defaults to 1 if no pagination found)
|
||||
*
|
||||
* @example
|
||||
* // Count pages from search results
|
||||
* const $ = await extractPages(searchUrl);
|
||||
* const totalPages = countPages($);
|
||||
* // totalPages: 5 (if pages 1-5 exist)
|
||||
*
|
||||
* @note
|
||||
* This function assumes standard pagination HTML structure with
|
||||
* numeric page links inside .pagination > li > a elements.
|
||||
*/
|
||||
const countPages = ($) => {
|
||||
const pages = [];
|
||||
$(".pagination li a").each((i, el) => {
|
||||
@@ -9,4 +50,5 @@ const countPages = ($) => {
|
||||
return pages.length > 0 ? Math.max(...pages) : 1;
|
||||
};
|
||||
|
||||
export { countPages };
|
||||
export { countPages };
|
||||
// ══════════════════════════════════════════════════════════════ END: countPages.helper.js
|
||||
@@ -1,7 +1,83 @@
|
||||
/*
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
* AniKatoAPI — extractPages.helper.js
|
||||
* Repository: https://github.com/Shineii86/AniKatoAPI
|
||||
*
|
||||
* @description
|
||||
* HTTP client utility for fetching and parsing HTML content from
|
||||
* paginated URLs. Uses axios for HTTP requests and Cheerio for
|
||||
* DOM parsing, with support for page-based pagination.
|
||||
*
|
||||
* @exports
|
||||
* extractPages
|
||||
*
|
||||
* @author Shinei Nouzen
|
||||
* @license MIT
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
*/
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// DEPENDENCIES
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Cheerio HTML parser import ----
|
||||
/**
|
||||
* Cheerio library for server-side DOM manipulation.
|
||||
* Used to parse and query HTML content from fetched pages.
|
||||
*
|
||||
* @type {module:cheerio}
|
||||
*/
|
||||
import * as cheerio from "cheerio";
|
||||
|
||||
// ---- FEATURE: Axios HTTP client import ----
|
||||
/**
|
||||
* Axios HTTP client for making requests to the source site.
|
||||
* Handles redirects, timeouts, and response parsing.
|
||||
*
|
||||
* @type {module:axios}
|
||||
*/
|
||||
import axios from "axios";
|
||||
|
||||
// ---- FEATURE: Browser-mimicking headers import ----
|
||||
/**
|
||||
* Pre-configured HTTP headers to mimic browser requests.
|
||||
* Imported from header.config.js for consistent usage.
|
||||
*
|
||||
* @type {Object}
|
||||
*/
|
||||
import { headers } from "../configs/header.config.js";
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// PAGE EXTRACTION FUNCTION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Fetch and parse paginated URL content ----
|
||||
/**
|
||||
* Fetches HTML content from a URL with optional pagination support.
|
||||
* Appends page query parameter for pages > 1 and returns parsed
|
||||
* Cheerio instance for DOM querying.
|
||||
*
|
||||
* @param {string} url - Base URL to fetch (without page parameter)
|
||||
* @param {number} [page=1] - Page number to fetch (1-indexed)
|
||||
* @returns {Promise<CheerioAPI>} Parsed Cheerio instance of the page
|
||||
* @throws {Error} If HTTP request fails or returns non-2xx status
|
||||
*
|
||||
* @example
|
||||
* // Fetch first page of search results
|
||||
* const $ = await extractPages("https://anikototv.to/filter?keyword=one-piece");
|
||||
*
|
||||
* @example
|
||||
* // Fetch second page of genre listing
|
||||
* const $ = await extractPages(genreUrl, 2);
|
||||
*
|
||||
* @note
|
||||
* WARNING: The site may block requests without proper headers.
|
||||
* Always use the imported headers configuration.
|
||||
*
|
||||
* @note
|
||||
* TIP: Consider implementing retry logic for failed requests
|
||||
* in production environments.
|
||||
*/
|
||||
const extractPages = async (url, page = 1) => {
|
||||
try {
|
||||
const finalUrl = page > 1 ? `${url}?page=${page}` : url;
|
||||
@@ -13,4 +89,5 @@ const extractPages = async (url, page = 1) => {
|
||||
}
|
||||
};
|
||||
|
||||
export { extractPages };
|
||||
export { extractPages };
|
||||
// ══════════════════════════════════════════════════════════════ END: extractPages.helper.js
|
||||
@@ -1,3 +1,55 @@
|
||||
/*
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
* AniKatoAPI — formatTitle.helper.js
|
||||
* Repository: https://github.com/Shineii86/AniKatoAPI
|
||||
*
|
||||
* @description
|
||||
* String utility function for normalizing anime titles into
|
||||
* URL-safe slug format. Converts titles to lowercase, replaces
|
||||
* special characters with hyphens, and trims leading/trailing dashes.
|
||||
*
|
||||
* @exports
|
||||
* formatTitle
|
||||
*
|
||||
* @author Shinei Nouzen
|
||||
* @license MIT
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
*/
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// TITLE FORMATTING UTILITY
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Convert title string to URL-safe slug format ----
|
||||
/**
|
||||
* Formats an anime title into a URL-safe slug format.
|
||||
* - Converts to lowercase
|
||||
* - Replaces non-alphanumeric characters with hyphens
|
||||
* - Removes leading and trailing hyphens
|
||||
*
|
||||
* @param {string} title - The anime title to format
|
||||
* @returns {string} URL-safe slug version of the title
|
||||
*
|
||||
* @example
|
||||
* // Basic title formatting
|
||||
* formatTitle("One Piece") // "one-piece"
|
||||
*
|
||||
* @example
|
||||
* // Title with special characters
|
||||
* formatTitle(" Attack on Titan: The Final Season! ")
|
||||
* // "attack-on-titan-the-final-season"
|
||||
*
|
||||
* @example
|
||||
* // Edge cases
|
||||
* formatTitle("") // ""
|
||||
* formatTitle(null) // ""
|
||||
* formatTitle(" --- ") // ""
|
||||
*
|
||||
* @note
|
||||
* This function preserves alphanumeric characters and replaces
|
||||
* all other characters (spaces, punctuation, symbols) with hyphens.
|
||||
* Multiple consecutive special characters become a single hyphen.
|
||||
*/
|
||||
const formatTitle = (title) => {
|
||||
if (!title) return "";
|
||||
return title
|
||||
@@ -6,4 +58,5 @@ const formatTitle = (title) => {
|
||||
.replace(/^-+|-+$/g, "");
|
||||
};
|
||||
|
||||
export { formatTitle };
|
||||
export { formatTitle };
|
||||
// ══════════════════════════════════════════════════════════════ END: formatTitle.helper.js
|
||||
Reference in New Issue
Block a user