What's New
Legacy Get Migration Guide

14min
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.
If you're already using hyper-connect@>=0.6.0, then you don't need to worry about this; you're already using the new shape. :)
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:
TypeScript
|
interface HyperResponse {
  ok: boolean
  msg?: string
  status?: number
}
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.
For adapters, we encourage status to be some http status code (no point in re-inventing the wheel), but it is a convention, not a requirement
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.
Effectively, ok is a discriminating field between a "hyper success response" and a "hyper error response"
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:
TypeScript
|
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
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:
TypeScript
|
// 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
// 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:
TypeScript
|
// a hyper response shape
{
  ok: true,
  doc: {...}
}
// 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:
TypeScript
|
// a hyper response shape
{
  ok: true,
  doc: {...} // your value
}
// a hyper response shape
{
  ok: true,
  doc: {...} // your value
}
﻿
Bump your hyper-connect version to 0.6.0 and start consuming the new shape:
TypeScript
|
// 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
// 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
﻿
﻿