ᗊ Ingest


An unopinionated, event driven, pluggable, server/less framework.

Overview

Ingest is a lightweight, flexible server framework that brings the familiar Express.js-like API to serverless environments. Built on top of the powerful @stackpress/lib event system, Ingest provides a unified approach to building applications that can run anywhere - from traditional Node.js servers to serverless platforms like AWS Lambda, Vercel, and Netlify.

Key Features

- 🚀 Serverless-First: Designed specifically for serverless environments while maintaining compatibility with traditional servers
- 🔄 Event-Driven: Built on a robust event system that enables reactive programming patterns
- 🛣️ Multi-Routing Interface: Four different routing approaches in one framework
- 🔌 Plugin System: Highly extensible with a simple plugin architecture
- 📦 Build Support: Exposes routing information for bundlers and build tools
- 🌐 Cross-Platform: Works with Node.js HTTP, WHATWG Fetch, and various serverless platforms

Installation

``bash
npm install @stackpress/ingest


or


yarn add @stackpress/ingest
`

Quick Start

$3

`typescript
import { server } from '@stackpress/ingest/http';

const app = server();

// Traditional Express-like routing
app.get('/', (req, res) => {
res.setHTML('

Hello World!

');
});

app.get('/api/users/:id', (req, res) => {
const userId = req.data.get('id');
res.setJSON({ id: userId, name: 'John Doe' });
});

// Start the server
app.create().listen(3000, () => {
console.log('Server running on port 3000');
});
`

$3

`typescript
import { server } from '@stackpress/ingest/whatwg';

const app = server();

app.get('/api/hello', (req, res) => {
res.setJSON({ message: 'Hello from Vercel!' });
});

export default async function handler(request: Request) {
return await app.handle(request, new Response());
}
`

Multi-Routing Interface

Ingest provides four different ways to define routes, giving you flexibility in how you organize your application:

$3

Express.js-like inline route handlers:

`typescript
app.action.get('/users', (req, res) => {
res.setJSON({ users: [] });
});
`

$3

Route to files that export default handlers:

`typescript
app.entry.get('/users', './routes/users.js');
`

$3

Dynamic imports for code splitting:

`typescript
app.import.get('/users', () => import('./routes/users.js'));
`

$3

Direct template rendering:

`typescript
app.view.get('/users', './views/users.hbs');
`

$3

Ingest can automatically determine which router to use based on your input:

`typescript
// Automatically uses action router
app.get('/users', (req, res) => { / handler / });

// Automatically uses import router
app.get('/users', () => import('./routes/users.js'));

// Automatically uses view router
app.get('/users', './views/users.hbs');
`

Plugin System

Ingest features a powerful plugin system that allows you to modularize your application:

$3

`typescript
// src/plugins/auth.ts
export default function authPlugin(server) {
server.on('request', (req, res) => {
// Add authentication logic
if (!req.headers.get('authorization')) {
res.setError('Unauthorized', {}, [], 401);
return false; // Stop processing
}
});
}
`

$3

Add plugins to your package.json:

`json
{
"plugins": [
"./src/plugins/auth",
"./src/plugins/logging",
"@my-org/ingest-plugin"
]
}
`

$3

`typescript
import { server } from '@stackpress/ingest/http';

const app = server();

// Load all plugins
await app.bootstrap();

app.create().listen(3000);
`

Event-Driven Architecture

Ingest is built on a powerful event system that allows for reactive programming:

`typescript
// Listen to all requests
app.on('request', (req, res) => {
console.log(${req.method} ${req.url.pathname});
});

// Listen to specific routes
app.on('GET /api/users', (req, res) => {
// This runs for GET /api/users
});

// Priority-based listeners
app.on('request', middleware1, 10); // Higher priority
app.on('request', middleware2, 5); // Lower priority
`

Deployment Examples

$3

`typescript
import { server } from '@stackpress/ingest/whatwg';

const app = server();
app.get('/api/hello', (req, res) => {
res.setJSON({ message: 'Hello from Lambda!' });
});

export const handler = async (event, context) => {
const request = new Request(event.requestContext.http.sourceIp);
const response = new Response();
return await app.handle(request, response);
};
`

$3

`typescript
import { server } from '@stackpress/ingest/whatwg';

const app = server();
app.get('/api/users', (req, res) => {
res.setJSON({ users: [] });
});

export default async function handler(req: Request) {
return await app.handle(req, new Response());
}
`

$3

`typescript
import { server } from '@stackpress/ingest/whatwg';

const app = server();
app.get('/.netlify/functions/api', (req, res) => {
res.setJSON({ message: 'Hello from Netlify!' });
});

export const handler = async (event, context) => {
const request = new Request(event.rawUrl);
const response = new Response();
return await app.handle(request, response);
};
`

Build Support

Ingest exposes routing information that can be used by bundlers and build tools:

`typescript
const app = server();
app.get('/users', () => import('./routes/users.js'));
app.get('/posts', () => import('./routes/posts.js'));

// Access routing information
console.log(app.routes); // Route definitions
console.log(app.imports); // Dynamic imports
console.log(app.entries); // File entries
console.log(app.views); // View templates
`

This information can be used by bundlers to:
- Pre-bundle route modules
- Generate static route manifests
- Optimize code splitting
- Create deployment artifacts

Documentation

- API Reference - Complete API documentation
- Examples - Comprehensive usage examples
- Plugin Development - Guide to creating plugins

Examples

Check out the examples/ directory for complete working examples:

- with-http - Basic HTTP server
- with-vercel - Vercel deployment
- with-lambda - AWS Lambda deployment
- with-netlify - Netlify deployment
- with-plugins - Plugin system usage
- with-handlebars` - Template engine integration