@quenty/loader 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [10.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/loader@10.0.0...@quenty/loader@10.1.0) (2024-03-09)
+
+**Note:** Version bump only for package @quenty/loader
+
+
+
+
+
 # [10.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/loader@9.0.0...@quenty/loader@10.0.0) (2024-02-14)
 
 

package/default.project.json

@@ -1,6 +1,6 @@
 {
   "name": "loader",
   "tree": {
-    "$path": "src2"
+    "$path": "src"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/loader",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "description": "A simple module loader for Roblox",
   "keywords": [
     "Roblox",
@@ -26,5 +26,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "63f949a67b77d3edc98b358cace163da8c789e9f"
+  "gitHead": "e0148dde5ca3864389a0faa2da66153a776acc1e"
 }

package/src/LoaderUtils.lua

@@ -1,236 +1,3 @@
---[=[
-	@private
-	@class LoaderUtils
-]=]
+-- Literally here just so old loading code works
 
-local loader = script.Parent
-local BounceTemplateUtils = require(script.Parent.BounceTemplateUtils)
-local GroupInfoUtils = require(script.Parent.GroupInfoUtils)
-local PackageInfoUtils = require(script.Parent.PackageInfoUtils)
-local ScriptInfoUtils = require(script.Parent.ScriptInfoUtils)
-local Utils = require(script.Parent.Utils)
-
-local LoaderUtils = {}
-LoaderUtils.Utils = Utils -- TODO: Remove this
-
-LoaderUtils.ContextTypes = Utils.readonly({
-	CLIENT = "client";
-	SERVER = "server";
-})
-LoaderUtils.IncludeBehavior = Utils.readonly({
-	NO_INCLUDE = "noInclude";
-	INCLUDE_ONLY = "includeOnly";
-	INCLUDE_SHARED = "includeShared";
-})
-
-function LoaderUtils.toWallyFormat(instance, isPlugin)
-	assert(typeof(instance) == "Instance", "Bad instance")
-	assert(type(isPlugin) == "boolean", "Bad isPlugin")
-
-	local topLevelPackages = {}
-	LoaderUtils.discoverTopLevelPackages(topLevelPackages, instance)
-	LoaderUtils.injectLoader(topLevelPackages)
-
-	local packageInfoList = {}
-	local packageInfoMap = {}
-	local defaultReplicationType = isPlugin
-		and ScriptInfoUtils.ModuleReplicationTypes.PLUGIN
-		or ScriptInfoUtils.ModuleReplicationTypes.SHARED
-
-	for _, folder in pairs(topLevelPackages) do
-		local packageInfo = PackageInfoUtils.getOrCreatePackageInfo(folder, packageInfoMap, "", defaultReplicationType)
-		table.insert(packageInfoList, packageInfo)
-	end
-
-	PackageInfoUtils.fillDependencySet(packageInfoList)
-
-	if isPlugin then
-		local pluginGroup = GroupInfoUtils.groupPackageInfos(packageInfoList, ScriptInfoUtils.ModuleReplicationTypes.PLUGIN)
-		local publishSet = LoaderUtils.getPublishPackageInfoSet(packageInfoList)
-
-		local pluginFolder = Instance.new("Folder")
-		pluginFolder.Name = "PluginPackages"
-
-		LoaderUtils.reifyGroupList(pluginGroup, publishSet, pluginFolder, ScriptInfoUtils.ModuleReplicationTypes.PLUGIN)
-
-		return pluginFolder
-	else
-		local clientGroupList = GroupInfoUtils.groupPackageInfos(packageInfoList, ScriptInfoUtils.ModuleReplicationTypes.CLIENT)
-		local serverGroupList = GroupInfoUtils.groupPackageInfos(packageInfoList, ScriptInfoUtils.ModuleReplicationTypes.SERVER)
-		local sharedGroupList = GroupInfoUtils.groupPackageInfos(packageInfoList, ScriptInfoUtils.ModuleReplicationTypes.SHARED)
-		local publishSet = LoaderUtils.getPublishPackageInfoSet(packageInfoList)
-
-		local clientFolder = Instance.new("Folder")
-		clientFolder.Name = "Packages"
-
-		local sharedFolder = Instance.new("Folder")
-		sharedFolder.Name = "SharedPackages"
-
-		local serverFolder = Instance.new("Folder")
-		serverFolder.Name = "Packages"
-
-		LoaderUtils.reifyGroupList(clientGroupList, publishSet, clientFolder, ScriptInfoUtils.ModuleReplicationTypes.CLIENT)
-		LoaderUtils.reifyGroupList(serverGroupList, publishSet, serverFolder, ScriptInfoUtils.ModuleReplicationTypes.SERVER)
-		LoaderUtils.reifyGroupList(sharedGroupList, publishSet, sharedFolder, ScriptInfoUtils.ModuleReplicationTypes.SHARED)
-
-		return clientFolder, serverFolder, sharedFolder
-	end
-end
-
-function LoaderUtils.isPackage(folder)
-	assert(typeof(folder) == "Instance", "Bad instance")
-
-	for _, item in pairs(folder:GetChildren()) do
-		if item:IsA("Folder") or item:IsA("Camera") then
-			if item.Name == "Server"
-				or item.Name == "Client"
-				or item.Name == "Shared"
-				or item.Name == ScriptInfoUtils.DEPENDENCY_FOLDER_NAME then
-				return true
-			end
-		end
-	 end
-
-	 return false
-end
-
-function LoaderUtils.injectLoader(topLevelPackages)
-	for _, item in pairs(topLevelPackages) do
-		-- If we're underneath the hierachy or if we're in the actual item...
-		if item == loader or loader:IsDescendantOf(item) then
-			return
-		end
-	end
-
-	-- We need the loader injected!
-	table.insert(topLevelPackages, loader)
-end
-
-function LoaderUtils.discoverTopLevelPackages(packages, instance)
-	assert(type(packages) == "table", "Bad packages")
-	assert(typeof(instance) == "Instance", "Bad instance")
-
-	if LoaderUtils.isPackage(instance) then
-		table.insert(packages, instance)
-	elseif instance:IsA("ObjectValue") then
-		local linkedValue = instance.Value
-		if linkedValue and LoaderUtils.isPackage(linkedValue) then
-			table.insert(packages, linkedValue)
-		end
-	else
-		-- Loop through all folders
-		for _, item in pairs(instance:GetChildren()) do
-			if item:IsA("Folder") or item:IsA("Camera") then
-				LoaderUtils.discoverTopLevelPackages(packages, item)
-			elseif item:IsA("ObjectValue") then
-				local linkedValue = item.Value
-				if linkedValue and LoaderUtils.isPackage(linkedValue) then
-					table.insert(packages, linkedValue)
-				end
-			elseif item:IsA("ModuleScript") then
-				table.insert(packages, item)
-			end
-		end
-	end
-end
-
-function LoaderUtils.reifyGroupList(groupInfoList, publishSet, parent, replicationMode)
-	assert(type(groupInfoList) == "table", "Bad groupInfoList")
-	assert(type(publishSet) == "table", "Bad publishSet")
-	assert(typeof(parent) == "Instance", "Bad parent")
-	assert(type(replicationMode) == "string", "Bad replicationMode")
-
-	local folder = Instance.new("Folder")
-	folder.Name = "_Index"
-
-	for _, groupInfo in pairs(groupInfoList) do
-		if LoaderUtils.needToReify(groupInfo, replicationMode) then
-			LoaderUtils.reifyGroup(groupInfo, folder, replicationMode)
-		end
-	end
-
-	-- Publish
-	for packageInfo, _ in pairs(publishSet) do
-		for scriptName, scriptInfo in pairs(packageInfo.scriptInfoLookup[replicationMode]) do
-			local link = BounceTemplateUtils.create(scriptInfo.instance, scriptName)
-			link.Parent = parent
-		end
-	end
-
-	folder.Parent = parent
-end
-
-function LoaderUtils.getPublishPackageInfoSet(packageInfoList)
-	local packageInfoSet = {}
-	for _, packageInfo in pairs(packageInfoList) do
-		packageInfoSet[packageInfo] = true
-		-- First level declared dependencies too (assuming we're importing just one item)
-		for dependentPackageInfo, _ in pairs(packageInfo.explicitDependencySet) do
-			packageInfoSet[dependentPackageInfo] = true
-		end
-	end
-	return packageInfoSet
-end
-
-function LoaderUtils.needToReify(groupInfo, replicationMode)
-	for _, scriptInfo in pairs(groupInfo.packageScriptInfoMap) do
-		if scriptInfo.replicationMode == replicationMode then
-			return true
-		end
-	end
-
-	return false
-end
-
-function LoaderUtils.reifyGroup(groupInfo, parent, replicationMode)
-	assert(type(groupInfo) == "table", "Bad groupInfo")
-	assert(typeof(parent) == "Instance", "Bad parent")
-	assert(type(replicationMode) == "string", "Bad replicationMode")
-
-	local folder = Instance.new("Folder")
-	folder.Name = assert(next(groupInfo.packageSet).fullName, "Bad package fullName")
-
-	for scriptName, scriptInfo in pairs(groupInfo.packageScriptInfoMap) do
-		assert(scriptInfo.name == scriptName, "Bad scriptInfo.name")
-
-		if scriptInfo.replicationMode == replicationMode then
-			if scriptInfo.instance == loader and loader.Parent == game:GetService("ReplicatedStorage") then
-				-- Hack to prevent reparenting of loader in legacy mode
-				local link = BounceTemplateUtils.create(scriptInfo.instance, scriptName)
-				link.Parent = folder
-			else
-				scriptInfo.instance.Name = scriptName
-				scriptInfo.instance.Parent = folder
-			end
-		else
-			if scriptInfo.instance == loader then
-				local link = BounceTemplateUtils.create(scriptInfo.instance, scriptName)
-				link.Parent = folder
-			else
-				-- Turns out creating these links are a LOT faster than cloning a module script
-				local link = BounceTemplateUtils.createLink(scriptInfo.instance, scriptName)
-				link.Parent = folder
-			end
-		end
-	end
-
-	-- Link all of the other dependencies
-	for scriptName, scriptInfo in pairs(groupInfo.scriptInfoMap) do
-		assert(scriptInfo.name == scriptName, "Bad scriptInfo.name")
-
-		if not groupInfo.packageScriptInfoMap[scriptName] then
-			if scriptInfo.instance == loader then
-				local link = BounceTemplateUtils.create(scriptInfo.instance, scriptName)
-				link.Parent = folder
-			else
-				-- Turns out creating these links are a LOT faster than cloning a module script
-				local link = BounceTemplateUtils.createLink(scriptInfo.instance, scriptName)
-				link.Parent = folder
-			end
-		end
-	end
-
-	folder.Parent = parent
-end
-
-return LoaderUtils
+error("Not implemented! Please require LoaderUtils.Parent. This file acts as a marker for old loader versions.")

package/src/Utils.lua

@@ -6,7 +6,7 @@
 local Utils = {}
 
 local function errorOnIndex(_, index)
-	error(("Bad index %q"):format(tostring(index)), 2)
+	error(string.format("Bad index %q", tostring(index)), 2)
 end
 
 local READ_ONLY_METATABLE = {

package/src/init.lua

@@ -1,137 +1,188 @@
 --[=[
-	Loads Nevermore and handles loading!
+	Primary loader which handles bootstrapping different scenarios quickly
 
-	This is a centralized loader that handles the following scenarios:
-
-	* Specific layouts for npm node_modules
-	* Layouts for node_modules being symlinked
-	* Multiple versions of modules being used in conjunction with each other
-	* Relative path requires
-	* Require by name
-	* Replication to client and server
-
-	@class Loader
+	@class loader
 ]=]
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local ServerScriptService = game:GetService("ServerScriptService")
 local RunService = game:GetService("RunService")
 
-local LegacyLoader = require(script.LegacyLoader)
-local StaticLegacyLoader = require(script.StaticLegacyLoader)
-local LoaderUtils = require(script.LoaderUtils)
-
-local loader, metatable
-if RunService:IsRunning() then
-	loader = LegacyLoader.new(script)
-	metatable = {
-		__call = function(_self, value)
-			return loader:Require(value)
-		end;
-		__index = function(_self, key)
-			return loader:Require(key)
-		end;
-	}
-else
-	loader = StaticLegacyLoader.new()
-	metatable = {
-		__call = function(_self, value)
-			local env = getfenv(2)
-			return loader:Require(env.script, value)
-		end;
-		__index = function(_self, key)
-			local env = getfenv(2)
-			return loader:Require(env.script, key)
-		end;
-	}
+local DependencyUtils = require(script.Dependencies.DependencyUtils)
+local LoaderLinkCreator = require(script.LoaderLink.LoaderLinkCreator)
+local LoaderLinkUtils = require(script.LoaderLink.LoaderLinkUtils)
+local Maid = require(script.Maid)
+local PackageTrackerProvider = require(script.Dependencies.PackageTrackerProvider)
+local ReplicationType = require(script.Replication.ReplicationType)
+local ReplicationTypeUtils = require(script.Replication.ReplicationTypeUtils)
+local Replicator = require(script.Replication.Replicator)
+local ReplicatorReferences = require(script.Replication.ReplicatorReferences)
+
+local GLOBAL_PACKAGE_TRACKER = PackageTrackerProvider.new()
+
+local Loader = {}
+Loader.__index = Loader
+Loader.ClassName = "Loader"
+
+function Loader.new(packages, replicationType)
+	assert(typeof(packages) == "Instance", "Bad packages")
+	assert(ReplicationTypeUtils.isReplicationType(replicationType), "Bad replicationType")
+
+	local self = setmetatable({}, Loader)
+
+	self._maid = Maid.new()
+
+	self._replicationType = assert(replicationType, "No replicationType")
+	self._packages = assert(packages, "No packages")
+
+	return self
 end
 
---[=[
-	Bootstraps the game by replicating packages to server, client, and
-	shared.
+function Loader.bootstrapGame(packages)
+	assert(typeof(packages) == "Instance", "Bad packages")
 
-	```lua
-	local ServerScriptService = game:GetService("ServerScriptService")
+	local self = Loader.new(packages, ReplicationTypeUtils.inferReplicationType())
 
-	local loader = ServerScriptService:FindFirstChild("LoaderUtils", true).Parent
-	local require = require(loader).bootstrapGame(ServerScriptService.ik)
-	```
+	if self._replicationType == ReplicationType.SERVER then
+		self:_setupLoaderPopulation()
 
-	:::info
-	The game must be running to do this bootstrapping operation.
-	:::
+		-- Trade off security for performance
+		if RunService:IsStudio() then
+			packages.Parent = ReplicatedStorage
+		else
+			self:_setupClientReplication()
+		end
+	end
 
-	@server
-	@function bootstrapGame
-	@param packageFolder Instance
-	@return Folder -- serverFolder
-	@within Loader
-]=]
-local function bootstrapGame(packageFolder)
-	assert(typeof(packageFolder) == "Instance", "Bad instance")
-	assert(RunService:IsRunning(), "Game must be running")
+	GLOBAL_PACKAGE_TRACKER:AddPackageRoot(packages)
+
+	-- We need to wait here once we "populate" the loader so the Ancestry/query events can
+	-- fire in Signal deferred mode.
+	self:_waitForNextDeferFrame()
+
+	return self
+end
+
+function Loader.bootstrapPlugin(packages)
+	assert(typeof(packages) == "Instance", "Bad packages")
+
+	local self = Loader.new(packages, ReplicationType.PLUGIN)
+
+	self:_setupLoaderPopulation()
+
+	GLOBAL_PACKAGE_TRACKER:AddPackageRoot(packages)
+
+	-- We need to wait here once we "populate" the loader so the Ancestry/query events can
+	-- fire in Signal deferred mode.
+	self:_waitForNextDeferFrame()
+
+	return self
+end
+
+function Loader.load(packagesOrModuleScript)
+	assert(typeof(packagesOrModuleScript) == "Instance", "Bad packagesOrModuleScript")
 
-	loader:Lock()
+	local self = Loader.new(packagesOrModuleScript, ReplicationTypeUtils.inferReplicationType())
 
-	local clientFolder, serverFolder, sharedFolder = LoaderUtils.toWallyFormat(packageFolder, false)
+	return self
+end
 
-	clientFolder.Parent = ReplicatedStorage
-	sharedFolder.Parent = ReplicatedStorage
-	serverFolder.Parent = ServerScriptService
+function Loader:__index(request)
+	if Loader[request] then
+		return Loader[request]
+	end
 
-	return serverFolder, clientFolder, sharedFolder
+	return self:_findDependency(request)
 end
 
-local function bootstrapPlugin(packageFolder)
-	assert(typeof(packageFolder) == "Instance", "Bad instance")
-	loader = LegacyLoader.new(script)
-	loader:Lock()
+function Loader:__call(request)
+	if type(request) == "string" then
+		local module = self:_findDependency(request)
+		return require(module)
+	else
+		return require(request)
+	end
+end
 
-	local pluginFolder = LoaderUtils.toWallyFormat(packageFolder, true)
-	pluginFolder.Parent = packageFolder
+function Loader:_waitForNextDeferFrame()
+	local signal = Instance.new("BindableEvent")
+	task.defer(function()
+		signal:Fire()
+	end)
+	signal.Event:Wait()
+	signal:Destroy()
+end
+
+function Loader:_findDependency(request)
+	assert(type(request) == "string", "Bad request")
 
-	return function(value)
-		if type(value) == "string" then
-			if pluginFolder:FindFirstChild(value) then
-				return require(pluginFolder:FindFirstChild(value))
+	local packageTracker = GLOBAL_PACKAGE_TRACKER:FindPackageTracker(self._packages)
+	if packageTracker then
+		local foundDependency = packageTracker:ResolveDependency(request, self._replicationType)
+		if foundDependency then
+			return foundDependency
+		end
+
+		-- Otherwise let's fail with an error acknowledging that the module exists
+		if self._replicationType == ReplicationType.SERVER or self._replicationType == ReplicationType.SHARED then
+			local foundClientDependency = packageTracker:ResolveDependency(request, ReplicationType.CLIENT)
+			if foundClientDependency then
+				error(string.format("[Loader] - %q is only available on the client", foundClientDependency.Name))
 			end
+		end
 
-			error(string.format("Unknown module %q", tostring(value)))
-		else
-			return require(value)
+		if self._replicationType == ReplicationType.CLIENT or self._replicationType == ReplicationType.SHARED then
+			local foundServerDependency = packageTracker:ResolveDependency(request, ReplicationType.SERVER)
+			if foundServerDependency then
+				error(string.format("[Loader] - %q is only available on the server", foundServerDependency.Name))
+			end
 		end
 	end
+
+	-- Just standard dependency search
+	local foundBackup = DependencyUtils.findDependency(self._packages, request, self._replicationType)
+	if foundBackup then
+		if RunService:IsRunning() then
+			warn(string.format("[Loader] - Failed to find package %q in package tracker\n%s", request, debug.traceback()))
+		end
+
+		-- Ensure hoarcekat story has a link to use
+		-- TODO: Maybe add to global package cache instead...
+		local parent = foundBackup.Parent
+		if parent and not parent:FindFirstChild("loader") then
+			local link = LoaderLinkUtils.create(script, "loader")
+			link.Parent = parent
+		end
+
+		return foundBackup
+	end
+
+	-- TODO: Track location and provider install command
+	error(string.format("[Loader] - %q is not available. Please make this module or install it to the package requiring it.", request))
+	return nil
 end
 
---[=[
-	A type that can be loaded into a module
-	@type ModuleReference ModuleScript | number | string
-	@within Loader
-]=]
+function Loader:_setupClientReplication()
+	local copy = self._maid:Add(Instance.new("Folder"))
+	copy.Name = self._packages.Name
 
---[=[
-	Returns a function that can be used to load modules relative
-	to the script specified.
+	local references = ReplicatorReferences.new()
 
-	```lua
-	local require = require(script.Parent.loader).load(script)
+	local replicator = self._maid:Add(Replicator.new(references))
+	replicator:SetTarget(copy)
+	replicator:ReplicateFrom(self._packages)
 
-	local maid = require("Maid")
-	```
+	self._maid:Add(LoaderLinkCreator.new(copy, references, true))
 
-	@function load
-	@param script Script -- The script to load dependencies for.
-	@return (moduleReference: ModuleReference) -> any
-	@within Loader
-]=]
-local function handleLoad(moduleScript)
-	assert(typeof(moduleScript) == "Instance", "Bad moduleScript")
+	copy.Parent = ReplicatedStorage
+end
+
+function Loader:_setupLoaderPopulation()
+	self._maid:Add(LoaderLinkCreator.new(self._packages, nil, true))
+end
 
-	return loader:GetLoader(moduleScript)
+function Loader:Destroy()
+	self._maid:DoCleaning()
+	setmetatable(self, nil)
 end
 
-return setmetatable({
-	load = handleLoad;
-	bootstrapGame = bootstrapGame;
-	bootstrapPlugin = bootstrapPlugin;
-}, metatable)
+return Loader

package/src/BounceTemplate.lua

@@ -1,17 +0,0 @@
---[=[
-	Bounces the current named script to the expected version of this module
-
-	@private
-	@class BounceTemplate
-]=]
-
-local function waitForValue(objectValue)
-	local value = objectValue.Value
-	if value then
-		return value
-	end
-
-	return objectValue.Changed:Wait()
-end
-
-return require(waitForValue(script:WaitForChild("BounceTarget")))

package/src/BounceTemplateUtils.lua

@@ -1,66 +0,0 @@
---[=[
-	@class BounceTemplateUtils
-	@private
-]=]
-
-local BounceTemplate = script.Parent.BounceTemplate
-
-local CREATE_ONLY_LINK = false
-
-local BounceTemplateUtils = {}
-
-function BounceTemplateUtils.isBounceTemplate(instance)
-	return instance:GetAttribute("IsBounceTemplate", true) == true
-end
-
-function BounceTemplateUtils.getTarget(instance)
-	if not BounceTemplateUtils.isBounceTemplate(instance) then
-		return nil
-	end
-
-	if instance:IsA("ObjectValue") then
-		return instance.Value
-	else
-		local found = instance:FindFirstChild("BounceTarget")
-		if found then
-			return found.Value
-		else
-			warn("[BounceTemplateUtils.getTarget] - Bounce template without BounceTarget")
-			return nil
-		end
-	end
-end
-
-function BounceTemplateUtils.create(target, linkName)
-	assert(typeof(target) == "Instance", "Bad target")
-	assert(type(linkName) == "string", "Bad linkName")
-
-	if CREATE_ONLY_LINK then
-		return BounceTemplateUtils.createLink(target, linkName)
-	end
-
-	local copy = BounceTemplate:Clone()
-	copy:SetAttribute("IsBounceTemplate", true)
-	copy.Name = linkName
-
-	local objectValue = Instance.new("ObjectValue")
-	objectValue.Name = "BounceTarget"
-	objectValue.Value = target
-	objectValue.Parent = copy
-
-	return copy
-end
-
-function BounceTemplateUtils.createLink(target, linkName)
-	assert(typeof(target) == "Instance", "Bad target")
-	assert(type(linkName) == "string", "Bad linkName")
-
-	local objectValue = Instance.new("ObjectValue")
-	objectValue.Name = linkName
-	objectValue.Value = target
-	objectValue:SetAttribute("IsBounceTemplate", true)
-
-	return objectValue
-end
-
-return BounceTemplateUtils