@tstdl/base 0.93.139 → 0.93.141

package/schema/README.md

@@ -0,0 +1,342 @@
+# @tstdl/base/schema
+
+A powerful, TypeScript-first schema declaration and validation library. Define data structures once using builder functions or class decorators and get static types, runtime validation, and OpenAPI specifications for free.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Builder Functions](#builder-functions)
+  - [Class Decorators](#class-decorators)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Class-based Schemas](#class-based-schemas)
+  - [Type Coercion](#type-coercion)
+  - [Object Utilities](#object-utilities)
+  - [Recursive Schemas](#recursive-schemas)
+  - [OpenAPI Generation](#openapi-generation)
+  - [Function & Method Schemas](#function--method-schemas)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type Safety**: Automatically infers TypeScript types directly from your schemas.
+- **Dual API**: Define schemas using functional builders or class decorators.
+- **Runtime Validation**: Robust validation for API payloads, configuration, and user input.
+- **Type Coercion**: Automatically convert input data (e.g., strings to numbers) during parsing.
+- **Detailed Error Reporting**: JSON-path based error reporting to pinpoint exactly where validation failed.
+- **OpenAPI Support**: Generate OpenAPI v3 schema definitions from your code.
+- **Reflection**: Leverages TypeScript metadata to infer schemas from class properties.
+- **Extensible**: Supports custom transformations and complex types like `Uint8Array` and `ReadableStream`.
+
+## Core Concepts
+
+The library provides two primary ways to define schemas. Both produce a `Schema` object that can be used for validation.
+
+### Builder Functions
+
+Ideal for defining data shapes on the fly, for API contracts, or when you don't need a class instance.
+
+```typescript
+import { object, string, number } from '@tstdl/base/schema';
+
+const userSchema = object({
+  name: string(),
+  age: number(),
+});
+```
+
+### Class Decorators
+
+Ideal for domain models where you want the class to serve as both the type definition and the validation schema. This requires `experimentalDecorators` and `emitDecoratorMetadata` in your `tsconfig.json`.
+
+```typescript
+import { Class, StringProperty, NumberProperty } from '@tstdl/base/schema';
+
+@Class()
+class User {
+  @StringProperty()
+  name: string;
+
+  @NumberProperty()
+  age: number;
+}
+```
+
+## 🚀 Basic Usage
+
+The `Schema` class provides static methods to validate and parse data.
+
+```typescript
+import { Schema, object, string, number, array, optional, SchemaError } from '@tstdl/base/schema';
+
+// 1. Define a schema
+const productSchema = object({
+  id: string(),
+  name: string(),
+  price: number({ minimum: 0 }),
+  tags: array(string()),
+  description: optional(string()),
+});
+
+// 2. Infer the TypeScript type (optional, but useful)
+type Product = Schema.Output<typeof productSchema>;
+
+// 3. Validate data
+const rawData = {
+  id: 'prod_123',
+  name: 'Super Widget',
+  price: 29.99,
+  tags: ['gadget', 'new'],
+};
+
+try {
+  // .parse() returns the typed value if valid, or throws SchemaError
+  const product = Schema.parse(productSchema, rawData);
+  console.log(`Validated product: ${product.name}`);
+} catch (error) {
+  if (error instanceof SchemaError) {
+    console.error('Validation failed:', error.message);
+  }
+}
+
+// .validate() returns a boolean
+const isValid = Schema.validate(productSchema, { id: 123 }); // false
+```
+
+## 🔧 Advanced Topics
+
+### Class-based Schemas
+
+You can use decorators to define schemas directly on your classes. The class constructor itself becomes a valid schema object.
+
+```typescript
+import { Schema, Class, StringProperty, NumberProperty, Array, Integer } from '@tstdl/base/schema';
+
+@Class()
+class User {
+  @StringProperty()
+  id: string;
+
+  @StringProperty()
+  username: string;
+
+  @Integer({ minimum: 18 })
+  age: number;
+
+  @Array(String)
+  roles: string[];
+}
+
+const input = {
+  id: 'u1',
+  username: 'admin',
+  age: 25,
+  roles: ['admin', 'editor'],
+};
+
+// Pass the Class constructor to Schema methods
+const user = Schema.parse(User, input);
+
+console.log(user instanceof User); // true
+console.log(user.username); // 'admin'
+```
+
+### Type Coercion
+
+When handling data from sources like query strings or form data, types are often strings. Enable `coerce` to automatically convert them.
+
+```typescript
+import { Schema, object, number, boolean, date } from '@tstdl/base/schema';
+
+const querySchema = object({
+  page: number({ integer: true }),
+  active: boolean(),
+  from: date(),
+});
+
+const rawQuery = {
+  page: '5',
+  active: 'true',
+  from: '2023-10-27',
+};
+
+// Enable coercion in the options
+const parsed = Schema.parse(querySchema, rawQuery, { coerce: true });
+
+console.log(typeof parsed.page); // 'number'
+console.log(typeof parsed.active); // 'boolean'
+console.log(parsed.from instanceof Date); // true
+```
+
+### Object Utilities
+
+Compose new schemas from existing ones using utilities similar to TypeScript's utility types.
+
+```typescript
+import { object, string, number, pick, omit, partial, assign } from '@tstdl/base/schema';
+
+const baseUser = object({
+  id: string(),
+  name: string(),
+  email: string(),
+  age: number(),
+});
+
+// Pick specific fields
+const userSummary = pick(baseUser, ['id', 'name']);
+
+// Omit sensitive fields
+const publicUser = omit(baseUser, ['email']);
+
+// Make all fields optional (e.g., for patch updates)
+const patchUser = partial(baseUser);
+
+// Merge schemas
+const timestampedUser = assign(
+  baseUser,
+  object({
+    createdAt: number(),
+    updatedAt: number(),
+  }),
+);
+```
+
+### Recursive Schemas
+
+Use `deferred` to define schemas that reference themselves, useful for tree structures.
+
+```typescript
+import { Schema, object, string, array, optional, deferred } from '@tstdl/base/schema';
+
+type Category = {
+  name: string;
+  children?: Category[];
+};
+
+const categorySchema = object({
+  name: string(),
+  children: optional(array(deferred(() => categorySchema))),
+});
+
+const tree = {
+  name: 'Root',
+  children: [{ name: 'Child A' }, { name: 'Child B', children: [{ name: 'Grandchild B.1' }] }],
+};
+
+const validTree = Schema.parse(categorySchema, tree);
+```
+
+### OpenAPI Generation
+
+Convert your schemas into OpenAPI v3 compatible JSON schema objects. This is perfect for generating API documentation automatically.
+
+```typescript
+import { object, string, integer, enumeration } from '@tstdl/base/schema';
+import { convertToOpenApiSchema } from '@tstdl/base/schema/converters';
+
+enum Status {
+  Active = 'active',
+  Inactive = 'inactive',
+}
+
+const apiResponseSchema = object({
+  id: string({ description: 'Unique identifier' }),
+  count: integer({ minimum: 0 }),
+  status: enumeration(Status),
+});
+
+const openApiSpec = convertToOpenApiSchema(apiResponseSchema);
+console.log(JSON.stringify(openApiSpec, null, 2));
+```
+
+### Function & Method Schemas
+
+You can define schemas for functions and class methods, validating both arguments and return values.
+
+```typescript
+import { Method, StringProperty, Integer } from '@tstdl/base/schema';
+
+class Calculator {
+  @Method([Integer(), Integer()], Integer())
+  add(a: number, b: number): number {
+    return a + b;
+  }
+}
+```
+
+## 📚 API
+
+### Static Methods
+
+| Method                                     | Description                                                                         |
+| :----------------------------------------- | :---------------------------------------------------------------------------------- |
+| `Schema.parse(schema, value, options?)`    | Validates and returns the typed value. Throws `SchemaError` on failure.             |
+| `Schema.validate(schema, value, options?)` | Returns `true` if valid, `false` otherwise.                                         |
+| `Schema.assert(schema, value, options?)`   | Asserts that `value` matches the schema (TypeScript type guard). Throws on failure. |
+| `Schema.test(schema, value, options?)`     | Returns a result object `{ valid: boolean, value?: T, error?: SchemaError }`.       |
+
+### Schema Builders
+
+| Function                  | Description                                                 |
+| :------------------------ | :---------------------------------------------------------- |
+| `string(options?)`        | Schema for strings. Supports regex pattern, min/max length. |
+| `number(options?)`        | Schema for numbers. Supports min/max.                       |
+| `integer(options?)`       | Schema for integers.                                        |
+| `boolean(options?)`       | Schema for booleans.                                        |
+| `date(options?)`          | Schema for `Date` objects.                                  |
+| `bigint(options?)`        | Schema for `bigint` values.                                 |
+| `symbol(options?)`        | Schema for `symbol` values.                                 |
+| `regexp(options?)`        | Schema for `RegExp` objects.                                |
+| `object(props, options?)` | Schema for objects with defined properties.                 |
+| `record(key, value)`      | Schema for objects/dictionaries with arbitrary keys.        |
+| `array(item, options?)`   | Schema for arrays.                                          |
+| `uint8Array(options?)`    | Schema for `Uint8Array`. Supports base64/hex coercion.      |
+| `readableStream()`        | Schema for `ReadableStream`.                                |
+| `enumeration(enum)`       | Schema for TypeScript enums or array of values.             |
+| `literal(value)`          | Schema for exact primitive values.                          |
+| `union(...schemas)`       | Schema matching any one of the provided schemas.            |
+| `instance(Class)`         | Schema checking `instanceof`.                               |
+| `any()`                   | Allows any value (use carefully).                           |
+| `unknown()`               | Allows any value but types it as `unknown`.                 |
+| `never()`                 | Allows no values.                                           |
+| `func(...)`               | Schema for functions.                                       |
+
+### Modifiers & Utilities
+
+| Function                 | Description                                          |
+| :----------------------- | :--------------------------------------------------- |
+| `optional(schema)`       | Allows `undefined`.                                  |
+| `nullable(schema)`       | Allows `null`.                                       |
+| `defaulted(schema, val)` | Provides a default value if input is null/undefined. |
+| `oneOrMany(schema)`      | Accepts a single item or an array of items.          |
+| `deferred(() => schema)` | Defers schema resolution (for recursion).            |
+| `transform(schema, fn)`  | Transforms the value after validation.               |
+| `pick(schema, keys)`     | Creates a new object schema with picked keys.        |
+| `omit(schema, keys)`     | Creates a new object schema without specified keys.  |
+| `partial(schema)`        | Makes all object properties optional.                |
+| `assign(...schemas)`     | Merges multiple object schemas.                      |
+
+### Decorators
+
+| Decorator            | Description                                          |
+| :------------------- | :--------------------------------------------------- |
+| `@Class(options?)`   | Marks a class as a schema source.                    |
+| `@Property(schema?)` | Defines a property schema.                           |
+| `@StringProperty()`  | Shortcut for `string()`.                             |
+| `@NumberProperty()`  | Shortcut for `number()`.                             |
+| `@Integer()`         | Shortcut for `integer()`.                            |
+| `@BooleanProperty()` | Shortcut for `boolean()`.                            |
+| `@DateProperty()`    | Shortcut for `date()`.                               |
+| `@Array(schema)`     | Shortcut for `array()`.                              |
+| `@Optional(schema?)` | Marks property as optional.                          |
+| `@Nullable(schema?)` | Marks property as nullable.                          |
+| `@Enumeration(enum)` | Shortcut for `enumeration()`.                        |
+| `@Method(...)`       | Defines schema for method arguments and return type. |
+| `@Parameter(name)`   | Defines schema/name for a parameter.                 |
+
+### Converters
+
+| Function                         | Description                                       |
+| :------------------------------- | :------------------------------------------------ |
+| `convertToOpenApiSchema(schema)` | Converts a schema to an OpenAPI v3 schema object. |

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;
+};
+```