@flamework-experimental/core 2.0.0-alpha.1 → 2.0.0-alpha.3

package/out/utility/leftOut.luau

@@ -0,0 +1,171 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local describeConditions = TS.import(script, script.Parent.Parent, "module", "scopes").describeConditions
+local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local getGlobPaths = TS.import(script, script.Parent, "globs").getGlobPaths
+local findModuleClass = TS.import(script, script.Parent, "moduleClasses").findModuleClass
+local getPathRoot = TS.import(script, script.Parent, "pathRoot").getPathRoot
+--[[
+	*
+	 * A path or glob registration that its own scope condition left out. Its folder was never looked up,
+	 * so nothing under it was loaded, and nothing from it was registered or recorded as inactive: this
+	 * is what a miss can still say about the classes there.
+	 
+]]
+--[[
+	*
+	 * Records a registration left out by its own condition. Reads nothing but the path root, which is
+	 * found from Flamework's own metadata, never from the folder.
+	 
+]]
+local function leftOutRegistration(call, condition, folder)
+	return {
+		call = call,
+		condition = {
+			activeIn = condition.activeIn,
+			inactiveIn = condition.inactiveIn,
+		},
+		path = folder.path,
+		glob = folder.glob,
+		root = getPathRoot(),
+	}
+end
+--[[
+	*
+	 * The tree path of a loaded module below `root`, in the form a compile-time path has: a client's
+	 * `PlayerScripts` is written as `StarterPlayer/StarterPlayerScripts`, where its content comes from.
+	 * Nothing when the module is not below `root`.
+	 
+]]
+local function treePathOf(moduleScript, root)
+	local names = {}
+	local current = moduleScript
+	while current ~= nil and current ~= root do
+		local _name = current.Name
+		table.insert(names, 1, _name)
+		current = current.Parent
+	end
+	if current == nil then
+		return nil
+	end
+	if root == game and names[1] == "Players" and names[3] == "PlayerScripts" then
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _callback = function(_, index)
+			return index >= 3
+		end
+		local _length = 0
+		for _k, _v in names do
+			if _callback(_v, _k - 1, names) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		local rest = _newValue
+		local _array = { "StarterPlayer", "StarterPlayerScripts" }
+		local _length_1 = #_array
+		table.move(rest, 1, #rest, _length_1 + 1, _array)
+		return _array
+	end
+	return names
+end
+local function startsWith(path, prefix)
+	if #path < #prefix then
+		return false
+	end
+	for i = 0, #prefix - 1 do
+		if path[i + 1] ~= prefix[i + 1] then
+			return false
+		end
+	end
+	return true
+end
+--* Whether a loaded module is under the folder, or one of the folders, a left-out registration named. 
+local function isUnder(moduleScript, registration)
+	local modulePath = treePathOf(moduleScript, registration.root)
+	if modulePath == nil then
+		return false
+	end
+	if registration.path ~= nil then
+		return startsWith(modulePath, registration.path)
+	end
+	if registration.glob ~= nil then
+		-- `globs.json`, not the folders: what the glob matched when the build was compiled.
+		local ok, paths = pcall(getGlobPaths, registration.glob)
+		if not ok then
+			return false
+		end
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		local _callback = function(path)
+			return startsWith(modulePath, path)
+		end
+		for _k, _v in paths do
+			if _callback(_v, _k - 1, paths) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		return _result
+	end
+	return false
+end
+--[[
+	*
+	 * What a miss on `id` can say about the registrations its module or plugin left out by their own
+	 * condition, without looking at their folders:
+	 *
+	 * - the class has loaded some other way, and its module is under one of them: that one, and why;
+	 * - the class has not loaded: every one of them, since the class may be under any;
+	 * - nothing when there are none, or when the loaded class is under none of them.
+	 
+]]
+local function explainLeftOut(id, leftOut)
+	if #leftOut == 0 then
+		return nil
+	end
+	local advice = "the build's scopes so that the condition holds, or do not depend on it in this build"
+	local found = findModuleClass(function(value)
+		return Reflect.getOwnMetadata(value, "identifier") == id
+	end)
+	if found ~= nil then
+		local _binding = found
+		local value = _binding[1]
+		local moduleScript = _binding[2]
+		-- ▼ ReadonlyArray.find ▼
+		local _callback = function(registration)
+			return isUnder(moduleScript, registration)
+		end
+		local _result
+		for _i, _v in leftOut do
+			if _callback(_v, _i - 1, leftOut) == true then
+				_result = _v
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.find ▲
+		local under = _result
+		if under == nil then
+			return nil
+		end
+		local where = if typeof(moduleScript) == "Instance" then moduleScript:GetFullName() else tostring(moduleScript)
+		return `'{value}' ({where}) is under {under.call}, which is left out by its scope ` .. `({describeConditions({ under.condition })}): nothing under it is registered. Change {advice}`
+	end
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#leftOut)
+	local _callback = function(v)
+		return `{v.call} ({describeConditions({ v.condition })})`
+	end
+	for _k, _v in leftOut do
+		_newValue[_k] = _callback(_v, _k - 1, leftOut)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local listed = table.concat(_newValue, ", ")
+	return `nothing registers it. Left out by their scope, without loading their folders: {listed}. ` .. `If it is defined under one of them, change {advice}`
+end
+return {
+	leftOutRegistration = leftOutRegistration,
+	explainLeftOut = explainLeftOut,
+}

package/out/utility/moduleClasses.d.ts

@@ -0,0 +1,9 @@
+/** Records a class against the module that defined it. Called by `Reflect.defineMetadata`. */
+export declare function recordModuleClass(moduleScript: unknown, value: object): void;
+/** The classes a module defined as it loaded, in definition order, or none. */
+export declare function getModuleClasses(moduleScript: unknown): ReadonlyArray<object> | undefined;
+/**
+ * Every recorded class, with the module that defined it, until the callback answers `true`. For
+ * explaining a failed resolution, which is rare: nothing here is indexed for it.
+ */
+export declare function findModuleClass(predicate: (value: object) => boolean): [object, unknown] | undefined;

package/out/utility/moduleClasses.luau

@@ -0,0 +1,64 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * The Flamework classes each module defined as it loaded, by the module's `script`, in the order
+	 * they were defined: what path registration finds in a module besides what it exports.
+	 *
+	 * The transformer records a class with `Reflect.defineMetadata(class, "flamework:module", script)`,
+	 * and only a class the module creates once per load -- declared at the top level of the file, or
+	 * of a namespace in it. A class declared inside a function is created by every call and is never
+	 * recorded, so nothing here grows with calls, and a later path registration never finds a class
+	 * that belongs to a test case or a factory. Keyed by the ModuleScript rather than read off the
+	 * class's identifier, which says nothing about where the class came from once ids are short, tiny
+	 * or obfuscated.
+	 *
+	 * Held for good, as the module's own exports are held by the require cache: a module loads once.
+	 
+]]
+local classesByModule = {}
+--* Records a class against the module that defined it. Called by `Reflect.defineMetadata`. 
+local function recordModuleClass(moduleScript, value)
+	if moduleScript == nil then
+		return nil
+	end
+	local _moduleScript = moduleScript
+	local classes = classesByModule[_moduleScript]
+	if classes == nil then
+		classes = {}
+		local _moduleScript_1 = moduleScript
+		local _classes = classes
+		classesByModule[_moduleScript_1] = _classes
+	end
+	local _classes = classes
+	local _value = value
+	if not (table.find(_classes, _value) ~= nil) then
+		local _classes_1 = classes
+		local _value_1 = value
+		table.insert(_classes_1, _value_1)
+	end
+end
+--* The classes a module defined as it loaded, in definition order, or none. 
+local function getModuleClasses(moduleScript)
+	local _moduleScript = moduleScript
+	return classesByModule[_moduleScript]
+end
+--[[
+	*
+	 * Every recorded class, with the module that defined it, until the callback answers `true`. For
+	 * explaining a failed resolution, which is rare: nothing here is indexed for it.
+	 
+]]
+local function findModuleClass(predicate)
+	for moduleScript, classes in classesByModule do
+		for _, value in classes do
+			if predicate(value) then
+				return { value, moduleScript }
+			end
+		end
+	end
+end
+return {
+	recordModuleClass = recordModuleClass,
+	getModuleClasses = getModuleClasses,
+	findModuleClass = findModuleClass,
+}

