Client Phase 2: Push Event Example and Test Coverage #15

SeanTAllen · 2026-03-12T02:33:20Z

SeanTAllen
Mar 12, 2026
Maintainer

Context

Server Phase 2 added external message delivery (handle_info, InfoReceiver, PubSub, push_event). Client Phase 1 proactively implemented push message handling — decode and dispatch via LiveView.on(event, callback). The infrastructure is complete end-to-end but never demonstrated: the ticker example works entirely through assign changes → re-render, never calling push_event or on().

Client Phase 2 closes this gap by enhancing the ticker to demonstrate both mechanisms and adding client-side test coverage for push event edge cases.

Change classification: Internal (example enhancement, tests, docs). VERSION is 0.0.0 — no release notes.

Design Decision: Enhance Ticker vs. New Example

Options:

(A) Enhance the ticker example to call push_event in handle_info and use on() in the HTML. Shows both re-render and push event mechanisms working together.

(B) Create a separate example (e.g., "notifications") that demonstrates push events independently.

Recommendation: Option A. The ticker already demonstrates server push via PubSub. Adding push_event shows the full picture — server-rendered DOM updates AND client-side push event handling — in one coherent example. A separate example adds file proliferation for what's a natural extension of the ticker's existing behavior.

Steps

1. Modify `examples/ticker/main.pony`

Add a push_event call in handle_info to send the timer tick count alongside the assign update:

fun ref handle_info(message: Any val, socket: Socket ref) =>
  try
    let current = socket.get_assign("count")?.string()?.i64()?
    socket.assign("count", (current + 1).string())
  end
  match message
  | let n: U64 =>
    socket.push_event("tick",
      JsonObject.update("timer_count", n.i64()))
  end

Uses unqualified JsonObject matching the existing example import convention (use "json").

Demonstrates the key distinction:

Assigns trigger re-renders (server-managed DOM) — the Ticks: N heading updates via morphdom
Push events trigger client-side callbacks (JavaScript-managed behavior) — the #push-log element updates via on() handler

2. Modify `examples/ticker/index.html`

Add a push event handler and a DOM element outside the LiveView container:

<body>
  <div id="lv-root"></div>
  <p id="push-log">Waiting for push events...</p>
  <script src="../../client/dist/livery.iife.js"></script>
  <script>
    var lv = new LiveView({
      url: "ws://localhost:8082/ticker",
      target: document.getElementById("lv-root")
    });
    lv.on("tick", function(payload) {
      document.getElementById("push-log").textContent =
        "Last push: timer tick #" + payload.timer_count;
    });
    lv.connect();
  </script>
</body>

#lv-root: managed by the server (morphdom re-renders)
#push-log: managed by the client (on() callback)

3. Add client tests for push edge cases

Add to client/test/live-view.test.js:

Push with no handler registered — push message arrives, no error thrown
Push handler registered after connect — handler still fires when push arrives
Multiple sequential push events — all dispatched to correct handlers
on() overwrites previous handler for same event — second registration replaces first
Push handlers survive reconnection — after socket close + reconnect, handlers still fire

4. Update `examples/README.md`

Update the ticker entry to mention push events alongside re-renders.

5. Update `CLAUDE.md`

Update the file layout ticker comment to reflect that it also demonstrates push_event and client-side push handling.

6. Build and verify

# Server: build and run tests + examples
make test ssl=openssl_3.0.x

# Client: run tests
cd client && npm test

Files

File	Action
`examples/ticker/main.pony`	Modify
`examples/ticker/index.html`	Modify
`client/test/live-view.test.js`	Modify
`examples/README.md`	Modify
`CLAUDE.md`	Modify

What's Not in Client Phase 2

lv-change / lv-submit (Phase 3 — forms, client + server together)
off() method for unregistering push handlers (no demonstrated need)
params on connect (needs server-side mount(socket, params))
CSS transition hooks
Loading states / connection status UI
Client-side hooks API
npm publishing

SeanTAllen · 2026-03-12T02:54:54Z

SeanTAllen
Mar 12, 2026
Maintainer Author

implemented in #16

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Client Phase 2: Push Event Example and Test Coverage #15

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Client Phase 2: Push Event Example and Test Coverage #15

Uh oh!

SeanTAllen Mar 12, 2026 Maintainer

Context

Design Decision: Enhance Ticker vs. New Example

Steps

1. Modify examples/ticker/main.pony

2. Modify examples/ticker/index.html

3. Add client tests for push edge cases

4. Update examples/README.md

5. Update CLAUDE.md

6. Build and verify

Files

What's Not in Client Phase 2

Replies: 1 comment

Uh oh!

SeanTAllen Mar 12, 2026 Maintainer Author

SeanTAllen
Mar 12, 2026
Maintainer

1. Modify `examples/ticker/main.pony`

2. Modify `examples/ticker/index.html`

4. Update `examples/README.md`

5. Update `CLAUDE.md`

SeanTAllen
Mar 12, 2026
Maintainer Author