rpc-express-toolkit 4.2.1 → 4.3.2

package/src/index.js

@@ -1,1035 +1,1153 @@
-const path = require('path');
-const express = require('express');
-const expressPkg = require('express/package.json');
-const NestedError = require('nested-error-stacks');
-const pkg = require('../package.json');
-
-/** @typedef {import("express").Router} Router */
-/** @typedef {import("express").Request} Request */
-/** @typedef {import("express").Response} Response */
-
-const Logger = require('./logger');
-const { MiddlewareManager, builtInMiddlewares } = require('./middleware');
-const {
-  SchemaValidator,
-  commonSchemas,
-  SchemaBuilder,
-} = require('./validation');
-const BatchHandler = require('./batch');
-
-/**
- * Default properties to include in error serialization.
- * @type {Array<string>}
- */
-const defaultProperties = [
-  'stackTraceLimit',
-  'cause',
-  'code',
-  'message',
-  'stack',
-  'address',
-  'dest',
-  'errno',
-  'info',
-  'path',
-  'port',
-  'syscall',
-  'opensslErrorStack',
-  'function',
-  'library',
-  'reason',
-];
-
-/**
- * Serializes an error into a JSON-compatible format, with optional sanitization.
- * @param {Error | NestedError | Object} error - The error to serialize.
- * @param {boolean} sanitize - Whether to remove sensitive fields.
- * @param {Array<string>} properties - Properties to include in serialization.
- * @returns {Object} The serialized error.
- */
-const serializeError = (
-  error,
-  sanitize = false,
-  properties = defaultProperties
-) => {
-  if (error === null || error === undefined) return error;
-
-  const result = {};
-  const includeProperties = sanitize
-    ? properties.filter((prop) => !['address', 'path'].includes(prop))
-    : properties;
-
-  includeProperties.forEach((prop) => {
-    if (error?.[prop] !== undefined) {
-      result[prop] = error[prop];
-    }
-  });
-
-  if (error instanceof NestedError) {
-    result.type = 'NestedError';
-    if (error.nested)
-      result.nested = serializeError(error.nested, sanitize, properties);
-  } else if (error instanceof Error) {
-    result.type = 'Error';
-  } else if (error instanceof Object) {
-    result.type = 'Object';
-    Object.assign(result, error);
-  } else {
-    result.type = 'Default';
-    result.instance = error;
-  }
-
-  return result;
-};
-
-/**
- * @template C
- */
-class RpcEndpoint {
-  /**
-   * Serve client scripts for making JSON-RPC calls from the browser.
-   * @param {Router} router Express.Router instance
-   * @param {string} [url="/vendor/rpc-client"]
-   *    The path from which client scripts will be served.
-   */
-  static serveScripts(router, url = '/vendor/rpc-client') {
-    router.use(url, express.static(path.join(__dirname, 'clients')));
-  }
-
-  /** @type {string} */
-  #endpoint;
-
-  /** @type {{ [name: string]: any }} */
-  #methods = {};
-
-  /** @type {string} */
-  #introspectionPrefix = '__rpc';
-
-  /** @type {boolean} */
-  #isInternalRegistration = false;
-
-  /** @type {Logger} */
-  #logger;
-
-  /** @type {MiddlewareManager} */
-  #middleware;
-
-  /** @type {SchemaValidator} */
-  #validator;
-
-  /** @type {BatchHandler} */
-  #batchHandler;
-
-  /** @type {Object} */
-  #options;
-
-  /**
-   * @param {Router} router The Express router to attach the endpoint to.
-   * @param {C} context The context object to pass to the method handlers.
-   * @param {string|Object} [endpointOrOptions="/api"] The endpoint path or options object.
-   * @param {Object} [options={}] Options object if first param is string.
-   */
-  constructor(router, context, endpointOrOptions = '/api', options = {}) {
-    // Handle both signatures: (router, context, "/api", options) and (router, context, options)
-    if (typeof endpointOrOptions === 'string') {
-      this.#endpoint = endpointOrOptions;
-      this.#options = { ...options };
-    } else {
-      this.#endpoint = endpointOrOptions.endpoint || '/api';
-      this.#options = { ...endpointOrOptions };
-    }
-
-    // Initialize components
-    this.#logger = new Logger(this.#options.logging || {});
-    this.#middleware = new MiddlewareManager();
-    this.#validator = new SchemaValidator(this.#options.validation || {});
-    this.#batchHandler = new BatchHandler(this);
-
-    // Set default options
-    this.#options.safeEnabled = this.#options.safeEnabled === true; // Default false
-    this.#options.warnOnUnsafe = this.#options.warnOnUnsafe !== false; // Default true
-    this.#options.strictMode = this.#options.strictMode !== false; // Default true
-    this.#options.enableIntrospection =
-      this.#options.enableIntrospection === true; // Default false
-    this.#options.introspectionPrefix =
-      this.#options.introspectionPrefix || '__rpc'; // Default __rpc
-
-    this.#introspectionPrefix = this.#options.introspectionPrefix;
-
-    // Validate that the router can handle JSON parsing
-    this.#validateJsonMiddleware();
-
-    // Register introspection methods if enabled
-    if (this.#options.enableIntrospection) {
-      this.#registerIntrospectionMethods();
-    }
-
-    // Setup built-in middleware if configured
-    this.#setupBuiltInMiddleware();
-
-    // Wire up routes
-    this.#setupRoutes(router, context);
-  }
-
-  /**
-   * Setup built-in middleware based on options
-   */
-  #setupBuiltInMiddleware() {
-    const { rateLimit, cors, auth, timing, methodWhitelist } = this.#options;
-
-    if (timing !== false) {
-      this.use('beforeCall', builtInMiddlewares.timing());
-    }
-
-    if (cors) {
-      this.use('beforeCall', builtInMiddlewares.cors(cors));
-    }
-
-    if (rateLimit) {
-      this.use('beforeCall', builtInMiddlewares.rateLimit(rateLimit));
-    }
-
-    if (auth) {
-      this.use('beforeCall', builtInMiddlewares.auth(auth));
-    }
-
-    if (methodWhitelist && Array.isArray(methodWhitelist)) {
-      this.use(
-        'beforeCall',
-        builtInMiddlewares.methodWhitelist(methodWhitelist)
-      );
-    }
-  }
-
-  /**
-   * Register introspection methods (__rpc.*)
-   * @private
-   */
-  #registerIntrospectionMethods() {
-    this.#isInternalRegistration = true;
-
-    // __rpc.listMethods - List all user methods (excludes __rpc.* methods)
-    this.addMethod(
-      `${this.#introspectionPrefix}.listMethods`,
-      async (_req, _context, _params) =>
-        Object.keys(this.#methods).filter(
-          (name) => !name.startsWith(this.#introspectionPrefix)
-        ),
-      {
-        description: 'List all available RPC methods',
-        exposeSchema: true,
-      }
-    );
-
-    // __rpc.describe - Get schema and description of a specific method
-    this.addMethod(
-      `${this.#introspectionPrefix}.describe`,
-      async (_req, _context, params) => {
-        const methodName = params?.method;
-
-        if (!methodName || typeof methodName !== 'string') {
-          throw {
-            code: -32602,
-            message: 'Invalid params: method name required',
-          };
-        }
-
-        // Prevent introspection of __rpc.* methods
-        if (methodName.startsWith(this.#introspectionPrefix)) {
-          throw {
-            code: -32601,
-            message: 'Cannot describe introspection methods',
-          };
-        }
-
-        const methodConfig = this.#methods[methodName];
-        if (!methodConfig) {
-          throw { code: -32601, message: `Method not found: ${methodName}` };
-        }
-
-        // Check if schema is exposed
-        const config = typeof methodConfig === 'function' ? {} : methodConfig;
-        if (!config.exposeSchema) {
-          throw { code: -32601, message: 'Method schema not available' };
-        }
-
-        return {
-          name: methodName,
-          schema: config.schema || null,
-          description: config.description || '',
-        };
-      },
-      {
-        schema: {
-          type: 'object',
-          properties: {
-            method: { type: 'string' },
-          },
-          required: ['method'],
-        },
-        description: 'Get schema and description of a specific method',
-        exposeSchema: true,
-      }
-    );
-
-    // __rpc.describeAll - Get all methods with public schemas
-    this.addMethod(
-      `${this.#introspectionPrefix}.describeAll`,
-      async (_req, _context, _params) => {
-        const publicMethods = [];
-
-        for (const [name, methodConfig] of Object.entries(this.#methods)) {
-          // Skip introspection methods
-          if (name.startsWith(this.#introspectionPrefix)) continue;
-
-          const config = typeof methodConfig === 'function' ? {} : methodConfig;
-          if (config.exposeSchema) {
-            publicMethods.push({
-              name,
-              schema: config.schema || null,
-              description: config.description || '',
-            });
-          }
-        }
-
-        return publicMethods;
-      },
-      {
-        description: 'List all methods with public schemas',
-        exposeSchema: true,
-      }
-    );
-
-    // __rpc.version - Get toolkit version
-    this.addMethod(
-      `${this.#introspectionPrefix}.version`,
-      async (_req, _context, _params) => ({
-        toolkit: 'rpc-express-toolkit',
-        version: pkg.version,
-        expressVersion: expressPkg.version,
-        nodeVersion: process.version,
-      }),
-      {
-        description: 'Get RPC toolkit version information',
-        exposeSchema: true,
-      }
-    );
-
-    // __rpc.capabilities - Get server capabilities
-    this.addMethod(
-      `${this.#introspectionPrefix}.capabilities`,
-      async (_req, _context, _params) => ({
-        safeMode: this.#options.safeEnabled,
-        batch: true,
-        introspection: true,
-        introspectionPrefix: this.#introspectionPrefix,
-        validation: !!this.#options.validation,
-        cors: !!this.#options.cors,
-        auth: !!this.#options.auth,
-        rateLimit: !!this.#options.rateLimit,
-        methodCount: Object.keys(this.#methods).filter(
-          (n) => !n.startsWith(this.#introspectionPrefix)
-        ).length,
-      }),
-      {
-        description: 'Get server capabilities and configuration',
-        exposeSchema: true,
-      }
-    );
-
-    this.#isInternalRegistration = false;
-  }
-
-  /**
-   * Validate JSON middleware functionality and Express compatibility
-   * @private
-   */
-  #validateJsonMiddleware() {
-    try {
-      // Check if express.json is available (Express 4.16.0+)
-      if (typeof express.json !== 'function') {
-        throw new Error(
-          'express.json() is not available. Please ensure you are using Express 4.16.0 or later, or install body-parser separately.'
-        );
-      }
-
-      // Test JSON middleware creation with default options
-      const jsonMiddleware = express.json({ limit: '10mb' });
-
-      if (typeof jsonMiddleware !== 'function') {
-        throw new Error(
-          'express.json() did not return a valid middleware function'
-        );
-      }
-
-      // Verify middleware has correct signature (req, res, next)
-      if (jsonMiddleware.length !== 3) {
-        throw new Error(
-          'JSON middleware has invalid signature - expected (req, res, next)'
-        );
-      }
-
-      this.#logger.debug('JSON middleware validation passed', {
-        expressJsonAvailable: true,
-        middlewareValid: true,
-        endpoint: this.#endpoint,
-      });
-    } catch (error) {
-      const errorMsg =
-        `JSON middleware validation failed: ${error.message}\n` +
-        `This router cannot handle JSON-RPC requests properly.\n\n` +
-        `Possible solutions:\n` +
-        `- Update Express: npm install express@latest (requires >=4.16.0)\n` +
-        `- Add JSON parsing middleware manually: router.use(express.json())\n` +
-        `- Install body-parser: npm install body-parser`;
-
-      this.#logger.error('JSON middleware validation failed', {
-        error: error.message,
-        expressVersion: expressPkg?.version || 'unknown',
-        endpoint: this.#endpoint,
-      });
-
-      throw new Error(errorMsg);
-    }
-  }
-
-  /**
-   * Setup Express routes
-   * @param {Router} router
-   * @param {C} context
-   */
-  #setupRoutes(router, context) {
-    // Health check endpoint
-    if (this.#options.healthCheck !== false) {
-      router.get(`${this.#endpoint}/health`, (req, res) => {
-        res.json({
-          status: 'ok',
-          timestamp: new Date().toISOString(),
-          version: pkg.version,
-        });
-      });
-    }
-
-    // Metrics endpoint
-    if (this.#options.metrics) {
-      router.get(`${this.#endpoint}/metrics`, (req, res) => {
-        res.json(this.getMetrics());
-      });
-    }
-
-    // Main JSON-RPC endpoint
-    router.post(this.#endpoint, async (req, res) => {
-      const startTime = Date.now();
-
-      try {
-        // Check if it's a batch request
-        if (this.#batchHandler.isBatchRequest(req.body)) {
-          this.#logger.info('Batch request received', {
-            batchSize: req.body.length,
-            ip: req.ip,
-          });
-
-          const results = await this.#batchHandler.processBatch(
-            req.body,
-            req,
-            res,
-            context
-          );
-
-          // Only send response if there are results (non-notification requests)
-          if (results.length > 0) {
-            // Align batch responses with single-call header negotiation
-            res.setHeader(
-              'X-RPC-Safe-Enabled',
-              this.#options.safeEnabled ? 'true' : 'false'
-            );
-            res.json(results);
-          } else {
-            res.status(204).end(); // No content for all-notification batch
-          }
-
-          this.#logger.info('Batch request completed', {
-            batchSize: req.body.length,
-            responseCount: results.length,
-            duration: Date.now() - startTime,
-          });
-
-          return;
-        }
-
-        // Single request processing
-        await this.#processSingleRequest(req, res, context, startTime);
-      } catch (error) {
-        this.#logger.error('Endpoint error', {
-          error: error.message,
-          stack: error.stack,
-        });
-
-        res.json({
-          jsonrpc: '2.0',
-          id: null,
-          error: {
-            code: -32603,
-            message: 'Internal error',
-            data: serializeError(error, true),
-          },
-        });
-      }
-    });
-  }
-
-  /**
-   * Process a single JSON-RPC request
-   * @param {Request} req
-   * @param {Response} res
-   * @param {C} context
-   * @param {number} startTime
-   */
-  async #processSingleRequest(req, res, context, startTime) {
-    const { jsonrpc, method, params, id } = req.body || {};
-
-    // Log the incoming request
-    this.#logger.rpcCall(method, params, id, req);
-
-    // Validate JSON-RPC 2.0 request
-    if (jsonrpc !== '2.0') {
-      return this.reply(res, {
-        id,
-        error: {
-          code: -32600,
-          message: `Invalid Request: 'jsonrpc' must be '2.0'.`,
-        },
-      });
-    }
-
-    if (typeof method !== 'string') {
-      return this.reply(res, {
-        id,
-        error: {
-          code: -32600,
-          message: `Invalid Request: 'method' must be a string.`,
-        },
-      });
-    }
-
-    const methodConfig = this.#methods[method];
-    if (!methodConfig) {
-      return this.reply(res, {
-        id,
-        error: { code: -32601, message: `Method "${method}" not found` },
-      });
-    }
-
-    const handler =
-      typeof methodConfig === 'function' ? methodConfig : methodConfig.handler;
-    const schema =
-      typeof methodConfig === 'object' ? methodConfig.schema : null;
-
-    try {
-      // Check client's safe options from request headers
-      const clientSafeHeader = req.headers['x-rpc-safe-enabled'];
-
-      // Strict mode: se server ha safe enabled ma client non invia header → JSON-RPC ERROR
-      if (
-        this.#options.strictMode &&
-        this.#options.safeEnabled &&
-        !clientSafeHeader
-      ) {
-        return this.reply(res, {
-          id,
-          error: {
-            code: -32600, // Invalid Request
-            message:
-              'RPC Compatibility Error: Server requires safe serialization header but client did not provide it.',
-            data: {
-              serverSafeEnabled: this.#options.safeEnabled,
-              requiredHeader: 'X-RPC-Safe-Enabled',
-              strictMode: true,
-              solution:
-                'Update client to rpc-express-toolkit v4+ or disable server strict mode',
-            },
-          },
-        });
-      }
-
-      // Use client's safe options for parameter deserialization
-      const clientSafeEnabled = clientSafeHeader === 'true';
-      const deserializationOptions = {
-        safeEnabled: clientSafeEnabled,
-      };
-
-      // Deserialize parameters using client's safe options
-      const deserializedParams = params
-        ? this.deserializeBigIntsAndDates(params, deserializationOptions)
-        : params;
-
-      // Prepare middleware context
-      let middlewareContext = {
-        req,
-        res,
-        method,
-        params: deserializedParams,
-        context,
-        id,
-        startTime,
-      };
-
-      // Execute beforeCall middleware
-      middlewareContext = await this.#middleware.execute(
-        'beforeCall',
-        middlewareContext
-      );
-
-      // Validate parameters if schema is provided
-      if (schema) {
-        middlewareContext = await this.#middleware.execute(
-          'beforeValidation',
-          middlewareContext
-        );
-
-        const validation = this.#validator.validate(
-          middlewareContext.params,
-          schema
-        );
-        if (!validation.valid) {
-          const error = new Error('Validation failed');
-          error.code = -32602;
-          error.data = {
-            validationErrors: validation.errors.map((err) => ({
-              field: err.instancePath || err.schemaPath,
-              message: err.message,
-              value: err.data,
-            })),
-          };
-          throw error;
-        }
-
-        middlewareContext.params = validation.data;
-        middlewareContext = await this.#middleware.execute(
-          'afterValidation',
-          middlewareContext
-        );
-      }
-
-      // Invoke the handler
-      const result = await Promise.resolve(
-        handler(req, context, middlewareContext.params)
-      );
-
-      // Execute afterCall middleware
-      middlewareContext.result = result;
-      await this.#middleware.execute('afterCall', middlewareContext);
-
-      // Log success
-      const duration = Date.now() - startTime;
-      this.#logger.rpcSuccess(method, id, duration, result);
-
-      // Convert any BigInt/Date values before JSON-stringifying
-      const safeResult = this.serializeBigIntsAndDates(result);
-      this.reply(res, { id, result: safeResult });
-    } catch (err) {
-      const duration = Date.now() - startTime;
-      this.#logger.rpcError(method, id, duration, err);
-
-      // Execute error middleware
-      try {
-        await this.#middleware.execute('onError', {
-          req,
-          res,
-          method,
-          params,
-          context,
-          id,
-          error: err,
-          startTime,
-          duration,
-        });
-      } catch (middlewareError) {
-        this.#logger.error('Error middleware failed', {
-          error: middlewareError.message,
-        });
-      }
-
-      this.reply(res, {
-        id,
-        error: {
-          code: err.code || -32603,
-          message: err.message || `Internal error`,
-          ...(err.data && { data: err.data }),
-          error: serializeError(err, true),
-        },
-      });
-    }
-    // Ensure explicit return for consistent-return rule
-    return null;
-  }
-
-  /**
-   * Register a new JSON-RPC method.
-   * @param {string} name The method name.
-   * @param {Function|Object} handlerOrConfig The function to handle calls or config object with handler, schema, exposeSchema, description.
-   * @param {Object} [optionsOrSchema] Optional config object or schema for backward compatibility.
-   */
-  addMethod(name, handlerOrConfig, optionsOrSchema = null) {
-    // Prevent users from registering introspection methods
-    if (
-      name.startsWith(this.#introspectionPrefix) &&
-      !this.#isInternalRegistration
-    ) {
-      throw new Error(
-        `Method names starting with '${this.#introspectionPrefix}.' are reserved for RPC introspection`
-      );
-    }
-
-    let methodConfig;
-
-    if (typeof handlerOrConfig === 'function') {
-      // Function handler - optionsOrSchema can be schema (backward compat) or options object
-      if (
-        optionsOrSchema &&
-        (optionsOrSchema.schema ||
-          optionsOrSchema.exposeSchema ||
-          optionsOrSchema.description)
-      ) {
-        // New format: options object
-        methodConfig = {
-          handler: handlerOrConfig,
-          ...optionsOrSchema,
-        };
-      } else if (optionsOrSchema) {
-        // Old format: schema directly
-        methodConfig = {
-          handler: handlerOrConfig,
-          schema: optionsOrSchema,
-        };
-      } else {
-        // Just the handler
-        methodConfig = handlerOrConfig;
-      }
-    } else if (typeof handlerOrConfig === 'object' && handlerOrConfig.handler) {
-      // Config object
-      methodConfig = handlerOrConfig;
-    } else {
-      throw new Error('Invalid handler configuration');
-    }
-
-    this.#methods[name] = methodConfig;
-
-    const config = typeof methodConfig === 'function' ? {} : methodConfig;
-    this.#logger.debug('Method registered', {
-      method: name,
-      hasSchema: !!config.schema,
-      exposeSchema: !!config.exposeSchema,
-      hasDescription: !!config.description,
-    });
-  }
-
-  /**
-   * Add middleware for specific hooks
-   * @param {string} hook
-   * @param {Function} middleware
-   */
-  use(hook, middleware) {
-    this.#middleware.use(hook, middleware);
-  }
-
-  /**
-   * Remove method
-   * @param {string} name
-   */
-  removeMethod(name) {
-    delete this.#methods[name];
-    this.#logger.debug('Method removed', { method: name });
-  }
-
-  /**
-   * Get method configuration
-   * @param {string} name
-   * @returns {any}
-   */
-  getMethod(name) {
-    return this.#methods[name];
-  }
-
-  /**
-   * List all registered methods
-   * @returns {string[]}
-   */
-  listMethods() {
-    return Object.keys(this.#methods);
-  }
-
-  /** @returns {string} The endpoint path (e.g. "/api"). */
-  get endpoint() {
-    return this.#endpoint;
-  }
-
-  /**
-   * @returns {{ [name: string]: any }}
-   * All registered methods.
-   */
-  get methods() {
-    return this.#methods;
-  }
-
-  /**
-   * Get logger instance
-   * @returns {Logger}
-   */
-  get logger() {
-    return this.#logger;
-  }
-
-  /**
-   * Get middleware manager
-   * @returns {MiddlewareManager}
-   */
-  get middleware() {
-    return this.#middleware;
-  }
-
-  /**
-   * Get validator instance
-   * @returns {SchemaValidator}
-   */
-  get validator() {
-    return this.#validator;
-  }
-
-  /**
-   * Get metrics data
-   * @returns {Object}
-   */
-  getMetrics() {
-    return {
-      methods: Object.keys(this.#methods).length,
-      middleware: {
-        beforeCall: this.#middleware.getMiddlewares('beforeCall').length,
-        afterCall: this.#middleware.getMiddlewares('afterCall').length,
-        onError: this.#middleware.getMiddlewares('onError').length,
-      },
-      uptime: process.uptime(),
-      memory: process.memoryUsage(),
-      timestamp: new Date().toISOString(),
-    };
-  }
-
-  /**
-   * Send a JSON-RPC 2.0 response.
-   * @param {Response} res The Express response object.
-   * @param {{
-   *   id?: string|number|null,
-   *   result?: any,
-   *   error?: { code: number, message: string, data?: any }
-   * }} responsePayload The JSON-RPC response fields.
-   */
-  reply(res, { id, result, error }) {
-    const response = { jsonrpc: '2.0', id: id === undefined ? null : id };
-
-    if (error) {
-      response.error = error;
-    } else {
-      response.result = result;
-    }
-
-    // Add safe options headers so client knows how to deserialize
-    // Send safe options headers to client
-    res.setHeader(
-      'X-RPC-Safe-Enabled',
-      this.#options.safeEnabled ? 'true' : 'false'
-    );
-
-    res.json(response);
-  }
-
-  /**
-   * Recursively convert BigInt values to strings and Date objects to ISO strings.
-   * This is crucial because JSON.stringify() cannot handle BigInt natively
-   * and Date objects are best transmitted in a standardized format.
-   *
-   * @param {any} value The value to serialize.
-   * @returns {any} A version of `value` safe for JSON serialization.
-   */
-  serializeBigIntsAndDates(value) {
-    return this.#serializeValue(value, false);
-  }
-
-  /**
-   * Internal serialization method with BigInt and Date warning tracking
-   * @private
-   */
-  #serializeValue(value, hasBigInt = false, hasDate = false) {
-    if (typeof value === 'bigint') {
-      // Warn if safeEnabled is disabled and we have BigInt
-      if (
-        !this.#options.safeEnabled &&
-        !hasBigInt &&
-        this.#options.warnOnUnsafe
-      ) {
-        this.#logger.warn(
-          'BigInt detected in serialization. Consider enabling safeEnabled option to avoid potential string/BigInt confusion.'
-        );
-      }
-      // Convert BigInt to string with 'n' suffix for proper deserialization
-      return `${value.toString()}n`;
-    }
-    if (value instanceof Date) {
-      // Warn if safeEnabled is disabled and we have Date
-      if (
-        !this.#options.safeEnabled &&
-        !hasDate &&
-        this.#options.warnOnUnsafe
-      ) {
-        this.#logger.warn(
-          'Date detected in serialization. Consider enabling safeEnabled option to avoid potential string/Date confusion.'
-        );
-      }
-      // Convert Date to ISO string with D: prefix if safeEnabled
-      const isoString = value.toISOString();
-      return this.#options.safeEnabled ? `D:${isoString}` : isoString;
-    }
-    if (typeof value === 'string') {
-      // Add S: prefix if safeEnabled is true
-      if (this.#options.safeEnabled) {
-        return `S:${value}`;
-      }
-      return value;
-    }
-    if (Array.isArray(value)) {
-      // Recurse into arrays - don't pass hasBigInt/hasDate to children
-      // Each element should be checked independently for warnings
-      return value.map((v) => this.#serializeValue(v, false, false));
-    }
-    if (value && typeof value === 'object') {
-      // Recurse into plain objects - don't pass hasBigInt/hasDate to children
-      // Each property should be checked independently for warnings
-      const result = {};
-      for (const [key, val] of Object.entries(value)) {
-        result[key] = this.#serializeValue(val, false, false);
-      }
-      return result;
-    }
-
-    // If it's none of the above, return as-is
-    return value;
-  }
-
-  /**
-   * Check if an object has BigInt values deep inside
-   * @private
-   */
-  #hasDeepBigInt(obj) {
-    if (typeof obj === 'bigint') return true;
-    if (Array.isArray(obj))
-      return obj.some((item) => this.#hasDeepBigInt(item));
-    if (obj && typeof obj === 'object') {
-      return Object.values(obj).some((val) => this.#hasDeepBigInt(val));
-    }
-    return false;
-  }
-
-  /**
-   * Check if an object has Date values deep inside
-   * @private
-   */
-  #hasDeepDate(obj) {
-    if (obj instanceof Date) return true;
-    if (Array.isArray(obj)) return obj.some((item) => this.#hasDeepDate(item));
-    if (obj && typeof obj === 'object') {
-      return Object.values(obj).some((val) => this.#hasDeepDate(val));
-    }
-    return false;
-  }
-
-  /**
-   * Recursively convert stringified BigInts back to BigInt,
-   * and ISO 8601 date strings back to Date objects.
-   *
-   * This is useful if you receive JSON that was serialized
-   * by `serializeBigIntsAndDates()` and want to re-hydrate
-   * the original types.
-   *
-   * @param {any} value The value to deserialize.
-   * @param {Object} [options] Custom deserialization options (uses server options if not provided).
-   * @param {boolean} [options.safeEnabled] Whether to expect safe prefixes for strings and dates.
-   * @returns {any} The re-hydrated value.
-   */
-  deserializeBigIntsAndDates(value, options = null) {
-    // Use provided options or fall back to server options
-    const safeEnabled = options
-      ? options.safeEnabled
-      : this.#options.safeEnabled;
-
-    // More comprehensive ISO date regex that handles:
-    // - UTC: 2023-01-01T12:00:00.000Z
-    // - With timezone: 2023-01-01T12:00:00.000+01:00
-    // - Without timezone: 2023-01-01T12:00:00.000 (treated as local)
-    const ISO_DATE_REGEX =
-      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
-
-    // 1. Check if it's a string that might be a BigInt, Date, or safe string
-    if (typeof value === 'string') {
-      // Safe string check: if safeEnabled and starts with S:
-      if (safeEnabled && value.startsWith('S:')) {
-        return value.substring(2); // Remove 'S:' prefix
-      }
-
-      // Safe date check: if safeEnabled and starts with D:
-      if (safeEnabled && value.startsWith('D:')) {
-        const isoString = value.substring(2); // Remove 'D:' prefix
-        const date = new Date(isoString);
-        // Double-check that we got a valid date
-        if (!Number.isNaN(date.getTime())) {
-          return date;
-        }
-      }
-
-      // BigInt check: matches digits (including negative), ending in "n"
-      if (/^-?\d+n$/.test(value)) {
-        return BigInt(value.slice(0, -1)); // Remove 'n' and convert
-      }
-
-      // Date check: matches an ISO 8601 string (only if safeEnabled is false)
-      if (!safeEnabled && ISO_DATE_REGEX.test(value)) {
-        const date = new Date(value);
-        // Double-check that we got a valid date
-        if (!Number.isNaN(date.getTime())) {
-          return date;
-        }
-      }
-    }
-
-    // 2. If it's an array, handle each element
-    if (Array.isArray(value)) {
-      return value.map((v) => this.deserializeBigIntsAndDates(v, options));
-    }
-
-    // 3. If it's a plain object, recurse into each property
-    if (value && typeof value === 'object') {
-      return Object.fromEntries(
-        Object.entries(value).map(([key, val]) => [
-          key,
-          this.deserializeBigIntsAndDates(val, options),
-        ])
-      );
-    }
-
-    // 4. For everything else (number, boolean, null, undefined, etc.), return as-is
-    return value;
-  }
-}
-
-// Import the client class
-const RpcClient = require('./clients/rpc-client');
-
-// Export both server and client, plus utilities
-module.exports = RpcEndpoint;
-module.exports.RpcEndpoint = RpcEndpoint;
-module.exports.RpcClient = RpcClient;
-module.exports.Logger = Logger;
-module.exports.MiddlewareManager = MiddlewareManager;
-module.exports.builtInMiddlewares = builtInMiddlewares;
-module.exports.SchemaValidator = SchemaValidator;
-module.exports.commonSchemas = commonSchemas;
-module.exports.SchemaBuilder = SchemaBuilder;
-module.exports.BatchHandler = BatchHandler;
+const path = require('path');
+const express = require('express');
+const expressPkg = require('express/package.json');
+const NestedError = require('nested-error-stacks');
+const {
+  RpcClient,
+  RpcError,
+  RpcHttpError,
+  RpcSafeClient,
+} = require('rpc-toolkit-js-client');
+const pkg = require('../package.json');
+
+const rpcClientAssetsPath = path.dirname(
+  require.resolve('rpc-toolkit-js-client')
+);
+const DEFAULT_MAX_SERIALIZATION_DEPTH = 100;
+
+/** @typedef {import("express").Router} Router */
+/** @typedef {import("express").Request} Request */
+/** @typedef {import("express").Response} Response */
+
+const Logger = require('./logger');
+const { MiddlewareManager, builtInMiddlewares } = require('./middleware');
+const {
+  SchemaValidator,
+  commonSchemas,
+  SchemaBuilder,
+} = require('./validation');
+const BatchHandler = require('./batch');
+const { hasOwn, validateEnvelope } = require('./protocol');
+
+/**
+ * Default properties to include in error serialization.
+ * @type {Array<string>}
+ */
+const defaultProperties = [
+  'stackTraceLimit',
+  'cause',
+  'code',
+  'message',
+  'stack',
+  'address',
+  'dest',
+  'errno',
+  'info',
+  'path',
+  'port',
+  'syscall',
+  'opensslErrorStack',
+  'function',
+  'library',
+  'reason',
+];
+
+/**
+ * Serializes an error into a JSON-compatible format, with optional sanitization.
+ * @param {Error | NestedError | Object} error - The error to serialize.
+ * @param {boolean} sanitize - Whether to remove sensitive fields.
+ * @param {Array<string>} properties - Properties to include in serialization.
+ * @returns {Object} The serialized error.
+ */
+const serializeError = (
+  error,
+  sanitize = false,
+  properties = defaultProperties
+) => {
+  if (error === null || error === undefined) return error;
+
+  const result = {};
+  const includeProperties = sanitize
+    ? properties.filter((prop) => !['address', 'path'].includes(prop))
+    : properties;
+
+  includeProperties.forEach((prop) => {
+    if (error?.[prop] !== undefined) {
+      result[prop] = error[prop];
+    }
+  });
+
+  if (error instanceof NestedError) {
+    result.type = 'NestedError';
+    if (error.nested)
+      result.nested = serializeError(error.nested, sanitize, properties);
+  } else if (error instanceof Error) {
+    result.type = 'Error';
+  } else if (error instanceof Object) {
+    result.type = 'Object';
+    Object.assign(result, error);
+  } else {
+    result.type = 'Default';
+    result.instance = error;
+  }
+
+  return result;
+};
+
+/**
+ * @template C
+ */
+class RpcEndpoint {
+  /**
+   * Serve client scripts for making JSON-RPC calls from the browser.
+   * @param {Router} router Express.Router instance
+   * @param {string} [url="/vendor/rpc-client"]
+   *    The path from which client scripts will be served.
+   */
+  static serveScripts(router, url = '/vendor/rpc-client') {
+    router.use(url, express.static(rpcClientAssetsPath));
+  }
+
+  /** @type {string} */
+  #endpoint;
+
+  /** @type {{ [name: string]: any }} */
+  #methods = {};
+
+  /** @type {string} */
+  #introspectionPrefix = '__rpc';
+
+  /** @type {boolean} */
+  #isInternalRegistration = false;
+
+  /** @type {Logger} */
+  #logger;
+
+  /** @type {MiddlewareManager} */
+  #middleware;
+
+  /** @type {SchemaValidator} */
+  #validator;
+
+  /** @type {BatchHandler} */
+  #batchHandler;
+
+  /** @type {Object} */
+  #options;
+
+  /**
+   * @param {Router} router The Express router to attach the endpoint to.
+   * @param {C} context The context object to pass to the method handlers.
+   * @param {string|Object} [endpointOrOptions="/api"] The endpoint path or options object.
+   * @param {Object} [options={}] Options object if first param is string.
+   */
+  constructor(router, context, endpointOrOptions = '/api', options = {}) {
+    // Handle both signatures: (router, context, "/api", options) and (router, context, options)
+    if (typeof endpointOrOptions === 'string') {
+      this.#endpoint = endpointOrOptions;
+      this.#options = { ...options };
+    } else {
+      this.#endpoint = endpointOrOptions.endpoint || '/api';
+      this.#options = { ...endpointOrOptions };
+    }
+
+    // Initialize components
+    this.#logger = new Logger(this.#options.logging || {});
+    this.#middleware = new MiddlewareManager();
+    this.#validator = new SchemaValidator(this.#options.validation || {});
+    this.#batchHandler = new BatchHandler(this);
+
+    // Set default options
+    this.#options.safeEnabled = this.#options.safeEnabled === true; // Default false
+    this.#options.warnOnUnsafe = this.#options.warnOnUnsafe !== false; // Default true
+    this.#options.strictMode = this.#options.strictMode !== false; // Default true
+    this.#options.enableIntrospection =
+      this.#options.enableIntrospection === true; // Default false
+    this.#options.introspectionPrefix =
+      this.#options.introspectionPrefix || '__rpc'; // Default __rpc
+
+    this.#introspectionPrefix = this.#options.introspectionPrefix;
+
+    // Validate that the router can handle JSON parsing
+    this.#validateJsonMiddleware();
+
+    // Register introspection methods if enabled
+    if (this.#options.enableIntrospection) {
+      this.#registerIntrospectionMethods();
+    }
+
+    // Setup built-in middleware if configured
+    this.#setupBuiltInMiddleware();
+
+    // Wire up routes
+    this.#setupRoutes(router, context);
+  }
+
+  /**
+   * Setup built-in middleware based on options
+   */
+  #setupBuiltInMiddleware() {
+    const { rateLimit, cors, auth, timing, methodWhitelist } = this.#options;
+
+    if (timing !== false) {
+      this.use('beforeCall', builtInMiddlewares.timing());
+    }
+
+    if (cors) {
+      this.use('beforeCall', builtInMiddlewares.cors(cors));
+    }
+
+    if (rateLimit) {
+      this.use('beforeCall', builtInMiddlewares.rateLimit(rateLimit));
+    }
+
+    if (auth) {
+      this.use('beforeCall', builtInMiddlewares.auth(auth));
+    }
+
+    if (methodWhitelist && Array.isArray(methodWhitelist)) {
+      this.use(
+        'beforeCall',
+        builtInMiddlewares.methodWhitelist(methodWhitelist)
+      );
+    }
+  }
+
+  /**
+   * Register introspection methods (__rpc.*)
+   * @private
+   */
+  #registerIntrospectionMethods() {
+    this.#isInternalRegistration = true;
+
+    // __rpc.listMethods - List all user methods (excludes __rpc.* methods)
+    this.addMethod(
+      `${this.#introspectionPrefix}.listMethods`,
+      async (_req, _context, _params) =>
+        Object.keys(this.#methods).filter(
+          (name) => !name.startsWith(this.#introspectionPrefix)
+        ),
+      {
+        description: 'List all available RPC methods',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.describe - Get schema and description of a specific method
+    this.addMethod(
+      `${this.#introspectionPrefix}.describe`,
+      async (_req, _context, params) => {
+        const methodName = params?.method;
+
+        if (!methodName || typeof methodName !== 'string') {
+          throw {
+            code: -32602,
+            message: 'Invalid params: method name required',
+          };
+        }
+
+        // Prevent introspection of __rpc.* methods
+        if (methodName.startsWith(this.#introspectionPrefix)) {
+          throw {
+            code: -32601,
+            message: 'Cannot describe introspection methods',
+          };
+        }
+
+        const methodConfig = this.#methods[methodName];
+        if (!methodConfig) {
+          throw { code: -32601, message: `Method not found: ${methodName}` };
+        }
+
+        // Check if schema is exposed
+        const config = typeof methodConfig === 'function' ? {} : methodConfig;
+        if (!config.exposeSchema) {
+          throw { code: -32601, message: 'Method schema not available' };
+        }
+
+        return {
+          name: methodName,
+          schema: config.schema || null,
+          description: config.description || '',
+        };
+      },
+      {
+        schema: {
+          type: 'object',
+          properties: {
+            method: { type: 'string' },
+          },
+          required: ['method'],
+        },
+        description: 'Get schema and description of a specific method',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.describeAll - Get all methods with public schemas
+    this.addMethod(
+      `${this.#introspectionPrefix}.describeAll`,
+      async (_req, _context, _params) => {
+        const publicMethods = [];
+
+        for (const [name, methodConfig] of Object.entries(this.#methods)) {
+          // Skip introspection methods
+          if (name.startsWith(this.#introspectionPrefix)) continue;
+
+          const config = typeof methodConfig === 'function' ? {} : methodConfig;
+          if (config.exposeSchema) {
+            publicMethods.push({
+              name,
+              schema: config.schema || null,
+              description: config.description || '',
+            });
+          }
+        }
+
+        return publicMethods;
+      },
+      {
+        description: 'List all methods with public schemas',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.version - Get toolkit version
+    this.addMethod(
+      `${this.#introspectionPrefix}.version`,
+      async (_req, _context, _params) => ({
+        toolkit: 'rpc-express-toolkit',
+        version: pkg.version,
+        expressVersion: expressPkg.version,
+        nodeVersion: process.version,
+      }),
+      {
+        description: 'Get RPC toolkit version information',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.capabilities - Get server capabilities
+    this.addMethod(
+      `${this.#introspectionPrefix}.capabilities`,
+      async (_req, _context, _params) => ({
+        safeMode: this.#options.safeEnabled,
+        batch: true,
+        introspection: true,
+        introspectionPrefix: this.#introspectionPrefix,
+        validation: !!this.#options.validation,
+        cors: !!this.#options.cors,
+        auth: !!this.#options.auth,
+        rateLimit: !!this.#options.rateLimit,
+        methodCount: Object.keys(this.#methods).filter(
+          (n) => !n.startsWith(this.#introspectionPrefix)
+        ).length,
+      }),
+      {
+        description: 'Get server capabilities and configuration',
+        exposeSchema: true,
+      }
+    );
+
+    this.#isInternalRegistration = false;
+  }
+
+  /**
+   * Validate JSON middleware functionality and Express compatibility
+   * @private
+   */
+  #validateJsonMiddleware() {
+    try {
+      // Check if express.json is available (Express 4.16.0+)
+      if (typeof express.json !== 'function') {
+        throw new Error(
+          'express.json() is not available. Please ensure you are using Express 4.16.0 or later, or install body-parser separately.'
+        );
+      }
+
+      // Test JSON middleware creation with default options
+      const jsonMiddleware = express.json({ limit: '10mb' });
+
+      if (typeof jsonMiddleware !== 'function') {
+        throw new Error(
+          'express.json() did not return a valid middleware function'
+        );
+      }
+
+      // Verify middleware has correct signature (req, res, next)
+      if (jsonMiddleware.length !== 3) {
+        throw new Error(
+          'JSON middleware has invalid signature - expected (req, res, next)'
+        );
+      }
+
+      this.#logger.debug('JSON middleware validation passed', {
+        expressJsonAvailable: true,
+        middlewareValid: true,
+        endpoint: this.#endpoint,
+      });
+    } catch (error) {
+      const errorMsg =
+        `JSON middleware validation failed: ${error.message}\n` +
+        `This router cannot handle JSON-RPC requests properly.\n\n` +
+        `Possible solutions:\n` +
+        `- Update Express: npm install express@latest (requires >=4.16.0)\n` +
+        `- Add JSON parsing middleware manually: router.use(express.json())\n` +
+        `- Install body-parser: npm install body-parser`;
+
+      this.#logger.error('JSON middleware validation failed', {
+        error: error.message,
+        expressVersion: expressPkg?.version || 'unknown',
+        endpoint: this.#endpoint,
+      });
+
+      throw new Error(errorMsg);
+    }
+  }
+
+  /**
+   * Setup Express routes
+   * @param {Router} router
+   * @param {C} context
+   */
+  #setupRoutes(router, context) {
+    // Health check endpoint
+    if (this.#options.healthCheck !== false) {
+      router.get(`${this.#endpoint}/health`, (req, res) => {
+        res.json({
+          status: 'ok',
+          timestamp: new Date().toISOString(),
+          version: pkg.version,
+        });
+      });
+    }
+
+    // Metrics endpoint
+    if (this.#options.metrics) {
+      router.get(`${this.#endpoint}/metrics`, (req, res) => {
+        res.json(this.getMetrics());
+      });
+    }
+
+    // Main JSON-RPC endpoint
+    router.post(this.#endpoint, async (req, res) => {
+      const startTime = Date.now();
+
+      try {
+        // Check if it's a batch request
+        if (this.#batchHandler.isBatchRequest(req.body)) {
+          this.#logger.info('Batch request received', {
+            batchSize: req.body.length,
+            ip: req.ip,
+          });
+
+          const results = await this.#batchHandler.processBatch(
+            req.body,
+            req,
+            res,
+            context
+          );
+
+          // Only send response if there are results (non-notification requests)
+          if (!Array.isArray(results)) {
+            res.setHeader(
+              'X-RPC-Safe-Enabled',
+              this.#options.safeEnabled ? 'true' : 'false'
+            );
+            res.json(results);
+          } else if (results.length > 0) {
+            // Align batch responses with single-call header negotiation
+            res.setHeader(
+              'X-RPC-Safe-Enabled',
+              this.#options.safeEnabled ? 'true' : 'false'
+            );
+            res.json(results);
+          } else {
+            res.status(204).end(); // No content for all-notification batch
+          }
+
+          this.#logger.info('Batch request completed', {
+            batchSize: req.body.length,
+            responseCount: Array.isArray(results) ? results.length : 1,
+            duration: Date.now() - startTime,
+          });
+
+          return;
+        }
+
+        // Single request processing
+        await this.#processSingleRequest(req, res, context, startTime);
+      } catch (error) {
+        this.#logger.error('Endpoint error', {
+          error: error.message,
+          stack: error.stack,
+        });
+
+        res.json({
+          jsonrpc: '2.0',
+          id: null,
+          error: {
+            code: -32603,
+            message: 'Internal error',
+            data: serializeError(error, true),
+          },
+        });
+      }
+    });
+  }
+
+  /**
+   * Process a single JSON-RPC request
+   * @param {Request} req
+   * @param {Response} res
+   * @param {C} context
+   * @param {number} startTime
+   */
+  async #processSingleRequest(req, res, context, startTime) {
+    const { method, params, id } = req.body || {};
+    const envelope = validateEnvelope(req.body);
+
+    // Log the incoming request
+    this.#logger.rpcCall(method, params, id, req);
+
+    if (!envelope.valid) {
+      return this.reply(res, {
+        id: envelope.responseId,
+        error: envelope.error,
+      });
+    }
+
+    const methodConfig = this.#methods[method];
+    if (!methodConfig) {
+      if (envelope.isNotification) {
+        res.status(204).end();
+        return null;
+      }
+
+      return this.reply(res, {
+        id,
+        error: { code: -32601, message: `Method "${method}" not found` },
+      });
+    }
+
+    const handler =
+      typeof methodConfig === 'function' ? methodConfig : methodConfig.handler;
+    const schema =
+      typeof methodConfig === 'object' ? methodConfig.schema : null;
+
+    try {
+      // Check client's safe options from request headers
+      const clientSafeHeader = req.headers['x-rpc-safe-enabled'];
+
+      // Strict mode: se server ha safe enabled ma client non invia header → JSON-RPC ERROR
+      if (
+        this.#options.strictMode &&
+        this.#options.safeEnabled &&
+        !clientSafeHeader
+      ) {
+        if (envelope.isNotification) {
+          res.status(204).end();
+          return null;
+        }
+
+        return this.reply(res, {
+          id,
+          error: {
+            code: -32600, // Invalid Request
+            message:
+              'RPC Compatibility Error: Server requires safe serialization header but client did not provide it.',
+            data: {
+              serverSafeEnabled: this.#options.safeEnabled,
+              requiredHeader: 'X-RPC-Safe-Enabled',
+              strictMode: true,
+              solution:
+                'Update client to rpc-express-toolkit v4+ or disable server strict mode',
+            },
+          },
+        });
+      }
+
+      // Use client's safe options for parameter deserialization
+      const clientSafeEnabled = clientSafeHeader === 'true';
+      const deserializationOptions = {
+        safeEnabled: clientSafeEnabled,
+      };
+
+      // Deserialize parameters using client's safe options
+      const deserializedParams = hasOwn(req.body, 'params')
+        ? this.deserializeBigIntsAndDates(params, deserializationOptions)
+        : params;
+
+      // Prepare middleware context
+      let middlewareContext = {
+        req,
+        res,
+        method,
+        params: deserializedParams,
+        context,
+        id,
+        startTime,
+      };
+
+      // Execute beforeCall middleware
+      middlewareContext = await this.#middleware.execute(
+        'beforeCall',
+        middlewareContext
+      );
+
+      // Validate parameters if schema is provided
+      if (schema) {
+        middlewareContext = await this.#middleware.execute(
+          'beforeValidation',
+          middlewareContext
+        );
+
+        const validation = this.#validator.validate(
+          middlewareContext.params,
+          schema
+        );
+        if (!validation.valid) {
+          const error = new Error('Validation failed');
+          error.code = -32602;
+          error.data = {
+            validationErrors: validation.errors.map((err) => ({
+              field: err.instancePath || err.schemaPath,
+              message: err.message,
+              value: err.data,
+            })),
+          };
+          throw error;
+        }
+
+        middlewareContext.params = validation.data;
+        middlewareContext = await this.#middleware.execute(
+          'afterValidation',
+          middlewareContext
+        );
+      }
+
+      // Invoke the handler
+      const result = await Promise.resolve(
+        handler(req, context, middlewareContext.params)
+      );
+
+      // Execute afterCall middleware
+      middlewareContext.result = result;
+      await this.#middleware.execute('afterCall', middlewareContext);
+
+      // Log success
+      const duration = Date.now() - startTime;
+      this.#logger.rpcSuccess(method, id, duration, result);
+
+      // Convert any BigInt/Date values before JSON-stringifying
+      const safeResult = this.serializeBigIntsAndDates(result);
+      if (envelope.isNotification) {
+        res.status(204).end();
+        return null;
+      }
+
+      this.reply(res, { id, result: safeResult });
+    } catch (err) {
+      const duration = Date.now() - startTime;
+      this.#logger.rpcError(method, id, duration, err);
+
+      // Execute error middleware
+      try {
+        await this.#middleware.execute('onError', {
+          req,
+          res,
+          method,
+          params,
+          context,
+          id,
+          error: err,
+          startTime,
+          duration,
+        });
+      } catch (middlewareError) {
+        this.#logger.error('Error middleware failed', {
+          error: middlewareError.message,
+        });
+      }
+
+      if (envelope.isNotification) {
+        res.status(204).end();
+        return null;
+      }
+
+      this.reply(res, {
+        id,
+        error: {
+          code: err.code || -32603,
+          message: err.message || `Internal error`,
+          ...(err.data && { data: err.data }),
+          error: serializeError(err, true),
+        },
+      });
+    }
+    // Ensure explicit return for consistent-return rule
+    return null;
+  }
+
+  /**
+   * Register a new JSON-RPC method.
+   * @param {string} name The method name.
+   * @param {Function|Object} handlerOrConfig The function to handle calls or config object with handler, schema, exposeSchema, description.
+   * @param {Object} [optionsOrSchema] Optional config object or schema for backward compatibility.
+   */
+  addMethod(name, handlerOrConfig, optionsOrSchema = null) {
+    // Prevent users from registering introspection methods
+    if (
+      name.startsWith(this.#introspectionPrefix) &&
+      !this.#isInternalRegistration
+    ) {
+      throw new Error(
+        `Method names starting with '${this.#introspectionPrefix}.' are reserved for RPC introspection`
+      );
+    }
+
+    let methodConfig;
+
+    if (typeof handlerOrConfig === 'function') {
+      // Function handler - optionsOrSchema can be schema (backward compat) or options object
+      if (
+        optionsOrSchema &&
+        (optionsOrSchema.schema ||
+          optionsOrSchema.exposeSchema ||
+          optionsOrSchema.description)
+      ) {
+        // New format: options object
+        methodConfig = {
+          handler: handlerOrConfig,
+          ...optionsOrSchema,
+        };
+      } else if (optionsOrSchema) {
+        // Old format: schema directly
+        methodConfig = {
+          handler: handlerOrConfig,
+          schema: optionsOrSchema,
+        };
+      } else {
+        // Just the handler
+        methodConfig = handlerOrConfig;
+      }
+    } else if (typeof handlerOrConfig === 'object' && handlerOrConfig.handler) {
+      // Config object
+      methodConfig = handlerOrConfig;
+    } else {
+      throw new Error('Invalid handler configuration');
+    }
+
+    this.#methods[name] = methodConfig;
+
+    const config = typeof methodConfig === 'function' ? {} : methodConfig;
+    this.#logger.debug('Method registered', {
+      method: name,
+      hasSchema: !!config.schema,
+      exposeSchema: !!config.exposeSchema,
+      hasDescription: !!config.description,
+    });
+  }
+
+  /**
+   * Add middleware for specific hooks
+   * @param {string} hook
+   * @param {Function} middleware
+   */
+  use(hook, middleware) {
+    this.#middleware.use(hook, middleware);
+  }
+
+  /**
+   * Remove method
+   * @param {string} name
+   */
+  removeMethod(name) {
+    delete this.#methods[name];
+    this.#logger.debug('Method removed', { method: name });
+  }
+
+  /**
+   * Get method configuration
+   * @param {string} name
+   * @returns {any}
+   */
+  getMethod(name) {
+    return this.#methods[name];
+  }
+
+  /**
+   * List all registered methods
+   * @returns {string[]}
+   */
+  listMethods() {
+    return Object.keys(this.#methods);
+  }
+
+  /** @returns {string} The endpoint path (e.g. "/api"). */
+  get endpoint() {
+    return this.#endpoint;
+  }
+
+  /**
+   * @returns {{ [name: string]: any }}
+   * All registered methods.
+   */
+  get methods() {
+    return this.#methods;
+  }
+
+  /**
+   * Get logger instance
+   * @returns {Logger}
+   */
+  get logger() {
+    return this.#logger;
+  }
+
+  /**
+   * Get middleware manager
+   * @returns {MiddlewareManager}
+   */
+  get middleware() {
+    return this.#middleware;
+  }
+
+  /**
+   * Get validator instance
+   * @returns {SchemaValidator}
+   */
+  get validator() {
+    return this.#validator;
+  }
+
+  /**
+   * Get endpoint options
+   * @returns {Object}
+   */
+  get options() {
+    return { ...this.#options };
+  }
+
+  /**
+   * Get metrics data
+   * @returns {Object}
+   */
+  getMetrics() {
+    return {
+      methods: Object.keys(this.#methods).length,
+      middleware: {
+        beforeCall: this.#middleware.getMiddlewares('beforeCall').length,
+        afterCall: this.#middleware.getMiddlewares('afterCall').length,
+        onError: this.#middleware.getMiddlewares('onError').length,
+      },
+      uptime: process.uptime(),
+      memory: process.memoryUsage(),
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Send a JSON-RPC 2.0 response.
+   * @param {Response} res The Express response object.
+   * @param {{
+   *   id?: string|number|null,
+   *   result?: any,
+   *   error?: { code: number, message: string, data?: any }
+   * }} responsePayload The JSON-RPC response fields.
+   */
+  reply(res, { id, result, error }) {
+    const response = { jsonrpc: '2.0', id: id === undefined ? null : id };
+
+    if (error) {
+      response.error = error;
+    } else {
+      response.result = result;
+    }
+
+    // Add safe options headers so client knows how to deserialize
+    // Send safe options headers to client
+    res.setHeader(
+      'X-RPC-Safe-Enabled',
+      this.#options.safeEnabled ? 'true' : 'false'
+    );
+
+    res.json(response);
+  }
+
+  /**
+   * Recursively convert BigInt values to strings and Date objects to ISO strings.
+   * This is crucial because JSON.stringify() cannot handle BigInt natively
+   * and Date objects are best transmitted in a standardized format.
+   *
+   * @param {any} value The value to serialize.
+   * @returns {any} A version of `value` safe for JSON serialization.
+   */
+  serializeBigIntsAndDates(value) {
+    return this.#serializeValue(value, false, false, {
+      depth: 0,
+      seen: new WeakSet(),
+    });
+  }
+
+  /**
+   * Internal serialization method with BigInt and Date warning tracking
+   * @private
+   */
+  #serializeValue(
+    value,
+    hasBigInt = false,
+    hasDate = false,
+    state = { depth: 0, seen: new WeakSet() }
+  ) {
+    const maxDepth =
+      this.#options.maxSerializationDepth || DEFAULT_MAX_SERIALIZATION_DEPTH;
+    if (state.depth > maxDepth) {
+      throw new Error('Serialization depth limit exceeded');
+    }
+
+    if (typeof value === 'bigint') {
+      // Warn if safeEnabled is disabled and we have BigInt
+      if (
+        !this.#options.safeEnabled &&
+        !hasBigInt &&
+        this.#options.warnOnUnsafe
+      ) {
+        this.#logger.warn(
+          'BigInt detected in serialization. Consider enabling safeEnabled option to avoid potential string/BigInt confusion.'
+        );
+      }
+      // Convert BigInt to string with 'n' suffix for proper deserialization
+      return `${value.toString()}n`;
+    }
+    if (value instanceof Date) {
+      // Warn if safeEnabled is disabled and we have Date
+      if (
+        !this.#options.safeEnabled &&
+        !hasDate &&
+        this.#options.warnOnUnsafe
+      ) {
+        this.#logger.warn(
+          'Date detected in serialization. Consider enabling safeEnabled option to avoid potential string/Date confusion.'
+        );
+      }
+      // Convert Date to ISO string with D: prefix if safeEnabled
+      const isoString = value.toISOString();
+      return this.#options.safeEnabled ? `D:${isoString}` : isoString;
+    }
+    if (typeof value === 'string') {
+      // Add S: prefix if safeEnabled is true
+      if (this.#options.safeEnabled) {
+        return `S:${value}`;
+      }
+      return value;
+    }
+    if (Array.isArray(value)) {
+      if (state.seen.has(value)) {
+        throw new Error('Circular reference detected during serialization');
+      }
+
+      state.seen.add(value);
+      // Recurse into arrays - don't pass hasBigInt/hasDate to children
+      // Each element should be checked independently for warnings
+      try {
+        return value.map((v) =>
+          this.#serializeValue(v, false, false, {
+            depth: state.depth + 1,
+            seen: state.seen,
+          })
+        );
+      } finally {
+        state.seen.delete(value);
+      }
+    }
+    if (value && typeof value === 'object') {
+      if (state.seen.has(value)) {
+        throw new Error('Circular reference detected during serialization');
+      }
+
+      state.seen.add(value);
+      // Recurse into plain objects - don't pass hasBigInt/hasDate to children
+      // Each property should be checked independently for warnings
+      const result = {};
+      try {
+        Object.entries(value).forEach(([key, val]) => {
+          Object.defineProperty(result, key, {
+            value: this.#serializeValue(val, false, false, {
+              depth: state.depth + 1,
+              seen: state.seen,
+            }),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        });
+      } finally {
+        state.seen.delete(value);
+      }
+      return result;
+    }
+
+    // If it's none of the above, return as-is
+    return value;
+  }
+
+  /**
+   * Check if an object has BigInt values deep inside
+   * @private
+   */
+  #hasDeepBigInt(obj) {
+    if (typeof obj === 'bigint') return true;
+    if (Array.isArray(obj))
+      return obj.some((item) => this.#hasDeepBigInt(item));
+    if (obj && typeof obj === 'object') {
+      return Object.values(obj).some((val) => this.#hasDeepBigInt(val));
+    }
+    return false;
+  }
+
+  /**
+   * Check if an object has Date values deep inside
+   * @private
+   */
+  #hasDeepDate(obj) {
+    if (obj instanceof Date) return true;
+    if (Array.isArray(obj)) return obj.some((item) => this.#hasDeepDate(item));
+    if (obj && typeof obj === 'object') {
+      return Object.values(obj).some((val) => this.#hasDeepDate(val));
+    }
+    return false;
+  }
+
+  /**
+   * Recursively convert stringified BigInts back to BigInt,
+   * and ISO 8601 date strings back to Date objects.
+   *
+   * This is useful if you receive JSON that was serialized
+   * by `serializeBigIntsAndDates()` and want to re-hydrate
+   * the original types.
+   *
+   * @param {any} value The value to deserialize.
+   * @param {Object} [options] Custom deserialization options (uses server options if not provided).
+   * @param {boolean} [options.safeEnabled] Whether to expect safe prefixes for strings and dates.
+   * @returns {any} The re-hydrated value.
+   */
+  deserializeBigIntsAndDates(value, options = null, state = null) {
+    const traversalState = state || {
+      depth: 0,
+      seen: new WeakSet(),
+    };
+    const maxDepth =
+      this.#options.maxDeserializationDepth || DEFAULT_MAX_SERIALIZATION_DEPTH;
+    if (traversalState.depth > maxDepth) {
+      throw new Error('Deserialization depth limit exceeded');
+    }
+
+    // Use provided options or fall back to server options
+    const safeEnabled = options
+      ? options.safeEnabled
+      : this.#options.safeEnabled;
+
+    // More comprehensive ISO date regex that handles:
+    // - UTC: 2023-01-01T12:00:00.000Z
+    // - With timezone: 2023-01-01T12:00:00.000+01:00
+    // - Without timezone: 2023-01-01T12:00:00.000 (treated as local)
+    const ISO_DATE_REGEX =
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
+
+    // 1. Check if it's a string that might be a BigInt, Date, or safe string
+    if (typeof value === 'string') {
+      // Safe string check: if safeEnabled and starts with S:
+      if (safeEnabled && value.startsWith('S:')) {
+        return value.substring(2); // Remove 'S:' prefix
+      }
+
+      // Safe date check: if safeEnabled and starts with D:
+      if (safeEnabled && value.startsWith('D:')) {
+        const isoString = value.substring(2); // Remove 'D:' prefix
+        const date = new Date(isoString);
+        // Double-check that we got a valid date
+        if (!Number.isNaN(date.getTime())) {
+          return date;
+        }
+      }
+
+      // BigInt check: matches digits (including negative), ending in "n"
+      if (/^-?\d+n$/.test(value)) {
+        return BigInt(value.slice(0, -1)); // Remove 'n' and convert
+      }
+
+      // Date check: matches an ISO 8601 string (only if safeEnabled is false)
+      if (!safeEnabled && ISO_DATE_REGEX.test(value)) {
+        const date = new Date(value);
+        // Double-check that we got a valid date
+        if (!Number.isNaN(date.getTime())) {
+          return date;
+        }
+      }
+    }
+
+    // 2. If it's an array, handle each element
+    if (Array.isArray(value)) {
+      if (traversalState.seen.has(value)) {
+        throw new Error('Circular reference detected during deserialization');
+      }
+
+      traversalState.seen.add(value);
+      try {
+        return value.map((v) =>
+          this.deserializeBigIntsAndDates(v, options, {
+            depth: traversalState.depth + 1,
+            seen: traversalState.seen,
+          })
+        );
+      } finally {
+        traversalState.seen.delete(value);
+      }
+    }
+
+    // 3. If it's a plain object, recurse into each property
+    if (value && typeof value === 'object') {
+      if (traversalState.seen.has(value)) {
+        throw new Error('Circular reference detected during deserialization');
+      }
+
+      traversalState.seen.add(value);
+      const result = {};
+      try {
+        Object.entries(value).forEach(([key, val]) => {
+          Object.defineProperty(result, key, {
+            value: this.deserializeBigIntsAndDates(val, options, {
+              depth: traversalState.depth + 1,
+              seen: traversalState.seen,
+            }),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        });
+      } finally {
+        traversalState.seen.delete(value);
+      }
+      return result;
+    }
+
+    // 4. For everything else (number, boolean, null, undefined, etc.), return as-is
+    return value;
+  }
+}
+
+// Export both server and client, plus utilities
+module.exports = RpcEndpoint;
+module.exports.RpcEndpoint = RpcEndpoint;
+module.exports.RpcClient = RpcClient;
+module.exports.RpcError = RpcError;
+module.exports.RpcHttpError = RpcHttpError;
+module.exports.RpcSafeClient = RpcSafeClient;
+module.exports.Logger = Logger;
+module.exports.MiddlewareManager = MiddlewareManager;
+module.exports.builtInMiddlewares = builtInMiddlewares;
+module.exports.SchemaValidator = SchemaValidator;
+module.exports.commonSchemas = commonSchemas;
+module.exports.SchemaBuilder = SchemaBuilder;
+module.exports.BatchHandler = BatchHandler;