@tstdl/base 0.93.139 → 0.93.141

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/reflection/decorator-data.js

@@ -1,7 +1,6 @@
 import { DetailsError } from '../errors/details.error.js';
 import { isDefined, isFunction, isNumber, isObject, isUndefined } from '../utils/type-guards.js';
 import { getConstructor } from './utils.js';
-// eslint-disable-next-line max-lines-per-function
 export function getDecoratorData(target, propertyKey, descriptorOrParameterIndex) {
     const constructor = getConstructor(target);
     const prototype = constructor.prototype;
@@ -10,54 +9,54 @@ export function getDecoratorData(target, propertyKey, descriptorOrParameterIndex
         return {
             type: 'class',
             constructor,
-            prototype
+            prototype,
         };
     }
-    else if (isDefined(propertyKey) && isUndefined(descriptorOrParameterIndex)) {
+    if (isDefined(propertyKey) && isUndefined(descriptorOrParameterIndex)) {
         return {
             type: 'property',
             constructor,
             prototype,
             static: isStatic,
-            propertyKey
+            propertyKey,
         };
     }
-    else if (isDefined(propertyKey) && isObject(descriptorOrParameterIndex) && (isFunction(descriptorOrParameterIndex.get ?? descriptorOrParameterIndex.set))) { // eslint-disable-line @typescript-eslint/unbound-method
+    if (isDefined(propertyKey) && isObject(descriptorOrParameterIndex) && (isFunction(descriptorOrParameterIndex.get ?? descriptorOrParameterIndex.set))) { // eslint-disable-line @typescript-eslint/unbound-method
         return {
             type: 'accessor',
             constructor,
             prototype,
             static: isStatic,
             propertyKey,
-            descriptor: descriptorOrParameterIndex
+            descriptor: descriptorOrParameterIndex,
         };
     }
-    else if (isDefined(propertyKey) && isObject(descriptorOrParameterIndex) && isFunction(descriptorOrParameterIndex.value)) {
+    if (isDefined(propertyKey) && isObject(descriptorOrParameterIndex) && isFunction(descriptorOrParameterIndex.value)) {
         return {
             type: 'method',
             constructor,
             prototype,
             static: isStatic,
             methodKey: propertyKey,
-            descriptor: descriptorOrParameterIndex
+            descriptor: descriptorOrParameterIndex,
         };
     }
-    else if (isDefined(propertyKey) && isNumber(descriptorOrParameterIndex)) {
+    if (isDefined(propertyKey) && isNumber(descriptorOrParameterIndex)) {
         return {
             type: 'method-parameter',
             constructor,
             prototype,
             static: isStatic,
             methodKey: propertyKey,
-            index: descriptorOrParameterIndex
+            index: descriptorOrParameterIndex,
         };
     }
-    else if (isNumber(descriptorOrParameterIndex)) {
+    if (isNumber(descriptorOrParameterIndex)) {
         return {
             type: 'constructor-parameter',
             constructor,
             prototype,
-            index: descriptorOrParameterIndex
+            index: descriptorOrParameterIndex,
         };
     }
     throw new DetailsError('unknown type', { type: constructor, isStatic, propertyKey, descriptorOrParameterIndex });