rpc-express-toolkit 4.1.0 → 4.2.1

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,10 +84,78 @@ 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');
+```
+
+## Introspection Methods
+
+Enable introspection to expose metadata about registered methods via reserved `__rpc.*` methods:
+
+```javascript
+const rpc = new RpcEndpoint(app, context, {
+  enableIntrospection: true  // Enable __rpc.* methods
+});
+
+// Register methods with public schemas
+rpc.addMethod('add', async (req, ctx, params) => {
+  return params.a + params.b;
+}, {
+  schema: {
+    type: 'object',
+    properties: {
+      a: { type: 'number' },
+      b: { type: 'number' }
+    },
+    required: ['a', 'b']
+  },
+  exposeSchema: true,        // Make schema publicly queryable
+  description: 'Add two numbers'
+});
+
+// Available introspection methods:
+// __rpc.listMethods() → ["add", "multiply", ...]
+// __rpc.describe({method: "add"}) → {name, schema, description}
+// __rpc.describeAll() → [{name, schema, description}, ...]
+// __rpc.version() → {toolkit, version, expressVersion, nodeVersion}
+// __rpc.capabilities() → {safeMode, batch, introspection, ...}
+
+// Client usage
+const methods = await client.call('__rpc.listMethods');
+const addInfo = await client.call('__rpc.describe', { method: 'add' });
+```
+
+**Note:** The introspection prefix is configurable via `introspectionPrefix` option (default: `__rpc`). User methods starting with this prefix are rejected to prevent conflicts.
+
 ## Full Details
 
 For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.
 
+## 🔗 Related Projects
+
+- [rpc-php-toolkit](https://github.com/n-car/rpc-php-toolkit) - PHP implementation
+- [rpc-dotnet-toolkit](https://github.com/n-car/rpc-dotnet-toolkit) - .NET implementation
+- [rpc-arduino-toolkit](https://github.com/n-car/rpc-arduino-toolkit) - Arduino/ESP32 implementation
+- [rpc-java-toolkit](https://github.com/n-car/rpc-java-toolkit) - Java & Android implementation
+- [node-red-contrib-rpc-toolkit](https://github.com/n-car/node-red-contrib-rpc-toolkit) - Node-RED visual programming
+
 ## Contributing
 
 ```bash

package/examples/introspection/client.js

@@ -0,0 +1,68 @@
+/**
+ * Introspection Example - Client
+ * Demonstrates how to use __rpc.* introspection methods
+ */
+
+const { RpcClient } = require('../..');
+
+async function main() {
+  const client = new RpcClient('http://localhost:3000/api');
+
+  console.log('=== RPC Introspection Demo ===\n');
+
+  // 1. List all methods
+  console.log('1. __rpc.listMethods():');
+  const methods = await client.call('__rpc.listMethods');
+  console.log('  Available methods:', methods);
+  console.log('');
+
+  // 2. Get version info
+  console.log('2. __rpc.version():');
+  const version = await client.call('__rpc.version');
+  console.log('  Toolkit:', version.toolkit);
+  console.log('  Version:', version.version);
+  console.log('  Express:', version.expressVersion);
+  console.log('  Node:', version.nodeVersion);
+  console.log('');
+
+  // 3. Get server capabilities
+  console.log('3. __rpc.capabilities():');
+  const caps = await client.call('__rpc.capabilities');
+  console.log('  Safe Mode:', caps.safeMode);
+  console.log('  Batch Support:', caps.batch);
+  console.log('  Introspection:', caps.introspection);
+  console.log('  Method Count:', caps.methodCount);
+  console.log('');
+
+  // 4. Describe a specific method
+  console.log('4. __rpc.describe({ method: "add" }):');
+  const addInfo = await client.call('__rpc.describe', { method: 'add' });
+  console.log('  Name:', addInfo.name);
+  console.log('  Description:', addInfo.description);
+  console.log('  Schema:', JSON.stringify(addInfo.schema, null, 2));
+  console.log('');
+
+  // 5. Describe all public methods
+  console.log('5. __rpc.describeAll():');
+  const allMethods = await client.call('__rpc.describeAll');
+  allMethods.forEach((method) => {
+    console.log(`  - ${method.name}: ${method.description}`);
+  });
+  console.log('');
+
+  // 6. Try to describe a private method (should fail)
+  console.log('6. Try to describe private method:');
+  try {
+    await client.call('__rpc.describe', { method: 'internalCalculation' });
+  } catch (error) {
+    console.log('  Error:', error.message);
+  }
+  console.log('');
+
+  // 7. Test a public method
+  console.log('7. Call add method:');
+  const sum = await client.call('add', { a: 5, b: 3 });
+  console.log('  5 + 3 =', sum);
+}
+
+main().catch(console.error);

