🥮 mooncakes.io
    Sign in

    moonasyncapi

    AsyncAPI 3.0 to MoonBit type and message interface generator

    asyncapi
    codegen
    event-driven
    moonbit
    mqtt
    Download zip
    Author
    Version
    0.2.0
    License
    Apache-2.0
    Repository
    Last updated
    last month
    Downloads
    22

    No dependencies

    #MoonAsyncAPI Codegen

    MoonAsyncAPI is an AsyncAPI 3.0 JSON to MoonBit code generator. It reads an event-driven API contract and emits a compilable MoonBit project containing schema types, typed message envelopes, transport-neutral operation ports, and MQTT, Kafka, or AMQP binding configuration skeletons.

    The generator is deterministic and offline. It does not connect to a broker, send messages, or fetch remote references. The parser and validator introduced in 0.1.0 remain available as the generator frontend and for input diagnostics; the primary 0.2.0 workflow is project generation.

    #Generated Output

    Given an AsyncAPI document, MoonAsyncAPI can generate:

    • MoonBit structs for object schemas and enums for string enumerations
    • primitive, array, optional, nested object, and local $ref type mappings
    • typed payload, header, and correlation ID message envelopes
    • publisher or receive-handler traits for AsyncAPI operations
    • MQTT, Kafka, AMQP, and custom binding configuration types
    • moon.mod, moon.pkg, and either split or single-file source layouts
    • stable diagnostics for unresolved references, cycles, unsupported types, and normalized identifier collisions

    See docs/SUPPORT_MATRIX.md for exact coverage and docs/CODEGEN_DESIGN.md for the generation pipeline.

    #Install

    moon add zbhzs1/moonasyncapi

    Add the library import to moon.pkg:

    ///|
    import {
      "zbhzs1/moonasyncapi",
    }

    #Library Usage

    let source =
      "{\"asyncapi\":\"3.0.0\",\"info\":{\"title\":\"Events\"},\"channels\":{}}"
    match @moonasyncapi.generate_from_json(source) {
      Ok(plan) => {
        for file in plan.files {
          println(file.path)
        }
      }
      Err(message) => println("parse error: " + message)
    }

    generate_project accepts CodegenOptions for module name, source directory, split-file output, binding skeletons, and operation stubs. Generated files are returned in memory so applications can write them to disk, show previews, or apply their own workspace policy.

    #CLI Usage

    The repository includes a Node-backed MoonBit CLI for writing a project:

    moon run cmd/main --target js -- \
  examples/order-events.json \
  _build/generated-orders \
  example/order-events-generated

cd _build/generated-orders
moon check --deny-warn

    The first argument is an AsyncAPI JSON file, the second is the output directory, and the optional third argument is the generated module name. Existing files at the generated paths are replaced; unrelated files are left untouched.

    #Examples

    • examples/temperature.json: MQTT channel with an inline object payload
    • examples/order-events.json: Kafka channel with component schemas, enum, headers, a local reference, and a receive operation

    CI generates both projects and runs moon check --deny-warn inside each output directory. This verifies the generated source rather than only snapshot text.

    #Parser And Diagnostics

    The 0.1.0 parser APIs remain source compatible. parse, validate, payload and header validation, document inventory, and compatibility diagnostics can be used before generation. They are supporting frontend capabilities, not a claim to replace schema-governance projects.

    #Development

    moon fmt --check
