@quenty/settings 4.12.0 → 4.13.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.13.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/settings@4.12.0...@quenty/settings@4.13.0) (2023-01-17)
+
+
+### Bug Fixes
+
+* Ensure that Settings can't contain invalid UTF8 characters and document settings package better ([cbf1406](https://github.com/Quenty/NevermoreEngine/commit/cbf140620795846daf35ce6945bcdf801e1156f9))
+
+
+
+
+
 # [4.12.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/settings@4.11.1...@quenty/settings@4.12.0) (2023-01-11)
 
 **Note:** Version bump only for package @quenty/settings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/settings",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "Centralized player settings service",
   "keywords": [
     "Roblox",
@@ -25,10 +25,10 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/attributeutils": "^8.4.0",
+    "@quenty/attributeutils": "^8.5.0",
     "@quenty/baseobject": "^6.0.1",
     "@quenty/binder": "^8.6.0",
-    "@quenty/datastore": "^7.4.1",
+    "@quenty/datastore": "^7.5.0",
     "@quenty/enumutils": "^3.0.0",
     "@quenty/jsonutils": "^6.0.1",
     "@quenty/loader": "^6.0.1",
@@ -51,5 +51,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "db2db00ab4e24a3eab0449b77a00bee6d91f2755"
+  "gitHead": "a89a3f27cad25767cd645b91cdc2a2881afeecd5"
 }

package/src/Client/Player/PlayerSettingsClient.lua

@@ -1,4 +1,8 @@
 --[=[
+	A player's current settings. Handles replication back to the server
+	when a setting changes. See [PlayerSettingsBase].
+
+	@client
 	@class PlayerSettingsClient
 ]=]
 
@@ -6,14 +10,15 @@ local require = require(script.Parent.loader).load(script)
 
 local Players = game:GetService("Players")
 
+local DataStoreStringUtils = require("DataStoreStringUtils")
+local Maid = require("Maid")
+local Observable = require("Observable")
 local PlayerSettingsBase = require("PlayerSettingsBase")
 local PlayerSettingsConstants = require("PlayerSettingsConstants")
-local RemoteFunctionUtils = require("RemoteFunctionUtils")
 local PlayerSettingsUtils = require("PlayerSettingsUtils")
-local ThrottledFunction = require("ThrottledFunction")
-local Maid = require("Maid")
+local RemoteFunctionUtils = require("RemoteFunctionUtils")
 local Symbol = require("Symbol")
-local Observable = require("Observable")
+local ThrottledFunction = require("ThrottledFunction")
 local ValueObject = require("ValueObject")
 
 local UNSET_VALUE = Symbol.named("unsetValue")
@@ -24,8 +29,15 @@ PlayerSettingsClient.__index = PlayerSettingsClient
 
 require("PromiseRemoteFunctionMixin"):Add(PlayerSettingsClient, PlayerSettingsConstants.REMOTE_FUNCTION_NAME)
 
-function PlayerSettingsClient.new(obj, serviceBag)
-	local self = setmetatable(PlayerSettingsBase.new(obj, serviceBag), PlayerSettingsClient)
+--[=[
+	See [SettingsBindersClient] and [SettingsServiceClient] on how to properly use this class.
+
+	@param folder Folder
+	@param serviceBag ServiceBag
+	@return PlayerSettingsClient
+]=]
+function PlayerSettingsClient.new(folder, serviceBag)
+	local self = setmetatable(PlayerSettingsBase.new(folder, serviceBag), PlayerSettingsClient)
 
 	if self:GetPlayer() == Players.LocalPlayer then
 		self._toReplicate = nil
@@ -48,6 +60,13 @@ function PlayerSettingsClient.new(obj, serviceBag)
 	return self
 end
 
+--[=[
+	Gets a settings value
+
+	@param settingName string
+	@param defaultValue T
+	@return T
+]=]
 function PlayerSettingsClient:GetValue(settingName, defaultValue)
 	assert(type(settingName) == "string", "Bad settingName")
 
@@ -63,6 +82,13 @@ function PlayerSettingsClient:GetValue(settingName, defaultValue)
 	return getmetatable(PlayerSettingsClient).GetValue(self, settingName, defaultValue)
 end
 
+--[=[
+	Observes a settings value.
+
+	@param settingName string
+	@param defaultValue T
+	@return Observable<T>
+]=]
 function PlayerSettingsClient:ObserveValue(settingName, defaultValue)
 	assert(type(settingName) == "string", "Bad settingName")
 
