Document speaker class

This commit is contained in:
Talia 2022-07-02 10:55:38 +02:00
parent e99df6b58f
commit 42fa5e8d4d
Signed by: darkwiiplayer
GPG key ID: 7808674088232B3E
2 changed files with 106 additions and 0 deletions

View file

@ -15,6 +15,8 @@
<p style="text-align: center;">
A collection of <em>JavaScript modules</em> to make <em>front-end</em> easier.
</p>
<p>
</p>
</section>
<section>
@ -81,6 +83,22 @@
</p>
</section>
<section>
<h2>Speaker</h2>
<p>
Publish and subscribe to messages, relayed via micro-tasks.
<a class="fancy" href="page/speaker.html">Read More</a>
<code-block>
const speaker = new Speaker()
speaker.listen((...args) =&gt; console.log(...args))
speaker.speak("First", "second", "third")
</code-block>
No, this has nothing to do with playing audio.
</p>
</section>
<section>
<h2>Debounce</h2>
<p>

88
page/speaker.html Normal file
View file

@ -0,0 +1,88 @@
<link rel="stylesheet" href="style.css">
<script type="module" src="codeblock.js"></script>
<script type="module" src="scrollToTop.js"></script>
<scroll-to-top>
</scroll-to-top>
<a class="back" href="..">Module Index</a>
<h1 class="js module">speaker.js</h1>
<code-block>import {Speaker} from 'speaker.js'</code-block>
<section>
<h2>Description</h2>
<p>
A publish/subscribe helper class that uses micro-tasks to relay messages to many subscribers.
</p>
</section>
<section>
<h2>Example</h2>
<code-block>
const speaker = new Speaker()
speaker.listen(message =&gt; { document.title = message })
speaker.listen(message =&gt; { console.log(`Message received: ${message}`) })
speaker.speak("New page title")
console.log("This line runs before any of the callbacks")
</code-block>
<p>
Note that the callbacks don't run immediately.
They are scheduled to a micro-task to be called later on.
</p>
</section>
<section>
<h2>Methods</h2>
<dl>
<dt><code>new Speaker(...initial) : Speaker</code></dt>
<dd>
Constructs a new speaker.
All arguments passed to the constructor will be retained and returned
by any call to <code>listen</code> before the first time <code>speak</code>
is called.
</dd>
<dt><code>Speaker.listen(callback : (...args) =&gt; undefined) : [...args]</code></dt>
<dd>
Registers a callback to be called on every new message.
Returns an array containing the retained arguments of the last message.
</dd>
<dt><code>Speaker.speak(...args)</code></dt>
<dd>
Relays a message of zero or more arguments to all registered callbacks.
As mentioned above, callbacks will not be called immediately, but scheduled in a new micro-task.
The arguments are retained until <code>speak</code> is called again.
</dd>
<dt><code>Speaker.forget(callback)</code></dt>
<dd>
Removes a single callback function from its list of callbacks.
</dd>
<dt><code>Speaker.silence()</code></dt>
<dd>
Clears the list of callbacks completely.
</dd>
</dl>
</section>
<section>
<h2>Immediate Speaker</h2>
<p>
Additionally, the module exposts the <code>ImmediateSpeaker</code> class,
which does the exact same as a normal speaker,
but executes its callbacks immediately instead of scheduling a micro-task.
</p>
<p>
The API is the <em>exact same</em> as a normal <code>Speaker</code>.
</p>
</section>