navis.js 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Syed Iman Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,158 @@
+# Navis.js
+
+A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js.
+
+## Philosophy
+
+Navis.js is "Express for serverless microservices — but simpler."
+
+- **Extremely lightweight** - Zero or minimal dependencies
+- **Serverless-first** - Built for AWS Lambda
+- **Microservice-friendly** - API-to-API communication made easy
+- **Simple & readable** - No magic abstractions
+
+## Installation
+
+### Via npm
+
+```bash
+npm install navis.js
+```
+
+### From GitHub
+
+```bash
+# Clone the repository
+git clone https://github.com/mafhh14/navis.js.git
+cd navis.js
+
+# Install dependencies (if any)
+npm install
+
+# Link CLI locally for development
+npm link
+```
+
+## Quick Start
+
+### Node.js HTTP Server
+
+```javascript
+const { NavisApp, response } = require('navis.js');
+
+const app = new NavisApp();
+
+app.get('/', (req, res) => {
+  response.success(res, { message: 'Hello Navis.js!' });
+});
+
+app.listen(3000);
+```
+
+### AWS Lambda
+
+```javascript
+const { NavisApp } = require('navis.js');
+
+const app = new NavisApp();
+
+app.get('/hello', (req, res) => {
+  res.statusCode = 200;
+  res.body = { message: 'Hello from Lambda!' };
+});
+
+exports.handler = async (event) => {
+  return await app.handleLambda(event);
+};
+```
+
+## CLI
+
+```bash
+# Start example server
+navis start
+```
+
+## Features
+
+### v1 (Current)
+
+- ✅ HTTP routing (GET, POST, PUT, DELETE)
+- ✅ Middleware support (`app.use()`)
+- ✅ Unified handler for Node.js and AWS Lambda
+- ✅ Simple path-based routing
+- ✅ ServiceClient for service-to-service calls
+- ✅ Timeout support
+
+### v2 (Planned)
+
+- 🔄 Retry logic
+- 🔄 Circuit breaker
+- 🔄 Config-based services
+- 🔄 Service discovery
+- 🔄 Async messaging (SQS / Kafka / NATS)
+- 🔄 CLI generators (`navis generate service`)
+
+## API Reference
+
+### NavisApp
+
+#### Methods
+
+- `app.use(fn)` - Register middleware
+- `app.get(path, handler)` - Register GET route
+- `app.post(path, handler)` - Register POST route
+- `app.put(path, handler)` - Register PUT route
+- `app.delete(path, handler)` - Register DELETE route
+- `app.listen(port, callback)` - Start HTTP server (Node.js)
+- `app.handleLambda(event)` - Handle AWS Lambda event
+
+### ServiceClient
+
+const { ServiceClient } = require('navis.js');
+
+const client = new ServiceClient('http://api.example.com', {
+  timeout: 5000, // milliseconds
+});
+
+// GET request
+const response = await client.get('/users');
+
+// POST request
+const result = await client.post('/users', { name: 'John' });
+```
+
+### Response Helpers
+
+```javascript
+const { response } = require('navis.js');
+
+// Success response
+response.success(res, { data: 'value' }, 200);
+
+// Error response
+response.error(res, 'Error message', 500);
+```
+
+## Examples
+
+See the `examples/` directory:
+
+- `server.js` - Node.js HTTP server example
+- `lambda.js` - AWS Lambda handler example
+- `service-client-demo.js` - ServiceClient usage example
+
+## Roadmap
+
+### v1 (Current)
+Core functionality: routing, middleware, Lambda support, ServiceClient
+
+### v2 (Next)
+Resilience patterns: retry, circuit breaker, service discovery
+
+### v3 (Future)
+Advanced features: async messaging, observability, advanced CLI
+
+## License
+
+MIT

package/bin/navis.js

@@ -0,0 +1,46 @@
+/**
+ * Navis.js CLI
+ * v1: Basic start command
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const command = process.argv[2];
+
+if (command === 'start') {
+  // Check if examples/server.js exists
+  const serverPath = path.join(__dirname, '..', 'examples', 'server.js');
+  
+  if (!fs.existsSync(serverPath)) {
+    console.error('Error: examples/server.js not found');
+    process.exit(1);
+  }
+
+  // Run the server
+  const server = spawn('node', [serverPath], {
+    stdio: 'inherit',
+    cwd: path.join(__dirname, '..'),
+  });
+
+  server.on('error', (err) => {
+    console.error('Error starting server:', err);
+    process.exit(1);
+  });
+
+  server.on('exit', (code) => {
+    process.exit(code);
+  });
+} else if (command === 'generate') {
+  // TODO v2: Implement navis generate service
+  console.log('Generator commands coming in v2');
+} else {
+  console.log('Navis.js CLI');
+  console.log('');
+  console.log('Usage:');
+  console.log('  navis start        Start the example server');
+  console.log('');
+  console.log('v2 commands:');
+  console.log('  navis generate     Generate service boilerplate');
+}

package/examples/lambda.js

@@ -0,0 +1,30 @@
+const { NavisApp } = require('../src/index');
+
+const app = new NavisApp();
+
+// Middleware example
+app.use((req, res, next) => {
+  console.log(`Lambda: ${req.method} ${req.path}`);
+  next();
+});
+
+// Routes
+app.get('/', (req, res) => {
+  res.statusCode = 200;
+  res.body = { message: 'Welcome to Navis.js Lambda!' };
+});
+
+app.get('/health', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'ok' };
+});
+
+app.post('/echo', (req, res) => {
+  res.statusCode = 200;
+  res.body = { echo: req.body };
+});
+
+// Lambda handler
+exports.handler = async (event) => {
+  return await app.handleLambda(event);
+};

package/examples/server.js

@@ -0,0 +1,36 @@
+const { NavisApp, response } = require('../src/index');
+
+const app = new NavisApp();
+
+// Middleware example
+app.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
+
+// Routes
+app.get('/', (req, res) => {
+  response.success(res, { message: 'Welcome to Navis.js!' });
+});
+
+app.get('/health', (req, res) => {
+  response.success(res, { status: 'ok' });
+});
+
+app.post('/echo', (req, res) => {
+  // In Node.js, we need to parse body manually (v1 simplicity)
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', () => {
+    const data = body ? JSON.parse(body) : {};
+    response.success(res, { echo: data });
+  });
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Example server running on http://localhost:${PORT}`);
+});

