### Install Datastar SDK

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Install the Datastar SDK using npm for Node.js or bun add for Bun.

```bash
# Node.js
npm install @starfederation/datastar-sdk

# Bun
bun add @starfederation/datastar-sdk
```

--------------------------------

### Install Datastar SDK for Bun

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Use bun add to install the Datastar SDK for Bun environments.

```bash
bun add @starfederation/datastar-sdk
```

--------------------------------

### Install Datastar SDK for Node.js

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Use npm to install the Datastar SDK for Node.js environments.

```bash
npm install @starfederation/datastar-sdk
```

--------------------------------

### Basic Datastar SDK Usage in Node.js

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Example demonstrating how to read client signals and send back element patches using the Node.js runtime. Ensure the ServerSentEventGenerator is imported for Node.js.

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

--------------------------------

### Run All Tests

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Executes all tests for Node.js, Deno, and Bun, mirroring the CI environment. This script checks for required tools, clones/updates the core datastar repo, builds the SDK, starts test servers, and runs the Go test suite.

```bash
bash test/run-all.sh
```

--------------------------------

### Import ServerSentEventGenerator for Deno

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Import the ServerSentEventGenerator class directly from npm for Deno runtime. No installation is needed.

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

--------------------------------

### Implement Custom SSE Generator in TypeScript

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Extend the abstract ServerSentEventGenerator to create a custom runtime implementation. This example shows how to integrate with a WritableStreamDefaultWriter for sending events.

```typescript
import { ServerSentEventGenerator as AbstractSSEGenerator } from "@starfederation/datastar-sdk/abstract";
import type { DatastarEventOptions, EventType, StreamOptions } from "@starfederation/datastar-sdk";

export class MyRuntimeSSEGenerator extends AbstractSSEGenerator {
  private writer: WritableStreamDefaultWriter<Uint8Array>;
  private encoder = new TextEncoder();

  protected constructor(writer: WritableStreamDefaultWriter<Uint8Array>) {
    super();
    this.writer = writer;
  }

  protected override send(
    event: EventType,
    dataLines: string[],
    options: DatastarEventOptions,
  ): string[] {
    const lines = super.send(event, dataLines, options) as string[];
    // Write all lines as a single encoded chunk
    this.writer.write(this.encoder.encode(lines.join("")));
    return lines;
  }

  public override close(): void {
    this.writer.close();
  }

  // Required static factory method
  static stream(
    onStart: (stream: MyRuntimeSSEGenerator) => Promise<void> | void,
    options?: StreamOptions,
  ): Response {
    let generatorRef: MyRuntimeSSEGenerator;
    const {readable, writable} = new TransformStream<Uint8Array>();
    const writer = writable.getWriter();

    (async () => {
      const generator = new MyRuntimeSSEGenerator(writer);
      try {
        const result = onStart(generator);
        if (result instanceof Promise) await result;
        if (!options?.keepalive) generator.close();
      } catch (err) {
        if (options?.onError) await options.onError(err);
        generator.close();
      }
    })();

    return new Response(readable, {
      headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
    });
  }

  static async readSignals(request: Request) {
    // Delegate to web implementation or implement custom parsing
    const { ServerSentEventGenerator: WebSSE } = await import("@starfederation/datastar-sdk/web");
    return WebSSE.readSignals(request);
  }
}

```

--------------------------------

### Bun Full Server with Datastar

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Create a Bun server for serving HTML and handling Server-Sent Events. Leverages the '@starfederation/datastar-sdk/web' package.

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