package/out/utility/recycleThread.d.ts

@@ -1 +1,13 @@
+/**
+ * Runs `func` with the arguments given, on a thread that is kept for the next call once it returns:
+ * one that yields keeps its thread, and the next call gets a new one.
+ *
+ * The arguments are passed through rather than closed over, so that a caller running many callbacks
+ * -- the per-frame events, once per listener every frame -- creates nothing per call.
+ */
 export declare function recycleThread(func: () => void): void;
+export declare function recycleThread<A>(func: (a: A) => void, a: A): void;
+export declare function recycleThread<A, B>(func: (a: A, b: B) => void, a: A, b: B): void;
+export declare function recycleThread<A, B, C>(func: (a: A, b: B, c: C) => void, a: A, b: B, c: C): void;
+export declare function recycleThread<A, B, C, D>(func: (a: A, b: B, c: C, d: D) => void, a: A, b: B, c: C, d: D): void;
+export declare function recycleThread<A, B, C, D, E>(func: (a: A, b: B, c: C, d: D, e: E) => void, a: A, b: B, c: C, d: D, e: E): void;

package/out/utility/recycleThread.luau

@@ -1,29 +1,48 @@
 -- Compiled with roblox-ts v3.0.0
 local inactiveThread
-local function reusableThread(func)
+local function reusableThread(func, a, b, c, d, e)
 	local thread = coroutine.running()
 	while true do
 		if inactiveThread == thread then
 			inactiveThread = nil
 		end
