@ts-contract/plugins 1.0.0-alpha.0 → 1.0.0-alpha.1

package/README.md

@@ -1,7 +1,216 @@
-# utils
+# @ts-contract/plugins
 
-This library was generated with [Nx](https://nx.dev).
+Built-in plugins for path building and schema validation for ts-contract.
 
-## Building
+## Overview
 
-Run `nx build utils` to build the library.
+`@ts-contract/plugins` provides official plugins that extend ts-contract with commonly needed functionality:
+
+- **Path Plugin** - Build URL paths with type-safe parameter substitution
+- **Validate Plugin** - Validate request/response data against schemas
+
+## Installation
+
+```bash
+npm install @ts-contract/plugins @ts-contract/core
+# or
+pnpm add @ts-contract/plugins @ts-contract/core
+# or
+yarn add @ts-contract/plugins @ts-contract/core
+```
+
+## Plugins
+
+### Path Plugin
+
+Build type-safe URL paths with parameter substitution and query string generation.
+
+#### Usage
+
+```typescript
+import { initContract } from '@ts-contract/core';
+import { pathPlugin } from '@ts-contract/plugins';
+import { contract } from './contract';
+
+const api = initContract(contract).use(pathPlugin).build();
+
+// Build path with parameters
+const path = api.getUser.buildPath({ id: '123' });
+// => "/users/123"
+
+// Build path with query parameters
+const path = api.listUsers.buildPath(undefined, { page: '1', limit: '10' });
+// => "/users?page=1&limit=10"
+
+// Build path with both
+const path = api.searchUsers.buildPath(
+  { category: 'active' },
+  { sort: 'name' },
+);
+// => "/users/active?sort=name"
+```
+
+#### API
+
+**`buildPath(params?, query?)`**
+
+Builds a URL path from the route definition.
+
+- **params** - Path parameters (typed from contract)
+- **query** - Query parameters (typed from contract)
+- **Returns:** String URL path
+
+### Validate Plugin
+
+Validate request bodies and response data against your contract schemas.
+
+#### Usage
+
+```typescript
+import { initContract } from '@ts-contract/core';
+import { validatePlugin } from '@ts-contract/plugins';
+import { contract } from './contract';
+
+const api = initContract(contract).use(validatePlugin).build();
+
+// Validate request body
+try {
+  const validatedBody = api.createUser.validateBody({
+    name: 'Alice',
+    email: 'alice@example.com',
+  });
+  // validatedBody is typed and validated
+} catch (error) {
+  // Validation failed
+}
+
+// Validate response
+try {
+  const validatedResponse = api.getUser.validateResponse(200, {
+    id: '123',
+    name: 'Alice',
+    email: 'alice@example.com',
+  });
+  // validatedResponse is typed and validated
+} catch (error) {
+  // Validation failed
+}
+
+// Validate path parameters
+const validatedParams = api.getUser.validatePathParams({ id: '123' });
+
+// Validate query parameters
+const validatedQuery = api.listUsers.validateQuery({ page: '1', limit: '10' });
+
+// Validate headers
+const validatedHeaders = api.getUser.validateHeaders({
+  authorization: 'Bearer token',
+});
+```
+
+#### API
+
+**`validateBody(data)`**
+
+Validates request body data against the route's body schema.
+
+- **data** - Data to validate
+- **Returns:** Validated and typed data
+- **Throws:** Validation error if data is invalid
+
+**`validateResponse(status, data)`**
+
+Validates response data against the route's response schema for a specific status code.
+
+- **status** - HTTP status code
+- **data** - Data to validate
+- **Returns:** Validated and typed data
+- **Throws:** Validation error if data is invalid
+
+**`validatePathParams(data)`**
+
+Validates path parameters against the route's pathParams schema.
+
+**`validateQuery(data)`**
+
+Validates query parameters against the route's query schema.
+
+**`validateHeaders(data)`**
+
+Validates headers against the route's headers schema.
+
+## Using Both Plugins
+
+Combine plugins for full functionality:
+
+```typescript
+import { initContract } from '@ts-contract/core';
+import { pathPlugin, validatePlugin } from '@ts-contract/plugins';
+
+const api = initContract(contract).use(pathPlugin).use(validatePlugin).build();
+
+// Use both plugin methods
+const path = api.createUser.buildPath();
+const validatedBody = api.createUser.validateBody({
+  name: 'Alice',
+  email: 'alice@example.com',
+});
+
+// Make request
+const response = await fetch(path, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(validatedBody),
+});
+
+const data = await response.json();
+const validatedResponse = api.createUser.validateResponse(201, data);
+```
+
+## Type Safety
+
+All plugin methods are fully typed based on your contract:
+
+- Path parameters are typed from `pathParams` schema
+- Query parameters are typed from `query` schema
+- Request body is typed from `body` schema
+- Response data is typed from `responses` schema
+- TypeScript will catch type errors at compile time
+
+## Error Handling
+
+Validation errors include detailed information:
+
+```typescript
+try {
+  api.createUser.validateBody({ name: 'Alice' }); // Missing email
+} catch (error) {
+  console.error(error.message);
+  // Detailed validation error from schema library
+}
+```
+
+## Schema Library Support
+
+Works with any schema library that implements the [Standard Schema](https://github.com/standard-schema/standard-schema) specification:
+
+- ✅ Zod
+- ✅ Valibot
+- ✅ Arktype
+- ✅ And more...
+
+## Documentation
+
+For complete documentation and examples, visit:
+
+- [Path Plugin Documentation](https://github.com/mbrimmer83/ts-contract/tree/main/docs/plugins/path-plugin.md)
+- [Validate Plugin Documentation](https://github.com/mbrimmer83/ts-contract/tree/main/docs/plugins/validate-plugin.md)
+- [Creating Custom Plugins](https://github.com/mbrimmer83/ts-contract/tree/main/docs/plugins/creating-custom-plugins.md)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please see the [contributing guide](../../CONTRIBUTING.md) for details.

package/dist/index.d.ts

@@ -2,4 +2,8 @@ export * from './lib/path';
 export * from './lib/validate';
 export * from './lib/plugins/path';
 export * from './lib/plugins/validate';
+export * from './lib/websocket-path';
+export * from './lib/websocket-validate';
+export * from './lib/plugins/websocket-path';
+export * from './lib/plugins/websocket-validate';
 //# 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,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC"}

package/dist/index.js

@@ -2,3 +2,7 @@ export * from './lib/path';
 export * from './lib/validate';
 export * from './lib/plugins/path';
 export * from './lib/plugins/validate';
+export * from './lib/websocket-path';
+export * from './lib/websocket-validate';
+export * from './lib/plugins/websocket-path';
+export * from './lib/plugins/websocket-validate';

package/dist/lib/plugins/websocket-path.d.ts

@@ -0,0 +1,12 @@
+import type { WebSocketDef, InferWebSocketPathParams, InferWebSocketQuery, WebSocketPlugin } from '@ts-contract/core';
+type BuildPathArgs<W extends WebSocketDef> = InferWebSocketPathParams<W> extends undefined ? InferWebSocketQuery<W> extends undefined ? [] : [params?: undefined, query?: InferWebSocketQuery<W>] : InferWebSocketQuery<W> extends undefined ? [params: InferWebSocketPathParams<W>] : [params: InferWebSocketPathParams<W>, query?: InferWebSocketQuery<W>];
+declare module '@ts-contract/core' {
+    interface WebSocketPluginTypeRegistry<W> {
+        'websocket-path': {
+            buildPath: W extends WebSocketDef ? (...args: BuildPathArgs<W>) => string : never;
+        };
+    }
+}
+export declare const websocketPathPlugin: WebSocketPlugin<'websocket-path'>;
+export {};
+//# sourceMappingURL=websocket-path.d.ts.map

package/dist/lib/plugins/websocket-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-path.d.ts","sourceRoot":"","sources":["../../../src/lib/plugins/websocket-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAG3B,KAAK,aAAa,CAAC,CAAC,SAAS,YAAY,IACvC,wBAAwB,CAAC,CAAC,CAAC,SAAS,SAAS,GACzC,mBAAmB,CAAC,CAAC,CAAC,SAAS,SAAS,GACtC,EAAE,GACF,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,GACtD,mBAAmB,CAAC,CAAC,CAAC,SAAS,SAAS,GACtC,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,GACrC,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9E,OAAO,QAAQ,mBAAmB,CAAC;IACjC,UAAU,2BAA2B,CAAC,CAAC;QACrC,gBAAgB,EAAE;YAChB,SAAS,EAAE,CAAC,SAAS,YAAY,GAC7B,CAAC,GAAG,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,MAAM,GACrC,KAAK,CAAC;SACX,CAAC;KACH;CACF;AAED,eAAO,MAAM,mBAAmB,EAAE,eAAe,CAAC,gBAAgB,CASjE,CAAC"}

package/dist/lib/plugins/websocket-path.js

@@ -0,0 +1,7 @@
+import { buildWebSocketPath } from '../websocket-path';
+export const websocketPathPlugin = {
+    name: 'websocket-path',
+    websocket: (def) => ({
+        buildPath: (...args) => buildWebSocketPath(def, ...args),
+    }),
+};

package/dist/lib/plugins/websocket-validate.d.ts

@@ -0,0 +1,14 @@
+import type { WebSocketDef, InferWebSocketPathParams, InferWebSocketQuery, InferWebSocketHeaders, InferClientMessage, InferServerMessage, WebSocketPlugin } from '@ts-contract/core';
+declare module '@ts-contract/core' {
+    interface WebSocketPluginTypeRegistry<W> {
+        'websocket-validate': {
+            validateClientMessage: W extends WebSocketDef ? <E extends keyof W['clientMessages'] & string>(eventName: E, data: unknown) => InferClientMessage<W, E> : never;
+            validateServerMessage: W extends WebSocketDef ? <E extends keyof W['serverMessages'] & string>(eventName: E, data: unknown) => InferServerMessage<W, E> : never;
+            validatePathParams: W extends WebSocketDef ? (params: unknown) => InferWebSocketPathParams<W> : never;
+            validateQuery: W extends WebSocketDef ? (query: unknown) => InferWebSocketQuery<W> : never;
+            validateHeaders: W extends WebSocketDef ? (headers: Record<string, unknown>) => InferWebSocketHeaders<W> : never;
+        };
+    }
+}
+export declare const websocketValidatePlugin: WebSocketPlugin<'websocket-validate'>;
+//# sourceMappingURL=websocket-validate.d.ts.map

package/dist/lib/plugins/websocket-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-validate.d.ts","sourceRoot":"","sources":["../../../src/lib/plugins/websocket-validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAS3B,OAAO,QAAQ,mBAAmB,CAAC;IACjC,UAAU,2BAA2B,CAAC,CAAC;QACrC,oBAAoB,EAAE;YACpB,qBAAqB,EAAE,CAAC,SAAS,YAAY,GACzC,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,gBAAgB,CAAC,GAAG,MAAM,EAC3C,SAAS,EAAE,CAAC,EACZ,IAAI,EAAE,OAAO,KACV,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,KAAK,CAAC;YACV,qBAAqB,EAAE,CAAC,SAAS,YAAY,GACzC,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,gBAAgB,CAAC,GAAG,MAAM,EAC3C,SAAS,EAAE,CAAC,EACZ,IAAI,EAAE,OAAO,KACV,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,KAAK,CAAC;YACV,kBAAkB,EAAE,CAAC,SAAS,YAAY,GACtC,CAAC,MAAM,EAAE,OAAO,KAAK,wBAAwB,CAAC,CAAC,CAAC,GAChD,KAAK,CAAC;YACV,aAAa,EAAE,CAAC,SAAS,YAAY,GACjC,CAAC,KAAK,EAAE,OAAO,KAAK,mBAAmB,CAAC,CAAC,CAAC,GAC1C,KAAK,CAAC;YACV,eAAe,EAAE,CAAC,SAAS,YAAY,GACnC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,qBAAqB,CAAC,CAAC,CAAC,GAC9D,KAAK,CAAC;SACX,CAAC;KACH;CACF;AAED,eAAO,MAAM,uBAAuB,EAAE,eAAe,CAAC,oBAAoB,CAazE,CAAC"}

package/dist/lib/plugins/websocket-validate.js

@@ -0,0 +1,11 @@
+import { validateClientMessage, validateServerMessage, validateWebSocketPathParams, validateWebSocketQuery, validateWebSocketHeaders, } from '../websocket-validate';
+export const websocketValidatePlugin = {
+    name: 'websocket-validate',
+    websocket: (def) => ({
+        validateClientMessage: (eventName, data) => validateClientMessage(def, eventName, data),
+        validateServerMessage: (eventName, data) => validateServerMessage(def, eventName, data),
+        validatePathParams: (params) => validateWebSocketPathParams(def, params),
+        validateQuery: (query) => validateWebSocketQuery(def, query),
+        validateHeaders: (headers) => validateWebSocketHeaders(def, headers),
+    }),
+};

package/dist/lib/websocket-path.d.ts

@@ -0,0 +1,5 @@
+import type { WebSocketDef, InferWebSocketPathParams, InferWebSocketQuery } from '@ts-contract/core';
+type BuildWebSocketPathArgs<W extends WebSocketDef> = InferWebSocketPathParams<W> extends undefined ? InferWebSocketQuery<W> extends undefined ? [] : [params?: undefined, query?: InferWebSocketQuery<W>] : InferWebSocketQuery<W> extends undefined ? [params: InferWebSocketPathParams<W>] : [params: InferWebSocketPathParams<W>, query?: InferWebSocketQuery<W>];
+export declare const buildWebSocketPath: <W extends WebSocketDef>(def: W, ...args: BuildWebSocketPathArgs<W>) => string;
+export {};
+//# sourceMappingURL=websocket-path.d.ts.map

package/dist/lib/websocket-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-path.d.ts","sourceRoot":"","sources":["../../src/lib/websocket-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,sBAAsB,CAAC,CAAC,SAAS,YAAY,IAChD,wBAAwB,CAAC,CAAC,CAAC,SAAS,SAAS,GACzC,mBAAmB,CAAC,CAAC,CAAC,SAAS,SAAS,GACtC,EAAE,GACF,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,GACtD,mBAAmB,CAAC,CAAC,CAAC,SAAS,SAAS,GACtC,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,GACrC,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9E,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,YAAY,EACvD,KAAK,CAAC,EACN,GAAG,MAAM,sBAAsB,CAAC,CAAC,CAAC,KACjC,MA+BF,CAAC"}

package/dist/lib/websocket-path.js

@@ -0,0 +1,25 @@
+export const buildWebSocketPath = (def, ...args) => {
+    const [params, query] = args;
+    let path = def.path;
+    if (params) {
+        path = path.replace(/:([^/]+)/g, (_, key) => {
+            if (!(key in params)) {
+                throw new Error(`Missing path parameter: ${key}`);
+            }
+            return encodeURIComponent(params[key]);
+        });
+    }
+    if (query) {
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null) {
+                searchParams.append(key, String(value));
+            }
+        }
+        const qs = searchParams.toString();
+        if (qs) {
+            path += `?${qs}`;
+        }
+    }
+    return path;
+};

package/dist/lib/websocket-validate.d.ts

@@ -0,0 +1,7 @@
+import type { WebSocketDef, InferWebSocketPathParams, InferWebSocketQuery, InferWebSocketHeaders, InferClientMessage, InferServerMessage } from '@ts-contract/core';
+export declare const validateClientMessage: <W extends WebSocketDef, E extends keyof W["clientMessages"] & string>(def: W, eventName: E, data: unknown) => InferClientMessage<W, E>;
+export declare const validateServerMessage: <W extends WebSocketDef, E extends keyof W["serverMessages"] & string>(def: W, eventName: E, data: unknown) => InferServerMessage<W, E>;
+export declare const validateWebSocketPathParams: <W extends WebSocketDef>(def: W, params: unknown) => InferWebSocketPathParams<W>;
+export declare const validateWebSocketQuery: <W extends WebSocketDef>(def: W, query: unknown) => InferWebSocketQuery<W>;
+export declare const validateWebSocketHeaders: <W extends WebSocketDef>(def: W, headers: Record<string, unknown>) => InferWebSocketHeaders<W>;
+//# sourceMappingURL=websocket-validate.d.ts.map

package/dist/lib/websocket-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-validate.d.ts","sourceRoot":"","sources":["../../src/lib/websocket-validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAEnB,MAAM,mBAAmB,CAAC;AAoB3B,eAAO,MAAM,qBAAqB,GAChC,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,MAAM,CAAC,CAAC,gBAAgB,CAAC,GAAG,MAAM,EAE5C,KAAK,CAAC,EACN,WAAW,CAAC,EACZ,MAAM,OAAO,KACZ,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAYzB,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,MAAM,CAAC,CAAC,gBAAgB,CAAC,GAAG,MAAM,EAE5C,KAAK,CAAC,EACN,WAAW,CAAC,EACZ,MAAM,OAAO,KACZ,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAYzB,CAAC;AAEF,eAAO,MAAM,2BAA2B,GAAI,CAAC,SAAS,YAAY,EAChE,KAAK,CAAC,EACN,QAAQ,OAAO,KACd,wBAAwB,CAAC,CAAC,CAS5B,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,CAAC,SAAS,YAAY,EAC3D,KAAK,CAAC,EACN,OAAO,OAAO,KACb,mBAAmB,CAAC,CAAC,CASvB,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,YAAY,EAC7D,KAAK,CAAC,EACN,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,qBAAqB,CAAC,CAAC,CAazB,CAAC"}

package/dist/lib/websocket-validate.js

@@ -0,0 +1,47 @@
+/**
+ * Validate a value against a Standard Schema, throwing on failure
+ */
+const validateSchema = (schema, value, label) => {
+    const result = schema['~standard'].validate(value);
+    if ('issues' in result && result.issues) {
+        const messages = result.issues.map((i) => i.message).join(', ');
+        throw new Error(`Validation failed for ${label}: ${messages}`);
+    }
+    return result.value;
+};
+export const validateClientMessage = (def, eventName, data) => {
+    const schema = def.clientMessages[eventName];
+    if (!schema) {
+        throw new Error(`WebSocket "${def.path}" has no client message schema for event "${eventName}"`);
+    }
+    return validateSchema(schema, data, `client message "${eventName}" of ${def.path}`);
+};
+export const validateServerMessage = (def, eventName, data) => {
+    const schema = def.serverMessages[eventName];
+    if (!schema) {
+        throw new Error(`WebSocket "${def.path}" has no server message schema for event "${eventName}"`);
+    }
+    return validateSchema(schema, data, `server message "${eventName}" of ${def.path}`);
+};
+export const validateWebSocketPathParams = (def, params) => {
+    if (!def.pathParams) {
+        throw new Error(`WebSocket "${def.path}" has no pathParams schema`);
+    }
+    return validateSchema(def.pathParams, params, `pathParams of ${def.path}`);
+};
+export const validateWebSocketQuery = (def, query) => {
+    if (!def.query) {
+        throw new Error(`WebSocket "${def.path}" has no query schema`);
+    }
+    return validateSchema(def.query, query, `query of ${def.path}`);
+};
+export const validateWebSocketHeaders = (def, headers) => {
+    if (!def.headers) {
+        throw new Error(`WebSocket "${def.path}" has no headers schema`);
+    }
+    const result = {};
+    for (const [key, schema] of Object.entries(def.headers)) {
+        result[key] = validateSchema(schema, headers[key], `header "${key}" of ${def.path}`);
+    }
+    return result;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-contract/plugins",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.1",
   "description": "Built-in plugins for path building and schema validation for ts-contract",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@ts-contract/core": "1.0.0-alpha.0"
+    "@ts-contract/core": "1.0.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.lib.json",