External modules
"@harelpls/use-pusher
-
</ul>
)
}
-
+
<button onClick={handleClick}>Say Hello</button>
)
}
-
+
@harelpls/use-pusher
+@harelpls/use-pusher
--Easy as hooks that integrate with the pusher-js library.
+Easy as React hooks that integrate with the
pusher-jslibrary.
API Reference/Docs
+
-
+
- Install +
- Hooks +
- Usage +
useChannel
+ usePresenceChannel
+ useEvent
+ useTrigger
+ usePusher
+ - Trigger Server +
useClientTrigger
+ - Typescript +
- Testing +
- React Native +
- Contributing +
- License +
API Reference/Docs
Install
@@ -93,23 +113,23 @@Hooks
Usage
You must wrap your app with a PusherProvider and pass it config props for pusher-js initialisation.
import React from 'react';
-import { PusherProvider } from '@harelpls/use-pusher';
+ import React from "react";
+import { PusherProvider } from "@harelpls/use-pusher";
const config = {
// required config props
- clientKey: 'client-key',
- cluster: 'ap4',
+ clientKey: "client-key",
+ cluster: "ap4",
// optional if you'd like to trigger events. BYO endpoint.
// see "Trigger Server" below for more info
- triggerEndpoint: '/pusher/trigger',
+ triggerEndpoint: "/pusher/trigger",
// required for private/presence channels
// also sends auth headers to trigger endpoint
- authEndpoint: '/pusher/auth',
+ authEndpoint: "/pusher/auth",
auth: {
- headers: { Authorization: 'Bearer token' },
+ headers: { Authorization: "Bearer token" },
},
};
@@ -119,13 +139,13 @@ Usage
<Example />
</PusherProvider>;
};
-
+
useChannel
Use this hook to subscribe to a channel.
// returns channel instance.
-const channel = useChannel('channel-name');
-
+const channel = useChannel("channel-name");usePresenceChannel
Augments a regular channel with member functionality.
@@ -145,22 +165,19 @@usePresenceChannel
</ul>
)
}
-
+
useEvent
Bind to events on a channel with a callback.
const Example = () => {
const [message, setMessages] = useState();
- const channel = useChannel('channel-name');
- useEvent(
- channel,
- 'message',
- ({ data }) => setMessages(messages => [...messages, data]),
- // optional dependencies array. Passed through to useCallback. Defaults to [].
- []
+ const channel = useChannel("channel-name");
+ useEvent(channel, "message", ({ data }) =>
+ setMessages((messages) => [...messages, data])
);
};Note: This will bind and unbind to the event on each render. You may want to memoise your callback with useCallback before passing it in if you notice performance issues.
useTrigger
A helper function to create a server triggered event. BYO server (See Trigger Server below). Pass in triggerEndpoint prop to <PusherProvider />. Any auth headers from config.auth.headers automatically get passed to the fetch call.
useTrigger
<button onClick={handleClick}>Say Hello</button>
)
}
-
+
usePusher
Get access to the Pusher instance to do other things.
-import { usePusher } from '@harelpls/use-pusher';
+ import { usePusher } from "@harelpls/use-pusher";
const Example = () => {
const { client } = usePusher();
- client.log('Look ma, logs!');
+ client.log("Look ma, logs!");
return null;
};
@@ -191,13 +208,13 @@ usePusher
Trigger Server
In order to trigger an event, you'll have to create a simple lambda (or an express server if that's your thing). Below is a short lambda that can handle triggered events from useTrigger.
- import Pusher from 'pusher';
+ import Pusher from "pusher";
const pusher = new Pusher({
- appId: 'app-id',
- key: 'client-key',
- secret: 'mad-secret',
- cluster: 'ap4',
+ appId: "app-id",
+ key: "client-key",
+ secret: "mad-secret",
+ cluster: "ap4",
});
export async function handler(event) {
@@ -205,20 +222,20 @@ Trigger Server
pusher.trigger(channelName, eventName, data);
return { statusCode: 200 };
}
-
+
useClientTrigger
I don't want a server though
I hear ya. If you're feeling audacious, you can use client events to push directly from the client:
- import { useChannel, useClientTrigger } from '@harelpls/use-pusher';
+ import { useChannel, useClientTrigger } from "@harelpls/use-pusher";
const Example = () => {
- const channel = useChannel('presence-danger-zone');
+ const channel = useChannel("presence-ca");
const trigger = useClientTrigger(channel);
const handleClientEvent = () => {
- trigger('Pew pew');
+ trigger("Pew pew");
};
return <button onClick={handleClientEvent}>Fire</button>;
@@ -230,34 +247,34 @@ Typescript
Testing
- Typed PusherMock, PusherChannelMock and PusherPresenceChannelMock utils are provided based on pusher-js-mock (thanks mate 🙏). Use these to stub out the client and channels, with an additional emit method on the channel classes.
+ I've teamed up with @nikolalsvk on pusher-js-mock to bring y'all a great pusher mock.
Testing emitted events with jest can be achieved using jest.mock and @testing-library/react (or enzyme, though your tests should reflect what the user should see NOT how the component handles events internally):
// Example.tsx
-import React from 'react';
-import { useChannel, useEvent } from '@harelpls/use-pusher';
+import React from "react";
+import { useChannel, useEvent } from "@harelpls/use-pusher";
const Example = () => {
const [title, setTitle] = useState();
- const channel = useChannel('my-channel');
- useEvent(channel, 'title', ({ data }) => setTitle(data));
+ const channel = useChannel("my-channel");
+ useEvent(channel, "title", ({ data }) => setTitle(data));
return <span>{title}</span>;
};
// Example.test.tsx
-import { render, act } from '@testing-library/react';
-import { PusherMock, PusherChannelMock } from '@harelpls/use-pusher';
+import { render, act } from "@testing-library/react";
+import { PusherMock, PusherChannelMock } from "pusher-js-mock";
// mock out the result of the useChannel hook
const mockChannel = new PusherChannelMock();
-jest.mock('@harelpls/use-pusher', () => ({
- ...require.requireActual('@harelpls/use-pusher'),
+jest.mock("@harelpls/use-pusher", () => ({
+ ...require.requireActual("@harelpls/use-pusher"),
useChannel: () => mockChannel,
}));
-test('should show a title when it receives a title event', async () => {
+test("should show a title when it receives a title event", async () => {
// mock the client
- const client = { current: new PusherMock('client-key', { cluster: 'ap4' }) };
+ const client = new PusherMock("client-key", { cluster: "ap4" });
// render component and provider with a mocked context value
const { findByText } = render(
@@ -267,12 +284,17 @@ Testing
);
// emit an event on the mocked channel
- act(() => mockChannel.emit('title', { data: 'Hello world' }));
+ act(() => mockChannel.emit("title", { data: "Hello world" }));
// assert expectations
- expect(await findByText('Hello world')).toBeInTheDocument();
+ expect(await findByText("Hello world")).toBeInTheDocument();
});
Check out the example tests for testing presence channels.
+
+ React Native
+
+ This package comes with React Native support. Import your PusherProvider from @harelpls/use-pusher/react-native instead of the default @harelpls/use-pusher. All exports (except testing utils) are re-exported from there.
+ import { PusherProvider, useChannel } from "@harelpls/use-pusher/react-native";
Contributing
@@ -299,10 +321,10 @@ License
"PusherProvider"
-
- "mocks"
+ "react-
native/PusherProvider"
-
- "types"
+ "test
Utils"
-
"use
Channel"
diff --git a/docs/interfaces/_types_.pushercontextvalues.html b/docs/interfaces/_types_.pushercontextvalues.html
deleted file mode 100644
index ddc2873..0000000
--- a/docs/interfaces/_types_.pushercontextvalues.html
+++ /dev/null
@@ -1,359 +0,0 @@
-
-
-
-
-
- PusherContextValues | @harelpls/use-pusher
-
-
-
-
-
-
-
-
-
-
- Interface PusherContextValues
-
-
-
-
-
-
-
- Hierarchy
-
- -
- PusherContextValues
-
-
-
-
- Index
-
-
-
- Properties
-
- -
- client
-
- -
- trigger
-
-
-
-
-
-
- Properties
-
-
- Optional client
-
-
-
-
-
- Optional trigger
-
-
-
-
-
-
-
-
-
-
- Generated using TypeDoc
-
-
-
-
-
-
diff --git a/docs/interfaces/_types_.pusherproviderprops.html b/docs/interfaces/_types_.pusherproviderprops.html
deleted file mode 100644
index 058dbf1..0000000
--- a/docs/interfaces/_types_.pusherproviderprops.html
+++ /dev/null
@@ -1,1269 +0,0 @@
-
-
-
-
-
- PusherProviderProps | @harelpls/use-pusher
-
-
-
-
-
-
-
-
-
-
- Interface PusherProviderProps
-
-
-
-
-
-
-
- Hierarchy
-
- -
- Options
-
- -
- PusherProviderProps
-
-
-
-
-
-
- Index
-
-
-
- Properties
-
- -
- activity
- -
- auth
-
- -
- auth
- -
- auth
- -
- authorizer
-
- -
- client
- -
- cluster
-
- -
- defer
-
- -
- disable
- -
- disabled
- -
- enable
- -
- enabled
- -
- encrypted
-
- -
- forceTLS
-
- -
- http
- -
- http
- -
- https
- -
- ignore
- -
- pong
- -
- stats
- -
- timeline
- -
- trigger
- -
- unavailable_
- -
- value
-
- -
- ws
- -
- ws
- -
- ws
- -
- wss
-
-
-
-
-
-
- Properties
-
-
- Optional activity
-
-
-
-
-
- Optional auth
-
-
-
-
-
- Optional auth
-
-
-
-
-
- Optional auth
-
-
-
-
-
- Optional authorizer
-
-
-
-
-
- client
-
-
-
-
-
- cluster
-
-
-
-
-
- Optional defer
-
-
-
-
-
- Optional disable
-
-
-
-
-
-
- Optional disabled
-
-
-
-
-
- Optional enable
-
-
-
-
-
-
- Optional enabled
-
-
-
-
-
- Optional encrypted
-
-
-
-
-
- Optional forceTLS
-
-
-
-
-
- Optional http
-
-
-
-
-
- Optional http
-
-
-
-
-
- Optional https
-
-
-
-
-
-
- Optional
- ignore
-
-
-
-
-
- Optional pong
-
-
-
-
-
- Optional stats
-
-
-
-
-
- Optional timeline
-
-
-
-
-
- Optional trigger
-
-
-
-
-
-
- Optional unavailable_
-
-
-
-
-
- Optional value
-
-
-
-
-
- Optional ws
-
-
-
-
-
- Optional ws
-
-
-
-
-
- Optional ws
-
-
-
-
-
- Optional wss
-
-
-
-
-
-
-
-
-
-
- Generated using TypeDoc
-
-
-
-
-
-
diff --git a/docs/modules/_mocks_.html b/docs/interfaces/_usepresencechannel_.usepresencechannelvalue.html
similarity index 67%
rename from docs/modules/_mocks_.html
rename to docs/interfaces/_usepresencechannel_.usepresencechannelvalue.html
index 7bbb8b0..4a0ec9b 100644
--- a/docs/modules/_mocks_.html
+++ b/docs/interfaces/_usepresencechannel_.usepresencechannelvalue.html
@@ -3,7 +3,7 @@
- "mocks" | @harelpls/use-pusher
+ usePresenceChannelValue | @harelpls/use-pusher
@@ -56,72 +56,63 @@
Globals
-
- "mocks"
+ "usePresenceChannel"
+
+ -
+ usePresenceChannelValue
- External module "mocks"
+ Interface usePresenceChannelValue
+
+
+
+
-
-
- Callback
-
+
+
+
@@ -132,47 +123,71 @@
+
+
+
+ Hook return value
+Hierarchy
+-
+
-
+ {}
+
-
+
- + usePresenceChannelValue + +
+
Index
-
-
-
Classes
- -Type aliases
+Properties
Type aliases
-CallbackSignature
-
+ Properties
+Optional channel
+ -
-
Type declaration
--
-
-
-
-
-
-
-
-
-
-
Parameters
--
-
-
-
data: any
-
- -
-
Optional metadata: any
-
-
Returns void
-
- -
-
- -
-
Returns voidGlobals
-
- "
PusherProvider"
-
- -
- "mocks"
+ "
PusherProvider"
-
- "types"
+ "react-
native/PusherProvider"
-
- "use
Channel"
+ "testUtils"
-
- "use
ClientTrigger"
+ "useChannel"
-
- "use
Event"
+ "useClientTrigger"
-
- "use
PresenceChannel"
+ "useEvent"
+
+ -
+ "use
PresenceChannel"
-
- "use
Pusher"
+ "usePusher"
-
- "use
Trigger"
+ "useTrigger"
diff --git a/docs/modules/_pusherprovider_.html b/docs/modules/_pusherprovider_.html
index 997faab..430f05f 100644
--- a/docs/modules/_pusherprovider_.html
+++ b/docs/modules/_pusherprovider_.html
@@ -1,651 +1,287 @@
-
+
-
-
-
- "PusherProvider" | @harelpls/use-pusher
-
-
-
-
-
-
-
-
-
-
- External module "PusherProvider"
-
-
-
-
-
-
-
- Index
-
-
-
- Variables
-
- -
- Pusher
- -
- __
-
-
-
- Functions
-
- -
- Pusher
-
-
-
-
-
-
- Variables
-
-
- Const Pusher
-
-
-
-
-
-
- Const __
-
-
-
-
-
- Functions
-
-
- Const Pusher
-
-
-
-
- -
-
-
-
-
- Provider that creates your pusher instance and provides it to child hooks
- throughout your app. Note, you can pass in value={{}} as a prop if you'd
- like to override the pusher client passed. This is handy when simulating
- pusher locally, or for testing.
-
-
-
- Parameters
-
- -
-
- __namedParameters: { children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal; clientKey: string; cluster: "mt1" | "us2" | "us3" | "eu" | "ap1" | "ap2" | "ap3" | "ap4"; defer: boolean; props: props; triggerEndpoint: undefined | string }
-
-
- -
-
- children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal
-
-
- -
-
- client
-
- -
-
- cluster: "mt1" | "us2" | "us3" | "eu" | "ap1" | "ap2" | "ap3" | "ap4"
-
-
- -
-
- defer: boolean
-
-
- -
-
- props: props
-
-
- -
-
- trigger
-
-
-
-
-
- Returns Element
-
-
-
-
-
-
-
-
-
-
-
- Generated using TypeDoc
-
-
-
-
-
-
+
+
+
+ "PusherProvider" | @harelpls/use-pusher
+
+
+
+
+
+
+
+
+
+
+ External module "PusherProvider"
+
+
+
+
+
+
+
+ Index
+
+
+
+ Variables
+
+ - Pusher
Context
+ - __
PusherContext
+
+
+
+ Functions
+
+ - Pusher
Provider
+
+
+
+
+
+
+ Variables
+
+
+ Const PusherContext
+
+
+
+
+
+ Const __PusherContext
+
+
+
+
+
+ Functions
+
+
+ Const PusherProvider
+
+
+
+
+ -
+
+
+
+
Provider that creates your pusher instance and provides it to child hooks throughout your app.
+ Note, you can pass in value={{}} as a prop if you'd like to override the pusher client passed.
+ This is handy when simulating pusher locally, or for testing.
+
+
+ Parameters
+
+ -
+
__namedParameters: { _PusherRuntime: Pusher; children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal; clientKey: undefined | string; cluster: undefined | string; defer: boolean; props: props; triggerEndpoint: undefined | string }
+
+ -
+
_PusherRuntime: Pusher
+
+ -
+
children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal
+
+ -
+
clientKey: undefined | string
+
+ -
+
cluster: undefined | string
+
+ -
+
defer: boolean
+
+ -
+
props: props
+
+ -
+
triggerEndpoint: undefined | string
+
+
+
+
+ Returns Element
+
+
+
+
+
+
+
+
+
+
+ Generated using TypeDoc
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/modules/_types_.html b/docs/modules/_react_native_pusherprovider_.html
similarity index 70%
rename from docs/modules/_types_.html
rename to docs/modules/_react_native_pusherprovider_.html
index dcb2fe0..941b1d4 100644
--- a/docs/modules/_types_.html
+++ b/docs/modules/_react_native_pusherprovider_.html
@@ -3,7 +3,7 @@
- "types" | @harelpls/use-pusher
+ "react-native/PusherProvider" | @harelpls/use-pusher
@@ -56,10 +56,10 @@
Globals
-
- "types"
+ "react-native/PusherProvider"
- External module "types"
+ External module "react-native/PusherProvider"
-
-
-
-
- External module "PusherProvider"
-
-
-
-
-
-
-
-
-
-
- Const Pusher
-
-
-
-
-
-
- Const __
-
-
-
-
-
-
-
- Const Pusher
-
-
-
-
- Index
-
-
-
-
-
-
- Variables
--
-
-
- Pusher
Context -
- -
- __
Pusher Context -
-
Functions
--
-
-
- Pusher
Provider -
-
Variables
-Const Pusher
-
-
-
- Const __
-
-
- Functions
-Const Pusher
- -
-
-
-
-
-
-
- ----
- Provider that creates your pusher instance and provides it to child hooks - throughout your app. Note, you can pass in value={{}} as a prop if you'd - like to override the pusher client passed. This is handy when simulating - pusher locally, or for testing. -
-Parameters
--
-
-
-
- __namedParameters: { children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal; clientKey: string; cluster: "mt1" | "us2" | "us3" | "eu" | "ap1" | "ap2" | "ap3" | "ap4"; defer: boolean; props: props; triggerEndpoint: undefined | string } -
--
-
-
-
- children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal -
-
- -
-
- client
-Key: string -
- -
-
- cluster: "mt1" | "us2" | "us3" | "eu" | "ap1" | "ap2" | "ap3" | "ap4" -
-
- -
-
- defer: boolean -
-
- -
-
- props: props -
-
- -
-
- trigger
-Endpoint: undefined | string -
-
- -
-
- Returns Element -
-
- -
-
Generated using TypeDoc
-
+
+
+
+
+ External module "PusherProvider"
+
+
+
+
+
+
+
+
+
+
+ Const Pusher
+
+
+
+
+
+ Const __
+
+
+
+
+
+
+
+ Const Pusher
+
+
+
+
+ Index
+
+
+
+
+
+
+ Variables
+-
+
- Pusher
Context
+ - __
Pusher Context
+
Functions
+-
+
- Pusher
Provider
+
Variables
+Const PusherContext
+
+
+ Const __PusherContext
+
+
+ Functions
+Const PusherProvider
+ -
+
+
-
+
-
+
+ ++++
Provider that creates your pusher instance and provides it to child hooks throughout your app. + Note, you can pass in value={{}} as a prop if you'd like to override the pusher client passed. + This is handy when simulating pusher locally, or for testing.
+Parameters
+-
+
-
+
__namedParameters: { _PusherRuntime: Pusher; children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal; clientKey: undefined | string; cluster: undefined | string; defer: boolean; props: props; triggerEndpoint: undefined | string }
+-
+
-
+
_
+Pusher Runtime: Pusher
+ -
+
children: undefined | null | string | number | false | true | {} | ReactElement<any, string | ((props: P) => ReactElement | null) | {}> | ReactNodeArray | ReactPortal
+
+ -
+
client
+Key: undefined | string
+ -
+
cluster: undefined | string
+
+ -
+
defer: boolean
+
+ -
+
props: props
+
+ -
+
trigger
+Endpoint: undefined | string
+
+ -
+
Returns Element
+
+ -
+
Generated using TypeDoc
+Index
Interfaces
+References
+Functions
+References
+__PusherContext
+ Re-exports __PusherContext
+ Functions
+Const PusherProvider
+ -
+
+
-
+
-
+
+ ++++
Wrapper around the core PusherProvider that passes in the Pusher react-native lib
+Parameters
+-
+
-
+
props: PusherProviderProps & { children?: ReactNode }
+
+
Returns Element
+
+ -
+
Initialize PusherChannelMock with callbacks object.
-