Bun.serve({
  port: 3000,
  routes: {
    "/": () =>
      new Response(
        `<html>
          <head>
            <script type="module"
              src="https://cdn.jsdelivr.net/gh/starfederation/datastar@1.0.1/bundles/datastar.js">
            </script>
          </head>
          <body>
            <div id="toMerge"
                 data-signals:foo="'World'"
                 data-init="@get('/merge')">Hello</div>
          </body>
        </html>`,
        { headers: { "Content-Type": "text/html" } }
      ),

    "/merge": async (req: Request) => {
      const reader = await ServerSentEventGenerator.readSignals(req);

      if (!reader.success) {
        return new Response(`Error: ${reader.error}`, { status: 400 });
      }

      return ServerSentEventGenerator.stream((stream) => {
        stream.patchElements(
          `<div id="toMerge">Hello ${reader.signals.foo}</div>`
        );
      });
    },
  },
  fetch(req) {
    return new Response("Not found", { status: 404 });
  },
});
```

--------------------------------

### Node.js Full Server with Datastar

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Set up a Node.js HTTP server to serve an HTML page and handle Server-Sent Events for dynamic updates. Requires the '@starfederation/datastar-sdk/node' package.

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

createServer(async (req, res) => {
  if (req.url === "/") {
    res.setHeader("Content-Type", "text/html");
    res.end(
      `
      <html>
        <head>
          <script type="module"
            src="https://cdn.jsdelivr.net/gh/starfederation/datastar@1.0.1/bundles/datastar.js">
          </script>
        </head>
        <body>
          <div id="toMerge"
               data-signals:foo="'World'"
               data-init="@get('/merge')">Hello</div>
        </body>
      </html>
    `
    );
  } else if (req.url?.includes("/merge")) {
    const reader = await ServerSentEventGenerator.readSignals(req);

    if (!reader.success) {
      res.end(`Error: ${reader.error}`);
      return;
    }

    await ServerSentEventGenerator.stream(req, res, (stream) => {
      stream.patchElements(
        `<div id="toMerge">Hello ${reader.signals.foo}</div>`
      );
    }, {
      onError: (err) => console.error("SSE error:", err),
    });
  }
}).listen(3000, "127.0.0.1", () =>
  console.log("Server running at http://127.0.0.1:3000/")
);
```

--------------------------------

### Using DataStar SDK with Bun

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Instructions for importing and using the DataStar SDK within a Bun environment. Requires Bun version 1.0 or higher and utilizes Web Standards APIs.

```APIDOC
## Bun Usage

### Import
`@starfederation/datastar-sdk/web`

### Requirements
- Bun 1.0+
- Uses Web Standards APIs
```

--------------------------------

### Deno Full Server with Datastar

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Implement a Deno server to serve an HTML page and manage Server-Sent Events. Uses the 'npm:@starfederation/datastar-sdk/web' package.

```typescript
import { ServerSentEventGenerator } from "npm:@starfederation/datastar-sdk/web";

Deno.serve(async (req: Request) => {
  const url = new URL(req.url);

  if (url.pathname === "/") {
    return new Response(
      `<html>
        <head>
          <script type="module"
            src="https://cdn.jsdelivr.net/gh/starfederation/datastar@1.0.1/bundles/datastar.js">
          </script>
        </head>
        <body>
          <div id="toMerge"
               data-signals:foo="'World'"
               data-init="@get('/merge')">Hello</div>
        </body>
      </html>`,
      { headers: { "Content-Type": "text/html" } }
    );
  }

  if (url.pathname.includes("/merge")) {
    const reader = await ServerSentEventGenerator.readSignals(req);

    if (!reader.success) {
      return new Response(`Error: ${reader.error}`, { status: 400 });
    }

    return ServerSentEventGenerator.stream((stream) => {
      stream.patchElements(
        `<div id="toMerge">Hello ${reader.signals.foo}</div>`
      );
    });
  }

  return new Response("Not found", { status: 404 });
});
```

--------------------------------

### Import ServerSentEventGenerator for Bun

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Import the ServerSentEventGenerator class for Bun runtime. This is the same import path as for Deno.

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

--------------------------------

### Build NPM Package

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Builds the npm package for the SDK. Specify a version number as an argument to override the version defined in `src/consts.ts`.

```bash
deno run -A build.ts
```

```bash
deno run -A build.ts VERSION
```

--------------------------------

### Import ServerSentEventGenerator

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Import the ServerSentEventGenerator class for Node.js, Deno, or Bun environments.

```typescript
// Node.js
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";

// Deno (no install needed)
import { ServerSentEventGenerator } from "npm:@starfederation/datastar-sdk/web";

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

--------------------------------

### ServerSentEventGenerator.stream()

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Opens a Server-Sent Events stream and executes the onStart callback with a live ServerSentEventGenerator instance. The stream closes automatically when onStart returns unless keepalive: true is set.

```APIDOC
## `ServerSentEventGenerator.stream(...)` — Open an SSE Stream