package/examples/service-client-demo.js

@@ -0,0 +1,27 @@
+const { ServiceClient } = require('../src/index');
+
+// Example: Call another microservice
+async function demo() {
+  const client = new ServiceClient('http://localhost:3000', {
+    timeout: 3000,
+  });
+
+  try {
+    // GET request
+    const healthCheck = await client.get('/health');
+    console.log('Health check:', healthCheck);
+
+    // POST request
+    const echo = await client.post('/echo', { message: 'Hello from ServiceClient!' });
+    console.log('Echo:', echo);
+  } catch (err) {
+    console.error('Service call failed:', err.message);
+  }
+}
+
+// Run demo if called directly
+if (require.main === module) {
+  demo();
+}
+
+module.exports = { demo };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "navis.js",
+  "version": "1.0.0",
+  "description": "A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js",
+  "main": "src/index.js",
+  "bin": {
+    "navis": "bin/navis.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node examples/server.js"
+  },
+  "keywords": [
+    "serverless",
+    "lambda",
+    "aws-lambda",
+    "microservice",
+    "api",
+    "framework",
+    "express",
+    "http",
+    "routing",
+    "middleware",
+    "nodejs"
+  ],
+  "author": "Syed Iman Ali",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mafhh14/navis.js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mafhh14/navis.js/issues"
+  },
+  "homepage": "https://github.com/mafhh14/navis.js#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/core/app.js

