@routepact/core 0.1.0

package/README.md

@@ -0,0 +1,163 @@
+# @routepact/core
+
+Shared types and utilities for defining type-safe route pacts. This package is the contract between your server and client — import it in shared code that both sides depend on.
+
+## Installation
+
+```bash
+npm install @routepact/core zod
+```
+
+## Defining a route spec
+
+A `RoutePact` describes a single endpoint: its path, HTTP method, and optional Zod schemas for request body, response body, and response metadata.
+
+```ts
+import { z } from "zod";
+import type { RoutePact } from "@routepact/core";
+
+export const PostPacts = {
+  list: {
+    method: "get",
+    path: "/posts",
+    validation: {
+      response: z.object({ id: z.string(), title: z.string() }).array(),
+      meta: z.object({ total: z.number(), page: z.number() }),
+    },
+  },
+  getById: {
+    method: "get",
+    path: "/posts/:id",
+    validation: {
+      response: z.object({
+        id: z.string(),
+        title: z.string(),
+        body: z.string(),
+      }),
+    },
+  },
+  create: {
+    method: "post",
+    path: "/posts",
+    validation: {
+      request: z.object({ title: z.string(), body: z.string() }),
+      response: z.object({
+        id: z.string(),
+        title: z.string(),
+        body: z.string(),
+      }),
+    },
+  },
+  update: {
+    method: "patch",
+    path: "/posts/:id",
+    validation: {
+      request: z.object({
+        title: z.string().optional(),
+        body: z.string().optional(),
+      }),
+      response: z.object({
+        id: z.string(),
+        title: z.string(),
+        body: z.string(),
+      }),
+    },
+  },
+  delete: {
+    method: "delete",
+    path: "/posts/:id",
+    validation: {},
+  },
+} satisfies Record<string, RoutePact>;
+```
+
+Using `satisfies Record<string, RoutePact>` lets TypeScript keep the literal types (exact path strings, exact method literals) while still validating the shape.
+
+## Validation rules
+
+| Field                 | Required                        | Description                                  |
+| --------------------- | ------------------------------- | -------------------------------------------- |
+| `validation.request`  | Only for `post`, `patch`, `put` | Zod schema for `req.body.resource`           |
+| `validation.response` | Optional                        | Zod schema for `res.json({ resource: ... })` |
+| `validation.meta`     | Optional                        | Zod schema for `res.json({ meta: ... })`     |
+
+## Path parameters
+
+Parameters in the path are extracted as a type-safe object. If a path contains `:id`, the `params` option is required and typed as `{ id: string }`.
+
+```ts
+// TypeScript requires params when the path has parameters
+await request(PostPacts.getById, { params: { id: "abc" } });
+
+// TypeScript forbids params when there are none
+await request(PostPacts.list);
+```
+
+## API response shape
+
+All endpoints follow the same envelope:
+
+```ts
+// Response body sent from the server
+interface ApiResponse<TResource, TMeta> {
+  resource: TResource;
+  meta?: TMeta;
+  message?: string;
+}
+
+// Request body sent to the server
+interface ApiRequest<TResource> {
+  resource: TResource;
+}
+```
+
+## Utilities
+
+### `buildEndpoint(spec, options)`
+
+Interpolates path params and appends a query string.
+
+```ts
+import { buildEndpoint } from "@routepact/core";
+
+buildEndpoint(PostPacts.getById, { params: { id: "42" } });
+// → "/posts/42"
+
+buildEndpoint(PostPacts.list, { queries: { page: "2", limit: "10" } });
+// → "/posts?page=2&limit=10"
+```
+
+### `exhaustiveGuard(value)`
+
+A compile-time exhaustiveness check for `switch` statements. Throws at runtime if an unhandled branch is reached.
+
+```ts
+import { exhaustiveGuard, type HttpMethod } from "@routepact/core";
+
+function handle(method: HttpMethod) {
+  switch (method) {
+    case "get":
+      return "GET";
+    case "post":
+      return "POST";
+    // ... etc
+    default:
+      exhaustiveGuard(method); // TypeScript errors if a case is missing
+  }
+}
+```
+
+## Type reference
+
+| Type                          | Description                                                       |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `RoutePact`                   | Base type for a single endpoint definition                        |
+| `RouteValidation`             | The `validation` field of a spec                                  |
+| `HttpMethod`                  | `"get" \| "post" \| "patch" \| "put" \| "delete"`                 |
+| `RouteOptions<TPact>`         | Inferred options (params, payload, queries) for a spec            |
+| `RouteOptionsRequired<TPact>` | `true` if options are required (has params or request schema)     |
+| `RequestResult<TPact>`        | Inferred return type when calling a spec from the client          |
+| `ExtractParams<TPath>`        | Extracts parameter names from a path string                       |
+| `ExpectedParams<TPath>`       | Maps extracted param names to `string` values                     |
+| `ApiRequest<T>`               | `{ resource: T }` — request body envelope                         |
+| `ApiResponse<T, M>`           | `{ resource: T; meta?: M; message?: string }` — response envelope |