Opens a Server-Sent Events stream and executes the `onStart` callback with a live `ServerSentEventGenerator` instance. The stream closes automatically when `onStart` returns unless `keepalive: true` is set. The Node.js variant takes `(req, res, onStart, options?)` and writes directly to `ServerResponse`; the Web Standards variant takes `(onStart, options?)` and returns a `Response`.

```typescript
// Node.js — basic stream with error handling
import { createServer } from "node:http";
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";

createServer(async (req, res) => {
  await ServerSentEventGenerator.stream(req, res, async (stream) => {
    stream.patchElements('<div id="status">Processing…</div>');
    await new Promise((r) => setTimeout(r, 1000));
    stream.patchElements('<div id="status">Done!</div>');
    stream.patchSignals(JSON.stringify({ done: true }));
  }, {
    onError: (err) => console.error("Stream error:", err),
    onAbort: () => console.log("Client disconnected"),
  });
}).listen(3000);

// Web Standards — keepalive stream closed manually
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/web";

async function liveHandler(req: Request): Promise<Response> {
  let streamRef: typeof ServerSentEventGenerator.prototype;

  return ServerSentEventGenerator.stream((stream) => {
    // Non-blocking: stream stays open because keepalive: true
    const interval = setInterval(() => {
      stream.patchSignals(JSON.stringify({ tick: Date.now() }));
    }, 500);

    // Store ref to close later from outside (e.g., on some event)
    setTimeout(() => {
      clearInterval(interval);
      stream.close(); // manually close when keepalive is true
    }, 5000);
  }, {
    keepalive: true,
    onAbort: (reason) => console.log("Aborted:", reason),
    responseInit: { headers: { "X-Custom": "header" } },
  });
}
```
```

--------------------------------

### Extending ServerSentEventGenerator

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Guidance on how to extend the abstract `ServerSentEventGenerator` class to support additional runtimes or frameworks. This involves implementing specific methods to handle runtime-specific logic.

```APIDOC
## 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
```

--------------------------------

### Import ServerSentEventGenerator for Node.js

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Import the ServerSentEventGenerator class specifically for Node.js runtime.

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

--------------------------------

### executeScript

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Executes a script on the client by sending a <script> tag via SSE. Supports options for auto-removal, custom attributes, and error handling.

```APIDOC
## executeScript(script, options?)

### Description
Executes a script on the client by sending a <script> tag via SSE.

### Parameters
- **script** (string) - The JavaScript code to execute
- **options** (object) - Optional configuration object:
  - **autoRemove** (boolean) - If true (default), adds data-effect="el.remove()" to the script tag
  - **attributes** (object) - Object of script tag attributes (preferred)
  - **eventId** (any) - Optional event identifier
  - **retryDuration** (number) - Optional retry duration in milliseconds

### Examples
```javascript
// 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" } });
```
```

--------------------------------

### Patch Signals into Client Store

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Use this to patch JSON signals into the client's signal store. The `options` parameter can include `onlyIfMissing` to only patch signals that do not already exist.

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

--------------------------------

### stream.patchSignals(signals, options?)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Sends a datastar-patch-signals SSE event that updates the client-side signal store using RFC 7386 JSON Merge Patch semantics. The signals parameter must be a JSON string. Use onlyIfMissing: true to only set signals that do not already exist on the client.

```APIDOC
## `stream.patchSignals(signals, options?)` — Patch Client Signal Store

Sends a `datastar-patch-signals` SSE event that updates the client-side signal store using RFC 7386 JSON Merge Patch semantics. The `signals` parameter must be a JSON string. Use `onlyIfMissing: true` to only set signals that do not already exist on the client.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Patch a single signal
  stream.patchSignals(JSON.stringify({ isLoading: false }));

  // Patch nested signals
  stream.patchSignals(JSON.stringify({
    user: { name: "Alice", role: "admin" },
    pagination: { page: 2, total: 50 },
  }));

  // Only patch if the client doesn't already have these signals (initialization)
  stream.patchSignals(JSON.stringify({ theme: "dark", lang: "en" }), {
    onlyIfMissing: true,
  });

  // With event tracking options
  stream.patchSignals(JSON.stringify({ counter: 10 }), {
    eventId: "counter-update-1",
    retryDuration: 3000,
  });
});
```
```

