Datastar TypeScript SDK

 !Static Badge !Static Badge !Static Badge

A TypeScript SDK for building reactive web applications with Datastar.

Implements the SDK spec and exposes an abstract ServerSentEventGenerator class that can be used to implement runtime specific classes. NodeJS and web standard runtimes are currently implemented.

Currently it only exposes an http1 server, if you want http2 I recommend you use a reverse proxy until http2 support is added.

Features

- Multi-runtime support: Works with Node.js, Deno, and Bun
- TypeScript support: Full type safety and IntelliSense

Quick Start

$3

Node.js:
``bash
npm install @starfederation/datastar-sdk
`
`javascript
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";
`

Deno:
`typescript
// No installation needed, import directly from npm
import { ServerSentEventGenerator } from "npm:@starfederation/datastar-sdk/web";
`

Bun:
`bash
bun add @starfederation/datastar-sdk
`
`javascript
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/web";
`

$3

Here's a simple example in Node showing how to read client signals and send back element patches:

`javascript
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";

// Read signals from the client request
const reader = await ServerSentEventGenerator.readSignals(req);

if (!reader.success) {
console.error('Error reading signals:', reader.error);
return;
}

// Stream updates back to the client
ServerSentEventGenerator.stream(req, res, (stream) => {
// Patch signals
stream.patchSignals(JSON.stringify({ foo: reader.signals.foo }));

// Patch DOM elements
stream.patchElements(

| Runtime | Example Location | How to Run | Try Online |
|---------|-----------------|------------|------------|
| Node.js | examples/node/node.js | Instructions | StackBlitz |
| Deno | examples/deno/deno.ts | Instructions | Val.town |
| Bun | examples/bun/bun.ts | Instructions | Replit |

Each example creates a simple web server demonstrating:
- Signal handling from client requests
- Element patching for DOM updates
- Real-time communication via Server-Sent Events

$3

1. Clone the repository
2. Navigate to the specific example directory (e.g., examples/node/)
3. Follow the instructions in the example's README file
4. Visit http://localhost:3000 in your browser

> [!NOTE]
> The npm run serve- and deno task serve- commands in the root directory are for SDK development and testing, not for running the user examples.

API Reference

$3

The main class for handling Datastar communication.

#### Static Methods

##### readSignals(request)
Reads signals from a client request.

Parameters:
- request: HTTP request object

Returns:
`typescript
{
success: boolean;
signals?: Record;
error?: string;
}
`

##### stream(request, response, callback, options?)
Creates a Server-Sent Event stream for real-time communication.

Parameters:
- request: HTTP request object
- response: HTTP response object
- callback: Function that receives a stream instance
- options: Optional configuration object

Options:
`typescript
{
onError?: (error: Error) => void;
onAbort?: () => void;
keepalive?: boolean;
}
`

> [!IMPORTANT]
> When keepalive: true is set, the stream will not be closed automatically after the callback finishes. You are responsible for calling stream.close() to end the stream.

#### Stream Instance Methods

##### patchSignals(signals, options?)
Patches signals into the client signal store.

Parameters:
- signals: JSON string containing signal data to patch
- options: Optional configuration object with onlyIfMissing boolean

Example:
`javascript
stream.patchSignals(JSON.stringify({ foo: "bar", count: 42 }));
`

##### patchElements(elements, options?)
Patches HTML elements into the client DOM.

Parameters:
- elements: HTML string containing elements to patch
- options: Optional configuration object with mode and selector

Options:
- mode: Patch mode - "outer", "inner", "replace", "prepend", "append", "before", "after", "remove"
- selector: CSS selector for targeting elements (required for some modes)
- useViewTransition: Whether to use View Transition API

Example:
`javascript
stream.patchElements('

##### removeElements(selector?, elements?, options?)
Removes elements from the client DOM by selector or by HTML string with IDs.

Parameters:
- selector: CSS selector for elements to remove (optional; mutually exclusive with elements)
- elements: HTML string of elements with IDs to remove (optional; required if selector is not provided)
- options: Optional configuration object with eventId, retryDuration

Examples:
`javascript
// Remove by selector
stream.removeElements('#feed, #otherid');
// Remove by HTML elements with IDs
stream.removeElements(undefined, '

##### removeSignals(signalKeys, options?)
Removes one or more signals from the client signal store.

Parameters:
- signalKeys: The signal key or array of keys to remove
- options: Optional configuration object with onlyIfMissing, eventId, retryDuration

Examples:
`javascript
// Remove a single signal
stream.removeSignals('foo');
// Remove multiple signals
stream.removeSignals(['foo', 'bar']);
`

##### executeScript(script, options?)
Executes a script on the client by sending a