Skip to content

Commit e23bd48

Browse files
MaverikMinettMaverikMinett
authored
Merge pull request #4 from AgapeToolkit/metadata/typedocs
add name decorator and typedoc documentation
2 parents bbf753e + e888e79 commit e23bd48

23 files changed

Lines changed: 542 additions & 37 deletions

‎package.json‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@agape/metadata",
3-
"version": "0.1.0",
3+
"version": "0.2.0",
44
"description": "Metadata annotations",
55
"main": "./cjs/index.js",
66
"module": "./es2020/index.js",
@@ -33,8 +33,5 @@
3333
"require": "./cjs/index.js",
3434
"import": "./es2020/index.js"
3535
}
36-
},
37-
"dependencies": {
38-
"@agape/string": "^2.0.0"
3936
}
4037
}

‎src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
export * from './lib/decorators/description.decorator';
22
export * from './lib/decorators/example.decorator';
33
export * from './lib/decorators/label.decorator';
4+
export * from './lib/decorators/name.decorator';
45
export * from './lib/decorators/noun.decorator';
56
export * from './lib/decorators/sensitive.decorator';
67
export * from './lib/decorators/token.decorator';
@@ -9,6 +10,7 @@ export * from './lib/functions/description';
910
export * from './lib/functions/example';
1011
export * from './lib/functions/label';
1112
export * from './lib/functions/labels';
13+
export * from './lib/functions/name';
1214
export * from './lib/functions/noun';
1315
export * from './lib/functions/nouns';
1416
export * from './lib/functions/sensitive';

