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

Publishing

This repo is designed to publish automatically to npm when a PR is merged into master. For this process to run smoothly you will need to do two things, set a GitHub label on the project of either minor or patch, and then merge the PR. The package.json scripts should not be run manually as this can generate artifacts that prevent the automatic publishing process from running smoothly.

Process

1. Create a new branch, make your changes, push it up to GitHub then create a new PR.
2. Add a GitHub label to the PR, you can do this from the sidebar on the GitHub landing page for the PR.

• Use the tag minor if there's no breaking changes and you're adding a semver feature
• Use the tag patch if there's no breaking changes and you're adding a semver bug fix

3. Get your PR reviewed and approved then merge the PR back to master
4. This should kick off the deployment process and automatically build and publish the latest version of the sdk to npm.

Developing Locally

You can replace a node_module dependency downloaded from npm with a local copy of that module. This can be done using yarn link to create a symlink between the two repos that allows you to use the local copy instead. With this technique you can create a link from the web repo to this repo while you're developing. Then you can develop locally without having to publish multiple canary builds of this repo to npm. Once you've setup your link you can run a watcher in both the web and sdk projects so any changes are built automatically and you can debug live.

Create a symlink from web to your local sdk

1. Open a new Terminal window and navigate into your sdk repo folder
2. Run the command yarn link
3. Change the directory so that you're in the web repo folder
4. Run the command yarn link @lighthouse/sdk

You should now be able to make changes in your local sdk project and they will be available in your web project immediately.

Run the project with automatic builds

If you open two terminals and run yarn start from the web repo and yarn dev from the sdk repo then a change to sdk will trigger a build on save and when that build is finished it will automatically trigger a fresh build and deploy of web. You can use this to live debug in the browser locally.

Cleanup

Once you're done you can remove the symlink with the yarn unlink command, it works in a similar fashion to creating a link.

1. Open a new Terminal window and navigate into your sdk repo folder
2. Run the command yarn unlink
3. Change the directory so that you're in the web repo folder
4. Run the command yarn unlink @lighthouse/sdk

You will now be back to using the version of ths sdk that you downloaded from npm