The purpose of the local data endpoint is to persist data across app restarts and machine reboots. Read more about this in our Data Introduction.

Warning: Local Data should not be used for personal information or secrets. It is stored in plain text and could be read if somebody gained access to the hardware.

Data sets

When storing data you have to specify a 'set' that the data goes into. This set is then also used to retrieve your data.

API

Create Set

Create a data set on the local machine. This can then be used to add data to via your application. The set persists across machine and application reboots.

// Create a set
OS.Data.local.createSet({
  name: 'leaderboard'
})
.then(console.log)
.catch(console.error)

Properties

Errors

Note that you will not get an error if the set already exists.

Delete Set

You can either programmatically delete a stored local set (example below) or use the machines UI to view and remove individual records or whole data sets. As you should be calling the createSet action every time your app starts there will not be a problem removing it in the UI as data will just be saved to the newly created and empty set.

Warning: If you delete a set all data within it is removed. This cannot be undone.

// Delete a set (and all the data within)
OS.Data.local.deleteSet({
  name: 'leaderboard'
})
.then(console.log)
.catch(console.error)

Save

All that is needed to save your data is the name of the set and the data you want to save. Your saved data can be an array or an object.

// Delete a set (and all the data within)
OS.Data.local.save({
  set: 'leaderboard',
  data: {
    name: 'Jack',
    score: 1200
  }
})
.then(console.log)
.catch(console.error)

Once the data is saved you will receive a response containing the unique index of the saved data within that set. For example {ok: true, set: 'leaderboard', index: 123}.

Properties

Get

When retrieving saved data you can either grab a whole set, a specific record or a limit of the set.

Whole set

OS.Data.local.get({
  set: 'leaderboard'
})
.then(console.log)

Partial set

Will grab the first 100 records.

OS.Data.local.get({
  set: 'leaderboard',
  limit: 100
})
.then(console.log)

Will grab the next 100 records.

OS.Data.local.get({
  set: 'leaderboard',
  from: 100,
  limit: 100
})
.then(console.log)

Single Record

OS.Data.local.get({
  set: 'leaderboard',
  index: 123
})
.then(console.log)

Properties

Update

Once data is saved to the set you can update or delete the record.

Updating

When updating you need to replace the whole record by an index, as all sets are arrays of objects/arrays.

OS.Data.local.update({
  set: 'leaderboard',
  index: 123,
  data: {
    foo: 'bar'
  }
})
.then(console.log)
.catch(console.error)

Often, you'll want to change some specific index based on what is currently in the data set. Here's an example of changing the score in a leaderboard for only one user:

OS.Data.local.get({  
  set: 'leaderboard'
}).then({records} => {

  const recordIndex = records.findIndex(r => r.name === 'Jack')
  const record = records[recordIndex]

  return OS.Data.local.update({
    set: 'leaderboard',
    index: recordIndex,
    data: {
      ...record,
      score: record.score + 1
    }
  })
})
.then(console.log)
.catch(console.error)

Properties

Delete

OS.Data.local.delete({
  set: 'leaderboard',
  index: 123
})
.then(console.log)
.catch(console.error)

Properties

Error codes

vendOS DevTools currently only supports two error codes for Data.local, but more granular codes will be added soon.