package/examples/introspection/server.js

@@ -0,0 +1,89 @@
+/**
+ * Introspection Example - Server
+ * Demonstrates how to enable and use __rpc.* introspection methods
+ */
+
+const express = require('express');
+const { RpcEndpoint } = require('../..');
+
+const app = express();
+app.use(express.json());
+
+// Context for methods
+const context = {
+  database: 'mock-db',
+  config: { maxValue: 1000 },
+};
+
+// Create endpoint with introspection enabled
+const rpc = new RpcEndpoint(app, context, {
+  endpoint: '/api',
+  enableIntrospection: true, // Enable __rpc.* methods
+  introspectionPrefix: '__rpc', // Optional: customize prefix (default: __rpc)
+});
+
+// Public method with exposed schema
+rpc.addMethod('add', async (req, ctx, params) => params.a + params.b, {
+  schema: {
+    type: 'object',
+    properties: {
+      a: { type: 'number' },
+      b: { type: 'number' },
+    },
+    required: ['a', 'b'],
+  },
+  exposeSchema: true,
+  description: 'Add two numbers and return the sum',
+});
+
+// Public method with exposed schema
+rpc.addMethod('multiply', async (req, ctx, params) => params.a * params.b, {
+  schema: {
+    type: 'object',
+    properties: {
+      a: { type: 'number' },
+      b: { type: 'number' },
+    },
+    required: ['a', 'b'],
+  },
+  exposeSchema: true,
+  description: 'Multiply two numbers',
+});
+
+// Private method (schema not exposed)
+rpc.addMethod(
+  'internalCalculation',
+  async (req, ctx, params) => params.value * 2 + 42,
+  {
+    schema: {
+      type: 'object',
+      properties: {
+        value: { type: 'number' },
+      },
+      required: ['value'],
+    },
+    exposeSchema: false, // Schema is private
+    description: 'Internal calculation (not exposed)',
+  }
+);
+
+// Public method without schema
+rpc.addMethod('echo', async (req, ctx, params) => params, {
+  exposeSchema: true,
+  description: 'Echo back the parameters',
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(
+    `RPC Server with introspection running on http://localhost:${PORT}/api`
+  );
+  console.log('\nAvailable introspection methods:');
+  console.log('- __rpc.listMethods()');
+  console.log('- __rpc.describe({method: "add"})');
+  console.log('- __rpc.describeAll()');
+  console.log('- __rpc.version()');
+  console.log('- __rpc.capabilities()');
+  console.log('\nTry: node client.js');
+});

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.1",
     "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/batch.js

@@ -140,8 +140,8 @@ class BatchHandler {
       };
     }
 
-    const handler = this.endpoint.methods[method];
-    if (!handler) {
+    const methodConfig = this.endpoint.methods[method];
+    if (!methodConfig) {
       return {
         jsonrpc: '2.0',
         id: id || null,
@@ -153,6 +153,10 @@ class BatchHandler {
       };
     }
 
+    // Extract handler (support both function and config object)
+    const handler =
+      typeof methodConfig === 'function' ? methodConfig : methodConfig.handler;
+
     // If no id is provided, this is a notification - don't return response
     const isNotification = id === undefined || id === null;