@iota-big3/sdk-adapters

Framework adapters for IOTA Big3 SDK - provides a unified interface for Express, Fastify, Koa, and other web frameworks.

Current Status (December 2024)

• Build: ✅ TypeScript compilation successful (0 errors)
• Tests: ✅ 49/49 passing (100% pass rate, 3 skipped)
• Phase: Completed Phase 2e & 2h
• Production Ready: Yes (Express adapter fully implemented)
• Documentation: Phase 2e & 2h Complete

Installation

npm install @iota-big3/sdk-adapters

Features

• 🚀 Multi-Framework Support: Express, Fastify, Koa (more coming)
• 🔌 Middleware System: CORS, Helmet, Rate Limiting, Compression, Logging
• 📊 Metrics & Monitoring: Built-in performance tracking
• 🔒 Security: Helmet security headers, rate limiting
• 🎯 Type Safety: Full TypeScript support
• 🔄 Event-Driven: Lifecycle events for all operations
• 🧩 SDK Integrations: Works with other IOTA Big3 SDKs

Quick Start

import { FrameworkAdaptersSDK } from "@iota-big3/sdk-adapters";

// Create SDK instance
const sdk = new FrameworkAdaptersSDK();

// Create an Express adapter
const adapter = sdk.createAdapter("express", {
  framework: "express",
  version: "4.18.0",
});

// Create Express app
const app = await adapter.createApp();

// Add middleware
const cors = MiddlewareHelpers.cors({
  origin: "https://example.com",
  credentials: true,
});
await adapter.addMiddleware(cors);

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

SDK Integrations

The adapters SDK can integrate with other IOTA Big3 SDKs for enhanced functionality:

With Event Bus

import { EventBus } from "@iota-big3/sdk-events";

const eventBus = new EventBus();
const sdk = new FrameworkAdaptersSDK({ eventBus });

// Listen to adapter events
eventBus.on("adapters:route.registered", (event) => {
  console.log("New route registered:", event);
});

With Logger

import { Logger } from "@iota-big3/sdk-observability";

const logger = new Logger("my-app");
const sdk = new FrameworkAdaptersSDK({ logger });

// All adapter operations will be logged

With Cache (Enhanced Rate Limiting)

import { CacheManager } from "@iota-big3/sdk-performance";

const cache = new CacheManager({
  redis: { host: "localhost" },
});
const sdk = new FrameworkAdaptersSDK({ cache });

// Rate limiting now uses Redis instead of in-memory

With Security

import { SecurityManager } from "@iota-big3/sdk-security";

const security = new SecurityManager();
const sdk = new FrameworkAdaptersSDK({ security });

// Enhanced security validation for all requests

Complete Integration Example

import { FrameworkAdaptersSDK } from "@iota-big3/sdk-adapters";
import { EventBus } from "@iota-big3/sdk-events";
import { Logger } from "@iota-big3/sdk-observability";
import { CacheManager } from "@iota-big3/sdk-performance";

// Create SDK with multiple integrations
const sdk = new FrameworkAdaptersSDK({
  eventBus: new EventBus(),
  logger: new Logger("adapters"),
  cache: new CacheManager({ redis: { host: "localhost" } }),
  enableMetrics: true,
  enableLogging: true,
});

// Create adapter
const adapter = sdk.createAdapter("express", {
  framework: "express",
});

// Events are automatically forwarded to event bus
// Logging is automatic
// Rate limiting uses Redis cache

Middleware

Built-in middleware helpers:

import { MiddlewareHelpers } from "@iota-big3/sdk-adapters";

// CORS
const cors = MiddlewareHelpers.cors({
  origin: "https://example.com",
  methods: ["GET", "POST"],
  credentials: true,
});

// Security Headers
const helmet = MiddlewareHelpers.helmet({
  contentSecurityPolicy: true,
  hsts: true,
});

// Rate Limiting
const rateLimit = MiddlewareHelpers.rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
});

// Request Logger
const logger = MiddlewareHelpers.logger({
  format: "combined",
});

// Compression
const compression = MiddlewareHelpers.compression({
  enabled: true,
});

// Error Handler
const errorHandler = MiddlewareHelpers.errorHandler({
  env: "production",
});

Events

The SDK emits various events that can be listened to:

// Direct event listening
adapter.on("route-registered", (data) => {
  console.log("Route registered:", data);
});

// Through event bus integration
eventBus.on("adapters:adapter.initialized", (event) => {
  console.log("Adapter initialized:", event);
});

Configuration

The SDK can be configured through options or centralized config:

// Option 1: Direct configuration
const sdk = new FrameworkAdaptersSDK({
  defaultFramework: "express",
  enableMetrics: true,
  enableLogging: true,
});

// Option 2: Through config integration
const config = new ConfigManager();
config.set("adapters", {
  defaultFramework: "fastify",
  enableMetrics: false,
});

const sdk = new FrameworkAdaptersSDK({ config });

Documentation

See https://docs.iota-big3.com for full documentation.

License

MIT