bun-crumb 0.12.0 → 0.12.2

package/README.md

@@ -9,11 +9,11 @@
 
 ### Features
 
--   Only Bun is supported
+- Only Bun is supported
 
--   No classes
+- No classes
 
--   Uses Bun’s HTTP API
+- Uses `Bun.serve` routes
 
 ### Installation
 
@@ -34,59 +34,158 @@ const products: Product[] = [];
 
 createRoute({
     url: '/products',
+
     method: 'GET',
+
     handler: (request, response: RouteResponse<{ body: Product[] }>) => {
         return response.send(
             [
-                { title: 'cookie', price: 100, id: 1 },
-                { title: 'bread', price: 1600, id: 2 },
+                { title: 'bananas', price: 0.57, id: 1 },
+
+                { title: 'bread', price: 0.89, id: 2 },
+
+                { title: 'milk', price: 0.83, id: 3 },
             ],
-            { status: 200 }
+
+            { status: 200 },
         );
     },
 });
 ```
 
-&nbsp;
+### Benchmarks
+
+- Machine:
+    - windows 11
+    - intel core i5 10300H
+    - 16gb ram
+
+- Load testing tool: grafana/k6
+
+- Bun version: 1.3.6
+
+<details> 
+    <summary>k6 script</summary>
+
+```bash
+    sleep 1 | k6 run script.js
+```
 
-Middleware / Pre-handlers
+```javascript
+import { PORT } from './constants.js';
+
+import http from 'k6/http';
+
+export const options = {
+    scenarios: {
+        load: {
+            executor: 'constant-arrival-rate',
+
+            rate: 16000,
+            timeUnit: '1s',
+
+            duration: '30s',
+            preAllocatedVUs: 1000,
+
+            maxVUs: 3000,
+        },
+    },
+};
+
+export default () => {
+    http.post(
+        'http://localhost:' + PORT + '/',
+        JSON.stringify({ key: 'value' }),
+        { headers: { 'Content-Type': 'application/json' } },
+    );
+};
+```
+
+</details>
+
+<details>
+    <summary>Pure Bun server code</summary>
 
 ```typescript
