@rexeus/typeweaver-types 0.0.1

package/dist/lib/InvalidResponseStatusCodeError.ts

@@ -0,0 +1,21 @@
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+
+/**
+ * Error thrown when an HTTP response has an unexpected status code.
+ *
+ * This error is typically thrown during response validation when the
+ * actual status code doesn't match any of the expected status codes
+ * defined in the operation specification.
+ *
+ * The error includes the complete response for debugging and error handling.
+ */
+export class InvalidResponseStatusCodeError extends Error {
+  /**
+   * Creates a new InvalidResponseStatusCodeError.
+   *
+   * @param response - The HTTP response with unexpected status code
+   */
+  constructor(public response: IHttpResponse) {
+    super("Invalid response status code");
+  }
+}

package/dist/lib/RequestValidator.ts

@@ -0,0 +1,43 @@
+import type {
+  IHttpRequest,
+  IRequestValidator,
+  SafeRequestValidationResult,
+} from "@rexeus/typeweaver-core";
+
+/**
+ * Abstract base class for HTTP request validation.
+ *
+ * This class provides the foundation for request validators that:
+ * - Validate headers, body, query parameters, and path parameters
+ * - Support both safe (non-throwing) and unsafe (throwing) validation
+ * - Integrate with Zod schemas for runtime validation
+ * - Provide detailed error information for debugging
+ *
+ * Implementations should validate all request components and either:
+ * - Return validated data (for `validate`)
+ * - Return success/error result (for `safeValidate`)
+ */
+export abstract class RequestValidator implements IRequestValidator {
+  public constructor() {
+    //
+  }
+
+  /**
+   * Validates a request without throwing errors.
+   *
+   * @param request - The HTTP request to validate
+   * @returns A result object containing either the validated request or error details
+   */
+  public abstract safeValidate(
+    request: IHttpRequest
+  ): SafeRequestValidationResult<IHttpRequest>;
+
+  /**
+   * Validates a request and throws if validation fails.
+   *
+   * @param request - The HTTP request to validate
+   * @returns The validated request with proper typing
+   * @throws {RequestValidationError} If any part of the request fails validation
+   */
+  public abstract validate(request: IHttpRequest): IHttpRequest;
+}

package/dist/lib/ResponseValidator.ts

@@ -0,0 +1,39 @@
+import type {
+  IHttpResponse,
+  IResponseValidator,
+  SafeResponseValidationResult,
+} from "@rexeus/typeweaver-core";
+
+/**
+ * Abstract base class for HTTP response validation.
+ *
+ * This class provides the foundation for response validators that:
+ * - Validate response status codes match expected values
+ * - Validate response headers and body against schemas
+ * - Support both safe (non-throwing) and unsafe (throwing) validation
+ * - Integrate with Zod schemas for runtime validation
+ *
+ * Response validators are typically used in API clients to ensure
+ * responses match the expected format before processing.
+ */
+export abstract class ResponseValidator implements IResponseValidator {
+  /**
+   * Validates a response without throwing errors.
+   *
+   * @param response - The HTTP response to validate
+   * @returns A result object containing either the validated response or error details
+   */
+  public abstract safeValidate(
+    response: IHttpResponse
+  ): SafeResponseValidationResult<IHttpResponse>;
+
+  /**
+   * Validates a response and throws if validation fails.
+   *
+   * @param response - The HTTP response to validate
+   * @returns The validated response with proper typing
+   * @throws {InvalidResponseStatusCodeError} If status code doesn't match expected
+   * @throws {ResponseValidationError} If response structure fails validation
+   */
+  public abstract validate(response: IHttpResponse): IHttpResponse;
+}

package/dist/lib/assert.ts

@@ -0,0 +1,5 @@
+export function assert(value: any, message?: string): asserts value {
+  if (!value) {
+    throw new Error(message || "Assertion failed");
+  }
+}

package/dist/lib/index.ts