--------------------------------

### Read Client Signals in Web Standards

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Parses client-sent signals from an HTTP request in a Web Standards environment (Deno/Bun). Returns a Response object with a stream for SSE.

```typescript
// Web Standards (Deno / Bun) example
// GET /action?datastar={"username":"Alice","count":42}
async function handler(req: Request): Promise<Response> {
  const result = await ServerSentEventGenerator.readSignals(req);

  if (!result.success) {
    return new Response(result.error, { status: 400 });
  }

  return ServerSentEventGenerator.stream((stream) => {
    stream.patchSignals(JSON.stringify({ ack: true }));
  });
}

```

--------------------------------

### stream.patchElements(elements, options?)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Sends a `datastar-patch-elements` SSE event to morph, insert, replace, or remove HTML elements in the client DOM. Elements must have `id` attributes when no `selector` is specified. Supports eight patch modes: `outer` (default), `inner`, `replace`, `prepend`, `append`, `before`, `after`, `remove`.

```APIDOC
## `stream.patchElements(elements, options?)` — Patch DOM Elements

Sends a `datastar-patch-elements` SSE event to morph, insert, replace, or remove HTML elements in the client DOM. Elements must have `id` attributes when no `selector` is specified. Supports eight patch modes: `outer` (default), `inner`, `replace`, `prepend`, `append`, `before`, `after`, `remove`.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Default mode "outer": morph entire element by ID
  stream.patchElements('<div id="card">Updated card content</div>');

  // Append a new item inside a list container
  stream.patchElements('<li id="item-99">New item</li>', {
    selector: "#todo-list",
    mode: "append",
  });

  // Replace (reset state) using selector
  stream.patchElements('<section id="hero"><h1>New Hero</h1></section>', {
    mode: "replace",
  });

  // Patch SVG element in svg namespace
  stream.patchElements('<circle id="dot" cx="50" cy="50" r="10"/>', {
    selector: "#my-svg",
    mode: "append",
    namespace: "svg",
  });

  // Animate with View Transition API
  stream.patchElements('<div id="banner">Flash message</div>', {
    useViewTransition: true,
  });

  // Insert before a specific element
  stream.patchElements('<div id="notice">Above the fold</div>', {
    selector: "#main-content",
    mode: "before",
  });
});
```
```

--------------------------------

### Execute Script on Client

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Executes JavaScript code on the client by sending a script tag via SSE. By default, the script tag is removed after execution (`autoRemove: true`). Custom attributes can be provided via the `attributes` option.

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

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

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

--------------------------------

### Patch HTML Elements into Client DOM

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Patch HTML content into the client's DOM. The `options` parameter allows specifying a `mode` (e.g., 'outer', 'inner', 'replace') and a CSS `selector` for targeting elements.

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

--------------------------------

### Manually Close SSE Stream (Node.js)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Demonstrates manually closing an SSE stream using `stream.close()` when `keepalive: true` is set. This is necessary when the stream needs to remain open for a period and then be explicitly closed after a condition is met.

```typescript
// Node.js: keepalive stream closed after a timed event
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";

createServer((req, res) => {
  ServerSentEventGenerator.stream(req, res, (stream) => {
    let count = 0;
    const interval = setInterval(() => {
      stream.patchSignals(JSON.stringify({ count: ++count }));
      if (count >= 5) {
        clearInterval(interval);
        stream.close(); // explicitly close the stream
      }
    }, 1000);
  }, { keepalive: true });
}).listen(3000);
```

--------------------------------

### stream.close()

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Manually closes the underlying SSE stream. Required when using keepalive: true in stream(), since the stream will not auto-close after the onStart callback returns.

```APIDOC
## `stream.close()` — Manually Close the Stream

Closes the underlying SSE stream. Required when using `keepalive: true` in `stream()`, since the stream will not auto-close after the `onStart` callback returns.

