Sucker Framework

A modern, high-performance web framework built with TypeScript and Node.js native HTTP module.

✨ Features

• 🚀 High Performance - Built on Node.js native HTTP module with zero framework dependencies
• 🔒 Type Safe - Full TypeScript support with complete type definitions
• 🧅 Onion Model - Async middleware with onion-style execution order
• 🛣️ Smart Routing - Parameter routes, wildcard routes, and nested routing
• 🔐 Built-in Security - CORS, Rate Limiting, XSS protection and more
• 📊 Performance Monitoring - Built-in request logging and metrics collection
• 🐳 Container Ready - Docker deployment and graceful shutdown support

🚀 Quick Start

Installation

npm install @jackie733/sucker-framework

Basic Usage

import { Application } from '@jackie733/sucker-framework';
import {
  cors,
  logger,
  bodyParser
} from '@jackie733/sucker-framework/middleware';

const app = new Application({
  port: 3000,
  host: '0.0.0.0'
});

// Add middleware
app.use(logger({ format: 'combined' }));
app.use(cors({ origin: '*' }));
app.use(bodyParser());

// Define routes
app.get('/api/hello', async ctx => {
  ctx.json({ message: 'Hello World!' });
});

app.get('/api/users/:id', async ctx => {
  const { id } = ctx.params;
  ctx.json({ id, name: `User ${id}` });
});

// Start server
app.listen();

�️ API Reference

Application

import { Application, ApplicationConfig } from '@jackie733/sucker-framework';

const app = new Application(config?: ApplicationConfig);

Configuration Options:

interface ApplicationConfig {
  port?: number; // Default: 3000
  host?: string; // Default: '0.0.0.0'
  maxRequestSize?: number; // Default: 10MB
  timeout?: number; // Default: 30000ms
}

Context API

The context object provides access to request and response:

app.get('/example', async ctx => {
  // Request properties
  ctx.method; // HTTP method
  ctx.url; // Full URL
  ctx.path; // URL pathname
  ctx.query; // Query parameters object
  ctx.headers; // Request headers
  ctx.params; // Route parameters
  ctx.body; // Request body (with bodyParser middleware)

  // Response methods
  ctx.status = 200;
  ctx.setHeader('X-Custom', 'value');
  ctx.json({ data: 'value' });
  ctx.text('Hello World');
  ctx.html('<h1>Hello</h1>');
  ctx.redirect('/other-page');
});

Routing

// HTTP methods
app.get('/path', handler);
app.post('/path', handler);
app.put('/path', handler);
app.delete('/path', handler);
app.patch('/path', handler);

// Route parameters
app.get('/users/:id', async ctx => {
  const userId = ctx.params.id;
});

// Multiple parameters
app.get('/users/:userId/posts/:postId', async ctx => {
  const { userId, postId } = ctx.params;
});

// Query parameters
app.get('/search', async ctx => {
  const { q, page = 1 } = ctx.query;
});

🔧 Built-in Middleware

Import middleware from the middleware submodule:

import {
  cors,
  logger,
  bodyParser,
  rateLimit,
  errorHandler,
  staticFiles
} from '@jackie733/sucker-framework/middleware';

CORS

app.use(
  cors({
    origin: ['http://localhost:3000', 'https://yourdomain.com'],
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    credentials: true,
    maxAge: 86400 // Cache preflight for 24 hours
  })
);

Request Logger

app.use(
  logger({
    format: 'combined' // 'combined' | 'common' | 'short' | 'tiny'
  })
);

Body Parser

app.use(
  bodyParser({
    limit: '10mb',
    enableTypes: ['json', 'form', 'text']
  })
);

Rate Limiting

app.use(
  rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // Limit each IP to 100 requests per windowMs
    message: 'Too many requests'
  })
);

Static Files

app.use(
  staticFiles({
    root: './public',
    prefix: '/static'
  })
);

Error Handler

app.use(
  errorHandler({
    expose: process.env.NODE_ENV === 'development',
    format: 'json' // 'json' | 'html' | 'text'
  })
);

Custom Middleware

app.use(async (ctx, next) => {
  const start = Date.now();

  try {
    await next();
  } catch (error) {
    ctx.status = 500;
    ctx.json({ error: 'Internal Server Error' });
  }

  const duration = Date.now() - start;
  console.log(`${ctx.method} ${ctx.path} - ${duration}ms`);
});

📊 Performance Features

• Zero-copy Stream Processing - Efficient handling of large file uploads/downloads
• Connection Pool Optimization - HTTP Keep-Alive connection reuse
• Memory Management - Automatic garbage collection and memory leak protection
• Concurrency Control - Smart request concurrency limiting

🔒 Security Features

• CORS Protection - Configurable Cross-Origin Resource Sharing
• Rate Limiting - Request frequency limiting to prevent DDoS
• XSS Protection - Automatic output content escaping
• Request Size Limiting - Protection against large request attacks
• Security Headers - Automatic security-related HTTP headers

🏗️ TypeScript Support

The framework is built with TypeScript and provides full type definitions:

import type {
  Context,
  Middleware,
  RouteHandler,
  ApplicationConfig
} from '@jackie733/sucker-framework';

const middleware: Middleware = async (ctx, next) => {
  // ctx is fully typed
  await next();
};

const handler: RouteHandler = async ctx => {
  // Full intellisense support
  ctx.json({ message: 'Typed response' });
};

🧪 Testing

# Install dev dependencies for testing
npm install --save-dev jest @types/jest supertest

# Example test
import { Application } from '@jackie733/sucker-framework';
import request from 'supertest';

describe('API Tests', () => {
  const app = new Application();

  app.get('/test', async ctx => {
    ctx.json({ success: true });
  });

  test('should return success', async () => {
    const response = await request(app.callback())
      .get('/test')
      .expect(200);

    expect(response.body.success).toBe(true);
  });
});

🚢 Deployment

Docker

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --production

COPY . .
EXPOSE 3000

CMD ["node", "index.js"]

PM2

{
  "name": "my-app",
  "script": "index.js",
  "instances": "max",
  "exec_mode": "cluster",
  "env": {
    "NODE_ENV": "production",
    "PORT": 3000
  }
}

📚 Examples

Check out the examples directory for complete sample applications.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

MIT License - see the LICENSE file for details.

🔗 Links

• GitHub Repository
• npm Package
• Documentation
• Issue Tracker