@@ -0,0 +1,4 @@
+export * from "./assert";
+export * from "./InvalidResponseStatusCodeError";
+export * from "./RequestValidator";
+export * from "./ResponseValidator";

package/dist/templates/Request.ejs

@@ -0,0 +1,93 @@
+import definition from "<%= sourcePath %>";
+import { HttpMethod, type IHttpResponse } from "@rexeus/typeweaver-core";
+import { RequestCommand } from "../lib/clients";
+import { <%= pascalCaseOperationId %>ResponseValidator } from "<%= responseValidationFile %>";
+import {
+    type <%= pascalCaseOperationId %>Response,
+    <% for (const ownResponse of [...ownSuccessResponses, ...ownErrorResponses]) { %>
+        <%= ownResponse.name %>Response,
+    <% } %>
+} from "<%= responseFile %>";
+<% for (const sharedResponse of [...sharedSuccessResponses, ...sharedErrorResponses]) { %>
+    import { <%= sharedResponse.name %>Response } from "<%= sharedResponse.path %>";
+<% } %>
+
+<% if (headerTsType) { %>
+export type I<%= pascalCaseOperationId %>RequestHeader = <%- headerTsType %>
+<% } %>
+
+<% if (paramTsType) { %>
+export type I<%= pascalCaseOperationId %>RequestParam = <%- paramTsType %>
+<% } %>
+
+<% if (queryTsType) { %>
+export type I<%= pascalCaseOperationId %>RequestQuery = <%- queryTsType %>
+<% } %>
+
+<% if (bodyTsType) { %>
+export type I<%= pascalCaseOperationId %>RequestBody = <%- bodyTsType %>
+<% } %>
+
+export type I<%= pascalCaseOperationId %>Request = {
+    path: string;
+    method: HttpMethod.<%= method %>;
+    <%= headerTsType ? `header: I${pascalCaseOperationId}RequestHeader;` : "" %>
+    <%= paramTsType ? `param: I${pascalCaseOperationId}RequestParam;` : "" %>
+    <%= queryTsType ? `query: I${pascalCaseOperationId}RequestQuery;` : "" %>
+    <%= bodyTsType ? `body: I${pascalCaseOperationId}RequestBody;` : "" %>
+};
+
+<% if (!hasSuccessResponses) { %>
+    export type Successful<%= pascalCaseOperationId %>Response = never;
+<% } else if (!hasErrorResponses) { %>
+    export type Successful<%= pascalCaseOperationId %>Response = <%= pascalCaseOperationId %>Response;
+<% } else { %>
+    export type Successful<%= pascalCaseOperationId %>Response = Exclude<<%= pascalCaseOperationId %>Response, <%= [...ownErrorResponses, ...sharedErrorResponses].map(({ name }) => `${name}Response`).join(" | ") %>
+    >;
+<% } %>
+
+export class <%= pascalCaseOperationId %>RequestCommand extends RequestCommand implements I<%= pascalCaseOperationId %>Request {
+    public override readonly method = definition.method as HttpMethod.<%= method %>;
+    public override readonly path = definition.path;
+
+    public <%= headerTsType ? `override` : `declare` %> readonly header: <%= headerTsType ? `I${pascalCaseOperationId}RequestHeader` : `undefined` %>;
+    public  <%= paramTsType ? `override` : `declare` %> readonly param: <%= paramTsType ? `I${pascalCaseOperationId}RequestParam` : `undefined` %>;
+    public <%= queryTsType ? `override` : `declare` %> readonly query: <%= queryTsType ? `I${pascalCaseOperationId}RequestQuery` : `undefined` %>;
+    public <%= bodyTsType ? `override` : `declare` %> readonly body: <%= bodyTsType ? `I${pascalCaseOperationId}RequestBody` : `undefined` %>;
+
+    private readonly responseValidator: <%= pascalCaseOperationId %>ResponseValidator;
+
+    public constructor(input: Omit<I<%= pascalCaseOperationId %>Request, "method" | "path">) {
+        super();
+
+        <% if (headerTsType) { %>
+        this.header = input.header;
+        <% } %>
+
+        <% if (paramTsType) { %>
+        this.param = input.param;
+        <% } %>
+
+        <% if (queryTsType) { %>
+        this.query = input.query;
+        <% } %>
+
+        <% if (bodyTsType) { %>
+        this.body = input.body;
+        <% } %>
+
+        this.responseValidator = new <%= pascalCaseOperationId %>ResponseValidator();
+    }
+
+    public processResponse(response: IHttpResponse): Successful<%= pascalCaseOperationId %>Response {
+        const result = this.responseValidator.validate(response);
+
+        <% for (const successResponse of [...ownSuccessResponses, ...sharedSuccessResponses]) { %>
+            if (result instanceof <%= successResponse.name %>Response) {
+                return result;
+            }
+        <% } %>
+
+        throw result;
+    }
+}

