rpc-express-toolkit 3.0.2 → 4.0.1

package/src/clients/rpc-client.js

@@ -1,43 +1,28 @@
 /**
  * JSON-RPC 2.0 Client for browser and Node.js environments.
- * Handles BigInt and Date serialization/deserialization automatically.
- *
- * Note: We extend BigInt.prototype.toJSON to handle automatic serialization
- * when JSON.stringify() is called, as BigInt doesn't have native JSON support.
+ * Handles BigInt and Date serialization/deserialization automatically
+ * using explicit serializers (no global prototype extensions).
  */
 
-// Extend BigInt prototype to handle JSON serialization
-if (typeof BigInt !== 'undefined' && !BigInt.prototype.toJSON) {
-  BigInt.prototype.toJSON = function () {
-    return this.toString();
-  };
-}
-
-// Polyfill for Node.js environments that don't have fetch
+// Select fetch implementation (Node 18+ or browser)
 let fetchFn;
-if (typeof fetch !== 'undefined') {
-  fetchFn = fetch;
+if (typeof globalThis !== 'undefined' && globalThis.fetch) {
+  fetchFn = globalThis.fetch.bind(globalThis);
 } else {
-  // Try to use node-fetch if available, otherwise use built-in fetch in Node.js 18+
-  try {
-    fetchFn = require('node-fetch');
-  } catch (e) {
-    // For Node.js 18+, use global fetch
-    if (typeof globalThis !== 'undefined' && globalThis.fetch) {
-      fetchFn = globalThis.fetch;
-    } else {
-      throw new Error(
-        'fetch is not available. Please install node-fetch or use Node.js 18+'
-      );
-    }
-  }
+  throw new Error(
+    'globalThis.fetch is not available. Node.js 18+ is required.'
+  );
 }
 
 class RpcClient {
   #endpoint;
+
   #defaultHeaders;
+
   #requestId;
+
   #fetchOptions;
+
   #options;
 
   /**
@@ -45,8 +30,8 @@ class RpcClient {
    * @param {Object} [defaultHeaders={}] Optional default headers to include in requests.
    * @param {Object} [options={}] Optional configuration options.
    * @param {boolean} [options.rejectUnauthorized=true] Whether to reject unauthorized SSL certificates. Set to false for development with self-signed certificates.
-   * @param {boolean} [options.safeStringEnabled=true] Whether to prefix strings with 'S:' to avoid confusion with BigInt values.
-   * @param {boolean} [options.safeDateEnabled=true] Whether to prefix dates with 'D:' to avoid confusion with ISO string values.
+   * @param {boolean} [options.safeEnabled=false] Whether to use safe serialization for both strings and dates to avoid confusion with BigInt/ISO values. Default false for JSON-RPC 2.0 compliance.
+   * @param {boolean} [options.warnOnUnsafe=true] Whether to show educational warnings when BigInt/Date objects are serialized without safe mode. Default true.
    */
   constructor(endpoint, defaultHeaders = {}, options = {}) {
     this.#endpoint = endpoint;
@@ -59,11 +44,9 @@ class RpcClient {
 
     // Store options
     this.#options = {
-      safeStringEnabled: options.safeStringEnabled !== false, // Default true
-      safeDateEnabled: options.safeDateEnabled !== false, // Default true
-      warnOnUnsafeString: options.warnOnUnsafeString !== false, // Default true
-      warnOnUnsafeDate: options.warnOnUnsafeDate !== false, // Default true
-      ...options
+      safeEnabled: options.safeEnabled === true, // Default false
+      warnOnUnsafe: options.warnOnUnsafe !== false, // Default true
+      ...options,
     };
 
     // Store fetch options for Node.js environments
@@ -84,11 +67,12 @@ class RpcClient {
 
   /**
    * Make a JSON-RPC call to the server.
+   * @template T
    * @param {string} method The RPC method name.
    * @param {any} params The parameters to pass to the RPC method.
    * @param {string|number|null} [id] The request ID (auto-generated if not provided).
    * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
-   * @returns {Promise<any>} The result of the RPC call.
+   * @returns {Promise<T>} The result of the RPC call.
    */
   async call(method, params, id = undefined, overrideHeaders = {}) {
     // Auto-generate ID if not provided (null means notification)
@@ -110,13 +94,11 @@ class RpcClient {
         method: 'POST',
         headers: {
           ...this.#defaultHeaders,
-          // Add safe options headers so server knows what client expects
-          'X-RPC-SafeString-Enabled': this.#options.safeStringEnabled ? 'true' : 'false',
-          'X-RPC-SafeDate-Enabled': this.#options.safeDateEnabled ? 'true' : 'false',
+          // Add safe options header so server knows what client expects
+          'X-RPC-Safe-Enabled': this.#options.safeEnabled ? 'true' : 'false',
           ...overrideHeaders,
         },
-        // Since we have BigInt.prototype.toJSON, we don't need manual serialization
-        // JSON.stringify will handle BigInt and Date automatically
+        // Params are pre-serialized (BigInt/Date) via serializeBigIntsAndDates
         body: JSON.stringify(requestBody),
         ...this.#fetchOptions, // Include any additional fetch options (e.g., SSL settings)
       });
@@ -133,18 +115,42 @@ class RpcClient {
         throw responseBody.error;
       }
 
-      // Check server's safe options from response headers
-      const serverSafeStringEnabled = response.headers.get('X-RPC-SafeString-Enabled') === 'true';
-      const serverSafeDateEnabled = response.headers.get('X-RPC-SafeDate-Enabled') === 'true';
+      // Check server's safe options from response headers - strict compatibility checking
+      const serverSafeHeader = response.headers.get('X-RPC-Safe-Enabled');
+
+      // Errore rigoroso: se client ha safe enabled ma server non risponde con header
+      if (this.#options.safeEnabled && serverSafeHeader === null) {
+        throw new Error(
+          'RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). ' +
+            'This may indicate a version mismatch or non-toolkit server. ' +
+            'Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.'
+        );
+      }
+
+      // Warning: se client ha safe disabled ma server offre compatibilità
+      if (
+        !this.#options.safeEnabled &&
+        serverSafeHeader === 'true' &&
+        this.#options.warnOnUnsafe
+      ) {
+        console.warn(
+          '⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. ' +
+            'Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.'
+        );
+      }
+
+      const serverSafeEnabled = serverSafeHeader === 'true';
 
       // Create deserialization options based on server's configuration
       const deserializationOptions = {
-        safeStringEnabled: serverSafeStringEnabled,
-        safeDateEnabled: serverSafeDateEnabled
+        safeEnabled: serverSafeEnabled,
       };
 
       // Convert back BigInts and Dates in the result using server's options
-      return this.deserializeBigIntsAndDates(responseBody.result, deserializationOptions);
+      return this.deserializeBigIntsAndDates(
+        responseBody.result,
+        deserializationOptions
+      );
     } catch (error) {
       console.error('RPC call failed:', error);
       throw error;
@@ -164,9 +170,10 @@ class RpcClient {
 
   /**
    * Make multiple JSON-RPC calls in a single batch request.
+   * @template T
    * @param {Array<{method: string, params?: any, id?: string|number}>} requests Array of request objects.
    * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
-   * @returns {Promise<Array<any>>} Array of results in the same order as requests.
+   * @returns {Promise<Array<T>>} Array of results in the same order as requests.
    */
   async batch(requests, overrideHeaders = {}) {
     const batchRequests = requests.map((req) => {
@@ -187,11 +194,11 @@ class RpcClient {
         method: 'POST',
         headers: {
           ...this.#defaultHeaders,
-          // Add safe options headers so server knows what client expects
-          'X-RPC-SafeString-Enabled': this.#options.safeStringEnabled ? 'true' : 'false',
-          'X-RPC-SafeDate-Enabled': this.#options.safeDateEnabled ? 'true' : 'false',
+          // Add safe options header so server knows what client expects
+          'X-RPC-Safe-Enabled': this.#options.safeEnabled ? 'true' : 'false',
           ...overrideHeaders,
         },
+        // Params are pre-serialized per item
         body: JSON.stringify(batchRequests),
         ...this.#fetchOptions, // Include any additional fetch options (e.g., SSL settings)
       });
@@ -204,14 +211,35 @@ class RpcClient {
 
       const responseBody = await response.json();
 
-      // Check server's safe options from response headers
-      const serverSafeStringEnabled = response.headers.get('X-RPC-SafeString-Enabled') === 'true';
-      const serverSafeDateEnabled = response.headers.get('X-RPC-SafeDate-Enabled') === 'true';
+      // Check server's safe options from response headers - strict compatibility checking
+      const serverSafeHeader = response.headers.get('X-RPC-Safe-Enabled');
+
+      // Errore rigoroso: se client ha safe enabled ma server non risponde con header
+      if (this.#options.safeEnabled && serverSafeHeader === null) {
+        throw new Error(
+          'RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). ' +
+            'This may indicate a version mismatch or non-toolkit server. ' +
+            'Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.'
+        );
+      }
+
+      // Warning: se client ha safe disabled ma server offre compatibilità
+      if (
+        !this.#options.safeEnabled &&
+        serverSafeHeader === 'true' &&
+        this.#options.warnOnUnsafe
+      ) {
+        console.warn(
+          '⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. ' +
+            'Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.'
+        );
+      }
+
+      const serverSafeEnabled = serverSafeHeader === 'true';
 
       // Create deserialization options based on server's configuration
       const deserializationOptions = {
-        safeStringEnabled: serverSafeStringEnabled,
-        safeDateEnabled: serverSafeDateEnabled
+        safeEnabled: serverSafeEnabled,
       };
 
       // Handle batch response
@@ -220,15 +248,22 @@ class RpcClient {
           if (res.error) {
             throw res.error;
           }
-          return this.deserializeBigIntsAndDates(res.result, deserializationOptions);
+          return this.deserializeBigIntsAndDates(
+            res.result,
+            deserializationOptions
+          );
         });
-      } else {
-        // Single response in batch
-        if (responseBody.error) {
-          throw responseBody.error;
-        }
-        return [this.deserializeBigIntsAndDates(responseBody.result, deserializationOptions)];
       }
+      // Single response in batch
+      if (responseBody.error) {
+        throw responseBody.error;
+      }
+      return [
+        this.deserializeBigIntsAndDates(
+          responseBody.result,
+          deserializationOptions
+        ),
+      ];
     } catch (error) {
       console.error('Batch RPC call failed:', error);
       throw error;
@@ -244,21 +279,40 @@ class RpcClient {
   serializeBigIntsAndDates(value) {
     if (typeof value === 'bigint') {
       // Convert BigInt to string with 'n' suffix for proper deserialization
-      return value.toString() + 'n';
-    } else if (value instanceof Date) {
-      // Convert Date to ISO string with D: prefix if safeDateEnabled
+      return `${value.toString()}n`;
+    }
+    if (value instanceof Date) {
+      // Convert Date to ISO string with D: prefix if safeEnabled
       const isoString = value.toISOString();
-      return this.#options.safeDateEnabled ? `D:${isoString}` : isoString;
-    } else if (typeof value === 'string') {
-      // Add S: prefix if safeStringEnabled is true
-      if (this.#options.safeStringEnabled) {
-        return 'S:' + value;
+      if (this.#options.safeEnabled) {
+        return `D:${isoString}`;
+      }
+      // Show educational warning if enabled
+      if (this.#options.warnOnUnsafe) {
+        console.warn(
+          '⚠️  Date serialization: Using plain ISO string format for JSON-RPC 2.0 compliance. Date objects will be deserialized as strings on the receiving end. Consider enabling safeEnabled or using string timestamps for better type safety.'
+        );
+      }
+      return isoString;
+    }
+    if (typeof value === 'string') {
+      // Add S: prefix if safeEnabled is true
+      if (this.#options.safeEnabled) {
+        return `S:${value}`;
+      }
+      // Show educational warning if enabled and string could be confused with BigInt
+      if (this.#options.warnOnUnsafe && /^-?\d+n?$/.test(value)) {
+        console.warn(
+          `⚠️  String serialization: String "${value}" could be confused with BigInt. Consider enabling safeEnabled for disambiguation or use explicit typing.`
+        );
       }
       return value;
-    } else if (Array.isArray(value)) {
+    }
+    if (Array.isArray(value)) {
       // Recurse into arrays
       return value.map((v) => this.serializeBigIntsAndDates(v));
-    } else if (value && typeof value === 'object') {
+    }
+    if (value && typeof value === 'object') {
       // Recurse into plain objects
       const result = {};
       for (const [key, val] of Object.entries(value)) {
@@ -277,14 +331,14 @@ class RpcClient {
    *
    * @param {any} value The value to deserialize.
    * @param {Object} [options] Custom deserialization options (uses client options if not provided).
-   * @param {boolean} [options.safeStringEnabled] Whether to expect S: prefixed strings.
-   * @param {boolean} [options.safeDateEnabled] Whether to expect D: prefixed dates.
+   * @param {boolean} [options.safeEnabled] Whether to expect safe prefixes for strings and dates.
    * @returns {any}
    */
   deserializeBigIntsAndDates(value, options = null) {
     // Use provided options or fall back to client options
-    const safeStringEnabled = options ? options.safeStringEnabled : this.#options.safeStringEnabled;
-    const safeDateEnabled = options ? options.safeDateEnabled : this.#options.safeDateEnabled;
+    const safeEnabled = options
+      ? options.safeEnabled
+      : this.#options.safeEnabled;
 
     // More comprehensive ISO date regex that handles:
     // - UTC: 2023-01-01T12:00:00.000Z
@@ -295,17 +349,17 @@ class RpcClient {
 
     // 1. Check if it's a string that might be a BigInt, Date, or safe string
     if (typeof value === 'string') {
-      // Safe string check: if safeStringEnabled and starts with S:
-      if (safeStringEnabled && value.startsWith('S:')) {
+      // 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 safeDateEnabled and starts with D:
-      if (safeDateEnabled && value.startsWith('D:')) {
+      // 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 (!isNaN(date.getTime())) {
+        if (!Number.isNaN(date.getTime())) {
           return date;
         }
       }
@@ -315,12 +369,12 @@ class RpcClient {
       if (/^-?\d+n$/.test(value)) {
         return BigInt(value.slice(0, -1)); // Remove 'n' and convert
       }
-      
-      // Date check: matches an ISO 8601 string (only if safeDateEnabled is false)
-      if (!safeDateEnabled && ISO_DATE_REGEX.test(value)) {
+
+      // Date check: matches an ISO 8601 string (only if safeEnabled is false)
+      if (!safeEnabled && ISO_DATE_REGEX.test(value)) {
         const date = new Date(value);
         // Ensure it's valid
-        if (!isNaN(date.getTime())) {
+        if (!Number.isNaN(date.getTime())) {
           return date;
         }
       }
@@ -347,4 +401,3 @@ class RpcClient {
 }
 
 module.exports = RpcClient;
-module.exports.RpcClient = RpcClient;

package/src/clients/rpc-client.min.js

@@ -1 +1 @@
-let fetchFn;if("undefined"==typeof BigInt||BigInt.prototype.toJSON||(BigInt.prototype.toJSON=function(){return this.toString()}),"undefined"!=typeof fetch)fetchFn=fetch;else try{fetchFn=require("node-fetch")}catch(e){if("undefined"==typeof globalThis||!globalThis.fetch)throw new Error("fetch is not available. Please install node-fetch or use Node.js 18+");fetchFn=globalThis.fetch}class RpcClient{#e;#t;#n;#s;#a;constructor(e,t={},n={}){this.#e=e,this.#t={"Content-Type":"application/json",...t},this.#n=1e3*Date.now()+Math.floor(1e3*Math.random()),this.#a={safeStringEnabled:!1!==n.safeStringEnabled,safeDateEnabled:!1!==n.safeDateEnabled,warnOnUnsafeString:!1!==n.warnOnUnsafeString,warnOnUnsafeDate:!1!==n.warnOnUnsafeDate,...n},this.#s={}}#r(){return++this.#n}async call(e,t,n=void 0,s={}){const a={jsonrpc:"2.0",method:e,id:void 0===n?this.#r():n};null!=t&&(a.params=this.serializeBigIntsAndDates(t));try{const e=await fetchFn(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-SafeString-Enabled":this.#a.safeStringEnabled?"true":"false","X-RPC-SafeDate-Enabled":this.#a.safeDateEnabled?"true":"false",...s},body:JSON.stringify(a),...this.#s});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`);const t=await e.json();if(t.error)throw t.error;const n="true"===e.headers.get("X-RPC-SafeString-Enabled"),r={safeStringEnabled:n,safeDateEnabled:"true"===e.headers.get("X-RPC-SafeDate-Enabled")};return this.deserializeBigIntsAndDates(t.result,r)}catch(e){throw console.error("RPC call failed:",e),e}}async notify(e,t={},n={}){await this.call(e,t,null,n)}async batch(e,t={}){const n=e.map(e=>{const t={jsonrpc:"2.0",method:e.method,id:void 0!==e.id?e.id:this.#r()};return void 0!==e.params&&null!==e.params&&(t.params=this.serializeBigIntsAndDates(e.params)),t});try{const e=await fetchFn(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-SafeString-Enabled":this.#a.safeStringEnabled?"true":"false","X-RPC-SafeDate-Enabled":this.#a.safeDateEnabled?"true":"false",...t},body:JSON.stringify(n),...this.#s});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`);const s=await e.json(),a="true"===e.headers.get("X-RPC-SafeString-Enabled"),r={safeStringEnabled:a,safeDateEnabled:"true"===e.headers.get("X-RPC-SafeDate-Enabled")};if(Array.isArray(s))return s.map(e=>{if(e.error)throw e.error;return this.deserializeBigIntsAndDates(e.result,r)});if(s.error)throw s.error;return[this.deserializeBigIntsAndDates(s.result,r)]}catch(e){throw console.error("Batch RPC call failed:",e),e}}serializeBigIntsAndDates(e){if("bigint"==typeof e)return e.toString()+"n";if(e instanceof Date){const t=e.toISOString();return this.#a.safeDateEnabled?`D:${t}`:t}if("string"==typeof e)return this.#a.safeStringEnabled?"S:"+e:e;if(Array.isArray(e))return e.map(e=>this.serializeBigIntsAndDates(e));if(e&&"object"==typeof e){const t={};for(const[n,s]of Object.entries(e))t[n]=this.serializeBigIntsAndDates(s);return t}return e}deserializeBigIntsAndDates(e,t=null){const n=t?t.safeStringEnabled:this.#a.safeStringEnabled,s=t?t.safeDateEnabled:this.#a.safeDateEnabled,a=/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;if("string"==typeof e){if(n&&e.startsWith("S:"))return e.substring(2);if(s&&e.startsWith("D:")){const t=e.substring(2),n=new Date(t);if(!isNaN(n.getTime()))return n}if(/^-?\d+n$/.test(e))return BigInt(e.slice(0,-1));if(!s&&a.test(e)){const t=new Date(e);if(!isNaN(t.getTime()))return t}}return Array.isArray(e)?e.map(e=>this.deserializeBigIntsAndDates(e,t)):e&&"object"==typeof e?Object.fromEntries(Object.entries(e).map(([e,n])=>[e,this.deserializeBigIntsAndDates(n,t)])):e}}module.exports=RpcClient,module.exports.RpcClient=RpcClient;
+let fetchFn;if("undefined"==typeof globalThis||!globalThis.fetch)throw new Error("globalThis.fetch is not available. Node.js 18+ is required.");fetchFn=globalThis.fetch.bind(globalThis);class RpcClient{#e;#t;#i;#s;#n;constructor(e,t={},i={}){this.#e=e,this.#t={"Content-Type":"application/json",...t},this.#i=1e3*Date.now()+Math.floor(1e3*Math.random()),this.#n={safeEnabled:!0===i.safeEnabled,warnOnUnsafe:!1!==i.warnOnUnsafe,...i},this.#s={}}#a(){return++this.#i}async call(e,t,i=void 0,s={}){const n={jsonrpc:"2.0",method:e,id:void 0===i?this.#a():i};null!=t&&(n.params=this.serializeBigIntsAndDates(t));try{const e=await fetchFn(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-Safe-Enabled":this.#n.safeEnabled?"true":"false",...s},body:JSON.stringify(n),...this.#s});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`);const t=await e.json();if(t.error)throw t.error;const i=e.headers.get("X-RPC-Safe-Enabled");if(this.#n.safeEnabled&&null===i)throw new Error("RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). This may indicate a version mismatch or non-toolkit server. Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.");!this.#n.safeEnabled&&"true"===i&&this.#n.warnOnUnsafe&&console.warn("⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.");const a={safeEnabled:"true"===i};return this.deserializeBigIntsAndDates(t.result,a)}catch(e){throw console.error("RPC call failed:",e),e}}async notify(e,t={},i={}){await this.call(e,t,null,i)}async batch(e,t={}){const i=e.map(e=>{const t={jsonrpc:"2.0",method:e.method,id:void 0!==e.id?e.id:this.#a()};return void 0!==e.params&&null!==e.params&&(t.params=this.serializeBigIntsAndDates(e.params)),t});try{const e=await fetchFn(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-Safe-Enabled":this.#n.safeEnabled?"true":"false",...t},body:JSON.stringify(i),...this.#s});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`);const s=await e.json(),n=e.headers.get("X-RPC-Safe-Enabled");if(this.#n.safeEnabled&&null===n)throw new Error("RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). This may indicate a version mismatch or non-toolkit server. Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.");!this.#n.safeEnabled&&"true"===n&&this.#n.warnOnUnsafe&&console.warn("⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.");const a={safeEnabled:"true"===n};if(Array.isArray(s))return s.map(e=>{if(e.error)throw e.error;return this.deserializeBigIntsAndDates(e.result,a)});if(s.error)throw s.error;return[this.deserializeBigIntsAndDates(s.result,a)]}catch(e){throw console.error("Batch RPC call failed:",e),e}}serializeBigIntsAndDates(e){if("bigint"==typeof e)return`${e.toString()}n`;if(e instanceof Date){const t=e.toISOString();return this.#n.safeEnabled?`D:${t}`:(this.#n.warnOnUnsafe&&console.warn("⚠️  Date serialization: Using plain ISO string format for JSON-RPC 2.0 compliance. Date objects will be deserialized as strings on the receiving end. Consider enabling safeEnabled or using string timestamps for better type safety."),t)}if("string"==typeof e)return this.#n.safeEnabled?`S:${e}`:(this.#n.warnOnUnsafe&&/^-?\d+n?$/.test(e)&&console.warn(`⚠️  String serialization: String "${e}" could be confused with BigInt. Consider enabling safeEnabled for disambiguation or use explicit typing.`),e);if(Array.isArray(e))return e.map(e=>this.serializeBigIntsAndDates(e));if(e&&"object"==typeof e){const t={};for(const[i,s]of Object.entries(e))t[i]=this.serializeBigIntsAndDates(s);return t}return e}deserializeBigIntsAndDates(e,t=null){const i=t?t.safeEnabled:this.#n.safeEnabled,s=/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;if("string"==typeof e){if(i&&e.startsWith("S:"))return e.substring(2);if(i&&e.startsWith("D:")){const t=e.substring(2),i=new Date(t);if(!Number.isNaN(i.getTime()))return i}if(/^-?\d+n$/.test(e))return BigInt(e.slice(0,-1));if(!i&&s.test(e)){const t=new Date(e);if(!Number.isNaN(t.getTime()))return t}}return Array.isArray(e)?e.map(e=>this.deserializeBigIntsAndDates(e,t)):e&&"object"==typeof e?Object.fromEntries(Object.entries(e).map(([e,i])=>[e,this.deserializeBigIntsAndDates(i,t)])):e}}module.exports=RpcClient;

package/src/clients/rpc-client.min.mjs

@@ -1 +1 @@
-let e;if("undefined"==typeof BigInt||BigInt.prototype.toJSON||(BigInt.prototype.toJSON=function(){return this.toString()}),"undefined"!=typeof fetch)e=fetch;else try{e=require("node-fetch")}catch(t){if("undefined"==typeof globalThis||!globalThis.fetch)throw new Error("fetch is not available. Please install node-fetch or use Node.js 18+");e=globalThis.fetch}class t{#e;#t;#s;#r;#a;constructor(e,t={},s={}){this.#e=e,this.#t={"Content-Type":"application/json",...t},this.#s=1e3*Date.now()+Math.floor(1e3*Math.random()),this.#a={safeStringEnabled:!1!==s.safeStringEnabled,safeDateEnabled:!1!==s.safeDateEnabled,...s},this.#r={}}#i(){return++this.#s}async call(t,s,r=void 0,a={}){const i={jsonrpc:"2.0",method:t,id:void 0===r?this.#i():r};null!=s&&(i.params=this.serializeBigIntsAndDates(s));try{const t=await e(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-SafeString-Enabled":this.#a.safeStringEnabled?"true":"false","X-RPC-SafeDate-Enabled":this.#a.safeDateEnabled?"true":"false",...a},body:JSON.stringify(i),...this.#r});if(!t.ok)throw new Error(`HTTP Error: ${t.status} ${t.statusText}`);const s=await t.json();if(s.error)throw s.error;const r="true"===t.headers.get("X-RPC-SafeString-Enabled"),n={safeStringEnabled:r,safeDateEnabled:"true"===t.headers.get("X-RPC-SafeDate-Enabled")};return this.deserializeBigIntsAndDates(s.result,n)}catch(e){throw console.error("RPC call failed:",e),e}}async notify(e,t={},s={}){await this.call(e,t,null,s)}async batch(t,s={}){const r=t.map(e=>{const t={jsonrpc:"2.0",method:e.method,id:void 0!==e.id?e.id:this.#i()};return void 0!==e.params&&null!==e.params&&(t.params=this.serializeBigIntsAndDates(e.params)),t});try{const t=await e(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-SafeString-Enabled":this.#a.safeStringEnabled?"true":"false","X-RPC-SafeDate-Enabled":this.#a.safeDateEnabled?"true":"false",...s},body:JSON.stringify(r),...this.#r});if(!t.ok)throw new Error(`HTTP Error: ${t.status} ${t.statusText}`);const a=await t.json(),i="true"===t.headers.get("X-RPC-SafeString-Enabled"),n={safeStringEnabled:i,safeDateEnabled:"true"===t.headers.get("X-RPC-SafeDate-Enabled")};if(Array.isArray(a))return a.map(e=>{if(e.error)throw e.error;return this.deserializeBigIntsAndDates(e.result,n)});if(a.error)throw a.error;return[this.deserializeBigIntsAndDates(a.result,n)]}catch(e){throw console.error("Batch RPC call failed:",e),e}}serializeBigIntsAndDates(e){if("bigint"==typeof e)return e.toString()+"n";if(e instanceof Date){const t=e.toISOString();return this.#a.safeDateEnabled?`D:${t}`:t}if("string"==typeof e)return this.#a.safeStringEnabled?"S:"+e:e;if(Array.isArray(e))return e.map(e=>this.serializeBigIntsAndDates(e));if(e&&"object"==typeof e){const t={};for(const[s,r]of Object.entries(e))t[s]=this.serializeBigIntsAndDates(r);return t}return e}deserializeBigIntsAndDates(e,t=null){const s=t?t.safeStringEnabled:this.#a.safeStringEnabled,r=t?t.safeDateEnabled:this.#a.safeDateEnabled,a=/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;if("string"==typeof e){if(s&&e.startsWith("S:"))return e.substring(2);if(r&&e.startsWith("D:")){const t=e.substring(2),s=new Date(t);if(!isNaN(s.getTime()))return s}if(/^-?\d+n$/.test(e))return BigInt(e.slice(0,-1));if(!r&&a.test(e)){const t=new Date(e);if(!isNaN(t.getTime()))return t}}return Array.isArray(e)?e.map(e=>this.deserializeBigIntsAndDates(e,t)):e&&"object"==typeof e?Object.fromEntries(Object.entries(e).map(([e,s])=>[e,this.deserializeBigIntsAndDates(s,t)])):e}}export default t;export{t as RpcClient};
+let e;if("undefined"==typeof BigInt||BigInt.prototype.toJSON||(BigInt.prototype.toJSON=function(){return this.toString()}),"undefined"!=typeof fetch)e=fetch;else try{e=require("node-fetch")}catch(t){if("undefined"==typeof globalThis||!globalThis.fetch)throw new Error("fetch is not available. Please install node-fetch or use Node.js 18+");e=globalThis.fetch}class t{#e;#t;#i;#s;#n;constructor(e,t={},i={}){this.#e=e,this.#t={"Content-Type":"application/json",...t},this.#i=1e3*Date.now()+Math.floor(1e3*Math.random()),this.#n={safeEnabled:!0===i.safeEnabled,warnOnUnsafe:!1!==i.warnOnUnsafe,...i},this.#s={}}#r(){return++this.#i}async call(t,i,s=void 0,n={}){const r={jsonrpc:"2.0",method:t,id:void 0===s?this.#r():s};null!=i&&(r.params=this.serializeBigIntsAndDates(i));try{const t=await e(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-Safe-Enabled":this.#n.safeEnabled?"true":"false",...n},body:JSON.stringify(r),...this.#s});if(!t.ok)throw new Error(`HTTP Error: ${t.status} ${t.statusText}`);const i=await t.json();if(i.error)throw i.error;const s=t.headers.get("X-RPC-Safe-Enabled");if(this.#n.safeEnabled&&null===s)throw new Error("RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). This may indicate a version mismatch or non-toolkit server. Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.");!this.#n.safeEnabled&&"true"===s&&this.#n.warnOnUnsafe&&console.warn("⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.");const a={safeEnabled:"true"===s};return this.deserializeBigIntsAndDates(i.result,a)}catch(e){throw console.error("RPC call failed:",e),e}}async notify(e,t={},i={}){await this.call(e,t,null,i)}async batch(t,i={}){const s=t.map(e=>{const t={jsonrpc:"2.0",method:e.method,id:void 0!==e.id?e.id:this.#r()};return void 0!==e.params&&null!==e.params&&(t.params=this.serializeBigIntsAndDates(e.params)),t});try{const t=await e(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-Safe-Enabled":this.#n.safeEnabled?"true":"false",...i},body:JSON.stringify(s),...this.#s});if(!t.ok)throw new Error(`HTTP Error: ${t.status} ${t.statusText}`);const n=await t.json(),r=t.headers.get("X-RPC-Safe-Enabled");if(this.#n.safeEnabled&&null===r)throw new Error("RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). This may indicate a version mismatch or non-toolkit server. Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.");!this.#n.safeEnabled&&"true"===r&&this.#n.warnOnUnsafe&&console.warn("⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.");const a={safeEnabled:"true"===r};if(Array.isArray(n))return n.map(e=>{if(e.error)throw e.error;return this.deserializeBigIntsAndDates(e.result,a)});if(n.error)throw n.error;return[this.deserializeBigIntsAndDates(n.result,a)]}catch(e){throw console.error("Batch RPC call failed:",e),e}}serializeBigIntsAndDates(e){if("bigint"==typeof e)return e.toString()+"n";if(e instanceof Date){const t=e.toISOString();return this.#n.safeEnabled?`D:${t}`:(this.#n.warnOnUnsafe&&console.warn("⚠️  Date serialization: Using plain ISO string format for JSON-RPC 2.0 compliance. Date objects will be deserialized as strings on the receiving end. Consider enabling safeEnabled or using string timestamps for better type safety."),t)}if("string"==typeof e)return this.#n.safeEnabled?"S:"+e:(this.#n.warnOnUnsafe&&/^-?\d+n?$/.test(e)&&console.warn(`⚠️  String serialization: String "${e}" could be confused with BigInt. Consider enabling safeEnabled for disambiguation or use explicit typing.`),e);if(Array.isArray(e))return e.map(e=>this.serializeBigIntsAndDates(e));if(e&&"object"==typeof e){const t={};for(const[i,s]of Object.entries(e))t[i]=this.serializeBigIntsAndDates(s);return t}return e}deserializeBigIntsAndDates(e,t=null){const i=t?t.safeEnabled:this.#n.safeEnabled,s=/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;if("string"==typeof e){if(i&&e.startsWith("S:"))return e.substring(2);if(i&&e.startsWith("D:")){const t=e.substring(2),i=new Date(t);if(!isNaN(i.getTime()))return i}if(/^-?\d+n$/.test(e))return BigInt(e.slice(0,-1));if(!i&&s.test(e)){const t=new Date(e);if(!isNaN(t.getTime()))return t}}return Array.isArray(e)?e.map(e=>this.deserializeBigIntsAndDates(e,t)):e&&"object"==typeof e?Object.fromEntries(Object.entries(e).map(([e,i])=>[e,this.deserializeBigIntsAndDates(i,t)])):e}}export default t;export{t as RpcClient};

package/src/clients/rpc-client.mjs

@@ -45,8 +45,8 @@ class RpcClient {
    * @param {Object} [defaultHeaders={}] Optional default headers to include in requests.
    * @param {Object} [options={}] Optional configuration options.
    * @param {boolean} [options.rejectUnauthorized=true] Whether to reject unauthorized SSL certificates. Set to false for development with self-signed certificates.
-   * @param {boolean} [options.safeStringEnabled=true] Whether to prefix strings with 'S:' to avoid confusion with BigInt values.
-   * @param {boolean} [options.safeDateEnabled=true] Whether to prefix dates with 'D:' to avoid confusion with ISO string values.
+   * @param {boolean} [options.safeEnabled=false] Whether to use safe serialization for both strings and dates to avoid confusion with BigInt/ISO values. Default false for JSON-RPC 2.0 compliance.
+   * @param {boolean} [options.warnOnUnsafe=true] Whether to show educational warnings when BigInt/Date objects are serialized without safe mode. Default true.
    */
   constructor(endpoint, defaultHeaders = {}, options = {}) {
     this.#endpoint = endpoint;
@@ -59,8 +59,8 @@ class RpcClient {
 
     // Store options
     this.#options = {
-      safeStringEnabled: options.safeStringEnabled !== false, // Default true
-      safeDateEnabled: options.safeDateEnabled !== false, // Default true
+      safeEnabled: options.safeEnabled === true, // Default false
+      warnOnUnsafe: options.warnOnUnsafe !== false, // Default true
       ...options
     };
 
@@ -82,11 +82,12 @@ class RpcClient {
 
   /**
    * Make a JSON-RPC call to the server.
+   * @template T
    * @param {string} method The RPC method name.
    * @param {any} params The parameters to pass to the RPC method.
    * @param {string|number|null} [id] The request ID (auto-generated if not provided).
    * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
-   * @returns {Promise<any>} The result of the RPC call.
+   * @returns {Promise<T>} The result of the RPC call.
    */
   async call(method, params, id = undefined, overrideHeaders = {}) {
     // Auto-generate ID if not provided (null means notification)
@@ -108,9 +109,8 @@ class RpcClient {
         method: 'POST',
         headers: {
           ...this.#defaultHeaders,
-          // Add safe options headers so server knows what client expects
-          'X-RPC-SafeString-Enabled': this.#options.safeStringEnabled ? 'true' : 'false',
-          'X-RPC-SafeDate-Enabled': this.#options.safeDateEnabled ? 'true' : 'false',
+          // Add safe options header so server knows what client expects
+          'X-RPC-Safe-Enabled': this.#options.safeEnabled ? 'true' : 'false',
           ...overrideHeaders,
         },
         // Since we have BigInt.prototype.toJSON, we don't need manual serialization
@@ -131,14 +131,31 @@ class RpcClient {
         throw responseBody.error;
       }
 
-      // Check server's safe options from response headers
-      const serverSafeStringEnabled = response.headers.get('X-RPC-SafeString-Enabled') === 'true';
-      const serverSafeDateEnabled = response.headers.get('X-RPC-SafeDate-Enabled') === 'true';
+      // Check server's safe options from response headers - strict compatibility checking
+      const serverSafeHeader = response.headers.get('X-RPC-Safe-Enabled');
+
+      // Errore rigoroso: se client ha safe enabled ma server non risponde con header
+      if (this.#options.safeEnabled && serverSafeHeader === null) {
+        throw new Error(
+          'RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). ' +
+          'This may indicate a version mismatch or non-toolkit server. ' +
+          'Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.'
+        );
+      }
+
+      // Warning: se client ha safe disabled ma server offre compatibilità
+      if (!this.#options.safeEnabled && serverSafeHeader === 'true' && this.#options.warnOnUnsafe) {
+        console.warn(
+          '⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. ' +
+          'Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.'
+        );
+      }
+
+      const serverSafeEnabled = serverSafeHeader === 'true';
 
       // Create deserialization options based on server's configuration
       const deserializationOptions = {
-        safeStringEnabled: serverSafeStringEnabled,
-        safeDateEnabled: serverSafeDateEnabled
+        safeEnabled: serverSafeEnabled
       };
 
       // Convert back BigInts and Dates in the result using server's options
@@ -162,9 +179,10 @@ class RpcClient {
 
   /**
    * Make multiple JSON-RPC calls in a single batch request.
+   * @template T
    * @param {Array<{method: string, params?: any, id?: string|number}>} requests Array of request objects.
    * @param {Object} [overrideHeaders={}] Optional headers to override defaults for this request.
-   * @returns {Promise<Array<any>>} Array of results in the same order as requests.
+   * @returns {Promise<Array<T>>} Array of results in the same order as requests.
    */
   async batch(requests, overrideHeaders = {}) {
     const batchRequests = requests.map((req) => {
@@ -185,9 +203,8 @@ class RpcClient {
         method: 'POST',
         headers: {
           ...this.#defaultHeaders,
-          // Add safe options headers so server knows what client expects
-          'X-RPC-SafeString-Enabled': this.#options.safeStringEnabled ? 'true' : 'false',
-          'X-RPC-SafeDate-Enabled': this.#options.safeDateEnabled ? 'true' : 'false',
+          // Add safe options header so server knows what client expects
+          'X-RPC-Safe-Enabled': this.#options.safeEnabled ? 'true' : 'false',
           ...overrideHeaders,
         },
         body: JSON.stringify(batchRequests),
@@ -202,14 +219,31 @@ class RpcClient {
 
       const responseBody = await response.json();
 
-      // Check server's safe options from response headers
-      const serverSafeStringEnabled = response.headers.get('X-RPC-SafeString-Enabled') === 'true';
-      const serverSafeDateEnabled = response.headers.get('X-RPC-SafeDate-Enabled') === 'true';
+      // Check server's safe options from response headers - strict compatibility checking
+      const serverSafeHeader = response.headers.get('X-RPC-Safe-Enabled');
+
+      // Errore rigoroso: se client ha safe enabled ma server non risponde con header
+      if (this.#options.safeEnabled && serverSafeHeader === null) {
+        throw new Error(
+          'RPC Compatibility Error: Client has safe serialization enabled but server did not respond with compatibility header (X-RPC-Safe-Enabled). ' +
+          'This may indicate a version mismatch or non-toolkit server. ' +
+          'Solutions: (1) Update server to rpc-express-toolkit v4+, (2) Disable client safeEnabled option, or (3) Use a compatible JSON-RPC server.'
+        );
+      }
+
+      // Warning: se client ha safe disabled ma server offre compatibilità
+      if (!this.#options.safeEnabled && serverSafeHeader === 'true' && this.#options.warnOnUnsafe) {
+        console.warn(
+          '⚠️  RPC Compatibility Notice: Server supports safe serialization but client has safeEnabled=false. ' +
+          'Consider enabling safeEnabled option for better BigInt/Date handling and forward compatibility.'
+        );
+      }
+
+      const serverSafeEnabled = serverSafeHeader === 'true';
 
       // Create deserialization options based on server's configuration
       const deserializationOptions = {
-        safeStringEnabled: serverSafeStringEnabled,
-        safeDateEnabled: serverSafeDateEnabled
+        safeEnabled: serverSafeEnabled
       };
 
       // Handle batch response
@@ -244,15 +278,28 @@ class RpcClient {
       // Convert BigInt to string with 'n' suffix for proper deserialization
       return value.toString() + 'n';
     } else if (value instanceof Date) {
-      // Convert Date to ISO string with D: prefix if safeDateEnabled
+      // Convert Date to ISO string with D: prefix if safeEnabled
       const isoString = value.toISOString();
-      return this.#options.safeDateEnabled ? `D:${isoString}` : isoString;
+      if (this.#options.safeEnabled) {
+        return `D:${isoString}`;
+      } else {
+        // Show educational warning if enabled
+        if (this.#options.warnOnUnsafe) {
+          console.warn('⚠️  Date serialization: Using plain ISO string format for JSON-RPC 2.0 compliance. Date objects will be deserialized as strings on the receiving end. Consider enabling safeEnabled or using string timestamps for better type safety.');
+        }
+        return isoString;
+      }
     } else if (typeof value === 'string') {
-      // Add S: prefix if safeStringEnabled is true
-      if (this.#options.safeStringEnabled) {
+      // Add S: prefix if safeEnabled is true
+      if (this.#options.safeEnabled) {
         return 'S:' + value;
+      } else {
+        // Show educational warning if enabled and string could be confused with BigInt
+        if (this.#options.warnOnUnsafe && /^-?\d+n?$/.test(value)) {
+          console.warn(`⚠️  String serialization: String "${value}" could be confused with BigInt. Consider enabling safeEnabled for disambiguation or use explicit typing.`);
+        }
+        return value;
       }
-      return value;
     } else if (Array.isArray(value)) {
       // Recurse into arrays
       return value.map((v) => this.serializeBigIntsAndDates(v));
@@ -275,14 +322,12 @@ class RpcClient {
    *
    * @param {any} value The value to deserialize.
    * @param {Object} [options] Custom deserialization options (uses client options if not provided).
-   * @param {boolean} [options.safeStringEnabled] Whether to expect S: prefixed strings.
-   * @param {boolean} [options.safeDateEnabled] Whether to expect D: prefixed dates.
+   * @param {boolean} [options.safeEnabled] Whether to expect safe prefixes for strings and dates.
    * @returns {any}
    */
   deserializeBigIntsAndDates(value, options = null) {
     // Use provided options or fall back to client options
-    const safeStringEnabled = options ? options.safeStringEnabled : this.#options.safeStringEnabled;
-    const safeDateEnabled = options ? options.safeDateEnabled : this.#options.safeDateEnabled;
+    const safeEnabled = options ? options.safeEnabled : this.#options.safeEnabled;
 
     // More comprehensive ISO date regex that handles:
     // - UTC: 2023-01-01T12:00:00.000Z
@@ -293,13 +338,13 @@ class RpcClient {
 
     // 1. Check if it's a string that might be a BigInt, Date, or safe string
     if (typeof value === 'string') {
-      // Safe string check: if safeStringEnabled and starts with S:
-      if (safeStringEnabled && value.startsWith('S:')) {
+      // 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 safeDateEnabled and starts with D:
-      if (safeDateEnabled && value.startsWith('D:')) {
+      // 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
@@ -314,8 +359,8 @@ class RpcClient {
         return BigInt(value.slice(0, -1)); // Remove 'n' and convert
       }
       
-      // Date check: matches an ISO 8601 string (only if safeDateEnabled is false)
-      if (!safeDateEnabled && ISO_DATE_REGEX.test(value)) {
+      // Date check: matches an ISO 8601 string (only if safeEnabled is false)
+      if (!safeEnabled && ISO_DATE_REGEX.test(value)) {
         const date = new Date(value);
         // Ensure it's valid
         if (!isNaN(date.getTime())) {