@creatorem/next-trpc 1.0.1 → 1.0.5

package/README.md

@@ -1,2 +1,215 @@
 # next-trpc
-A simple typed rpc interface to easily type api endpoints in a app router nextjs application
+
+A simple typed rpc interface to easily type api endpoints in an app router nextjs application.
+
+## Installation
+
+```sh
+npm install @creatorem/next-trpc
+```
+
+<br/>
+
+## Setup
+
+### Create a router file
+
+Contains your api endpoints.
+
+`trpc/router.ts`
+
+```ts
+import { router, endpoint } from "@creatorem/next-trpc";
+import z from "zod";
+
+export const appRouter = router({
+  getUser: endpoint.action(async ({ db }) => {
+    return await myAsyncFunction();
+  }),
+  greeting: endpoint
+    .input(
+      // you can add zod typechecking to your entry params
+      z.object({
+        name: z.string(),
+        age: z.coerce.number(),
+      })
+    )
+    .action(({ name, age }) => {
+      return `Hi my name is ${name}, and I am ${age} years old.`;
+    }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### Connect your router to an api endpoint.
+
+`app/api/trpc/[trpc]/route.ts`
+
+```ts
+import { createTrpcAPI } from "@creatorem/next-trpc/server";
+import { appRouter } from "~/trpc/router";
+
+const handler = createTrpcAPI({
+  router: appRouter,
+});
+
+export { handler as GET, handler as POST };
+```
+
+### Start fetching with a type safe client!
+
+`trpc/client.ts`
+
+```ts
+import { envs } from "~/envs";
+import { createTrpcClient } from "@creatorem/next-trpc/client";
+import { type AppRouter } from "./router";
+
+const url = envs().NEXT_PUBLIC_YOUR_APP_URL + "/api/trpc";
+
+export const trpc = createTrpcClient<AppRouter>({
+  url,
+  headers: async () => {
+    // add custom headers like Authorization to make it works with auth logic
+    return {
+      /* Authorization: `Bearer ${jwt!}` */
+    };
+  },
+});
+```
+
+Done !
+
+## Usage
+
+Now you can use the `trpc` client and server side.
+
+`app/layout.tsx`
+
+```tsx
+import React from "react";
+import { redirect } from "next/navigation";
+import { trpc } from "~/trpc/client";
+
+export default async function Layout(
+  props: React.PropsWithChildren
+): Promise<React.JSX.Element> {
+  const user = await trpc.getUser.fetch();
+
+  if (!user) {
+    return redirect(/* path to login page */);
+  }
+
+  return <>{props.children}</>;
+}
+```
+
+### Integrated useQuery hook usage
+
+We offer a client side only function to create client object that pre-implement the `useQuery` hook from `@tanstack/react-query` package.
+
+You need to have `@tanstack/react-query` installed.
+
+```sh
+npm install @tanstack/react-query
+```
+
+Then you can create the following file :
+
+`trpc/query-client.ts`
+
+```ts
+import "client-only";
+
+import { envs } from "~/envs";
+import { createTrpcQueryClient } from "@creatorem/next-trpc/query-client";
+import { type AppRouter } from "./router";
+
+const url = envs().NEXT_PUBLIC_YOUR_APP_URL + "/api/trpc";
+
+export const clientTrpc = createTrpcQueryClient<AppRouter>({
+  url,
+  headers: async () => {
+    // add custom headers like Authorization to make it works with auth logic
+    return {
+      /* Authorization: `Bearer ${jwt!}` */
+    };
+  },
+});
+```
+
+Now you can do :
+
+```tsx
+"use client";
+
+import React from "react";
+import { clientTrpc } from "~/trpc/query-client";
+
+export const MyClientComponent: React.FC<React.PropsWithChildren> = (props) => {
+  const { data: user } = clientTrpc.getUser.useQuery();
+  /* ... */
+
+  return <>{props.children}</>;
+};
+```
+
+> [!WARNING]
+> Do not forget to wrap your app with `<QueryClientProvider>`. See [installation instructions](https://tanstack.com/query/latest/docs/framework/react/installation) for more details.
+
+## Use a router context
+
+You can use a context object to pass data to all your endpoint callbacks.
+
+`trpc/router.ts`
+
+```ts {4-7,9}
+import { CtxRouter, endpoint } from "@creatorem/next-trpc";
+import z from "zod";
+
+export const createContext = async () => {
+  /* your own context logic here ... */
+  return { db /* let's say db is a database client. */ };
+};
+
+const ctx = new CtxRouter<Awaited<ReturnType<typeof createContext>>>();
+
+export const appRouter = ctx.router({
+  getUser: ctx.endpoint.action(async ({ db }) => {
+    return await db.user.get();
+  }),
+  greeting: ctx.endpoint
+    .input(
+      // you can add zod typechecking to your entry params
+      z.object({
+        name: z.string(),
+        age: z.coerce.number(),
+      })
+    )
+    .action(({ name, age }) => {
+      return `Hi my name is ${name}, and I am ${age} years old.`;
+    }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+> [!NOTE]
+> Param types are serialized during the http request to the api. You need to use `z.coerce` for non-string types.
+
+Next pass your context to the nextjs api endpoint.
+
+`app/api/trpc/[trpc]/route.ts`
+
+```ts {6}
+import { createTrpcAPI } from "@creatorem/next-trpc/server";
+import { appRouter, createContext } from "~/trpc/router";
+
+const handler = createTrpcAPI({
+  router: appRouter,
+  ctx: createContext,
+});
+
+export { handler as GET, handler as POST };
+```

package/dist/core.d.ts

@@ -1,21 +1,27 @@
-import { type Schema } from "zod";
+import z, { type Schema } from "zod";
 import type { NextRequest } from "next/server";
 export type Endpoint<Output, Input extends Schema | undefined = undefined, Ctx = {}> = {
     input?: Input;
     action: Input extends undefined ? (context: {
         request: NextRequest;
-    } & Ctx) => Output : (input: Input extends Schema ? import("zod").infer<Input> : Input, context: {
+    } & Ctx) => Output : (input: Input extends Schema ? z.infer<Input> : Input, context: {
         request: NextRequest;
     } & Ctx) => Output;
 };
 export declare const endpoint: {
-    input: <Input extends Schema, Ctx>(schema: Input) => {
-        action: <Output>(actionFn: Endpoint<Output, Input, Ctx>["action"]) => Endpoint<Output, Input, Ctx>;
+    input: <Input extends Schema>(schema: Input) => {
+        action: <Output, Ctx = {}>(actionFn: Endpoint<Output, Input, Ctx>["action"]) => Endpoint<Output, Input, Ctx>;
     };
-    action: <Output, Ctx>(actionFn: Endpoint<Output, undefined, Ctx>["action"]) => Endpoint<Output, undefined, Ctx>;
+    action: <Output, Ctx = {}>(actionFn: Endpoint<Output, undefined, Ctx>["action"]) => Endpoint<Output, undefined, Ctx>;
 };
 export type Router<Ctx> = Record<string, Endpoint<any, any, Ctx>>;
 export declare const router: <Ctx, R extends Router<Ctx>>(r: R) => R;
 export declare class CtxRouter<Ctx> {
+    endpoint: {
+        input: <Input extends Schema>(schema: Input) => {
+            action: <Output>(actionFn: Endpoint<Output, Input, Ctx>["action"]) => Endpoint<Output, Input, Ctx>;
+        };
+        action: <Output>(actionFn: Endpoint<Output, undefined, Ctx>["action"]) => Endpoint<Output, undefined, Ctx>;
+    };
     router<R extends Router<Ctx>>(r: R): R;
 }

package/dist/core.js

@@ -1,4 +1,7 @@
-export const endpoint = {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CtxRouter = exports.router = exports.endpoint = void 0;
+exports.endpoint = {
     input: (schema) => ({
         action: (actionFn) => ({
             input: schema,
@@ -9,9 +12,24 @@ export const endpoint = {
         action: actionFn,
     }),
 };
-export const router = (r) => r;
-export class CtxRouter {
+const router = (r) => r;
+exports.router = router;
+class CtxRouter {
+    constructor() {
+        this.endpoint = {
+            input: (schema) => ({
+                action: (actionFn) => ({
+                    input: schema,
+                    action: actionFn,
+                }),
+            }),
+            action: (actionFn) => ({
+                action: actionFn,
+            }),
+        };
+    }
     router(r) {
         return r;
     }
 }
+exports.CtxRouter = CtxRouter;

package/dist/{create-rpc-api.d.ts → create-trpc-api.d.ts}

@@ -1,6 +1,6 @@
 import { type NextRequest, NextResponse } from "next/server";
 import { type router as routerFn, Router } from "./core";
-export declare const createRpcAPI: <Ctx>({ router, ctx, }: {
+export declare const createTrpcAPI: <Ctx>({ router, ctx, }: {
     router: ReturnType<typeof routerFn<any, Router<any>>>;
     ctx?: (request: NextRequest) => Promise<Ctx>;
 }) => (request: NextRequest, context: {

package/dist/{create-rpc-api.js → create-trpc-api.js}

@@ -1,6 +1,9 @@
+"use strict";
 "server-only";
-import { NextResponse } from "next/server";
-import { camelize } from "./utils";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrpcAPI = void 0;
+const server_1 = require("next/server");
+const utils_1 = require("./utils");
 const parseInput = (request, endpoint) => {
     if (!endpoint.input)
         return undefined;
@@ -13,24 +16,24 @@ const parseInput = (request, endpoint) => {
     // Validate input with endpoint schema
     return endpoint.input.parse(paramsObj);
 };
-export const createRpcAPI = ({ router, ctx, }) => {
+const createTrpcAPI = ({ router, ctx, }) => {
     return async function handler(request, context) {
         const params = (await context.params);
-        if (!("rpc" in params)) {
-            return NextResponse.json({
+        if (!("trpc" in params)) {
+            return server_1.NextResponse.json({
                 data: null,
-                error: "You must call createAPI in a [rpc]/route.ts file.",
+                error: "You must call createAPI in a [trpc]/route.ts file.",
             }, { status: 400 });
         }
-        if (!params.rpc) {
-            return NextResponse.json({
+        if (!params.trpc) {
+            return server_1.NextResponse.json({
                 data: null,
-                error: "You must pass a params in your [rpc]/you-must-put-a-param-here call",
+                error: "You must pass a params in your [trpc]/you-must-put-a-param-here call",
             }, { status: 400 });
         }
-        const endpointAttribute = camelize(params.rpc);
+        const endpointAttribute = (0, utils_1.camelize)(params.trpc);
         if (!(endpointAttribute in router) || !router[endpointAttribute]) {
-            return NextResponse.json({
+            return server_1.NextResponse.json({
                 data: null,
                 error: `No ${endpointAttribute} endpoints found in the router object.`,
             }, { status: 400 });
@@ -38,18 +41,19 @@ export const createRpcAPI = ({ router, ctx, }) => {
         const endpoint = router[endpointAttribute];
         try {
             const input = parseInput(request, endpoint);
-            const context = ctx ? await ctx(request) : {};
+            const context = (ctx ? (await ctx(request)) : {});
             const result = endpoint.input
                 ? await endpoint.action(input, Object.assign(Object.assign({}, context), { request }))
                 : await endpoint.action(Object.assign(Object.assign({}, context), { request }));
-            return NextResponse.json({ data: result }, { status: 200 });
+            return server_1.NextResponse.json({ data: result }, { status: 200 });
         }
         catch (error) {
             if (error instanceof Error && "issues" in error) {
                 // Zod validation error
-                return NextResponse.json({ data: null, error: "Invalid request data", details: error.message }, { status: 400 });
+                return server_1.NextResponse.json({ data: null, error: "Invalid request data", details: error.message }, { status: 400 });
             }
-            return NextResponse.json({ data: null, error: "Internal Server Error" }, { status: 500 });
+            return server_1.NextResponse.json({ data: null, error: "Internal Server Error" }, { status: 500 });
         }
     };
 };
+exports.createTrpcAPI = createTrpcAPI;

package/dist/create-trpc-client.d.ts

@@ -0,0 +1,19 @@
+import { Router, type Endpoint, type router } from "./core";
+import z from "zod";
+export type EndpointClient<Input, Output> = Input extends undefined ? {
+    fetch: () => Promise<Output>;
+} : {
+    fetch: (input: Input extends import("zod").Schema ? z.infer<Input> : Input) => Promise<Output>;
+};
+type TrpcClient<R extends Router<any>> = {
+    [K in keyof R]: R[K] extends Endpoint<infer Output, infer Input, any> ? EndpointClient<Input, Output> : never;
+};
+export declare const getTrpcFetch: ({ endpointSlug, url, headers, }: {
+    endpointSlug: string;
+} & createTrpcClientOptions) => (input?: any) => Promise<any>;
+export interface createTrpcClientOptions {
+    url: string;
+    headers?: HeadersInit | (() => Promise<HeadersInit>);
+}
+export declare const createTrpcClient: <R extends ReturnType<typeof router<any, Router<any>>>>(opts: createTrpcClientOptions) => TrpcClient<R>;
+export {};

package/dist/{create-rpc-client.js → create-trpc-client.js}

@@ -1,6 +1,9 @@
-import { kebabize } from "./utils";
-export const getRpcFetch = ({ endpointSlug, url, headers, }) => async (input) => {
-    const endpointName = kebabize(endpointSlug);
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrpcClient = exports.getTrpcFetch = void 0;
+const utils_1 = require("./utils");
+const getTrpcFetch = ({ endpointSlug, url, headers, }) => async (input) => {
+    const endpointName = (0, utils_1.kebabize)(endpointSlug);
     // Build URL with search params if input exists
     let requestUrl = `${url}/${endpointName}`;
     if (input) {
@@ -10,7 +13,7 @@ export const getRpcFetch = ({ endpointSlug, url, headers, }) => async (input) =>
         }
         requestUrl += `?${searchParams.toString()}`;
     }
-    const headerObject = typeof headers === "function" ? await headers() : headers;
+    const headerObject = typeof headers === "function" ? await headers() : headers || {};
     const response = await fetch(requestUrl, {
         method: "GET",
         headers: Object.assign({ "Content-Type": "application/json" }, headerObject),
@@ -22,16 +25,17 @@ export const getRpcFetch = ({ endpointSlug, url, headers, }) => async (input) =>
     const result = await response.json();
     return result.data;
 };
-// export const createRpcClient = <R extends ReturnType<typeof router>>({
-export const createRpcClient = (opts) => {
+exports.getTrpcFetch = getTrpcFetch;
+const createTrpcClient = (opts) => {
     return new Proxy({}, {
         get(target, prop) {
             if (typeof prop === "string") {
                 return {
-                    fetch: getRpcFetch(Object.assign({ endpointSlug: prop }, opts)),
+                    fetch: (0, exports.getTrpcFetch)(Object.assign({ endpointSlug: prop }, opts)),
                 };
             }
             return undefined;
         },
     });
 };
+exports.createTrpcClient = createTrpcClient;

package/dist/create-trpc-query-client.d.ts

@@ -0,0 +1,10 @@
+import { useQuery } from "@tanstack/react-query";
+import { type EndpointClient, createTrpcClientOptions } from "./create-trpc-client";
+import type { Router, Endpoint, router } from "./core";
+type TrpcClientWithQuery<R extends Router<any>> = {
+    [K in keyof R]: R[K] extends Endpoint<infer Output, infer Input, any> ? EndpointClient<Input, Output> & {
+        useQuery: (queryOptions?: Omit<Parameters<typeof useQuery>[0], "queryKey" | "queryFn">) => ReturnType<typeof useQuery<Promise<Output>, Error, Promise<Output>, string[]>>;
+    } : never;
+};
+export declare const createTrpcQueryClient: <R extends ReturnType<typeof router<any, Router<any>>>>(opts: createTrpcClientOptions) => TrpcClientWithQuery<R>;
+export {};

package/dist/create-trpc-query-client.js

@@ -0,0 +1,23 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrpcQueryClient = void 0;
+const react_query_1 = require("@tanstack/react-query");
+const create_trpc_client_1 = require("./create-trpc-client");
+const createTrpcQueryClient = (opts) => {
+    return new Proxy({}, {
+        get(target, prop) {
+            if (typeof prop === "string") {
+                return {
+                    fetch: (0, create_trpc_client_1.getTrpcFetch)(Object.assign({ endpointSlug: prop }, opts)),
+                    useQuery: (queryOptions) => {
+                        const endpointName = prop.replace(/([A-Z])/g, "-$1").toLowerCase();
+                        return (0, react_query_1.useQuery)(Object.assign(Object.assign({}, queryOptions), { queryKey: [endpointName], queryFn: (0, create_trpc_client_1.getTrpcFetch)(Object.assign({ endpointSlug: prop }, opts)) }));
+                    },
+                };
+            }
+            return undefined;
+        },
+    });
+};
+exports.createTrpcQueryClient = createTrpcQueryClient;