package/dist/templates/RequestValidator.ejs

@@ -0,0 +1,92 @@
+import definition from "<%= sourcePath %>";
+import { 
+  type IHttpRequest,
+  type SafeRequestValidationResult,
+  RequestValidationError
+} from "@rexeus/typeweaver-core";
+import { RequestValidator } from "../lib/types";
+import type { I<%= pascalCaseOperationId %>Request } from "<%= requestFile %>";
+
+export class <%= pascalCaseOperationId %>RequestValidator extends RequestValidator {
+    public safeValidate(request: IHttpRequest): SafeRequestValidationResult<I<%= pascalCaseOperationId %>Request> {
+        const error = new RequestValidationError();
+        const validatedRequest: IHttpRequest = {
+            method: request.method,
+            path: request.path,
+            query: undefined,
+            header: undefined,
+            body: undefined,
+            param: undefined,
+        };
+
+        <% if(body) { %>
+            if (definition.request.body) {
+                const result = definition.request.body.safeParse(request.body);
+          
+                if (!result.success) {
+                  error.addBodyIssues(result.error.issues);
+                } else {
+                  validatedRequest.body = result.data;
+                }
+            }
+        <% } %>
+
+        <% if(header) { %>
+            if (definition.request.header) {
+                const result = definition.request.header.safeParse(request.header);
+          
+                if (!result.success) {
+                  error.addHeaderIssues(result.error.issues);
+                } else {
+                  validatedRequest.header = result.data;
+                }
+            }
+        <% } %>
+
+        <% if(param) { %>
+            if (definition.request.param) {
+                const result = definition.request.param.safeParse(request.param);
+          
+                if (!result.success) {
+                  error.addPathParamIssues(result.error.issues);
+                } else {
+                  validatedRequest.param = result.data;
+                }
+            }
+        <% } %>
+
+        <% if(query) { %>
+            if (definition.request.query) {
+                const result = definition.request.query.safeParse(request.query);
+          
+                if (!result.success) {
+                  error.addQueryIssues(result.error.issues);
+                } else {
+                  validatedRequest.query = result.data;
+                }
+            }
+        <% } %>
+
+        if (error.hasIssues()) {
+            return {
+              isValid: false,
+              error,
+            };
+          }
+      
+          return {
+            isValid: true,
+            data: validatedRequest as I<%= pascalCaseOperationId %>Request,
+          };
+    }
+
+    public validate(request: IHttpRequest): I<%= pascalCaseOperationId %>Request {
+        const result = this.safeValidate(request);
+    
+        if (!result.isValid) {
+          throw result.error;
+        }
+    
+        return result.data;
+      }
+}

package/dist/templates/Response.ejs

