zenko 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/RawToast/zenko/actions/workflows/ci.yml/badge.svg)](https://github.com/RawToast/zenko/actions/workflows/ci.yml)
 
-A TypeScript generator for OpenAPI specifications that creates **Zod schemas**, **type-safe path functions**, and **operation objects**.
+A work in progress TypeScript generator for OpenAPI specifications that creates **Zod schemas**, **type-safe path functions**, and **operation objects**.
 
 Unlike most OpenAPI generators, Zenko does not create a client. Instead you are free to use your own fetch wrapper or library of choice.
 
@@ -11,6 +11,7 @@ Unlike most OpenAPI generators, Zenko does not create a client. Instead you are
 - 🔧 **Zod Schema Generation** - Generates runtime-validated Zod schemas from OpenAPI schemas
 - 🛣️ **Type-safe Path Functions** - Creates functions to build API paths with proper TypeScript types
 - 📋 **Operation Objects** - Generates objects containing path functions, request validation, and response types
+- 🧰 **Operation Type Helpers** - Import `PathFn`, `HeaderFn`, `OperationDefinition`, and `OperationErrors` to power reusable clients
 - 🔄 **Dependency Resolution** - Automatically resolves schema dependencies with topological sorting
 - ⚡ **CLI & Programmatic API** - Use via command line or import as a library
 
@@ -66,10 +67,14 @@ bunx zenko input.yaml output.ts
 
 ### Config File
 
-The config file is a JSON file that contains an array of schema objects. Each schema object contains the input and output files, and the strict dates and numeric options.
+The config file controls generation for multiple specs and can also configure type helper emission.
 
 ```json
 {
+  "types": {
+    "emit": true,
+    "helpers": "package"
+  },
   "schemas": [
     {
       "input": "my-api.yaml",
@@ -79,12 +84,22 @@ The config file is a JSON file that contains an array of schema objects. Each sc
       "input": "my-strict-api.yaml",
       "output": "my-strict-api.gen.ts",
       "strictDates": true,
-      "strictNumeric": true
+      "strictNumeric": true,
+      "types": {
+        "helpers": "inline"
+      }
     }
   ]
 }
 ```
 
+#### Type Helper Modes
+
+- `helpers: "package"` (default) imports helpers from `zenko`
+- `helpers: "inline"` writes the helper definitions into each generated file
+- `helpers: "file"` imports from a custom module (`helpersOutput` path)
+- `emit: false` disables per-operation type aliases entirely
+
 ### Programmatic Usage
 
 ```typescript
@@ -157,7 +172,7 @@ export const paths = {
 } as const
 ```
 
-### 3. Operation Objects
+### 3. Operation Objects & Types
 
 ```typescript
 // Operation Objects
@@ -171,12 +186,28 @@ export const getUserById = {
   path: paths.getUserById,
   response: UserResponse,
 } as const
+
+// Operation Types
+import type { OperationDefinition, OperationErrors } from "zenko"
+
+export type AuthenticateUserOperation = OperationDefinition<
+  typeof paths.authenticateUser,
+  typeof AuthenticateRequest,
+  typeof AuthenticateResponse,
+  undefined,
+  OperationErrors
+>
 ```
 
 ## Example Usage in Your App
 
 ```typescript
-import { paths, authenticateUser, AuthenticateRequest } from "./generated-types"
+import {
+  paths,
+  authenticateUser,
+  type AuthenticateUserOperation,
+  AuthenticateRequest,
+} from "./generated-types"
 
 // Type-safe path building
 const userPath = paths.getUserById({ userId: "123" })
@@ -201,6 +232,30 @@ if (validation.success) {
 }
 ```
 
+### Building a Generic Client
+
+```typescript
+import type { OperationDefinition } from "zenko"
+
+async function runOperation<
+  T extends OperationDefinition<PathFn<any[]>, any, any>,
+>(
+  operation: T,
+  config: { baseUrl: string; init?: RequestInit }
+): Promise<
+  T["response"] extends undefined
+    ? void
+    : T["response"] extends (...args: any[]) => infer U
+      ? U
+      : T["response"]
+> {
+  const url = `${config.baseUrl}${operation.path()}`
+  const res = await fetch(url, config.init)
+  if (!res.ok) throw new Error(`Request failed: ${res.status}`)
+  return (await res.json()) as any
+}
+```
+
 ## Key Improvements
 
 ### Dependency Resolution
@@ -234,10 +289,3 @@ zenko src/resources/petstore.yaml output.ts
 # Format code
 bun run format
 ```
-
-## Architecture
-
-- **`src/zenko.ts`** - Main OpenAPI → TypeScript generator
-- **`src/cli.ts`** - Command-line interface
-- **`dist/`** - Bundled outputs (CJS + ESM)
-- **Topological Sort** - Ensures proper dependency ordering for schema generation

package/dist/cli.cjs

@@ -237,11 +237,13 @@ function generate(spec, options = {}) {
   const output = [];
   const generatedTypes = /* @__PURE__ */ new Set();
   const { strictDates = false, strictNumeric = false } = options;
+  const typesConfig = normalizeTypesConfig(options.types);
   const schemaOptions = {
     strictDates,
     strictNumeric
   };
   output.push('import { z } from "zod";');
+  appendHelperTypesImport(output, typesConfig);
   output.push("");
   if (spec.components?.schemas) {
     output.push("// Generated Zod Schemas");
@@ -261,16 +263,79 @@ function generate(spec, options = {}) {
   output.push("// Path Functions");
   output.push("export const paths = {");
   for (const op of operations) {
-    if (op.pathParams.length === 0) {
+    const pathParamNames = op.pathParams.map((p) => p.name);
+    const hasPathParams = pathParamNames.length > 0;
+    const hasQueryParams = op.queryParams.length > 0;
+    if (!hasPathParams && !hasQueryParams) {
       output.push(`  ${op.operationId}: () => "${op.path}",`);
-    } else {
-      const paramNames = op.pathParams.map((p) => p.name).join(", ");
-      const paramTypes = op.pathParams.map((p) => `${p.name}: string`).join(", ");
-      const pathWithParams = op.path.replace(/{([^}]+)}/g, "${$1}");
+      continue;
+    }
+    const allParamNames = [
+      ...pathParamNames,
+      ...op.queryParams.map((p) => p.name)
+    ];
+    const signaturePieces = [];
+    for (const param of op.pathParams) {
+      signaturePieces.push(`${param.name}: string`);
+    }
+    for (const param of op.queryParams) {
+      signaturePieces.push(
+        `${param.name}${param.required ? "" : "?"}: ${mapQueryType(param)}`
+      );
+    }
+    const signatureParams = signaturePieces.join(", ");
+    const needsDefaultObject = !hasPathParams && hasQueryParams && op.queryParams.every((param) => !param.required);
+    const signatureArgs = allParamNames.length ? `{ ${allParamNames.join(", ")} }` : "{}";
+    const signature = `${signatureArgs}: { ${signatureParams} }${needsDefaultObject ? " = {}" : ""}`;
+    const pathWithParams = op.path.replace(/{([^}]+)}/g, "${$1}");
+    if (!hasQueryParams) {
       output.push(
-        `  ${op.operationId}: ({ ${paramNames} }: { ${paramTypes} }) => \`${pathWithParams}\`,`
+        `  ${op.operationId}: (${signature}) => \`${pathWithParams}\`,`
       );
