From b78d35d0f8c9c883ba97bb484e00c8722ec43971 Mon Sep 17 00:00:00 2001 From: rainbow napkin Date: Mon, 1 Sep 2025 14:15:02 -0400 Subject: [PATCH] JSDoc for src/schemas/*.js complete. Just need to finish src/schemas/channel --- src/schemas/emoteSchema.js | 21 ++++++++++-- src/schemas/flairSchema.js | 6 ++++ src/schemas/permissionSchema.js | 59 +++++++++++++++++++++++++++++++++ src/schemas/statSchema.js | 30 +++++++++++++++++ 4 files changed, 114 insertions(+), 2 deletions(-) diff --git a/src/schemas/emoteSchema.js b/src/schemas/emoteSchema.js index 9afb512..c059a0c 100644 --- a/src/schemas/emoteSchema.js +++ b/src/schemas/emoteSchema.js @@ -21,8 +21,14 @@ const {mongoose} = require('mongoose'); const defaultEmote = require("../../defaultEmotes.json"); const server = require('../server'); +/** + * "Enum" for emote type property + */ const typeEnum = ["image", "video"]; +/** + * DB Schema for documents represnting site-wide emotes + */ const emoteSchema = new mongoose.Schema({ name:{ type: mongoose.SchemaTypes.String, @@ -41,19 +47,26 @@ const emoteSchema = new mongoose.Schema({ } }); -//post-save function +/** + * Post-Save function, ensures all new emotes are broadcastes to actively connected clients + */ emoteSchema.post('save', async function (next){ //broadcast updated emotes server.channelManager.broadcastSiteEmotes(); }); -//post-delete function (document not query) +/** + * Post-Delete function, ensures all deleted emotes are removed from actively connected clients + */ emoteSchema.post('deleteOne', {document: true}, async function (next){ //broadcast updated emotes server.channelManager.broadcastSiteEmotes(); }); //statics +/** + * Loads un-loaded emotes from defaultEmotes.json + */ emoteSchema.statics.loadDefaults = async function(){ //Make sure registerEmote function is happy const _this = this; @@ -84,6 +97,10 @@ emoteSchema.statics.loadDefaults = async function(){ } } +/** + * Generates a network-friendly browser-digestable list of emotes + * @returns {Object} - network-friendly browser-digestable list of emotes + */ emoteSchema.statics.getEmotes = async function(){ //Create an empty array to hold our emote list const emoteList = []; diff --git a/src/schemas/flairSchema.js b/src/schemas/flairSchema.js index a10589e..e0b7956 100644 --- a/src/schemas/flairSchema.js +++ b/src/schemas/flairSchema.js @@ -21,6 +21,9 @@ const {mongoose} = require('mongoose'); const permissionModel = require("./permissionSchema"); const defaultFlair = require("../../defaultFlair.json"); +/** + * DB Schema for documents representing chat flair + */ const flairSchema = new mongoose.Schema({ name:{ type: mongoose.SchemaTypes.String, @@ -38,6 +41,9 @@ const flairSchema = new mongoose.Schema({ } }); +/** + * Function which runs on server startup to load un-loaded flairs from defaultFlair.json into the DB + */ flairSchema.statics.loadDefaults = async function(){ //Make sure registerFlair function is happy const _this = this; diff --git a/src/schemas/permissionSchema.js b/src/schemas/permissionSchema.js index e3dcde9..108c888 100644 --- a/src/schemas/permissionSchema.js +++ b/src/schemas/permissionSchema.js @@ -26,6 +26,9 @@ const {errorHandler} = require('../utils/loggerUtils'); //We could update all references but quite honestly I that would be uglier, this should have a copy too... const rankEnum = channelPermissionSchema.statics.rankEnum; +/** + * DB Schema for the singular site-wide permission document + */ const permissionSchema = new mongoose.Schema({ adminPanel: { type: mongoose.SchemaTypes.String, @@ -102,6 +105,10 @@ const permissionSchema = new mongoose.Schema({ //Statics permissionSchema.statics.rankEnum = rankEnum; +/** + * Returns the server's singular permission document from the DB + * @returns {Mongoose.Document} - The server's singular permission document + */ permissionSchema.statics.getPerms = async function(){ //Not sure why 'this' didn't work from here when calling this, I'm assuming it's because I'm doing it from middleware //which is probably binding shit to this function, either way this works :P @@ -126,10 +133,21 @@ permissionSchema.statics.getPerms = async function(){ } } +/** + * Converts rank name to number + * @param {String} rank - rank to check + * @returns {Number} Rank level + */ permissionSchema.statics.rankToNum = function(rank){ return rankEnum.indexOf(rank); } +/** + * Check users rank against a given permission by username + * @param {String} user - Username of the user to check against a perm + * @param {String} perm - Permission to check user against + * @returns {Boolean} Whether or not the user is authorized for the permission in question + */ permissionSchema.statics.permCheck = async function(user, perm){ //Check if the user is null if(user != null){ @@ -142,6 +160,12 @@ permissionSchema.statics.permCheck = async function(user, perm){ } } +/** + * Syntatic sugar for perms.CheckByUserDoc so we don't have to get the document ourselves + * @param {Mongoose.Document} user - User document to check perms against + * @param {String} perm - Permission to check user against + * @returns {Boolean} Whether or not the user is authorized for the permission in question + */ permissionSchema.statics.permCheckByUserDoc = async function(user, perm){ //Get permission list const perms = await this.getPerms(); @@ -149,6 +173,12 @@ permissionSchema.statics.permCheckByUserDoc = async function(user, perm){ return perms.permCheckByUserDoc(user, perm); } +/** + * Check users rank by a given permission by username + * @param {String} user - Username of the user to check against a perm + * @param {String} perm - Permission to check user against + * @returns {Boolean} Whether or not the user is authorized for the permission in question + */ permissionSchema.statics.overrideCheck = async function(user, perm){ //Check if the user is null if(user != null){ @@ -161,6 +191,13 @@ permissionSchema.statics.overrideCheck = async function(user, perm){ } } +/** + * Syntatic sugar for perms.overrideCheckByUSerDoc so we don't have to seperately get the perm doc + * Checks channel perm override against a given user by username + * @param {String} user - Username of the user to check against a perm + * @param {String} perm - Permission to check user against + * @returns {Boolean} Whether or not the user is authorized for the permission in question + */ permissionSchema.statics.overrideCheckByUserDoc = async function(user, perm){ //Get permission list const perms = await this.getPerms(); @@ -169,6 +206,11 @@ permissionSchema.statics.overrideCheckByUserDoc = async function(user, perm){ } //Middleware for rank checks +/** + * Configurable express middleware which checks user's request against a given permission + * @param {String} perm - Permission to check + * @returns {Function} Express middlewhere function with given permission injected into it + */ permissionSchema.statics.reqPermCheck = function(perm){ return (req, res, next)=>{ permissionSchema.statics.permCheck(req.session.user, perm).then((access) => { @@ -183,6 +225,12 @@ permissionSchema.statics.reqPermCheck = function(perm){ //methods //these are good to have even for single-doc collections since we can loop through them without finding them in the database each time +/** + * Checks permission against a single user by document + * @param {Mongoose.Document} userDB - User doc to rank check against + * @param {String} perm - Permission to check user doc against + * @returns {Boolean} True if authorized + */ permissionSchema.methods.permCheckByUserDoc = function(userDB, perm){ //Set user to anon rank if no rank was found for the given user if(userDB == null || userDB.rank == null){ @@ -205,6 +253,12 @@ permissionSchema.methods.permCheckByUserDoc = function(userDB, perm){ } } +/** + * Checks channel override permission against a single user by document + * @param {Mongoose.Document} userDB - User doc to rank check against + * @param {String} perm - Channel Override Permission to check user doc against + * @returns {Boolean} True if authorized + */ permissionSchema.methods.overrideCheckByUserDoc = function(userDB, perm){ //Set user to anon rank if no rank was found for the given user if(userDB == null || userDB.rank == null){ @@ -227,6 +281,11 @@ permissionSchema.methods.overrideCheckByUserDoc = function(userDB, perm){ } } +/** + * Returns entire permission map marked with booleans + * @param {Mongoose.Document} userDB - User Doc to generate perm map against + * @returns {Map} Permission map containing booleans for each permission's authorization for a given user doc + */ permissionSchema.methods.getPermMapByUserDoc = function(userDB){ //Pull permissions keys let permTree = this.schema.tree; diff --git a/src/schemas/statSchema.js b/src/schemas/statSchema.js index 3168f62..f0a2c3f 100644 --- a/src/schemas/statSchema.js +++ b/src/schemas/statSchema.js @@ -20,6 +20,9 @@ const {mongoose} = require('mongoose'); //Local Imports const config = require('./../../config.json'); +/** + * DB Schema for single document for keeping track of server stats + */ const statSchema = new mongoose.Schema({ //This does NOT handle deleted accounts/channels. Use userModel.estimatedDocumentCount() for number of active users. userCount: { @@ -57,6 +60,10 @@ const statSchema = new mongoose.Schema({ }); //statics +/** + * Get's servers sole stat document from the DB + * @returns {Mongoose.Document} Server's sole statistics document + */ statSchema.statics.getStats = async function(){ //Get the first document we find var stats = await this.findOne({}); @@ -78,6 +85,9 @@ statSchema.statics.getStats = async function(){ } } +/** + * Increments Lunach count upon server launch and prints out amount of launches since server initialization + */ statSchema.statics.incrementLaunchCount = async function(){ //get our statistics document const stats = await this.getStats(); @@ -91,6 +101,10 @@ statSchema.statics.incrementLaunchCount = async function(){ console.log(`First booted on ${stats.firstLaunch}.`); } +/** + * Increments user count upon new user registration + * @returns {Number} Number of users before count was incremented + */ statSchema.statics.incrementUserCount = async function(){ //get our statistics document const stats = await this.getStats(); @@ -105,6 +119,10 @@ statSchema.statics.incrementUserCount = async function(){ return oldCount; } +/** + * Increments channel count upon new channel registration + * @returns {Number} Number of channels before count was incremented + */ statSchema.statics.incrementChannelCount = async function(){ //get our statistics document const stats = await this.getStats(); @@ -119,6 +137,10 @@ statSchema.statics.incrementChannelCount = async function(){ return oldCount; } +/** + * Tattoo's toke to the server statistics document + * @param {Map} toke - Tokemap handed down from Tokebot + */ statSchema.statics.tattooToke = async function(toke){ //Get the statistics document const stats = await this.getStats(); @@ -130,6 +152,10 @@ statSchema.statics.tattooToke = async function(toke){ await stats.save(); } +/** + * Gets toke count from statistics document + * @returns {Number} Number of tokes across the entire site + */ statSchema.statics.getTokeCount = async function(){ //get stats doc const stats = await this.getStats(); @@ -138,6 +164,10 @@ statSchema.statics.getTokeCount = async function(){ return stats.tokes.length; } +/** + * Gets toke counts for each individual callout in a map + * @returns {Map} Map of toke counts for each individual callout registered to the server + */ statSchema.statics.getTokeCommandCounts = async function(){ //get stats doc const stats = await this.getStats()