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

package/out/utility/getClassesInPath.luau

@@ -1,9 +1,34 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
 local tsImport = TS.import(script, script.Parent, "tsImport").tsImport
 local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
-local resolveRbxPath = TS.import(script, script.Parent, "pathRoot").resolveRbxPath
+local _pathRoot = TS.import(script, script.Parent, "pathRoot")
+local findRbxPath = _pathRoot.findRbxPath
+local getPathRoot = _pathRoot.getPathRoot
+local resolveRbxPath = _pathRoot.resolveRbxPath
 local getModuleClasses = TS.import(script, script.Parent, "moduleClasses").getModuleClasses
+--* How long {@link requireModules} waits for a folder that is not in the place, in seconds. 
+local MISSING_FOLDER_TIMEOUT = 5
+--[[
+	*
+	 * Why this realm cannot require a folder under `game` that belongs to the other realm, or nothing
+	 * when it can: a client sees nothing of the server's containers, and the server has no
+	 * `PlayerScripts` to take a client folder from.
+	 
+]]
+local function otherRealmReason(rbxPath)
+	if getPathRoot() ~= game then
+		return nil
+	end
+	local service = rbxPath[1]
+	if RunService:IsClient() and (service == "ServerScriptService" or service == "ServerStorage") then
+		return `the folder is in {service}, which does not replicate to clients. Call requireModules for it on the server`
+	end
+	if not RunService:IsClient() and service == "StarterPlayer" then
+		return "the folder is in StarterPlayer/StarterPlayerScripts, which only a client requires from, through its PlayerScripts. Call requireModules for it on the client"
+	end
+end
 --[[
 	*
 	 * Requires one ModuleScript through the roblox-ts runtime, as an `import` would, and returns what
@@ -23,23 +48,42 @@ local function importModule(moduleScript)
 end
 --[[
 	*
-	 * Requires every ModuleScript at and under a Rojo path, in tree order, handing each to `visit` with
+	 * Requires every ModuleScript at and under an instance, in tree order, handing each to `visit` with
 	 * what it exported.
 	 
 ]]
-local function loadModulesInPath(rbxPath, visit)
-	local _rbxPath = rbxPath
-	assert(_rbxPath)
-	local preloadPath = resolveRbxPath(rbxPath)
-	if preloadPath:IsA("ModuleScript") then
-		visit(preloadPath, importModule(preloadPath))
+local function loadModulesIn(root, visit)
+	if root:IsA("ModuleScript") then
+		visit(root, importModule(root))
 	end
-	for _, instance in preloadPath:GetDescendants() do
+	for _, instance in root:GetDescendants() do
 		if instance:IsA("ModuleScript") then
 			visit(instance, importModule(instance))
 		end
 	end
 end
+--[[
+	*
+	 * Requires every ModuleScript at and under a Rojo path, in tree order, handing each to `visit` with
+	 * what it exported. `caller` names the call that gave the path, for the warning a slow wait gets.
+	 
+]]
+local function loadModulesInPath(rbxPath, visit, caller)
+	local _rbxPath = rbxPath
+	assert(_rbxPath)
+	loadModulesIn(resolveRbxPath(rbxPath, caller), visit)
+end
+--* What every ModuleScript at and under an instance exported, leaving out the ones that exported nothing. 
+local function requireModulesIn(root)
+	local loaded = {}
+	loadModulesIn(root, function(_, value)
+		if value ~= nil then
+			local _value = value
+			table.insert(loaded, _value)
+		end
+	end)
+	return loaded
+end
 --[[
 	*
 	 * Requires every ModuleScript at and under the specified Rojo path, in tree order, and returns
@@ -52,14 +96,48 @@ end
 	 
 ]]
 local function requireModulesInPath(rbxPath)
-	local loaded = {}
-	loadModulesInPath(rbxPath, function(_, value)
-		if value ~= nil then
-			local _value = value
-			table.insert(loaded, _value)
-		end
-	end)
-	return loaded
+	local _rbxPath = rbxPath
+	assert(_rbxPath)
+	return requireModulesIn(resolveRbxPath(rbxPath))
+end
+--[[
+	*
+	 * Requires every ModuleScript at and under a source folder, in tree order, for what the modules do
+	 * as they load, and returns what each exported, leaving out the ones that exported nothing. This is
+	 * v1's `Flamework.addPaths` for a folder that holds no providers: modules that register themselves
+	 * with a library, such as commands.
+	 *
+	 * The path is a source path, as a string literal: `requireModules("src/server/commands")`. The build
+	 * turns it into the Rojo path the folder ends up at, as it does for `registerProviders`, so the
+	 * folder has to be in your Rojo project.
+	 *
+	 * Each module is required through the roblox-ts module cache, so it runs once, however many times
+	 * it is required. A folder inside a folder that `registerProviders` registers needs no call:
+	 * registration already requires every ModuleScript under it.
+	 *
+	 * Raises when a module fails to load, and when the folder is not in the place. A missing folder is
+	 * waited for five seconds, once the place has loaded, and the error names the part that is missing.
+	 * A folder of the other realm's -- a server folder on a client, a client folder on the server --
+	 * raises at once, saying so.
+	 *
+	 * @metadata macro
+	 
+]]
+local function requireModules(path, rbxPath)
+	if rbxPath == nil then
+		error(`requireModules("{path}") was called without the folder's Rojo path, which the build fills in. ` .. "Call it directly, with a string literal, in code that the Flamework transformer compiles.", 2)
+	end
+	local otherRealm = otherRealmReason(rbxPath)
+	if otherRealm ~= nil then
+		error(`requireModules("{path}"): {otherRealm}.`, 2)
+	end
+	local _binding = findRbxPath(rbxPath, MISSING_FOLDER_TIMEOUT)
+	local found = _binding.found
+	local missing = _binding.missing
+	if missing ~= nil then
+		error(`requireModules("{path}"): the folder is not in the place. The build put it at {table.concat(rbxPath, "/")}, ` .. `and {found:GetFullName()} has no child named '{missing}' after {MISSING_FOLDER_TIMEOUT} seconds. ` .. "The path is misspelled or differs in case from the folder, or the folder is empty and missing from this " .. "clone, since git keeps no empty folder (the build warns about these where the path is used); or it was " .. "moved or renamed after the build; or the Rojo project the place was built from leaves it out.", 2)
+	end
+	return requireModulesIn(found)
 end
 --[[
 	*
@@ -76,9 +154,12 @@ end
 	 *
 	 * A module that fails to load raises, as it did in v1: a class that silently fails to register
 	 * would otherwise only show up later as an unresolvable dependency, far from the cause.
+	 *
+	 * The folder is waited for as {@link resolveRbxPath} waits: `caller`, the registration that gave the
+	 * path (`registerProviders("src/server/services")`), is named in the warning a slow wait gets.
 	 
 ]]
-local function getClassesInPath(rbxPath)
+local function getClassesInPath(rbxPath, caller)
 	local foundClasses = {}
 	local found = {}
 	-- Own metadata only: an undecorated subclass inherits its parent's identifier, and must not be
@@ -120,11 +201,12 @@ local function getClassesInPath(rbxPath)
 		for _, member in pairs(value) do
 			add(member)
 		end
-	end)
+	end, caller)
 	return foundClasses
 end
 return {
 	importModule = importModule,
 	requireModulesInPath = requireModulesInPath,
+	requireModules = requireModules,
 	getClassesInPath = getClassesInPath,
 }