+      continue;
+    }
+    output.push(`  ${op.operationId}: (${signature}) => {`);
+    output.push("    const params = new URLSearchParams()");
+    for (const param of op.queryParams) {
+      const propertyKey = formatPropertyName(param.name);
+      const accessor = isValidJSIdentifier(param.name) ? param.name : propertyKey;
+      const schema = param.schema ?? {};
+      if (schema?.type === "array") {
+        const itemValueExpression = convertQueryParamValue(
+          schema.items ?? {},
+          "value"
+        );
+        if (param.required) {
+          output.push(`    for (const value of ${accessor}) {`);
+          output.push(
+            `      params.append("${param.name}", ${itemValueExpression})`
+          );
+          output.push("    }");
+        } else {
+          output.push(`    if (${accessor} !== undefined) {`);
+          output.push(`      for (const value of ${accessor}) {`);
+          output.push(
+            `        params.append("${param.name}", ${itemValueExpression})`
+          );
+          output.push("      }");
+          output.push("    }");
+        }
+        continue;
+      }
+      const valueExpression = convertQueryParamValue(schema, accessor);
+      if (param.required) {
+        output.push(`    params.set("${param.name}", ${valueExpression})`);
+      } else {
+        output.push(`    if (${accessor} !== undefined) {`);
+        output.push(`      params.set("${param.name}", ${valueExpression})`);
+        output.push("    }");
+      }
     }