package/dist/api.d.ts

@@ -0,0 +1,10 @@
+export interface ApiResponse<TResource, TMeta = undefined> {
+    resource: TResource;
+    meta?: TMeta;
+    message?: string;
+}
+export interface ApiRequest<TResource> {
+    resource: TResource;
+}
+export type QueryParam = Record<string, string | number | boolean | undefined>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW,CAAC,SAAS,EAAE,KAAK,GAAG,SAAS;IACvD,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU,CAAC,SAAS;IACnC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC"}

package/dist/api.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./api.js";
+export * from "./types.js";
+export * from "./utils.js";
+//# 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,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./api.js";
+export * from "./types.js";
+export * from "./utils.js";
+//# 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,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+import type z from "zod/v4";
+import type { ApiResponse } from "./api.js";
+export type HttpMethod = "get" | "post" | "patch" | "put" | "delete";
+export type RouteValidation = {
+    response?: z.ZodType<unknown>;
+    request?: z.ZodType<unknown>;
+    meta?: z.ZodType<unknown>;
+};
+export type RoutePact = {
+    path: string;
+    method: HttpMethod;
+    validation: RouteValidation;
+};
+export type ExtractParams<T extends string> = T extends `${string}/:${infer Param}/${infer Rest}` ? Param | ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}` ? Param : never;
+export type ExpectedParams<T extends string> = {
+    [Key in ExtractParams<T>]: string;
+};
+type ParamsOption<TPath extends string> = [ExtractParams<TPath>] extends [never] ? {
+    params?: never;
+} : {
+    params: ExpectedParams<TPath>;
+};
+type PayloadOption<TPact extends RoutePact> = TPact["method"] extends "post" | "patch" | "put" ? TPact["validation"]["request"] extends z.ZodType<unknown> ? {
+    payload: z.infer<TPact["validation"]["request"]>;
+} : {
+    payload?: never;
+} : {
+    payload?: never;
+};
+export type RouteOptions<TPact extends RoutePact> = ParamsOption<TPact["path"]> & PayloadOption<TPact> & {
+    queries?: Record<string, string>;
+};
+export type RouteOptionsRequired<TPact extends RoutePact> = TPact["validation"]["request"] extends z.ZodType<unknown> ? true : [ExtractParams<TPact["path"]>] extends [never] ? false : true;
+export type RequestResult<TPact extends RoutePact> = ApiResponse<TPact["validation"] extends {
+    response: z.ZodType<unknown>;
+} ? z.infer<TPact["validation"]["response"]> : undefined, TPact["validation"] extends {
+    response: z.ZodType<unknown>;
+    meta: z.ZodType<unknown>;
+} ? z.infer<TPact["validation"]["meta"]> : undefined>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import type { RouteOptions, RoutePact } from "./types.js";
+export declare function exhaustiveGuard(_value: never): never;
+export declare function buildEndpoint<TPact extends RoutePact>(pact: TPact, options?: RouteOptions<TPact>): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,CAIpD;AAED,wBAAgB,aAAa,CAAC,KAAK,SAAS,SAAS,EACnD,IAAI,EAAE,KAAK,EACX,OAAO,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,GAC5B,MAAM,CAUR"}

package/dist/utils.js

@@ -0,0 +1,14 @@
+export function exhaustiveGuard(_value) {
+    throw new Error(`Reached forbidden guard function with unexpected value: ${JSON.stringify(_value)}`);
+}
+export function buildEndpoint(pact, options) {
+    const replacedEndpoint = pact.path.replace(/:(\w+)/g, (match, key) => {
+        if (options?.params && key in options.params) {
+            return options.params[key];
+        }
+        return match;
+    });
+    const queryString = new URLSearchParams(options?.queries).toString();
+    return queryString ? `${replacedEndpoint}?${queryString}` : replacedEndpoint;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,eAAe,CAAC,MAAa;IAC3C,MAAM,IAAI,KAAK,CACb,2DAA2D,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CACpF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,IAAW,EACX,OAA6B;IAE7B,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACnE,IAAI,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAC7C,OAAO,OAAO,CAAC,MAAM,CAAC,GAA0C,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,IAAI,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACrE,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,gBAAgB,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;AAC/E,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@routepact/core",
+  "version": "0.1.0",
+  "description": "Type-safe route spec definitions shared between server and client",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "zod": "4.1.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "routes",
+    "typesafe",
+    "zod",
+    "spec"
+  ],
+  "license": "MIT"
+}