@quenty/adorneedata 1.0.1-canary.433.80025dc.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 1.0.1-canary.433.80025dc.0 (2023-12-14)
+
+**Note:** Version bump only for package @quenty/adorneedata

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2014-2023 James Onnen (Quenty)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+## AdorneeData
+
+<div align="center">
+  <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/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" />
+  </a>
+</div>
+
+Bridges attributes and serialization
+
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/AdorneeData">View docs →</a></div>
+
+## Installation
+
+```
+npm install @quenty/adorneedata --save
+```
+
+## Requirements
+These are the requirements for this attribute data library.
+
+* Not like Tie in that it is focused on serialization/boundary between Roblox and our stuff (tie is interfaces separated by network boundary)
+* Easy to transform between data and attributes
+* No service bag requirements
+
+### Centralized definition with no server/client information
+```lua
+return AdorneeData.new({
+  CurrencyColor = Color3.new();
+  CurrencyNameTranslationKey = "";
+  CurrencyFormatTranslationKey = "";
+  CurrencyImageId = "";
+  CurrencyShowType = CurrencyShowTypes.NONE;
+  GivePlayerCurrency = false;
+  CurrencySaves = false;
+})
+```
+
+### Easy to write/author
+We should be able to create new data that is validated
+
+```lua
+CurrencyDefinitionData:CreateData({
+  CurrencyKey = CurrencyDefinitionConstants.DEFAULT_CURRENCY_KEY
+  CurrencyColor = Color3.fromRGB(55, 180, 74)
+  CurrencyTranslationKey = "currency.default.name"
+  CurrencyFormatTranslationKey = "currency.default.format"
+  DoesSave = true
+  ImageId = "rbxassetid://10049671651"
+})
+```
+
+We should be able to create partial data
+
+```lua
+CurrencyDefinitionData:CreatePartialData({
+  CurrencyKey = CurrencyDefinitionConstants.DEFAULT_CURRENCY_KEY
+  CurrencyColor = Color3.fromRGB(55, 180, 74)
+  CurrencyTranslationKey = "currency.default.name"
+  CurrencyFormatTranslationKey = "currency.default.format"
+  DoesSave = true
+  ImageId = "rbxassetid://10049671651"
+})
+```
+#### Additional authorship requirements
+
+* Should be able to set optional values
+
+### Easy to validate/assert/assign
+
+We should be able to check data types
+
+```lua
+function CurrencyService:InitCurrencyDefinition(currencyDefinitionData)
+  assert(CurrencyDefinitionData:IsData(currencyDefinitionData), "Bad currencyDefinitionData")
+
+  local currencyDefinition = CurrencyDefinition:Create("Folder")
+  CurrencyDefinitionData:SetAttributes(currencyDefinition, currencyDefinitionData)
+
+  return currencyDefinition
+end
+```
+
+### Replacement files
+
+Should replace following files:
+
+* CurrencyDefinitionDataUtils - Files with `t` interface asserting type
+* CurrencyDefinitionConstants - Files with constant attribute names
+* CurrencyDefinitionUtils - File that sets certain properties or attributes and do validation
+
+### Easy to serialize
+
+Should be able to flash to constant 
+

package/default.project.json

