A library that exposes matrix-js-sdk state via Redux
Matrix Redux Wrap was motivated by the need to expose the Matrix protocol via a Redux store. The matrix-js-sdk API does not expose a Redux-like pattern through which data flows but rather a number of asyncronous HTTP-request wrappers and a number of models that encapsulate the objects within the Matrix protocol. These models are updated by a mixture of server responses and API calls and do not necessarily lend themselves to simple mental models or the ability to be incorporated into frameworks such as Flux and Redux.
Wrapping matrix-js-sdk is not the ideal solution. Ideally, the logic contained within it (for handling the Matrix-specific long-polling etc.) could be split out into a special Asynchronous Action Creator. A reducer could be written to handle the dispatched actions and update the store accordingly. However, the complexity of this task iss greater than creating Matrix Redux Wrap, which harnesses the existing logic of the js-sdk whilst paying the price of duplicating js-sdk model state.
For examples, see the examples directory.
Simple usage:
const { wrapSyncingClient, matrixReduce } = require('matrix-redux-wrap');
const Matrix = require('matrix-js-sdk');
let state = {};
const dispatch = (action) => {
state = matrixReduce(action, state);
const roomCount = Object.keys(state.mrw.wrapped_state.rooms).length;
console.info('You are in ' + roomCount + ' rooms');
}
// initialise store
dispatch(undefined);
const syncClient = Matrix.createClient({
baseUrl: "https://my.home.server",
userId: "@myusername:my.home.server",
accessToken: "myaccesstoken12345",
});
wrapSyncingClient(syncClient, dispatch);
syncClient.startClient();
Output:
...
You are in 1234 rooms
You are in 1234 rooms
You are in 1234 rooms
...
Below is a quick explanation of the provided API for using matrix-redux-wrap. For full examples of how these functions can be used, see the examples directory.
asyncAction(stateKey, promise) => (dispatch) => {...}
Returns a function that calls the dispatch
argument asyncronously as such:
These actions will have namespaced type
fields of:
mrw.wrapped_api.pending
mrw.wrapped_api.success
mrw.wrapped_api.failure
Each of these have different fields present and all can be passed to
matrixRedux
to update the mrw.wrapped_api
state.
{
type: "mrw.wrapped_api.pending",
method: stateKey,
pendingState: ...,
id: "bfadef89"
}
method
: the stateKey
given to asyncAction
id
: an random opaque identifier for this call to asyncAction
{
type: "mrw.wrapped_api.success",
method: stateKey,
result: ...,
id: "bfadef89"
}
method
: see aboveid
: an random opaque identifier that refers to the previously dispatched "pending" actionresult
: the value that promise
resolved to{
type: "mrw.wrapped_api.failure",
method: stateKey,
error: ...,
id: "bfadef89"
}
method
, id
: see aboveerror
: the value that the promise
was rejected withwrapSyncingClient(matrixClient) => void
When given a matrix-js-sdk
MatrixClient instance, it will dispatch an action for each event
emitted by the instance, taking certain keys from the event, assigning them to fields on the
action. Once a client instance is passed to the function, the caller calls startClient
to
start the long-polling process that will cause the instance to emit events.
This creates actions of the following shape:
{
type: 'mrw.wrapped_event',
emittedType: 'Room.timeline',
emittedArgs: wrappedArgs,
}
matrixReduce
can be used to reduce these actions to the current state of the matrix client
as exposed in the state under the mrw
key.
matrixReduce(action, state) => newState
Reduces state according to the mrw.*
action passed, returning the new state. The state has
the following structure:
{
mrw: {
wrapped_api: {
login: {
loading: false,
status: 'success',
pendingState: ['username', 'password'],
lastResult: {
access_token: '12345',
},
},
},
wrapped_state: {
sync: {
state: 'SYNCING',
},
rooms: {
'!myroomid': {
members: {
'@userid:domain': {
membership: 'join',
name: 'Morpheus',
},
},
name: "some room name",
state: {
'm.room.member': {
'@userid:domain': {
id: '$some_awesome_event_id',
content: {
membership: 'join',
name: 'Morpheus',
avatarUrl: 'mxc://domain/flibblejibble',
},
ts: 1234,
},
},
'm.room.avatar': {
'': {
content: {
url: 'mxc://domain/flibblejibble',
},
},
},
},
timeline: [{
id: '$some_event_id',
type: 'm.room.message',
content: { body: 'hello, world!' },
sender: '@userid:domain',
ts: 12345,
}, {
id: '$some_other_event_id',
type: 'm.room.message',
content: { body: 'hello (again), world!' },
sender: '@userid:domain',
ts: 123456,
}, {
id: '$some_other_event_id2',
type: 'x.weird.event',
content: {},
sender: '@userid:domain',
ts: 1234567,
redactedBecause: {
sender: '@userid:domain',
ts: 12345678,
},
}],
receipts: {
'$some_event_id': {
'm.receipt': {
'@userid:domain': {
ts: 12345,
},
},
},
},
},
},
},
},
}