@@ -0,0 +1,78 @@
+import { HttpResponse, HttpStatusCode } from "<%= coreDir %>";
+<% for(const sharedResponse of sharedResponses) { %>
+import type { I<%= sharedResponse.name %>Response, <%= sharedResponse.name %>Response } from "<%= sharedResponse.path %>";
+<% } %>
+
+<% for (const ownResponse of ownResponses) { %>
+    <% if (ownResponse.header) { %>
+        export type I<%= ownResponse.name %>ResponseHeader = <%- ownResponse.header %>;
+    <% } %>
+
+    <% if (ownResponse.body) { %>
+        export type I<%= ownResponse.name %>ResponseBody = <%- ownResponse.body %>;
+    <% } %>
+
+
+    export type I<%= ownResponse.name %>Response =  {
+            statusCode: HttpStatusCode.<%= ownResponse.statusCodeKey %>
+            <%= ownResponse.header ? `header: I${ownResponse.name}ResponseHeader;` : "" %>
+            <%= ownResponse.body ? `body: I${ownResponse.name}ResponseBody;` : "" %>
+            };
+
+    export class <%= ownResponse.name %>Response extends HttpResponse<
+            <%= ownResponse.header ? `I${ownResponse.name}ResponseHeader` : 'undefined' %>,
+            <%= ownResponse.body ? `I${ownResponse.name}ResponseBody` : 'undefined' %>,
+            > implements I<%= ownResponse.name %>Response {
+        public override readonly statusCode: HttpStatusCode.<%= ownResponse.statusCodeKey %>;
+
+        public constructor(response: I<%= ownResponse.name %>Response) {
+            super(
+                response.statusCode,
+                <%= ownResponse.header ? `response.header` : 'undefined' %>,
+                <%= ownResponse.body ? `response.body` : 'undefined' %>,
+            );
+
+            if(response.statusCode !== HttpStatusCode.<%= ownResponse.statusCodeKey %>) {
+                throw new Error(`Invalid status code: '${response.statusCode}' for <%= ownResponse.name %>Response`);
+            }
+
+            this.statusCode = response.statusCode;
+        }
+    }
+<% } %>
+
+<%
+// Identify success responses (status codes 200-299)
+const successResponses = ownResponses.filter(response => response.statusCode >= 200 && response.statusCode < 300);
+const errorResponses = ownResponses.filter(response => response.statusCode < 200 || response.statusCode >= 300);
+%>
+
+<% if (successResponses.length > 0) { %>
+export type I<%= pascalCaseOperationId %>SuccessResponses =<% if (successResponses.length === 1) { %> I<%= successResponses[0].name %>Response;<% } else { %>
+<% for (const [index, successResponse] of successResponses.entries()) { %>
+<% if (index === 0) { %>    I<%= successResponse.name %>Response<% } else { %>
+    | I<%= successResponse.name %>Response<% } %>
+<% } %>;<% } %>
+
+export type <%= pascalCaseOperationId %>SuccessResponses =<% if (successResponses.length === 1) { %> <%= successResponses[0].name %>Response;<% } else { %>
+<% for (const [index, successResponse] of successResponses.entries()) { %>
+<% if (index === 0) { %>    <%= successResponse.name %>Response<% } else { %>
+    | <%= successResponse.name %>Response<% } %>
+<% } %>;<% } %>
+<% } %>
+
+export type I<%= pascalCaseOperationId %>Response =
+<% for (const ownResponse of ownResponses) { %>
+    | I<%= ownResponse.name %>Response
+<% } %>
+<% for (const sharedResponse of sharedResponses) { %>
+    | I<%= sharedResponse.name %>Response
+<% } %>;
+
+export type <%= pascalCaseOperationId %>Response =
+<% for (const ownResponse of ownResponses) { %>
+    | <%= ownResponse.name %>Response
+<% } %>
+<% for (const sharedResponse of sharedResponses) { %>
+    | <%= sharedResponse.name %>Response
+<% } %>;

package/dist/templates/ResponseValidator.ejs

