@quenty/instanceutils 3.4.1-canary.8533eea.0 → 3.5.1

package/CHANGELOG.md

@@ -3,7 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.4.1-canary.8533eea.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/instanceutils@3.4.0...@quenty/instanceutils@3.4.1-canary.8533eea.0) (2021-12-18)
+## [3.5.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/instanceutils@3.5.0...@quenty/instanceutils@3.5.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/instanceutils
+
+
+
+
+
+# [3.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/instanceutils@3.4.0...@quenty/instanceutils@3.5.0) (2021-12-18)
 
 **Note:** Version bump only for package @quenty/instanceutils
 

package/README.md

@@ -1,10 +1,10 @@
 ## InstanceUtils
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,24 +13,9 @@
 
 Utility functions involving instances in Roblox
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/RxInstanceUtils">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/instanceutils --save
-```
-
-## API
-
-### `RxInstanceUtils.observeProperty(instance, property)`
-
-### `RxInstanceUtils.observeAncestry(instance)`
-
-### `RxInstanceUtils.observePropertyBrio(instance, property, predicate)`
-
-### `RxInstanceUtils.observeLastNamedChildBrio(parent, className, name)`
-
-### `RxInstanceUtils.observeChildrenOfClassBrio(parent, className)`
-
-### `RxInstanceUtils.observeChildrenBrio(parent, predicate)`
-
-### `RxInstanceUtils.observeDescendants(parent, predicate)`
-
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/instanceutils",
-  "version": "3.4.1-canary.8533eea.0",
+  "version": "3.5.1",
   "description": "Utility functions involving instances in Roblox",
   "keywords": [
     "Roblox",
@@ -26,13 +26,13 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/brio": "3.4.1-canary.8533eea.0",
-    "@quenty/loader": "3.1.1",
-    "@quenty/maid": "2.0.1",
-    "@quenty/rx": "3.4.1-canary.8533eea.0"
+    "@quenty/brio": "^3.5.1",
+    "@quenty/loader": "^3.1.2",
+    "@quenty/maid": "^2.0.2",
+    "@quenty/rx": "^3.5.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8533eeade3bf6835c0295785c1c326b9abee3222"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Shared/RxInstanceUtils.lua

@@ -1,6 +1,14 @@
----
--- @module RxInstanceUtils
--- @author Quenty
+--[=[
+	Utility functions to observe the state of Roblox. This is a very powerful way to query
+	Roblox's state.
+
+	:::tip
+	Use RxInstanceUtils to program streaming enabled games, and make it easy to debug. This API surface
+	lets you use Roblox as a source-of-truth which is very valuable.
+	:::
+
+	@class RxInstanceUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -11,6 +19,13 @@ local Rx = require("Rx")
 
 local RxInstanceUtils = {}
 
+--[=[
+	Observes an instance's property
+
+	@param instance Instance
+	@param propertyName string
+	@return Observable<T>
+]=]
 function RxInstanceUtils.observeProperty(instance, propertyName)
 	assert(typeof(instance) == "Instance", "Not an instance")
 	assert(type(propertyName) == "string", "Bad propertyName")
@@ -27,6 +42,12 @@ function RxInstanceUtils.observeProperty(instance, propertyName)
 	end)
 end
 
+--[=[
+	Observes an instance's ancestry
+
+	@param instance Instance
+	@return Observable<Instance>
+]=]
 function RxInstanceUtils.observeAncestry(instance)
 	local startWithParent = Rx.start(function()
 		return instance, instance.Parent
@@ -35,10 +56,17 @@ function RxInstanceUtils.observeAncestry(instance)
 	return startWithParent(Rx.fromSignal(instance.AncestryChanged))
 end
 
--- Returns a brio of the property value
-function RxInstanceUtils.observePropertyBrio(instance, property, predicate)
+--[=[
+	Returns a brio of the property value
+
+	@param instance Instance
+	@param propertyName string
+	@param predicate ((value: T) -> boolean)? -- Optional filter
+	@return Observable<Brio<T>>
+]=]
+function RxInstanceUtils.observePropertyBrio(instance, propertyName, predicate)
 	assert(typeof(instance) == "Instance", "Bad instance")
-	assert(type(property) == "string", "Bad property")
+	assert(type(propertyName) == "string", "Bad propertyName")
 	assert(type(predicate) == "function" or predicate == nil, "Bad predicate")
 
 	return Observable.new(function(sub)
@@ -47,21 +75,29 @@ function RxInstanceUtils.observePropertyBrio(instance, property, predicate)
 		local function handlePropertyChanged()
 			maid._property = nil
 
-			local propertyValue = instance[property]
+			local propertyValue = instance[propertyName]
 			if not predicate or predicate(propertyValue) then
-				local brio = Brio.new(instance[property])
+				local brio = Brio.new(instance[propertyName])
 				maid._property = brio
 				sub:Fire(brio)
 			end
 		end
 
-		maid:GiveTask(instance:GetPropertyChangedSignal(property):Connect(handlePropertyChanged))
+		maid:GiveTask(instance:GetPropertyChangedSignal(propertyName):Connect(handlePropertyChanged))
 		handlePropertyChanged()
 
 		return maid
 	end)
 end
 
+--[=[
+	Observes the last child with a specific name.
+
+	@param parent Instance
+	@param className string
+	@param name string
+	@return Observable<Brio<Instance>>
+]=]
 function RxInstanceUtils.observeLastNamedChildBrio(parent, className, name)
 	assert(typeof(parent) == "Instance", "Bad parent")
 	assert(type(className) == "string", "Bad className")
@@ -108,6 +144,13 @@ function RxInstanceUtils.observeLastNamedChildBrio(parent, className, name)
 	end)
 end
 
+--[=[
+	Observes all children of a specific class
+
+	@param parent Instance
+	@param className string
+	@return Observable<Instance>
+]=]
 function RxInstanceUtils.observeChildrenOfClassBrio(parent, className)
 	assert(typeof(parent) == "Instance", "Bad parent")
 	assert(type(className) == "string", "Bad className")
@@ -117,6 +160,13 @@ function RxInstanceUtils.observeChildrenOfClassBrio(parent, className)
 	end)
 end
 
+--[=[
+	Observes all children
+
+	@param parent Instance
+	@param predicate ((value: Instance) -> boolean)? -- Optional filter
+	@return Observable<Brio<Instance>>
+]=]
 function RxInstanceUtils.observeChildrenBrio(parent, predicate)
 	assert(typeof(parent) == "Instance", "Bad parent")
 	assert(type(predicate) == "function" or predicate == nil, "Bad predicate")
@@ -145,6 +195,13 @@ function RxInstanceUtils.observeChildrenBrio(parent, predicate)
 	end)
 end
 
+--[=[
+	Observes all descendants that match a predicate
+
+	@param parent Instance
+	@param predicate ((value: Instance) -> boolean)? -- Optional filter
+	@return Observable<Brio<Instance>>
+]=]
 function RxInstanceUtils.observeDescendants(parent, predicate)
 	assert(typeof(parent) == "Instance", "Bad parent")
 	assert(type(predicate) == "function" or predicate == nil, "Bad predicate")

package/src/Shared/RxInstanceUtils.spec.lua

@@ -1,5 +1,6 @@
----
--- @module RxInstanceUtils.spec.lua
+--[[
+	@class RxInstanceUtils.spec.lua
+]]
 
 local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)