Basilic (alpha)
A minimalist Node.js JSON API with database integration.
Table of contents
Introduction
Basilic is a minimalist Node.js framework, based on http
package. Its aim is
to provide the minimal things you need to build a functional API, from the
routes to the database.
import basilic , { sqlite } from ' basilic '
const api = basilic
. database ( sqlite , ' :memory: ' )
. get ( ' /check ' , ctx => 204 )
. get ( ' /posts ' , ctx => {
const posts = await sql ` SELECT * FROM posts `
return { posts }
} )
. listen ( )
Installation
Note: basilic is written in TypeScript, so types are included - no need for
@types
.
Don't forget the driver, depending on your database:
yarn add sqlite3
yarn add pg
yarn add mysql
Usage
Database
type database = ( BasilicConnector , options ? : string ) => BasilicServer
basilic . database ( connector , ' : memory : ' )
Available connectors:
import { sqlite , postgres , mysql } from ' basilic '
You can also define your own driver (see existing
ones ):
import { BasilicConnector } from ' basilic '
const custom : BasilicConnector = {
...
}
basilic . database ( custom , ' options ' )
Method
Routes any incomming request to the correct handler . A route
matches when the method and the path match:
type get : ( Path , Handler ) => BasilicServer
type post : ( Path , Handler ) => BasilicServer
type patch : ( Path , Handler ) => BasilicServer
type put : ( Path , Handler ) => BasilicServer
type delete : ( Path , Handler ) => BasilicServer
api
. get ( ' /route ' , handler )
. post ( ' /route ' , handler )
. patch ( ' /route ' , handler )
. put ( ' /route ' , handler )
. delete ( ' /route ' , handler )
Path
A path can be a string or a regular
RegExp :
type Path = string | RegExp
api
. get ( ' /route ' , handler )
. get ( /^\/ route /, handler )
. get ( /\/ route \/ ( ? < id > \ d + ) /, handler )
Handler
type Handler = BasilicContext => any | void
api
. get ( ' /route ' , ctx => null )
. get ( ' /route ' , ctx => 401 )
. get ( ' /route ' , ctx => ( { data : ' test ' } ) )
. get ( ' /route ' , ctx => ' data ' )
. get ( ' /route ' , ctx => ( {
status : 401 ,
headers : { ' Content-Type ' : ' text/plain ' } ,
body : ' data ' ,
} ) )
Context
type BasilicContext = {
method : ' GET ' | ' POST ' | ' PUT ' | ' PATCH ' | ' DELETE '
url : string
params : any
sql : BasilicConnector [ ' sql ' ]
}
basilic . get ( ' /route ' , ctx => {
const { method } = ctx
const { url } = ctx
const { params } = ctx
const { sql } = ctx
const value = ' value '
const res = await sql `
SELECT *
FROM table
WHERE attr = ${ value }
`
} )
Listen
Starts the server:
type listen = ( port = 5000 , hostname = ' localhost ' ) => void
basilic . listen ( )
Testing
You can test your API with
supertest :
import basilic , { sqlite } from ' basilic '
const api = basilic
. database ( sqlite , ' :memory: ' )
. get ( ' /route ' , ctx => 204 )
export default api
import api from ' ./api '
api . listen ( )
import request from ' supertest '
import api from ' ../api '
const app = api . getListener ( )
describe ( ' routes ' , ( ) => {
it ( ' should match route ' , done => {
request ( app )
. get ( ' /route ' )
. expect ( 204 , done )
} )
} )
Roadmap