rpc-express-toolkit 2.0.0

package/examples/example.js

@@ -0,0 +1,41 @@
+const express = require('express');
+const { RpcEndpoint } = require('../src/index');
+
+const app = express();
+
+app.use(express.json());
+
+const context = { user: 'admin' };
+
+// Attach to the app router at POST /api endpoint
+const rpc = new RpcEndpoint(app, context);
+
+rpc.addMethod('greet', (req, ctx, params) => {
+    const { name } = params;
+    return `Hello, ${name}!`;
+});
+
+rpc.addMethod('getTime', (req, ctx, params) => {
+    return new Date().toISOString();
+});
+
+rpc.addMethod('invalid-token', (req, ctx, params) => {
+    // Example: Validate the token from request headers
+    const token = req.headers.authorization;
+    if (!token || !isValidToken(token)) { // Replace `isValidToken` with your validation logic
+        throw new Error('Invalid or missing token');
+    }
+    return 'OK';
+});
+
+// Example token validation function (replace with your actual logic)
+function isValidToken(token) {
+    // Simple example: Check if the token matches a predefined value
+    const expectedToken = 'my-secret-token'; // Replace with your actual token handling logic
+    return token === expectedToken;
+}
+
+const PORT = 3000;
+app.listen(PORT, () => {
+    console.log(`Server listening on port ${PORT}`);
+});

package/examples/server-client-example.js

@@ -0,0 +1,114 @@
+const express = require('express');
+const { RpcEndpoint, RpcClient } = require('../src/index');
+
+// === SERVER SETUP ===
+const app = express();
+app.use(express.json());
+
+const context = { 
+  database: new Map(),
+  userId: 'system'
+};
+
+// Create JSON-RPC endpoint with clean names
+const rpc = new RpcEndpoint(app, context);
+
+// Add some methods
+rpc.addMethod('saveData', (req, ctx, params) => {
+  const { key, value } = params;
+  ctx.database.set(key, value);
+  return { success: true, message: `Data saved with key: ${key}` };
+});
+
+rpc.addMethod('getData', (req, ctx, params) => {
+  const { key } = params;
+  const value = ctx.database.get(key);
+  if (value === undefined) {
+    throw new Error(`Key '${key}' not found`);
+  }
+  return { key, value };
+});
+
+rpc.addMethod('getAllData', (req, ctx) => {
+  return Array.from(ctx.database.entries()).map(([key, value]) => ({ key, value }));
+});
+
+rpc.addMethod('testBigInt', (req, ctx, params) => {
+  const bigNumber = BigInt(params.number || '123456789012345678901234567890');
+  return {
+    original: params.number,
+    bigint: bigNumber,
+    doubled: bigNumber * 2n,
+    timestamp: new Date()
+  };
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+const server = app.listen(PORT, () => {
+  console.log(`🚀 JSON-RPC Server running on http://localhost:${PORT}`);
+  console.log(`📡 Endpoint: http://localhost:${PORT}/api`);
+  
+  // === CLIENT DEMO ===
+  setTimeout(async () => {
+    console.log('\n🔧 Testing client...');
+    
+    const client = new RpcClient(`http://localhost:${PORT}/api`);
+    
+    try {
+      // Test 1: Save some data
+      console.log('📝 Saving data...');
+      const saveResult = await client.call('saveData', { key: 'test', value: 'Hello World!' });
+      console.log('✅ Save result:', saveResult);
+      
+      // Test 2: Get data back
+      console.log('\n📖 Getting data...');
+      const getData = await client.call('getData', { key: 'test' });
+      console.log('✅ Get result:', getData);
+      
+      // Test 3: Test BigInt handling
+      console.log('\n🔢 Testing BigInt...');
+      const bigIntResult = await client.call('testBigInt', { number: '999999999999999999999999999999' });
+      console.log('✅ BigInt result:', bigIntResult);
+      console.log('   - Original BigInt type:', typeof bigIntResult.bigint);
+      console.log('   - Doubled BigInt type:', typeof bigIntResult.doubled);
+      console.log('   - Timestamp type:', typeof bigIntResult.timestamp);
+      
+      // Test 4: Get all data
+      console.log('\n📊 Getting all data...');
+      const allData = await client.call('getAllData');
+      console.log('✅ All data:', allData);
+      
+      // Test 5: Test error handling
+      console.log('\n❌ Testing error handling...');
+      try {
+        await client.call('getData', { key: 'nonexistent' });
+      } catch (error) {
+        console.log('✅ Error caught correctly:', error.message);
+      }
+      
+      console.log('\n✨ All tests completed successfully!');
+      
+    } catch (error) {
+      console.error('❌ Client error:', error);
+    }
+    
+    // Close server after demo
+    setTimeout(() => {
+      server.close(() => {
+        console.log('\n👋 Server closed');
+        process.exit(0);
+      });
+    }, 1000);
+    
+  }, 1000);
+});
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n🛑 Shutting down server...');
+  server.close(() => {
+    console.log('👋 Server closed');
+    process.exit(0);
+  });
+});

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "rpc-express-toolkit",
+  "version": "2.0.0",
+  "description": "Enterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, structured logging, middleware system, schema validation, and comprehensive BigInt/Date support.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src/ examples/",
+    "lint:fix": "eslint src/ examples/ --fix",
+    "clean": "node -e \"require('fs').existsSync('dist') && require('fs').rmSync('dist', {recursive: true})\"",
+    "build": "npm run build:minify",
+    "build:minify": "npm run build:js && npm run build:mjs",
+    "build:js": "terser src/clients/rpc-client.js -o src/clients/rpc-client.min.js --compress --mangle --comments false",
+    "build:mjs": "terser src/clients/rpc-client.mjs -o src/clients/rpc-client.min.mjs --compress --mangle --comments false --module",
+    "prepublishOnly": "npm run build",
+    "precommit": "npm run lint && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/n-car/rpc-express-toolkit.git"
+  },
+  "keywords": [
+    "json-rpc",
+    "express",
+    "toolkit",
+    "rpc",
+    "server",
+    "client",
+    "middleware",
+    "validation",
+    "bigint",
+    "enterprise",
+    "nodejs"
+  ],
+  "author": "Nicola Carpanese <nicola.carpanese@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/n-car/rpc-express-toolkit/issues"
+  },
+  "homepage": "https://github.com/n-car/rpc-express-toolkit#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-prettier": "^8.8.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "husky": "^8.0.0",
+    "jest": "^29.7.0",
+    "lint-staged": "^13.0.0",
+    "prettier": "^3.4.2",
+    "supertest": "^6.3.3",
+    "terser": "^5.43.1"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "express": "^4.21.2",
+    "nested-error-stacks": "^2.1.1"
+  },
+  "optionalDependencies": {
+    "node-fetch": "^2.7.0"
+  },
+  "contributors": [
+    {
+      "name": "Nicola Carpanese",
+      "email": "nicola.carpanese@gmail.com",
+      "url": "https://github.com/n-car"
+    }
+  ],
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "src/**/*.js": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "examples/**/*.js": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

package/src/batch.js

@@ -0,0 +1,237 @@
+"use strict";
+
+/**
+ * Batch request handler for JSON-RPC 2.0
+ */
+class BatchHandler {
+  constructor(endpoint) {
+    this.endpoint = endpoint;
+  }
+
+  /**
+   * Check if request is a batch request
+   * @param {any} body 
+   * @returns {boolean}
+   */
+  isBatchRequest(body) {
+    return Array.isArray(body) && body.length > 0;
+  }
+
+  /**
+   * Validate batch request
+   * @param {Array} batch 
+   * @returns {Object}
+   */
+  validateBatch(batch) {
+    if (!Array.isArray(batch)) {
+      return {
+        valid: false,
+        error: { code: -32600, message: 'Invalid Request: Batch must be an array' }
+      };
+    }
+
+    if (batch.length === 0) {
+      return {
+        valid: false,
+        error: { code: -32600, message: 'Invalid Request: Batch cannot be empty' }
+      };
+    }
+
+    // Check for duplicate IDs in the batch
+    const ids = batch.map(req => req.id).filter(id => id !== undefined && id !== null);
+    const uniqueIds = new Set(ids);
+    
+    if (ids.length !== uniqueIds.size) {
+      return {
+        valid: false,
+        error: { code: -32600, message: 'Invalid Request: Duplicate IDs in batch' }
+      };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Process a batch of JSON-RPC requests
+   * @param {Array} batch 
+   * @param {Object} req 
+   * @param {Object} res 
+   * @param {any} context 
+   * @returns {Promise<Array>}
+   */
+  async processBatch(batch, req, res, context) {
+    const validation = this.validateBatch(batch);
+    if (!validation.valid) {
+      return [{ 
+        jsonrpc: '2.0', 
+        id: null, 
+        error: validation.error 
+      }];
+    }
+
+    // Process all requests in parallel
+    const promises = batch.map(async (request, index) => {
+      try {
+        return await this.processSingleRequest(request, req, context, index);
+      } catch (error) {
+        return {
+          jsonrpc: '2.0',
+          id: request.id || null,
+          error: {
+            code: error.code || -32603,
+            message: error.message || 'Internal error',
+            data: { batchIndex: index }
+          }
+        };
+      }
+    });
+
+    const results = await Promise.all(promises);
+    
+    // Filter out notifications (requests without id)
+    return results.filter(result => result !== null);
+  }
+
+  /**
+   * Process a single request within a batch
+   * @param {Object} request 
+   * @param {Object} req 
+   * @param {any} context 
+   * @param {number} batchIndex 
+   * @returns {Promise<Object|null>}
+   */
+  async processSingleRequest(request, req, context, batchIndex) {
+    const { jsonrpc, method, params, id } = request;
+
+    // Validate JSON-RPC 2.0 request structure
+    if (jsonrpc !== "2.0") {
+      return {
+        jsonrpc: '2.0',
+        id: id || null,
+        error: { 
+          code: -32600, 
+          message: `Invalid Request: 'jsonrpc' must be '2.0'`,
+          data: { batchIndex }
+        }
+      };
+    }
+
+    if (typeof method !== "string") {
+      return {
+        jsonrpc: '2.0',
+        id: id || null,
+        error: { 
+          code: -32600, 
+          message: `Invalid Request: 'method' must be a string`,
+          data: { batchIndex }
+        }
+      };
+    }
+
+    const handler = this.endpoint.methods[method];
+    if (!handler) {
+      return {
+        jsonrpc: '2.0',
+        id: id || null,
+        error: { 
+          code: -32601, 
+          message: `Method "${method}" not found`,
+          data: { batchIndex }
+        }
+      };
+    }
+
+    // If no id is provided, this is a notification - don't return response
+    const isNotification = id === undefined || id === null;
+
+    try {
+      // Execute middleware
+      let middlewareContext = {
+        req,
+        res: null, // No response object for batch items
+        method,
+        params,
+        context,
+        batchIndex,
+        isNotification
+      };
+
+      if (this.endpoint.middleware) {
+        middlewareContext = await this.endpoint.middleware.execute('beforeCall', middlewareContext);
+      }
+
+      // Execute the handler
+      const result = await Promise.resolve(handler(req, context, middlewareContext.params));
+      
+      // Execute after middleware
+      if (this.endpoint.middleware) {
+        middlewareContext.result = result;
+        await this.endpoint.middleware.execute('afterCall', middlewareContext);
+      }
+
+      // For notifications, return null (will be filtered out)
+      if (isNotification) {
+        return null;
+      }
+
+      // Serialize the result
+      const safeResult = this.endpoint.serializeBigIntsAndDates(result);
+      
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: safeResult
+      };
+
+    } catch (error) {
+      // Execute error middleware
+      if (this.endpoint.middleware) {
+        try {
+          await this.endpoint.middleware.execute('onError', {
+            ...middlewareContext,
+            error,
+            batchIndex
+          });
+        } catch (middlewareError) {
+          // Ignore middleware errors in error handling
+        }
+      }
+
+      // For notifications, return null even on error
+      if (isNotification) {
+        return null;
+      }
+
+      return {
+        jsonrpc: '2.0',
+        id: id || null,
+        error: {
+          code: error.code || -32603,
+          message: error.message || 'Internal error',
+          data: { batchIndex }
+        }
+      };
+    }
+  }
+
+  /**
+   * Get batch statistics
+   * @param {Array} batch 
+   * @returns {Object}
+   */
+  getBatchStats(batch) {
+    const notifications = batch.filter(req => req.id === undefined || req.id === null).length;
+    const requests = batch.length - notifications;
+    const methods = [...new Set(batch.map(req => req.method))];
+    
+    return {
+      total: batch.length,
+      requests,
+      notifications,
+      uniqueMethods: methods.length,
+      methods
+    };
+  }
+}
+
+module.exports = BatchHandler;