@srpc.org/core 0.20.3

package/dist/shared.d.ts

@@ -0,0 +1,400 @@
+import { SRPC as SRPC$1, AnySRPC } from './server.js';
+
+type ProcedureType<TContext> = (
+  ctx: TContext,
+  ...args: any[]
+) => Promise<any> | any;
+
+type AnyProcedure = ProcedureType<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>;
+}
+
+/**
+ * Used from trpc.io
+ */
+interface ProxyCallbackOptions {
+    path: readonly string[];
+    args: readonly unknown[];
+}
+type ProxyCallback = (opts: ProxyCallbackOptions) => unknown;
+/**
+ * Creates a proxy that calls the callback with the path and arguments
+ *
+ * @internal
+ */
+declare const createRecursiveProxy: <TFaux = unknown>(callback: ProxyCallback) => TFaux;
+/**
+ * Used in place of `new Proxy` where each handler will map 1 level deep to another value.
+ *
+ * @internal
+ */
+declare const createFlatProxy: <TFaux>(callback: (path: string & keyof TFaux) => any) => TFaux;
+
+/**
+ * @module
+ *
+ * Shared SRPC utilities, types, and error handling.
+ *
+ * This module contains types and utilities used by both client and server sides:
+ * - Error handling with `SRPCError`
+ * - Serialization interfaces
+ * - Type inference utilities
+ * - Proxy utilities for dynamic API creation
+ *
+ * @example
+ * ```typescript
+ * import { SRPCError, type InferRouterInputs, type InferRouterOutputs } from "@srpc/core/shared";
+ *
+ * // Throw typed errors
+ * throw new SRPCError("Not found", "NOT_FOUND");
+ *
+ * // Extract types from router
+ * type Inputs = InferRouterInputs<AppRouter>;
+ * type Outputs = InferRouterOutputs<AppRouter>;
+ * ```
+ */
+
+/**
+ * Interface for custom serialization strategies.
+ *
+ * Implement this interface to support serialization formats beyond JSON,
+ * such as MessagePack, Protocol Buffers, or superjson for complex types.
+ *
+ * @example Using superjson for Date, Map, Set support
+ * ```typescript
+ * import superjson from "superjson";
+ * import type { Serializer } from "@srpc/core/shared";
+ *
+ * const customSerializer: Serializer = {
+ *   serialize: (value) => superjson.stringify(value),
+ *   deserialize: (value) => superjson.parse(value)
+ * };
+ *
+ * // Use with client
+ * const client = createSRPCClient<AppRouter>({
+ *   endpoint: "/api",
+ *   transformer: customSerializer
+ * });
+ *
+ * // Use with server
+ * const { fetch } = srpcFetchApi({
+ *   router: appRouter,
+ *   endpoint: "/api",
+ *   transformer: customSerializer
+ * });
+ * ```
+ */
+interface Serializer {
+    serialize: (value: any) => any;
+    deserialize: (value: any) => any;
+}
+/**
+ * Default JSON-based serializer used by SRPC.
+ *
+ * Uses `JSON.stringify` for serialization and `JSON.parse` for deserialization.
+ * Works with JSON-compatible types (strings, numbers, booleans, objects, arrays, null).
+ * Does not support: Date, Map, Set, undefined, functions, symbols.
+ *
+ * For complex types, provide a custom `Serializer` implementation.
+ */
+declare const defaultSerializer: Serializer;
+/**
+ * Union type of all standard error codes in SRPC.
+ *
+ * Each error code maps to a specific HTTP status code:
+ * - `BAD_REQUEST` → 400
+ * - `UNAUTHORIZED` → 401
+ * - `FORBIDDEN` → 403
+ * - `NOT_FOUND` → 404
+ * - `UNSUPPORTED_MEDIA_TYPE` → 415
+ * - `INTERNAL_SERVER_ERROR` → 500
+ * - `NOT_IMPLEMENTED` → 501
+ * - `GENERIC_ERROR` → 500 (fallback for unexpected errors)
+ */
+type ErrorCodes = "NOT_FOUND" | "FORBIDDEN" | "UNAUTHORIZED" | "INTERNAL_SERVER_ERROR" | "BAD_REQUEST" | "NOT_IMPLEMENTED" | "UNSUPPORTED_MEDIA_TYPE" | "GENERIC_ERROR";
+/**
+ * Mapping of error codes to HTTP status codes.
+ *
+ * Used internally by server adapters to convert `SRPCError` instances
+ * to appropriate HTTP responses.
+ */
+declare const StatusCodeMap: {
+    BAD_REQUEST: number;
+    NOT_FOUND: number;
+    FORBIDDEN: number;
+    UNAUTHORIZED: number;
+    INTERNAL_SERVER_ERROR: number;
+    NOT_IMPLEMENTED: number;
+    UNSUPPORTED_MEDIA_TYPE: number;
+    GENERIC_ERROR: number;
+};
+/**
+ * Standard error class for SRPC procedures.
+ *
+ * Thrown errors are automatically serialized and sent to the client with
+ * the appropriate HTTP status code. The client reconstructs the error
+ * with the same message and code.
+ *
+ * @example Throwing errors in procedures
+ * ```typescript
+ * import { SRPCError } from "@srpc.org/core";
+ *
+ * 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");
+ *     }
+ *     return user;
+ *   },
+ *   deleteUser: async (ctx, id: number) => {
+ *     if (!ctx.user?.isAdmin) {
+ *       throw new SRPCError("Insufficient permissions", "FORBIDDEN");
+ *     }
+ *     await db.users.delete(id);
+ *     return { success: true };
+ *   }
+ * });
+ * ```
+ *
+ * @example Handling errors on the client
+ * ```typescript
+ * import { SRPCError } from "@srpc.org/core";
+ *
+ * try {
+ *   const user = await client.getUser(999);
+ * } catch (error) {
+ *   if (error instanceof SRPCError) {
+ *     switch (error.code) {
+ *       case "NOT_FOUND":
+ *         console.log("User not found");
+ *         break;
+ *       case "FORBIDDEN":
+ *         console.log("Access denied");
+ *         break;
+ *       case "UNAUTHORIZED":
+ *         redirectToLogin();
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class SRPCError extends Error {
+    readonly code: ErrorCodes;
+    constructor(message: string, code: ErrorCodes);
+    __BRAND__: string;
+}
+/**
+ * Type utility to extract input parameter types from a single procedure.
+ *
+ * Returns a tuple of the procedure's parameters, excluding the context parameter.
+ *
+ * @template T - The procedure type to extract inputs from
+ *
+ * @example
+ * ```typescript
+ * import type { InferProcedureInput } from "@srpc/core/shared";
+ *
+ * type GetUserProcedure = (ctx: Context, id: number) => Promise<User>;
+ * type GetUserInput = InferProcedureInput<GetUserProcedure>; // [id: number]
+ *
+ * type CreateUserProcedure = (ctx: Context, name: string, email: string) => Promise<User>;
+ * type CreateUserInput = InferProcedureInput<CreateUserProcedure>; // [name: string, email: string]
+ * ```
+ */
+type InferProcedureInput<T extends AnyProcedure> = T extends (_ctx: any, ...args: infer TArgs) => any ? TArgs : never;
+/**
+ * Type utility to convert a server procedure to a client-side callable function.
+ *
+ * Removes the context parameter and preserves the return type.
+ *
+ * @template T - The procedure type to convert
+ *
+ * @example
+ * ```typescript
+ * import type { ClientProcedure } from "@srpc/core/shared";
+ *
+ * // Server procedure
+ * type ServerProc = (ctx: Context, id: number) => Promise<User>;
+ *
+ * // Client procedure (context removed)
+ * type ClientProc = ClientProcedure<ServerProc>; // (id: number) => Promise<User>
+ * ```
+ */
+type ClientProcedure<T extends AnyProcedure> = (...args: InferProcedureInput<T>) => ReturnType<T>;
+/**
+ * Type utility that transforms a router's procedures into client-callable functions.
+ *
+ * Recursively processes nested routers and converts each procedure to a client
+ * procedure (with context parameter removed).
+ *
+ * @template TRouter - The router routes type
+ *
+ * @example
+ * ```typescript
+ * import type { DecoratedProcedureRecord } from "@srpc/core/shared";
+ *
+ * // Server router
+ * const appRouter = s.router({
+ *   getUser: async (ctx, id: number) => ({ id, name: "John" }),
+ *   users: s.router({
+ *     admin: s.router({
+ *       createUser: async (ctx, data: UserData) => ({ id: 1, ...data })
+ *     })
+ *   })
+ * });
+ *
+ * type Routes = typeof appRouter["ipc"];
+ * type ClientAPI = DecoratedProcedureRecord<Routes>;
+ * // {
+ * //   getUser: (id: number) => Promise<{ id: number, name: string }>,
+ * //   users: {
+ * //     admin: {
+ * //       createUser: (data: UserData) => Promise<{ id: number } & UserData>
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+type DecoratedProcedureRecord<TRouter extends Routes<any>> = {
+    [TKey in keyof TRouter]: TRouter[TKey] extends AnyProcedure ? ClientProcedure<TRouter[TKey]> : TRouter[TKey] extends SRPC$1<any> ? DecoratedProcedureRecord<TRouter[TKey]["ipc"]> : never;
+};
+/**
+ * Type utility to extract the client API type from an SRPC router.
+ *
+ * Convenience type that wraps `DecoratedProcedureRecord`.
+ *
+ * @template TRouter - The SRPC router type
+ */
+type InferRPCFromRouter<TRouter extends AnySRPC> = DecoratedProcedureRecord<TRouter["ipc"]>;
+/**
+ * Type utility that extracts return types from all procedures in a router.
+ *
+ * Recursively processes nested routers and extracts awaited return types
+ * from each procedure.
+ *
+ * @template TRouter - The router routes type
+ *
+ * @example
+ * ```typescript
+ * import type { DecoratedProcedureOutputs } from "@srpc/core/shared";
+ *
+ * const appRouter = s.router({
+ *   getUser: async (ctx, id: number) => ({ id, name: "John" }),
+ *   users: s.router({
+ *     createUser: async (ctx, data: UserData) => ({ id: 1, ...data })
+ *   })
+ * });
+ *
+ * type Routes = typeof appRouter["ipc"];
+ * type Outputs = DecoratedProcedureOutputs<Routes>;
+ * // {
+ * //   getUser: { id: number, name: string },
+ * //   users: {
+ * //     createUser: { id: number } & UserData
+ * //   }
+ * // }
+ * ```
+ */
+type DecoratedProcedureOutputs<TRouter extends Routes<any>> = {
+    [TKey in keyof TRouter]: TRouter[TKey] extends AnyProcedure ? Awaited<ReturnType<TRouter[TKey]>> : TRouter[TKey] extends SRPC$1<any> ? DecoratedProcedureOutputs<TRouter[TKey]["ipc"]> : never;
+};
+/**
+ * Type utility to extract output types from all procedures in an SRPC router.
+ *
+ * Returns a mapped type where each key is a procedure name and the value
+ * is the awaited return type of that procedure.
+ *
+ * @template TRouter - The SRPC router type
+ *
+ * @example
+ * ```typescript
+ * import type { InferRouterOutputs } from "@srpc.org/core";
+ * import type { AppRouter } from "./server";
+ *
+ * type RouterOutputs = InferRouterOutputs<AppRouter>;
+ *
+ * // Use output types in your code
+ * type User = RouterOutputs["getUser"];
+ * type Post = RouterOutputs["posts"]["getPost"];
+ * ```
+ */
+type InferRouterOutputs<TRouter extends AnySRPC> = DecoratedProcedureOutputs<TRouter["ipc"]>;
+/**
+ * Type utility that extracts input parameter tuples from all procedures in a router.
+ *
+ * Recursively processes nested routers and extracts input parameters
+ * (excluding context) from each procedure.
+ *
+ * @template TRouter - The router routes type
+ *
+ * @example
+ * ```typescript
+ * import type { DecoratedProcedureInputs } from "@srpc/core/shared";
+ *
+ * const appRouter = s.router({
+ *   getUser: async (ctx, id: number) => ({ id, name: "John" }),
+ *   users: s.router({
+ *     createUser: async (ctx, name: string, email: string) => ({ id: 1, name, email })
+ *   })
+ * });
+ *
+ * type Routes = typeof appRouter["ipc"];
+ * type Inputs = DecoratedProcedureInputs<Routes>;
+ * // {
+ * //   getUser: [id: number],
+ * //   users: {
+ * //     createUser: [name: string, email: string]
+ * //   }
+ * // }
+ * ```
+ */
+type DecoratedProcedureInputs<TRouter extends Routes<any>> = {
+    [TKey in keyof TRouter]: TRouter[TKey] extends AnyProcedure ? InferProcedureInput<TRouter[TKey]> : TRouter[TKey] extends SRPC$1<any> ? DecoratedProcedureInputs<TRouter[TKey]["ipc"]> : never;
+};
+/**
+ * Type utility to extract input parameter types from all procedures in an SRPC router.
+ *
+ * Returns a mapped type where each key is a procedure name and the value
+ * is a tuple of that procedure's input parameters (excluding context).
+ *
+ * @template TRouter - The SRPC router type
+ *
+ * @example
+ * ```typescript
+ * import type { InferRouterInputs } from "@srpc.org/core";
+ * import type { AppRouter } from "./server";
+ *
+ * type RouterInputs = InferRouterInputs<AppRouter>;
+ *
+ * // Use input types in your code
+ * type GetUserArgs = RouterInputs["getUser"]; // [id: number]
+ * type CreatePostArgs = RouterInputs["posts"]["createPost"]; // [title: string, content: string]
+ *
+ * // Useful for creating type-safe helpers
+ * function callGetUser(...args: RouterInputs["getUser"]) {
+ *   return client.getUser(...args);
+ * }
+ * ```
+ */
+type InferRouterInputs<TRouter extends AnySRPC> = DecoratedProcedureInputs<TRouter["ipc"]>;
+
+/**
+ * Type representing any routes object with any context.
+ *
+ * Used as a constraint for generic types that accept any routes.
+ */
+type AnyRoutes = Routes<any>;
+
+export { SRPCError, StatusCodeMap, createFlatProxy, createRecursiveProxy, defaultSerializer };
+export type { AnyProcedure, AnyRoutes, ClientProcedure, DecoratedProcedureInputs, DecoratedProcedureOutputs, DecoratedProcedureRecord, ErrorCodes, InferProcedureInput, InferRPCFromRouter, InferRouterInputs, InferRouterOutputs, Routes, Serializer };

