@quenty/adorneedata 7.3.0 → 7.4.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.
 
+# [7.4.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/adorneedata@7.3.0...@quenty/adorneedata@7.4.0) (2024-05-18)
+
+
+### Features
+
+* Add AdorneeData docs and ability to use indirectly ([8df4e84](https://github.com/Quenty/NevermoreEngine/commit/8df4e844c027ec196476306d472c7c8e4625c53f))
+
+
+
+
+
 # [7.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/adorneedata@7.2.0...@quenty/adorneedata@7.3.0) (2024-05-09)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/adorneedata",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Bridges attributes and serialization",
   "keywords": [
     "Roblox",
@@ -37,5 +37,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "3fd5cdca3128bf34c8d9dfae1e92d62533b6e6f5"
+  "gitHead": "a9256cab3584bea4bd32c327d00b9a52f2a3ec95"
 }

package/src/Shared/AdorneeData.lua

@@ -7,6 +7,67 @@
 
 	Providing all 3
 
+	## Usage
+	Here's how the usage works:
+
+	```lua
+	-- Store data somewhere central
+
+	return AdorneeData.new({
+		EnableCombat = true;
+		PunchDamage = 15;
+	})
+	```
+
+	You can then use the data to retrieve values
+
+	```lua
+	local data = CombatConfiguration:CreateValue(workspace)
+
+	-- Can ready any data
+	print(data.EnableCombat.Value) --> true
+	print(data.PunchDamage.Value) --> 15
+	print(data.Value) --> { EnableCombat = true, PunchDamage = true }
+
+	-- Can write any data
+	data.EnableCombat.Value = false
+	data.PunchDamage.Value = 15
+	data.Value = {
+		EnableCombat = false;
+		PunchDamage = 150;
+	}
+
+	-- Can subscribe to the data
+	data.EnableCombat:Observe():Subscribe(print)
+	data.PunchDamage:Observe():Subscribe(print)
+	data:Observe():Subscribe(print)
+
+	-- Can also operate without creating a value (although creating value is cheap)
+	local punchDamage = CombatConfiguration.PunchDamage:Create(workspace)
+	punchDamage.Value = 20
+	punchDamage:Observe():Subscribe(print)
+
+	-- Or like this
+	CombatConfiguration.PunchDamage:SetValue(workspace, 25)
+	print(CombatConfiguration.PunchDamage:GetValue(workspace))
+	CombatConfiguration.PunchDamage:Observe(workspace):Subscribe(print)
+
+	-- You can also create validated data
+	local defaultCombatState = CombatConfiguration:CreateData({
+		EnableCombat = true;
+		PunchDamage = 15;
+	})
+
+	-- Or validate that the data you're getting is valid
+	assert(CombatConfiguration:IsData(defaultCombatState))
+
+	-- Or read attributes directly
+	CombatConfiguration:GetAttributes(workspace))
+
+	-- Note that this is the same as an attribute
+	print(workspace:GetAttribute("EnableCombat")) --> true
+	```
+
 	@class AdorneeData
 ]=]
 
@@ -15,6 +76,7 @@ local require = require(script.Parent.loader).load(script)
 local AdorneeDataEntry = require("AdorneeDataEntry")
 local AdorneeDataValue = require("AdorneeDataValue")
 local AttributeUtils = require("AttributeUtils")
+local AttributeValue = require("AttributeValue")
 local t = require("t")
 
 local AdorneeData = {}
@@ -49,6 +111,26 @@ function AdorneeData.new(prototype)
 	return self
 end
 
+function AdorneeData:__index(index)
+	if AdorneeData[index] then
+		return AdorneeData[index]
+	elseif type(index) == "string" then
+		local found = self._fullPrototype[index]
+		if not found then
+			error(string.format("[AdorneeData] - Bad index %q is not a known adornee", index))
+		end
+
+		if AdorneeDataEntry.isAdorneeDataEntry(found) then
+			return found
+		else
+			-- TODO: Cache this construction
+			return AdorneeDataEntry.new(index, function(adornee)
+				return AttributeValue.new(adornee, index, found)
+			end)
+		end
+	end
+end
+
 --[=[
 	Returns true if the data is valid data, otherwise returns false and an error.
 
@@ -165,7 +247,7 @@ function AdorneeData:GetAttributes(adornee)
 
 	-- TODO: Avoid additional allocation
 	for key, value in pairs(self._valueObjectPrototype) do
-		data[key] = value:CreateValueObject(adornee).Value
+		data[key] = value:Create(adornee).Value
 	end
 
 	return self:CreateStrictData(data)
@@ -203,7 +285,7 @@ function AdorneeData:SetStrictAttributes(adornee, data)
 
 	-- TODO: Avoid additional allocation
 	for key, value in pairs(self._valueObjectPrototype) do
-		value:CreateValueObject(adornee).Value = data[key]
+		value:Create(adornee).Value = data[key]
 	end
 end
 
@@ -230,7 +312,7 @@ function AdorneeData:InitAttributes(adornee, data)
 
 	-- TODO: Avoid additional allocation
 	for key, value in pairs(self._valueObjectPrototype) do
-		local valueObject = value:CreateValueObject(adornee)
+		local valueObject = value:Create(adornee)
 		if valueObject == nil then
 			if data[key] ~= nil then
 				valueObject.Value = data[key]
@@ -246,8 +328,9 @@ end
 	@return function
 ]=]
 function AdorneeData:GetStrictTInterface()
