@quenty/textfilterutils 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/textfilterutils@5.0.0...@quenty/textfilterutils@5.1.0) (2022-07-31)
+
+**Note:** Version bump only for package @quenty/textfilterutils
+
+
+
+
+
 # [5.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/textfilterutils@4.2.0...@quenty/textfilterutils@5.0.0) (2022-05-21)
 
 **Note:** Version bump only for package @quenty/textfilterutils

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/textfilterutils",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Utility functions for filtering text",
   "keywords": [
     "Roblox",
@@ -26,10 +26,10 @@
   ],
   "dependencies": {
     "@quenty/loader": "^5.0.0",
-    "@quenty/promise": "^5.0.0"
+    "@quenty/promise": "^5.1.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9f7eaea7543c33c89d2e32c38491b13f9271f4f7"
+  "gitHead": "e31b3a35aa475bb5699a24898a8639e107165b36"
 }

package/src/Shared/TextFilterUtils.lua

@@ -1,5 +1,6 @@
 --[=[
-	Utility functions for filtering text
+	Utility functions for filtering text wrapping [TextService] and legacy [Chat] API surfaces.
+
 	@class TextFilterUtils
 ]=]
 
@@ -12,18 +13,44 @@ local Promise = require("Promise")
 
 local TextFilterUtils = {}
 
-function TextFilterUtils.promiseNonChatStringForBroadcast(str, fromUserId, textContext)
-	assert(type(str) == "string", "Bad str")
+--[=[
+	Returns a filtered string for broadcast. Tends to look like this:
+
+	```lua
+	TextFilterUtils.promiseNonChatStringForBroadcast(text, player.UserId, Enum.TextFilterContext.PublicChat)
+		:Then(function(filtered)
+			print(filtered)
+		end)
+	```
+
+	The two options for textFilterContext are `Enum.TextFilterContext.PublicChat` and `Enum.TextFilterContext.PrivateChat`.
+
+	@param text string
+	@param fromUserId number
+	@param textFilterContext TextFilterContext
+	@return Promise<string>
+]=]
+function TextFilterUtils.promiseNonChatStringForBroadcast(text, fromUserId, textFilterContext)
+	assert(type(text) == "string", "Bad text")
 	assert(type(fromUserId) == "number", "Bad fromUserId")
-	assert(typeof(textContext) == "EnumItem", "Bad textContext")
+	assert(typeof(textFilterContext) == "EnumItem", "Bad textFilterContext")
 
 	return TextFilterUtils._promiseTextResult(
 		TextFilterUtils.getNonChatStringForBroadcastAsync,
-		str,
+		text,
 		fromUserId,
-		textContext)
+		textFilterContext)
 end
 
+--[=[
+	Legacy filter broadcast using the `Chat:FilterStringForBroadcast` API call. It's recommended
+	you use [TextFilterUtils.promiseNonChatStringForBroadcast] instead.
+
+
+	@param playerFrom Player
+	@param text string
+	@return Promise<string>
+]=]
 function TextFilterUtils.promiseLegacyChatFilter(playerFrom, text)
 	assert(typeof(playerFrom) == "Instance" and playerFrom:IsA("Player"), "Bad playerFrom")
 	assert(type(text) == "string", "Bad text")
@@ -44,63 +71,90 @@ function TextFilterUtils.promiseLegacyChatFilter(playerFrom, text)
 	end)
 end
 
-function TextFilterUtils.promiseNonChatStringForUserAsync(str, fromUserId, toUserId, textContext)
-	assert(type(str) == "string", "Bad str")
+--[=[
+	Returns a filtered string for a specific user to another user. This is preferable over broadcast if
+	possible.
+
+	@param text string
+	@param fromUserId number
+	@param toUserId number
+	@param textFilterContext TextFilterContext
+	@return Promise<string>
+]=]
+function TextFilterUtils.promiseNonChatStringForUserAsync(text, fromUserId, toUserId, textFilterContext)
+	assert(type(text) == "string", "Bad text")
 	assert(type(fromUserId) == "number", "Bad fromUserId")
 	assert(type(toUserId) == "number", "Bad toUserId")
-	assert(typeof(textContext) == "EnumItem", "Bad textContext")
+	assert(typeof(textFilterContext) == "EnumItem", "Bad textFilterContext")
 
 	return TextFilterUtils._promiseTextResult(
 		TextFilterUtils.getNonChatStringForUserAsync,
-		str,
+		text,
 		fromUserId,
 		toUserId,
-		textContext)
+		textFilterContext)
 end
 
-function TextFilterUtils.getNonChatStringForBroadcastAsync(str, fromUserId, textContext)
-	assert(type(str) == "string", "Bad str")
+--[=[
+	Blocking call to get a non-chat string for broadcast. Wraps [TextService.FilterStringAsync].
+
+	@param text string
+	@param fromUserId number
+	@param textFilterContext TextFilterContext
+	@return Promise<string>
+]=]
+function TextFilterUtils.getNonChatStringForBroadcastAsync(text, fromUserId, textFilterContext)
+	assert(type(text) == "string", "Bad text")
 	assert(type(fromUserId) == "number", "Bad fromUserId")
-	assert(typeof(textContext) == "EnumItem", "Bad textContext")
+	assert(typeof(textFilterContext) == "EnumItem", "Bad textFilterContext")
 
-	local text = nil
+	local resultText = nil
 	local ok, err = pcall(function()
-		local result = TextService:FilterStringAsync(str, fromUserId, textContext)
+		local result = TextService:FilterStringAsync(text, fromUserId, textFilterContext)
 		if not result then
 			error("No TextFilterResult")
 		end
 
-		text = result:GetNonChatStringForBroadcastAsync()
+		resultText = result:GetNonChatStringForBroadcastAsync()
 	end)
 
 	if not ok then
 		return false, err
 	end
 
-	return text
+	return resultText
 end
 
-function TextFilterUtils.getNonChatStringForUserAsync(str, fromUserId, toUserId, textContext)
-	assert(type(str) == "string", "Bad str")
+--[=[
+	Blocking call to get a non-chat string for a user.
+
+	@param text string
+	@param fromUserId number
+	@param toUserId number
+	@param textFilterContext TextFilterContext
+	@return Promise<string>
+]=]
+function TextFilterUtils.getNonChatStringForUserAsync(text, fromUserId, toUserId, textFilterContext)
+	assert(type(text) == "string", "Bad text")
 	assert(type(fromUserId) == "number", "Bad fromUserId")
 	assert(type(toUserId) == "number", "Bad toUserId")
-	assert(typeof(textContext) == "EnumItem", "Bad textContext")
+	assert(typeof(textFilterContext) == "EnumItem", "Bad textFilterContext")
 
-	local text = nil
+	local textResult = nil
 	local ok, err = pcall(function()
-		local result = TextService:FilterStringAsync(str, fromUserId, textContext)
+		local result = TextService:FilterStringAsync(text, fromUserId, textFilterContext)
 		if not result then
 			error("No TextFilterResult")
 		end
 
-		text = result:GetNonChatStringForUserAsync(toUserId)
+		textResult = result:GetNonChatStringForUserAsync(toUserId)
 	end)
 
 	if not ok then
 		return false, err
 	end
 
-	return text
+	return textResult
 end
 
 function TextFilterUtils._promiseTextResult(getResult, ...)