@@ -0,0 +1,177 @@
+const http = require('http');
+const Router = require('./router');
+const { executeMiddleware } = require('./middleware');
+const { error: errorResponse } = require('../utils/response');
+
+/**
+ * NavisApp - Main application class
+ */
+class NavisApp {
+  constructor() {
+    this.router = new Router();
+    this.middlewares = [];
+    this.server = null;
+  }
+
+  /**
+   * Register middleware
+   * @param {Function} fn - Middleware function (req, res, next)
+   */
+  use(fn) {
+    this.middlewares.push(fn);
+  }
+
+  /**
+   * Register GET route
+   */
+  get(path, handler) {
+    this.router.get(path, handler);
+  }
+
+  /**
+   * Register POST route
+   */
+  post(path, handler) {
+    this.router.post(path, handler);
+  }
+
+  /**
+   * Register PUT route
+   */
+  put(path, handler) {
+    this.router.put(path, handler);
+  }
+
+  /**
+   * Register DELETE route
+   */
+  delete(path, handler) {
+    this.router.delete(path, handler);
+  }
+
+  /**
+   * Handle HTTP request (Node.js)
+   * @param {Object} req - Node.js HTTP request
+   * @param {Object} res - Node.js HTTP response
+   */
+  async handleRequest(req, res) {
+    const method = req.method;
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const path = url.pathname;
+
+    // Find route handler
+    const handler = this.router.find(method, path);
+
+    if (!handler) {
+      errorResponse(res, 'Not Found', 404);
+      return;
+    }
+
+    // Execute middleware chain, then route handler
+    try {
+      await executeMiddleware(
+        this.middlewares,
+        req,
+        res,
+        handler,
+        false
+      );
+    } catch (err) {
+      errorResponse(res, err.message || 'Internal Server Error', 500);
+    }
+  }
+
+  /**
+   * Handle AWS Lambda event
+   * @param {Object} event - Lambda event
+   * @returns {Object} - Lambda response
+   */
+  async handleLambda(event) {
+    const method = event.httpMethod || event.requestContext?.http?.method || 'GET';
+    const path = event.path || event.rawPath || '/';
+
+    // Find route handler
+    const handler = this.router.find(method, path);
+
+    if (!handler) {
+      return {
+        statusCode: 404,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ error: 'Not Found' }),
+      };
+    }
+
+    // Create Lambda-compatible req/res objects
+    const req = {
+      method,
+      path,
+      headers: event.headers || {},
+      body: event.body ? JSON.parse(event.body) : {},
+      query: event.queryStringParameters || {},
+      // Store original event for advanced use cases
+      event,
+    };
+
+    const res = {
+      statusCode: 200,
+      headers: {},
+      body: null,
+    };
+
+    // Execute middleware chain, then route handler
+    try {
+      const result = await executeMiddleware(
+        this.middlewares,
+        req,
+        res,
+        handler,
+        true
+      );
+
+      // If handler returned a Lambda response directly, use it
+      if (result && result.statusCode) {
+        return result;
+      }
+
+      // Otherwise, construct response from res object
+      return {
+        statusCode: res.statusCode || 200,
+        headers: {
+          'Content-Type': 'application/json',
+          ...res.headers,
+        },
+        body: res.body ? JSON.stringify(res.body) : JSON.stringify(result || {}),
+      };
+    } catch (err) {
+      return {
+        statusCode: 500,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ error: err.message || 'Internal Server Error' }),
+      };
+    }
+  }
+
+  /**
+   * Start HTTP server (Node.js)
+   * @param {number} port - Port number
+   * @param {Function} callback - Optional callback
+   */
+  listen(port = 3000, callback) {
+    this.server = http.createServer((req, res) => {
+      this.handleRequest(req, res);
+    });
+
+    this.server.listen(port, () => {
+      if (callback) callback();
+      console.log(`Navis.js server listening on port ${port}`);
+    });
+
+    return this.server;
+  }
+}
+
+module.exports = NavisApp;

package/src/core/middleware.js

@@ -0,0 +1,39 @@
+/**
+ * Middleware engine for sequential execution
+ */
+
+/**
+ * Execute middleware chain sequentially
+ * @param {Array} middlewares - Array of middleware functions
+ * @param {Object} req - Request object
+ * @param {Object} res - Response object
+ * @param {Function} finalHandler - Final route handler
+ * @param {boolean} isLambda - Whether this is a Lambda invocation
+ */
+async function executeMiddleware(middlewares, req, res, finalHandler, isLambda = false) {
+  let index = 0;
+
+  const next = async () => {
+    if (index >= middlewares.length) {
+      // All middleware executed, run final handler
+      if (finalHandler) {
+        return await finalHandler(req, res);
+      }
+      return;
+    }
+
+    const middleware = middlewares[index++];
+    try {
+      await middleware(req, res, next);
+    } catch (err) {
+      // Error in middleware - stop chain
+      throw err;
+    }
+  };
+
+  return await next();
+}
+
+module.exports = {
+  executeMiddleware,
+};

package/src/core/router.js

@@ -0,0 +1,71 @@
+/**
+ * Simple path-based router
+ * v1: No regex, no params (keep it simple)
+ */
+
+class Router {
+  constructor() {
+    this.routes = {
+      GET: {},
+      POST: {},
+      PUT: {},
+      DELETE: {},
+    };
+  }
+
+  /**
+   * Register a route handler
+   * @param {string} method - HTTP method
+   * @param {string} path - Route path (exact match only in v1)
+   * @param {Function} handler - Route handler function
+   */
+  register(method, path, handler) {
+    const normalizedMethod = method.toUpperCase();
+    if (!this.routes[normalizedMethod]) {
+      throw new Error(`Unsupported HTTP method: ${method}`);
+    }
+    this.routes[normalizedMethod][path] = handler;
+  }
+
+  /**
+   * Get route handler for a method and path
+   * @param {string} method - HTTP method
+   * @param {string} path - Route path
+   * @returns {Function|null} - Route handler or null if not found
+   */
+  find(method, path) {
+    const normalizedMethod = method.toUpperCase();
+    const methodRoutes = this.routes[normalizedMethod] || {};
+    return methodRoutes[path] || null;
+  }
+
+  /**
+   * Register GET route
+   */
+  get(path, handler) {
+    this.register('GET', path, handler);
+  }
+
+  /**
+   * Register POST route
+   */
+  post(path, handler) {
+    this.register('POST', path, handler);
+  }
+
+  /**
+   * Register PUT route
+   */
+  put(path, handler) {
+    this.register('PUT', path, handler);
+  }
+
+  /**
+   * Register DELETE route
+   */
+  delete(path, handler) {
+    this.register('DELETE', path, handler);
+  }
+}
+
+module.exports = Router;

