Updated TypeScript SDK (#984)

* bring in exsting work from: https://github.com/eduwass/datastar/tree/clean-pr-branch/sdk/typescript

* Update TypeScript SDK: Move test servers files to enhance clarity, modify build process, and adjust tsconfig accordingly.

* Update TypeScript SDK package.json: Add files section to include necessary directories and files for npm packaging. This way we exclude unnecessary example/test dirs from distribution.

* rm leftover files

* update .gitignored editor directories and files

* Enhance README.md with structured notes for SDK usage and build process. Added emphasis on important notes regarding server commands and stream management.

* Add migration plan for Datastar TypeScript SDK: outline key changes, migration tasks, and breaking changes.

Implement 1.1: Update constants and types for new API specification, including renaming and restructuring of methods and parameters.

* Implement Tasks 1.2 and 3.1 of Migration Plan
1.2 Abstract Class Core Changes
3.1 Add New Methods to Abstract Class

* Complete Phase 2 implementation updates for serverSentEventGenerator in Node.js and Web SDK. Enhanced header handling, improved error validation, and ensured compliance with new specifications. Updated imports to use local Jsonifiable type.

* Implements 3.2 Parameter Validation and Defaults

Enhance validation in ServerSentEventGenerator: Implement checks for ElementPatchMode, required parameters, JSON format, and script attributes. Update migration plan to reflect verification of defaults and added validation methods.

* Revise migration plan for Datastar TypeScript SDK: Update testing phases, including existing test updates and new test cases for specification compliance. Enhance documentation updates and build validation steps to align with recent changes in method names and parameter handling.

* Refactor ServerSentEventGenerator: Remove ExecuteScript method and related validation logic. Update imports to remove file extensions. Bump version to 1.0.0-RC.12 and clean up unused constants in types and consts files.

* Update examples and tests to use the latest Datastar release candidate version. Replace beta version references with the release candidate in Bun, Deno, and Node.js examples and tests.

* Refactor imports in ServerSentEventGenerator and types files to include file extensions (deno compatibility). Update type definitions for responseInit and improve patch mode handling in validation logic.

* Update eachNewlineIsADataLine method in ServerSentEventGenerator to add a space before each line prefix for improved formatting.

* Update tests to use new spec methods. Refactors ServerSentEventGenerator tests to replace mergeFragments with PatchElements and update type imports for compatibility. Remove type-fest dependency from package.json and deno.lock. Fix line missing space.

* Update package.json scripts for testing: change serve commands to point to test files instead of source files for Deno, Bun, and Node.js.

* Update package version to 1.0.0-RC.12 in package.json

* Refactor ServerSentEventGenerator methods: rename readSignals to ReadSignals and update related documentation and examples to reflect changes in signal handling and DOM updates.

* Refactor examples to replace mergeFragments with PatchElements in Bun, Deno, and Node.js implementations for consistency with updated ServerSentEventGenerator methods.

* Fix for compatiblity with new SDK test suite.

* remove reference file

* cleanup readme

* remove outer mode from readme examples

* Remove version edit

Co-authored-by: Johnathan Stevers <[email protected]>

* update version

Co-authored-by: Johnathan Stevers <[email protected]>

* Update sdk/typescript/examples/bun/package.json

Co-authored-by: Johnathan Stevers <[email protected]>

* Remove deepmerge-ts dependency, and refactor server-sent event generator to eliminate deepmerge usage. Update lock files accordingly.

* Remove validateJson

Co-authored-by: Johnathan Stevers <[email protected]>

* Remove validateJson

Co-authored-by: Johnathan Stevers <[email protected]>

* use camelCase for ts sdk syntax and update readme

* Ensure refactor method names to camelCase in TypeScript SDK, updating all relevant examples and documentation to use `readSignals` instead of `ReadSignals`.

* Fix naming convention for DefaultpatchSignalsOnlyIfMissing to DefaultPatchSignalsOnlyIfMissing in consts.ts and types.ts for consistency.

* Update script source URLs in TypeScript examples and tests.

See: #984 (comment)

* use main js bundle in tests too

---------

Co-authored-by: Johnathan Stevers <[email protected]>

Author: eduwass

sdk/typescript/.gitignore

@@ -14,6 +14,7 @@ dist-ssr
 
 # Editor directories and files
 .vscode/*
+.cursor/*
 !.vscode/extensions.json
 .idea
 .DS_Store

sdk/typescript/README.md

@@ -1,96 +1,276 @@
-# TypeScript SDK for Datastar
 
-Implements the [SDK spec](../README.md) and exposes an abstract
-ServerSentEventGenerator class that can be used to implement runtime specific
-classes. NodeJS and web standard runtimes are currently implemented.
+<p align="center"><img width="200" height="200" src="https://data-star.dev/static/images/rocket-512x512.png"></p>
 
-Currently it only exposes an http1 server, if you want http2 I recommend you use
-a reverse proxy until http2 support is added.
+# Datastar TypeScript SDK 
 
-Deno is used for building the npm package: `deno run -A build.ts VERSION`
+[![Version](https://img.shields.io/badge/version-1.0.0–RC.1-orange)](https://github.com/starfederation/datastar/releases) ![Static Badge](https://img.shields.io/badge/run_time-node_js-2a682d?logo=nodedotjs&labelColor=black) ![Static Badge](https://img.shields.io/badge/run_time-deno-6affaf?logo=deno&labelColor=black) ![Static Badge](https://img.shields.io/badge/run_time-bun-f672b6?logo=bun&labelColor=black)
 
-Usage is straightforward:
+A TypeScript SDK for building reactive web applications with [Datastar](https://github.com/starfederation/datastar).
+
+Implements the [SDK spec](../README.md) 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:**
+```bash
+npm install datastar-sdk
+```
+```javascript
+import { ServerSentEventGenerator } from "datastar-sdk/node";
+```
+
+**Deno:**
+```typescript
+// No installation needed, import directly from npm
+import { ServerSentEventGenerator } from "npm:datastar-sdk/web";
+```
+
+**Bun:**
+```bash
+bun add datastar-sdk
+```
+```javascript
+import { ServerSentEventGenerator } from "datastar-sdk/web";
+```
+
+### Basic Usage
+
+Here's a simple example in Node showing how to read client signals and send back element patches:
 
 ```javascript
-// this example is for node
+import { ServerSentEventGenerator } from "datastar-sdk/node";
+
+// Read signals from the client request
 const reader = await ServerSentEventGenerator.readSignals(req);
 
 if (!reader.success) {
-    console.error('Error while reading signals', reader.error);
-    res.end('Error while reading signals`);
-    return;
-}
-
-if (!('foo' in reader.signals)) {
-    console.error('The foo signal is not present');
-    res.end('The foo signal is not present');
+    console.error('Error reading signals:', reader.error);
     return;
 }
 
+// Stream updates back to the client
 ServerSentEventGenerator.stream(req, res, (stream) => {
-     stream.mergeSignals({ foo: reader.signals.foo });
-     stream.mergeFragments(`<div id="toMerge">Hello <span data-text="$foo">${reader.signals.foo}</span></div>`);
+    // 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>`);
 });
 ```
 
-The stream static method can receive an extra `options` object that can contain
-onError and onAbort callbacks as well as the keepalive option. The keepalive
-option will stop the stream from being closed once the onStart callback is
-finished. That means the user is responsible for ending the stream with
-`this.close()`.
+See examples for other runtimes below.
 
 ## Examples
 
-Follow the links for more complete (and executable) examples
+### Runtime-Specific Examples
+
+| Runtime | Example Location | How to Run | Try Online |
+|---------|-----------------|------------|------------|
+| **Node.js** | `examples/node/node.js` | [Instructions](examples/node/README.md) | [StackBlitz](https://stackblitz.com/edit/node-datastar) |
+| **Deno** | `examples/deno/deno.ts` | [Instructions](examples/deno/README.md) | [Val.town](https://www.val.town/x/eduwass/datastar-deno/code/main.tsx) |
+| **Bun** | `examples/bun/bun.ts` | [Instructions](examples/bun/README.md) | [Replit](https://replit.com/@eduwass/Bun-Datastar) |
 
-- [NodeJS](./examples/node.js)
-- [Deno](./examples/deno.ts)
+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
 
-## Frameworks / Alternate runtimes
+### Running Examples
 
-If you can't simply use the node / web versions, then you can extend the
-abstract class in `./src/abstractServerSentEventGenerator.ts`. You will need to
-provide implementations of the `constructor`, `readSignals`, `stream` and `send`
-methods.
+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
 
-## Testing
+> [!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.
 
-A shell based testing suite is provided; see the [readme](../test/README.md) for
-more information.
+## API Reference
 
-### Testing node
+### ServerSentEventGenerator
 
-Start by building and running the node server
+The main class for handling Datastar communication.
 
-```shell
-$ deno run -A build.ts xxx
-$ node ./npm/esm/node/node.js
+#### Static Methods
+
+##### `readSignals(request)`
+Reads signals from a client request.
+
+**Parameters:**
+- `request`: HTTP request object
+
+**Returns:**
+```typescript
+{
+    success: boolean;
+    signals?: Record<string, any>;
+    error?: string;
+}
 ```
 
-Then run the test suite
+##### `stream(request, response, callback, options?)`
+Creates a Server-Sent Event stream for real-time communication.
 
-```shell
-$ cd ../test
-$ ./test-all.sh http://127.0.0.1:3000
-Running tests with argument: http://127.0.0.1:3000
-Processing GET cases...
-Processing POST cases...
+**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;
+}
 ```
 
-### Testing deno
+> [!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.
 
-Start by running the deno server
+**Parameters:**
+- `signals`: JSON string containing signal data to patch
+- `options`: Optional configuration object with `onlyIfMissing` boolean
 
-```shell
-$ deno --allow-net  ./src/web/deno.ts
+**Example:**
+```javascript
+stream.patchSignals(JSON.stringify({ foo: "bar", count: 42 }));
 ```
 
-Then run the test suite
+##### `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`
 
-```shell
-$ cd ../test
-$ ./test-all.sh http://localhost:8000/
-Running tests with argument: http://localhost:8000/
-Processing GET cases...
-Processing POST cases...
+**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('<div id="myDiv">Updated content</div>');
 ```
+
+## Development
+
+### Prerequisites
+
+To develop or contribute to this SDK, you'll need:
+- [Deno](https://deno.land/) (primary development environment)
+- [Node.js](https://nodejs.org/) (for Node.js compatibility testing)
+- [Bun](https://bun.sh/) (for Bun compatibility testing)
+
+### Building
+
+Build the npm package:
+```bash
+deno run -A build.ts
+```
+
+The above will pick the version from the [src/consts.ts](src/consts.ts) file. If you want to specify the version, use:
+```bash
+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
+
+#### Automated Testing
+
+Run tests for all runtimes:
+```bash
+# Node.js
+npm run test-node
+
+# Deno
+deno task test-deno
+
+# Bun
+bun run test-bun
+```
+
+#### Manual Testing
+
+Start a development server:
+```bash
+# Node.js
+npm run serve-node
+
+# Deno
+deno task serve-deno
+
+# Bun
+bun run serve-bun
+```
+
+Then run the test suite manually:
+```bash
+cd ../test
+./test-all.sh http://127.0.0.1:3000
+```
+
+### Project Structure
+
+```
+typescript/
+├── src/
+│   ├── node/           # Node.js-specific implementation
+│   ├── web/            # Web standards implementation (Deno/Bun)
+│   └── abstract/       # Abstract base classes
+├── examples/
+│   ├── node/           # Node.js example
+│   ├── deno/           # Deno example
+│   └── bun/            # Bun example
+└── test/               # Test suite
+```
+
+## Runtime Support
+
+### Node.js
+- Import: `datastar-sdk/node`
+- Requires: Node.js 18+
+- Uses Node.js-specific HTTP APIs
+
+### Deno
+- Import: `npm:datastar-sdk/web`
+- Requires: Deno 1.30+
+- Uses Web Standards APIs
+
+### Bun
+- Import: `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

sdk/typescript/build.ts

@@ -1,12 +1,14 @@
 // ex. scripts/build_npm.ts
 import { build, emptyDir } from "@deno/dnt";
+import { VERSION } from "./src/consts.ts";
 
 await emptyDir("./npm");
 
 await build({
   entryPoints: [
     "./src/node/serverSentEventGenerator.ts",
     "./src/web/serverSentEventGenerator.ts",
+    "./test/node.ts",
   ],
   outDir: "./npm",
   shims: {
@@ -16,7 +18,7 @@ await build({
   package: {
     // package.json properties
     name: "@starfederation/datastar-sdk",
-    version: Deno.args[0],
+    version: Deno.args[0] || VERSION,
     description: "Cross-runtime Javascript SDK for Datastar",
     license: "MIT",
     repository: {

sdk/typescript/bun.lockb

@@ -1,5 +1,12 @@
 {
   "imports": {
     "@deno/dnt": "jsr:@deno/dnt@^0.41.3"
-  }
+  },
+  "tasks": {
+    "check": "deno lint && deno check src/node/node.ts && deno check src/web/deno.ts && bun run --check src/web/bun.ts",
+    "build": "deno run -A build.ts",
+    "serve-deno": "deno run -A src/web/deno.ts",
+    "test-deno": "./test/test-deno.sh"
+  },
+  "nodeModulesDir": "auto"
 }