Skip to main content

Nexus

Nexus is a module loading provider framework forked from Roam that is inspired by Sleitnick's Axis framework.) This module loader is barebones with the exception of extensions. There is no built-in networking layer or built-in state management. Nexus is designed to be a simple, yet powerful module loader that allows developers to easily load and manage modules in their game with the ability to add extensions for additional functionality.

Nexus collects load-elligable modules (modules that pass the predicate if one is supplied) and initializes them "syncronously" in the order they were collected in - the order is determined "randomly" or by the table of paths provided by the developer. Once all modules are initialized, Nexus then "starts" the modules "asyncronously" by spawning the "Start" method in a new thread.

NOTES

  • Nexus does not need to be required in each module.
  • All modules are guaranteed safe to access in the "Start" method.
  • All modules are guaranteed to be initialized before the "Start" method is spawned.
  • Providers do not have to have either the "Init" or "Start" method.
  • Providers are guaranteed to be initialized in the expected order VIA the custom load order or topological sorting where dependencies are actually respected.
  • The name "Provider", "Service", or "Controller" is not required, you decide what convention to follow when naming your modules.
  • Extensions are optional and are used to extend the functionality of modules under-the-hood. They are there to save time writing common boilerplate code.

EXAMPLE USAGE

local MyProvider = {
	Config = {
		Name = "MyProvider", -- Optional, name is auto-generated.
		Dependencies = {
			[MyOtherProvider] = true,
		},
	},
}

function MyProvider:Add(x: number, y: number): number
	return x + y
end

function MyProvider:Init()
	print("MyProvider initialized!")

	-- This is 100% safe to do:
	print("OtherProvider runtime data:", MyOtherProvider:SomeMethod())
end

function MyProvider:Start()
	print("MyProvider started!")
	print(MyProvider:Add(1, 2))
end

return MyProvider

Types​

StartConfig​

</>
interface StartConfig {
ExtensionsToLoad: {ModuleScript}?--

A table of module scripts of extensions that will be registered

ProvidersToLoad: {ModuleScript}?--

A table of module scripts of modules that will be registered and

PostInitPreStartCallback: (() → Promise)?--

A callback that is called after all modules have been

Debug: boolean?--

Whether to log debug information.

}

and loaded in the order they are provided. loaded in the order they are provided. initialized and before they are started.

Provider​

</>
interface Provider {
Init: (self: Provider) → ()?--

The method that is spawned syncronously when the provider is initialized.

Start: (self: Provider) → ()?--

The method that is spawned asyncronously when the provider is started.

}

Extension​

</>
interface Extension {
BeforeInit: (
self: Extension,
provider: Provider
) → ()?--

The hook that fires before each provider is initialized.

BeforeStart: (
self: Extension,
provider: Provider
) → ()?--

The hook that fires before each provider is started.

}

Extensions allow developers to extend the functionality of modules under-the-hood. This is useful for adding additional functionality to modules without modifying the provider itself. Developers can save time writing common boilerplate code by using extensions, however, extensions do add a layer of abstraction. The use of extensions is optional and not required.

Functions​

Predicates.MatchesName​

</>
Nexus.Predicates.MatchesName(
name: string--

The name to match.

) → (moduleScript: ModuleScript) → boolean

Returns a predicate that matches a module script's name.

Predicates.IsService​

</>
Nexus.Predicates.IsService(moduleScript: ModuleScript) → boolean

Returns the matching result of a module script's name ending with "Service".

Predicates.IsController​

</>
Nexus.Predicates.IsController(moduleScript: ModuleScript) → boolean

Returns the matching result of a module script's name ending with "Controller".

Predicates.IsProvider​

</>
Nexus.Predicates.IsProvider(moduleScript: ModuleScript) → boolean

Returns the matching result of a module script's name ending with "Provider".

Predicates.IsComponent​

</>
Nexus.Predicates.IsComponent(moduleScript: ModuleScript) → boolean

Returns the matching conditions of a module script being a component. This checks if the type is a table, if it has a metatable, and if the __tostring cotains "Component" in the beginning of the string.

Compatibility

This predicate is only compatible with component libraries that mimic Sleitnick's Component library! If you are using a different component library, that doesn't happen to follow the same structure, you will need to write your own predicate.

GetProvider​

</>
Nexus.GetProvider(name: string) → Provider

Returns a provider by name. Will error if the provider doesn't exist.

Safety

Providers are only safe to access after Nexus has started! If you try to access a provider before Nexus has started, you could encounter unexpected behavior. 

