docs/index.html

<!doctype html>
<html class="default no-js">
<head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<title>@harelpls/use-pusher</title>
	<meta name="description" content="Documentation for @harelpls/use-pusher">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
	<div class="tsd-page-toolbar">
		<div class="container">
			<div class="table-wrap">
				<div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base=".">
					<div class="field">
						<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
						<input id="tsd-search-field" type="text" />
					</div>
					<ul class="results">
						<li class="state loading">Preparing search index...</li>
						<li class="state failure">The search index is not available</li>
					</ul>
					<a href="index.html" class="title">@harelpls/use-pusher</a>
				</div>
				<div class="table-cell" id="tsd-widgets">
					<div id="tsd-filter">
						<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
						<div class="tsd-filter-group">
							<div class="tsd-select" id="tsd-filter-visibility">
								<span class="tsd-select-label">All</span>
								<ul class="tsd-select-list">
									<li data-value="public">Public</li>
									<li data-value="protected">Public/Protected</li>
									<li data-value="private" class="selected">All</li>
								</ul>
							</div>
							<input type="checkbox" id="tsd-filter-inherited" checked />
							<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
							<input type="checkbox" id="tsd-filter-externals" checked />
							<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
							<input type="checkbox" id="tsd-filter-only-exported" />
							<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
						</div>
					</div>
					<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
				</div>
			</div>
		</div>
	</div>
	<div class="tsd-page-title">
		<div class="container">
			<ul class="tsd-breadcrumb">
				<li>
					<a href="globals.html">Globals</a>
				</li>
			</ul>
			<h1>@harelpls/use-pusher</h1>
		</div>
	</div>
</header>
<div class="container container-main">
	<div class="row">
		<div class="col-8 col-content">
			<div class="tsd-panel tsd-typography">
				<a href="#harelplsuse-pusher" id="harelplsuse-pusher" style="color: inherit; text-decoration: none;">
					<h1><code>@harelpls/use-pusher</code></h1>
				</a>
				<blockquote>
					<p>Easy as <a href="https://reactjs.org/docs/hooks-intro.html">React hooks</a> that integrate with the <a href="https://github.com/pusher/pusher-js"><code>pusher-js</code></a> library.</p>
				</blockquote>
				<p><a href="https://www.npmjs.com/package/@harelpls/use-pusher"><img src="https://img.shields.io/npm/v/@harelpls/use-pusher.svg" alt="NPM"></a> <img src="https://badgen.net/badge//types/Typescript?icon=typescript" alt="Typed"></p>
				<!-- START doctoc generated TOC please keep comment here to allow auto update -->
				<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
				<ul>
					<li><a href="#install">Install</a></li>
					<li><a href="#hooks">Hooks</a></li>
					<li><a href="#usage">Usage</a></li>
					<li><a href="#usechannel"><code>useChannel</code></a></li>
					<li><a href="#usepresencechannel"><code>usePresenceChannel</code></a></li>
					<li><a href="#useevent"><code>useEvent</code></a></li>
					<li><a href="#usetrigger"><code>useTrigger</code></a></li>
					<li><a href="#usepusher"><code>usePusher</code></a></li>
					<li><a href="#trigger-server">Trigger Server</a></li>
					<li><a href="#useclienttrigger"><code>useClientTrigger</code></a></li>
					<li><a href="#typescript">Typescript</a></li>
					<li><a href="#testing">Testing</a></li>
					<li><a href="#react-native">React Native</a></li>
					<li><a href="#contributing">Contributing</a></li>
					<li><a href="#license">License</a></li>
				</ul>
				<!-- END doctoc generated TOC please keep comment here to allow auto update -->
				<a href="#api-referencedocs" id="api-referencedocs" style="color: inherit; text-decoration: none;">
					<h2><a href="https://use-pusher-docs.netlify.com/">API Reference/Docs</a></h2>
				</a>
				<a href="#install" id="install" style="color: inherit; text-decoration: none;">
					<h2>Install</h2>
				</a>
				<pre><code class="language-bash">yarn add @harelpls/use-pusher</code></pre>
				<a href="#hooks" id="hooks" style="color: inherit; text-decoration: none;">
					<h2>Hooks</h2>
				</a>
				<ul>
					<li><a href="#usechannel"><code>useChannel</code></a></li>
					<li><a href="#usepresencechannel"><code>usePresenceChannel</code></a></li>
					<li><a href="#useevent"><code>useEvent</code></a></li>
					<li><a href="#usetrigger"><code>useTrigger</code></a></li>
					<li><a href="#useclienttrigger"><code>useClientTrigger</code></a></li>
					<li><a href="#usepusher"><code>usePusher</code></a></li>
				</ul>
				<a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
					<h2>Usage</h2>
				</a>
				<p>You must wrap your app with a <code>PusherProvider</code> and pass it config props for <a href="https://github.com/pusher/pusher-js"><code>pusher-js</code></a> initialisation.</p>
				<pre><code class="language-typescript"><span class="hljs-keyword">import</span> React <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;react&quot;</span>;