@@ -128,9 +154,24 @@ function PlayerSettingsClient:ObserveValue(settingName, defaultValue)
 	end)
 end
 
+--[=[
+	Sets a settings value and replicates the value eventually (in a de-duplicated manner).
+
+	@param settingName string
+	@param value T
+]=]
 function PlayerSettingsClient:SetValue(settingName, value)
 	assert(type(settingName) == "string", "Bad settingName")
 	assert(self:GetPlayer() == Players.LocalPlayer, "Cannot set settings of another player")
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
+
+	if type(value) == "string" then
+		assert(DataStoreStringUtils.isValidUTF8(value), "Invalid string")
+
+		if (#value + #settingName) > PlayerSettingsConstants.MAX_SETTINGS_LENGTH then
+			error(string.format("[PlayerSettingsClient.SetValue] - Setting is too long for %q", settingName))
+		end
+	end
 
 	local queueReplication = false
 	if not self._toReplicate then

package/src/Client/SettingsServiceClient.lua

@@ -1,4 +1,8 @@
 --[=[
+	Provides access to settings on the client. See [SettingDefinition] which should
+	register settings on the server. See [SettingsService] for server component.
+
+	@client
 	@class SettingsServiceClient
 ]=]
 
@@ -11,6 +15,11 @@ local Rx = require("Rx")
 
 local SettingsServiceClient = {}
 
+--[=[
+	Initializes the setting service. Should be done via ServiceBag.
+
+	@param serviceBag ServiceBag
+]=]
 function SettingsServiceClient:Init(serviceBag)
 	assert(not self._serviceBag, "Already initialized")
 	self._serviceBag = assert(serviceBag, "No serviceBag")
@@ -20,40 +29,85 @@ function SettingsServiceClient:Init(serviceBag)
 	self._binders = self._serviceBag:GetService(require("SettingsBindersClient"))
 end
 
+--[=[
+	Gets the local player settings
+	@return PlayerSettingsClient | nil
+]=]
 function SettingsServiceClient:GetLocalPlayerSettings()
 	return self:GetPlayerSettings(Players.LocalPlayer)
 end
 
+--[=[
+	Observes the local player settings in a brio
+
+	@return Observable<Brio<PlayerSettingsClient>>
+]=]
 function SettingsServiceClient:ObserveLocalPlayerSettingsBrio()
 	return self:ObservePlayerSettingsBrio(Players.LocalPlayer)
 end
 
+--[=[
+	Observes the local player settings
+
+	@return Observable<PlayerSettingsClient | nil>
+]=]
 function SettingsServiceClient:ObserveLocalPlayerSettings()
 	return self:ObservePlayerSettings(Players.LocalPlayer)
 end
 
+--[=[
+	Promises the local player settings
+
+	@param cancelToken CancellationToken
+	@return Promise<PlayerSettingsClient>
+]=]
 function SettingsServiceClient:PromiseLocalPlayerSettings(cancelToken)
 	return self:PromisePlayerSettings(Players.LocalPlayer, cancelToken)
 end
 
+--[=[
+	Observes the player settings
+
+	@param player Player
+	@return Observable<PlayerSettingsClient | nil>
+]=]
 function SettingsServiceClient:ObservePlayerSettings(player)
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
 
 	return PlayerSettingsUtils.observePlayerSettings(self._binders.PlayerSettings, player)
 end
 
+--[=[
+	Observes the player settings in a brio
+
+	@param player Player
+	@return Observable<Brio<PlayerSettingsClient>>
+]=]
 function SettingsServiceClient:ObservePlayerSettingsBrio(player)
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
 
 	return PlayerSettingsUtils.observePlayerSettingsBrio(self._binders.PlayerSettings, player)
 end
 
+--[=[
+	Gets a player's settings
+
+	@param player Player
+	@return PlayerSettingsClient | nil
+]=]
 function SettingsServiceClient:GetPlayerSettings(player)
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
 
 	return PlayerSettingsUtils.getPlayerSettings(self._binders.PlayerSettings, player)
 end
 
+--[=[
+	Promises the player's settings
+
+	@param player Player
+	@param cancelToken CancellationToken
+	@return Promise<PlayerSettingsClient>
+]=]
 function SettingsServiceClient:PromisePlayerSettings(player, cancelToken)
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
 

package/src/Server/Player/PlayerHasSettings.lua

@@ -8,6 +8,8 @@ local BaseObject = require("BaseObject")
 local PlayerSettingsUtils = require("PlayerSettingsUtils")
 local SettingsBindersServer = require("SettingsBindersServer")
 local PlayerDataStoreService = require("PlayerDataStoreService")
+local DataStoreStringUtils = require("DataStoreStringUtils")
+local PlayerSettingsConstants = require("PlayerSettingsConstants")
 
 local PlayerHasSettings = setmetatable({}, BaseObject)
 PlayerHasSettings.ClassName = "PlayerHasSettings"
@@ -64,7 +66,21 @@ function PlayerHasSettings:_handleAttributeChanged(subStore, attributeName)
 
 	-- Write the new value
 	local settingName = PlayerSettingsUtils.getSettingName(attributeName)
+	if not DataStoreStringUtils.isValidUTF8(settingName) then
+		warn(string.format("[PlayerHasSettings] - Bad settingName %q, cannot save", settingName))
+		return
+	end
+
 	local newValue = PlayerSettingsUtils.decodeForAttribute(self._settings:GetAttribute(attributeName))
+
+	if type(newValue) == "string" then
+		if (#settingName + #newValue) > PlayerSettingsConstants.MAX_SETTINGS_LENGTH then
+			warn(string.format("[PlayerSettingsClient.SetValue] - Setting is too long for %q. Cannot save.", settingName))
+			return
+		end
+		-- TODO: JSON encode and check length for ther scenarios
+	end
+
 	subStore:Store(settingName, newValue)
 end
 

package/src/Server/Player/PlayerSettings.lua

@@ -8,6 +8,7 @@ local PlayerSettingsBase = require("PlayerSettingsBase")
 local PlayerSettingsConstants = require("PlayerSettingsConstants")
 local PlayerSettingsUtils = require("PlayerSettingsUtils")
 local SettingRegistryServiceShared = require("SettingRegistryServiceShared")
+local DataStoreStringUtils = require("DataStoreStringUtils")
 
 local PlayerSettings = setmetatable({}, PlayerSettingsBase)
 PlayerSettings.ClassName = "PlayerSettings"
@@ -42,12 +43,25 @@ function PlayerSettings.new(obj, serviceBag)
 end
 
 function PlayerSettings:EnsureInitialized(settingName, defaultValue)
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
 	assert(defaultValue ~= nil, "defaultValue cannot be nil")
 
 	local attributeName = PlayerSettingsUtils.getAttributeName(settingName)
 
+	-- Paranoid UTF8 check. Don't even initialize this setting.
+	if type(defaultValue) == "string" then
+		assert(DataStoreStringUtils.isValidUTF8(defaultValue), "Bad UTF8 defaultValue")
+	end
+
 	if self._obj:GetAttribute(attributeName) == nil then
-		self._obj:SetAttribute(attributeName, PlayerSettingsUtils.encodeForAttribute(defaultValue))
+		local encoded = PlayerSettingsUtils.encodeForAttribute(defaultValue)
+
+		-- Paranoid UTF8 check
+		if type(encoded) == "string" then
+			assert(DataStoreStringUtils.isValidUTF8(defaultValue), "Bad UTF8 defaultValue")
+		end
+
+		self._obj:SetAttribute(attributeName, encoded)
 	end
 end
 
@@ -67,6 +81,12 @@ function PlayerSettings:_setSettings(settingsMap)
 	for settingName, value in pairs(settingsMap) do
 		assert(type(settingName) == "string", "Bad key")
 
+		-- Avoid even letting these be set.
+		if not DataStoreStringUtils.isValidUTF8(settingName) then
+			warn("[PlayerSettings] - Bad UTF8 settingName. Skipping setting.")
+			continue
+		end
+
 		local attributeName = PlayerSettingsUtils.getAttributeName(settingName)
 
 		if self._obj:GetAttribute(attributeName) == nil then
@@ -74,8 +94,32 @@ function PlayerSettings:_setSettings(settingsMap)
 			continue
 		end
 
+		-- Paranoid UTF8 check. Avoid letting this value be set.
+		if type(value) == "string" then
+			if not DataStoreStringUtils.isValidUTF8(value) then
+				warn(string.format("[PlayerSettings] - Bad UTF8 value setting value for %q. Skipping setting.", settingName))
+				continue
+			end
+		end
+
 		local decoded = PlayerSettingsUtils.decodeForNetwork(value)
-		self._obj:SetAttribute(attributeName, PlayerSettingsUtils.encodeForAttribute(decoded))
+		local encodedAttribute = PlayerSettingsUtils.encodeForAttribute(decoded)
+
+		if type(encodedAttribute) == "string" then
+			-- Paranoid UTF8 check. Avoid letting this value be set.
+			if not DataStoreStringUtils.isValidUTF8(encodedAttribute) then
+				warn(string.format("[PlayerSettings] - Bad UTF8 encodedAttribute value for %q. Skipping setting.", settingName))
+				continue
+			end
+
+			-- Paranoid length check. One setting could prevent all from saving if we overflow our save limit.
+			if (#encodedAttribute + #settingName) > PlayerSettingsConstants.MAX_SETTINGS_LENGTH then
+				warn(string.format("[PlayerSettings] - Setting %q is too long. Skipping setting.", settingName))
+				continue
+			end
+		end
+
+		self._obj:SetAttribute(attributeName, encodedAttribute)
 	end
 end
 

package/src/Shared/Player/PlayerSettingsBase.lua

@@ -1,4 +1,6 @@
 --[=[
+	Base class for player settings.
+
 	@class PlayerSettingsBase
 ]=]
 
@@ -9,13 +11,21 @@ local PlayerSettingsUtils = require("PlayerSettingsUtils")
 local RxAttributeUtils = require("RxAttributeUtils")
 local SettingDefinition = require("SettingDefinition")
 local Rx = require("Rx")
+local DataStoreStringUtils = require("DataStoreStringUtils")
 
 local PlayerSettingsBase = setmetatable({}, BaseObject)
 PlayerSettingsBase.ClassName = "PlayerSettingsBase"
 PlayerSettingsBase.__index = PlayerSettingsBase
 
-function PlayerSettingsBase.new(obj, serviceBag)
-	local self = setmetatable(BaseObject.new(obj), PlayerSettingsBase)
+--[=[
+	Base class for player settings
+
+	@param folder Folder
+	@param serviceBag ServiceBag
+	@return PlayerSettingsBase
+]=]
+function PlayerSettingsBase.new(folder, serviceBag)
+	local self = setmetatable(BaseObject.new(folder), PlayerSettingsBase)
 
 	self._serviceBag = assert(serviceBag, "No serviceBag")
 
@@ -65,6 +75,7 @@ end
 function PlayerSettingsBase:GetValue(settingName, defaultValue)
 	assert(type(settingName) == "string", "Bad settingName")
 	assert(defaultValue ~= nil, "defaultValue cannot be nil")
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
 
 	local attributeName = PlayerSettingsUtils.getAttributeName(settingName)
 
@@ -87,6 +98,7 @@ end
 ]=]
 function PlayerSettingsBase:SetValue(settingName, value)
 	assert(type(settingName) == "string", "Bad settingName")
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
 
 	local attributeName = PlayerSettingsUtils.getAttributeName(settingName)
 
@@ -103,6 +115,7 @@ end
 function PlayerSettingsBase:ObserveValue(settingName, defaultValue)
 	assert(type(settingName) == "string", "Bad settingName")
 	assert(defaultValue ~= nil, "defaultValue cannot be nil")
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
 
 	local attributeName = PlayerSettingsUtils.getAttributeName(settingName)
 
@@ -114,7 +127,16 @@ function PlayerSettingsBase:ObserveValue(settingName, defaultValue)
 		})
 end
 
