From 5a3c5f8f821f923ee133263e5320d4c80ca7dff2 Mon Sep 17 00:00:00 2001 From: amerah-abdul Date: Wed, 18 Dec 2024 20:51:14 +0800 Subject: [PATCH 1/7] Add READ.md file --- docs/README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8d925f3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,29 @@ +# ᗊ Ingest Documentation + +Welcome to the Ingest documentation! Ingest is an unopinionated, +event-driven, pluggable, serverless framework designed for building +modern web applications. + +## Documentation Structure + +- [Getting Started](./getting-started.md) - Quick start guide and installation +- [Core Concepts](./core-concepts.md) - Understanding Ingest's fundamental concepts +- [Features](./features.md) - Detailed overview of framework features +- [API Reference](./api-reference.md) - Complete API documentation +- [Examples](./examples.md) - Code examples and use cases +- [Contributing](./contributing.md) - Guidelines for contributing to Ingest + +## Quick Links + +- [GitHub Repository](https://github.com/yourusername/ingest) +- [NPM Package](https://www.npmjs.com/package/@stackpress/ingest) +- [Issue Tracker](https://github.com/yourusername/ingest/issues) + +## Support + +If you need help or have questions, please: +1. Check the documentation +2. Look for existing issues +3. Create a new issue if needed + +Last updated: December 18, 2024 From c9ae6a38617f6beea0729751b13e63da7529f04e Mon Sep 17 00:00:00 2001 From: amerah-abdul Date: Wed, 18 Dec 2024 20:58:02 +0800 Subject: [PATCH 2/7] Add getting-started.md file --- docs/getting-started.md | 89 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/getting-started.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..2376d65 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,89 @@ +# Getting Started with Ingest + +## Installation + +You can install Ingest using npm: + +```bash +npm install @stackpress/ingest +``` + +Or using yarn: + +```bash +yarn add @stackpress/ingest +``` + +## Quick Start + +### Basic HTTP Server + +Create a simple HTTP server with Ingest: + +```javascript +// src/server.ts +import { server } from '@stackpress/ingest/http'; + +const app = server(); + +app.get('/', function HomePage(req, res) { + res.setHTML('Hello, World'); +}); + +app.create().listen(3000); +``` + +### File-Based Routing + +```javascript +import path from 'node:path'; +import { server } from '@stackpress/ingest/http'; + +const app = server(); +route.get('/', path.join(__dirname, 'home')); +app.create().listen(3000); +``` + +```javascript +// src/home.ts +export default function HomePage(req, res) { + res.setHTML('Hello, World'); +}; +``` + +## Project Setup + +1. Initialize your project: +```bash +mkdir my-ingest-app +cd my-ingest-app +yarn init -y +``` + +2. Install dependencies: +```bash +yarn add @stackpress/ingest +``` + +3. Create your first server file and start coding! + +## Development Mode + +To run your application in development mode: + +```bash +yarn dev +``` + +## Building for Production + +To build your application for production: + +```bash +yarn build +``` + +For more detailed information, check out: +- [Core Concepts](./core-concepts.md) +- [Features](./features.md) +- [Examples](./examples.md) From ba107f793f523e996cda26da772cb7e7b2c8e1ee Mon Sep 17 00:00:00 2001 From: amerah-abdul Date: Wed, 18 Dec 2024 21:00:01 +0800 Subject: [PATCH 3/7] Add core-concepts.md file --- docs/core-concepts.md | 50 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/core-concepts.md diff --git a/docs/core-concepts.md b/docs/core-concepts.md new file mode 100644 index 0000000..b914a96 --- /dev/null +++ b/docs/core-concepts.md @@ -0,0 +1,50 @@ +# Core Concepts + +Ingest is built on several fundamental concepts that make it powerful +and flexible. + +## Unopinionated Design + +Ingest doesn't force you into specific patterns or structures. +You're free to: +- Organize your code as you see fit +- Choose your preferred tools and libraries +- Implement your own architectural patterns + +## Event-Driven Architecture + +The framework is built around an event-driven model: +- Events are the primary mechanism for communication +- Handlers respond to specific events +- Asynchronous processing is first-class + +## Pluggable System + +Extend functionality through plugins: +- Add new features without modifying core code +- Share reusable components +- Create custom middleware + +## Serverless First + +Designed with serverless deployment in mind: +- Stateless by default +- Quick cold starts +- Efficient resource usage + +## File-Based Routing + +Organize your routes using the filesystem: +- Intuitive directory structure +- Automatic route generation +- Clean separation of concerns + +## Type Safety + +Built with TypeScript for better development experience: +- Full type definitions +- Compile-time checks +- Better IDE support + +For practical examples of these concepts, +see the [Examples](./examples.md) section. From af64434da37de3ab8528756a4727d9b0d43bcbfb Mon Sep 17 00:00:00 2001 From: amerah-abdul Date: Wed, 18 Dec 2024 21:01:05 +0800 Subject: [PATCH 4/7] Add api-reference.md file --- docs/api-reference.md | 91 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/api-reference.md diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..998ae94 --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,91 @@ +# API Reference + +## HTTP Server + +### Server Creation +```javascript +import { server } from '@stackpress/ingest/http'; +const app = server(); +``` + +### Route Handlers + +#### GET Routes +```javascript +app.get(path: string, handler: RouteHandler) +``` + +#### POST Routes +```javascript +app.post(path: string, handler: RouteHandler) +``` + +#### PUT Routes +```javascript +app.put(path: string, handler: RouteHandler) +``` + +#### DELETE Routes +```javascript +app.delete(path: string, handler: RouteHandler) +``` + +### Response Methods + +#### HTML Response +```javascript +res.setHTML(content: string) +``` + +#### JSON Response +```javascript +res.json(data: any) +``` + +#### Status Codes +```javascript +res.status(code: number) +``` + +### Request Object + +#### Properties +- `req.url`: URL of the request +- `req.method`: HTTP method +- `req.headers`: Request headers +- `req.query`: Query parameters +- `req.body`: Request body (for POST/PUT requests) + +### Middleware + +```javascript +app.use(middleware: MiddlewareFunction) +``` + +### Server Lifecycle + +```javascript +const server = app.create() +server.listen(port: number) +``` + +## Plugin System + +### Creating Plugins +```javascript +export default function myPlugin(options) { + return { + name: 'my-plugin', + setup(app) { + // Plugin setup code + } + } +} +``` + +### Using Plugins +```javascript +app.use(myPlugin(options)) +``` + +For practical examples of API usage, refer to the [Examples](./examples.md) section. From dba199d5d35be9bb3e029dbd5830c8fe787a6bff Mon Sep 17 00:00:00 2001 From: amerah-abdul Date: Wed, 18 Dec 2024 21:03:43 +0800 Subject: [PATCH 5/7] Add examples.md file --- docs/examples.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/examples.md diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..497536c --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,100 @@ +# Examples + +This document provides various examples of using Ingest in +different scenarios. + +## Basic HTTP Server + +```javascript +// Basic HTTP server example +import { server } from '@stackpress/ingest/http'; + +const app = server(); + +app.get('/', (req, res) => { + res.setHTML('

