@quenty/observablecollection 12.7.0 → 12.8.1

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [12.8.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/observablecollection@12.8.0...@quenty/observablecollection@12.8.1) (2024-10-04)
+
+**Note:** Version bump only for package @quenty/observablecollection
+
+
+
+
+
+# [12.8.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/observablecollection@12.7.0...@quenty/observablecollection@12.8.0) (2024-10-04)
+
+
+### Features
+
+* Add ObservableSortedList:Contains(value) ([049c9df](https://github.com/Quenty/NevermoreEngine/commit/049c9df1df0cc765124c624a1276a456ff3e7700))
+* ObservableSortedList can take non rx-value and still be performant ([e5c1d4f](https://github.com/Quenty/NevermoreEngine/commit/e5c1d4fb272f22d2559fba6f1a533686a730fca8))
+
+
+### Performance Improvements
+
+* Predeclare size of lists to allocate for lists ([b662bbb](https://github.com/Quenty/NevermoreEngine/commit/b662bbb814f91a1853a549b217fa8af8a9f74d3d))
+* Use switchToBrio() and table.create ([f73644e](https://github.com/Quenty/NevermoreEngine/commit/f73644e56a9ffd0991833bd147c705c210553539))
+
+
+
+
+
 # [12.7.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/observablecollection@12.6.0...@quenty/observablecollection@12.7.0) (2024-09-25)
 
 **Note:** Version bump only for package @quenty/observablecollection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/observablecollection",
-  "version": "12.7.0",
+  "version": "12.8.1",
   "description": "A set of observable collections, such as sets, maps, sorted lists, and more.",
   "keywords": [
     "Roblox",
@@ -27,23 +27,23 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "^10.5.0",
-    "@quenty/brio": "^14.7.0",
-    "@quenty/ducktype": "^5.5.0",
-    "@quenty/loader": "^10.5.0",
-    "@quenty/maid": "^3.3.0",
-    "@quenty/promise": "^10.5.0",
-    "@quenty/rx": "^13.7.0",
-    "@quenty/signal": "^7.6.0",
-    "@quenty/steputils": "^3.5.0",
-    "@quenty/symbol": "^3.1.0",
-    "@quenty/valueobject": "^13.7.0"
+    "@quenty/baseobject": "^10.6.0",
+    "@quenty/brio": "^14.8.1",
+    "@quenty/ducktype": "^5.6.0",
+    "@quenty/loader": "^10.6.0",
+    "@quenty/maid": "^3.4.0",
+    "@quenty/promise": "^10.6.0",
+    "@quenty/rx": "^13.8.0",
+    "@quenty/signal": "^7.7.0",
+    "@quenty/steputils": "^3.5.1",
+    "@quenty/symbol": "^3.2.0",
+    "@quenty/valueobject": "^13.8.1"
   },
   "devDependencies": {
-    "@quenty/blend": "^12.7.0"
+    "@quenty/blend": "^12.8.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9b17fe79cddd071f0f06a9d35184e76b44bd6fe6"
+  "gitHead": "539802fea720a92f81ad48d6d5579605d8844d0a"
 }

package/src/Shared/ObservableList.lua

@@ -205,7 +205,7 @@ end
 	@return Observable<number>
 ]=]
 function ObservableList:ObserveIndexByKey(key)
-	assert(type(key) == "userdata", "Bad key")
+	assert(Symbol.isSymbol(key), "Bad key")
 
 	return self._keyIndexObservables:Observe(key, function(sub)
 		sub:Fire(self:GetIndexByKey(key))
@@ -417,9 +417,9 @@ end
 	@return { T }
 ]=]
 function ObservableList:GetList()
-	local list = {}
-	for _, key in pairs(self._keyList) do
-		table.insert(list, self._contents[key])
+	local list = table.create(#self._keyList)
+	for index, key in pairs(self._keyList) do
+		list[index] = self._contents[key]
 	end
 	return list
 end

package/src/Shared/ObservableMap.lua

@@ -184,10 +184,9 @@ function ObservableMap:ObserveAtKeyBrio(key)
 	assert(key ~= nil, "Bad key")
 
 	return self:ObserveAtKey(key):Pipe({
-		RxBrioUtils.toBrio();
-		RxBrioUtils.where(function(value)
+		RxBrioUtils.switchToBrio(function(value)
 			return value ~= nil
-		end)
+		end);
 	})
 end
 
@@ -275,7 +274,7 @@ end
 	@return { TValue }
 ]=]
 function ObservableMap:GetValueList()
-	local list = {}
+	local list = table.create(self._countValue.Value)
 	for _, value in pairs(self._map) do
 		table.insert(list, value)
 	end
@@ -287,7 +286,7 @@ end
 	@return { TKey }
 ]=]
 function ObservableMap:GetKeyList()
-	local list = {}
+	local list = table.create(self._countValue.Value)
 	for key, _ in pairs(self._map) do
 		table.insert(list, key)
 	end
@@ -303,7 +302,10 @@ function ObservableMap:ObserveKeyList()
 		local topMaid = Maid.new()
 
 		-- TODO: maybe don't allocate as much here?
-		local keyList = {}
+		local keyList = table.create(self._countValue.Value)
+		for key, _ in pairs(self._map) do
+			table.insert(keyList, key)
+		end
 
 		topMaid:GiveTask(self.KeyAdded:Connect(function(addedKey)
 			table.insert(keyList, addedKey)
@@ -318,10 +320,6 @@ function ObservableMap:ObserveKeyList()
 			sub:Fire(table.clone(keyList))
 		end))
 
-		for key, _ in pairs(self._map) do
-			table.insert(keyList, key)
-		end
-
 		sub:Fire(table.clone(keyList))
 
 		return topMaid

package/src/Shared/ObservableMapList.lua

@@ -27,6 +27,29 @@ function ObservableMapList.new()
 	self._maid = Maid.new()
 	self._observableMapOfLists = self._maid:Add(ObservableMap.new())
 
+--[=[
+	Fires when an item is added
+	@readonly
+	@prop ListAdded Signal<TKey>
+	@within ObservableMapSet
+]=]
+	self.ListAdded = assert(self._observableMapOfLists.KeyAdded, "Bad KeyAdded") -- :Fire(key, set)
+
+--[=[
+	Fires when an item is removed
+	@readonly
+	@prop ListRemoved Signal<TKey>
+	@within ObservableMapSet
+]=]
+	self.ListRemoved = assert(self._observableMapOfLists.KeyRemoved, "Bad KeyRemoved") -- :Fire(key)
+
+--[=[
+	Fires when the count changes.
+	@prop CountChanged RBXScriptSignal
+	@within ObservableMap
+]=]
+	self.CountChanged = assert(self._observableMapOfLists.CountChanged, "Bad CountChanged")
+
 	return self
 end
 
@@ -46,19 +69,19 @@ function ObservableMapList:Push(observeKey, entry)
 	assert(observeKey ~= nil, "Bad observeKey")
 	assert(entry ~= nil, "Bad entry")
 
-	if not Observable.isObservable(observeKey) then
-		observeKey = Rx.of(observeKey)
-	end
-
 	local maid = Maid.new()
 
-	maid:GiveTask(observeKey:Subscribe(function(key)
-		maid._currentAddValue = nil
+	if Observable.isObservable(observeKey) then
+		maid:GiveTask(observeKey:Subscribe(function(key)
+			maid._currentAddValue = nil
 
-		if key ~= nil then
-			maid._currentAddValue = self:_addToList(key, entry)
-		end
-	end))
+			if key ~= nil then
+				maid._currentAddValue = self:_addToList(key, entry)
+			end
+		end))
+	else
+		maid:GiveTask(self:_addToList(observeKey, entry))
+	end
 
 	-- Ensure self-cleanup when map cleans up
 	self._maid[maid] = maid
@@ -221,18 +244,36 @@ function ObservableMapList:GetListForKey(key)
 	return self._observableMapOfLists:Get(key)
 end
 
+--[=[
+	Observes the observable list for the given key
+
+	@param key TKey
+	@return Observable<ObservableList<TValue>>
+]=]
 function ObservableMapList:ObserveList(key)
 	assert(key ~= nil, "Bad key")
 
 	return self._observableMapOfLists:ObserveAtKey(key)
 end
 
+--[=[
+	Observes the observable list for the given key
+
+	@param key TKey
+	@return Observable<Brio<ObservableList<TValue>>>
+]=]
 function ObservableMapList:ObserveListBrio(key)
 	assert(key ~= nil, "Bad key")
 
 	return self._observableMapOfLists:ObserveAtKeyBrio(key)
 end
 
+--[=[
+	Observes the number of entries for the given key
+
+	@param key TKey
+	@return Observable<number>
+]=]
 function ObservableMapList:ObserveCountForKey(key)
 	assert(key ~= nil, "Bad key")
 
@@ -249,10 +290,6 @@ function ObservableMapList:_addToList(key, entry)
 	return list:Add(entry)
 end
 
-function ObservableMapList:_removeList(list)
-	self._maid[list] = nil
-end
-
 function ObservableMapList:_getOrCreateList(key)
 	local existing = self._observableMapOfLists:Get(key)
 	if existing then

package/src/Shared/ObservableMapSet.lua

@@ -9,12 +9,10 @@ local require = require(script.Parent.loader).load(script)
 
 local Maid = require("Maid")
 local Observable = require("Observable")
+local ObservableMap = require("ObservableMap")
 local ObservableSet = require("ObservableSet")
-local Signal = require("Signal")
-local Brio = require("Brio")
-local RxBrioUtils = require("RxBrioUtils")
-local ValueObject = require("ValueObject")
 local Rx = require("Rx")
+local RxBrioUtils = require("RxBrioUtils")
 
 local ObservableMapSet = {}
 ObservableMapSet.ClassName = "ObservableMapSet"
@@ -28,7 +26,7 @@ function ObservableMapSet.new()
 	local self = setmetatable({}, ObservableMapSet)
 
 	self._maid = Maid.new()
-	self._observableSetMap = {} -- [key] = ObservableSet<TEntry>
+	self._observableMapOfSets = self._maid:Add(ObservableMap.new())
 
 --[=[
 	Fires when an item is added
@@ -36,7 +34,7 @@ function ObservableMapSet.new()
 	@prop SetAdded Signal<TKey>
 	@within ObservableMapSet
 ]=]
-	self.SetAdded = self._maid:Add(Signal.new()) -- :Fire(key, set)
+	self.SetAdded = assert(self._observableMapOfSets.KeyAdded, "Bad KeyAdded") -- :Fire(key, set)
 
 --[=[
 	Fires when an item is removed
@@ -44,9 +42,14 @@ function ObservableMapSet.new()
 	@prop SetRemoved Signal<TKey>
 	@within ObservableMapSet
 ]=]
-	self.SetRemoved = self._maid:Add(Signal.new()) -- :Fire(key)
+	self.SetRemoved = assert(self._observableMapOfSets.KeyRemoved, "Bad KeyRemoved") -- :Fire(key)
 
-	self._setCount = self._maid:Add(ValueObject.new(0, "number"))
+--[=[
+	Fires when the count changes.
+	@prop CountChanged RBXScriptSignal
+	@within ObservableMap
+]=]
+	self.CountChanged = assert(self._observableMapOfSets.CountChanged, "Bad CountChanged")
 
 	return self
 end
@@ -68,31 +71,19 @@ function ObservableMapSet:Push(observeKey, entry)
 	assert(observeKey ~= nil, "Bad observeKey")
 	assert(entry ~= nil, "Bad entry")
 
-	if not Observable.isObservable(observeKey) then
-		observeKey = Rx.of(observeKey)
-	end
-
 	local maid = Maid.new()
 
-	local lastKey = nil
-	local function removeLastEntry()
-		if lastKey ~= nil then
-			self:_removeFromObservableSet(lastKey, entry)
-		end
-		lastKey = nil
-	end
-
-	maid:GiveTask(observeKey:Subscribe(function(key)
-		removeLastEntry()
+	if Observable.isObservable(observeKey) then
+		maid:GiveTask(observeKey:Subscribe(function(key)
+			maid._currentAddValue = nil
 
-		if key ~= nil then
-			self:_addToObservableSet(key, entry)
-		end
-
-		lastKey = key
-	end))
-
-	maid:GiveTask(removeLastEntry)
+			if key ~= nil then
+				maid._currentAddValue = self:_addToSet(key, entry)
+			end
+		end))
+	else
+		maid:GiveTask(self:_addToSet(observeKey, entry))
+	end
 
 	-- Ensure self-cleanup when map cleans up
 	self._maid[maid] = maid
@@ -131,12 +122,8 @@ end
 	Gets a list of all keys.
 	@return { TKey }
 ]=]
