@lighthouse/sdk

Lighthouse SDK

SDK for communicating with the Lighthouse API, built with Redux.

Aims

• To abstract API data communication enabling re-use across multiple clients (Web, Native)
• Standardise data structures, especially for basic CRUD resources
• Logic should be easily testable
• Ease development cycle with data utilities, e.g. Replays, Undos, Fast-Forward

Importing/Using a module with React/Redux

import { getModule } from '@lighthouse/sdk'

const listId = 'all' // optional, defaults to 'default' in all module methods
const location = getModule('location')

@connect(
  mapStateToProps,
  mapDispatchToProps,
)
export default class MyComponent extends Component {
  // build component...
}

// React Redux
function mapStateToProps(state) {
  const listOpts = { /* sort options etc. */ }
  const locationSelectors = location.selectors(state)
  return {
    // returns an array of location resources
    locations: locationSelectors(listId).list(listOptions),
    // returns the current location resrouce
    currentLocation: locationSelectors.current(),
  }
}

function mapDispatchToProps(dispatch) {
  const { query, save, findById, remove } = location
  return {
    fetch: params => dispatch(query(listId, params)),
    save: (params, payload, id) => dispatch(save(params, payload, id)),
    findById: id => dispatch(findById(id)),
    remove: id => dispatch(remove(id)),
  }
}

Optimistic Updates

You can use the optimistic option to specify the new entities or updates to entities should be stored in the cache as soon as the request is sent. This improves the experience of the UX in some situations, resulting in a perceived performance increase and instant feedback.

It is particular useful for a chat interface where waiting for new messages to be persisted to the API hampers the experience (loading spinners). Whereas more often than not you can be sure that a send message request will be successful, so you can treat it as sent as soon as it is created and if it does fail, retry the request.

To make an optimistic update to save requests, pass the optimistic option to the params option, e.g:

// assuming we have setup messages module...
const params = {
  optimistic: true
}
const payload = {
  body: 'Hi Friend!'
}
// message will be available in cache as soon as request is made
message.save(params, payload)

Offline First

You can follow an offline-first workflow using the optimistic option as above. Here's how the offline-first flow works:

1. If optimistic param is detected in action creator, a redux-offline action is created for the request and the entity is assigned a temporary id value
2. redux-offline adds the request to its outbox, which it serially works over to send data to the server
3. If the server responds successfully to a redux-offline request, the entity will be updated in state with it's database id (_id) returned in the response
4. If the server rejects the request, a rollback action will be dispatched (define at time of making request). We use this action to mark the entity in the state as rolled-back so we can retry it if we want. We can identify these items in the cache via their state value of rolled-back and (if it was a new document) the fact it doesn't have an _id value in it's entity data

There's some things to keep in mind when working in an offline manner:

• It's only save/update requests that are affected by offline-first. If we need to get data from the server then we need to make a request for that which requires a network connection
• We can however use data previously requested from the server to submit new data when there is no network, just keep in mind that the data be out of date
• We detect offline state via APIs on the client. On mobile, this is via react-native NetInfo APIs and on the web it's the Network Information API
• Non-optimistic requests are handled by our request middleware. Both optimistic/non-optimistic requests use the request helper for making the requests (using the Fetch API) but the flows are handle by each middleware depending on the optimistic flag
• We use the redux-offline module to support our offline-first workflow. They have some pretty good documentation on the pattern, so it's worth referring to that project

Adding a New CRUD module

Most of our resources follow a RESTful CRUD pattern, so it's easy to add new modules to the sdk. To add a new CRUD module:

1. Create a folder for the resource in /modules. The simplest way is to clone an existing CRUD module, e.g. 'zone' and update the references in the index file and the test.
2. Add the new module reducer in /module/index.js along with with the other modules
3. Update the test for the root module /module/test/index.test.js which ensures the correct modules are correctly exported