Nexus Express TypeScript

🚀 A powerful, extensible Node.js/TypeScript framework built for scalability, with advanced features and ready for enterprise integrations.

📋 Table of Contents

• Core Features
• Installation
• Documentation
• Architecture
• Integration Patterns
• Roadmap
• Contributing
• License

🌟 Core Features

1. Advanced Authorization with CASL

• Fine-grained permission control using CASL
• Role-based access control (RBAC) integration
• Dynamic ability checks for all CRUD operations
• Declarative permission definitions

2. Dynamic CRUD Operations

Introducing a powerful baseHandler that provides:

// Example usage
import baseHandler from '../utils/baseHandler';

router.post('/', baseHandler.createOne(YourModel, {
  auth: true,
  ability: true,
  discriminator: {
    field: 'type',
    models: { /* your model mapping */ }
  }
}));

Supported Operations:

• createOne: Single document creation
• createMany: Bulk document creation
• getAll: Smart paginated listing
• getOne: Single document retrieval
• updateOne: Document updates
• deleteOne: Single document deletion
• deleteMany: Bulk deletion
• getSelf: Current user document

3. Smart Data Handling

• Automatic Population:

  // Automatically detects and populates references
  const data = await Model.findById(id).populate(autoDetectedFields);

• Dynamic Search:

  // Example search query
  GET /api/v1/resources?search={"keyword":"search","fields":["name","description"]}

• Complex Filtering:

  // Support for complex query parameters
  GET /api/v1/resources?query={"status":"active"}&options={"sort":"createdAt"}

4. Enterprise-Ready Features

• Type discrimination for flexible data modeling
• Automatic audit trails (createdBy/updatedBy)
• Extensible authentication system
• Ready for multiple integration patterns

🛠️ Installation

1. Clone the repository:

   git clone https://github.com/miirshe/nexus-express-typescript.git
   cd nexus-express-typescript

2. Install dependencies:

   npm install
   # or
   yarn install

3. Set up environment variables:

   cp .env.example .env

4. Start development server:

   npm run dev
   # or
   yarn dev

📚 Documentation

Base Handler Options

interface HandlerOptions {
    auth?: boolean;          // Enable/disable authentication
    ability?: boolean;       // Enable/disable authorization
    discriminator?: {
        field: string;       // Field for type discrimination
        models: { [key: string]: Model<any> }; // Model mapping
    };
}

API Examples

1. Create with Type Discrimination:

POST /api/v1/resources
{
    "type": "custom",
    "name": "Example Resource",
    "metadata": { /* custom fields */ }
}

2. Smart Search:

GET /api/v1/resources?search={"keyword":"example","fields":["name","metadata"]}

3. Complex Queries:

GET /api/v1/resources?query={"status":"active"}&options={"sort":"-createdAt","populate":"relations"}

🔒 Security Features

• Authentication checks in every handler
• CASL-based authorization
• Type-safe implementations
• Request validation
• Error handling with proper status codes

🔄 Integration Ready

• Authentication providers
• Notification systems
• External APIs
• Message queues
• Caching layers
• Monitoring systems

🏗 Architecture

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Nexus Express TypeScript                 │
├─────────────┬─────────────┬────────────────┬───────────────┤
│   API Layer │  Services   │  Data Layer    │  Integrations │
├─────────────┼─────────────┼────────────────┼───────────────┤
│ • REST API  │ • Business  │ • MongoDB      │ • Auth        │
│ • GraphQL   │   Logic     │ • Redis Cache  │   Providers   │
│ • WebSocket │ • Validation│ • Elasticsearch│ • Payment     │
│ • gRPC      │ • CASL Auth │ • Queue System │   Gateways    │
└─────────────┴─────────────┴────────────────┴───────────────┘

Key Components

1. API Layer

   • REST endpoints with OpenAPI/Swagger
   • Optional GraphQL support
   • Real-time WebSocket capabilities
   • gRPC for microservices

2. Service Layer

   • Business logic isolation
   • CASL-based authorization
   • Service-to-service communication
   • Event handling

3. Data Layer

   • MongoDB with Mongoose
   • Redis for caching
   • Elasticsearch for search
   • Message queues

4. Integration Layer

   • Authentication providers
   • Payment systems
   • External APIs
   • Monitoring systems

🔌 Integration Patterns

1. Authentication Providers

// Support for multiple auth strategies
interface AuthProvider {
  initialize(): Promise<void>;
  authenticate(credentials: any): Promise<User>;
  verify(token: string): Promise<boolean>;
}

// Implementation examples:
class JWTAuthProvider implements AuthProvider { ... }
class OAuth2Provider implements AuthProvider { ... }
class SAMLProvider implements AuthProvider { ... }

2. Notification System

// Unified notification interface
interface NotificationChannel {
  send(message: NotificationMessage): Promise<void>;
}

// Multiple channel support
class EmailNotification implements NotificationChannel { ... }
class SMSNotification implements NotificationChannel { ... }
class PushNotification implements NotificationChannel { ... }

3. Payment Integration

// Generic payment interface
interface PaymentGateway {
  processPayment(payment: Payment): Promise<Transaction>;
  refund(transaction: Transaction): Promise<Refund>;
}

// Multiple provider support
class StripeGateway implements PaymentGateway { ... }
class PayPalGateway implements PaymentGateway { ... }

4. Caching Strategy

// Flexible caching interface
interface CacheProvider {
  get<T>(key: string): Promise<T>;
  set<T>(key: string, value: T, ttl?: number): Promise<void>;
}

// Implementation examples:
class RedisCache implements CacheProvider { ... }
class MemcachedCache implements CacheProvider { ... }

🎯 Roadmap

Phase 1: Core Enhancement (Current)

• CASL Integration
• Dynamic CRUD Operations
• Type Discrimination
• Smart Data Handling

Phase 2: Authentication & Security (Next)

• Multi-factor Authentication
• OAuth2 Provider Integration
• SAML Support
• Rate Limiting
• API Key Management

Phase 3: Performance & Scaling

• Redis Caching Layer
• Elasticsearch Integration
• Message Queue System
• Horizontal Scaling Support
• GraphQL API Layer

Phase 4: Developer Experience

• OpenAPI/Swagger Documentation
• CLI Tool for Code Generation
• Development Container Support
• Enhanced Debugging Tools
• Integration Test Framework

Phase 5: Enterprise Features

• Audit Logging System
• Business Event System
• Workflow Engine
• Report Generation
• Data Export/Import

Phase 6: Monitoring & Operations

• APM Integration
• Metrics Collection
• Alert System
• Log Aggregation
• Performance Analytics

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.