@quenty/observablecollection 2.2.0 → 2.2.1-canary.261.5628274.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.
 
+## [2.2.1-canary.261.5628274.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/observablecollection@2.2.0...@quenty/observablecollection@2.2.1-canary.261.5628274.0) (2022-05-21)
+
+
+### Features
+
+* Add more observable collections ([039cea8](https://github.com/Quenty/NevermoreEngine/commit/039cea80f4f21c075f3d857f70dac709c2ce1a64))
+
+
+
+
+
 # [2.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/observablecollection@2.1.0...@quenty/observablecollection@2.2.0) (2022-03-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/observablecollection",
-  "version": "2.2.0",
+  "version": "2.2.1-canary.261.5628274.0",
   "description": "An observable set",
   "keywords": [
     "Roblox",
@@ -27,16 +27,17 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/brio": "^5.2.0",
-    "@quenty/loader": "^4.1.0",
-    "@quenty/maid": "^2.3.0",
-    "@quenty/promise": "^4.2.0",
-    "@quenty/rx": "^4.2.0",
-    "@quenty/signal": "^2.2.0",
-    "@quenty/valuebaseutils": "^4.2.0"
+    "@quenty/brio": "5.2.1-canary.261.5628274.0",
+    "@quenty/loader": "4.1.1-canary.261.5628274.0",
+    "@quenty/maid": "2.3.0",
+    "@quenty/promise": "4.2.1-canary.261.5628274.0",
+    "@quenty/rx": "4.2.1-canary.261.5628274.0",
+    "@quenty/signal": "2.2.0",
+    "@quenty/symbol": "2.1.0",
+    "@quenty/valuebaseutils": "4.2.1-canary.261.5628274.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "501844bd6c3d3f765fd3032b997d8030bc963a1f"
+  "gitHead": "5628274461f4fa0135e63b62e99fcd508d4c94f9"
 }

package/src/Shared/ObservableCountingMap.lua

@@ -0,0 +1,338 @@
+--[=[
+	An observable map that counts up/down and removes when the count is zero.
+	@class ObservableCountingMap
+]=]
+
+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 ObservableCountingMap = {}
+ObservableCountingMap.ClassName = "ObservableCountingMap"
+ObservableCountingMap.__index = ObservableCountingMap
+
+--[=[
+	Constructs a new ObservableCountingMap
+	@return ObservableCountingMap<T>
+]=]
+function ObservableCountingMap.new()
+	local self = setmetatable({}, ObservableCountingMap)
+
+	self._maid = Maid.new()
+	self._map = {}
+
+	self._totalKeyCountValue = Instance.new("IntValue")
+	self._totalKeyCountValue.Value = 0
+	self._maid:GiveTask(self._totalKeyCountValue)
+
+--[=[
+	Fires when an key is added
+	@readonly
+	@prop KeyAdded Signal<T>
+	@within ObservableCountingMap
+]=]
+	self.KeyAdded = Signal.new()
+	self._maid:GiveTask(self.KeyAdded)
+
+--[=[
+	Fires when an key is removed.
+	@readonly
+	@prop KeyRemoved Signal<T>
+	@within ObservableCountingMap
+]=]
+	self.KeyRemoved = Signal.new()
+	self._maid:GiveTask(self.KeyRemoved)
+
+--[=[
+	Fires when an item count changes
+	@readonly
+	@prop KeyChanged Signal<T>
+	@within ObservableCountingMap
+]=]
+	self.KeyChanged = Signal.new()
+	self._maid:GiveTask(self.KeyChanged)
+
+--[=[
+	Fires when the total count changes.
+	@prop CountChanged RBXScriptSignal
+	@within ObservableCountingMap
+]=]
+	self.TotalKeyCountChanged = self._totalKeyCountValue.Changed
+
+	return self
+end
+
+--[=[
+	Returns whether the value is an observable counting map
+	@param value any
+	@return boolean
+]=]
+function ObservableCountingMap.isObservableMap(value)
+	return type(value) == "table" and getmetatable(value) == ObservableCountingMap
+end
+
+--[=[
+	Observes the current set of active keys
+	@return Observable<{ T }>
+]=]
+function ObservableCountingMap:ObserveKeysList()
+	return self:_observeDerivedDataStructureFromKeys(function()
+		local list = {}
+
+		for key, _ in pairs(self._map) do
+			table.insert(list, key)
+		end
+
+		return list
+	end)
+end
+
+--[=[
+	Observes the current set of active keys
+	@return Observable<{ [T]: true }>
+]=]
+function ObservableCountingMap:ObserveKeysSet()
+	return self:_observeDerivedDataStructureFromKeys(function()
+		local set = {}
+
+		for key, _ in pairs(self._map) do
+			set[key] = true
+		end
+
+		return set
+	end)
+end
+
+function ObservableCountingMap:_observeDerivedDataStructureFromKeys(gatherValues)
+		return Observable.new(function(sub)
+		local maid = Maid.new()
+
+		local function emit()
+			sub:Fire(gatherValues())
+		end
+
+		maid:GiveTask(self.KeyAdded:Connect(emit))
+		maid:GiveTask(self.KeyRemoved:Connect(emit))
+
+		emit()
+
+		self._maid[sub] = maid
+		maid:GiveTask(function()
+			self._maid[sub] = nil
+			sub:Complete()
+		end)
+
+		return maid
+	end)
+end
+
+--[=[
+	Observes all keys in the map
+	@return Observable<Brio<T>>
+]=]
+function ObservableCountingMap:ObserveKeysBrio()
+	return Observable.new(function(sub)
+		local maid = Maid.new()
+
+		local function handleItem(key)
+			local brio = Brio.new(key)
+			maid[key] = brio
+			sub:Fire(brio)
+		end
+
+		for key, _ in pairs(self._map) do
+			handleItem(key)
+		end
+
+		maid:GiveTask(self.KeyAdded:Connect(handleItem))
+		maid:GiveTask(self.KeyRemoved:Connect(function(key)
+			maid[key] = nil
+		end))
+
+		self._maid[sub] = maid
+		maid:GiveTask(function()
+			self._maid[sub] = nil
+			sub:Complete()
+		end)
+
+		return maid
+	end)
+end
+
+--[=[
+	Returns whether the map contains the key
+	@param key T
+	@return boolean
+]=]
+function ObservableCountingMap:Contains(key)
+	assert(key ~= nil, "Bad key")
+
+	return self._map[key] ~= nil
+end
+
+--[=[
+	Returns the count for the key or 0 if there is no key
+	@param key T
+	@return number
+]=]
+function ObservableCountingMap:Get(key)
+	assert(key ~= nil, "Bad key")
+
+	return self._map[key] or 0
+end
+
+--[=[
+	Gets the count of keys in the map
+	@return number
+]=]
+function ObservableCountingMap:GetTotalKeyCount()
+	return self._totalKeyCountValue.Value
+end
+
+--[=[
+	Observes the count of the keys in the map
+	@return Observable<number>
+]=]
+function ObservableCountingMap:ObserveTotalKeyCount()
+	return RxValueBaseUtils.observeValue(self._totalKeyCountValue)
+end
+
+--[=[
+	Sets the current value
+	@param key T
+	@param amount number?
+	@return callback
+]=]
+function ObservableCountingMap:Set(key, amount)
+	local current = self:Get(key)
+	if current == amount then
+		return
+	end
+
+	if current < amount then
+		self:Remove(amount - current)
+		return
+	elseif current == amount then
+		return
+	else
+		self:Add(current - amount)
+		return
+	end
+end
+
+--[=[
+	Adds the key to the map if it does not exists.
+	@param key T
+	@param amount number?
+	@return callback
+]=]
+function ObservableCountingMap:Add(key, amount)
+	assert(key ~= nil, "Bad key")
+	assert(type(amount) == "number" or amount == nil, "Bad amount")
+	amount = amount or 1
+
+	if amount == 0 then
+		return
+	elseif amount < 0 then
+		self:Remove(key, -amount)
+		return
+	end
+
+	if not self._map[key] then
+		self._map[key] = amount
+		self._totalKeyCountValue.Value = self._totalKeyCountValue.Value + 1
+
+		if self.Destroy then
+			self.KeyAdded:Fire(key)
+		end
+	else
+		local newValue = self._map[key] + amount
+		self._map[key] = newValue
+		self.KeyChanged:Fire(key, newValue)
+	end
+
+	local removed = false
+	return function()
+		if self.Destroy and not removed then
+			removed = true
+			self:RemoveCount(key, amount)
+		end
+	end
+end
+
+--[=[
+	Removes the key from the set if it exists.
+	@param key T
+	@param amount number?
+	@return callback
+]=]
+function ObservableCountingMap:RemoveCount(key, amount)
+	assert(key ~= nil, "Bad key")
+	assert(type(amount) == "number" or amount == nil, "Bad amount")
+	amount = amount or 1
+
+	if amount == 0 then
+		return
+	elseif amount < 0 then
+		self:Add(key, -amount)
+		return
+	end
+
+	local current = self._map[key]
+	if not current then
+		return
+	end
+
+	local newValue = current - amount
+	if newValue > 0 then
+		self._map[key] = newValue
+		self.KeyChanged:Fire(key, newValue)
+	else
+		self._map[key] = nil
+
+		self._totalKeyCountValue.Value = self._totalKeyCountValue.Value - 1
+
+		if self.Destroy then
+			self.KeyRemoved:Fire(key)
+		end
+
+		if self.Destroy then
+			self.KeyChanged:Fire(key, 0)
+		end
+	end
+end
+
+--[=[
+	Gets the first key
+	@return T
+]=]
+function ObservableCountingMap:GetFirstKey()
+	local value = next(self._map)
+	return value
+end
+
+--[=[
+	Gets a list of all keys.
+	@return { T }
+]=]
+function ObservableCountingMap:GetKeysList()
+	local list = {}
+	for key, _ in pairs(self._map) do
+		table.insert(list, key)
+	end
+	return list
+end
+
+--[=[
+	Cleans up the ObservableCountingMap and sets the metatable to nil.
+]=]
+function ObservableCountingMap:Destroy()
+	self._maid:DoCleaning()
+	setmetatable(self, nil)
+end
+
+return ObservableCountingMap

package/src/Shared/ObservableCountingMap.spec.lua

@@ -0,0 +1,38 @@
+--[[
+	@class ObservableCountingMap.spec.lua
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local ObservableCountingMap = require("ObservableCountingMap")
+
+return function()
+	describe("ObservableCountingMap.new()", function()
+		local observableCountingMap = ObservableCountingMap.new()
+
+		it("should return 0 for unset values", function()
+			expect(observableCountingMap:Get("a")).to.equal(0)
+			expect(observableCountingMap:GetTotalKeyCount()).to.equal(0)
+		end)
+
+		it("should allow you to add to a value", function()
+			expect(observableCountingMap:Get("a")).to.equal(0)
+			expect(observableCountingMap:GetTotalKeyCount()).to.equal(0)
+			observableCountingMap:Add("a", 5)
+			expect(observableCountingMap:Get("a")).to.equal(5)
+			expect(observableCountingMap:GetTotalKeyCount()).to.equal(1)
+		end)
+
+		it("should allow you to add to a value that is already defined", function()
+			expect(observableCountingMap:Get("a")).to.equal(5)
+			expect(observableCountingMap:GetTotalKeyCount()).to.equal(1)
+			observableCountingMap:Add("a", 5)
+			expect(observableCountingMap:Get("a")).to.equal(10)
+			expect(observableCountingMap:GetTotalKeyCount()).to.equal(1)
+		end)
+
+		it("should clean up", function()
+			observableCountingMap:Destroy()
+		end)
+	end)
+end

package/src/Shared/ObservableList.lua

@@ -0,0 +1,400 @@
+--[=[
+	A list that can be observed for blend and other components
+	@class ObservableList
+]=]
+
+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 ObservableList = {}
+ObservableList.ClassName = "ObservableList"
+ObservableList.__index = ObservableList
+
+--[=[
+	Constructs a new ObservableList
+	@return ObservableList<T>
+]=]
+function ObservableList.new()
+	local self = setmetatable({}, ObservableList)
+
+	self._maid = Maid.new()
+
+	self._keyList = {} -- { [number]: Symbol }
+	self._contents = {} -- { [Symbol]: T }
+	self._indexes = {} -- { [Symbol]: number }
+
+	self._keyObservables = {} -- { [Symbol]: { Subscription } }
+
+	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 ObservableList
+]=]
+	self.ItemAdded = Signal.new()
+	self._maid:GiveTask(self.ItemAdded)
+
+--[=[
+	Fires when an item is removed.
+	@readonly
+	@prop ItemRemoved Signal<T, Symbol>
+	@within ObservableList
+]=]
+	self.ItemRemoved = Signal.new()
+	self._maid:GiveTask(self.ItemRemoved)
+
+--[=[
+	Fires when the count changes.
+	@prop CountChanged RBXScriptSignal
+	@within ObservableList
+]=]
+	self.CountChanged = self._countValue.Changed
+
+	return self
+end
+
+--[=[
+	Returns whether the value is an observable list
+	@param value any
+	@return boolean
+]=]
+function ObservableList.isObservableList(value)
+	return type(value) == "table" and getmetatable(value) == ObservableList
+end
+
+--[=[
+	Observes all items in the list
+	@return Observable<Brio<T>>
+]=]
+function ObservableList: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 ObservableList: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 ObservableList:ObserveIndexByKey(key)
+	assert(key, "Bad key")
+
+	return Observable.new(function(sub)
+		local currentIndex = self._indexes[key]
+		if not currentIndex then
+			sub:Complete()
+			return
+		end
+
+		local maid = Maid.new()
+		self._keyObservables[key] = self._keyObservables[key] or {}
+		table.insert(self._keyObservables[key], sub)
+
+		sub:Fire(currentIndex)
+
+		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 count of items in the list
+	@return number
+]=]
+function ObservableList:GetCount()
+	return self._countValue.Value
+end
+
+--[=[
+	Observes the count of the list
+	@return Observable<number>
+]=]
+function ObservableList:ObserveCount()
+	return RxValueBaseUtils.observeValue(self._countValue)
+end
+
+--[=[
+	Adds the item to the list at the specified index
+	@param item T
+	@return callback -- Call to remove
+]=]
+function ObservableList:Add(item)
+	return self:InsertAt(item, #self._keyList + 1)
+end
+
+--[=[
+	Gets the current item at the index, or nil if it is not defined.
+	@param index number
+	@return T?
+]=]
+function ObservableList: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
+
+--[=[
+	Adds the item to the list at the specified index
+	@param item T
+	@param index number?
+	@return callback -- Call to remove
+]=]
+function ObservableList:InsertAt(item, index)
+	assert(item ~= nil, "Bad item")
+	assert(type(index) == "number", "Bad index")
+
+	index = math.clamp(index, 1, #self._keyList + 1)
+
+	local key = Symbol.named("entryKey")
+
+	self._contents[key] = item
+	self._indexes[key] = index
+
+	local changed = {}
+
+	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
+
+		local subs = self._keyObservables[nextKey]
+		if subs then
+			table.insert(changed, {
+				key = nextKey;
+				newIndex = i + 1;
+				subs = subs;
+			})
+		end
+	end
+
+	self._keyList[index] = key
+
+	-- Fire off count
+	self._countValue.Value = self._countValue.Value + 1
+
+	-- Fire off add
+	self.ItemAdded:Fire(item, index, key)
+
+	-- 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
+		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
+			self:_fireSubs(data.subs, data.newIndex)
+		end
+	end
+
+	return function()
+		if self.Destroy then
+			self:RemoveByKey(key)
+		end
+	end
+end
+
+--[=[
+	Removes the item at the index
+	@param index number
+	@return T
+]=]
+function ObservableList:RemoveAt(index)
+	assert(type(index) == "number", "Bad index")
+
+	local key = self._keyList[index]
+	if not key then
+		return nil
+	end
+
+	return self:RemoveByKey(key)
+end
+
+--[=[
+	Removes the item from the list if it exists.
+	@param key Symbol
+	@return T
+]=]
+function ObservableList:RemoveByKey(key)
+	assert(key ~= nil, "Bad key")
+
+	local index = self._indexes[key]
+	if not index then
+		return nil
+	end
+
+	local item = self._contents[key]
+	if not item then
+		return nil
+	end
+
+	local observableSubs = self._keyObservables[key]
+	self._keyObservables[key] = nil
+	self._indexes[key] = nil
+	self._contents[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
+
+		local subs = self._keyObservables[nextKey]
+		if subs then
+			table.insert(changed, {
+				key = nextKey;
+				newIndex = i;
+				subs = subs;
+			})
+		end
+	end
+	self._keyList[n] = nil
+
+	-- Fire off that count changed
+	self._countValue.Value = self._countValue.Value - 1
+
+	if self.Destroy then
+		self.ItemRemoved:Fire(item, key)
+	end
+
+	-- Fire off the index change on the value
+	if observableSubs then
+		self:_completeSubs(observableSubs)
+	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
+			self:_fireSubs(data.subs, data.newIndex)
+		end
+	end
+
+	return item
+end
+
+function ObservableList:_fireSubs(list, index)
+	for _, sub in pairs(list) do
+		if sub:IsPending() then
+			task.spawn(function()
+				sub:Fire(index)
+			end)
+		end
+	end
+end
+
+function ObservableList:_completeSubs(list)
+	for _, sub in pairs(list) do
+		if sub:IsPending() then
+			sub:Fire(nil)
+			sub:Complete()
+		end
+	end
+end
+
+--[=[
+	Gets a list of all entries.
+	@return { T }
+]=]
+function ObservableList:GetList()
+	local list = {}
+	for _, key in pairs(self._keyList) do
+		table.insert(list, self._contents[key])
+	end
+	return list
+end
+
+--[=[
+	Cleans up the ObservableList and sets the metatable to nil.
+]=]
+function ObservableList:Destroy()
+	self._maid:DoCleaning()
+	setmetatable(self, nil)
+end
+
+return ObservableList

package/src/Shared/ObservableList.spec.lua

@@ -0,0 +1,82 @@
+--[[
+	@class ObservableList.spec.lua
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local ObservableList = require("ObservableList")
+
+return function()
+	describe("ObservableList.new()", function()
+		local observableList = ObservableList.new()
+
+		it("should return nil for unset values", function()
+			expect(observableList:Get(1)).to.equal(nil)
+		end)
+
+		it("should allow inserting an value", function()
+			expect(observableList:GetCount()).to.equal(0)
+
+			observableList:Add("a")
+
+			expect(observableList:Get(1)).to.equal("a")
+			expect(observableList:GetCount()).to.equal(1)
+		end)
+
+
+		it("should allow false as a value", function()
+			expect(observableList:Get(2)).to.equal(nil)
+			observableList:Add(false)
+			expect(observableList:Get(2)).to.equal(false)
+		end)
+
+		it("should fire off events for a specific key", function()
+			local seen = {}
+			local sub = observableList:ObserveIndex(1):Subscribe(function(value)
+				table.insert(seen, value)
+			end)
+			observableList:InsertAt("c", 1)
+
+			sub:Destroy()
+
+			expect(#seen).to.equal(2)
+			expect(seen[1]).to.equal(1)
+			expect(seen[2]).to.equal(2)
+		end)
+
+		it("should fire off events for all keys", function()
+			local seen = {}
+			local sub = observableList:ObserveItemsBrio():Subscribe(function(value)
+				table.insert(seen, value)
+			end)
+			observableList:Add("a")
+
+			expect(#seen).to.equal(4)
+			expect(seen[4]:GetValue()).to.equal("a")
+			expect(seen[4]:IsDead()).to.equal(false)
+
+			sub:Destroy()
+
+			expect(#seen).to.equal(4)
+			expect(seen[4]:IsDead()).to.equal(true)
+		end)
+
+		it("should fire off events on removal", function()
+			local seen = {}
+			local sub = observableList:ObserveIndex(2):Subscribe(function(value)
+				table.insert(seen, value)
+			end)
+			observableList:RemoveAt(1)
+
+			sub:Destroy()
+
+			expect(#seen).to.equal(2)
+			expect(seen[1]).to.equal(2)
+			expect(seen[2]).to.equal(1)
+		end)
+
+		it("should clean up", function()
+			observableList:Destroy()
+		end)
+	end)
+end

package/src/Shared/ObservableMap.lua

@@ -0,0 +1,302 @@
+--[=[
+	A list that can be observed for blend and other components
+	@class ObservableMap
+]=]
+
+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 ObservableMap = {}
+ObservableMap.ClassName = "ObservableMap"
+ObservableMap.__index = ObservableMap
+
+--[=[
+	Constructs a new ObservableMap
+	@return ObservableMap<TKey, TValue>
+]=]
+function ObservableMap.new()
+	local self = setmetatable({}, ObservableMap)
+
+	self._maid = Maid.new()
+	self._map = {}
+
+	self._keyToSubList = {}
+
+	self._countValue = Instance.new("IntValue")
+	self._countValue.Value = 0
+	self._maid:GiveTask(self._countValue)
+
+--[=[
+	Fires when a key is added
+	@readonly
+	@prop KeyAdded Signal<TKey>
+	@within ObservableMap
+]=]
+	self.KeyAdded = Signal.new() -- :Fire(key, value)
+	self._maid:GiveTask(self.KeyAdded)
+
+--[=[
+	Fires when a key is removed
+	@readonly
+	@prop KeyRemoved Signal<TKey>
+	@within ObservableMap
+]=]
+	self.KeyRemoved = Signal.new() -- :Fire(key)
+	self._maid:GiveTask(self.KeyRemoved)
+
+--[=[
+	Fires when a key value changes, including add and remove.
+	@readonly
+	@prop KeyValueChanged Signal<(TKey, TValue, TValue)>
+	@within ObservableMap
+]=]
+	self.KeyValueChanged = Signal.new() -- :Fire(key, value, oldValue)
+	self._maid:GiveTask(self.KeyValueChanged)
+
+--[=[
+	Fires when the count changes.
+	@prop CountChanged RBXScriptSignal
+	@within ObservableMap
+]=]
+	self.CountChanged = self._countValue.Changed
+
+	return self
+end
+
+--[=[
+	Returns whether the set is an observable map
+	@param value any
+	@return boolean
+]=]
+function ObservableMap.isObservableMap(value)
+	return type(value) == "table" and getmetatable(value) == ObservableMap
+end
+
+--[=[
+	Observes all keys in the map
+	@return Observable<Brio<TKey>>
+]=]
+function ObservableMap:ObserveKeysBrio()
+	return self:_observeKeyValueChanged(function(key, _value)
+		return Brio.new(key)
+	end)
+end
+
+--[=[
+	Observes all keys in the map
+	@return Observable<Brio<TKey>>
+]=]
+function ObservableMap:ObserveValuesBrio()
+	return self:_observeKeyValueChanged(function(_key, value)
+		return Brio.new(value)
+	end)
+end
+
+--[=[
+	Observes all keys in the map
+	@return Observable<Brio<(TKey, TValue)>>
+]=]
+function ObservableMap:ObservePairsBrio()
+	return self:_observeKeyValueChanged(function(key, value)
+		return Brio.new(key, value)
+	end)
+end
+
+function ObservableMap:_observeKeyValueChanged(packValue)
+	return Observable.new(function(sub)
+		local maid = Maid.new()
+
+		local function handleValue(key, value)
+			if value ~= nil then
+				local brio = packValue(key, value)
+				maid[key] = brio
+				sub:Fire(brio)
+			else
+				maid[key] = nil
+			end
+		end
+
+		for key, value in pairs(self._map) do
+			handleValue(key, value)
+		end
+
+		maid:GiveTask(self.KeyValueChanged:Connect(handleValue))
+
+		self._maid[sub] = maid
+		maid:GiveTask(function()
+			self._maid[sub] = nil
+			sub:Complete()
+		end)
+
+		return maid
+	end)
+end
+
+--[=[
+	Returns the value for the given key
+	@param key TKey
+	@return TValue
+]=]
+function ObservableMap:Get(key)
+	assert(key ~= nil, "Bad key")
+
+	return self._map[key]
+end
+
+--[=[
+	Returns whether the map contains the key
+	@param key TKey
+	@return boolean
+]=]
+function ObservableMap:ContainsKey(key)
+	assert(key ~= nil, "Bad key")
+
+	return self._map[key] ~= nil
+end
+
+--[=[
+	Gets the count of items in the set
+	@return number
+]=]
+function ObservableMap:GetCount()
+	return self._countValue.Value
+end
+
+--[=[
+	Observes the count of the set
+	@return Observable<number>
+]=]
+function ObservableMap:ObserveCount()
+	return RxValueBaseUtils.observeValue(self._countValue)
+end
+
+--[=[
+	Observes the value for the given slot
+	@param key TKey
+	@return Observable<TValue?>
+]=]
+function ObservableMap:ObserveValueForKey(key)
+	assert(key ~= nil, "Bad key")
+
+	return Observable.new(function(sub)
+		local maid = Maid.new()
+
+		if not self._keyToSubList[key] then
+			self._keyToSubList[key] = {}
+		end
+		table.insert(self._keyToSubList[key], sub)
+
+		maid:GiveTask(function()
+			local subsList = self._keyToSubList[key]
+			if subsList then
+				local index = table.find(subsList, sub)
+
+				if index then
+					table.remove(subsList, index)
+				end
+
+				if #subsList == 0 then
+					self._keyToSubList[key] = nil
+				end
+			end
+		end)
+
+		sub:Fire(self._map[key])
+
+		return maid
+	end)
+end
+
+--[=[
+	Adds the item to the set if it does not exists.
+	@param key TKey
+	@param value TValue?
+	@return callback -- Call to remove the value.
+]=]
+function ObservableMap:Set(key, value)
+	assert(key ~= nil, "Bad key")
+
+	local oldValue = self._map[key]
+	if oldValue == value then
+		return
+	end
+
+	self._map[key] = value
+
+	if oldValue == nil then
+		self._countValue.Value = self._countValue.Value + 1
+		self.KeyAdded:Fire(key, value)
+	elseif value == nil then
+		self._countValue.Value = self._countValue.Value - 1
+		self.KeyRemoved:Fire(key)
+	end
+
+	self.KeyValueChanged:Fire(key, value, oldValue)
+
+	local subList = self._keyToSubList[key]
+	if subList then
+		for _, sub in pairs(table.clone(subList)) do
+			if sub and sub:IsPending() then
+				task.spawn(function()
+					sub:Fire(value)
+				end)
+			end
+		end
+	end
+
+	return function()
+		if self.Destroy then
+			self:Remove(key)
+		end
+	end
+end
+
+--[=[
+	Removes the item from the map if it exists.
+	@param key TKey
+]=]
+function ObservableMap:Remove(key)
+	assert(key ~= nil, "Bad key")
+
+	self:Set(key, nil)
+end
+
+--[=[
+	Gets a list of all values.
+	@return { TValue }
+]=]
+function ObservableMap:GetValueList()
+	local list = {}
+	for _, value in pairs(self._map) do
+		table.insert(list, value)
+	end
+	return list
+end
+
+--[=[
+	Gets a list of all keys.
+	@return { TKey }
+]=]
+function ObservableMap:GetKeyList()
+	local list = {}
+	for key, _ in pairs(self._map) do
+		table.insert(list, key)
+	end
+	return list
+end
+
+
+--[=[
+	Cleans up the ObservableMap and sets the metatable to nil.
+]=]
+function ObservableMap:Destroy()
+	self._maid:DoCleaning()
+	setmetatable(self, nil)
+end
+
+return ObservableMap

package/src/Shared/ObservableMap.spec.lua

@@ -0,0 +1,74 @@
+--[[
+	@class ObservableMap.spec.lua
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local ObservableMap = require("ObservableMap")
+
+return function()
+	describe("ObservableMap.new()", function()
+		local observableMap = ObservableMap.new()
+
+		it("should return nil for unset values", function()
+			expect(observableMap:Get("a")).to.equal(nil)
+		end)
+
+		it("should allow setting a value", function()
+			expect(observableMap:GetCount()).to.equal(0)
+
+			observableMap:Set("a", "Hello World")
+
+			expect(observableMap:Get("a")).to.equal("Hello World")
+			expect(observableMap:GetCount()).to.equal(1)
+		end)
+
+		it("should overwrite values", function()
+			expect(observableMap:Get("a")).to.equal("Hello World")
+
+			observableMap:Set("a", "Hello World 2")
+
+			expect(observableMap:Get("a")).to.equal("Hello World 2")
+		end)
+
+		it("should allow false as a key", function()
+			expect(observableMap:Get(false)).to.equal(nil)
+			observableMap:Set(false, "Hello")
+			expect(observableMap:Get(false)).to.equal("Hello")
+		end)
+
+		it("should fire off events for a specific key", function()
+			local seen = {}
+			local sub = observableMap:ObserveValueForKey("c"):Subscribe(function(value)
+				table.insert(seen, value)
+			end)
+			observableMap:Set("c", "Hello")
+
+			sub:Destroy()
+
+			expect(#seen).to.equal(1)
+			expect(seen[1]).to.equal("Hello")
+		end)
+
+		it("should fire off events for all keys", function()
+			local seen = {}
+			local sub = observableMap:ObserveValuesBrio():Subscribe(function(value)
+				table.insert(seen, value)
+			end)
+			observableMap:Set("d", "Hello")
+
+			expect(#seen).to.equal(4)
+			expect(seen[4]:GetValue()).to.equal("Hello")
+			expect(seen[4]:IsDead()).to.equal(false)
+
+			sub:Destroy()
+
+			expect(#seen).to.equal(4)
+			expect(seen[4]:IsDead()).to.equal(true)
+		end)
+
+		it("should clean up", function()
+			observableMap:Destroy()
+		end)
+	end)
+end

package/src/Shared/ObservableMapSet.lua

@@ -1,4 +1,7 @@
 --[=[
+	Holds a map of sets. That is, for a given key, a set of all valid entries. This is great
+	for looking up something that may have duplicate keys, like configurations or other things.
+
 	@class ObservableMapSet
 ]=]
 
@@ -13,21 +16,44 @@ local ObservableMapSet = {}
 ObservableMapSet.ClassName = "ObservableMapSet"
 ObservableMapSet.__index = ObservableMapSet
 
+--[=[
+	Constructs a new ObservableMapSet
+	@return ObservableMapSet<TKey, TValue>
+]=]
 function ObservableMapSet.new()
 	local self = setmetatable({}, ObservableMapSet)
 
 	self._maid = Maid.new()
 	self._observableSetMap = {} -- [key] = ObservableSet<TEntry>
 
+--[=[
+	Fires when an item is added
+	@readonly
+	@prop SetAdded Signal<TKey>
+	@within ObservableMapSet
+]=]
 	self.SetAdded = Signal.new() -- :Fire(key, set)
 	self._maid:GiveTask(self.SetAdded)
 
+--[=[
+	Fires when an item is removed
+	@readonly
+	@prop SetRemoved Signal<TKey>
+	@within ObservableMapSet
+]=]
 	self.SetRemoved = Signal.new() -- :Fire(key)
 	self._maid:GiveTask(self.SetRemoved)
 
 	return self
 end
 
+--[=[
+	Adds an entry with a dynamic key. This is great for caching things
+	that need to be looked up by key.
+
+	@param entry TValue
+	@param observeKey Observable<Brio<TKey>>
+]=]
 function ObservableMapSet:Add(entry, observeKey)
 	local maid = Maid.new()
 

package/src/Shared/ObservableSet.lua

@@ -17,7 +17,7 @@ ObservableSet.__index = ObservableSet
 
 --[=[
 	Constructs a new ObservableSet
-	@return ObservableSet
+	@return ObservableSet<T>
 ]=]
 function ObservableSet.new()
 	local self = setmetatable({}, ObservableSet)
@@ -58,7 +58,7 @@ function ObservableSet.new()
 end
 
 --[=[
-	Returns whether the set is an observable set
+	Returns whether the value is an observable set
 	@param value any
 	@return boolean
 ]=]
@@ -129,6 +129,7 @@ end
 --[=[
 	Adds the item to the set if it does not exists.
 	@param item T
+	@return callback -- Call to remove
 ]=]
 function ObservableSet:Add(item)
 	assert(item ~= nil, "Bad item")
@@ -163,6 +164,10 @@ function ObservableSet:Remove(item)
 	end
 end
 
+--[=[
+	Gets an arbitrary item in the set (not guaranteed to be ordered)
+	@return T
+]=]
 function ObservableSet:GetFirstItem()
 	local value = next(self._set)
 	return value
@@ -180,6 +185,18 @@ function ObservableSet:GetList()
 	return list
 end
 
+--[=[
+	Gets a copy of the set
+	@return { [T]: true }
+]=]
+function ObservableSet:GetSetCopy()
+	local set = {}
+	for item, _ in pairs(self._set) do
+		set[item] = true
+	end
+	return set
+end
+
 --[=[
 	Cleans up the ObservableSet and sets the metatable to nil.
 ]=]

package/test/default.project.json

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