Add basic documentation for helper functions

src/lib/items.ts

@@ -8,7 +8,9 @@ interface itemChangeResult {
     count: number,
     inv?: inventory
 }
-
+/** Check if the target user can use/lose item(s) and return the new inventory
+ * @param [amount=-1] If not specified, reduce count by one
+ * @param [preconfirmed=false] If it is confirmed that the change is allowed, update the inventory immediately */
 export async function changeItemCount(user: HelixUser, item: string, amount = -1, preconfirmed = false): Promise<itemChangeResult> {
     if (!ITEMS.includes(item)) return { result: false, reason: 'noexist', count: 0 }
     let inv = await getInventory(user)

src/lib/lootboxes.ts

@@ -8,13 +8,14 @@ interface lootboxReadyResult {
     lastlootbox: number,
     DBuser: User
 }
-
-export async function lootboxReady(user: HelixUser | null): Promise<lootboxReadyResult> {
+/** Check if the lootbox is ready for specified user */
+export async function lootboxReady(user: HelixUser): Promise<lootboxReadyResult> {
     const DBuser = await pb.collection('users').getFirstListItem(`id="${user!.id}"`)
     if ((Date.parse(DBuser.lastlootbox) + COOLDOWN) > Date.now()) return { result: false, lastlootbox: Date.parse(DBuser.lastlootbox), DBuser }
     return { result: true, lastlootbox: 0, DBuser }
 }
 
+/** Set the time for last time user got lootbox to now */
 export async function resetLootboxTimer(user: User) {
     const data = { lastlootbox: new Date(Date.now()).toISOString() }
     await pb.collection('users').update(user.id, data)

src/lib/timeoutHelper.ts

@@ -10,6 +10,9 @@ interface statusmessage {
     reason: string
 }
 
+/** Ban a specific user out by another user for specified amout of time, with specific reason
+ * If the user does not exist or is already banned return status: false
+ * If the user is a moderator, make sure they get their status back after timeout has elapsed */
 export async function timeout(broadcasterid: string, target: HelixUser, duration: number, reason: string): Promise<statusmessage> {
     if (!target) return { status: false, reason: 'noexist' }
     const tmpapi = broadcasterApi ?? api
@@ -30,6 +33,7 @@ export async function timeout(broadcasterid: string, target: HelixUser, duration
     }
 }
 
+/** Add an entry to the timeouts table */
 export async function addTimeoutToDB(attacker: HelixUser, target: HelixUser, source: shooter) {
     // This has passed the existance check so there's no need to check if the users exist (twitch)
     const timeoutobj = {
@@ -42,6 +46,7 @@ export async function addTimeoutToDB(attacker: HelixUser, target: HelixUser, sou
     await pb.collection('timeouts').create(timeoutobj)
 }
 
+/** Give the target mod status back after timeout */
 function remodMod(broadcasterid: string, target: HelixUser, duration: number, api: ApiClient) {
     setTimeout(async () => {
         const bandata = await api.moderation.getBannedUsers(broadcasterid, { userId: target.id })

src/lib/userHelper.ts

@@ -16,6 +16,8 @@ type balanceGetResult = {
     data: User
 }
 
+/** Ensures that the user exists in the database
+ * Returns an object with balance as well as the entire user entry from the database */
 export async function getBalance(user: HelixUser): Promise<balanceGetResult> {
     await DBValidation(user)
     const data = await pb.collection('users').getFirstListItem(`id="${user!.id}"`)
@@ -28,6 +30,7 @@ type balanceChangeResult = {
     count: number
 }
 
+/** Changes the balance of the current user by the requested amount */
 export async function changeBalance(user: HelixUser, amount: number): Promise<balanceChangeResult> {
     let { balance, data } = await getBalance(user)
     if (amount < 0 && balance - amount < 0) return { result: false, reason: 'negative', count: balance }
@@ -49,6 +52,8 @@ interface timeoutsGetResult {
 
 const BLASTERS = ['blaster', 'grenade', 'tnt']
 
+/** Get the amount of times the user has (been) shot (by) another user
+ * The 'blaster' data is all timeouts excluding silver bullets */
 async function getTimeouts(userId: string, monthdata?: string): Promise<timeoutsGetResult> {
     let monthquery = ''
     if (monthdata) monthquery = ` && created~"${monthdata}"`
@@ -72,6 +77,8 @@ async function getTimeouts(userId: string, monthdata?: string): Promise<timeouts
     }
 }
 
+/** Get the amount of grenades and tnt used by specified user
+ * The monthdata should be something like "2025-01" if specified */
 async function getItemUses(userId: string, monthdata?: string): Promise<inventory> {
     let monthquery = ''
     if (monthdata) monthquery = ` && created~"${monthdata}"`
@@ -82,6 +89,7 @@ async function getItemUses(userId: string, monthdata?: string): Promise<inventor
     }
 }
 
+/** Get the inventory of specific user */
 export async function getInventory(user: HelixUser): Promise<inventory> {
     await DBValidation(user)
     const data = await pb.collection('users').getFirstListItem(`id="${user.id}"`)
@@ -92,6 +100,8 @@ interface statsGetResult extends timeoutsGetResult {
     used: inventory
 }
 
+/** Get the hits, shoot and used item stats from specific user
+ * The monthdata should be something like "2025-01" if specified */
 export async function getStats(user: HelixUser, monthdata?: string): Promise<statsGetResult> {
     await DBValidation(user)
     const { hit, shot } = await getTimeouts(user.id, monthdata)
@@ -99,18 +109,21 @@ export async function getStats(user: HelixUser, monthdata?: string): Promise<sta
     return { hit, shot, used }
 }
 
+/** Update the inventory of the target user with new inventory data */
 export async function updateInventory(user: HelixUser, newinv: inventory) {
     await DBValidation(user)
     const data = await pb.collection('users').getFirstListItem(`id="${user.id}"`)
     const recordid = data.id
     await pb.collection('users').update(recordid, { inventory: newinv })
 }
-
+/** Creates a new entry in the useditems table */
 export async function addUsedItem(user: HelixUser, item: string) {
     await DBValidation(user)
     await pb.collection('itemuses').create({ user: user.id, name: item })
 }
 
+/** Validate if the HelixUser has an entry in the database
+ * Add missing inventory items*/
 export async function DBValidation(user: HelixUser) {
     try {
         let { inventory } = await pb.collection('users').getFirstListItem(`id="${user.id}"`)
@@ -123,13 +136,12 @@ export async function DBValidation(user: HelixUser) {
         await createUser(user!)
     }
 }
-
+/** Create the user in the database */
 async function createUser(user: HelixUser) {
     const data = {
         id: user.id,
         firstname: user.name,
         inventory: EMPTYINV,
-        itemuses: EMPTYINV,
         lastlootbox: "1970-01-01 12:00:00.000Z",
         balance: 0
     }