Legacy Get Migration Guide

This migration guide is to prepare customers for the upcoming change in the service framework api for retrieving Cache and Data documents by key and _id, respectively.

Some Background

Almost all hyper service apis return a common shape, referred to in this guide as the "hyper response shape". This shape looks something like:

interface HyperResponse {
  ok: boolean
  msg?: string
  status?: number
}

If ok is false, then msg and status may be provided for additional context into the error that occurred. For example, if a document is not found when Retrieving a Data Service document by _id, then a "hyper response shape" is returned with ok false and status 404.

Otherwise, if ok is true, a service api response will include a field on the "hyper response". For example, when Querying a Data Service, the "hyper response" will also contain docs fields. When Querying a Search Index, the "hyper response" will also contain a matches field.

With the hyper-connect client, similar to fetch, it will only throw if a 5xx status code is received from a request. Therefore, any other status codes, for example 4xx statuses, must be checked for by business logic. This is by design, as it forces developers to handle error cases in consumer code, without relying on their services tier to handle errors. These errors most likely have semantic meaning according to the business rules, and should be handled accordingly.

A common pattern is something like this:

const res = await hyper.data.query(...)

if (!res.ok) {
  // process the error, maybe even look at res.status
  throw new Error(res.msg)
}

const docs = res.docs
// do something with res.docs

The Problem

The exception to this "hyper response shape" convention have been when Retrieving a Data Service document by _id and Retrieving a Cache Service value by key. Instead of always returning a "hyper response shape", these apis would return the resource directly if found, and then a "hyper error response shape" only if an error occurred ie. the document or value was not found.

This divergence from the convention leads to some unergonomic usage in consumer code:

// The actual document is returned OR a hyper response shape with ok: false
const res = await hyper.data.get(...)

/**
 * This check is no longer reliable.
 * What if the document has an `ok` field and what if that field is `false`
*/
if (!res.ok) {
  ....
}

const doc = res // usually would have to typecast here

Checking the status has similar issues, in that what if the document has a status field?

Finally, TypeScript, which has become ubiquitous in the Node/JavaScript world, is not able to reconcile this overlap, forcing developers to typecast, or using @ts-ignore to get around the errors. This makes these apis a potential source of bugs and in consumer code.

To address this, we will be changing the behavior of these two apis to return a "hyper response shape", just like all of the other apis.

A hyper Response shape

For both Retrieving a Data Service document by _id and Retrieving a Cache Service value by key, the new response shape will look like this:

// a hyper response shape
{
  ok: true,
  doc: {...}
}

doc will contain the value retrieved from the service. To allow teams to migrate to this new shape, we have introduced a new header that can be used to incrementally adopt this new shape.

Migration Path

The X-HYPER-LEGACY-GETheader can be used to tell your hyper service whether to return the new "hyper response shape" or the legacy shape.

If set to true, your hyper service will return the legacy shape. If set to false , your hyper service will return the "hyper response shape".

This header can be used by consumers to allow incremental migration to the new shape, in a multi-phase approach.

First Phase: On By Default

Right now, by default, your hyper service will return the legacy shape, if the header is not provided.

This allows for teams to optionally set the X-HYPER-LEGACY-GET header to true when they are ready to adopt the new shape.

Second Phase: Off By Default

In a future major release, we will make a breaking change to default to the "hyper response shape", if the header is not provided

If your team is still not ready to use the new shape, you should explicitly set X-HYPER-LEGACY-GET to true to continue receiving the legacy shape

Third Phase: Remove the Header

In another future major release, we will remove the X-HYPER-LEGACY-GET header entirely, thus removing the legacy shape from the hyper service apis.

hyper-connect breaking change

We made a breaking change in hyper-connect@v0.6.0 to automatically set the X-HYPER-LEGACY-GET header to true. This is an easy way to adopt the new shape: bump your version and let TypeScript or your editor tell you where to make the updates.

TL;DR

We are changing Retrieving a Data Service document by _id and Retrieving a Cache Service value by key to return the following shape, instead of the document directly:

// a hyper response shape
{
  ok: true,
  doc: {...} // your value
}

Bump your hyper-connect version to 0.6.0 and start consuming the new shape:

// The actual document is returned OR a hyper response shape with ok: false
const res = await hyper.data.get(...)
// or hyper.cache.get(...)

// const oldDoc = res
if (!res.ok) {
  ...
}

// Instead of this
// const oldShape = res

// Now do this
const doc = res.doc