@lighthouse/sdk

Lighthouse API Interface

A data library for clients to interface with Lighthouse API, built on 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-api-interface'

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)

Adding a New CRUD module

Most of our resources follow a RESTful CRUD pattern, so it's easy to add new modules to the interface. 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