@tstdl/base 0.93.139 → 0.93.140

package/reflection/README.md

@@ -0,0 +1,305 @@
+# Reflection
+
+A powerful and unified toolkit for creating and managing TypeScript decorators with a robust runtime reflection system. It simplifies decorator creation, manages metadata storage, and supports inheritance, enabling advanced runtime introspection.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Unified Decorator API**: Consistent factory functions (`Class`, `Property`, `Method`, etc.) to create type-safe decorators for specific targets.
+- **Centralized Registry**: A global `reflectionRegistry` automatically collects and organizes metadata from all decorators.
+- **Metadata Storage**: Attach arbitrary custom data to classes, properties, methods, and parameters via a `ContextDataMap`. Supports merging complex data structures.
+- **Inheritance Support**: Metadata is automatically inherited from parent classes, allowing for polymorphic behavior in frameworks.
+- **Static Member Support**: Reflect on both instance and static properties and methods.
+- **Decorator Wrapping**: Utilities to wrap third-party decorators, integrating them into the reflection system without modifying their source.
+- **Inclusive Decorators**: Apply multiple decorators simultaneously via a single wrapper, simplifying complex decoration logic.
+- **Type Inspection**: Helper functions to visualize and inspect registered type information at runtime.
+
+## Core Concepts
+
+### Decorator Factories
+
+Instead of writing raw decorator functions that handle `target`, `propertyKey`, and `descriptor` manually, this module provides factories. These factories accept an options object, often including a `handler` function where you define your logic.
+
+- **`Class()`**: Creates a class decorator.
+- **`Property()`**: Creates a property decorator.
+- **`Method()`**: Creates a method decorator.
+- **`Parameter()`**: Creates a parameter decorator (constructor or method).
+- **`Decorate()`**: Creates a universal decorator applicable to multiple targets.
+
+### Reflection Registry
+
+The `reflectionRegistry` is a singleton that stores `TypeMetadata` for every class decorated with this library. When a decorator is applied, it registers the target (class, method, property) and allows you to attach data to it.
+
+You can later retrieve this metadata using `reflectionRegistry.getMetadata(Constructor)`. This metadata object contains a structured view of the class, including its properties, methods, parameters, and any custom data attached.
+
+### Context Data
+
+Every metadata object (for a type, property, method, etc.) has a `data` property, which is a `ContextDataMap`. This acts as a key-value store for your custom metadata (e.g., serialization rules, validation constraints, dependency injection tokens).
+
+## 🚀 Basic Usage
+
+### Creating and Using a Class Decorator
+
+This example demonstrates how to create a decorator to mark a class as a "Service" and retrieve that information at runtime.
+
+```typescript
+import { Class, reflectionRegistry } from '@tstdl/base/reflection';
+
+// 1. Define a key for the metadata
+const SERVICE_NAME_KEY = Symbol('ServiceName');
+
+// 2. Create the decorator factory
+function Service(name: string) {
+  return Class({
+    handler: (data, metadata) => {
+      // 'metadata' is the TypeMetadata for the class
+      metadata.data.set(SERVICE_NAME_KEY, name);
+    },
+  });
+}
+
+// 3. Apply the decorator
+@Service('UserManagement')
+class UserService {
+  // ...
+}
+
+// 4. Inspect metadata at runtime
+const metadata = reflectionRegistry.getMetadata(UserService);
+
+if (metadata) {
+  const serviceName = metadata.data.get(SERVICE_NAME_KEY);
+  console.log(`Service Name: ${serviceName}`); // Output: Service Name: UserManagement
+}
+```
+
+### Property and Parameter Decorators
+
+Decorators are often used for defining schemas or dependency injection.
+
+```typescript
+import { Property, Parameter, reflectionRegistry } from '@tstdl/base/reflection';
+
+const SERIALIZE_KEY = Symbol('Serialize');
+const INJECT_KEY = Symbol('Inject');
+
+// Property decorator to mark fields for serialization
+function Serializable() {
+  return Property({
+    handler: (data, metadata) => {
+      metadata.data.set(SERIALIZE_KEY, true);
+    },
+  });
+}
+
+// Parameter decorator for dependency injection
+function Inject(token: string) {
+  return Parameter({
+    handler: (data, metadata) => {
+      metadata.data.set(INJECT_KEY, token);
+    },
+  });
+}
+
+class Database {}
+
+class User {
+  @Serializable()
+  id: string;
+
+  @Serializable()
+  username: string;
+
+  passwordHash: string; // Not marked
+
+  constructor(@Inject('DbConnection') db: Database) {}
+}
+
+// Inspecting the class
+const meta = reflectionRegistry.getMetadata(User);
+
+// Find serializable properties
+for (const [key, propMeta] of meta.properties) {
+  if (propMeta.data.get(SERIALIZE_KEY)) {
+    console.log(`Property '${String(key)}' is serializable.`);
+  }
+}
+// Output:
+// Property 'id' is serializable.
+// Property 'username' is serializable.
+
+// Check constructor parameters
+const ctorParams = meta.parameters; // Array of ConstructorParameterMetadata
+if (ctorParams) {
+  const firstParamToken = ctorParams[0].data.get(INJECT_KEY);
+  console.log(`Constructor param 0 injects: ${firstParamToken}`);
+  // Output: Constructor param 0 injects: DbConnection
+}
+```
+
+## 🔧 Advanced Topics
+
+### Method Interception
+
+You can use `Method` decorators to wrap or intercept method calls. The handler receives the property descriptor, allowing you to modify the `value`.
+
+```typescript
+import { Method } from '@tstdl/base/reflection';
+
+function Log() {
+  return Method({
+    handler: (data, metadata, [target, propertyKey, descriptor]) => {
+      const originalMethod = descriptor.value;
+
+      descriptor.value = function (...args: any[]) {
+        console.log(`Calling ${String(data.methodKey)} with`, args);
+        return originalMethod.apply(this, args);
+      };
+    },
+  });
+}
+
+class Calculator {
+  @Log()
+  add(a: number, b: number) {
+    return a + b;
+  }
+}
+
+new Calculator().add(2, 3);
+// Console: Calling add with [2, 3]
+```
+
+### Wrapping Third-Party Decorators
+
+If you use decorators from other libraries (like an ORM or validation library), you can wrap them to ensure they also register metadata in the `reflectionRegistry`.
+
+```typescript
+import { wrapDecorator } from '@tstdl/base/reflection';
+
+// Assume this comes from an external library
+function ExternalEntity(tableName: string) {
+  return (target: any) => {
+    /* ... external logic ... */
+  };
+}
+
+// Wrap it
+const Entity = (tableName: string) =>
+  wrapDecorator(ExternalEntity(tableName), {
+    data: { tableName }, // Automatically attach this data to metadata
+    handler: (data, metadata) => {
+      console.log(`Registered entity: ${tableName}`);
+    },
+  });
+
+@Entity('users')
+class User {}
+```
+
+### Inheritance
+
+Metadata is inherited. If you request metadata for a subclass, it includes properties and methods decorated in the parent class, marked with `inherited: true`.
+
+```typescript
+import { Property, reflectionRegistry } from '@tstdl/base/reflection';
+
+function Prop() {
+  return Property();
+}
+
+class Base {
+  @Prop() baseField: string;
+}
+
+class Child extends Base {
+  @Prop() childField: string;
+}
+
+const meta = reflectionRegistry.getMetadata(Child);
+console.log(meta.properties.has('baseField')); // true
+console.log(meta.properties.get('baseField').inherited); // true
+```
+
+### Inclusive Decorators
+
+The `include` option allows you to trigger other decorators when your decorator is applied. This is useful for creating "composite" decorators.
+
+```typescript
+import { Class, Property } from '@tstdl/base/reflection';
+
+const MyClassDecorator = Class();
+const MyPropertyDecorator = Property();
+
+function Composite() {
+  return Class({
+    include: [MyClassDecorator, MyPropertyDecorator] // Error in this specific case as targets differ, but shows the concept
+  });
+}
+```
+
+*Note: The included decorators must be compatible with the target where the main decorator is applied.*
+
+### Data Merging
+
+When setting data on metadata, you can choose to merge instead of overwrite by setting `mergeData: true`. This works for objects, arrays, maps, and sets.
+
+```typescript
+import { Class } from '@tstdl/base/reflection';
+
+const KEY = Symbol('Tags');
+
+function Tag(tag: string) {
+  return Class({
+    data: { [KEY]: [tag] },
+    mergeData: true
+  });
+}
+
+@Tag('alpha')
+@Tag('beta')
+class MyClass {}
+
+// Metadata for MyClass will have [KEY]: ['alpha', 'beta']
+```
+
+## 📚 API
+
+| Function / Object                         | Description                                                                                                 |
+| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
+| `reflectionRegistry`                      | The global singleton instance of `ReflectionRegistry`. Use this to retrieve metadata (`getMetadata(Type)`), check for registration (`hasType(Type)`), or manually unregister types (`unregister(Type)`). |
+| `Class(options?)`                         | Factory for creating a class decorator.                                                                     |
+| `Property(options?)`                      | Factory for creating a property decorator.                                                                  |
+| `Method(options?)`                        | Factory for creating a method decorator.                                                                    |
+| `Accessor(options?)`                      | Factory for creating an accessor (getter/setter) decorator.                                                 |
+| `PropertyOrAccessor(options?)`            | Factory for creating a decorator that can target both properties and accessors.                             |
+| `Parameter(options?)`                     | Factory for creating a parameter decorator (works on constructor and method parameters).                    |
+| `ConstructorParameter(options?)`          | Factory for creating a decorator specifically for constructor parameters.                                   |
+| `MethodParameter(options?)`               | Factory for creating a decorator specifically for method parameters.                                        |
+| `Decorate(options?)`                      | Factory for creating a universal decorator that can target multiple types (class, property, etc.).          |
+| `createDecorator(options, handler?)`      | Low-level primitive for creating highly customized decorators.                                               |
+| `wrapDecorator(decorator, options?)`      | Wraps an existing decorator instance to integrate it with the reflection system.                            |
+| `wrapDecoratorFactory(factory, options?)` | Wraps a decorator factory function.                                                                         |
+| `getDecoratorData(...)`                   | Utility to parse standard decorator arguments into a structured `DecoratorData` object.                     |
+| `getConstructor(target)`                  | Utility to get the constructor from either a constructor function or an instance prototype.                 |
+| `getTypeInfoString(constructor)`          | Debug utility that returns a string representation of the type structure.                                   |
+| `printType(constructor)`                  | Debug utility that prints the structure of a type based on registered metadata to the console.              |
+
+### Types
+
+| Type                | Description                                                                               |
+| :------------------ | :---------------------------------------------------------------------------------------- |
+| `TypeMetadata`      | Metadata for a class, containing maps of properties, methods, and constructor parameters. |
+| `PropertyMetadata`  | Metadata for a specific property (instance or static).                                    |
+| `MethodMetadata`    | Metadata for a method, including its parameters and return type (instance or static).     |
+| `ParameterMetadata` | Metadata for a parameter (index, type).                                                   |
+| `DecoratorData`     | Object passed to handlers containing context (e.g., `propertyKey`, `index`, `static`).    |
+| `DecoratorHandler`  | Function signature for the logic inside a decorator factory.                              |
+| `MetadataType`      | Union of possible metadata types (`'type'`, `'property'`, `'method'`, etc.).              |

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.