@navios/core 0.3.0 → 0.5.0

package/README.md

@@ -4,7 +4,24 @@ Navios is a Type-Safe HTTP Server with Zod Validation.
 
 It is a powerful tool for building robust and type-safe APIs using TypeScript. It leverages the power of Zod for validation and provides a simple and intuitive API for defining endpoints, request and response schemas, and handling errors.
 
-It uses Fastify under the hood, which is a fast and low-overhead web framework for Node.js. This allows Navios to provide high performance and low latency for your APIs.
+Navios is adapter-based, allowing you to choose the underlying HTTP server implementation. Currently supported adapters include:
+
+- **Fastify** (via `@navios/adapter-fastify`) - A fast and low-overhead web framework for Node.js
+- **Bun** (via `@navios/adapter-bun`) - A fast JavaScript runtime optimized for server-side applications
+
+## Prerequisites
+
+To work as an HTTP server, you must install one of the supported adapters:
+
+```bash
+# For Fastify adapter
+npm install @navios/adapter-fastify
+
+# OR for Bun adapter
+npm install @navios/adapter-bun
+```
+
+The adapter must be provided when creating your Navios application to define the underlying HTTP server implementation.
 
 ## Features
 
@@ -15,6 +32,49 @@ It uses Fastify under the hood, which is a fast and low-overhead web framework f
 - **Customizable**: The package allows you to customize the behavior of the API client, such as using a custom client.
 - **Error Handling**: The package provides built-in error handling capabilities, allowing you to handle API errors gracefully and provide meaningful feedback to users.
 
