Merge pull request #1704 from esx-framework/player-class

refactor(es_extended/server/class/player): add proper type annotations

Author: Kenshiin13

[core]/es_extended/client/functions.lua

@@ -1,4 +1,5 @@
 ---@return boolean
+---@diagnostic disable-next-line: duplicate-set-field
 function ESX.IsPlayerLoaded()
     return ESX.PlayerLoaded
 end
@@ -559,7 +560,8 @@ function ESX.Game.SpawnVehicle(vehicleModel, coords, heading, cb, networked)
         local modelHash = ESX.Streaming.RequestModel(model)
         if not modelHash then
             if promise then
-                return promise:reject(("Tried to spawn invalid vehicle - ^5%s^7!"):format(model))
+                promise:reject(("Tried to spawn invalid vehicle - ^5%s^7!"):format(model))
+                return
             end
            error(("Tried to spawn invalid vehicle - ^5%s^7!"):format(model))
         end

[core]/es_extended/client/imports/point.lua

@@ -1,6 +1,6 @@
 local Point = ESX.Class()
 
-local nearby, loop = {}
+local nearby, loop = {}, nil
 
 function Point:constructor(properties)
 	self.coords = properties.coords
@@ -23,7 +23,7 @@ function Point:constructor(properties)
 							point:inside(#(coords - point.coords))
 						end
 					end
-					Wait()
+					Wait(0)
 				end
 			end)
 		end

[core]/es_extended/client/modules/callback.lua

@@ -92,7 +92,7 @@ end
 
 ---@param eventName string
 ---@param ... any
----@return any
+---@return ...
 function ESX.AwaitServerCallback(eventName, ...)
     local invokingResource = GetInvokingResource()
     local invoker = (invokingResource and invokingResource ~= "unknown") and invokingResource or "es_extended"

[core]/es_extended/imports.lua

@@ -218,9 +218,10 @@ if GetResourceState("ox_lib") == "missing" then
         return nil, err or 'unknown error'
     end
 
+    ---@diagnostic disable-next-line: duplicate-doc-alias
     ---@alias PackageSearcher
     ---| fun(modName: string): function loader
