@routepact/core 0.1.2 → 0.1.4

package/README.md

@@ -8,82 +8,77 @@ Shared types and utilities for defining type-safe route pacts. This package is t
 npm install @routepact/core zod
 ```
 
-## Defining a route spec
+## Defining a pact
 
-A `RoutePact` describes a single endpoint: its path, HTTP method, and optional Zod schemas for request body, response body, and response metadata.
+A pact describes a single endpoint: its path, HTTP method, and optional Zod schemas for the request body, response body, query parameters, path parameters, and response metadata.
+
+Use `definePact` to get full type inference while keeping literal types (exact path strings, method literals):
 
 ```ts
 import { z } from "zod";
-import type { RoutePact } from "@routepact/core";
+import { definePact } from "@routepact/core";
 
 export const PostPacts = {
-  list: {
+  list: definePact({
     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: {
+    response: z.object({
+      items: z.object({ id: z.string(), title: z.string() }).array(),
+      total: z.number(),
+      page: z.number(),
+    }),
+    query: z.object({ page: z.string().optional(), limit: z.string().optional() }),
+  }),
+  getById: definePact({
     method: "get",
     path: "/posts/:id",
-    validation: {
-      response: z.object({
-        id: z.string(),
-        title: z.string(),
-        body: z.string(),
-      }),
-    },
-  },
-  create: {
+    response: z.object({
+      id: z.string(),
+      title: z.string(),
+      body: z.string(),
+    }),
+  }),
+  create: definePact({
     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: {
+    request: z.object({ title: z.string(), body: z.string() }),
+    response: z.object({
+      id: z.string(),
+      title: z.string(),
+      body: z.string(),
+    }),
+  }),
+  update: definePact({
     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: {
+    request: z.object({
+      title: z.string().optional(),
+      body: z.string().optional(),
+    }),
+    response: z.object({
+      id: z.string(),
+      title: z.string(),
+      body: z.string(),
+    }),
+  }),
+  delete: definePact({
     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
+## Validation schemas
 
-| 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: ... })`     |
+| Field      | Required for                    | Description                                                       |
+| ---------- | ------------------------------- | ----------------------------------------------------------------- |
+| `request`  | Only for `post`, `patch`, `put` | Zod schema for `req.body` on the server                           |
+| `response` | Optional                        | Zod schema for the full response body sent via `res.json(...)`    |
+| `query`    | Optional                        | Zod schema for query parameters — typed on both server and client |
 
 ## 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 }`.
+Parameters in the path (`:param`) 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
@@ -93,71 +88,34 @@ await request(PostPacts.getById, { params: { id: "abc" } });
 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"
-```
+On the server, `req.parsedParams` is automatically populated from `req.params` and typed as `{ [key: string]: string }` based on the path string — no Zod schema needed.
 
-### `exhaustiveGuard(value)`
+## Query parameters
 
-A compile-time exhaustiveness check for `switch` statements. Throws at runtime if an unhandled branch is reached.
+Add a `query` Zod schema to make query parameters type-safe on both server and client. If any field in the schema is required, TypeScript will require the `queries` option at the call site:
 
 ```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
-  }
-}
+const list = definePact({
+  method: "get",
+  path: "/posts",
+  query: z.object({ page: z.string().optional(), sort: z.string() }), // sort is required
+});
+
+// TypeScript requires queries.sort
+await request(list, { queries: { sort: "createdAt" } });
 ```
 
 ## 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 |
+| Type                          | Description                                                                        |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `RoutePact`                   | Generic type for a single pact definition                                          |
+| `AnyRoutePact`                | Widened pact type — used internally and in package integrations                    |
+| `AnyRouteValidation`          | The set of optional Zod schemas that can be attached to a pact                     |
+| `HttpMethod`                  | `"get" \| "post" \| "patch" \| "put" \| "delete"`                                 |
+| `RouteOptions<TPact>`         | Inferred call-site options (params, payload, queries) for a pact                   |
+| `RouteOptionsRequired<TPact>` | `true` if options are required (pact has params or a request schema)               |
+| `QueryOption<TPact>`          | Inferred `queries` option — required if the query schema has required fields       |
+| `PactResponse<TPact>`         | Inferred return type when calling a pact from the client — `z.infer<response>` or `undefined` |
+| `ExtractParams<TPath>`        | Extracts parameter names from a path string                                        |
+| `ExpectedParams<TPath>`       | Maps extracted param names to `string` values                                      |

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./api.js";
 export * from "./types.js";
 export * from "./utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,3 @@
-export * from "./api.js";
 export * from "./types.js";
 export * from "./utils.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -1,41 +1,49 @@
 import type z from "zod/v4";
-import type { ApiResponse } from "./api.js";
 export type HttpMethod = "get" | "post" | "patch" | "put" | "delete";
-export type RouteValidation = {
+export type QueryParam = Record<string, string | number | boolean | undefined>;
+export type AnyRouteValidation = {
     response?: z.ZodType<unknown>;
     request?: z.ZodType<unknown>;
-    meta?: z.ZodType<unknown>;
-};
-export type RoutePact = {
-    path: string;
-    method: HttpMethod;
-    validation: RouteValidation;
+    query?: z.ZodType<QueryParam>;
+    params?: z.ZodType<Record<string, unknown>>;
 };
+export type RoutePact<TPath extends string, TMethod extends HttpMethod, TValidation extends AnyRouteValidation> = {
+    path: TPath;
+    method: TMethod;
+} & TValidation;
+export type AnyRoutePact = RoutePact<string, HttpMethod, AnyRouteValidation>;
 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;
-} : {
+type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+type RequiredOnly<T> = Pick<T, RequiredKeys<T>>;
+type HasParams<TPath extends string> = [ExtractParams<TPath>] extends [never] ? false : true;
+type ParamsOption<TPath extends string> = HasParams<TPath> extends true ? {
     params: ExpectedParams<TPath>;
+} : {
+    params?: never;
 };
-type PayloadOption<TPact extends RoutePact> = TPact["method"] extends "post" | "patch" | "put" ? TPact["validation"]["request"] extends z.ZodType<unknown> ? {
-    payload: z.infer<TPact["validation"]["request"]>;
+type PayloadOption<TPact extends AnyRoutePact> = TPact["method"] extends "post" | "patch" | "put" ? TPact["request"] extends z.ZodType<unknown> ? {
+    payload: z.infer<TPact["request"]>;
 } : {
     payload?: never;
 } : {
     payload?: never;
 };
-export type RouteOptions<TPact extends RoutePact> = ParamsOption<TPact["path"]> & PayloadOption<TPact> & {
-    queries?: Record<string, string>;
+export type QueryOption<TPact extends AnyRoutePact> = TPact["query"] extends z.ZodType<infer TQuery> ? {} extends RequiredOnly<TQuery> ? {
+    queries?: TQuery;
+} : {
+    queries: TQuery;
+} : {
+    queries?: never;
 };
-export type RouteOptionsRequired<TPact extends RoutePact> = TPact["validation"]["request"] extends z.ZodType<unknown> ? true : [ExtractParams<TPact["path"]>] extends [never] ? false : true;
-export type PactResponse<TPact extends RoutePact> = ApiResponse<TPact["validation"] extends {
-    response: z.ZodType<unknown>;
-} ? z.infer<TPact["validation"]["response"]> : undefined, TPact["validation"] extends {
+export type RouteOptions<TPact extends AnyRoutePact> = ParamsOption<TPact["path"]> & PayloadOption<TPact> & QueryOption<TPact>;
+export type RouteOptionsRequired<TPact extends AnyRoutePact> = {} extends RouteOptions<TPact> ? false : true;
+export type PactResponse<TPact extends AnyRoutePact> = TPact extends {
     response: z.ZodType<unknown>;
-    meta: z.ZodType<unknown>;
-} ? z.infer<TPact["validation"]["meta"]> : undefined>;
+} ? z.infer<TPact["response"]> : undefined;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils.d.ts

@@ -1,4 +1,22 @@
-import type { RouteOptions, RoutePact } from "./types.js";
+import type { AnyRoutePact, AnyRouteValidation, HttpMethod, 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;
+/**
+ * Builds a full endpoint path from a pact, substituting path parameters and
+ * appending a query string. Path param values are URL-encoded automatically.
+ * Throws if a required path parameter is missing from `options.params`.
+ */
+export declare function buildEndpoint<TPact extends AnyRoutePact>(pact: TPact, options?: RouteOptions<TPact>): string;
+/**
+ * Defines a type-safe route pact
+ *
+ * @example
+ * const getUser = definePact({
+ *    path: "/users/:id",
+ *    method: "get",
+ *    response: z.object({ id: z.string(), name: z.string() }),
+ *    params: z.object({ param: z.string() }),
+ *    query: z.object({ query: z.string() }),
+ * });
+ */
+export declare function definePact<const TPath extends string, TMethod extends HttpMethod, TValidation extends AnyRouteValidation>(pact: RoutePact<TPath, TMethod, TValidation>): RoutePact<TPath, TMethod, TValidation>;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAElB,UAAU,EACV,YAAY,EACZ,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,SAAS,YAAY,EACtD,IAAI,EAAE,KAAK,EACX,OAAO,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,GAC5B,MAAM,CAiBR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,KAAK,CAAC,KAAK,SAAS,MAAM,EAC1B,OAAO,SAAS,UAAU,EAC1B,WAAW,SAAS,kBAAkB,EAEtC,IAAI,EAAE,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,GAC3C,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAExC"}

package/dist/utils.js

@@ -1,14 +1,37 @@
 export function exhaustiveGuard(_value) {
     throw new Error(`Reached forbidden guard function with unexpected value: ${JSON.stringify(_value)}`);
 }
+/**
+ * Builds a full endpoint path from a pact, substituting path parameters and
+ * appending a query string. Path param values are URL-encoded automatically.
+ * Throws if a required path parameter is missing from `options.params`.
+ */
 export function buildEndpoint(pact, options) {
-    const replacedEndpoint = pact.path.replace(/:(\w+)/g, (match, key) => {
+    const replacedEndpoint = pact.path.replace(/:(\w+)/g, (_match, key) => {
         if (options?.params && key in options.params) {
-            return options.params[key];
+            return encodeURIComponent(options.params[key]);
         }
-        return match;
+        throw new Error(`Missing required path parameter: ${key}`);
     });
-    const queryString = new URLSearchParams(options?.queries).toString();
+    const queryEntries = Object.entries(options?.queries ?? {})
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, String(value)]);
+    const queryString = new URLSearchParams(queryEntries).toString();
     return queryString ? `${replacedEndpoint}?${queryString}` : replacedEndpoint;
 }
+/**
+ * Defines a type-safe route pact
+ *
+ * @example
+ * const getUser = definePact({
+ *    path: "/users/:id",
+ *    method: "get",
+ *    response: z.object({ id: z.string(), name: z.string() }),
+ *    params: z.object({ param: z.string() }),
+ *    query: z.object({ query: z.string() }),
+ * });
+ */
+export function definePact(pact) {
+    return pact;
+}
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,eAAe,CAAC,MAAa;IAC3C,MAAM,IAAI,KAAK,CACb,2DAA2D,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CACpF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAW,EACX,OAA6B;IAE7B,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;QACpE,IAAI,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAC7C,OAAO,kBAAkB,CACvB,OAAO,CAAC,MAAM,CAAC,GAA0C,CAAC,CAC3D,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC;SACxD,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE/C,MAAM,WAAW,GAAG,IAAI,eAAe,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;IAEjE,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,gBAAgB,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAKxB,IAA4C;IAE5C,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routepact/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Type-safe route spec definitions shared between server and client",
   "type": "module",
   "repository": "gitlab:mr5k/routepact",