+--[=[
+	Restores the default value for the setting
+
+	@param settingName string
+	@param defaultValue T
+]=]
 function PlayerSettingsBase:RestoreDefault(settingName, defaultValue)
+	assert(type(settingName) == "string", "Bad settingName")
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
+
 	-- TODO: Maybe something more sophisticated?
 	self:SetValue(settingName, defaultValue)
 end
@@ -128,6 +150,7 @@ end
 function PlayerSettingsBase:EnsureInitialized(settingName, defaultValue)
 	assert(type(settingName) == "string", "Bad settingName")
 	assert(defaultValue ~= nil, "defaultValue cannot be nil")
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
 
 	-- noop
 end

package/src/Shared/Player/PlayerSettingsConstants.lua

@@ -14,4 +14,5 @@ return Table.readonly({
 	PLAYER_SETTINGS_NAME = "PlayerSettings";
 	REMOTE_FUNCTION_NAME = "PlayerSettingsRemoteFunction";
 	REQUEST_UPDATE_SETTINGS = "requestUpdateSettings";
+	MAX_SETTINGS_LENGTH = 2048;
 })

package/src/Shared/Player/PlayerSettingsUtils.lua

@@ -1,4 +1,6 @@
 --[=[
+	Utility helpers to work with settings.
+
 	@class PlayerSettingsUtils
 ]=]
 
