@quenty/brio 3.5.2 → 3.5.3-canary.241.8dba9c1.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.5.3-canary.241.8dba9c1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/brio@3.5.2...@quenty/brio@3.5.3-canary.241.8dba9c1.0) (2022-01-03)
+
+
+### Bug Fixes
+
+* Fix moonwave documentation ([8dba9c1](https://github.com/Quenty/NevermoreEngine/commit/8dba9c1e474a8f8c5de373dc04e3c876e21b034b))
+
+
+### Features
+
+* Deprecate old brio commands and add new utility functions, including: ([4cb10f2](https://github.com/Quenty/NevermoreEngine/commit/4cb10f2033d10052b0542f54ab53cbf871897a03))
+
+
+
+
+
 ## [3.5.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/brio@3.5.1...@quenty/brio@3.5.2) (2021-12-30)
 
 **Note:** Version bump only for package @quenty/brio

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/brio",
-  "version": "3.5.2",
+  "version": "3.5.3-canary.241.8dba9c1.0",
   "description": "Brios wrap an object and either are alive or dead",
   "keywords": [
     "Roblox",
@@ -26,12 +26,12 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/loader": "^3.1.2",
-    "@quenty/maid": "^2.0.2",
-    "@quenty/rx": "^3.5.2"
+    "@quenty/loader": "3.1.3-canary.241.8dba9c1.0",
+    "@quenty/maid": "2.0.2",
+    "@quenty/rx": "3.5.3-canary.241.8dba9c1.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "4afdd64f4ff6bc3b4b4c0ca7a31e839196f2411e"
+  "gitHead": "8dba9c1e474a8f8c5de373dc04e3c876e21b034b"
 }

package/src/Shared/Brio.lua

@@ -80,7 +80,6 @@ end
 --[=[
 	Constructs a new Brio.
 
-
 	```lua
 	local brio = Brio.new("a", "b")
 	print(brio:GetValue()) --> a b
@@ -95,6 +94,22 @@ function Brio.new(...) -- Wrap
 	}, Brio)
 end
 
+--[=[
+	Constructs a new brio that will cleanup afer the set amount of time
+
+	@since 3.6.0
+	@param time number
+	@param ... any -- Brio values
+	@return Brio
+]=]
+function Brio.delayed(time, ...)
+	local brio = Brio.new(...)
+	task.delay(time, function()
+		brio:Kill()
+	end)
+	return brio
+end
+
 --[=[
 	Gets a signal that will fire when the Brio dies. If the brio is already dead
 	calling this method will error.
@@ -214,6 +229,18 @@ function Brio:GetValue()
 	return unpack(self._values, 1, self._values.n)
 end
 
+--[=[
+	Returns the packed values from table.pack() format
+
+	@since 3.6.0
+	@return { n: number, ... T }
+]=]
+function Brio:GetPackedValues()
+	assert(self._values, "Brio is dead")
+
+	return self._values
+end
+
 --[=[
 	Kills the Brio.
 

package/src/Shared/BrioUtils.lua

@@ -126,6 +126,31 @@ function BrioUtils.first(brios, ...)
 	return topBrio
 end
 
+--[=[
+	Clones a brio, such that it may be killed without affecting the original
+	brio.
+
+	@since 3.6.0
+	@param brio Brio<T>
+	@param ... U
+	@return Brio<U>
+]=]
+function BrioUtils.withOtherValues(brio, ...)
+	assert(brio, "Bad brio")
+
+	if brio:IsDead() then
+		return Brio.DEAD
+	end
+
+	local newBrio = Brio.new(...)
+
+	newBrio:ToMaid():GiveTask(brio:GetDiedSignal():Connect(function()
+		newBrio:Kill()
+	end))
+
+	return newBrio
+end
+
 --[=[
 	Makes a brio that is limited by the lifetime of its parent (but could be shorter)
 	and has the new values given.
@@ -163,6 +188,44 @@ function BrioUtils.extend(brio, ...)
 	return newBrio
 end
 
+--[=[
+	Makes a brio that is limited by the lifetime of its parent (but could be shorter)
+	and has the new values given at the beginning of the result
+
+	@since 3.6.0
+	@param brio Brio<U>
+	@param ... T
+	@return Brio<T>
+]=]
+function BrioUtils.prepend(brio, ...)
+	if brio:IsDead() then
+		return Brio.DEAD
+	end
+
+	local values = brio._values
+	local current = {}
+	local otherValues = table.pack(...)
+	for i=1, otherValues.n do
+		current[i] = otherValues[i]
+	end
+	for i=1, values.n do
+		current[otherValues.n+i] = values[i]
+	end
+
+	local maid = Maid.new()
+	local newBrio = Brio.new(unpack(current, 1, values.n + otherValues.n))
+
+	maid:GiveTask(brio:GetDiedSignal():Connect(function()
+		newBrio:Kill()
+	end))
+
+	maid:GiveTask(newBrio:GetDiedSignal():Connect(function()
+		maid:DoCleaning()
+	end))
+
+	return newBrio
+end
+
 --[=[
 	Merges the existing brio value with the other brio
 

package/src/Shared/RxBrioUtils.lua

@@ -284,10 +284,11 @@ end
 	Unpacks the brio, and then repacks it. Ignored items
 	still invalidate the previous brio
 
+	@since 3.6.0
 	@param predicate (T) -> boolean
 	@return (source: Observable<Brio<T>>) -> Observable<Brio<T>>
 ]=]
-function RxBrioUtils.filter(predicate)
+function RxBrioUtils.where(predicate)
 	assert(type(predicate) == "function", "Bad predicate")
 
 	return function(source)
@@ -321,16 +322,30 @@ function RxBrioUtils.filter(predicate)
 	end
 end
 
+--[=[
+	Same as [RxBrioUtils.where]. Here to keep backwards compatability.
+
+	@deprecated 3.6.0 -- This method does not wrap the resulting value in a Brio, which can sometimes lead to leaks.
+	@function filter
+	@param predicate (T) -> boolean
+	@return (source: Observable<Brio<T>>) -> Observable<Brio<T>>
+	@within RxBrioUtils
+]=]
+RxBrioUtils.filter = RxBrioUtils.where
+
 --[=[
 	Flattens all the brios in one brio and combines them. Note that this method leads to
 	gaps in the lifetime of the brio.
 
+	@deprecated 3.6.0 -- This method does not wrap the resulting value in a Brio, which can sometimes lead to leaks.
 	@param observables { [any]: Observable<Brio<T>> | Observable<T> | T }
 	@return Observable<Brio<{ [any]: T }>>
 ]=]
 function RxBrioUtils.combineLatest(observables)
 	assert(type(observables) == "table", "Bad observables")
 
+	warn("[RxBrioUtils.combineLatest] - Deprecated since 3.6.0. Use RxBrioUtils.flatCombineLatest")
+
 	return Rx.combineLatest(observables)
 		:Pipe({
 			Rx.map(BrioUtils.flatten);
@@ -339,29 +354,70 @@ function RxBrioUtils.combineLatest(observables)
 end
 
 --[=[
-	Flat map equivalent for brios
+	Flat map equivalent for brios. The resulting observables will
+	be disconnected at the end of the brio.
 
+	@deprecated 3.6.0 -- This method does not wrap the resulting value in a Brio, which can sometimes lead to leaks.
 	@param project (value: TBrio) -> TProject
-	@param resultSelector ((value: TProject) -> TResult)?
-	@return (source: Observable<Brio<TBrio>> -> Observable<Brio<TResult>>)
+	@param resultSelector ((initial TBrio, value: TProject) -> TResult)?
+	@return (source: Observable<Brio<TBrio>> -> Observable<TResult>)
 ]=]
 function RxBrioUtils.flatMap(project, resultSelector)
 	assert(type(project) == "function", "Bad project")
 
+	warn("[RxBrioUtils.flatMap] - Deprecated since 3.6.0. Use RxBrioUtils.flatMapBrio")
+
 	return Rx.flatMap(RxBrioUtils.mapBrio(project), resultSelector)
 end
 
 --[=[
-	Switch map but for Brio.
+	Flat map equivalent for brios. The resulting observables will
+	be disconnected at the end of the brio.
+
+	Like [RxBrioUtils.flatMap], but emitted values are wrapped in brios.
+	The lifetime of this brio is limited by the lifetime of the
+	input brios, which are unwrapped and repackaged.
 
+	@since 3.6.0
+	@param project (value: TBrio) -> TProject | Brio<TProject>
+	@return (source: Observable<Brio<TBrio>> -> Observable<Brio<TResult>>)
+]=]
+function RxBrioUtils.flatMapBrio(project)
+	return Rx.flatMap(RxBrioUtils.mapBrioBrio(project))
+end
+
+--[=[
+	Switch map but for brios. The resulting observable will be
+	disconnected on the end of the brio's life.
+
+	@deprecated 3.6.0 -- This method does not wrap the resulting value in a Brio, which can sometimes lead to leaks.
 	@param project (value: TBrio) -> TProject
-	@param resultSelector ((value: TProject) -> TResult)?
+	@return (source: Observable<Brio<TBrio>>) -> Observable<TResult>
+]=]
+function RxBrioUtils.switchMap(project)
+	assert(type(project) == "function", "Bad project")
+
+	warn("[RxBrioUtils.switchMap] - Deprecated since 3.6.0. Use RxBrioUtils.switchMapBrio")
+
+	return Rx.switchMap(RxBrioUtils.mapBrio(project))
+end
+
+--[=[
+	Switch map but for brios. The resulting observable will be
+	disconnected on the end of the brio's life.
+
+	Like [RxBrioUtils.switchMap] but emitted values are wrapped in brios.
+	The lifetime of this brio is limited by the lifetime of the
+	input brios, which are unwrapped and repackaged.
+
+	@since 3.6.0
+	@param project (value: TBrio) -> TProject | Brio<TProject>
 	@return (source: Observable<Brio<TBrio>>) -> Observable<Brio<TResult>>
 ]=]
-function RxBrioUtils.switchMap(project, resultSelector)
+function RxBrioUtils.switchMapBrio(project)
 	assert(type(project) == "function", "Bad project")
 
-	return Rx.switchMap(RxBrioUtils.mapBrio(project), resultSelector)
+	return Rx.switchMap(RxBrioUtils.mapBrioBrio(project))
 end
 
 --[=[
@@ -378,8 +434,9 @@ end
 	With this method we are able to do this, as we'll re-emit a table with all resoruces
 	except the invalidated one.
 
+	@since 3.6.0
 	@param observables { [any]: Observable<Brio<T>> | Observable<T> | T }
-	@return Observable<Brio<{ [any]: T }>>
+	@return Observable<{ [any]: T? }>
 ]=]
 function RxBrioUtils.flatCombineLatest(observables)
 	assert(type(observables) == "table", "Bad observables")
@@ -400,12 +457,15 @@ end
 	Takes in a brio and returns an observable that emits the brio, and then completes
 	on death.
 
+	@deprecated 3.6.0 -- This method does not wrap the resulting value in a Brio, which can sometimes lead to leaks.
 	@param project (value: TBrio) -> TProject
-	@return (brio<TBrio>) -> Brio<TProject>
+	@return (brio<TBrio>) -> TProject
 ]=]
 function RxBrioUtils.mapBrio(project)
 	assert(type(project) == "function", "Bad project")
 
+	warn("[RxBrioUtils.mapBrio] - Deprecated since 3.6.0. Use RxBrioUtils.mapBrioBrio")
+
 	return function(brio)
 		assert(Brio.isBrio(brio), "Not a brio")
 
@@ -420,6 +480,151 @@ function RxBrioUtils.mapBrio(project)
 	end
 end
 
+--[=[
+	Prepends the value onto the emitted brio
+	@since 3.6.0
+	@param ... T
+	@return (source: Observable<Brio<U>>) -> Observable<Brio<U | T>>
+]=]
+function RxBrioUtils.prepend(...)
+	local args = table.pack(...)
+
+	return Rx.map(function(brio)
+		assert(Brio.isBrio(brio), "Bad brio")
+
+		return BrioUtils.prepend(brio, table.unpack(args, 1, args.n))
+	end)
+end
+
+--[=[
+	Extends the value onto the emitted brio
+	@since 3.6.0
+	@param ... T
+	@return (source: Observable<Brio<U>>) -> Observable<Brio<U | T>>
+]=]
+function RxBrioUtils.extend(...)
+	local args = table.pack(...)
+
+	return Rx.map(function(brio)
+		assert(Brio.isBrio(brio), "Bad brio")
+
+		return BrioUtils.extend(brio, table.unpack(args, 1, args.n))
+	end)
+end
+
+--[=[
+	Maps the input brios to the output observables
+	@since 3.6.0
+	@param project project (Brio<T> | T) -> Brio<U> | U
+	@return (source: Observable<Brio<T> | T>) -> Observable<Brio<U>>
+]=]
+function RxBrioUtils.map(project)
+	return Rx.map(function(...)
+		local n = select("#", ...)
+		local brios = {}
+		local args
+
+		if n == 1 then
+			if Brio.isBrio(...) then
+				table.insert(brios, (...))
+				args = (...):GetPackedValues()
+			else
+				args = {[1] = ...}
+			end
+		else
+			args = {}
+			for index, item in pairs({...}) do
+				if Brio.isBrio(item) then
+					table.insert(brios, item)
+					args[index] = item:GetValue() -- we lose data here, but I think this is fine
+				else
+					args[index] = item
+				end
+			end
+			args.n = n
+		end
+
+		local results = table.pack(project(table.unpack(args, 1, args.n)))
+		if results.n == 1 then
+			if Brio.isBrio(results[1]) then
+				table.insert(brios, results[1])
+				return BrioUtils.first(brios, results:GetValue())
+			else
+				return BrioUtils.withOtherValues(brios, results[1])
+			end
+		else
+			local transformedResults = {}
+			for i=1, results.n do
+				local item = results[i]
+				if Brio.isBrio(item) then
+					table.insert(brios, item) -- add all subsequent brios into this table...
+					transformedResults[i] = item:GetValue()
+				else
+					transformedResults[i] = item
+				end
+			end
+
+			return BrioUtils.first(brios, table.unpack(transformedResults, 1, transformedResults.n))
+		end
+	end)
+end
+
+function RxBrioUtils._mapResult(brio)
+	return function(...)
+		local n = select("#", ...)
+		if n == 0 then
+			return BrioUtils.withOtherValues(brio)
+		elseif n == 1 then
+			if Brio.isBrio(...) then
+				return BrioUtils.first({brio, (...)}, (...):GetValue())
+			else
+				return BrioUtils.withOtherValues(brio, ...)
+			end
+		else
+			local brios = { brio }
+			local args = {}
+
+			for index, item in pairs({...}) do
+				if Brio.isBrio(item) then
+					table.insert(brios, item)
+					args[index] = item:GetValue() -- we lose data here, but I think this is fine
+				else
+					args[index] = item
+				end
+			end
+
+			return BrioUtils.first(brios, unpack(args, 1, n))
+		end
+	end
+end
+
+--[=[
+	Takes in a brio and returns an observable that emits the brio, and then completes
+	on death.
+
+	@since 3.6.0
+	@param project (value: TBrio) -> TProject | Brio<TProject>
+	@return (brio<TBrio>) -> Brio<TProject>
+]=]
+function RxBrioUtils.mapBrioBrio(project)
+	assert(type(project) == "function", "Bad project")
+
+	return function(brio)
+		assert(Brio.isBrio(brio), "Not a brio")
+
+		if brio:IsDead() then
+			return Rx.EMPTY
+		end
+
+		local observable = project(brio:GetValue())
+		assert(Observable.isObservable(observable), "Not an observable")
+
+		return RxBrioUtils.completeOnDeath(brio, observable):Pipe({
+			Rx.map(RxBrioUtils._mapResult(brio))
+		})
+	end
+end
+
 --[=[
 	Transforms the brio into an observable that emits the initial value of the brio, and then another value on death
 	@param brio Brio<T> | T
@@ -508,4 +713,17 @@ function RxBrioUtils.onlyLastBrioSurvives()
 	end
 end
 
+--[=[
+	Switches the result to a brio, and ensures only the last brio lives.
+
+	@since 3.6.0
+	@function switchToBrio
+	@return (source: Observable<T>) -> Observable<Brio<T>>
+	@within RxBrioUtils
+]=]
+RxBrioUtils.switchToBrio = Rx.pipe({
+	RxBrioUtils.toBrio();
+	RxBrioUtils.onlyLastBrioSurvives();
+})
+
 return RxBrioUtils