Nostalgic Perogi Monogramming

    @cuties/rest

    1.2.20 • Public • Published

    cutie-rest

    NPM Version Build Status codecov

    Cutie extension for using REST (based on cutie-http and cutie-https) in Node. It's based on the Async Tree Pattern.

    Install

    npm install @cuties/rest

    Run test

    npm test

    Run build

    npm run build

    Run example

    npm run example

    Run procedural example

    npm run procedural-example

    Usage

    const {
      // Needed async objects here from the table below
    } = require('@cuties/rest')

    This library provides following objects: Backend, RestApi, RequestBody, CreatedServingFilesEndpoint, CreatedCachedServingFilesEndpoint, ServingFiles, CachedServingFiles, CORSEndpoint and Endpoint, NotFoundEndpoint, IndexEndpoint, InternalServerErrorEndpoint interfaces.

    Object Parameters(type) Description
    Backend protocol, port(number), host(string), api(RestApi)[, options] It's AsyncObject. It Declares backend server with protocol(http or https) on specified port and host, also it provides declared api (REST). options is for options of the http/https server(it's optional).
    ClusteredBackendWith505ErrorEvent domain, cluster, errorEvent, protocol, port, host, api[, options[, numberOfForks]] It's AsyncObject. It declares backend which based on clusters (Cluster API from Node.js) and also provides a way to handle any uncaught exceptions in the program via Domain module in Node(will be replace with other alternative solution from Node once it's released). For more details check example below.
    RestApi ...endpoints(classes that extend Endpoint) Represents request-response listener. Declares endpoints of api.
    RequestBody request Reads body of request in body(request, response) method of Endpoint implementation
    RequestParams request Reads params of request in body(request, response) method of Endpoint implementation
    RequestWithProgress request, response[, totalLengthHeaderName('content-length' by default)] Send progress to client via response.write while loading request body
    Endpoint regexpUrl (RegExp), method(string)[, ...args] Declares an endpoint(in api) with url that matches regexpUrl and specified method('GET', 'POST', etc.). Also it's possible to pass some custom arguments via ...args. This class has a method body(request, response[, ...args]) that needs to be overridden and must return async object.
    ServingFilesEndpoint regexpUrl (RegExp), mapper (function(url)), headers(additional headers to 'Content-Type' in response), notFoundEndpoint(Endpoint) Extends Endpoint and serves files on url that mathes regexpUrl with mapper function that gets location of a file on a disk by the url. Also it's required to declare notFoundEndpoint that handles the cases when a file is not found. You also can specify headers in response(no need to specify the 'Content-Type', library makes it for you).
    CachedServingFilesEndpoint regexpUrl (RegExp), mapper(function(url)), headers(additional headers to 'Content-Type' in response), notFoundEndpoint(Endpoint) Does the same that ServingFilesEndpoint does and caches files on server side for increasing speed of serving them.
    IndexEndpoint no args Endpoint that is used for representing index page.
    NotFoundEndpoint regexpUrl (RegExp) Endpoint that is used in RestApi, ServingFilesEndpoint, CachedServingFilesEndpoint for declaring endpoint on 404(NOT_FOUND) status.
    CORSEndpoint endpoint, { allowedOrigins, allowedMethods, allowedHeaders, allowedCredentials, maxAge } Enables CORS for specified endpoint and configuration (example)
    InternalServerErrorEndpoint regexpUrl (RegExp, default is new RegExp(/^\/internal-server-error/)) Endpoint that is used for handling underlying internal failure(not for user error).

    Example

    'use strict'
    
    const path = require('path')
    const {
      Backend,
      RestApi,
      ServingFilesEndpoint,
      CachedServingFilesEndpoint
    } = require('@cuties/rest')
    const {
      CreatedOptions
    } = require('@cuties/https')
    const { ReadDataByPath } = require('@cuties/fs')
    const SimpleResponseOnGETRequest = require('./example/SimpleResponseOnGETRequest')
    const SimpleResponseOnPOSTRequest = require('./example/SimpleResponseOnPOSTRequest')
    const SimpleProgressEndpoint = require('./example/SimpleProgressEndpoint')
    const CustomNotFoundEndpoint = require('./example/CustomNotFoundEndpoint')
    const CustomInternalServerErrorEndpoint = require('./example/CustomInternalServerErrorEndpoint')
    const CustomIndexEndpoint = require('./example/CustomIndexEndpoint')
    
    const notFoundEndpoint = new CustomNotFoundEndpoint(new RegExp(/\/not-found/))
    const internalServerErrorEndpoint = new CustomInternalServerErrorEndpoint(new RegExp(/^\/internal-server-error/))
    
    const mapper = (url) => {
      let parts = url.split('/').filter(part => part !== '')
      return path.join(...parts)
    }
    
    const cacheMapper = (url) => {
      let parts = url.split('/').filter(part => part !== '').slice(1)
      parts.unshift('files')
      return path.join(...parts)
    }
    
    new Backend(
      'https', 
      8000, 
      '127.0.0.1',
      new RestApi(
        new CustomIndexEndpoint(),
        new SimpleResponseOnGETRequest(new RegExp(/^\/get/), 'GET'),
        new SimpleResponseOnPOSTRequest(new RegExp(/^\/post/), 'POST'),
        new SimpleProgressEndpoint(new RegExp(/^\/progress/), 'POST'),
        new ServingFilesEndpoint(new RegExp(/^\/files/), mapper, {}, notFoundEndpoint),
        new CachedServingFilesEndpoint(new RegExp(/^\/cached/), cacheMapper, {}, notFoundEndpoint),
        notFoundEndpoint,
        internalServerErrorEndpoint
      ), new CreatedOptions(
        'key', new ReadDataByPath('./example/pem/key.pem'),
        'cert', new ReadDataByPath('./example/pem/cert.pem')
      )
    ).call()

    CustomIndexEndpoint

    'use strict'
    
    const { IndexEndpoint } = require('@cuties/rest')
    
    class CustomIndexEndpoint extends IndexEndpoint {
      constructor () {
        super()
      }
    
      body (request, response) {
        return super.body(request, response)
      }
    }
    
    module.exports = CustomIndexEndpoint
    

    IndexEndpoint

    CustomNotFoundEndpoint

    'use strict'
    
    const { NotFoundEndpoint } = require('@cuties/rest')
    
    class CustomNotFoundEndpoint extends NotFoundEndpoint {
      constructor (regexpUrl) {
        super(regexpUrl)
      }
    
      body (request, response) {
        return super.body(request, response)
      }
    }
    
    module.exports = CustomNotFoundEndpoint

    NotFoundEndpoint

    SimpleResponseOnGETRequest

    'use strict'
    
    const {
      Endpoint
    } = require('@cuties/rest')
    const {
      EndedResponse,
      WrittenResponse,
      ResponseWithWrittenHead
    } = require('@cuties/http')
    
    class SimpleResponseOnGETRequest extends Endpoint {
      constructor (regexpUrl, type) {
        super(regexpUrl, type)
      }
    
      body (request, response) {
        return new EndedResponse(
          new WrittenResponse(
            new ResponseWithWrittenHead(
              response, 200, 'ok', {
                'Content-Type': 'text/plain'
              }
            ), 'content'
          ), ' is delivered'
        )
      }
    }
    
    module.exports = SimpleResponseOnGETRequest

    SimpleResponseOnPOSTRequest

    'use strict'
    
    const {
      EndedResponse,
      WrittenResponse,
      ResponseWithWrittenHead
    } = require('@cuties/http')
    const {
      Endpoint,
      RequestBody
    } = require('@cuties/rest')
    
    class SimpleResponseOnPOSTRequest extends Endpoint {
      constructor (regexpUrl, type) {
        super(regexpUrl, type)
      }
    
      body (request, response) {
        //  Use RequestBody object for fetching body from request
        return new EndedResponse(
          new WrittenResponse(
            new ResponseWithWrittenHead(
              response, 200, 'ok', {
                'Content-Type': 'text/plain'
              }
            ), new RequestBody(request)
          ), ' is delivered'
        )
      }
    }
    
    module.exports = SimpleResponseOnPOSTRequest

    SimpleProgressEndpoint

    'use strict'
    
    const {
      EndedResponse,
      WrittenResponse,
      ResponseWithWrittenHead
    } = require('@cuties/http')
    const {
      Endpoint,
      RequestBody,
      RequestWithProgress
    } = require('./../index')
    
    class SimpleProgressEndpoint extends Endpoint {
      constructor (regexpUrl, type) {
        super(regexpUrl, type)
      }
    
      body (request, response) {
        return new EndedResponse(
          new WrittenResponse(
            new ResponseWithWrittenHead(
              response, 200, 'ok', {
                'Content-Type': 'text/plain'
              }
            ),
            new RequestBody(
              new RequestWithProgress(request, response)
            )
          ), ' is delivered'
        )
      }
    }
    
    module.exports = SimpleProgressEndpoint

    CustomInternalServerErrorEndpoint

    'use strict'
    
    const { InternalServerErrorEndpoint } = require('@cuties/rest')
    
    class CustomInternalServerErrorEndpoint extends InternalServerErrorEndpoint {
      constructor (regexpUrl) {
        super(regexpUrl)
      }
    
      body (request, response, error) {
        return super.body(request, response, error)
      }
    }
    
    module.exports = CustomInternalServerErrorEndpoint

    InternalServerErrorEndpoint

    Example Of Using CORSEndpoint

    'use strict'
    
    const {
      Backend,
      RestApi,
      CORSEndpoint
    } = require('@cuties/rest')
    const SimpleResponseOnPOSTRequest = require('./example/SimpleResponseOnPOSTRequest')
    const CustomNotFoundEndpoint = require('./example/CustomNotFoundEndpoint')
    const CustomInternalServerErrorEndpoint = require('./example/CustomInternalServerErrorEndpoint')
    const CustomIndexEndpoint = require('./example/CustomIndexEndpoint')
    
    new Backend(
      'http', 
      8001, 
      '127.0.0.1',
      new RestApi(
        new CustomIndexEndpoint(),
        new CORSEndpoint(
          new SimpleResponseOnPOSTRequest(new RegExp(/^\/post/), 'POST'),
          {
            allowedOrigins: [ 'https://127.0.0.1:8000' ], // or it can be just a string '*' (which is default value)
            allowedMethods: [ 'POST, OPTIONS' ], // by default it's methods in the encapsulated SimpleResponseOnPOSTRequest and OPTIONS
            allowedHeaders: [ ], // by default it's all headers of the request,
            allowedCredentials: true, // by default this value is not set,
            maxAge: 86400 // by default this value is not set
          }
        ),
        notFoundEndpoint,
        internalServerErrorEndpoint
      )
    ).call()

    Example Of Using Clustered Backend

    'use strict'
    
    const domain = require('domain')
    const cluster = require('cluster')
    const path = require('path')
    const {
      ClusteredBackendWith500ErrorEvent,
      RestApi,
      ServingFilesEndpoint,
      CachedServingFilesEndpoint,
      CORSEndpoint
    } = require('@cuties/rest')
    const SimpleResponseOnGETRequest = require('./example/SimpleResponseOnGETRequest')
    const SimpleResponseOnPOSTRequest = require('./example/SimpleResponseOnPOSTRequest')
    const SimpleResponseOnPUTRequest = require('./example/SimpleResponseOnPUTRequest')
    const SimpleProgressEndpoint = require('./example/SimpleProgressEndpoint')
    const CustomNotFoundEndpoint = require('./example/CustomNotFoundEndpoint')
    const CustomInternalServerErrorEndpoint = require('./example/CustomInternalServerErrorEndpoint')
    const CustomIndexEndpoint = require('./example/CustomIndexEndpoint')
    const ErrorEndpoint = require('./example/ErrorEndpoint')
    
    const notFoundEndpoint = new CustomNotFoundEndpoint(new RegExp(/\/not-found/))
    const internalServerErrorEndpoint = new CustomInternalServerErrorEndpoint()
    
    const mapper = (url) => {
      let parts = url.split('/').filter(part => part !== '')
      return path.join(...parts)
    }
    
    const cacheMapper = (url) => {
      let parts = url.split('/').filter(part => part !== '').slice(1)
      parts.unshift('files')
      return path.join(...parts)
    }
    
    new ClusteredBackendWith500ErrorEvent(
      domain,
      cluster,
      (error, request, response) => {
        response.statusCode = 500
        response.setHeader('content-type', 'text/plain')
        response.end(`Internal Server Error (500):\n ${error}`)
      },
      'http',
      8000,
      '127.0.0.1',
      new RestApi(
        new CustomIndexEndpoint(),
        new SimpleResponseOnGETRequest(new RegExp(/^\/get/), 'GET'),
        new ErrorEndpoint(new RegExp(/^\/error/), 'GET'),
        new SimpleResponseOnPOSTRequest(new RegExp(/^\/post/), 'POST'),
        new SimpleProgressEndpoint(new RegExp(/^\/progress/), 'POST'),
        new ServingFilesEndpoint(new RegExp(/^\/files/), mapper, {}, notFoundEndpoint),
        new CachedServingFilesEndpoint(new RegExp(/^\/cached/), cacheMapper, {}, notFoundEndpoint),
        notFoundEndpoint,
        internalServerErrorEndpoint
      )
    ).call()

    Keywords

    Install

    npm i @cuties/rest

    DownloadsWeekly Downloads

    41

    Version

    1.2.20

    License

    MIT

    Unpacked Size

    352 kB

    Total Files

    96

    Last publish

    Collaborators

    • guseyn