pronghorn 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

package/README.md

@@ -0,0 +1,137 @@
+# Pronghorn 🦌
+
+Pronghorn is a fast, lightweight, TypeScript-first backend framework built for [Bun](https://bun.sh/). Like its namesake, it's designed for speed and agility, with a clean API, zero-config setup, and a modular plugin system. Pronghorn brings together the simplicity of [Express](https://expressjs.com/) and the performance-first mindset of [Fastify](https://fastify.dev/), giving developers a streamlined way to build modern, scalable applications.
+
+> Built exclusively for Bun, no Node.js support, by design.> Built exclusively for Bun, no Node.js support, by design.
+
+## Why Pronghorn
+
+Pronghorn avoids two failure modes seen in other Bun frameworks: forced file-based conventions, and unecessary Node-era abstractions layered on top of what Bun's own `Bun.serve` already provides.
+- Routes, middleware, and plugins are all defined programmatically, and registered via plain method calls (`app.get(...)`, `app.use(...)`, `app.register(...)`).
+- Filesystem-convention discovery is available as an opt-in layer, fully composable with manual registration.
+- It sits directly on top of `Bun.serve`, with a typed `Context` wrapping the standard `Request`/`Response` Web APIs.
+- Middleware declares its own scope (`"global"` or `"route"`), so you can control exactly where each one runs.
+- Pluggable, not batteries-included, it ships with generic building blocks (CORS, logging, JWT parsing, rate limiting, validation, EJS, static files) with zero opinions about your database or business logic.
+- First-class WebSockets via `app.ws(path, handlers)`, dispatched through Bun's native WebSocket support.
+
+## Installation
+
+```bash
+bun add pronghorn
+```
+
+Requires Bun `>=1.3.0`. Installing under Node.js fails intentionally during `preinstall`.
+
+## Quick Start
+
+```ts
+import { createApp, cors, logger, errorHandler } from 'pronghorn'
+
+const app = createApp()
+
+app.use(cors)
+app.use(logger)
+app.use(errorHandler)
+
+app.get('/', context => context.json({ message: 'Hello from Pronghorn 🦌' }))
+
+const server = await app.listen(4000)
+console.log(`Server running at http://localhost:${server.port}`)
+```
+
+## Core concepts
+
+### Routes
+
+Registered via `app.get/post/put/patch/delete(path, handler, options?)`, with `:param` dynamic segments and optional per-route middlewares/schema.
+
+### Middleware
+
+Shape: `(context, next) => Response`. Each middleware exports a scope, `"global"` (applied via `app.use()`, runs on every request) or `"route"` (never auto-applied, opt in via a route's middlewares option). This is why `createJwtAuth` (global, non-blocking token decode) and `requireAuth` (route-scoped, blocking) are separate exports.
+
+### Plugins
+
+Plain functions receiving the shared AppContext, which can call `app.decorate(name, value)` to attach anything app-wide: a Database client, a render function, a logger. `app.register()` awaits async plugins before the server starts.
+
+### Decorators
+
+Anything decorated in a plugin is readable in any request via `context.get<T>(name)`, this is how `ejsPlugin` exposes `render`, `prismaPlugin` exposes `prisma`, and `staticPlugin` exposes `serveStatic`.
+
+### Hooks
+
+`app.addHook(name, handler)` for `"onRequest"`, `"preHandler"`, or `"onResponse"`, fixed lifecycle points independent of the middleware chain.
+
+### WebSockets
+
+`app.ws(path, handlers)` registers `open`/`message`/`close` handlers, dispatched by path through Bun's single native websocket object.
+
+### Schema validation
+
+Pass a Zod schema via a route's schema option; Pronghorn validates automatically and populates `context.locals.body`/`context.locals.query`, throwing a structured `HttpError(400)` on failure.
+
+### Error handling
+
+Throw `HttpError` or use `badRequest`/`unauthorized`/`forbidden`/`notFound`; the `errorHandler` middleware converts these into clean JSON responses.
+
+### Graceful shutdown
+
+`app.onClose(handler)` registers cleanup logic that runs automatically on `SIGINT`/`SIGTERM` before the server stops.
+
+## Autoloading (optional)
+
+```ts
+import { createApp, autoloadRoutes, autoloadMiddlewares, autoloadPlugins, autoloadHooks } from 'pronghorn'
+import { join } from 'node:path'
+
+const app = createApp()
+
+await autoloadPlugins(app, join(__dirname, 'plugins'))
+await autoloadMiddlewares(app, join(__dirname, 'middlewares'))
+await autoloadHooks(app, join(__dirname, 'hooks'))
+await autoloadRoutes(app, join(__dirname, 'routes'))
+
+await app.listen(4000)
+```
+
+Route files use a `.method.ts` suffix (`.get.ts`, `.post.ts`, etc.), folder structure maps to path segments, `index` files map to the parent path, and `[param]` folders/files become `:param`.
+
+## Built-in middleware
+
+| Export                       | Scope            | Description                                                   |
+| ---------------------------- | ---------------- | ------------------------------------------------------------- |
+| `cors`                       | global           | CORS headers + `OPTIONS` preflight handling                   |
+| `logger`                     | global           | Logs method, path, status, duration                           |
+| `errorHandler`               | global           | Converts thrown `HttpErrors` into JSON responses              |
+| createJwtAuth({ secret })    | global (factory) | Decodes `Bearer` JWT into `context.locals.user`, never blocks |
+| `requireAuth`                | route            | Rejects with `401` unless `context.locals.user` is set        |
+| `rateLimit(limit, windowMs)` | route (factory)  | In-memory IP-keyed token-bucket limiter                       |
+| `validate(schema)`           | -                | Applied automatically via a route's `schema` option           |
+
+## Built-in plugins
+
+| Export       | Decorates   | Description                                                                                |
+| ------------ | ----------- | ------------------------------------------------------------------------------------------ |
+| ejsPlugin    | render      | Renders `.ejs` views, optional shared layout                                               |
+| staticPlugin | serveStatic | Serves files from a public directory with path-traversal protection                        |
+| prismaPlugin | prisma      | Attaches any DB client you pass in, no `@prisma/client` dependency inside Pronghorm itself |
+
+## API reference
+
+`createApp(): App` creates a new application instance.
+
+| Method                                                | Description                                  |
+| ----------------------------------------------------- | -------------------------------------------- |
+| `.use(middleware, scope?)`                            | Registers global middleware                  |
+| `.register(plugin, options?)`                         | Runs a plugin against the shared app context |
+| `.get/post/put/patch/delete(path, handler, options?)` | Registers a route                            |
+| `.ws(path, handlers)`                                 | Registers a WebSocket route                  |
+| `.addHook(name, handler)`                             | Registers a lifecycle hook                   |
+| `.onClose(handler)`                                   | Registers shutdown cleanup logic             |
+| `.listen(port)`                                       | Starts the Bun server                        |
+| `.close()`                                            | Stops the server manually                    |
+
+`Context` exposes `request`, `params`, `query`, `locals`, `get<T>(name)`, `json(data, status?)`, and `redirect(url, status?)`.
+
+## License
+
+[WTFPL](https://www.wtfpl.net/) (Do What the Fuck You Want to Public License), see [LICENSE](./LICENSE) for details.

package/dist/core/app.d.ts

@@ -0,0 +1,34 @@
+import type { AppContext, Dispatcher, Handler, Hook, HookName, Method, Middleware, MiddlewareScope, PluginFn, RouteOptions, WebSocketHandlers, WebSocketData, CloseHandler } from '../core/types';
+import { type Route } from '../core/router';
+import type { Server } from 'bun';
+export declare class App {
+    private globalMiddlewares;
+    private routes;
+    private wsRoutes;
+    private hooks;
+    private closeHandlers;
+    private decorators;
+    private store;
+    private server;
+    readonly context: AppContext;
+    use(middleware: Middleware, scope?: MiddlewareScope): this;
+    register(plugin: PluginFn, options?: Record<string, unknown>): Promise<this>;
+    addHook(name: HookName, handler: Hook): this;
+    onClose(handler: CloseHandler): this;
+    route(method: Method, path: string, handler: Handler, options?: RouteOptions): this;
+    get(path: string, handler: Handler, options?: RouteOptions): this;
+    post(path: string, handler: Handler, options?: RouteOptions): this;
+    put(path: string, handler: Handler, options?: RouteOptions): this;
+    patch(path: string, handler: Handler, options?: RouteOptions): this;
+    delete(path: string, handler: Handler, options?: RouteOptions): this;
+    ws(path: string, handlers: WebSocketHandlers): this;
+    getWsRoute(path: string): WebSocketHandlers | undefined;
+    hasWsRoute(path: string): boolean;
+    dispatcher(): Dispatcher;
+    private buildContext;
+    listen(port: number): Promise<Server<WebSocketData>>;
+    close(): void;
+    getRoutes(): Route[];
+    getDecorators(): Record<string, unknown>;
+}
+export declare function createApp(): App;

package/dist/core/autoload.d.ts

@@ -0,0 +1,5 @@
+import type { App } from './app';
+export declare function autoloadPlugins(app: App, directory: string): Promise<void>;
+export declare function autoloadMiddlewares(app: App, directory: string): Promise<void>;
+export declare function autoloadHooks(app: App, directory: string): Promise<void>;
+export declare function autoloadRoutes(app: App, directory: string): Promise<void>;

package/dist/core/hooks.d.ts

@@ -0,0 +1,2 @@
+import type { Hook, Context } from './types';
+export declare function runHooks(hooks: Hook[], context: Context): Promise<void>;

package/dist/core/loader.d.ts

@@ -0,0 +1 @@
+export declare function scanDirectory(directory: string, extensions?: string[]): Promise<string[]>;

package/dist/core/middleware.d.ts

@@ -0,0 +1,2 @@
+import type { Middleware, Dispatcher } from './types';
+export declare function composeMiddlewares(middlewares: Middleware[], finalHandler: Dispatcher): Dispatcher;

package/dist/core/router.d.ts

@@ -0,0 +1,12 @@
+import type { Handler, Middleware, Method, RouteSchema } from './types';
+export interface Route {
+    method: Method;
+    segments: string[];
+    handler: Handler;
+    middlewares: Middleware[];
+    schema?: RouteSchema;
+}
+export declare function matchRoute(routes: Route[], method: string, pathname: string): {
+    route: Route;
+    params: Record<string, string>;
+} | null;

package/dist/core/types.d.ts

@@ -0,0 +1,61 @@
+import type { ServerWebSocket } from 'bun';
+import type { ZodType } from 'zod';
+export interface Context {
+    request: Request;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    locals: Record<string, unknown>;
+    decorators: Record<string, unknown>;
+    get: <T = unknown>(name: string) => T;
+    json: (data: unknown, status?: number) => Response;
+    redirect: (url: string, status?: number) => Response;
+}
+export interface AppContext {
+    set: (key: string, value: unknown) => void;
+    get: <T = unknown>(key: string) => T;
+    decorate: (name: string, value: unknown) => void;
+    decorators: Record<string, unknown>;
+}
+export type PluginFn = (app: AppContext, options?: Record<string, unknown>) => Promise<void> | void;
+export type MiddlewareScope = 'global' | 'route';
+export type Next = () => Promise<Response>;
+export type Middleware = (context: Context, next: Next) => Promise<Response>;
+export type Handler = (context: Context) => Promise<Response> | Response;
+export type Dispatcher = (context: Context) => Promise<Response>;
+export type Method = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+export interface RouteSchema {
+    body?: ZodType;
+    query?: ZodType;
+}
+export interface RouteOptions {
+    middlewares?: Middleware[];
+    schema?: RouteSchema;
+}
+export type HookName = 'onRequest' | 'preHandler' | 'onResponse';
+export type Hook = (context: Context) => Promise<void> | void;
+export type CloseHandler = () => Promise<void> | void;
+export interface WebSocketData {
+    path: string;
+}
+export interface WebSocketHandlers {
+    open?: (ws: ServerWebSocket<WebSocketData>) => void;
+    message?: (ws: ServerWebSocket<WebSocketData>, message: string | Buffer) => void;
+    close?: (ws: ServerWebSocket<WebSocketData>) => void;
+}
+export interface MiddlewareFileModule {
+    default: Middleware;
+    scope?: MiddlewareScope;
+}
+export interface PluginFileModule {
+    default: PluginFn;
+    options?: Record<string, unknown>;
+}
+export interface RouteFileModule {
+    default: Handler;
+    middlewares?: Middleware[];
+    schema?: RouteSchema;
+}
+export interface HookFileModule {
+    name: HookName;
+    handler: Hook;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { createApp, App } from './core/app';
+export { composeMiddlewares } from './core/middleware';
+export { autoloadPlugins, autoloadMiddlewares, autoloadHooks, autoloadRoutes } from './core/autoload';
+export { HttpError, badRequest, unauthorized, forbidden, notFound } from './lib/http-error';
+export { signToken, verifyToken } from './lib/jwt';
+export { validate } from './middlewares/validate.middleware';
+export { default as cors } from './middlewares/cors.middleware';
+export { default as logger } from './middlewares/logger.middleware';
+export { default as errorHandler } from './middlewares/error.middleware';
+export { createJwtAuth } from './middlewares/jwt-auth.middleware';
+export { default as requireAuth } from './middlewares/require-auth.middleware';
+export { rateLimit } from './middlewares/rate-limit.middleware';
+export { ejsPlugin } from './plugins/ejs.plugin';
+export { staticPlugin } from './plugins/static.plugin';
+export { prismaPlugin } from './plugins/prisma.plugin';
+export type * from './core/types';