-		func()
+		func(a, b, c, d, e)
 		-- If there's a different idle thread, we should end the current thread.
 		if inactiveThread ~= nil then
 			break
 		end
 		inactiveThread = thread
-		-- Let go of the callback while idle: it closes over whatever it was run for -- a lifecycle
-		-- listener, a component -- which would otherwise stay reachable from this thread until the
-		-- next callback comes through, and for good when none does.
+		-- Let go of the callback and its arguments while idle: they are whatever it was run for -- a
+		-- lifecycle listener, a component -- which would otherwise stay reachable from this thread
+		-- until the next callback comes through, and for good when none does.
 		func = nil
-		func = coroutine.yield()
+		a = nil
+		b = nil
+		c = nil
+		d = nil
+		e = nil
+		func, a, b, c, d, e = coroutine.yield()
 	end
 end
-local function recycleThread(func)
-	if inactiveThread then
-		task.spawn(inactiveThread, func)
+--[[
+	*
+	 * Runs `func` with the arguments given, on a thread that is kept for the next call once it returns:
+	 * one that yields keeps its thread, and the next call gets a new one.
+	 *
+	 * The arguments are passed through rather than closed over, so that a caller running many callbacks
+	 * -- the per-frame events, once per listener every frame -- creates nothing per call.
+	 
+]]
+local function recycleThread(func, a, b, c, d, e)
+	-- Only while it is parked: a callback that kept `coroutine.running()` and cancelled it later left
+	-- a dead thread here, and every later call, of every module, raised trying to resume it. One that
+	-- is not is dropped, and a new thread takes its place.
+	local idle = inactiveThread
+	if idle ~= nil and coroutine.status(idle) == "suspended" then
+		task.spawn(idle, func, a, b, c, d, e)
 	else
