Update API JS docs

server/Database.js

@@ -390,16 +390,6 @@ class Database {
     return this.models.user.updateFromOld(oldUser)
   }
 
-  removeUser(userId) {
-    if (!this.sequelize) return false
-    return this.models.user.removeById(userId)
-  }
-
-  upsertMediaProgress(oldMediaProgress) {
-    if (!this.sequelize) return false
-    return this.models.mediaProgress.upsertFromOld(oldMediaProgress)
-  }
-
   updateBulkBooks(oldBooks) {
     if (!this.sequelize) return false
     return Promise.all(oldBooks.map((oldBook) => this.models.book.saveFromOld(oldBook)))

server/controllers/AuthorController.js

@@ -1,3 +1,4 @@
+const { Request, Response, NextFunction } = require('express')
 const sequelize = require('sequelize')
 const fs = require('../libs/fsExtra')
 const { createNewSortInstance } = require('../libs/fastSort')
@@ -14,9 +15,23 @@ const { reqSupportsWebp, isValidASIN } = require('../utils/index')
 const naturalSort = createNewSortInstance({
   comparer: new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' }).compare
 })
+
+/**
+ * @typedef RequestUserObject
+ * @property {import('../models/User')} user
+ *
+ * @typedef {Request & RequestUserObject} RequestWithUser
+ */
+
 class AuthorController {
   constructor() {}
 
+  /**
+   * GET: /api/authors/:id
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   async findOne(req, res) {
     const include = (req.query.include || '').split(',')
 
@@ -63,9 +78,10 @@ class AuthorController {
   }
 
   /**
+   * PATCH: /api/authors/:id
    *
-   * @param {import('express').Request} req
-   * @param {import('express').Response} res
+   * @param {RequestWithUser} req
+   * @param {Response} res
    */
   async update(req, res) {
     const payload = req.body
@@ -194,8 +210,8 @@ class AuthorController {
    * DELETE: /api/authors/:id
    * Remove author from all books and delete
    *
-   * @param {import('express').Request} req
-   * @param {import('express').Response} res
+   * @param {RequestWithUser} req
+   * @param {Response} res
    */
   async delete(req, res) {
     Logger.info(`[AuthorController] Removing author "${req.author.name}"`)
@@ -218,8 +234,8 @@ class AuthorController {
    * POST: /api/authors/:id/image
    * Upload author image from web URL
    *
-   * @param {import('express').Request} req
-   * @param {import('express').Response} res
+   * @param {RequestWithUser} req
+   * @param {Response} res
    */
   async uploadImage(req, res) {
     if (!req.user.canUpload) {
@@ -263,8 +279,8 @@ class AuthorController {
    * DELETE: /api/authors/:id/image
    * Remove author image & delete image file
    *
-   * @param {import('express').Request} req
-   * @param {import('express').Response} res
+   * @param {RequestWithUser} req
+   * @param {Response} res
    */
   async deleteImage(req, res) {
     if (!req.author.imagePath) {
@@ -284,6 +300,12 @@ class AuthorController {
     })
   }
 
+  /**
+   * POST: /api/authors/:id/match
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   async match(req, res) {
     let authorData = null
     const region = req.body.region || 'us'
@@ -334,7 +356,12 @@ class AuthorController {
     })
   }
 
-  // GET api/authors/:id/image
+  /**
+   * GET: /api/authors/:id/image
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   async getImage(req, res) {
     const {
       query: { width, height, format, raw },
@@ -358,6 +385,12 @@ class AuthorController {
     return CacheManager.handleAuthorCache(res, author, options)
   }
 
+  /**
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   * @param {NextFunction} next
+   */
   async middleware(req, res, next) {
     const author = await Database.authorModel.getOldById(req.params.id)
     if (!author) return res.sendStatus(404)

server/controllers/BackupController.js

@@ -1,12 +1,28 @@
+const { Request, Response, NextFunction } = require('express')
 const Path = require('path')
 const fs = require('../libs/fsExtra')
 const Logger = require('../Logger')
 const Database = require('../Database')
 const fileUtils = require('../utils/fileUtils')
 
+/**
+ * @typedef RequestUserObject
+ * @property {import('../models/User')} user
+ *
+ * @typedef {Request & RequestUserObject} RequestWithUser
+ */
+
 class BackupController {
   constructor() {}
 
+  /**
+   * GET: /api/backups
+   *
+   * @this import('../routers/ApiRouter')
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   getAll(req, res) {
     res.json({
       backups: this.backupManager.backups.map((b) => b.toJSON()),
@@ -15,10 +31,26 @@ class BackupController {
     })
   }
 
+  /**
+   * POST: /api/backups
+   *
+   * @this import('../routers/ApiRouter')
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   create(req, res) {
     this.backupManager.requestCreateBackup(res)
   }
 
+  /**
+   * DELETE: /api/backups/:id
+   *
+   * @this import('../routers/ApiRouter')
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   async delete(req, res) {
     await this.backupManager.removeBackup(req.backup)
 
@@ -27,6 +59,14 @@ class BackupController {
     })
   }
 
+  /**
+   * POST: /api/backups/upload
+   *
+   * @this import('../routers/ApiRouter')
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   upload(req, res) {
     if (!req.files.file) {
       Logger.error('[BackupController] Upload backup invalid')
@@ -41,8 +81,8 @@ class BackupController {
    *
    * @this import('../routers/ApiRouter')
    *
-   * @param {import('express').Request} req
-   * @param {import('express').Response} res
+   * @param {RequestWithUser} req
+   * @param {Response} res
    */
   async updatePath(req, res) {
     // Validate path is not empty and is a string
@@ -86,10 +126,10 @@ class BackupController {
   }
 
   /**
-   * api/backups/:id/download
+   * GET: /api/backups/:id/download
    *
-   * @param {*} req
-   * @param {*} res
+   * @param {RequestWithUser} req
+   * @param {Response} res
    */
   download(req, res) {
     if (global.XAccel) {
@@ -104,14 +144,23 @@ class BackupController {
   }
 
   /**
+   * GET: /api/backups/:id/apply
+   *
+   * @this import('../routers/ApiRouter')
    *
-   * @param {import('express').Request} req
-   * @param {import('express').Response} res
+   * @param {RequestWithUser} req
+   * @param {Response} res
    */
   apply(req, res) {
     this.backupManager.requestApplyBackup(this.apiCacheManager, req.backup, res)
   }
 
+  /**
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   * @param {NextFunction} next
+   */
   middleware(req, res, next) {
     if (!req.user.isAdminOrUp) {
       Logger.error(`[BackupController] Non-admin user "${req.user.username}" attempting to access backups`)

server/controllers/CacheController.js

@@ -1,9 +1,22 @@
+const { Request, Response } = require('express')
 const CacheManager = require('../managers/CacheManager')
 
+/**
+ * @typedef RequestUserObject
+ * @property {import('../models/User')} user
+ *
+ * @typedef {Request & RequestUserObject} RequestWithUser
+ */
+
 class CacheController {
   constructor() {}
 
-  // POST: api/cache/purge
+  /**
+   * POST: /api/cache/purge
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   async purgeCache(req, res) {
     if (!req.user.isAdminOrUp) {
       return res.sendStatus(403)
@@ -12,7 +25,12 @@ class CacheController {
     res.sendStatus(200)
   }
 
-  // POST: api/cache/items/purge
+  /**
+   * POST: /api/cache/items/purge
+   *
+   * @param {RequestWithUser} req
+   * @param {Response} res
+   */
   async purgeItemsCache(req, res) {
     if (!req.user.isAdminOrUp) {
       return res.sendStatus(403)