-import { createRoute, type RouteResponse } from 'bun-crumb';
+import { serve, stdout } from 'bun';
+
+import { PORT } from './constants';
+
+serve({
+    routes: {
+        '/': {
+            POST: (request) => {
+                return request.json().then(
+                    (body) =>
+                        new Response(JSON.stringify(body), {
+                            headers: { 'Content-Type': 'application/json' },
+                        }),
+                );
+            },
+        },
+    },
+    port: PORT,
+});
+stdout.write('Bun is running\n');
+```
 
-type Product = { title: string; price: number; id: number };
+</details>
 
-const products: Product[] = [];
+<details>
+    <summary>Fastify server code</summary>
 
-createRoute({
-    url: '/products',
+```typescript
+import Fastify from 'fastify';
+
+import { PORT } from './constants';
+
+const fastify = Fastify({ logger: false });
+
+fastify.route({
+    url: '/',
     method: 'POST',
-    preHandler: (request, response) => {
-        if (products.find((product) => product.id === request.body.id)) {
-            return response.send(
-                { message: 'Product with this id already exists' },
-                { status: 409 }
-            );
-        }
+    handler: (request, response) => {
+        return response.send(request.body);
     },
-    handler: (request, response: RouteResponse<{ body: Product }>) => {
-        products.push(body);
+});
 
-        return response.send(body, { status: 201 });
-    },
+fastify.listen({ port: PORT }, () => {
+    Bun.stdout.write('Fastify is running\n');
 });
 ```
 
-&nbsp;
+</details>
+
+<details>
+    <summary>Bun Crumb server code</summary>
 
-Setting Headers and Status
+```bash
+sleep 1 | k6 run script.js
+```
 
 ```typescript
-import { createRoute } from 'bun-crumb';
+import { PORT } from './constants';
+
+import { listen, createRoute } from 'bun-crumb';
 
+//
 createRoute({
-    url: '/auth',
+    url: '/',
+
     method: 'POST',
-    handler: (request, response) => {},
+
+    handler: (request, response) => {
+        return request.handleBody().then(response.send);
+    },
 });
+
+listen({ port: PORT });
 ```
+
+</details>
+
+| Library   | Total requests | RPS            | Requests failed | Avg. request duration |
+| --------- | -------------- | -------------- | --------------- | --------------------- |
+| Pure Bun  | 482681         | 15958.069946/s | 0.00% (0)       | 12.48ms               |
+| Bun Crumb | 474870         | 15789.504029/s | 0.02% (101)     | 23.08ms               |
+| Fastify   | 364525         | 12060.63486/s  | 0.27% (1002)    | 237.68ms              |

package/dist/bench/src/k6/bunCrumb.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bench/src/k6/fastify.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bench/src/k6/pureBun.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bench/src/k6/script.d.ts

@@ -1,6 +1,14 @@
 export namespace options {
-    let vus: number;
-    let duration: string;
+    namespace scenarios {
+        namespace load {
+            let executor: string;
+            let rate: number;
+            let timeUnit: string;
+            let duration: string;
+            let preAllocatedVUs: number;
+            let maxVUs: number;
+        }
+    }
 }
 declare function _default(): void;
 export default _default;

package/dist/index.d.ts

@@ -121,7 +121,46 @@ interface RouteResponse<T extends {
 } = {
     body: unknown;
 }> {
-    send: (data: T['body'], options?: ResponseOptions) => void;
+    /**
+     * Sets Response body to provided `data`.
+     * Automatically sets `Content-Type` to `application/json` if an object was provided and transforms `data` to JSON.
+     *
+     * ### **IMPORTANT NOTES**:
+     *  - #### If `Content-Type` header is already set, this function will not change this header.
+     *
+     *
+     *
+     *
+     *  - #### If you want to complete request and send response, you must necessarily `return` the call of this function. Otherwise, code of your handler will continue executing and `Response` body could be changed.
+     *
+     * @param data value that will be sent to client
+     * @param options standard `Response` options from web API
+     *
+     * @example
+     * ```typescript
+     * response.setHeader('content-type', 'x-www-form-urlencoded'); // Set `Content-Type` header
+     *
+     * return response.send('Hello'); // This does not change `Content-Type` header, because this header is set above
+     * ```
+     *
+     * @example
+     * ```typescript
+     * return response.send('Hello'); // This sets `Content-Type` header to `text/plain`, because this header is not set above.
+     * ```
+     *
+     * @example
+     * ```typescript
+     * return response.send({ key: 'value' }); // This will set `Content-Type` header to `application/json`, because this header is not set above. Object is transformed to JSON automatically
+     * ```
+     *
+     * @example
+     * ```typescript
+     * response.send({key: 'value'}); // ❌ Without return, the code below changes the body of response
+     * response.send('Hello'); // ❌ This changes the body of response, but `Content-Type` header will not change
+     * ```
+     *
+     */
+    send: (data?: T['body'], options?: ResponseOptions) => void;
     /**
      * Sets `Location` header to provided `url` and `response.status` to provided `status`
      *
@@ -129,7 +168,7 @@ interface RouteResponse<T extends {
      *
      * @param url `Location` to redirect
      *
-     * @param status redirect http code (`3xx`)
+     * @param status redirect http code (`3xx`). Equals to 302 by default
      *
      * @example
      *
@@ -140,7 +179,7 @@ interface RouteResponse<T extends {
      * The same behaviour is
      * ```typescript
      * response.setHeader('Location', 'https://bun-crumb.vercel.app');
-     * return response.send('', {status: 302});
+     * return response.send('', { status: 302 });
      * ```
      */
     redirect: (url: string, status?: RedirectStatusCode | (number & {})) => void;
@@ -169,7 +208,7 @@ interface RouteResponse<T extends {
     setHeader: (name: Header['name'], value: Header['value']) => void;
     /**
      *
-     * @param options `Bun.Cookie` options parametr
+     * @param options `Bun.Cookie` options parameter
      *
      *
      *
@@ -215,7 +254,8 @@ interface ListenOptions {
 }
 
 /**
- * Starts serving http server.
+ *
+ *  Starts to serve http server.
  *
  *
  * @param {ListenOption} options - options
@@ -236,7 +276,8 @@ interface ListenOptions {
 declare const listen: (options?: ListenOptions) => void;
 
 /**
- * Creates a route with `url`, `method` and `handler`.
+ * #### Creates a route with `url`, `method` and `handler`.
+ *
  * Should be called before `listen` function is called.
  *
  *
@@ -260,8 +301,8 @@ declare const listen: (options?: ListenOptions) => void;
  *
  * @example
  * ```typescript
- * const deleteProduct = (
- *   request: RouteRequest,
+ * const deleteProduct: RouteHandler = (
+ *   request,
  *   response: RouteResponse<{ body: { error: string } | { product: Product } }>
  * ) => {
  *     const id = request.params.id;

package/dist/route.d.ts

@@ -1,6 +1,7 @@
 import type { RouteOptions } from './types';
 /**
- * Creates a route with `url`, `method` and `handler`.
+ * #### Creates a route with `url`, `method` and `handler`.
+ *
  * Should be called before `listen` function is called.
  *
  *
@@ -24,8 +25,8 @@ import type { RouteOptions } from './types';
  *
  * @example
  * ```typescript
- * const deleteProduct = (
- *   request: RouteRequest,
+ * const deleteProduct: RouteHandler = (
+ *   request,
  *   response: RouteResponse<{ body: { error: string } | { product: Product } }>
  * ) => {
  *     const id = request.params.id;

package/dist/runtime.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.d.ts

@@ -25,6 +25,10 @@ export declare const _routes: Routes;
  * @param {Validate} schemaValidator schema validator function that receives `data` and `schema` arguments.
  *
  * @returns {Promise<unknown>} Promise with body
+ *
+ *
+ *
+ *
  */
 export declare const handleBody: (request: BunRequest, contentType: string, schema?: SchemaData, schemaValidator?: Validate) => Promise<unknown>;
 /**
@@ -90,7 +94,8 @@ export declare const prepareRoute: (route: Route, schemaValidator?: Validate) =>
  */
 export declare const prepareRoutes: (routes: Routes, schemaValidator?: Validate) => PreparedRoutes;
 /**
- * Starts serving http server.
+ *
+ *  Starts to serve http server.
  *
  *
  * @param {ListenOption} options - options

package/dist/types/route.d.ts

@@ -60,7 +60,46 @@ export interface RouteResponse<T extends {
 } = {
     body: unknown;
 }> {
-    send: (data: T['body'], options?: ResponseOptions) => void;
+    /**
+     * Sets Response body to provided `data`.
+     * Automatically sets `Content-Type` to `application/json` if an object was provided and transforms `data` to JSON.
+     *
+     * ### **IMPORTANT NOTES**:
+     *  - #### If `Content-Type` header is already set, this function will not change this header.
+     *
+     *
+     *
+     *
+     *  - #### If you want to complete request and send response, you must necessarily `return` the call of this function. Otherwise, code of your handler will continue executing and `Response` body could be changed.
+     *
+     * @param data value that will be sent to client
+     * @param options standard `Response` options from web API
+     *
+     * @example
+     * ```typescript
+     * response.setHeader('content-type', 'x-www-form-urlencoded'); // Set `Content-Type` header
+     *
+     * return response.send('Hello'); // This does not change `Content-Type` header, because this header is set above
+     * ```
+     *
+     * @example
+     * ```typescript
+     * return response.send('Hello'); // This sets `Content-Type` header to `text/plain`, because this header is not set above.
+     * ```
+     *
+     * @example
+     * ```typescript
+     * return response.send({ key: 'value' }); // This will set `Content-Type` header to `application/json`, because this header is not set above. Object is transformed to JSON automatically
+     * ```
+     *
+     * @example
+     * ```typescript
+     * response.send({key: 'value'}); // ❌ Without return, the code below changes the body of response
+     * response.send('Hello'); // ❌ This changes the body of response, but `Content-Type` header will not change
+     * ```
+     *
+     */
+    send: (data?: T['body'], options?: ResponseOptions) => void;
     /**
      * Sets `Location` header to provided `url` and `response.status` to provided `status`
      *
@@ -68,7 +107,7 @@ export interface RouteResponse<T extends {
      *
      * @param url `Location` to redirect
      *
-     * @param status redirect http code (`3xx`)
+     * @param status redirect http code (`3xx`). Equals to 302 by default
      *
      * @example
      *
@@ -79,7 +118,7 @@ export interface RouteResponse<T extends {
      * The same behaviour is
      * ```typescript
      * response.setHeader('Location', 'https://bun-crumb.vercel.app');
-     * return response.send('', {status: 302});
+     * return response.send('', { status: 302 });
      * ```
      */
     redirect: (url: string, status?: RedirectStatusCode | (number & {})) => void;
@@ -108,7 +147,7 @@ export interface RouteResponse<T extends {
     setHeader: (name: Header['name'], value: Header['value']) => void;
     /**
      *
-     * @param options `Bun.Cookie` options parametr
+     * @param options `Bun.Cookie` options parameter
      *
      *
      *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bun-crumb",
-    "version": "0.12.0",
+    "version": "0.12.2",
     "author": "marigold",
     "module": "dist/index.js",
     "license": "UNLICENSED",
@@ -17,6 +17,7 @@
         "rollup-plugin-dts": "^6.3.0",
         "tslib": "^2.8.1"
     },
+    "homepage": "https://bun-crumb.vercel.app",
     "files": [
         "dist"
     ],