rpc-express-toolkit 3.0.2 → 4.0.0

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 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;#i;#n;#s;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.#s={safeEnabled:!0===i.safeEnabled,warnOnUnsafe:!1!==i.warnOnUnsafe,...i},this.#n={}}#r(){return++this.#i}async call(e,t,i=void 0,n={}){const s={jsonrpc:"2.0",method:e,id:void 0===i?this.#r():i};null!=t&&(s.params=this.serializeBigIntsAndDates(t));try{const e=await fetchFn(this.#e,{method:"POST",headers:{...this.#t,"X-RPC-Safe-Enabled":this.#s.safeEnabled?"true":"false",...n},body:JSON.stringify(s),...this.#n});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.#s.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.#s.safeEnabled&&"true"===i&&this.#s.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 r={safeEnabled:"true"===i};return this.deserializeBigIntsAndDates(t.result,r)}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.#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-Safe-Enabled":this.#s.safeEnabled?"true":"false",...t},body:JSON.stringify(i),...this.#n});if(!e.ok)throw new Error(`HTTP Error: ${e.status} ${e.statusText}`);const n=await e.json(),s=e.headers.get("X-RPC-Safe-Enabled");if(this.#s.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.#s.safeEnabled&&"true"===s&&this.#s.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 r={safeEnabled:"true"===s};if(Array.isArray(n))return n.map(e=>{if(e.error)throw e.error;return this.deserializeBigIntsAndDates(e.result,r)});if(n.error)throw n.error;return[this.deserializeBigIntsAndDates(n.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.#s.safeEnabled?`D:${t}`:(this.#s.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.#s.safeEnabled?"S:"+e:(this.#s.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,n]of Object.entries(e))t[i]=this.serializeBigIntsAndDates(n);return t}return e}deserializeBigIntsAndDates(e,t=null){const i=t?t.safeEnabled:this.#s.safeEnabled,n=/^\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&&n.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}}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())) {

package/src/index.d.ts

