This page lists the breaking API changes between major versions of Kinto.js, as well as upgrade tips.
The v13.0.0 release of kinto.js
is the first release that's using our new modern build system, which targets modern browsers supporting the latest JavaScript features. As such, if you were relying on polyfills in our previous releases, you'll need to make sure that your build system is updated to account for these changes. In particular, you'll need to ensure that your build system is setup for async
/await
. Each build system has a different way of enabling support, so we can't detail them here. That being said, if you're using Babel, you most likely want @babel/plugin-transform-runtime.
- The
dbPrefix
option in theKinto
andCollection
constructors was dropped in favor of thedbName
field in theadapterOptions
.
Database Schema Change
This version introduces a major change: instead of having one IndexedDB database per collection (named {bucket}/{collection}
), we now have only one database (called KintoDB
by default) which stores records indexed by collection.
If you are upgrading and want your data to be automatically migrated, set the adapterOptions.migrateOldData
to true
in the Kinto()
constructor, or false
otherwise. Note that the old database will also be deleted.
const db = new Kinto({
adapterOptions: {
migrateOldData: true,
}
});
const tasks = db.collection("tasks");
The database (named KintoDB
by default) will have two stores records
and timestamps
.
The records
store now looks like this:
+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| Primary Key | Data |
+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| ["blog/articles", "df85ec54-87aa-405d-bfc5-bcc96adef7ae"] | {_cid: "blog/articles", id: "df85ec54-87aa-405d-bfc5-bcc96adef7ae", _status: "created"} |
| ["blog/articles", "161c26be-6f84-49e6-973c-533a5950223d"] | {_cid: "blog/articles", id: "161c26be-6f84-49e6-973c-533a5950223d", _status: "deleted"} |
| ["default/tasks", "29db6353-276a-4c77-82ef-be937fbbcfa3"] | {_cid: "default/tasks", id: "29db6353-276a-4c77-82ef-be937fbbcfa3", _status: "sync", last_modified: 1346} |
| ["default/tasks", "c91dcef8-062c-481a-8c06-bfa344f2837d"] | {_cid: "default/tasks", id: "c91dcef8-062c-481a-8c06-bfa344f2837d", _status: "sync", last_modified: 1142} |
+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
The timestamps
store now looks like this:
+-----------------+--------------------------------------------+
| Primary Key | Data |
+-----------------+--------------------------------------------+
| "blog/articles" | {cid: "blog/articles", value: 12958536703} |
| "default/tasks" | {cid: "default/tasks", value: 14896689683} |
+-----------------+--------------------------------------------+
- When fixing #691, the types of values in SyncResultObject.resolved were changed. Previously, they were just the resolution for a given record; now, they are {accepted, rejected}, with accepted being the new value. Any code using elements of this list (e.g.
SyncResultObject.resolved[i]
) should now use the accepted property of that element (e.g.SyncResultObject.resolved[i].accepted
).
- As part of #640, some of the expectations of remote transformers were changed. Previously, a remote transformer could return anything for a deleted record, and that record would still be deleted. Now, if a transformer changes a record's
_status
, it will be respected.
- The open() and close() methods were removed from BaseAdapter (#599). These were never called by Kinto code. You can continue to define these methods and invoke them as you like.
- The Firefox storage adapter was removed (#562). Development on this module has been moved to the Firefox Mercurial repository.
- 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 stringpushChanges()
method was changed and now accepts a list of records- the database is not scanned anymore when pushing conflicts resolutions
- Deleted records are now decoded/encoded (#510)
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.
The format of updates and deletions in the SyncResultObject
has changed.
- The
updated
list now contains a list of objects withold
andnew
attributes - The
deleted
list now contains the full old record instead of just a stripped object containingid
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
}],
}
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"});
})
Once again, you usually don't have to worry about this change if you're only relying on the
Collection
public API, whereCollection#create()
and friends are still available.