🥮 mooncakes.io

    proton_contract

    Target-neutral typed contracts for Proton applications and extensions.

    proton
    contract
    ipc
    Download zip
    Version
    0.2.10
    License
    Apache-2.0
    Repository
    Last updated
    3 hours ago
    Downloads
    8K

    #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",
    )

    Descriptors are inert values. Reconstructing an event does not register a listener or mutate process state. Keep shared route and payload definitions in one contract package so independently compiled frontends and backends agree. Command binding and extension event-source installation reject conflicting registrations in their owning runtime; descriptors do not prove that a remote handler is installed or authorized.

    Use a response enum for expected business outcomes (for example Created, InvalidTitle, or MissingTodo). Transport and unexpected execution failures remain client failures. Runtime identifiers belong in payloads rather than dynamically generated route names.

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

    The former DuplicateEventRoute definition error has been removed. Applications that matched that variant should remove that branch; repeated descriptor construction is now valid. Existing command and event route names are unchanged.

    ContractDefinitionError

    source
    pub(all) suberror ContractDefinitionError {
      EmptyApplicationName
      EmptyExtensionId
      EmptyExtensionNamespace
      EmptyExtensionMember(extension_namespace~ : 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?
    }

    A target-neutral live-event descriptor.

    Events are not replayed by the descriptor. Runtime integrations decide how an event is emitted and subscribed. Descriptors are inert values; share their definitions across processes to keep payload types consistent.

    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 an inert typed live-event descriptor scoped to this extension.

    Descriptor construction does not register a listener or event source.

    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 an inert application event descriptor.

    Reconstructing a descriptor has no registration side effects. Runtime values belong in the payload; export shared descriptors for stable routes.

    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