package/out/utility/pathRoot.d.ts

@@ -13,5 +13,24 @@ export declare function getPathRoot(): Instance;
  *
  * Under `game` the first segment names a service, and `StarterPlayer/StarterPlayerScripts` is
  * answered from the local player's `PlayerScripts`, which is where that content actually runs.
+ *
+ * A child that is not there within five seconds (on a client, once the place has loaded) is warned
+ * about, naming `caller` -- the call that gave the path, such as `registerProviders("src/shared/components")`
+ * -- and the child missing, and then waited for without a limit: content that arrives late still
+ * resolves, as it always has. The warning comes once per path: a child further down that is late
+ * too is the same wait, and is waited for without a second one.
+ */
+export declare function resolveRbxPath(rbxPath: readonly string[], caller?: string): Instance;
+/**
+ * Walks a compile-time path as {@link resolveRbxPath} does, but gives up on a child that is not
+ * there instead of waiting for it forever. A client still loading the place waits for it to load
+ * first, since the place's content arrives as it loads; after that, a missing child is given
+ * `timeout` seconds to appear.
+ *
+ * Returns the instance the path names, or the deepest instance it found and the name missing below
+ * it.
  */
-export declare function resolveRbxPath(rbxPath: readonly string[]): Instance;
+export declare function findRbxPath(rbxPath: readonly string[], timeout: number): {
+    found: Instance;
+    missing?: string;
+};

package/out/utility/pathRoot.luau

@@ -56,13 +56,14 @@ local function getPathRoot()
 end
 --[[
 	*
-	 * Walks a compile-time path from {@link getPathRoot}, waiting for each child in turn.
+	 * Walks a compile-time path from {@link getPathRoot}, asking `child` for each segment in turn, and
+	 * stops at the first segment it has no instance for.
 	 *
 	 * Under `game` the first segment names a service, and `StarterPlayer/StarterPlayerScripts` is
 	 * answered from the local player's `PlayerScripts`, which is where that content actually runs.
 	 
 ]]
