Valory

A server agnostic web framework for creating bulletproof apis

Contents

• Documentation
• API Reference
• Example Project
• Description
• Installation
• Basic Usage
• Extensions
• Contributions
• Acknowledgements

Description

Valory is small framework designed to standardize the process of writing well documented, bulletproof api's using whatever server backend you want.

What it do

• First class Typescript support with decorator based API
• Uses swagger to specify endpoints
• Supports the entire swagger 2.0 spec (even discriminators)
• Automatically generates swagger documentation
• Performs super fast input validations for requests
• Modular adaptor system that allows you to (with a little work) use any node server

What it don't do

• Make you write your code and docs separately

Installation

If you are on windows, you will want to install Java 1.7+. Closure compiler will work without it, but will be slow.

Next, you'll need to add the Valory runtime to your project along with a server adaptor

npm install valory-runtime valory-adaptor-fastify

Next, install the cli

npm i -g valory
 
# You can install it locally as well for build consistency 
npm i -D valory

Lastly, you'll need to create a Valory project

# Run in your project dir and commit the valory.json file 
valory init

Basic Usage

Using Valory is pretty straightforward.

index.ts

import {Valory, Swagger} from "valory-runtime";
import {FastifyAdaptor} from "valory-adaptor-fastify"
 
// import our controller
import "./someController"
 
// Define basic info for the api
const info: Swagger.Info = {
    title: "Test api",
    version: "1",
};
 
// Create the valory singleton
Valory.createInstance({
    info,
    server: new FastifyAdaptor(),
});
 
// Retrieve the valory instance (can be called anywhere)
const valoryInstance = Valory.getInstance();
 
// Build and start the app, passing any adaptor specific config data
valoryInstance.start({port: 8080});

someController.ts

import {Get, Route, Controller, Post, Body, Path, Header} from "valory-runtime";
 
export interface Item {
    someField: string;
    optionalField?: string;
    aNumber: number;
}
 
// Use fancy decorators to generate endpoints
@Route("base") export class SimpleController extends Controller {
    /**
     * Swagger endpoint description
     * @summary swagger summary
     */
    @Get("somepath") public someHandler() {
        return "Some response"
    }
    
    // Function arguments can be injected from request object   
    @Get("{name}") public async someOtherHandler(@Path() name: string, @Header() authorization: string): Promise<string> {
        return `name is ${name}`;
    }
    
    // even complex types work
    @Post("submit") public submit(@Body() input: Item): {content: Item} {
        // set the status code
        this.setStatus(418);
        
        // access request logger
        this.logger.info("yay!");
        
        return {
            content: input,
        }
    }
}
 

Once you have your api written, you have to compile it.

# Just run in your project dir next to your valory.json 
valory compile

Now all you need to do is run it

# This will be adaptor specific 
node path/to/api.js
 
# Valory provides an adaptor agnostic test command 
valory test

By default, this will also host a ReDoc powered documentation site at the site root.

Extensions

These are the officially maintained adaptors and middleware available for Valory.

Adaptors

• valory-adaptor-slimjim
  • Adaptor that uses slimjim (High speed)
• valory-adaptor-polka
  • Adaptor that uses polka (Smallest size)
• valory-adaptor-fastify
  • Adaptor that uses fastify (High stability)
• valory-adaptor-alb
  • Adaptor for directly processing events from an AWS Application Load Balancer
• valory-adaptor-claudia
  • Adaptor for use with Claudia and claudia-api-builder. Allows valory to be deployed as a serverless application in AWS Lambda.

Middleware

• valory-middleware-jwt
  • Simple JWT auth middleware

Related Projects

• parcel-plugin-valory
  • Plugin for parcel-bundler that adds valory support

Contributions

PR's are welcome!

PR guidelines

• Use Angular Commit Guidelines
• Explain why the change is necessary/helpful

Roadmap

• More comprehensive tests
• Additional adaptors

Acknowledgements

• Shoutout to TSOA. Decorator support in Valory is based on that project, huge 👍