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>

src/extractors/newRelease.extractor.js

@@ -1,3 +1,21 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKatoAPI — newRelease.extractor.js
+ * Repository: https://github.com/Shineii86/AniKatoAPI
+ *
+ * @description
+ *   Extracts newly released and newly added anime with pagination.
+ *   Provides both new releases and sorted by addition date.
+ *
+ * @exports
+ *   extractNewRelease
+ *   extractNewlyAdded
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
 import * as cheerio from "cheerio";
 import axios from "axios";
 import { headers } from "../configs/header.config.js";
@@ -5,12 +23,43 @@ import { URLS } from "../configs/dataUrl.js";
 import { extractPages } from "../helper/extractPages.helper.js";
 import { countPages } from "../helper/countPages.helper.js";
 
+// ══════════════════════════════════════════════════════════════
+// NEW RELEASE EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extract newly released anime with pagination ----
+/**
+ * Fetches and parses newly released anime with pagination.
+ * Returns paginated results with total page count.
+ *
+ * @param {number} page - Page number to fetch (default: 1)
+ * @returns {Promise<Object>} Object containing totalPages and data array
+ * @returns {number} return.totalPages - Total number of pages available
+ * @returns {Array<Object>} return.data - Array of anime objects
+ * @returns {string} return.data[].slug - URL slug for the anime
+ * @returns {string} return.data[].poster - Poster image URL
+ * @returns {string} return.data[].title - English title
+ * @returns {string} return.data[].japaneseTitle - Japanese title
+ * @returns {number} return.data[].sub - Subbed episode count
+ * @returns {number} return.data[].dub - Dubbed episode count
+ * @returns {number} return.data[].total - Total episode count
+ * @returns {string} return.data[].type - Anime type (TV, Movie, etc.)
+ * @returns {string} return.data[].rating - Anime rating
+ *
+ * @example
+ *   const newRelease = await extractNewRelease(1);
+ *   console.log(newRelease.totalPages);
+ *   console.log(newRelease.data[0].title);
+ */
 const extractNewRelease = async (page = 1) => {
   try {
+    // NOTE: extractPages handles pagination and returns parsed Cheerio object
     const $ = await extractPages(URLS.newRelease, page);
     const totalPages = countPages($);
 
     const results = [];
+
+    // NOTE: Multiple selectors to handle different page layouts
     $(".film_list-wrap .flw-item, .film-detail, .item").each((i, el) => {
       const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find("img").attr("src") || "";
@@ -22,6 +71,7 @@ const extractNewRelease = async (page = 1) => {
       const type = $(el).find(".meta .inner .right, .fdi-item:nth-child(2)").text().trim() || "";
       const rating = $(el).find(".rating, .fdi-item:nth-child(3)").text().trim() || "";
 
+      // NOTE: Only include items with valid slugs
       if (slug) {
         results.push({
           slug,
@@ -43,12 +93,42 @@ const extractNewRelease = async (page = 1) => {
   }
 };
 
+// ══════════════════════════════════════════════════════════════
+// NEWLY ADDED EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extract newly added anime sorted by addition date ----
+/**
+ * Fetches and parses newly added anime sorted by addition date.
+ * Uses the latestUpdated endpoint with sort=added parameter.
+ *
+ * @param {number} page - Page number to fetch (default: 1)
+ * @returns {Promise<Object>} Object containing totalPages and data array
+ * @returns {number} return.totalPages - Total number of pages available
+ * @returns {Array<Object>} return.data - Array of anime objects
+ * @returns {string} return.data[].slug - URL slug for the anime
+ * @returns {string} return.data[].poster - Poster image URL
+ * @returns {string} return.data[].title - English title
+ * @returns {string} return.data[].japaneseTitle - Japanese title
+ * @returns {number} return.data[].sub - Subbed episode count
+ * @returns {number} return.data[].dub - Dubbed episode count
+ * @returns {number} return.data[].total - Total episode count
+ * @returns {string} return.data[].type - Anime type (TV, Movie, etc.)
+ *
+ * @example
+ *   const newlyAdded = await extractNewlyAdded(1);
+ *   console.log(newlyAdded.totalPages);
+ *   console.log(newlyAdded.data[0].title);
+ */
 const extractNewlyAdded = async (page = 1) => {
   try {
+    // NOTE: The latestUpdated endpoint with sort=added returns recently added anime
     const $ = await extractPages(`${URLS.latestUpdated}?sort=added`, page);
     const totalPages = countPages($);
 
     const results = [];
+
+    // NOTE: Multiple selectors to handle different page layouts
     $(".film_list-wrap .flw-item, .film-detail, .item").each((i, el) => {
       const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find("img").attr("src") || "";
@@ -59,6 +139,7 @@ const extractNewlyAdded = async (page = 1) => {
       const total = parseInt($(el).find(".ep-status.total span").text().trim()) || 0;
       const type = $(el).find(".meta .inner .right, .fdi-item:nth-child(2)").text().trim() || "";
 
+      // NOTE: Only include items with valid slugs
       if (slug) {
         results.push({
           slug,
@@ -79,4 +160,6 @@ const extractNewlyAdded = async (page = 1) => {
   }
 };
 
-export { extractNewRelease, extractNewlyAdded };
+export { extractNewRelease, extractNewlyAdded };
+
+// ══════════════════════════════════════════════════════════════ END: newRelease.extractor.js