RFC: 007 Refine and productize hyper63 nodejs client

[twilson63]

NodeJS Client

Summary

Refine and productize the hyper63 client

Motivation

Currently, the client is a proof of concept and a prototype at best, we need to document the client api and vet it via the advisory panel then implement a production stable version. This version should be well documented with examples and demos.

Detailed design

The hyper63 NodeJS client should be the goto solution to connect and leverage hyper63 services in NodeJS.

Version 1 Requirements

• Should support all ports of hyper63
• Should have plugin system for authentication (hyper63 can be secured using many different patterns the client should be capable of supporting those different patterns)
• Should contain a setup step to setup services
• Should be extendable - using Async Data Type
• Minimum Dependencies (crocks, ramda, date-fns)
• should support seeding ports with data
• should support migrations within port - ie converting data from one shape to another shape
• v1.5 should support migration between clients

What v1 won't do

• no magic, it will not auto cache or auto search or anything else, it just provides a DSL on top of the REST API interface

Setup Examples

Schema

const createClientSchema = z.function()
  .args(
     z.string().url(), // hyper63 URL
     z.function().args(z.void()).returns(z.string()), // value for Bearer Token
     z.array(
       z.object({
         name: z.string(),
         types: z.array(z.string()),
         ports: z.array(z.enum(['data', 'cache', 'search', 'storage'])),
       })
     )
  )
  .returns(z.object().passthrough())

Implementation Example

import hyper63 from '@hyper63/client'
import * as z from 'zod'

const client = hyper63.createClient(
  'https://play.hyper63.com',
  () => process.env.TOKEN,
  [
    { name: 'movies', types: ['movie', 'actor', 'poster'], ports: ['data', 'cache', 'storage'] },
    { name: 'users', types: ['account', 'user', 'role', 'avatar'], ports: ['data', 'cache', 'storage'] },
    { name: 'titles', ports: ['search'] }
  ]
)

client.movies.movie.schema(
  z.object({
    id: z.string(),
    title: z.string(),
    year: z.string().min(4).max(4)
  })
)

client.movies.bulkDocs([
  {
    id: '1',
    type: 'movie',
    title: 'Ghostbusters',
    year: '1984'
  },
  {
    id: '2',
    type: 'movie',
    title: 'Groundhog Day',
    year: '1993'
  }
])
  .fork(
    e => console.log('error: ', e),
    r => console.log('result: ', r)
  )


client.movies.movie.post({
  id: '3',
  title: 'Avengers',
  year: '2012'
})
  .fork(
    e => console.log('error: ', e),
    r => console.log('result: ', r)
  )

client.movies.movie.get('1')
  .fork(
    e => console.log('error: ', e),
    r => console.log('result: ', r)
  )

client.movies.query({
  year: {
    $gt: '2000'
  }
})
  .fork(...)

client.titles.search({
  query: 'Avengers'
})
  .fork(...)

How we teach this

What names and terminology work best for these concepts and why? How is this
idea best presented? As a continuation of existing Atlas patterns, or as a
wholly new one?

Would the acceptance of this proposal mean the Atlas guides must be
re-organized or altered? Does it change how Atlas is taught to new users
at any level?

How should this feature be introduced and taught to existing Atlas
users?

Drawbacks

Why should we not do this? Please consider the impact on teaching Atlas,
on the integration of this feature with other existing and planned features,
on the impact of the API churn on existing apps, etc.

There are tradeoffs to choosing any path, please attempt to identify them here.

Alternatives

What other designs have been considered? What is the impact of not doing this?

This section could also include prior art, that is, how other frameworks in the same domain have solved this problem.

Unresolved questions

Optional, but suggested for first drafts. What parts of the design are still
TBD?

[twilson63]

@TillaTheHun0 @Benanna2019 @JanitaM @cawilson1 @tripott @rpearce

☝️ Please review this proposal and discuss and question. The goal would to provide a first class client to hyper63 that gives api developers a great user experience connecting with hyper63. The client api would not implement any patterns on v1 it would only abstract the rest api into a DSL api so that users can leverage declarative syntax in their business logic.

Thoughts?

[rpearce]

This is real nice 👌. Nearly every question I've written out here so far, upon further inspection, has led me to delete it because what you've got here makes sense.

My only remaining questions:

• Does createClient do asynchronous stuff in the background that you might need to await on or some such?
• What's a more real-life example of the bearer token callback function?
• The ports values are all strings, and since strings are notorious for being mistyped, will the client throw or log an error if anything unexpected is passed in via that array? I played with the idea of exporting a PORTS object with key+value mappings like PORTS.CACHE that the client imports and uses in the array, but it feels like too much. I think ensuring you stop the show might be worth considering if you haven't already.

[rpearce]

I also think if you go with the Asyncs that you should also have your own docs on useful stuff you can do with them before linking out to Async/Task/Future sites and stuff elsewhere.

And example would be chaining a few of these together, showing how simple that can be (it's lazy!), then calling fork at the end. Also the ability to set a timeout, cancel, etc.

[twilson63]

Hey Robert,

First, thank you for taking the time to read and the time to think through the proposal.

I will try to answer your questions below:

Does createClient do asynchronous stuff in the background that you might need to await on or some such?

Great question, currently, it does nothing but setiup a closure to provide configuration information to the client object.

What's a more real-life example of the bearer token callback function?

import jwt from 'jsonwebtoken'

const generateToken = ({token, exp}) => {
  // maybe add some caching logic to only generate a new token when one is expired
  
  const exp = Math.floor(Date.now() / 1000) + (60 * 60)
  const token = jwt.sign({ sub: 'MyAppName', scope: '*:READ', exp }, process.env.PRIVATE_KEY, { algorithm: 'EC256' })
  return { token, exp }
}

const client = hyper63.createClient(
  'https://play.hyper63.com',
  generateToken, 
  [
    { name: 'movies', types: ['movie', 'actor', 'poster'], ports: ['data', 'cache', 'storage'] },
    { name: 'users', types: ['account', 'user', 'role', 'avatar'], ports: ['data', 'cache', 'storage'] },
    { name: 'titles', ports: ['search'] }
  ]
)

The ports values are all strings, and since strings are notorious for being mistyped, will the client throw or log an error if anything unexpected is passed in via that array?

Yes, with the schema validation it would only accept the values provided by the enum, we could do something more fancy, like providing constants, but create client would throw an error if the schema was not valid returning a list of issues for that invalidation.

---

I also think if you go with the Asyncs that you should also have your own docs on useful stuff you can do with them before linking out to Async/Task/Future sites and stuff elsewhere.

👍

I agree, I have some posts coming out next week highlighting EvilSofts videos on Async and Reader. But I will work on producing my own posts and screencasts, explaining these topics.

[rpearce]

All that sounds good. Is there a scenario where generateToken needs to do something promisey? If so, would this argument be able to handle async gnerateToken () => {}?

[twilson63]

Good question let me think through that I suppose the check on the returned value could resolve either or

…

Sent from my iPhone

On Feb 22, 2021, at 3:20 PM, Robert Pearce ***@***.***> wrote:  All that sounds good. Is there a scenario where generateToken needs to do something promisey? If so, would this argument be able to handle async gnerateToken () => {}? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[twilson63]

Took a step back and delivered @hyper.io/connect a easy way to connect to a hyper meta-service using the url and token methods, check it out at https://github.com/hyper63/connect