```typescript
// Node.js: keepalive stream closed after a timed event
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";

createServer((req, res) => {
  ServerSentEventGenerator.stream(req, res, (stream) => {
    let count = 0;
    const interval = setInterval(() => {
      stream.patchSignals(JSON.stringify({ count: ++count }));
      if (count >= 5) {
        clearInterval(interval);
        stream.close(); // explicitly close the stream
      }
    }, 1000);
  }, { keepalive: true });
}).listen(3000);

// Web Standards: same pattern returns a Response
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/web";

function timedStream(): Response {
  return ServerSentEventGenerator.stream((stream) => {
    setTimeout(() => {
      stream.patchElements('<div id="result">Finished</div>');
      stream.close();
    }, 3000);
  }, { keepalive: true });
}
```
```

--------------------------------

### stream.executeScript(script, options?)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Sends a datastar-patch-elements event that appends a <script> tag to document.body, executing arbitrary JavaScript in the browser. By default the script tag includes data-effect="el.remove()" to auto-remove itself after execution. Set autoRemove: false to keep the script in the DOM.

```APIDOC
## `stream.executeScript(script, options?)` — Execute Client-Side JavaScript

Sends a `datastar-patch-elements` event that appends a `<script>` tag to `document.body`, executing arbitrary JavaScript in the browser. By default the script tag includes `data-effect="el.remove()"` to auto-remove itself after execution. Set `autoRemove: false` to keep the script in the DOM.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Execute a one-shot script (auto-removed from DOM)
  stream.executeScript('console.log("Hello from server!")');

  // Trigger a client-side notification
  stream.executeScript('window.showNotification("Upload complete!")');

  // Keep the script in the DOM (e.g., for a persistent module)
  stream.executeScript('initAnalytics()', { autoRemove: false });

  // Execute as ES module with additional attributes (object form preferred)
  stream.executeScript('import("/dynamic-module.js").then(m => m.init())', {
    attributes: { type: "module", async: "true" },
  });

  // Advanced: attributes as array of strings
  stream.executeScript('doWork()', {
    attributes: ['type="module"', "defer"],
    autoRemove: true,
  });
});
```
```

--------------------------------

### Open an SSE Stream with ServerSentEventGenerator.stream()

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Opens a Server-Sent Events stream. The Node.js variant takes request and response objects, while the Web Standards variant returns a Response object. The stream closes automatically when the onStart callback returns, unless keepalive is true.

```typescript
// Node.js — basic stream with error handling
import { createServer } from "node:http";
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";

createServer(async (req, res) => {
  await ServerSentEventGenerator.stream(req, res, async (stream) => {
    stream.patchElements('<div id="status">Processing…</div>');
    await new Promise((r) => setTimeout(r, 1000));
    stream.patchElements('<div id="status">Done!</div>');
    stream.patchSignals(JSON.stringify({ done: true }));
  }, {
    onError: (err) => console.error("Stream error:", err),
    onAbort: () => console.log("Client disconnected"),
  });
}).listen(3000);
```

```typescript
// Web Standards — keepalive stream closed manually
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/web";

async function liveHandler(req: Request): Promise<Response> {
  let streamRef: typeof ServerSentEventGenerator.prototype;

  return ServerSentEventGenerator.stream((stream) => {
    // Non-blocking: stream stays open because keepalive: true
    const interval = setInterval(() => {
      stream.patchSignals(JSON.stringify({ tick: Date.now() }));
    }, 500);

    // Store ref to close later from outside (e.g., on some event)
    setTimeout(() => {
      clearInterval(interval);
      stream.close(); // manually close when keepalive is true
    }, 5000);
  }, {
    keepalive: true,
    onAbort: (reason) => console.log("Aborted:", reason),
    responseInit: { headers: { "X-Custom": "header" } },
  });
}
```

--------------------------------

### Manually Close SSE Stream (Web Standards)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Demonstrates manually closing an SSE stream using `stream.close()` when `keepalive: true` is set in a Web Standards environment. The stream is closed after a timeout and a client-side element is patched.

```typescript
// Web Standards: same pattern returns a Response
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/web";

function timedStream(): Response {
  return ServerSentEventGenerator.stream((stream) => {
    setTimeout(() => {
      stream.patchElements('<div id="result">Finished</div>');
      stream.close();
    }, 3000);
  }, { keepalive: true });
}
```

--------------------------------

