@quenty/maid 2.0.1-canary.c3c8cd3.0 → 2.0.2

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.
 
-## [2.0.1-canary.c3c8cd3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/maid@2.0.0...@quenty/maid@2.0.1-canary.c3c8cd3.0) (2021-10-12)
+## [2.0.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/maid@2.0.1...@quenty/maid@2.0.2) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/maid
+
+
+
+
+
+## [2.0.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/maid@2.0.0...@quenty/maid@2.0.1) (2021-10-06)
 
 **Note:** Version bump only for package @quenty/maid
 

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014 Quenty
+Copyright (c) 2014-2021 Quenty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
 ## Maid
 <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" />
@@ -12,6 +12,8 @@
 </div>
 Easily cleanup event listeners and objects in Roblox
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/Maid">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/maid --save

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/maid",
-  "version": "2.0.1-canary.c3c8cd3.0",
+  "version": "2.0.2",
   "description": "Easily cleanup event listeners and objects in Roblox",
   "keywords": [
     "Roblox",
@@ -29,5 +29,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c3c8cd3fe14e7342315d82f45c53f887be5ce192"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Shared/Maid.lua

@@ -1,26 +1,76 @@
----	Manages the cleaning of events and other things.
--- Useful for encapsulating state and make deconstructors easy
--- @classmod Maid
--- @see Signal
+-- luacheck: push ignore
+--[=[
+	Manages the cleaning of events and other things. Useful for
+	encapsulating state and make deconstructors easy.
+
+	See the [Five Powerful Code Patterns talk](https://developer.roblox.com/en-us/videos/5-powerful-code-patterns-behind-top-roblox-games)
+	for a more in-depth look at Maids in top games.
+
+	```lua
+	local maid = Maid.new()
+
+	maid:GiveTask(function()
+		print("Cleaning up")
+	end)
+
+	maid:GiveTask(workspace.ChildAdded:Connect(print))
+
+	-- Disconnects all events, and executes all functions
+	maid:DoCleaning()
+	```
+
+	@class Maid
+]=]
+-- luacheck: pop
 
 local Maid = {}
 Maid.ClassName = "Maid"
 
---- Returns a new Maid object
--- @constructor Maid.new()
--- @treturn Maid
+--[=[
+	Constructs a new Maid object
+
+	```lua
+	local maid = Maid.new()
+	```
+
+	@return Maid
+]=]
 function Maid.new()
 	return setmetatable({
 		_tasks = {}
 	}, Maid)
 end
 
+--[=[
+	Returns true if the class is a maid, and false otherwise.
+
+	```lua
+	print(Maid.isMaid(Maid.new())) --> true
+	print(Maid.isMaid(nil)) --> false
+	```
+
+	@param value any
+	@return boolean
+]=]
 function Maid.isMaid(value)
 	return type(value) == "table" and value.ClassName == "Maid"
 end
 
---- Returns Maid[key] if not part of Maid metatable
--- @return Maid[key] value
+--[=[
+	Returns Maid[key] if not part of Maid metatable
+
+	```lua
+	local maid = Maid.new()
+	maid._current = Instance.new("Part")
+	print(maid._current) --> Part
+
+	maid._current = nil
+	print(maid._current) --> nil
+	```
+
+	@param index any
+	@return MaidTask
+]=]
 function Maid:__index(index)
 	if Maid[index] then
 		return Maid[index]
@@ -29,15 +79,24 @@ function Maid:__index(index)
 	end
 end
 
---- Add a task to clean up. Tasks given to a maid will be cleaned when
---  maid[index] is set to a different value.
--- @usage
--- Maid[key] = (function)         Adds a task to perform
--- Maid[key] = (event connection) Manages an event connection
--- Maid[key] = (Maid)             Maids can act as an event connection, allowing a Maid to have other maids to clean up.
--- Maid[key] = (Object)           Maids can cleanup objects with a `Destroy` method
--- Maid[key] = nil                Removes a named task. If the task is an event, it is disconnected. If it is an object,
---                                it is destroyed.
+--[=[
+	Add a task to clean up. Tasks given to a maid will be cleaned when
+	maid[index] is set to a different value.
+
+	Task cleanup is such that if the task is an event, it is disconnected.
+	If it is an object, it is destroyed.
+
+	```
+	Maid[key] = (function)         Adds a task to perform
+	Maid[key] = (event connection) Manages an event connection
+	Maid[key] = (Maid)             Maids can act as an event connection, allowing a Maid to have other maids to clean up.
+	Maid[key] = (Object)           Maids can cleanup objects with a `Destroy` method
+	Maid[key] = nil                Removes a named task.
+	```
+
+	@param index any
+	@param newTask MaidTask
+]=]
 function Maid:__newindex(index, newTask)
 	if Maid[index] ~= nil then
 		error(("'%s' is reserved"):format(tostring(index)), 2)
@@ -63,9 +122,12 @@ function Maid:__newindex(index, newTask)
 	end
 end
 
---- Same as indexing, but uses an incremented number as a key.
--- @param task An item to clean
--- @treturn number taskId
+--[=[
+	Gives a task to the maid for cleanup, but uses an incremented number as a key.
+
+	@param task MaidTask -- An item to clean
+	@return number -- taskId
+]=]
 function Maid:GiveTask(task)
 	if not task then
 		error("Task cannot be false or nil", 2)
@@ -81,6 +143,12 @@ function Maid:GiveTask(task)
 	return taskId
 end
 
+--[=[
+	Gives a promise to the maid for clean.
+
+	@param promise Promise<T>
+	@return Promise<T>
+]=]
 function Maid:GivePromise(promise)
 	if not promise:IsPending() then
 		return promise
@@ -97,8 +165,22 @@ function Maid:GivePromise(promise)
 	return newPromise
 end
 
---- Cleans up all tasks.
--- @alias Destroy
+--[=[
+	Cleans up all tasks and removes them as entries from the Maid.
+
+	:::note
+	Signals that are already connected are always disconnected first. After that
+	any signals added during a cleaning phase will be disconnected at random times.
+	:::
+
+	:::tip
+	DoCleaning() may be recursively invoked. This allows the you to ensure that
+	tasks or other tasks. Each task will be executed once.
+
+	However, adding tasks while cleaning is not generally a good idea, as if you add a
+	function that adds itself, this will loop indefinitely.
+	:::
+]=]
 function Maid:DoCleaning()
 	local tasks = self._tasks
 
@@ -125,8 +207,12 @@ function Maid:DoCleaning()
 	end
 end
 
---- Alias for DoCleaning()
--- @function Destroy
+--[=[
+	Alias for [Maid.DoCleaning()](/api/Maid#DoCleaning)
+
+	@function Destroy
+	@within Maid
+]=]
 Maid.Destroy = Maid.DoCleaning
 
 return Maid

package/src/Shared/MaidTaskUtils.lua

@@ -1,15 +1,39 @@
----
--- @module MaidTaskUtils
--- @author Quenty
+--[=[
+	Utility methods involving maids and tasks.
+	@class MaidTaskUtils
+]=]
 
+--[=[
+	An object that can have the method :Destroy() called on it
+	@type Destructable Instance | { Destroy: function }
+	@within MaidTaskUtils
+]=]
+
+--[=[
+	An object that can be cleaned up
+	@type MaidTask function | Destructable | RBXScriptConnection
+	@within MaidTaskUtils
+]=]
 local MaidTaskUtils = {}
 
+--[=[
+	Returns whether a task is a valid job.
+
+	@param job any
+	@return boolean
+]=]
 function MaidTaskUtils.isValidTask(job)
 	return type(job) == "function"
 		or typeof(job) == "RBXScriptConnection"
 		or type(job) == "table" and type(job.Destroy) == "function"
+		or typeof(job) == "Instance"
 end
 
+--[=[
+	Executes the task as requested.
+
+	@param job MaidTask -- Task to execute
+]=]
 function MaidTaskUtils.doTask(job)
 	if type(job) == "function" then
 		job()
@@ -17,11 +41,26 @@ function MaidTaskUtils.doTask(job)
 		job:Disconnect()
 	elseif type(job) == "table" and type(job.Destroy) == "function" then
 		job:Destroy()
+	-- selene: allow(if_same_then_else)
+	elseif typeof(job) == "Instance" then
+		job:Destroy()
 	else
 		error("Bad job")
 	end
 end
 
+--[=[
+	Executes the task delayed after some time.
+
+	```lua
+	-- delays cleanup by 5 seconds
+	maid:GiveTask(MaidTaskUtils.delayed(5, gui))
+	```
+
+	@param time number -- Time in seconds
+	@param job MaidTask -- Job to delay execution
+	@return () -> () -- function that will execute the job delayed
+]=]
 function MaidTaskUtils.delayed(time, job)
 	assert(type(time) == "number", "Bad time")
 	assert(MaidTaskUtils.isValidTask(job), "Bad job")