<span class="hljs-keyword">import</span> { PusherProvider } <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;@harelpls/use-pusher&quot;</span>;

<span class="hljs-keyword">const</span> config = {
  <span class="hljs-comment">// required config props</span>
  clientKey: <span class="hljs-string">&quot;client-key&quot;</span>,
  cluster: <span class="hljs-string">&quot;ap4&quot;</span>,

  <span class="hljs-comment">// optional if you&#x27;d like to trigger events. BYO endpoint.</span>
  <span class="hljs-comment">// see &quot;Trigger Server&quot; below for more info</span>
  triggerEndpoint: <span class="hljs-string">&quot;/pusher/trigger&quot;</span>,

  <span class="hljs-comment">// required for private/presence channels</span>
  <span class="hljs-comment">// also sends auth headers to trigger endpoint</span>
  authEndpoint: <span class="hljs-string">&quot;/pusher/auth&quot;</span>,
  auth: {
    headers: { Authorization: <span class="hljs-string">&quot;Bearer token&quot;</span> },
  },
};

<span class="hljs-comment">// Wrap app in provider</span>
<span class="hljs-keyword">const</span> App = <span class="hljs-function">() =&gt;</span> {
  &lt;PusherProvider {...config}&gt;
    &lt;Example /&gt;
  &lt;/PusherProvider&gt;;
};</code></pre>
				<a href="#usechannel" id="usechannel" style="color: inherit; text-decoration: none;">
					<h2><code>useChannel</code></h2>
				</a>
				<p>Use this hook to subscribe to a channel.</p>
				<pre><code class="language-typescript"><span class="hljs-comment">// returns channel instance.</span>