### patchSignals

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Patches signals into the client signal store. Accepts a JSON string of signal data and optional configuration.

```APIDOC
## patchSignals(signals, options?)

### Description
Patches signals into the client signal store.

### Parameters
- **signals** (string) - JSON string containing signal data to patch
- **options** (object) - Optional configuration object with `onlyIfMissing` boolean

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

--------------------------------

### patchElements

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Patches HTML elements into the client DOM. Accepts an HTML string and optional configuration for patching mode and element targeting.

```APIDOC
## patchElements(elements, options?)

### Description
Patches HTML elements into the client DOM.

### Parameters
- **elements** (string) - HTML string containing elements to patch
- **options** (object) - Optional configuration object with `mode` and `selector`
  - **mode** (string) - Patch mode: "outer", "inner", "replace", "prepend", "append", "before", "after", "remove"
  - **selector** (string) - CSS selector for targeting elements (required for some modes)
  - **useViewTransition** (boolean) - Whether to use View Transition API

### Request Example
```javascript
stream.patchElements('<div id="myDiv">Updated content</div>');
```
```

--------------------------------

### ServerSentEventGenerator.readSignals(request)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Parses client-sent signals from an HTTP request. It handles signals from query parameters for GET/DELETE requests and from the request body for POST/PUT/PATCH requests. Returns a success object with signals or an error object.

```APIDOC
## ServerSentEventGenerator.readSignals(request)

### Description
Parses client-sent signals from an HTTP request. For `GET`/`DELETE` requests it reads the `datastar` query parameter; for `POST`/`PUT`/`PATCH` it parses the JSON request body. Returns a discriminated union: `{ success: true, signals }` or `{ success: false, error }`.

### Method
`static readSignals(request: IncomingMessage | Request): Promise<{ success: true; signals: Record<string, Jsonifiable>; } | { success: false; error: string; }>;`

### Parameters
#### Request
- **request** (IncomingMessage | Request) - Required - The incoming HTTP request object.

### Response
- **success** (boolean) - Indicates if the signals were parsed successfully.
- **signals** (Record<string, Jsonifiable>) - An object containing the parsed signals if successful.
- **error** (string) - An error message if parsing failed.
```

--------------------------------

### Execute Client-Side JavaScript

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Use `executeScript` to send a `datastar-patch-elements` event that appends a `<script>` tag to `document.body`, executing arbitrary JavaScript in the browser. By default the script tag includes `data-effect="el.remove()"` to auto-remove itself after execution. Set `autoRemove: false` to keep the script in the DOM.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Execute a one-shot script (auto-removed from DOM)
  stream.executeScript('console.log("Hello from server!")');

  // Trigger a client-side notification
  stream.executeScript('window.showNotification("Upload complete!")');

  // Keep the script in the DOM (e.g., for a persistent module)
  stream.executeScript('initAnalytics()', { autoRemove: false });

  // Execute as ES module with additional attributes (object form preferred)
  stream.executeScript('import("/dynamic-module.js").then(m => m.init())', {
    attributes: { type: "module", async: "true" },
  });

  // Advanced: attributes as array of strings
  stream.executeScript('doWork()', {
    attributes: ['type="module"', "defer"],
    autoRemove: true,
  });
});
```

--------------------------------

### Read Client Signals in Node.js

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Parses client-sent signals from an HTTP request in a Node.js environment. Handles GET/DELETE via query parameters and POST/PUT/PATCH via request body. Returns a success or error object.

```typescript
// Node.js example
import { createServer } from "node:http";
import { ServerSentEventGenerator } from "@starfederation/datastar-sdk/node";

const server = createServer(async (req, res) => {
  if (req.url?.includes("/action")) {
    const result = await ServerSentEventGenerator.readSignals(req);

    if (!result.success) {
      console.error("Signal parse error:", result.error);
      res.writeHead(400).end(result.error);
      return;
    }

    // result.signals is typed as Record<string, Jsonifiable>
    const { username, count } = result.signals;
    console.log("Received signals:", { username, count });
    // → { username: "Alice", count: 42 }

    ServerSentEventGenerator.stream(req, res, (stream) => {
      stream.patchSignals(JSON.stringify({ count: (count as number) + 1 }));
    });
  }
});

```

--------------------------------

