@tstdl/base 0.93.139 → 0.93.141

package/signals/implementation/README.md

@@ -0,0 +1,134 @@
+# Signals Implementation
+
+This module provides the core reactive implementation for the Tstdl library. It is based on Angular's Signals system, adapted for use in any environment (Node.js or Browser) without requiring the Angular runtime.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Writable Signals](#writable-signals)
+  - [Computed Signals](#computed-signals)
+  - [Effects](#effects)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Untracked Reads](#untracked-reads)
+  - [RxJS Interop](#rxjs-interop)
+  - [Equality Functions](#equality-functions)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Granular Reactivity**: Only dependents of changed signals are re-evaluated.
+- **Lazy Evaluation**: Computed signals only calculate their value when read.
+- **Glitch-Free**: Eliminates intermediate inconsistent states during updates.
+- **RxJS Integration**: Seamlessly bridge between reactive signals and asynchronous observables.
+- **Environment Agnostic**: Works in Node.js, browsers, and other JavaScript environments.
+
+## Core Concepts
+
+### Writable Signals
+
+A `WritableSignal` is the primary source of truth in the reactive graph. It holds a value that can be explicitly set or updated.
+
+- `set(value)`: Overwrites the current value.
+- `update(fn)`: Computes a new value based on the previous one.
+- `asReadonly()`: Returns a version of the signal that cannot be modified.
+
+### Computed Signals
+
+A `computed` signal derives its value from other signals. It automatically tracks any signals accessed during its execution and re-evaluates only when those dependencies change. Computations are lazy and memoized.
+
+### Effects
+
+An `effect` is a reactive block of code that automatically re-runs whenever any signals it reads change. Effects are scheduled to run asynchronously using a microtask to batch updates and avoid redundant executions.
+
+## 🚀 Basic Usage
+
+```typescript
+import { signal, computed, effect } from './index.js';
+
+// Create a writable signal
+const count = signal(0);
+
+// Create a computed signal
+const isEven = computed(() => count() % 2 === 0);
+
+// Create an effect
+effect(() => {
+  console.log(`Count: ${count()}, isEven: ${isEven()}`);
+});
+
+// Updating the signal triggers the effect
+count.set(1); // Output: Count: 1, isEven: false
+count.update(c => c + 1); // Output: Count: 2, isEven: true
+```
+
+## 🔧 Advanced Topics
+
+### Untracked Reads
+
+Sometimes you want to read a signal's value without creating a dependency. Use `untracked` for this purpose.
+
+```typescript
+import { signal, effect, untracked } from './index.js';
+
+const count = signal(0);
+const other = signal('A');
+
+effect(() => {
+  console.log(count());
+  console.log(untracked(other)); // Changes to 'other' won't trigger this effect
+});
+```
+
+### RxJS Interop
+
+The module provides utilities to convert between signals and observables.
+
+```typescript
+import { signal, toObservable, toSignal } from './index.js';
+import { interval } from 'rxjs';
+
+// Signal to Observable
+const count = signal(0);
+const count$ = toObservable(count);
+
+// Observable to Signal
+const timer$ = interval(1000);
+const timer = toSignal(timer$, { initialValue: 0 });
+```
+
+### Equality Functions
+
+You can customize how signal changes are detected by providing a custom `equal` function.
+
+```typescript
+import { signal } from './index.js';
+
+const user = signal({ id: 1, name: 'John' }, {
+  equal: (a, b) => a.id === b.id
+});
+
+// This update will NOT trigger dependents because the ID is the same
+user.set({ id: 1, name: 'John Doe' });
+```
+
+## 📚 API
+
+### Functions
+
+- `signal(initialValue, options?)`: Creates a `WritableSignal`.
+- `computed(computation, options?)`: Creates a computed `Signal`.
+- `effect(effectFn, options?)`: Creates an `EffectRef`.
+- `untracked(fn)`: Runs `fn` in a non-reactive context.
+- `isSignal(value)`: Returns `true` if the value is a Signal.
+- `isWritableSignal(value)`: Returns `true` if the value is a WritableSignal.
+- `toObservable(signal, options?)`: Converts a signal to an RxJS Observable.
+- `toSignal(observable, options?)`: Converts an RxJS Observable to a signal.
+- `configureDefaultSignalsImplementation()`: Configures the library to use this implementation by default.
+
+### Interfaces
+
+- `Signal<T>`: A readonly reactive value.
+- `WritableSignal<T>`: A signal that can be changed.
+- `EffectRef`: A handle to a running effect, allowing it to be destroyed.

package/sse/README.md

@@ -0,0 +1,278 @@
+# @tstdl/base/sse
+
+A comprehensive module for Server-Sent Events (SSE) that provides both a low-level reactive client for discrete events and a high-level, delta-capable data streaming abstraction for synchronizing complex objects efficiently.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [High-Level: Data Streaming](#high-level-data-streaming)
+  - [Low-Level: Event Pushing](#low-level-event-pushing)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Server-Side Data Streaming](#server-side-data-streaming)
+  - [Client-Side Data Consumption](#client-side-data-consumption)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Low-Level Event Pushing](#low-level-event-pushing-1)
+  - [Handling Errors](#handling-errors)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Isomorphic Design**: Type-safe utilities for both server (Node.js/Edge) and client (Browser) environments.
+- **Smart Data Synchronization**: `DataStreamSource` automatically calculates JSON diffs (deltas) between updates to minimize bandwidth usage. For optimal array synchronization, ensure your objects have an `id` property.
+- **Automatic State Reconstruction**: The client-side `DataStream` utility automatically patches the local state with incoming deltas, exposing a seamless RxJS Observable of the full object.
+- **Reactive Client**: A robust RxJS wrapper around the native `EventSource` API (`ServerSentEvents`) for handling connection states and events.
+- **Web Streams Support**: Server-side implementation uses standard `ReadableStream`, making it compatible with modern runtimes.
+- **Full SSE Specification**: Supports named events, custom IDs, retry intervals, and comments.
+
+## Core Concepts
+
+### High-Level: Data Streaming
+
+The **Data Streaming** abstraction is designed for synchronizing a single, potentially complex state object between the server and client.
+
+- **Server (`DataStreamSource`)**: You simply pass the full object to the source whenever it changes. The source uses `jsondiffpatch` to calculate the difference between the current and previous object. It sends the full object initially, and then only the small deltas for subsequent updates.
+- **Client (`DataStream`)**: Consumes the stream, listening for `data` (full snapshot) and `delta` (patch) events. It maintains the local state by applying patches automatically and emits the fully updated object to subscribers.
+
+### Low-Level: Event Pushing
+
+The **Event Pushing** layer provides direct control over the SSE protocol, suitable for sending discrete notifications (e.g., "OrderShipped", "NewMessage").
+
+- **Server (`ServerSentEventsSource`)**: A wrapper around a `TransformStream` that formats messages according to the SSE spec.
+- **Client (`ServerSentEvents`)**: Wraps the browser's `EventSource` to provide RxJS Observables for messages, connection status, and errors.
+
+## 🚀 Basic Usage
+
+### Server-Side Data Streaming
+
+Use `DataStreamSource` to stream state changes. The most convenient way is `DataStreamSource.fromIterable`.
+
+```typescript
+import { apiController, type ApiServerResult } from '@tstdl/base/api/server';
+import { defineApi } from '@tstdl/base/api';
+import { DataStream, DataStreamSource } from '@tstdl/base/sse';
+import { CancellationSignal } from '@tstdl/base/cancellation';
+import { inject } from '@tstdl/base/injector';
+import { timeout } from '@tstdl/base/utils/timing';
+import { object, string, number } from '@tstdl/base/schema';
+
+// 1. Define the data shape
+const StockPrice = object({
+  symbol: string(),
+  price: number(),
+  timestamp: number(),
+});
+type StockPrice = typeof StockPrice.T;
+
+// 2. Define the API
+const stockApi = defineApi({
+  resource: 'stocks',
+  endpoints: {
+    track: {
+      resource: ':symbol/stream',
+      method: 'GET',
+      parameters: object({ symbol: string() }),
+      result: DataStream<StockPrice>, // Type hint for the client
+    },
+  },
+});
+
+// 3. Implement the Controller
+@apiController(stockApi)
+class StockApiController {
+  #cancellationSignal = inject(CancellationSignal);
+
+  track({ parameters }: any): ApiServerResult<typeof stockApi, 'track'> {
+    // Create an async generator that yields data updates
+    const ticker = this.createTicker(parameters.symbol, this.#cancellationSignal);
+
+    // Create a source that automatically handles diffing and serialization
+    return DataStreamSource.fromIterable(ticker, { delta: true });
+  }
+
+  async *createTicker(symbol: string, signal: CancellationSignal): AsyncIterable<StockPrice> {
+    let price = 100;
+    while (signal.isUnset) {
+      price += (Math.random() - 0.5) * 2;
+      yield { symbol, price, timestamp: Date.now() };
+      await timeout(1000, signal);
+    }
+  }
+}
+```
+
+### Client-Side Data Consumption
+
+Use `DataStream.parse` to transform the raw SSE connection into a stream of your data objects.
+
+```typescript
+import { DataStream, ServerSentEvents } from '@tstdl/base/sse';
+import { type Observable } from 'rxjs';
+
+type StockPrice = {
+  symbol: string;
+  price: number;
+  timestamp: number;
+};
+
+// 1. Establish the connection
+const sse = new ServerSentEvents('/api/stocks/AAPL/stream');
+
+// 2. Parse the data stream
+// This handles the initial full load and all subsequent delta patches automatically
+const stock$: Observable<StockPrice> = DataStream.parse<StockPrice>(sse);
+
+// 3. Subscribe to updates
+const subscription = stock$.subscribe({
+  next: (stock) => {
+    console.log(`Update for ${stock.symbol}: $${stock.price.toFixed(2)}`);
+  },
+  error: (err) => console.error('Stream error:', err),
+  complete: () => console.log('Stream closed'),
+});
+
+// Cleanup when done
+// subscription.unsubscribe();
+```
+
+## 🔧 Advanced Topics
+
+### Low-Level Event Pushing
+
+If you don't need object synchronization and just want to send named events, use `ServerSentEventsSource` directly.
+
+**Server:**
+
+```typescript
+import { ServerSentEventsSource } from '@tstdl/base/sse';
+import { timeout } from '@tstdl/base/utils/timing';
+
+async function notificationStream(): Promise<ServerSentEventsSource> {
+  const source = new ServerSentEventsSource();
+
+  // Run in background
+  (async () => {
+    await timeout(1000);
+    if (source.closed()) return;
+
+    // Send a named JSON event
+    await source.sendJson({
+      name: 'notification',
+      id: '1',
+      data: { message: 'Hello World' },
+    });
+
+    await timeout(2000);
+    if (source.closed()) return;
+
+    // Send a text event
+    await source.sendText({
+      name: 'ping',
+      data: 'keep-alive',
+    });
+
+    await source.close();
+  })();
+
+  return source;
+}
+```
+
+**Client:**
+
+```typescript
+import { ServerSentEvents } from '@tstdl/base/sse';
+import { filter, map } from 'rxjs';
+
+const sse = new ServerSentEvents('/api/notifications');
+
+// Listen specifically for 'notification' events
+const notifications$ = sse.message$('notification').pipe(map((event) => JSON.parse(event.data)));
+
+notifications$.subscribe((data) => console.log('New notification:', data));
+```
+
+### Handling Errors
+
+The `DataStreamSource` has a built-in mechanism to send errors to the client before closing the stream.
+
+```typescript
+// Server
+const source = new DataStreamSource();
+try {
+  // ... logic
+} catch (err) {
+  // Sends an 'error' event with the formatted error and closes the connection
+  await source.error(err);
+}
+```
+
+On the client side, `DataStream.parse` will listen for these `error` events and error out the Observable stream accordingly.
+
+## 📚 API
+
+### `DataStreamSource<T>`
+
+Server-side class for streaming data objects with optional delta compression.
+
+| Member         | Signature                                                    | Description                                                                         |
+| :------------- | :----------------------------------------------------------- | :---------------------------------------------------------------------------------- |
+| `constructor`  | `(options?: DataStreamSourceOptions)`                        | Creates a new source. Options include `delta` (boolean) and `errorFormatter`.       |
+| `fromIterable` | `static fromIterable<T>(iterable: AnyIterable<T>, options?)` | Creates a source that automatically pulls from an async iterable and sends updates. |
+| `send`         | `send(data: T): Promise<void>`                               | Sends a data update. If `delta` is enabled, calculates diff from previous data.     |
+| `error`        | `error(error: unknown): Promise<void>`                       | Sends an error event to the client and closes the stream.                           |
+| `close`        | `close(): Promise<void>`                                     | Closes the underlying stream.                                                       |
+| `closed`       | `ReadonlySignal<boolean>`                                    | Signal indicating if the stream is closed.                                          |
+| `eventSource`  | `ServerSentEventsSource`                                     | Access to the underlying SSE source.                                                |
+
+### `DataStream<T>`
+
+Client-side utility for reconstructing data streams.
+
+| Member  | Signature                                                       | Description                                                                          |
+| :------ | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
+| `parse` | `static parse<T>(eventSource: ServerSentEvents): Observable<T>` | Transforms an SSE connection into an Observable of the synchronized data object `T`. |
+
+### `ServerSentEventsSource`
+
+Low-level server-side SSE writer.
+
+| Member        | Signature                                             | Description                                                               |
+| :------------ | :---------------------------------------------------- | :------------------------------------------------------------------------ |
+| `readable`    | `ReadableStream<string>`                              | The Web Stream to return in the HTTP response body.                       |
+| `sendJson`    | `sendJson(event: ServerSentJsonEvent): Promise<void>` | Sends a named event with JSON data.                                       |
+| `sendText`    | `sendText(event: ServerSentTextEvent): Promise<void>` | Sends a named event with raw text data.                                   |
+| `sendComment` | `sendComment(comment: string): Promise<void>`         | Sends an SSE comment (ignored by browser clients, useful for keep-alive). |
+| `close`       | `close(): Promise<void>`                              | Closes the stream.                                                        |
+| `closed`      | `ReadonlySignal<boolean>`                             | Signal indicating if the stream is closed.                                |
+| `error`       | `ReadonlySignal<Error \| undefined>`                  | Signal containing the error if the stream failed.                         |
+
+### `ServerSentEvents`
+
+Client-side reactive wrapper for `EventSource`.
+
+| Member          | Signature                                            | Description                                                                            |
+| :-------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------- |
+| `constructor`   | `(url: string, options?: EventSourceInit)`           | Initiates the connection.                                                              |
+| `message$`      | `message$(event?: string): Observable<MessageEvent>` | Returns an Observable of messages. If `event` is provided, filters by that event name. |
+| `state$`        | `Observable<ServerSentEventsState>`                  | Emits connection state changes (`Connecting`, `Open`, `Closed`).                       |
+| `open$`         | `Observable<void>`                                   | Emits when the connection is open.                                                     |
+| `close$`        | `Observable<void>`                                   | Emits when the connection is closed.                                                   |
+| `error$`        | `Observable<Event>`                                  | Emits on connection errors.                                                            |
+| `isOpen$`       | `Observable<boolean>`                                | Emits `true` when connected.                                                           |
+| `isConnecting$` | `Observable<boolean>`                                | Emits `true` when connecting.                                                          |
+| `isClosed$`     | `Observable<boolean>`                                | Emits `true` when closed.                                                              |
+| `state`         | `ServerSentEventsState`                              | Gets the current connection state.                                                     |
+| `close`         | `close(): void`                                      | Manually closes the connection.                                                        |
+
+### Types
+
+| Type                        | Description                                                                       |
+| :-------------------------- | :-------------------------------------------------------------------------------- |
+| `DataStreamSourceOptions`   | Options for `DataStreamSource`: `delta` (boolean) and `errorFormatter` (function). |
+| `DataStreamErrorFormatter`  | Function type: `(error: unknown) => UndefinableJson`.                             |
+| `ServerSentEventBase<Data>` | Base interface for events with `name`, `data`, `id`, and `retry`.                 |
+| `ServerSentJsonEvent`       | Event where `data` is any JSON-serializable value.                                |
+| `ServerSentTextEvent`       | Event where `data` is a string.                                                   |
+| `ServerSentEvent`           | Union of `ServerSentTextEvent` and `ServerSentJsonEvent`.                         |
+| `ServerSentEventsState`     | Enum: `Connecting` (0), `Open` (1), `Closed` (2).                                 |