🥮 mooncakes.io

    proton_contract

    Target-neutral typed contracts for Proton applications and extensions.

    proton
    contract
    ipc
    Download zip
    Version
    0.2.5
    License
    Apache-2.0
    Repository
    Last updated
    10 days ago
    Downloads
    7K

    #Proton Contract

    moonbit-community/proton_contract defines target-neutral typed command and event descriptors shared by Proton frontends and backends.

    Application contracts use explicit stable identities:

    ///|
    pub let create_todo : @proton_contract.Command[CreateTodoRequest, Todo] = @proton_contract.command(
      "create_todo",
    )

    ///|
    pub let todo_changed : @proton_contract.Event[TodoChanged] = @proton_contract.event(
      "todo_changed",
    )

    Each event route is declared exactly once within its scope. Put event descriptors in a shared contract package and import those values from both the frontend and backend. Constructing another event descriptor with the same route is rejected, even when it repeats the same payload type. Runtime identifiers and other varying data belong in event payloads, not in dynamically constructed route names.

    The descriptors do not own serialization. Frontend and backend integrations apply the appropriate ToJson and FromJson constraints when a descriptor is used.

    ContractDefinitionError

    source
    pub(all) suberror ContractDefinitionError {
      EmptyApplicationName
      EmptyExtensionId
      EmptyExtensionNamespace
      EmptyExtensionMember(extension_namespace~ : String)
      DuplicateEventRoute(route~ : String)
      ExpectedExtensionEvent(route~ : String)
    } derive(Eq, 
    Debug    )

    Failures found while validating a contract descriptor before use.

    ContractDefinitionError::equal

    source

    ContractDefinitionError::message

    source
    fn ContractDefinitionError::message(self : ContractDefinitionError) -> String

    ContractDefinitionError::not_equal

    source

    ContractDefinitionError::output

    source
    fn ContractDefinitionError::output(self : ContractDefinitionError, logger : &Logger) -> Unit

    ContractDefinitionError::to_repr

    source

    ContractDefinitionError::to_string

    source
    fn ContractDefinitionError::to_string(self : ContractDefinitionError) -> String

    Command

    source
    pub struct Command[Request, Response] {
      route : ContractRoute
      type_marker : (Request) -> Response?
    }

    A target-neutral command descriptor.

    The request and response parameters bind one stable command identity to its payload types without storing serialization logic.

    Command::name

    source
    fn[Request, Response] Command::name(self : Command[Request, Response]) -> String

    Returns a command's stable member name without a transport prefix.

    Command::validate

    source
    fn[Request, Response] Command::validate(self : Command[Request, Response]) -> Unit raise ContractDefinitionError

    Validates a command descriptor before registration or invocation.

    ContractRoute

    source
    pub struct ContractRoute {
      scope : ContractScope
      name : String
    }

    An opaque application or extension route carried by a typed descriptor.

    Application code does not construct routes or assemble transport names directly. Use command, event, or an ExtensionContract.

    EmptyRequest

    source

    A request payload with no fields, shared by commands that take no input.

    EmptyRequest::equal

    source

    EmptyRequest::from_json

    source

    EmptyRequest::not_equal

    source
    fn EmptyRequest::not_equal(x : EmptyRequest, y : EmptyRequest) -> Bool

    EmptyRequest::to_json

    source

    EmptyRequest::to_repr

    source

    Event

    source
    pub struct Event[Payload] {
      route : ContractRoute
      type_marker : (Payload) -> Unit?
      duplicate_route : Bool
    }

    A target-neutral live-event descriptor.

    Events are not replayed by the descriptor. Runtime integrations decide how an event is emitted and subscribed. A route may be declared as an event only once within its scope. Export and reuse that descriptor everywhere instead of constructing another event with the same route, even with the same payload type.

    Event::name

    source
    fn[Payload] Event::name(self : Event[Payload]) -> String

    Returns an event's stable member name without a transport prefix.

    Event::validate

    source
    fn[Payload] Event::validate(self : Event[Payload]) -> Unit raise ContractDefinitionError

    Validates an event descriptor before subscription or emission.

    ExtensionContract

    source
    pub struct ExtensionContract {
      id : String
      js_namespace : String
    }

    The identity and route scope shared by one Proton extension contract.

    ExtensionContract::command

    source
    fn[Request, Response] ExtensionContract::command(self : ExtensionContract, name : String) -> Command[Request, Response]

    Creates a typed command descriptor scoped to this extension.

    ExtensionContract::event

    source
    fn[Payload] ExtensionContract::event(self : ExtensionContract, name : String) -> Event[Payload]

    Creates a unique typed live-event descriptor scoped to this extension.

    Calling this method more than once with the same member name on the same extension contract is an invalid contract declaration. Runtime values belong in the event payload, not in a dynamically constructed member name.

    ExtensionContract::id

    source
    fn ExtensionContract::id(self : ExtensionContract) -> String

    Returns this extension contract's stable catalog identity.

    ExtensionContract::js_namespace

    source
    fn ExtensionContract::js_namespace(self : ExtensionContract) -> String

    Returns this extension contract's JavaScript and transport namespace.

    ExtensionContract::validate

    source

    Validates the extension identity before it is installed or used.

    SupportReply

    source
    pub(all) struct SupportReply {
      supported : Bool
      platform : String
      reason : String?
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Standard platform-support probe result, shared by extension support commands.

    SupportReply::equal

    source

    SupportReply::from_json

    source

    SupportReply::not_equal

    source
    fn SupportReply::not_equal(x : SupportReply, y : SupportReply) -> Bool

    SupportReply::to_json

    source

    SupportReply::to_repr

    source

    command

    source
    fn[Request, Response] command(name : String) -> Command[Request, Response]

    Creates an application command descriptor.

    event

    source
    fn[Payload] event(name : String) -> Event[Payload]

    Creates a unique application event descriptor.

    Calling this function more than once with the same name is an invalid contract declaration. Runtime values belong in the event payload, not in a dynamically constructed event name.

    extension

    source
    fn extension(id~ : String, js_namespace~ : String) -> ExtensionContract

    Creates the identity shared by an extension's command and event descriptors.

    Extension packages normally expose a value generated from proton.ext.json instead of calling this constructor by hand.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io