openapi-remote-codegen 0.1.0

package/src/parser.ts

@@ -0,0 +1,303 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { OperationInfo, InlineRequestBody, ParsedSpec, ParameterInfo, RemoteType } from './types.js';
+
+// Extended operation type to include our custom extensions
+type OperationWithExtensions = OpenAPIV3.OperationObject & {
+  'x-remote-type'?: RemoteType;
+  'x-remote-invalidates'?: string[];
+  'x-client-property'?: string;
+  'x-remote-batch'?: boolean;
+};
+
+export function parseOpenApiSpec(spec: OpenAPIV3.Document): ParsedSpec {
+  const operations: OperationInfo[] = [];
+  const tagsSet = new Set<string>();
+
+  for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+    if (!pathItem) continue;
+
+    const methods = ['get', 'post', 'put', 'patch', 'delete'] as const;
+
+    for (const method of methods) {
+      const operation = pathItem[method] as OperationWithExtensions | undefined;
+      if (!operation) continue;
+
+      const remoteType = operation['x-remote-type'];
+      if (!remoteType) continue;
+
+      const tag = operation.tags?.[0] ?? 'Default';
+      tagsSet.add(tag);
+
+      const invalidates = operation['x-remote-invalidates'] ?? [];
+
+      const parameters = parseParameters(
+        operation.parameters ?? [],
+        pathItem.parameters ?? [],
+        spec.components
+      );
+      const requestBodyResult = parseRequestBody(operation.requestBody as OpenAPIV3.RequestBodyObject | undefined);
+      const requestBodySchema = requestBodyResult?.schema;
+      const isArrayBody = requestBodyResult?.isArray ?? false;
+
+      // Check success response codes in priority order (200, 201, 202)
+      const responseSchema =
+        parseResponse(operation.responses?.['200'] as OpenAPIV3.ResponseObject | undefined) ??
+        parseResponse(operation.responses?.['201'] as OpenAPIV3.ResponseObject | undefined) ??
+        parseResponse(operation.responses?.['202'] as OpenAPIV3.ResponseObject | undefined);
+
+      // Detect void response: commands with no JSON response body (204 No Content, or 200 with no body)
+      const isVoidResponse = !responseSchema && (remoteType === 'command' || remoteType === 'form');
+      const isBatch = remoteType === 'query' && (operation['x-remote-batch'] === true);
+
+      operations.push({
+        operationId: operation.operationId ?? `${method}_${path}`,
+        tag,
+        method,
+        path,
+        remoteType,
+        invalidates,
+        parameters,
+        requestBodySchema,
+        requestBodyRequired: requestBodyResult?.required,
+        isArrayBody,
+        inlineRequestBody: requestBodyResult?.inline,
+        responseSchema,
+        isVoidResponse,
+        isBatch,
+        summary: operation.summary,
+        clientPropertyName: operation['x-client-property'],
+      });
+    }
+  }
+
+  return {
+    operations,
+    tags: Array.from(tagsSet),
+  };
+}
+
+function parseParameters(
+  opParams: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[],
+  pathParams: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[],
+  components?: OpenAPIV3.ComponentsObject
+): ParameterInfo[] {
+  const allParams = [...pathParams, ...opParams];
+  const result: ParameterInfo[] = [];
+
+  for (const param of allParams) {
+    if ('$ref' in param) continue;
+
+    const schema = param.schema as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined;
+    const resolved = resolveSchema(schema, components);
+
+    const paramInfo: ParameterInfo = {
+      name: param.name,
+      in: param.in as 'query' | 'path' | 'header',
+      required: param.required ?? false,
+      type: getSchemaType(resolved),
+    };
+
+    // Check if the resolved schema is an enum
+    if (resolved?.enum) {
+      const enumName = findEnumName(schema, components);
+      if (enumName) {
+        paramInfo.enumName = enumName;
+      }
+    }
+
+    // For array parameters, capture the item type
+    if (resolved?.type === 'array' && resolved.items) {
+      const itemSchema = resolveSchema(
+        resolved.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+        components
+      );
+      paramInfo.itemType = getSchemaType(itemSchema);
+    }
+
+    result.push(paramInfo);
+  }
+
+  return result;
+}
+
+/**
+ * Resolve a schema through $ref and oneOf to get the underlying schema object.
+ */
+function resolveSchema(
+  schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+  components?: OpenAPIV3.ComponentsObject
+): OpenAPIV3.SchemaObject | undefined {
+  if (!schema) return undefined;
+
+  if ('$ref' in schema) {
+    const refName = schema.$ref.split('/').pop();
+    if (refName && components?.schemas?.[refName]) {
+      return components.schemas[refName] as OpenAPIV3.SchemaObject;
+    }
+    return undefined;
+  }
+
+  // Handle oneOf wrapping (NSwag nullable enums)
+  const schemaObj = schema as OpenAPIV3.SchemaObject;
+  if (schemaObj.oneOf) {
+    for (const item of schemaObj.oneOf) {
+      const resolved = resolveSchema(
+        item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+        components
+      );
+      if (resolved?.type || resolved?.enum) return resolved;
+    }
+  }
+
+  return schemaObj;
+}
+
+/**
+ * Find the enum type name from a schema that may be wrapped in oneOf/$ref.
+ */
+function findEnumName(
+  schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+  components?: OpenAPIV3.ComponentsObject
+): string | undefined {
+  if (!schema) return undefined;
+
+  if ('$ref' in schema) {
+    const refName = schema.$ref.split('/').pop();
+    if (refName && components?.schemas?.[refName]) {
+      const resolved = components.schemas[refName] as OpenAPIV3.SchemaObject;
+      if (resolved.enum) return refName;
+    }
+    return undefined;
+  }
+
+  const schemaObj = schema as OpenAPIV3.SchemaObject;
+  if (schemaObj.oneOf) {
+    for (const item of schemaObj.oneOf) {
+      const name = findEnumName(
+        item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+        components
+      );
+      if (name) return name;
+    }
+  }
+
+  return undefined;
+}
+
+interface RequestBodyParseResult {
+  schema: string;
+  isArray: boolean;
+  required: boolean;
+  inline?: InlineRequestBody;
+}
+
+function parseRequestBody(body: OpenAPIV3.RequestBodyObject | undefined): RequestBodyParseResult | undefined {
+  if (!body?.content?.['application/json']?.schema) return undefined;
+
+  const required = body.required ?? false;
+  const schema = body.content['application/json'].schema;
+  if ('$ref' in schema) {
+    const refName = schema.$ref.split('/').pop();
+    return refName ? { schema: `${refName}Schema`, isArray: false, required } : undefined;
+  }
+
+  // Handle array request bodies (e.g., Treatment[])
+  const schemaObj = schema as OpenAPIV3.SchemaObject;
+  if (schemaObj.type === 'array' && schemaObj.items) {
+    const items = schemaObj.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+    if ('$ref' in items) {
+      const itemName = items.$ref.split('/').pop();
+      return itemName ? { schema: `${itemName}Schema`, isArray: true, required } : undefined;
+    }
+  }
+
+  // Handle inline object schemas (e.g., Dictionary<string, string> -> { type: "object", additionalProperties: ... })
+  if (schemaObj.type === 'object' && schemaObj.additionalProperties) {
+    const inline = resolveInlineObjectSchema(schemaObj);
+    if (inline) {
+      return { schema: '', isArray: false, required, inline };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Convert an inline OpenAPI object schema with additionalProperties to a Zod schema and TS type.
+ * Handles Dictionary<TKey, TValue> patterns from C#.
+ */
+function resolveInlineObjectSchema(schema: OpenAPIV3.SchemaObject): InlineRequestBody | undefined {
+  const additionalProps = schema.additionalProperties;
+  if (!additionalProps || additionalProps === true) {
+    // additionalProperties: true or {} -> Record<string, unknown>
+    return {
+      zodSchema: 'z.record(z.string(), z.unknown())',
+      tsType: '{ [key: string]: any; }',
+    };
+  }
+
+  if (typeof additionalProps === 'object' && !('$ref' in additionalProps)) {
+    const valueSchema = additionalProps as OpenAPIV3.SchemaObject;
+    switch (valueSchema.type) {
+      case 'string':
+        return {
+          zodSchema: 'z.record(z.string(), z.string())',
+          tsType: '{ [key: string]: string; }',
+        };
+      case 'number':
+      case 'integer':
+        return {
+          zodSchema: 'z.record(z.string(), z.number())',
+          tsType: '{ [key: string]: number; }',
+        };
+      case 'boolean':
+        return {
+          zodSchema: 'z.record(z.string(), z.boolean())',
+          tsType: '{ [key: string]: boolean; }',
+        };
+      default:
+        return {
+          zodSchema: 'z.record(z.string(), z.unknown())',
+          tsType: '{ [key: string]: any; }',
+        };
+    }
+  }
+
+  return undefined;
+}
+
+function parseResponse(response: OpenAPIV3.ResponseObject | undefined): string | undefined {
+  if (!response?.content?.['application/json']?.schema) return undefined;
+
+  const schema = response.content['application/json'].schema;
+  if ('$ref' in schema) {
+    return schema.$ref.split('/').pop();
+  }
+
+  // Handle array responses (e.g., TrackerDefinitionDto[])
+  const schemaObj = schema as OpenAPIV3.SchemaObject;
+  if (schemaObj.type === 'array' && schemaObj.items) {
+    const items = schemaObj.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+    if ('$ref' in items) {
+      const itemName = items.$ref.split('/').pop();
+      return itemName ? `${itemName}[]` : undefined;
+    }
+  }
+
+  return undefined;
+}
+
+function getSchemaType(schema: OpenAPIV3.SchemaObject | undefined): string {
+  if (!schema) return 'unknown';
+
+  if (schema.type === 'string') {
+    if (schema.format === 'uuid') return 'string';
+    if (schema.format === 'date-time') return 'Date';
+    return 'string';
+  }
+  if (schema.type === 'integer' || schema.type === 'number') return 'number';
+  if (schema.type === 'boolean') return 'boolean';
+  if (schema.type === 'array') return 'array';
+
+  return 'unknown';
+}

package/src/public.ts

@@ -0,0 +1,7 @@
+// Public API for openapi-remote-codegen
+export { defineConfig, resolveConfig } from './config.js';
+export type { GeneratorConfig, UserConfig, ImportPaths, ErrorHandling } from './config.js';
+export { parseOpenApiSpec } from './parser.js';
+export type { ParsedSpec, OperationInfo, ParameterInfo, RemoteType, InlineRequestBody } from './types.js';
+export { generateRemoteFunctions } from './generators/remote-functions.js';
+export { generateApiClient } from './generators/api-client.js';

package/src/types.ts

@@ -0,0 +1,48 @@
+export type RemoteType = 'query' | 'command' | 'form';
+
+export interface ParameterInfo {
+  name: string;
+  in: 'query' | 'path' | 'header';
+  required: boolean;
+  type: string;
+  enumName?: string;
+  /** For array-type parameters, the type of each item (e.g., 'string', 'number') */
+  itemType?: string;
+}
+
+/**
+ * Represents an inline request body that doesn't have a named $ref schema.
+ * Used for types like Dictionary<string, string> which become { type: "object", additionalProperties: ... }.
+ */
+export interface InlineRequestBody {
+  /** Zod schema expression (e.g., "z.record(z.string(), z.string())") */
+  zodSchema: string;
+  /** TypeScript type for the NSwag client cast (e.g., "{ [key: string]: string; }") */
+  tsType: string;
+}
+
+export interface OperationInfo {
+  operationId: string;
+  tag: string;
+  method: string;
+  path: string;
+  remoteType: RemoteType;
+  invalidates: string[];
+  parameters: ParameterInfo[];
+  requestBodySchema?: string;
+  requestBodyRequired?: boolean;
+  isArrayBody?: boolean;
+  /** Inline request body for schemas that don't have a named $ref (e.g., Dictionary<string, string>) */
+  inlineRequestBody?: InlineRequestBody;
+  responseSchema?: string;
+  isVoidResponse: boolean;
+  /** Whether this query should use query.batch() for N+1 prevention */
+  isBatch?: boolean;
+  summary?: string;
+  clientPropertyName?: string;
+}
+
+export interface ParsedSpec {
+  operations: OperationInfo[];
+  tags: string[];
+}

package/src/utils/client-mapping.ts

@@ -0,0 +1,9 @@
+/**
+ * Get the apiClient property name for an OpenAPI tag using camelCase fallback.
+ * Strips version prefixes (e.g., "V4 Trackers" -> "Trackers") and converts to camelCase.
+ * Used as fallback when no [ClientPropertyName] attribute is set on the controller.
+ */
+export function getClientPropertyName(tag: string): string {
+  const cleaned = tag.replace(/^V\d+\s*/i, '').replace(/\s+/g, '');
+  return cleaned.charAt(0).toLowerCase() + cleaned.slice(1);
+}

package/src/utils/naming.ts

@@ -0,0 +1,99 @@
+/**
+ * JavaScript reserved keywords that cannot be used as export names.
+ * Maps known API method names to safe alternatives.
+ */
+const RESERVED_KEYWORD_MAP: Record<string, string> = {
+  delete: 'remove',
+};
+
+const JS_RESERVED_KEYWORDS = new Set([
+  'delete', 'new', 'return', 'switch', 'throw', 'try', 'catch', 'finally',
+  'class', 'const', 'let', 'var', 'function', 'import', 'export', 'default',
+  'void', 'typeof', 'instanceof', 'in', 'of', 'if', 'else', 'for', 'while',
+  'do', 'break', 'continue', 'with', 'yield', 'await', 'async', 'super',
+  'this', 'null', 'undefined', 'true', 'false', 'enum', 'implements',
+  'interface', 'package', 'private', 'protected', 'public', 'static',
+]);
+
+/**
+ * Ensure a function name is not a JavaScript reserved keyword.
+ * Uses explicit mapping for common cases (delete -> remove),
+ * falls back to underscore prefix for others.
+ */
+function safeExportName(name: string): string {
+  if (!JS_RESERVED_KEYWORDS.has(name)) return name;
+  return RESERVED_KEYWORD_MAP[name] ?? `_${name}`;
+}
+
+/**
+ * Convert operationId to function name.
+ * "Note_GetNotes" -> "getNotes"
+ * "Note_CreateNote" -> "createNote"
+ * "ClockFaces_Delete" -> "remove" (reserved keyword handling)
+ */
+export function operationIdToFunctionName(operationId: string): string {
+  const parts = operationId.split('_');
+  const name = parts.length > 1 ? parts.slice(1).join('_') : parts[0];
+  const functionName = name.charAt(0).toLowerCase() + name.slice(1);
+  return safeExportName(functionName);
+}
+
+/**
+ * Pluralize a single word.
+ */
+function pluralize(word: string): string {
+  const lower = word.toLowerCase();
+  if (lower.endsWith('s')) return lower;
+  if (lower.endsWith('y') && !/[aeiou]y$/.test(lower)) {
+    return lower.slice(0, -1) + 'ies';
+  }
+  if (/(?:sh|ch|x|z)$/.test(lower)) {
+    return lower + 'es';
+  }
+  return lower + 's';
+}
+
+/**
+ * Convert tag to camelCase file name with proper pluralization.
+ * "Note" -> "notes"
+ * "V4 Notes" -> "notes"
+ * "V4 Compression Lows" -> "compressionLows"
+ * "V1 Connector Status" -> "connectorStatus"
+ * "Battery" -> "batteries"
+ */
+export function tagToFileName(tag: string): string {
+  const cleaned = tag.replace(/^V\d+\s*/i, '').trim();
+  const words = cleaned.split(/\s+/);
+
+  // Pluralize the last word
+  const lastWord = pluralize(words[words.length - 1]);
+  const prefix = words.slice(0, -1);
+
+  // Build camelCase: first word lowercase, rest capitalized
+  const parts = [...prefix.map(w => w.toLowerCase()), lastWord];
+  return parts[0] + parts.slice(1).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+
+/**
+ * Resolve invalidation targets.
+ * Short names resolve within same tag, full operationIds are used as-is.
+ * "GetNotes" with currentTag "Note" -> "getNotes"
+ * "Trackers_GetActiveInstances" -> "getActiveInstances" (from trackers)
+ */
+export function resolveInvalidation(
+  invalidate: string,
+  currentTag: string
+): { functionName: string; fromTag: string } {
+  if (invalidate.includes('_')) {
+    const [tag, ...rest] = invalidate.split('_');
+    return {
+      functionName: operationIdToFunctionName(invalidate),
+      fromTag: tag,
+    };
+  }
+
+  return {
+    functionName: invalidate.charAt(0).toLowerCase() + invalidate.slice(1),
+    fromTag: currentTag,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/__tests__"]
+}