Fix misc typings, RPC logic, OpenAPI generation etc. (#108)

This bumps the Next.js version to 14 and
adds various typing improvements, OpenAPI
generation, RPC and docs improvements for
client implementation.

apps/example/src/actions.ts

@@ -0,0 +1,83 @@
+'use server';
+
+import { rpcOperation } from 'next-rest-framework';
+import { MOCK_TODOS, todoSchema } from 'utils';
+import { z } from 'zod';
+
+// The RPC operations can be used as server-actions and imported in the RPC route handlers.
+
+export const getTodos = rpcOperation({
+  tags: ['RPC']
+})
+  .outputs([
+    {
+      schema: z.array(todoSchema)
+    }
+  ])
+  .handler(() => {
+    return MOCK_TODOS; // Type-checked output.
+  });
+
+export const getTodoById = rpcOperation({
+  tags: ['RPC']
+})
+  .input(z.string())
+  .outputs([
+    {
+      schema: z.object({
+        error: z.string()
+      })
+    },
+    {
+      schema: todoSchema
+    }
+  ])
+  .handler((id) => {
+    const todo = MOCK_TODOS.find((t) => t.id === Number(id));
+
+    if (!todo) {
+      return { error: 'TODO not found.' }; // Type-checked output.
+    }
+
+    return todo; // Type-checked output.
+  });
+
+export const createTodo = rpcOperation({
+  tags: ['RPC']
+})
+  .input(
+    z.object({
+      name: z.string()
+    })
+  )
+  .outputs([{ schema: todoSchema }])
+  .handler(
+    async ({
+      name // Strictly-typed input.
+    }) => {
+      // Create todo.
+      const todo = { id: 2, name, completed: false };
+      return todo; // Type-checked output.
+    }
+  );
+
+export const deleteTodo = rpcOperation({
+  tags: ['RPC']
+})
+  .input(z.string())
+  .outputs([
+    { schema: z.object({ error: z.string() }) },
+    { schema: z.object({ message: z.string() }) }
+  ])
+  .handler((id) => {
+    // Delete todo.
+    const todo = MOCK_TODOS.find((t) => t.id === Number(id));
+
+    if (!todo) {
+      return {
+        error: 'TODO not found.' // Type-checked output.
+      };
+    }
+
+    return { message: 'TODO deleted.' }; // Type-checked output.
+  });

apps/example/src/app/api/v2/route.ts

@@ -0,0 +1,6 @@
+import { docsRoute } from 'next-rest-framework';
+
+export const { GET } = docsRoute({
+  deniedPaths: ['/api/routes/third-party-endpoint'],
+  openApiJsonPath: '/openapi.json'
+});

apps/example/src/app/api/v2/rpc/[operationId]/route.ts

@@ -0,0 +1,13 @@
+import { createTodo, deleteTodo, getTodoById, getTodos } from 'actions';
+import { rpcRoute } from 'next-rest-framework';
+
+const { POST, client } = rpcRoute({
+  getTodos,
+  getTodoById,
+  createTodo,
+  deleteTodo
+});
+
+export type RpcClient = typeof client;
+
+export { POST };

apps/example/src/app/api/routes/todos/[id]/route.ts → apps/example/src/app/api/v2/todos/[id]/route.ts

@@ -1,8 +1,4 @@
-import {
-  TypedNextResponse,
-  routeHandler,
-  routeOperation
-} from 'next-rest-framework';
+import { TypedNextResponse, route, routeOperation } from 'next-rest-framework';
 import { z } from 'zod';
 
 const TODOS = [
@@ -14,10 +10,13 @@ const TODOS = [
 ];
 
 // Example dynamic App Router route handler with GET/DELETE handlers.
-export const GET = routeHandler({
-  GET: routeOperation({
-    operationId: 'getTodoById',
-    tags: ['example-api', 'todos', 'app-router']
+export const { GET, DELETE } = route({
+  getTodoById: routeOperation({
+    method: 'GET',
+    // Optional OpenAPI operation documentation.
+    openApiOperation: {
+      tags: ['example-api', 'todos', 'app-router']
+    }
   })
     .outputs([
       {
@@ -49,9 +48,12 @@ export const GET = routeHandler({
       });
     }),
 
-  DELETE: routeOperation({
-    operationId: 'deleteTodo',
-    tags: ['example-api', 'todos', 'app-router']
+  deleteTodo: routeOperation({
+    method: 'DELETE',
+    // Optional OpenAPI operation documentation.
+    openApiOperation: {
+      tags: ['example-api', 'todos', 'app-router']
+    }
   })
     .outputs([
       {

apps/example/src/app/api/routes/todos/route.ts → apps/example/src/app/api/v2/todos/route.ts

@@ -1,50 +1,37 @@
-import {
-  TypedNextResponse,
-  routeHandler,
-  routeOperation
-} from 'next-rest-framework';
+import { TypedNextResponse, route, routeOperation } from 'next-rest-framework';
+import { MOCK_TODOS, todoSchema } from 'utils';
 import { z } from 'zod';
 
-const TODOS = [
-  {
-    id: 1,
-    name: 'TODO 1',
-    completed: false
-  }
-];
-
 // Example App Router route handler with GET/POST handlers.
-const handler = routeHandler({
-  GET: routeOperation({
+const { GET, POST } = route({
+  getTodos: routeOperation({
+    method: 'GET',
     // Optional OpenAPI operation documentation.
-    operationId: 'getTodos',
-    tags: ['example-api', 'todos', 'app-router']
+    openApiOperation: {
+      tags: ['example-api', 'todos', 'app-router']
+    }
   })
     // Output schema for strictly-typed responses and OpenAPI documentation.
     .outputs([
       {
         status: 200,
         contentType: 'application/json',
-        schema: z.array(
-          z.object({
-            id: z.number(),
-            name: z.string(),
-            completed: z.boolean()
-          })
-        )
+        schema: z.array(todoSchema)
       }
     ])
     .handler(() => {
       // Type-checked response.
-      return TypedNextResponse.json(TODOS, {
+      return TypedNextResponse.json(MOCK_TODOS, {
         status: 200
       });
     }),
 
-  POST: routeOperation({
+  createTodo: routeOperation({
+    method: 'POST',
     // Optional OpenAPI operation documentation.
-    operationId: 'createTodo',
-    tags: ['example-api', 'todos', 'app-router']
+    openApiOperation: {
+      tags: ['example-api', 'todos', 'app-router']
+    }
   })
     // Input schema for strictly-typed request, request validation and OpenAPI documentation.
     .input({
@@ -66,15 +53,17 @@ const handler = routeHandler({
         schema: z.string()
       }
     ])
-    // Optional middleware logic executed before request validation.
-    .middleware((req) => {
-      if (!req.headers.get('authorization')) {
-        // Type-checked response.
-        return TypedNextResponse.json('Unauthorized', {
-          status: 401
-        });
+    .middleware(
+      // Optional middleware logic executed before request validation.
+      (req) => {
+        if (!req.headers.get('authorization')) {
+          // Type-checked response.
+          return TypedNextResponse.json('Unauthorized', {
+            status: 401
+          });
+        }
       }
-    })
+    )
     .handler(async (req) => {
       const { name } = await req.json(); // Strictly-typed request.
 
@@ -85,4 +74,4 @@ const handler = routeHandler({
     })
 });
 
-export { handler as GET, handler as POST };
+export { GET, POST };

apps/example/src/app/client/ClientExample.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import { type RpcClient } from 'app/api/v2/rpc/[operationId]/route';
+import { rpcClient } from 'next-rest-framework/dist/client/rpc-client';
+import { useEffect, useState } from 'react';
+import { type Todo } from 'utils';
+
+const client = rpcClient<RpcClient>({
+  url: 'http://localhost:3000/api/v2/rpc'
+});
+
+export const ClientExample: React.FC = () => {
+  const [loading, setLoading] = useState(true);
+  const [todos, setTodos] = useState<Todo[]>([]);
+
+  useEffect(() => {
+    client
+      .getTodos()
+      .then(setTodos)
+      .catch(console.error)
+      .finally(() => {
+        setLoading(false);
+      });
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <h1 className="text-2xl font-bold">RPC client example</h1>
+      {loading ? (
+        <p>Loading...</p>
+      ) : (
+        <>
+          <p>Data:</p> <p>{JSON.stringify(todos)}</p>
+        </>
+      )}
+    </div>
+  );
+};