@quenty/brio 3.1.2 → 3.3.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 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/brio@3.2.0...@quenty/brio@3.3.0) (2021-11-20)
+
+
+### Bug Fixes
+
+* Support MacOS syncing ([#225](https://github.com/Quenty/NevermoreEngine/issues/225)) ([03f9183](https://github.com/Quenty/NevermoreEngine/commit/03f918392c6a5bdd33f8a17c38de371d1e06c67a))
+
+
+
+
+
+# [3.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/brio@3.1.2...@quenty/brio@3.2.0) (2021-10-30)
+
+
+### Features
+
+* BrioUtils.first allows no brios to be passed into the brio. This allows BrioUtils.flatten to accept non-brios as a result. ([6cf4bdf](https://github.com/Quenty/NevermoreEngine/commit/6cf4bdf504ace3dfcc37faa717363c4455be52aa))
+* Update RxBrioUtils to allow the transformation of a brio into an observable that emits the value, and then nil, on death. This is like combineLatest. ([86df73f](https://github.com/Quenty/NevermoreEngine/commit/86df73f529740a7785eafa4bcd51639e5e20574c))
+
+
+
+
+
 ## [3.1.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/brio@3.1.1...@quenty/brio@3.1.2) (2021-10-30)
 
 **Note:** Version bump only for package @quenty/brio

package/README.md

@@ -38,6 +38,14 @@ resources.
 
 Anything may "kill" a brio by calling :Destroy() or :Kill().
 
+## Design philosophy
+
+Brios are designed to solve this issue where we emit an object with a lifetime associated with it from an Observable stream. This resource is only valid for some amount of time (for example, while the object is in the Roblox data model).
+
+In order to know how long we can keep this object/use it, we wrap the object with a Brio, which denotes the lifetime of the object.
+
+Modeling this with pure observables is very tricky because the subscriber will have to also monitor/emit a similar object with less clear conventions. For example  an observable that emits the object, and then nil on death. 
+
 ## API Surface
 
 ### `Brio.isBrio(value)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/brio",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "description": "Brios wrap an object and either are alive or dead",
   "keywords": [
     "Roblox",
@@ -28,10 +28,10 @@
   "dependencies": {
     "@quenty/loader": "^3.1.1",
     "@quenty/maid": "^2.0.1",
-    "@quenty/rx": "^3.1.2"
+    "@quenty/rx": "^3.3.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "e9cd4223c7fda7c852db9743ef844baa19cacb13"
+  "gitHead": "87ab1435a59a05e7dd745db1dfcec26116d1d71d"
 }

package/src/Shared/BrioUtils.lua

@@ -66,8 +66,10 @@ end
 
 function BrioUtils.first(brios, ...)
 	for _, brio in pairs(brios) do
-		if brio:IsDead() then
-			return Brio.DEAD
+		if Brio.isBrio(brio) then
+			if brio:IsDead() then
+				return Brio.DEAD
+			end
 		end
 	end
 
@@ -75,9 +77,11 @@ function BrioUtils.first(brios, ...)
 	local topBrio = Brio.new(...)
 
 	for _, brio in pairs(brios) do
-		maid:GiveTask(brio:GetDiedSignal():Connect(function()
-			topBrio:Kill()
-		end))
+		if Brio.isBrio(brio) then
+			maid:GiveTask(brio:GetDiedSignal():Connect(function()
+				topBrio:Kill()
+			end))
+		end
 	end
 
 	maid:GiveTask(topBrio:GetDiedSignal():Connect(function()

package/src/Shared/BrioUtils.spec.lua

@@ -0,0 +1,74 @@
+---
+-- @module RxBrioUtils.spec.lua
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local BrioUtils = require("BrioUtils")
+local Brio = require("Brio")
+
+return function()
+	describe("BrioUtils.flatten({})", function()
+		local brio = BrioUtils.flatten({})
+
+		describe("should return a brio that", function()
+			it("is a brio", function()
+				expect(brio).to.be.a("table")
+				expect(Brio.isBrio(brio)).to.equal(true)
+			end)
+
+			it("is alive", function()
+				expect(not brio:IsDead()).to.equal(true)
+			end)
+
+			it("contains a table", function()
+				expect(brio:GetValue()).to.be.a("table")
+			end)
+
+			it("contains a table with nothing in it", function()
+				expect(next(brio:GetValue())).to.equal(nil)
+			end)
+		end)
+	end)
+
+	describe("BrioUtils.flatten with out a brio in it", function()
+		local brio = BrioUtils.flatten({
+			value = 5;
+		})
+
+		describe("should return a brio that", function()
+			it("is a brio", function()
+				expect(brio).to.be.a("table")
+				expect(Brio.isBrio(brio)).to.equal(true)
+			end)
+
+			it("is alive", function()
+				expect(not brio:IsDead()).to.equal(true)
+			end)
+
+			it("contains a table", function()
+				expect(brio:GetValue()).to.be.a("table")
+			end)
+
+			it("contains a table with value", function()
+				expect(brio:GetValue().value).to.equal(5)
+			end)
+		end)
+	end)
+
+	describe("BrioUtils.flatten a dead brio in it", function()
+		local brio = BrioUtils.flatten({
+			value = Brio.DEAD;
+		})
+
+		describe("should return a brio that", function()
+			it("is a brio", function()
+				expect(brio).to.be.a("table")
+				expect(Brio.isBrio(brio)).to.equal(true)
+			end)
+
+			it("is dead", function()
+				expect(brio:IsDead()).to.equal(true)
+			end)
+		end)
+	end)
+end

package/src/Shared/RxBrioUtils.lua

@@ -283,7 +283,8 @@ function RxBrioUtils.filter(predicate)
 	end
 end
 
--- Flattens all the brios in the combineLatest
+-- Flattens all the brios in one brio and combines them. Note that this method leads to
+-- gaps in the lifetime of the brio.
 function RxBrioUtils.combineLatest(observables)
 	assert(type(observables) == "table", "Bad observables")
 
@@ -306,6 +307,36 @@ function RxBrioUtils.switchMap(project, resultSelector)
 	return Rx.switchMap(RxBrioUtils.mapBrio(project), resultSelector)
 end
 
+--[[
+Works line combineLatest, but allow the transformation of a brio into an observable
+that emits the value, and then nil, on death.
+
+The issue here is this:
+
+1. Resources are found with combineLatest()
+2. One resource dies
+3. All resources are invalidated
+4. We still wanted to be able to use most of the resources
+
+With this method we are able to do this, as we'll re-emit a table with all resoruces
+except the invalidated one.
+]]
+function RxBrioUtils.flatCombineLatest(observables)
+	assert(type(observables) == "table", "Bad observables")
+
+	local newObservables = {}
+	for key, observable in pairs(observables) do
+		if Observable.isObservable(observable) then
+			newObservables[key] = RxBrioUtils.flattenToValueAndNil(observable)
+		else
+			newObservables[key] = observable
+		end
+	end
+
+	return Rx.combineLatest(newObservables)
+end
+
+-- Takes in a brio and returns an observable that completes ony
 function RxBrioUtils.mapBrio(project)
 	assert(type(project) == "function", "Bad project")
 
@@ -323,6 +354,41 @@ function RxBrioUtils.mapBrio(project)
 	end
 end
 
+-- Transforms the brio into an observable that emits the initial value of the brio, and then another value on death
+function RxBrioUtils.toEmitOnDeathObservable(brio, emitOnDeathValue)
+	if not Brio.isBrio(brio) then
+		return Rx.of(brio)
+	else
+		return Observable.new(function(sub)
+			if brio:IsDead() then
+				sub:Fire(emitOnDeathValue)
+				sub:Complete()
+			else
+				sub:Fire(brio:GetValue())
+
+				return brio:GetDiedSignal():Connect(function()
+					sub:Fire(emitOnDeathValue)
+					sub:Complete()
+				end)
+			end
+		end)
+	end
+end
+
+function RxBrioUtils.mapBrioToEmitOnDeathObservable(emitOnDeathValue)
+	return function(brio)
+		return RxBrioUtils.toEmitOnDeathObservable(brio, emitOnDeathValue)
+	end
+end
+
+--- Takes in an observable of brios and returns an observable of the inner values that will also output
+-- nil if there is no other value for the brio
+function RxBrioUtils.emitOnDeath(emitOnDeathValue)
+	return Rx.switchMap(RxBrioUtils.mapBrioToEmitOnDeathObservable(emitOnDeathValue));
+end
+
+RxBrioUtils.flattenToValueAndNil = RxBrioUtils.emitOnDeath(nil)
+
 function RxBrioUtils.onlyLastBrioSurvives()
 	return function(source)
 		return Observable.new(function(sub)

package/src/Shared/RxBrioUtils.spec.lua

@@ -0,0 +1,109 @@
+---
+-- @module RxBrioUtils.spec.lua
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local RxBrioUtils = require("RxBrioUtils")
+local Brio = require("Brio")
+local Observable = require("Observable")
+
+return function()
+	describe("RxBrioUtils.combineLatest({})", function()
+		it("should execute immediately", function()
+			local observe = RxBrioUtils.combineLatest({})
+			local brio
+			observe:Subscribe(function(result)
+				brio = result
+			end)
+			expect(brio).to.be.ok()
+			expect(Brio.isBrio(brio)).to.equal(true)
+			expect(brio:IsDead()).to.equal(true)
+		end)
+	end)
+
+	describe("RxBrioUtils.combineLatest({ value = Observable(Brio(5)) })", function()
+		it("should execute immediately", function()
+			local observe = RxBrioUtils.combineLatest({
+				value = Observable.new(function(sub)
+					sub:Fire(Brio.new(5));
+				end);
+				otherValue = 25;
+			})
+			local brio
+
+			observe:Subscribe(function(result)
+				brio = result
+			end)
+			expect(brio).to.be.ok()
+			expect(Brio.isBrio(brio)).to.equal(true)
+			expect(not brio:IsDead()).to.equal(true)
+			expect(brio:GetValue()).to.be.a("table")
+			expect(brio:GetValue().value).to.equal(5)
+		end)
+	end)
+
+	describe("RxBrioUtils.flatCombineLatest", function()
+		local doFire
+		local brio = Brio.new(5)
+		local observe = RxBrioUtils.flatCombineLatest({
+			value = Observable.new(function(sub)
+				sub:Fire(brio);
+				doFire = function(...)
+					sub:Fire(...)
+				end
+			end);
+			otherValue = 25;
+		})
+
+		local lastResult = nil
+		local fireCount = 0
+
+		it("should execute immediately", function()
+			observe:Subscribe(function(result)
+				lastResult = result
+				fireCount = fireCount + 1
+			end)
+			expect(fireCount).to.equal(1)
+			expect(lastResult).to.be.a("table")
+			expect(Brio.isBrio(lastResult)).to.equal(false)
+			expect(lastResult.value).to.equal(5)
+			expect(lastResult.otherValue).to.equal(25)
+		end)
+
+		it("should reset when the brio is killed", function()
+			expect(fireCount).to.equal(1)
+
+			brio:Kill()
+
+			expect(fireCount).to.equal(2)
+			expect(lastResult).to.be.a("table")
+			expect(Brio.isBrio(lastResult)).to.equal(false)
+			expect(lastResult.value).to.equal(nil)
+			expect(lastResult.otherValue).to.equal(25)
+		end)
+
+		it("should allow a new value", function()
+			expect(fireCount).to.equal(2)
+
+			doFire(Brio.new(70))
+
+			expect(fireCount).to.equal(3)
+			expect(lastResult).to.be.a("table")
+			expect(Brio.isBrio(lastResult)).to.equal(false)
+			expect(lastResult.value).to.equal(70)
+			expect(lastResult.otherValue).to.equal(25)
+		end)
+
+		it("should only fire once if we replace the value", function()
+			expect(fireCount).to.equal(3)
+
+			doFire(Brio.new(75))
+
+			expect(fireCount).to.equal(4)
+			expect(lastResult).to.be.a("table")
+			expect(Brio.isBrio(lastResult)).to.equal(false)
+			expect(lastResult.value).to.equal(75)
+			expect(lastResult.otherValue).to.equal(25)
+		end)
+	end)
+end

package/src/node_modules.project.json

@@ -2,6 +2,6 @@
   "name": "node_modules",
   "globIgnorePaths": [ "**/.package-lock.json" ],
   "tree": {
-    "$path": { "optional": "..\\node_modules" }
+    "$path": { "optional": "../node_modules" }
   }
 }