Biscuitsjar NPM

Biscuit Framework with Custom Hook System

Introduction

Biscuit is a lightweight and flexible HTTP server framework for Node.js, built to provide a robust Hook system for managing request flow, authentication, error handling, and middleware execution. It includes a custom router and advanced hook management, making it highly customizable and extensible.

Features

🍪: Custom Hook System

Define pre-request, post-response, and error-handling hooks.
Attach hooks to specific routes or apply them globally.
Priority-based execution for hooks.
Conditional Execution: Hooks can run only if specific conditions are met.
Cancellation Support using AbortController.
Execution Limits & Lifetimes to control hook invocation.

🍪:Built-in Router

Supports GET, POST, PUT, DELETE, PATCH methods.
Dynamic route parameter handling (/api/user/:id).
Middleware-like execution via hooks.

🍪:Advanced Response Handling

Automatic JSON serialization.
Streaming support for large responses.
Custom status code hooks to handle different HTTP statuses.

🍪:Error Handling & Logging

Hooks can capture and handle errors gracefully.
Global error hooks ensure stability.
Custom event emitters for debugging.

Installation

npm install biscuitsjar

Usage

Initializing the Framework

const Biscuit = require('./Biscuit');
const app = new Biscuit();

Defining Routes

app.route('GET', '/api/hello', async (req, res) => {
  res.send({ message: 'Hello, World!' });
});

app.route('POST', '/api/data', async (req, res) => {
  res.send({ message: 'Data received' }, 201);
});

Hook System Usage

Biscuit's hook system allows attaching custom behavior to different parts of the request lifecycle.

Request Hooks (atReq)

Executed when a request is received.

app.hook.atReq('/api/data', async (req, res) => {
  console.log('Processing request:', req.url);
}, { priority: 50 });

Response Hooks (atRes)

Executed before sending the response.

app.hook.atRes('/api/data', async (req, res) => {
  console.log('Finalizing response for:', req.url);
});

Authentication Hooks (atAuth)

Executed before route processing to enforce authentication.

app.hook.atAuth('/secure', async (req, res) => {
  if (!req.headers.authorization) {
    throw new Error('Unauthorized');
  }
});

Route-Specific Hooks (atRoute)

Executed after the route handler.

app.hook.atRoute('/api/users', async (req, res) => {
  console.log('Route logic executed');
});

Error Handling Hooks (atErr)

Executed when an error occurs.

app.hook.atErr('/api/data', async (req, res) => {
  console.error('Handling error for:', req.url);
});

Status-Based Hooks (atStatus)

Executed when a specific HTTP status is set.

app.hook.atStatus(404, async (req, res) => {
  console.warn('Handling 404 error.');
});

Pre and Post Hooks

Define pre-processing and post-processing hooks for more granular control.

app.hook.preHook('atReq', '/api/data', async (req, res) => {
  console.log('Pre-processing request...');
});

app.hook.postHook('atReq', '/api/data', async (req, res) => {
  console.log('Post-processing request...');
});

Removing Hooks

Hooks can be removed dynamically.

app.hook.removeHook('atReq', '/api/data', someFunction);

Event Handling

Biscuit provides an event system for handling errors and debugging.

app.hook.on('error', (err) => {
  console.error('Hook Error:', err);
});

Starting the Server

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Detailed Explanation of Biscuit Components

Hook System

The Hook system in Biscuit allows developers to attach middleware-like functions at different request lifecycle stages.

Hook Structure

Each hook has:

Function (fn): The function to execute.
Lifetime (lifetime): How long the hook remains active.
Execution Limit (maxExecutions): Maximum times it can be executed.
Condition (condition): A function that must return true for execution.
Priority (priority): Determines execution order.

Router System

Biscuit's Router is designed to handle: 🍪: Static Routes (/api/users) 🍪: Dynamic Routes (/api/user/:id) 🍪:Method-Specific Routes (GET, POST, etc.) 🍪:Query Parameters & URL Parsing

Example:

app.route('GET', '/api/user/:id', async (req, res) => {
  res.send({ userId: req.params.id });
});

Response System

Biscuit provides enhanced response handling: 🍪 Automatic JSON Serialization 🍪:Streaming Support for large data 🍪:Custom Status Codes & Status-Based Hooks

Example:

res.send({ message: "Success" }, 200);

Advanced Features

Streaming Response Handling

For large datasets, use streaming instead of sending entire data at once.

const fs = require('fs');
app.route('GET', '/download', (req, res) => {
  const fileStream = fs.createReadStream('largefile.txt');
  res.send(fileStream);
});

Global Middleware via Hooks

Example of a global request logger:

app.hook.atReq(async (req, res) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
});

Graceful Shutdown Handling

To ensure proper cleanup when the server shuts down:

process.on('SIGTERM', () => {
  console.log("Shutting down server...");
  app.server.close(() => {
    console.log("Server closed.");
  });
});

Final Thoughts

Biscuit is designed to be lightweight, flexible, and highly customizable. The powerful Hook system allows developers to modify request flow, add authentication, handle errors, and customize routing seamlessly.