@quenty/loader 3.1.1 → 3.2.0-canary.241.a4e8214.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.2.0-canary.241.a4e8214.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/loader@3.1.2...@quenty/loader@3.2.0-canary.241.a4e8214.0) (2022-01-03)
+
+
+### Bug Fixes
+
+* Better error messages ([4a49909](https://github.com/Quenty/NevermoreEngine/commit/4a49909e607ca21d751da510f57ee0629808f11d))
+
+
+
+
+
+## [3.1.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/loader@3.1.1...@quenty/loader@3.1.2) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/loader
+
+
+
+
+
 ## [3.1.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/loader@3.1.0...@quenty/loader@3.1.1) (2021-10-30)
 
 

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 @@
 # Nevermore Loader
 <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" />
@@ -18,6 +18,8 @@ A simple module loader for Roblox
 npm install @quenty/loader --save
 ```
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/loader">View docs →</a></div>
+
 ## Installation with NPM
 
 Install via NPM like this:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/loader",
-  "version": "3.1.1",
+  "version": "3.2.0-canary.241.a4e8214.0",
   "description": "A simple module loader for Roblox",
   "keywords": [
     "Roblox",
@@ -26,5 +26,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "e9cd4223c7fda7c852db9743ef844baa19cacb13"
+  "gitHead": "a4e821471f35998d63f38a4f4a578e07b4e79035"
 }

package/src/BounceTemplate.lua

@@ -1,6 +1,9 @@
---- Bounces the current named script to the expected version of this module
--- @module BounceTemplate
--- @author Quenty
+--[=[
+	Bounces the current named script to the expected version of this module
+
+	@private
+	@class BounceTemplate
+]=]
 
 local function waitForValue(objectValue)
 	local value = objectValue.Value

package/src/BounceTemplateUtils.lua

@@ -1,6 +1,7 @@
----
--- @module BounceTemplateUtils
--- @author Quenty
+--[=[
+	@class BounceTemplateUtils
+	@private
+]=]
 
 local BounceTemplate = script.Parent.BounceTemplate
 
@@ -9,57 +10,57 @@ local CREATE_ONLY_LINK = false
 local BounceTemplateUtils = {}
 
 function BounceTemplateUtils.isBounceTemplate(instance)
-    return instance:GetAttribute("IsBounceTemplate", true) == true
+	return instance:GetAttribute("IsBounceTemplate", true) == true
 end
 
 function BounceTemplateUtils.getTarget(instance)
-    if not BounceTemplateUtils.isBounceTemplate(instance) then
-        return nil
-    end
+	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
+	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")
+	assert(typeof(target) == "Instance", "Bad target")
+	assert(type(linkName) == "string", "Bad linkName")
 
-    if CREATE_ONLY_LINK then
-        return BounceTemplateUtils.createLink(target, linkName)
-    end
+	if CREATE_ONLY_LINK then
+		return BounceTemplateUtils.createLink(target, linkName)
+	end
 
-    local copy = BounceTemplate:Clone()
-    copy:SetAttribute("IsBounceTemplate", true)
-    copy.Name = linkName
+	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
+	local objectValue = Instance.new("ObjectValue")
+	objectValue.Name = "BounceTarget"
+	objectValue.Value = target
+	objectValue.Parent = copy
 
-    return copy
+	return copy
 end
 
 function BounceTemplateUtils.createLink(target, linkName)
-    assert(typeof(target) == "Instance", "Bad target")
-    assert(type(linkName) == "string", "Bad 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)
+	local objectValue = Instance.new("ObjectValue")
+	objectValue.Name = linkName
+	objectValue.Value = target
+	objectValue:SetAttribute("IsBounceTemplate", true)
 
-    return objectValue
+	return objectValue
 end
 
 return BounceTemplateUtils

package/src/GroupInfoUtils.lua

@@ -1,6 +1,8 @@
----
--- @module GroupInfoUtils
--- @author Quenty
+--[=[
+	Nevermore loader utility library
+	@private
+	@class GroupInfoUtils
+]=]
 
 local Utils = require(script.Parent.Utils)
 local Queue = require(script.Parent.Queue)

package/src/LegacyLoader.lua

@@ -1,5 +1,9 @@
---- Legacy loading logic
--- @module loader
+--[=[
+	Legacy loading logic
+
+	@private
+	@class LegacyLoader
+]=]
 
 local RunService = game:GetService("RunService")
 local ReplicatedStorage = game:GetService("ReplicatedStorage")

package/src/Loader.lua

@@ -1,5 +1,9 @@
---- Loading logic
--- @module loader
+--[=[
+	Loading logic for Nevermore
+
+	@private
+	@class LoaderClass
+]=]
 
 local Loader = {}
 Loader.ClassName = "Loader"

package/src/LoaderUtils.lua

@@ -1,6 +1,7 @@
----
--- @module LoaderUtils
--- @author Quenty
+--[=[
+	@private
+	@class LoaderUtils
+]=]
 
 local loader = script.Parent
 local BounceTemplateUtils = require(script.Parent.BounceTemplateUtils)

package/src/PackageInfoUtils.lua

@@ -1,6 +1,8 @@
---- Utility methods to build a virtual graph of the existing package information set
--- @module PackageInfoUtils
--- @author Quenty
+--[=[
+	Utility methods to build a virtual graph of the existing package information set
+	@private
+	@class PackageInfoUtils
+]=]
 
 local Utils = require(script.Parent.Utils)
 local ScriptInfoUtils = require(script.Parent.ScriptInfoUtils)
@@ -183,7 +185,7 @@ function PackageInfoUtils.tryLoadPackageFromInstance(packageInfoList, packageInf
 		if value and (value:IsA("Folder") or value:IsA("ModuleScript")) then
 			table.insert(packageInfoList, PackageInfoUtils.getOrCreatePackageInfo(value, packageInfoMap, scope))
 		else
-			warn(("Invalid %q ObjectValue in package linking to nothing cannot be resolved into package dependency\n\t-> %s")
+			error(("Invalid %q ObjectValue in package linking to nothing cannot be resolved into package dependency\n\t-> %s")
 				:format(instance.Name, instance:GetFullName()))
 		end
 	end

package/src/Queue.lua

@@ -1,11 +1,18 @@
----
--- @module Queue
--- @author Quenty
+--[=[
+	Private queue class for loading system.
+
+	@private
+	@class Queue
+]=]
 
 local Queue = {}
 Queue.ClassName = "Queue"
 Queue.__index = Queue
 
+--[=[
+	Constructs a new queue
+	@return Queue<T>
+]=]
 function Queue.new()
 	return setmetatable({
 		_first = 0;
@@ -13,16 +20,28 @@ function Queue.new()
 	}, Queue)
 end
 
+--[=[
+	Pushes an entry to the left of the queue
+	@param value T
+]=]
 function Queue:PushLeft(value)
 	self._first = self._first - 1
 	self[self._first] = value
 end
 
+--[=[
+	Pushes an entry to the right of the queue
+	@param value T
+]=]
 function Queue:PushRight(value)
 	self._last = self._last + 1
 	self[self._last] = value
 end
 
+--[=[
+	Pops an entry from the left of the queue
+	@return T
+]=]
 function Queue:PopLeft()
 	if self._first > self._last then
 		error("Queue is empty")
@@ -35,6 +54,10 @@ function Queue:PopLeft()
 	return value
 end
 
+--[=[
+	Pops an entry from the right of the queue
+	@return T
+]=]
 function Queue:PopRight()
 	if self._first > self._last then
 		error("Queue is empty")
@@ -47,6 +70,10 @@ function Queue:PopRight()
 	return value
 end
 
+--[=[
+	Returns true if the queue is empty
+	@return boolean
+]=]
 function Queue:IsEmpty()
 	return self._first > self._last
 end

package/src/ScriptInfoUtils.lua

@@ -1,6 +1,7 @@
----
--- @module ScriptInfoUtils
--- @author Quenty
+--[=[
+	@private
+	@class ScriptInfoUtils
+]=]
 
 local CollectionService = game:GetService("CollectionService")
 

package/src/StaticLegacyLoader.lua

@@ -1,6 +1,7 @@
----
--- @classmod StaticLegacyLoader
--- @author Quenty
+--[=[
+	@private
+	@class StaticLegacyLoader
+]=]
 
 local loader = script.Parent
 local ScriptInfoUtils = require(script.Parent.ScriptInfoUtils)

package/src/Utils.lua

@@ -1,112 +1,113 @@
----
--- @module Utils
--- @author Quenty
+--[=[
+	@private
+	@class Utils
+]=]
 
 local Utils = {}
 
 local function errorOnIndex(_, index)
-    error(("Bad index %q"):format(tostring(index)), 2)
+	error(("Bad index %q"):format(tostring(index)), 2)
 end
 
 local READ_ONLY_METATABLE = {
-    __index = errorOnIndex;
-    __newindex = errorOnIndex;
+	__index = errorOnIndex;
+	__newindex = errorOnIndex;
 }
 
 function Utils.readonly(_table)
-    return setmetatable(_table, READ_ONLY_METATABLE)
+	return setmetatable(_table, READ_ONLY_METATABLE)
 end
 
 function Utils.copyTable(target)
-    local new = {}
-    for key, value in pairs(target) do
-        new[key] = value
-    end
-    return new
+	local new = {}
+	for key, value in pairs(target) do
+		new[key] = value
+	end
+	return new
 end
 
 function Utils.count(_table)
-    local count = 0
-    for _, _ in pairs(_table) do
-        count = count + 1
-    end
-    return count
+	local count = 0
+	for _, _ in pairs(_table) do
+		count = count + 1
+	end
+	return count
 end
 
 function Utils.getOrCreateValue(parent, instanceType, name, defaultValue)
-    assert(typeof(parent) == "Instance", "Bad argument 'parent'")
-    assert(type(instanceType) == "string", "Bad argument 'instanceType'")
-    assert(type(name) == "string", "Bad argument 'name'")
-
-    local foundChild = parent:FindFirstChild(name)
-    if foundChild then
-        if not foundChild:IsA(instanceType) then
-            warn(("[Utils.getOrCreateValue] - Value of type %q of name %q is of type %q in %s instead")
-                :format(instanceType, name, foundChild.ClassName, foundChild:GetFullName()))
-        end
-
-        return foundChild
-    else
-        local newChild = Instance.new(instanceType)
-        newChild.Name = name
-        newChild.Value = defaultValue
-        newChild.Parent = parent
-
-        return newChild
-    end
+	assert(typeof(parent) == "Instance", "Bad argument 'parent'")
+	assert(type(instanceType) == "string", "Bad argument 'instanceType'")
+	assert(type(name) == "string", "Bad argument 'name'")
+
+	local foundChild = parent:FindFirstChild(name)
+	if foundChild then
+		if not foundChild:IsA(instanceType) then
+			warn(("[Utils.getOrCreateValue] - Value of type %q of name %q is of type %q in %s instead")
+				:format(instanceType, name, foundChild.ClassName, foundChild:GetFullName()))
+		end
+
+		return foundChild
+	else
+		local newChild = Instance.new(instanceType)
+		newChild.Name = name
+		newChild.Value = defaultValue
+		newChild.Parent = parent
+
+		return newChild
+	end
 end
 
 function Utils.getValue(parent, instanceType, name, default)
-    assert(typeof(parent) == "Instance", "Bad argument 'parent'")
-    assert(type(instanceType) == "string", "Bad argument 'instanceType'")
-    assert(type(name) == "string", "Bad argument 'name'")
-
-    local foundChild = parent:FindFirstChild(name)
-    if foundChild then
-        if foundChild:IsA(instanceType) then
-            return foundChild.Value
-        else
-            warn(("[Utils.getValue] - Value of type %q of name %q is of type %q in %s instead")
-                :format(instanceType, name, foundChild.ClassName, foundChild:GetFullName()))
-            return nil
-        end
-    else
-        return default
-    end
+	assert(typeof(parent) == "Instance", "Bad argument 'parent'")
+	assert(type(instanceType) == "string", "Bad argument 'instanceType'")
+	assert(type(name) == "string", "Bad argument 'name'")
+
+	local foundChild = parent:FindFirstChild(name)
+	if foundChild then
+		if foundChild:IsA(instanceType) then
+			return foundChild.Value
+		else
+			warn(("[Utils.getValue] - Value of type %q of name %q is of type %q in %s instead")
+				:format(instanceType, name, foundChild.ClassName, foundChild:GetFullName()))
+			return nil
+		end
+	else
+		return default
+	end
 end
 
 function Utils.setValue(parent, instanceType, name, value)
-    assert(typeof(parent) == "Instance", "Bad argument 'parent'")
-    assert(type(instanceType) == "string", "Bad argument 'instanceType'")
-    assert(type(name) == "string", "Bad argument 'name'")
-
-    local foundChild = parent:FindFirstChild(name)
-    if foundChild then
-        if not foundChild:IsA(instanceType) then
-            warn(("[Utils.setValue] - Value of type %q of name %q is of type %q in %s instead")
-                :format(instanceType, name, foundChild.ClassName, foundChild:GetFullName()))
-        end
-
-        foundChild.Value = value
-    else
-        local newChild = Instance.new(instanceType)
-        newChild.Name = name
-        newChild.Value = value
-        newChild.Parent = parent
-    end
+	assert(typeof(parent) == "Instance", "Bad argument 'parent'")
+	assert(type(instanceType) == "string", "Bad argument 'instanceType'")
+	assert(type(name) == "string", "Bad argument 'name'")
+
+	local foundChild = parent:FindFirstChild(name)
+	if foundChild then
+		if not foundChild:IsA(instanceType) then
+			warn(("[Utils.setValue] - Value of type %q of name %q is of type %q in %s instead")
+				:format(instanceType, name, foundChild.ClassName, foundChild:GetFullName()))
+		end
+
+		foundChild.Value = value
+	else
+		local newChild = Instance.new(instanceType)
+		newChild.Name = name
+		newChild.Value = value
+		newChild.Parent = parent
+	end
 end
 
 
 function Utils.getOrCreateFolder(parent, folderName)
-    local found = parent:FindFirstChild(folderName)
-    if found then
-        return found
-    else
-        local folder = Instance.new("Folder")
-        folder.Name = folderName
-        folder.Parent = parent
-        return folder
-    end
+	local found = parent:FindFirstChild(folderName)
+	if found then
+		return found
+	else
+		local folder = Instance.new("Folder")
+		folder.Name = folderName
+		folder.Parent = parent
+		return folder
+	end
 end
 
 

package/src/init.lua

@@ -1,5 +1,17 @@
---- Loads things
--- @module loader
+--[=[
+	Loads Nevermore and handles loading!
+
+	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
+]=]
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local ServerScriptService = game:GetService("ServerScriptService")
@@ -34,6 +46,27 @@ else
 	}
 end
 
+--[=[
+	Bootstraps the game by replicating packages to server, client, and
+	shared.
+
+	```lua
+	local ServerScriptService = game:GetService("ServerScriptService")
+
+	local loader = ServerScriptService:FindFirstChild("LoaderUtils", true).Parent
+	local packages = require(loader).bootstrapGame(ServerScriptService.ik)
+	```
+
+	:::info
+	The game must be running to do this bootstrapping operation.
+	:::
+
+	@server
+	@function bootstrapGame
+	@param packageFolder Instance
+	@return Folder -- serverFolder
+	@within Loader
+]=]
 local function bootstrapGame(packageFolder)
 	assert(RunService:IsRunning(), "Game must be running")
 
@@ -48,6 +81,27 @@ local function bootstrapGame(packageFolder)
 	return serverFolder
 end
 
+--[=[
+	A type that can be loaded into a module
+	@type ModuleReference ModuleScript | number | string
+	@within Loader
+]=]
+
+--[=[
+	Returns a function that can be used to load modules relative
+	to the script specified.
+
+	```lua
+	local require = require(script.Parent.loader).load(script)
+
+	local maid = require("Maid")
+	```
+
+	@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")