@@ -99,14 +99,13 @@ interface RpcEndpointOptions {
   cors?: boolean | CorsOptions;
   auth?: AuthConfig;
   validation?: ValidationConfig;
-  safeStringEnabled?: boolean;
-  safeDateEnabled?: boolean;
+  safeEnabled?: boolean;
   crossConfigurationEnabled?: boolean;
   enableSchema?: boolean;
   rateLimit?: RateLimitConfig;
   logging?: LoggingConfig;
-  warnOnUnsafeString?: boolean;
-  warnOnUnsafeDate?: boolean;
+  warnOnUnsafe?: boolean;
+  strictMode?: boolean;
   autoJsonMiddleware?: boolean;
   jsonOptions?: {
     limit?: string;
@@ -120,18 +119,15 @@ interface RpcEndpointOptions {
  * RPC client configuration options
  */
 interface RpcClientOptions {
-  safeStringEnabled?: boolean;
-  safeDateEnabled?: boolean;
-  warnOnUnsafeString?: boolean;
-  warnOnUnsafeDate?: boolean;
+  safeEnabled?: boolean;
+  warnOnUnsafe?: boolean;
 }
 
 /**
  * Deserialization options for safe prefixes
  */
 interface DeserializationOptions {
-  safeStringEnabled?: boolean;
-  safeDateEnabled?: boolean;
+  safeEnabled?: boolean;
 }
 
 /**
@@ -236,12 +232,12 @@ declare class RpcClient {
   /**
    * Make a JSON-RPC call to the server.
    */
-  call(
+  call<T = any>(
     method: string,
     params?: any,
     id?: string | number | null,
     overrideHeaders?: Record<string, string>
-  ): Promise<any>;
+  ): Promise<T>;
 
   /**
    * Make a JSON-RPC notification (no response expected).
@@ -255,7 +251,7 @@ declare class RpcClient {
   /**
    * Make a batch JSON-RPC call.
    */
-  batch(
+  batch<T = any>(
     requests: Array<{
       method: string;
       params?: any;
@@ -263,7 +259,7 @@ declare class RpcClient {
       notification?: boolean;
     }>,
     overrideHeaders?: Record<string, string>
-  ): Promise<any[]>;
+  ): Promise<T[]>;
 
   /**
    * Recursively serialize BigInt and Date to JSON-safe string formats.

package/src/index.js

@@ -138,10 +138,9 @@ class RpcEndpoint {
     this.#batchHandler = new BatchHandler(this);
 
     // Set default options
-    this.#options.safeStringEnabled = this.#options.safeStringEnabled !== false; // Default true
-    this.#options.safeDateEnabled = this.#options.safeDateEnabled !== false; // Default true
-    this.#options.warnOnUnsafeString = this.#options.warnOnUnsafeString !== false; // Default true
-    this.#options.warnOnUnsafeDate = this.#options.warnOnUnsafeDate !== false; // Default true
+    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
 
     // Validate that the router can handle JSON parsing
     this.#validateJsonMiddleware();
@@ -359,13 +358,29 @@ class RpcEndpoint {
 
     try {
       // Check client's safe options from request headers
-      const clientSafeStringEnabled = req.headers['x-rpc-safestring-enabled'] === 'true';
-      const clientSafeDateEnabled = req.headers['x-rpc-safedate-enabled'] === 'true';
+      const clientSafeHeader = req.headers['x-rpc-safe-enabled'];
 
-      // Create deserialization options based on client's configuration
+      // 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 = {
-        safeStringEnabled: clientSafeStringEnabled,
-        safeDateEnabled: clientSafeDateEnabled
+        safeEnabled: clientSafeEnabled
       };
 
       // Deserialize parameters using client's safe options
@@ -602,8 +617,8 @@ class RpcEndpoint {
     }
 
     // Add safe options headers so client knows how to deserialize
-    res.setHeader('X-RPC-SafeString-Enabled', this.#options.safeStringEnabled ? 'true' : 'false');
-    res.setHeader('X-RPC-SafeDate-Enabled', this.#options.safeDateEnabled ? 'true' : 'false');
+    // Send safe options headers to client
+    res.setHeader('X-RPC-Safe-Enabled', this.#options.safeEnabled ? 'true' : 'false');
 
     res.json(response);
   }
@@ -626,23 +641,23 @@ class RpcEndpoint {
    */
   #serializeValue(value, hasBigInt = false, hasDate = false) {
     if (typeof value === 'bigint') {
-      // Warn if safeStringEnabled is disabled and we have BigInt
-      if (!this.#options.safeStringEnabled && !hasBigInt && this.#options.warnOnUnsafeString) {
-        this.#logger.warn('BigInt detected in serialization. Consider enabling safeStringEnabled option to avoid potential string/BigInt confusion.');
+      // 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';
     } else if (value instanceof Date) {
-      // Warn if safeDateEnabled is disabled and we have Date
-      if (!this.#options.safeDateEnabled && !hasDate && this.#options.warnOnUnsafeDate) {
-        this.#logger.warn('Date detected in serialization. Consider enabling safeDateEnabled option to avoid potential string/Date confusion.');
+      // 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 safeDateEnabled
+      // Convert Date to ISO string with D: prefix if safeEnabled
       const isoString = value.toISOString();
-      return this.#options.safeDateEnabled ? `D:${isoString}` : isoString;
+      return this.#options.safeEnabled ? `D:${isoString}` : 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;
       }
       return value;
@@ -700,14 +715,12 @@ class RpcEndpoint {
    *
    * @param {any} value The value to deserialize.
    * @param {Object} [options] Custom deserialization options (uses server 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} The re-hydrated value.
    */
   deserializeBigIntsAndDates(value, options = null) {
     // Use provided options or fall back to server 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
@@ -718,13 +731,13 @@ class RpcEndpoint {
 
     // 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
@@ -738,8 +751,8 @@ class RpcEndpoint {
         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);
         // Double-check that we got a valid date
         if (!isNaN(date.getTime())) {