-function ObservableMapSet:GetKeyList()
-	local list = {}
-	for key, _ in pairs(self._observableSetMap) do
-		table.insert(list, key)
-	end
-	return list
+function ObservableMapSet:ObserveKeyList()
+	return self._observableMapOfSets:GetKeyList()
 end
 
 --[=[
@@ -144,33 +131,15 @@ end
 	@return Observable<{ TKey }>
 ]=]
 function ObservableMapSet:ObserveKeyList()
-	return Observable.new(function(sub)
-		local topMaid = Maid.new()
-
-		-- TODO: maybe don't allocate as much here?
-		local keyList = {}
-
-		topMaid:GiveTask(self.SetAdded:Connect(function(addedKey)
-			table.insert(keyList, addedKey)
-			sub:Fire(table.clone(keyList))
-		end))
-
-		topMaid:GiveTask(self.SetRemoved:Connect(function(removedKey)
-			local index = table.find(keyList, removedKey)
-			if index then
-				table.remove(keyList, index)
-			end
-			sub:Fire(table.clone(keyList))
-		end))
-
-		for key, _ in pairs(self._observableSetMap) do
-			table.insert(keyList, key)
-		end
-
-		sub:Fire(table.clone(keyList))
+	return self._observableMapOfSets:ObserveKeyList()
+end
 
-		return topMaid
-	end)
+--[=[
+	Observes all keys in the map
+	@return Observable<Brio<TKey>>
+]=]
+function ObservableMapSet:ObserveKeysBrio()
+	return self._observableMapOfSets:ObserveKeysBrio()
 end
 
 --[=[
@@ -178,7 +147,7 @@ end
 	@return number
 ]=]
 function ObservableMapSet:GetSetCount()
-	return self._setCount.Value
+	return self._observableMapOfSets:GetCount()
 end
 
 --[=[
@@ -186,7 +155,7 @@ end
 	@return Observable<number>
 ]=]
 function ObservableMapSet:ObserveSetCount()
-	return self._setCount:Observe()
+	return self._observableMapOfSets:ObserveCount()
 end
 
 --[=[
@@ -197,49 +166,26 @@ end
 function ObservableMapSet:ObserveItemsForKeyBrio(key)
 	assert(key ~= nil, "Bad key")
 
-	return Observable.new(function(sub)
-		local topMaid = Maid.new()
-
-		local function connect()
-			local maid = Maid.new()
-
-			local set = self._observableSetMap[key]
+	return self._observableMapOfSets:ObserveAtKeyBrio(key):Pipe({
+		RxBrioUtils.switchMapBrio(function(set)
 			if set then
-				maid:GiveTask(set:ObserveItemsBrio():Subscribe(function(brio)
-					sub:Fire(brio)
-				end))
+				return set:ObserveItemsBrio()
+			else
+				return Rx.EMPTY
 			end
-
-			topMaid._current = maid
-		end
-
-		topMaid:GiveTask(self.SetAdded:Connect(function(addedKey)
-			if addedKey == key then
-				connect()
-			end
-		end))
-
-		topMaid:GiveTask(self.SetRemoved:Connect(function(removedKey)
-			if removedKey == key then
-				connect()
-			end
-		end))
-
-		connect()
-
-		return topMaid
-	end)
+		end);
+	})
 end
 
 --[=[
 	Gets the first item for the given key
 	@param key TKey
-	@return TValue
+	@return TValue | nil
 ]=]
 function ObservableMapSet:GetFirstItemForKey(key)
 	assert(key ~= nil, "Bad key")
 
-	local observableSet = self._observableSetMap[key]
+	local observableSet = self:GetObservableSetForKey(key)
 	if not observableSet then
 		return nil
 	end
@@ -255,7 +201,7 @@ end
 function ObservableMapSet:GetListForKey(key)
 	assert(key ~= nil, "Bad key")
 
-	local observableSet = self._observableSetMap[key]
+	local observableSet = self:GetObservableSetForKey(key)
 	if not observableSet then
 		return {}
 	end
@@ -271,45 +217,27 @@ end
 function ObservableMapSet:GetObservableSetForKey(key)
 	assert(key ~= nil, "Bad key")
 
-	return self._observableSetMap[key]
+	return self._observableMapOfSets:Get(key)
 end
 
+--[=[
+	Observes the observable set for the given key
+
+	@param key TKey
+	@return Observable<Brio<ObservableSet<TValue>>>
+]=]
 function ObservableMapSet:ObserveSetBrio(key)
 	assert(key ~= nil, "Bad key")
 
-	return Observable.new(function(sub)
-		local topMaid = Maid.new()
-
-		local function connect()
-			local brio
-
-			local set = self._observableSetMap[key]
-			if set then
-				brio = Brio.new(set)
-				sub:Fire(brio)
-			end
-
-			topMaid._current = brio
-		end
-
-		topMaid:GiveTask(self.SetAdded:Connect(function(addedKey)
-			if addedKey == key then
-				connect()
-			end
-		end))
-
-		topMaid:GiveTask(self.SetRemoved:Connect(function(removedKey)
-			if removedKey == key then
-				connect()
-			end
-		end))
-
-		connect()
-
-		return topMaid
-	end)
+	return self._observableMapOfSets:ObserveAtKeyBrio(key)
 end
 
+--[=[
+	Observes the number of entries for the given key
+
+	@param key TKey
+	@return Observable<number>
+]=]
 function ObservableMapSet:ObserveCountForKey(key)
 	assert(key ~= nil, "Bad key")
 
@@ -321,66 +249,30 @@ function ObservableMapSet:ObserveCountForKey(key)
 	})
 end
 