@@ -11,9 +13,16 @@ local BinderUtils = require("BinderUtils")
 local Binder = require("Binder")
 local RxStateStackUtils = require("RxStateStackUtils")
 local EnumUtils = require("EnumUtils")
+local DataStoreStringUtils = require("DataStoreStringUtils")
 
 local PlayerSettingsUtils = {}
 
+--[=[
+	Creates a new player settings
+
+	@param binder Binder<PlayerSettings>
+	@return Folder
+]=]
 function PlayerSettingsUtils.create(binder)
 	assert(Binder.isBinder(binder), "No binder")
 
@@ -25,6 +34,13 @@ function PlayerSettingsUtils.create(binder)
 	return playerSettings
 end
 
+--[=[
+	Observe a player settings for a player.
+
+	@param binder Binder<PlayerSettings>
+	@param player Player
+	@return Observable<PlayerSettings>
+]=]
 function PlayerSettingsUtils.observePlayerSettingsBrio(binder, player)
 	assert(Binder.isBinder(binder), "No binder")
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
@@ -32,12 +48,26 @@ function PlayerSettingsUtils.observePlayerSettingsBrio(binder, player)
 	return RxBinderUtils.observeBoundChildClassBrio(binder, player)
 end
 
+--[=[
+	Observe a player's latest settings
+
+	@param binder Binder<PlayerSettings>
+	@param player Player
+	@return Observable<PlayerSettings>
+]=]
 function PlayerSettingsUtils.observePlayerSettings(binder, player)
 	return RxBinderUtils.observeBoundChildClassBrio(binder, player):Pipe({
 		RxStateStackUtils.topOfStack()
 	})
 end
 
