Datastar-Pharo-SDK

README excerpt

# Datastar SDK for Pharo

A spec-compliant implementation of the [Datastar](https://data-star.dev) real-time hypermedia protocol for Pharo Smalltalk. This SDK allows you to push live DOM updates, signals, and scripts from Pharo to the browser using Server-Sent Events (SSE).

## Features

- **Spec-Compliant SSE**: Implements the official Datastar ADR for `patch-elements` and `patch-signals`.
- **Zinc Integration**: Purpose-built `DatastarLiveEntity` for non-blocking, infinite streaming in Zinc.
- **Fluent API**: A `DatastarGenerator` to chain updates without manual string manipulation.
- **Portability**: Built using standard Pharo protocols (no external framework dependencies like Seaside or Grease required).
- **JSON Safety**: Automatic serialization of Pharo objects (DateAndTime, Dictionaries, etc.) into web-safe JSON.

## Installation

To install the Datastar SDK, execute the following Metacello script in your Pharo Playground:

```smalltalk
Metacello new
    baseline: 'DatastarSDK';
repository: 'github://NathanFrund/Datastar-Pharo-SDK:main/src';
    load.
```

## Quick Start: The Live Clock

This example creates a server-side clock that pushes a new time to the browser every second.

### 1. The Server Handler
In your `ZnServer` delegate (e.g., your `TestServer`), define the streaming route:

```smalltalk
handleClockRequest: request
    ^ DatastarSSE streamingResponse: [ :stream |
        | generator |
        generator := DatastarGenerator on: stream.
        
        [ 10 timesRepeat: [ 
            generator patchElements: ('<div id="clock">Time is: ', Time now asString, '</div>').
            (Delay forSeconds: 1) wait.
        ] ] ensure: [ stream close ]
    ]
```

### 2. The HTML Page
In your frontend HTML, use the Datastar attributes to connect to the stream:

```html
<div id="clock" data-init="@get('/updates-clock')">
    Connecting to Pharo...
</div>
```

## Architecture

The SDK is composed of three primary layers:

1.  **`DatastarLiveEntity`**: The bridge to Zinc. It handles the HTTP "handshake" and keeps the socket open.
2.  **`DatastarSSE`**: The protocol layer. It formats Smalltalk data into the specific `event:` and `data:` lines required by Datastar.
3.  **`DatastarGenerator`**: The developer-facing API. It provides a "safe-write" environment to prevent server crashes if a browser disconnects.

## API Overview

### Patching Elements
Update the DOM by sending HTML fragments.
```smalltalk
generator patchElements: '<div id="status">Active</div>'.
```

### Updating Signals
Update client-side state/variables via JSON Merge Patch.
```smalltalk
generator patchSignals: { #user -> 'Guest'. #count -> 42 } asDictionary.
```

### Executing Scripts
Run arbitrary JavaScript on the client.
```smalltalk
generator executeScript: 'console.log("Hello from Pharo!")'.
```

## Running Tests

The SDK comes with a full suite of unit tests covering protocol integrity and generator resilience. To run them, open the **Test Runner** and search for:

- `DatastarSSETest`
- `DatastarGeneratorTest`
- `DatastarLiveEntityTest`

## More Examples

Check the `examples/` directory for a complete `TestServer` with:
- Live clock with signals
- Element patching demo
- JavaScript execution demo

## License

Distributed under the MIT License.
Description

Details

README excerpt
