{"id":"mark-marks/sapphire","name":"sapphire","scope":"mark-marks","platform":"roblox","description":"Mirrored from the Wally registry.","version":"0.1.3","latest":"0.1.3","versions":["0.1.0","0.1.1","0.1.2","0.1.3"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"red-blox/signal":{"version":"^2.0.2","alias":"signal"},"red-blox/spawn":{"version":"^1.1.0","alias":"spawn"}},"integrity":"e926352f9051c516e1262a2ce33ee7cdda8402076aafc2f32a7e636050ca51ac","likes":0,"downloads":0,"install":"forest install mark-marks/sapphire","url":"https://forest.dev/p/roblox/mark-marks/sapphire","files":"https://api.forest.dev/ai/package/roblox/mark-marks/sapphire/files","readme":"# sapphire\r\nA lightweight module loader or a batteries included framework\r\n\r\n# API\r\n\r\n## Types\r\n\r\n### SignalNode<T...>\r\n```luau\r\nPRIVATE type SignalNode<T...> = {\r\n    Next: SignalNode<T...>?,\r\n    Callback: (T...) -> (),\r\n}\r\n```\r\n\r\n### Signal<T...>\r\n[red-blox/signal](https://github.com/red-blox/Util/blob/main/libs/Signal/Signal.luau) signal type.\r\n```luau\r\ntype Signal<T...> = {\r\n    Root: SignalNode<T...>?,\r\n\r\n    Connect: (self: Signal<T...>, Callback: (T...) -> ()) -> () -> (),\r\n    Wait: (self: Signal<T...>) -> T...,\r\n    Once: (self: Signal<T...>, Callback: (T...) -> ()) -> (),\r\n    Fire: (self: Signal<T...>, T...) -> (),\r\n    DisconnectAll: (self: Signal<T...>) -> (),\r\n}\r\n```\r\n\r\n### singleton\r\nRegisterable singleton.\r\n```luau\r\ntype singleton = {\r\n    --- The name of the ModuleScript which holds the singleton. Overwritten by sapphire.\r\n    identifier: string?,\r\n    --- Any singleton without priority will automatically have its priority set to 1, where 1 is the lowest priority.\r\n    priority: number?,\r\n\r\n    --- Initializes the singleton.\r\n    --- Called prior to all singletons being started and their lifecycles ran.\r\n    --- `.start()` should be preferred unless you need `.init()`'s unique behaviour.\r\n    init: (() -> ())?,\r\n    --- Starts the singleton.\r\n    --- Called after all singletons are initialized, but before other lifecycles are ran.\r\n    --- This is called in another thread and can yield.\r\n    start: (() -> ())?,\r\n\r\n    [string]: any,\r\n}\r\n```\r\n\r\n### extension\r\nExtensions are in their simplest form singletons that are instantly ran.\r\n```luau\r\ntype extension = {\r\n    --- What to identify the extension by.\r\n    identifier: string,\r\n\r\n    --- Starts the extension. This is called prior to any methods being registered.\r\n    extension: (sapphire: sapphire) -> (),\r\n\r\n    --- Registers the given methods within sapphire.\r\n    methods: { [string]: (singleton: singleton) -> () },\r\n\r\n    [string]: any,\r\n}\r\n```\r\n\r\n### sapphire\r\n```luau\r\ntype sapphire = {\r\n    signals = {\r\n        on_extension_registerd: Signal<extension>,\r\n        on_singleton_registered: Signal<singleton>,\r\n        on_singleton_initialized: Signal<singleton>,\r\n        on_singleton_started: Signal<singleton>,\r\n    },\r\n\r\n    _singletons: { [string]: singleton },\r\n    _extensions: { [string]: extension },\r\n    _extra_methods: { [string]: (singleton: singleton) -> () },\r\n\r\n    use: (self: sapphire, extension: extension) -> sapphire,\r\n    register_singleton: (self: sapphire, mod: ModuleScript) -> sapphire,\r\n    register_singletons: (self: sapphire, container: Folder) -> sapphire,\r\n    start: (self: sapphire) -> (),\r\n}\r\n```\r\n\r\n## Registered methods\r\n\r\n### .init()\r\n> [!TIP]\r\n> `.init()` and `.start()` are optional, singletons can exist without them.\r\nCalled before singletons are started.\r\nYielding here yields everything else.\r\n```luau\r\n() -> ()\r\n```\r\n\r\n### .start()\r\n> [!TIP]\r\n> `.init()` and `.start()` are optional, singletons can exist without them.\r\nSpawned with `task.spawn` after all singletons are initialized.\r\n```luau\r\n() -> ()\r\n```\r\n\r\n## Note\r\n> [!NOTE]\r\n> Sapphire returns a function which is used to construct it.\r\n> ```luau\r\n> () -> sapphire\r\n> ```\r\n> All of the following exports and function definitions are of what's returned by the constructor.\r\n\r\n## Exports\r\n\r\n### .signals\r\nList of signals ran during certain stages.\r\n```luau\r\n{\r\n    -- Runs after an extension is registered.\r\n    on_extension_registered: Signal<extension>,\r\n    --- Runs after a singleton is registered.\r\n    on_singleton_registered: Signal<singleton>,\r\n    --- Runs after a singleton is initialized.\r\n    on_singleton_initialized: Signal<singleton>,\r\n    --- Runs after a singleton is started.\r\n    on_singleton_started: Signal<singleton>,\r\n}\r\n```\r\n\r\n### ._singletons\r\nReadonly map of identifiers to registered singletons.\r\n> [!WARNING]\r\n> Use `:register_singleton()` or `:register_singletons()` instead of editing directly.\r\n\r\n### ._extensions\r\nReadonly map of identifiers to registered extensions.\r\n> [!WARNING]\r\n> Use `:use()` instead of editing directly.\r\n\r\n### .extra_methods\r\nReadonly array of registered extended methods.\r\n> [!WARNING]\r\n> Use an extension instead of editing directly.\r\n\r\n## Functions\r\n\r\n### :use()\r\nUses an extension.\r\n```luau\r\n(\r\n    self: sapphire,\r\n    extension: extension\r\n) -> sapphire\r\n```\r\n\r\n### :register_singleton()\r\nRegisters a singleton.\r\n```luau\r\n(\r\n    self: sapphire,\r\n    mod: ModuleScript\r\n) -> sapphire\r\n```\r\n\r\n### :register_singletons()\r\nRegisters multiple singletons parented to a container - wrapper around `:register_singleton()`.\r\n```luau\r\n(\r\n    self: sapphire,\r\n    container: Folder\r\n) -> sapphire\r\n```\r\n\r\n### :start()\r\nStarts all singletons.\r\n```luau\r\n(\r\n    self: sapphire\r\n) -> ()\r\n```\r\n","readmeTruncated":false}