@quenty/friendutils 3.3.0 → 3.4.0-canary.241.a4e8214.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.4.0-canary.241.a4e8214.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/friendutils@3.3.1...@quenty/friendutils@3.4.0-canary.241.a4e8214.0) (2022-01-03)
+
+**Note:** Version bump only for package @quenty/friendutils
+
+
+
+
+
+## [3.3.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/friendutils@3.3.0...@quenty/friendutils@3.3.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/friendutils
+
+
+
+
+
 # [3.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/friendutils@3.2.0...@quenty/friendutils@3.3.0) (2021-12-18)
 
 **Note:** Version bump only for package @quenty/friendutils

package/README.md

@@ -1,10 +1,10 @@
 ## FriendUtils
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,27 +13,9 @@
 
 Utlity functions to help find friends of a user. Also contains utility to make testing in studio easier.
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/FriendUtils">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/friendutils --save
-```
-
-## Usage
-Usage is designed to be simple.
-
-### `FriendUtils.promiseAllStudioFriends()`
-
-### `FriendUtils.onlineFriends(friends)`
-
-### `FriendUtils.friendsNotInGame(friends)`
-
-### `FriendUtils.promiseAllFriends(userId, limitMaxFriends)`
-
-### `FriendUtils.promiseFriendPages(userId)`
-
-### `FriendUtils.iterateFriendsYielding(pages)`
-
-### `FriendUtils.promiseStudioServiceUserId()`
-
-### `FriendUtils.promiseCurrentStudioUserId()`
-
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/friendutils",
-  "version": "3.3.0",
+  "version": "3.4.0-canary.241.a4e8214.0",
   "description": "Utlity functions to help find friends of a user. Also contains utility to make testing in studio easier.",
   "keywords": [
     "Roblox",
@@ -25,11 +25,11 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/loader": "^3.1.1",
-    "@quenty/promise": "^3.3.0"
+    "@quenty/loader": "3.2.0-canary.241.a4e8214.0",
+    "@quenty/promise": "3.4.0-canary.241.a4e8214.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6eb398e9fb81191f0815885f807ab0cb3bb9bad1"
+  "gitHead": "a4e821471f35998d63f38a4f4a578e07b4e79035"
 }

package/src/Shared/FriendUtils.lua

@@ -1,5 +1,7 @@
---- Utlity functions to help find friends of a user. Also contains utility to make testing in studio easier.
--- @module FriendUtils
+--[=[
+	Utlity functions to help find friends of a user. Also contains utility to make testing in studio easier.
+	@class FriendUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,11 +11,36 @@ local Promise = require("Promise")
 
 local FriendUtils = {}
 
+--[=[
+	@interface FriendData
+	.Id number -- The friend's UserId
+	.Username string -- The friend's username
+	.DisplayName string -- The display name of the friend.
+	.IsOnline bool -- If the friend is currently online
+	@within FriendUtils
+]=]
+
+--[=[
+	Returns the current studio users friends
+
+	```lua
+	FriendUtils.promiseAllStudioFriends()
+		:Then(function(studioFriends)
+			print(studioFriends)
+		end)
+	```
+	@return Promise<{ FriendData }>
+]=]
 function FriendUtils.promiseAllStudioFriends()
 	return FriendUtils.promiseCurrentStudioUserId()
 		:Then(FriendUtils.promiseAllFriends)
 end
 
+--[=[
+	Outputs a list of only online friends
+	@param friends { FriendData }
+	@return { FriendData }
+]=]
 function FriendUtils.onlineFriends(friends)
 	local onlineFriends = {}
 	for _, friend in pairs(friends) do
@@ -24,6 +51,11 @@ function FriendUtils.onlineFriends(friends)
 	return onlineFriends
 end
 
+--[=[
+	Outputs a list of only friends not in game
+	@param friends { FriendData }
+	@return { FriendData }
+]=]
 function FriendUtils.friendsNotInGame(friends)
 	local userIdsInGame = {}
 	for _, player in pairs(Players:GetPlayers()) do
@@ -39,7 +71,12 @@ function FriendUtils.friendsNotInGame(friends)
 	return onlineFriends
 end
 
--- @param[opt=nil] limitMaxFriends
+--[=[
+	Retrieves all friends.
+	@param userId number
+	@param limitMaxFriends number? -- Optional max friends
+	@return Promise<{ FriendData }>
+]=]
 function FriendUtils.promiseAllFriends(userId, limitMaxFriends)
 	assert(userId, "Bad userId")
 
@@ -62,6 +99,11 @@ function FriendUtils.promiseAllFriends(userId, limitMaxFriends)
 		end)
 end
 
+--[=[
+	Wraps [Players.GetFriendsAsync]
+	@param userId number
+	@return Promise<FriendPages>
+]=]
 function FriendUtils.promiseFriendPages(userId)
 	assert(type(userId) == "number", "Bad userId")
 
@@ -80,6 +122,11 @@ function FriendUtils.promiseFriendPages(userId)
 	end)
 end
 
+--[=[
+	Iterates over the current FriendPage and returns the next page
+	@param pages FriendPages
+	@return () => FrienData? -- Iterator
+]=]
 function FriendUtils.iterateFriendsYielding(pages)
 	assert(pages, "Bad pages")
 
@@ -100,6 +147,16 @@ function FriendUtils.iterateFriendsYielding(pages)
 	end)
 end
 
+--[=[
+	Gets the current studio user's user id.
+
+	:::tip
+	Consider using [FriendUtils.promiseCurrentStudioUserId] if you want this code
+	to work while the game is running or in team create. This is specific to [StudioService].
+	:::
+
+	@return Promise<number>
+]=]
 function FriendUtils.promiseStudioServiceUserId()
 	return Promise.new(function(resolve, reject)
 		local userId
@@ -119,6 +176,10 @@ function FriendUtils.promiseStudioServiceUserId()
 	end)
 end
 
+--[=[
+	Gets the current studio user's user id.
+	@return Promise<number>
+]=]
 function FriendUtils.promiseCurrentStudioUserId()
 	return FriendUtils.promiseStudioServiceUserId()
 		:Catch(function(...)