{"id":50749645,"url":"https://github.com/n-car/rpc-express-toolkit","last_synced_at":"2026-06-11T00:02:53.018Z","repository":{"id":302799391,"uuid":"1013672795","full_name":"n-car/rpc-express-toolkit","owner":"n-car","description":"JSON-RPC 2.0 runtime for Node.js (Express) with introspection, schema validation and middleware support","archived":false,"fork":false,"pushed_at":"2026-06-04T19:40:50.000Z","size":520,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T21:24:34.285Z","etag":null,"topics":["ajv","authentication","batch","bigint","browser","cors","date","express","json-rpc","json-rpc-2-0","jsonrpc","logging","middleware","node","rate-limit","rpc","schema","typescript","validation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/rpc-express-toolkit","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n-car.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-04T09:23:58.000Z","updated_at":"2026-06-04T19:40:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"f98118f4-126e-491b-a196-5c538c5da021","html_url":"https://github.com/n-car/rpc-express-toolkit","commit_stats":null,"previous_names":["n-car/rpc-express-toolkit"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/n-car/rpc-express-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-car%2Frpc-express-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-car%2Frpc-express-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-car%2Frpc-express-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-car%2Frpc-express-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n-car","download_url":"https://codeload.github.com/n-car/rpc-express-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-car%2Frpc-express-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34175888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajv","authentication","batch","bigint","browser","cors","date","express","json-rpc","json-rpc-2-0","jsonrpc","logging","middleware","node","rate-limit","rpc","schema","typescript","validation"],"created_at":"2026-06-11T00:02:52.267Z","updated_at":"2026-06-11T00:02:53.003Z","avatar_url":"https://github.com/n-car.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RPC Express Toolkit\n\n[![CI](https://github.com/n-car/rpc-express-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/n-car/rpc-express-toolkit/actions/workflows/ci.yml)\n[![Coverage Status](https://coveralls.io/repos/github/n-car/rpc-express-toolkit/badge.svg?branch=main)](https://coveralls.io/github/n-car/rpc-express-toolkit?branch=main)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![npm version](https://img.shields.io/npm/v/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)\n[![npm downloads](https://img.shields.io/npm/dm/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)\n[![node](https://img.shields.io/node/v/rpc-express-toolkit.svg)](https://www.npmjs.com/package/rpc-express-toolkit)\n\nEnterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, middleware, schema validation, batch support, and optional safe type disambiguation.\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install rpc-express-toolkit\n# or\nyarn add rpc-express-toolkit\n```\n\nRequirements:\n- Node.js 18+ (uses `globalThis.fetch`)\n\n### Server\n\n```javascript\nconst express = require('express');\nconst { RpcEndpoint } = require('rpc-express-toolkit');\n\nconst app = express();\napp.use(express.json()); // required\n\nconst context = { database: db, config };\n\nconst rpc = new RpcEndpoint(app, context);\nrpc.addMethod('add', (req, ctx, params) =\u003e params.a + params.b);\n\napp.listen(3000);\n```\n\n### Client\n\n```javascript\nconst { RpcClient, RpcSafeClient } = require('rpc-express-toolkit');\n\nconst client = new RpcClient('http://localhost:3000/api');\nconst sum = await client.call('add', { a: 1, b: 2 });\n\nconst safeClient = new RpcSafeClient('http://localhost:3000/api');\nawait safeClient.notify('add', { a: 0, b: 0 });\n```\n\n`RpcClient` and `RpcSafeClient` are re-exported from the shared `rpc-toolkit-js-client` package, so existing Node.js imports from `rpc-express-toolkit` continue to work.\n\n### Browser Client Assets\n\nServe the shared browser client bundles from the endpoint:\n\n```javascript\nconst { RpcEndpoint } = require('rpc-express-toolkit');\n\nRpcEndpoint.serveScripts(app);\n```\n\nDefault paths:\n\n```text\n/vendor/rpc-client/rpc-client.js\n/vendor/rpc-client/rpc-client.min.js\n/vendor/rpc-client/rpc-client.mjs\n/vendor/rpc-client/rpc-client.min.mjs\n```\n\nClassic browser script:\n\n```html\n\u003cscript src=\"/vendor/rpc-client/rpc-client.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const client = new RpcToolkitClient.RpcClient('/api');\n  const safeClient = new RpcToolkitClient.RpcSafeClient('/api');\n\n  client.call('add', { a: 1, b: 2 }).then(console.log);\n  safeClient.notify('add', { a: 0, b: 0 });\n\u003c/script\u003e\n```\n\nModule script:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { RpcClient, RpcSafeClient } from '/vendor/rpc-client/rpc-client.mjs';\n\n  const client = new RpcClient('/api');\n  const safeClient = new RpcSafeClient('/api');\n\n  console.log(await client.call('add', { a: 1, b: 2 }));\n  await safeClient.notify('add', { a: 0, b: 0 });\n\u003c/script\u003e\n```\n\n### Safe Type Disambiguation (optional)\n\nSafe type disambiguation is disabled by default for maximum JSON-RPC 2.0 compatibility. The library can show warnings when BigInt or Date values are serialized in standard mode. Enable safe serialization with `safeEnabled: true` to add safe prefixes (`S:` for strings, `D:` for dates), or suppress warnings with `warnOnUnsafe: false`. See `README_ADVANCED.md#safe-serialization` for details.\n\n## Minimal API\n\n- `new RpcEndpoint(router, context, options?)`: create and attach a JSON-RPC endpoint.\n- `rpc.addMethod(name, handlerOrConfig)`: register a method (function or `{ handler, schema }`).\n- `new RpcClient(baseUrl, headers?, options?)`: client for making calls.\n- `client.call(method, params?)`: single call.\n- `client.batch([...])`: batch.\n- `client.notify(method, params?)`: notification.\n\n## Authentication And Method Restrictions\n\nAuthentication is supported through the built-in `auth` middleware. The `auth` option is a function that receives the Express request. Returning a truthy value allows the RPC call; returning a falsy value rejects it with JSON-RPC error `-32001` and message `Authentication required`. Throwing also rejects the call and returns a JSON-RPC error based on the thrown error.\n\n```js\nconst rpc = new RpcEndpoint(app, context, {\n  auth: async (req) =\u003e {\n    const token = req.headers.authorization;\n    return token === 'Bearer secret-token';\n  },\n});\n\nrpc.addMethod('ping', () =\u003e 'pong');\n```\n\nFor simple method-level restriction, use `methodWhitelist`:\n\n```js\nconst rpc = new RpcEndpoint(app, context, {\n  methodWhitelist: ['ping', 'status.read'],\n});\n```\n\nCalls to methods outside the whitelist are rejected. This is a basic method restriction mechanism, not a complete role or permission system. Project-specific authorization rules can be implemented with middleware hooks such as `beforeCall`; see `README_ADVANCED.md`.\n\n### Safe Import (opt-in)\n\n[![npm (proxy)](https://img.shields.io/npm/v/rpc-express-toolkit-safe.svg)](https://www.npmjs.com/package/rpc-express-toolkit-safe)\n[![safe preset](https://img.shields.io/badge/safe%20preset-available-blue)](#safe-import-opt-in)\n\nWhen 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):\n\n```js\n// Server (safe preset)\nconst express = require('express');\nconst { RpcSafeEndpoint } = require('rpc-express-toolkit/safe');\n\nconst app = express();\napp.use(express.json());\n\nconst rpc = new RpcSafeEndpoint(app, {}, { endpoint: '/api' /* strictMode: true by default */ });\n\n// Client (safe preset)\nconst { RpcSafeClient } = require('rpc-express-toolkit/safe');\nconst client = new RpcSafeClient('http://localhost:3000/api');\n```\n\nThis 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.\n\nAlternative: npm proxy package\n\nIf you prefer a dedicated package name, you can install the thin proxy `rpc-express-toolkit-safe` which simply re-exports the safe preset:\n\n```bash\nnpm install rpc-express-toolkit-safe\n```\n\n```js\n// Server\nconst express = require('express');\nconst { RpcSafeEndpoint } = require('rpc-express-toolkit-safe');\nconst app = express();\napp.use(express.json());\nconst rpc = new RpcSafeEndpoint(app, {}, { endpoint: '/api' });\n\n// Client\nconst { RpcSafeClient } = require('rpc-express-toolkit-safe');\nconst client = new RpcSafeClient('http://localhost:3000/api');\n```\n\n## Introspection Methods\n\nEnable introspection to expose metadata about registered methods via reserved `__rpc.*` methods:\n\n```javascript\nconst rpc = new RpcEndpoint(app, context, {\n  enableIntrospection: true  // Enable __rpc.* methods\n});\n\n// Register methods with public schemas\nrpc.addMethod('add', async (req, ctx, params) =\u003e {\n  return params.a + params.b;\n}, {\n  schema: {\n    type: 'object',\n    properties: {\n      a: { type: 'number' },\n      b: { type: 'number' }\n    },\n    required: ['a', 'b']\n  },\n  exposeSchema: true,        // Make schema publicly queryable\n  description: 'Add two numbers'\n});\n\n// Available introspection methods:\n// __rpc.listMethods() → [\"add\", \"multiply\", ...]\n// __rpc.describe({method: \"add\"}) → {name, schema, description}\n// __rpc.describeAll() → [{name, schema, description}, ...]\n// __rpc.version() → {toolkit, version, expressVersion, nodeVersion}\n// __rpc.capabilities() → {safeMode, batch, introspection, ...}\n\n// Client usage\nconst methods = await client.call('__rpc.listMethods');\nconst addInfo = await client.call('__rpc.describe', { method: 'add' });\n```\n\nIn `__rpc.capabilities`, `auth` is a boolean indicating whether authentication middleware is configured. It does not expose roles, scopes, or permission rules.\n\n**Note:** The introspection prefix is configurable via `introspectionPrefix` option (default: `__rpc`). User methods starting with this prefix are rejected to prevent conflicts.\n\n## Full Details\n\nFor advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.\n\n## 🔗 Related Projects\n\n- [rpc-php-toolkit](https://github.com/n-car/rpc-php-toolkit) - PHP implementation\n- [rpc-dotnet-toolkit](https://github.com/n-car/rpc-dotnet-toolkit) - .NET implementation\n- [rpc-arduino-toolkit](https://github.com/n-car/rpc-arduino-toolkit) - Arduino/ESP32 implementation\n- [rpc-java-toolkit](https://github.com/n-car/rpc-java-toolkit) - Java \u0026 Android implementation\n- [node-red-contrib-rpc-toolkit](https://github.com/n-car/node-red-contrib-rpc-toolkit) - Node-RED visual programming\n\n## Contributing\n\n```bash\ngit clone https://github.com/n-car/rpc-express-toolkit.git\nnpm install\nnpm test\nnpm run lint\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-car%2Frpc-express-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn-car%2Frpc-express-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-car%2Frpc-express-toolkit/lists"}