feat(server)!: redesign callable ability (#78)

* class

* wip

* createProcedureClient now accept 2 args

* createRouterClient new accept 2 args

* callable

* actionable

* docs

* call utils

* client context

* decorated lazy now not callable

* fixed

* docs: Server Action tab

* fix spacing

* fix spacing

Author: unnoq

apps/content/content/docs/client/react-query.mdx

@@ -135,7 +135,7 @@ queryClient.invalidateQueries({ queryKey: orpc.posts.getPost.key({ input: { id:
 Infinite queries require a `cursor` in the input field for pagination.
 
 ```tsx twoslash
-import { os } from '@orpc/server';
+import { os, createRouterClient } from '@orpc/server';
 import { z } from 'zod';
 import { createORPCReactQueryUtils } from '@orpc/react-query';
 import { useInfiniteQuery, useSuspenseInfiniteQuery } from '@tanstack/react-query';
@@ -152,7 +152,8 @@ const router = {
   },
 };
 
-const orpc = createORPCReactQueryUtils<typeof router>('fake-client' as any);
+const client = createRouterClient(router); // or any kind of client
+const orpc = createORPCReactQueryUtils(client);
 
 export function MyComponent() {
   const query = useInfiniteQuery(

apps/content/content/docs/client/vue-query.mdx

@@ -76,7 +76,7 @@ queryClient.invalidateQueries({ queryKey: orpc.posts.getPost.key({ input: { id:
 Infinite queries require a `cursor` in the input field for pagination.
 
 ```ts twoslash
-import { os } from '@orpc/server';
+import { os, createRouterClient } from '@orpc/server';
 import { z } from 'zod';
 import { createORPCVueQueryUtils } from '@orpc/vue-query';
 import { useInfiniteQuery } from '@tanstack/vue-query';
@@ -92,7 +92,8 @@ const router = {
   },
 };
 
-const orpc = createORPCVueQueryUtils<typeof router>('fake-client' as any);
+const client = createRouterClient(router); // or any kind of client
+const orpc = createORPCVueQueryUtils(client);
 
 const query = useInfiniteQuery(
   orpc.user.list.infiniteOptions({

apps/content/content/docs/server/client.mdx

@@ -3,86 +3,61 @@ title: Caller/Client
 description: Make your procedures callable in oRPC.
 ---
 
-## Direct Procedure Calls
-
-You can directly call a procedure if its [Global Context](/docs/server/global-context) can accept `undefined`.
-For security reasons, context cannot be passed when invoking such procedures directly.
+## Make procedures callable with `.callable()`
 
 ```ts twoslash
-import { os, createProcedureClient } from '@orpc/server'
+import { os } from '@orpc/server'
 import { z } from 'zod'
 
-// ❌ Cannot call this procedure directly because undefined is not assignable to 'Context'
-const e1 = os.context<{ auth: boolean }>().handler(() => 'pong')
-// @errors: 2349
-e1() // Error: Procedure 'e1' cannot be called directly
-
-// ✅ Can call this procedure directly because undefined is assignable to 'Context'
-const e2 = os.context<{ auth: boolean } | undefined>().handler(() => 'pong')
-const o2 = await e2() // Ok, output is 'pong'
-
-// ✅ Can call this procedure directly because undefined is assignable to 'Context'
-const getting = os.input(z.object({ name: z.string() })).handler(({ input }) => `Hello, ${input.name}!`)
-
-const router = os.router({
-    getting
-})
-
-// call directly
-const output = await getting({ name: 'World' }) // output is 'Hello, World!'
-// or through router
-const output_ = await router.getting({ name: 'World' }) // output is 'Hello, World!'
+export const getting = os
+  .input(z.object({
+    name: z.string(),
+  }))
+  .output(z.string())
+  .handler(async ({ input }) => {
+    return `Hello ${input.name}`
+  })
+  .callable()
+
+// use it like a regular function
+const output = await getting({ name: 'Unnoq' })
 ```
 
-## Calling Procedures with Context
-
-For context-sensitive calls, use a Procedure Client. 
-A Procedure Client securely provides the required context during invocation.
+## use `call` helper function
 
 ```ts twoslash
-import { os, createProcedureClient } from '@orpc/server'
-
-type Context = { user?: { id: string } }
-
-const getting = os.context<Context>().handler(() => 'pong')
-
-const gettingClient = createProcedureClient({
-    procedure: getting,
-    context: async () => {
-        // you can access headers, cookies, etc. here to create context
-        return { user: { id: 'example' } }
-    },
-})
+import { call } from '@orpc/server'
+import { os } from '@orpc/server'
+import { z } from 'zod'
 
-const output = await gettingClient() // output is 'pong'
+export const getting = os
+  .input(z.object({
+    name: z.string(),
+  }))
+  .output(z.string())
+  .handler(async ({ input }) => {
+    return `Hello ${input.name}`
+  })
+
+// call a procedure without creating a client
+const output = await call(getting, { name: 'Unnoq' })
 ```
 
-Now, you can provide context when invoking a procedure. 
-Additionally, you can use `gettingClient` as a [Server Action](/docs/server/server-action).
-
-## Calling Routers with Shared Context
+## Use `createRouterClient` or `createProcedureClient`
 
 To call multiple procedures with shared context, use a `Router Client`.
 
 ```ts twoslash
-import { os, createRouterClient } from '@orpc/server'
+import { os, createRouterClient, createProcedureClient } from '@orpc/server'
 
 const router = os.router({
     ping: os.handler(() => 'pong')
 })
 
-const client = createRouterClient({
-    router: router,
-    context: {},
-})
+const client = createRouterClient(router)
 
 const result = await client.ping() // result is 'pong'
-```
-
-## Summary
-
-- **Direct Calls:** Use when no context is required, or the context accepts `undefined`.
-- **Procedure Client:** Use for securely calling a single procedure with a specific context.
-- **Router Client:** Use for securely calling multiple procedures with shared context.
 
-oRPC provides flexible and secure ways to invoke procedures tailored to your application needs.
+const pingClient = createProcedureClient(router.ping)
+const result2 = await pingClient() // result is 'pong'
+```

apps/content/content/docs/server/context.mdx

@@ -45,7 +45,7 @@ If your procedure only depends on `Middleware Context`, you can
 [call it](/docs/server/client) or use it as a [Server Action](/docs/server/server-action) directly.
 
 ```ts twoslash
-import { os, ORPCError } from '@orpc/server'
+import { os, ORPCError, call } from '@orpc/server'
 import { headers } from 'next/headers'
 
 const base = os.use(async ({ context, path, next }, input) => {
@@ -80,7 +80,7 @@ export const router = base.router({
 })
 
 // You can call this procedure directly without manually providing context
-const output = await router.getUser()
+const output = await call(router.getUser, null)
 
 import { ORPCHandler } from '@orpc/server/fetch'
 import { OpenAPIServerlessHandler, OpenAPIServerHandler } from '@orpc/openapi/fetch'
@@ -144,8 +144,7 @@ export async function fetch(request: Request) {
 
 // If you want to call this procedure or use as server action
 //  you must create another client with context by using `createProcedureClient` or `createRouterClient`
-const client = createProcedureClient({
-    procedure: router.getUser,
+const client = createProcedureClient(router.getUser, {
     context: async () => {
         // some logic to create context
         return { 

apps/content/content/docs/server/error-handling.mdx

@@ -31,7 +31,7 @@ const createPost = os
     // throw errors.ANY_CODE()
   })
 
-const client = createProcedureClient({ procedure: createPost }) // or any kind of client
+const client = createProcedureClient(createPost) // or any kind of client
 
 const [data, error, isDefined] = await safe(client({ title: 'title' }))
 

apps/content/content/docs/server/lazy.mdx

@@ -14,7 +14,7 @@ Lazy routers make your application modular and efficient without sacrificing eas
 Here's how you can set up and use them:
 
 ```typescript twoslash
-import { os } from '@orpc/server'
+import { os, call } from '@orpc/server'
 
 const pub = os.context<{ user?: { id: string } } | undefined>()
 
@@ -26,7 +26,7 @@ const router = pub.router({
 })
 
 // Use the lazy-loaded router as if it were a regular one
-const output = await router.lazy.getUser({ id: '123' })
+const output = await call(router.lazy.getUser, { id: '123' })
 ```
 
 ### Key Points:

apps/content/content/docs/server/meta.json

@@ -7,6 +7,7 @@
     "contract",
     "file-upload",
     "lazy",
+    "server-action",
     "client",
     "error-handling",
     "data-types",

apps/content/content/docs/server/server-action.mdx

@@ -0,0 +1,100 @@
+---
+title: Server Actions
+description: Leverage oRPC for type-safe and powerful server actions
+---
+
+Server Actions in oRPC allow you to define type-safe server-side procedures that can be seamlessly invoked from client applications. 
+To enable a procedure as a server action, you need to call the `.actionable()` method.
+
+## Basic Usage
+
+To make a procedure compatible with server actions, use `.actionable()` as shown below:
+
+```ts twoslash
+'use server'
+
+import { os } from '@orpc/server'
+import { z } from 'zod'
+
+export const getting = os
+  .input(z.object({
+    name: z.string(),
+  }))
+  .output(z.string())
+  .handler(async ({ input }) => {
+    return `Hello ${input.name}`
+  })
+  .actionable()
+
+// from client just call it as a function
+const onClick = async () => {
+  const result = await getting({ name: 'Unnoq' })
+  alert(result)
+}
+```
+
+## Passing Context via `.actionable()`
+
+When calling `.actionable()`, you can pass a context function that provides additional information for the procedure:
+
+```ts twoslash
+'use server'
+
+import { os } from '@orpc/server'
+import { z } from 'zod'
+
+const pub = os.context<{ db: string } | undefined>()
+
+export const getting = pub
+  .input(z.object({
+    name: z.string(),
+  }))
+  .output(z.string())
+  .handler(async ({ input, context }) => {
+    // ^ context is fully typed
+    return `Hello ${input.name}`
+  })
+  .actionable({
+    context: async () => { // or just pass context directly
+      return { db: 'postgres' }
+    },
+  })
+```
+
+## Using Middleware to Inject Context
+
+Middleware can be used to inject context dynamically before the procedure is executed:
+
+```ts twoslash
+'use server'
+
+import { ORPCError, os } from '@orpc/server'
+import { headers } from 'next/headers'
+import { z } from 'zod'
+
+const authed = os.use(async ({ next }) => {
+  const headersList = await headers()
+  const user = headersList.get('Authorization') ? { id: 'example' } : undefined
+
+  if (!user) {
+    throw new ORPCError({ code: 'UNAUTHORIZED' })
+  }
+
+  return next({
+    context: {
+      user,
+    },
+  })
+})
+
+export const getting = authed
+  .input(z.object({
+    name: z.string(),
+  }))
+  .output(z.string())
+  .handler(async ({ input, context }) => {
+    // ^ context is fully typed
+    return `Hello ${input.name}`
+  })
+  .actionable()
+```

apps/content/content/home/landing.mdx

@@ -30,6 +30,8 @@ export const updateUser = os
 		// or throw
 		throw errors.NOT_FOUND({ data: { why: 'some reason' } })
 	})
+	.callable() // make this work like a regular function
+	.actionable() // like .callable but compatible with server action
 ```
 
 > Only the `.handler` method is required. All other chain methods are optional.

apps/content/content/home/server.mdx

@@ -42,4 +42,15 @@
 }
 ```
 </Tab>
+
+<Tab value="Server Action">
+```json doc-gen:file
+{
+  "file": "examples/server-action.ts",
+  "codeblock": {
+    "meta": "twoslash"
+  }
+}
+```
+</Tab>
 </Tabs>