rpc-express-toolkit 4.0.1 → 4.1.0

package/README.md

@@ -59,6 +59,27 @@ Safe type disambiguation is disabled by default for maximum JSON-RPC 2.0 compati
 - `client.batch([...])`: batch.
 - `client.notify(method, params?)`: notification.
 
+### 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
+// Server (safe preset)
+const express = require('express');
+const { createSafeEndpoint } = require('rpc-express-toolkit/safe');
+
+const app = express();
+app.use(express.json());
+
+const rpc = createSafeEndpoint(app, {}, { endpoint: '/api' /* strictMode: true by default */ });
+
+// Client (safe preset)
+const { createSafeClient } = require('rpc-express-toolkit/safe');
+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.
+
 ## Full Details
 
 For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.

package/examples/safe-preset-example.js

@@ -0,0 +1,45 @@
+const express = require('express');
+/* eslint-disable import/no-unresolved, prettier/prettier */
+const { createSafeEndpoint, createSafeClient } = require('rpc-express-toolkit/safe');
+/* eslint-enable import/no-unresolved, prettier/prettier */
+
+async function main() {
+  const app = express();
+  app.use(express.json());
+
+  // Server with safe defaults (safeEnabled=true, strictMode=true)
+  const rpc = createSafeEndpoint(app, {}, { endpoint: '/api' });
+
+  rpc.addMethod('sum', (req, ctx, params) => {
+    // params are already deserialized according to the client's safe header
+    const a =
+      typeof params.a === 'string' && params.a.endsWith('n')
+        ? BigInt(params.a.slice(0, -1))
+        : BigInt(params.a);
+    const b =
+      typeof params.b === 'string' && params.b.endsWith('n')
+        ? BigInt(params.b.slice(0, -1))
+        : BigInt(params.b);
+    return a + b; // will be serialized as "<value>n" safely
+  });
+
+  const server = app.listen(0, async () => {
+    const { port } = server.address();
+    const url = `http://localhost:${port}/api`;
+    console.log('Safe server listening on', url);
+
+    // Safe client (sends header and expects safe response)
+    const client = createSafeClient(url);
+    const res = await client.call('sum', { a: '10n', b: '32n' });
+    console.log('sum result (BigInt):', res.toString());
+
+    server.close();
+  });
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,114 +1,126 @@
-{
-  "name": "rpc-express-toolkit",
-  "version": "4.0.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",
-  "files": [
-    "src/",
-    "examples/",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "jest",
-    "test:coverage": "jest --coverage",
-    "test:watch": "jest --watch",
-    "lint": "eslint src/ examples/",
-    "lint:fix": "eslint src/ examples/ --fix",
-    "clean": "node -e \"require('fs').existsSync('dist') && require('fs').rmSync('dist', {recursive: true})\"",
-    "build": "npm run build:minify",
-    "build:minify": "npm run build:js && npm run build:mjs",
-    "build:js": "terser src/clients/rpc-client.js -o src/clients/rpc-client.min.js --compress --mangle --comments false --ecma 2020",
-    "build:mjs": "terser src/clients/rpc-client.mjs -o src/clients/rpc-client.min.mjs --compress --mangle --comments false --module --ecma 2020",
-    "prepublishOnly": "npm run build",
-    "precommit": "npm run lint && npm test"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/n-car/rpc-express-toolkit.git"
-  },
-  "keywords": [
-    "json-rpc",
-    "jsonrpc",
-    "json-rpc-2.0",
-    "express",
-    "toolkit",
-    "rpc",
-    "server",
-    "client",
-    "middleware",
-    "validation",
-    "schema",
-    "ajv",
-    "bigint",
-    "date",
-    "enterprise",
-    "nodejs",
-    "node",
-    "browser",
-    "ssl",
-    "self-signed",
-    "secure",
-    "fetch",
-    "batch",
-    "typescript",
-    "logging",
-    "cors",
-    "rate-limit",
-    "authentication"
-  ],
-  "author": "Nicola Carpanese <nicola.carpanese@gmail.com>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/n-car/rpc-express-toolkit/issues"
-  },
-  "homepage": "https://github.com/n-car/rpc-express-toolkit#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "eslint": "^8.57.1",
-    "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-config-prettier": "^9.1.2",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-prettier": "^5.5.3",
-    "husky": "^8.0.0",
-    "jest": "^29.7.0",
-    "lint-staged": "^13.0.0",
-    "prettier": "^3.6.2",
-    "supertest": "^6.3.3",
-    "terser": "^5.43.1"
-  },
-  "dependencies": {
-    "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1",
-    "express": "^4.21.2",
-    "nested-error-stacks": "^2.1.1"
-  },
-  "optionalDependencies": {
-    "node-fetch": "^2.7.0"
-  },
-  "contributors": [
-    {
-      "name": "Nicola Carpanese",
-      "email": "nicola.carpanese@gmail.com",
-      "url": "https://github.com/n-car"
-    }
-  ],
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
-  },
-  "lint-staged": {
-    "src/**/*.js": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "examples/**/*.js": [
-      "eslint --fix",
-      "prettier --write"
-    ]
-  }
-}
+{
+    "name":  "rpc-express-toolkit",
+    "version":  "4.1.0",
+    "description":  "Enterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, structured logging, middleware system, schema validation, comprehensive BigInt/Date support. JSON middleware validation and explicit configuration.",
+    "main":  "src/index.js",
+    "types":  "src/index.d.ts",
+    "exports":  {
+                    ".":  {
+                              "types":  "./src/index.d.ts",
+                              "require":  "./src/index.js",
+                              "import":  "./src/index.js"
+                          },
+                    "./safe":  {
+                                   "types":  "./src/safe.d.ts",
+                                   "require":  "./src/safe.js",
+                                   "import":  "./src/safe.js"
+                               }
+                },
+    "files":  [
+                  "src/",
+                  "examples/",
+                  "README.md",
+                  "LICENSE"
+              ],
+    "scripts":  {
+                    "test":  "jest",
+                    "test:coverage":  "jest --coverage",
+                    "test:watch":  "jest --watch",
+                    "lint":  "eslint src/ examples/",
+                    "lint:fix":  "eslint src/ examples/ --fix",
+                    "clean":  "node -e \"require(\u0027fs\u0027).existsSync(\u0027dist\u0027) \u0026\u0026 require(\u0027fs\u0027).rmSync(\u0027dist\u0027, {recursive: true})\"",
+                    "build":  "npm run build:minify",
+                    "build:minify":  "npm run build:js \u0026\u0026 npm run build:mjs",
+                    "build:js":  "terser src/clients/rpc-client.js -o src/clients/rpc-client.min.js --compress --mangle --comments false --ecma 2020",
+                    "build:mjs":  "terser src/clients/rpc-client.mjs -o src/clients/rpc-client.min.mjs --compress --mangle --comments false --module --ecma 2020",
+                    "prepublishOnly":  "npm run build",
+                    "precommit":  "npm run lint \u0026\u0026 npm test"
+                },
+    "repository":  {
+                       "type":  "git",
+                       "url":  "git+https://github.com/n-car/rpc-express-toolkit.git"
+                   },
+    "keywords":  [
+                     "json-rpc",
+                     "jsonrpc",
+                     "json-rpc-2.0",
+                     "express",
+                     "toolkit",
+                     "rpc",
+                     "server",
+                     "client",
+                     "middleware",
+                     "validation",
+                     "schema",
+                     "ajv",
+                     "bigint",
+                     "date",
+                     "enterprise",
+                     "nodejs",
+                     "node",
+                     "browser",
+                     "ssl",
+                     "self-signed",
+                     "secure",
+                     "fetch",
+                     "batch",
+                     "typescript",
+                     "logging",
+                     "cors",
+                     "rate-limit",
+                     "authentication"
+                 ],
+    "author":  "Nicola Carpanese \u003cnicola.carpanese@gmail.com\u003e",
+    "license":  "MIT",
+    "bugs":  {
+                 "url":  "https://github.com/n-car/rpc-express-toolkit/issues"
+             },
+    "homepage":  "https://github.com/n-car/rpc-express-toolkit#readme",
+    "engines":  {
+                    "node":  "\u003e=18.0.0"
+                },
+    "devDependencies":  {
+                            "eslint":  "^8.57.1",
+                            "eslint-config-airbnb-base":  "^15.0.0",
+                            "eslint-config-prettier":  "^9.1.2",
+                            "eslint-plugin-import":  "^2.31.0",
+                            "eslint-plugin-prettier":  "^5.5.3",
+                            "husky":  "^8.0.0",
+                            "jest":  "^29.7.0",
+                            "lint-staged":  "^13.0.0",
+                            "prettier":  "^3.6.2",
+                            "supertest":  "^6.3.3",
+                            "terser":  "^5.43.1"
+                        },
+    "dependencies":  {
+                         "ajv":  "^8.12.0",
+                         "ajv-formats":  "^2.1.1",
+                         "express":  "^4.21.2",
+                         "nested-error-stacks":  "^2.1.1"
+                     },
+    "optionalDependencies":  {
+                                 "node-fetch":  "^2.7.0"
+                             },
+    "contributors":  [
+                         {
+                             "name":  "Nicola Carpanese",
+                             "email":  "nicola.carpanese@gmail.com",
+                             "url":  "https://github.com/n-car"
+                         }
+                     ],
+    "husky":  {
+                  "hooks":  {
+                                "pre-commit":  "lint-staged"
+                            }
+              },
+    "lint-staged":  {
+                        "src/**/*.js":  [
+                                            "eslint --fix",
+                                            "prettier --write"
+                                        ],
+                        "examples/**/*.js":  [
+                                                 "eslint --fix",
+                                                 "prettier --write"
+                                             ]
+                    }
+}

