@tstdl/base 0.93.138 → 0.93.140

package/serializer/README.md

@@ -0,0 +1,342 @@
+# @tstdl/base/serializer
+
+A robust and extensible serialization library for TypeScript that transforms complex object graphs—including circular references, built-in types, and custom classes—into a JSON-compatible format and back.
+
+## Table of Contents
+
+1.  [✨ Features](#-features)
+2.  [Core Concepts](#core-concepts)
+3.  [🚀 Basic Usage](#-basic-usage)
+4.  [🔧 Advanced Topics](#-advanced-topics)
+    - [Handling Circular References](#handling-circular-references)
+    - [Custom Serializable Classes](#custom-serializable-classes)
+    - [Registering External Types](#registering-external-types)
+    - [Contextual Serialization](#contextual-serialization)
+    - [Raw Serialization](#raw-serialization)
+5.  [📚 API](#-api)
+
+## ✨ Features
+
+- **Circular Reference Handling**: Automatically detects cycles and serializes them as references to the original path.
+- **Rich Type Support**: Out-of-the-box support for:
+  - `Map`, `Set`
+  - `Date`, `RegExp`, `Error`
+  - `BigInt`, `Symbol` (global via `Symbol.for`)
+  - `ArrayBuffer`, `TypedArray` (Int8, Uint8, etc.), `Buffer`
+  - `MessagePort` (serialized as raw if available)
+- **JSON Compatible**: The output is a plain JavaScript object structure safe for `JSON.stringify`.
+- **Extensible**: Add support for your own classes using decorators or registration functions.
+- **Context Aware**: Pass shared state (context) during serialization/deserialization to avoid embedding large shared objects.
+- **Type Safe**: Preserves type information for registered classes.
+
+## Core Concepts
+
+The serializer converts objects into a "Serialized Data" format. This format is composed entirely of JSON primitives (`string`, `number`, `boolean`, `null`) and plain objects/arrays.
+
+- **Primitives**: Kept as-is. `undefined` becomes `{ "<undefined>": null }`.
+- **Wrappers**: Complex types are wrapped in objects with specific keys, e.g., `{ "<Date>": 1672531200000 }` or `{ "<Map>": [...] }`.
+- **References**: If an object is encountered more than once, subsequent occurrences are replaced with a reference path, e.g., `{ "<ref>": "$['users'][0]" }`.
+- **Deserialization**: The `deserialize` function reconstructs the graph. It uses a multi-pass approach to resolve circular references (`ForwardRef`) ensuring the object graph identity is preserved.
+
+## 🚀 Basic Usage
+
+The most common use case is serializing an object to a JSON string and restoring it.
+
+```typescript
+import { stringSerialize, stringDeserialize } from '@tstdl/base/serializer';
+
+const data = {
+  id: 1,
+  created: new Date(),
+  meta: new Map<string, any>([['role', 'admin']]),
+  tags: new Set(['user', 'active']),
+};
+
+// Serialize to JSON string
+const json = stringSerialize(data);
+console.log(json);
+// Output: {"id":1,"created":{"<Date>":...},"meta":{"<Map>":[["role","admin"]]},"tags":{"<Set>":["user","active"]}}
+
+// Deserialize back to object
+const restored = stringDeserialize<typeof data>(json);
+
+console.log(restored.created instanceof Date); // true
+console.log(restored.meta instanceof Map); // true
+console.log(restored.meta.get('role')); // 'admin'
+```
+
+## 🔧 Advanced Topics
+
+### Handling Circular References
+
+You don't need to do anything special; the serializer handles this automatically.
+
+```typescript
+import { serialize, deserialize } from '@tstdl/base/serializer';
+
+type Node = { id: number; next?: Node };
+
+const nodeA: Node = { id: 1 };
+const nodeB: Node = { id: 2 };
+
+nodeA.next = nodeB;
+nodeB.next = nodeA; // Cycle
+
+const serialized = serialize(nodeA);
+const restored = deserialize<Node>(serialized);
+
+console.log(restored.next?.next === restored); // true
+```
+
+### Custom Serializable Classes
+
+To make your own classes serializable, implement the `Serializable` interface and use the `@serializable` decorator.
+
+```typescript
+import { Serializable, serializable, TryDereference, stringSerialize, stringDeserialize } from '@tstdl/base/serializer';
+
+type UserData = { name: string; email: string };
+
+@serializable('User') // Unique type name
+class User implements Serializable<User, UserData> {
+  constructor(
+    public name: string,
+    public email: string,
+  ) {}
+
+  // Define how to extract data.
+  // 'instance' is this, 'context' is from options.data
+  [Serializable.serialize](instance: User, context: any): UserData {
+    return { name: instance.name, email: instance.email };
+  }
+
+  // Define how to reconstruct the instance.
+  // 'tryDereference' is used to resolve circular references in complex data.
+  [Serializable.deserialize](data: UserData, tryDereference: TryDereference, context: any): User {
+    return new User(data.name, data.email);
+  }
+}
+
+const user = new User('Alice', 'alice@example.com');
+const json = stringSerialize(user);
+const restored = stringDeserialize<User>(json);
+
+console.log(restored instanceof User); // true
+console.log(restored.name); // 'Alice'
+```
+
+### Advanced Deserialization (Circular References)
+
+If your custom data structure contains other objects that might have circular references back to the object currently being deserialized, use the `tryDereference` callback.
+
+```typescript
+ [Serializable.deserialize](data: any, tryDereference: TryDereference): Folder {
+   const folder = new Folder();
+
+   for (const childData of data.children) {
+     const child = deserialize(childData);
+     folder.add(child);
+
+     // If 'child' is a forward reference (not yet fully deserialized),
+     // this will register a callback to be called once it is.
+     tryDereference(child, (dereferenced) => {
+       // logic to update the reference if needed
+     });
+   }
+
+   return folder;
+ }
+```
+
+### Registering External Types
+
+If you cannot modify the class (e.g., it comes from a third-party library), use `registerSerializer`.
+
+```typescript
+import { registerSerializer, serialize, deserialize } from '@tstdl/base/serializer';
+
+class Point {
+  constructor(
+    public x: number,
+    public y: number,
+  ) {}
+}
+
+// Register the serializer
+registerSerializer(
+  Point,
+  'Point',
+  (instance) => ({ x: instance.x, y: instance.y }), // Serializer
+  (data) => new Point(data.x, data.y), // Deserializer
+);
+
+const point = new Point(10, 20);
+const serialized = serialize(point);
+const restored = deserialize<Point>(serialized);
+
+console.log(restored instanceof Point); // true
+```
+
+### Contextual Serialization
+
+Use `context` to reference shared objects that exist in both the serialization and deserialization environments, reducing payload size.
+
+```typescript
+import { serialize, deserialize } from '@tstdl/base/serializer';
+
+const appConfig = { theme: 'dark', version: 2 };
+
+const userSettings = {
+  notifications: true,
+  config: appConfig, // Reference to shared object
+};
+
+// Pass context during serialization
+const serialized = serialize(userSettings, {
+  context: { appConfig },
+});
+
+// The serialized output will reference appConfig via path, not copy it.
+// { "notifications": true, "config": { "<ref>": "$['__context__']['appConfig']" } }
+
+// Pass the SAME context during deserialization
+const restored = deserialize<typeof userSettings>(serialized, {
+  context: { appConfig },
+});
+
+console.log(restored.config === appConfig); // true
+```
+
+### Raw Serialization
+
+Sometimes you want an object to be passed through as-is (treated as a primitive), or you know it is already JSON-safe and don't want the serializer to traverse it.
+
+```typescript
+import { registerRawSerializable, serialize } from '@tstdl/base/serializer';
+
+class Vector3 {
+  constructor(
+    public x: number,
+    public y: number,
+    public z: number,
+  ) {}
+}
+
+// Treat Vector3 as a raw object (properties are serialized directly, no type wrapper)
+registerRawSerializable(Vector3);
+
+const vec = new Vector3(1, 2, 3);
+const serialized = serialize(vec);
+
+console.log(serialized);
+// Output: { x: 1, y: 2, z: 3 }
+// Note: When deserialized, this will be a plain object, NOT an instance of Vector3.
+```
+
+### Replacers
+
+Replacers allow you to transform values before they are processed by the serializer. This is useful for sanitizing data or handling types not known by the serializer.
+
+```typescript
+import { serialize } from '@tstdl/base/serializer';
+
+const data = { password: 'secret', name: 'Bob' };
+
+const serialized = serialize(data, {
+  replacers: [
+    (value, context) => {
+      if (typeof value === 'object' && value !== null && 'password' in value) {
+        return { ...value, password: '***' };
+      }
+      return value;
+    }
+  ]
+});
+
+console.log(serialized.password); // '***'
+```
+
+### ⚠️ Security (Unsafe Serialization)
+
+By default, the serializer throws an error if it encounters a `function`. You can enable function serialization using `allowUnsafe`.
+
+> [!WARNING]
+> Enabling `allowUnsafe` is dangerous. It uses `eval()` during deserialization, which can lead to **Remote Code Execution (RCE)** if the source data is not trusted. Use this only with data from verified, secure sources.
+
+```typescript
+import { stringSerialize, stringDeserialize } from '@tstdl/base/serializer';
+
+const data = {
+  greet: (name: string) => `Hello, ${name}!`,
+};
+
+const json = stringSerialize(data, { allowUnsafe: true });
+const restored = stringDeserialize<typeof data>(json, { allowUnsafe: true });
+
+console.log(restored.greet('World')); // 'Hello, World!'
+```
+
+## 📚 API
+
+### Functions
+
+| Function                               | Description                                                                   |
+| :------------------------------------- | :---------------------------------------------------------------------------- |
+| `serialize<T>(value, options?)`        | Serializes a value into a JSON-compatible object structure (`Serialized<T>`). |
+| `deserialize<T>(data, options?)`       | Reconstructs a value from its serialized structure.                           |
+| `stringSerialize<T>(value, options?)`  | Helper that calls `serialize` and then `JSON.stringify`.                      |
+| `stringDeserialize<T>(json, options?)` | Helper that calls `JSON.parse` and then `deserialize`.                        |
+| `registerSerializer(...)`              | Manually registers a serializer/deserializer pair for a class constructor.    |
+| `registerSerializable(type, name?)`    | Registers a class that implements the `Serializable` interface.               |
+| `registerRawSerializable(ctor)`        | Registers a constructor to be treated as a raw object (passed through).       |
+
+### Decorators
+
+| Decorator                  | Description                                                      |
+| :------------------------- | :--------------------------------------------------------------- |
+| `@serializable(typeName?)` | Class decorator to register a class implementing `Serializable`. |
+
+### Interfaces & Types
+
+| Type                    | Description                                                                              |
+| :---------------------- | :--------------------------------------------------------------------------------------- |
+| `Serializable<T, Data>` | Interface requiring `[Serializable.serialize]` and `[Serializable.deserialize]` methods. |
+| `SerializationOptions`  | Options object for serialization/deserialization.                                        |
+
+### SerializationOptions
+
+```typescript
+type SerializationOptions = {
+  /**
+   * Enable de/serialization of functions (unsafe!).
+   * @default false
+   */
+  allowUnsafe?: boolean;
+
+  /**
+   * Custom replacer functions to transform values before serialization.
+   */
+  replacers?: SerializationReplacer[];
+
+  /**
+   * Constructors to treat as raw (not serialized with type info).
+   */
+  raws?: AbstractConstructor[];
+
+  /**
+   * Context object for referencing shared data.
+   */
+  context?: Record<string, any>;
+
+  /**
+   * Data object passed to custom serializers/deserializers and replacers.
+   */
+  data?: Record<string, any>;
+
+  /**
+   * Disables dereferencing of ForwardRefs. Mostly useful for debugging custom serializers.
+   * @default false
+   */
+  doNotDereferenceForwardRefs?: boolean;
+};
+```

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.