Workshop: NodeJS Hello World

28min
Intro
This example provides the steps to build a simple API using hyper and NodeJS. It includes:
hyper Data API﻿ : a scalable database solution with a clean separation from business logic and service implementation
hyper Cache API﻿ : a scalable cache solution that gives JSON document Key Value features with Time To Live functionality
hyper Search API ﻿ : a scalable search solution that makes it as simple as a click to spin up a search index
﻿Zod: a data validation utility that empowers the development team to manage their data model in the business layer of the application  
﻿expressJS: a nodejs application server framework
By the end of this workshop, you'll have an API service that allows users to create, update, list, view, search and delete video game documents.
hoppscotch showcasing workshop
﻿
Github
Whenever you get stuck at any point, take a look at this repo
Project setup
Before we get started we need to setup our hyper services, This is as simple as logging into the hyper dashboard and clicking add application - You can name the application whatever you like (ie. [initials]-video-game-api) and make sure that both the data and cache services are selected. Awesome!
Get the API Key
When the app is created, copy the Connection String on the keys tab, by clicking the copy icon to the right of the string.
Create a NodeJS/Express project
📝 You will need to have nodejs >= v14 installed and access to a code editor like visual studio code, and a command-line terminal window. You can download https://nodejs.org﻿
In a command-line terminal window type the following commands:
Shell
mkdir video-game-api
cd video-game-api
npm init -y
npm install express zod hyper-connect cors
npm install --save-dev nodemon dotenv
touch server.js
# make project esm
npx json -I -f package.json -e 'this.type="module"'
# create start script
npx json -I -f package.json -e 'this.scripts.start="nodemon -r dotenv/config server.js"'
# configure .env file
echo 'HYPER=[PASTE HYPER APP CONNECTION STRING HERE]' >> .env
mkdir video-game-api
cd video-game-api
npm init -y
npm install express zod hyper-connect cors
npm install --save-dev nodemon dotenv
touch server.js
# make project esm
npx json -I -f package.json -e 'this.type="module"'
# create start script
npx json -I -f package.json -e 'this.scripts.start="nodemon -r dotenv/config server.js"'
# configure .env file
echo 'HYPER=[PASTE HYPER APP CONNECTION STRING HERE]' >> .env
﻿
❓ If you have any problems installing the above tools, please reach out to our community slack. You can register at https://hyper.io/slack and go to the #getting startedchannel, and someone will help you out.
Shell
npm start
npm start
﻿
Building the App
Let's start building our API from scratch! 
Create Express App
Open the server.js file in your code editor and type the following:
JS
import express from 'express'
import cors from 'cors'
import { connect } from 'hyper-connect'

const app = express()
const hyper = connect(process.env.HYPER)

app.use(cors())

app.get('/', function (req, res) {
  res.send('Video Game API')
})

app.listen(3000)
console.log('API Server Running on port 3000')

import express from 'express'
import cors from 'cors'
import { connect } from 'hyper-connect'

const app = express()
const hyper = connect(process.env.HYPER)

app.use(cors())

app.get('/', function (req, res) {
  res.send('Video Game API')
})

app.listen(3000)
console.log('API Server Running on port 3000')
﻿
Open your browser to port 3000 and you should see:
Video Game API in text in the browser window!
Let's use a free API tool to talk to our API. https://hoppscotch.io/ 
Open hoppscotch in a new browser tab and set the method to be GET and enter in your server address: http://localhost:3000 - then click send - you should see the result 'Video Game API' in the response body.
Creating a Video Game Document
create a new file called Game.js - This file will contain our document schema, and a validation function
JS
import { z } from 'zod'

const Game = z.object({
  _id: z.string(),
  type: z.literal('game'),
  name: z.string(),
  company: z.string(),
  released: z.string().min(4).max(4).regex(/^([0-9]){4}$/)
})

/**
 * @param {Game} data
 */
export function validate(data) {
  return Game.parseAsync(data)
}
import { z } from 'zod'

