website logo
⌘K
πŸ–οΈIntroduction to hyper cloud
🍎Getting Started
😍What's New
Legacy Get Migration Guide
Blueberry Migration Guide
πŸ’ͺWorkshops
Deno Workshops
NodeJS Workshops
⚑Quickstarts
NodeJS Quickstarts
πŸ”ŒAPI Reference (hyper cloud)
🍎Basics
⚑hyper connect
πŸ”‘JWT Auth
πŸ’ΎData API
🏎️Cache API
πŸ”ŽSearch API
πŸ—„οΈStorage API
πŸ€“Queue API
πŸ”“Sign In
⚑Applications
βš™οΈSettings
πŸ”‘App Keys
πŸ‘₯Teams
Switching Between Accounts
Application Services
Application Service Instances
Adding a Queue Service
Adding a Search Service
Subscriptions
πŸ€‘Upgrade
πŸ“•Terminology
Parameters
πŸ’³Billing
Payment and Pricing Terms
πŸ’ΌLegal
Terms of Service
Acceptable Use Policy
Privacy Policy
πŸ•ΆοΈHyper Vision
Docs powered byΒ archbeeΒ 
14min

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.

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
}
ο»Ώ

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
ο»Ώ

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
ο»Ώ

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: {...}
}
ο»Ώ

ο»Ώ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
}
ο»Ώ

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
ο»Ώ

ο»Ώ

Updated 21 Feb 2023
Did this page help you?
Yes
No
UP NEXT
Blueberry Migration Guide
Docs powered byΒ archbeeΒ 
TABLE OF CONTENTS
Some Background
The Problem
A hyper Response shape
Migration Path
First Phase: On By Default
Second Phase: Off By Default
Third Phase: Remove the Header
hyper-connect breaking change
TL;DR