Change typing script and improve JSDoc comments

Stevox404 · Sep 16, 2021 · 5b00f7a · 5b00f7a
1 parent 880283f
commit 5b00f7a
Show file tree

Hide file tree

Showing 16 changed files with 2,321 additions and 1,933 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,12 +1,12 @@
 {
   "name": "mangadex-full-api",
-  "version": "5.5.1",
+  "version": "5.6.0",
   "description": "A MangaDex api based around the official API.",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "scripts": {
     "test": "mocha",
-    "gen-types": "tsc && node ./types/compress-types.js"
+    "gen-types": "dts-bundle-generator --out-file=./types/index.d.ts --external-types=node --no-banner ./src/index.js"
   },
   "engines": {
     "node": ">=10.12.0"
@@ -30,7 +30,8 @@
   },
   "homepage": "https://github.com/md-y/mangadex-full-api#readme",
   "devDependencies": {
-    "mocha": "^8.4.0",
-    "typescript": "^4.1.3"
+    "@types/node": "^16.9.1",
+    "dts-bundle-generator": "^5.9.0",
+    "mocha": "^8.4.0"
   }
 }
diff --git a/src/index.js b/src/index.js
@@ -79,10 +79,11 @@ Relationship.registerType('cover_art', Cover);
 
 /**
  * A shortcut for resolving all relationships in an array
- * @param {Relationship[]} relationshipArray
- * @returns {Promise}
+ * @template T
+ * @param {Relationship<T>[]} relationshipArray
+ * @returns {Promise<T[]>}
  */