<span class="hljs-keyword">const</span> channel = useChannel(<span class="hljs-string">&quot;channel-name&quot;</span>);</code></pre>
				<a href="#usepresencechannel" id="usepresencechannel" style="color: inherit; text-decoration: none;">
					<h2><code>usePresenceChannel</code></h2>
				</a>
				<p>Augments a regular channel with member functionality.</p>
				<pre><code class="language-typescript"><span class="hljs-keyword">const</span> Example = <span class="hljs-function">() =&gt;</span> {
  <span class="hljs-keyword">const</span> { members, myID } = usePresenceChannel(<span class="hljs-string">&#x27;presence-awesome&#x27;</span>);

  <span class="hljs-keyword">return</span> (
    &lt;ul&gt;
      {<span class="hljs-built_in">Object</span>.entries(members)
        <span class="hljs-comment">// filter self from members</span>
        .filter([id] =&gt; id !== myID)
        <span class="hljs-comment">// map them to a list</span>
        .map([id, info] =&gt; (
          &lt;li key={id}&gt;{info.name}&lt;/li&gt;
        ))
      }
    &lt;/ul&gt;
  )
}</code></pre>
				<a href="#useevent" id="useevent" style="color: inherit; text-decoration: none;">
					<h2><code>useEvent</code></h2>
				</a>
				<p>Bind to events on a channel with a callback.</p>
				<pre><code class="language-typescript"><span class="hljs-keyword">const</span> Example = <span class="hljs-function">() =&gt;</span> {
  <span class="hljs-keyword">const</span> [message, setMessages] = useState();
  <span class="hljs-keyword">const</span> channel = useChannel(<span class="hljs-string">&quot;channel-name&quot;</span>);
  useEvent(channel, <span class="hljs-string">&quot;message&quot;</span>, <span class="hljs-function">(<span class="hljs-params">{ data }</span>) =&gt;</span>
    setMessages(<span class="hljs-function">(<span class="hljs-params">messages</span>) =&gt;</span> [...messages, data])
  );
};</code></pre>
				<p><em>Note</em>: This will bind and unbind to the event on each render. You may want to memoise your callback with <code>useCallback</code> before passing it in if you notice performance issues.</p>
				<a href="#usetrigger" id="usetrigger" style="color: inherit; text-decoration: none;">
					<h2><code>useTrigger</code></h2>
				</a>
				<p>A helper function to create a <strong>server triggered</strong> event. BYO server (See <a href="#trigger-server">Trigger Server</a> below). Pass in <code>triggerEndpoint</code> prop to <code>&lt;PusherProvider /&gt;</code>. Any auth headers from <code>config.auth.headers</code> automatically get passed to the <code>fetch</code> call.</p>
				<pre><code class="language-typescript"><span class="hljs-keyword">import</span> { useTrigger } <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;@harelpls/use-pusher&#x27;</span>;

<span class="hljs-keyword">const</span> Example = <span class="hljs-function">() =&gt;</span> {.
  <span class="hljs-keyword">const</span> trigger = useTrigger();
  <span class="hljs-keyword">const</span> handleClick = <span class="hljs-function">() =&gt;</span>
    trigger(<span class="hljs-string">&quot;channel-name&quot;</span>, <span class="hljs-string">&quot;event-name&quot;</span>, <span class="hljs-string">&quot;hello&quot;</span>);

  <span class="hljs-keyword">return</span> (
    &lt;button onClick={handleClick}&gt;Say Hello&lt;/button&gt;
  )
}</code></pre>
				<a href="#usepusher" id="usepusher" style="color: inherit; text-decoration: none;">
					<h2><code>usePusher</code></h2>
				</a>
				<p>Get access to the Pusher instance to do other things.</p>
				<pre><code class="language-typescript"><span class="hljs-keyword">import</span> { usePusher } <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;@harelpls/use-pusher&quot;</span>;

<span class="hljs-keyword">const</span> Example = <span class="hljs-function">() =&gt;</span> {
  <span class="hljs-keyword">const</span> { client } = usePusher();
  client.log(<span class="hljs-string">&quot;Look ma, logs!&quot;</span>);

  <span class="hljs-keyword">return</span> <span class="hljs-literal">null</span>;
};</code></pre>
				<a href="#trigger-server" id="trigger-server" style="color: inherit; text-decoration: none;">
					<h2>Trigger Server</h2>
				</a>
				<p>In order to trigger an event, you&#39;ll have to create a simple lambda (or an express server if that&#39;s your thing). Below is a short lambda that can handle triggered events from <code>useTrigger</code>.</p>
				<pre><code class="language-typescript"><span class="hljs-keyword">import</span> Pusher <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;pusher&quot;</span>;

<span class="hljs-keyword">const</span> pusher = <span class="hljs-keyword">new</span> Pusher({
  appId: <span class="hljs-string">&quot;app-id&quot;</span>,
  key: <span class="hljs-string">&quot;client-key&quot;</span>,
  secret: <span class="hljs-string">&quot;mad-secret&quot;</span>,
  cluster: <span class="hljs-string">&quot;ap4&quot;</span>,
});

<span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">handler</span>(<span class="hljs-params">event</span>) </span>{
  <span class="hljs-keyword">const</span> { channelName, eventName, data } = <span class="hljs-built_in">JSON</span>.parse(event.body);
  pusher.trigger(channelName, eventName, data);
  <span class="hljs-keyword">return</span> { statusCode: <span class="hljs-number">200</span> };
}</code></pre>
				<a href="#useclienttrigger" id="useclienttrigger" style="color: inherit; text-decoration: none;">
					<h2><code>useClientTrigger</code></h2>
				</a>
				<blockquote>
					<p><em>I don&#39;t want a server though</em></p>
				</blockquote>
				<p>I hear ya. If you&#39;re feeling audacious, you can use <a href="https://pusher.com/docs/channels/using_channels/events#triggering-client-events">client events</a> to push directly from the client:</p>
				<pre><code class="language-typescript"><span class="hljs-keyword">import</span> { useChannel, useClientTrigger } <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;@harelpls/use-pusher&quot;</span>;

