@tstdl/base 0.93.139 → 0.93.141

package/rpc/README.md

@@ -0,0 +1,386 @@
+# RPC Module
+
+A powerful, type-safe Remote Procedure Call (RPC) framework for seamless communication between JavaScript environments, such as the main thread, Web Workers, SharedWorkers, and Node.js worker threads. It abstracts the complexity of message passing into intuitive local function calls and object interactions.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Streaming Data](#streaming-data)
+  - [Transferring Data Efficiently](#transferring-data-efficiently)
+  - [Serialization vs. Proxying](#serialization-vs-proxying)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type-Safe Proxies**: Interact with remote objects and functions with full TypeScript support, as if they were local.
+- **Environment Agnostic**: Works with `Worker`, `SharedWorker`, `MessagePort`, `Window`, and Node.js `worker_threads`.
+- **Efficient Data Transfer**: Built-in support for `Transferable` objects (like `ArrayBuffer`) to avoid copying overhead.
+- **Custom Adapters**: Extensible architecture to handle complex non-serializable types like `ReadableStream`.
+- **Flexible Serialization**: Control whether objects are sent by reference (proxy) or by value (serialized).
+
+## Core Concepts
+
+The RPC module simplifies cross-context communication by establishing a structured connection.
+
+### Endpoint
+
+An **Endpoint** (`RpcEndpoint`) wraps the underlying transport mechanism (like a `Worker` or `MessagePort`). It manages the lifecycle of the connection and handles the routing of messages. The primary implementation provided is `MessagePortRpcEndpoint`.
+
+### Channel
+
+A **Channel** (`RpcChannel`) is a logical subdivision of an endpoint. While the endpoint manages the physical connection, channels allow multiple independent conversations to happen simultaneously without interference. The system uses a control channel to negotiate connections and dynamic channels for specific object proxies.
+
+### Expose & Connect
+
+The fundamental pattern is **Expose** and **Connect**:
+
+- **Expose**: One side (e.g., a Worker) registers an object or function under a specific name using `Rpc.expose()`.
+- **Connect**: The other side (e.g., the Main Thread) requests access to that named resource using `Rpc.connect()`. This returns a **Proxy**.
+
+### Proxies
+
+When you connect to a remote object, you receive a **Proxy**. Accessing properties or calling methods on this proxy sends a message to the remote side, executes the operation on the original object, and returns the result. This makes remote interactions feel synchronous or promise-based, hiding the asynchronous nature of message passing.
+
+The system also supports class constructors. If you expose a class (constructor), you can `new` it on the client side, and it will return a proxy to a remote instance.
+
+### Automatic Cleanup & Lifecycle
+
+The RPC module uses `FinalizationRegistry` to manage the lifecycle of channels automatically. When a proxy is garbage collected on the receiving side, the corresponding channel on both sides is closed.
+
+However, garbage collection is non-deterministic. For scenarios requiring explicit control (like unit tests), you can use:
+
+- **`Rpc.isAlive(proxy)`**: Checks if the proxy's underlying channel is still open.
+- **`Rpc.release(proxy)`**: Immediately closes the channel associated with the proxy. Subsequent calls to the proxy will throw an `RpcConnectionClosedError`.
+
+### Async Property Assignments, `has`, and `delete`
+
+While you can assign properties directly (`proxy.foo = 42`), check for existence (`'foo' in proxy`), or delete properties (`delete proxy.foo`), standard JavaScript expects these operations to be synchronous. However, remote operations are inherently asynchronous.
+
+When using these operators on a proxy:
+
+- **Assignment**: Returns the value assigned immediately, while the remote operation happens in the background.
+- **`in` operator**: Returns a `Promise` (which is truthy), not the actual boolean result.
+- **`delete` operator**: Returns a `Promise` (which is truthy), not the actual boolean result.
+
+**Recommendation**: Use the `Rpc` helpers for awaitable and correct results:
+
+```typescript
+// Awaitable assignment
+await Rpc.set(remoteService, 'status', 'active');
+
+// Awaitable 'in' check
+if (await Rpc.has(remoteService, 'status')) { ... }
+
+// Awaitable 'delete'
+const deleted = await Rpc.delete(remoteService, 'status');
+```
+
+### Enhanced Error Handling
+
+When a connection is lost or manually released, pending and future requests throw an `RpcConnectionClosedError`.
+
+Remote errors are wrapped in `RpcRemoteError`. This implementation is now enhanced to:
+
+1. Preserve the original error name, message, and stack.
+2. Attempt to reconstruct the original error prototype if the error type was registered with the `@tstdl/base/serializer` system.
+
+### Proxy Trap Support
+
+The RPC proxies now support additional standard traps, allowing more natural interaction with remote objects:
+
+- **`has`**: Works with the `in` operator (e.g., `'foo' in proxy`).
+- **`deleteProperty`**: Works with the `delete` operator (e.g., `delete proxy.foo`).
+- **`defineProperty`**: Supports remote definition of properties with full descriptor support.
+
+---
+
+## 🚀 Basic Usage
+
+This example demonstrates how to expose a service in a Web Worker and consume it from the main thread.
+
+### 1. Define the Service (Shared)
+
+```typescript
+// pet.service.ts
+export type Pet = {
+  name: string;
+  species: 'dog' | 'cat';
+};
+
+export class PetService {
+  private pets: Pet[] = [{ name: 'Fido', species: 'dog' }];
+
+  async getPets(): Promise<Pet[]> {
+    return this.pets;
+  }
+
+  async addPet(pet: Pet): Promise<void> {
+    this.pets.push(pet);
+  }
+}
+```
+
+### 2. Expose in Worker
+
+```typescript
+// worker.ts
+import { Rpc } from '@tstdl/base/rpc';
+import { MessagePortRpcEndpoint } from '@tstdl/base/rpc/endpoints';
+import { PetService } from './pet.service.js';
+
+// Create an endpoint wrapping the worker's global scope
+const endpoint = new MessagePortRpcEndpoint(self as any);
+
+// Start listening for incoming connections
+Rpc.listen(endpoint);
+
+// Instantiate and expose the service
+const petService = new PetService();
+Rpc.expose(petService, 'pet-service');
+```
+
+### 3. Connect from Main Thread
+
+```typescript
+// main.ts
+import { Rpc } from '@tstdl/base/rpc';
+import { MessagePortRpcEndpoint } from '@tstdl/base/rpc/endpoints';
+import type { PetService } from './pet.service.js';
+
+async function main() {
+  const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
+  const endpoint = new MessagePortRpcEndpoint(worker);
+
+  // Connect to the remote service.
+  // The generic type argument ensures type safety for the returned proxy.
+  const remotePetService = await Rpc.connect<PetService>(endpoint, 'pet-service');
+
+  // Call methods as if they were local
+  const allPets = await remotePetService.getPets();
+  console.log('Initial pets:', allPets);
+
+  await remotePetService.addPet({ name: 'Whiskers', species: 'cat' });
+
+  const updatedPets = await remotePetService.getPets();
+  console.log('Updated pets:', updatedPets);
+}
+
+main();
+```
+
+## 🔧 Advanced Topics
+
+### Streaming Data
+
+Standard serialization cannot handle streams. The `ReadableStreamRpcAdapter` allows you to stream data transparently between environments.
+
+**Worker (Source):**
+
+```typescript
+import { Rpc } from '@tstdl/base/rpc';
+import { ReadableStreamRpcAdapter } from '@tstdl/base/rpc/adapters';
+import { MessagePortRpcEndpoint } from '@tstdl/base/rpc/endpoints';
+import { timeout } from '@tstdl/base/utils';
+
+// 1. Register the adapter
+Rpc.registerAdapter(new ReadableStreamRpcAdapter());
+
+const endpoint = new MessagePortRpcEndpoint(self as any);
+Rpc.listen(endpoint);
+
+function getLogStream(): ReadableStream<string> {
+  let count = 0;
+  return new ReadableStream({
+    async pull(controller) {
+      if (count++ >= 5) {
+        controller.close();
+        return;
+      }
+      await timeout(500);
+      controller.enqueue(`Log entry #${count}`);
+    },
+  });
+}
+
+// 2. Use Rpc.adapt to wrap the stream
+const getAdaptedLogStream = () => Rpc.adapt(getLogStream(), new ReadableStreamRpcAdapter());
+
+Rpc.expose(getAdaptedLogStream, 'log-service');
+```
+
+**Main Thread (Target):**
+
+```typescript
+import { Rpc } from '@tstdl/base/rpc';
+import { ReadableStreamRpcAdapter } from '@tstdl/base/rpc/adapters';
+import { MessagePortRpcEndpoint } from '@tstdl/base/rpc/endpoints';
+
+async function main() {
+  // 1. Register the adapter here as well
+  Rpc.registerAdapter(new ReadableStreamRpcAdapter());
+
+  const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
+  const endpoint = new MessagePortRpcEndpoint(worker);
+
+  const getRemoteLogStream = await Rpc.connect<() => ReadableStream<string>>(endpoint, 'log-service');
+
+  // 2. Receive the proxy stream
+  const stream = await getRemoteLogStream();
+  const reader = stream.getReader();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    console.log('Received:', value);
+  }
+}
+```
+
+### Transferring Data Efficiently
+
+To avoid cloning large objects (like `ArrayBuffer`, `MessagePort`, `ImageBitmap`), use `Rpc.transfer()`. This moves ownership of the object to the receiving context.
+
+```typescript
+// In Main Thread
+const buffer = new Uint8Array(1024 * 1024 * 10).buffer; // 10MB
+
+// Mark 'buffer' to be transferred in the second argument
+await remoteService.processData(Rpc.transfer(buffer, [buffer]));
+
+console.log(buffer.byteLength); // 0 (ownership transferred)
+```
+
+### Serialization vs. Proxying
+
+By default:
+
+- **Primitives** are copied.
+- **Objects** are proxied (a reference is kept, and a proxy is sent).
+
+You can change this behavior:
+
+- **`Rpc.serialize(obj)`**: Forces an object to be serialized (deep copied) instead of proxied. Useful for DTOs or configuration objects.
+- **`Rpc.proxy(obj)`**: Explicitly marks an object to be proxied. Useful if the default heuristic doesn't catch it or if you are nesting objects.
+
+```typescript
+const config = { mode: 'dark', settings: { ... } };
+
+// Send a copy of 'config', not a proxy to it
+await remoteService.updateConfig(Rpc.serialize(config));
+```
+
+### Error Handling
+
+When an error occurs on the remote side, it is caught, serialized, and re-thrown on the calling side.
+
+- **`RpcError`**: The base error thrown by the RPC system itself (e.g., connection lost, method not found).
+- **`RpcRemoteError`**: Wraps an error that occurred on the remote implementation. It preserves the original error's message, stack, and name where possible.
+
+```typescript
+try {
+  await remoteService.doSomethingRisky();
+} catch (error) {
+  if (error instanceof RpcError) {
+    console.error('RPC communication failed:', error.message);
+    if (error.cause instanceof RpcRemoteError) {
+      console.error('Original remote error:', error.cause.message);
+    }
+  }
+}
+```
+
+### Implementing Custom Adapters
+
+You can handle types that aren't natively serializable by implementing the `RpcAdapter` interface.
+
+```typescript
+import { RpcAdapter, RpcChannel, RpcEndpoint } from '@tstdl/base/rpc';
+
+class MyCustomAdapter implements RpcAdapter<MyType, MyData> {
+  name = 'MyCustom';
+
+  adaptSource(value: MyType, channel: RpcChannel): { data: MyData } {
+    // Setup communication on the source side
+    return {
+      data: {
+        /* ... */
+      },
+    };
+  }
+
+  adaptTarget(data: MyData, channel: RpcChannel): MyType {
+    // Reconstruct the object on the target side using the channel
+    return new MyType(/* ... */);
+  }
+}
+
+// Don't forget to register it on both sides!
+Rpc.registerAdapter(new MyCustomAdapter());
+```
+
+## 📚 API
+
+### Rpc
+
+The main entry point for the library.
+
+| Method            | Arguments                | Returns                 | Description                                                                                                  |
+| :---------------- | :----------------------- | :---------------------- | :----------------------------------------------------------------------------------------------------------- |
+| `listen`          | `endpoint: RpcEndpoint`  | `void`                  | Starts listening for incoming connections on the provided endpoint.                                          |
+| `connect`         | `endpoint, name?`        | `Promise<RpcRemote<T>>` | Connects to a remote object exposed with the given name (default: `'default'`).                              |
+| `expose`          | `object, name?`          | `void`                  | Makes an object or function available for remote connections (default: `'default'`).                         |
+| `registerAdapter` | `adapter: RpcAdapter`    | `void`                  | Registers a custom adapter for handling specific types (e.g., streams).                                      |
+| `proxy`           | `object, root?`          | `T`                     | Explicitly marks an object to be transmitted as a remote proxy.                                              |
+| `transfer`        | `object, transfer`       | `T`                     | Marks an object and specifies associated transferable data (e.g., ArrayBuffers).                             |
+| `serialize`       | `object, options?`       | `T`                     | Forces an object to be transmitted by value (serialized) instead of by proxy using `@tstdl/base/serializer`. |
+| `adapt`           | `object, adapter, root?` | `T`                     | Marks an object to be handled by a specific adapter instance.                                                |
+| `isProxied`       | `object: object`         | `boolean`               | Returns `true` if the object has been marked for proxying via `Rpc.proxy()`.                                 |
+| `release`         | `proxy: object`          | `void`                  | Manually closes the channel associated with the proxy (deterministic cleanup).                               |
+| `isAlive`         | `proxy: object`          | `boolean`               | Returns `true` if the proxy's underlying channel is still open.                                              |
+| `set`             | `proxy, property, value` | `Promise<void>`         | Sets a property on the remote object and awaits completion.                                                  |
+| `has`             | `proxy, property`        | `Promise<boolean>`      | Checks if a property exists on the remote object and awaits the result.                                      |
+| `delete`          | `proxy, property`        | `Promise<boolean>`      | Deletes a property on the remote object and awaits the result.                                               |
+| `reset`           | -                        | `void`                  | Clears all exposed objects.                                                                                  |
+
+### MessagePortRpcEndpoint
+
+Implementation of `RpcEndpoint` for message-passing environments.
+
+| Method        | Arguments                            | Returns                  | Description                                                                                                                |
+| :------------ | :----------------------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| `constructor` | `source: MessagePortRpcTransport`    | `MessagePortRpcEndpoint` | Creates an endpoint. `source` can be `Worker`, `MessagePort`, `Window`, `SharedWorker`, or Node.js `Worker`/`MessagePort`. |
+| `static from` | `transport: MessagePortRpcTransport` | `MessagePortRpcEndpoint` | Static factory method to create an endpoint.                                                                               |
+| `close`       | -                                    | `void`                   | Closes the endpoint and the underlying transport.                                                                          |
+
+### RpcChannel
+
+Low-level communication channel.
+
+| Property / Method | Returns                  | Description                                     |
+| :---------------- | :----------------------- | :---------------------------------------------- |
+| `id`              | `string`                 | The unique identifier for this channel.         |
+| `request$`        | `Observable<RpcRequest>` | Emits incoming requests for this channel.       |
+| `message$`        | `Observable<any>`        | Emits incoming data messages for this channel.  |
+| `request(data)`   | `Promise<any>`           | Sends a request and waits for a response.       |
+| `respond(id, ok)` | `Promise<void>`          | Sends a response to a specific request.         |
+| `send(data)`      | `Promise<void>`          | Sends a one-way data message.                   |
+| `close()`         | `void`                   | Closes the channel and stops all subscriptions. |
+
+### ReadableStreamRpcAdapter
+
+Adapter for transmitting `ReadableStream` objects.
+
+| Method        | Arguments               | Description                                                                                      |
+| :------------ | :---------------------- | :----------------------------------------------------------------------------------------------- |
+| `constructor` | `maxChunkSize?: number` | Creates a new adapter. `maxChunkSize` controls how many items are pulled at once (default 1000). |
+
+## 💡 Best Practices
+
+- **Explicit Release**: While `FinalizationRegistry` provides automatic cleanup, it is non-deterministic. For resources that are frequently created and destroyed, use `Rpc.release(proxy)` to free up communication channels immediately.
+- **Register Adapters on Both Sides**: Custom adapters (like `ReadableStreamRpcAdapter`) MUST be registered on both the exposing and the consuming side.
+- **Prefer `Rpc.serialize` for DTOs**: If you are passing plain data objects that don't need to be interactive, use `Rpc.serialize(obj)`. This is more efficient as it avoids the overhead of creating and managing a proxy channel.
+- **Error Handling**: Always wrap remote calls in `try...catch`. Be aware that `RpcRemoteError` preserves the original error's properties, which is useful for structured error reporting.
+- **Type Safety**: Always provide the generic type argument to `Rpc.connect<T>(...)` to ensure full TypeScript support for the returned proxy.

package/rxjs-utils/README.md

@@ -0,0 +1,262 @@
+# rxjs-utils
+
+A collection of custom RxJS operators, Observable creators, and utilities designed to enhance reactive programming workflows. This module provides tools for type safety, advanced retry strategies, timing and scheduling, progressive data emission, and integration with reactive signals.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Type Casting](#type-casting)
+  - [Retry with Backoff](#retry-with-backoff)
+  - [Timing Observables](#timing-observables)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Progressive Array Emission](#progressive-array-emission)
+  - [Lifecycle Teardown](#lifecycle-teardown)
+  - [Signal Integration](#signal-integration)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type Safety Operators**: Explicitly cast observable types for better TypeScript inference.
+- **Retry Strategies**: Robust `retryBackoff` operators supporting exponential backoff and custom handling logic.
+- **Timing Sources**: Observables wrapping `requestAnimationFrame`, `requestIdleCallback`, `setImmediate`, and `process.nextTick`.
+- **Progressive Loading**: `slowArray` operators to emit array chunks over time (useful for rendering large lists).
+- **Lifecycle Hooks**: `teardown` operator to access the last emitted value or error when a subscription ends.
+- **Signal Integration**: `untrack` operator to prevent RxJS subscriptions from tracking dependencies within Signal effects.
+
+## Core Concepts
+
+### Robust Retries
+
+Standard RxJS `retry` is often too aggressive (immediate retry). `retryBackoff` implements delays (constant, linear, or exponential) between retries to prevent overwhelming failing services.
+
+### Scheduling & Timing
+
+Instead of using `interval` or `timer` for everything, this module provides specific observables for the browser's render loop (`animationFrame$`), idle periods (`idle$`), and Node.js event loop phases (`nextTick$`, `immediate$`).
+
+### Progressive Data
+
+When dealing with large datasets in a UI, emitting the entire array at once can freeze the interface. `slowArray` allows you to emit an initial chunk and then progressively add more items, smoothing out the rendering process.
+
+## 🚀 Basic Usage
+
+### Type Casting
+
+Use `cast` to assert a more specific type for an Observable, or `forceCast` to cast from `unknown`.
+
+```ts
+import { cast, forceCast } from '@tstdl/base/rxjs-utils';
+import { of } from 'rxjs';
+
+interface User {
+  id: string;
+  name: string;
+}
+interface Admin extends User {
+  permissions: string[];
+}
+
+const user$ = of({ id: '1', name: 'Alice', permissions: ['root'] } as User);
+const admin$ = of({ id: '1', name: 'Alice', permissions: ['root'] } as Admin);
+
+// Safe upcast: Admin to User (Admin extends User)
+const userFromAdmin$ = admin$.pipe(cast<Admin, User>());
+
+// Force cast: unknown to User
+const unknown$ = of<unknown>({ id: '2', name: 'Bob' });
+const forcedUser$ = unknown$.pipe(forceCast<User>());
+```
+
+### Retry with Backoff
+
+Handle temporary failures with exponential backoff.
+
+```ts
+import { retryBackoff } from '@tstdl/base/rxjs-utils';
+import { HttpClient } from '@tstdl/base/http/client'; // Example http client
+import { inject } from '@tstdl/base/injector';
+
+const http = inject(HttpClient);
+
+http
+  .get('https://api.example.com/data')
+  .pipe(
+    // Retry up to 3 times
+    // Initial delay 500ms, increasing exponentially
+    retryBackoff(3, {
+      strategy: 'exponential',
+      initialDelay: 500,
+      maximumDelay: 5000,
+    }),
+  )
+  .subscribe({
+    next: (response) => console.log('Success:', response),
+    error: (err) => console.error('Failed after retries:', err),
+  });
+```
+
+### Timing Observables
+
+Use specific schedulers for performance-critical tasks.
+
+```ts
+import { animationFrame$, idle$ } from '@tstdl/base/rxjs-utils';
+
+// Run logic on every animation frame (recursive)
+const renderLoop$ = animationFrame$.subscribe(() => {
+  // Update canvas or DOM
+});
+
+// Run logic only when the browser is idle
+const backgroundTask$ = idle$.subscribe((deadline) => {
+  console.log('Browser is idle, time remaining:', deadline.timeRemaining());
+});
+```
+
+## 🔧 Advanced Topics
+
+### Progressive Array Emission
+
+Use `slowArray` to emit a large array in chunks. This is useful for "infinite scroll" behavior or rendering large lists without blocking the main thread.
+
+```ts
+import { slowArray } from '@tstdl/base/rxjs-utils';
+
+const largeData = Array.from({ length: 1000 }, (_, i) => i);
+
+slowArray(largeData, {
+  delay: 0, // Start immediately
+  initialSize: 20, // Emit first 20 items immediately
+  interval: 50, // Add more items every 50ms
+  size: 10, // Add 10 items per interval
+}).subscribe((currentArray) => {
+  // currentArray grows: [0..19] -> [0..29] -> [0..39] ...
+  console.log(`Rendered ${currentArray.length} items`);
+});
+```
+
+To handle a stream of incoming arrays (e.g., from a search result that updates), use the `persistentSlowArray` operator. It maintains the current "chunk size" even when the underlying source array changes.
+
+```ts
+import { persistentSlowArray } from '@tstdl/base/rxjs-utils';
+import { fromEvent, map, debounceTime } from 'rxjs';
+
+// Imagine a search input emitting new results
+const searchResults$ = fromEvent(input, 'input').pipe(
+  debounceTime(300),
+  switchMap(q => fetchResults(q)), // returns Observable<Item[]>
+  persistentSlowArray({
+    interval: 100,
+    size: 5,
+    initialSize: 10
+  })
+);
+```
+
+### Lazy Initial Values
+
+Use `startWithProvider` when you need to emit an initial value that must be calculated at the exact moment of subscription (e.g., a timestamp or a value from another service).
+
+```ts
+import { startWithProvider } from '@tstdl/base/rxjs-utils';
+import { of } from 'rxjs';
+
+const source$ = of('event 1', 'event 2').pipe(
+  startWithProvider(() => `Started at ${new Date().toISOString()}`)
+);
+```
+
+### Lifecycle Teardown
+
+The `teardown` operator allows you to execute logic when the stream ends (completes, errors, or unsubscribes), with access to the last emitted value and the error (if any).
+
+```ts
+import { teardown } from '@tstdl/base/rxjs-utils';
+import { interval } from 'rxjs';
+
+const sub = interval(1000)
+  .pipe(
+    teardown((lastValue, error) => {
+      if (error) {
+        console.error('Stream crashed at:', lastValue, error);
+      } else {
+        console.log('Stream cleaned up. Last value was:', lastValue);
+      }
+    }),
+  )
+  .subscribe();
+
+setTimeout(() => sub.unsubscribe(), 2500);
+// Output after 2.5s: "Stream cleaned up. Last value was: 1"
+```
+
+### Signal Integration
+
+When using RxJS inside a reactive context (like `@tstdl/base/signals` effects), subscriptions might accidentally become dependencies. `untrack` wraps the subscription callbacks to prevent this.
+
+```ts
+import { untrack } from '@tstdl/base/rxjs-utils';
+import { effect } from '@tstdl/base/signals';
+import { interval } from 'rxjs';
+
+effect(() => {
+  // This subscription will NOT cause the effect to re-run
+  // when the observable emits, because the subscriber logic is untracked.
+  const sub = interval(1000)
+    .pipe(untrack())
+    .subscribe((val) => {
+      console.log(val);
+    });
+
+  return () => sub.unsubscribe();
+});
+```
+
+## 📚 API
+
+### Operators
+
+| Function                                          | Description                                                                                                     |
+| :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
+| `cast<Input, Output>()`                           | Casts an Observable from `Input` type to `Output` type (checked).                                               |
+| `forceCast<Output>()`                             | Casts an Observable from `unknown` to `Output` type.                                                            |
+| `noopOperator<T>()`                               | An operator that does nothing and passes values through unchanged.                                              |
+| `rejectErrors<T>()`                               | Suppresses errors from the source observable (stops emission on error without notifying downstream).            |
+| `retryBackoff<T>(count, options)`                 | Retries the source observable on error with a specified backoff strategy.                                       |
+| `retryBackoffHandled<T>(count, options, handler)` | Similar to `retryBackoff`, but allows a custom handler function to determine behavior or side effects on retry. |
+| `persistentSlowArray<T>(options)`                 | Operator version of `slowArray`. Emits growing arrays from a source array emission.                             |
+| `startWithProvider<T, D>(provider)`               | Like `startWith`, but accepts a function to lazily generate the initial value.                                  |
+| `teardown<T>(fn)`                                 | Registers a callback to run on finalization, receiving the last value and error.                                |
+| `untrack<T>()`                                    | Wraps subscription handlers in `untracked()` to prevent signal dependency tracking.                             |
+
+### Observable Creators
+
+| Function                       | Description                                                                      |
+| :----------------------------- | :------------------------------------------------------------------------------- |
+| `noop<T>(source)`              | Returns the source observable as is.                                             |
+| `slowArray<T>(array, options)` | Creates an observable that emits the provided array in growing chunks over time. |
+| `singleIdle$`                  | Emits once when the browser is idle (via `requestIdleCallback`).                 |
+| `idle$`                        | Emits repeatedly when the browser is idle.                                       |
+| `singleAnimationFrame$`        | Emits once on the next animation frame.                                          |
+| `animationFrame$`              | Emits repeatedly on every animation frame.                                       |
+| `singleImmediate$`             | Emits once via `setImmediate` (Node.js/Polyfill).                                |
+| `immediate$`                   | Emits repeatedly via `setImmediate`.                                             |
+| `microtask$`                   | Emits once via `queueMicrotask`.                                                 |
+| `singleNextTick$`              | Emits once via `process.nextTick`.                                               |
+| `nextTick$`                    | Emits repeatedly via `process.nextTick`.                                         |
+
+### Types
+
+| Type               | Description                                                                                                   |
+| :----------------- | :------------------------------------------------------------------------------------------------------------ |
+| `SlowArrayOptions` | Configuration for `slowArray` (`delay`, `initialSize`, `interval`, `size`).                                   |
+| `BackoffOptions`   | Configuration for retry backoff (`strategy`, `initialDelay`, `maximumDelay`, `increase`, `jitter`).           |
+| `BackoffStrategy`  | Either `'linear'` or `'exponential'`.                                                                         |
+| `IdleDeadline`     | The object passed to `idle$` subscribers, containing `timeRemaining()` and `didTimeout`. (native JS type)     |
+
+## 🏁 Platform Compatibility
+
+- **Browser**: Full support for all operators and observables, including `animationFrame$` and `idle$`.
+- **Node.js**: Full support, though `animationFrame$` and `idle$` require polyfills if used. `nextTick$` and `immediate$` are native to Node.js.
+- **Workers**: Support varies depending on the availability of `requestAnimationFrame` and `requestIdleCallback`.