package/src/index.js

@@ -0,0 +1,12 @@
+const NavisApp = require('./core/app');
+const ServiceClient = require('./utils/service-client');
+const { success, error } = require('./utils/response');
+
+module.exports = {
+  NavisApp,
+  ServiceClient,
+  response: {
+    success,
+    error,
+  },
+};

package/src/utils/response.js

@@ -0,0 +1,56 @@
+/**
+ * Unified response helper for Node.js HTTP and AWS Lambda
+ */
+
+/**
+ * Send a unified response
+ * @param {Object} context - Response context (res for Node.js, or Lambda context)
+ * @param {number} statusCode - HTTP status code
+ * @param {Object|string} data - Response data
+ * @param {boolean} isLambda - Whether this is a Lambda invocation
+ */
+function sendResponse(context, statusCode, data, isLambda = false) {
+  const body = typeof data === 'string' ? data : JSON.stringify(data);
+  
+  if (isLambda) {
+    // Lambda response format
+    return {
+      statusCode,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body,
+    };
+  } else {
+    // Node.js HTTP response
+    context.writeHead(statusCode, {
+      'Content-Type': 'application/json',
+    });
+    context.end(body);
+  }
+}
+
+/**
+ * Success response helper
+ */
+function success(context, data, statusCode = 200, isLambda = false) {
+  return sendResponse(context, statusCode, data, isLambda);
+}
+
+/**
+ * Error response helper
+ */
+function error(context, message, statusCode = 500, isLambda = false) {
+  return sendResponse(
+    context,
+    statusCode,
+    { error: message },
+    isLambda
+  );
+}
+
+module.exports = {
+  sendResponse,
+  success,
+  error,
+};

package/src/utils/service-client.js

@@ -0,0 +1,105 @@
+const http = require('http');
+const https = require('https');
+
+/**
+ * ServiceClient - Lightweight HTTP client for service-to-service calls
+ * v1: Basic get() and post() with timeout support
+ */
+
+class ServiceClient {
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl;
+    this.timeout = options.timeout || 5000; // Default 5s timeout
+    // TODO v2: Add retry logic
+    // TODO v2: Add circuit breaker
+    // TODO v2: Add config-based services
+  }
+
+  /**
+   * Make HTTP request
+   * @private
+   */
+  _request(method, path, data = null, options = {}) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.baseUrl);
+      const isHttps = url.protocol === 'https:';
+      const client = isHttps ? https : http;
+
+      const requestOptions = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname + url.search,
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...options.headers,
+        },
+        timeout: options.timeout || this.timeout,
+      };
+
+      const req = client.request(requestOptions, (res) => {
+        let body = '';
+
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+
+        res.on('end', () => {
+          try {
+            const parsedBody = body ? JSON.parse(body) : {};
+            resolve({
+              statusCode: res.statusCode,
+              headers: res.headers,
+              data: parsedBody,
+            });
+          } catch (err) {
+            resolve({
+              statusCode: res.statusCode,
+              headers: res.headers,
+              data: body,
+            });
+          }
+        });
+      });
+
+      req.on('error', (err) => {
+        reject(err);
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error('Request timeout'));
+      });
+
+      if (data) {
+        req.write(JSON.stringify(data));
+      }
+
+      req.end();
+    });
+  }
+
+  /**
+   * GET request
+   * @param {string} path - Request path
+   * @param {Object} options - Request options
+   */
+  async get(path, options = {}) {
+    return this._request('GET', path, null, options);
+  }
+
+  /**
+   * POST request
+   * @param {string} path - Request path
+   * @param {Object} data - Request body data
+   * @param {Object} options - Request options
+   */
+  async post(path, data, options = {}) {
+    return this._request('POST', path, data, options);
+  }
+
+  // TODO v2: Add PUT, DELETE, PATCH methods
+  // TODO v2: Add service discovery integration
+}
+
+module.exports = ServiceClient;