H4.

A HTTP framework for productive and fun API development with dart.

Inspired by unjs H3.

This is a new project under active development, production use is not advised.

The docs site is still in construction🚧🚧 - link

Features

• Lightweight: H4 ships with a small core and a set of composable utilities.
• Middleware: H4 comes with onRequest and onError middleware.
• Generic Handlers: Specify the return type of your handler functions.

Getting Started

Add H4 to your pubspec.yaml:

dependencies:
  h4: ^1.0.0

Or install with dart pub get

dart pub add h4

Import the library and start building your server:

import 'package:h4/create.dart';

void main() {
 var app = createApp();
 var router = createRouter();

 app.use(router);

 router.get("/", (event) => "Hello world!");
}

Examples

Hello world

void main() {
  var app = createApp(port: 4000);
  var router = createRouter();

  app.use(router);

  router.get("/", (event) => "Hello world")
}

Generic handlers

Specify the return type of your handlers

router.get<bool>("/25/**", (event) => true);

Global Hooks

You can register global hooks:

• onRequest
• onError
• afterResponse

These hooks are called for every request and can be used to add global logic to your app such as logging, error handling, etc.

 var app = createApp(
   port: 5173,
   onRequest: (event) => {},
   onError: (error, stacktrace, event) => {},
   afterResponse: (event) => {},
 );
 var router = createRouter();
 app.use(router);

Error Handling

You can throw a create error Exception that will terminate the request and send a 400 - Bad Request response

router.get('/error', (event) async {
 try {
  // Code that could fail.
 }
 catch(e) {
   throw CreateError(message: 'Womp Womp', errorCode: 400);
 }
});

The client recieves this json payload -

{
 "status": 400,
 "message": "Womp Womp"
}

Param Routing

You can define parameters in your routes using : prefix:

router.get('/users/:id', (event) {
 final userId = event.params['id'];
 return 'User $userId'
});

Wildcard Routing

// Matches 'articles/page' and '/articles/otherPage' but not 'articles/page/otherPage'
router.get('/articles/*', (event) {
 final path = event.path;
 return 'The tea is teaing!!'
});

// Matches 'articles/foo/bar' and 'articles/rice/eba/beans'
router.get('/articles/**', (event) {
 final path = event.path;
 return 'The tea is teaing!!'
});

Utilities

A set of composable utilities that help you add functionality to your server

readRequestBody

Reads the request body as json or text depending on the contentType of the request body.

router.post("/vamos", (event) async {
 var body = await readRequestBody(event);
 return body;
});

getHeader

Get the value of any of the incoming request headers. For convenience you can use the HTTPHeaders utility to get header strings.

router.post("/vamos", (event) async {
 var header = getHeader(event, HttpHeaders.userAgentHeader);
 return body;
});

Contributing

A good first PR would be helping me improve the test coverage of this library, or adding one of the utilities listed here.

Running tests

In the root directory run

dart test

Code of Conduct.

Show respect and consideration for others when creating issues and contributing to the library. Only good vibes!