@srpc.org/core 0.20.3

package/README.md

@@ -0,0 +1,322 @@
+# @srpc/core
+
+A lightweight, type-safe RPC framework for TypeScript with automatic type inference, multiple runtime support, and zero dependencies.
+
+## Installation
+
+```bash
+# Using JSR (recommended)
+deno add @srpc/core
+npx jsr add @srpc/core
+yarn dlx jsr add @srpc/core
+pnpm dlx jsr add @srpc/core
+bunx jsr add @srpc/core
+```
+
+## Features
+
+- **Type-safe**: Full TypeScript support with automatic type inference
+- **Zero dependencies**: Lightweight core with no external dependencies
+- **Runtime agnostic**: Works with Node.js, Deno, Bun, Cloudflare Workers, and more
+- **Multiple adapters**: Support for both Node.js HTTP and standard Fetch API
+- **Nested routers**: Organize procedures into nested namespaces
+- **Custom serialization**: Pluggable serialization layer
+- **Error handling**: Built-in error types with HTTP status code mapping
+
+## Quick Start
+
+### Server Setup
+
+#### Using Fetch API (Recommended for Edge Runtimes)
+
+```typescript
+import { initSRPC, srpcFetchApi } from "@srpc/core/server";
+
+// Initialize SRPC
+const s = initSRPC();
+
+// Define your router
+const appRouter = s.router({
+  sayHello: async (_, name: string) => {
+    return `Hello ${name}!`;
+  },
+  getUser: async (_, id: number) => {
+    return { id, name: "John Doe", email: "john@example.com" };
+  },
+});
+
+// Export the router type for client usage
+export type AppRouter = typeof appRouter;
+
+// Create Fetch API handler
+const { fetch: handleRequest } = srpcFetchApi({
+  router: appRouter,
+  endpoint: "/api",
+});
+
+// Use with any framework supporting Fetch API
+export default {
+  fetch: handleRequest,
+};
+```
+
+#### Using Node.js HTTP Server
+
+```typescript
+import { initSRPC } from "@srpc/core/server";
+import { createSrpcServer } from "@srpc/core/server";
+
+const s = initSRPC();
+
+const appRouter = s.router({
+  sayHello: async (_, name: string) => {
+    return `Hello ${name}!`;
+  },
+});
+
+export type AppRouter = typeof appRouter;
+
+// Create Node.js server
+const server = createSrpcServer({
+  router: appRouter,
+  endpoint: "/api",
+});
+
+server.listen(3000, () => {
+  console.log("SRPC server listening on port 3000");
+});
+```
+
+### Client Setup
+
+```typescript
+import { createSRPCClient } from "@srpc/core/client";
+import type { AppRouter } from "./server";
+
+// Create type-safe client
+const client = createSRPCClient<AppRouter>({
+  endpoint: "http://localhost:3000/api",
+});
+
+// Call procedures with full type safety
+const greeting = await client.sayHello("World"); // Type: string
+const user = await client.getUser(1); // Type: { id: number, name: string, email: string }
+```
+
+## Advanced Usage
+
+### Nested Routers
+
+Organize your procedures into logical groups:
+
+```typescript
+import { initSRPC } from "@srpc/core/server";
+
+const s = initSRPC();
+
+// Admin procedures
+const adminRouter = s.router({
+  createUser: async (_, data: { name: string; email: string }) => {
+    // Create user logic
+    return { id: 1, ...data };
+  },
+  deleteUser: async (_, id: number) => {
+    // Delete user logic
+    return { success: true };
+  },
+});
+
+// Public user procedures
+const usersRouter = s.router({
+  getUser: async (_, id: number) => {
+    return { id, name: "John Doe" };
+  },
+  admin: adminRouter, // Nested router
+});
+
+// Main app router
+const appRouter = s.router({
+  users: usersRouter,
+  sayHello: async (_, name: string) => `Hello ${name}!`,
+});
+
+// Client usage:
+// client.users.getUser(1)
+// client.users.admin.createUser({ name: "Jane", email: "jane@example.com" })
+// client.sayHello("World")
+```
+
+### Context
+
+Add context (authentication, database connections, etc.) to your procedures:
+
+```typescript
+import { initSRPC, srpcFetchApi } from "@srpc/core/server";
+
+// Define your context type
+type Context = {
+  user?: { id: number; name: string };
+  db: Database;
+};
+
+// Initialize with context type
+const s = initSRPC().context<Context>();
+
+// Use context in procedures
+const appRouter = s.router({
+  getCurrentUser: async (ctx) => {
+    if (!ctx.user) throw new Error("Not authenticated");
+    return ctx.user;
+  },
+  getPost: async (ctx, id: number) => {
+    return await ctx.db.posts.findById(id);
+  },
+});
+
+// Provide context creation function
+const { fetch: handleRequest } = srpcFetchApi({
+  router: appRouter,
+  endpoint: "/api",
+  createContext: async (req) => {
+    const user = await authenticateRequest(req);
+    return { user, db: getDatabase() };
+  },
+});
+```
+
+### Error Handling
+
+Use `SRPCError` for proper HTTP status code mapping:
+
+```typescript
+import { initSRPC } from "@srpc/core/server";
+import { SRPCError } from "@srpc.org/core";
+
+const s = initSRPC();
+
+const appRouter = s.router({
+  getUser: async (_, id: number) => {
+    const user = await db.users.findById(id);
+    if (!user) {
+      throw new SRPCError("User not found", "NOT_FOUND"); // Returns HTTP 404
+    }
+    return user;
+  },
+  deleteUser: async (_, id: number) => {
+    if (!hasPermission()) {
+      throw new SRPCError("Unauthorized", "UNAUTHORIZED"); // Returns HTTP 401
+    }
+    await db.users.delete(id);
+    return { success: true };
+  },
+});
+
+// Client-side error handling
+try {
+  await client.getUser(999);
+} catch (error) {
+  if (error instanceof SRPCError) {
+    console.log(error.code); // "NOT_FOUND"
+    console.log(error.message); // "User not found"
+  }
+}
+```
+
+### Custom Serialization
+
+Use custom serializers for complex data types:
+
+```typescript
+import { createSRPCClient } from "@srpc/core/client";
+import type { Serializer } from "@srpc/core/shared";
+
+// Example: Using superjson for Date, Map, Set support
+import superjson from "superjson";
+
+const customSerializer: Serializer = {
+  serialize: (value) => superjson.stringify(value),
+  deserialize: (value) => superjson.parse(value),
+};
+
+const client = createSRPCClient<AppRouter>({
+  endpoint: "http://localhost:3000/api",
+  transformer: customSerializer,
+});
+
+// Server-side
+const { fetch: handleRequest } = srpcFetchApi({
+  router: appRouter,
+  endpoint: "/api",
+  transformer: customSerializer,
+});
+```
+
+### Type Inference Utilities
+
+Extract input and output types from your router:
+
+```typescript
+import type { InferRouterInputs, InferRouterOutputs } from "@srpc.org/core";
+import type { AppRouter } from "./server";
+
+// Get all input types
+type RouterInputs = InferRouterInputs<AppRouter>;
+type GetUserInput = RouterInputs["getUser"]; // [id: number]
+
+// Get all output types
+type RouterOutputs = InferRouterOutputs<AppRouter>;
+type GetUserOutput = RouterOutputs["getUser"]; // { id: number, name: string, email: string }
+```
+
+### Server-Side Calling
+
+Call procedures directly on the server without HTTP:
+
+```typescript
+import { createSRPCCaller } from "@srpc/core/server";
+import { appRouter } from "./router";
+
+const caller = createSRPCCaller({
+  router: appRouter,
+  createContext: async () => ({ user: null, db: getDatabase() }),
+});
+
+// Call procedures directly
+const result = await caller.sayHello("World");
+```
+
+## API Reference
+
+### Server
+
+- `initSRPC()` - Initialize SRPC builder
+- `srpcFetchApi(options)` - Create Fetch API handler
+- `createSrpcServer(options)` - Create Node.js HTTP server
+- `createSRPCCaller(options)` - Create server-side caller
+
+### Client
+
+- `createSRPCClient<TRouter>(options)` - Create type-safe client
+
+### Shared
+
+- `SRPCError` - Error class with HTTP status mapping
+- `ErrorCodes` - Available error codes
+- `Serializer` - Serialization interface
+- `InferRouterInputs<TRouter>` - Extract input types
+- `InferRouterOutputs<TRouter>` - Extract output types
+
+## Error Codes
+
+- `BAD_REQUEST` → HTTP 400
+- `UNAUTHORIZED` → HTTP 401
+- `FORBIDDEN` → HTTP 403
+- `NOT_FOUND` → HTTP 404
+- `UNSUPPORTED_MEDIA_TYPE` → HTTP 415
+- `INTERNAL_SERVER_ERROR` → HTTP 500
+- `NOT_IMPLEMENTED` → HTTP 501
+- `GENERIC_ERROR` → HTTP 500
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,149 @@
+import { AnySRPC } from './server.js';
+import { Serializer, DecoratedProcedureRecord } from './shared.js';
+export * from './shared.js';
+
+type ProcedureType<TContext> = (
+  ctx: TContext,
+  ...args: any[]
+) => Promise<any> | any;
+
+type Routes<TContext> = {
+    [key: string]: ProcedureType<TContext> | SRPC<TContext>;
+};
+declare class SRPC<TContext, TRoutes extends Routes<TContext> = {}> {
+    __context: TContext;
+    ipc: TRoutes;
+    constructor(routes?: TRoutes);
+    context<T>(): SRPC<T>;
+    router<T extends Routes<TContext>>(routes: T): SRPC<TContext, T>;
+}
+
+/**
+ * @module
+ *
+ * Client-side SRPC module for creating type-safe RPC clients.
+ *
+ * This module provides the `createSRPCClient` function which creates a proxy-based
+ * client that converts method calls into HTTP requests to your SRPC server.
+ *
+ * @example
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import type { AppRouter } from "./server";
+ *
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "http://localhost:3000/api",
+ *   headers: async () => ({
+ *     "Authorization": `Bearer ${await getToken()}`
+ *   })
+ * });
+ *
+ * // Type-safe procedure calls
+ * const user = await client.users.getUser(1);
+ * const result = await client.users.admin.createUser({ name: "Jane" });
+ * ```
+ */
+
+/**
+ * Configuration options for creating an SRPC client.
+ *
+ * @property endpoint - Base URL for the SRPC server (e.g., "http://localhost:3000/api")
+ * @property headers - Optional function to provide custom headers for each request
+ * @property transformer - Optional custom serializer for request/response data (default: JSON)
+ * @property fetch - Optional custom fetch implementation (default: globalThis.fetch)
+ *
+ * @example
+ * ```typescript
+ * const options: SRPCClientOptions = {
+ *   endpoint: "http://localhost:3000/api",
+ *   headers: async ({ path }) => {
+ *     const token = await getAuthToken();
+ *     return {
+ *       "Authorization": `Bearer ${token}`,
+ *       "X-Request-Path": path.join(".")
+ *     };
+ *   },
+ *   transformer: customSerializer,
+ *   fetch: customFetch
+ * };
+ * ```
+ */
+type SRPCClientOptions = {
+    endpoint: string;
+    headers?: (op: {
+        path: readonly string[];
+    }) => HeadersInit | Promise<HeadersInit>;
+    transformer?: Serializer;
+    fetch?: typeof fetch;
+};
+/**
+ * Creates a type-safe SRPC client that converts method calls into HTTP requests.
+ *
+ * The client uses JavaScript Proxies to intercept property access and method calls,
+ * automatically converting them into HTTP POST requests to the server. All procedure
+ * calls are fully type-safe based on the router type provided.
+ *
+ * @template TRouter - The SRPC router type from your server
+ * @template TRoutes - Internal routes type (inferred automatically)
+ *
+ * @param options - Client configuration options
+ * @returns A type-safe client proxy matching your server's router structure
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import type { AppRouter } from "./server";
+ *
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "http://localhost:3000/api"
+ * });
+ *
+ * // All calls are type-checked
+ * const greeting = await client.sayHello("World"); // string
+ * const user = await client.users.getUser(1); // User type
+ * ```
+ *
+ * @example With authentication headers
+ * ```typescript
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "http://localhost:3000/api",
+ *   headers: async () => ({
+ *     "Authorization": `Bearer ${await getAuthToken()}`
+ *   })
+ * });
+ * ```
+ *
+ * @example With custom serialization
+ * ```typescript
+ * import superjson from "superjson";
+ *
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "http://localhost:3000/api",
+ *   transformer: {
+ *     serialize: (value) => superjson.stringify(value),
+ *     deserialize: (value) => superjson.parse(value)
+ *   }
+ * });
+ *
+ * // Now Date, Map, Set, etc. are properly serialized
+ * await client.createEvent({ date: new Date() });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * import { SRPCError } from "@srpc.org/core";
+ *
+ * try {
+ *   await client.users.getUser(999);
+ * } catch (error) {
+ *   if (error instanceof SRPCError) {
+ *     console.log(error.code); // "NOT_FOUND"
+ *     console.log(error.message); // "User not found"
+ *   }
+ * }
+ * ```
+ */
+declare const createSRPCClient: <TRouter extends AnySRPC, TRoutes extends Routes<any> = TRouter["ipc"]>({ endpoint, headers: getHeaders, transformer, fetch, }: SRPCClientOptions) => DecoratedProcedureRecord<TRoutes>;
+
+export { createSRPCClient };
+export type { SRPCClientOptions };