@@ -0,0 +1,142 @@
+import definition from "<%= sourcePath %>";
+import { 
+    type IHttpResponse,
+    type SafeResponseValidationResult,
+    ResponseValidationError
+} from "@rexeus/typeweaver-core";
+import {
+    ResponseValidator,
+    InvalidResponseStatusCodeError,
+    assert,
+} from "../lib/types";
+import {
+type <%= pascalCaseOperationId %>Response,
+<% for (const ownResponse of ownResponses) { %>
+    type I<%= ownResponse.name %>Response,
+    <%= ownResponse.name %>Response,
+<% } %>
+} from "<%= responseFile %>";
+<% for (const sharedResponse of sharedResponses) { %>
+    import {
+        type I<%= sharedResponse.name %>Response,
+        <%= sharedResponse.name %>Response,
+    } from "<%= sharedResponse.importPath %>";
+<% } %>
+
+export class <%= pascalCaseOperationId %>ResponseValidator extends ResponseValidator {
+    public safeValidate(response: IHttpResponse): SafeResponseValidationResult<<%= pascalCaseOperationId %>Response> {
+        const error = new ResponseValidationError(response.statusCode);
+        const validationResult = this.validateAgainstDefinedResponses(response, error);
+
+        if (error.hasIssues() && !validationResult.validResponseName) {
+            return {
+              isValid: false,
+              error,
+            };
+        }
+
+        let data: <%= pascalCaseOperationId %>Response;
+        switch (response.statusCode) {
+            <% for (const statusCode of allStatusCodes) { %>
+                case <%= statusCode.statusCode %>: {
+                    <%
+                        for (const response of [...ownResponses, ...sharedResponses]) {
+                            if (response.statusCode === statusCode.statusCode) {
+                    %>
+                        if (validationResult.validResponseName === "<%= response.name %>") {
+                            data = new <%= response.name %>Response(validationResult.validatedResponse as unknown as I<%= response.name %>Response);
+                            break;
+                        }
+                    <% } } %>
+                    throw new Error("Could not find a response for status code '<%= statusCode.statusCode %>'");
+                }
+            <% } %>
+
+            default: {
+                throw new InvalidResponseStatusCodeError(response);
+            }
+        }
+
+        return {
+            isValid: true,
+            data,
+        };
+    }
+
+    public validate(response: IHttpResponse): <%= pascalCaseOperationId %>Response {
+        const result = this.safeValidate(response);
+    
+        if (!result.isValid) {
+          throw result.error;
+        }
+    
+        return result.data;
+    }
+
+    private validateAgainstDefinedResponses(response: IHttpResponse, error: ResponseValidationError): { validResponseName?: string; validatedResponse?: IHttpResponse } {
+        const validatedResponse: IHttpResponse = {
+            statusCode: response.statusCode,
+            header: undefined,
+            body: undefined,
+        };
+
+        <% for (const statusCode of allStatusCodes) { %>
+            if (response.statusCode === <%= statusCode.statusCode %>) {
+            <%
+            for (const response of [...ownResponses, ...sharedResponses]) {
+            if (response.statusCode === statusCode.statusCode) {
+            %>
+                const is<%= response.name %>Response = this.validate<%= response.name %>Response(response, validatedResponse, error);
+                if (is<%= response.name %>Response) {
+                    return { validResponseName: "<%= response.name %>", validatedResponse };
+                }
+            <% } } %>
+            }
+
+        <% } %>
+
+        return {};
+    }
+
+    <% for (const response of [...ownResponses, ...sharedResponses]) { %>
+    private validate<%= response.name %>Response(response: IHttpResponse, validatedResponse: IHttpResponse, error: ResponseValidationError): boolean {
+        let isValid = true;
+
+        <% if(response.hasBody) { %>
+            assert(
+                definition.responses[<%= response.index %>] 
+                && "body" in definition.responses[<%= response.index %>] 
+                && definition.responses[<%= response.index %>].body,
+                "'<%= response.name %>ResponseBody' has to be defined in the definition"
+            );
+            const validateBodyResult = definition.responses[<%= response.index %>].body.safeParse(response.body);
+
+            if (!validateBodyResult.success) {
+                error.addBodyIssues(validateBodyResult.error.issues);
+                isValid = false;
+            } else {
+                validatedResponse.body = validateBodyResult.data;
+            }
+        <% } %>
+
+        <% if(response.hasHeader) { %>
+            assert(
+                definition.responses[<%= response.index %>] 
+                && "header" in definition.responses[<%= response.index %>] 
+                && definition.responses[<%= response.index %>].header,
+                "'<%= response.name %>ResponseHeader' has to be defined in the definition"
+            );
+            const validateHeaderResult = definition.responses[<%= response.index %>].header.safeParse(response.header);
+
+            if (!validateHeaderResult.success) {
+                error.addHeaderIssues(validateHeaderResult.error.issues);
+                isValid = false;
+            } else {
+                validatedResponse.header = validateHeaderResult.data;
+            }
+        <% } %>
+
+        return isValid;
+    }
+    <% } %>
+}

