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

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.2",
+  "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"