### stream.removeElements(selector?, elements?, options?)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Convenience wrapper around `patchElements` with `mode: "remove"`. Provide either a CSS `selector` to remove all matching elements, or an HTML string of elements with `id` attributes. Exactly one of the two must be supplied.

```APIDOC
## `stream.removeElements(selector?, elements?, options?)` — Remove DOM Elements

Convenience wrapper around `patchElements` with `mode: "remove"`. Provide either a CSS `selector` to remove all matching elements, or an HTML string of elements with `id` attributes. Exactly one of the two must be supplied.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Remove by CSS selector (removes all matching elements)
  stream.removeElements("#notification-banner");

  // Remove multiple elements by selector
  stream.removeElements(".toast-message, #overlay");

  // Remove by providing HTML elements with IDs
  stream.removeElements(
    undefined,
    '<div id="item-1"></div><div id="item-2"></div>'
  );

  // Remove with retry options
  stream.removeElements("#expired-session", undefined, {
    eventId: "remove-session-42",
    retryDuration: 2000,
  });
});
```
```

--------------------------------

### Patch Client Signals with JSON Merge Patch

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Use `patchSignals` to update the client-side signal store using RFC 7386 JSON Merge Patch semantics. The `signals` parameter must be a JSON string. Use `onlyIfMissing: true` to only set signals that do not already exist on the client.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Patch a single signal
  stream.patchSignals(JSON.stringify({ isLoading: false }));

  // Patch nested signals
  stream.patchSignals(JSON.stringify({
    user: { name: "Alice", role: "admin" },
    pagination: { page: 2, total: 50 },
  }));

  // Only patch if the client doesn't already have these signals (initialization)
  stream.patchSignals(JSON.stringify({ theme: "dark", lang: "en" }), {
    onlyIfMissing: true,
  });

  // With event tracking options
  stream.patchSignals(JSON.stringify({ counter: 10 }), {
    eventId: "counter-update-1",
    retryDuration: 3000,
  });
});
```

--------------------------------

### Patch DOM Elements with stream.patchElements()

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Sends a datastar-patch-elements SSE event to morph, insert, replace, or remove HTML elements in the client DOM. Elements must have id attributes when no selector is specified. Supports eight patch modes: outer (default), inner, replace, prepend, append, before, after, remove.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Default mode "outer": morph entire element by ID
  stream.patchElements('<div id="card">Updated card content</div>');

  // Append a new item inside a list container
  stream.patchElements('<li id="item-99">New item</li>', {
    selector: "#todo-list",
    mode: "append",
  });

  // Replace (reset state) using selector
  stream.patchElements('<section id="hero"><h1>New Hero</h1></section>', {
    mode: "replace",
  });

  // Patch SVG element in svg namespace
  stream.patchElements('<circle id="dot" cx="50" cy="50" r="10"/>', {
    selector: "#my-svg",
    mode: "append",
    namespace: "svg",
  });

  // Animate with View Transition API
  stream.patchElements('<div id="banner">Flash message</div>', {
    useViewTransition: true,
  });

  // Insert before a specific element
  stream.patchElements('<div id="notice">Above the fold</div>', {
    selector: "#main-content",
    mode: "before",
  });
});
```

--------------------------------

### ServerSentEventGenerator.stream

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Creates a Server-Sent Event stream for real-time communication. This method facilitates sending updates from the server to the client.

```APIDOC
## stream(request, response, callback, options?)

### Description
Creates a Server-Sent Event stream for real-time communication.

### Method
Static method of ServerSentEventGenerator

### Parameters
#### Path Parameters
- **request** (HTTP request object) - Required - The incoming HTTP request object.
- **response** (HTTP response object) - Required - The outgoing HTTP response object.
- **callback** (Function) - Required - A function that receives a stream instance to send data.
- **options** (object) - Optional - Configuration object for the stream.

##### Options
- **onError** (Function) - Optional - Callback function to handle stream errors.
- **onAbort** (Function) - Optional - Callback function to handle stream abortion.
- **keepalive** (boolean) - Optional - If true, the stream will not close automatically. Manual closing via `stream.close()` is required.
```

--------------------------------

### stream.removeSignals(signalKeys, options?)

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Removes one or more signals from the client signal store by sending a JSON Merge Patch with the specified keys set to null, per RFC 7386 and the Datastar spec.

```APIDOC
## `stream.removeSignals(signalKeys, options?)` — Remove Client Signals