package/dist/templates/SharedResponse.ejs

@@ -0,0 +1,38 @@
+import { HttpResponse, HttpStatusCode } from "<%= coreDir %>";
+
+<% if (headerTsType) { %>
+    export type I<%= pascalCaseName %>ResponseHeader = <%- headerTsType %>;
+<% } %>
+
+<% if (bodyTsType) { %>
+    export type I<%= pascalCaseName %>ResponseBody = <%- bodyTsType %>;
+<% } %>
+
+export type I<%= pascalCaseName %>Response = {
+statusCode: HttpStatusCode.<%= httpStatusCode[sharedResponse.statusCode] %>
+<%= sharedResponse.header ? `header: I${pascalCaseName}ResponseHeader;` : "" %>
+<%= sharedResponse.body ? `body: I${pascalCaseName}ResponseBody;` : "" %>
+};
+
+export class <%= pascalCaseName %>Response extends HttpResponse<
+<%= sharedResponse.header ? `I${pascalCaseName}ResponseHeader` : 'undefined' %>,
+<%= sharedResponse.body ? `I${pascalCaseName}ResponseBody` : 'undefined' %>
+> implements I<%= pascalCaseName %>Response {
+public override readonly statusCode: HttpStatusCode.<%= httpStatusCode[sharedResponse.statusCode] %>;
+
+public constructor(response: I<%= pascalCaseName %>Response) {
+    super(
+        response.statusCode,
+        <%= sharedResponse.header ? `response.header` : 'undefined' %>,
+        <%= sharedResponse.body ? `response.body` : 'undefined' %>,
+    );
+
+    if (response.statusCode !== HttpStatusCode.<%= httpStatusCode[sharedResponse.statusCode] %>) {
+        throw new Error(`Invalid status code: '${response.statusCode}' for <%= pascalCaseName %>Response`);
+    }
+
+    this.statusCode = response.statusCode;
+}
+}
+
+

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@rexeus/typeweaver-types",
+  "version": "0.0.1",
+  "description": "TypeScript type and Zod validator generators for TypeWeaver APIs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [
+    "api",
+    "spec",
+    "definition",
+    "typescript",
+    "zod",
+    "generator",
+    "typeweaver"
+  ],
+  "author": "Dennis Wentzien <dw@rexeus.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rexeus/typeweaver.git",
+    "directory": "packages/types"
+  },
+  "bugs": {
+    "url": "https://github.com/rexeus/typeweaver/issues"
+  },
+  "homepage": "https://github.com/rexeus/typeweaver#readme",
+  "peerDependencies": {
+    "@rexeus/typeweaver-core": "*",
+    "@rexeus/typeweaver-gen": "*"
+  },
+  "devDependencies": {
+    "@rexeus/typeweaver-core": "0.0.1",
+    "@rexeus/typeweaver-gen": "0.0.1"
+  },
+  "dependencies": {
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "build": "pkgroll --clean-dist && cp -r ./src/templates ./dist/templates && cp -r ./src/lib ./dist/lib",
+    "preversion": "npm run build"
+  }
+}