const Game = z.object({
  _id: z.string(),
  type: z.literal('game'),
  name: z.string(),
  company: z.string(),
  released: z.string().min(4).max(4).regex(/^([0-9]){4}$/)
})

/**
 * @param {Game} data
 */
export function validate(data) {
  return Game.parseAsync(data)
}
﻿
🎓 This functionality is not hyper-related, but you always want to validate any data coming from a client or a service. (Soapbox 🧼 📦 ) Never trust the shape of the data and don't depend on your database to validate the shape, you will want to add custom business logic and you don't want to add this logic to your data service, it will create a maintenance nightmare over time.
Create API Endpoint to create a video game
In the server.js file lets create new express handler 
JS
... 
import { validate } from './Game'

...

app.post('/games', express.json(), function (req, res) {
  validate(req.body)
    .then(hyper.data.add)
    .then(result => result.ok ? res.send(result) : Promise.reject(result))
    .catch(error => res.status(err.status || 500).send(error))
})

... 


... 
import { validate } from './Game'

...

app.post('/games', express.json(), function (req, res) {
  validate(req.body)
    .then(hyper.data.add)
    .then(result => result.ok ? res.send(result) : Promise.reject(result))
    .catch(error => res.status(err.status || 500).send(error))
})

... 

﻿
🎓 The POST /games endpoint, uses hyper.data.add method to submit the game document to the data store, the validate method makes sure the document is the correct shape, but it could be a duplicate, this is where the response from hyper comes in, if the document _id already exists, this function will return a 409 error, document conflict.
You will want to add the API handler after the const declarations, but before the app.get handler.
Using hoppscotch, send a POST command to http://localhost:3000/games URL. It should return back a status of 500 and an error, showing that several elements are required!
Now, use the body tab in the hoppscotch UI to create our JSON document
JSON
{
    "_id": "game-1",
    "type": "game",
    "name": "Donkey Kong",
    "company": "Nintendo",
    "released": "1981"
}
{
    "_id": "game-1",
    "type": "game",
    "name": "Donkey Kong",
    "company": "Nintendo",
    "released": "1981"
}
﻿
You should see the response
JSON
{
    "ok": true,
    "id": "game-1"
}
{
    "ok": true,
    "id": "game-1"
}
﻿
⚡️ Easy Peasy - Just like that, we are adding data to our hyper data service!
Create a counter in our cache
Let`s add a game counter in our cache, this counter will count every game added to the data store.
First, create a incrementCounter utility method 
utils.js 
JS
import { connect } from 'hyper-connect'
const hyper = connect(process.env.HYPER)

const increment = result => result.count ? result.count + 1 : 1
const update = name => count => hyper.cache.set(name, { count })
const resolve = x => result => result.ok ? x : Promise.reject({ status: 500, error: 'Could not find cache' })

export function incrementCounter(type) {
  return function (x) {
    return hyper.cache.get(`${type}-counter`)
      .then(increment)
      .then(update(`${type}-counter`))
      .then(resolve(x))
  }

}
import { connect } from 'hyper-connect'
const hyper = connect(process.env.HYPER)

const increment = result => result.count ? result.count + 1 : 1
const update = name => count => hyper.cache.set(name, { count })
const resolve = x => result => result.ok ? x : Promise.reject({ status: 500, error: 'Could not find cache' })

export function incrementCounter(type) {
  return function (x) {
    return hyper.cache.get(`${type}-counter`)
      .then(increment)
      .then(update(`${type}-counter`))
      .then(resolve(x))
  }

}
﻿
🎓 This incrementCounter utility shows how composable hyper's API is, we are using a Promise chain to create a functional pipeline passing one result from one call to the other, until we get the final result. If for any reason an error occurs in this pipeline, it should prevent the rest of the pipeline from continuing. To create an even safer ADT, check out the Async module from the Crocs Library.
In the server.js let's modify the promise chain in the app.post handler 
JS
...
import { incrementCounter } from './utils.js'

...

app.post('/games', express.json(), function (req, res) {
  validate(req.body)
    .then(hyper.data.add)
    .then(incrementCounter('game'))
    .then(result => res.send(result))
    .catch(error => res.status(500).send(error))
})
...
import { incrementCounter } from './utils.js'

...

app.post('/games', express.json(), function (req, res) {
  validate(req.body)
    .then(hyper.data.add)
    .then(incrementCounter('game'))
    .then(result => res.send(result))
    .catch(error => res.status(500).send(error))
})
﻿
🎓 here we just add and extra chain method in the promise pipeline, called incrementCounter this method is a generic utility method that will increment any type proved by the caller, so if we add other models to our application, we can take advantage of this re-usable module to keep count stats on all models. 
Now add another game using hoppscotch 
JSON
{
    "_id": "game-2",
    "type": "game",
    "name": "Galaga",
    "company": "Nameco",
    "released": "1980"
}

{
    "_id": "game-2",
    "type": "game",
    "name": "Galaga",
    "company": "Nameco",
    "released": "1980"
}
﻿
Looking at our data
Using the hyper-vision tool, we can look at our data and cache services: https://vision.hyper.io - paste the connection string from the .env file, and go to the cache section, you should see a game-counter key, and the value should be { count: 1 } 
⚡️🕶 hyper-vision is a data explorer for your hyper services, you can checkout data, cache, and search services, it is a simple troubleshooting tool to verify you have data available in your system.
Get a game document by id
Its time to create the get document by id endpoint, GET /games/:id 
`server.js`
create a new API handler underneath the post handler:
JS
app.get('/games/:id', function (req, res) {
    hyper.data.get(req.params.id)
      .then(validate)
      .then(game => res.send(game))
      .catch(err => res.status(404).send({error: 'Not Found'}))
})
app.get('/games/:id', function (req, res) {
    hyper.data.get(req.params.id)
      .then(validate)
      .then(game => res.send(game))
      .catch(err => res.status(404).send({error: 'Not Found'}))
})
﻿
🎓 Using hyper.data.get we request the game document from the data service and validate that the document is correct, before we send it to the client. Just like incoming requests, we do not want to trust the data from the data store, we want to make sure it matches our document shape and specifications.
Using hoppscotch lets get a game document, modify the method to GET and change the URL to http://localhost:3000/games/game-1 then click on the send button.
Response
JSON
{
  "_id": "game-1",
  "type": "game",
  "name": "Donkey Kong",
  "company": "Nintendo",
  "released": "1979"
}
{
  "_id": "game-1",
  "type": "game",
  "name": "Donkey Kong",
  "company": "Nintendo",
  "released": "1979"
}
﻿
Get Game Counts
server.js NOTE: make sure you add this above the app.get('/games/:id') handler
JS
app.get('/games/count', function (req, res) {
  hyper.cache.get('game-counter')
    .then(result => result.count ? res.send(result) : Promise.reject(result))
    .catch(err => res.status(err.status || 500).send(err))
})

... 

app.get('/games/:id', ...) // count endpoint should be above of the get doc endpoint

app.get('/games/count', function (req, res) {
  hyper.cache.get('game-counter')
    .then(result => result.count ? res.send(result) : Promise.reject(result))
    .catch(err => res.status(err.status || 500).send(err))
})

... 

app.get('/games/:id', ...) // count endpoint should be above of the get doc endpoint
﻿
🎓 Using hyper.cache.get to get the game-counter value from the cache, and check if we got the count property, and handle the response to the caller.
Using hoppscotch call the new endpoint GET /games/count 
Response
JSON
{
    "count": 1
}
{
    "count": 1
}
﻿
Update Game Document
Clients should be able to update Game documents, so lets make that happen, by creating a new API endpoint 
JS
app.put('/games/:id', express.json(), function (req, res) {
  validate(req.body)
    .then(body => hyper.data.update(req.params.id, body))
    .then(result => result.ok ? res.send(result) : Promise.reject(result))
    .catch(err => res.status(err.status || 500).send(err))
})
app.put('/games/:id', express.json(), function (req, res) {
  validate(req.body)
    .then(body => hyper.data.update(req.params.id, body))
    .then(result => result.ok ? res.send(result) : Promise.reject(result))
    .catch(err => res.status(err.status || 500).send(err))
})
﻿
🎓 The hyper.data.update command takes an _id and a document, in this implementation, we validate the incoming data, then we chain it to the hyper.data.update method, then chain the result and if successful return the successful response, otherwise reject it and return an error response. 
Using hoppscotch lets update a game document, by setting the method to PUT and the URL to http://localhost:3000/games/game-1 and the body to the following and click the `send` button:

JSON
{
  "_id": "game-1",
  "type": "game",
  "name": "Donkey Kong",
  "company": "Nintendo",
  "released": "1980"
}
{
  "_id": "game-1",
  "type": "game",
  "name": "Donkey Kong",
  "company": "Nintendo",
  "released": "1980"
}
﻿
Here is the expected response
JSON
{
  "ok": true,
  "id": "game-1"
}
{
  "ok": true,
  "id": "game-1"
}
﻿
﻿
Delete Game Document
Let's delete a game document
update the utils.js , by adding decrementCounter 
JS
import { connect } from 'hyper-connect'
const hyper = connect(process.env.HYPER)

const increment = result => result.count ? result.count + 1 : 1
const decrement = result => result.count ? result.count - 1 : 0

const update = name => count => hyper.cache.set(name, { count })
const resolve = x => result => result.ok ? x : Promise.reject({ status: 500, error: 'Could not find cache' })

export function incrementCounter(type) {
  return function (x) {
    return hyper.cache.get(`${type}-counter`)
      .then(increment)
      .then(update(`${type}-counter`))
      .then(resolve(x))
  }

}

export function decrementCounter(type) {
  return function (x) {
    return hyper.cache.get(`${type}-counter`)
      .then(decrement)
      .then(update(`${type}-counter`))
      .then(resolve(x))
  }

}
import { connect } from 'hyper-connect'
const hyper = connect(process.env.HYPER)

const increment = result => result.count ? result.count + 1 : 1
const decrement = result => result.count ? result.count - 1 : 0

const update = name => count => hyper.cache.set(name, { count })
const resolve = x => result => result.ok ? x : Promise.reject({ status: 500, error: 'Could not find cache' })

export function incrementCounter(type) {
  return function (x) {
    return hyper.cache.get(`${type}-counter`)
      .then(increment)
      .then(update(`${type}-counter`))
      .then(resolve(x))
  }

}

export function decrementCounter(type) {
  return function (x) {
    return hyper.cache.get(`${type}-counter`)
      .then(decrement)
      .then(update(`${type}-counter`))
      .then(resolve(x))
  }

}
﻿
﻿
in the server.js file, create a app.delete handler
JS
...
import { decrementCounter, incrementCounter } from './utils.js'

...

app.delete('/games/:id', function(req, res) {
    return hyper.data.get(req.params.id)
      .then(validate)
      .then(game => hyper.data.remove(game._id))
      .then(decrementCounter('game'))
      .then(result => result.ok ? res.send(result) : Promise.reject(result))
      .catch(err => res.status(err.status || 500).send(err))
})

...
import { decrementCounter, incrementCounter } from './utils.js'

...

app.delete('/games/:id', function(req, res) {
    return hyper.data.get(req.params.id)
      .then(validate)
      .then(game => hyper.data.remove(game._id))
      .then(decrementCounter('game'))
      .then(result => result.ok ? res.send(result) : Promise.reject(result))
      .catch(err => res.status(err.status || 500).send(err))
})
﻿
List Game Documents
GET /games 
List Companies
Query Game Documents by Company

Query Game Documents by Year 
Search Game Documents by Name
﻿
Next steps
﻿
Updated 03 Mar 2023
Did this page help you?
NodeJS Workshops
Quickstarts