appstruct-codegen 0.2.0

Deterministic Rust, SQL, OpenAPI, TypeScript, and React generation for AppStruct
Documentation
use super::{
    auth, error_response, if_match_parameter, request_body, response, schema_ref, tenant,
    versioned_response,
};
use appstruct_ir::{AccessRuleIr, AppIr, EntityIr, FieldTypeIr};
use serde_json::{Map, Value, json};

mod collections;
mod lookup;
mod schema;
pub(super) fn add_paths(paths: &mut Map<String, Value>, ir: &AppIr, entity: &EntityIr) {
    let singular = &entity.rust_name;
    let collection = format!("/api/{}/", entity.table_name);
    let member = format!("/api/{}/{{id}}", entity.table_name);
    let mut list_parameters = list_parameters(ir, entity);
    let mut member_parameters = vec![json!({
        "name": "id",
        "in": "path",
        "required": true,
        "schema": schema::primary_key(entity),
    })];
    let create_parameters = if entity.tenant_scoped {
        list_parameters.push(tenant::parameter());
        member_parameters.push(tenant::parameter());
        vec![tenant::parameter()]
    } else {
        Vec::new()
    };
    paths.insert(
        collection,
        json!({
            "get": {
                "operationId": format!("list{singular}"),
                "tags": [singular],
                "security": auth::security(&entity.access.list),
                "parameters": list_parameters,
                "responses": {
                    "200": response(
                        "Paginated resource collection",
                        &schema_ref(&format!("{singular}ListResponse"))
                    )
                }
            },
            "post": {
                "operationId": format!("create{singular}"),
                "tags": [singular],
                "security": auth::security(&entity.access.create),
                "parameters": create_parameters,
                "requestBody": request_body(&format!("Create{singular}Input")),
                "responses": {
                    "201": versioned_response("Resource created", &schema_ref(singular)),
                    "422": error_response(),
                }
            }
        }),
    );
    paths.insert(
        member,
        json!({
            "parameters": member_parameters,
            "get": {
                "operationId": format!("get{singular}"),
                "tags": [singular],
                "security": auth::security(&entity.access.read),
                "responses": {
                    "200": versioned_response("Resource", &schema_ref(singular)),
                    "404": error_response(),
                }
            },
            "patch": {
                "operationId": format!("update{singular}"),
                "tags": [singular],
                "security": auth::security(&entity.access.update),
                "parameters": [if_match_parameter()],
                "requestBody": request_body(&format!("Update{singular}Input")),
                "responses": {
                    "200": versioned_response("Resource updated", &schema_ref(singular)),
                    "404": error_response(),
                    "412": error_response(),
                    "422": error_response(),
                    "428": error_response(),
                }
            },
            "delete": {
                "operationId": format!("delete{singular}"),
                "tags": [singular],
                "security": auth::security(&entity.access.delete),
                "parameters": [if_match_parameter()],
                "responses": {
                    "204": { "description": "Resource deleted" },
                    "404": error_response(),
                    "412": error_response(),
                    "428": error_response(),
                }
            }
        }),
    );
    add_aggregate_path(paths, ir, entity);
    add_facet_path(paths, ir, entity);
    lookup::add_path(paths, entity);
    super::bulk::add_paths(paths, ir, entity);
    add_workflow_paths(paths, entity);
    collections::add_paths(paths, ir, entity);
}

