event_hub

1.0.2
Event-Hub is a Gleam library that provides simple hubs with publishers and subscribers for event-driven observers. It supports asynchronous message handling and event notifications, decoupling components efficiently. It works on Erlang and JavaScript.
HexDocs
Current section
Files
Jump to
Readme 3 Versions 1 Dependency Dependants Files Activity
event_hub src event_hub@topic.erl
Raw
src/event_hub@topic.erl

-module(event_hub@topic).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch]).
-define(FILEPATH, "src/event_hub/topic.gleam").
-export([new_n/1, notify_n/3, subscribe_n/3, new/1, notify/3, subscribe/3, new2/1, notify2/4, subscribe2/4, new3/1, notify3/5, subscribe3/5, new4/1, notify4/6, subscribe4/6]).
-export_type([hub_n/1, hub/1, hub2/1, hub3/1, hub4/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 `topic` module provides a way to manage and notify subscribers about events based on hierarchical topics.\n"
    " It supports creating observers that can filter events using one or more levels of topics, allowing more fine-grained\n"
    " control over event handling.\n"
    "\n"
    " ## Examples\n"
    "\n"
    " ### Single-Level Topic-Based Observer\n"
    " ```gleam\n"
    " import gleam/io\n"
    " import event_hub/topic\n"
    " \n"
    " pub fn main() {\n"
    "   use hub <- topic.new()\n"
    "   let unsubscribe_a =\n"
    "     topic.subscribe(hub, [\"a\"], fn(value) {\n"
    "       io.println(\"A received: \" <> value)\n"
    "     })\n"
    " \n"
    "   let unsubscribe_b =\n"
    "     topic.subscribe(hub, [\"b\"], fn(value) {\n"
    "       io.println(\"B received: \" <> value)\n"
    "     })\n"
    " \n"
    "   topic.notify(hub, [\"a\"], \"Message for A\")\n"
    "   topic.notify(hub, [\"b\"], \"Message for B\")\n"
    " \n"
    "   unsubscribe_a()\n"
    "   unsubscribe_b()\n"
    " }\n"
    " ```\n"
).

-type hub_n(EGU) :: any() | {gleam_phantom, EGU}.

-opaque hub(EGV) :: {hub, hub_n(EGV)}.

-opaque hub2(EGW) :: {hub2, hub_n(EGW)}.

-opaque hub3(EGX) :: {hub3, hub_n(EGX)}.

-opaque hub4(EGY) :: {hub4, hub_n(EGY)}.

-file("src/event_hub/topic.gleam", 89).
?DOC(
    " Creates a new topic-based event hub, executes the given context with the hub, and stops the hub afterward.\n"
    "\n"
    " ## Parameters\n"
    " - `context`: A function that takes the created `HubN` and returns a result.\n"
    "\n"
    " ## Returns\n"
    " The result of executing the context function.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example() {\n"
    "   topic.new(fn(hub) {\n"
    "     // Use the hub\n"
    "     Nil\n"
    "   })\n"
    " }\n"
    " ```\n"
).
-spec new_n(fun((hub_n(any())) -> EHQ)) -> EHQ.
new_n(Context) ->
    Hub = event_hub_ffi:start_topic_based(),
    Result = Context(Hub),
    event_hub_ffi:stop_topic_based(Hub),
    Result.

-file("src/event_hub/topic.gleam", 114).
?DOC(
    " Notifies subscribers of the hub about an event with the given topics and value.\n"
    " These notifications occur in parallel but `notify_n` waits for all of them to complete.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `HubN` to notify.\n"
    " - `topics`: The list of topics associated with the event.\n"
    " - `value`: The value to send to all subscribers.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example(hub: topic.HubN(String)) {\n"
    "   topic.notify_n(hub, [[\"topic1\"]], \"event\")\n"
    " }\n"
    " ```\n"
).
-spec notify_n(hub_n(EHR), list(list(binary())), EHR) -> nil.
notify_n(Hub, Topics, Value) ->
    event_hub_ffi:invoke_topic_based(Hub, Topics, Value).

-file("src/event_hub/topic.gleam", 148).
?DOC(
    " Subscribes to specific topics and returns an unsubscribe function.\n"
    " The callback will be invoked only if the event topics match the subscription topics.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `HubN` to add the callback to.\n"
    " - `topics`: The list of topics to subscribe to.\n"
    " - `callback`: The callback function to invoke when an event with matching topics occurs.\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/topic\n"
    " \n"
    " pub fn example(hub: topic.HubN(String)) {\n"
    "   let unsubscribe =\n"
    "     topic.subscribe_n(hub, [[\"topic1\"]], fn(value) {\n"
    "       io.println(\"Received value: \" <> value)\n"
    "     })\n"
    " \n"
    "   // To unsubscribe\n"
    "   unsubscribe()\n"
    " }\n"
    " ```\n"
).
-spec subscribe_n(hub_n(EHV), list(list(binary())), fun((EHV) -> nil)) -> fun(() -> nil).
subscribe_n(Hub, Topics, Callback) ->
    Index = event_hub_ffi:add_topic_based(Hub, Topics, Callback),
    fun() -> event_hub_ffi:remove_topic_based(Hub, Index) end.

-file("src/event_hub/topic.gleam", 181).
?DOC(
    " Creates a new single-level topic-based event hub, executes the given context with the hub.\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/topic\n"
    "\n"
    " pub fn example() {\n"
    "   topic.new(fn(hub) {\n"
    "     // Use the hub\n"
    "     Nil\n"
    "   })\n"
    " }\n"
    " ```\n"
).
-spec new(fun((hub(any())) -> EIC)) -> EIC.
new(Context) ->
    new_n(fun(Hub) -> Context({hub, Hub}) end).

-file("src/event_hub/topic.gleam", 201).
?DOC(
    " Notifies subscribers of the hub about an event with the given single-level topics and value.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub` to notify.\n"
    " - `topics`: The list of topics associated with the event.\n"
    " - `value`: The value to send to all subscribers.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example(hub: topic.Hub(String)) {\n"
    "   topic.notify(hub, [\"topic1\"], \"event\")\n"
    " }\n"
    " ```\n"
).
-spec notify(hub(EID), list(binary()), EID) -> nil.
notify(Hub, Topics, Value) ->
    notify_n(erlang:element(2, Hub), [Topics], Value).

-file("src/event_hub/topic.gleam", 234).
?DOC(
    " Subscribes to specific single-level topics and returns an unsubscribe function.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub` to add the callback to.\n"
    " - `topics`: The list of topics to subscribe to.\n"
    " - `callback`: The callback function to invoke when an event with matching topics occurs.\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/topic\n"
    " \n"
    " pub fn example(hub: topic.Hub(String)) {\n"
    "   let unsubscribe =\n"
    "     topic.subscribe(hub, [\"topic1\"], fn(value) {\n"
    "       io.println(\"Received value: \" <> value)\n"
    "     })\n"
    " \n"
    "   // To unsubscribe\n"
    "   unsubscribe()\n"
    " }\n"
    " ```\n"
).
-spec subscribe(hub(EIG), list(binary()), fun((EIG) -> nil)) -> fun(() -> nil).
subscribe(Hub, Topics, Callback) ->
    subscribe_n(erlang:element(2, Hub), [Topics], Callback).

-file("src/event_hub/topic.gleam", 266).
?DOC(
    " Creates a new two-level topic-based event hub, executes the given context with the hub.\n"
    "\n"
    " ## Parameters\n"
    " - `context`: A function that takes the created `Hub2` and returns a result.\n"
    "\n"
    " ## Returns\n"
    " The result of executing the context function.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example() {\n"
    "   topic.new2(fn(hub) {\n"
    "     // Use the hub\n"
    "     Nil\n"
    "   })\n"
    " }\n"
    " ```\n"
).
-spec new2(fun((hub2(any())) -> EIM)) -> EIM.
new2(Context) ->
    new_n(fun(Hub) -> Context({hub2, Hub}) end).

-file("src/event_hub/topic.gleam", 287).
?DOC(
    " Notifies subscribers of the hub about an event with two levels of topics and a value.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub2` to notify.\n"
    " - `topics1`: The first level of topics associated with the event.\n"
    " - `topics2`: The second level of topics associated with the event.\n"
    " - `value`: The value to send to all subscribers.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example(hub: topic.Hub2(String)) {\n"
    "   topic.notify2(hub, [\"topic1\"], [\"subtopic1\"], \"event\")\n"
    " }\n"
    " ```\n"
).
-spec notify2(hub2(EIN), list(binary()), list(binary()), EIN) -> nil.
notify2(Hub, Topics1, Topics2, Value) ->
    notify_n(erlang:element(2, Hub), [Topics1, Topics2], Value).

-file("src/event_hub/topic.gleam", 322).
?DOC(
    " Subscribes to specific two-level topics and returns an unsubscribe function.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub2` to add the callback to.\n"
    " - `topics1`: The first level of topics to subscribe to.\n"
    " - `topics2`: The second level of topics to subscribe to.\n"
    " - `callback`: The callback function to invoke when an event with matching topics occurs.\n"
    "\n"
    " ## Returns\n"
    " An `Unsubscribe` function that can be called to remove the callback.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    " import gleam/io\n"
    " \n"
    " pub fn example(hub: topic.Hub2(String)) {\n"
    "   let unsubscribe =\n"
    "     topic.subscribe2(hub, [\"topic1\"], [\"subtopic1\"], fn(value) {\n"
    "       io.println(\"Received value: \" <> value)\n"
    "     })\n"
    " \n"
    "   // To unsubscribe\n"
    "   unsubscribe()\n"
    " }\n"
    " ```\n"
).
-spec subscribe2(hub2(EIR), list(binary()), list(binary()), fun((EIR) -> nil)) -> fun(() -> nil).
subscribe2(Hub, Topics1, Topics2, Callback) ->
    subscribe_n(erlang:element(2, Hub), [Topics1, Topics2], Callback).

-file("src/event_hub/topic.gleam", 355).
?DOC(
    " Creates a new three-level topic-based event hub, executes the given context with the hub.\n"
    "\n"
    " ## Parameters\n"
    " - `context`: A function that takes the created `Hub3` and returns a result.\n"
    "\n"
    " ## Returns\n"
    " The result of executing the context function.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example() {\n"
    "   topic.new3(fn(hub) {\n"
    "     // Use the hub\n"
    "     Nil\n"
    "   })\n"
    " }\n"
    " ```\n"
).
-spec new3(fun((hub3(any())) -> EIY)) -> EIY.
new3(Context) ->
    new_n(fun(Hub) -> Context({hub3, Hub}) end).

-file("src/event_hub/topic.gleam", 377).
?DOC(
    " Notifies subscribers of the hub about an event with three levels of topics and a value.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub3` to notify.\n"
    " - `topics1`: The first level of topics associated with the event.\n"
    " - `topics2`: The second level of topics associated with the event.\n"
    " - `topics3`: The third level of topics associated with the event.\n"
    " - `value`: The value to send to all subscribers.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example(hub: topic.Hub3(String)) {\n"
    "   topic.notify3(hub, [\"topic1\"], [\"subtopic1\"], [\"subsubtopic1\"], \"event\")\n"
    " }\n"
    " ```\n"
).
-spec notify3(hub3(EIZ), list(binary()), list(binary()), list(binary()), EIZ) -> nil.
notify3(Hub, Topics1, Topics2, Topics3, Value) ->
    notify_n(erlang:element(2, Hub), [Topics1, Topics2, Topics3], Value).

-file("src/event_hub/topic.gleam", 418).
?DOC(
    " Subscribes to specific three-level topics and returns an unsubscribe function.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub3` to add the callback to.\n"
    " - `topics1`: The first level of topics to subscribe to.\n"
    " - `topics2`: The second level of topics to subscribe to.\n"
    " - `topics3`: The third level of topics to subscribe to.\n"
    " - `callback`: The callback function to invoke when an event with matching topics occurs.\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/topic\n"
    " \n"
    " pub fn example(hub: topic.Hub3(String)) {\n"
    "   let unsubscribe =\n"
    "     topic.subscribe3(\n"
    "       hub,\n"
    "       [\"topic1\"],\n"
    "       [\"subtopic1\"],\n"
    "       [\"subsubtopic1\"],\n"
    "       fn(value) { io.println(\"Received value: \" <> value) },\n"
    "     )\n"
    " \n"
    "   // To unsubscribe\n"
    "   unsubscribe()\n"
    " }\n"
    " ```\n"
).
-spec subscribe3(
    hub3(EJE),
    list(binary()),
    list(binary()),
    list(binary()),
    fun((EJE) -> nil)
) -> fun(() -> nil).
subscribe3(Hub, Topics1, Topics2, Topics3, Callback) ->
    subscribe_n(erlang:element(2, Hub), [Topics1, Topics2, Topics3], Callback).

-file("src/event_hub/topic.gleam", 452).
?DOC(
    " Creates a new four-level topic-based event hub, executes the given context with the hub.\n"
    "\n"
    " ## Parameters\n"
    " - `context`: A function that takes the created `Hub4` and returns a result.\n"
    "\n"
    " ## Returns\n"
    " The result of executing the context function.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    "\n"
    " pub fn example() {\n"
    "   topic.new4(fn(hub) {\n"
    "     // Use the hub\n"
    "     Nil\n"
    "   })\n"
    " }\n"
    " ```\n"
).
-spec new4(fun((hub4(any())) -> EJM)) -> EJM.
new4(Context) ->
    new_n(fun(Hub) -> Context({hub4, Hub}) end).

-file("src/event_hub/topic.gleam", 482).
?DOC(
    " Notifies subscribers of the hub about an event with four levels of topics and a value.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub4` to notify.\n"
    " - `topics1`: The first level of topics associated with the event.\n"
    " - `topics2`: The second level of topics associated with the event.\n"
    " - `topics3`: The third level of topics associated with the event.\n"
    " - `topics4`: The fourth level of topics associated with the event.\n"
    " - `value`: The value to send to all subscribers.\n"
    "\n"
    " ## Example\n"
    " ```gleam\n"
    " import event_hub/topic\n"
    " \n"
    " pub fn example(hub: topic.Hub4(String)) {\n"
    "   topic.notify4(\n"
    "     hub,\n"
    "     [\"topic1\"],\n"
    "     [\"subtopic1\"],\n"
    "     [\"subsubtopic1\"],\n"
    "     [\"subsubsubtopic1\"],\n"
    "     \"event\",\n"
    "   )\n"
    " }\n"
    " ```\n"
).
-spec notify4(
    hub4(EJN),
    list(binary()),
    list(binary()),
    list(binary()),
    list(binary()),
    EJN
) -> nil.
notify4(Hub, Topics1, Topics2, Topics3, Topics4, Value) ->
    notify_n(
        erlang:element(2, Hub),
        [Topics1, Topics2, Topics3, Topics4],
        Value
    ).

-file("src/event_hub/topic.gleam", 526).
?DOC(
    " Subscribes to specific four-level topics and returns an unsubscribe function.\n"
    "\n"
    " ## Parameters\n"
    " - `hub`: The `Hub4` to add the callback to.\n"
    " - `topics1`: The first level of topics to subscribe to.\n"
    " - `topics2`: The second level of topics to subscribe to.\n"
    " - `topics3`: The third level of topics to subscribe to.\n"
    " - `topics4`: The fourth level of topics to subscribe to.\n"
    " - `callback`: The callback function to invoke when an event with matching topics occurs.\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/topic\n"
    " \n"
    " pub fn example(hub: topic.Hub4(String)) {\n"
    "   let unsubscribe =\n"
    "     topic.subscribe4(\n"
    "       hub,\n"
    "       [\"topic1\"],\n"
    "       [\"subtopic1\"],\n"
    "       [\"subsubtopic1\"],\n"
    "       [\"subsubsubtopic1\"],\n"
    "       fn(value) { io.println(\"Received value: \" <> value) },\n"
    "     )\n"
    " \n"
    "   // To unsubscribe\n"
    "   unsubscribe()\n"
    " }\n"
    " ```\n"
).
-spec subscribe4(
    hub4(EJT),
    list(binary()),
    list(binary()),
    list(binary()),
    list(binary()),
    fun((EJT) -> nil)
) -> fun(() -> nil).
subscribe4(Hub, Topics1, Topics2, Topics3, Topics4, Callback) ->
    subscribe_n(
        erlang:element(2, Hub),
        [Topics1, Topics2, Topics3, Topics4],
        Callback
    ).
Operator	Description	Example
name:	Match package name. Supports * wildcards and repo/package form	name:phx* or name:hexpm/phoenix
description:	Full-text search of package descriptions	description:auth
depends:	Packages depending on a given package. Supports repo:package form	depends:ecto or depends:hexpm:ecto
build_tool:	Filter by build tool	build_tool:mix
updated_after:	Packages updated after an ISO8601 datetime	updated_after:2025-01-01T00:00:00Z
extra:	Match custom metadata (key,value). Nested keys are separated by commas	extra:license,MIT