@quenty/observablecollection 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/observablecollection@3.2.0...@quenty/observablecollection@3.3.0) (2022-07-31)
+
+
+### Bug Fixes
+
+* Prevent observables from being removed during insertion of observable ([27a3594](https://github.com/Quenty/NevermoreEngine/commit/27a35941f457f63a5f1dc84169448a750308fdc2))
+
+
+### Features
+
+* Add ObservableSortedList ([cca209f](https://github.com/Quenty/NevermoreEngine/commit/cca209fd8a6c2cfeb1ee6e39d2aabce0202b3072))
+
+
+
+
+
 # [3.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/observablecollection@3.1.0...@quenty/observablecollection@3.2.0) (2022-07-02)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/observablecollection",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "An observable set",
   "keywords": [
     "Roblox",
@@ -27,17 +27,17 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/brio": "^6.1.0",
+    "@quenty/brio": "^6.2.0",
     "@quenty/loader": "^5.0.0",
-    "@quenty/maid": "^2.3.0",
-    "@quenty/promise": "^5.0.0",
-    "@quenty/rx": "^5.1.0",
+    "@quenty/maid": "^2.4.0",
+    "@quenty/promise": "^5.1.0",
+    "@quenty/rx": "^5.2.0",
     "@quenty/signal": "^2.2.0",
     "@quenty/symbol": "^2.1.0",
-    "@quenty/valuebaseutils": "^5.1.0"
+    "@quenty/valuebaseutils": "^5.2.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "de33c83e7f897e2b0887c77aeb1fc7963756f234"
+  "gitHead": "e31b3a35aa475bb5699a24898a8639e107165b36"
 }

package/src/Shared/ObservableList.lua

@@ -131,7 +131,7 @@ end
 	@return Observable<number>
 ]=]
 function ObservableList:ObserveIndexByKey(key)
-	assert(key, "Bad key")
+	assert(type(key) == "userdata", "Bad key")
 
 	return Observable.new(function(sub)
 		local currentIndex = self._indexes[key]
@@ -266,18 +266,17 @@ function ObservableList:InsertAt(item, index)
 
 	-- Fire off the index change on the value
 	do
-		local list = self._keyObservables[key]
-		if list then
-			self._keyObservables[key] = nil
-
-			for _, sub in pairs(list) do
-				if sub:IsPending() then
-					sub:Fire(index)
-				end
-			end
+		local subs = self._keyObservables[key]
+		if subs then
+			table.insert(changed, {
+				key = key;
+				newIndex = index;
+				subs = subs;
+			})
 		end
 	end
 
+
 	-- Fire off index change on each key list (if the data isn't stale)
 	for _, data in pairs(changed) do
 		if self._indexes[data.key] == data.newIndex then
@@ -322,7 +321,7 @@ function ObservableList:RemoveByKey(key)
 	end
 
 	local item = self._contents[key]
-	if not item then
+	if item == nil then
 		return nil
 	end
 

package/src/Shared/ObservableSortedList.lua

@@ -0,0 +1,526 @@
+--[=[
+	A list that can be observed for blend and other components and maintains sorting order.
+
+	This class is very expensive to use as it enforces maintaining order on the object. Each entries produces
+	what is most likely 4-5 tables, and changing can result in O(n) table construction and deltas.
+
+	However, for small lists that don't change frequently, such as a global leaderboard, this can be
+	a nice small interactive class.
+
+	For performance reasons this class defers firing events until the next defer() event frame.
+
+	@class ObservableSortedList
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Signal = require("Signal")
+local Observable = require("Observable")
+local Maid = require("Maid")
+local Brio = require("Brio")
+local RxValueBaseUtils = require("RxValueBaseUtils")
+local Symbol = require("Symbol")
+
+local function defaultCompare(a, b)
+	return a < b
+end
+
+local ObservableSortedList = {}
+ObservableSortedList.ClassName = "ObservableSortedList"
+ObservableSortedList.__index = ObservableSortedList
+
+--[=[
+	Constructs a new ObservableSortedList
+	@param compare callback?
+	@return ObservableSortedList<T>
+]=]
+function ObservableSortedList.new(compare)
+	local self = setmetatable({}, ObservableSortedList)
+
+	self._maid = Maid.new()
+
+	self._keyList = {} -- { [number]: Symbol } -- immutable
+
+	self._sortValue = {} -- { [Symbol]: number }
+	self._contents = {} -- { [Symbol]: T }
+	self._indexes = {} -- { [Symbol]: number }
+
+	self._keyObservables = {} -- { [Symbol]: { Subscription } }
+
+	self._compare = compare or defaultCompare
+	self._countValue = Instance.new("IntValue")
+	self._countValue.Value = 0
+	self._maid:GiveTask(self._countValue)
+
+--[=[
+	Fires when an item is added
+	@readonly
+	@prop ItemAdded Signal<T, number, Symbol>
+	@within ObservableSortedList
+]=]
+	self.ItemAdded = Signal.new()
+	self._maid:GiveTask(self.ItemAdded)
+
+--[=[
+	Fires when an item is removed.
+	@readonly
+	@prop ItemRemoved Signal<T, Symbol>
+	@within ObservableSortedList
+]=]
+	self.ItemRemoved = Signal.new()
+	self._maid:GiveTask(self.ItemRemoved)
+
+--[=[
+	Fires when the count changes.
+	@prop CountChanged RBXScriptSignal
+	@within ObservableSortedList
+]=]
+	self.CountChanged = self._countValue.Changed
+
+	return self
+end
+
+--[=[
+	Returns whether the value is an observable list
+	@param value any
+	@return boolean
+]=]
+function ObservableSortedList.isObservableSortedList(value)
+	return type(value) == "table" and getmetatable(value) == ObservableSortedList
+end
+
+--[=[
+	Observes all items in the list
+	@return Observable<Brio<T>>
+]=]
+function ObservableSortedList:ObserveItemsBrio()
+	return Observable.new(function(sub)
+		local maid = Maid.new()
+
+		local function handleItem(item, _index, includeKey)
+			local brio = Brio.new(item, includeKey)
+			maid[includeKey] = brio
+			sub:Fire(brio)
+		end
+
+		for index, key in pairs(self._keyList) do
+			handleItem(self._contents[key], index, key)
+		end
+
+		maid:GiveTask(self.ItemAdded:Connect(handleItem))
+		maid:GiveTask(self.ItemRemoved:Connect(function(_item, includeKey)
+			maid[includeKey] = nil
+		end))
+
+		self._maid[sub] = maid
+		maid:GiveTask(function()
+			self._maid[sub] = nil
+			sub:Complete()
+		end)
+
+		return maid
+	end)
+end
+
+--[=[
+	Observes the index as it changes, until the entry at the existing
+	index is removed.
+
+	@param indexToObserve number
+	@return Observable<number>
+]=]
+function ObservableSortedList:ObserveIndex(indexToObserve)
+	assert(type(indexToObserve) == "number", "Bad indexToObserve")
+
+	local key = self._keyList[indexToObserve]
+	if not key then
+		error(("No entry at index %q, cannot observe changes"):format(indexToObserve))
+	end
+
+	return self:ObserveIndexByKey(key)
+end
+
+--[=[
+	Observes the index as it changes, until the entry at the existing
+	key is removed.
+
+	@param key Symbol
+	@return Observable<number>
+]=]
+function ObservableSortedList:ObserveIndexByKey(key)
+	assert(type(key) == "userdata", "Bad key")
+
+	return Observable.new(function(sub)
+		local maid = Maid.new()
+		self._keyObservables[key] = self._keyObservables[key] or {}
+		table.insert(self._keyObservables[key], sub)
+
+		local currentIndex = self._indexes[key]
+		if currentIndex then
+			sub:Fire(currentIndex)
+		end
+
+		maid:GiveTask(function()
+			local list = self._keyObservables[key]
+			if not list then
+				return
+			end
+
+			local index = table.find(list, sub)
+			if index then
+				table.remove(list, index)
+				if #list == 0 then
+					self._keyObservables[key] = nil
+				end
+			end
+		end)
+
+		return maid
+	end)
+end
+
+--[=[
+	Gets the current index from the key
+
+	@param key Symbol
+	@return number
+]=]
+function ObservableSortedList:GetIndexByKey(key)
+	local currentIndex = self._indexes[key]
+	if currentIndex then
+		return currentIndex
+	else
+		return nil
+	end
+end
+
+--[=[
+	Gets the count of items in the list
+	@return number
+]=]
+function ObservableSortedList:GetCount()
+	return self._countValue.Value
+end
+
+--[=[
+	Gets a list of all entries.
+	@return { T }
+]=]
+function ObservableSortedList:GetList()
+	local list = {}
+	for _, key in pairs(self._keyList) do
+		table.insert(list, self._contents[key])
+	end
+	return list
+end
+
+--[=[
+	Observes the count of the list
+	@return Observable<number>
+]=]
+function ObservableSortedList:ObserveCount()
+	return RxValueBaseUtils.observeValue(self._countValue)
+end
+
+--[=[
+	Adds the item to the list at the specified index
+	@param item T
+	@param observeValue Observable<Comparable>
+	@return callback -- Call to remove
+]=]
+function ObservableSortedList:Add(item, observeValue)
+	assert(item ~= nil, "Bad item")
+	assert(Observable.isObservable(observeValue), "Bad observeValue")
+
+	local key = Symbol.named("entryKey")
+	local maid = Maid.new()
+
+	self._contents[key] = item
+
+	maid:GiveTask(observeValue:Subscribe(function(sortValue)
+		self._sortValue[key] = sortValue
+
+		if sortValue ~= nil then
+			local currentIndex = self._indexes[key]
+			local targetIndex = self:_findCorrectIndex(sortValue, currentIndex)
+			self:_updateIndex(key, item, targetIndex)
+		else
+			local observableSubs = self._keyObservables[key]
+
+			-- calling this also may unsubscribe some observables.
+			self:_removeItemByKey(key, item)
+
+			if observableSubs then
+				-- fire nil index
+				self:_fireSubs(observableSubs, nil)
+			end
+		end
+	end))
+
+	maid:GiveTask(function()
+		local observableSubs = self._keyObservables[key]
+		self._keyObservables[key] = nil
+
+		self:_removeItemByKey(key, item)
+
+		-- Fire off the index change on the value
+		if observableSubs then
+			self:_completeSubs(observableSubs)
+		end
+
+		self._contents[key] = nil
+		self._sortValue[key] = nil
+	end)
+
+	self._maid[key] = maid
+
+	return function()
+		self._maid[key] = nil
+	end
+end
+
+--[=[
+	Gets the current item at the index, or nil if it is not defined.
+	@param index number
+	@return T?
+]=]
+function ObservableSortedList:Get(index)
+	assert(type(index) == "number", "Bad index")
+
+	local key = self._keyList[index]
+	if not key then
+		return nil
+	end
+
+	return self._contents[key]
+end
+
+--[=[
+	Removes the item from the list if it exists.
+	@param key Symbol
+	@return T
+]=]
+function ObservableSortedList:RemoveByKey(key)
+	assert(key ~= nil, "Bad key")
+
+	self._maid[key] = nil
+end
+
+function ObservableSortedList:_updateIndex(key, item, index)
+	assert(item ~= nil, "Bad item")
+	assert(type(index) == "number", "Bad index")
+
+	local pastIndex = self._indexes[key]
+	if pastIndex == index then
+		return
+	end
+
+	self._indexes[key] = index
+
+	local changed = {}
+
+	if not pastIndex then
+		-- shift everything up to fit this space
+		local n = #self._keyList
+		for i=n, index, -1 do
+			local nextKey = self._keyList[i]
+			self._indexes[nextKey] = i + 1
+			self._keyList[i + 1] = nextKey
+
+			table.insert(changed, {
+				key = nextKey;
+				newIndex = i + 1;
+			})
+		end
+	elseif index > pastIndex then
+		-- we're moving up (3 -> 5), so everything shifts down to fill up the pastIndex
+		for i=pastIndex + 1, index do
+			local nextKey = self._keyList[i]
+			self._indexes[nextKey] = i - 1
+			self._keyList[i - 1] = nextKey
+
+			table.insert(changed, {
+				key = nextKey;
+				newIndex = i - 1;
+			})
+		end
+	else
+		-- if index < pastIndex then
+		-- we're moving down (5 -> 3) so everything shifts up to fit this space
+		for i=pastIndex-1, index, -1 do
+			local belowKey = self._keyList[i]
+			self._indexes[belowKey] = i + 1
+			self._keyList[i + 1] = belowKey
+			table.insert(changed, {
+				key = belowKey;
+				newIndex = i + 1;
+			})
+		end
+	end
+
+	local itemAdded = {
+		key = key;
+		newIndex = index;
+		item = item;
+	}
+
+	-- ensure ourself is considered changed
+	table.insert(changed, itemAdded)
+
+
+	self._keyList[index] = key
+
+	-- Fire off our count value changed
+	-- still O(n^2) but at least we prevent emitting O(n^2) events
+	if pastIndex == nil then
+		self:_deferChange(1, itemAdded, nil, changed)
+	else
+		self:_deferChange(0, nil, nil, changed)
+	end
+end
+
+function ObservableSortedList:_removeItemByKey(key, item)
+	assert(key ~= nil, "Bad key")
+
+	local index = self._indexes[key]
+	if not index then
+		return
+	end
+
+	self._indexes[key] = nil
+	self._sortValue[key] = nil
+
+	local changed = {}
+
+	-- shift everything down
+	local n = #self._keyList
+	for i=index, n - 1 do
+		local nextKey = self._keyList[i+1]
+		self._indexes[nextKey] = i
+		self._keyList[i] = nextKey
+
+		table.insert(changed, {
+			key = nextKey;
+			newIndex = i;
+		})
+	end
+	self._keyList[n] = nil
+
+	local itemRemoved = {
+		key = key;
+		item = item;
+	}
+
+	-- TODO: Defer item removed as a changed event?
+
+	-- still O(n^2) but at least we prevent emitting O(n^2) events
+	self:_deferChange(-1, nil, itemRemoved, changed)
+end
+
+function ObservableSortedList:_deferChange(countChange, itemAdded, itemRemoved, indexChanges)
+	self:_queueDeferredChange()
+
+	if itemAdded then
+		self._deferredChange.itemsRemoved[itemAdded.key] = nil
+		self._deferredChange.itemsAdded[itemAdded.key] = itemAdded
+	end
+
+	if itemRemoved then
+		self._deferredChange.itemsAdded[itemRemoved.key] = nil
+		self._deferredChange.itemsRemoved[itemRemoved.key] = itemRemoved
+	end
+
+	self._deferredChange.countChange += countChange
+
+	for _, data in pairs(indexChanges) do
+		self._deferredChange.indexChanges[data.key] = data
+	end
+end
+
+function ObservableSortedList:_queueDeferredChange()
+	if not self._deferredChange then
+		self._deferredChange = {
+			countChange = 0;
+			indexChanges = {};
+			itemsAdded = {};
+			itemsRemoved = {};
+		}
+
+		task.defer(function()
+			local snapshot = self._deferredChange
+			self._deferredChange = nil
+
+			self._countValue.Value = self._countValue.Value + snapshot.countChange
+
+			if self.Destroy then
+				-- Fire off last adds
+				for _, lastAdded in pairs(snapshot.itemsAdded) do
+					self.ItemAdded:Fire(lastAdded.item, lastAdded.newIndex, lastAdded.key)
+				end
+
+				for _, lastRemoved in pairs(snapshot.itemsRemoved) do
+					self.ItemRemoved:Fire(lastRemoved.item, lastRemoved.key)
+				end
+			end
+
+			-- Fire off index change on each key list (if the data isn't stale)
+			for _, lastChange in pairs(snapshot.indexChanges) do
+				if self._indexes[lastChange.key] == lastChange.newIndex then
+					local subs = self._keyObservables[lastChange.key]
+					if subs then
+						self:_fireSubs(subs, lastChange.newIndex)
+					end
+				end
+			end
+		end)
+	end
+end
+
+function ObservableSortedList:_findCorrectIndex(sortValue, currentIndex)
+	-- todo: binary search
+	-- todo: stable
+
+	for i=#self._keyList, 1, -1 do
+		local currentKey = self._keyList[i]
+		if self._compare(self._sortValue[currentKey], sortValue) then
+
+			-- include index in this
+			if currentIndex and currentIndex <= i then
+				return i
+			end
+
+			return i + 1
+		end
+	end
+
+	return 1
+end
+
+function ObservableSortedList:_fireSubs(list, index)
+	for _, sub in pairs(list) do
+		if sub:IsPending() then
+			task.spawn(function()
+				sub:Fire(index)
+			end)
+		end
+	end
+end
+
+function ObservableSortedList:_completeSubs(list)
+	for _, sub in pairs(list) do
+		if sub:IsPending() then
+			sub:Fire(nil)
+			sub:Complete()
+		end
+	end
+end
+
+--[=[
+	Cleans up the ObservableSortedList and sets the metatable to nil.
+]=]
+function ObservableSortedList:Destroy()
+	self._maid:DoCleaning()
+	setmetatable(self, nil)
+end
+
+return ObservableSortedList

package/src/Shared/ObservableSortedList.spec.lua

@@ -0,0 +1,37 @@
+--[[
+	@class ObservableSortedList.spec.lua
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local ObservableSortedList = require("ObservableSortedList")
+local Rx = require("Rx")
+
+return function()
+	describe("ObservableSortedList.new()", function()
+		local observableSortedList = ObservableSortedList.new()
+
+		it("should return nil for unset values", function()
+			expect(observableSortedList:Get(1)).to.equal(nil)
+		end)
+
+		it("should allow inserting an value", function()
+			expect(observableSortedList:GetCount()).to.equal(0)
+
+			observableSortedList:Add("b", Rx.of("b"))
+
+			expect(observableSortedList:Get(1)).to.equal("b")
+			expect(observableSortedList:GetCount()).to.equal(1)
+		end)
+
+		it("should sort the items", function()
+			expect(observableSortedList:GetCount()).to.equal(1)
+
+			observableSortedList:Add("a", Rx.of("a"))
+
+			expect(observableSortedList:Get(1)).to.equal("a")
+			expect(observableSortedList:Get(2)).to.equal("b")
+			expect(observableSortedList:GetCount()).to.equal(2)
+		end)
+	end)
+end

package/test/default.project.json

@@ -4,7 +4,16 @@
     "$className": "DataModel",
     "ServerScriptService": {
       "observablecollection": {
-        "$path": ".."
+        "$className": "Folder",
+        "observablecollection": {
+          "$path": ".."
+        },
+        "instanceutils": {
+          "$path": "../../instanceutils"
+        }
+      },
+      "Script": {
+        "$path": "scripts/Server"
       }
     }
   }

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,112 @@
+--[[
+	@class ServerMain
+]]
+local ServerScriptService = game:GetService("ServerScriptService")
+local TweenService = game:GetService("TweenService")
+
+local loader = ServerScriptService:FindFirstChild("LoaderUtils", true).Parent
+local packages = require(loader).bootstrapGame(ServerScriptService.observablecollection)
+
+local ObservableSortedList = require(packages.ObservableSortedList)
+local RxInstanceUtils = require(packages.RxInstanceUtils)
+local Rx = require(packages.Rx)
+
+local observableSortedList = ObservableSortedList.new()
+
+observableSortedList.CountChanged:Connect(function(count)
+	print("Count", count)
+end)
+
+observableSortedList:ObserveItemsBrio():Subscribe(function(brio)
+	if brio:IsDead() then
+		return
+	end
+
+	local part, key = brio:GetValue()
+	local maid = brio:ToMaid()
+
+	local currentTween
+	local function setCFrame(cframe, doNotAnimate)
+		if currentTween then
+			currentTween:Cancel()
+			currentTween = nil
+		end
+
+		if doNotAnimate then
+			part.CFrame = cframe
+		else
+			local tweenInfo = TweenInfo.new(0.2)
+			local tween = TweenService:Create(part, tweenInfo, {
+				CFrame = cframe;
+			})
+			currentTween = tween
+			tween:Play()
+		end
+	end
+
+	local first = true
+
+	maid:GiveTask(observableSortedList:ObserveIndexByKey(key):Subscribe(function(index)
+		print("change")
+
+		if index then
+			part:SetAttribute("CurrentIndex", index)
+			setCFrame(CFrame.new(-5*index, 5, 0) * CFrame.Angles(0, math.pi/2, 0), first)
+			first = false
+		else
+			part:SetAttribute("CurrentIndex", "nil")
+			setCFrame(CFrame.new(part.CFrame.x, 10, 0) * CFrame.Angles(0, math.pi/2, 0), first)
+			first = false
+		end
+	end))
+
+	maid:GiveTask(function()
+		part:SetAttribute("CurrentIndex", "nil")
+		setCFrame(CFrame.new(part.CFrame.x, 5, 5) * CFrame.Angles(0, math.pi/2, 0), first)
+		first = false
+	end)
+end)
+
+local parts = {}
+for i=9, 1, -1 do
+	local part = Instance.new("Part")
+	part.TopSurface = Enum.SurfaceType.Smooth
+	part.BottomSurface = Enum.SurfaceType.Smooth
+	part.Anchored = true
+	part.Size = Vector3.new(3, 3, 3)
+	part.Name = i
+
+	local surfaceGui = Instance.new("SurfaceGui")
+	surfaceGui.Name = "SurfaceGui"
+	surfaceGui.Face = Enum.NormalId.Top
+	surfaceGui.SizingMode = Enum.SurfaceGuiSizingMode.PixelsPerStud
+	surfaceGui.Adornee = part
+	surfaceGui.Parent = part
+
+	local textLabel = Instance.new("TextLabel")
+	textLabel.Name = "TextLabel"
+	textLabel.Size = UDim2.new(1, 0, 1, 0)
+	textLabel.TextScaled = true
+	textLabel.BackgroundTransparency = 1
+	textLabel.TextColor3 = Color3.new(0, 0, 0)
+	textLabel.BorderSizePixel = 0
+	textLabel.Parent = surfaceGui
+
+	RxInstanceUtils.observeProperty(part, "Name", nil):Subscribe(function(value)
+		textLabel.Text = tostring(value)
+	end)
+
+	parts[i] = part
+	part.Parent = workspace
+
+	observableSortedList:Add(part, RxInstanceUtils.observeProperty(part, "Name", nil):Pipe({
+		Rx.map(function(name)
+			return tonumber(name)
+		end)
+	}))
+end
+
+parts[5].Name = "25"
+parts[9].Name = "3.1"
+parts[2].Name = "remove"
+