What's new in v0.16
This is a distillation of what’s new in Orbit v0.16, intended as a reference for developers who need to upgrade their apps and libraries from v0.15.
New packages have been introduced since v0.15:
@orbit/storepackage has been deprecated in favor of a new
@orbit/memorypackage (which contains all the same functionality). This clears the way for future Orbit packages that contain higher level Model and Store primitives.
@orbit/record-cache- Extracts the
@orbit/memoryas well as its associated processors to provide an abstract base for creating sources that access and maintain a complete set of records. Sync and async versions of caching logic are supported. This package is now used not only by
@orbit/memory, but also by
@orbit/serializers- A set of interfaces and serializer classes that can be used by sources to serialize / deserialize primitive data types. Serializers are now used within the JSONAPISerializer to handle types such as
number. Serializers for custom types can also be registered (see https://github.com/orbitjs/orbit/pull/591 for a complete description).
@orbit/identity-map- A new identity map for managing model instances. Intended for building Model and Store primitives.
Orbit continues to ship with a matrix of distributions that combine different module types (ESM, CJS, and even AMD) with language levels (ES5 and ES2017).
Because the codebase now extensively uses
await as well as
for ... of, the ES5 builds now must be paired with the
package to ensure that the
regeneratorRuntime global is defined.
The default builds targeted by each package’s
module are now
ES-latest. These builds are as small and performant as possible, and of course
can be further processed with Babel if necessary.
Important: There were still some build issues in v0.16.0, which have been resolved in v0.16.1. Please upgrade!
Orbit v0.16 introduces the concept of “hints”, which allow request listeners to influence the results that a source returns from that request.
The main reason to use hints is to allow sources to take into account outside
information when processing a request. For instance, let’s say that a user
queries a memory source and wants records returned in the same order they’re
returned from the server. If the server is using a complex sorting algorithm, it
may be impossible to recreate that same logic (and full dataset) on the client
Read more about using hints in the guide to coordination strategies.
rebase method has been added to
rebase method works similarly to a git rebase. After a memory source has been forked, there will be two sources: a base and a fork. Both may be updated with transforms. When
fork.rebase() is called, any commits on the fork will be undone, the commits to the base store since the fork point will be replayed on the fork, and then the commits on the fork will be replayed on top.
Relationships in your schemas can now specify multiple possible models as an array in the
model field. For example:
In this way, a star can have both planets and moons as
celestialObjects. Orbit is now one step closer to full JSON:API compliance! ⭐️
@orbit/jsonapi source now does its request processing in a new customizable
This release introduces preliminary and partial support for JSON:API Operations in
@orbit/jsonapi, which are expected to be introduced to the JSON:API spec soon. Serialization and deserialization support for operations has been added to the
JSONAPISerializer class. Further support will be added to the
JSONAPISource for processing requests that include operations.
While testing the hinting feature and its interactions with different source interfaces, Paul Chavard (@tchak) uncovered some scenarios in which hints could fail to return expected results (see #612). This led to a quest to understand those problems and fix them across source interfaces. Unfortunately, in order to guarantee predictable and consistent behavior, we needed to move some responsibilities to source implementations that were previously handled in Orbit’s private implementations of those interfaces.
Thus, if you’re writing sources, please ensure that you do the following in any of your internal implementation methods that work with transforms (e.g.
transformLogfor the requested transform to see if work actually needs to be done before doing it.
transformedfor any transforms that are applied.
By moving these responsibilities to source implementations, we allow more flexibility in implementations. For instance,
_update can ignore re-applying transforms that may have been sync’d via
beforeUpdate listeners, while still returning results that are specified via the
In order to update the
@orbit/memory source to both support hints and respond to the above requirements, the following changes were needed:
Please review your custom sources to make any necessary changes. If your methods don’t support hints, the diffs should rather small, like in the
_sync method above. If you want to support
hints, you’ll need to provide alternate code paths for when hints are provided and not, like in the
_query methods above.
We’re planning to include a guide to writing your own sources with the v0.16 release to clarify all these responsibilities.
@orbit/jsonapisource now supports the
Updatableinterface, which can be more user-friendly to directly interact with than the
pagesupport has been added to
findRelatedRecordsqueries and all the standard implementations.
#671 Explicit source
deactivatemethods have been added to provide hooks to ensure that sources have performed any setup and teardown steps prior to processing. These hooks are automatically called as part of coordinator activation / deactivation, and sources themselves will auto-activate by default (note that this is an async process that can be watched via the new
#673 Whenever tasks are cancelled and removed from a queue (such as a source’s
syncQueue), the promise associated with that task will now always be rejected (if it hasn’t already settled). You can control the rejection error or use the default error.
replaceRecordop in favor of
deprecateonly on OrbitGlobal.
Listenerinterface and remove support for explicit binding object in listeners.
Many thanks to the committers who made v0.16 possible:
- Alexey (@Raiondesu)
- Andrey Mikhaylov (@lolmaus)
- Bernhard Halbartschlager (@Bernhard—H)
- Dan Gebhardt (@dgeb)
- Gerald Gayowsky (@ggayowsky)
- Luke Melia (@lukemelia)
- Miguel Camba (@cibernox)
- Paul Chavard (@tchak)
- Paweł Bator (@jembezmamy)
- Pieter-Jan Vandenbussche (@PieterJanVdb)
- Simon Ihmig (@simonihmig)