npm package: @lifjs/core
Description: A blazingly fast web framework for Bun
Author: 1jmdev
Latest version: 0.1.2

# LifJS ⚡

A blazingly fast, type-safe web framework for [Bun](https://bun.sh). LifJS is built for Bun's native APIs, providing a modern developer experience without the bloat.

## Key Features

- 🚀 **Extreme Performance** - Optimized radix tree routing and fast path extraction (no `new URL()` overhead).
- 🎯 **Deep Type Safety** - First-class TypeScript support with automatic param inference.
- 🔌 **Middleware & Plugins** - Robust middleware composition and a flexible plugin system.
- 📦 **Zero Dependencies** - Purely uses Bun's native APIs for a minimal footprint.
- 🛠️ **Modern DX** - Fluent context helpers, built-in CORS, logging, and rate limiting.

## Quick Start

```typescript
import { lifjs } from '@lifjs/core';

const app = lifjs();

// Simple text response
app.get('/', (ctx) => ctx.text('Hello LifJS!'));

// JSON response with route params
app.get('/users/:id', (ctx) => {
  const { id } = ctx.params;
  return ctx.json({ id, status: 'active' });
});

// Start the server (Bun native pattern)
export default {
  port: 3000,
  fetch: app.fetch
};
```

## Installation

```bash
bun add @lifjs/core
```

## Core Concepts

### Application Setup

You can customize the base path and global error/not-found handlers.

```typescript
import { lifjs } from '@lifjs/core';

const app = lifjs({
  basePath: '/api/v1',
  onNotFound: (ctx) => ctx.status(404).json({ error: 'Custom Not Found' }),
  onError: (err, ctx) => ctx.status(500).json({ msg: err.message })
});
```

### Routing

Supports standard methods (`get`, `post`, `put`, `delete`, `patch`, `all`).

```typescript
// Named parameters
app.get('/posts/:slug', (ctx) => {
  return ctx.text(`Reading ${ctx.params.slug}`);
});

// Wildcards (stored in ctx.params['*'])
app.get('/files/*', (ctx) => {
  return ctx.json({ path: ctx.params['*'] });
});
```

### Sub-Routers

Organize your routes using `createRouter` and mounting them with `app.route()`.

```typescript
import { createRouter } from '@lifjs/core';

const auth = createRouter();
auth.post('/login', (ctx) => /* ... */);
auth.post('/signup', (ctx) => /* ... */);

app.route('/auth', auth);
```

### Middleware

LifJS includes high-performance built-in middleware.

```typescript
import { logger, cors, rateLimit, timeout } from '@lifjs/core';

app.use(logger());
app.use(cors({ origin: 'https://example.com' }));
app.use(rateLimit({ max: 100, window: 60000 }));

// Custom middleware
app.use(async (ctx, next) => {
  ctx.state.user = 'guest'; // State sharing
  const res = await next();
  // Modify response
  return res;
});
```

### Context Helpers

The `ctx` object simplifies common tasks:

- **Metadata:** `ctx.path`, `ctx.method`, `ctx.headers`, `ctx.query`, `ctx.params`.
- **Response:** `ctx.json()`, `ctx.text()`, `ctx.html()`, `ctx.redirect()`, `ctx.status(418).send()`.
- **Body:** `await ctx.body()` (auto-parses JSON/Form), `ctx.formData()`, `ctx.blob()`.

## Project Structure

```text
lifjs/
├── packages/
│   └── core/           # Main framework source
├── examples/
│   ├── basic-api/      # Simple API usage
│   ├── blog-api/       # Models and routing
│   └── todo-api/       # CRUD with services
├── LICENSE             # MIT License
└── package.json        # Workspace configuration
```

## Development

```bash
# Install dependencies
bun install

# Run tests
bun run test

# Build all packages
bun run build
```

## License

[MIT](LICENSE) © 2026 LifJS Contributors