{"id":"hypurh/foundry","name":"foundry","scope":"hypurh","platform":"roblox","description":"This is essentially a module loader factory.","version":"0.1.4","latest":"0.1.4","versions":["0.1.3","0.1.4"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{"evaera/promise":{"version":"^4.0.0","alias":"Promise"}},"integrity":"4555592078a7fca97dfbeac1644f0ee0bbe1c539f4bc71a69ef73cd8e158bc0c","likes":0,"downloads":0,"install":"forest install hypurh/foundry","url":"https://forest.dev/p/roblox/hypurh/foundry","files":"https://api.forest.dev/ai/package/roblox/hypurh/foundry/files","readme":"# *`foundry`*\r\n\r\n> This is essentially a module loader factory.\r\n\r\n## Install\r\n\r\nAdd Foundry to your Roblox project with Wally:\r\n\r\n```toml\r\n[dependencies]\r\nFoundry = \"hypurh/foundry@0.1.4\"\r\n```\r\n\r\nThen run:\r\n\r\n```bash\r\nwally install\r\n```\r\n\r\nRequire Foundry from the generated `Packages` folder:\r\n\r\n```lua\r\nlocal Foundry = require(Packages.Foundry)\r\n```\r\n\r\n## Basic Usage\r\n\r\nCreate a Folder containing the modules you want Foundry to manage. Each module must have its `Enabled` attribute set to `true`.\r\n\r\n```lua\r\nlocal Foundry = require(Packages.Foundry)\r\n\r\nlocal modules = script.Parent.Modules\r\n\r\nlocal loader = Foundry.new({\r\n\tFolder = modules,\r\n})\r\n\r\nloader:Init()\r\nloader:YieldTillLoaded()\r\n\r\nlocal inventory = loader:Get(\"Inventory\")\r\ninventory:Refresh()\r\n```\r\n\r\n`Init()` begins loading all enabled ModuleScripts and returns the loader.\r\n\r\n`YieldTillLoaded()` yields until every enabled module has finished loading.\r\n\r\n`Get()` yields until the requested module finishes loading if it is still in the process of loading.\r\n\r\n## Module Format\r\n\r\nFoundry modules must return a table. Modules may optionally define an `Init` method, which Foundry calls after requiring the module.\r\n\r\n```lua\r\nlocal Inventory = {}\r\n\r\nfunction Inventory:Init(loader, context)\r\n\tself.Data = context.DataStore\r\n\tself.Users = loader:Get(\"Users\")\r\nend\r\n\r\nfunction Inventory:Refresh()\r\n\t-- Module implementation\r\nend\r\n\r\nreturn Inventory\r\n```\r\n\r\nA context can be passed to `Init()` and is provided to every module's `Init` method:\r\n\r\n```lua\r\nloader:Init({\r\n\tDataStore = dataStore,\r\n})\r\n```\r\n\r\nThe module's `Init` method receives:\r\n\r\n1. `self` — the module itself\r\n2. `loader` — the loader that is initializing the module\r\n3. `context` — the value passed to `loader:Init(...)`\r\n\r\nFor example:\r\n\r\n```lua\r\nfunction Inventory:Init(loader, context)\r\n\t-- self     -> Inventory\r\n\t-- loader   -> the current LoaderObject\r\n\t-- context  -> the table passed to loader:Init(...)\r\nend\r\n```\r\n\r\n## Rules\r\n\r\n* ModuleScript names must be unique within the managed Folder.\r\n* Only direct child ModuleScripts with `Enabled` set to `true` are loaded.\r\n* A module's `Init` member must be a function when present.\r\n* Circular dependencies created through `loader:Get()` raise an error.\r\n* A loader can only be initialized once.\r\n* `Get()` returns `nil` when the requested module is not registered.\r\n\r\n## API\r\n\r\n### `Foundry.new(config: { Folder: Folder }): LoaderObject`\r\n\r\nCreates and returns a new loader for `config.Folder`.\r\n\r\nThe Folder is not loaded until `Init()` is called.\r\n\r\n### `loader:Init(...): LoaderObject`\r\n\r\nInitializes the loader and begins asynchronously loading all enabled ModuleScripts.\r\n\r\nFor each loaded module, Foundry calls its optional `Init` method as:\r\n\r\n```lua\r\nmodule:Init(loader, ...)\r\n```\r\n\r\nThe arguments after `loader` are the same values passed to `loader:Init(...)`.\r\n\r\nReturns the loader.\r\n\r\n### `loader:Get(name: string): Module?`\r\n\r\nReturns the module registered under `name`.\r\n\r\nIf the module is still loading, `Get()` yields until it finishes.\r\n\r\nIf the module fails to load, the error is propagated to the caller.\r\n\r\nReturns `nil` if no enabled module with the given name is registered.\r\n\r\n`Get()` also tracks module dependencies and detects circular dependencies.\r\n\r\n### `loader:YieldTillLoaded(): ()`\r\n\r\nYields until all enabled modules have finished loading.\r\n\r\nThis waits for the loading process to complete, including modules that failed to load.\r\n","readmeTruncated":false}