rpc-express-toolkit 3.0.1 → 4.0.0

package/README.md

@@ -2,1071 +2,70 @@
 
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)
-<!-- [![Build Status](https://github.com/n-car/rpc-express-toolkit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/n-car/rpc-express-toolkit/actions/workflows/ci.yml) -->
-<!-- [![Coverage Status](https://coveralls.io/repos/github/n-car/rpc-express-toolkit/badge.svg?branch=main)](https://coveralls.io/github/n-car/rpc-express-toolkit?branch=main) -->
 
-An enterprise-ready JSON-RPC 2.0 toolkit for Express.js applications with simplified APIs, structured logging, middleware system, schema validation, batch processing, and comprehensive BigInt/Date serialization support.
+Enterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, middleware, schema validation, batch support, and optional safe type disambiguation.
 
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Advanced Usage](#advanced-usage)
-  - [Configuration Options](#configuration-options)
-  - [Schema Validation](#schema-validation)
-  - [Middleware System](#middleware-system)
-  - [Batch Requests](#batch-requests)
-  - [Structured Logging](#structured-logging)
-  - [Built-in Middlewares](#built-in-middlewares)
-- [API Reference](#api-reference)
-- [Examples](#examples)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Features
-
-### Core Features
-- **JSON-RPC 2.0 Compliance:** Fully adheres to the JSON-RPC 2.0 specification
-- **Server & Client Support:** Provides both server endpoint and client classes
-- **Asynchronous Support:** Handle asynchronous operations seamlessly with Promises
-- **BigInt & Date Serialization:** Robust serialization/deserialization with timezone support
-- **Cross-Platform:** Works in both browser and Node.js environments
-- **Error Handling:** Comprehensive error responses with sanitization options
-
-### Enterprise Features
-- **🔧 Structured Logging:** Configurable logging with multiple transports and levels
-- **⚡ Middleware System:** Extensible middleware with built-in rate limiting, CORS, auth
-- **✅ Schema Validation:** JSON Schema validation with Ajv and schema builder utilities
-- **📦 Batch Processing:** Efficient batch request handling with concurrent processing
-- **📊 Health & Metrics:** Built-in health checks and metrics endpoints
-- **🔒 Security:** Method whitelisting, authentication, and error sanitization
-- **🎯 Performance:** Request timing, caching support, and optimized serialization
+## Quick Start
 
-## Installation
+### Installation
 
 ```bash
 npm install rpc-express-toolkit
-```
-
-Or using yarn:
-
-```bash
+# or
 yarn add rpc-express-toolkit
 ```
 
-**Note:** For Node.js environments older than v18, you may need to install `node-fetch` for HTTP requests:
-
-## Quick Start
-
-### Basic Setup
+### Server
 
 ```javascript
 const express = require('express');
 const { RpcEndpoint } = require('rpc-express-toolkit');
 
 const app = express();
-// Configure JSON middleware yourself
-app.use(express.json());
+app.use(express.json()); // required
 
-// Context object to pass to method handlers
-const context = { database: db, config: config };
+const context = { database: db, config };
 
-// Create JSON-RPC server (validates JSON middleware compatibility)
 const rpc = new RpcEndpoint(app, context);
-
-// Add simple methods
-rpc.addMethod('add', (req, ctx, params) => {
-    const { a, b } = params;
-    return a + b;
-});
-
-rpc.addMethod('getUser', async (req, ctx, params) => {
-    const { userId } = params;
-    const user = await ctx.database.users.findById(userId);
-    return user;
-});
-
-app.listen(3000, () => {
-    console.log('Server running on port 3000');
-});
-```
-
-
-### Client Usage
-
-```javascript
-const { RpcClient } = require('rpc-express-toolkit');
-
-// Node.js client
-const client = new RpcClient('http://localhost:3000/api');
-
-// Make RPC calls
-const result = await client.call('add', { a: 5, b: 3 });
-console.log(result); // 8
-
-// Browser client (include the client script)
-const client = new RpcClient('/api');
-const user = await client.call('getUser', { userId: 123 });
-```
-
-
-#### ⚠️ SSL and self-signed certificates in development (Node.js)
-
-If you need to connect to a server with a self-signed certificate during development, set the following environment variable **before** starting your Node.js process:
-
-```js
-process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-```
-
-**Warning:**
-- This disables SSL certificate validation for all HTTPS requests in the Node.js process.
-- Use this only in development environments!
-- Never commit or enable this setting in production.
-
-Advanced options like `agent` and `ca` have been removed for simplicity and compatibility with modern Node.js. This is the only universal and reliable way to bypass SSL validation for development with self-signed certificates.
-
-## Advanced Usage
-
-### Configuration Options
-
-```javascript
-const rpc = new RpcEndpoint(app, context, {
-    endpoint: '/api',
-    
-    // Logging configuration
-    logging: {
-        level: 'info',
-        format: 'json',
-        transports: ['console', 'file'],
-        file: {
-            filename: 'rpc.log',
-            maxsize: 10485760, // 10MB
-            maxFiles: 5
-        }
-    },
-    
-    // Built-in middleware
-    cors: {
-        origin: ['http://localhost:3000'],
-        credentials: true
-    },
-    
-    rateLimit: {
-        windowMs: 15 * 60 * 1000, // 15 minutes
-        max: 100 // limit each IP to 100 requests per windowMs
-    },
-    
-    auth: {
-        required: true,
-        verify: (req) => {
-            const token = req.headers.authorization;
-            return verifyToken(token);
-        }
-    },
-    
-    methodWhitelist: ['add', 'subtract', 'getUser'],
-    
-    // Schema validation
-    validation: {
-        strict: true,
-        coerceTypes: true,
-        removeAdditional: true
-    },
-    
-    // Safe serialization options
-    safeStringEnabled: true,    // Add 'S:' prefix to strings (default: true)
-    safeDateEnabled: true,      // Add 'D:' prefix to dates (default: true)
-    warnOnUnsafeString: true,   // Warn when BigInt found with safeStringEnabled=false (default: true)
-    warnOnUnsafeDate: true,     // Warn when Date found with safeDateEnabled=false (default: true)
-    
-    // Other middleware options
-    cors: true,
-    rateLimit: { windowMs: 15 * 60 * 1000, max: 100 },
-    jsonOptions: {              // Options to pass to express.json()
-        limit: '10mb',          // Body size limit (default: uses maxBodySize)
-        strict: true,           // Only parse arrays and objects
-        type: 'application/json' // Content-Type to parse
-    },
-    warnOnUnsafeDate: true,     // Warn when Date found with safeDateEnabled=false (default: true)
-    
-    // Feature flags
-    healthCheck: true,
-    metrics: true,
-    timing: true
-});
-```
-
-### Schema Validation
-
-```javascript
-const { SchemaBuilder, commonSchemas } = require('rpc-express-toolkit');
-
-// Using schema builder
-const addSchema = SchemaBuilder.object({
-    a: SchemaBuilder.number().required(),
-    b: SchemaBuilder.number().required()
-});
-
-// Register method with schema
-rpc.addMethod('add', {
-    handler: (req, ctx, params) => params.a + params.b,
-    schema: addSchema
-});
-
-// Using common schemas
-rpc.addMethod('getUser', {
-    handler: async (req, ctx, params) => {
-        return await ctx.database.users.findById(params.userId);
-    },
-    schema: {
-        type: 'object',
-        properties: {
-            userId: commonSchemas.positiveInteger
-        },
-        required: ['userId']
-    }
-});
-```
-
-### Middleware System
-
-**JSON Middleware Validation**
-
-RpcEndpoint validates that your Express router can handle JSON parsing properly:
-
-```javascript
-const express = require('express');
-const { RpcEndpoint } = require('rpc-express-toolkit');
-
-const app = express();
-app.use(express.json()); // You must configure JSON middleware
-
-try {
-  // RpcEndpoint validates JSON middleware compatibility during construction
-  const rpc = new RpcEndpoint(app, context);
-  console.log('✅ JSON middleware validation passed');
-} catch (error) {
-  console.error('❌ JSON middleware validation failed:', error.message);
-  // This router cannot handle JSON-RPC requests properly.
-}
-```
-
-**Benefits of JSON Middleware Validation:**
-
-- 🛡️ **Early Error Detection**: Catches JSON parsing issues at startup, not runtime
-- 🎯 **Express Version Compatibility**: Ensures Express ≥4.16.0 for `express.json()` support
-- 📋 **Clear Error Messages**: Provides specific solutions for configuration problems
-- 🔍 **Debug Information**: Logs validation status for troubleshooting
-
-**JSON Middleware Validation:**
-
-The system validates JSON middleware functionality during RpcEndpoint construction:
-
-**Customizing JSON Options:**
-```javascript
-const rpc = new RpcEndpoint(app, context, {
-    endpoint: '/api',
-    jsonOptions: {
-        limit: '50mb',           // Increase body size limit
-        strict: false,           // Allow non-objects/arrays
-        type: ['application/json', 'text/plain'] // Accept multiple content types
-    }
-});
-```
-
-**Common JSON Validation Errors:**
-
-```javascript
-// Error: Express version too old
-// Solution: Update Express to ≥4.16.0
-npm install express@latest
-
-// Error: No JSON middleware configured
-// Solution: Add JSON middleware to your router
-app.use(express.json());
-
-// Error: body-parser required for older Express
-// Solution: Install and configure body-parser
-npm install body-parser
-app.use(require('body-parser').json());
-```
-
-## API Reference
-
-### RpcEndpoint Class
-
-#### Constructor
-
-```javascript
-new RpcEndpoint(router, context, options)
-```
-
-**Parameters:**
-- `router` (Express.Router): Express router instance
-- `context` (Object): Context object passed to method handlers
-- `options` (Object|string): Configuration options or endpoint path
-
-**Options:**
-- `endpoint` (string): Endpoint path (default: '/api')
-- `logging` (Object): Logging configuration
-- `cors` (Object): CORS configuration  
-- `rateLimit` (Object): Rate limiting configuration
-- `auth` (Object): Authentication configuration
-- `methodWhitelist` (Array): Allowed method names
-- `validation` (Object): Schema validation options
-- `healthCheck` (boolean): Enable health check endpoint
-- `metrics` (boolean): Enable metrics endpoint
-- `timing` (boolean): Enable request timing
-
-#### Methods
-
-##### `addMethod(name, handlerOrConfig, schema)`
-
-Register a new JSON-RPC method.
-
-```javascript
-// Simple method
-rpc.addMethod('add', (req, ctx, params) => {
-    return params.a + params.b;
-});
-
-// Method with schema validation
-rpc.addMethod('getUser', {
-    handler: async (req, ctx, params) => {
-        return await ctx.db.users.findById(params.userId);
-    },
-    schema: {
-        type: 'object',
-        properties: {
-            userId: { type: 'number', minimum: 1 }
-        },
-        required: ['userId']
-    }
-});
-```
-
-##### `use(hook, middleware)`
-
-Add middleware for specific execution hooks.
-
-```javascript
-rpc.use('beforeCall', async (context) => {
-    // Pre-processing
-    return context;
-});
-
-rpc.use('afterCall', async (context) => {
-    // Post-processing
-    return context;
-});
-
-rpc.use('onError', async (context) => {
-    // Error handling
-});
-```
-
-##### `removeMethod(name)`
-
-Remove a registered method.
-
-```javascript
-rpc.removeMethod('methodName');
-```
-
-##### `getMethod(name)`
-
-Get method configuration.
-
-```javascript
-const config = rpc.getMethod('methodName');
-```
-
-##### `listMethods()`
-
-List all registered methods.
-
-```javascript
-const methods = rpc.listMethods();
-```
-
-##### `getMetrics()`
-
-Get current metrics data.
-
-```javascript
-const metrics = rpc.getMetrics();
-```
-
-#### Properties
-
-- `endpoint`: The endpoint path
-- `methods`: All registered methods
-- `logger`: Logger instance
-- `middleware`: Middleware manager
-- `validator`: Schema validator
-
-### RpcClient Class
-
-#### Constructor
-
-```javascript
-new RpcClient(baseUrl, options)
-```
-
-#### Methods
-
-
-##### `call(method, params, options)`
-
-Make a single RPC call.
-
-```javascript
-// If the method does not require parameters, you can omit the params argument:
-const result = await client.call('ping');
-
-// If you pass params as undefined or null, the field will be omitted from the JSON-RPC payload (per spec):
-await client.call('ping', undefined);
-await client.call('ping', null);
-
-// If you pass an object or array, it will be sent as params:
-await client.call('add', { a: 1, b: 2 });
-```
-
-> **Note:**
-> The `params` field is omitted from the JSON-RPC request if you pass `undefined` or `null`, as required by the JSON-RPC 2.0 specification. If you pass an object or array, it will be included as `params`.
-
-##### `batch(requests)`
-
-Make batch RPC calls.
-
-```javascript
-const results = await client.batch([
-    { method: 'add', params: { a: 1, b: 2 } },
-    { method: 'subtract', params: { a: 5, b: 3 } }
-]);
-```
-
-##### `notify(method, params)`
-
-Send notification (no response expected).
-
-```javascript
-await client.notify('logEvent', { event: 'user_login' });
-```
-
-### Logger Class
-
-Structured logging with configurable transports and levels.
-
-```javascript
-const logger = new Logger({
-    level: 'info',
-    format: 'json',
-    transports: ['console', 'file']
-});
-
-logger.info('Message', { key: 'value' });
-logger.error('Error', { error: err.message });
-```
-
-### SchemaValidator Class
-
-JSON Schema validation with Ajv.
-
-```javascript
-const validator = new SchemaValidator({
-    strict: true,
-    coerceTypes: true
-});
-
-const result = validator.validate(data, schema);
-```
-
-### SchemaBuilder
-
-Utility for building JSON schemas.
-
-```javascript
-const schema = SchemaBuilder.object({
-    name: SchemaBuilder.string().required(),
-    age: SchemaBuilder.number().min(0).max(150),
-    email: SchemaBuilder.string().format('email')
-});
-```
-
-### BatchHandler
-
-Handles batch request processing with concurrency control.
-
-```javascript
-const batchHandler = new BatchHandler(endpoint, {
-    maxConcurrency: 10,
-    timeout: 30000
-});
-```
-
-## Examples
-
-### Enterprise Configuration
-
-```javascript
-const express = require('express');
-const { RpcEndpoint, SchemaBuilder } = require('rpc-express-toolkit');
-
-const app = express();
-app.use(express.json());
-
-const rpc = new RpcEndpoint(app, { db, config }, {
-    endpoint: '/api/v1',
-    logging: {
-        level: 'info',
-        format: 'json',
-        transports: ['console', 'file'],
-        file: { filename: 'api.log' }
-    },
-    cors: {
-        origin: process.env.ALLOWED_ORIGINS?.split(',') || ['http://localhost:3000'],
-        credentials: true
-    },
-    rateLimit: {
-        windowMs: 15 * 60 * 1000,
-        max: 100
-    },
-    auth: {
-        required: true,
-        verify: async (req) => {
-            const token = req.headers.authorization?.replace('Bearer ', '');
-            return await verifyJWT(token);
-        }
-    },
-    validation: {
-        strict: true,
-        coerceTypes: true
-    },
-    healthCheck: true,
-    metrics: true
-});
-
-// Add methods with validation
-rpc.addMethod('createUser', {
-    handler: async (req, ctx, params) => {
-        const user = await ctx.db.users.create(params);
-        return { id: user.id, message: 'User created successfully' };
-    },
-    schema: SchemaBuilder.object({
-        name: SchemaBuilder.string().min(1).max(100).required(),
-        email: SchemaBuilder.string().format('email').required(),
-        age: SchemaBuilder.number().min(0).max(150).optional()
-    })
-});
+rpc.addMethod('add', (req, ctx, params) => params.a + params.b);
 
 app.listen(3000);
 ```
 
-### BigInt and Date Handling
+### Client
 
 ```javascript
-// BigInt serialization
-rpc.addMethod('getBigNumber', () => {
-    return BigInt('9007199254740991123456789'); // Automatically serialized to string
-});
-
-// Date serialization  
-rpc.addMethod('getCurrentTime', () => {
-    return new Date(); // Automatically serialized to ISO string
-});
-
-// Client receives properly typed data
-const client = new RpcClient('http://localhost:3000/api');
-const bigNum = await client.call('getBigNumber'); // Returns BigInt
-const date = await client.call('getCurrentTime'); // Returns Date object
-```
-
-### Handling Numeric Strings with Leading Zeros
-
-When working with numeric strings that need to preserve leading zeros (like IDs, codes, or references), be aware of BigInt auto-conversion behavior:
-
-```javascript
-// ✅ CORRECT: Numeric strings without 'n' suffix are preserved
-await client.call('processCode', { code: '0123456' }); 
-// → Server receives: '0123456' (string)
-// → Client receives: '0123456' (string) ✅
-
-// ❌ POTENTIAL ISSUE: Strings ending with 'n' are converted to BigInt
-await client.call('processRef', { ref: '012312031203120301230123123n' });
-// → Server receives: '012312031203120301230123123n' (string)  
-// → Client receives: 12312031203120301230123123n (BigInt, leading zero lost!) ❌
-
-// ✅ SOLUTIONS for strings that should remain strings:
-
-// Solution 1: Use schema validation to force string type
-rpc.addMethod('processRef', (req, ctx, params) => {
-    // params.ref will always be a string due to schema validation
-    return { processed: params.ref };
-}, {
-    type: 'object',
-    properties: {
-        ref: { type: 'string' }  // Forces string type, prevents BigInt conversion
-    }
-});
-
-// Solution 2: Use escape prefix for problematic strings
-await client.call('processRef', { ref: 'S:012312031203120301230123123n' });
-// Server strips prefix: const actualRef = params.ref.replace(/^S:/, '');
-
-// Solution 3: Use different suffix
-await client.call('processRef', { ref: '012312031203120301230123123_id' });
-// → Remains string: '012312031203120301230123123_id' ✅
-```
-
-**Note:** Only strings explicitly ending with 'n' and containing only digits are auto-converted to BigInt. This preserves leading zeros for most numeric strings while maintaining BigInt functionality for intentional use.
-
-### Safe Serialization with Prefixes
-
-The toolkit provides safe serialization options to prevent confusion between strings, BigInt values, and dates:
-
-```javascript
-// Enable safe serialization (default: true for both)
-const rpc = new RpcEndpoint(app, context, {
-    safeStringEnabled: true,  // Strings get 'S:' prefix
-    safeDateEnabled: true     // Dates get 'D:' prefix
-});
-
-// Example serialization with safe options enabled:
-rpc.addMethod('getComplexData', () => {
-    return {
-        message: "Hello World",              // → "S:Hello World"
-        timestamp: new Date(),               // → "D:2023-06-15T10:30:00.000Z"
-        count: 42n,                         // → "42n"
-        value: 123                          // → 123 (unchanged)
-    };
-});
-
-// Client automatically deserializes based on server headers:
-const client = new RpcClient('http://localhost:3000/api');
-const result = await client.call('getComplexData');
-// result.message: "Hello World" (string, prefix removed)
-// result.timestamp: Date object
-// result.count: 42n (BigInt)
-// result.value: 123 (number)
-```
-
-#### Cross-Configuration Support
-
-Client and server can have different safe options - they communicate automatically via HTTP headers:
-
-```javascript
-// Server with safe dates disabled
-const rpc = new RpcEndpoint(app, context, {
-    safeStringEnabled: true,   // S: prefix for strings
-    safeDateEnabled: false     // No prefix for dates
-});
-
-// Client with safe dates enabled  
-const client = new RpcClient('http://localhost:3000/api', {
-    safeStringEnabled: true,   // S: prefix for strings
-    safeDateEnabled: true      // D: prefix for dates
-});
-
-// Data flows correctly despite different configurations:
-// Client sends: { date: "D:2023-01-01T00:00:00.000Z" }
-// Server receives: Date object (auto-deserialized using client's headers)
-// Server responds: { date: "2023-01-01T00:00:00.000Z" } (no prefix, per server config)
-// Client receives: Date object (auto-deserialized using server's headers)
-```
-
-#### Benefits of Safe Prefixes
-
-- **Prevents ambiguity:** `"123n"` vs `"S:123n"` (string) vs `123n` (BigInt)
-- **Cross-configuration:** Different client/server settings work seamlessly
-- **Compact:** Short prefixes (`S:`, `D:`) minimize payload overhead
-- **Automatic:** No manual intervention required, handled by headers
-- **Backward compatible:** Can be disabled if needed
-
-### Disabling Serialization Warnings
-
-When safe options are disabled (`safeStringEnabled: false` or `safeDateEnabled: false`), the toolkit warns about potential data type confusion. You can disable these warnings to reduce console noise:
-
-```javascript
-// Disable all serialization warnings
-const rpc = new RpcEndpoint(app, context, {
-    safeStringEnabled: false,      // Disable safe strings
-    safeDateEnabled: false,        // Disable safe dates
-    warnOnUnsafeString: false,     // Disable BigInt warnings
-    warnOnUnsafeDate: false        // Disable Date warnings
-});
-
-// Disable only specific warnings
-const rpc = new RpcEndpoint(app, context, {
-    safeStringEnabled: false,      // Still disabled
-    safeDateEnabled: false,        // Still disabled  
-    warnOnUnsafeString: false,     // No BigInt warnings
-    warnOnUnsafeDate: true         // Keep Date warnings
-});
-
-// Client also supports warning options
-const client = new RpcClient('http://localhost:3000/api', {
-    safeStringEnabled: false,
-    warnOnUnsafeString: false      // Disable client-side warnings
-});
-```
-
-**Warning types:**
-- `warnOnUnsafeString`: Warns when BigInt values are serialized without `safeStringEnabled`
-- `warnOnUnsafeDate`: Warns when Date values are serialized without `safeDateEnabled`
-
-**Use cases for disabling warnings:**
-- Production environments where warnings would clutter logs
-- Legacy applications that intentionally use unsafe serialization
-- Bulk data processing where performance is critical
-
-### Error Handling
-
-```javascript
-rpc.addMethod('mayFail', (req, ctx, params) => {
-    if (params.shouldFail) {
-        const error = new Error('Something went wrong');
-        error.code = -32001; // Custom error code
-        error.data = { details: 'Additional error info' };
-        throw error;
-    }
-    return 'success';
-});
-
-// Client error handling
-try {
-    await client.call('mayFail', { shouldFail: true });
-} catch (error) {
-    console.log(error.code); // -32001
-    console.log(error.message); // 'Something went wrong'
-    console.log(error.data); // { details: 'Additional error info' }
-}
-``` 
-    userId: 123, 
-    action: 'login',
-    ip: req.ip 
-});
-
-logger.error('Database error', { 
-    error: err.message,
-    query: 'SELECT * FROM users',
-    duration: 150 
-});
-
-// RPC calls are automatically logged
-// [2024-01-01T10:00:00.000Z] INFO: RPC call - {"method":"getUser","params":{"userId":123},"id":"req-123","ip":"192.168.1.1"}
-// [2024-01-01T10:00:00.050Z] INFO: RPC success - {"method":"getUser","id":"req-123","duration":50,"resultSize":245}
-```
-
-### Client Configuration
-
-The `RpcClient` supports various configuration options for different environments, **inclusa la gestione di certificati self-signed**:
-
-```javascript
-const fs = require('fs');
 const { RpcClient } = require('rpc-express-toolkit');
-
-// Basic client
-const client = new RpcClient('https://api.example.com/rpc');
-
-// Client con header personalizzati
-const clientWithHeaders = new RpcClient('https://api.example.com/rpc', {
-    'Authorization': 'Bearer your-token',
-    'X-API-Key': 'your-api-key',
-    'User-Agent': 'MyApp/1.0'
-});
-
-// Development client with self-signed certificate (accepts any certificate, DO NOT use in production)
-const devClient = new RpcClient('https://localhost:3000/api', {
-    'Authorization': 'Bearer dev-token'
-}, {
-    rejectUnauthorized: false // Development only!
-});
-
-// Development client with custom self-signed CA (safer: accepts only your CA)
-const ca = fs.readFileSync('path/to/your/selfsigned-ca.pem');
-const devClientWithCA = new RpcClient('https://localhost:3000/api', {
-    'Authorization': 'Bearer dev-token'
-}, {
-    ca // Pass your self-signed CA certificate
-    // or: agent: new require('https').Agent({ ca, rejectUnauthorized: true })
-});
-```  
-
-```
-
-**⚠️ Security Warning**: Use `rejectUnauthorized: false` for development only. For better security, always prefer the `ca` solution to accept only your self-signed CA. In production always use valid certificates signed by a trusted CA.
-
-### Built-in Middlewares
-
-```javascript
-const { builtInMiddlewares } = require('rpc-express-toolkit');
-
-// Rate limiting
-rpc.use('beforeCall', builtInMiddlewares.rateLimit({
-    windowMs: 15 * 60 * 1000, // 15 minutes
-    max: 100, // limit each IP to 100 requests per windowMs
-    message: 'Too many requests from this IP'
-}));
-
-// CORS
-rpc.use('beforeCall', builtInMiddlewares.cors({
-    origin: ['http://localhost:3000', 'https://myapp.com'],
-    credentials: true,
-    methods: ['POST']
-}));
-
-// Authentication
-rpc.use('beforeCall', builtInMiddlewares.auth({
-    required: true,
-    verify: async (req) => {
-        const token = req.headers.authorization?.replace('Bearer ', '');
-        return await verifyJWT(token);
-    },
-    onError: (req, error) => {
-        console.log('Auth failed:', error.message);
-    }
-}));
-
-// Method whitelisting
-rpc.use('beforeCall', builtInMiddlewares.methodWhitelist([
-    'add', 'subtract', 'getUser', 'updateUser'
-]));
-
-// Request timing
-rpc.use('beforeCall', builtInMiddlewares.timing());
-```  
-```
-
-// 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;
-}
-
-// Start the server
-const PORT = process.env.PORT || 3000;
-app.listen(PORT, () => {
-    console.log(`Server is running on port ${PORT}`);
-});
-```
-
-### Adding Methods
-
-You can add RPC methods using the `addMethod` function. Each method receives the `context` and `params` as arguments.
-
-```javascript
-// Synchronous method
-rpc.addMethod('multiply', (req, ctx, params) => {
-    const { a, b } = params;
-    return a * b;
-});
-
-// Asynchronous method
-rpc.addMethod('divide', async (req, ctx, params) => {
-    const { a, b } = params;
-    if (b === 0) {
-        throw new Error('Division by zero');
-    }
-    // Simulate async operation
-    return Promise.resolve(a / b);
-});
-```
-
-## API
-
-### RpcEndpoint Class
-
-A class to handle JSON-RPC 2.0 requests in Express.js applications.
-
-#### Constructor
-
-```javascript
-new RpcEndpoint(router, context, endpoint = '/api')
-```
-
-- **router**: *(Express.Router)* - The Express router to attach the endpoint to.
-- **context**: *(Object)* - The context object to pass to the method handlers.
-- **endpoint** *(optional)*: *(string)* - The endpoint path (default is `/api`).
-
-#### addMethod
-
-```javascript
-addMethod(name, handler)
-```
-
-- **name**: *(string)* - The name of the RPC method.
-- **handler**: *(Function)* - The function that handles the method. Receives `req` (the Request object) `context` and `params` as arguments.
-
-  ```javascript
-  (req, context, params) => { /* ... */ }
-  ```
-
-#### Properties
-
-- **endpoint**: *(string)* - Returns the endpoint path.
-- **methods**: *(Object)* - Returns the registered methods.
-
-#### reply
-
-```javascript
-reply(res, { id, result, error })
-```
-
-- **res**: *(Express.Response)* - The Express response object.
-- **responsePayload**: *(Object)* - The JSON-RPC response payload.
-
-  ```javascript
-  {
-      id: string | number | null,
-      result: any,
-      error: {
-          code: number,
-          message: string,
-          data?: any
-      }
-  }
-  ```
-
-#### serializeBigInts
-
-```javascript
-serializeBigInts(value)
+const client = new RpcClient('http://localhost:3000/api');
+const sum = await client.call('add', { a: 1, b: 2 });
 ```
 
-- **value**: *(any)* - The value to serialize.
-- **returns**: *(any)* - The serialized value with `BigInt` converted to strings.
-
-Recursively converts `BigInt` values to strings to ensure JSON serialization compatibility.
-
-## Examples
-
-Check out the [examples](./examples) directory for more usage examples.
-
-### Example: Complete Express Server Integration
+### Safe Type Disambiguation (optional)
 
-```javascript
-const express = require('express');
-const { RpcEndpoint } = require('rpc-express-toolkit');
+Safe type disambiguation is **disabled by default** for maximum JSON-RPC 2.0 compatibility. The library will show educational warnings when you use BigInt or Date values, helping you understand when these types need special handling. Enable safe serialization with `safeEnabled: true` to add safe prefixes (`S:` for strings, `D:` for dates), or suppress warnings with `warnOnUnsafe: false`. See `README_ADVANCED.md#safe-serialization` for full details and best practices.
 
-const app = express();
+## Minimal API
 
-app.use(express.json());
+- `new RpcEndpoint(router, context, options?)` — create and attach a JSON-RPC endpoint.  
+- `rpc.addMethod(name, handlerOrConfig)` — register a method.  
+- `new RpcClient(baseUrl, headers?, options?)` — client for making calls.  
+- `client.call(method, params?)` — single call.  
+- `client.batch([...])` — batch.  
+- `client.notify(method, params?)` — notification.
 
-const context = { user: 'admin' };
+## Full Details
 
-// 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', () => {
-    return new Date().toISOString();
-});
-
-const PORT = 3000;
-app.listen(PORT, () => {
-    console.log(`Server listening on port ${PORT}`);
-});
-```
+For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-### Development Setup
-
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/yourusername/rpc-express-toolkit.git`
-3. Install dependencies: `npm install`
-4. Run tests: `npm test`
-5. Run linting: `npm run lint`
-
-### Running Tests
-
 ```bash
-npm test                 # Run all tests
-npm run test:watch      # Run tests in watch mode
-npm run test:coverage   # Run tests with coverage report
+git clone https://github.com/n-car/rpc-express-toolkit.git
+npm install
+npm test
+npm run lint
 ```
 
-### Code Style
-
-This project uses ESLint and Prettier for code formatting. Run `npm run lint` to check code style.
-
-## Security
-
-### Best Practices
-
-- Always validate input parameters using schema validation
-- Use authentication middleware for sensitive operations
-- Enable rate limiting to prevent abuse
-- Sanitize error messages in production environments
-- Use HTTPS in production
-- Implement proper logging for audit trails
-
-## Performance
-
-### Optimization Tips
-
-- Use batch requests for multiple operations
-- Implement caching where appropriate
-- Use connection pooling for database operations
-- Monitor metrics and logs for performance bottlenecks
-- Use clustering for high-load applications
-
-### Benchmarks
-
-Performance benchmarks on a typical server setup:
-
-- Single request: ~1-2ms overhead
-- Batch request (10 items): ~5-10ms total
-- Memory usage: ~50MB for 10,000 concurrent connections
-- Throughput: ~5,000 requests/second
-
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Changelog
-
-### v2.0.0 (Enterprise Edition)
-
-- ✨ **BREAKING**: Clean API with `RpcEndpoint` and `RpcClient` classes (100% backward compatible)
-- ✨ **BREAKING**: Renamed package to `rpc-express-toolkit` for better clarity
-- ✨ Added structured logging with configurable transports
-- ✨ Implemented middleware system with built-in middlewares
-- ✨ Added schema validation with Ajv and schema builder
-- ✨ Implemented batch request processing
-- ✨ Added health check and metrics endpoints
-- ✨ Enhanced BigInt/Date serialization with timezone support
-- ✨ Added authentication and authorization middleware
-- ✨ Implemented rate limiting and CORS support
-- ✨ Added method whitelisting and security features
-- ✨ Clean API: `RpcEndpoint`/`RpcClient` classes
-- 🔧 Improved error handling and sanitization
-- 🔧 Enhanced client with batch and notification support
-- 🔧 Added comprehensive test coverage
-- 📚 Updated documentation with enterprise features
-
-## Support
-
-- 📖 [Documentation](https://github.com/n-car/rpc-express-toolkit/wiki)
-- 🐛 [Issue Tracker](https://github.com/n-car/rpc-express-toolkit/issues)
-- 💬 [Discussions](https://github.com/n-car/rpc-express-toolkit/discussions)
-
-## Acknowledgments
-
-- JSON-RPC 2.0 Specification
-- Express.js community
-- Ajv JSON Schema validator
-- All contributors and users
-
----
-
-Made with ❤️ by n-car
+MIT. See [LICENSE](LICENSE).