Skip to main content

shaperail_codegen/
typescript.rs

1use std::collections::BTreeMap;
2
3/// Generate TypeScript type definitions from an OpenAPI 3.1 spec.
4///
5/// Reads the `components.schemas` section and produces one interface per schema.
6/// This generates types that match what `openapi-typescript` would produce from
7/// the same spec — the spec JSON is also written alongside so users can run
8/// `npx openapi-typescript openapi.json -o types.ts` if they prefer.
9pub fn generate_from_spec(spec: &serde_json::Value) -> BTreeMap<String, String> {
10    let mut files: BTreeMap<String, String> = BTreeMap::new();
11
12    let schemas = match spec
13        .get("components")
14        .and_then(|c| c.get("schemas"))
15        .and_then(|s| s.as_object())
16    {
17        Some(s) => s,
18        None => return files,
19    };
20
21    let mut all_interfaces = Vec::new();
22
23    // Sort schema names for deterministic output
24    let mut schema_names: Vec<&String> = schemas.keys().collect();
25    schema_names.sort();
26
27    for name in &schema_names {
28        let schema = &schemas[*name];
29        if let Some(interface) = schema_to_interface(name, schema) {
30            all_interfaces.push(interface);
31        }
32    }
33
34    // Generate per-resource files by grouping schemas
35    // Collect resource names from paths tags
36    let mut resource_schemas: BTreeMap<String, Vec<String>> = BTreeMap::new();
37
38    if let Some(paths) = spec.get("paths").and_then(|p| p.as_object()) {
39        for (_path, methods) in paths {
40            if let Some(methods_obj) = methods.as_object() {
41                for (_method, operation) in methods_obj {
42                    if let Some(tags) = operation.get("tags").and_then(|t| t.as_array()) {
43                        if let Some(tag) = tags.first().and_then(|t| t.as_str()) {
44                            let pascal = to_pascal_case(tag);
45                            // Add the main schema and any input schemas
46                            for schema_name in &schema_names {
47                                if schema_name.starts_with(&pascal) {
48                                    resource_schemas
49                                        .entry(tag.to_string())
50                                        .or_default()
51                                        .push((*schema_name).clone());
52                                }
53                            }
54                        }
55                    }
56                }
57            }
58        }
59    }
60
61    // Deduplicate schema lists
62    for schemas_list in resource_schemas.values_mut() {
63        schemas_list.sort();
64        schemas_list.dedup();
65    }
66
67    // Generate per-resource .ts files
68    for (resource_name, schema_list) in &resource_schemas {
69        let mut content = String::new();
70        for schema_name in schema_list {
71            if let Some(schema) = schemas.get(schema_name) {
72                if let Some(interface) = schema_to_interface(schema_name, schema) {
73                    content.push_str(&interface);
74                    content.push('\n');
75                }
76            }
77        }
78        if !content.is_empty() {
79            files.insert(format!("{resource_name}.ts"), content);
80        }
81    }
82
83    // Generate index.ts that re-exports everything
84    let index: String = resource_schemas
85        .keys()
86        .map(|r| format!("export * from './{r}';"))
87        .collect::<Vec<_>>()
88        .join("\n");
89    if !index.is_empty() {
90        files.insert("index.ts".to_string(), format!("{index}\n"));
91    }
92
93    files
94}
95
96fn schema_to_interface(name: &str, schema: &serde_json::Value) -> Option<String> {
97    let properties = schema.get("properties")?.as_object()?;
98    let required_fields: Vec<&str> = schema
99        .get("required")
100        .and_then(|r| r.as_array())
101        .map(|arr| arr.iter().filter_map(|v| v.as_str()).collect())
102        .unwrap_or_default();
103
104    let mut fields = Vec::new();
105
106    // Sort property names for deterministic output
107    let mut prop_names: Vec<&String> = properties.keys().collect();
108    prop_names.sort();
109
110    for prop_name in prop_names {
111        let prop = &properties[prop_name];
112        let ts_type = openapi_type_to_ts(prop);
113        let optional = if required_fields.contains(&prop_name.as_str()) {
114            ""
115        } else {
116            "?"
117        };
118        fields.push(format!("  {prop_name}{optional}: {ts_type};"));
119    }
120
121    Some(format!(
122        "export interface {name} {{\n{}\n}}\n",
123        fields.join("\n")
124    ))
125}
126
127fn openapi_type_to_ts(schema: &serde_json::Value) -> &'static str {
128    // Check for $ref — treat as unknown
129    if schema.get("$ref").is_some() {
130        return "unknown";
131    }
132
133    let type_val = schema.get("type").and_then(|t| t.as_str());
134    let format_val = schema.get("format").and_then(|f| f.as_str());
135
136    match (type_val, format_val) {
137        (Some("string"), _) => "string",
138        (Some("integer"), _) | (Some("number"), _) => "number",
139        (Some("boolean"), _) => "boolean",
140        (Some("array"), _) => "unknown[]",
141        (Some("object"), _) => "Record<string, unknown>",
142        _ => "unknown",
143    }
144}
145
146fn to_pascal_case(s: &str) -> String {
147    s.split('_')
148        .map(|word| {
149            let mut chars = word.chars();
150            match chars.next() {
151                None => String::new(),
152                Some(c) => {
153                    let upper: String = c.to_uppercase().collect();
154                    upper + &chars.as_str().to_lowercase()
155                }
156            }
157        })
158        .collect()
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164    use indexmap::IndexMap;
165    use shaperail_core::{
166        AuthRule, CacheSpec, EndpointSpec, FieldSchema, FieldType, HttpMethod, PaginationStyle,
167        ResourceDefinition,
168    };
169
170    fn test_config() -> shaperail_core::ProjectConfig {
171        shaperail_core::ProjectConfig {
172            project: "test-api".to_string(),
173            port: 3000,
174            workers: shaperail_core::WorkerCount::Auto,
175            databases: None,
176            cache: None,
177            auth: None,
178            storage: None,
179            logging: None,
180            events: None,
181            protocols: vec!["rest".to_string()],
182            graphql: None,
183            grpc: None,
184        }
185    }
186
187    fn sample_resource() -> ResourceDefinition {
188        let mut schema = IndexMap::new();
189        schema.insert(
190            "id".to_string(),
191            FieldSchema {
192                field_type: FieldType::Uuid,
193                primary: true,
194                generated: true,
195                required: false,
196                unique: false,
197                nullable: false,
198                reference: None,
199                min: None,
200                max: None,
201                format: None,
202                values: None,
203                default: None,
204                sensitive: false,
205                search: false,
206                items: None,
207                transient: false,
208            },
209        );
210        schema.insert(
211            "name".to_string(),
212            FieldSchema {
213                field_type: FieldType::String,
214                primary: false,
215                generated: false,
216                required: true,
217                unique: false,
218                nullable: false,
219                reference: None,
220                min: None,
221                max: None,
222                format: None,
223                values: None,
224                default: None,
225                sensitive: false,
226                search: false,
227                items: None,
228                transient: false,
229            },
230        );
231        schema.insert(
232            "active".to_string(),
233            FieldSchema {
234                field_type: FieldType::Boolean,
235                primary: false,
236                generated: false,
237                required: false,
238                unique: false,
239                nullable: true,
240                reference: None,
241                min: None,
242                max: None,
243                format: None,
244                values: None,
245                default: None,
246                sensitive: false,
247                search: false,
248                items: None,
249                transient: false,
250            },
251        );
252
253        let mut endpoints = IndexMap::new();
254        endpoints.insert(
255            "list".to_string(),
256            EndpointSpec {
257                method: Some(HttpMethod::Get),
258                path: Some("/items".to_string()),
259                auth: Some(AuthRule::Roles(vec!["member".to_string()])),
260                pagination: Some(PaginationStyle::Cursor),
261                cache: Some(CacheSpec {
262                    ttl: 60,
263                    invalidate_on: None,
264                }),
265                ..Default::default()
266            },
267        );
268        endpoints.insert(
269            "create".to_string(),
270            EndpointSpec {
271                method: Some(HttpMethod::Post),
272                path: Some("/items".to_string()),
273                auth: Some(AuthRule::Roles(vec!["admin".to_string()])),
274                input: Some(vec!["name".to_string(), "active".to_string()]),
275                ..Default::default()
276            },
277        );
278
279        ResourceDefinition {
280            resource: "items".to_string(),
281            version: 1,
282            db: None,
283            tenant_key: None,
284            schema,
285            endpoints: Some(endpoints),
286            relations: None,
287            indexes: None,
288        }
289    }
290
291    #[test]
292    fn generates_ts_from_openapi_spec() {
293        let config = test_config();
294        let resources = vec![sample_resource()];
295        let spec = crate::openapi::generate(&config, &resources);
296        let files = generate_from_spec(&spec);
297
298        assert!(files.contains_key("items.ts"), "items.ts generated");
299        assert!(files.contains_key("index.ts"), "index.ts generated");
300    }
301
302    #[test]
303    fn ts_contains_interfaces() {
304        let config = test_config();
305        let resources = vec![sample_resource()];
306        let spec = crate::openapi::generate(&config, &resources);
307        let files = generate_from_spec(&spec);
308
309        let items_ts = &files["items.ts"];
310        assert!(
311            items_ts.contains("export interface Items"),
312            "main interface"
313        );
314        assert!(
315            items_ts.contains("export interface ItemsCreateInput"),
316            "input interface"
317        );
318    }
319
320    #[test]
321    fn ts_field_types_correct() {
322        let config = test_config();
323        let resources = vec![sample_resource()];
324        let spec = crate::openapi::generate(&config, &resources);
325        let files = generate_from_spec(&spec);
326
327        let items_ts = &files["items.ts"];
328        assert!(items_ts.contains("id?: string;"), "uuid → optional string");
329        assert!(items_ts.contains("name: string;"), "required string");
330        assert!(
331            items_ts.contains("active?: boolean;"),
332            "nullable boolean optional"
333        );
334    }
335
336    #[test]
337    fn ts_index_reexports() {
338        let config = test_config();
339        let resources = vec![sample_resource()];
340        let spec = crate::openapi::generate(&config, &resources);
341        let files = generate_from_spec(&spec);
342
343        let index = &files["index.ts"];
344        assert!(index.contains("export * from './items';"));
345    }
346
347    #[test]
348    fn sensitive_field_omitted_from_ts_response_interface() {
349        let config = test_config();
350        let mut resource = sample_resource();
351        resource.schema.get_mut("active").unwrap().sensitive = true;
352        let spec = crate::openapi::generate(&config, &[resource]);
353        let files = generate_from_spec(&spec);
354
355        let items_ts = &files["items.ts"];
356
357        // Response interface (Items) drops the sensitive field
358        let response_block = items_ts
359            .split("export interface Items {")
360            .nth(1)
361            .and_then(|s| s.split('}').next())
362            .expect("Items interface body");
363        assert!(
364            !response_block.contains("active"),
365            "sensitive `active` must be absent from Items response interface, got: {response_block:?}"
366        );
367
368        // Input interface still includes it (declared in `input:`)
369        let input_block = items_ts
370            .split("export interface ItemsCreateInput {")
371            .nth(1)
372            .and_then(|s| s.split('}').next())
373            .expect("ItemsCreateInput interface body");
374        assert!(
375            input_block.contains("active"),
376            "sensitive fields declared in input: must remain in request interface, got: {input_block:?}"
377        );
378    }
379
380    #[test]
381    fn deterministic_ts_output() {
382        let config = test_config();
383        let resources = vec![sample_resource()];
384        let spec = crate::openapi::generate(&config, &resources);
385
386        let files1 = generate_from_spec(&spec);
387        let files2 = generate_from_spec(&spec);
388
389        assert_eq!(files1, files2, "TS SDK output must be deterministic");
390    }
391}