bun-crumb 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,93 @@
+# <div align='center'> <a> **Crumb** </a> </div>
+
+<div align='center'>  
+ 
+ [![CI](https://github.com/a-marigold/crumb/actions/workflows/ci.yaml/badge.svg)](https://github.com/a-marigold/crumb/actions) ![bun](https://img.shields.io/badge/Bun-000?logo=bun&logoColor=fff) [![npm](https://img.shields.io/npm/v/bun-crumb)](https://npmjs.com/package/bun-crumb)
+
+</div>
+ 
+
+
+### Features
+
+-   Only Bun is supported
+
+-   No classes
+
+-   Uses Bun’s HTTP API
+
+### Installation
+
+```bash
+bun add crumb
+```
+
+### Usage
+
+Handling Requests
+
+```typescript
+import { createRoute, type RouteResponse } from 'crumb-bun';
+
+type Product = { title: string; price: number; id: number };
+
+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 },
+            ],
+            { status: 200 }
+        );
+    },
+});
+```
+
+&nbsp;
+
+Middleware / Pre-handlers
+
+```typescript
+import { createRoute, type RouteResponse } from 'crumb-bun';
+
+type Product = { title: string; price: number; id: number };
+
+const products: Product[] = [];
+
+createRoute({
+    url: '/products',
+    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: RouteResponse<{ body: Product }>) => {
+        products.push(body);
+
+        return response.send(body, { status: 201 });
+    },
+});
+```
+
+&nbsp;
+
+Setting Headers and Status
+
+```typescript
+import { createRoute } from 'crumb-bun';
+
+createRoute({
+    url: '/auth',
+    method: 'POST',
+    handler: (request, response) => {},
+});
+```

package/dist/__tests__/server.test.d.ts

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

package/dist/errors/HttpError.d.ts

@@ -0,0 +1,4 @@
+export declare class HttpError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,284 @@
+import { BunRequest } from 'bun';
+
+/**
+ * The global Schema type that reflects schema type in `Validate` function
+ *
+ * @default {}
+ *
+ * @example
+ *
+ * ```typescript
+ * // types/global.d.ts
+ * import type { ZodType } from 'zod';
+ *
+ *
+ *
+ * declare module 'crumb-bun' {
+ *    interface Schema {
+ *        zod: ZodType;
+ *    }
+ * }
+ * ```
+ *  
+ * ```json
+ * // tsconfig.json
+ * {
+ *    "include": ["types"]
+ * }
+ * ```
+ */
+interface Schema {
+}
+/**
+ * Straight `Schema` type
+ */
+type SchemaData = Schema[keyof Schema];
+/**
+ * The schema validator function type.
+ *
+ * Supports any schemas like `zod`, `ajv`, `yup`
+ */
+type Validate = (data: unknown, schema: SchemaData) => boolean;
+
+/**
+ * HTTP Method primitive.
+ *
+ * @example
+ * ```typescript
+ * const method: HttpMethod = 'GET';
+ * ```
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+/**
+ * HTTP Header struct.
+ */
+type Header = {
+    name: string;
+    value: string;
+};
+type Headers = ResponseInit['headers'];
+/**
+ * Type of route handler `request`
+ */
+interface RouteRequest<T extends {
+    parsedBody: unknown;
+} = {
+    parsedBody: unknown;
+}> extends Omit<BunRequest, 'body'> {
+    /**
+     * Parsed, validated from schema body of reqeust
+     */
+    parsedBody: T extends {
+        parsedBody: unknown;
+    } ? T['parsedBody'] : unknown;
+}
+interface ResponseOptions {
+    status: number;
+    statusText?: string;
+}
+/**
+ * Type of route handler `response`
+ */
+interface RouteResponse<T extends {
+    body: unknown;
+} = {
+    body: unknown;
+}> {
+    setHeader: (name: Header['name'], value: Header['value']) => void;
+    send: (data: T['body'], options?: ResponseOptions) => void;
+}
+type Route = Partial<Record<HttpMethod, RouteOptions>>;
+type RouteHandler = (request: RouteRequest, response: RouteResponse) => void;
+type RouteOptions = {
+    url: string;
+    method: HttpMethod;
+    schema?: SchemaData;
+    onRequest?: RouteHandler;
+    preHandler?: RouteHandler;
+    handler: RouteHandler;
+};
+
+interface ListenOptions {
+    /**
+     * Server port to listen
+     */
+    port?: number | string;
+    /**
+     * Server hostname to listen
+     *
+     * @example `localhost`, `0.0.0.0`
+     *
+     */
+    hostname?: string;
+    /**
+     * Development flag.
+     *
+     * @default NODE_ENV enviroment variable value
+     */
+    development?: boolean;
+    /**
+     * Global schema validator function that will be used in every route
+     */
+    schemaValidator?: Validate;
+}
+
+type PreparedRoute = Partial<Record<HttpMethod, WrappedRouteCallback>>;
+type WrappedRouteCallback = (request: BunRequest) => Promise<Response>;
+/**
+ * Used straight as Bun.serve `routes` object.
+ */
+type PreparedRoutes = Record<RouteOptions['url'], PreparedRoute>;
+type Routes = Map<RouteOptions['url'], Route>;
+/**
+ * An internal Map with routes of app. Do not use it in user code to prevent undefined errors
+ */
+declare const _routes: Routes;
+/**
+ * Runtime function that used in request.
+ * Parses body to supported content type (json, plain text) and validates it with route schema.
+ *
+ * @param {BunRequest} request incoming bun request.
+ * @param {string} contentType request `Content-Type` header value.
+ * @param {Schema} schema json or any schema with declared `Schema` type.
+ * @param {Validate} schemaValidator schema validator function that receives `data` and `schema` arguments.
+ *
+ * @returns {Promise<unknown>} Promise with body
+ */
+declare const handleBody: (request: BunRequest, contentType: string, schema?: SchemaData, schemaValidator?: Validate) => Promise<unknown>;
+/**
+ * Internal `server` function.
+ * Creates a function with handler and all route hooks.
+ *
+ * The created function can be used as a callback for route in Bun.serve `routes` object.
+ *
+ *
+ *
+ *
+ *
+ * @param routeOptions options of route
+ * @returns {WrappedRouteCallback} Function that is ready to be used in Bun.serve `routes`
+ */
+declare const wrapRouteCallback: (routeOptions: RouteOptions, schemaValidator?: Validate) => WrappedRouteCallback;
+/**
+ * Internal `server` function.
+ * Prepares a route to be used in Bun.serve `routes` object.
+ *
+ * @param {Route} route
+ *
+ * @returns {PreparedRoute} Route object with `GET` or other http method keys with wrapped route callbacks.
+ *
+ * @example
+ * ```typescript
+ * prepareRoute({
+ *   GET: {
+ *     url: '/products',
+ *       method: 'GET',
+ *       handler: (request, response) => {},
+ *   },
+ *   POST: {
+ *     url: '/products/:id',
+ *       method: 'POST',
+ *       handler: (request, response) => {},
+ *   },
+ * });
+ * // Output will be:
+ * ({
+ *   GET: (request: BunRequest) => {
+ *     // ...code
+ *     return new Response();
+ *   },
+ *   POST: (request: BunRequest) => {
+ *     // ...code
+ *     return new Response();
+ *   },
+ * })
+ * ```
+ *
+ */
+declare const prepareRoute: (route: Route, schemaValidator?: Validate) => PreparedRoute;
+/**
+ * Internal server function.
+ * Calls `prepareRoute` for every route of `routes` Map and returns prepared routes to use in Bun.serve `routes`.
+ *
+ * @param {Routes} routes Map with routes to prepare.
+ *
+ * @returns {PreparedRoutes} An object that is used straight in Bun.serve `routes` object.
+ */
+declare const prepareRoutes: (routes: Routes, schemaValidator?: Validate) => PreparedRoutes;
+/**
+ * Starts serving http server.
+ *
+ *
+ * @param {ListenOption} options - options
+ *
+ *
+ *
+ * @example
+ *
+ * ```typescript
+ * import { listen } from 'crumb-bun';
+ *
+ * const PORT = proccess.env['PORT'] || 1000;
+ *
+ * listen(PORT, 'localhost');
+ * ```
+ */
+declare const listen: (options: ListenOptions) => void;
+
+/**
+ * Creates a route with `url`, `method` and `handler`.
+ * Should be called before `listen` function is called.
+ *
+ *
+ * @param {RouteOptions} routeOptions - route
+ *
+ *
+ *
+ * @example
+ * ```typescript
+ * createRoute({
+ *   url: '*',
+ *   method: 'GET',
+ *   handler: (request, response) => {
+ *     response.send(
+ *       { message: 'The resource you are looking for is not found.' },
+ *       { status: 404, statusText: 'Not Found' }
+ *     );
+ *  },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const deleteProduct = (
+ *   request: RouteRequest,
+ *   response: RouteResponse<{ body: { error: string } | { product: Product } }>
+ * ) => {
+ *     const id = request.params.id;
+ *
+ *     if (!(id in products)) {
+ *         return response.send(
+ *           { error: 'Product with this id is not found' },
+ *           { status: 404 }
+ *         );
+ *     }
+ *
+ *     const product = products[id];
+ *
+ *     products[id] = null;
+ *
+ *     return response.send(product);
+ * };
+ *
+ * createRoute({
+ *   url: '/products/:id',
+ *   method: 'DELETE',
+ *
+ *   handler: deleteProduct,
+ * });
+ * ```
+ */
+declare const createRoute: (routeOptions: RouteOptions) => void;
+
+export { _routes, createRoute, handleBody, listen, prepareRoute, prepareRoutes, wrapRouteCallback };
+export type { Header, Headers, HttpMethod, ListenOptions, ResponseOptions, Route, RouteHandler, RouteOptions, RouteRequest, RouteResponse, Routes, Schema, SchemaData, Validate, WrappedRouteCallback };

package/dist/index.js

@@ -0,0 +1 @@
+import{serve as t}from"bun";class e extends Error{status;constructor(t,e){super(e),this.status=t,this.name="HttpError"}}const n=new Map,s=(t,n,s,r)=>{const o={"application/json":t=>t.json().catch(t=>{throw new e(400,t)}).then(t=>{if(s&&r&&!r(t,s))throw new e(400,"Request does not match schema");return t}),"text/plain":t=>t.text().catch(t=>{throw new e(400,t)}).then(t=>{if(s&&r&&!r(t,s))throw new e(400,"Request does not match schema");return t})};return n in o?o[n](t):Promise.reject(new e(415,"Unsupported media type"))},r=(t,n)=>r=>{const o=r.headers.get("Content-Type")??"text/plain";return s(r,o,t.schema,n).then(e=>{const n=r;return n.parsedBody=e,((t,e)=>{let n,s,r=null;const o={},a={setHeader:(t,e)=>{o[t]=e},send:(t,e)=>{"object"==typeof t?o["Content-Type"]="application/json":"string"==typeof t&&(o["Content-Type"]="text/plain"),r=t,n=e?.status,s=e?.statusText}};return e.onRequest?.(t,a),e.preHandler?.(t,a),e.handler(t,a),new Response(null==r?null:JSON.stringify(r),{headers:o,status:n,statusText:s})})(n,t)}).catch(t=>t instanceof e?new Response(t.message,{status:t.status}):new Response("Internal server error",{status:500}))},o=(t,e)=>{const n={};for(const s of Object.entries(t))n[s[0]]=r(s[1],e);return n},a=(t,e)=>{const n={};for(const s of t)n[s[0]]=o(s[1],e);return t.clear(),n},c=e=>{t({port:e.port,hostname:e.hostname,development:e.development??!1,routes:a(n,e?.schemaValidator)})},u=t=>{const e=n.get(t.url);e?e[t.method]=t:n.set(t.url,{[t.method]:t})};export{n as _routes,u as createRoute,s as handleBody,c as listen,o as prepareRoute,a as prepareRoutes,r as wrapRouteCallback};

package/dist/route.d.ts

@@ -0,0 +1,55 @@
+import type { RouteOptions } from './types';
+/**
+ * Creates a route with `url`, `method` and `handler`.
+ * Should be called before `listen` function is called.
+ *
+ *
+ * @param {RouteOptions} routeOptions - route
+ *
+ *
+ *
+ * @example
+ * ```typescript
+ * createRoute({
+ *   url: '*',
+ *   method: 'GET',
+ *   handler: (request, response) => {
+ *     response.send(
+ *       { message: 'The resource you are looking for is not found.' },
+ *       { status: 404, statusText: 'Not Found' }
+ *     );
+ *  },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const deleteProduct = (
+ *   request: RouteRequest,
+ *   response: RouteResponse<{ body: { error: string } | { product: Product } }>
+ * ) => {
+ *     const id = request.params.id;
+ *
+ *     if (!(id in products)) {
+ *         return response.send(
+ *           { error: 'Product with this id is not found' },
+ *           { status: 404 }
+ *         );
+ *     }
+ *
+ *     const product = products[id];
+ *
+ *     products[id] = null;
+ *
+ *     return response.send(product);
+ * };
+ *
+ * createRoute({
+ *   url: '/products/:id',
+ *   method: 'DELETE',
+ *
+ *   handler: deleteProduct,
+ * });
+ * ```
+ */
+export declare const createRoute: (routeOptions: RouteOptions) => void;

package/dist/server.d.ts

@@ -0,0 +1,107 @@
+import type { BunRequest } from 'bun';
+import type { Route, RouteOptions, HttpMethod } from './types/route';
+import type { SchemaData, Validate } from './types';
+import type { ListenOptions } from './types';
+type PreparedRoute = Partial<Record<HttpMethod, WrappedRouteCallback>>;
+export type WrappedRouteCallback = (request: BunRequest) => Promise<Response>;
+/**
+ * Used straight as Bun.serve `routes` object.
+ */
+type PreparedRoutes = Record<RouteOptions['url'], PreparedRoute>;
+export type Routes = Map<RouteOptions['url'], Route>;
+/**
+ * An internal Map with routes of app. Do not use it in user code to prevent undefined errors
+ */
+export declare const _routes: Routes;
+/**
+ * Runtime function that used in request.
+ * Parses body to supported content type (json, plain text) and validates it with route schema.
+ *
+ * @param {BunRequest} request incoming bun request.
+ * @param {string} contentType request `Content-Type` header value.
+ * @param {Schema} schema json or any schema with declared `Schema` type.
+ * @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>;
+/**
+ * Internal `server` function.
+ * Creates a function with handler and all route hooks.
+ *
+ * The created function can be used as a callback for route in Bun.serve `routes` object.
+ *
+ *
+ *
+ *
+ *
+ * @param routeOptions options of route
+ * @returns {WrappedRouteCallback} Function that is ready to be used in Bun.serve `routes`
+ */
+export declare const wrapRouteCallback: (routeOptions: RouteOptions, schemaValidator?: Validate) => WrappedRouteCallback;
+/**
+ * Internal `server` function.
+ * Prepares a route to be used in Bun.serve `routes` object.
+ *
+ * @param {Route} route
+ *
+ * @returns {PreparedRoute} Route object with `GET` or other http method keys with wrapped route callbacks.
+ *
+ * @example
+ * ```typescript
+ * prepareRoute({
+ *   GET: {
+ *     url: '/products',
+ *       method: 'GET',
+ *       handler: (request, response) => {},
+ *   },
+ *   POST: {
+ *     url: '/products/:id',
+ *       method: 'POST',
+ *       handler: (request, response) => {},
+ *   },
+ * });
+ * // Output will be:
+ * ({
+ *   GET: (request: BunRequest) => {
+ *     // ...code
+ *     return new Response();
+ *   },
+ *   POST: (request: BunRequest) => {
+ *     // ...code
+ *     return new Response();
+ *   },
+ * })
+ * ```
+ *
+ */
+export declare const prepareRoute: (route: Route, schemaValidator?: Validate) => PreparedRoute;
+/**
+ * Internal server function.
+ * Calls `prepareRoute` for every route of `routes` Map and returns prepared routes to use in Bun.serve `routes`.
+ *
+ * @param {Routes} routes Map with routes to prepare.
+ *
+ * @returns {PreparedRoutes} An object that is used straight in Bun.serve `routes` object.
+ */
+export declare const prepareRoutes: (routes: Routes, schemaValidator?: Validate) => PreparedRoutes;
+/**
+ * Starts serving http server.
+ *
+ *
+ * @param {ListenOption} options - options
+ *
+ *
+ *
+ * @example
+ *
+ * ```typescript
+ * import { listen } from 'crumb-bun';
+ *
+ * const PORT = proccess.env['PORT'] || 1000;
+ *
+ * listen(PORT, 'localhost');
+ * ```
+ */
+export declare const listen: (options: ListenOptions) => void;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './route';
+export * from './server';
+export * from './schema';

package/dist/types/route.d.ts

@@ -0,0 +1,59 @@
+import type { BunRequest } from 'bun';
+import type { SchemaData } from './schema';
+/**
+ * HTTP Method primitive.
+ *
+ * @example
+ * ```typescript
+ * const method: HttpMethod = 'GET';
+ * ```
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+/**
+ * HTTP Header struct.
+ */
+export type Header = {
+    name: string;
+    value: string;
+};
+export type Headers = ResponseInit['headers'];
+/**
+ * Type of route handler `request`
+ */
+export interface RouteRequest<T extends {
+    parsedBody: unknown;
+} = {
+    parsedBody: unknown;
+}> extends Omit<BunRequest, 'body'> {
+    /**
+     * Parsed, validated from schema body of reqeust
+     */
+    parsedBody: T extends {
+        parsedBody: unknown;
+    } ? T['parsedBody'] : unknown;
+}
+export interface ResponseOptions {
+    status: number;
+    statusText?: string;
+}
+/**
+ * Type of route handler `response`
+ */
+export interface RouteResponse<T extends {
+    body: unknown;
+} = {
+    body: unknown;
+}> {
+    setHeader: (name: Header['name'], value: Header['value']) => void;
+    send: (data: T['body'], options?: ResponseOptions) => void;
+}
+export type Route = Partial<Record<HttpMethod, RouteOptions>>;
+export type RouteHandler = (request: RouteRequest, response: RouteResponse) => void;
+export type RouteOptions = {
+    url: string;
+    method: HttpMethod;
+    schema?: SchemaData;
+    onRequest?: RouteHandler;
+    preHandler?: RouteHandler;
+    handler: RouteHandler;
+};

package/dist/types/schema.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The global Schema type that reflects schema type in `Validate` function
+ *
+ * @default {}
+ *
+ * @example
+ *
+ * ```typescript
+ * // types/global.d.ts
+ * import type { ZodType } from 'zod';
+ *
+ *
+ *
+ * declare module 'crumb-bun' {
+ *    interface Schema {
+ *        zod: ZodType;
+ *    }
+ * }
+ * ```
+ *  
+ * ```json
+ * // tsconfig.json
+ * {
+ *    "include": ["types"]
+ * }
+ * ```
+ */
+export interface Schema {
+}
+/**
+ * Straight `Schema` type
+ */
+export type SchemaData = Schema[keyof Schema];
+/**
+ * The schema validator function type.
+ *
+ * Supports any schemas like `zod`, `ajv`, `yup`
+ */
+export type Validate = (data: unknown, schema: SchemaData) => boolean;

package/dist/types/server.d.ts

@@ -0,0 +1,24 @@
+import type { Validate } from './schema';
+export interface ListenOptions {
+    /**
+     * Server port to listen
+     */
+    port?: number | string;
+    /**
+     * Server hostname to listen
+     *
+     * @example `localhost`, `0.0.0.0`
+     *
+     */
+    hostname?: string;
+    /**
+     * Development flag.
+     *
+     * @default NODE_ENV enviroment variable value
+     */
+    development?: boolean;
+    /**
+     * Global schema validator function that will be used in every route
+     */
+    schemaValidator?: Validate;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "bun-crumb",
+    "version": "0.1.0",
+    "author": "marigold",
+    "module": "dist/index.js",
+    "license": "UNLICENSED",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/a-marigold/crumb-bun"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.3.10",
+        "@rollup/plugin-terser": "^0.4.4",
+        "@rollup/plugin-typescript": "^12.3.0",
+        "@types/bun": "latest",
+        "rollup": "^4.53.5",
+        "rollup-plugin-dts": "^6.3.0",
+        "tslib": "^2.8.1"
+    },
+    "files": [
+        "dist"
+    ],
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js"
+    },
+    "peerDependencies": {
+        "typescript": "^5"
+    },
+    "keywords": [
+        "typescript",
+        "bun",
+        "bun-crumb"
+    ],
+    "private": false,
+    "scripts": {
+        "lint": "bunx biome check",
+        "build": "bunx rollup -c",
+        "prepublishOnly": "bun run build",
+        "pshPublic": "bun publish --access public"
+    }
+}