@bv.event — declare an event source

Overview

An event in beava is the typed input you push into the server. Every app.push(...) call references an event by name, and that name has to be registered first — either as a fresh source (class form) or as a derivation chained on top of an existing one (def form).

The decorator has two shapes:

• Class form — @bv.event class Click: .... Type annotations on the class body become the wire schema.
• Def form — @bv.event def BigClick(click: Click): .... The function body returns a chain expression; the decorator captures it as a stable, addressable derivation.

import beava as bv

# Class form — declares a fresh event source.
@bv.event
class Click:
    user_id: str
    page:    str

# Def form — derives a new event from the source above.
@bv.event
def BigClick(click: Click):
    return click.filter(bv.col("page") == "/checkout")

Class form

Apply @bv.event to a plain Python class. Each annotated attribute becomes a column in the wire schema; types are mapped str → "str", int → "i64", float → "f64", bool → "bool". Anything else is coerced to "str".

@bv.event
class Login:
    user_id:    str
    success:    bool
    latency_ms: int

The decorator returns the same class with chain methods attached as static methods, so you can write Login.filter(...) or Login.group_by(...).agg(...) directly without instantiating it. The class also gains state attributes (Login._name, Login._schema, Login._chain, ...) that the SDK uses to walk the descriptor tree at register time.

When you pass Login to app.register(...), it serializes to:

{
  "kind": "event",
  "name": "Login",
  "schema": {
    "fields": {
      "user_id":    "str",
      "success":    "bool",
      "latency_ms": "i64"
    },
    "optional_fields": []
  }
}

Once registered, push events by name:

curl -X POST http://localhost:8080/push \
  -H "content-type: application/json" \
  -d '{"event": "Login", "data": {"user_id": "alice", "success": true, "latency_ms": 142}}'

Def form

Apply @bv.event to a function that takes one or more decorated upstream events as parameters and returns a chain expression. The decorator captures the chain under the function's name, registering it as a derivation node on the wire.

@bv.event
class Click:
    user_id: str
    page:    str

@bv.event
def CheckoutClick(click: Click):
    return click.filter(bv.col("page") == "/checkout")

Why the def form exists. The chain methods (filter, select, with_columns, ...) return anonymous EventDerivation objects with auto-generated names like Click__derived_1. Those auto-names are not addressable on the wire — the server's apply-time routing index keys derivations by their declared upstream name, and only stable names survive the round-trip. @bv.event def wraps a chain into a stable name ("CheckoutClick") so downstream @bv.tables can declare it as their upstream and so you can push it by name from the client.

If you pass a raw chain expression (e.g. Click.filter(...).named("X")) to app.register(...), the SDK raises RegistrationError with the canonical rewrite — wrap it in @bv.event def instead.

Constraints on the function body

• Must declare at least one parameter; each parameter's annotation must resolve to an @bv.event-decorated class or function.
• Must return an EventDerivation (the result of a chain method). Returning anything else raises TypeError.
• The function body runs once at decorator time with the upstream descriptors as arguments. It is not invoked per push; the server replays the chain on every event.

Optional kwargs

The decorator-factory shape @bv.event(...) accepts per-source knobs. They are stored on the EventSource and forwarded to the server at register time.

@bv.event(
    keep_events_for="30d",
    dedupe_key="id",
    dedupe_window="5m",
)
class Login:
    id:      str
    user_id: str

Wire shape

At register time the SDK serializes each @bv.event descriptor into a JSON node and posts the array as {"nodes": [...]} to the server. The class form emits a node with kind: "event"; the def form emits kind: "derivation" with the upstream's name and the chain ops.

{
  "kind": "event",
  "name": "Click",
  "schema": {
    "fields": {
      "user_id": "str",
      "page":    "str"
    },
    "optional_fields": []
  }
}

{
  "kind": "derivation",
  "name": "CheckoutClick",
  "output_kind": "event",
  "upstreams": ["Click"],
  "ops": [
    { "op": "filter", "expr": "page == '/checkout'" }
  ],
  "schema": { "fields": {...}, "optional_fields": [] }
}

The full envelope and per-field semantics are documented at HTTP /register.

Common questions

Where to go next

You've declared the inputs. The next step is to declare the per-entity feature tables that aggregate them: