- 🎯 Type-First Design: TypeScript types generated directly from OpenAPI spec (not inferred from schemas)
- ⚡ Blazing Fast Autocomplete: Clean, responsive IntelliSense with zero runtime overhead
- 🛡️ Runtime Validation: Valibot schema validation for request/response
- 📦 Tree-Shakable: Optimized builds with code splitting for both ESM and CJS
- 🧪 98%+ Test Coverage: Comprehensive automated testing with dynamically generated test suites
- 🔄 Auto-Updated: Daily synchronization with NEAR Protocol's latest OpenAPI specification
- 🎭 Mock Generation: Test data generation using valimock
- 🔌 Modular Architecture: Separate packages for types and client implementation
- Overview
- Packages
- Quick Start
- Installation
- Documentation Overview
- Development
- Code Generation
- Testing
- CI/CD
- Contributing
- Architecture
This monorepo provides a type-safe, high-performance JSON-RPC client for interacting with NEAR Protocol nodes. It features automatic code generation from OpenAPI specifications, comprehensive type safety, and extensive test coverage.
| Package | Version | Description |
|---|---|---|
| @space-rock/jsonrpc-client | JSON-RPC fetch client with runtime validation | |
| @space-rock/jsonrpc-types | TypeScript types and Valibot schemas |
# Install the client
pnpm add @space-rock/jsonrpc-client
# If you need types
pnpm add @space-rock/jsonrpc-typesimport { block, createRpcClient } from '@space-rock/jsonrpc-client';
// Initialize client
const client = createRpcClient('https://near.lava.build:443');
// Make block method request
const response = await block(client, { finality: 'final' });
if ('error' in response) {
console.log(response.error.message);
} else {
console.log(response.result.header.hash);
}- Node.js >= 20.0.0
- pnpm >= 10.0.0
# Clone the repository
git clone https://github.com/@space-rock/jsonrpc-client.git
cd jsonrpc-client
# Install dependencies
pnpm install
# Build all packages
pnpm build| Document | Description |
|---|---|
| CONTRIBUTING.md | Contribution guidelines |
| SETUP.md | Development setup guide |
| CODE_GENERATION.md | Code generation guide |
| DEPLOYMENT.md | Deployment and release guide |
# Generate types, schemas, and tests from OpenAPI spec
pnpm codegen
# Build all packages
pnpm build
# Run tests
pnpm test
# Run tests with coverage
pnpm test:coverage
# Run tests in watch mode
pnpm test:watch
# Type checking
pnpm typecheck
# Format code
pnpm format
# Clean build artifacts
pnpm cleanThe project uses a sophisticated code generation pipeline to ensure type safety and maintainability:
-
TypeScript Types (
codegen/src/types.ts)- Generates TypeScript interfaces from
openapi.json - Uses
openapi-typescriptfor accurate type generation - Creates method-to-request/response mappings
- Generates TypeScript interfaces from
-
Valibot Schemas (
codegen/src/schemas.ts)- Generates Valibot schemas from TypeScript types
- Maintains runtime validation capabilities
-
Test Suites (
codegen/src/tests.ts)- Dynamically generates comprehensive tests
- Uses
valimockfor mock data generation - Ensures high test coverage across all methods
# Generate all artifacts
pnpm codegen
# This runs:
# 1. Type generation
# 2. Schema generation
# 3. Test generation
# 4. Code formattingThe project automatically fetches the latest OpenAPI specification daily:
# Manual trigger (requires repository access)
# Set INPUT_JSON_URL repository variable or use workflow dispatch
# Local update
curl -L -o codegen/openapi.json <openapi-spec-url>
pnpm codegen- Dynamic Test Generation: Tests are automatically generated for all RPC methods
- Mock Data: Uses
valimockto generate valid test data - Coverage Target: Maintains >80% code coverage
- Validation Testing: Tests both validated and non-validated request paths
# Run all tests
pnpm test
# Run with coverage report
pnpm test:coverage
# Watch mode for development
pnpm test:watch
# Run tests for specific package
pnpm --filter @space-rock/jsonrpc-client testCoverage reports are generated in the coverage/ directory and include:
- Line coverage
- Branch coverage
- Function coverage
- Statement coverage
Runs on every push and pull request:
-
Code Quality
- Formatting check (Prettier)
- Type checking (TypeScript)
- Linting
-
Testing
- Unit tests across all packages
- Coverage reporting to Codecov
- Coverage threshold enforcement (>80%)
-
Build Verification
- Package builds (ESM & CJS)
- Tree-shaking verification
- Bundle size checks
-
Release Dry Run
- Validates package publishing configuration
- Checks version consistency
Daily workflow that:
- Fetches latest OpenAPI specification from NEAR Protocol
- Regenerates types, schemas, and tests
- Creates PR with updates if changes detected
- Runs full CI pipeline on generated code
Uses release-please for automated releases:
- Version Management: Semantic versioning based on conventional commits
- Changelog Generation: Automatic changelog from commit messages
- Package Publishing: Automated npm publishing
- GitHub Releases: Creates GitHub releases with notes
Please see our Contributing Guide for details on:
- Code of Conduct
- Development workflow
- Commit conventions
- Pull request process
- Code review guidelines
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
pnpm test) - Commit with conventional commits (
feat: add amazing feature) - Push to your fork
- Open a Pull Request
-
Type-First Development
- Types are the source of truth
- Runtime validation
- Zero runtime overhead for type information
-
Modular Design
- Separate concerns (types vs. client)
- Tree-shakable exports
- Framework agnostic
-
Developer Experience
- Fast autocomplete
- Clear error messages
- Comprehensive documentation
- Code Splitting: Separate entry points for different functionalities
- Tree Shaking: Unused code elimination in production builds
- Lazy Loading: Schemas loaded only when validation is enabled
- Bundle Optimization: Dual ESM/CJS builds with optimized chunks
MIT License - see LICENSE for details
- RPC Documentation
- Client Package Documentation
- Types Package Documentation
- NPM - Client
- NPM - Types
- NEAR Protocol
Built with ❤️ for the NEAR community