Issho.Event (Issho v0.4.0)

Copy Markdown View Source

Something that happened in a room, for whoever acts on it: the app's code, the room's components, agents (Issho.Events).

  • :name: what happened, a dotted name ("document.changed").
  • :room: the room it happened in.
  • :document: the document it is about, or nil.
  • :by: who made it happen (Issho.Identity: a person, an agent and whom it acts for, a service), or nil.
  • :data: what else there is to know, a map of the event's.
  • :at: when, a DateTime in UTC.

Names

Issho's own names, and those its components emit, are reserved, so that every app and component means the same by them:

  • "document.changed": a document accepted a change (data: %{revision: n}). Every document emits it, and so does a component whose content is its own, not an Issho document's (Masu's rows: data: %{op: :update, count: n}).
  • "person.joined" and "person.left": someone entered the room (their first tab, or an agent) or left it (their last), data: %{can: "write"}.
  • "selection.changed": a session's place changed (data: %{place: place, session: id}, the place nil when it has none): what someone selected, in the document's own terms.
  • "agent.started" (%{title, steps}) and "agent.finished" (%{title, summary}): an agent began or ended a task (Issho.Work); "agent.interrupted" (%{agent: key, action: "pause" | "stop"}) and "agent.resumed" (%{agent: key}), by the person who paused, stopped or resumed it; "agent.failed" (%{agent: key, title, reason}): its work crashed (Issho.Work.failed/2).
  • "stream.started", "stream.finished", "stream.failed", "stream.closed": a stream of the room (Issho.Streams), data %{stream: id, kind: kind, for: for} and the reason or outcome.
  • "thread.created", "comment.created", "comment.edited", "comment.deleted", "thread.resolved", "thread.reopened": comments (Issho.Comments).

An app's own events take a name of its own, outside these ("retro.voted", "myapp.toast").

Summary

Types

t()

Functions

to_map(event)

The event as JSON (string keys, the time in ISO 8601), for a model or a browser: who made it happen is their public identity, and the data's values that JSON has no way to say (a struct, a tuple) are inspected.

Types

t()

@type t() :: %Issho.Event{
  at: DateTime.t(),
  by: Issho.Identity.t() | nil,
  data: map(),
  document: String.t() | nil,
  name: String.t(),
  room: String.t()
}

Functions

to_map(event)

@spec to_map(t()) :: map()

The event as JSON (string keys, the time in ISO 8601), for a model or a browser: who made it happen is their public identity, and the data's values that JSON has no way to say (a struct, a tuple) are inspected.