H4. #

A lightweight, minimal, and incredibly fast HTTP framework for productive and fun API development with dart.

This is a very new project under active development

Do not use in production as it could break unexpectedly.

You're welcome to try it out, see what breaks and give feedback.

There's already an express.js implementation called Alfred in the dart ecosystem.

This is the H3 implementation with similar design goals. Special thanks to Pooya Parsa and the Unjs community for making a great library.

Features #

• Lightweight: H4 ships with a small core and a set of composable utilities.
• Fast: H4's trie-based router is incredibly fast, with support for route params and wildcard patterns.
• Middleware: H4 comes with built-in onRequest and onError middleware.
• Generic Handlers: Specify the return type of your handler functions for increased type safety.

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 #

Manual Start #

var app = createApp(port: 4000, autoStart: false);

app.start().then((h4) => print(h4?.port));

var router = createRouter();

app.use(router);

Generic handlers #

Specify the return type of your handlers

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

Middleware #

H4 provides two middleware functions out of the box.

// Invoked when a request comes in
app.onRequest((event) {
 print('Incoming request method: ${event.method}');
});

// Global error handler - Called when an error occurs in non-async handlers
app.onError((error) {
 print("$error");
});

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) {
 try {
  // Code that could fail.
 }
 catch(e) {
   throw CreateError(message: 'Error - $e', errorCode: 400);
 }
});

The client recieves this json payload -

{
 "status": 400,
 "message": "[Error message]"
}

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 #

This is a design philosophy from h3.

I'm working on adding an exhaustive list of composable utilities for easily extending functionality of your server.

More utilities will be added with each release and soon a guide to creating your own utils will be published.

readRequestBody #

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

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

Contributing #

We are looking for contributors!

There's still quite a bit of work to do to get H4 to 1.0.0 and ready for production use.

If you find a bug or have an idea for a new feature, please open an issue or submit a pull request.

First Contribution #

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

Code of Conduct. #

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