-		task.spawn(reusableThread, func)
+		inactiveThread = nil
+		task.spawn(reusableThread, func, a, b, c, d, e)
 	end
 end
 return {

package/out/utility/threadWaits.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Every thread waiting for another to finish something, to the thread it waits for: an extinguish
+ * waiting in `awaitExtinguished` for one running on another thread, and an ignition waiting for an
+ * `onInit` the lifecycle plugin runs on a thread of its own. Shared by every module, since a chain
+ * of waits runs through several: `awaitExtinguished` follows it to refuse the wait that would close
+ * a circle.
+ *
+ * Or to the Promise it waits for: an ignition waiting for the Promise an `onInit` returned, whose
+ * work runs on a thread nothing can name -- an `async` method's body runs on one of its own, not the
+ * `onInit` thread. A chain that ends at one may end at any thread, the waiting one included.
+ *
+ * An entry is removed by whatever ends the wait -- what is waited for, as it finishes, or the poll
+ * that sees the waiting thread die -- and not by the waiting thread once it resumes: one that is
+ * cancelled never resumes.
+ */
+export declare const threadWaits: Map<thread, thread | Promise<unknown>>;
+/**
+ * How many extinguishes have begun, in any module, counted from the first line of `extinguish()`.
+ * The lifecycle plugin's per-frame walks read it after every callback and ask their module whether
+ * it has begun to extinguish only when it has changed, so that a callback that extinguishes the
+ * module -- itself, on a thread it starts, through a signal it fires -- stops the walk without a
+ * call per listener.
+ */
+export declare const extinguishesBegun: {
+    count: number;
+};
+/**
+ * Whether a thread does Promise work: whether its outermost function -- what it was started with --
+ * is the Promise library's or the one an `async` function's body runs in.
+ *
+ * The lifecycle plugin takes such a thread to be doing the work of the Promise an `onInit` returned
+ * while it waits on one, since nothing records which threads that is: an `async` body that has
+ * yielded, an executor, a chained callback. An unrelated Promise's thread passes too, and a thread
+ * an executor starts itself with `task.spawn` or `task.delay` does not.
+ */
+export declare function runsPromiseWork(thread: thread): boolean;

package/out/utility/threadWaits.luau

@@ -0,0 +1,81 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+--[[
+	*
+	 * Every thread waiting for another to finish something, to the thread it waits for: an extinguish
+	 * waiting in `awaitExtinguished` for one running on another thread, and an ignition waiting for an
+	 * `onInit` the lifecycle plugin runs on a thread of its own. Shared by every module, since a chain
+	 * of waits runs through several: `awaitExtinguished` follows it to refuse the wait that would close
+	 * a circle.
+	 *
+	 * Or to the Promise it waits for: an ignition waiting for the Promise an `onInit` returned, whose
+	 * work runs on a thread nothing can name -- an `async` method's body runs on one of its own, not the
+	 * `onInit` thread. A chain that ends at one may end at any thread, the waiting one included.
+	 *
+	 * An entry is removed by whatever ends the wait -- what is waited for, as it finishes, or the poll
+	 * that sees the waiting thread die -- and not by the waiting thread once it resumes: one that is
+	 * cancelled never resumes.
+	 
+]]
+local threadWaits = {}
+--[[
+	*
+	 * How many extinguishes have begun, in any module, counted from the first line of `extinguish()`.
+	 * The lifecycle plugin's per-frame walks read it after every callback and ask their module whether
+	 * it has begun to extinguish only when it has changed, so that a callback that extinguishes the
+	 * module -- itself, on a thread it starts, through a signal it fires -- stops the walk without a
+	 * call per listener.
+	 
+]]
+local extinguishesBegun = {
+	count = 0,
+}
+local asyncFunction = TS.async(function() end)
+--[[
+	*
+	 * The scripts a thread doing Promise work starts in: the Promise library, which runs executors and
+	 * chained callbacks on threads of their own, and the runtime library, which runs an `async`
+	 * function's body on one of its own.
+	 
+]]
+local promiseSources = {
+	[(debug.info(TS.Promise.is, "s"))] = true,
+	[(debug.info(asyncFunction, "s"))] = true,
+}
+--[[
+	*
+	 * Whether a thread does Promise work: whether its outermost function -- what it was started with --
+	 * is the Promise library's or the one an `async` function's body runs in.
+	 *
+	 * The lifecycle plugin takes such a thread to be doing the work of the Promise an `onInit` returned
+	 * while it waits on one, since nothing records which threads that is: an `async` body that has
+	 * yielded, an executor, a chained callback. An unrelated Promise's thread passes too, and a thread
+	 * an executor starts itself with `task.spawn` or `task.delay` does not.
+	 
+]]
+local function runsPromiseWork(thread)
+	local outermost
+	local level = 1
+	while true do
+		local source = (debug.info(thread, level, "s"))
+		if source == nil then
+			break
+		end
+		-- A C function (`pcall`, the scheduler's resume) is not where the thread's work comes from.
+		if source ~= "[C]" then
+			outermost = source
+		end
+		level += 1
+	end
+	local _condition = outermost ~= nil
+	if _condition then
+		local _outermost = outermost
+		_condition = promiseSources[_outermost] ~= nil
+	end
+	return _condition
+end
+return {
+	runsPromiseWork = runsPromiseWork,
+	threadWaits = threadWaits,
+	extinguishesBegun = extinguishesBegun,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamework-experimental/core",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.3",
   "main": "out/init.luau",
   "types": "out/index.d.ts",
   "scripts": {