moon check --deny-warn
moon check --target js --deny-warn
moon build
moon test

    The project is licensed under Apache-2.0. Contributions should include focused tests and, for generation changes, at least one generated-project check.

    AsyncApiChannel

    source
    pub struct AsyncApiChannel {
      address : String
      messages : Map[String, AsyncApiMessage]
      binding : String?
      parameters : Map[String, ChannelParameter]
    } derive(Eq, 
    Debug    )

    AsyncApiDocument

    source
    pub struct AsyncApiDocument {
      asyncapi : String
      version : String
      title : String
      channels : Map[String, AsyncApiChannel]
      operations : Array[AsyncApiOperation]
      schemas : Map[String, Schema]
      messages : Map[String, AsyncApiMessage]
      servers : Map[String, AsyncApiServer]
      security_schemes : Map[String, SecurityScheme]
    } derive(Eq, 
    Debug    )

    A small, typed and executable AsyncAPI 3.0 document model.

    This release supports JSON documents, local references, channels, operations, messages, a JSON Schema subset, and compatibility diagnostics. It intentionally does not claim complete YAML or JSON Schema support.

    AsyncApiMessage

    source
    pub struct AsyncApiMessage {
      name : String
      title : String
      content_type : String?
      payload : Schema?
      headers : Schema?
      correlation_id_location : String?
    } derive(Eq, 
    Debug    )

    AsyncApiOperation

    source
    pub struct AsyncApiOperation {
      name : String
      action : String
      channel : String
      messages : Array[String]
      protocol : String?
      summary : String?
      description : String?
      tags : Array[String]
      security_requirements : Array[String]
    } derive(Eq, 
    Debug    )

    AsyncApiServer

    source
    pub struct AsyncApiServer {
      name : String
      host : String
      protocol : String
      protocol_version : String?
      pathname : String?
      description : String?
      variables : Map[String, ServerVariable]
      security_requirements : Array[String]
    } derive(Eq, 
    Debug    )

    ChannelParameter

    source
    pub struct ChannelParameter {
      name : String
      description : String?
      location : String?
      enum_values : Array[String]
      default_value : String?
    } derive(Eq, 
    Debug    )

    CodegenDiagnostic

    source
    pub(all) struct CodegenDiagnostic {
      severity : String
      code : String
      path : String
      message : String
    } derive(Eq, 
    Debug    )

    A generator diagnostic is separate from contract validation diagnostics.

    CodegenOptions

    source
    pub(all) struct CodegenOptions {
      module_name : String
      source_dir : String
      split_files : Bool
      emit_protocol_bindings : Bool
      emit_operation_stubs : Bool
    } derive(Eq, 
    Debug    )

    Options controlling AsyncAPI-to-MoonBit project generation.

    Diagnostic

    source
    pub struct Diagnostic {
      severity : String
      code : String
      path : String
      message : String
    } derive(Eq, 
    Debug    )

    DiagnosticSummary

    source
    pub struct DiagnosticSummary {
      errors : Int
      warnings : Int
      infos : Int
      total : Int
    } derive(Eq, 
    Debug    )

    DocumentInventory

    source
    pub struct DocumentInventory {
      channel_count : Int
      message_count : Int
      operation_count : Int
      schema_count : Int
      server_count : Int
      security_scheme_count : Int
      parameter_count : Int
    } derive(Eq, 
    Debug    )

    GeneratedFile

    source
    pub(all) struct GeneratedFile {
      path : String
      content : String
      kind : String
    } derive(Eq, 
    Debug    )

    A file produced by the generator. Paths always use forward slashes.

    GeneratedType

    source
    pub(all) struct GeneratedType {
      source_name : String
      moonbit_name : String
      declaration : String
      dependencies : Array[String]
    } derive(Eq, 
    Debug    )

    Intermediate representation for a generated MoonBit type.

    GenerationPlan

    source
    pub(all) struct GenerationPlan {
      files : Array[GeneratedFile]
      diagnostics : Array[CodegenDiagnostic]
      schema_count : Int
      message_count : Int
      operation_count : Int
    } derive(Eq, 
    Debug    )

    A deterministic plan containing every file and generator diagnostic.

    OperationHeadersValidationReport

    source
    pub struct OperationHeadersValidationReport {
      operation_name : String
      action : String
      channel : String
      message_count : Int
      diagnostics : Array[Diagnostic]
    } derive(Eq, 
    Debug    )

    OperationValidationReport

    source
    pub struct OperationValidationReport {
      operation_name : String
      action : String
      channel : String
      protocol : String?
      message_count : Int
      diagnostics : Array[Diagnostic]
    } derive(Eq, 
    Debug    )

    Schema

    source
    pub struct Schema {
      kind : String?
      required : Array[String]
      properties : Map[String, Schema]
      enum_values : Array[String]
      enum_json_values : Array[Json]
      const_value : Json?
      format_name : String?
      default_value : Json?
      examples : Array[Json]
      ref_name : String?
      ref_cycle : Bool
      items : Schema?
      minimum : Double?
      maximum : Double?
      multiple_of : Double?
      exclusive_minimum : Double?
      exclusive_maximum : Double?
      min_length : Double?
      max_length : Double?
      min_items : Double?
      max_items : Double?
      unique_items : Bool
      min_properties : Double?
      max_properties : Double?
      additional_properties : Bool?
      unsupported_keywords : Array[String]
    } derive(Eq, 
    Debug    )

    SchemaSummary

    source
    pub struct SchemaSummary {
      kind : String?
      property_count : Int
      required_count : Int
      enum_count : Int
      has_items : Bool
      has_default : Bool
      example_count : Int
      has_constraints : Bool
    } derive(Eq, 
    Debug    )

    SecurityScheme

    source
    pub struct SecurityScheme {
      name : String
      kind : String
      description : String?
      location : String?
      scheme : String?
      bearer_format : String?
    } derive(Eq, 
    Debug    )

    ServerVariable

    source
    pub struct ServerVariable {
      name : String
      default_value : String?
      enum_values : Array[String]
      description : String?
    } derive(Eq, 
    Debug    )

    address_parameters

    source
    fn address_parameters(address : String) -> Array[String]

    Extract parameter names from a channel address in declaration order.

    channel_message_names

    source
    fn channel_message_names(document : AsyncApiDocument, channel_name : String) -> Array[String]

    Return channel message names in a stable traversal order.

    channel_names

    source
    fn channel_names(document : AsyncApiDocument) -> Array[String]

    Return channel names in document declaration order.

    default_codegen_options

    source
    fn default_codegen_options() -> CodegenOptions

    diagnostics_by_severity

    source
    fn diagnostics_by_severity(issues : Array[Diagnostic], severity : String) -> Array[Diagnostic]

    Keep only diagnostics with the requested severity.

    diagnostics_count

    source
    fn diagnostics_count(issues : Array[Diagnostic], severity : String) -> Int

    diagnostics_exit_code

    source
    fn diagnostics_exit_code(issues : Array[Diagnostic], warnings_as_errors? : Bool) -> Int

    Recommend a conventional process exit code for the diagnostic set.

    diagnostics_has_errors

    source
    fn diagnostics_has_errors(issues : Array[Diagnostic]) -> Bool

    diagnostics_to_text

    source
    fn diagnostics_to_text(issues : Array[Diagnostic]) -> String

    diff

    source
    fn diff(before : AsyncApiDocument, after : AsyncApiDocument) -> Array[Diagnostic]

    document_inventory

    source
    fn document_inventory(document : AsyncApiDocument) -> DocumentInventory

    Return counts for the main contract namespaces.

    document_inventory_to_text

    source
    fn document_inventory_to_text(inventory : DocumentInventory) -> String

    Render the inventory as stable key/value lines for CI logs.

    document_namespaces_to_text

    source
    fn document_namespaces_to_text(document : AsyncApiDocument) -> String

    Render the names available in each top-level contract namespace.

    document_summary

    source
    fn document_summary(document : AsyncApiDocument) -> String

    Return a compact inventory of the parsed contract.

    find_channel

    source
    fn find_channel(document : AsyncApiDocument, name : String) -> AsyncApiChannel?

    Find a channel by its document key.

    find_channel_parameter

    source
    fn find_channel_parameter(channel : AsyncApiChannel, name : String) -> ChannelParameter?

    Find a declared parameter on a channel.

    find_generated_file

    source
    fn find_generated_file(plan : GenerationPlan, path : String) -> GeneratedFile?

    find_message

    source
    fn find_message(document : AsyncApiDocument, name : String) -> AsyncApiMessage?

    Find a reusable component message by name.

    find_operation

    source
    fn find_operation(document : AsyncApiDocument, name : String) -> AsyncApiOperation?

    Find an operation by its document key.

    find_schema

    source
    fn find_schema(document : AsyncApiDocument, name : String) -> Schema?

    Find a reusable component schema by name.

    find_security_scheme

    source
    fn find_security_scheme(document : AsyncApiDocument, name : String) -> SecurityScheme?

    Find a reusable security scheme declaration.

    find_server

    source
    fn find_server(document : AsyncApiDocument, name : String) -> AsyncApiServer?

    Find a server declaration by name.

    find_server_variable

    source
    fn find_server_variable(server : AsyncApiServer, name : String) -> ServerVariable?

    Find a variable declaration on a server.

    generate_from_json

    source
    fn generate_from_json(input : String, options? : CodegenOptions) -> Result[GenerationPlan, String]

    Parse JSON and generate a project in one call.

    generate_project

    source
    fn generate_project(document : AsyncApiDocument, options? : CodegenOptions) -> GenerationPlan

    Generate a complete MoonBit project plan from a parsed AsyncAPI document.

    generation_has_errors

    source
    fn generation_has_errors(plan : GenerationPlan) -> Bool

    generation_manifest

    source
    fn generation_manifest(plan : GenerationPlan) -> String

    has_operation

    source
    fn has_operation(document : AsyncApiDocument, name : String) -> Bool

    Test whether an operation name is declared in the document.

    highest_severity

    source
    fn highest_severity(issues : Array[Diagnostic]) -> String

    Return the most severe level present, or none for an empty list.

    message_names

    source
    fn message_names(document : AsyncApiDocument) -> Array[String]

    Return component message names in document declaration order.

    moonbit_type_name

    source
    fn moonbit_type_name(source : String) -> String

    Convert an arbitrary AsyncAPI component key to a MoonBit type identifier.

    moonbit_value_name

    source
    fn moonbit_value_name(source : String) -> String

    Convert an arbitrary property or operation key to a MoonBit value identifier.

    operation_count_by_action

    source
    fn operation_count_by_action(document : AsyncApiDocument, action : String) -> Int

    Count operations using one AsyncAPI action.

    operation_count_by_protocol

    source
    fn operation_count_by_protocol(document : AsyncApiDocument, protocol : String) -> Int

    Count operations that declare a protocol binding.

    operation_headers_reports_to_text

    source
    fn operation_headers_reports_to_text(reports : Array[OperationHeadersValidationReport]) -> String

    Render header reports without exposing internal report layout.

    operation_names

    source
    fn operation_names(document : AsyncApiDocument) -> Array[String]

    Return operation names from the parsed document.

    operation_names_by_action

    source
    fn operation_names_by_action(document : AsyncApiDocument, action : String) -> Array[String]

    Return operations using one AsyncAPI action, such as send or receive.

    operation_names_by_protocol

    source
    fn operation_names_by_protocol(document : AsyncApiDocument, protocol : String) -> Array[String]

    Return operations that declare a particular protocol binding.

    operation_report_diagnostics

    source
    fn operation_report_diagnostics(reports : Array[OperationValidationReport]) -> Array[Diagnostic]

    Flatten operation report diagnostics for CI summary handling.

    operation_reports_to_text

    source
    fn operation_reports_to_text(reports : Array[OperationValidationReport]) -> String

    Render operation reports without exposing internal data layout.

    operation_tags

    source
    fn operation_tags(operation : AsyncApiOperation) -> Array[String]

    Return the declared tags for an operation.

    parse

    source
    fn parse(input : String) -> Result[AsyncApiDocument, String]

    render_channel_address

    source
    fn render_channel_address(channel : AsyncApiChannel, values : Map[String, String]) -> Result[String, String]

    Render a concrete channel address from declared parameter values. Declared defaults are used when the caller omits a value.

    render_server_endpoint

    source
    fn render_server_endpoint(server : AsyncApiServer, values : Map[String, String]) -> Result[String, String]

    Render a server endpoint using explicit values and declared defaults.

    schema_names

    source
    fn schema_names(document : AsyncApiDocument) -> Array[String]

    Return schema names in document declaration order.

    schema_paths

    source
    fn schema_paths(schema : Schema) -> Array[String]

    Return property and item paths in a schema, bounded to avoid pathological input.

    security_scheme_names

    source
    fn security_scheme_names(document : AsyncApiDocument) -> Array[String]

    Return security scheme names in document declaration order.

    server_names

    source
    fn server_names(document : AsyncApiDocument) -> Array[String]

    Return server names in document declaration order.

    summarize_diagnostics

    source
    fn summarize_diagnostics(issues : Array[Diagnostic]) -> DiagnosticSummary

    Count diagnostics by severity for CI and command-line consumers.

    summarize_schema

    source
    fn summarize_schema(schema : Schema) -> SchemaSummary

    Summarize the supported parts of a schema for tooling and code generation.

    validate

    source
    fn validate(document : AsyncApiDocument) -> Array[Diagnostic]

    validate_headers

    source
    fn validate_headers(message : AsyncApiMessage, headers : Json) -> Array[Diagnostic]

    Validate message headers against the declared headers schema.

    validate_operation_headers

    source
    fn validate_operation_headers(document : AsyncApiDocument, operation_name : String, headers : Json) -> Array[Diagnostic]

    Validate headers against every message selected by an operation.

    validate_operation_headers_batch

    source
    fn validate_operation_headers_batch(document : AsyncApiDocument, headers_by_operation : Map[String, Json]) -> Array[OperationHeadersValidationReport]

    Validate headers for every operation and preserve operation context.

    validate_operation_payload

    source
    fn validate_operation_payload(document : AsyncApiDocument, operation_name : String, payload : Json) -> Array[Diagnostic]

    Validate a payload against every message selected by an operation.

    validate_operations

    source
    fn validate_operations(document : AsyncApiDocument, payloads : Map[String, Json]) -> Array[OperationValidationReport]

    Validate payloads for several operations in one deterministic report.

    validate_payload

    source
    fn validate_payload(message : AsyncApiMessage, payload : Json) -> Array[Diagnostic]

    Validate a JSON value against the supported schema subset of a message.

    validate_strict

    source
    fn validate_strict(document : AsyncApiDocument) -> Array[Diagnostic]

    Validate a document and promote warnings to errors for strict CI mode.

    validation_report

    source
    fn validation_report(document : AsyncApiDocument) -> String

    Produce a compact human-readable validation report with counts.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io