‎src/lib/decorators/description.decorator.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
88
* > This decorator sets the `<property>description` property on the associated
99
* {@link MetadataDescriptor}.
1010
*
11-
* ## Usage
12-
*
11+
* @example
1312
* ### Class
1413
* ```ts
1514
* @Description('Represents a user profile with personal and contact information')
@@ -19,6 +18,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
1918
* }
2019
* ```
2120
*
21+
* @example
2222
* ### Property
2323
* ```ts
2424
* class Profile {
@@ -27,6 +27,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
2727
* }
2828
* ```
2929
*
30+
* @example
3031
* ### Method
3132
* ```ts
3233
* class ProfileService {
@@ -37,6 +38,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
3738
* }
3839
* ```
3940
*
41+
* @example
4042
* ### Parameter
4143
* ```ts
4244
* class ProfileService {

‎src/lib/decorators/example.decorator.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
88
* > This decorator sets the `<property>example` property on the associated
99
* {@link MetadataDescriptor}.
1010
*
11-
* ## Usage
12-
*
11+
* @example
1312
* ### Class
1413
* ```ts
1514
* @Example({ name: 'Wireless Mouse', price: 29.99 })
@@ -19,6 +18,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
1918
* }
2019
* ```
2120
*
21+
* @example
2222
* ### Property
2323
* ```ts
2424
* class Product {
@@ -30,6 +30,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
3030
* }
3131
* ```
3232
*
33+
* @example
3334
* ### Method
3435
* ```ts
3536
* class ProductService {
@@ -40,6 +41,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
4041
* }
4142
* ```
4243
*
44+
* @example
4345
* ### Parameter
4446
* ```ts
4547
* class ProductService {

‎src/lib/decorators/label.decorator.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
1111
* > This decorator sets the `<property>label` and `<property>labels` properties
1212
* on the associated {@link MetadataDescriptor}.
1313
*
14-
* ## Usage
15-
*
14+
* @example
1615
* ### Class
1716
* ```ts
1817
* @Label('Product', 'Products')
@@ -22,6 +21,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
2221
* }
2322
* ```
2423
*
24+
* @example
2525
* ### Property
2626
* ```ts
2727
* class Product {
@@ -30,6 +30,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
3030
* }
3131
* ```
3232
*
33+
* @example
3334
* ### Method
3435
* ```ts
3536
* class ProductService {
@@ -40,6 +41,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
4041
* }
4142
* ```
4243
*
44+
* @example
4345
* ### Parameter
4446
* ```ts
4547
* class ProductService {

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
import { Name } from './name.decorator';
2+
import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
3+
4+
describe('Name', () => {
5+
6+
it('should set name on class', () => {
7+
@Name('Product')
8+
class Product {
9+
name!: string;
10+
}
11+
12+
const descriptor = MetadataDescriptor.for(Product);
13+
expect(descriptor.name).toEqual('Product');
14+
});
15+
16+
it('should set name on property', () => {
17+
class Product {
18+
@Name('skuCode')
19+
sku!: string;
20+
}
21+
22+
const descriptor = MetadataDescriptor.for(Product, 'sku');
23+
expect(descriptor.name).toEqual('skuCode');
24+
});
25+
26+
it('should set name on method', () => {
27+
class ProductService {
28+
@Name('createProduct')
29+
create(): void {
30+
// ...
31+
}
32+
}
33+
34+
const descriptor = MetadataDescriptor.for(ProductService, 'create');
35+
expect(descriptor.name).toEqual('createProduct');
36+
});
37+
38+
it('should set name on parameter', () => {
39+
class ProductService {
40+
create(@Name('product') product: any): void {
41+
// ...
42+
}
43+
}
44+
45+
const descriptor = MetadataDescriptor.for(ProductService, 'create', 0);
46+
expect(descriptor.name).toEqual('product');
47+
});
48+
49+
it('should override automatically set name', () => {
50+
@Name('CustomProduct')
51+
class Product {
52+
@Name('customSku')
53+
sku!: string;
54+
}
55+
56+
const classDescriptor = MetadataDescriptor.for(Product);
57+
const propertyDescriptor = MetadataDescriptor.for(Product, 'sku');
58+
59+
expect(classDescriptor.name).toEqual('CustomProduct');
60+
expect(propertyDescriptor.name).toEqual('customSku');
61+
});
62+
63+
});

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

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
/* eslint-disable @typescript-eslint/no-explicit-any */
2+
import { Class } from '@agape/types';
3+
import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
4+
5+
/**
6+
* Specifies a name for the decorated class, property, method, or parameter.
7+
*
8+
* Names are used to identify the decorated element and can be used for
9+
* serialization, validation, and other metadata-driven operations.
10+
*
11+
* > This decorator sets the `name` property on the associated {@link MetadataDescriptor}.
12+
*
13+
* @example
14+
* ### Class
15+
* ```ts
16+
* @Name('Product')
17+
* class Product {
18+
* name: string;
19+
* price: number;
20+
* }
21+
* ```
22+
*
23+
* @example
24+
* ### Property
25+
* ```ts
26+
* class Product {
27+
* @Name('skuCode')
28+
* sku: string;
29+
* }
30+
* ```
31+
*
32+
* @example
33+
* ### Method
34+
* ```ts
35+
* class ProductService {
36+
* @Name('createProduct')
37+
* create(): void {
38+
* // ...
39+
* }
40+
* }
41+
* ```
42+
*
43+
* @example
44+
* ### Parameter
45+
* ```ts
46+
* class ProductService {
47+
* create(@Name('product') product: Product): void {
48+
* // ...
49+
* }
50+
* }
51+
* ```
52+
*
53+
* @decorator Class
54+
* @decorator Property
55+
* @decorator Method
56+
* @decorator Parameter
57+
* @decoratorKind Metadata
58+
* @decoratorPropertyType string
59+
*/
60+
export function Name(name: string): (target: object | Class, name?: string, index?: TypedPropertyDescriptor<any> | number) => void
61+
export function Name(...args: any[]) {
62+
63+
function Name(target: object | Class, name?: string, index?: TypedPropertyDescriptor<any> | number) {
64+
65+
const descriptor = index !== undefined && typeof index === "number"
66+
? MetadataDescriptor.for(target, name, index)
67+
: MetadataDescriptor.for(target, name);
68+
69+
descriptor.name = args[0];
70+
}
71+
72+
return Name
73+
}

‎src/lib/decorators/noun.decorator.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
1010
* > This decorator sets the `<property>noun` and `<property>nouns` properties
1111
* on the associated {@link MetadataDescriptor}.
1212
*
13-
* ## Usage
14-
*
13+
* @example
1514
* ### Class
1615
* ```ts
1716
* @Noun('product', 'products')
@@ -21,6 +20,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
2120
* }
2221
* ```
2322
*
23+
* @example
2424
* ### Property
2525
* ```ts
2626
* class Product {
@@ -29,6 +29,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
2929
* }
3030
* ```
3131
*
32+
* @example
3233
* ### Method
3334
* ```ts
3435
* class ProductService {
@@ -39,6 +40,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
3940
* }
4041
* ```
4142
*
43+
* @example
4244
* ### Parameter
4345
* ```ts
4446
* class ProductService {

‎src/lib/decorators/sensitive.decorator.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
88
* > This decorator sets `<property>sensitive` to `<intrinsic>true` on the corresponding
99
* {@link MetadataDescriptor}
1010
*
11-
* ## Usage
12-
*
11+
* @example
1312
* ### Class
1413
* ```ts
1514
* @Sensitive
@@ -19,6 +18,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
1918
* }
2019
* ```
2120
*
21+
* @example
2222
* ### Property
2323
* ```ts
2424
* class Employee {
@@ -27,6 +27,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
2727
* }
2828
* ```
2929
*
30+
* @example
3031
* ### Method
3132
* ```ts
3233
* class AuthService {
@@ -37,6 +38,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
3738
* }
3839
* ```
3940
*
41+
* @example
4042
* ### Parameter
4143
* ```ts
4244
* class AuthService {
@@ -48,6 +50,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
4850
* }
4951
* ```
5052
*
53+
* @example
5154
* ### Explicitly disable sensitivity
5255
* ```ts
5356
* class Admin extends User {

‎src/lib/decorators/token.decorator.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
1313
* > This decorator sets the `<property>token` and `<property>tokens` properties
1414
* on the associated {@link MetadataDescriptor}.
1515
*
16-
* ## Usage
17-
*
16+
* @example
1817
* ### Class
1918
* ```ts
2019
* @Token('product', 'products')
@@ -24,6 +23,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
2423
* }
2524
* ```
2625
*
26+
* @example
2727
* ### Property
2828
* ```ts
2929
* class Product {
@@ -32,6 +32,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
3232
* }
3333
* ```
3434
*
35+
* @example
3536
* ### Method
3637
* ```ts
3738
* class ProductService {
@@ -42,6 +43,7 @@ import { MetadataDescriptor } from '../descriptors/metadata.descriptor';
4243
* }
4344
* ```
4445
*
46+
* @example
4547
* ### Parameter
4648
* ```ts
4749
* class ProductService {

0 commit comments

Comments
 (0)