+--[=[
+	Gets a player's latest settings
+
+	@param binder Binder<PlayerSettings>
+	@param player Player
+	@return PlayerSettings
+]=]
 function PlayerSettingsUtils.getPlayerSettings(binder, player)
 	assert(Binder.isBinder(binder), "No binder")
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
@@ -45,25 +75,50 @@ function PlayerSettingsUtils.getPlayerSettings(binder, player)
 	return BinderUtils.findFirstChild(binder, player)
 end
 
+--[=[
+	Gets the attribute name for a setting
+
+	@param settingName string
+	@return string
+]=]
 function PlayerSettingsUtils.getAttributeName(settingName)
 	assert(type(settingName) == "string", "Bad settingName")
+	assert(DataStoreStringUtils.isValidUTF8(settingName), "Bad settingName")
 
 	return PlayerSettingsConstants.SETTING_ATTRIBUTE_PREFIX .. settingName
 end
 
+--[=[
+	Gets the settings name from an attribute. May return a string
+	that cannot be loaded into datastore.
+
+	@param attributeName string
+	@return string
+]=]
 function PlayerSettingsUtils.getSettingName(attributeName)
 	assert(type(attributeName) == "string", "Bad attributeName")
 
-	attributeName = String.removePrefix(attributeName, PlayerSettingsConstants.SETTING_ATTRIBUTE_PREFIX)
-	return attributeName
+	return String.removePrefix(attributeName, PlayerSettingsConstants.SETTING_ATTRIBUTE_PREFIX)
 end
 
+--[=[
+	Returns true if the attribute name is a settings attribute
+
+	@param attributeName string
+	@return string
+]=]
 function PlayerSettingsUtils.isSettingAttribute(attributeName)
 	assert(type(attributeName) == "string", "Bad attributeName")
 
 	return String.startsWith(attributeName, PlayerSettingsConstants.SETTING_ATTRIBUTE_PREFIX)
 end
 
+--[=[
+	Encodes a given value for network transfer
+
+	@param settingValue any
+	@return any
+]=]
 function PlayerSettingsUtils.encodeForNetwork(settingValue)
 	assert(settingValue ~= "<NIL_SETTING_VALUE>", "Cannot have setting as <NIL_SETTING_VALUE>")
 
@@ -76,6 +131,12 @@ function PlayerSettingsUtils.encodeForNetwork(settingValue)
 	end
 end
 
+--[=[
+	Decodes a given value from network transfer
+
+	@param settingValue any
+	@return any
+]=]
 function PlayerSettingsUtils.decodeForNetwork(settingValue)
 	if settingValue == "<NIL_SETTING_VALUE>" then
 		return nil
