rpc-express-toolkit 4.3.5 → 4.4.1

package/README.md

@@ -6,21 +6,108 @@
 [![npm version](https://img.shields.io/npm/v/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)
 [![npm downloads](https://img.shields.io/npm/dm/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)
 [![node](https://img.shields.io/node/v/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)
+[![Status](https://img.shields.io/badge/status-stable-green.svg)](https://github.com/n-car/rpc-express-toolkit/releases)
 
 JSON-RPC 2.0 toolkit for Express.js with simplified APIs, middleware, schema validation, batch support, and optional Safe Mode type preservation.
 
+## Which Package Should I Use?
+
+- Use `rpc-express-toolkit` if you are building a JSON-RPC endpoint on Express.
+- Use [`rpc-node-toolkit`](https://github.com/n-car/rpc-node-toolkit) if you want framework-agnostic Node.js or plain `node:http`.
+- Use [`rpc-toolkit-js-client`](https://github.com/n-car/rpc-toolkit-js-client) if you only need a browser or Node.js client.
+- Use [`rpc-toolkit`](https://github.com/n-car/rpc-toolkit) as the ecosystem hub and compatibility reference.
+
 ## Quick Start
 
 ### Installation
 
 ```bash
-npm install rpc-express-toolkit
+npm install express rpc-express-toolkit
 # or
-yarn add rpc-express-toolkit
+yarn add express rpc-express-toolkit
 ```
 
 Requirements:
+
 - Node.js 18+ (uses `globalThis.fetch`)
+- Express 4.21+ or Express 5.x
+
+### Compatibility
+
+`rpc-express-toolkit` is tested with Node.js 18, 20, 22, and 24 across Express 4 and Express 5. See [Compatibility](docs/COMPATIBILITY.md) for the current runtime matrix.
+
+### TypeScript
+
+The package supports TypeScript ESM/NodeNext and CommonJS consumers. Both forms are tested with `strict: true`, `skipLibCheck: false`, and `esModuleInterop: false` against the tarball produced by `npm pack`.
+
+Install the TypeScript and Express declarations used by these examples:
+
+```bash
+npm install --save-dev typescript @types/express @types/node
+```
+
+ESM/NodeNext (`package.json` contains `"type": "module"`):
+
+```typescript
+import express from 'express';
+import RpcEndpoint, {
+  RpcEndpoint as NamedRpcEndpoint,
+  RpcClient,
+  type RpcEndpointOptions,
+} from 'rpc-express-toolkit';
+import {
+  RpcSafeClient,
+  RpcSafeEndpoint,
+} from 'rpc-express-toolkit/safe';
+
+const app = express();
+app.use(express.json());
+
+const options: RpcEndpointOptions = { safeEnabled: false };
+const rpc = new RpcEndpoint(app, {}, options);
+const namedRpc = new NamedRpcEndpoint(app, {}, '/named');
+const client = new RpcClient('http://localhost:3000/api');
+const safeRpc = new RpcSafeEndpoint(app, {}, '/safe');
+const safeClient = new RpcSafeClient('http://localhost:3000/safe');
+```
+
+Use these compiler options for the ESM example:
+
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": false,
+    "esModuleInterop": false,
+    "ignoreDeprecations": "6.0"
+  }
+}
+```
+
+`ignoreDeprecations` only acknowledges TypeScript 6's deprecation notice for
+the explicitly tested `esModuleInterop: false` setting.
+
+CommonJS TypeScript (`.cts` with NodeNext or Node16 resolution):
+
+```typescript
+import express = require('express');
+import RpcEndpoint = require('rpc-express-toolkit');
+import Safe = require('rpc-express-toolkit/safe');
+
+const app = express();
+app.use(express.json());
+
+const options: RpcEndpoint.RpcEndpointOptions = { safeEnabled: false };
+const rpc = new RpcEndpoint(app, {}, options);
+const namedRpc = new RpcEndpoint.RpcEndpoint(app, {}, '/named');
+const client = new RpcEndpoint.RpcClient('http://localhost:3000/api');
+const safeRpc = new Safe.RpcSafeEndpoint(app, {}, '/safe');
+const safeClient = new Safe.RpcSafeClient('http://localhost:3000/safe');
+```
+
+The root import remains the `RpcEndpoint` CommonJS default while also exposing its named API. The `/safe` subpath exposes the safe classes and the root utilities it re-exports at runtime.
 
 ### Server
 
@@ -142,7 +229,7 @@ Calls to methods outside the whitelist are rejected. This is a basic method rest
 [![npm (proxy)](https://img.shields.io/npm/v/rpc-express-toolkit-safe.svg)](https://www.npmjs.com/package/rpc-express-toolkit-safe)
 [![safe preset](https://img.shields.io/badge/safe%20preset-available-blue)](#safe-import-opt-in)
 
-When you control both client and server and want safer type round-trips, import the safe preset. It enables safe serialization by default (and strict mode on the server):
+When you control both client and server and want safer type round-trips, import the built-in safe preset from `rpc-express-toolkit/safe`. It enables safe serialization by default and strict mode on the server:
 
 ```js
 // Server (safe preset)
@@ -161,9 +248,9 @@ const client = new RpcSafeClient('http://localhost:3000/api');
 
 This keeps JSON-RPC 2.0 compliance as default for the main entrypoint, while offering a convenient safe-mode import for projects that prefer explicit type disambiguation.
 
-Alternative: npm proxy package
+#### Alternative Compatibility Package
 
-If you prefer a dedicated package name, you can install the thin proxy `rpc-express-toolkit-safe` which simply re-exports the safe preset:
+`rpc-express-toolkit-safe` is a thin compatibility package that re-exports the same safe preset. Use it only when a separate package name is useful for dependency policy or migration; new projects can import `rpc-express-toolkit/safe` directly.
 
 ```bash
 npm install rpc-express-toolkit-safe
@@ -227,7 +314,7 @@ In `__rpc.capabilities`, `auth` is a boolean indicating whether authentication m
 
 For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.
 
-## 🔗 Related Projects
+## Related Projects
 
 - [rpc-php-toolkit](https://github.com/n-car/rpc-php-toolkit) - PHP implementation
 - [rpc-dotnet-toolkit](https://github.com/n-car/rpc-dotnet-toolkit) - .NET implementation

package/docs/COMPATIBILITY.md

@@ -0,0 +1,64 @@
+# Compatibility
+
+`rpc-express-toolkit` is tested as an Express integration library, not as an application framework replacement.
+
+## Runtime Matrix
+
+| Runtime | Status |
+| --- | --- |
+| Node.js 18.x | CI tested |
+| Node.js 20.x | CI tested |
+| Node.js 22.x | CI tested |
+| Node.js 24.x | CI tested |
+| Express 4.x | CI tested |
+| Express 5.x | CI tested |
+
+The GitHub Actions matrix runs the test suite across Node.js 18, 20, 22, and 24 with both Express 4 and Express 5.
+
+## Module And TypeScript Compatibility
+
+The published package remains CommonJS at runtime and supports both CommonJS and Node.js ESM consumers. Its TypeScript declarations model the CommonJS default export and the named properties exposed by the root and `/safe` entrypoints.
+
+| Consumer | Module setup | Verified imports | Validation |
+| --- | --- | --- | --- |
+| TypeScript ESM | `"type": "module"` with `module` and `moduleResolution` set to `NodeNext` | Root default and named imports, public root types, and named `/safe` imports | TypeScript 6, `strict: true`, `skipLibCheck: false`, `esModuleInterop: false` |
+| TypeScript CommonJS | `.cts` with NodeNext resolution | `import = require()` for the root and `/safe`, including namespace properties | TypeScript 6, `strict: true`, `skipLibCheck: false`, `esModuleInterop: false` |
+| Node.js ESM | `.mjs` | Root default and named imports plus named `/safe` imports | Runtime smoke test |
+| Node.js CommonJS | `.cjs` | `require()` for the root and `/safe`, including root default identity | Runtime smoke test |
+
+The TypeScript ESM consumer covers `RpcEndpoint` as both the default and a named import, `RpcClient`, `RpcEndpointOptions`, `RpcSafeEndpoint`, and `RpcSafeClient`. The CommonJS consumer covers the constructable root export, `RpcEndpoint.RpcClient`, `Safe.RpcSafeEndpoint`, and `Safe.RpcSafeClient`.
+
+TypeScript applications using Express should install `@types/express` and
+`@types/node`; the package test installs these declarations in its isolated
+consumer.
+
+The TypeScript 6 fixtures set `ignoreDeprecations: "6.0"` solely to
+acknowledge the compiler's deprecation notice for the deliberately explicit
+`esModuleInterop: false` test setting.
+
+### Packaged Consumer Validation
+
+`npm run package-test` builds a tarball with `npm pack`, installs that tarball into isolated consumer fixtures, and runs the full matrix above. This verifies the published `exports` map, included files, declaration resolution, module extensions, and runtime format instead of importing the repository sources directly.
+
+Package validation runs in CI and as part of `prepublishOnly`, so declaration or packaging regressions block publication.
+
+## Express Dependency
+
+Express is declared as a peer dependency:
+
+```json
+"express": "^4.21.2 || ^5.0.0"
+```
+
+Applications should install Express directly alongside `rpc-express-toolkit`.
+
+## Compatibility Coverage
+
+The Express compatibility tests cover:
+
+- standard JSON-RPC endpoint calls;
+- batch requests;
+- Safe Mode endpoints;
+- introspection reporting of the active Express runtime.
+
+Broader RPC behavior is covered by the main test suite and is expected to run identically on Express 4 and Express 5. Module and declaration compatibility is covered separately by the packaged consumer validation.

package/package.json

@@ -1,9 +1,10 @@
 {
     "name":  "rpc-express-toolkit",
-    "version":  "4.3.5",
+    "version":  "4.4.1",
     "description":  "JSON-RPC 2.0 toolkit for Express.js with simplified APIs, structured logging, middleware, schema validation, batch support, and optional Safe Mode.",
     "main":  "src/index.js",
     "types":  "src/index.d.ts",
+    "type":  "commonjs",
     "exports":  {
                     ".":  {
                               "types":  "./src/index.d.ts",
@@ -19,6 +20,7 @@
     "files":  [
                   "src/",
                   "examples/",
+                  "docs/COMPATIBILITY.md",
                   "README.md",
                   "LICENSE"
               ],
@@ -30,7 +32,9 @@
                     "lint:fix":  "eslint src/ examples/ --fix",
                     "clean":  "node -e \"require(\u0027fs\u0027).existsSync(\u0027dist\u0027) \u0026\u0026 require(\u0027fs\u0027).rmSync(\u0027dist\u0027, {recursive: true})\"",
                     "build":  "node -e \"require.resolve(\u0027rpc-toolkit-js-client\u0027)\"",
-                    "prepublishOnly":  "npm run build",
+                    "typecheck":  "node test/package/runner.js --types-only",
+                    "package-test":  "node test/package/runner.js",
+                    "prepublishOnly":  "npm run build \u0026\u0026 npm run package-test",
                     "precommit":  "npm run lint \u0026\u0026 npm test"
                 },
     "repository":  {
@@ -66,7 +70,7 @@
                      "rate-limit",
                      "authentication"
                  ],
-    "author":  "Nicola Carpanese \u003cnicola.carpanese@gmail.com\u003e",
+    "author":  "Nicola Carpanese (https://github.com/n-car)",
     "license":  "MIT",
     "bugs":  {
                  "url":  "https://github.com/n-car/rpc-express-toolkit/issues"
@@ -76,22 +80,30 @@
                     "node":  "\u003e=18.0.0"
                 },
     "devDependencies":  {
+                            "@arethetypeswrong/cli":  "^0.18.5",
+                            "@types/express":  "^5.0.6",
+                            "@types/node":  "^18.19.0",
                             "eslint":  "^8.57.1",
                             "eslint-config-airbnb-base":  "^15.0.0",
                             "eslint-config-prettier":  "^9.1.2",
                             "eslint-plugin-import":  "^2.31.0",
                             "eslint-plugin-prettier":  "^5.5.3",
+                            "express":  "^4.21.2 || ^5.0.0",
                             "husky":  "^8.0.0",
                             "jest":  "^29.7.0",
                             "lint-staged":  "^13.0.0",
                             "prettier":  "^3.6.2",
+                            "publint":  "^0.3.22",
                             "supertest":  "^6.3.3",
-                            "terser":  "^5.43.1"
+                            "terser":  "^5.43.1",
+                            "typescript":  "~6.0.3"
                         },
+    "peerDependencies":  {
+                             "express":  "^4.21.2 || ^5.0.0"
+                         },
     "dependencies":  {
                          "ajv":  "^8.12.0",
                          "ajv-formats":  "^2.1.1",
-                         "express":  "^4.21.2",
                          "nested-error-stacks":  "^2.1.1",
                          "rpc-toolkit-js-client":  "^1.1.2"
                      },
@@ -101,7 +113,6 @@
     "contributors":  [
                          {
                              "name":  "Nicola Carpanese",
-                             "email":  "nicola.carpanese@gmail.com",
                              "url":  "https://github.com/n-car"
                          }
                      ],

package/src/index.d.ts

@@ -1,290 +1,287 @@
 // Type definitions for rpc-express-toolkit
 
-import type { Router, Request, Response } from 'express';
+import type { Request, Response, Router } from 'express';
 import {
   RpcClient as SharedRpcClient,
   RpcError as SharedRpcError,
   RpcHttpError as SharedRpcHttpError,
-  RpcSafeClient as SharedRpcSafeClient
+  RpcSafeClient as SharedRpcSafeClient,
 } from 'rpc-toolkit-js-client';
 import type {
   RpcBatchRequest as SharedRpcBatchRequest,
-  RpcClientOptions as SharedRpcClientOptions
+  RpcClientOptions as SharedRpcClientOptions,
 } from 'rpc-toolkit-js-client';
 
 /**
- * JSON-RPC handler function type
+ * The main RpcEndpoint class for JSON-RPC 2.0 endpoints.
  */
-type JSONRPCHandler<C> = (
-  req: Request,
-  context: C,
-  params: any
-) => any | Promise<any>;
+declare class RpcEndpoint<C = any> {
+  constructor(router: Router, context: C, endpoint?: string);
+  constructor(
+    router: Router,
+    context: C,
+    options?: RpcEndpoint.RpcEndpointOptions
+  );
+  constructor(
+    router: Router,
+    context: C,
+    endpoint?: string,
+    options?: RpcEndpoint.RpcEndpointOptions
+  );
+
+  /** The endpoint path, for example "/api". */
+  get endpoint(): string;
 
-/**
- * Method configuration object
- */
-interface MethodConfig<C> {
-  handler: JSONRPCHandler<C>;
-  schema?: object;
-}
+  /** All registered methods. */
+  get methods(): Record<
+    string,
+    RpcEndpoint.JSONRPCHandler<C> | RpcEndpoint.MethodConfig<C>
+  >;
 
-/**
- * JSON-RPC error object
- */
-interface JSONRPCError {
-  code: number;
-  message: string;
-  data?: any;
-}
+  get logger(): RpcEndpoint.Logger;
+  get middleware(): RpcEndpoint.MiddlewareManager;
+  get validator(): RpcEndpoint.SchemaValidator;
+  get options(): RpcEndpoint.RpcEndpointOptions;
 
-/**
- * JSON-RPC response payload
- */
-interface JSONRPCResponsePayload {
-  id?: string | number | null;
-  result?: any;
-  error?: JSONRPCError;
-}
+  addMethod(name: string, handler: RpcEndpoint.JSONRPCHandler<C>): void;
+  addMethod(
+    name: string,
+    handler: RpcEndpoint.JSONRPCHandler<C>,
+    schemaOrOptions: object
+  ): void;
+  addMethod(name: string, config: RpcEndpoint.MethodConfig<C>): void;
 
-/**
- * Logging configuration
- */
-interface LoggingConfig {
-  level?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
-  format?: 'json' | 'simple';
-  transports?: Array<'console' | 'file'>;
-  file?: {
-    filename?: string;
-    maxsize?: number;
-    maxFiles?: number;
-  };
-}
+  use(hook: RpcEndpoint.MiddlewareHook, middleware: Function): void;
 
-/**
- * CORS configuration
- */
-interface CorsConfig {
-  origin?: string | string[] | boolean;
-  credentials?: boolean;
-  methods?: string[];
-  allowedHeaders?: string[];
-}
+  removeMethod(name: string): void;
+  getMethod(
+    name: string
+  ): RpcEndpoint.JSONRPCHandler<C> | RpcEndpoint.MethodConfig<C> | undefined;
+  listMethods(): string[];
+  getMetrics(): object;
 
-/**
- * Rate limiting configuration
- */
-interface RateLimitConfig {
-  windowMs?: number;
-  max?: number;
-  message?: string;
-  standardHeaders?: boolean;
-  legacyHeaders?: boolean;
-}
+  static serveScripts(router: Router, url?: string): void;
 
-/**
- * Authentication verifier. Return a truthy value to allow the call.
- */
-type AuthConfig = (req: Request) => boolean | Promise<boolean>;
+  reply(
+    res: Response,
+    responsePayload: RpcEndpoint.JSONRPCResponsePayload
+  ): void;
 
-/**
- * Schema validation configuration
- */
-interface ValidationConfig {
-  strict?: boolean;
-  coerceTypes?: boolean;
-  removeAdditional?: boolean;
+  serializeBigIntsAndDates(value: any): any;
+  deserializeBigIntsAndDates(
+    value: any,
+    options?: RpcEndpoint.DeserializationOptions
+  ): any;
 }
 
 /**
- * RPC endpoint configuration options
+ * Public properties and types attached to the CommonJS export.
  */
-interface RpcEndpointOptions {
-  prefix?: string;
-  maxBodySize?: string;
-  timeout?: number;
-  cors?: boolean | CorsConfig;
-  auth?: AuthConfig;
-  validation?: ValidationConfig;
-  safeEnabled?: boolean;
-  crossConfigurationEnabled?: boolean;
-  enableSchema?: boolean;
-  rateLimit?: RateLimitConfig;
-  logging?: LoggingConfig;
-  warnOnUnsafe?: boolean;
-  strictMode?: boolean;
-  maxSerializationDepth?: number;
-  maxDeserializationDepth?: number;
-  autoJsonMiddleware?: boolean;
-  jsonOptions?: {
-    limit?: string;
-    strict?: boolean;
-    type?: string | string[] | ((req: any) => boolean);
-    verify?: (req: any, res: any, buf: Buffer, encoding: string) => void;
+declare namespace RpcEndpoint {
+  // module.exports.RpcEndpoint === module.exports
+  export { RpcEndpoint };
+
+  // Classes re-exported from rpc-toolkit-js-client.
+  export {
+    SharedRpcClient as RpcClient,
+    SharedRpcError as RpcError,
+    SharedRpcHttpError as RpcHttpError,
+    SharedRpcSafeClient as RpcSafeClient,
   };
-  // Additional options supported by implementation
-  methodWhitelist?: string[];
-  timing?: boolean;
-  metrics?: boolean;
-  healthCheck?: boolean;
-}
-
-/**
- * RPC client configuration options
- */
-type RpcClientOptions = SharedRpcClientOptions;
-type RpcBatchRequest = SharedRpcBatchRequest;
-type RpcClient = SharedRpcClient;
-type RpcError = SharedRpcError;
-type RpcHttpError = SharedRpcHttpError;
-type RpcSafeClient = SharedRpcSafeClient;
-
-declare const RpcClient: typeof SharedRpcClient;
-declare const RpcError: typeof SharedRpcError;
-declare const RpcHttpError: typeof SharedRpcHttpError;
-declare const RpcSafeClient: typeof SharedRpcSafeClient;
-
-/**
- * Deserialization options for safe prefixes
- */
-interface DeserializationOptions {
-  safeEnabled?: boolean;
-}
-
-/**
- * The main RpcEndpoint class for JSON-RPC 2.0 endpoints.
- */
-declare class RpcEndpoint<C = any> {
-  /**
-   * Constructor.
-   */
-  constructor(router: Router, context: C, endpoint?: string);
-  constructor(router: Router, context: C, options?: RpcEndpointOptions);
-  constructor(router: Router, context: C, endpoint?: string, options?: RpcEndpointOptions);
-
-  /**
-   * Returns the endpoint path, e.g. "/api".
-   */
-  get endpoint(): string;
 
-  /**
-   * Returns the map of all registered methods.
-   */
-  get methods(): { [methodName: string]: JSONRPCHandler<C> | MethodConfig<C> };
-
-  /**
-   * Get logger instance
-   */
-  get logger(): any;
-
-  /**
-   * Get middleware manager
-   */
-  get middleware(): any;
-
-  /**
-   * Get validator instance
-   */
-  get validator(): any;
-
-  /**
-   * Add a JSON-RPC method with optional schema validation.
-   */
-  addMethod(name: string, handler: JSONRPCHandler<C>): void;
-  addMethod(name: string, handler: JSONRPCHandler<C>, schema: object): void;
-  addMethod(name: string, config: MethodConfig<C>): void;
-
-  /**
-   * Add middleware for specific hooks
-   */
-  use(hook: 'beforeCall' | 'afterCall' | 'onError' | 'beforeValidation' | 'afterValidation', middleware: Function): void;
+  /** JSON-RPC handler function. */
+  export type JSONRPCHandler<C> = (
+    req: Request,
+    context: C,
+    params: any
+  ) => any | Promise<any>;
+
+  /** Method configuration object. */
+  export interface MethodConfig<C> {
+    handler: JSONRPCHandler<C>;
+    schema?: object;
+    exposeSchema?: boolean;
+    description?: string;
+  }
+
+  /** JSON-RPC error object. */
+  export interface JSONRPCError {
+    code: number;
+    message: string;
+    data?: any;
+  }
+
+  /** JSON-RPC response payload. */
+  export interface JSONRPCResponsePayload {
+    id?: string | number | null;
+    result?: any;
+    error?: JSONRPCError;
+  }
+
+  export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+
+  /** Logging configuration. */
+  export interface LoggingConfig {
+    level?: LogLevel;
+    enabled?: boolean;
+    prefix?: string;
+    logger?: Partial<
+      Record<LogLevel, (entry: Record<string, unknown>) => void>
+    >;
+    format?: 'json' | 'simple';
+    transports?: Array<'console' | 'file'>;
+    file?: {
+      filename?: string;
+      maxsize?: number;
+      maxFiles?: number;
+    };
+  }
+
+  /** CORS configuration. */
+  export interface CorsConfig {
+    origin?: string | string[] | boolean;
+    credentials?: boolean;
+    methods?: string[];
+    allowedHeaders?: string[];
+    headers?: string[];
+  }
+
+  /** Rate limiting configuration. */
+  export interface RateLimitConfig {
+    windowMs?: number;
+    max?: number;
+    message?: string;
+    standardHeaders?: boolean;
+    legacyHeaders?: boolean;
+  }
+
+  /** Authentication verifier. Return a truthy value to allow the call. */
+  export type AuthConfig = (req: Request) => boolean | Promise<boolean>;
+
+  /** Schema validation configuration. */
+  export interface ValidationConfig {
+    strict?: boolean;
+    coerceTypes?: boolean;
+    removeAdditional?: boolean;
+    useDefaults?: boolean;
+    ajvOptions?: Record<string, unknown>;
+  }
+
+  /** RPC endpoint configuration options. */
+  export interface RpcEndpointOptions {
+    endpoint?: string;
+    prefix?: string;
+    maxBodySize?: string;
+    timeout?: number;
+    cors?: boolean | CorsConfig;
+    auth?: AuthConfig;
+    validation?: ValidationConfig;
+    safeEnabled?: boolean;
+    crossConfigurationEnabled?: boolean;
+    enableSchema?: boolean;
+    rateLimit?: RateLimitConfig;
+    logging?: LoggingConfig;
+    warnOnUnsafe?: boolean;
+    strictMode?: boolean;
+    maxSerializationDepth?: number;
+    maxDeserializationDepth?: number;
+    autoJsonMiddleware?: boolean;
+    jsonOptions?: {
+      limit?: string;
+      strict?: boolean;
+      type?: string | string[] | ((req: any) => boolean);
+      verify?: (req: any, res: any, buf: Buffer, encoding: string) => void;
+    };
+    methodWhitelist?: string[];
+    timing?: boolean;
+    metrics?: boolean;
+    healthCheck?: boolean;
+    enableIntrospection?: boolean;
+    introspectionPrefix?: string;
+  }
+
+  /** RPC client configuration options. */
+  export type RpcClientOptions = SharedRpcClientOptions;
+  export type RpcBatchRequest = SharedRpcBatchRequest;
+
+  /** Deserialization options for safe prefixes. */
+  export interface DeserializationOptions {
+    safeEnabled?: boolean;
+  }
+
+  export type MiddlewareHook =
+    | 'beforeCall'
+    | 'afterCall'
+    | 'onError'
+    | 'beforeValidation'
+    | 'afterValidation';
+
+  export interface MiddlewareContext<C = any> {
+    req?: Request;
+    res?: Response | null;
+    context?: C;
+    method?: string;
+    params?: any;
+    result?: any;
+    error?: any;
+    batchIndex?: number;
+    isNotification?: boolean;
+    startTime?: number;
+    [key: string]: any;
+  }
+
+  export type Middleware = (context: MiddlewareContext) => any | Promise<any>;
+
+  export interface RpcMetrics {
+    methods: number;
+    middleware: {
+      beforeCall: number;
+      afterCall: number;
+      onError: number;
+    };
+    uptime: number;
+    memory: Record<string, number>;
+    timestamp: string;
+  }
 
   /**
-   * Remove a method
+   * Utility helpers were historically exposed as `any`. Keep their instance
+   * contracts permissive in this patch while still publishing value/type names.
    */
-  removeMethod(name: string): void;
+  export type Logger = any;
+  export const Logger: {
+    new (...args: any[]): Logger;
+  };
 
-  /**
-   * Get method configuration
-   */
-  getMethod(name: string): JSONRPCHandler<C> | MethodConfig<C> | undefined;
+  export type MiddlewareManager = any;
+  export const MiddlewareManager: {
+    new (...args: any[]): MiddlewareManager;
+  };
 
-  /**
-   * List all registered methods
-   */
-  listMethods(): string[];
+  export const builtInMiddlewares: any;
 
-  /**
-   * Get metrics data
-   */
-  getMetrics(): object;
+  export interface SchemaValidationResult<T = any> {
+    valid: boolean;
+    errors: any[] | null;
+    data: T;
+  }
 
-  /**
-   * Serve client scripts (for calling JSON-RPC from browser).
-   */
-  static serveScripts(router: Router, url?: string): void;
+  export type SchemaValidator = any;
+  export const SchemaValidator: {
+    new (...args: any[]): SchemaValidator;
+  };
 
-  /**
-   * Send a JSON-RPC 2.0 response to the client.
-   */
-  reply(res: Response, responsePayload: JSONRPCResponsePayload): void;
+  export const commonSchemas: any;
 
-  /**
-   * Recursively serialize BigInt and Date to JSON-safe string formats.
-   */
-  serializeBigIntsAndDates(value: any): any;
+  export type SchemaBuilder = any;
+  export const SchemaBuilder: {
+    new (...args: any[]): SchemaBuilder;
+  };
 
-  /**
-   * Recursively deserialize strings representing BigInt and Date.
-   */
-  deserializeBigIntsAndDates(value: any, options?: DeserializationOptions): any;
+  export type BatchHandler = any;
+  export const BatchHandler: {
+    new (...args: any[]): BatchHandler;
+  };
 }
 
-/**
- * Export types for external use
- */
-export {
-  JSONRPCHandler,
-  MethodConfig,
-  JSONRPCError,
-  JSONRPCResponsePayload,
-  LoggingConfig,
-  CorsConfig,
-  RateLimitConfig,
-  AuthConfig,
-  ValidationConfig,
-  RpcEndpointOptions,
-  RpcClientOptions,
-  RpcBatchRequest,
-  DeserializationOptions,
-  RpcEndpoint,
-  RpcClient,
-  RpcError,
-  RpcHttpError,
-  RpcSafeClient
-};
-
-/**
- * Main export - RpcEndpoint class with static properties
- */
-declare const Main: {
-  new <C>(router: Router, context: C, endpoint?: string): RpcEndpoint<C>;
-  new <C>(router: Router, context: C, options?: RpcEndpointOptions): RpcEndpoint<C>;
-  new <C>(router: Router, context: C, endpoint?: string, options?: RpcEndpointOptions): RpcEndpoint<C>;
-  prototype: RpcEndpoint<any>;
-  serveScripts(router: Router, url?: string): void;
-  RpcEndpoint: typeof RpcEndpoint;
-  RpcClient: typeof RpcClient;
-  RpcError: typeof RpcError;
-  RpcHttpError: typeof RpcHttpError;
-  RpcSafeClient: typeof RpcSafeClient;
-  Logger: any;
-  MiddlewareManager: any;
-  builtInMiddlewares: any;
-  SchemaValidator: any;
-  commonSchemas: any;
-  SchemaBuilder: any;
-  BatchHandler: any;
-};
-
-export = Main;
+export = RpcEndpoint;

package/src/index.js

@@ -288,21 +288,23 @@ class RpcEndpoint {
     this.addMethod(
       `${this.#introspectionPrefix}.describeAll`,
       async (_req, _context, _params) => {
-        const publicMethods = [];
+        const publicMethods = Object.entries(this.#methods)
+          .filter(([name]) => !name.startsWith(this.#introspectionPrefix))
+          .map(([name, methodConfig]) => {
+            const config =
+              typeof methodConfig === 'function' ? {} : methodConfig;
 
-        for (const [name, methodConfig] of Object.entries(this.#methods)) {
-          // Skip introspection methods
-          if (name.startsWith(this.#introspectionPrefix)) continue;
+            if (!config.exposeSchema) {
+              return null;
+            }
 
-          const config = typeof methodConfig === 'function' ? {} : methodConfig;
-          if (config.exposeSchema) {
-            publicMethods.push({
+            return {
               name,
               schema: config.schema || null,
               description: config.description || '',
-            });
-          }
-        }
+            };
+          })
+          .filter(Boolean);
 
         return publicMethods;
       },
@@ -1156,3 +1158,6 @@ module.exports.SchemaValidator = SchemaValidator;
 module.exports.commonSchemas = commonSchemas;
 module.exports.SchemaBuilder = SchemaBuilder;
 module.exports.BatchHandler = BatchHandler;
+// Keep the existing static method discoverable as a named export to Node's
+// CommonJS lexer without changing the RpcEndpoint object or its descriptor.
+module.exports.serveScripts = RpcEndpoint.serveScripts;

package/src/safe.d.ts

@@ -1,63 +1,91 @@
 import type { Router } from 'express';
-import type { RpcEndpoint, RpcClient, RpcEndpointOptions, RpcClientOptions } from './index';
+import Main = require('./index');
 
 /**
- * RPC Client with safe serialization enabled by default.
- * Extends RpcClient with safeEnabled: true preset.
+ * Public properties attached to the CommonJS safe preset export.
  */
-export class RpcSafeClient extends RpcClient {
-  constructor(
-    endpoint: string,
-    defaultHeaders?: Record<string, string>,
-    options?: RpcClientOptions
-  );
-}
+declare namespace Safe {
+  // Root values re-exported by src/safe.js.
+  export import RpcEndpoint = Main;
+  export import RpcClient = Main.RpcClient;
+  export import RpcError = Main.RpcError;
+  export import RpcHttpError = Main.RpcHttpError;
+  export import Logger = Main.Logger;
+  export import MiddlewareManager = Main.MiddlewareManager;
+  export import builtInMiddlewares = Main.builtInMiddlewares;
+  export import SchemaValidator = Main.SchemaValidator;
+  export import commonSchemas = Main.commonSchemas;
+  export import SchemaBuilder = Main.SchemaBuilder;
+  export import BatchHandler = Main.BatchHandler;
 
-/**
- * RPC Endpoint with safe serialization enabled by default.
- * Extends RpcEndpoint with safeEnabled: true and strictMode: true presets.
- */
-export class RpcSafeEndpoint<C = any> extends RpcEndpoint<C> {
-  constructor(
+  // Root public types previously re-exported by `export *`.
+  export import JSONRPCHandler = Main.JSONRPCHandler;
+  export import MethodConfig = Main.MethodConfig;
+  export import JSONRPCError = Main.JSONRPCError;
+  export import JSONRPCResponsePayload = Main.JSONRPCResponsePayload;
+  export import LogLevel = Main.LogLevel;
+  export import LoggingConfig = Main.LoggingConfig;
+  export import CorsConfig = Main.CorsConfig;
+  export import RateLimitConfig = Main.RateLimitConfig;
+  export import AuthConfig = Main.AuthConfig;
+  export import ValidationConfig = Main.ValidationConfig;
+  export import RpcEndpointOptions = Main.RpcEndpointOptions;
+  export import RpcClientOptions = Main.RpcClientOptions;
+  export import RpcBatchRequest = Main.RpcBatchRequest;
+  export import DeserializationOptions = Main.DeserializationOptions;
+  export import MiddlewareHook = Main.MiddlewareHook;
+  export import MiddlewareContext = Main.MiddlewareContext;
+  export import Middleware = Main.Middleware;
+  export import RpcMetrics = Main.RpcMetrics;
+  export import SchemaValidationResult = Main.SchemaValidationResult;
+
+  /**
+   * RPC client with safe serialization enabled by default.
+   */
+  export class RpcSafeClient extends Main.RpcClient {
+    constructor(
+      endpoint: string,
+      defaultHeaders?: Record<string, string>,
+      options?: Main.RpcClientOptions
+    );
+  }
+
+  /**
+   * RPC endpoint with safe serialization and strict mode enabled by default.
+   */
+  export class RpcSafeEndpoint<C = any> extends Main<C> {
+    constructor(
+      router: Router,
+      context: C,
+      endpoint?: string,
+      options?: Main.RpcEndpointOptions
+    );
+    constructor(router: Router, context: C, options?: Main.RpcEndpointOptions);
+  }
+
+  /**
+   * @deprecated Use `new RpcSafeEndpoint(...)` instead.
+   */
+  export function createSafeEndpoint<C = any>(
     router: Router,
     context: C,
     endpoint?: string,
-    options?: RpcEndpointOptions
-  );
-  
-  constructor(
+    options?: Main.RpcEndpointOptions
+  ): RpcSafeEndpoint<C>;
+  export function createSafeEndpoint<C = any>(
     router: Router,
     context: C,
-    options?: RpcEndpointOptions
-  );
-}
+    options?: Main.RpcEndpointOptions
+  ): RpcSafeEndpoint<C>;
 
-/**
- * @deprecated Use `new RpcSafeEndpoint(...)` instead.
- * Factory: create a RpcEndpoint with safe defaults (safeEnabled=true, strictMode=true).
- */
-export function createSafeEndpoint<C = any>(
-  router: Router,
-  context: C,
-  endpoint?: string,
-  options?: RpcEndpointOptions
-): RpcEndpoint<C>;
-
-export function createSafeEndpoint<C = any>(
-  router: Router,
-  context: C,
-  options?: RpcEndpointOptions
-): RpcEndpoint<C>;
-
-/**
- * @deprecated Use `new RpcSafeClient(...)` instead.
- * Factory: create a RpcClient with safe defaults (safeEnabled=true).
- */
-export function createSafeClient(
-  endpoint: string,
-  defaultHeaders?: Record<string, string>,
-  options?: RpcClientOptions
-): RpcClient;
-
-export * from './index';
+  /**
+   * @deprecated Use `new RpcSafeClient(...)` instead.
+   */
+  export function createSafeClient(
+    endpoint: string,
+    defaultHeaders?: Record<string, string>,
+    options?: Main.RpcClientOptions
+  ): RpcSafeClient;
+}
 
+export = Safe;

package/src/safe.js

@@ -110,3 +110,17 @@ module.exports = {
   createSafeEndpoint,
   createSafeClient,
 };
+
+// Make spread-based root re-exports visible to Node's CommonJS named-export
+// detection. These assignments preserve the existing object values and order.
+module.exports.RpcEndpoint = Main.RpcEndpoint;
+module.exports.RpcClient = Main.RpcClient;
+module.exports.RpcError = Main.RpcError;
+module.exports.RpcHttpError = Main.RpcHttpError;
+module.exports.Logger = Main.Logger;
+module.exports.MiddlewareManager = Main.MiddlewareManager;
+module.exports.builtInMiddlewares = Main.builtInMiddlewares;
+module.exports.SchemaValidator = Main.SchemaValidator;
+module.exports.commonSchemas = Main.commonSchemas;
+module.exports.SchemaBuilder = Main.SchemaBuilder;
+module.exports.BatchHandler = Main.BatchHandler;