@kedoska/resty

An NPM package for providing quick and dirty JSON CRUD REST API into your existing ExpressJS application servers.

npm install @kedoska/resty

Key concept

• Define CRUD operations on the data-adapter.
• Built-in extractors for pagination and query.

Define your resources

Example: './resources/users'

import resty, { Pagination, Query } from '@kedoska/resty'

export interface User {
  email: string
  username: string
}

const selectMany = (pagination: Pagination, query?: Query): Promise<User[]> =>
  new Promise((resolve, reject) => {
    try {
      resolve([])
    } catch ({message}) {
      reject(Error(`could not "select" the resources, ${message}`))
    }
  })

export default () => {
  return resty({
    version: 'v1',
    resource: 'users',
    dataAdapter: {
      // createOne,
      selectMany, 
      // selectOne, 
      // updateOne, 
      // deleteOne, 
      // deleteAll, 
    },
  })
}

Consume the resource

Example: '.server.ts'

// in your server
import express from 'express'
import users from './resources/users'

const app = express()
app.use(users())
app.listen(8080)

The Data Adapter

⚠️ Everything is a Promise

Defines the data functions to mount the endpoints.
The following functions can be defined into the data-adapter and passed as argument.

• createOne (optional promise): creates the post endpoint.
• selectMany (optional promise): creates the get endpoint.
• selectOne (optional promise): creates the get ID endpoint.
• updateOne (optional promise): creates the put ID endpoint.
• deleteOne (optional promise): creates the delete ID endpoint.
• deleteAll (optional promise): creates the delete endpoint.

selectMany

  const users = resty({
    version: 'v1',
    resource: 'users',
    dataAdapter: {
      selectMany: () => new Promise((resolve) => resolve([]))
    },
  })

  const app = express()
  app.use(users)

The above server exposes the GET endpoint for the Users resource, mounting the path /v1/users.
The data returned by the promise selectMany, an empty array in the example, is sent back as JSON response body.

selectMany with default pagination

  const users = resty({
    version: 'v1',
    resource: 'users',
    dataAdapter: {
      selectMany: (pagination) => new Promise((resolve) => {
        const {page, limit} = pagination
        // limit your data...
        resolve([])
      }
    },
  })

  const app = express()
  app.use(users)

selectMany receives the pagination data as the first parameter. Limit and Page are parsed from the Querystring.
Consider the below examples, the default pagination is very straightforward, the data coming from the query string is parsed and passed directly to the selectMany Function.

• curl https://localhost:8080? becomes { limit: 0 page: 0 }
• curl https://localhost:8080?limit=10&page=2 becomes { limit: 10 page: 2 }
• ...

Examples

• (TS) Copy/Paste Data Adapter Skeleton gits
• (JS) How to build a CRUD REST API using Express, resty and Sqlite3 examples/sqllite3

Error Handling

The below example implements the errorHandler middleware from '@kedoska/resty' to catch the error sent by the createOne function.
The function handles eventual rejections coming from the data-adapter.

// in your server
import express from 'express'
import resty, { errorHandler } from '@kedoska/resty'

const app = express()
app.use(
  resty({
    version: 'v1',
    resource: 'users',
    dataAdapter: {
      createOne: (resource: any) => new Promise((resolve, reject) => {
        reject(Error('Not Yet Implemented'))
      }),
    },
  })
)

app.use(errorHandler)
app.listen(8080)

The post endpoint created by createOne is /v1/users/.
It will fail, returning status 200 OK, having the following body:

{
  "message": "createOne not yet implemented"
}