@@ -86,6 +147,12 @@ function PlayerSettingsUtils.decodeForNetwork(settingValue)
 	end
 end
 
+--[=[
+	Decodes a given value for attribute storage
+
+	@param settingValue any
+	@return any
+]=]
 function PlayerSettingsUtils.decodeForAttribute(settingValue)
 	if EnumUtils.isEncodedEnum(settingValue) then
 		return EnumUtils.decodeFromString(settingValue)
@@ -94,6 +161,12 @@ function PlayerSettingsUtils.decodeForAttribute(settingValue)
 	end
 end
 
+--[=[
+	Encodes a given value for attribute storage
+
+	@param settingValue any
+	@return any
+]=]
 function PlayerSettingsUtils.encodeForAttribute(settingValue)
 	if typeof(settingValue) == "EnumItem" then
 		return EnumUtils.encodeAsString(settingValue)
@@ -102,5 +175,4 @@ function PlayerSettingsUtils.encodeForAttribute(settingValue)
 	end
 end
 
-
 return PlayerSettingsUtils

package/src/Shared/Setting/SettingDefinition.lua

@@ -1,4 +1,20 @@
 --[=[
+	These settings definitions are used to define a setting and register them on both the client and server. See
+	[SettingDefinitionProvider] for more details on grouping these.
+
+	Notably a setting is basically anything on the client that can be stored on the server by the client, and that
+	relatively minimal validation is required upon. This can be both user-set settings, as well as very temporary
+	data.
+
+	```lua
+	local SettingDefinition = require("SettingDefinition")
+
+	return require("SettingDefinitionProvider").new({
+		SettingDefinition.new("LastTimeUpdateSeen", 0);
+		SettingDefinition.new("LastTimeShopSeen", 0);
+	})
+	```
+
 	@class SettingDefinition
 ]=]
 

package/src/Shared/Setting/SettingDefinitionProvider.lua

@@ -1,4 +1,26 @@
 --[=[
+	Provides settings in bulk, and can be initialized by a [ServiceBag]. See [SettingDefinition] for
+	more details on how to use this.
+
+	:::tip
+	These settings providers should be used on both the client and the server. On the client, these
+	are registered with the [SettingRegistryServiceShared] so that they can be shown in UI automatically
+	if desired.
+
+	On the server, these are registered with [SettingRegistryServiceShared] and then are checked before
+	arbitrary data can e sent.
+	:::
+
+	```lua
+	local SettingDefinition = require("SettingDefinition")
+
+	return require("SettingDefinitionProvider").new({
+		SettingDefinition.new("KeyBinding", Enum.KeyCode.X);
+		SettingDefinition.new("CameraShake", true);
+		SettingDefinition.new("CameraSensitivity", 1);
+	})
+	```
+
 	@class SettingDefinitionProvider
 ]=]
 
@@ -12,6 +34,22 @@ SettingDefinitionProvider.ClassName = "SettingDefinitionProvider"
 SettingDefinitionProvider.ServiceName = "SettingDefinitionProvider"
 SettingDefinitionProvider.__index = SettingDefinitionProvider
 
+--[=[
+	Constructs a new provider with a list of [SettingDefinition]'s.
+
+	```lua
+	local SettingDefinition = require("SettingDefinition")
+
+	return require("SettingDefinitionProvider").new({
+		SettingDefinition.new("KeyBinding", Enum.KeyCode.X);
+		SettingDefinition.new("CameraShake", true);
+		SettingDefinition.new("CameraSensitivity", 1);
+	})
+	```
+
+	@param settingDefinitions { SettingDefinition }
+	@return SettingDefinitionProvider
+]=]
 function SettingDefinitionProvider.new(settingDefinitions)
 	local self = setmetatable({}, SettingDefinitionProvider)
 
@@ -26,6 +64,11 @@ function SettingDefinitionProvider.new(settingDefinitions)
 	return self
 end
 
+--[=[
+	Initializes the provider, storing the data in [SettingRegistryServiceShared]
+
+	@param serviceBag ServiceBag
+]=]
 function SettingDefinitionProvider:Init(serviceBag)
 	assert(serviceBag, "No serviceBag")
 	assert(not self._maid, "Already initialized")
@@ -38,16 +81,47 @@ function SettingDefinitionProvider:Init(serviceBag)
 	end
 end
 
+--[=[
+	Starts the provider. Empty.
+]=]
 function SettingDefinitionProvider:Start()
 	-- Empty, to prevent us from erroring on service bag init
 end
 
