navis.js 1.0.0 → 3.0.0

package/examples/v3-features-demo.js

@@ -0,0 +1,226 @@
+/**
+ * Navis.js v3 Features Demo
+ * Demonstrates async messaging, observability, and enhanced features
+ */
+
+const {
+  Logger,
+  Metrics,
+  Tracer,
+  SQSMessaging,
+  KafkaMessaging,
+  NATSMessaging,
+} = require('../src/index');
+
+// Example 1: Structured Logging
+async function demoLogger() {
+  console.log('\n=== Structured Logging (v3) ===\n');
+
+  const logger = new Logger({
+    level: 'DEBUG',
+    format: 'text',
+    enableColors: true,
+    context: { service: 'demo-service', version: '1.0.0' },
+  });
+
+  logger.debug('Debug message', { userId: 123 });
+  logger.info('User logged in', { userId: 123, ip: '192.168.1.1' });
+  logger.warn('Rate limit approaching', { userId: 123, requests: 95 });
+  logger.error('Failed to process request', new Error('Connection timeout'), { userId: 123 });
+  
+  // Child logger with additional context
+  const requestLogger = logger.child({ requestId: 'req-123' });
+  requestLogger.info('Processing request');
+}
+
+// Example 2: Metrics Collection
+async function demoMetrics() {
+  console.log('\n=== Metrics Collection (v3) ===\n');
+
+  const metrics = new Metrics();
+
+  // Record some metrics
+  metrics.increment('api_calls_total', 1, { endpoint: '/users', method: 'GET' });
+  metrics.increment('api_calls_total', 1, { endpoint: '/users', method: 'POST' });
+  metrics.gauge('active_connections', 42);
+  metrics.histogram('response_time_ms', 150, { endpoint: '/users' });
+  metrics.histogram('response_time_ms', 200, { endpoint: '/users' });
+  metrics.histogram('response_time_ms', 120, { endpoint: '/users' });
+
+  // Record HTTP request
+  metrics.recordRequest('GET', '/users', 150, 200);
+  metrics.recordRequest('POST', '/users', 250, 201);
+
+  // Get all metrics
+  const allMetrics = metrics.getAll();
+  console.log('All metrics:', JSON.stringify(allMetrics, null, 2));
+
+  // Prometheus format
+  console.log('\nPrometheus format:');
+  console.log(metrics.toPrometheus());
+}
+
+// Example 3: Distributed Tracing
+async function demoTracer() {
+  console.log('\n=== Distributed Tracing (v3) ===\n');
+
+  const tracer = new Tracer({ serviceName: 'demo-service' });
+
+  // Start a trace
+  const traceId = tracer.startTrace('user-request');
+  console.log('Trace ID:', traceId);
+
+  // Start spans
+  const span1 = tracer.startSpan('database-query', { traceId });
+  tracer.addTag(span1, 'db.type', 'postgres');
+  tracer.addTag(span1, 'db.query', 'SELECT * FROM users');
+  tracer.addLog(span1, 'Query executed', { rows: 10 });
+  
+  // Simulate work
+  await new Promise(resolve => setTimeout(resolve, 100));
+  
+  tracer.finishSpan(span1, { status: 'ok' });
+
+  const span2 = tracer.startSpan('cache-lookup', { traceId, parentSpanId: span1 });
+  tracer.addTag(span2, 'cache.type', 'redis');
+  tracer.finishSpan(span2, { status: 'ok' });
+
+  // Get trace
+  const trace = tracer.getTrace(traceId);
+  console.log('Trace data:', JSON.stringify(trace, null, 2));
+}
+
+// Example 4: SQS Messaging (requires AWS SDK)
+async function demoSQS() {
+  console.log('\n=== SQS Messaging (v3) ===\n');
+  console.log('Note: Requires @aws-sdk/client-sqs and AWS credentials');
+
+  try {
+    const sqs = new SQSMessaging({
+      region: 'us-east-1',
+      queueUrl: process.env.SQS_QUEUE_URL,
+    });
+
+    await sqs.connect();
+    console.log('✅ Connected to SQS');
+
+    // Publish message
+    const result = await sqs.publish(process.env.SQS_QUEUE_URL, {
+      userId: 123,
+      action: 'user.created',
+      data: { name: 'John Doe' },
+    });
+    console.log('Published message:', result);
+
+    // Subscribe (would need actual queue)
+    // await sqs.subscribe(process.env.SQS_QUEUE_URL, async (message, metadata) => {
+    //   console.log('Received:', message);
+    // });
+
+  } catch (error) {
+    if (error.message.includes('@aws-sdk/client-sqs')) {
+      console.log('⚠️  AWS SDK not installed. Install with: npm install @aws-sdk/client-sqs');
+    } else {
+      console.log('⚠️  SQS demo requires AWS credentials and queue URL');
+    }
+  }
+}
+
+// Example 5: Kafka Messaging (requires kafkajs)
+async function demoKafka() {
+  console.log('\n=== Kafka Messaging (v3) ===\n');
+  console.log('Note: Requires kafkajs and Kafka broker');
+
+  try {
+    const kafka = new KafkaMessaging({
+      brokers: ['localhost:9092'],
+      clientId: 'navis-demo',
+    });
+
+    await kafka.connect();
+    console.log('✅ Connected to Kafka');
+
+    // Publish message
+    const result = await kafka.publish('user-events', {
+      userId: 123,
+      event: 'user.created',
+      data: { name: 'Jane Doe' },
+    });
+    console.log('Published to Kafka:', result);
+
+  } catch (error) {
+    if (error.message.includes('kafkajs')) {
+      console.log('⚠️  kafkajs not installed. Install with: npm install kafkajs');
+    } else {
+      console.log('⚠️  Kafka demo requires running Kafka broker');
+    }
+  }
+}
+
+// Example 6: NATS Messaging (requires nats)
+async function demoNATS() {
+  console.log('\n=== NATS Messaging (v3) ===\n');
+  console.log('Note: Requires nats and NATS server');
+
+  try {
+    const nats = new NATSMessaging({
+      servers: ['nats://localhost:4222'],
+    });
+
+    await nats.connect();
+    console.log('✅ Connected to NATS');
+
+    // Publish message
+    const result = await nats.publish('user.created', {
+      userId: 123,
+      name: 'Bob Smith',
+    });
+    console.log('Published to NATS:', result);
+
+    // Request-reply pattern
+    // const response = await nats.request('user.get', { userId: 123 });
+    // console.log('Response:', response);
+
+  } catch (error) {
+    if (error.message.includes('nats')) {
+      console.log('⚠️  nats not installed. Install with: npm install nats');
+    } else {
+      console.log('⚠️  NATS demo requires running NATS server');
+    }
+  }
+}
+
+// Run all demos
+async function runDemos() {
+  console.log('🚀 Navis.js v3 Features Demo\n');
+  console.log('='.repeat(50));
+
+  await demoLogger();
+  await demoMetrics();
+  await demoTracer();
+  await demoSQS();
+  await demoKafka();
+  await demoNATS();
+
+  console.log('\n' + '='.repeat(50));
+  console.log('✅ v3 features demo completed!');
+  console.log('\nNote: Messaging adapters require their respective dependencies:');
+  console.log('  - SQS: npm install @aws-sdk/client-sqs');
+  console.log('  - Kafka: npm install kafkajs');
+  console.log('  - NATS: npm install nats');
+}
+
+// Run if called directly
+if (require.main === module) {
+  runDemos().catch(console.error);
+}
+
+module.exports = {
+  demoLogger,
+  demoMetrics,
+  demoTracer,
+  demoSQS,
+  demoKafka,
+  demoNATS,
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navis.js",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -1,12 +1,50 @@
-const NavisApp = require('./core/app');
-const ServiceClient = require('./utils/service-client');
-const { success, error } = require('./utils/response');
-
-module.exports = {
-  NavisApp,
-  ServiceClient,
-  response: {
-    success,
-    error,
-  },
-};
+const NavisApp = require('./core/app');
+const ServiceClient = require('./utils/service-client');
+const ServiceConfig = require('./utils/service-config');
+const ServiceDiscovery = require('./utils/service-discovery');
+const CircuitBreaker = require('./utils/circuit-breaker');
+const { success, error } = require('./utils/response');
+const { retry, shouldRetryHttpStatus } = require('./utils/retry');
+
+// v3: Async Messaging
+const SQSMessaging = require('./messaging/sqs-adapter');
+const KafkaMessaging = require('./messaging/kafka-adapter');
+const NATSMessaging = require('./messaging/nats-adapter');
+
+// v3: Observability
+const Logger = require('./observability/logger');
+const Metrics = require('./observability/metrics');
+const Tracer = require('./observability/tracer');
+
+module.exports = {
+  // Core
+  NavisApp,
+  
+  // Service Client (v2 enhanced)
+  ServiceClient,
+  
+  // v2 Features
+  ServiceConfig,
+  ServiceDiscovery,
+  CircuitBreaker,
+  
+  // v3: Async Messaging
+  SQSMessaging,
+  KafkaMessaging,
+  NATSMessaging,
+  
+  // v3: Observability
+  Logger,
+  Metrics,
+  Tracer,
+  
+  // Utilities
+  response: {
+    success,
+    error,
+  },
+  retry: {
+    retry,
+    shouldRetryHttpStatus,
+  },
+};

package/src/messaging/base-messaging.js

@@ -0,0 +1,82 @@
+/**
+ * Base Messaging Interface
+ * v3: Abstract base class for async messaging adapters
+ */
+
+class BaseMessaging {
+  constructor(options = {}) {
+    this.options = options;
+    this.subscribers = new Map(); // topic -> [handlers]
+    this.isConnected = false;
+  }
+
+  /**
+   * Connect to messaging broker
+   * @abstract
+   */
+  async connect() {
+    throw new Error('connect() must be implemented by subclass');
+  }
+
+  /**
+   * Disconnect from messaging broker
+   * @abstract
+   */
+  async disconnect() {
+    throw new Error('disconnect() must be implemented by subclass');
+  }
+
+  /**
+   * Publish a message to a topic/queue
+   * @abstract
+   * @param {string} topic - Topic/queue name
+   * @param {Object} message - Message payload
+   * @param {Object} options - Publishing options
+   */
+  async publish(topic, message, options = {}) {
+    throw new Error('publish() must be implemented by subclass');
+  }
+
+  /**
+   * Subscribe to a topic/queue
+   * @abstract
+   * @param {string} topic - Topic/queue name
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Subscription options
+   */
+  async subscribe(topic, handler, options = {}) {
+    throw new Error('subscribe() must be implemented by subclass');
+  }
+
+  /**
+   * Unsubscribe from a topic/queue
+   * @abstract
+   * @param {string} topic - Topic/queue name
+   * @param {Function} handler - Optional specific handler to unsubscribe
+   */
+  async unsubscribe(topic, handler = null) {
+    throw new Error('unsubscribe() must be implemented by subclass');
+  }
+
+  /**
+   * Register a handler for a topic
+   * @protected
+   */
+  _registerHandler(topic, handler) {
+    if (!this.subscribers.has(topic)) {
+      this.subscribers.set(topic, []);
+    }
+    this.subscribers.get(topic).push(handler);
+  }
+
+  /**
+   * Get all handlers for a topic
+   * @protected
+   */
+  _getHandlers(topic) {
+    return this.subscribers.get(topic) || [];
+  }
+}
+
+module.exports = BaseMessaging;
+

package/src/messaging/kafka-adapter.js

@@ -0,0 +1,152 @@
+/**
+ * Kafka Messaging Adapter
+ * v3: Kafka integration for async messaging
+ * 
+ * Note: Requires kafkajs to be installed
+ * npm install kafkajs
+ */
+
+const BaseMessaging = require('./base-messaging');
+
+class KafkaMessaging extends BaseMessaging {
+  constructor(options = {}) {
+    super(options);
+    this.brokers = options.brokers || ['localhost:9092'];
+    this.clientId = options.clientId || 'navis-client';
+    this.consumerGroupId = options.consumerGroupId || 'navis-group';
+    this.kafka = null;
+    this.producer = null;
+    this.consumer = null;
+  }
+
+  /**
+   * Connect to Kafka
+   */
+  async connect() {
+    try {
+      const { Kafka } = require('kafkajs');
+      this.Kafka = Kafka;
+    } catch (err) {
+      throw new Error('kafkajs is required. Install it with: npm install kafkajs');
+    }
+
+    this.kafka = new this.Kafka({
+      clientId: this.clientId,
+      brokers: this.brokers,
+      ...this.options.kafkaConfig,
+    });
+
+    this.producer = this.kafka.producer();
+    await this.producer.connect();
+
+    this.consumer = this.kafka.consumer({ groupId: this.consumerGroupId });
+    await this.consumer.connect();
+
+    this.isConnected = true;
+    return this;
+  }
+
+  /**
+   * Disconnect from Kafka
+   */
+  async disconnect() {
+    this.isConnected = false;
+    
+    if (this.producer) {
+      await this.producer.disconnect();
+      this.producer = null;
+    }
+    
+    if (this.consumer) {
+      await this.consumer.disconnect();
+      this.consumer = null;
+    }
+  }
+
+  /**
+   * Publish message to Kafka topic
+   * @param {string} topic - Kafka topic name
+   * @param {Object} message - Message payload
+   * @param {Object} options - Publishing options
+   */
+  async publish(topic, message, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    const result = await this.producer.send({
+      topic,
+      messages: [{
+        key: options.key || null,
+        value: JSON.stringify(message),
+        headers: options.headers || {},
+      }],
+    });
+
+    return {
+      topic,
+      partition: result[0].partition,
+      offset: result[0].offset,
+    };
+  }
+
+  /**
+   * Subscribe to Kafka topic
+   * @param {string} topic - Kafka topic name
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Subscription options
+   */
+  async subscribe(topic, handler, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    this._registerHandler(topic, handler);
+
+    await this.consumer.subscribe({ 
+      topic,
+      fromBeginning: options.fromBeginning || false,
+    });
+
+    await this.consumer.run({
+      eachMessage: async ({ topic, partition, message }) => {
+        try {
+          const body = JSON.parse(message.value.toString());
+          const handlers = this._getHandlers(topic);
+
+          for (const h of handlers) {
+            await h(body, {
+              topic,
+              partition,
+              offset: message.offset,
+              key: message.key?.toString(),
+              headers: message.headers,
+            });
+          }
+        } catch (error) {
+          console.error('Error processing Kafka message:', error);
+        }
+      },
+    });
+
+    return { topic, handler };
+  }
+
+  /**
+   * Unsubscribe from topic
+   */
+  async unsubscribe(topic, handler = null) {
+    if (handler) {
+      const handlers = this._getHandlers(topic);
+      const index = handlers.indexOf(handler);
+      if (index > -1) {
+        handlers.splice(index, 1);
+      }
+    } else {
+      this.subscribers.delete(topic);
+    }
+  }
+}
+
+module.exports = KafkaMessaging;
+

package/src/messaging/nats-adapter.js

@@ -0,0 +1,141 @@
+/**
+ * NATS Messaging Adapter
+ * v3: NATS integration for async messaging
+ * 
+ * Note: Requires nats to be installed
+ * npm install nats
+ */
+
+const BaseMessaging = require('./base-messaging');
+
+class NATSMessaging extends BaseMessaging {
+  constructor(options = {}) {
+    super(options);
+    this.servers = options.servers || ['nats://localhost:4222'];
+    this.nc = null;
+  }
+
+  /**
+   * Connect to NATS
+   */
+  async connect() {
+    try {
+      const { connect } = require('nats');
+      this.connectNATS = connect;
+    } catch (err) {
+      throw new Error('nats is required. Install it with: npm install nats');
+    }
+
+    this.nc = await this.connectNATS({
+      servers: this.servers,
+      ...this.options.natsConfig,
+    });
+
+    this.isConnected = true;
+    return this;
+  }
+
+  /**
+   * Disconnect from NATS
+   */
+  async disconnect() {
+    this.isConnected = false;
+    if (this.nc) {
+      await this.nc.close();
+      this.nc = null;
+    }
+  }
+
+  /**
+   * Publish message to NATS subject
+   * @param {string} subject - NATS subject
+   * @param {Object} message - Message payload
+   * @param {Object} options - Publishing options
+   */
+  async publish(subject, message, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    const data = Buffer.from(JSON.stringify(message));
+    this.nc.publish(subject, data);
+    
+    return { subject, published: true };
+  }
+
+  /**
+   * Subscribe to NATS subject
+   * @param {string} subject - NATS subject
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Subscription options
+   */
+  async subscribe(subject, handler, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    this._registerHandler(subject, handler);
+
+    const subscription = this.nc.subscribe(subject, {
+      queue: options.queue || undefined,
+    });
+
+    (async () => {
+      for await (const msg of subscription) {
+        try {
+          const body = JSON.parse(msg.data.toString());
+          const handlers = this._getHandlers(subject);
+
+          for (const h of handlers) {
+            await h(body, {
+              subject: msg.subject,
+              reply: msg.reply,
+              sid: msg.sid,
+            });
+          }
+        } catch (error) {
+          console.error('Error processing NATS message:', error);
+        }
+      }
+    })().catch(console.error);
+
+    return { subject, handler, subscription };
+  }
+
+  /**
+   * Unsubscribe from subject
+   */
+  async unsubscribe(subject, handler = null) {
+    if (handler) {
+      const handlers = this._getHandlers(subject);
+      const index = handlers.indexOf(handler);
+      if (index > -1) {
+        handlers.splice(index, 1);
+      }
+    } else {
+      this.subscribers.delete(subject);
+    }
+  }
+
+  /**
+   * Request-reply pattern
+   * @param {string} subject - NATS subject
+   * @param {Object} message - Request message
+   * @param {Object} options - Request options
+   */
+  async request(subject, message, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    const data = Buffer.from(JSON.stringify(message));
+    const response = await this.nc.request(subject, data, {
+      timeout: options.timeout || 5000,
+    });
+
+    return JSON.parse(response.data.toString());
+  }
+}
+
+module.exports = NATSMessaging;
+