package/src/safe.d.ts

@@ -0,0 +1,30 @@
+import type { Router } from 'express';
+import type { RpcEndpoint, RpcClient, RpcEndpointOptions, RpcClientOptions } from './index';
+
+/**
+ * Factory: create a RpcEndpoint with safe defaults (safeEnabled=true, strictMode=true).
+ */
+export function createSafeEndpoint<C = any>(
+  router: Router,
+  context: C,
+  endpoint?: string,
+  options?: RpcEndpointOptions
+): RpcEndpoint<C>;
+
+export function createSafeEndpoint<C = any>(
+  router: Router,
+  context: C,
+  options?: RpcEndpointOptions
+): RpcEndpoint<C>;
+
+/**
+ * Factory: create a RpcClient with safe defaults (safeEnabled=true).
+ */
+export function createSafeClient(
+  endpoint: string,
+  defaultHeaders?: Record<string, string>,
+  options?: RpcClientOptions
+): RpcClient;
+
+export * from './index';
+

package/src/safe.js

@@ -0,0 +1,54 @@
+const Main = require('./index');
+
+// Default safe options applied unless explicitly overridden
+const defaultSafeOptions = {
+  safeEnabled: true,
+  strictMode: true,
+};
+
+/**
+ * Create a RpcEndpoint with safe defaults (safeEnabled=true, strictMode=true).
+ * Preserves both constructor signatures supported by RpcEndpoint.
+ *
+ * @param {import('express').Router} router
+ * @param {any} context
+ * @param {string|object} [endpointOrOptions='/api']
+ * @param {object} [options]
+ */
+function createSafeEndpoint(
+  router,
+  context,
+  endpointOrOptions = '/api',
+  options = {}
+) {
+  if (typeof endpointOrOptions === 'string') {
+    const finalOptions = { ...defaultSafeOptions, ...options };
+    return new Main.RpcEndpoint(
+      router,
+      context,
+      endpointOrOptions,
+      finalOptions
+    );
+  }
+  // options object form
+  const final = { ...defaultSafeOptions, ...endpointOrOptions };
+  return new Main.RpcEndpoint(router, context, final);
+}
+
+/**
+ * Create a RpcClient with safe defaults (safeEnabled=true).
+ * @param {string} endpoint
+ * @param {Record<string,string>} [defaultHeaders]
+ * @param {object} [options]
+ */
+function createSafeClient(endpoint, defaultHeaders = {}, options = {}) {
+  const finalOptions = { safeEnabled: true, ...options };
+  return new Main.RpcClient(endpoint, defaultHeaders, finalOptions);
+}
+
+module.exports = {
+  // Re-export everything for convenience
+  ...Main,
+  createSafeEndpoint,
+  createSafeClient,
+};