+--[=[
+	Returns the setting definition
+
+	@return { SettingDefinition }
+]=]
 function SettingDefinitionProvider:GetSettingDefinitions()
 	return self._settingDefinitions
 end
 
+--[=[
+	You can index the provider to get a setting. For example
+
+	```lua
+	local SettingDefinition = require("SettingDefinition")
+
+	local provider = require("SettingDefinitionProvider").new({
+		SettingDefinition.new("KeyBinding", Enum.KeyCode.X);
+		SettingDefinition.new("CameraShake", true);
+		SettingDefinition.new("CameraSensitivity", 1);
+	})
+
+	local service = serviceBag:GetService(provider)
+
+	-- Write a setting
+	service.CamaraShake:GetLocalPlayerSettingProperty(serviceBag).Value = false
+	```
+
+	@param index string
+	@return SettingDefinition
+]=]
 function SettingDefinitionProvider:__index(index)
-	if SettingDefinitionProvider[index] then
+	if index == nil then
+		error("[SettingDefinitionProvider] - Cannot index provider with nil value")
+	elseif SettingDefinitionProvider[index] then
 		return SettingDefinitionProvider[index]
 	elseif index == "_lookup" or index == "_settingDefinitions" or index == "_maid" then
 		return rawget(self, index)
@@ -64,10 +138,21 @@ function SettingDefinitionProvider:__index(index)
 	end
 end
 
+--[=[
+	Gets a new setting definition if it exists
+
+	@param settingName string
+	@return SettingDefinition
+]=]
 function SettingDefinitionProvider:Get(settingName)
+	assert(type(settingName) == "string", "Bad settingName")
+
 	return self._lookup[settingName]
 end
 
+--[=[
+	Cleans up the setting registration
+]=]
 function SettingDefinitionProvider:Destroy()
 	self._maid:DoCleaning()
 end

package/src/Shared/Setting/SettingProperty.lua

@@ -11,6 +11,14 @@ local SettingProperty = {}
 SettingProperty.ClassName = "SettingProperty"
 SettingProperty.__index = SettingProperty
 
+--[=[
+	Constructs a new SettingProperty.
+
+	@param serviceBag ServiceBag
+	@param player Player
+	@param definition SettingDefinition
+	@return SettingProperty<T>
+]=]
 function SettingProperty.new(serviceBag, player, definition)
 	local self = setmetatable({}, SettingProperty)
 
@@ -27,6 +35,10 @@ function SettingProperty.new(serviceBag, player, definition)
 	return self
 end
 
