HeavenWeb

Extremely simple, blazing fast web framework for Node.js

Heaven is a minimalist web framework that gets out of your way and lets you build web applications quickly. It's the Node.js port of the popular Python Heaven framework, designed with simplicity and performance in mind.

✨ Features

• 🚀 Blazing Fast - Minimal overhead, maximum performance
• 🎯 Simple API - Learn the entire framework in 10 minutes
• 📦 Lightweight - Small footprint, minimal dependencies
• 🔧 Flexible - Works with Nunjucks templates or any database
• 🌐 Modern - ES modules, async/await, Node.js 16+
• 🛡️ Secure - Built-in security best practices
• 📝 Well Documented - Comprehensive guides and examples

🚀 Quick Start

Installation

npm install heavenweb

Basic Usage

import { Router } from 'heavenweb';

const app = new Router();

// Simple route
app.GET('/', (req, res, ctx) => {
  res.json({ message: 'Hello from Heaven!' });
});

// Route with parameters
app.GET('/hello/:name', (req, res, ctx) => {
  const { name } = req.params;
  res.json({ message: `Hello, ${name}!` });
});

// Start the server
app.run({ port: 3000 });

With Templates and Static Files

import { Router } from 'heavenweb';

const app = new Router();

// Configure templates and static files
await app.TEMPLATES('./views');
await app.ASSETS('./public');

// Render templates
app.GET('/', async (req, res, ctx) => {
  ctx.keep('title', 'Welcome to Heaven');
  ctx.keep('message', 'Build amazing web apps!');
  await res.render('index.njk');
});

app.run({ port: 3000 });

API Compatibility

Heaven.js maintains API compatibility with the Python Heaven framework:

Router/App Class

• Router() / App() / Application() - Main application class
• GET(), POST(), PUT(), PATCH(), DELETE() - HTTP method handlers
• BEFORE(), AFTER() - Middleware registration
• ONCE() - Lifecycle hooks (startup/shutdown)
• TEMPLATES() - Enable template rendering
• ASSETS() - Enable static file serving
• mount() - Mount other applications
• subdomain() - Register subdomain routing

Request Object

• req.params - Route parameters
• req.queries - Query string parameters
• req.body - Request body (after parsing)
• req.headers - Request headers
• req.cookies - Parsed cookies
• req.method, req.url, req.ip - Basic request info

Response Object

• res.json() - Send JSON response
• res.html() - Send HTML response
• res.text() - Send text response
• res.render() - Render template (async)
• res.renders() - Render template (sync)
• res.redirect() - Redirect response
• res.setCookie() - Set cookies

Context Object

• ctx.keep() - Store typed values
• ctx.getTyped() - Retrieve with type checking
• Dynamic property access via proxy

Testing

Run the test application:

node test-app.js

Then visit http://localhost:3000/ to see the test interface.

Test Results

✅ Basic Routing - Root route serves HTML page
✅ Parameter Routing - /hello/:name extracts parameters correctly
✅ Query Parameters - /params/:id?sort=name&filter=active parses both params and queries
✅ JSON Responses - /json returns proper JSON with headers
✅ POST Requests - /echo handles POST with JSON body parsing
✅ Context System - /context demonstrates typed value storage and retrieval
✅ Error Handling - /error properly catches and handles exceptions
✅ Lifecycle Hooks - Startup and shutdown hooks execute correctly

Performance

The framework successfully handles:

• Route matching with parameters
• JSON request/response processing
• Template rendering (Nunjucks)
• Static file serving
• Middleware execution
• Context state management

Differences from Python Version

1. Template Engine: Uses Nunjucks instead of Jinja2
2. HTTP Server: Uses Node.js native HTTP server instead of ASGI/uvicorn
3. Async/Await: Full async/await support throughout
4. ES Modules: Uses ES6 modules instead of Python imports
5. Type System: JavaScript dynamic typing with runtime type preservation in Context

Project Structure

ported/
├── src/
│   ├── index.js          # Main exports
│   ├── router.js         # Router/App class
│   ├── request.js        # Request handling
│   ├── response.js       # Response handling
│   ├── context.js        # Context system
│   ├── routes.js         # Routing engine
│   ├── templater.js      # Nunjucks template engine
│   ├── static.js         # Static file serving
│   ├── form.js           # Form data parsing
│   ├── utils.js          # Utilities
│   ├── constants.js      # Constants
│   └── errors.js         # Error classes
├── examples/
│   ├── basic-app.js      # Basic example
│   └── templates/        # Example templates
├── test-app.js           # Test application
├── package.json          # Dependencies
└── README.md             # This file

🎯 Examples

REST API

import { Router } from 'heavenweb';

const app = new Router();

// In-memory data store (use a real database in production)
let users = [
  { id: 1, name: 'John Doe', email: '[email protected]' },
  { id: 2, name: 'Jane Smith', email: '[email protected]' }
];

// Get all users
app.GET('/api/users', (req, res, ctx) => {
  res.json(users);
});

// Get user by ID
app.GET('/api/users/:id', (req, res, ctx) => {
  const id = parseInt(req.params.id);
  const user = users.find(u => u.id === id);

  if (!user) {
    res.status(404).json({ error: 'User not found' });
    return;
  }

  res.json(user);
});

// Create new user
app.POST('/api/users', async (req, res, ctx) => {
  const userData = await req.json();
  const newUser = {
    id: users.length + 1,
    ...userData
  };

  users.push(newUser);
  res.status(201).json(newUser);
});

app.run({ port: 3000 });

🔧 Configuration

Server Options

app.run({
  port: 3000,
  host: 'localhost',
  debug: true
});

🧪 Testing

Heaven applications are easy to test with supertest:

import request from 'supertest';
import { Router } from 'heavenweb';

const app = new Router();

app.GET('/api/health', (req, res, ctx) => {
  res.json({ status: 'ok' });
});

describe('API Tests', () => {
  test('GET /api/health', async () => {
    const response = await request(app.server)
      .get('/api/health')
      .expect(200);

    expect(response.body).toEqual({ status: 'ok' });
  });
});

📊 Performance

Heaven is designed for performance:

• Minimal overhead: Direct request handling without unnecessary abstractions
• Efficient routing: Fast route matching and parameter extraction
• Memory efficient: Low memory footprint and garbage collection pressure
• Async optimized: Built for modern async/await patterns

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation
• GitHub Repository
• npm Package
• Examples

Made with ❤️ by the HeavenWeb Team