+## Adapters
+
+Navios uses an adapter pattern to support different HTTP server implementations. Each adapter provides the necessary bindings to integrate with a specific runtime or framework.
+
+### Available Adapters
+
+#### Fastify Adapter (`@navios/adapter-fastify`)
+
+- Built on top of [Fastify](https://www.fastify.io/), a fast and low-overhead web framework
+- Excellent performance and a rich ecosystem of plugins
+- Full Node.js compatibility
+- Supports all Fastify features including hooks, plugins, and decorators
+
+```ts
+import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+
+const app = await NaviosFactory.create(AppModule, {
+  adapter: defineFastifyEnvironment(),
+})
+```
+
+#### Bun Adapter (`@navios/adapter-bun`)
+
+- Built for [Bun](https://bun.sh/), a fast JavaScript runtime optimized for performance
+- Native HTTP server implementation with excellent performance
+- Optimized for Bun's runtime features
+- Lightweight and efficient
+
+```ts
+import { defineBunEnvironment } from '@navios/adapter-bun'
+
+const app = await NaviosFactory.create(AppModule, {
+  adapter: defineBunEnvironment(),
+})
+```
+
+### Choosing an Adapter
+
+The choice of adapter depends on your deployment environment and performance requirements:
+
+- Use **Fastify adapter** if you need Node.js compatibility, access to the Fastify ecosystem, or are deploying to traditional Node.js environments
+- Use **Bun adapter** if you're running on Bun runtime and want to take advantage of its performance optimizations
+
 ## Main Concepts
 
 - **Module**: A module is a collection of controllers, and other modules. It is used to group related functionality together and provide a clear structure for your API. It also can define some shared guards and attributes.
@@ -33,7 +93,7 @@ Define your API in a shared location accessible to both the client and server. T
 ```ts
 import { builder } from '@navios/core'
 
-import { z } from 'zod'
+import { z } from 'zod/v4'
 
 const api = builder({
   useDiscriminatorResponse: true,
@@ -66,7 +126,13 @@ const login = api.declareEndpoint({
 ### Create your server
 
 ```bash
+# Install core dependencies
 yarn install --save @navios/core @navios/builder zod
+
+# Install one of the supported adapters
+yarn install --save @navios/adapter-fastify
+# OR
+yarn install --save @navios/adapter-bun
 ```
 
 Create AuthService:
@@ -130,12 +196,20 @@ export class AppModule {}
 Create your server:
 
 ```ts
+// Import your chosen adapter
+import { defineFastifyEnvironment } from '@navios/adapter-fastify'
 import { NaviosFactory } from '@navios/core'
 
+// OR import { defineBunEnvironment } from '@navios/adapter-bun'
+
 import { AppModule } from './src/app.module.mjs'
 
 export async function boot() {
-  const app = await NaviosFactory.create(AppModule)
+  const app = await NaviosFactory.create(AppModule, {
+    // Provide the adapter environment
+    adapter: defineFastifyEnvironment(),
+    // OR adapter: defineBunEnvironment(),
+  })
   app.setGlobalPrefix('/api')
   app.enableCors({
     methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
@@ -147,3 +221,22 @@ await boot()
 ```
 
 That's it! You have created your first Navios server. You can now run your server and test the `/api/login` endpoint.
+
+## Documentation
+
+- **[Quick Start Guide](./docs/quick-start.md)** - Get up and running quickly
+- **[Complete Documentation](./docs/README.md)** - Comprehensive framework documentation
+- **[Adapter Guide](./docs/adapters.md)** - Detailed adapter information and comparison
+- **[API Examples](https://github.com/Arilas/navios/tree/main/examples)** - Working code examples
+
+## Related Packages
+
+- **[@navios/adapter-fastify](https://www.npmjs.com/package/@navios/adapter-fastify)** - Fastify HTTP adapter
+- **[@navios/adapter-bun](https://www.npmjs.com/package/@navios/adapter-bun)** - Bun HTTP adapter
+- **[@navios/builder](https://www.npmjs.com/package/@navios/builder)** - Type-safe API definitions
+- **[@navios/di](https://www.npmjs.com/package/@navios/di)** - Dependency injection container
+- **[@navios/jwt](https://www.npmjs.com/package/@navios/jwt)** - JWT authentication utilities
+
+## License
+
+MIT

package/docs/README.md

@@ -1,6 +1,313 @@
-# Introduction
+# Navios Documentation
 
-Navios us a framework for building Type-Safe Node.js servers. It uses TypeScript and Navios builder to generate a server with a specific structure. The framework is designed to be easy to use and understand, while also being powerful and flexible.
+## Table of Contents
 
-Under the hood, Navios makes use of [Fastify](https://www.fastify.io/) for the server implementation, and [Zod](https://zod.dev/) for schema validation. This allows Navios to provide a type-safe experience while still being performant and easy to use.
+### Getting Started
 
+- [Quick Start Guide](./quick-start.md) - Get up and running quickly
+- [Application Setup and Configuration](./application-setup.md) - Comprehensive setup guide
+
+### Core Concepts
+
+- [Modules](./modules.md) - Application organization and structure
+- [Controllers](./controllers.md) - Request handlers and routing
+- [Endpoints](./endpoints.md) - HTTP route definitions and configuration
+- [Services and Dependency Injection](./services.md) - Business logic and DI system
+- [Guards](./guards.md) - Authentication, authorization, and request filtering
+- [Exception Handling](./exceptions.md) - Error handling and HTTP exceptions
+- [Attribute System](./attributes.md) - Metadata and custom decorators
+
+### Infrastructure
+
+- [HTTP Server Adapters](./adapters.md) - Fastify, Bun, and custom adapters
+
+### Advanced Topics
+
+- [Testing Guide](./testing.md) - Unit, integration, and E2E testing strategies
+- Performance Optimization
+- Deployment Patterns
+- Plugin Development
+
+---
+
+## Introduction
+
+Navios is a framework for building Type-Safe HTTP servers with TypeScript. It uses TypeScript and Navios builder to create servers with a well-defined structure, emphasizing type safety, validation, and developer experience.
+
+The framework is adapter-based, allowing you to choose the underlying HTTP server implementation that best fits your deployment environment and performance requirements.
+
+> **Important**: Always use `@navios/builder` to define your API endpoints instead of passing configuration objects directly to decorators. This ensures better type safety, maintainability, and access to advanced features like client generation.
+
+## Architecture Overview
+
+Navios follows a modular architecture with the following key components:
+
+- **Core Framework** (`@navios/core`) - Provides the main framework features
+- **Adapters** - HTTP server implementations (Fastify, Bun)
+- **Builder** (`@navios/builder`) - Type-safe API definition and client generation
+- **Dependency Injection** (`@navios/di`) - Powerful DI container
+- **Additional Packages** - JWT, scheduling, React Query integration, and more
+
+## HTTP Server Adapters
+
+Navios requires an HTTP adapter to function as a server. The adapter pattern allows Navios to support different runtimes and frameworks while maintaining a consistent API.
+
+### Prerequisites
+
+**Important**: To use Navios as an HTTP server, you **must** install one of the supported adapters:
+
+```bash
+# For Fastify adapter (Node.js)
+npm install @navios/adapter-fastify
+
+# OR for Bun adapter (Bun runtime)
+npm install @navios/adapter-bun
+```
+
+### Fastify Adapter
+
+The Fastify adapter (`@navios/adapter-fastify`) integrates Navios with the [Fastify](https://www.fastify.io/) web framework.
+
+#### Features:
+
+- High performance HTTP server
+- Rich ecosystem of plugins
+- Full Node.js compatibility
+- Built-in request/response validation
+- Comprehensive middleware support
+- Production-ready with extensive documentation
+
+#### Usage:
+
+```ts
+import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+import { NaviosFactory } from '@navios/core'
+
+import { AppModule } from './app.module.js'
+
+async function bootstrap() {
+  const app = await NaviosFactory.create(AppModule, {
+    adapter: defineFastifyEnvironment(),
+  })
+
+  // Configure CORS
+  app.enableCors({
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+  })
+
+  // Enable multipart support for file uploads
+  app.enableMultipart({})
+
+  await app.init()
+  await app.listen({ port: 3000, host: '0.0.0.0' })
+}
+
+bootstrap()
+```
+
+#### Dependencies:
+
+The Fastify adapter requires `fastify` as a peer dependency:
+
+```json
+{
+  "dependencies": {
+    "@navios/core": "^0.5.0",
+    "@navios/adapter-fastify": "^0.5.0",
+    "fastify": "^5.6.0"
+  }
+}
+```
+
+### Bun Adapter
+
+The Bun adapter (`@navios/adapter-bun`) integrates Navios with [Bun's](https://bun.sh/) native HTTP server.
+
+#### Features:
+
+- Optimized for Bun runtime performance
+- Native HTTP server implementation
+- Lightweight with minimal overhead
+- Fast startup times
+- Efficient memory usage
+
+#### Usage:
+
+```ts
+import { defineBunEnvironment } from '@navios/adapter-bun'
+import { NaviosFactory } from '@navios/core'
+
+import { AppModule } from './app.module.js'
+
+async function bootstrap() {
+  const app = await NaviosFactory.create(AppModule, {
+    adapter: defineBunEnvironment(),
+  })
+
+  // Configure CORS
+  app.enableCors({
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+  })
+
+  // Enable multipart support
+  app.enableMultipart({})
+
+  await app.init()
+  await app.listen({ port: 3000, host: '0.0.0.0' })
+}
+
+bootstrap()
+```
+
+#### Dependencies:
+
+The Bun adapter works with Bun runtime and requires no additional HTTP server dependencies:
+
+```json
+{
+  "dependencies": {
+    "@navios/core": "^0.5.0",
+    "@navios/adapter-bun": "^0.5.0"
+  }
+}
+```
+
+## Adapter Selection Guide
+
+Choose the appropriate adapter based on your deployment environment and requirements:
+
+| Adapter | Runtime | Performance | Ecosystem | Use Case                                      |
+| ------- | ------- | ----------- | --------- | --------------------------------------------- |
+| Fastify | Node.js | High        | Rich      | Production Node.js apps, need Fastify plugins |
+| Bun     | Bun     | Very High   | Growing   | Performance-critical apps, Bun runtime        |
+
+### When to use Fastify Adapter:
+
+- Deploying to Node.js environments
+- Need access to Fastify's extensive plugin ecosystem
+- Require compatibility with existing Node.js tooling
+- Working with teams familiar with Express/Fastify patterns
+- Need mature production support and documentation
+
+### When to use Bun Adapter:
+
+- Running on Bun runtime
+- Performance is critical
+- Want faster startup times
+- Prefer minimal dependencies
+- Building new applications without legacy constraints
+
+## Error Handling
+
+Both adapters provide consistent error handling through Navios's exception system:
+
+```ts
+import { BadRequestException, NotFoundException } from '@navios/core'
+
+@Controller()
+export class UserController {
+  @Endpoint(getUserEndpoint)
+  async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+    const { id } = request
+
+    if (!id) {
+      throw new BadRequestException('User ID is required')
+    }
+
+    const user = await this.userService.findById(id)
+    if (!user) {
+      throw new NotFoundException('User not found')
+    }
+
+    return user
+  }
+}
+```
+
+## Configuration
+
+Both adapters support the same Navios configuration options:
+
+```ts
+const app = await NaviosFactory.create(AppModule, {
+  adapter: defineFastifyEnvironment(), // or defineBunEnvironment()
+  logger: ['error', 'warn', 'log'], // Optional: configure logging levels
+})
+
+// Global configuration
+app.setGlobalPrefix('/api/v1')
+app.enableCors({
+  origin: ['http://localhost:3000'],
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  credentials: true,
+})
+
+// Enable file uploads
+app.enableMultipart({
+  limits: {
+    fileSize: 1024 * 1024 * 10, // 10MB
+  },
+})
+```
+
+## Advanced Usage
+
+### Custom Adapter Configuration
+
+You can pass configuration options to the underlying server:
+
+```ts
+// Fastify-specific configuration
+const app = await NaviosFactory.create(AppModule, {
+  adapter: defineFastifyEnvironment({
+    // Fastify instance options can be configured here if needed
+  }),
+})
+
+// Bun-specific configuration
+const app = await NaviosFactory.create(AppModule, {
+  adapter: defineBunEnvironment({
+    // Bun server options can be configured here if needed
+  }),
+})
+```
+
+### Multiple Adapters
+
+You can also configure multiple adapters if needed (advanced use case):
+
+```ts
+const app = await NaviosFactory.create(AppModule, {
+  adapter: [
+    defineFastifyEnvironment(),
+    // Additional adapters...
+  ],
+})
+```
+
+## Migration Between Adapters
+
+Switching between adapters is straightforward and requires minimal code changes:
+
+1. Install the new adapter package
+2. Update the import statement
+3. Change the adapter function call
+4. Update any adapter-specific configurations
+
+```ts
+// From Fastify
+
+// To Bun
+import { defineBunEnvironment } from '@navios/adapter-bun'
+import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+
+const app = await NaviosFactory.create(AppModule, {
+  adapter: defineFastifyEnvironment(),
+})
+
+const app = await NaviosFactory.create(AppModule, {
+  adapter: defineBunEnvironment(),
+})
+```
+
+Your controllers, services, and application logic remain unchanged.