{"id":"sleitnick/axis","name":"axis","scope":"sleitnick","platform":"roblox","description":"A provider framework for the Roblox ecosystem","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"bdddeaad20c308a8e36d483b9463029f69753a19a7c9be83a7d4090336a4e8e6","likes":0,"downloads":0,"install":"forest install sleitnick/axis","url":"https://forest.dev/p/roblox/sleitnick/axis","files":"https://api.forest.dev/ai/package/roblox/sleitnick/axis/files","readme":"[![CI](https://github.com/Sleitnick/Axis/actions/workflows/ci.yaml/badge.svg)](https://github.com/Sleitnick/Axis/actions/workflows/ci.yaml)\n[![CD](https://github.com/Sleitnick/Axis/actions/workflows/cd.yaml/badge.svg)](https://github.com/Sleitnick/Axis/actions/workflows/cd.yaml)\n\n# Axis\n\nAxis is a provider framework for the Roblox ecosystem.\n\n## Provider Example\n\nProviders are simply tables with a name and a couple lifecycle methods.\n\n```lua\nlocal MyProvider = {}\n\nfunction MyProvider:AxisPrepare()\n\tprint(\"Prepare the provider\")\nend\n\nfunction MyProvider:AxisStarted()\n\tprint(\"Started\")\nend\n\nreturn MyProvider\n```\n\nProviders must be explicitly added into Axis via `Axis:AddProvider()`. Once all providers are added, `Axis:Start()` will kick off the lifecycle methods of the providers.\n\nA script to bootstrap Axis might look like this:\n\n```lua\nlocal Axis = require(somewhere.Axis)\nlocal MyProvider = require(somewhere.MyProvider)\n\nAxis:AddProvider(MyProvider)\n\nAxis:Start()\n```\n\n## Using multiple providers\n\nBecause providers are just tables, it is easy for one provider to use another. Simply get a reference to the other provider (e.g. requiring its ModuleScript) and then access it after AxisStarted has fired. For example:\n\n```lua\nlocal MyProvider = require(somewhere.MyProvider) -- Grab the other provider\n\nlocal AnotherProvider = {}\n\nfunction AnotherProvider:AxisPrepare()\n\t-- Other providers are NOT safe to use here, because there's no guarantee\n\t-- that they have all been prepared yet. Wait until AxisStarted.\nend\n\nfunction AnotherProvider:AxisStarted()\n\t-- Other providers are safe to use once the AxisStarted method fires.\n\tMyProvider:DoSomething()\nend\n```\n\n## Extensions\n\nAxis providers are very simple. In order to expand the possibilities of providers, extensions can be added. Extensions can be added at the Axis level (e.g. apply to all providers) or at the individual provider level.\n\nExtensions allow code to run for a provider before certain lifecycle methods. This can be used to transform, inject, create networking, or do whatever is required to set up the providers for certain use-cases.\n\nBelow is an example of a simple logger extension:\n\n```lua\nlocal Axis = require(somewhere.Axis)\n\nAxis:AddExtension {\n\t-- Assumes that a custom 'Name' field has been added to all providers:\n\tBeforePrepare = function(provider)\n\t\tprint(\"Preparing provider\", provider.Name)\n\tend,\n\tBeforeStarted = function(provider)\n\t\tprint(\"Starting provider\", provider.Name)\n\tend,\n}\n```\n\nHere is a similar example, but on a provider:\n\n```lua\nlocal MyProvider = {}\n\nMyProvider.AxisExtensions = {\n\t{\n\t\tBeforePrepare = function(provider)\n\t\t\tprint(\"BeforePrepare MyProvider\")\n\t\tend,\n\t\tBeforeStarted = function(provider)\n\t\t\tprint(\"BeforeStarted MyProvider\")\n\t\tend,\n\t},\n}\n```\n\nExtensions will run in the order of which they were added. Axis-level extensions run before provider-level extensions.\n\n## Memory categories\n\nBecause Axis providers are started from one source, the default memory label within the Developer Console will appear the same for all providers. To solve this, Axis will automatically assign a memory category if the `AxisName` field is set.\n\n```lua\nlocal MyProvider = {}\n\nMyProvider.AxisName = \"MyProvider\"\n```\n\nWhen MyProvider is prepared/started, any memory usage will show up within the MyProvider label in the Developer Console memory section.\n\nIf the script being used to bootstrap Axis is grabbing each provider from its own ModuleScript, then a simple way to inject this is to set the `AxisName` property to the ModuleScript's name. For example:\n\n```lua\nfor _,module in ipairs(somewhere.MyProviderModules:GetChildren()) do\n\tlocal provider = require(module)\n\tprovider.AxisName = module.Name -- Inject name\n\tAxis:AddProvider(provider)\nend\n```\n","readmeTruncated":false}