+--[=[
+	Observes the value of the setting property
+	@return Observable<T>
+]=]
 function SettingProperty:Observe()
 	return self:_observePlayerSettings():Pipe({
 		Rx.where(function(settings)
@@ -85,15 +97,29 @@ function SettingProperty:__newindex(index, value)
 	end
 end
 
+--[=[
+	Sets the value of the setting property. Will warn if it cannot do so.
+
+	:::tip
+	Use [PromiseSetValue] to ensure value is set.
+	:::
+
+	@param value T
+]=]
 function SettingProperty:SetValue(value)
 	local settings = self:_getPlayerSettings()
 	if settings then
 		settings:SetValue(self._definition:GetSettingName(), value)
 	else
-		warn("Cannot set setting value. Use :PromiseSetValue() to ensure value is set after load.")
+		warn("[SettingProperty.SetValue] - Cannot set setting value. Use :PromiseSetValue() to ensure value is set after load.")
 	end
 end
 
+--[=[
+	Promises the value of the setting once it's loaded.
+
+	@return Promise<T>
+]=]
 function SettingProperty:PromiseValue()
 	return self:_promisePlayerSettings()
 		:Then(function(playerSettings)
@@ -101,6 +127,12 @@ function SettingProperty:PromiseValue()
 		end)
 end
 
+--[=[
+	Promises to set the value
+
+	@param value T
+	@return Promise
+]=]
 function SettingProperty:PromiseSetValue(value)
 	return self:_promisePlayerSettings()
 		:Then(function(playerSettings)
@@ -108,15 +140,33 @@ function SettingProperty:PromiseSetValue(value)
 		end)
 end
 
+--[=[
+	Restores the setting to the default value
+]=]
 function SettingProperty:RestoreDefault()
 	local settings = self:_getPlayerSettings()
 	if settings then
 		settings:RestoreDefault(self._definition:GetSettingName(), self._definition:GetDefaultValue())
 	else
-		warn("Cannot set setting value. Use :PromiseSetValue() to ensure value is set after load.")
+		warn("[SettingProperty.RestoreDefault] - Cannot set setting value. Use :PromiseRestoreDefault() to ensure value is set after load.")
 	end
 end
 
+--[=[
+	Restores the setting to the default value. This is different than setting to the default value
+	because it means there is no "user-set" value which could lead to values changing if
+	defaults change.
+
+	@return Promise
+]=]
+function SettingProperty:PromiseRestoreDefault()
+	return self:_promisePlayerSettings()
+		:Then(function(playerSettings)
+			playerSettings:RestoreDefault(self._definition:GetSettingName(), self._definition:GetDefaultValue())
+		end)
+end
+
+
 function SettingProperty:_observePlayerSettings()
 	return self._bridge:ObservePlayerSettings(self._player)
 end
@@ -129,6 +179,4 @@ function SettingProperty:_promisePlayerSettings()
 	return self._bridge:PromisePlayerSettings(self._player)
 end
 
-
-
 return SettingProperty

package/src/Shared/SettingRegistryServiceShared.lua

@@ -9,39 +9,81 @@ local require = require(script.Parent.loader).load(script)
 local ValueObject = require("ValueObject")
 local Rx = require("Rx")
 local ObservableSet = require("ObservableSet")
+local Maid = require("Maid")
 
 local SettingRegistryServiceShared = {}
 
+--[=[
+	Initializes the shared registry service. Should be done via [ServiceBag].
+
+	@param serviceBag ServiceBag
+]=]
 function SettingRegistryServiceShared:Init(serviceBag)
 	assert(not self._serviceBag, "Already initialized")
 	self._serviceBag = assert(serviceBag, "No serviceBag")
+	self._maid = Maid.new()
 
 	self._settingService = ValueObject.new()
+	self._maid:GiveTask(self._settingService)
+
 	self._settingDefinitions = ObservableSet.new()
+	self._maid:GiveTask(self._settingDefinitions)
 end
 
+--[=[
+	Registers the shared setting service for this bridge
+
+	@param settingService SettingService
+]=]
 function SettingRegistryServiceShared:RegisterSettingService(settingService)
 	self._settingService.Value = settingService
 end
 
+--[=[
+	Registers settings definitions
+
+	@param definition SettingDefinition
+	@return callback -- Cleanup callback
+]=]
 function SettingRegistryServiceShared:RegisterSettingDefinition(definition)
 	assert(definition, "No definition")
 
 	return self._settingDefinitions:Add(definition)
 end
 
+--[=[
+	Observes the registered definitions
+
+	@return Observable<Brio<SettingDefinition>>
+]=]
 function SettingRegistryServiceShared:ObserveRegisteredDefinitionsBrio()
 	return self._settingDefinitions:ObserveItemsBrio()
 end
 
+--[=[
+	Gets the current settings service
+
+	@return SettingService
+]=]
 function SettingRegistryServiceShared:GetSettingsService()
 	return self._settingService.Value
 end
 
+--[=[
+	Observes the current settings service
+
+	@return Observable<SettingService>
+]=]
 function SettingRegistryServiceShared:ObserveSettingsService()
 	return self._settingService:Observe()
 end
 
+--[=[
+	Observes the player's settings
+
+	@param player Player
+	@return Observable<PlayerSettingsBase>
+]=]
 function SettingRegistryServiceShared:ObservePlayerSettings(player)
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
 
@@ -56,6 +98,12 @@ function SettingRegistryServiceShared:ObservePlayerSettings(player)
 	})
 end
 
+--[=[
+	Promises the player's settings
+
+	@param player Player
+	@return Promise<PlayerSettingsBase>
+]=]
 function SettingRegistryServiceShared:PromisePlayerSettings(player)
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
 
@@ -69,6 +117,12 @@ function SettingRegistryServiceShared:PromisePlayerSettings(player)
 		end)
 end
 
+--[=[
+	Gets the player's settings
+
+	@param player Player
+	@return Promise<PlayerSettingsBase>
+]=]
 function SettingRegistryServiceShared:GetPlayerSettings(player)
 	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
 
@@ -80,4 +134,11 @@ function SettingRegistryServiceShared:GetPlayerSettings(player)
 	end
 end
 
+--[=[
+	Cleans up the shared registry service
+]=]
+function SettingRegistryServiceShared:Destroy()
+	self._maid:DoCleaning()
+end
+
 return SettingRegistryServiceShared