-function ObservableMapSet:_addToObservableSet(key, entry)
-	local set = self:_getOrCreateObservableSet(key)
-	set:Add(entry)
-end
-
-function ObservableMapSet:_removeFromObservableSet(key, entry)
-	local set = self._observableSetMap[key]
-	if not set then
-		return
-	end
-
-	-- This happens when we're cleaning up sometimes
-	if not set.Destroy then
-		return
-	end
-
-	if set:Contains(entry) then
-		set:Remove(entry)
-		if set:GetCount() == 0 then
-			self:_removeObservableSet(key)
-		end
-	end
-end
-
-function ObservableMapSet:_removeObservableSet(key)
-	local set = self._observableSetMap[key]
-	if set then
-		self._observableSetMap[key] = nil
 
-		-- Cleanup
-		self._maid[set] = nil
-
-		if self.SetRemoved.Destroy then
-			self.SetRemoved:Fire(key)
-		end
-
-		if self._setCount.Destroy then
-			self._setCount.Value = self._setCount.Value - 1
-		end
-	end
+function ObservableMapSet:_addToSet(key, entry)
+	local set = self:_getOrCreateSet(key)
+	return set:Add(entry)
 end
 
-function ObservableMapSet:_getOrCreateObservableSet(key)
-	if self._observableSetMap[key] then
-		return self._observableSetMap[key]
+function ObservableMapSet:_getOrCreateSet(key)
+	local existing = self._observableMapOfSets:Get(key)
+	if existing then
+		return existing
 	end
 
 	local maid = Maid.new()