+    output.push("    const _searchParams = params.toString()");
+    output.push(
+      `    return \`${pathWithParams}\${_searchParams ? \`?\${_searchParams}\` : ""}\``
+    );
+    output.push("  },");
   }
   output.push("} as const;");
   output.push("");
@@ -362,6 +427,7 @@ function generate(spec, options = {}) {
     output.push("} as const;");
     output.push("");
   }
+  generateOperationTypes(output, operations, typesConfig);
   return output.join("\n");
 }
 function appendOperationField(buffer, key, value) {
@@ -397,11 +463,13 @@ function parseOperations(spec) {
       );
       const resolvedParameters = collectParameters(pathItem, operation, spec);
       const requestHeaders = getRequestHeaders(resolvedParameters);
+      const queryParams = getQueryParams(resolvedParameters);
       operations.push({
         operationId: operation.operationId,
         path: path2,
         method: method.toLowerCase(),
         pathParams,
+        queryParams,
         requestType,
         responseType: successResponse,
         requestHeaders,
@@ -411,6 +479,91 @@ function parseOperations(spec) {
   }
   return operations;
 }
+function normalizeTypesConfig(config) {
+  return {
+    emit: config?.emit ?? true,
+    helpers: config?.helpers ?? "package",
+    helpersOutput: config?.helpersOutput ?? "./zenko-types"
+  };
+}
+function appendHelperTypesImport(buffer, config) {
+  if (!config.emit) return;
+  switch (config.helpers) {
+    case "package":
+      buffer.push(
+        'import type { PathFn, HeaderFn, OperationDefinition, OperationErrors } from "zenko";'
+      );
+      return;
+    case "file":
+      buffer.push(
+        `import type { PathFn, HeaderFn, OperationDefinition, OperationErrors } from "${config.helpersOutput}";`
+      );
+      return;
+    case "inline":
+      buffer.push(
+        "type PathFn<TArgs extends unknown[] = []> = (...args: TArgs) => string;"
+      );
+      buffer.push(
+        "type HeaderFn<TArgs extends unknown[] = [], TResult = Record<string, unknown> | Record<string, never>> = (...args: TArgs) => TResult;"
+      );
+      buffer.push(
+        "type OperationErrors<TClient = unknown, TServer = unknown, TDefault = unknown, TOther = unknown> = {"
+      );
+      buffer.push("  clientErrors?: Record<string, TClient>;");
+      buffer.push("  serverErrors?: Record<string, TServer>;");
+      buffer.push("  defaultErrors?: Record<string, TDefault>;");
+      buffer.push("  otherErrors?: Record<string, TOther>;");
+      buffer.push("};");
+      buffer.push(
+        "type OperationDefinition<TPath extends (...args: any[]) => string, TRequest = undefined, TResponse = undefined, THeaders extends HeaderFn | undefined = undefined, TErrors extends OperationErrors | undefined = undefined> = {"
+      );
+      buffer.push("  path: TPath;");
+      buffer.push("  request?: TRequest;");
+      buffer.push("  response?: TResponse;");
+      buffer.push("  headers?: THeaders;");
+      buffer.push("  errors?: TErrors;");
+      buffer.push("};");
+      return;
+  }
+}
+function generateOperationTypes(buffer, operations, config) {
+  if (!config.emit) return;
+  buffer.push("// Operation Types");
+  for (const op of operations) {
+    const headerType = op.requestHeaders?.length ? `typeof headers.${op.operationId}` : "undefined";
+    const requestType = op.requestType ?? "undefined";
+    const responseType = op.responseType ?? "undefined";
+    const errorsType = buildOperationErrorsType(op.errors);
+    buffer.push(
+      `export type ${capitalize(op.operationId)}Operation = OperationDefinition<`
+    );
+    buffer.push(`  typeof paths.${op.operationId},`);
+    buffer.push(`  ${requestType},`);
+    buffer.push(`  ${responseType},`);
+    buffer.push(`  ${headerType},`);
+    buffer.push(`  ${errorsType}`);
+    buffer.push(`>;`);
+    buffer.push("");
+  }
+}
+function buildOperationErrorsType(errors) {
+  if (!errors || !hasAnyErrors(errors)) {
+    return "OperationErrors";
+  }
+  const client = buildErrorBucket(errors.clientErrors);
+  const server = buildErrorBucket(errors.serverErrors);
+  const fallback = buildErrorBucket(errors.defaultErrors);
+  const other = buildErrorBucket(errors.otherErrors);
+  return `OperationErrors<${client}, ${server}, ${fallback}, ${other}>`;
+}
+function buildErrorBucket(bucket) {
+  if (!bucket || Object.keys(bucket).length === 0) {
+    return "unknown";
+  }
+  const entries = Object.entries(bucket);
+  const typeEntries = entries.map(([name, type]) => `${formatPropertyName(name)}: ${type}`).join("; ");
+  return `{ ${typeEntries} }`;
+}
 function collectParameters(pathItem, operation, spec) {
   const parametersMap = /* @__PURE__ */ new Map();
   const addParameters = (params) => {
@@ -553,6 +706,20 @@ function getRequestHeaders(parameters) {
   }
   return headers;
 }
+function getQueryParams(parameters) {
+  const queryParams = [];
+  for (const param of parameters ?? []) {
+    if (param.in === "query") {
+      queryParams.push({
+        name: param.name,
+        description: param.description,
+        schema: param.schema,
+        required: param.required
+      });
+    }
+  }
+  return queryParams;
+}
 function mapHeaderType(header) {
   const schemaType = header.schema?.type;
   switch (schemaType) {
@@ -565,6 +732,39 @@ function mapHeaderType(header) {
       return "string";
   }
 }
+function mapQueryType(param) {
+  return mapQuerySchemaType(param.schema);
+}
+function mapQuerySchemaType(schema) {
+  if (!schema) return "string";
+  if (schema.type === "array") {
+    const itemType = mapQuerySchemaType(schema.items);
+    return `Array<${itemType}>`;
+  }
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    default:
+      return "string";
+  }
+}
+function convertQueryParamValue(schema, accessor) {
+  if (!schema) {
+    return `String(${accessor})`;
+  }
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return `String(${accessor})`;
+    case "boolean":
+      return `${accessor} ? "true" : "false"`;
+    default:
+      return `String(${accessor})`;
+  }
+}
 function generateZodSchema(name, schema, generatedTypes, options) {
   if (generatedTypes.has(name)) return "";
   generatedTypes.add(name);
@@ -573,18 +773,7 @@ function generateZodSchema(name, schema, generatedTypes, options) {
     return `export const ${name} = z.enum([${enumValues}]);`;
   }
   if (schema.type === "object" || schema.properties) {
-    const properties = [];
-    for (const [propName, propSchema] of Object.entries(
-      schema.properties || {}
-    )) {
-      const isRequired = schema.required?.includes(propName) ?? false;
-      const zodType = getZodTypeFromSchema(propSchema, options);
-      const finalType = isRequired ? zodType : `${zodType}.optional()`;
-      properties.push(`  ${formatPropertyName(propName)}: ${finalType},`);
-    }
-    return `export const ${name} = z.object({
-${properties.join("\n")}
-});`;
+    return `export const ${name} = ${buildZodObject(schema, options)};`;
   }
   if (schema.type === "array") {
     const itemSchema = schema.items ?? { type: "unknown" };
@@ -607,6 +796,9 @@ function getZodTypeFromSchema(schema, options) {
     const enumValues = schema.enum.map((v) => `"${v}"`).join(", ");
     return `z.enum([${enumValues}])`;
   }
+  if (schema.type === "object" || schema.properties) {
+    return buildZodObject(schema, options);
+  }
   switch (schema.type) {
     case "string":
       return buildString(schema, options);
@@ -627,6 +819,23 @@ function getZodTypeFromSchema(schema, options) {
       return "z.unknown()";
   }
 }
+function buildZodObject(schema, options) {
+  const properties = [];
+  for (const [propName, propSchema] of Object.entries(
+    schema.properties || {}
+  )) {
+    const isRequired = schema.required?.includes(propName) ?? false;
+    const zodType = getZodTypeFromSchema(propSchema, options);
+    const finalType = isRequired ? zodType : `${zodType}.optional()`;
+    properties.push(`  ${formatPropertyName(propName)}: ${finalType},`);
+  }
+  if (properties.length === 0) {
+    return "z.object({})";
+  }
+  return `z.object({
+${properties.join("\n")}
+})`;
+}
 function buildString(schema, options) {
   if (options.strictDates) {
     switch (schema.format) {
@@ -817,7 +1026,7 @@ function printHelp() {
   console.log("");
   console.log("Config file format:");
   console.log(
-    '  {"schemas": [{ input, output, strictDates?, strictNumeric? }] }'
+    '  {"types"?: { emit?, helpers?, helpersOutput? }, "schemas": [{ input, output, strictDates?, strictNumeric?, types? }] }'
   );
 }
 async function runFromConfig(parsed) {
@@ -826,14 +1035,17 @@ async function runFromConfig(parsed) {
   const config = await loadConfig(resolvedConfigPath);
   validateConfig(config);
   const baseDir = path.dirname(resolvedConfigPath);
+  const baseTypesConfig = config.types;
   for (const entry of config.schemas) {
     const inputFile = resolvePath(entry.input, baseDir);
     const outputFile = resolvePath(entry.output, baseDir);
+    const typesConfig = resolveTypesConfig(baseTypesConfig, entry.types);
     await generateSingle({
       inputFile,
       outputFile,
       strictDates: entry.strictDates ?? parsed.strictDates,
-      strictNumeric: entry.strictNumeric ?? parsed.strictNumeric
+      strictNumeric: entry.strictNumeric ?? parsed.strictNumeric,
+      typesConfig
     });
   }
 }
@@ -870,12 +1082,23 @@ function validateConfig(config) {
 function resolvePath(filePath, baseDir) {
   return path.isAbsolute(filePath) ? filePath : path.join(baseDir, filePath);
 }
+function resolveTypesConfig(baseConfig, entryConfig) {
+  if (!baseConfig && !entryConfig) return void 0;
+  return {
+    ...baseConfig,
+    ...entryConfig
+  };
+}
 async function generateSingle(options) {
-  const { inputFile, outputFile, strictDates, strictNumeric } = options;
+  const { inputFile, outputFile, strictDates, strictNumeric, typesConfig } = options;
   const resolvedInput = path.resolve(inputFile);
   const resolvedOutput = path.resolve(outputFile);
   const spec = readSpec(resolvedInput);
-  const output = generate(spec, { strictDates, strictNumeric });
+  const output = generate(spec, {
+    strictDates,
+    strictNumeric,
+    types: typesConfig
+  });
   fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
   fs.writeFileSync(resolvedOutput, output);
   console.log(`\u2705 Generated TypeScript types in ${resolvedOutput}`);