Welcome to Ingest!

'); +}); + +app.create().listen(3000); +``` + +## File-Based Routing + +```javascript +// src/server.ts +import path from 'node:path'; +import { server } from '@stackpress/ingest/http'; + +const app = server(); +app.get('/', path.join(__dirname, 'pages/home')); +app.get('/about', path.join(__dirname, 'pages/about')); +app.create().listen(3000); + +// src/pages/home.ts +export default function HomePage(req, res) { + res.setHTML('

Home Page

'); +} + +// src/pages/about.ts +export default function AboutPage(req, res) { + res.setHTML('

About Us

'); +} +``` + +## Using Plugins + +```javascript +// Custom logger plugin +function loggerPlugin() { + return { + name: 'logger', + setup(app) { + app.use((req, res, next) => { + console.log(`${req.method} ${req.url}`); + next(); + }); + } + } +} + +const app = server(); +app.use(loggerPlugin()); +``` + +## API Routes + +```javascript +// RESTful API example +app.get('/api/users', (req, res) => { + res.json([ + { id: 1, name: 'John' }, + { id: 2, name: 'Jane' } + ]); +}); + +app.post('/api/users', async (req, res) => { + const user = await req.json(); + // Handle user creation + res.json({ success: true, user }); +}); +``` + +## Running Examples + +You can run the example projects included in the repository: + +```bash +# Development mode +yarn :dev + +# Build mode +yarn :build +``` + +Available examples: +- `entries`: File-based routing +- `fetch`: API integration +- `http`: Basic HTTP server +- `plugins`: Plugin system + +Each example in the `/examples` directory includes its own README with specific instructions. From ab4ed9bf5eec2cbc8f21e2b1fe3db9b9728a0c7d Mon Sep 17 00:00:00 2001 From: amerah-abdul Date: Wed, 18 Dec 2024 21:04:56 +0800 Subject: [PATCH 6/7] Add features.md file --- docs/features.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/features.md diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..4c84833 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,63 @@ +# Features + +## HTTP Server +- Built-in HTTP server with routing capabilities +- Support for all standard HTTP methods +- Middleware support +- Static file serving +- Body parsing +- Cookie handling + +## File-Based Routing +- Automatic route generation from file structure +- Support for dynamic routes +- Index routes +- Nested routing +- Custom route parameters + +## Plugin System +- Extensible plugin architecture +- Middleware integration +- Custom handlers +- Configuration options +- Hot reload support + +## Development Tools +- Development mode with hot reloading +- Build optimization for production +- TypeScript support +- Error handling and debugging +- Performance monitoring + +## API Features +- JSON response handling +- Form data parsing +- File uploads +- WebSocket support +- CORS configuration +- Rate limiting +- Authentication helpers + +## Security +- HTTPS support +- CSRF protection +- XSS prevention +- Security headers +- Input validation +- Rate limiting + +## Performance +- Efficient routing +- Caching mechanisms +- Compression +- Load balancing +- Resource optimization + +## Additional Features +- Environment configuration +- Logging system +- Error handling +- Testing utilities +- Documentation generation + +For practical examples of these features, see the [Examples](./examples.md) section. From 16d0aad5f70fc0eaabe61213c032343e6fcf363d Mon Sep 17 00:00:00 2001 From: amerah-abdul Date: Wed, 18 Dec 2024 21:05:57 +0800 Subject: [PATCH 7/7] Add contributing.md file --- docs/contributing.md | 82 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..c7288e0 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,82 @@ +# Contributing to Ingest + +We love your input! We want to make contributing to Ingest as easy +and transparent as possible. + +## Development Process + +1. Fork the repo +2. Clone your fork +3. Create a new branch +4. Make your changes +5. Submit a pull request + +## Project Setup + +```bash +# Clone your fork +git clone https://github.com/YOUR_USERNAME/ingest.git + +# Install dependencies +yarn install + +# Run tests +yarn test +``` + +## Development Workflow + +1. Create a feature branch: +```bash +git checkout -b feature/amazing-feature +``` + +2. Make your changes + +3. Run tests: +```bash +yarn test +``` + +4. Commit your changes: +```bash +git commit -m "Add amazing feature" +``` + +5. Push to your fork: +```bash +git push origin feature/amazing-feature +``` + +6. Open a Pull Request + +## Pull Request Process + +1. Update documentation +2. Update tests +3. Ensure CI passes +4. Get code review +5. Merge after approval + +## Code Style + +- Use TypeScript +- Follow ESLint rules +- Write meaningful commit messages +- Document new features +- Add tests for new functionality + +## License + +By contributing, you agree that your contributions will be licensed +under the project's license. + +## Questions? + +Feel free to open an issue for: +- Bug reports +- Feature requests +- Documentation improvements +- General questions + +Thank you for contributing to Ingest!