V4 API Migration Notes

It is relatively simply to migrate an old report to v4. There are a few major changes to be aware of:

• Reliance on backup versions or iOS versions is deprecated. reports should instead try all methods and merge the results.
• Reports are no longer responsible for formatting the output. Instead, they declare a public API which allows the core to retrieve a uniform object based on the underlying raw data.
• The main reporting function returns a promise which resolves to raw backup data.
• The main report entrypoint was renamed to run()
• v4 Reports can be run as sub-reports, using the lib.run() function.
• file lookup APIs have been slightly been renamed for ease of use.

v4 Report Examples

There are examples of the new report module format in the _example.js report, as well as on the wiki

Steps

0. Update the main entrypoint

The main entrypoint is now exposed as run.

run(lib, { backup }) {
  // Run returns a promise.
  return new Promise((resolve, reject) => {
    resolve({})
  })

  /* lib exposes two properties:
  
   - lib.run(reportName, params)
     This allows us to run other reports such as getting file lists in the backup, etc.
  
   - lib.base
     This is the base path for where backups are stored on the system.
   */

   /*
     the backup object exposes a few different properties:
   
   - backup.id (backup id string)
   - backup.base (same as lib.base)
   - backup.path (root directory of the backup)

   - backup.getFileID(path, domain)
     This derives a file's id from the path, domain.

   - backup.getFileName(fileID)
     get the local filesystem path to a backup file given an ID.
     this does lookups to find it.

   - backup.openDatabase(fileID)
     returns a promise with the sqlite3 database object.
   */
}

1. Copy the old formatter.columns declaration to the main module, exporting it as output. All these properties should follow JavaScript camelCase naming conventions wherever possible.

This:

 // (in the reporting function)
 var result = program.formatter.format(apps, {
    program: program,
    columns: {
      'Bundle ID': el => el.bundleID,
      'Bundle Path': el => el.path
    }
})

Becomes:

module.exports = {
... 

  output: {
    bundleID: el => el.bundleID,
    path: el => el.path
  }
}

2. Refactor database opening to use promises.

var db = backup.getDatabase(DB_FILEID)
// ... use it

becomes:

backup.openDatabase(DB_FILEID)
   .then(db => {
      // ...use it
      resolve(data)
   })
   .catch(reject)