refactor: ensure kebab-case names for generated models in for TS clients

Author: aorumbayev

api/oas_generator/ts_oas_generator/constants.py

@@ -198,6 +198,10 @@ class HttpMethod(StrEnum):
 DEFAULT_TAG: Final[str] = "default"
 DEFAULT_API_TAG: Final[str] = "api"
 
+
+# Vendor extensions
+X_ALGOKIT_FIELD_RENAME: Final[str] = "x-algokit-field-rename"
+
 # Backup directory prefix
 BACKUP_DIR_PREFIX: Final[str] = "tsgen_bak_"
 

api/oas_generator/ts_oas_generator/generator/filters.py

@@ -59,6 +59,11 @@ def ts_camel_case(name: str) -> str:
     return pas[:1].lower() + pas[1:] if pas else pas
 
 
+def ts_kebab_case(name: str) -> str:
+    parts = _split_words(name)
+    return "-".join(p.lower() for p in parts)
+
+
 def ts_property_name(name: str) -> str:
     """Return a safe TS property name, quoting if necessary."""
     return name if _IDENTIFIER_RE.match(name) else f"'{name}'"
@@ -108,6 +113,7 @@ def _inline_object(schema: dict[str, Any], schemas: dict[str, Any] | None) -> st
     parts: list[str] = []
 
     for prop_name, prop_schema in properties.items():
+        canonical_name = prop_schema.get(constants.X_ALGOKIT_FIELD_RENAME) or prop_name
         # Add property description as doc comment
         description = prop_schema.get("description")
         if description:
@@ -117,7 +123,7 @@ def _inline_object(schema: dict[str, Any], schemas: dict[str, Any] | None) -> st
             parts.append(f"\n  {indented_doc}")
 
         # Generate camelCase TS property names for better DX
-        ts_name = ts_camel_case(prop_name)
+        ts_name = ts_camel_case(canonical_name)
         ts_t = ts_type(prop_schema, schemas)
         opt = "" if prop_name in required else "?"
         parts.append(f"{ts_name}{opt}: {ts_t};")
@@ -313,6 +319,7 @@ def _traverse(obj: dict[str, Any]) -> None:  # noqa: C901
     "ts_type": ts_type,
     "ts_pascal_case": ts_pascal_case,
     "ts_camel_case": ts_camel_case,
+    "ts_kebab_case": ts_kebab_case,
     "ts_property_name": ts_property_name,
     "has_msgpack_2xx": has_msgpack_2xx,
     "response_content_types": response_content_types,

api/oas_generator/ts_oas_generator/generator/template_engine.py

@@ -9,7 +9,7 @@
 from jinja2 import Environment, FileSystemLoader, select_autoescape
 
 from ts_oas_generator import constants
-from ts_oas_generator.generator.filters import FILTERS, ts_camel_case, ts_pascal_case, ts_type
+from ts_oas_generator.generator.filters import FILTERS, ts_camel_case, ts_kebab_case, ts_pascal_case, ts_type
 from ts_oas_generator.parser.oas_parser import OASParser
 
 # Type aliases for clarity
@@ -120,7 +120,6 @@ def __init__(self, template_dir: Path | None = None) -> None:
         self.env = self._create_environment()
 
     def _create_environment(self) -> Environment:
-        """Create and configure Jinja2 environment."""
         env = Environment(
             loader=FileSystemLoader(str(self.template_dir)),
             autoescape=select_autoescape(["html", "xml"]),
@@ -131,12 +130,10 @@ def _create_environment(self) -> Environment:
         return env
 
     def render(self, template_name: str, context: TemplateContext) -> str:
-        """Render a single template."""
         template = self.env.get_template(template_name)
         return template.render(**context)
 
     def render_batch(self, template_map: dict[Path, tuple[str, TemplateContext]]) -> FileMap:
-        """Render multiple templates."""
         return {path: self.render(template, context) for path, (template, context) in template_map.items()}
 
 
@@ -145,25 +142,25 @@ class SchemaProcessor:
 
     def __init__(self, renderer: TemplateRenderer) -> None:
         self.renderer = renderer
+        self._wire_to_canonical: dict[str, str] = {}
+        self._camel_to_wire: dict[str, str] = {}
 
     def generate_models(self, output_dir: Path, schemas: Schema) -> FileMap:
-        """Generate TypeScript model files from schemas."""
         models_dir = output_dir / constants.DirectoryName.SRC / constants.DirectoryName.MODELS
         files: FileMap = {}
 
         # Generate individual model files
         for name, schema in schemas.items():
             context = self._create_model_context(name, schema, schemas)
             content = self.renderer.render(constants.MODEL_TEMPLATE, context)
-            files[models_dir / f"{name.lower()}{constants.MODEL_FILE_EXTENSION}"] = content
+            file_name = f"{ts_kebab_case(name)}{constants.MODEL_FILE_EXTENSION}"
+            files[models_dir / file_name] = content
 
-        # Generate comprehensive AlgokitSignedTransaction model
         # TODO(utils-ts): Delete this temporary model once utils-ts is part of the monorepo
         files[models_dir / f"algokitsignedtransaction{constants.MODEL_FILE_EXTENSION}"] = self.renderer.render(
             "models/algokitsignedtransaction.ts.j2", {}
         )
 
-        # Generate barrel export
         files[models_dir / constants.INDEX_FILE] = self.renderer.render(
             constants.MODELS_INDEX_TEMPLATE,
             {"schemas": schemas, "include_temp_signed_txn": True},
@@ -172,7 +169,6 @@ def generate_models(self, output_dir: Path, schemas: Schema) -> FileMap:
         return files
 
     def _create_model_context(self, name: str, schema: Schema, all_schemas: Schema) -> TemplateContext:
-        """Create context for model template rendering."""
         is_object = self._is_object_schema(schema)
         properties = self._extract_properties(schema) if is_object else []
 
@@ -188,21 +184,19 @@ def _create_model_context(self, name: str, schema: Schema, all_schemas: Schema)
 
     @staticmethod
     def _is_object_schema(schema: Schema) -> bool:
-        """Check if schema represents an object type."""
         is_type_object = schema.get(constants.SchemaKey.TYPE) == constants.TypeScriptType.OBJECT
         has_properties = constants.SchemaKey.PROPERTIES in schema
         has_composition = any(
             k in schema for k in [constants.SchemaKey.ALL_OF, constants.SchemaKey.ONE_OF, constants.SchemaKey.ANY_OF]
         )
         return (is_type_object or has_properties) and not has_composition
 
-    @staticmethod
-    def _extract_properties(schema: Schema) -> list[dict[str, Any]]:
-        """Extract properties from an object schema."""
+    def _extract_properties(self, schema: Schema) -> list[dict[str, Any]]:
         properties = []
         required_fields = set(schema.get(constants.SchemaKey.REQUIRED, []))
 
         for prop_name, prop_schema in (schema.get(constants.SchemaKey.PROPERTIES) or {}).items():
+            self._register_rename(prop_name, prop_schema)
             properties.append(
                 {
                     "name": prop_name,
@@ -213,6 +207,19 @@ def _extract_properties(schema: Schema) -> list[dict[str, Any]]:
 
         return properties
 
+    def _register_rename(self, wire_name: str, schema: dict[str, Any]) -> None:
+        rename_value = schema.get(constants.X_ALGOKIT_FIELD_RENAME)
+        if not isinstance(rename_value, str) or not rename_value:
+            return
+
+        # Preserve first occurrence to avoid accidental overrides from conflicting specs
+        self._wire_to_canonical.setdefault(wire_name, rename_value)
+        self._camel_to_wire.setdefault(ts_camel_case(rename_value), wire_name)
+
+    @property
+    def rename_mappings(self) -> tuple[dict[str, str], dict[str, str]]:
+        return self._wire_to_canonical, self._camel_to_wire
+
 
 class OperationProcessor:
     """Processes OpenAPI operations and generates API services."""
@@ -609,6 +616,7 @@ def generate(
         files.update(self.schema_processor.generate_models(output_dir, all_schemas))
         files.update(self.operation_processor.generate_service(output_dir, ops_by_tag, tags, service_class))
         files.update(self._generate_client_files(output_dir, client_class, service_class))
+        files.update(self._generate_rename_map(output_dir))
 
         return files
 
@@ -642,6 +650,7 @@ def _generate_runtime(
             core_dir / "json.ts": ("base/src/core/json.ts.j2", context),
             core_dir / "msgpack.ts": ("base/src/core/msgpack.ts.j2", context),
             core_dir / "casing.ts": ("base/src/core/casing.ts.j2", context),
+            core_dir / "codecs.ts": ("base/src/core/codecs.ts.j2", context),
             # Project files
             src_dir / "index.ts": ("base/src/index.ts.j2", context),
             output_dir / "package.json": ("base/package.json.j2", context),
@@ -669,6 +678,23 @@ def _generate_client_files(self, output_dir: Path, client_class: str, service_cl
 
         return self.renderer.render_batch(template_map)
 
+    def _generate_rename_map(self, output_dir: Path) -> FileMap:
+        """Render rename map supporting vendor rename extensions."""
+        wire_to_canonical, camel_to_wire = self.schema_processor.rename_mappings
+
+        core_dir = output_dir / constants.DirectoryName.SRC / constants.DirectoryName.CORE
+        return {
+            core_dir / "rename-map.ts": (
+                self.renderer.render(
+                    "base/src/core/rename-map.ts.j2",
+                    {
+                        "wire_to_canonical": wire_to_canonical,
+                        "camel_to_wire": camel_to_wire,
+                    },
+                )
+            )
+        }
+
     @staticmethod
     def _extract_class_names(package_name: str) -> tuple[str, str]:
         """Extract client and service class names from package name."""

api/oas_generator/ts_oas_generator/templates/base/src/core/casing.ts.j2

@@ -1,4 +1,8 @@
+import { CANONICAL_CAMEL_TO_WIRE, WIRE_TO_CANONICAL } from './rename-map';
+
 function toCamel(segmented: string): string {
+  const override = WIRE_TO_CANONICAL[segmented];
+  if (override) segmented = override;
   if (!segmented) return segmented;
   // Fast path: if no hyphen, return as-is but ensure typical camel conversion for underscores
   if (!segmented.includes('-')) return segmented.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
@@ -9,6 +13,8 @@ function toCamel(segmented: string): string {
 }
 
 function toKebab(camel: string): string {
+  const override = CANONICAL_CAMEL_TO_WIRE[camel];
+  if (override) return override;
   if (!camel) return camel;
   // Convert camelCase or mixedCase to kebab-case; leave existing hyphens and numbers intact
   return camel
@@ -49,4 +55,3 @@ export function toKebabCaseKeysDeep<T = any>(value: T): T { // eslint-disable-li
   return out as unknown as T;
 }
 
-

api/oas_generator/ts_oas_generator/templates/base/src/core/codecs.ts.j2

@@ -0,0 +1,87 @@
+// Temporary copy of codec helpers from utils-ts until the shared core moves into the monorepo.
+// These keep the generated clients self-contained and ready for future DTO <-> domain mappers.
+
+export abstract class Codec<T, TEncoded = T> {
+  public abstract defaultValue(): TEncoded;
+
+  protected toEncoded(value: T): TEncoded {
+    return value as unknown as TEncoded;
+  }
+
+  protected fromEncoded(value: TEncoded): T {
+    return value as unknown as T;
+  }
+
+  protected isDefaultValue(value: T): boolean {
+    return this.toEncoded(value) === this.defaultValue();
+  }
+
+  public encode(value?: T): TEncoded | undefined {
+    return value !== undefined && !this.isDefaultValue(value) ? this.toEncoded(value) : undefined;
+  }
+
+  public decode(value: TEncoded | undefined): T {
+    return this.fromEncoded(value ?? this.defaultValue());
+  }
+
+  public decodeOptional(value: TEncoded | undefined): T | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+    return this.fromEncoded(value);
+  }
+}
+
+export class NumberCodec extends Codec<number> {
+  public defaultValue(): number {
+    return 0;
+  }
+}
+
+export class BigIntCodec extends Codec<bigint, number | bigint> {
+  public defaultValue(): bigint {
+    return 0n;
+  }
+
+  protected fromEncoded(value: number | bigint): bigint {
+    return typeof value === 'bigint' ? value : BigInt(value);
+  }
+}
+
+export class StringCodec extends Codec<string> {
+  public defaultValue(): string {
+    return '';
+  }
+}
+
+export class BytesCodec extends Codec<Uint8Array> {
+  public defaultValue(): Uint8Array {
+    return new Uint8Array();
+  }
+
+  protected isDefaultValue(value: Uint8Array): boolean {
+    return value.byteLength === 0;
+  }
+}
+
+export class BooleanCodec extends Codec<boolean> {
+  public defaultValue(): boolean {
+    return false;
+  }
+}
+
+export class OmitEmptyObjectCodec<T extends object> extends Codec<T, T | undefined> {
+  public defaultValue(): T | undefined {
+    return undefined;
+  }
+
+  protected isDefaultValue(value: T): boolean {
+    return Object.values(value).filter((x) => x !== undefined).length === 0;
+  }
+}
+
+export const numberCodec = new NumberCodec();
+export const bigIntCodec = new BigIntCodec();
+export const stringCodec = new StringCodec();
+export const bytesCodec = new BytesCodec();
+export const booleanCodec = new BooleanCodec();

api/oas_generator/ts_oas_generator/templates/base/src/core/rename-map.ts.j2

@@ -0,0 +1,15 @@
+/* Auto-generated rename hints derived from OpenAPI vendor extensions. */
+
+export const WIRE_TO_CANONICAL: Record<string, string> = {
+{% for wire, canonical in wire_to_canonical|dictsort %}
+  '{{ wire }}': '{{ canonical }}',
+{% endfor %}
+};
+
+export const CANONICAL_CAMEL_TO_WIRE: Record<string, string> = {
+{% for camel, wire in camel_to_wire|dictsort %}
+  '{{ camel }}': '{{ wire }}',
+{% endfor %}
+};
+
+export const HAS_RENAME_HINTS = Object.keys(WIRE_TO_CANONICAL).length > 0;

api/oas_generator/ts_oas_generator/templates/models/index.ts.j2

@@ -1,6 +1,6 @@
 // Barrel file for models
 {% for name, _ in schemas.items() %}
-export type { {{ name | ts_pascal_case }} } from './{{ name | lower }}';
+export type { {{ name | ts_pascal_case }} } from './{{ name | ts_kebab_case }}';
 {% endfor %}
 {% if include_temp_signed_txn %}
 // TODO(utils-ts): Remove this export when utils-ts provides SignedTransaction types

api/oas_generator/ts_oas_generator/templates/models/model.ts.j2

@@ -9,8 +9,9 @@ import type { {{ refTypes | join(', ') }} } from './index';
 {% if isObject and schema.get('allOf') is not defined and schema.get('oneOf') is not defined and schema.get('anyOf') is not defined %}
 export interface {{ modelName }} {
 {%   for prop_name, prop_schema in (schema.get('properties') or {}).items() %}
+  {% set canonical_name = prop_schema.get('x-algokit-field-rename') or prop_name %}
   {{ prop_schema.description | ts_doc_comment }}
-  {{ prop_name | ts_camel_case }}{{ '' if (schema.get('required') or []) | list | select('equalto', prop_name) | list | length > 0 else '?' }}: {{ prop_schema | ts_type(schemas) }};
+  {{ canonical_name | ts_camel_case }}{{ '' if (schema.get('required') or []) | list | select('equalto', prop_name) | list | length > 0 else '?' }}: {{ prop_schema | ts_type(schemas) }};
 {%   endfor %}
 {%   if schema.get('additionalProperties') is sameas true %}
   [key: string]: any;