Introducing Whook
Extensible APIs done well

about:nfroidure

Web Platform Architect
 

Building softwares for Lille's innovative startups since JavaScript is a hot topic.

Almost passed the Rust compiler checks once.

Blog & Tweet randomly

Design choices

Open API based
Bring OAS3 definitions and get a router!

• A very wide used standard
• Learn a standard instead of a framework
• Enforces documentation (no doc, no route)

No OOP
FP without hysteria

• requests / responses are plain
  serializable objects
• handlers / services are just async
  functions
• middlewares are just higher order
  functions (called wrappers)

Dependency Injection
at its core with Knifecycle

• Highly customizable
• Easily testable (E2E, unit...)
• Configurable and manageable
• Optimized
• Lightweight (build only necessary code)

TypeScript

• Less bugs
• Better developer experience
• But you may still use raw JS

Configuration
over code

• Less breaking compatibility
• Auto-completed configuration
• Plugins for a lot of common use cases
• Still possible to override the code

KISS

• introduce only a few specific concepts
• flavor for extendable code over
  embrassing every use cases
• WET over DRY

Enterprise focused

• always favor reliability over ease of use
  (that said, provide both when possible)
• built for easy teams scaling over easy toy
  projects setup

Getting started

> npm init @whook

Dev commands

• `npm run dev`: run the backend for
   dev (typically for frontend devs)
• `npm run watch`: work on the backend
  (generates Open API types on the fly)
• `npm run whook-repl`: inject and use
  services on the fly

Key concepts

Services

• Initialize a reusable portion of code
• Usually, one that maintain states (IOs, FS, DB..)
• Can depend on other services
• Create new ones with:
  > npx whook create --type service
• find them in `src/services`

Providers

Like services but with extras behaviors

• Can declare a shutdown hook so that
  when the server is shut down, the service
  cleans up its states (close DB connections)
• Can declare an error promise to shut down
  the server if anything goes wrong
• Create new ones with:
  > npx whook create --type provider
• find them in `src/services`

Handlers

• Implementation of an endpoint
• Often also contains its definition
• Can depend on other services
• Can also reuse other handlers's code
  (they are just a special kind of service
  after all)
• Easily override an handler by proxying it
• Create new ones with:
  > npx whook create --type handler
• find them in `src/handlers`

Wrappers

• Wrap handlers to enrich their behavior
• Take an handler in parameter and
  output a new one
• Like Express middlewares but done
  with higher order function
• Useful for CORS, auth and others...
• Can be set globally thanks to the
  WRAPPERS service
• find them in `src/wrappers`

API

• A service that gather each handlers
  definitions
• Allow to make transformations
  on the overall API
• Mostly automated by the
  API_DEFINITIONS service
• find it at `src/services/API.ts`

Configurations

• Allow to configure each environment
• Type checked thanks to TypeScript
• Provide nice features for the injector
• find them in `src/config`

Commands

• Meant to tie CLI tools with the backend
  (sample command)
• Provide all injectable services
• All commands can be listed with:
  > npm run whook -- ls
• To create a new command:
  > npm run whook -- create --type command
• find them in `src/commands`

Main (index.js)

Allows to declare:

• the process environnement
• the server run function
• thought to be extendable

Avanced usage

Autoloader

• Allows to automatically load injected
  dependencies
• The default autoloader does it for services,
  providers, handlers and the API definitions
  in the various installed plugins,
• It can be overridden anytime with your own
  implementation or simply extended.

Plugins

• One can create plugins to provide
  extra services / handlers / commands
  out of the box by simply declaring it. 
• Default plugins can be completly released
  for a full customized experience

Service name map

• replace services per others for a given env
• replace services per others easily
• avoid extra costs by using mocked services
  in your preprod / uat envs

AWS Lambda

@whook/aws-lambda

• Build lightweigtht Lambda functions
  but still avoid being vendor locked
• Easily adapt your lambdas for any
  other cloud provider
• sample use of the module

GraphQL

@whook/graphql

• create GraphQL APIs with the
  Whook DI system (easily reuse
  handlers code)
• based on Apollo GraphQL server
• sample GraphQL server

Debugging

You never know!

Output debug infos

- to output Whook debug infos:

DEBUG=whook npm run dev

- to debug the router:

DEBUG=siso npm run dev

- to debug DI issues:

DEBUG=knifecycle npm run dev

Using the debugger

- for the Whook server:

npm run debug

- for commands:

npm run whook-dev -- ls

Ask for help!

• each error has a single code
• direct link to Stack Overflow :
  find answers easily or create yours