rpc-express-toolkit 4.1.0 → 4.2.0

package/README.md

@@ -5,6 +5,7 @@
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)
 [![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)
 
 Enterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, middleware, schema validation, batch support, and optional safe type disambiguation.
 
@@ -61,6 +62,9 @@ Safe type disambiguation is disabled by default for maximum JSON-RPC 2.0 compati
 
 ### Safe Import (opt-in)
 
+[![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):
 
 ```js
@@ -80,6 +84,27 @@ const client = createSafeClient('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
+
+If you prefer a dedicated package name, you can install the thin proxy `rpc-express-toolkit-safe` which simply re-exports the safe preset:
+
+```bash
+npm install rpc-express-toolkit-safe
+```
+
+```js
+// Server
+const express = require('express');
+const { createSafeEndpoint } = require('rpc-express-toolkit-safe');
+const app = express();
+app.use(express.json());
+const rpc = createSafeEndpoint(app, {}, { endpoint: '/api' });
+
+// Client
+const { createSafeClient } = require('rpc-express-toolkit-safe');
+const client = createSafeClient('http://localhost:3000/api');
+```
+
 ## Full Details
 
 For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.

package/examples/safe-preset-example.js

@@ -1,6 +1,6 @@
 const express = require('express');
 /* eslint-disable import/no-unresolved, prettier/prettier */
-const { createSafeEndpoint, createSafeClient } = require('rpc-express-toolkit/safe');
+const { RpcSafeEndpoint, RpcSafeClient } = require('rpc-express-toolkit/safe');
 /* eslint-enable import/no-unresolved, prettier/prettier */
 
 async function main() {
@@ -8,7 +8,7 @@ async function main() {
   app.use(express.json());
 
   // Server with safe defaults (safeEnabled=true, strictMode=true)
-  const rpc = createSafeEndpoint(app, {}, { endpoint: '/api' });
+  const rpc = new RpcSafeEndpoint(app, {}, { endpoint: '/api' });
 
   rpc.addMethod('sum', (req, ctx, params) => {
     // params are already deserialized according to the client's safe header
@@ -29,7 +29,7 @@ async function main() {
     console.log('Safe server listening on', url);
 
     // Safe client (sends header and expects safe response)
-    const client = createSafeClient(url);
+    const client = new RpcSafeClient(url);
     const res = await client.call('sum', { a: '10n', b: '32n' });
     console.log('sum result (BigInt):', res.toString());
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "rpc-express-toolkit",
-    "version":  "4.1.0",
+    "version":  "4.2.0",
     "description":  "Enterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, structured logging, middleware system, schema validation, comprehensive BigInt/Date support. JSON middleware validation and explicit configuration.",
     "main":  "src/index.js",
     "types":  "src/index.d.ts",

package/src/safe.d.ts

@@ -2,6 +2,38 @@ import type { Router } from 'express';
 import type { RpcEndpoint, RpcClient, RpcEndpointOptions, RpcClientOptions } from './index';
 
 /**
+ * RPC Client with safe serialization enabled by default.
+ * Extends RpcClient with safeEnabled: true preset.
+ */
+export class RpcSafeClient extends RpcClient {
+  constructor(
+    endpoint: string,
+    defaultHeaders?: Record<string, string>,
+    options?: RpcClientOptions
+  );
+}
+
+/**
+ * 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(
+    router: Router,
+    context: C,
+    endpoint?: string,
+    options?: RpcEndpointOptions
+  );
+  
+  constructor(
+    router: Router,
+    context: C,
+    options?: RpcEndpointOptions
+  );
+}
+
+/**
+ * @deprecated Use `new RpcSafeEndpoint(...)` instead.
  * Factory: create a RpcEndpoint with safe defaults (safeEnabled=true, strictMode=true).
  */
 export function createSafeEndpoint<C = any>(
@@ -18,6 +50,7 @@ export function createSafeEndpoint<C = any>(
 ): RpcEndpoint<C>;
 
 /**
+ * @deprecated Use `new RpcSafeClient(...)` instead.
  * Factory: create a RpcClient with safe defaults (safeEnabled=true).
  */
 export function createSafeClient(

package/src/safe.js

@@ -1,14 +1,72 @@
+/* eslint-disable max-classes-per-file */
 const Main = require('./index');
 
-// Default safe options applied unless explicitly overridden
-const defaultSafeOptions = {
-  safeEnabled: true,
-  strictMode: true,
-};
+/**
+ * RPC Client with safe serialization enabled by default.
+ * Extends RpcClient with safeEnabled: true preset.
+ *
+ * This class automatically enables safe prefixes for strings (S:) and dates (D:)
+ * to avoid ambiguity with BigInt and ISO date strings.
+ *
+ * @example
+ * const client = new RpcSafeClient('http://localhost:3000/api');
+ * const result = await client.call('add', { a: 10n, b: 20n });
+ */
+class RpcSafeClient extends Main.RpcClient {
+  /**
+   * @param {string} endpoint The JSON-RPC endpoint URL.
+   * @param {Object} [defaultHeaders={}] Optional default headers to include in requests.
+   * @param {Object} [options={}] Optional configuration options (safeEnabled will be set to true).
+   */
+  constructor(endpoint, defaultHeaders = {}, options = {}) {
+    super(endpoint, defaultHeaders, { safeEnabled: true, ...options });
+  }
+}
+
+/**
+ * RPC Endpoint with safe serialization enabled by default.
+ * Extends RpcEndpoint with safeEnabled: true and strictMode: true presets.
+ *
+ * This class automatically enables safe prefixes for strings (S:) and dates (D:)
+ * and enforces strict compatibility checking with clients.
+ *
+ * @example
+ * const app = express();
+ * const rpc = new RpcSafeEndpoint(app, {});
+ * rpc.addMethod('add', {
+ *   handler: (req, ctx, params) => params.a + params.b,
+ * });
+ *
+ * @template C
+ */
+class RpcSafeEndpoint extends Main.RpcEndpoint {
+  /**
+   * @param {import('express').Router} router Express router or app
+   * @param {C} context Context object passed to handlers
+   * @param {string|object} [endpointOrOptions='/api'] Endpoint path or options object
+   * @param {object} [options] Options object (when endpointOrOptions is a string)
+   */
+  constructor(router, context, endpointOrOptions = '/api', options = {}) {
+    const defaultSafeOptions = {
+      safeEnabled: true,
+      strictMode: true,
+    };
+
+    if (typeof endpointOrOptions === 'string') {
+      // String endpoint with options object
+      const finalOptions = { ...defaultSafeOptions, ...options };
+      super(router, context, endpointOrOptions, finalOptions);
+    } else {
+      // Options object form
+      const finalOptions = { ...defaultSafeOptions, ...endpointOrOptions };
+      super(router, context, finalOptions);
+    }
+  }
+}
 
 /**
+ * @deprecated Use `new RpcSafeEndpoint(...)` instead.
  * Create a RpcEndpoint with safe defaults (safeEnabled=true, strictMode=true).
- * Preserves both constructor signatures supported by RpcEndpoint.
  *
  * @param {import('express').Router} router
  * @param {any} context
@@ -21,34 +79,34 @@ function createSafeEndpoint(
   endpointOrOptions = '/api',
   options = {}
 ) {
-  if (typeof endpointOrOptions === 'string') {
-    const finalOptions = { ...defaultSafeOptions, ...options };
-    return new Main.RpcEndpoint(
-      router,
-      context,
-      endpointOrOptions,
-      finalOptions
-    );
-  }
-  // options object form
-  const final = { ...defaultSafeOptions, ...endpointOrOptions };
-  return new Main.RpcEndpoint(router, context, final);
+  console.warn(
+    'createSafeEndpoint() is deprecated. Use `new RpcSafeEndpoint(...)` instead.'
+  );
+  return new RpcSafeEndpoint(router, context, endpointOrOptions, options);
 }
 
 /**
+ * @deprecated Use `new RpcSafeClient(...)` instead.
  * Create a RpcClient with safe defaults (safeEnabled=true).
+ *
  * @param {string} endpoint
  * @param {Record<string,string>} [defaultHeaders]
  * @param {object} [options]
  */
 function createSafeClient(endpoint, defaultHeaders = {}, options = {}) {
-  const finalOptions = { safeEnabled: true, ...options };
-  return new Main.RpcClient(endpoint, defaultHeaders, finalOptions);
+  console.warn(
+    'createSafeClient() is deprecated. Use `new RpcSafeClient(...)` instead.'
+  );
+  return new RpcSafeClient(endpoint, defaultHeaders, options);
 }
 
 module.exports = {
   // Re-export everything for convenience
   ...Main,
+  // New class-based API
+  RpcSafeClient,
+  RpcSafeEndpoint,
+  // Deprecated factory functions (kept for backward compatibility)
   createSafeEndpoint,
   createSafeClient,
 };