package/dist/client.js

@@ -0,0 +1,158 @@
+import { defaultSerializer, SRPCError } from './shared.js';
+export * from './shared.js';
+
+/**
+ * Used from trpc.io
+ */ const noop = ()=>{
+// noop
+};
+const freezeIfAvailable = (obj)=>{
+    if (Object.freeze) {
+        Object.freeze(obj);
+    }
+};
+function createInnerProxy(callback, path, memo) {
+    var _memo, _cacheKey;
+    const cacheKey = path.join(".");
+    (_memo = memo)[_cacheKey = cacheKey] ?? (_memo[_cacheKey] = new Proxy(noop, {
+        get (_obj, key) {
+            if (typeof key !== "string" || key === "then") {
+                // special case for if the proxy is accidentally treated
+                // like a PromiseLike (like in `Promise.resolve(proxy)`)
+                return undefined;
+            }
+            return createInnerProxy(callback, [
+                ...path,
+                key
+            ], memo);
+        },
+        apply (_1, _2, args) {
+            const lastOfPath = path[path.length - 1];
+            let opts = {
+                args,
+                path
+            };
+            // special handling for e.g. `trpc.hello.call(this, 'there')` and `trpc.hello.apply(this, ['there'])
+            if (lastOfPath === "call") {
+                opts = {
+                    args: args.length >= 2 ? [
+                        args[1]
+                    ] : [],
+                    path: path.slice(0, -1)
+                };
+            } else if (lastOfPath === "apply") {
+                opts = {
+                    args: args.length >= 2 ? args[1] : [],
+                    path: path.slice(0, -1)
+                };
+            } else if (lastOfPath === "toString") {
+                return path.slice(0, -1).join(".");
+            } else if (lastOfPath === "toJSON") {
+                return {
+                    path: path.slice(0, -1),
+                    pathString: path.slice(0, -1).join("."),
+                    __type: "SRPC"
+                };
+            }
+            freezeIfAvailable(opts.args);
+            freezeIfAvailable(opts.path);
+            return callback(opts);
+        }
+    }));
+    return memo[cacheKey];
+}
+/**
+ * Creates a proxy that calls the callback with the path and arguments
+ *
+ * @internal
+ */ const createRecursiveProxy = (callback)=>createInnerProxy(callback, [], Object.create(null));
+
+/**
+ * Creates a type-safe SRPC client that converts method calls into HTTP requests.
+ *
+ * The client uses JavaScript Proxies to intercept property access and method calls,
+ * automatically converting them into HTTP POST requests to the server. All procedure
+ * calls are fully type-safe based on the router type provided.
+ *
+ * @template TRouter - The SRPC router type from your server
+ * @template TRoutes - Internal routes type (inferred automatically)
+ *
+ * @param options - Client configuration options
+ * @returns A type-safe client proxy matching your server's router structure
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createSRPCClient } from "@srpc/core/client";
+ * import type { AppRouter } from "./server";
+ *
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "http://localhost:3000/api"
+ * });
+ *
+ * // All calls are type-checked
+ * const greeting = await client.sayHello("World"); // string
+ * const user = await client.users.getUser(1); // User type
+ * ```
+ *
+ * @example With authentication headers
+ * ```typescript
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "http://localhost:3000/api",
+ *   headers: async () => ({
+ *     "Authorization": `Bearer ${await getAuthToken()}`
+ *   })
+ * });
+ * ```
+ *
+ * @example With custom serialization
+ * ```typescript
+ * import superjson from "superjson";
+ *
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "http://localhost:3000/api",
+ *   transformer: {
+ *     serialize: (value) => superjson.stringify(value),
+ *     deserialize: (value) => superjson.parse(value)
+ *   }
+ * });
+ *
+ * // Now Date, Map, Set, etc. are properly serialized
+ * await client.createEvent({ date: new Date() });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * import { SRPCError } from "@srpc.org/core";
+ *
+ * try {
+ *   await client.users.getUser(999);
+ * } catch (error) {
+ *   if (error instanceof SRPCError) {
+ *     console.log(error.code); // "NOT_FOUND"
+ *     console.log(error.message); // "User not found"
+ *   }
+ * }
+ * ```
+ */ const createSRPCClient = ({ endpoint, headers: getHeaders, transformer = defaultSerializer, fetch = globalThis.fetch })=>{
+    return createRecursiveProxy(async ({ path, args })=>{
+        const headers = await getHeaders?.({
+            path: path
+        });
+        const response = await fetch(`${endpoint}/${path.join(".")}`, {
+            method: "POST",
+            body: transformer.serialize(args),
+            headers
+        });
+        const responseText = await response.text();
+        const data = transformer.deserialize(responseText);
+        if (!response.ok) {
+            if ("__BRAND__" in data && data.__BRAND__ === "SRPCError") {
+                throw new SRPCError(data.message, data.code);
+            }
+            throw new SRPCError(response.statusText || "Unknown error", "GENERIC_ERROR");
+        }
+        return data;
+    });
+};
+
+export { createSRPCClient };

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { ErrorCodes, InferRouterInputs, InferRouterOutputs, SRPCError } from './shared.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { SRPCError } from './shared.js';