event_hub

-module(event_hub).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch]).
-define(FILEPATH, "src/event_hub.gleam").
-export([new/1, notify/2, subscribe/2]).
-export_type([hub/1]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " The `event_hub` module provides a way to manage and notify subscribers about events.\n"
    " It supports stateless observers, allowing functions to be registered and invoked in parallel when an event occurs.\n"
    "\n"
    " ## Examples\n"
    "\n"
    " ### Simple Observer\n"
    " ```gleam\n"
    " import gleam/io\n"
    " import event_hub\n"
    " \n"
    " pub fn main() {\n"
    "   use hub <- event_hub.new()\n"
    " \n"
    "   let unsubscribe =\n"
    "     event_hub.subscribe(hub, fn(value) {\n"
    "       io.println(\"Received value: \" <> value)\n"
    "     })\n"
    " \n"
    "   event_hub.notify(hub, \"Hello, world!\")\n"
    "   unsubscribe()\n"
    "   event_hub.notify(hub, \"This won't be received\")\n"
    " }\n"
    " ```\n"
).

-type hub(DTM) :: any() | {gleam_phantom, DTM}.

-file("src/event_hub.gleam", 77).
?DOC(
    " Creates a new stateless observer hub, executes the given context with the hub, and stops the hub afterward.\n"
    "\n"
    " ## Parameters\n"
    " - `context`: A function that takes the created `Hub` and returns a result.\n"
    "\n"
    " ## Returns\n"
    " The result of executing the context function.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub\n"
    " \n"
    " pub fn example() {\n"
    "   event_hub.new(fn(hub) { event_hub.notify(hub, \"event\") })\n"
    " }\n"
    " ```\n"
).
-spec new(fun((hub(any())) -> DUB)) -> DUB.
new(Context) ->
    Hub = event_hub_ffi:start_stateless(),
    Result = Context(Hub),
    event_hub_ffi:stop_stateless(Hub),
    Result.

-file("src/event_hub.gleam", 101).
?DOC(
    " Notifies all subscribers of the hub that an event has occurred with the given value.\n"
    " These notifications occur in parallel but `notify` waits for all of them to complete.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub` to notify.\n"
    " - `value`: The value to send to all subscribers.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub\n"
    "\n"
    " pub fn example(hub: event_hub.Hub(String)) {\n"
    "   event_hub.notify(hub, \"event\")\n"
    " }\n"
    " ```\n"
).
-spec notify(hub(DUC), DUC) -> nil.
notify(Hub, Value) ->
    event_hub_ffi:invoke_stateless(Hub, Value).

-file("src/event_hub.gleam", 129).
?DOC(
    " Adds a callback to the hub and returns an unsubscribe function.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub` to add the callback to.\n"
    " - `callback`: The callback function to add.\n"
    "\n"
    " ## Returns\n"
    " An `Unsubscribe` function that can be called to remove the callback.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import gleam/io\n"
    " import event_hub\n"
    " \n"
    " pub fn example(hub: event_hub.Hub(String)) {\n"
    "   let unsubscribe =\n"
    "     event_hub.subscribe(hub, fn(value) {\n"
    "       io.println(\"Received value: \" <> value)\n"
    "     })\n"
    " \n"
    "   // To unsubscribe\n"
    "   unsubscribe()\n"
    " }\n"
    " ```\n"
).
-spec subscribe(hub(DUE), fun((DUE) -> nil)) -> fun(() -> nil).
subscribe(Hub, Callback) ->
    Index = event_hub_ffi:add_stateless(Hub, Callback),
    fun() -> event_hub_ffi:remove_stateless(Hub, Index) end.