-local function resolveRbxPath(rbxPath)
+local function walkRbxPath(rbxPath, child)
 	-- Copied so that a generated path literal is not consumed by this call.
 	local _array = {}
 	local _length = #_array
@@ -83,9 +84,83 @@ local function resolveRbxPath(rbxPath)
 		end
 	end
 	for _, segment in path do
-		node = node:WaitForChild(segment)
+		local found = child(node, segment)
+		if found == nil then
+			return {
+				found = node,
+				missing = segment,
+			}
+		end
+		node = found
+	end
+	return {
+		found = node,
+	}
+end
+--[[
+	*
+	 * How long a child of a path is waited for before the wait is warned about, in seconds: when the
+	 * engine would warn of an infinite yield, which names neither the call nor the source path.
+	 
+]]
+local MISSING_CHILD_WARNING = 5
+--* A child that is there now, or once a client has loaded the place and `timeout` seconds more have passed. 
+local function waitForChild(parent, name, timeout)
+	local child = parent:FindFirstChild(name)
+	if child ~= nil then
+		return child
+	end
+	-- A client receives the place's content as it loads, so its time only starts once it has loaded.
+	if RunService:IsClient() and not game:IsLoaded() then
+		game.Loaded:Wait()
 	end
-	return node
+	return parent:WaitForChild(name, timeout)
+end
+--[[
+	*
+	 * Walks a compile-time path from {@link getPathRoot}, waiting for each child in turn.
+	 *
+	 * Under `game` the first segment names a service, and `StarterPlayer/StarterPlayerScripts` is
+	 * answered from the local player's `PlayerScripts`, which is where that content actually runs.
+	 *
+	 * A child that is not there within five seconds (on a client, once the place has loaded) is warned
+	 * about, naming `caller` -- the call that gave the path, such as `registerProviders("src/shared/components")`
+	 * -- and the child missing, and then waited for without a limit: content that arrives late still
+	 * resolves, as it always has. The warning comes once per path: a child further down that is late
+	 * too is the same wait, and is waited for without a second one.
+	 
+]]
+local function resolveRbxPath(rbxPath, caller)
+	local warned = false
+	return walkRbxPath(rbxPath, function(parent, name)
+		if warned then
+			return parent:WaitForChild(name)
+		end
+		local child = waitForChild(parent, name, MISSING_CHILD_WARNING)
+		if child ~= nil then
+			return child
+		end
+		warned = true
+		local waiting = if caller ~= nil then `{caller} is still waiting for its folder` else "Flamework is still waiting for a folder"
+		warn(`{waiting}: the build put it at {table.concat(rbxPath, "/")}, ` .. `and {parent:GetFullName()} has no child named '{name}' after {MISSING_CHILD_WARNING} seconds. ` .. "The path may be misspelled or differ in case from the folder, or the folder may be empty and missing from " .. "this clone, since git keeps no empty folder (the build warns about these where the path is used); or " .. "the folder was moved or renamed after the build, or the Rojo project the place was built from leaves it " .. "out. It keeps waiting.")
+		return parent:WaitForChild(name)
+	end).found
+end
+--[[
+	*
+	 * Walks a compile-time path as {@link resolveRbxPath} does, but gives up on a child that is not
+	 * there instead of waiting for it forever. A client still loading the place waits for it to load
+	 * first, since the place's content arrives as it loads; after that, a missing child is given
+	 * `timeout` seconds to appear.
+	 *
+	 * Returns the instance the path names, or the deepest instance it found and the name missing below
+	 * it.
+	 
+]]
+local function findRbxPath(rbxPath, timeout)
+	return walkRbxPath(rbxPath, function(parent, name)
+		return waitForChild(parent, name, timeout)
+	end)
 end
 --[[
 	*
@@ -101,5 +176,6 @@ end
 return {
 	getPathRoot = getPathRoot,
 	resolveRbxPath = resolveRbxPath,
+	findRbxPath = findRbxPath,
 	__setPathRoot = __setPathRoot,
 }

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@flamework-experimental/core",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.4",
   "main": "out/init.luau",
   "types": "out/index.d.ts",
-  "scripts": {
-    "build": "rbxtsc",
-    "watch": "rbxtsc -w"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rbxts-flamework/core.git"
+    "url": "git+https://github.com/Velover/ExperimentalFlameworkV2.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/Velover/ExperimentalFlameworkV2#readme",
+  "bugs": {
+    "url": "https://github.com/Velover/ExperimentalFlameworkV2/issues"
+  },
+  "scripts": {
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w",
+    "prepack": "node ../../scripts/copy-readme.mjs && node ../../scripts/copy-docs.mjs"
   },
   "files": [
     "out",
-    "flamework.build"
+    "flamework.build",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"