@@ -0,0 +1,6 @@
+{
+  "name": "adorneedata",
+  "tree": {
+    "$path": "src"
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@quenty/adorneedata",
+  "version": "1.0.1-canary.433.80025dc.0",
+  "description": "Bridges attributes and serialization",
+  "keywords": [
+    "Roblox",
+    "Nevermore",
+    "Lua",
+    "AdorneeData"
+  ],
+  "bugs": {
+    "url": "https://github.com/Quenty/NevermoreEngine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Quenty/NevermoreEngine.git",
+    "directory": "src/adorneedata/"
+  },
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/quenty"
+  },
+  "license": "MIT",
+  "contributors": [
+    "Quenty"
+  ],
+  "dependencies": {
+    "@quenty/attributeutils": "9.1.2-canary.433.80025dc.0",
+    "@quenty/ducktype": "2.0.1-canary.433.80025dc.0",
+    "@quenty/loader": "7.0.1-canary.433.80025dc.0",
+    "@quenty/rx": "8.1.2-canary.433.80025dc.0",
+    "@quenty/rxsignal": "2.1.2-canary.433.80025dc.0",
+    "@quenty/table": "3.3.1-canary.433.80025dc.0",
+    "@quentystudios/t": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "80025dcd926765b502d322bb84e013b973409d8c"
+}

package/src/Shared/AdorneeData.lua

@@ -0,0 +1,254 @@
+--[=[
+	Bridges attributes and serializable data table. It's typical to need to define data in 3 ways.
+
+	1. Attributes on an instance for replication
+	2. Tables for Lua configuration
+	3. Within AttributeValues for writing regular code
+
+	Providing all 3
+
+	@class AdorneeData
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local AdorneeDataEntry = require("AdorneeDataEntry")
+local AdorneeDataValue = require("AdorneeDataValue")
+local AttributeUtils = require("AttributeUtils")
+local t = require("t")
+
+local AdorneeData = {}
+AdorneeData.ClassName = "AdorneeData"
+AdorneeData.__index = AdorneeData
+
+--[=[
+	Attribute data specification
+
+	@param prototype any
+	@return AdorneeData<T>
+]=]
+function AdorneeData.new(prototype)
+	local self = setmetatable({}, AdorneeData)
+
+	self._fullPrototype = assert(prototype, "Bad prototype")
+	self._attributePrototype = {}
+	self._valueObjectPrototype = {}
+
+	for key, item in pairs(self._fullPrototype) do
+		if AdorneeDataEntry.isAdorneeDataEntry(item) then
+			self._valueObjectPrototype[key] = item
+		else
+			self._attributePrototype[key] = item
+		end
+	end
+
+	return self
+end
+
+--[=[
+	Returns true if the data is valid data, otherwise returns false and an error.
+
+	@param data any
+	@return boolean
+	@return string -- Error message
+]=]
+function AdorneeData:IsData(data)
+	return self:GetStrictTInterface()(data)
+end
+
+--[=[
+	Validates and creates a new data table for the data that is readonly and frozen
+
+	@param data T
+	@return T
+]=]
+function AdorneeData:CreateData(data)
+	assert(self:IsData(data))
+
+	return table.freeze(table.clone(data))
+end
+
+
+--[=[
+	Validates and creates a new data table that is readonly and frozen, but for partial
+	data.
+
+	The partial data can just be part of the attributes.
+
+	@param partialData TPartial
+	@return TPartial
+]=]
+function AdorneeData:CreatePartialData(partialData)
+	assert(self:IsPartialData(partialData))
+
+	return table.freeze(table.clone(partialData))
+end
+
+
+--[=[
+	Gets attribute table for the data
+
+	@param adornee Instance
+	@return AdorneeDataValue
+]=]
+function AdorneeData:CreateAdorneeDataValue(adornee)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+
+	local attributeTableValue = AdorneeDataValue.new(adornee, self._fullPrototype)
+
+	return attributeTableValue
+end
+
+--[=[
+	Gets the attributes for the adornee
+
+	@param adornee Instance
+	@return T
+]=]
+function AdorneeData:GetAttributes(adornee)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+
+	local data = {}
+	for key, value in pairs(self._attributePrototype) do
+		data[key] = adornee:GetAttribute(value)
+	end
+
+	-- TODO: Avoid additional allocation
+	for key, value in pairs(self._valueObjectPrototype) do
+		data[key] = value:CreateValueObject(adornee).Value
+	end
+
+	return self:CreateData(data)
+end
+
+--[=[
+	Sets the attributes for the adornee
+
+	@param adornee Instance
+	@param data T
+]=]
+function AdorneeData:SetAttributes(adornee, data)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+	assert(self:IsData(data))
+
+	for key, _ in pairs(self._attributePrototype) do
+		adornee:SetAttribute(key, data[key])
+	end
+
+	-- TODO: Avoid additional allocation
+	for key, value in pairs(self._valueObjectPrototype) do
+		value:CreateValueObject(adornee).Value = data[key]
+	end
+end
+
+--[=[
+	Initializes the attributes for the adornee
+
+	@param adornee Instance
+	@param data T
+]=]
+function AdorneeData:InitAttributes(adornee, data)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+	assert(self:IsData(data))
+
+	for key, _ in pairs(self._attributePrototype) do
+		if adornee:GetAttribute(key) == nil then
+			adornee:SetAttribute(key, data[key])
+		end
+	end
+
+	-- TODO: Avoid additional allocation
+	for key, value in pairs(self._valueObjectPrototype) do
+		local valueObject = value:CreateValueObject(adornee)
+		if valueObject == nil then
+			valueObject.Value = data[key]
+		end
+	end
+end
+
+--[=[
+	Sets partial attributes on the adornee
+
+	@param adornee Instance
+	@param partialData TPartial
+]=]
+function AdorneeData:SetPartialAttributes(adornee, partialData)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+	assert(self:IsPartialData(partialData))
+
+	local attributeTable = self:CreateAdorneeDataValue(adornee)
+	for key, value in pairs(partialData) do
+		attributeTable[key].Value = value
+	end
+end
+
+--[=[
+	Gets a strict interface which will return true if the value is a partial interface and
+	false otherwise.
+
+	@return function
+]=]
+function AdorneeData:GetStrictTInterface()
+	if self._fullInterface then
+		return self._fullInterface
+	end
+
+	self._fullInterface = t.strictInterface(self:_getOrCreateTypeInterfaceList())
+	return self._fullInterface
+end
+
+--[=[
+	Gets a [t] interface which will return true if the value is a partial interface, and
+	false otherwise.
+
+	@return function
+]=]
+function AdorneeData:GetPartialTInterface()
+	if self._partialInterface then
+		return self._partialInterface
+	end
+
+	local interfaceList = {}
+	for key, value in pairs(self:_getOrCreateTypeInterfaceList()) do
+		interfaceList[key] = t.optional(value)
+	end
+
+	self._partialInterface = t.strictInterface(interfaceList)
+	return self._partialInterface
+end
+
+
+--[=[
+	Returns true if the data is valid partial data, otherwise returns false and an error.
+
+	@param data any
+	@return boolean
+	@return string -- Error message
+]=]
+function AdorneeData:IsPartialData(data)
+	return self:GetPartialTInterface()(data)
+end
+
+function AdorneeData:_getOrCreateTypeInterfaceList()
+	if self._typeInterfaceList then
+		return self._typeInterfaceList
+	end
+
+	local interfaceList = {}
+
+	for key, value in pairs(self._fullPrototype) do
+		if AdorneeDataEntry.isAdorneeDataEntry(value) then
+			interfaceList[key] = value:GetStrictInterface()
+		else
+			local valueType = typeof(value)
+			assert(AttributeUtils.isValidAttributeType(valueType), "Not a valid value type")
+
+			interfaceList[key] = t.typeof(valueType)
+		end
+	end
+
+	self._typeInterfaceList = interfaceList
+	return interfaceList
+end
+
+return AdorneeData

package/src/Shared/AdorneeDataEntry.lua

@@ -0,0 +1,41 @@
+--[=[
+	@class AdorneeDataEntry
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local DuckTypeUtils = require("DuckTypeUtils")
+local t = require("t")
+
+local AdorneeDataEntry = {}
+AdorneeDataEntry.ClassName = "AdorneeDataEntry"
+AdorneeDataEntry.__index = AdorneeDataEntry
+
+function AdorneeDataEntry.new(dataType, createValueObject)
+	assert(type(dataType) == "string", "Bad dataType")
+	assert(type(createValueObject) == "function", "Bad createValueObject")
+
+	local self = setmetatable({}, AdorneeDataEntry)
+
+	self._dataType = dataType
+	self._createValueObject = createValueObject
+	self._strictInterface = t.typeof(self._dataType)
+
+	return self
+end
+
+function AdorneeDataEntry.isAdorneeDataEntry(data)
+	return DuckTypeUtils.isImplementation(AdorneeDataEntry, data)
+end
+
+function AdorneeDataEntry:CreateValueObject(adornee)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+
+	return self._createValueObject(adornee)
+end
+
+function AdorneeDataEntry:GetStrictInterface()
+	return self._strictInterface
+end
+
+return AdorneeDataEntry

package/src/Shared/AdorneeDataValue.lua

@@ -0,0 +1,152 @@
+--[=[
+	Allows access to an attribute like a ValueObject but in table form.
+
+	```lua
+	local data = AdorneeDataValue.new(workspace, {
+		Version = "1.0.0";
+		CFrame = CFrame.new();
+	})
+	print(data.Version.Value) --> 1.0.0
+	print(workspace:GetAttribute("version")) --> 1.0.0
+
+	data.Version.Changed:Connect(function()
+		print(data.Version.Value)
+	end)
+
+	workspace:SetAttribute("1.1.0") --> 1.1.0
+	data.Value = "1.2.0" --> 1.2.0
+	```
+
+	@class AdorneeDataValue
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local AttributeValue = require("AttributeValue")
+local RxSignal = require("RxSignal")
+local Rx = require("Rx")
+local AdorneeDataEntry = require("AdorneeDataEntry")
+
+local AdorneeDataValue = {}
+AdorneeDataValue.ClassName = "AdorneeDataValue"
+AdorneeDataValue.__index = AdorneeDataValue
+
+--[=[
+	Constructs a new AdorneeDataValue
+
+	@param adornee Instance
+	@param prototype table
+	@return AdorneeDataValue<T>
+]=]
+function AdorneeDataValue.new(adornee, prototype)
+	assert(typeof(adornee) == "Instance", "Bad adornee")
+	assert(type(prototype) == "table", "Bad prototype")
+
+	local self = {
+		_adornee = adornee;
+		_defaultValues = prototype;
+		_valueObjects = {};
+	}
+
+	for key, value in pairs(prototype) do
+		if AdorneeDataEntry.isAdorneeDataEntry(value) then
+			self._valueObjects[key] = value:CreateValueObject(adornee)
+		else
+			self._valueObjects[key] = AttributeValue.new(adornee, key, value)
+		end
+	end
+
+	return setmetatable(self, AdorneeDataValue)
+end
+
+--[=[
+	The current property of the Attribute. Can be assigned to to write
+	the attribute.
+	@prop Value T
+	@within AdorneeDataValue
+]=]
+
+--[=[
+	Signal that fires when the attribute changes
+	@readonly
+	@prop Changed Signal<()>
+	@within AdorneeDataValue
+]=]
+function AdorneeDataValue:__index(index)
+	if index == "Value" then
+		local result = {}
+		for key, valueObject in pairs(self._valueObjects) do
+			result[key] = valueObject.Value
+		end
+		return result
+	elseif index == "Changed" then
+		return RxSignal.new(self:Observe():Pipe({
+			Rx.skip(1);
+		}))
+	elseif AdorneeDataValue[index] then
+		return AdorneeDataValue[index]
+	elseif type(index) == "string" then
+		local attributeValues = rawget(self, "_valueObjects")
+		if attributeValues[index] then
+			return attributeValues[index]
+		else
+			error(string.format("%q is not a member of AdorneeDataValue", tostring(index)))
+		end
+	else
+		error(string.format("%q is not a member of AdorneeDataValue", tostring(index)))
+	end
+end
+
+--[=[
+	Observes an attribute on an instance.
+	@return Observable<any>
+]=]
+function AdorneeDataValue:Observe()
+	local current = rawget(self, "_defaultObservable")
+	if current then
+		return current
+	end
+
+	local attributeValues = rawget(self, "_valueObjects")
+
+	local observables = {}
+	for key, valueObject in pairs(attributeValues) do
+		observables[key] = valueObject:Observe()
+	end
+
+	local observable = Rx.combineLatest(observables)
+	rawset(self, "_defaultObservable", observable)
+	return observable
+end
+
+function AdorneeDataValue:__newindex(index, newValue)
+	if index == "Value" then
+		assert(type(newValue) == "table", "Bad newValue")
+		local attributeValues = rawget(self, "_valueObjects")
+
+		for key, value in pairs(newValue) do
+			if attributeValues[key] then
+				attributeValues[key].Value = value
+			else
+				error("%s is not a valid member of AttributeValue")
+			end
+		end
+	else
+		error(string.format("Use AttributeValue.%q.Value to set an attribute", tostring(index)))
+	end
+end
+
+function AdorneeDataValue:_getOrCreateAttributeValue(key)
+	local attributeValues = rawget(self, "_valueObjects")
+	if attributeValues[key] then
+		return attributeValues[key]
+	else
+		local prototype = rawget(self, "_defaultValues")
+		local adornee = rawget(self, "_adornee")
+
+		attributeValues[key] = AttributeValue.new(adornee, key, prototype[key])
+		return attributeValues
+	end
+end
+
+return AdorneeDataValue

package/src/node_modules.project.json

@@ -0,0 +1,7 @@
+{
+  "name": "node_modules",
+  "globIgnorePaths": [ "**/.package-lock.json" ],
+  "tree": {
+    "$path": { "optional": "../node_modules" }
+  }
+}

package/test/default.project.json

@@ -0,0 +1,11 @@
+{
+  "name": "AdorneeDataTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "adorneedata": {
+        "$path": ".."
+      }
+    }
+  }
+}