{"id":"averyark/craftsman-lifecycle","name":"craftsman-lifecycle","scope":"averyark","platform":"roblox","description":"The Craftsman module loader: dependency-ordered Init, Start and Stop for singleton modules.","version":"2.0.0","latest":"2.0.0","versions":["1.0.0","1.0.1","2.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":["The package archive does not include its license text; the license is declared in its manifest metadata."],"licenseVerified":false,"dependencies":{"averyark/keeper":{"version":"^1.10.2","alias":"Keeper"},"howmanysmall/typed-promise":{"version":"^4.0.6","alias":"Promise"}},"integrity":"955421e615b15ade192293c5189ac3cd6c485589616561dffd62fdefc8bd5aa2","likes":0,"downloads":0,"install":"forest install averyark/craftsman-lifecycle","url":"https://forest.dev/p/roblox/averyark/craftsman-lifecycle","files":"https://api.forest.dev/ai/package/roblox/averyark/craftsman-lifecycle/files","readme":"# Craftsman Lifecycle\n\nThe Craftsman module loader. Point it at a folder, and it requires every ModuleScript in it\nand in the folders under it, runs each module's `Init` and then its `Start` in dependency\norder, and later runs `Stop` in reverse. A ModuleScript's own children are never loaded.\n\nIt is `Craftsman.Component` in Craftsman Kit 0.9.0, moved out and fixed. It lives in its own\npackage so a game can use the lifecycle without Craftsman Kit, and Craftsman Kit without the\nlifecycle.\n\n```toml\n# wally.toml\n[dependencies]\nLifecycle = \"averyark/craftsman-lifecycle@2.0.0\"\n```\n\nInstall it with [Wally](https://wally.run). It requires its dependencies as siblings in Wally's\nlayout (`./Promise`), the same way Craftsman Kit and Craftsman Control do, so the three install\ninto one `Packages` folder. 1.0.0 required Ember's layout instead and cannot be installed by\nWally.\n\n## A module\n\n```lua\nlocal Inventory = require(\"./Inventory\")\n\nlocal Shop = {\n\tDependencies = { Inventory },\n}\n\nfunction Shop:Init()\n\t-- Synchronous. Set up state. Inventory:Init has already run.\nend\n\nfunction Shop:Start()\n\t-- Connect events and loops. Inventory:Start has already finished.\n\tself.Keeper:Add(workspace.ChildAdded:Connect(function() end))\nend\n\nfunction Shop:Stop()\n\t-- Runs before Inventory:Stop. Shop's Keeper is destroyed after this returns.\nend\n\nreturn Shop\n```\n\n`Dependencies` holds the module tables themselves, not their names. `Init`, `Start` and\n`Stop` are all optional. A module that is not a table is required and registered, and is\notherwise left alone.\n\n## Which modules are loaded\n\nThe loader walks Folders, and stops at a ModuleScript. A ModuleScript is one singleton, and\nanything inside it, ModuleScripts and Folders alike, belongs to it and is never looked at.\n\n```\nServerScriptService.Features   Folder, walked\n  Combat                       ModuleScript, loaded\n    Replication                ModuleScript, Combat's own, not loaded\n  Shared                       Folder, walked\n    Wind                       ModuleScript, loaded\n```\n\nSo a feature written as a folder with an `init.luau` is one module to the loader. Its parts\nkeep plain functions with whatever arguments they need, and its `Start` calls them in order.\nTwo features may each have a part named `Types` without clashing. A singleton that has to be\nloaded on its own belongs in a Folder, not inside another ModuleScript.\n\nThis is `TopLevelModulesOnly`, which is `true` by default and set per loader, like\n`HangWarningSeconds`. Set it to `false` to load every ModuleScript under the folder,\nincluding ones inside other ModuleScripts, as 1.0.1 did:\n\n```lua\nLifecycle.TopLevelModulesOnly = false\nLifecycle:LoadModulesAsync(folder):await()\n```\n\n## Craftsman Control features\n\nThe loader answers whether a module's code is loaded and wired up, once at boot. Craftsman\nControl answers whether a declared feature should be running, at any time. A module for a\nfeature declared in Control registers with Control in `Start` and does its work in the\nhandler, so switching the feature off in the console tears it down:\n\n```lua\nlocal Grass = {}\n\nfunction Grass:Start()\n\tself.Keeper:Add(Definitions:OnActivate(function(keeper)\n\t\t-- Build. Everything made here goes into keeper, which Control\n\t\t-- cleans every time the feature is switched off.\n\tend))\nend\n```\n\nThe module's own Keeper holds the registration, so `StopModulesAsync` unregisters it and\ncleans whatever the feature had running.\n\n## Booting\n\n```lua\nlocal ServerScriptService = game:GetService(\"ServerScriptService\")\nlocal Lifecycle = require(\"@game/ReplicatedStorage/Packages/Lifecycle\")\n\nLifecycle:LoadModulesAsync(ServerScriptService.Craftsman.Modules):await()\n```\n\n`Lifecycle` is itself a loader, so a game can use it directly. `Lifecycle.Loader()` makes an\nindependent one with its own modules, which is what a test uses so that stopping its fixtures\ndoes not stop the game.\n\nLoading more than one folder into the same loader is supported: a module in a later folder may\ndepend on a module from an earlier one, and one `StopModulesAsync` stops them all.\n\n## What it guarantees\n\n| Phase | Order | When something fails |\n| :--- | :--- | :--- |\n| require | Every module, concurrently, before any `Init` | The module is reported, and nothing it would have run runs. The rest still load. |\n| `Init` | One at a time, each after every module it depends on | Its dependents skip `Init` and `Start`. Unrelated modules carry on. |\n| `Start` | Concurrently, each after every module it depends on has finished `Start` | Its dependents skip `Start`. |\n| `Stop` | Each after every module that depends on it has stopped | Reported. Its Keeper is still destroyed. |\n\n`LoadModulesAsync` resolves once every `Start` has finished or failed. It rejects, before\nrunning any `Init`, when two modules share a name or when modules depend on each other in a\ncycle. Name clashes are refused before anything is required.\n\nEvery loaded table gets a `Keeper` (from `averyark/keeper`) unless it already has one, and\nthat Keeper is destroyed after the module's `Stop`.\n\n### Warnings\n\n- **`Init` yielded.** `Init` must not yield. The loader waits for it anyway, so the order\n  still holds, and names the module so the waiting can move into `Start`.\n- **`Start` or `Stop` has not finished.** After `HangWarningSeconds` (10 by default, set per\n  loader), a `Start` or `Stop` that is still running is reported along with the modules\n  waiting on it.\n\n## Skipping a folder\n\nEverything under an instance with the `CraftsmanLifecycleIgnore` attribute set to `true` is\nskipped, as is any ModuleScript whose name ends in `.spec`. A ModuleScript's children are\nskipped without it. With Rojo, mark a folder with an\n`init.meta.json`:\n\n```json\n{\n  \"attributes\": {\n    \"CraftsmanLifecycleIgnore\": true\n  }\n}\n```\n\nAnything that has to be loaded some other way belongs outside the loaded folder or under an\nignored one. That includes Craftsman Control's `ServerScriptService.Craftsman.Control` and\n`ServerScriptService.Craftsman.Verify`: Control opens its stores when `Stores` is required,\nbecause a Luau Execution session loads the place without running any Script, so no `Init` or\n`Start` would ever run there.\n\n## Moving from `Craftsman.Component`\n\n| Before | After |\n| :--- | :--- |\n| `Craftsman.Component:LoadModulesAsync(folder)` | `Lifecycle:LoadModulesAsync(folder)` |\n| `Craftsman.Component:StopModulesAsync()` | `Lifecycle:StopModulesAsync()` |\n| `Craftsman.Component.new(module)` | `Lifecycle.new(module)` |\n| A scratch loader via `setmetatable({ Modules = {}, LoadedModules = {} }, { __index = Craftsman.Component })` | `Lifecycle.Loader()` |\n| `Config.MODULE_LOAD_ORDER` | `Dependencies` on the modules themselves |\n\n`CHANGELOG.md` lists every behaviour that changed.\n\n## Development\n\n```\nrokit install\nwally install\nlune setup\nlune run test\n./scripts/analyze.ps1\nrojo build test.project.json -o Lifecycle.rbxl\n```\n\n`lune run test` runs the loader against fake instances. The place built from\n`test.project.json` runs the ordering, ignore, nesting and Stop checks over real ModuleScripts, and its\n`Smoke` script prints the result to the server output.\n","readmeTruncated":false}