ts-openapi-express 1.0.3 → 1.0.5

package/README.md

@@ -1,3 +1,266 @@
+**[Documentation](https://jacobshirley.github.io/ts-openapi-express/v1)**
+
 # ts-openapi-express
 
-For detailed documentation, examples, and API reference, see the [main README](../../README.md).
+An opinionated, type-safe Express.js integration library for OpenAPI specifications. This package enables you to build type-safe REST APIs with full request/response validation using OpenAPI schemas.
+
+[![npm version](https://img.shields.io/npm/v/ts-openapi-express.svg)](https://www.npmjs.com/package/ts-openapi-express)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Type-Safe Routes**: Leverage TypeScript to ensure your route handlers match your OpenAPI spec
+- **Request/Response Validation**: Built-in middleware to validate incoming requests and outgoing responses against your OpenAPI schema
+- **OpenAPI Schema Support**: Load OpenAPI specifications (YAML/JSON) and use them to drive your API implementation
+- **Zero Configuration**: Minimal setup required - just provide your spec and route handlers
+- **Middleware Support**: Integrate custom Express middleware alongside OpenAPI validation
+- **Streaming Support**: Handle streaming responses with native Node.js streams
+
+## Getting Started
+
+See [examples/](./examples/blog-api) for a complete working example.
+
+### 1. Generate TypeScript Types from Your OpenAPI Spec
+
+The first step is to generate TypeScript type definitions from your OpenAPI specification using [openapi-typescript](https://openapi-ts.pages.dev/).
+
+```bash
+npm install --save-dev openapi-typescript
+```
+
+Add this script to your `package.json`:
+
+```json
+{
+    "scripts": {
+        "generate:types": "openapi-typescript path/to/your/openapi.yaml --output path/to/generated/types.ts"
+    }
+}
+```
+
+Then run it to generate the types:
+
+```bash
+npm run generate:types
+```
+
+It's also recommended to add it to your `compile/build` script to ensure types are always up to date.
+
+```json
+{
+    "scripts": {
+        "build": "npm run generate:types && tsc"
+    }
+}
+```
+
+This command generates a `types.ts` file with path types that look like:
+
+```typescript
+export interface paths {
+    '/users': {
+        get: {
+            responses: {
+                '200': {
+                    content: {
+                        'application/json': {
+                            id: string
+                            name: string
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // ... more paths
+}
+```
+
+### 2. Install ts-openapi-express
+
+```bash
+npm install ts-openapi-express
+yarn add ts-openapi-express
+pnpm add ts-openapi-express
+```
+
+### 3. Define Your Routes with Type Safety
+
+```typescript
+import { openapiExpress } from 'ts-openapi-express'
+import { paths } from './generated/types' // Generated from step 1
+
+const app = openapiExpress<paths>({
+    specPath: './openapi.yaml',
+    routes: {
+        '/users': {
+            get: {
+                handler: async (req) => ({
+                    200: {
+                        headers: {},
+                        body: [
+                            { id: '1', name: 'John' },
+                            { id: '2', name: 'Jane' },
+                        ],
+                    },
+                }),
+            },
+            post: {
+                handler: async (req) => ({
+                    201: {
+                        headers: { 'content-type': 'application/json' },
+                        body: { id: '3', name: req.body.name },
+                    },
+                }),
+            },
+        },
+        '/users/{id}': {
+            get: {
+                handler: async (req) => ({
+                    200: {
+                        headers: {},
+                        body: { id: req.params.id, name: 'John' },
+                    },
+                }),
+            },
+        },
+    },
+})
+
+app.listen(3000, () => {
+    console.log('API running on http://localhost:3000')
+    console.log('OpenAPI spec available at http://localhost:3000/openapi.json')
+})
+```
+
+## Examples
+
+See the [examples/](./examples/) directory for complete working examples, including a simple blog API.
+
+## API Options
+
+```typescript
+interface OpenapiExpressOptions<Spec> {
+    /**
+     * Path to your OpenAPI specification file (YAML or JSON)
+     */
+    specPath: string
+
+    /**
+     * Route handlers object mapping paths to HTTP method handlers
+     */
+    routes: Routes<Spec>
+
+    /**
+     * Optional Express middleware to use
+     */
+    middleware?: ExpressMiddleware[]
+
+    /**
+     * Enable request validation against OpenAPI spec (default: true)
+     */
+    validateRequest?: boolean
+
+    /**
+     * Enable response validation against OpenAPI spec (default: true)
+     */
+    validateResponse?: boolean
+
+    /**
+     * Automatically parse JSON request bodies (default: true)
+     */
+    decodeJsonBody?: boolean
+
+    /**
+     * Provide an existing Express app instance (optional)
+     */
+    app?: Application
+
+    /**
+     * Disable the 'X-Powered-By' header (default: true)
+     */
+    disableXPoweredBy?: boolean
+}
+```
+
+## Handler Signature
+
+Route handlers receive type-safe request objects with:
+
+- `req.params`: Path parameters (fully typed)
+- `req.query`: Query parameters (fully typed)
+- `req.body`: Request body (fully typed)
+- `req.headers`: HTTP headers
+
+Handlers must return a response object with a single status code:
+
+```typescript
+{
+  200: {
+    headers: { 'content-type': 'application/json' },
+    body: { /* response data */ }
+  }
+}
+```
+
+Or, if no body is required:
+
+```typescript
+{
+  204: {
+    headers: {}
+  }
+}
+```
+
+Streaming responses are supported by passing a Node.js `Readable`:
+
+```typescript
+{
+  200: {
+    headers: { 'content-type': 'text/csv' },
+    body: fs.createReadStream('data.csv')
+  }
+}
+```
+
+## Examples
+
+### Running the Test
+
+This repository includes a comprehensive test suite that demonstrates usage. To run it:
+
+```bash
+# This will:
+# 1. Generate types from the OpenAPI spec
+# 2. Run the test suite with validation
+npm test
+```
+
+The test file at `packages/ts-openapi-express/test/unit/openapi.test.ts` shows:
+
+- Type-safe route definition
+- Request/response validation
+- Error handling
+- Path parameter usage
+- Query parameter handling
+
+### Regenerating Test Types
+
+If you modify the test OpenAPI spec, regenerate the types:
+
+```bash
+npm run test:compile:spec
+```
+
+## Architecture
+
+The library works in three main steps:
+
+1. **Type Generation** (via openapi-typescript): Convert your OpenAPI spec into TypeScript types
+2. **Route Definition**: Define your Express handlers using the generated types
+3. **Validation**: Automatic request/response validation ensures your implementation matches the spec
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -1,12 +1,7 @@
-import { error as openapiValidatorErrors } from 'express-openapi-validator';
-export type OpenapiValidatorError = (typeof openapiValidatorErrors)[keyof typeof openapiValidatorErrors];
-declare const isExpressOpenAPIValidatorError: (err: any) => err is Error & {
-    status: number;
-};
+import { error as OpenapiValidationErrors } from 'express-openapi-validator';
 declare class HttpError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
-    type(): string;
 }
 declare class UnauthorizedError extends HttpError {
     constructor();
@@ -18,4 +13,4 @@ declare class InvalidJsonError extends HttpError {
     readonly jsonString: string;
     constructor(jsonString: string);
 }
-export { isExpressOpenAPIValidatorError, HttpError, RequestBodyTooLargeError, InvalidJsonError, UnauthorizedError, };
+export { OpenapiValidationErrors, HttpError, RequestBodyTooLargeError, InvalidJsonError, UnauthorizedError, };

package/dist/errors.js

@@ -1,22 +1,10 @@
-import { error as openapiValidatorErrors } from 'express-openapi-validator';
-const isExpressOpenAPIValidatorError = (err) => {
-    for (const key in openapiValidatorErrors) {
-        if (err instanceof
-            openapiValidatorErrors[key]) {
-            return true;
-        }
-    }
-    return false;
-};
+import { error as OpenapiValidationErrors } from 'express-openapi-validator';
 class HttpError extends Error {
     status;
     constructor(message, status) {
         super(message);
         this.status = status;
     }
-    type() {
-        return this.constructor.name;
-    }
 }
 class UnauthorizedError extends HttpError {
     constructor() {
@@ -35,4 +23,4 @@ class InvalidJsonError extends HttpError {
         this.jsonString = jsonString;
     }
 }
-export { isExpressOpenAPIValidatorError, HttpError, RequestBodyTooLargeError, InvalidJsonError, UnauthorizedError, };
+export { OpenapiValidationErrors, HttpError, RequestBodyTooLargeError, InvalidJsonError, UnauthorizedError, };

package/dist/openapiExpress.js

@@ -15,7 +15,7 @@ function openapiExpress(options) {
     if (decodeJsonBody) {
         app.use(json());
     }
-    if (validateRequest || validateResponse)
+    if (validateRequest || validateResponse) {
         app.use(...requestResponseValidatorMiddleware({
             spec,
             validation: {
@@ -23,6 +23,7 @@ function openapiExpress(options) {
                 responses: validateResponse,
             },
         }));
+    }
     for (const m of middleware) {
         app.use(m);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ts-openapi-express",
   "type": "module",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "",
   "main": "dist/index.js",
   "directories": {
@@ -10,6 +10,9 @@
   "repository": {
     "url": "https://github.com/jacobshirley/ts-openapi-express"
   },
+  "bugs": {
+    "url": "https://github.com/jacobshirley/ts-openapi-express/issues"
+  },
   "homepage": "https://jacobshirley.github.io/ts-openapi-express/v1",
   "keywords": [
     "openapi",
@@ -28,13 +31,23 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "express": "^5.0.0",
-    "express-openapi-validator": "^5.3.9",
     "lodash-es": "^4.17.23",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.1",
+    "express-openapi-validator": "^5.0.0"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": false
+    },
+    "express-openapi-validator": {
+      "optional": false
+    }
   },
   "devDependencies": {
-    "@types/express": "^5.0.0",
+    "@types/express": "^5.0.6",
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^22.0.0",
     "@types/supertest": "^6.0.2",
@@ -50,9 +63,9 @@
     "README.md"
   ],
   "scripts": {
-    "test": "pnpm test:unit",
-    "test:unit": "pnpm test:compile:spec && vitest run",
-    "test:compile:spec": "openapi-typescript test/unit/openapi.test.yaml --output test/unit/test-schema.ts",
+    "test": "vitest run",
+    "test:unit": "pnpm pretest && vitest run",
+    "pretest": "openapi-typescript test/unit/openapi.test.yaml --output test/unit/test-schema.gen.ts",
     "compile": "tsc -p tsconfig.prod.json",
     "watch": "tsc -p tsconfig.prod.json --watch"
   }