How raviqqe/onerpc works
Project Overview and Type
• oneRPC is a minimal RPC library that “converts” a server-side function with type (input: T) => Promise<S> into a HTTP-compatible request handler (Request) => Promise<Response>.
• It is designed to provide type safety and smooth client-server communication for serverless environments such as Next.js Route Handlers and AWS Lambda.
• The project is a library (with demonstration examples in the “examples” directory) that abstracts the RPC pattern with adapters and middleware.
Components from the File Structure
• Top-Level Directories and Files
• The root has configuration files (.cspell.json, package.json, tsconfig.json, eslint.config.js, etc.), alongside the README and LICENSE.
• The “src” directory holds the core logic of oneRPC (client, main functions, error handling, validation, middleware, options, and utilities).
• The “src/adapter” folder shows that there is a dedicated adapter for AWS Lambda (“aws-lambda.ts”), indicating support for different runtime environments.
• The “src/middleware” directory (and related tests) builds the processing chain for request/response transformation (e.g., “etag.ts” and “utility.ts”).
• The “examples/aws” folder provides a concrete AWS Lambda implementation with its own project files and tests, illustrating practical usage.
Main Architectural Components
• Client Component
• Represented by files like “src/client.ts” which provides the RPC invocation functionality from the client side.
• RPC Server-side Handler (Core Logic)
• The “src/main.ts”, “src/error.ts”, “src/validation.ts”, “src/options.ts”, and “src/utility.ts” files form the core engine that wraps a server function (with type (T) => Promise<S>) into a Request handler.
• Middleware Chain
• The middleware components in “src/middleware” (for example, “etag.ts” and “utility.ts”) indicate that all requests/responses can be intercepted or modified.
• Environment Adapters
• The “src/adapter/aws-lambda.ts” is a key adapter that allows the oneRPC core to be deployed as an AWS Lambda function.
• Similarly, the README code snippet shows usage for Next.js Route Handlers—thus, while there might not be an explicit “adapter” for Next.js in the file tree, it is supported by design.
• External Integration Points
• Since additional routing/rpc conversion is delegated to external frameworks (e.g., Next.js or AWS), represent these as “External HTTP Framework/Infrastructure” components that feed into the adapter layer.
Relationships and Data Flow
• Client → RPC Call: The client component (using “src/client.ts”) initiates a remote function call from the client side.
• Request Routing via Environment Adapter: The call first reaches an environment-specific adapter (for instance, the AWS Lambda adapter shown in “src/adapter/aws-lambda.ts” or handled via Next.js routing in a Route Handler).
• Middleware Processing: Before reaching the core function, the request is processed through the middleware chain (as defined in “src/middleware”), which can handle concerns like header manipulation (e.g., ETag handling) and utility functions.
• Core RPC Function: The main processing occurs in “src/main.ts” and is supported by validation, error handling, and options configurations.
• Response Path: Once the core function processes the request, the response is sent back through the same middleware chain (if needed) and then returns to the client, converting promises and streaming responses as JSON Lines if applicable.
Architectural Design Principles to Emphasize
• Separation of Concerns: Clearly separate the client invocation, middleware processing, RPC core logic, and environment-specific adapters.
• Flexibility and Extensibility: The design allows plugging in new adapters for other environments due to the adapter pattern seen here.
• Minimal Dependencies & HTTP Friendliness: Emphasize that the library leverages Web APIs directly, ensuring portability across platforms like Node.js, Deno, and edge runtimes.
• Type-Safe Communication: Include that the use of TypeScript types ensures compile-time safety for both requests and responses.
Final Recommendations
• Clearly label every component, such as “Client”, “AWS Lambda Adapter”, “Middleware (ETag, Utility)”, “RPC Core”, “Validation”, and “Error Handling”.
• Annotations about TypeScript and the design goals (type safety, minimal dependencies, serverless-first) to inform about key non-functional design principles.