add name decorator and typedoc documentation

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agape/metadata",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Metadata annotations",
   "main": "./cjs/index.js",
   "module": "./es2020/index.js",
@@ -33,8 +33,5 @@
       "require": "./cjs/index.js",
       "import": "./es2020/index.js"
     }
-  },
-  "dependencies": {
-    "@agape/string": "^2.0.0"
   }
 }

src/index.ts

@@ -1,6 +1,7 @@
 export * from './lib/decorators/description.decorator';
 export * from './lib/decorators/example.decorator';
 export * from './lib/decorators/label.decorator';
+export * from './lib/decorators/name.decorator';
 export * from './lib/decorators/noun.decorator';
 export * from './lib/decorators/sensitive.decorator';
 export * from './lib/decorators/token.decorator';
@@ -9,6 +10,7 @@ export * from './lib/functions/description';
 export * from './lib/functions/example';
 export * from './lib/functions/label';
 export * from './lib/functions/labels';
+export * from './lib/functions/name';
 export * from './lib/functions/noun';
 export * from './lib/functions/nouns';
 export * from './lib/functions/sensitive';

src/lib/decorators/description.decorator.ts

@@ -8,8 +8,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * > This decorator sets the `<property>description` property on the associated
  * {@link MetadataDescriptor}.
  *