fn add_workflow_paths(paths: &mut Map<String, Value>, entity: &EntityIr) {
    let Some(workflow) = &entity.workflow else {
        return;
    };
    let singular = &entity.rust_name;
    let capabilities_path = format!("/api/{}/{{id}}/_transitions", entity.table_name);
    let transition_path = format!("{capabilities_path}/{{action}}");
    let mut base_parameters = vec![json!({
        "name": "id",
        "in": "path",
        "required": true,
        "schema": schema::primary_key(entity),
    })];
    if entity.tenant_scoped {
        base_parameters.push(tenant::parameter());
    }
    paths.insert(
        capabilities_path,
        json!({
            "get": {
                "operationId": format!("get{singular}WorkflowCapabilities"),
                "tags": [singular],
                "security": auth::security(&entity.access.read),
                "parameters": base_parameters,
                "responses": {
                    "200": versioned_response(
                        "Allowed workflow transitions for the current record revision",
                        &schema_ref(&format!("{singular}WorkflowCapabilities")),
                    ),
                    "404": error_response(),
                }
            }
        }),
    );
    let mut mutation_parameters = vec![
        json!({
            "name": "id",
            "in": "path",
            "required": true,
            "schema": schema::primary_key(entity),
        }),
        json!({
            "name": "action",
            "in": "path",
            "required": true,
            "schema": {
                "type": "string",
                "enum": workflow.transitions.iter().map(|transition| &transition.name).collect::<Vec<_>>(),
            },
        }),
        if_match_parameter(),
    ];
    if entity.tenant_scoped {
        mutation_parameters.push(tenant::parameter());
    }
    let access = AccessRuleIr::Any {
        rules: workflow
            .transitions
            .iter()
            .map(|transition| transition.access.clone())
            .collect(),
    };
    paths.insert(
        transition_path,
        json!({
            "post": {
                "operationId": format!("transition{singular}Workflow"),
                "tags": [singular],
                "security": auth::security(&access),
                "parameters": mutation_parameters,
                "requestBody": request_body(&format!("{singular}WorkflowTransitionInput")),
                "responses": {
                    "200": versioned_response("Workflow transition completed", &schema_ref(singular)),
                    "403": error_response(),
                    "404": error_response(),
                    "409": error_response(),
                    "412": error_response(),
                    "422": error_response(),
                    "428": error_response(),
                }
            }
        }),
    );
}
fn add_aggregate_path(paths: &mut Map<String, Value>, ir: &AppIr, entity: &EntityIr) {
    let singular = &entity.rust_name;
    let aggregate_path = format!("/api/{}/_aggregate", entity.table_name);
    paths.insert(
        aggregate_path,
        json!({
            "get": {
                "operationId": format!("aggregate{singular}"),
                "tags": [singular],
                "security": auth::security(&entity.access.list),
                "parameters": aggregate_parameters(ir, entity),
                "responses": {
                    "200": response(
                        "Aggregate and grouped resource data",
                        &schema_ref(&format!("{singular}AggregateResponse"))
                    ),
                    "400": error_response(),
                }
            }
        }),
    );
}
pub(super) fn add_schemas(schemas: &mut Map<String, Value>, entity: &EntityIr) {
    schema::add_schemas(schemas, entity);
}
pub(super) fn list_parameters(ir: &AppIr, entity: &EntityIr) -> Vec<Value> {
    let mut parameters = vec![
        query_parameter(
            "page",
            &json!({ "type": "integer", "minimum": 1, "default": 1 }),
        ),
        query_parameter(
            "page_size",
            &json!({ "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }),
        ),
        query_parameter("cursor", &json!({ "type": "string", "maxLength": 16384 })),
        query_parameter(
            "direction",
            &json!({ "type": "string", "enum": ["next", "previous"], "default": "next" }),
        ),
        query_parameter(
            "limit",
            &json!({ "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }),
        ),
        query_parameter("sort", &json!({ "type": "string" })),
        query_parameter("q", &json!({ "type": "string", "maxLength": 200 })),
        query_parameter(
            "where",
            &json!({ "type": "string", "maxLength": 16384, "description": "JSON filter tree: all/any groups or {field,op,values}. At most 8 levels, 64 nodes and 100 values; only filterable readable scalar fields." }),
        ),
        query_parameter(
            "fields",
            &json!({ "type": "string", "maxLength": 4096, "description": "Comma-separated readable fields. Omitted fields are not fetched or returned." }),
        ),
    ];
    for field in entity
        .fields
        .iter()
        .filter(|field| field.capabilities.filterable)
    {
        parameters.push(query_parameter(
            &format!("filter[{}]", field.rust_name),
            &schema::field_schema(field, false),
        ));
        if matches!(
            field.ty,
            FieldTypeIr::Integer
                | FieldTypeIr::Bigint
                | FieldTypeIr::Decimal
                | FieldTypeIr::Date
                | FieldTypeIr::Datetime
        ) {
            for operator in ["gte", "lte"] {
                parameters.push(query_parameter(
                    &format!("filter[{}][{operator}]", field.rust_name),
                    &schema::field_schema(field, false),
                ));
            }
        }
    }
    for relation_field in entity.fields.iter().filter(|field| {
        field.capabilities.filterable && matches!(field.ty, FieldTypeIr::Relation { .. })
    }) {
        let FieldTypeIr::Relation { target } = &relation_field.ty else {
            continue;
        };
        let target = ir
            .entities
            .iter()
            .find(|candidate| candidate.id == *target)
            .expect("validated relation target");
        for target_field in target
            .fields
            .iter()
            .filter(|field| field.capabilities.filterable)
        {
            parameters.push(query_parameter(
                &format!(
                    "filter[{}.{}]",
                    relation_field.api_name, target_field.rust_name
                ),
                &schema::field_schema(target_field, false),
            ));
            if matches!(
                target_field.ty,
                FieldTypeIr::Integer
                    | FieldTypeIr::Bigint
                    | FieldTypeIr::Decimal
                    | FieldTypeIr::Date
                    | FieldTypeIr::Datetime
            ) {
                for operator in ["gte", "lte"] {
                    parameters.push(query_parameter(
                        &format!(
                            "filter[{}.{}][{operator}]",
                            relation_field.api_name, target_field.rust_name
                        ),
                        &schema::field_schema(target_field, false),
                    ));
                }
            }
        }
    }
    parameters
}
fn aggregate_parameters(ir: &AppIr, entity: &EntityIr) -> Vec<Value> {
    let mut parameters = vec![
        query_parameter(
            "metrics",
            &json!({ "type": "string", "example": "count,sum:priority,avg:priority" }),
        ),
        query_parameter(
            "group_by",
            &json!({ "type": "string", "example": "status" }),
        ),
        query_parameter(
            "limit",
            &json!({ "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }),
        ),
        query_parameter(
            "order",
            &json!({ "type": "string", "enum": ["asc", "desc"], "description": "Defaults to asc for group order and desc for metric order." }),
        ),
        json!({ "name": "order_by", "in": "query", "schema": { "type": "string", "enum": ["metric", "group"] }, "description": "Orders by the first metric by default, or chronologically by group for time buckets. Group ordering requires group_by." }),
        json!({ "name": "time_bucket", "in": "query", "schema": { "type": "string", "enum": ["day", "week", "month"] }, "description": "Requires exactly one local date/datetime group. Datetime buckets use UTC; weeks start on Monday. Returns the bucket start as YYYY-MM-DD. Defaults to ascending group order." }),
    ];
    parameters.extend(list_parameters(ir, entity).into_iter().filter(|parameter| {
        let name = parameter["name"].as_str().unwrap_or_default();
        name == "q" || name == "where" || name.starts_with("filter[")
    }));
    parameters
}

fn add_facet_path(paths: &mut Map<String, Value>, ir: &AppIr, entity: &EntityIr) {
    let mut parameters = list_parameters(ir, entity)
        .into_iter()
        .filter(|parameter| {
            let name = parameter["name"].as_str().unwrap_or_default();
            matches!(name, "q" | "where") || name.starts_with("filter[")
        })
        .collect::<Vec<_>>();
    parameters.push(json!({ "name": "facet", "in": "query", "required": true, "schema": { "type": "string" }, "description": "1 to 5 comma-separated filterable scalar fields" }));
    parameters.push(query_parameter(
        "limit",
        &json!({ "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }),
    ));
    if entity.tenant_scoped {
        parameters.push(tenant::parameter());
    }
    paths.insert(format!("/api/{}/_facets", entity.table_name), json!({ "get": {
        "operationId": format!("facet{}", entity.rust_name), "tags": [&entity.rust_name], "security": auth::security(&entity.access.list), "parameters": parameters,
        "responses": { "200": response("Top-N facet buckets for the complete authorized filtered result, including SQL NULL and other_count", &json!({
            "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "additionalProperties": {
                "type": "object", "required": ["buckets", "other_count"], "properties": {
                    "other_count": { "type": "integer", "minimum": 0 },
                    "buckets": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": ["value", "count"], "properties": { "value": {}, "count": { "type": "integer", "minimum": 0 } } } }
                }
            } } }
        })), "400": error_response(), "403": error_response() }
    } }));
}
fn query_parameter(name: &str, schema: &Value) -> Value {
    json!({ "name": name, "in": "query", "required": false, "schema": schema })
}