v1.0.0 (#143)

Author: jlalmes

.eslintrc.js

@@ -1,3 +1,6 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
 module.exports = {
   root: true,
   extends: [
@@ -21,9 +24,12 @@ module.exports = {
     node: true,
   },
   rules: {
+    '@typescript-eslint/no-misused-promises': ['error', { checksVoidReturn: false }],
     '@typescript-eslint/no-unsafe-argument': 'warn',
     '@typescript-eslint/no-unsafe-assignment': 'warn',
+    '@typescript-eslint/no-unsafe-call': 'warn',
     '@typescript-eslint/no-unsafe-member-access': 'warn',
+    '@typescript-eslint/no-unsafe-return': 'warn',
   },
   overrides: [
     {

.github/workflows/test.yml

@@ -1,6 +1,6 @@
 name: Test
 on: [push]
-jobs: 
+jobs:
   test:
     runs-on: ubuntu-latest
     steps:
@@ -9,11 +9,11 @@ jobs:
 
       - name: Setup node
         uses: actions/setup-node@v3
-        with: 
+        with:
           node-version: 16
 
       - name: Install dependencies
-        run: npm ci
+        run: npm ci --force
 
       - name: Run tests
         run: npm test

README.md

@@ -21,37 +21,35 @@
 
 ```bash
 # npm
-npm install trpc-openapi
+npm install trpc-openapi@alpha
 # yarn
-yarn add trpc-openapi
+yarn add trpc-openapi@alpha
 ```
 
-**2. Add `OpenApiMeta` to your tRPC router.**
+**2. Add `OpenApiMeta` to your tRPC instance.**
 
 ```typescript
-import * as trpc from '@trpc/server';
+import { initTRPC } from '@trpc/server';
 import { OpenApiMeta } from 'trpc-openapi';
 
-export const appRouter = trpc.router<any, OpenApiMeta /* 👈 */>();
+const t = initTRPC.meta<OpenApiMeta>().create(); /* 👈 */
 ```
 
 **3. Enable `openapi` support for a procedure.**
 
 ```typescript
-import * as trpc from '@trpc/server';
-import { OpenApiMeta } from 'trpc-openapi';
-
-export const appRouter = trpc.router<any, OpenApiMeta>().query('sayHello', {
-  meta: { /* 👉 */ openapi: { enabled: true, method: 'GET', path: '/say-hello' } },
-  input: z.object({ name: z.string() }),
-  output: z.object({ greeting: z.string() }),
-  resolve: ({ input }) => {
-    return { greeting: `Hello ${input.name}!` };
-  },
+export const appRouter = t.router({
+  sayHello: t.procedure
+    .meta({ /* 👉 */ openapi: { method: 'GET', path: '/say-hello' } })
+    .input(z.object({ name: z.string() }))
+    .output(z.object({ greeting: z.string() }))
+    .query(({ input }) => {
+      return { greeting: `Hello ${input.name}!` };
+    });
 });
 ```
 
-**4. Generate OpenAPI v3 document.**
+**4. Generate an OpenAPI document.**
 
 ```typescript
 import { generateOpenApiDocument } from 'trpc-openapi';
@@ -68,9 +66,9 @@ export const openApiDocument = generateOpenApiDocument(appRouter, {
 
 **5. Add an `trpc-openapi` handler to your app.**
 
-We currently support adapters for [`Express`](http://expressjs.com/), [`Next.js`](https://nextjs.org/) & [`node:http`](https://nodejs.org/api/http.html).
+We currently support adapters for [`Express`](http://expressjs.com/), [`Next.js`](https://nextjs.org/), [`Serverless`](https://www.serverless.com/) & [`node:http`](https://nodejs.org/api/http.html).
 
-[`Fastify`](https://www.fastify.io/) & [`Serverless`](https://www.serverless.com/) soon™, PRs are welcomed 🙌.
+[`Fastify`](https://www.fastify.io/) & more soon™, PRs are welcomed 🙌.
 
 ```typescript
 import http from 'http';
@@ -88,29 +86,29 @@ server.listen(3000);
 ```typescript
 // client.ts
 const res = await fetch('http://localhost:3000/say-hello?name=James', { method: 'GET' });
-const body = await res.json(); /* { ok: true, data: { greeting: 'Hello James!' } } */
+const body = await res.json(); /* { greeting: 'Hello James!' } */
 ```
 
 ## Requirements
 
 Peer dependencies:
 
-- [`tRPC`](https://github.com/trpc/trpc) Server v9 (`@trpc/server@^9.23.0`) must be installed.
+- [`tRPC`](https://github.com/trpc/trpc) Server v10 (`@trpc/server@next`) must be installed.
 - [`Zod`](https://github.com/colinhacks/zod) v3 (`zod@^3.14.4`) must be installed.
 
 For a procedure to support OpenAPI the following _must_ be true:
 
 - Both `input` and `output` parsers are present AND use `Zod` validation.
 - Query `input` parsers extend `ZodObject<{ [string]: ZodString }>` or `ZodVoid`.
 - Mutation `input` parsers extend `ZodObject<{ [string]: ZodAnyType }>` or `ZodVoid`.
-- `meta.openapi.enabled` is set to `true`.
 - `meta.openapi.method` is `GET`, `POST`, `PATCH`, `PUT` or `DELETE`.
 - `meta.openapi.path` is a string starting with `/`.
 - `meta.openapi.path` parameters exist in `input` parser as `ZodString`
 
 Please note:
 
 - Data [`transformers`](https://trpc.io/docs/data-transformers) are ignored.
+- tRPC v9 `.interop()` routers are not supported.
 - Trailing slashes are ignored.
 - Routing is case-insensitive.
 
@@ -120,41 +118,43 @@ Procedures with a `GET`/`DELETE` method will accept inputs via URL `query parame
 
 ### Path parameters
 
-A procedure can accept a set of inputs via URL path parameters. You can add a path parameter to any OpenAPI enabled procedure by using curly brackets around an input name as a path segment in the `meta.openapi.path` field.
+A procedure can accept a set of inputs via URL path parameters. You can add a path parameter to any OpenAPI procedure by using curly brackets around an input name as a path segment in the `meta.openapi.path` field.
 
 ### Query parameters
 
 Query & path parameter inputs are always accepted as a `string`, if you wish to support other primitives such as `number`, `boolean`, `Date` etc. please use [`z.preprocess()`](https://github.com/colinhacks/zod#preprocess).
 
 ```typescript
 // Router
-export const appRouter = trpc.router<Context, OpenApiMeta>().query('sayHello', {
-  meta: { openapi: { enabled: true, method: 'GET', path: '/say-hello/{name}' /* 👈 */ } },
-  input: z.object({ name: z.string() /* 👈 */, greeting: z.string() }),
-  output: z.object({ greeting: z.string() }),
-  resolve: ({ input }) => {
-    return { greeting: `${input.greeting} ${input.name}!` };
-  },
+export const appRouter = t.router({
+  sayHello: t.procedure
+    .meta({ openapi: { method: 'GET', path: '/say-hello/{name}' /* 👈 */ } })
+    .input(z.object({ name: z.string() /* 👈 */, greeting: z.string() }))
+    .output(z.object({ greeting: z.string() }))
+    .query(({ input }) => {
+      return { greeting: `${input.greeting} ${input.name}!` };
+    });
 });
 
 // Client
 const res = await fetch('http://localhost:3000/say-hello/James?greeting=Hello' /* 👈 */, {
   method: 'GET',
 });
-const body = await res.json(); /* { ok: true, data: { greeting: 'Hello James!' } } */
+const body = await res.json(); /* { greeting: 'Hello James!' } */
 ```
 
 ### Request body
 
 ```typescript
 // Router
-export const appRouter = trpc.router<Context, OpenApiMeta>().mutation('sayHello', {
-  meta: { openapi: { enabled: true, method: 'POST', path: '/say-hello/{name}' /* 👈 */ } },
-  input: z.object({ name: z.string() /* 👈 */, greeting: z.string() }),
-  output: z.object({ greeting: z.string() }),
-  resolve: ({ input }) => {
-    return { greeting: `${input.greeting} ${input.name}!` };
-  },
+export const appRouter = t.router({
+  sayHello: t.procedure
+    .meta({ openapi: { method: 'POST', path: '/say-hello/{name}' /* 👈 */ } })
+    .input(z.object({ name: z.string() /* 👈 */, greeting: z.string() }))
+    .output(z.object({ greeting: z.string() }))
+    .mutation(({ input }) => {
+      return { greeting: `${input.greeting} ${input.name}!` };
+    });
 });
 
 // Client
@@ -163,7 +163,7 @@ const res = await fetch('http://localhost:3000/say-hello/James' /* 👈 */, {
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ greeting: 'Hello' }),
 });
-const body = await res.json(); /* { ok: true, data: { greeting: 'Hello James!' } } */
+const body = await res.json(); /* { greeting: 'Hello James!' } */
 ```
 
 ### Custom headers
@@ -172,32 +172,12 @@ Any custom headers can be specified in the `meta.openapi.headers` array, these h
 
 ## HTTP Responses
 
-Inspired by [Slack Web API](https://api.slack.com/web).
-
 Status codes will be `200` by default for any successful requests. In the case of an error, the status code will be derived from the thrown `TRPCError` or fallback to `500`.
 
 You can modify the status code or headers for any response using the `responseMeta` function.
 
 Please see [error status codes here](src/adapters/node-http/errors.ts).
 
-```jsonc
-{
-  "ok": true,
-  "data": "This is good" /* Output from tRPC procedure */
-}
-```
-
-```jsonc
-{
-  "ok": false,
-  "error": {
-    "message": "This is bad", /* Message from TRPCError */,
-    "code": "BAD_REQUEST", /* Code from TRPCError */
-    "issues": [...] /* (optional) ZodIssues[] from TRPCError */
-  }
-}
-```
-
 ## Authorization
 
 To create protected endpoints, add `protect: true` to the `meta.openapi` object of each tRPC procedure. You can then authenticate each request with the `createContext` function using the `Authorization` header with the `Bearer` scheme.
@@ -221,6 +201,8 @@ const users: User[] = [
 
 export type Context = { user: User | null };
 
+const t = initTRPC.context<Context>().meta<OpenApiMeta>().create();
+
 export const createContext = async ({ req, res }): Promise<Context> => {
   let user: User | null = null;
   if (req.headers.authorization) {
@@ -230,16 +212,17 @@ export const createContext = async ({ req, res }): Promise<Context> => {
   return { user };
 };
 
-export const appRouter = trpc.router<Context, OpenApiMeta>().query('sayHello', {
-  meta: { openapi: { enabled: true, method: 'GET', path: '/say-hello', protect: true /* 👈 */ } },
-  input: z.void(), // no input expected
-  output: z.object({ greeting: z.string() }),
-  resolve: ({ input, ctx }) => {
-    if (!ctx.user) {
-      throw new trpc.TRPCError({ message: 'User not found', code: 'UNAUTHORIZED' });
-    }
-    return { greeting: `Hello ${ctx.user.name}!` };
-  },
+export const appRouter = t.router({
+  sayHello: t.procedure
+    .meta({ openapi: { method: 'GET', path: '/say-hello', protect: true /* 👈 */ } })
+    .input(z.void()) // no input expected
+    .output(z.object({ greeting: z.string() }))
+    .query(({ input, ctx }) => {
+      if (!ctx.user) {
+        throw new trpc.TRPCError({ message: 'User not found', code: 'UNAUTHORIZED' });
+      }
+      return { greeting: `Hello ${ctx.user.name}!` };
+    }),
 });
 ```
 
@@ -250,7 +233,7 @@ const res = await fetch('http://localhost:3000/say-hello', {
   method: 'GET',
   headers: { Authorization: 'Bearer usr_123' } /* 👈 */,
 });
-const body = await res.json(); /* { ok: true, data: { greeting: 'Hello James!' } } */
+const body = await res.json(); /* { greeting: 'Hello James!' } */
 ```
 
 ## Examples
@@ -281,14 +264,26 @@ app.listen(3000);
 Please see [full example here](examples/with-nextjs).
 
 ```typescript
-// pages/api/[trpc].ts
+// pages/api/[...trpc].ts
 import { createOpenApiNextHandler } from 'trpc-openapi';
 
 import { appRouter } from '../../server/appRouter';
 
 export default createOpenApiNextHandler({ router: appRouter });
 ```
 
+#### With AWS Lambda
+
+Please see [full example here](examples/with-serverless).
+
+```typescript
+import { createOpenApiAwsLambdaHandler } from 'trpc-openapi';
+
+import { appRouter } from './appRouter';
+
+export const openApi = createOpenApiAwsLambdaHandler({ router: appRouter });
+```
+
 ## Types
 
 #### GenerateOpenApiDocumentOptions
@@ -310,7 +305,7 @@ Please see [full typings here](src/types.ts).
 
 | Property      | Type                | Description                                                                                                  | Required | Default     |
 | ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ----------- |
-| `enabled`     | `boolean`           | Exposes this procedure to `trpc-openapi` adapters and on the OpenAPI document.                               | `true`   | `false`     |
+| `enabled`     | `boolean`           | Exposes this procedure to `trpc-openapi` adapters and on the OpenAPI document.                               | `false`  | `true`      |
 | `method`      | `HttpMethod`        | HTTP method this endpoint is exposed on. Value can be `GET`, `POST`, `PATCH`, `PUT` or `DELETE`.             | `true`   | `undefined` |
 | `path`        | `string`            | Pathname this endpoint is exposed on. Value must start with `/`, specify path parameters using `{}`.         | `true`   | `undefined` |
 | `protect`     | `boolean`           | Requires this endpoint to use an `Authorization` header credential with `Bearer` scheme on OpenAPI document. | `false`  | `false`     |
@@ -329,12 +324,11 @@ Please see [full typings here](src/adapters/node-http/core.ts).
 | `createContext` | `Function` | Passes contextual (`ctx`) data to procedure resolvers. | `false`  |
 | `responseMeta`  | `Function` | Returns any modifications to statusCode & headers.     | `false`  |
 | `onError`       | `Function` | Called if error occurs inside handler.                 | `false`  |
-| `teardown`      | `Function` | Called after each request is completed.                | `false`  |
 | `maxBodySize`   | `number`   | Maximum request body size in bytes (default: 100kb).   | `false`  |
 
 ---
 
-_Are you using tRPC v10? See our [`next`](https://github.com/jlalmes/trpc-openapi/tree/next) branch._
+_Still using tRPC v9? See our [`.interop()`](examples/with-interop) example._
 
 ## License
 

examples/with-express/package.json

@@ -6,23 +6,23 @@
     "dev": "ts-node-dev --respawn --transpile-only --exit-child ./src/index.ts"
   },
   "dependencies": {
-    "@trpc/server": "^9.27.2",
+    "@trpc/server": "^10.3.0",
     "cors": "^2.8.5",
-    "express": "^4.18.1",
+    "express": "^4.18.2",
     "jsonwebtoken": "^8.5.1",
-    "swagger-ui-express": "^4.5.0",
-    "uuid": "^8.3.2",
-    "zod": "^3.18.0"
+    "swagger-ui-express": "^4.6.0",
+    "uuid": "^9.0.0",
+    "zod": "^3.19.1"
   },
   "devDependencies": {
     "@types/cors": "^2.8.12",
-    "@types/express": "^4.17.13",
+    "@types/express": "^4.17.14",
     "@types/jsonwebtoken": "^8.5.9",
-    "@types/node": "^18.7.13",
+    "@types/node": "^18.11.9",
     "@types/swagger-ui-express": "^4.1.3",
     "@types/uuid": "^8.3.4",
     "ts-node": "^10.9.1",
     "ts-node-dev": "^2.0.0",
-    "typescript": "^4.7.4"
+    "typescript": "^4.9.3"
   }
 }

examples/with-express/src/index.ts

@@ -22,6 +22,6 @@ app.use('/api', createOpenApiExpressMiddleware({ router: appRouter, createContex
 app.use('/', swaggerUi.serve);
 app.get('/', swaggerUi.setup(openApiDocument));
 
-app.listen(3001, () => {
-  console.log('Server started on http://localhost:3001');
+app.listen(3000, () => {
+  console.log('Server started on http://localhost:3000');
 });

examples/with-express/src/openapi.ts

@@ -7,7 +7,7 @@ export const openApiDocument = generateOpenApiDocument(appRouter, {
   title: 'Example CRUD API',
   description: 'OpenAPI compliant REST API built using tRPC with Express',
   version: '1.0.0',
-  baseUrl: 'http://localhost:3001/api',
+  baseUrl: 'http://localhost:3000/api',
   docsUrl: 'https://github.com/jlalmes/trpc-openapi',
   tags: ['auth', 'users', 'posts'],
 });