Upgrading

This page lists the breaking API changes between major versions of Kinto.js, as well as upgrade tips.

4.x to 5.x

  • The helper utils/reduceRecords was removed (#543)
  • collection.sync() now rejects asynchronously when the specified remote is invalid (#540)
  • incoming-changes hook now receives decoded records
  • Remote deletion conflicts are now resolved with decoded records
  • Last pull step in sync() only retrieves what was changed remotely while pushing local changes
  • importChanges() method was changed and now accepts a list of records and a strategy string
  • pushChanges() method was changed and now accepts a list of records
  • the database is not scanned anymore when pushing conflicts resolutions

3.x to 4.x

  • Deleted records are now decoded/encoded (#510)

2.x to 3.x

cleanRecord()

The cleanRecord() function from the collection module was dropped. Since local fields can be defined at the collection level, a cleanLocalFields() method was introduced instead.

SyncResultObject

The format of updates and deletions in the SyncResultObject has changed.

  • The updated list now contains a list of objects with old and new attributes
  • The deleted list now contains the full old record instead of just a stripped object containing id

Before with 2.X:

{
  ok: true,
  lastModified: 1434270764485,
  conflicts: [],
  errors:    [],
  created:   [],
  updated:   [{
    id: "08d5ae32-7f73-46bb-a8a6-c2bd80b15705",
    title: "blog post",
    _status: "synced",
    last_modified: 1434270764485
  }],
  skipped:   [],
  published: [],
  resolved:  [],
  deleted:   [{
    id: "131a100d-0732-494e-aa3c-e4a15e23eb77"
  }],
}

Now with 3.X:

{
  ok: true,
  lastModified: 1434270764485,
  conflicts: [],
  errors:    [],
  created:   [],
  updated:   [{
    old: {
      id: "08d5ae32-7f73-46bb-a8a6-c2bd80b15705",
      title: "draft",
      _status: "synced",
      last_modified: 1434243221112
    },
    new: {
      id: "08d5ae32-7f73-46bb-a8a6-c2bd80b15705",
      title: "blog post",
      _status: "synced",
      last_modified: 1434270764485
    }
  }],
  skipped:   [],
  published: [],
  resolved:  [],
  deleted:   [{
    id: "131a100d-0732-494e-aa3c-e4a15e23eb77",
    _status: "synced",
    last_modified: 1434223456788
  }],
}

1.x to 2.x

Kinto.js 2.x introduces general usage of transactions in database adapters. This change doesn't impact the Collection API, so most users shouldn't be impacted by this change.

As localStorage doesn't support transactions, its support has been entirely dropped. If you were using it in a Kinto.js 1.x project, please switch to using the default IndexedDB one when upgrading to Kinto.js 2.x.

The BaseAdapter interface has been updated to reflect the now mandatory reliance on transactions:

  • The Adapter#create(), #update() and #delete() methods are now gone;
  • The Adapter#execute() method is now to be used whenever you want to write to the database.

Any code directly invoking adapter methods should be updated to reflect this change, by calling #execute() instead of atomic operations; so instead of writing:

db.create({id: 1, title: "foo"})
  .then(_ => db.create({id: 2, title: "bar"}));

You now need to write:

db.execute(transaction => {
  transaction.create({id: 1, title: "foo"});
  transaction.create({id: 2, title: "bar"});
})

Note

Once again, you usually don't have to worry about this change if you're only relying on the Collection public API, where Collection#create() and friends are still available.