@quenty/tie 5.1.1 → 5.2.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.
 
+# [5.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/tie@5.1.1...@quenty/tie@5.2.0) (2023-12-14)
+
+
+### Features
+
+* Add realm support to tie ([cefc3fc](https://github.com/Quenty/NevermoreEngine/commit/cefc3fcd40287c85bd68e0f3438c15d701560df0))
+
+
+
+
+
 ## [5.1.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/tie@5.1.0...@quenty/tie@5.1.1) (2023-10-28)
 
 **Note:** Version bump only for package @quenty/tie

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/tie",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "description": "Tie allows interfaces to be defined between Lua OOP and Roblox objects.",
   "keywords": [
     "Roblox",
@@ -28,27 +28,27 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/attributeutils": "^9.1.1",
-    "@quenty/baseobject": "^7.0.0",
-    "@quenty/brio": "^9.1.1",
-    "@quenty/collectionserviceutils": "^3.1.1",
-    "@quenty/instanceutils": "^8.1.1",
-    "@quenty/loader": "^7.0.0",
+    "@quenty/attributeutils": "^9.2.0",
+    "@quenty/baseobject": "^7.1.0",
+    "@quenty/brio": "^9.2.0",
+    "@quenty/collectionserviceutils": "^3.2.0",
+    "@quenty/instanceutils": "^8.2.0",
+    "@quenty/loader": "^7.1.0",
     "@quenty/maid": "^2.6.0",
-    "@quenty/rx": "^8.1.1",
-    "@quenty/statestack": "^9.1.1",
+    "@quenty/rx": "^8.2.0",
+    "@quenty/statestack": "^9.2.0",
     "@quenty/string": "^3.1.0",
     "@quenty/symbol": "^2.2.0",
-    "@quenty/table": "^3.3.0",
-    "@quenty/valuebaseutils": "^8.1.1",
-    "@quenty/valueobject": "^8.1.1"
+    "@quenty/table": "^3.4.0",
+    "@quenty/valuebaseutils": "^8.2.0",
+    "@quenty/valueobject": "^8.2.0"
   },
   "devDependencies": {
-    "@quenty/promise": "^7.0.0",
-    "@quenty/signal": "^3.0.0"
+    "@quenty/promise": "^7.1.0",
+    "@quenty/signal": "^3.1.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "440aca7ce2b50b74317ee05fdc0b8d1e58001af3"
+  "gitHead": "2c2dbbc0cb2fbb46b4f3270c559c63890fe18b26"
 }

package/src/Shared/Definition/TieDefinition.lua

@@ -23,6 +23,7 @@ local TieMethodDefinition = require("TieMethodDefinition")
 local TiePropertyDefinition = require("TiePropertyDefinition")
 local TieSignalDefinition = require("TieSignalDefinition")
 local ValueObject = require("ValueObject")
+local TieRealms = require("TieRealms")
 
 local UNSET_VALUE = Symbol.named("unsetValue")
 
@@ -36,6 +37,8 @@ TieDefinition.Types = Table.readonly({
 	PROPERTY = Symbol.named("property"); -- will default to nil
 })
 
+TieDefinition.Realms = TieRealms
+
 function TieDefinition.new(definitionName, members, isSharedDefinition)
 	local self = setmetatable({}, TieDefinition)
 
@@ -44,21 +47,35 @@ function TieDefinition.new(definitionName, members, isSharedDefinition)
 
 	self._isSharedDefinition = isSharedDefinition
 
+	self:_addMembers(members, TieDefinition.Realms.SHARED)
+
+	return self
+end
+
+function TieDefinition:_addMembers(members, realm)
 	for memberName, memberTypeOrDefaultValue in pairs(members) do
-		assert(type(memberName) == "string", "Bad memberName")
-
-		if memberTypeOrDefaultValue == TieDefinition.Types.METHOD then
-			self._memberMap[memberName] = TieMethodDefinition.new(self, memberName)
-		elseif memberTypeOrDefaultValue == TieDefinition.Types.SIGNAL then
-			self._memberMap[memberName] = TieSignalDefinition.new(self, memberName)
-		elseif memberTypeOrDefaultValue == TieDefinition.Types.PROPERTY then
-			self._memberMap[memberName] = TiePropertyDefinition.new(self, memberName, nil)
+		if memberName == TieRealms.CLIENT then
+			self:_addMembers(memberTypeOrDefaultValue, TieRealms.CLIENT)
+		elseif memberName == TieRealms.SERVER then
+			self:_addMembers(memberTypeOrDefaultValue, TieRealms.SERVER)
 		else
-			self._memberMap[memberName] = TiePropertyDefinition.new(self, memberName, memberTypeOrDefaultValue)
+			assert(type(memberName) == "string", "Bad memberName")
+
+			self:_addMember(memberName, memberTypeOrDefaultValue, realm)
 		end
 	end
+end
 
-	return self
+function TieDefinition:_addMember(memberName, memberTypeOrDefaultValue, realm)
+	if memberTypeOrDefaultValue == TieDefinition.Types.METHOD then
+		self._memberMap[memberName] = TieMethodDefinition.new(self, memberName, realm)
+	elseif memberTypeOrDefaultValue == TieDefinition.Types.SIGNAL then
+		self._memberMap[memberName] = TieSignalDefinition.new(self, memberName, realm)
+	elseif memberTypeOrDefaultValue == TieDefinition.Types.PROPERTY then
+		self._memberMap[memberName] = TiePropertyDefinition.new(self, memberName, nil, realm)
+	else
+		self._memberMap[memberName] = TiePropertyDefinition.new(self, memberName, memberTypeOrDefaultValue, realm)
+	end
 end
 
 --[=[
@@ -348,7 +365,11 @@ function TieDefinition:_observeImplementation(folder)
 			update()
 		end))
 
-		for memberName, member in pairs(self._memberMap) do
+		for memberName, member in pairs(self:GetMemberMap()) do
+			if not member:IsAllowed() then
+				continue
+			end
+
 			if member.ClassName == "TiePropertyDefinition" then
 				maid:GiveTask(folder:GetAttributeChangedSignal(memberName):Connect(update))
 			end
@@ -411,6 +432,10 @@ function TieDefinition:GetName(): string
 	return self._definitionName
 end
 
+function TieDefinition:GetContainerNameForServer()
+	return self._definitionName
+end
+
 function TieDefinition:GetContainerName(): string
 	if RunService:IsClient() and not self._isSharedDefinition then
 		return self._definitionName .. "Client"
@@ -423,6 +448,12 @@ function TieDefinition:GetMemberMap()
 	return self._memberMap
 end
 
+--[=[
+	Returns true if the folder is an implementation
+
+	@param folder Folder
+	@return boolean
+]=]
 function TieDefinition:IsImplementation(folder)
 	local attributes = folder:GetAttributes()
 	local children = {}
@@ -430,7 +461,11 @@ function TieDefinition:IsImplementation(folder)
 		children[item.Name] = item
 	end
 
-	for memberName, member in pairs(self._memberMap) do
+	for memberName, member in pairs(self:GetMemberMap()) do
+		if not member:IsRequired() then
+			continue
+		end
+
 		local found = children[memberName]
 		if not found then
 			if member.ClassName == "TiePropertyDefinition" then

package/src/Shared/Definition/TieMethodDefinition.lua

@@ -6,20 +6,32 @@ local require = require(script.Parent.loader).load(script)
 
 local TieMethodImplementation = require("TieMethodImplementation")
 local TieMethodInterfaceUtils = require("TieMethodInterfaceUtils")
+local TieRealmUtils = require("TieRealmUtils")
 
 local TieMethodDefinition = {}
 TieMethodDefinition.ClassName = "TieMethodDefinition"
 TieMethodDefinition.__index = TieMethodDefinition
 
-function TieMethodDefinition.new(tieDefinition, methodName)
+function TieMethodDefinition.new(tieDefinition, methodName, realm)
 	local self = setmetatable({}, TieMethodDefinition)
 
 	self._tieDefinition = assert(tieDefinition, "No tieDefinition")
 	self._methodName = assert(methodName, "No methodName")
+	self._tieRealm = assert(realm, "No realm")
+	self._isRequired = TieRealmUtils.isRequired(self._tieRealm)
+	self._isAllowed = TieRealmUtils.isAllowed(self._tieRealm)
 
 	return self
 end
 
+function TieMethodDefinition:IsRequired()
+	return self._isRequired
+end
+
+function TieMethodDefinition:IsAllowed()
+	return self._isAllowed
+end
+
 function TieMethodDefinition:Implement(folder, initialValue, actualSelf)
 	assert(typeof(folder) == "Instance", "Bad folder")
 	assert(actualSelf, "No actualSelf")
@@ -34,6 +46,9 @@ function TieMethodDefinition:GetInterface(folder: Folder, aliasSelf)
 	return TieMethodInterfaceUtils.get(aliasSelf, self._tieDefinition, self, folder, nil)
 end
 
+function TieMethodDefinition:GetTieRealm()
+	return self._tieRealm
+end
 
 function TieMethodDefinition:GetTieDefinition()
 	return self._tieDefinition

package/src/Shared/Definition/TiePropertyDefinition.lua

@@ -7,17 +7,21 @@ local require = require(script.Parent.loader).load(script)
 local BaseObject = require("BaseObject")
 local TiePropertyImplementation = require("TiePropertyImplementation")
 local TiePropertyInterface = require("TiePropertyInterface")
+local TieRealmUtils = require("TieRealmUtils")
 
 local TiePropertyDefinition = setmetatable({}, BaseObject)
 TiePropertyDefinition.ClassName = "TiePropertyDefinition"
 TiePropertyDefinition.__index = TiePropertyDefinition
 
-function TiePropertyDefinition.new(tieDefinition, propertyName: string, defaultValue: any)
+function TiePropertyDefinition.new(tieDefinition, propertyName: string, defaultValue: any, realm)
 	local self = setmetatable(BaseObject.new(), TiePropertyDefinition)
 
 	self._tieDefinition = assert(tieDefinition, "No tieDefinition")
 	self._propertyName = assert(propertyName, "No propertyName")
 	self._defaultValue = defaultValue
+	self._tieRealm = assert(realm, "No realm")
+	self._isRequired = TieRealmUtils.isRequired(self._tieRealm)
+	self._isAllowed = TieRealmUtils.isAllowed(self._tieRealm)
 
 	return self
 end
@@ -30,6 +34,18 @@ function TiePropertyDefinition:GetDefaultValue()
 	return self._defaultValue
 end
 
+function TiePropertyDefinition:IsRequired()
+	return self._isRequired
+end
+
+function TiePropertyDefinition:IsAllowed()
+	return self._isAllowed
+end
+
+function TiePropertyDefinition:GetTieRealm()
+	return self._tieRealm
+end
+
 function TiePropertyDefinition:Implement(folder: Folder, initialValue)
 	assert(typeof(folder) == "Instance", "Bad folder")
 

package/src/Shared/Definition/TieSignalDefinition.lua

@@ -6,16 +6,20 @@ local require = require(script.Parent.loader).load(script)
 
 local TieSignalImplementation = require("TieSignalImplementation")
 local TieSignalInterface = require("TieSignalInterface")
+local TieRealmUtils = require("TieRealmUtils")
 
 local TieSignalDefinition = {}
 TieSignalDefinition.ClassName = "TieSignalDefinition"
 TieSignalDefinition.__index = TieSignalDefinition
 
-function TieSignalDefinition.new(tieDefinition, signalName)
+function TieSignalDefinition.new(tieDefinition, signalName, realm)
 	local self = setmetatable({}, TieSignalDefinition)
 
 	self._tieDefinition = assert(tieDefinition, "No tieDefinition")
 	self._signalName = assert(signalName, "No signalName")
+	self._tieRealm = assert(realm, "No realm")
+	self._isRequired = TieRealmUtils.isRequired(self._tieRealm)
+	self._isAllowed = TieRealmUtils.isAllowed(self._tieRealm)
 
 	return self
 end
@@ -24,6 +28,18 @@ function TieSignalDefinition:GetTieDefinition()
 	return self._tieDefinition
 end
 
+function TieSignalDefinition:IsRequired()
+	return self._isRequired
+end
+
+function TieSignalDefinition:IsAllowed()
+	return self._isAllowed
+end
+
+function TieSignalDefinition:GetTieRealm()
+	return self._tieRealm
+end
+
 function TieSignalDefinition:Implement(folder, initialValue)
 	assert(typeof(folder) == "Instance", "Bad folder")
 

package/src/Shared/Definition/Types/TieRealmUtils.lua

@@ -0,0 +1,60 @@
+--[=[
+	@class TieRealmUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local RunService = game:GetService("RunService")
+local TieRealms = require("TieRealms")
+
+local TieRealmUtils = {}
+
+function TieRealmUtils.isRequired(tieRealm)
+	if tieRealm == TieRealms.CLIENT then
+		-- Hack: TODO: Maybe we should contextualize the realm throughout all callers.
+		-- But otherwise, we'll need to do this
+		if not RunService:IsRunning() then
+			return false
+		end
+
+		return RunService:IsClient()
+	elseif tieRealm == TieRealms.SERVER then
+		-- Hack: TODO: Maybe we should contextualize the realm throughout all callers.
+		-- But otherwise, we'll need to do this
+		if not RunService:IsRunning() then
+			return false
+		end
+
+		return RunService:IsServer()
+	elseif tieRealm == TieRealms.SHARED then
+		return true
+	else
+		error("Unknown tieRealm")
+	end
+end
+
+function TieRealmUtils.isAllowed(tieRealm)
+	if tieRealm == TieRealms.CLIENT then
+		-- Hack: TODO: Maybe we should contextualize the realm throughout all callers.
+		-- But otherwise, we'll need to do this
+		if not RunService:IsRunning() then
+			return true
+		end
+
+		return RunService:IsClient()
+	elseif tieRealm == TieRealms.SERVER then
+		-- Hack: TODO: Maybe we should contextualize the realm throughout all callers.
+		-- But otherwise, we'll need to do this
+		if not RunService:IsRunning() then
+			return true
+		end
+
+		return RunService:IsServer()
+	elseif tieRealm == TieRealms.SHARED then
+		return true
+	else
+		error("Unknown tieRealm")
+	end
+end
+
+return TieRealmUtils

package/src/Shared/Definition/Types/TieRealms.lua

@@ -0,0 +1,16 @@
+--[=[
+	Realms sort of have to be a first class citizen...
+
+	@class TieRealms
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Table = require("Table")
+local Symbol = require("Symbol")
+
+return Table.readonly({
+	SHARED = Symbol.named("shared");
+	CLIENT = Symbol.named("client");
+	SERVER = Symbol.named("server");
+})

package/src/Shared/Implementation/TieImplementation.lua

@@ -9,6 +9,7 @@
 local require = require(script.Parent.loader).load(script)
 
 local BaseObject = require("BaseObject")
+local TieRealms = require("TieRealms")
 
 local TieImplementation = setmetatable({}, BaseObject)
 TieImplementation.ClassName = "TieImplementation"
@@ -21,10 +22,8 @@ function TieImplementation.new(tieDefinition, adornee, implementer)
 	self._adornee = assert(adornee, "No adornee")
 	self._actualSelf = implementer or {}
 
-	self._folder = Instance.new("Folder")
-	self._folder.Name = self._definition:GetContainerName()
+	self._folder = self._maid:Add(Instance.new("Folder"))
 	self._folder.Archivable = false
-	self._maid:GiveTask(self._folder)
 
 	self._memberImplementations = {}
 	self._memberMap = self._definition:GetMemberMap()
@@ -56,8 +55,13 @@ function TieImplementation:__index(index)
 	end
 
 	local memberMap = rawget(self, "_memberMap")
-	if memberMap[index] then
-		return memberMap[index]:GetInterface(self._folder, self)
+	local memberDefinition = memberMap[index]
+	if memberDefinition then
+		if memberDefinition:IsAllowed() then
+			return memberDefinition:GetInterface(self._folder, self)
+		else
+			error(string.format("%q is not a valid member", tostring(index)))
+		end
 	else
 		error(string.format("Bad index %q for TieImplementation", tostring(index)))
 	end
@@ -75,30 +79,51 @@ function TieImplementation:__newindex(index, value)
 	elseif self._memberImplementations[index] then
 		self._memberImplementations[index]:SetImplementation(value, self._actualSelf)
 	elseif TieImplementation[index] then
-		error(("Cannot set %q in TieImplementation"):format(tostring(index)))
+		error(string.format("Cannot set %q in TieImplementation", tostring(index)))
 	else
-		error(("Bad index %q for TieImplementation"):format(tostring(index)))
+		error(string.format("Bad index %q for TieImplementation", tostring(index)))
 	end
 end
 
 function TieImplementation:_buildMemberImplementations(implementer)
-	for _, memberDefinition in pairs(self._definition:GetMemberMap()) do
+	local allClientImplemented = true
+
+	for _, memberDefinition in pairs(self._memberMap) do
+		if not memberDefinition:IsAllowed() then
+			if memberDefinition:GetTieRealm() == TieRealms.CLIENT then
+				allClientImplemented = false
+			end
+			continue
+		end
+
 		local initialValue
 		if implementer then
 			local memberName = memberDefinition:GetMemberName()
 			initialValue = implementer[memberName]
 			if not initialValue then
-				error(("Missing member %q on %q"):format(memberName, self._adornee:GetFullName()))
+				if memberDefinition:IsRequired() then
+					error(string.format("Missing member %q on %q", memberName, self._adornee:GetFullName()))
+				else
+					if memberDefinition:GetTieRealm() == TieRealms.CLIENT then
+						allClientImplemented = false
+					end
+					continue
+				end
 			end
 		else
 			initialValue = nil
 		end
 
-		local memberImplementation = memberDefinition:Implement(self._folder, initialValue, self._actualSelf)
-		self._maid:GiveTask(memberImplementation)
-
+		local memberImplementation = self._maid:Add(memberDefinition:Implement(self._folder, initialValue, self._actualSelf))
 		self._memberImplementations[memberDefinition:GetMemberName()] = memberImplementation
 	end
+
+	-- Hack to make server objects look like server
+	if allClientImplemented then
+		self._folder.Name = self._definition:GetContainerName()
+	else
+		self._folder.Name = self._definition:GetContainerNameForServer()
+	end
 end
 
 return TieImplementation

package/src/Shared/Interface/TieInterface.lua

@@ -52,6 +52,25 @@ function TieInterface:IsImplemented()
 	return definition:HasImplementation(adornee)
 end
 
+--[=[
+	Gets the adornee the tie interface is on if it can be found.
+
+	@return Instance | nil
+]=]
+function TieInterface:GetTieAdornee()
+	local adornee = rawget(self, "_adornee")
+	if adornee then
+		return adornee
+	end
+
+	local folder = rawget(self, "_folder")
+	if folder then
+		return folder.Parent
+	end
+
+	return nil
+end
+
 --[=[
 	@return Observable<boolean>
 ]=]
@@ -74,7 +93,7 @@ end
 function TieInterface:__index(index)
 	local member = rawget(self, "_memberDefinitionMap")[index]
 	local definition = rawget(self, "_definition")
-	if member then
+	if member and member:IsAllowed() then
 		if member.ClassName == "TieMethodDefinition" then
 			local adornee = rawget(self, "_adornee")
 			local folder = rawget(self, "_folder")
@@ -91,12 +110,12 @@ function TieInterface:__index(index)
 
 			return TiePropertyInterface.new(folder, adornee, member)
 		else
-			error(("Unknown member definition %q"):format(tostring(member.ClassName)))
+			error(string.format("Unknown member definition %q", tostring(member.ClassName)))
 		end
 	elseif TieInterface[index] then
 		return TieInterface[index]
 	else
-		error(("Bad %q is not a member of %s"):format(tostring(index), definition:GetContainerName()))
+		error(string.format("Bad %q is not a member of %s", tostring(index), definition:GetContainerName()))
 	end
 end
 

package/src/Shared/Interface/TieMethodInterfaceUtils.lua

@@ -33,7 +33,7 @@ function TieMethodInterfaceUtils.get(aliasSelf, definition, member, folder, ador
 
 		local bindableFunction = folder:FindFirstChild(member:GetMemberName())
 		if not bindableFunction then
-			error("No bindableFunction")
+			error(string.format("No bindableFunction implemented for %s on %q", member:GetMemberName(), folder:GetFullName()))
 		end
 
 		return TieUtils.decode(bindableFunction:Invoke(TieUtils.encode(...)))

package/src/Shared/Interface/TiePropertyInterface.lua

@@ -39,6 +39,19 @@ function TiePropertyInterface.new(folder, adornee, memberDefinition)
 	return self
 end
 
+function TiePropertyInterface:ObserveBrio(predicate)
+	return self:_observeValueBaseBrio():Pipe({
+		RxBrioUtils.switchMapBrio(function(valueBase)
+			if typeof(valueBase) == "Instance" then
+				return RxInstanceUtils.observePropertyBrio(valueBase, "Value", predicate)
+			else
+				-- TODO: Maybe don't assumet his exists and use a helper method instead.
+				return valueBase:ObserveBrio(predicate)
+			end
+		end);
+	})
+end
+
 function TiePropertyInterface:Observe()
 	return self:_observeValueBaseBrio():Pipe({
 		Rx.switchMap(function(brio)