-    ---| fun(modName: string): nil, string errmsg
+    ---| fun(modName: string): nil|false, string errmsg
 
     ---@type PackageSearcher[]
     package.searchers = {

[core]/es_extended/server/classes/player.lua

@@ -292,7 +292,7 @@ end
 
 ---@param key? string
 ---@param val? string|table
----@return table
+---@return xPlayer[]|table<any, xPlayer[]>
 function ESX.GetExtendedPlayers(key, val)
     if not key then
         return ESX.Table.ToArray(ESX.Players)
@@ -348,13 +348,13 @@ function ESX.GetNumPlayers(key, val)
 end
 
 ---@param source number
----@return table
+---@return xPlayer?
 function ESX.GetPlayerFromId(source)
     return ESX.Players[tonumber(source)]
 end
 
 ---@param identifier string
----@return table
+---@return xPlayer?
 function ESX.GetPlayerFromIdentifier(identifier)
     return Core.playersByIdentifier[identifier]
 end
@@ -367,16 +367,17 @@ end
 
 ---@param source number
 ---@return boolean
+---@diagnostic disable-next-line: duplicate-set-field
 function ESX.IsPlayerLoaded(source)
     return ESX.Players[source] ~= nil
 end
 
 ---@param playerId number | string
----@return string
+---@return string, number
 function ESX.GetIdentifier(playerId)
     local fxDk = GetConvarInt("sv_fxdkMode", 0)
     if fxDk == 1 then
-        return "ESX-DEBUG-LICENCE"
+        return "ESX-DEBUG-LICENCE", 0
     end
 
     playerId = tostring(playerId)

[core]/es_extended/server/functions.lua

@@ -417,6 +417,10 @@ if not Config.CustomInventory then
         if itemType == "item_standard" then
             local sourceItem = sourceXPlayer.getInventoryItem(itemName)
 
+            if not sourceItem then
+                return
+            end
+
             if itemCount < 1 or sourceItem.count < itemCount then
                 return sourceXPlayer.showNotification(TranslateCap("imp_invalid_quantity"))
             end
@@ -453,6 +457,10 @@ if not Config.CustomInventory then
             end
 
             local _, weapon = sourceXPlayer.getWeapon(itemName)
+            if not weapon then
+                return
+            end
+
             local _, weaponObject = ESX.GetWeapon(itemName)
             itemCount = weapon.ammo
             local weaponComponents = ESX.Table.Clone(weapon.components)
@@ -485,6 +493,9 @@ if not Config.CustomInventory then
             end
 
             local _, weapon = sourceXPlayer.getWeapon(itemName)
+            if not weapon then
+                return
+            end
 
             if not targetXPlayer.hasWeapon(itemName) then
                 sourceXPlayer.showNotification(TranslateCap("gave_weapon_noweapon", targetXPlayer.name))
@@ -511,12 +522,19 @@ if not Config.CustomInventory then
         local playerId = source
         local xPlayer = ESX.GetPlayerFromId(playerId)
 
+        if not xPlayer then
+            return
+        end
+
         if itemType == "item_standard" then
             if not itemCount or itemCount < 1 then
                 return xPlayer.showNotification(TranslateCap("imp_invalid_quantity"))
             end
 
             local xItem = xPlayer.getInventoryItem(itemName)
+            if not xItem then
+                return
+            end
 
             if itemCount > xItem.count or xItem.count < 1 then
                 return xPlayer.showNotification(TranslateCap("imp_invalid_quantity"))
@@ -532,6 +550,9 @@ if not Config.CustomInventory then
             end
 
             local account = xPlayer.getAccount(itemName)
+            if not account then
+                return
+            end
 
             if itemCount > account.money or account.money < 1 then
                 return xPlayer.showNotification(TranslateCap("imp_invalid_amount"))
@@ -547,6 +568,10 @@ if not Config.CustomInventory then
             if not xPlayer.hasWeapon(itemName) then return end
 
             local _, weapon = xPlayer.getWeapon(itemName)
+            if not weapon then
+                return
+            end
+
             local _, weaponObject = ESX.GetWeapon(itemName)
             -- luacheck: ignore weaponPickupLabel
             local weaponPickupLabel = ""
@@ -569,6 +594,11 @@ if not Config.CustomInventory then
     RegisterNetEvent("esx:useItem", function(itemName)
         local source = source
         local xPlayer = ESX.GetPlayerFromId(source)
+
+        if not xPlayer then
+            return
+        end
+
         local count = xPlayer.getInventoryItem(itemName).count
 
         if count < 1 then
@@ -581,6 +611,10 @@ if not Config.CustomInventory then
     RegisterNetEvent("esx:onPickup", function(pickupId)
         local pickup, xPlayer, success = Core.Pickups[pickupId], ESX.GetPlayerFromId(source)
 
+        if not xPlayer then
+            return
+        end
+
         if not pickup then return end
 
         local playerPickupDistance = #(pickup.coords - xPlayer.getCoords(true))
@@ -623,6 +657,10 @@ end
 ESX.RegisterServerCallback("esx:getPlayerData", function(source, cb)
     local xPlayer = ESX.GetPlayerFromId(source)
 
+    if not xPlayer then
+        return
+    end
+
     cb({
         identifier = xPlayer.identifier,
         accounts = xPlayer.getAccounts(),
@@ -646,6 +684,10 @@ end)
 ESX.RegisterServerCallback("esx:getOtherPlayerData", function(_, cb, target)
     local xPlayer = ESX.GetPlayerFromId(target)
 
+    if not xPlayer then
+        return
+    end
+
     cb({
         identifier = xPlayer.identifier,
         accounts = xPlayer.getAccounts(),

[core]/es_extended/server/main.lua

@@ -98,7 +98,7 @@ end
 ---@param player number playerId
 ---@param eventName string
 ---@param ... any
----@return any
+---@return ...
 function ESX.AwaitClientCallback(player, eventName, ...)
     local invokingResource = GetInvokingResource()
     local invoker = (invokingResource and invokingResource ~= "Unknown") and invokingResource or "es_extended"

[core]/es_extended/server/modules/callback.lua

@@ -76,14 +76,15 @@ end
 
 ---@param weaponName string
 ---@param weaponComponent string
----@return table | nil
+---@return ESXWeaponComponent?
 function ESX.GetWeaponComponent(weaponName, weaponComponent)
     weaponName = string.upper(weaponName)
 
     assert(weaponsByName[weaponName], "Invalid weapon name!")
     local weapon = Config.Weapons[weaponsByName[weaponName]]
 
     for _, component in ipairs(weapon.components) do
+        ---@cast component ESXWeaponComponent
         if component.name == weaponComponent then
             return component
         end