Removes one or more signals from the client signal store by sending a JSON Merge Patch with the specified keys set to `null`, per RFC 7386 and the Datastar spec.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Remove a single signal
  stream.removeSignals("tempToken");

  // Remove multiple signals at once
  stream.removeSignals(["sessionId", "csrfToken", "pendingUpload"]);

  // Remove with event tracking
  stream.removeSignals("authUser", {
    eventId: "logout-event",
    retryDuration: 1000,
  });
});
```
```

--------------------------------

### Remove Signals from Client Store

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Removes one or more signals from the client's signal store. Accepts a single signal key or an array of keys. Optional parameters include `onlyIfMissing`, `eventId`, and `retryDuration`.

```javascript
// Remove a single signal
stream.removeSignals('foo');
```

```javascript
// Remove multiple signals
stream.removeSignals(['foo', 'bar']);
```

--------------------------------

### Remove Client Signals by Key

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

Use `removeSignals` to remove one or more signals from the client signal store by sending a JSON Merge Patch with the specified keys set to `null`, per RFC 7386 and the Datastar spec.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Remove a single signal
  stream.removeSignals("tempToken");

  // Remove multiple signals at once
  stream.removeSignals(["sessionId", "csrfToken", "pendingUpload"]);

  // Remove with event tracking
  stream.removeSignals("authUser", {
    eventId: "logout-event",
    retryDuration: 1000,
  });
});
```

--------------------------------

### Remove DOM Elements with stream.removeElements()

Source: https://context7.com/starfederation/datastar-typescript/llms.txt

A convenience wrapper around patchElements with mode: "remove". Provide either a CSS selector to remove all matching elements, or an HTML string of elements with id attributes. Exactly one of the two must be supplied.

```typescript
ServerSentEventGenerator.stream(req, res, (stream) => {
  // Remove by CSS selector (removes all matching elements)
  stream.removeElements("#notification-banner");

  // Remove multiple elements by selector
  stream.removeElements(".toast-message, #overlay");

  // Remove by providing HTML elements with IDs
  stream.removeElements(
    undefined,
    '<div id="item-1"></div><div id="item-2"></div>'
  );

  // Remove with retry options
  stream.removeElements("#expired-session", undefined, {
    eventId: "remove-session-42",
    retryDuration: 2000,
  });
});
```

--------------------------------

### removeElements

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Removes elements from the client DOM. Can target elements by a CSS selector or by providing an HTML string of elements with IDs.

```APIDOC
## removeElements(selector?, elements?, options?)

### Description
Removes elements from the client DOM by selector or by HTML string with IDs.

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

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

--------------------------------

### ServerSentEventGenerator.readSignals

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Reads signals from a client request. This method is used to capture data sent from the client to the server.

```APIDOC
## readSignals(request)

### Description
Reads signals from a client request.

### Method
Static method of ServerSentEventGenerator

### Parameters
#### Path Parameters
- **request** (HTTP request object) - Required - The incoming HTTP request object.

### Response
#### Success Response
- **success** (boolean) - Indicates if signals were read successfully.
- **signals** (Record<string, any>) - Optional - An object containing the signals if successful.
- **error** (string) - Optional - An error message if reading signals failed.
```

--------------------------------

### removeSignals

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Removes one or more signals from the client signal store. Accepts a single signal key or an array of keys.

```APIDOC
## removeSignals(signalKeys, options?)

### Description
Removes one or more signals from the client signal store.

### Parameters
- **signalKeys** (string | string[]) - The signal key or array of keys to remove
- **options** (object) - Optional configuration object with `onlyIfMissing`, `eventId`, `retryDuration`

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

--------------------------------

### Remove Elements from Client DOM

Source: https://github.com/starfederation/datastar-typescript/blob/main/README.md

Removes elements from the client DOM. Can target elements using a CSS selector or by providing an HTML string of elements with IDs. Options include `eventId` and `retryDuration`.

```javascript
// Remove by selector
stream.removeElements('#feed, #otherid');
```

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.