@rtorcato/api-ts-rest-express 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Torcato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @rtorcato/api-ts-rest-express
+
+Mount a [ts-rest](https://ts-rest.com) contract on Express and serve its OpenAPI docs (Scalar) in one call — wires `@ts-rest/express` + `@ts-rest/open-api` into the api-common docs stack.
+
+## Install
+
+```sh
+pnpm add @rtorcato/api-ts-rest-express @ts-rest/core @ts-rest/express @ts-rest/open-api express zod
+```
+
+> **Version note:** requires `@ts-rest/*` **≥ 3.53.0-rc.1**, which is the first release supporting **zod 4** and **express 5** (stable 3.52 pins zod 3 / express 4). Bump the peer range to `^3.53` once 3.53 ships stable.
+
+`@ts-rest/*`, `express`, and `zod` are peer dependencies.
+
+## Usage
+
+```ts
+import express from 'express'
+import { z } from 'zod'
+import { initContract, initServer, mountTsRest } from '@rtorcato/api-ts-rest-express'
+
+const c = initContract()
+const contract = c.router({
+  getUser: {
+    method: 'GET',
+    path: '/users/:id',
+    pathParams: z.object({ id: z.string() }),
+    responses: { 200: z.object({ id: z.string(), name: z.string() }) },
+  },
+})
+
+const s = initServer()
+const router = s.router(contract, {
+  getUser: async ({ params: { id } }) => ({ status: 200, body: { id, name: 'Ada' } }),
+})
+
+const app = express()
+app.use(express.json())
+
+mountTsRest(app, {
+  contract,
+  router,
+  openapi: { info: { title: 'Users API', version: '1.0.0' } },
+})
+// → contract routes are live
+// → GET /openapi.json  (OpenAPI 3.1 generated from the contract)
+// → GET /docs          (Scalar API reference UI)
+```
+
+`initContract` / `initServer` are re-exported so you can build the contract and server from one import.
+
+## Options
+
+`mountTsRest(app, options)`:
+
+- `contract` / `router` — the ts-rest contract and its `s.router(...)` implementation.
+- `endpointOptions?` — forwarded to `createExpressEndpoints` (`globalMiddleware`, `responseValidation`, …).
+- `openapi?` — `{ info, options?, mount? }`. When present, generates an OpenAPI 3.1 doc from the contract and serves it via [`@rtorcato/api-openapi-express`](https://github.com/rtorcato/api-common/tree/main/packages/api-openapi-express). `options` goes to `generateOpenApi` (e.g. `{ setOperationId: true }`); `mount` overrides the docs paths/UI/theme.
+
+## Related
+
+- [`@rtorcato/api-openapi-express`](https://github.com/rtorcato/api-common/tree/main/packages/api-openapi-express) — the Scalar/Swagger mount this builds on
+- [`@rtorcato/api-openapi-hono`](https://github.com/rtorcato/api-common/tree/main/packages/api-openapi-hono) — schema-first OpenAPI for Hono
+
+Source: https://github.com/rtorcato/api-common/tree/main/packages/api-ts-rest-express

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { type MountOpenAPIOptions } from '@rtorcato/api-openapi-express';
+import type { AppRouter } from '@ts-rest/core';
+import { createExpressEndpoints } from '@ts-rest/express';
+import { generateOpenApi } from '@ts-rest/open-api';
+import type { IRouter } from 'express';
+type EndpointOptions = Parameters<typeof createExpressEndpoints>[3];
+export interface OpenApiConfig {
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    /** Extra `generateOpenApi` options, e.g. `{ setOperationId: true }`. */
+    options?: Parameters<typeof generateOpenApi>[2];
+    /** Overrides for the docs mount (paths, UI, theme) — `doc` is supplied for you. */
+    mount?: Omit<MountOpenAPIOptions, 'doc'>;
+}
+export interface MountTsRestOptions {
+    contract: AppRouter;
+    /**
+     * The implemented router from `initServer().router(contract, handlers)` — that
+     * call already type-checks the handlers against the contract, so it's accepted
+     * loosely here.
+     */
+    router: unknown;
+    /** Passed to `createExpressEndpoints` (globalMiddleware, responseValidation, …). */
+    endpointOptions?: EndpointOptions;
+    /** Generate an OpenAPI 3.1 doc from the contract and serve it (Scalar by default). */
+    openapi?: OpenApiConfig;
+}
+/**
+ * Mount a ts-rest contract on an Express app/router and, optionally, serve its
+ * OpenAPI docs — one call wiring `@ts-rest/express` + `@ts-rest/open-api` into the
+ * api-common Scalar docs (`@rtorcato/api-openapi-express`).
+ *
+ * @example
+ * ```ts
+ * const s = initServer()
+ * const router = s.router(contract, { getUser: async ({ params }) => ({ status: 200, body: … }) })
+ * mountTsRest(app, { contract, router, openapi: { info: { title: 'My API', version: '1.0.0' } } })
+ * // → contract routes are live; GET /openapi.json + GET /docs (Scalar)
+ * ```
+ */
+export declare function mountTsRest(app: IRouter, options: MountTsRestOptions): void;
+export { initContract } from '@ts-rest/core';
+export { initServer } from '@ts-rest/express';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAKtC,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAA;AAEnE,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9D,wEAAwE;IACxE,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/C,mFAAmF;IACnF,KAAK,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAA;IACf,oFAAoF;IACpF,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,sFAAsF;IACtF,OAAO,CAAC,EAAE,aAAa,CAAA;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAoB3E;AAGD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,31 @@
+import { mountOpenAPI } from '@rtorcato/api-openapi-express';
+import { createExpressEndpoints } from '@ts-rest/express';
+import { generateOpenApi } from '@ts-rest/open-api';
+/**
+ * Mount a ts-rest contract on an Express app/router and, optionally, serve its
+ * OpenAPI docs — one call wiring `@ts-rest/express` + `@ts-rest/open-api` into the
+ * api-common Scalar docs (`@rtorcato/api-openapi-express`).
+ *
+ * @example
+ * ```ts
+ * const s = initServer()
+ * const router = s.router(contract, { getUser: async ({ params }) => ({ status: 200, body: … }) })
+ * mountTsRest(app, { contract, router, openapi: { info: { title: 'My API', version: '1.0.0' } } })
+ * // → contract routes are live; GET /openapi.json + GET /docs (Scalar)
+ * ```
+ */
+export function mountTsRest(app, options) {
+    createExpressEndpoints(options.contract, options.router, app, options.endpointOptions);
+    if (options.openapi) {
+        const doc = generateOpenApi(options.contract, { openapi: '3.1.0', info: options.openapi.info }, options.openapi.options);
+        // mountOpenAPI accepts any target with Express-style `.get(path, handler)`.
+        mountOpenAPI(app, {
+            doc,
+            ...options.openapi.mount,
+        });
+    }
+}
+// Re-export the ts-rest entry points so consumers build contracts + servers from one import.
+export { initContract } from '@ts-rest/core';
+export { initServer } from '@ts-rest/express';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA4B,MAAM,+BAA+B,CAAA;AAEtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AA8BnD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,OAA2B;IACpE,sBAAsB,CACrB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,MAAsB,EAC9B,GAAG,EACH,OAAO,CAAC,eAAe,CACvB,CAAA;IAED,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,eAAe,CAC1B,OAAO,CAAC,QAAQ,EAChB,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAChD,OAAO,CAAC,OAAO,CAAC,OAAO,CACvB,CAAA;QACD,4EAA4E;QAC5E,YAAY,CAAC,GAAoD,EAAE;YAClE,GAAG;YACH,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK;SACxB,CAAC,CAAA;IACH,CAAC;AACF,CAAC;AAED,6FAA6F;AAC7F,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@rtorcato/api-ts-rest-express",
+  "version": "0.2.0",
+  "description": "Mount a ts-rest contract on Express and serve its OpenAPI docs (Scalar) — wires @ts-rest/express + @ts-rest/open-api into api-common.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Richard Torcato",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@rtorcato/api-openapi-express": "0.2.0"
+  },
+  "peerDependencies": {
+    "@ts-rest/core": ">=3.53.0-rc.1 <4",
+    "@ts-rest/express": ">=3.53.0-rc.1 <4",
+    "@ts-rest/open-api": ">=3.53.0-rc.1 <4",
+    "express": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@ts-rest/core": "3.53.0-rc.1",
+    "@ts-rest/express": "3.53.0-rc.1",
+    "@ts-rest/open-api": "3.53.0-rc.1",
+    "@types/express": "^5.0.0",
+    "@types/supertest": "^7.2.0",
+    "express": "^5.1.0",
+    "supertest": "^7.1.0",
+    "typescript": "~6.0.3",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "api",
+    "nodejs",
+    "typescript",
+    "express",
+    "ts-rest",
+    "openapi",
+    "contract"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rtorcato/api-common.git",
+    "directory": "packages/api-ts-rest-express"
+  },
+  "homepage": "https://github.com/rtorcato/api-common/tree/main/packages/api-ts-rest-express#readme",
+  "bugs": {
+    "url": "https://github.com/rtorcato/api-common/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}