Arc: Minimalist Multi-Core Web Framework for Node.js

Arc is a lightweight low level web framework built from scratch using TypeScript and Node.js native modules. It is created for developers who require absolute control over the request lifecycle without the overhead of heavy external dependencies. By focusing on a strictly typed architecture and native performance, Arc provides a robust foundation for building scalable microservices and enterprise applications.

Table of Contents

• Installation
• Key Architectural Features
• Rapid Deployment Example
• Core Philosophy
• Core Engine Components
• Advanced Middleware Pipeline
• Distributed Systems and Clustering
• Project Roadmap
• Contributing
• Security Policy
• Running Tests
• Current Project Team Members
• License

Installation

Arc requires Node.js version 20.6.0 or higher to utilize native environment variable loading and enhanced ESM support.

1. Install the package via NPM:

   npm install @phantekzy/arc

2. Ensure your project is configured for ECMAScript Modules (ESM) by adding the following to your package.json:

   "type": "module"

Key Architectural Features

• Vertical Scalability: Built in support for Node.js clustering to utilize every CPU core on the host machine.
• Strictly Typed Pipeline: Full TypeScript support for request, response, and middleware objects.
• Zero Dependency Core: Engineered using native Node.js modules to minimize the attack surface and supply chain risks.
• Integrated Security: Native support for JWT authentication, CORS, and rate limiting out of the box.
• Native Environment Management: Zero reliance on third-party env loaders. Uses Node.js native --env-file integration for better performance and security.

Rapid Deployment Example

The following example demonstrates how to initialize the framework and define a protected, validated route.

import { Arc } from "@phantekzy/arc";
import { jwtAuth } from "@phantekzy/arc/middlewares/jwtAuth";
import { validate } from "@phantekzy/arc/middlewares/validator";

const app = new Arc();

// The Engine automatically picks up PORT from your environment
const port = process.env.PORT || 3000;

// Data Validation Schema
const userSchema = { name: "string", age: "number" };

// Protected and Validated Route
// Logic: Auth Check -> Schema Validation -> Final Handler
app.post("/api/user", jwtAuth, validate(userSchema, "body"), (req, res) => {
  res.json({ 
    success: true, 
    message: "Arc Engine: Data validated and user authenticated",
    data: req.body
  });
});

app.listen(port, () => {
  console.log(`Arc framework operational on port ${port}`);
});

Running the Application (Modern Node.js) :

Unlike legacy frameworks that rely on the dotenv package to patch variables at runtime, Arc utilizes Node.js native environment injection. This ensures a smaller attack surface and faster boot times.

1. Create your .env file:

PORT=3000
JWT_SECRET=your_secret_key

2. Start the Engine:

# Development
node --env-file=.env server.js

# Production (Standard)
node --env-file=.env dist/server.js

Core Philosophy

The development of Arc is guided by three fundamental principles:

1. Developer Autonomy: Zero hidden magic or forced dependencies.
2. Vertical Performance: Native multi core utilization by default.
3. Type Integrity: First class TypeScript support across the entire request lifecycle.

Core Engine Components

Arc abstracts raw HTTP streams into manageable typed objects while maintaining high performance data access.

Request Context (req)

• req.params: Access dynamic URL segments (e.g., /user/:id).
• req.query: Parse URL search parameters.
• req.body: Access parsed JSON or URL encoded payloads.
• req.cookies: Retrieve client side state and session identifiers.

Response Orchestration (res)

• res.status(code): Set explicit HTTP response codes.
• res.json(data): Send structured JSON responses with automatic headers.
• res.send(content): Dispatch raw text, buffers, or HTML.

Advanced Middleware Pipeline

The framework utilizes a linear execution pipeline allowing developers to chain logic as checkpoints before reaching the final handler.

1. Authentication: Integrated JWT verification to protect sensitive endpoints.
2. Input Validation: A schema based validator that scrubs both request bodies and URL parameters.
3. Rate Limiting: Protects the system against brute force attacks and request flooding.
4. CORS: Configurable headers to manage cross origin resource sharing safely.

Distributed Systems and Clustering

Arc is designed for high availability environments. By utilizing the built in clustering module, the framework can fork multiple worker processes to balance incoming traffic.

• Primary Process: Orchestrates the lifecycle of the application and monitors worker health.
• Worker Processes: Independent instances of the server running on separate CPU cores to maximize throughput.
• Self Healing: The system automatically detects worker failure and spawns replacement processes to ensure zero downtime.

Project Roadmap

The Arc framework is in active development. Future releases will focus on:

• Benchmarking Suites: Comparative performance analysis against Express and Fastify.
• Automated Testing: Implementation of a comprehensive unit and integration testing suite.
• Enhanced Telemetry: Internal metrics for monitoring performance in real time.

Contributing

The Arc project welcomes all contributors. Whether you are fixing a bug or suggesting a new feature, please feel free to fork the repository and submit a pull request.

Security Policy

To report a security vulnerability, please do not open a public issue. Instead, please open a private security advisory on GitHub or contact the maintainer directly.

Running Tests

To run the internal test suite, ensure you have the devDependencies installed and run: npm test

Current Project Team Members

• Maini Lotfi Abdelkader (@phantekzy) — Lead Architect & Maintainer

License

The Arc framework is licensed under the MIT License.

GitHub: github.com/phantekzy/Arc | NPM: @phantekzy/arc