qlobber-pg
Version:
PostgreSQL-based pub-sub and workqueues. Supports AMQP-like wildcard topics.
1,471 lines (844 loc) • 38.9 kB
HTML
<html lang="en">
<head>
<meta charset='utf-8'>
<title>qlobber-pg 2.0.9 | Documentation</title>
<meta name='description' content='PostgreSQL-based pub-sub and workqueues. Supports AMQP-like wildcard topics.'>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<link href='assets/bass.css' rel='stylesheet'>
<link href='assets/style.css' rel='stylesheet'>
<link href='assets/github.css' rel='stylesheet'>
<link href='assets/split.css' rel='stylesheet'>
</head>
<body class='documentation m0'>
<div class='flex'>
<div id='split-left' class='overflow-auto fs0 height-viewport-100'>
<div class='py1 px2'>
<h3 class='mb0 no-anchor'>qlobber-pg</h3>
<div class='mb1'><code>2.0.9</code></div>
<input
placeholder='Filter'
id='filter-input'
class='col12 block input'
spellcheck='false'
autocapitalize='off'
autocorrect='off'
type='text' />
<div id='toc'>
<ul class='list-reset h5 py1-ul'>
<li><a
href='#qlobberpg'
class=" toggle-sibling">
QlobberPG
<span class='icon'>▸</span>
</a>
<div class='toggle-target display-none'>
<ul class='list-reset py1-ul pl1'>
<li class='h5'><span>Instance members</span></li>
<li><a
href='#qlobberpgrefresh_now'
class='regular pre-open'>
#refresh_now
</a></li>
<li><a
href='#qlobberpgforce_refresh'
class='regular pre-open'>
#force_refresh
</a></li>
<li><a
href='#qlobberpgstop'
class='regular pre-open'>
#stop
</a></li>
<li><a
href='#qlobberpgstop_watching'
class='regular pre-open'>
#stop_watching
</a></li>
<li><a
href='#qlobberpgsubscribe'
class='regular pre-open'>
#subscribe
</a></li>
<li><a
href='#qlobberpgunsubscribe'
class='regular pre-open'>
#unsubscribe
</a></li>
<li><a
href='#qlobberpgpublish'
class='regular pre-open'>
#publish
</a></li>
</ul>
<ul class='list-reset py1-ul pl1'>
<li class='h5'>Events</li>
<li><a
href='#qlobberpgeventerror'
class='regular pre-open'>
ⓔ error
</a></li>
<li><a
href='#qlobberpgeventstart'
class='regular pre-open'>
ⓔ start
</a></li>
<li><a
href='#qlobberpgeventstop'
class='regular pre-open'>
ⓔ stop
</a></li>
<li><a
href='#qlobberpgeventwarning'
class='regular pre-open'>
ⓔ warning
</a></li>
</ul>
</div>
</li>
</ul>
</div>
<div class='mt1 h6 quiet'>
<a href='https://documentation.js.org/reading-documentation.html'>Need help reading this?</a>
</div>
</div>
</div>
<div id='split-right' class='relative overflow-auto height-viewport-100'>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='qlobberpg'>
QlobberPG
</h3>
</div>
<p>Creates a new <code>QlobberPG</code> object for publishing and subscribing to a
PostgreSQL queue.</p>
<div class='pre p1 fill-light mt0'>new QlobberPG(options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</div>
<p>
Extends
EventEmitter
</p>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
Configures the PostgreSQL queue.
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.name</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>Unique identifier for this
<code>QlobberPG</code>
instance. Every instance connected to the queue at the same time
must have a different name.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.db</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>
</td>
<td class='break-word'><span><a href="https://node-postgres.com/api/client"><code>node-postgres</code> configuration</a>
used for communicating with PostgreSQL.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.single_ttl</span> <code class='quiet'>Integer</code>
(default <code>1h</code>)
</td>
<td class='break-word'><span>Default time-to-live
(in milliseconds) for messages which should be read by at most one
subscriber. This value is added to the current time and the resulting
expiry time is put into the message's database row. After the expiry
time, the message is ignored and deleted when convenient.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.multi_ttl</span> <code class='quiet'>Integer</code>
(default <code>1m</code>)
</td>
<td class='break-word'><span>Default time-to-live
(in milliseconds) for messages which can be read by many subscribers.
This value is added to the current time and the resulting expiry time is
put into the message's database row. After the expiry time, the message
is ignored and deleted when convenient.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.expire_interval</span> <code class='quiet'>Integer</code>
(default <code>10s</code>)
</td>
<td class='break-word'><span>Number of milliseconds
between deleting expired messages from the database.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.poll_interval</span> <code class='quiet'>Integer</code>
(default <code>1s</code>)
</td>
<td class='break-word'><span>Number of milliseconds between
checking the database for new messages.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.notify</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>true</code>)
</td>
<td class='break-word'><span>Whether to use a database trigger
to watch for new messages. Note that this will be done in addition to
polling the database every
<code>poll_interval</code>
milliseconds.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.message_concurrency</span> <code class='quiet'>Integer</code>
(default <code>1</code>)
</td>
<td class='break-word'><span>The number of messages
to process at once.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.handler_concurrency</span> <code class='quiet'>Integer</code>
(default <code>0</code>)
</td>
<td class='break-word'><span>By default (0), a message
is considered handled by a subscriber only when all its data has been
read. If you set
<code>handler_concurrency</code>
to non-zero, a message is
considered handled as soon as a subscriber receives it. The next message
will then be processed straight away. The value of
<code>handler_concurrency</code>
limits the number of messages being handled by subscribers at any one
time.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.order_by_expiry</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>false</code>)
</td>
<td class='break-word'><span>Pass messages to
subscribers in order of their expiry time.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.dedup</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>true</code>)
</td>
<td class='break-word'><span>Whether to ensure each handler
function is called at most once when a message is received.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.single</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>true</code>)
</td>
<td class='break-word'><span>Whether to process messages meant
for
<em>at most</em>
one subscriber (across all
<code>QlobberPG</code>
instances), i.e.
work queues.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.separator</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>'.'</code>)
</td>
<td class='break-word'><span>The character to use for separating
words in message topics.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.wildcard_one</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>'*'</code>)
</td>
<td class='break-word'><span>The character to use for
matching exactly one word in a message topic to a subscriber.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.wildcard_some</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>'#'</code>)
</td>
<td class='break-word'><span>The character to use for
matching zero or more words in a message topic to a subscriber.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.filter</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>>)?</code>
</td>
<td class='break-word'><span>Function called before each message is processed.
<ul>
<li>The function signature is: <code>(info, handlers, cb(err, ready, filtered_handlers))</code></li>
<li>You can use this to filter the subscribed handler functions to be called
for the message (by passing the filtered list as the third argument to
<code>cb</code>).</li>
<li>If you want to ignore the message <em>at this time</em> then pass <code>false</code> as the
second argument to <code>cb</code>. <code>options.filter</code> will be called again later with
the same message.</li>
<li>Defaults to a function which calls <code>cb(null, true, handlers)</code>.</li>
<li><code>handlers</code> is an ES6 Set, or array if <code>options.dedup</code> is falsey.</li>
<li><code>filtered_handlers</code> should be an ES6 Set, or array if <code>options.dedup</code>
is falsey. If not, <code>new Set(filtered_handlers)</code> or
<code>Array.from(filtered_handlers)</code> will be used to convert it.</li>
<li>You can supply an array of filter functions - each will be called in turn
with the <code>filtered_handlers</code> from the previous one.</li>
<li>An array containing the filter functions is also available as the <code>filters</code>
property of the <code>QlobberPG</code> object and can be modified at any time.</li>
</ul>
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.batch_size</span> <code class='quiet'>Integer</code>
(default <code>100</code>)
</td>
<td class='break-word'><span>Passed to
<a href="https://github.com/brianc/node-pg-query-stream%5B%60node-pg-query-stream%60%5D">https://github.com/brianc/node-pg-query-stream[`node-pg-query-stream`]</a>
and specifies how many messages to retrieve from the database at a time
(using a cursor).
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Instance Members</div>
<div class="clearfix">
<div class='border-bottom' id='qlobberpgrefresh_now'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>refresh_now()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Check the database for new messages now rather than waiting for the next
periodic check to occur.</p>
<div class='pre p1 fill-light mt0'>refresh_now()</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgforce_refresh'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>force_refresh()</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Same as <a href="#qlobberpgrefresh_now">QlobberPG#refresh_now</a>.</p>
<div class='pre p1 fill-light mt0'>force_refresh()</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgstop'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>stop(cb?)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Stop checking for new messages.</p>
<div class='pre p1 fill-light mt0'>stop(cb: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>cb</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</code>
Optional function to call once access to the
database has stopped. Alternatively, you can listen for the
<a href="#qlobberpgstop">QlobberPG#stop</a>
event.
</div>
</div>
</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgstop_watching'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>stop_watching(cb)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Same as <a href="#qlobberpgstop">QlobberPG#stop</a>.</p>
<div class='pre p1 fill-light mt0'>stop_watching(cb: any)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>cb</span> <code class='quiet'>(any)</code>
</div>
</div>
</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgsubscribe'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>subscribe(topic, handler, options?, cb?)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Subscribe to messages in the PostgreSQL queue.</p>
<div class='pre p1 fill-light mt0'>subscribe(topic: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, handler: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>, options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?, cb: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>topic</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
Which messages you're interested in receiving.
Message topics are split into words using
<code>.</code>
as the separator. You can
use
<code>*</code>
to match exactly one word in a topic or
<code>#</code>
to match zero or more
words. For example,
<code>foo.*</code>
would match
<code>foo.bar</code>
whereas
<code>foo.#</code>
would
match
<code>foo</code>
,
<code>foo.bar</code>
and
<code>foo.bar.wup</code>
. Note you can change the
separator and wildcard characters by specifying the
<code>separator</code>
,
<code>wildcard_one</code>
and
<code>wildcard_some</code>
options when
<a href="#qlobberpg">constructing</a>
<code>QlobberPG</code>
objects. See the
<a href="https://github.com/davedoesdev/qlobber#qlobberoptions"><code>qlobber</code>
documentation</a>
for more information. Valid characters in
<code>topic</code>
are:
<code>A-Za-z0-9_*#.</code>
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>handler</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>)</code>
Function to call when a new message is
received on the PostgreSQL queue and its topic matches against
<code>topic</code>
.
<code>handler</code>
will be passed the following arguments:
<ul>
<li><strong><code>data</code></strong> (<a href="http://nodejs.org/api/stream.html#stream_class_stream_readable"><code>Readable</code></a> | <a href="http://nodejs.org/api/buffer.html#buffer_class_buffer"><code>Buffer</code></a>)
Message payload as a Readable stream or a Buffer.
By default you'll receive a Buffer. If <code>handler</code> has a property
<code>accept_stream</code> set to a truthy value then you'll receive a stream.
Note that <em>all</em> subscribers will receive the same stream or content for
each message. You should take this into account when reading from the
stream. The stream can be piped into multiple
<a href="http://nodejs.org/api/stream.html#stream_class_stream_writable">Writable</a>
streams but bear in mind it will go at the rate of the slowest one.</li>
<li><strong><code>info</code></strong> (<code>Object</code>) Metadata for the message, with the following
properties:
<ul>
<li><strong><code>topic</code></strong> (<code>String</code>) Topic the message was published with.</li>
<li><strong><code>expires</code></strong> (<code>Integer</code>) When the message expires (number of
milliseconds after January 1970 00:00:00 UTC).</li>
<li><strong><code>single</code></strong> (<code>Boolean</code>) Whether this message is being given to at
most one subscriber (across all <code>QlobberPG</code> instances).</li>
<li><strong><code>size</code></strong> (<code>Integer</code>) Message size in bytes.</li>
<li><strong><code>publisher</code></strong> (<code>String</code>) Name of the <code>QlobberPG</code> instance which
published the message.</li>
</ul>
</li>
<li><strong><code>done</code></strong> (<code>Function</code>) Function to call one you've handled the
message. Note that calling this function is only mandatory if
<code>info.single === true</code>, in order to delete and unlock the message
row in the database table. <code>done</code> takes two arguments:
<ul>
<li><strong><code>err</code></strong> (<code>Object</code>) If an error occurred then pass details of the
error, otherwise pass <code>null</code> or <code>undefined</code>.</li>
<li><strong><code>finish</code></strong> (<code>Function</code>) Optional function to call once the message
has been deleted and unlocked, in the case of
<code>info.single === true</code>, or straight away otherwise. It will be
passed the following argument:
<ul>
<li><strong><code>err</code></strong> (<code>Object</code>) If an error occurred then details of the
error, otherwise <code>null</code>.</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>?)</code>
Optional settings for this subscription.
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.subscribe_to_existing</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>false</code>)
</td>
<td class='break-word'><span>If
<code>true</code>
then
<code>handler</code>
will be called with any existing, unexpired messages that
match
<code>topic</code>
, as well as new ones. If
<code>false</code>
(the default) then
<code>handler</code>
will be called with new messages only.
</span></td>
</tr>
</tbody>
</table>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>cb</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</code>
Optional function to call once the subscription
has been registered. This will be passed the following argument:
<ul>
<li><strong><code>err</code></strong> (<code>Object</code>) If an error occurred then details of the error,
otherwise <code>null</code>.</li>
</ul>
</div>
</div>
</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgunsubscribe'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>unsubscribe(topic?, handler?, cb?)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Unsubscribe from messages in the PostgreSQL queue.</p>
<div class='pre p1 fill-light mt0'>unsubscribe(topic: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>?, handler: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?, cb: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>topic</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>?)</code>
Which messages you're no longer interested in
receiving via the
<code>handler</code>
function. This should be a topic you've
previously passed to
<a href="#qlobberpgsubscribe">QlobberPG#subscribe</a>
. If
<code>topic</code>
is
<code>undefined</code>
then all handlers for all topics are unsubscribed.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>handler</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</code>
The function you no longer want to be
called with messages published to the topic
<code>topic</code>
. This should be a
function you've previously passed to
<a href="#qlobberpgsubscribe">QlobberPG#subscribe</a>
.
If you subscribed
<code>handler</code>
to a different topic then it will still
be called for messages which match that topic. If
<code>handler</code>
is
<code>undefined</code>
, all handlers for the topic
<code>topic</code>
are unsubscribed.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>cb</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</code>
Optional function to call once
<code>handler</code>
has
been unsubscribed from
<code>topic</code>
. This will be passed the following
argument:
<ul>
<li><strong><code>err</code></strong> (<code>Object</code>) If an error occurred then details of the error,
otherwise <code>null</code>.</li>
</ul>
</div>
</div>
</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgpublish'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>publish(topic, payload, options, cb?)</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Publish a message to the PostgreSQL queue.</p>
<div class='pre p1 fill-light mt0'>publish(topic: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, payload: (<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, cb: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?): (<a href="https://nodejs.org/api/stream.html">Stream</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined">undefined</a>)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>topic</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
Message topic. The topic should be a series of
words separated by
<code>.</code>
(or the
<code>separator</code>
character you passed to
the
<a href="#qlobberpg">constructor</a>
). Valid characters in
<code>topic</code>
are:
<code>A-Za-z0-9_.</code>
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>payload</span> <code class='quiet'>((<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
Message payload. If you don't pass a
payload then
<code>publish</code>
will return a
<a href="http://nodejs.org/api/stream.html#stream_class_stream_writable"><code>Writable</code></a>
for you to write the payload info.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
Optional settings for this publication.
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.single</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>false</code>)
</td>
<td class='break-word'><span>If
<code>true</code>
then the message
will be given to
<em>at most</em>
one interested subscriber, across all
<code>QlobberPG</code>
instances querying the PostgreSQL queue. Otherwise all
interested subscribers will receive the message (the default).
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.ttl</span> <code class='quiet'>Integer?</code>
</td>
<td class='break-word'><span>Time-to-live (in milliseconds) for this
message. If you don't specify anything then
<code>single_ttl</code>
or
<code>multi_ttl</code>
(provided to the
<a href="#qlobberpg">constructor</a>
) will be
used, depending on the value of
<code>single</code>
. After the time-to-live
for the message has passed, the message is ignored and deleted when
convenient.
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.encoding</span> <code class='quiet'><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>"utf8"</code>)
</td>
<td class='break-word'><span>If
<code>payload</code>
is a string,
the encoding to use when writing to the database.
</span></td>
</tr>
</tbody>
</table>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>cb</span> <code class='quiet'>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function">Function</a>?)</code>
Optional function to call once the message has
been written to the database. It will be passed the following
arguments:
<ul>
<li><strong><code>err</code></strong> (<code>Object</code>) If an error occurred then details of the error,
otherwise <code>null</code>.</li>
<li><strong><code>info</code></strong> (<code>Object</code>) Metadata for the message. See
<a href="#qlobberpgsubscribe">QlobberPG#subscribe</a> for a description of <code>info</code>'s properties.</li>
</ul>
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>(<a href="https://nodejs.org/api/stream.html">Stream</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined">undefined</a>)</code>:
A
<a href="http://nodejs.org/api/stream.html#stream_class_stream_writable"><code>Writable</code></a>
if no
<code>payload</code>
was passed, otherwise
<code>undefined</code>
.
</section>
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Events</div>
<div class="clearfix">
<div class='border-bottom' id='qlobberpgeventerror'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>error</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Error event. Emitted if an unrecoverable error occurs.
QlobberPG may stop querying the database for messages.</p>
<div class='pre p1 fill-light mt0'>error</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
</p>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgeventstart'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>start</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Start event. Emitted when messages can be published and
subscribed to.</p>
<div class='pre p1 fill-light mt0'>start</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgeventstop'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>stop</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Stop event. Emitted after <a href="#qlobberpgstop">QlobberPG#stop</a> has been called
and access to the database has stopped.</p>
<div class='pre p1 fill-light mt0'>stop</div>
</section>
</div>
</div>
<div class='border-bottom' id='qlobberpgeventwarning'>
<div class="clearfix small pointer toggle-sibling">
<div class="py1 contain">
<a class='icon pin-right py1 dark-link caret-right'>▸</a>
<span class='code strong strong truncate'>warning</span>
</div>
</div>
<div class="clearfix display-none toggle-target">
<section class='p2 mb2 clearfix bg-white minishadow'>
<p>Warning event. Emitted if a recoverable error occurs.
QlobberPG will continue to query the database for messages.</p>
<p>If you don't handle this event, the error will be written to
<code>console.error</code>.</p>
<div class='pre p1 fill-light mt0'>warning</div>
<p>
Type:
<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
</p>
</section>
</div>
</div>
</div>
</section>
</div>
</div>
<script src='assets/anchor.js'></script>
<script src='assets/split.js'></script>
<script src='assets/site.js'></script>
</body>
</html>