package/dist/shared.js

@@ -0,0 +1,168 @@
+/**
+ * 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));
+/**
+ * Used in place of `new Proxy` where each handler will map 1 level deep to another value.
+ *
+ * @internal
+ */ const createFlatProxy = (callback)=>{
+    return new Proxy(noop, {
+        get (_obj, name) {
+            if (typeof name !== "string" || name === "then") {
+                // special case for if the proxy is accidentally treated
+                // like a PromiseLike (like in `Promise.resolve(proxy)`)
+                return undefined;
+            }
+            return callback(name);
+        }
+    });
+};
+
+/**
+ * Default JSON-based serializer used by SRPC.
+ *
+ * Uses `JSON.stringify` for serialization and `JSON.parse` for deserialization.
+ * Works with JSON-compatible types (strings, numbers, booleans, objects, arrays, null).
+ * Does not support: Date, Map, Set, undefined, functions, symbols.
+ *
+ * For complex types, provide a custom `Serializer` implementation.
+ */ const defaultSerializer = {
+    serialize: (value)=>JSON.stringify(value),
+    deserialize: (value)=>JSON.parse(value)
+};
+/**
+ * Mapping of error codes to HTTP status codes.
+ *
+ * Used internally by server adapters to convert `SRPCError` instances
+ * to appropriate HTTP responses.
+ */ const StatusCodeMap = {
+    BAD_REQUEST: 400,
+    NOT_FOUND: 404,
+    FORBIDDEN: 403,
+    UNAUTHORIZED: 401,
+    INTERNAL_SERVER_ERROR: 500,
+    NOT_IMPLEMENTED: 501,
+    UNSUPPORTED_MEDIA_TYPE: 415,
+    GENERIC_ERROR: 500
+};
+/**
+ * Standard error class for SRPC procedures.
+ *
+ * Thrown errors are automatically serialized and sent to the client with
+ * the appropriate HTTP status code. The client reconstructs the error
+ * with the same message and code.
+ *
+ * @example Throwing errors in procedures
+ * ```typescript
+ * import { SRPCError } from "@srpc.org/core";
+ *
+ * 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");
+ *     }
+ *     return user;
+ *   },
+ *   deleteUser: async (ctx, id: number) => {
+ *     if (!ctx.user?.isAdmin) {
+ *       throw new SRPCError("Insufficient permissions", "FORBIDDEN");
+ *     }
+ *     await db.users.delete(id);
+ *     return { success: true };
+ *   }
+ * });
+ * ```
+ *
+ * @example Handling errors on the client
+ * ```typescript
+ * import { SRPCError } from "@srpc.org/core";
+ *
+ * try {
+ *   const user = await client.getUser(999);
+ * } catch (error) {
+ *   if (error instanceof SRPCError) {
+ *     switch (error.code) {
+ *       case "NOT_FOUND":
+ *         console.log("User not found");
+ *         break;
+ *       case "FORBIDDEN":
+ *         console.log("Access denied");
+ *         break;
+ *       case "UNAUTHORIZED":
+ *         redirectToLogin();
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */ class SRPCError extends Error {
+    constructor(message, code){
+        super(message), this.code = code, this.__BRAND__ = "SRPCError";
+        this.name = "SRPCError";
+    }
+}
+
+export { SRPCError, StatusCodeMap, createFlatProxy, createRecursiveProxy, defaultSerializer };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@srpc.org/core",
+  "version": "0.20.3",
+  "description": "A lightweight, type-safe RPC framework for TypeScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.ts",
+      "default": "./dist/shared.js"
+    }
+  },
+  "keywords": [
+    "rpc",
+    "typescript",
+    "type-safe",
+    "api",
+    "client",
+    "server"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "bunchee": "^6.6.2",
+    "get-port-please": "^3.1.2",
+    "vitest": "^4.0.10"
+  },
+  "scripts": {
+    "build": "bunchee",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "version": "node ../../version.mjs",
+    "release:npm": "pnpm publish --access=public",
+    "release:jsr": "pnpx jsr publish"
+  }
+}