diesel-core
Version:
Web framework built on Web Standards
326 lines (248 loc) • 9.03 kB
Markdown
### [Read the docs](https://diesel-core.vercel.app/)
# DieselJS
**Diesel** is a simple and lightweight HTTP server library for Bun.js that provides you with complete control over your API routes and middleware. It is designed to be intuitive and efficient, allowing you to quickly set up a server, define routes, and optimize important paths for faster response times.
**Now Supports Node.js & Cloduflare adaptors**
## Installation
Install diesel-core via bun | npm | yarn | pnpm
```bash
npm install diesel-core
```
```bash
bun add diesel-core
```
### Code Example
```javascript
import {Diesel} from "diesel-core"
const app = new Diesel()
const port = 3000
app.get("/", async (ctx:ContextType) => {
return ctx.text("Hello world...!",200)
// Note :- passing statusCode is optional
})
// Start the server
app.listen(port, () => {
console.log(`diesel is running on port ${port}`)
})
```
# HttpMethods
**In Diesel there are almost all http methods that you can use**
```javascript
app.get() app.post() app.put()
app.patch() app.delete() app.any()
app.head() app.options() , app.onMethod(method,path,handler)
```
# Cloudflare workers
### now you can use diesel.js for cloudflare workers apis
```ts
import {Diesel} from "diesel-core"
const app = new Diesel({
platform: 'cf',
logger: true
})
.get("/", (ctx) => ctx.text("Welcome to Diesel.js on Cloudflare Workers!"));
export default {
fetch: app.fetch()
}
```
**Note make sure to add platform:'cf' & call fetch(), it gives you real fetch handler**
# Node.js adaptor
### Now you can use Diesel.js for Node.js
```ts
import { Diesel } from "diesel-core"
import { serve } from 'diesel-core/node'
const app =
new Diesel({
logger:true
})
.get("/", (c) => {
return c.text(`hello from node diesel/`)
})
serve({
fetch: app.fetch(),
port: 3000
})
```
# CORS
### Diesel supports cors out of the box
``` ts
app.use(cors{
origin: ['http://localhost:5173','*'],
methods: ['GET','POST','PUT','DELETE'],
allowedHeaders: ['Content-Type','Authorization']
})
```
# Filter and Route Security
**Diesel** provides a simple way to manage public and protected routes by using a filter() method. You can define specific routes to be publicly accessible, while others will require authentication or custom middleware functions.
### How to Use the Filter
The **filter()** method allows you to secure certain endpoints while keeping others public. You can specify routes that should be publicly accessible using permitAll(), and apply authentication or other middleware to the remaining routes with require().
### Example Usage
```javascript
import {Diesel} from "diesel-core";
import jwt from 'jsonwebtoken';
const app = new Diesel();
async function authJwt (ctx:ContextType, server?:Server): Promise<void | Response> {
const token = await ctx.cookies?.accessToken // Retrieve the JWT token from cookies
if (!token) {
return ctx.json({ message: "Authentication token missing" },401);
}
try {
// Verify the JWT token using a secret key
const user = jwt.verify(token, secret); // Replace with your JWT secret
// Set the user data in context
ctx.set('user',user);
} catch (error) {
return ctx.json({ message: "Invalid token" },403);
}
}
// Define routes and apply filter
app
.filter()
.routeMatcher('/api/user/register', '/api/user/login', '/test/:id', '/cookie')
.permitAll()
.authenticate([authJwt]);
// Example public route (no auth required)
app.get("/api/user/register", async (ctx:ContextType) => {
return ctx.json({ msg: "This is a public route. No authentication needed." });
});
// Example protected route (requires auth)
app.get("/api/user/profile", async (ctx:ContextType) => {
// This route is protected, so the auth middleware will run before this handler
const user = ctx.get.user
return ctx.json({
msg: "You are authenticated!" ,
user
});
});
// Start the server
const port = 3000;
app.listen(port, () => {
console.log(`Diesel is running on port ${port}`);
})
```
# Filter Methods
1. **routeMatcher(...routes: string[])** : Passed endpoints in this routeMatcher will be ***Public*** means they don't need authentication, including those with dynamic parameters (e.g., /test/:id).
```javascript
.routeMatcher('/api/user/register', '/api/user/login', '/test/:id')
```
1. **permitAll()** : Marks the routes specified in routeMatcher() as publicly accessible, meaning no middleware (like authentication) will be required for these routes.
```javascript
.permitAll()
```
1. **authenticate([fnc?: middlewareFunc])** :Means that defined routes in ***routeMatcher*** is public & All endpoints needs authentication.
*Note* : If you don't pass a middleware function to authenticate(), DieselJS will throw an "Unauthorized" error by default. Ensure that you implement and pass a valid authentication function
```javascript
.authenticate([authJwt])
.authenticate([authJwt, ....]) // you can can add many auth midlleware to authenticate
```
## Use Case
* **Public Routes** : Some routes ***(like /api/user/register or /api/user/login)*** are often open to all users without authentication. These routes can be specified with permitAll().
* **Protected Routes** : For other routes ***(like /api/user/profile)***, you'll want to require authentication or custom middleware. Use require(authJwt) to ensure that the user is authenticated before accessing these routes.
# Using Hooks in DieselJS
DieselJS allows you to enhance your request handling by utilizing hooks at various stages of the request lifecycle. This gives you the flexibility to execute custom logic for logging, authentication, data manipulation, and more.
### Available Hooks
1. **onRequest**: Triggered when a request is received.
2. **preHandler**: Invoked just before the request handler executes.
<!-- 3. **postHandler**: Executed after the request handler completes but before sending the response. -->
3. **onSend**: Called just before the response is sent to the client.
4. **onError** : Executes if any error occurs
### How to Define Hooks
To define hooks in your DieselJS application, you can add them directly to your `Diesel` instance. Here's how to set up and use each hook:
### Example Usage
```javascript
// define and onError hook
app.addHooks("onError",(error,req,url,server) => {
console.log(`error occured ${error.message}`)
// retunr new Response(......)
})
// Define an onRequest hook
app.addHooks("onRequest",(req,url,server) =>{
console.log(`Request received: ${req.method} ${url}`);
})
// you get req,url & server instance in onReq
// Define a preHandler hook
app.addHooks("preHandler",(ctx:ContextType) =>{
// Check for authentication token
const authToken = ctx.req.headers.get("Authorization");
if (!authToken) {
return new Response("Unauthorized", { status: 401 });
}
})
// Define an onSend hook
app.addHooks('onSend',async (ctx, result) => {
console.log(`Sending response with status: ${result.status}`);
return result; // You can modify the response here if needed
});
```
# Middleware example
**No Need to call NonSense *next()* in Middleware**
**just dont return , if evrything goes right**
```javascript
async function authJwt (ctx:ContextType): Promise<void | Response> {
try {
const token = ctx.cookies?.accessToken
if (!token) {
return ctx.json({ message: "Authentication token missing" },401);
}
// Verify the JWT token using a secret key
const user = jwt.verify(token, secret);
ctx.set('user',user);
} catch (error) {
return ctx.json({ message: "Invalid token" },403);
}
}
// this is a global middleware
app.use(authJwt)
OR
app.use(authJwt,middleware2 , ...)
// path middleware example
app.use("/user",authJWT)
OR
// app.use(["/user","/home"],[authJWT,middleware2])
//means /user and /home has two middlewares
```
# set cookies
```javascript
app.get("/set-cookie", async(ctx:ContextType) => {
const user = {
name: "pk",
age: 22,
}
const accessToken = jwt.sign(user, secret, { expiresIn: "1d" })
const refreshToken = jwt.sign(user, secret ,{ expiresIn: "10d" })
const options = {
httpOnly: true,
secure: true,
maxAge: 24 * 60 * 60 * 1000,
sameSite: "Strict",
path: "/",
}
ctx
.setCookie("accessToken", accessToken, options)
.setCookie("refreshToken", refreshToken, options)
return ctx.json({msg:"setting cookies"})
})
```
# Render a HTML page
```javascript
app.get("/render",async (ctx) => {
return ctx.file(`${import.meta.dir}/index.html`)
})
```
# redirect
```javascript
app.get("/redirect",(ctx:ContextType) => {
return ctx.redirect("/");
})
```
# get params
**You can use set ***Multiparams***** , ***like this***
```javascript
app.get("/product/:productId/:productName")
```
```javascript
app.get("/hello/:id/",(ctx:ContextType) => {
const id = ctx.params.id
const query = ctx.query // you can pass query name also , you wanna get
return ctx.json({ msg: "Hello", id });
})
```