<span class="hljs-keyword">const</span> Example = <span class="hljs-function">() =&gt;</span> {
  <span class="hljs-keyword">const</span> channel = useChannel(<span class="hljs-string">&quot;presence-ca&quot;</span>);
  <span class="hljs-keyword">const</span> trigger = useClientTrigger(channel);
  <span class="hljs-keyword">const</span> handleClientEvent = <span class="hljs-function">() =&gt;</span> {
    trigger(<span class="hljs-string">&quot;Pew pew&quot;</span>);
  };

  <span class="hljs-keyword">return</span> &lt;button onClick={handleClientEvent}&gt;Fire&lt;/button&gt;;
};</code></pre>
				<a href="#typescript" id="typescript" style="color: inherit; text-decoration: none;">
					<h2>Typescript</h2>
				</a>
				<p>This project was built using typescript, so types are built-in. Yeeeew!</p>
				<a href="#testing" id="testing" style="color: inherit; text-decoration: none;">
					<h2>Testing</h2>
				</a>
				<p>I&#39;ve teamed up with <a href="https://github.com/nikolalsvk">@nikolalsvk</a> on <a href="https://github.com/nikolalsvk/pusher-js-mock"><code>pusher-js-mock</code></a> to bring y&#39;all a great pusher mock.</p>
				<p>Testing emitted events with jest can be achieved using <code>jest.mock</code> and <code>@testing-library/react</code> (or <code>enzyme</code>, though your tests should reflect what the user should see <strong>NOT</strong> how the component handles events internally):</p>
				<pre><code class="language-typescript"><span class="hljs-comment">// Example.tsx</span>
<span class="hljs-keyword">import</span> React <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;react&quot;</span>;
<span class="hljs-keyword">import</span> { useChannel, useEvent } <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;@harelpls/use-pusher&quot;</span>;

<span class="hljs-keyword">const</span> Example = <span class="hljs-function">() =&gt;</span> {
  <span class="hljs-keyword">const</span> [title, setTitle] = useState();
  <span class="hljs-keyword">const</span> channel = useChannel(<span class="hljs-string">&quot;my-channel&quot;</span>);
  useEvent(channel, <span class="hljs-string">&quot;title&quot;</span>, <span class="hljs-function">(<span class="hljs-params">{ data }</span>) =&gt;</span> setTitle(data));

  <span class="hljs-keyword">return</span> &lt;span&gt;{title}&lt;/span&gt;;
};

<span class="hljs-comment">// Example.test.tsx</span>
<span class="hljs-keyword">import</span> { render, act } <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;@testing-library/react&quot;</span>;
<span class="hljs-keyword">import</span> { PusherMock, PusherChannelMock } <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;pusher-js-mock&quot;</span>;

<span class="hljs-comment">// mock out the result of the useChannel hook</span>
<span class="hljs-keyword">const</span> mockChannel = <span class="hljs-keyword">new</span> PusherChannelMock();
jest.mock(<span class="hljs-string">&quot;@harelpls/use-pusher&quot;</span>, <span class="hljs-function">() =&gt;</span> ({
  ...require.requireActual(<span class="hljs-string">&quot;@harelpls/use-pusher&quot;</span>),
  useChannel: <span class="hljs-function">() =&gt;</span> mockChannel,
}));