local MyProvider = Nexus.GetProvider("MyModule")
-- Safe ONLY after Nexus has started.
MyModule:SomeMethod()

GetNameFromProvider​

</>
Nexus.GetNameFromProvider(prov: Provider) → string

Returns the name of a provider.

local MyProvider = Nexus.GetProvider("MyModule")
print(Nexus.GetNameFromProvider(MyModule)) -- "MyModule"

RegisterExtensionsIn​

</>
Nexus.RegisterExtensionsIn(
dir: Folder | ModuleScript | {Folder | ModuleScript},--

The directory or directories

predicate: (moduleScript: ModuleScript) → boolean,--

The predicate to filter extensions.

deepSearch: boolean?--

Whether to search recursively within module scripts.

) → ()

Recursively registers extensions in the provided directories.

to search for modules.

Nexus.RegisterExtensionsIn(ServerScriptService.Extensions, Nexus.Predicates.IsExtension)

RegisterExtension​

</>
Nexus.RegisterExtension(ext: Extension) → Extension

Registers an extension to be loaded by Nexus. This method should be called before Nexus.Start is called.

RegisterProvidersIn​

</>
Nexus.RegisterProvidersIn(
dir: Folder | ModuleScript | {Folder | ModuleScript},--

The directory or directories

predicate: (moduleScript: ModuleScript) → boolean,--

The predicate to filter modules.

deepSearch: boolean?--

Whether to search recursively within module scripts.

) → ()

Recursively registers modules in the provided directories.

to search for modules.

Nexus.RegisterProvidersIn(ServerScriptService.Services, Nexus.Predicates.IsService)
Nexus.RegisterProvidersIn(ReplicatedStorage.Client.Controllers, Nexus.Predicates.IsController)

RegisterProvider​

</>
Nexus.RegisterProvider(prov: Provider) → ()

Registers a provider to be loaded by Nexus. This method should be called before Nexus.Start is called.

Start​

</>
Nexus.Start(
config: StartConfig?--

The configuration for starting Nexus.

) → Promise--

A promise that is resolved once Nexus has fully started.

Starts Nexus by initializing and starting all registered modules.

Call Once

Can only be called once. Calling more than once will throw an error. You cannot register modules after Nexus has started. 

Nexus.Start({
	ExtensionsToLoad = {
		ReplicatedStorage.Shared.Extensions.PlayerLifecycles,
	},
	ProvidersToLoad = {
		ReplicatedStorage.Shared.Providers.MySharedProvider,
		ServerScriptService.Server.Providers.MyServerProvider,
	},
	PostInitPreStartCallback = function()
		print("All modules have been initialized, about to start them!")
	end,
	Debug = true, -- Same as doing Nexus.Debug = true
}):andThen(function()
	print("Nexus has fully started!")
end):catch(warn)

PromiseOnStarted​

</>
Nexus.PromiseOnStarted() → Promise

Returns a promise that is resolved once Nexus has fully started. This is useful for any code that needs to tie into Nexus modules but is not the script that called Start. 