- function resolveArray(relationshipArray) {
+function resolveArray(relationshipArray) {
     return Relationship.resolveAll(relationshipArray);
 }
 exports.resolveArray = resolveArray;
diff --git a/src/internal/links.js b/src/internal/links.js
@@ -5,6 +5,9 @@
  * https://api.mangadex.org/docs.html#section/Static-data/Manga-links-data
  */
 class Links {
+    /**
+     * @param {Object.<string, string>} linksObject 
+     */
     constructor(linksObject) {
         if (!linksObject) {
             this.availableLinks = [];

diff --git a/src/internal/localizedstring.js b/src/internal/localizedstring.js
@@ -8,11 +8,14 @@
 class LocalizedString {
     /**
      * Global locale setting
-     * @private
+     * @ignore
      * @type {String}
      */
     static locale = 'en';
 
+    /**
+     * @param {Object.<string, string>} stringObject 
+     */
     constructor(stringObject) {
         if (!stringObject) {
             this.availableLocales = [];

diff --git a/src/internal/relationship.js b/src/internal/relationship.js
@@ -2,6 +2,7 @@
 
 /**
  * Represents a relationship from one Mangadex object to another such as a manga, author, etc via its id.
+ * @template ResolveType
  */
 class Relationship {
     static types = {};
@@ -30,7 +31,7 @@ class Relationship {
     /**
      * This function must be called to return the proper and complete object representation of this relationship.
      * Essentially, it calls and returns Manga.get(), Author.get(), Cover.get(), etc.
-     * @returns {Promise<Manga|Author|Chapter|User|Group|List|Cover>}
+     * @returns {Promise<ResolveType>}
      */
     resolve() {
         if (this.id === undefined || this.type === undefined) throw new Error('Invalid Relationship object');
@@ -40,11 +41,11 @@ class Relationship {
 
     /**
      * Returns an array of converted objects from a Mangadex Relationships Array
-     * @private
+     * @ignore
      * @param {String} type 
      * @param {Object[]} dataArray 
      * @param {Object} caller
-     * @returns {Object[]}
+     * @returns {Relationship<ResolveType>}
      */
     static convertType(type, dataArray, caller) {
         if (!(dataArray instanceof Array)) return [];
@@ -71,7 +72,7 @@ class Relationship {
     /**
      * Provides a constructor for a relationship type at run-time.
      * Should only be called in index.js
-     * @private
+     * @ignore
      * @param {String} name 
      * @param {Object} classObject 
      */
@@ -83,8 +84,10 @@ class Relationship {
 
     /**
      * Resolves an array of relationships
-     * @private
-     * @param {Relationship[]} relationshipArray
+     * @ignore
+     * @template T
+     * @param {Relationship<T>[]} relationshipArray
+     * @returns {Promise<T[]>}
      */
     static resolveAll(relationshipArray) {
         if (relationshipArray.length === 0) return [];

diff --git a/src/internal/tag.js b/src/internal/tag.js
@@ -61,7 +61,7 @@ class Tag {
     }
 
     /**
-     * @private
+     * @ignore
      * @returns {Promise<Tag[]>}
      */
     static async getAllTags() {
@@ -75,7 +75,7 @@ class Tag {
     }
 
     /**
-     * @private
+     * @ignore
      * @param {String} indentity
      * @returns {Promise<Tag>}
      */

diff --git a/src/internal/uploadsession.js b/src/internal/uploadsession.js
@@ -27,19 +27,19 @@ class UploadSession {
 
         /**
          * Relationship of the target manga
-         * @type {Relationship}
+         * @type {Relationship<import('../index').Manga>}
          */
         this.manga = Relationship.convertType('manga', res.data.relationships, this).pop();
 
         /**
          * Relationships to the groups attributed to this chapter
-         * @type {Relationship}
+         * @type {Relationship<import('../index').Group>}
          */
         this.groups = Relationship.convertType('group', res.data.relationships, this);
 
         /**
          * Relationship to the uploader (the current user)
-         * @type {Relationship}
+         * @type {Relationship<import('../index').User>}
          */
         this.uploader = Relationship.convertType('user', res.data.relationships, this).pop();
 
@@ -78,7 +78,7 @@ class UploadSession {
     /**
      * Requests MD to start an upload session
      * @param {String|Manga} manga 
-     * @param  {...String|Group|Relationship} groups 
+     * @param  {...String|import('../index').Group|Relationship<import('../index').Group>} groups
      * @returns {UploadSession}
      */
     static async open(manga, ...groups) {
@@ -111,7 +111,7 @@ class UploadSession {
     }
 
     /**
-     * @private
+     * @ignore
      * @typedef {Object} PageFileObject
      * @property {Buffer} PageFileObject.data 
      * @property {'jpeg'|'png'|'gif'} [PageFileObject.type]
@@ -158,7 +158,7 @@ class UploadSession {
     }
 
     /**
-     * @private
+     * @ignore
      * @typedef {Object} ChapterDraftObject
      * @property {String} ChapterDraftObject.volume
      * @property {String} ChapterDraftObject.chapter

diff --git a/src/structure/author.js b/src/structure/author.js
@@ -2,7 +2,6 @@
 
 const Util = require('../util.js');
 const Relationship = require('../internal/relationship.js');
-const Manga = require('./manga.js');
 
 /**
  * Represents an author or artist
@@ -61,13 +60,13 @@ class Author {
 
         /**
          * Manga this author/artist has been attributed to
-         * @type {Relationship[]}
+         * @type {Relationship<import('../index').Manga>[]}
          */
         this.manga = Relationship.convertType('manga', context.data.relationships, this);
     }
 
     /**
-     * @private
+     * @ignore
      * @typedef {Object} AuthorParameterObject
      * @property {String} [AuthorParameterObject.name]
      * @property {String[]} [AuthorParameterObject.ids] Max of 100 per request
@@ -92,7 +91,7 @@ class Author {
 
     /**
      * Gets multiple authors
-     * @param {...String|Author|Relationship} ids
+     * @param {...String|Author|Relationship<Author>} ids
      * @returns {Promise<Author[]>}
      */
     static getMultiple(...ids) {

diff --git a/src/structure/chapter.js b/src/structure/chapter.js
@@ -3,8 +3,6 @@
 const Util = require('../util.js');
 const AuthUtil = require('../auth.js');
 const Relationship = require('../internal/relationship.js');
-const Group = require('./group.js');
-const Manga = require('./manga.js');
 
 /**
  * Represents a chapter with readable pages
@@ -110,25 +108,25 @@ class Chapter {
 
         /**
          * The scanlation groups that are attributed to this chapter
-         * @type {Relationship[]}
+         * @type {Relationship<import('../index').Group>[]}
          */
         this.groups = Relationship.convertType('scanlation_group', context.data.relationships, this);
 
         /**
          * The manga this chapter belongs to
-         * @type {Relationship}
+         * @type {Relationship<import('../index').Manga>}
          */
         this.manga = Relationship.convertType('manga', context.data.relationships, this).pop();
 
         /**
          * The user who uploaded this chapter
-         * @type {Relationship}
+         * @type {Relationship<import('../index').User>}
          */
         this.uploader = Relationship.convertType('user', context.data.relationships, this).pop();
     }
 
     /**
-     * @private
+     * @ignore
      * @typedef {Object} ChapterParameterObject
      * @property {String} [ChapterParameterObject.title]
      * @property {String} [ChapterParameterObject.createdAtSince] DateTime string with following format: YYYY-MM-DDTHH:MM:SS
@@ -147,9 +145,9 @@ class Chapter {
      * @property {String[]} [ChapterParameterObject.ids] Max of 100 per request
      * @property {Number} [ChapterParameterObject.limit] Not limited by API limits (more than 100). Use Infinity for maximum results (use at your own risk)
      * @property {Number} [ChapterParameterObject.offset]
-     * @property {String[]|Group[]} [ChapterParameterObject.groups]
-     * @property {String|User|Relationship} [ChapterParameterObject.uploader]
-     * @property {String|Manga|Relationship} [ChapterParameterObject.manga]
+     * @property {String[]|import('../index').Group[]} [ChapterParameterObject.groups]
+     * @property {String|import('../index').User|Relationship<import('../index').User>} [ChapterParameterObject.uploader]
+     * @property {String|import('../index').Manga|Relationship<import('../index').Manga>} [ChapterParameterObject.manga]
      * @property {String[]} [ChapterParameterObject.volume]
      * @property {String} [ChapterParameterObject.chapter]
      */
@@ -162,14 +160,14 @@ class Chapter {
      * @returns {Promise<Chapter[]>}
      */
     static search(searchParameters = {}, includeSubObjects = false) {
-        if (typeof searchParameters === 'string') searchParameters = { title: searchParameters };
+        if (typeof searchParameters === 'string') searchParameters = { title: searchParameters, groups };
         if (includeSubObjects) searchParameters.includes = ['scanlation_group', 'manga', 'user'];
         return Util.apiCastedRequest('/chapter', Chapter, searchParameters);
     }
 
     /**
      * Gets multiple chapters
-     * @param {...String|Chapter|Relationship} ids
+     * @param {...String|Chapter|Relationship<Chapter>} ids
      * @returns {Promise<Chapter[]>}
      */
     static getMultiple(...ids) {

diff --git a/src/structure/cover.js b/src/structure/cover.js
@@ -2,8 +2,6 @@
 
 const Relationship = require('../internal/relationship.js');
 const Util = require('../util.js');
-const Manga = require('./manga.js');
-const User = require('./user.js');
 
 /**
  * Represents the cover art of a manga volume
@@ -57,14 +55,14 @@ class Cover {
 
         /**
          * Manga this is a cover for
-         * @type {Relationship}
+         * @type {Relationship<import('../index').Manga>}
          */
         this.manga = Relationship.convertType('manga', context.data.relationships, this).pop();
         if (!this.manga) this.manga = null;
 
         /**
          * The user who uploaded this cover
-         * @type {Relationship}
+         * @type {Relationship<import('../index').User>}
          */
         this.uploader = Relationship.convertType('user', context.data.relationships, this).pop();
         if (!this.uploader) this.uploader = null;
@@ -99,13 +97,13 @@ class Cover {
     }
 
     /**
-     * @private
+     * @ignore
      * @typedef {Object} CoverParameterObject
      * @property {Number} [CoverParameterObject.limit] Not limited by API limits (more than 100). Use Infinity for maximum results (use at your own risk)
      * @property {Number} [CoverParameterObject.offset]
-     * @property {String[]|Manga[]} [CoverParameterObject.manga] Manga ids (limited to 100 per request)
+     * @property {String[]|import('../index').Manga[]} [CoverParameterObject.manga] Manga ids (limited to 100 per request)
      * @property {String[]|Cover[]} [CoverParameterObject.ids] Covers ids (limited to 100 per request)
-     * @property {String[]|User[]} [CoverParameterObject.uploaders] User ids (limited to 100 per request)
+     * @property {String[]|import('../index').User[]} [CoverParameterObject.uploaders] User ids (limited to 100 per request)
      * @property {Object} [CoverParameterObject.order]
      * @property {'asc'|'desc'} [CoverParameterObject.order.createdAt]
      * @property {'asc'|'desc'} [CoverParameterObject.order.updatedAt]
@@ -126,7 +124,7 @@ class Cover {
 
     /**
      * Gets multiple covers
-     * @param {...String|Cover|Relationship} ids
+     * @param {...String|Cover|Relationship<Cover>} ids
      * @returns {Promise<Cover[]>}
      */
     static getMultiple(...ids) {
@@ -147,7 +145,7 @@ class Cover {
 
     /**
      * Get an array of manga's covers
-     * @param {...String|Manga|Relationship} manga
+     * @param {...String|import('../index').Manga|Relationship<import('../index').Manga>} manga
      * @returns {Promise<Cover[]>}
      */
     static getMangaCovers(...manga) {

diff --git a/src/structure/group.js b/src/structure/group.js
@@ -3,7 +3,6 @@
 const Util = require('../util.js');
 const AuthUtil = require('../auth.js');
 const Relationship = require('../internal/relationship.js');
-const User = require('./user.js');
 
 /**
  * Represents a scanlation group
@@ -98,19 +97,19 @@ class Group {
 
         /**
          * This group's leader
-         * @type {Relationship}
+         * @type {Relationship<import('../index').User>}
          */
         this.leader = Relationship.convertType('leader', context.data.relationships, this).pop();
 
         /**
          * Array of this group's members
-         * @type {Relationship[]}
+         * @type {Relationship<import('../index').User>[]}
          */
         this.members = Relationship.convertType('member', context.data.relationships, this);
     }
 
     /**
-     * @private
+     * @ignore
      * @typedef {Object} GroupParameterObject
      * @property {String} [GroupParameterObject.name]
      * @property {String[]} [GroupParameterObject.ids] Max of 100 per request
@@ -133,7 +132,7 @@ class Group {
 
     /**
      * Gets multiple groups
-     * @param {...String|Group|Relationship} ids
+     * @param {...String|Group|Relationship<Group>} ids
      * @returns {Promise<Group[]>}
      */
     static getMultiple(...ids) {