-	if self._fullInterface then
-		return self._fullInterface
+	local found = rawget(self, "_fullInterface")
+	if found then
+		return found
 	end
 
 	self._fullInterface = t.strictInterface(self:_getOrCreateTypeInterfaceList())
@@ -261,8 +344,9 @@ end
 	@return function
 ]=]
 function AdorneeData:GetTInterface()
-	if self._interface then
-		return self._interface
+	local found = rawget(self, "_interface")
+	if found then
+		return found
 	end
 
 	local interfaceList = {}
@@ -286,8 +370,9 @@ function AdorneeData:IsData(data)
 end
 
 function AdorneeData:_getOrCreateTypeInterfaceList()
-	if self._typeInterfaceList then
-		return self._typeInterfaceList
+	local found = rawget(self, "_typeInterfaceList")
+	if found then
+		return found
 	end
 
 	local interfaceList = {}

package/src/Shared/AdorneeDataEntry.lua

@@ -1,4 +1,6 @@
 --[=[
+	Declaration for the adornee data value
+
 	@class AdorneeDataEntry
 ]=]
 
@@ -12,6 +14,13 @@ local AdorneeDataEntry = {}
 AdorneeDataEntry.ClassName = "AdorneeDataEntry"
 AdorneeDataEntry.__index = AdorneeDataEntry
 
+--[=[
+	Creates a new adornee data entry
+
+	@param dataType string
+	@param createValueObject (adornee: Instance) -> ValueObject<T>
+	@return AdorneeDataEntry<T>
+]=]
 function AdorneeDataEntry.new(dataType, createValueObject)
 	assert(type(dataType) == "string", "Bad dataType")
 	assert(type(createValueObject) == "function", "Bad createValueObject")
@@ -31,22 +40,95 @@ function AdorneeDataEntry.new(dataType, createValueObject)
 	return self
 end
 
+--[=[
+	Returns true if the implementation is an AdorneeDataEntry
+
+	@param data any
+	@return boolean
+]=]
 function AdorneeDataEntry.isAdorneeDataEntry(data)
 	return DuckTypeUtils.isImplementation(AdorneeDataEntry, data)
 end
 
-function AdorneeDataEntry:CreateValueObject(adornee)
+--[=[
+	Creates a value object for the given adornee
+
+	@param adornee Instance
+	@return ValueObject<T>
+]=]
+function AdorneeDataEntry:Create(adornee)
 	assert(typeof(adornee) == "Instance", "Bad adornee")
 
 	return self._createValueObject(adornee)
 end
 
+--[=[
+	Observes the current value for the adornee
+
+	@param adornee Instance
+	@return Observable<T>
+]=]
+function AdorneeDataEntry:Observe(adornee)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+
+	local valueObject = self:Create(adornee)
+	return valueObject:Observe()
+end
+
+--[=[
+	Gets the value for the adornee
+
+	@param adornee Instance
+	@return T
+]=]
+function AdorneeDataEntry:GetValue(adornee)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+
+	local valueObject = self:Create(adornee)
+
+	return valueObject.Value
+end
+
+--[=[
+	Sets the value for the adornee
+
+	@param adornee Instance
+	@param value T
+]=]
+function AdorneeDataEntry:SetValue(adornee, value)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+	assert(self._strictInterface(value))
+
+	local valueObject = self:CreateValueObject(adornee)
+	valueObject.Value = value
+end
+
+--[=[
+	Gets the default value
+
+	@return T
+]=]
 function AdorneeDataEntry:GetDefaultValue()
 	return self._defaultValue
 end
 
+--[=[
+	Gets the estrict interface for the entry
+
+	@return (value: any) -> (boolean, string)
+]=]
 function AdorneeDataEntry:GetStrictInterface()
 	return self._strictInterface
 end
 
+--[=[
+	Returns true if the item is valid.
+
+	@param value any
+	@return (boolean, string)
+]=]
+function AdorneeDataEntry:IsValid(value)
+	return self._strictInterface(value)
+end
+
 return AdorneeDataEntry

package/src/Shared/AdorneeDataValue.lua

@@ -50,7 +50,7 @@ function AdorneeDataValue.new(adornee, prototype)
 
 	for key, value in pairs(prototype) do
 		if AdorneeDataEntry.isAdorneeDataEntry(value) then
-			self._valueObjects[key] = value:CreateValueObject(adornee)
+			self._valueObjects[key] = value:Create(adornee)
 		else
 			self._valueObjects[key] = AttributeValue.new(adornee, key, value)
 		end