Datastar TypeScript SDK

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

Installation & Import

Node.js:

npm install @starfederation/datastar-sdk

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

Deno:

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

Bun:

bun add @starfederation/datastar-sdk

import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/web";

Basic Usage

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

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(`<div id="toMerge">Hello <span data-text="$foo">${reader.signals.foo}</span></div>`);
});

See examples for other runtimes below.

Examples

Runtime-Specific Examples

| 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

Running Examples

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

ServerSentEventGenerator

The main class for handling Datastar communication.

Static Methods

readSignals(request)

Reads signals from a client request.

Parameters:

• request: HTTP request object

Returns:

{
    success: boolean;
    signals?: Record<string, any>;
    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:

{
    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:

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:

stream.patchElements('<div id="myDiv">Updated content</div>');

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:

// Remove by selector
stream.removeElements('#feed, #otherid');
// Remove by HTML elements with IDs
stream.removeElements(undefined, '<div id="first"></div><div id="second"></div>');

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:

// 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 tag via SSE.

Parameters:

• script: The JavaScript code to execute
• options: Optional configuration object:
  • autoRemove: If true (default), adds data-effect="el.remove()" to the script tag
  • attributes: Object of script tag attributes (preferred)
  • eventId, retryDuration

Examples:

// Execute a simple script
stream.executeScript('console.log("Hello from server!")');

// Execute a script and keep it in the DOM
stream.executeScript('alert("Persistent!")', { autoRemove: false });

// Execute with custom attributes (object form preferred)
stream.executeScript('doSomething()', { attributes: { type: "module", async: "true" } });

Development

Prerequisites

To develop or contribute to this SDK, you'll need:

• Deno (primary development environment)
• Node.js (for Node.js compatibility testing)
• Bun (for Bun compatibility testing)
• Go (required for running the Go test suite)

Building

Build the npm package:

deno run -A build.ts

The above will pick the version from the src/consts.ts file. If you want to specify the version, use:

deno run -A build.ts VERSION

[!NOTE] For Developers: The build process includes test files in the npm/ directory for local testing, but they are excluded from the published npm package via .npmignore. Test files are built into npm/esm/test/ and npm/script/test/ directories to support the test scripts (npm run test-node, etc.), but these directories are not included when publishing to the npm registry.

Testing

To run all tests for Node.js, Deno, and Bun (mirroring CI):

bash test/run-all.sh

• This script will:
  • Check for required tools (deno, node, bun, go, git)
  • Clone or update the core datastar repo for test files (in /datastar/, which is gitignored)
  • Build the SDK
  • Start test servers for each runtime
  • Run the Go test suite against each server
  • Print results and logs

Note: This is the same script used by GitHub Actions for CI.

Project Structure

typescript/
├── src/                  # SDK source code
│   ├── node/             # Node.js-specific implementation
│   ├── web/              # Web standards implementation (Deno/Bun)
│   └── abstract/         # Abstract base classes
├── examples/             # Example apps for each runtime
│   ├── node/
│   ├── deno/
│   └── bun/
├── test/                 # Unified test runner and test entrypoints
└── datastar/             # (gitignored) Cloned core repo for Go test files (used by test/run-all.sh)

Runtime Support

Node.js

• Import: @starfederation/datastar-sdk/node
• Requires: Node.js 18+
• Uses Node.js-specific HTTP APIs

Deno

• Import: npm:@starfederation/datastar-sdk/web
• Requires: Deno 1.30+
• Uses Web Standards APIs

Bun

• Import: @starfederation/datastar-sdk/web
• Requires: Bun 1.0+
• Uses Web Standards APIs

Custom Implementations

To support additional runtimes or frameworks, extend the abstract ServerSentEventGenerator class from ./src/abstractServerSentEventGenerator.ts.

You'll need to implement:

• constructor: Initialize runtime-specific components
• readSignals: Parse signals from requests
• stream: Create SSE streams
• send: Send data to clients

The abstract class provides these public methods:

• patchElements(elements, options?): Patch HTML elements
• patchSignals(signals, options?): Patch signal data
• removeElements(selector?, elements?, options?): Remove elements by selector or HTML string
• removeSignals(signalKeys, options?): Remove one or more signals
• executeScript(script, options?): Execute a script on the client