-	local set = ObservableSet.new()
-	maid:GiveTask(set)
-
-	self._observableSetMap[key] = set
+	local set = maid:Add(ObservableSet.new(nil))
 
-	self.SetAdded:Fire(key, set)
-
-	if self._setCount.Destroy then
-		self._setCount.Value = self._setCount.Value + 1
-	end
+	maid:GiveTask(set.CountChanged:Connect(function(count)
+		if count <= 0 then
+			self._maid[set] = nil
+		end
+	end))
 
+	maid:GiveTask(self._observableMapOfSets:Set(key, set))
 	self._maid[set] = maid
+
 	return set
 end
 

package/src/Shared/ObservableSet.lua

@@ -223,7 +223,7 @@ end
 	@return { T }
 ]=]
 function ObservableSet:GetList()
-	local list = {}
+	local list = table.create(self._countValue.Value)
 	for item, _ in pairs(self._set) do
 		table.insert(list, item)
 	end

package/src/Shared/ObservableSortedList.lua

@@ -58,11 +58,8 @@ function ObservableSortedList.new(isReversed, compare)
 
 	self._keyList = {} -- { [number]: Symbol } -- immutable
 
-	self._indexObservers = ObservableSubscriptionTable.new()
-	self._maid:GiveTask(self._indexObservers)
-
-	self._contentIndexObservers = ObservableSubscriptionTable.new()
-	self._maid:GiveTask(self._contentIndexObservers)
+	self._indexObservers = self._maid:Add(ObservableSubscriptionTable.new())
+	self._contentIndexObservers = self._maid:Add(ObservableSubscriptionTable.new())
 
 	self._sortValue = {} -- { [Symbol]: number }
 	self._contents = {} -- { [Symbol]: T }
@@ -127,6 +124,16 @@ function ObservableSortedList:Observe()
 	})
 end
 
+function ObservableSortedList:Contains(value)
+	-- TODO: Binary search
+	for _, item in pairs(self._contents) do
+		if item == value then
+			return true
+		end
+	end
+
+	return false
+end
 
 --[=[
 	Returns whether the value is an observable list
@@ -230,7 +237,7 @@ end
 	@return Observable<number>
 ]=]
 function ObservableSortedList:ObserveIndexByKey(key)
-	assert(type(key) == "userdata", "Bad key")
+	assert(Symbol.isSymbol(key), "Bad key")
 
 	return Observable.new(function(sub)
 		local maid = Maid.new()
@@ -289,9 +296,9 @@ end
 	@return { T }
 ]=]
 function ObservableSortedList:GetList()
-	local list = {}
-	for _, key in pairs(self._keyList) do
-		table.insert(list, self._contents[key])
+	local list = table.create(#self._keyList)
+	for index, key in pairs(self._keyList) do
+		list[index] = self._contents[key]
 	end
 	return list
 end
@@ -307,41 +314,27 @@ end
 --[=[
 	Adds the item to the list at the specified index
 	@param item T
-	@param observeValue Observable<Comparable>
+	@param observeValue Observable<Comparable> | Comparable
 	@return callback -- Call to remove
 ]=]
 function ObservableSortedList:Add(item, observeValue)
 	assert(item ~= nil, "Bad item")
-	assert(Observable.isObservable(observeValue), "Bad observeValue")
+	assert(Observable.isObservable(observeValue) or observeValue ~= nil, "Bad observeValue")
 
 	local key = Symbol.named("entryKey")
 	local maid = Maid.new()
 
 	self._contents[key] = item
 
-	maid:GiveTask(observeValue:Subscribe(function(sortValue)
-		self:_debugVerifyIntegrity()
-
-		if sortValue ~= nil then
-			local currentIndex = self._indexes[key]
-			local targetIndex = self:_findCorrectIndex(sortValue, currentIndex)
-
-			self._sortValue[key] = sortValue
-			self:_updateIndex(key, item, targetIndex, sortValue)
-		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
-
-		self:_debugVerifyIntegrity()
-	end))
+	if Observable.isObservable(observeValue) then
+		maid:GiveTask(observeValue:Subscribe(function(sortValue)
+			self:_assignSortValue(key, item, sortValue)
+		end))
+	elseif observeValue ~= nil then
+		self:_assignSortValue(key, item, observeValue)
+	else
+		error("Bad observeValue")
+	end
 
 	maid:GiveTask(function()
 		local observableSubs = self._keyObservables[key]
@@ -365,6 +358,31 @@ function ObservableSortedList:Add(item, observeValue)
 	end
 end
 
+function ObservableSortedList:_assignSortValue(key, item, sortValue)
+	self:_debugVerifyIntegrity()
+
+	if sortValue ~= nil then
+		local currentIndex = self._indexes[key]
+		local targetIndex = self:_findCorrectIndex(sortValue, currentIndex)
+
+		self._sortValue[key] = sortValue
+		self:_updateIndex(key, item, targetIndex, sortValue)
+	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
+
+	self:_debugVerifyIntegrity()
+end
+
+
 --[=[
 	Gets the current item at the index, or nil if it is not defined.
 	@param index number
@@ -446,11 +464,11 @@ function ObservableSortedList:_updateIndex(key, item, newIndex)
 		error("Bad state")
 	end
 
-	local itemAdded = {
+	local itemAdded = table.freeze({
 		key = key;
 		newIndex = newIndex;
 		item = item;
-	}
+	})
 
 	-- ensure ourself is considered changed
 	table.insert(changed, itemAdded)
@@ -493,11 +511,11 @@ function ObservableSortedList:_removeItemByKey(key, item)
 	end
 	self._keyList[n] = nil
 
-	local itemRemoved = {
+	local itemRemoved = table.freeze({
 		key = key;
 		item = item;
 		previousIndex = index;
-	}
+	})
 
 	-- TODO: Defer item removed as a changed event?