test(<span class="hljs-string">&quot;should show a title when it receives a title event&quot;</span>, <span class="hljs-keyword">async</span> () =&gt; {
  <span class="hljs-comment">// mock the client</span>
  <span class="hljs-keyword">const</span> client = <span class="hljs-keyword">new</span> PusherMock(<span class="hljs-string">&quot;client-key&quot;</span>, { cluster: <span class="hljs-string">&quot;ap4&quot;</span> });

  <span class="hljs-comment">// render component and provider with a mocked context value</span>
  <span class="hljs-keyword">const</span> { findByText } = render(
    &lt;PusherProvider clientKey=<span class="hljs-string">&quot;client-key&quot;</span> cluster=<span class="hljs-string">&quot;ap4&quot;</span> value={{ client }}&gt;
      &lt;Example /&gt;
    &lt;/PusherProvider&gt;
  );

  <span class="hljs-comment">// emit an event on the mocked channel</span>
  act(<span class="hljs-function">() =&gt;</span> mockChannel.emit(<span class="hljs-string">&quot;title&quot;</span>, { data: <span class="hljs-string">&quot;Hello world&quot;</span> }));

  <span class="hljs-comment">// assert expectations</span>
  expect(<span class="hljs-keyword">await</span> findByText(<span class="hljs-string">&quot;Hello world&quot;</span>)).toBeInTheDocument();
});</code></pre>
				<p><a href="https://github.com/mayteio/use-pusher/blob/master/src/__tests__/Example.tsx">Check out the example tests</a> for testing presence channels.</p>
				<a href="#react-native" id="react-native" style="color: inherit; text-decoration: none;">
					<h2>React Native</h2>
				</a>
				<p>This package comes with React Native support. Import your <code>PusherProvider</code> from <code>@harelpls/use-pusher/react-native</code> instead of the default <code>@harelpls/use-pusher</code>. All exports are re-exported from there.</p>
				<p>Ensure you add the netinfo package to your project too: <a href="https://github.com/react-native-community/react-native-netinfo"><code>@react-native-community/netinfo</code></a>.</p>
				<pre><code class="language-ts"><span class="hljs-keyword">import</span> { PusherProvider, useChannel } <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;@harelpls/use-pusher/react-native&quot;</span>;</code></pre>
				<a href="#contributing" id="contributing" style="color: inherit; text-decoration: none;">
					<h2>Contributing</h2>
				</a>
				<ol>
					<li>Clone the repository and run <code>yarn &amp;&amp; yarn test:watch</code></li>
					<li>Get coding!</li>
				</ol>
				<p>Please write tests (100% jest coverage) and types.</p>
				<a href="#license" id="license" style="color: inherit; text-decoration: none;">
					<h2>License</h2>
				</a>
				<p>MIT © <a href="https://github.com/@mayteio">@mayteio</a></p>
				<hr>
				<p>This hook is created using <a href="https://github.com/hermanya/create-react-hook">create-react-hook</a>.</p>
			</div>
		</div>
		<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
			<nav class="tsd-navigation primary">
				<ul>
					<li class="globals  ">
						<a href="globals.html"><em>Globals</em></a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_core_pusherprovider_.html">&quot;core/<wbr>Pusher<wbr>Provider&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_core_usechannel_.html">&quot;core/use<wbr>Channel&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_core_useclienttrigger_.html">&quot;core/use<wbr>Client<wbr>Trigger&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_core_useevent_.html">&quot;core/use<wbr>Event&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_core_usepresencechannel_.html">&quot;core/use<wbr>Presence<wbr>Channel&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_core_usepusher_.html">&quot;core/use<wbr>Pusher&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_core_usetrigger_.html">&quot;core/use<wbr>Trigger&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_native_pusherprovider_.html">&quot;native/<wbr>Pusher<wbr>Provider&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_testutils_.html">&quot;test<wbr>Utils&quot;</a>
					</li>
					<li class=" tsd-kind-module">
						<a href="modules/_web_pusherprovider_.html">&quot;web/<wbr>Pusher<wbr>Provider&quot;</a>
					</li>
				</ul>
			</nav>
			<nav class="tsd-navigation secondary menu-sticky">
				<ul class="before-current">
				</ul>
			</nav>
		</div>
	</div>
</div>
<footer class="with-border-bottom">
	<div class="container">
		<h2>Legend</h2>
		<div class="tsd-legend-group">
			<ul class="tsd-legend">
				<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
				<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
				<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
				<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
			</ul>
		</div>
	</div>
</footer>
<div class="container tsd-generator">
	<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
</body>
</html>