Nexus.PromiseOnStarted():andThen(function()
	local MyProvider = Nexus.GetProvider("MyModule")
	MyModule:SomeMethod()
end):catch(warn)
Show raw api
{
    "functions": [
        {
            "name": "Predicates.MatchesName",
            "desc": "Returns a predicate that matches a module script's name.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name to match.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "(moduleScript: ModuleScript) -> boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 278,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "Predicates.IsService",
            "desc": "Returns the matching result of a module script's name ending with \"Service\".",
            "params": [
                {
                    "name": "moduleScript",
                    "desc": "",
                    "lua_type": "ModuleScript"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 292,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "Predicates.IsController",
            "desc": "Returns the matching result of a module script's name ending with \"Controller\".",
            "params": [
                {
                    "name": "moduleScript",
                    "desc": "",
                    "lua_type": "ModuleScript"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 304,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "Predicates.IsProvider",
            "desc": "Returns the matching result of a module script's name ending with \"Provider\".",
            "params": [
                {
                    "name": "moduleScript",
                    "desc": "",
                    "lua_type": "ModuleScript"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 316,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "Predicates.IsComponent",
            "desc": "Returns the matching conditions of a module script being a component.\nThis checks if the type is a table, if it has a metatable, and if the\n__tostring cotains \"Component\" in the beginning of the string.\n\n:::caution Compatibility\nThis predicate is only compatible with component libraries that mimic\nSleitnick's Component library! If you are using a different component\nlibrary, that doesn't happen to follow the same structure, you will\nneed to write your own predicate.\n:::",
            "params": [
                {
                    "name": "moduleScript",
                    "desc": "",
                    "lua_type": "ModuleScript"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 337,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "GetProvider",
            "desc": "Returns a provider by name. Will error if the provider doesn't exist.\n\n:::warning Safety\nProviders are only safe to access after Nexus has started! If you try to access a provider before Nexus\nhas started, you could encounter unexpected behavior.\n\n```lua\nlocal MyProvider = Nexus.GetProvider(\"MyModule\")\n-- Safe ONLY after Nexus has started.\nMyModule:SomeMethod()\n```\n:::",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Provider\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 360,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "GetNameFromProvider",
            "desc": "Returns the name of a provider.\n\n```lua\nlocal MyProvider = Nexus.GetProvider(\"MyModule\")\nprint(Nexus.GetNameFromProvider(MyModule)) -- \"MyModule\"\n```",
            "params": [
                {
                    "name": "prov",
                    "desc": "",
                    "lua_type": "Provider"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 375,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "RegisterExtensionsIn",
            "desc": "Recursively registers extensions in the provided directories.\n\nto search for modules.\n\n```lua\nNexus.RegisterExtensionsIn(ServerScriptService.Extensions, Nexus.Predicates.IsExtension)\n```",
            "params": [
                {
                    "name": "dir",
                    "desc": "The directory or directories",
                    "lua_type": "Folder | ModuleScript | { Folder | ModuleScript }"
                },
                {
                    "name": "predicate",
                    "desc": "The predicate to filter extensions.",
                    "lua_type": "(moduleScript: ModuleScript) -> boolean"
                },
                {
                    "name": "deepSearch",
                    "desc": "Whether to search recursively within module scripts.",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 393,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "RegisterExtension",
            "desc": "Registers an extension to be loaded by Nexus. This method should be called before Nexus.Start is called.",
            "params": [
                {
                    "name": "ext",
                    "desc": "",
                    "lua_type": "Extension"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Extension\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 400,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "RegisterProvidersIn",
            "desc": "Recursively registers modules in the provided directories.\n\nto search for modules.\n\n```lua\nNexus.RegisterProvidersIn(ServerScriptService.Services, Nexus.Predicates.IsService)\nNexus.RegisterProvidersIn(ReplicatedStorage.Client.Controllers, Nexus.Predicates.IsController)\n```",
            "params": [
                {
                    "name": "dir",
                    "desc": "The directory or directories",
                    "lua_type": "Folder | ModuleScript | { Folder | ModuleScript }"
                },
                {
                    "name": "predicate",
                    "desc": "The predicate to filter modules.",
                    "lua_type": "(moduleScript: ModuleScript) -> boolean"
                },
                {
                    "name": "deepSearch",
                    "desc": "Whether to search recursively within module scripts.",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 425,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "RegisterProvider",
            "desc": "Registers a provider to be loaded by Nexus. This method should be called before Nexus.Start is called.",
            "params": [
                {
                    "name": "prov",
                    "desc": "",
                    "lua_type": "Provider"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 432,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "Start",
            "desc": "Starts Nexus by initializing and starting all registered modules.\n\n:::warning Call Once\nCan only be called once. Calling more than once will throw an error.\nYou cannot register modules after Nexus has started.\n\n```lua\nNexus.Start({\n\tExtensionsToLoad = {\n\t\tReplicatedStorage.Shared.Extensions.PlayerLifecycles,\n\t},\n\tProvidersToLoad = {\n\t\tReplicatedStorage.Shared.Providers.MySharedProvider,\n\t\tServerScriptService.Server.Providers.MyServerProvider,\n\t},\n\tPostInitPreStartCallback = function()\n\t\tprint(\"All modules have been initialized, about to start them!\")\n\tend,\n\tDebug = true, -- Same as doing Nexus.Debug = true\n}):andThen(function()\n\tprint(\"Nexus has fully started!\")\nend):catch(warn)\n```\n:::",
            "params": [
                {
                    "name": "config",
                    "desc": "The configuration for starting Nexus.",
                    "lua_type": "StartConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "A promise that is resolved once Nexus has fully started.",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 506,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "PromiseOnStarted",
            "desc": "Returns a promise that is resolved once Nexus has fully started. This is useful for any code that\nneeds to tie into Nexus modules but is not the script that called `Start`.\n\n```lua\nNexus.PromiseOnStarted():andThen(function()\n\tlocal MyProvider = Nexus.GetProvider(\"MyModule\")\n\tMyModule:SomeMethod()\nend):catch(warn)\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 694,
                "path": "lib/nexus/src/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "StartConfig",
            "desc": "and loaded in the order they are provided.\nloaded in the order they are provided.\ninitialized and before they are started.",
            "fields": [
                {
                    "name": "ExtensionsToLoad",
                    "lua_type": "{ ModuleScript }?",
                    "desc": "A table of module scripts of extensions that will be registered"
                },
                {
                    "name": "ProvidersToLoad",
                    "lua_type": "{ ModuleScript }?",
                    "desc": "A table of module scripts of modules that will be registered and"
                },
                {
                    "name": "PostInitPreStartCallback",
                    "lua_type": "(() -> Promise)?",
                    "desc": "A callback that is called after all modules have been"
                },
                {
                    "name": "Debug",
                    "lua_type": "boolean?",
                    "desc": "Whether to log debug information."
                }
            ],
            "source": {
                "line": 92,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "Provider",
            "desc": "",
            "fields": [
                {
                    "name": "Init",
                    "lua_type": "(self: Provider) -> ()?",
                    "desc": "The method that is spawned syncronously when the provider is initialized."
                },
                {
                    "name": "Start",
                    "lua_type": "(self: Provider) -> ()?",
                    "desc": "The method that is spawned asyncronously when the provider is started."
                }
            ],
            "source": {
                "line": 105,
                "path": "lib/nexus/src/init.luau"
            }
        },
        {
            "name": "Extension",
            "desc": "Extensions allow developers to extend the functionality of modules under-the-hood.\nThis is useful for adding additional functionality to modules without modifying the provider itself.\nDevelopers can save time writing common boilerplate code by using extensions, however, extensions\ndo add a layer of abstraction. The use of extensions is optional and not required.",
            "fields": [
                {
                    "name": "BeforeInit",
                    "lua_type": "(self: Extension, provider: Provider) -> ()?",
                    "desc": "The hook that fires before each provider is initialized."
                },
                {
                    "name": "BeforeStart",
                    "lua_type": "(self: Extension, provider: Provider) -> ()?",
                    "desc": "The hook that fires before each provider is started."
                }
            ],
            "source": {
                "line": 126,
                "path": "lib/nexus/src/init.luau"
            }
        }
    ],
    "name": "Nexus",
    "desc": "Nexus is a module loading provider framework forked from Roam that is inspired by Sleitnick's [Axis\nframework](https://github.com/Sleitnick/Axis).) This module loader is barebones with the exception\nof extensions. There is no built-in networking layer or built-in state management. Nexus is designed\nto be a simple, yet powerful module loader that allows developers to easily load and manage modules\nin their game with the ability to add extensions for additional functionality.\n\nNexus collects load-elligable modules (modules that pass the predicate if one is supplied) and\ninitializes them \"syncronously\" in the order they were collected in - the order is determined\n\"randomly\" or by the table of paths provided by the developer. Once all modules are initialized,\nNexus then \"starts\" the modules \"asyncronously\" by spawning the \"Start\" method in a new thread.\n\n### NOTES\n* Nexus does not need to be required in each module.\n* All modules are guaranteed safe to access in the \"Start\" method.\n* All modules are guaranteed to be initialized before the \"Start\" method is\nspawned.\n* Providers do not have to have either the \"Init\" or \"Start\" method.\n* Providers are guaranteed to be initialized in the expected order VIA the custom\nload order or topological sorting where dependencies are actually respected.\n* The name \"Provider\", \"Service\", or \"Controller\" is not required, you decide\nwhat convention to follow when naming your modules.\n* Extensions are optional and are used to extend the functionality of modules\nunder-the-hood. They are there to save time writing common boilerplate code.\n\n### EXAMPLE USAGE\n```lua\nlocal MyProvider = {\n\tConfig = {\n\t\tName = \"MyProvider\", -- Optional, name is auto-generated.\n\t\tDependencies = {\n\t\t\t[MyOtherProvider] = true,\n\t\t},\n\t},\n}\n\nfunction MyProvider:Add(x: number, y: number): number\n\treturn x + y\nend\n\nfunction MyProvider:Init()\n\tprint(\"MyProvider initialized!\")\n\n\t-- This is 100% safe to do:\n\tprint(\"OtherProvider runtime data:\", MyOtherProvider:SomeMethod())\nend\n\nfunction MyProvider:Start()\n\tprint(\"MyProvider started!\")\n\tprint(MyProvider:Add(1, 2))\nend\n\nreturn MyProvider\n```",
    "source": {
        "line": 62,
        "path": "lib/nexus/src/init.luau"
    }
}