🥮 mooncakes.io

proton_contract

Target-neutral typed contracts for Proton applications and extensions.

proton
contract
ipc
moon add moonbit-community/proton_contract@0.1.16
Download zip
Version
0.1.16
License
Apache-2.0
Repository
Last updated
3 days ago
Downloads
39
README

#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)
} derive(Eq, 
Debug)

Failures found while validating a contract descriptor before use.

#
ContractDefinitionError::message

source
fn ContractDefinitionError::message(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.

#
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.

#
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