whisper

-module(whisper).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/whisper.gleam").
-export([new/1, on/3, subscribe/2, publish/3]).
-export_type([subscription/1, whisper/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.

-type subscription(DQM) :: {subscription,
        fun(() -> {ok, DQM} | {error, nil}),
        fun(() -> nil)}.

-type whisper(DQN) :: any() | {gleam_phantom, DQN}.

-file("src/whisper.gleam", 22).
?DOC(
    " Creates a new whisper pub/sub system with a specified buffer capacity.\n"
    "\n"
    " The capacity determines how many messages each subscription can buffer\n"
    " before older messages are dropped.\n"
    "\n"
    " ## Example\n"
    "\n"
    " ```gleam\n"
    " let whisper = whisper.new(100)\n"
    " ```\n"
).
-spec new(integer()) -> whisper(any()).
new(Capacity) ->
    whisper_ffi:new(Capacity).

-file("src/whisper.gleam", 49).
?DOC(
    " Registers a callback listener for a specific topic.\n"
    "\n"
    " The listener function will be called immediately whenever a message\n"
    " is published to the topic. Returns a cancellation function to stop\n"
    " listening.\n"
    "\n"
    " ## Example\n"
    "\n"
    " ```gleam\n"
    " let whisper = whisper.new(10)\n"
    " let cancel = whisper.on(whisper, \"notifications\", fn(msg) {\n"
    "   io.println(\"Received: \" <> msg)\n"
    " })\n"
    "\n"
    " whisper.publish(whisper, \"notifications\", \"Hello!\")\n"
    " // Prints: \"Received: Hello!\"\n"
    "\n"
    " cancel()  // Stop listening\n"
    " ```\n"
).
-spec on(whisper(DQS), binary(), fun((DQS) -> nil)) -> fun(() -> nil).
on(Whisper, Topic, Listener) ->
    whisper_ffi:on(Whisper, Topic, Listener).

-file("src/whisper.gleam", 86).
?DOC(
    " Creates a subscription to a topic with a buffered message queue.\n"
    "\n"
    " Messages published to the topic are stored in a buffer until retrieved\n"
    " with `receive()`. The subscription's `receive()` function is non-blocking\n"
    " and returns `Error(Nil)` if no messages are available.\n"
    "\n"
    " ## Example\n"
    "\n"
    " ```gleam\n"
    " let whisper = whisper.new(10)\n"
    " let sub = whisper.subscribe(whisper, \"events\")\n"
    "\n"
    " whisper.publish(whisper, \"events\", 42)\n"
    "\n"
    " case sub.receive() {\n"
    "   Ok(msg) -> io.debug(msg)  // 42\n"
    "   Error(Nil) -> io.println(\"No messages\")\n"
    " }\n"
    "\n"
    " sub.cancel()  // Clean up\n"
    " ```\n"
).
-spec subscribe(whisper(DQW), binary()) -> subscription(DQW).
subscribe(Whisper, Topic) ->
    {Receive_fn, Cancel_fn} = whisper_ffi:subscribe(Whisper, Topic),
    {subscription, Receive_fn, Cancel_fn}.

-file("src/whisper.gleam", 117).
?DOC(
    " Publishes a message to all listeners and subscribers of a topic.\n"
    "\n"
    " The message is immediately delivered to all callback listeners and\n"
    " added to the buffer of all subscriptions for the topic.\n"
    "\n"
    " ## Example\n"
    "\n"
    " ```gleam\n"
    " let whisper = whisper.new(10)\n"
    "\n"
    " let sub1 = whisper.subscribe(whisper, \"chat\")\n"
    " let sub2 = whisper.subscribe(whisper, \"chat\")\n"
    "\n"
    " whisper.publish(whisper, \"chat\", \"Hello everyone!\")\n"
    "\n"
    " // Both subscribers will receive the message\n"
    " let assert Ok(msg1) = sub1.receive()\n"
    " let assert Ok(msg2) = sub2.receive()\n"
    " ```\n"
).
-spec publish(whisper(DRD), binary(), DRD) -> nil.
publish(Whisper, Topic, Message) ->
    whisper_ffi:publish(Whisper, Topic, Message).