- * ## Usage
- *
+ * @example
  * ### Class
  * ```ts
  * @Description('Represents a user profile with personal and contact information')
@@ -19,6 +18,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Property
  * ```ts
  * class Profile {
@@ -27,6 +27,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Method
  * ```ts
  * class ProfileService {
@@ -37,6 +38,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Parameter
  * ```ts
  * class ProfileService {

src/lib/decorators/example.decorator.ts

@@ -8,8 +8,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * > This decorator sets the `<property>example` property on the associated
  * {@link MetadataDescriptor}.
  *
- * ## Usage
- *
+ * @example
  * ### Class
  * ```ts
  * @Example({ name: 'Wireless Mouse', price: 29.99 })
@@ -19,6 +18,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Property
  * ```ts
  * class Product {
@@ -30,6 +30,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Method
  * ```ts
  * class ProductService {
@@ -40,6 +41,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Parameter
  * ```ts
  * class ProductService {

src/lib/decorators/label.decorator.ts

@@ -11,8 +11,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * > This decorator sets the `<property>label` and `<property>labels` properties
  * on the associated {@link MetadataDescriptor}.
  *
- * ## Usage
- *
+ * @example
  * ### Class
  * ```ts
  * @Label('Product', 'Products')
@@ -22,6 +21,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Property
  * ```ts
  * class Product {
@@ -30,6 +30,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Method
  * ```ts
  * class ProductService {
@@ -40,6 +41,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Parameter
  * ```ts
  * class ProductService {

src/lib/decorators/name.decorator.spec.ts

@@ -0,0 +1,63 @@
+import { Name } from './name.decorator';
+import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
+
+describe('Name', () => {
+
+  it('should set name on class', () => {
+    @Name('Product')
+    class Product {
+      name!: string;
+    }
+
+    const descriptor = MetadataDescriptor.for(Product);
+    expect(descriptor.name).toEqual('Product');
+  });
+
+  it('should set name on property', () => {
+    class Product {
+      @Name('skuCode')
+      sku!: string;
+    }
+
+    const descriptor = MetadataDescriptor.for(Product, 'sku');
+    expect(descriptor.name).toEqual('skuCode');
+  });
+
+  it('should set name on method', () => {
+    class ProductService {
+      @Name('createProduct')
+      create(): void {
+        // ...
+      }
+    }
+
+    const descriptor = MetadataDescriptor.for(ProductService, 'create');
+    expect(descriptor.name).toEqual('createProduct');
+  });
+
+  it('should set name on parameter', () => {
+    class ProductService {
+      create(@Name('product') product: any): void {
+        // ...
+      }
+    }
+
+    const descriptor = MetadataDescriptor.for(ProductService, 'create', 0);
+    expect(descriptor.name).toEqual('product');
+  });
+
+  it('should override automatically set name', () => {
+    @Name('CustomProduct')
+    class Product {
+      @Name('customSku')
+      sku!: string;
+    }
+
+    const classDescriptor = MetadataDescriptor.for(Product);
+    const propertyDescriptor = MetadataDescriptor.for(Product, 'sku');
+
+    expect(classDescriptor.name).toEqual('CustomProduct');
+    expect(propertyDescriptor.name).toEqual('customSku');
+  });
+
+});

src/lib/decorators/name.decorator.ts

@@ -0,0 +1,73 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Class } from '@agape/types';
+import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
+
+/**
+ * Specifies a name for the decorated class, property, method, or parameter.
+ *
+ * Names are used to identify the decorated element and can be used for
+ * serialization, validation, and other metadata-driven operations.
+ *
+ * > This decorator sets the `name` property on the associated {@link MetadataDescriptor}.
+ *
+ * @example
+ * ### Class
+ * ```ts
+ * @Name('Product')
+ * class Product {
+ *   name: string;
+ *   price: number;
+ * }
+ * ```
+ *
+ * @example
+ * ### Property
+ * ```ts
+ * class Product {
+ *   @Name('skuCode')
+ *   sku: string;
+ * }
+ * ```
+ *
+ * @example
+ * ### Method
+ * ```ts
+ * class ProductService {
+ *   @Name('createProduct')
+ *   create(): void {
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ### Parameter
+ * ```ts
+ * class ProductService {
+ *   create(@Name('product') product: Product): void {
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @decorator Class
+ * @decorator Property
+ * @decorator Method
+ * @decorator Parameter
+ * @decoratorKind Metadata
+ * @decoratorPropertyType string
+ */
+export function Name(name: string): (target: object | Class, name?: string, index?: TypedPropertyDescriptor<any> | number) => void
+export function Name(...args: any[]) {
+
+  function Name(target: object | Class, name?: string, index?: TypedPropertyDescriptor<any> | number) {
+
+    const descriptor = index !== undefined && typeof index === "number"
+      ? MetadataDescriptor.for(target, name, index)
+      : MetadataDescriptor.for(target, name);
+
+    descriptor.name = args[0];
+  }
+
+  return Name
+}

src/lib/decorators/noun.decorator.ts

@@ -10,8 +10,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * > This decorator sets the `<property>noun` and `<property>nouns` properties
  * on the associated {@link MetadataDescriptor}.
  *
- * ## Usage
- *
+ * @example
  * ### Class
  * ```ts
  * @Noun('product', 'products')
@@ -21,6 +20,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Property
  * ```ts
  * class Product {
@@ -29,6 +29,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Method
  * ```ts
  * class ProductService {
@@ -39,6 +40,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Parameter
  * ```ts
  * class ProductService {

src/lib/decorators/sensitive.decorator.ts

@@ -8,8 +8,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * > This decorator sets `<property>sensitive` to `<intrinsic>true` on the corresponding
  * {@link MetadataDescriptor}
  *
- * ## Usage
- *
+ * @example
  * ### Class
  * ```ts
  * @Sensitive
@@ -19,6 +18,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Property
  * ```ts
  * class Employee {
@@ -27,6 +27,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Method
  * ```ts
  * class AuthService {
@@ -37,6 +38,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Parameter
  * ```ts
  * class AuthService {
@@ -48,6 +50,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Explicitly disable sensitivity
  * ```ts
  * class Admin extends User {

src/lib/decorators/token.decorator.ts

@@ -13,8 +13,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * > This decorator sets the `<property>token` and `<property>tokens` properties
  * on the associated {@link MetadataDescriptor}.
  *
- * ## Usage
- *
+ * @example
  * ### Class
  * ```ts
  * @Token('product', 'products')
@@ -24,6 +23,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Property
  * ```ts
  * class Product {
@@ -32,6 +32,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Method
  * ```ts
  * class ProductService {
@@ -42,6 +43,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
  * }
  * ```
  *
+ * @example
  * ### Parameter
  * ```ts
  * class ProductService {