@attrx/role-morphic 0.1.0 → 0.2.1

package/README.md

@@ -23,10 +23,10 @@ Cada role implementa 4 operações fundamentais:
 
 ## Uso Rápido
 
-### Direto (Recomendado)
+### Import Completo
 
 ```typescript
-import { areaRole, lengthRole, colorRole, dateRole } from '@attrx/role-morphic';
+import { areaRole, lengthRole, colorRole, dateRole, currencyRole } from '@attrx/role-morphic';
 
 // Area
 areaRole.convert('hectare', 'acre', 1);         // 2.47105
@@ -44,7 +44,27 @@ colorRole.format('hex', '#ff0000', { uppercase: true });  // "#FF0000"
 
 // Date
 dateRole.convert('iso', 'timestamp', '2024-12-05T00:00:00.000Z');  // 1733356800000
-dateRole.format('iso', '2024-12-05T00:00:00.000Z', { dateOnly: true });
+
+// Currency (sem convert - só validate/cast/format)
+currencyRole.cast('R$ 1.500,50');               // 1500.50
+currencyRole.format(1500.50, { currency: 'BRL' }); // "R$1.500,50"
+```
+
+### Import por Pilar (Tree-Shaking)
+
+```typescript
+// Apenas validate (zero dependências!)
+import { validateArea } from '@attrx/role-morphic/area/validate';
+import { validateDate } from '@attrx/role-morphic/date/validate';
+
+// Apenas convert
+import { convertLength, toBaseLength } from '@attrx/role-morphic/length/convert';
+
+// Apenas cast
+import { castCurrency, tryCastCurrency } from '@attrx/role-morphic/currency/cast';
+
+// Apenas format
+import { formatColor, formatHex } from '@attrx/role-morphic/color/format';
 ```
 
 ### Via RoleMorphic (Registry)
@@ -67,40 +87,63 @@ if (result.ok) {
 }
 ```
 
+## Estrutura de Arquivos
+
+Cada role segue o padrão:
+
+```
+src/roles/{role}/
+├── {Role}Role.ts      # Classe + singleton
+├── constants.ts       # Tipos e configurações
+├── validate.ts        # Pilar validate (standalone, zero deps)
+├── convert.ts         # Pilar convert
+├── cast.ts            # Pilar cast
+├── format.ts          # Pilar format
+├── index.ts           # Exports organizados
+└── {Role}Role.test.ts # Testes
+```
+
 ## API
 
+### Funções Standalone (por pilar)
+
+```typescript
+// Validate
+validateArea(100);                    // { valid: true, errors: [] }
+isValidArea(100);                     // true
+
+// Convert
+convertArea('hectare', 'acre', 1);    // 2.47105
+toBaseArea('hectare', 1);             // 10000 (→ m²)
+fromBaseArea('acre', 10000);          // 2.47105
+
+// Cast
+castArea('100 ha');                   // 100
+castArea('100 ha', 'acre');           // 247.105 (converte)
+tryCastArea('invalid');               // { ok: false, error: '...' }
+
+// Format
+formatArea('hectare', 2.5);           // "2.5 ha"
+formatArea('hectare', 2.5, { verbose: true }); // "2.5 hectares"
+```
+
 ### Role Instance Methods
 
-Cada role exporta uma instância singleton (ex: `areaRole`, `lengthRole`):
-
-| Método | Retorno | Throws |
-|--------|---------|--------|
-| `convert(from, to, value)` | `T` | Sim |
-| `tryConvert(from, to, value)` | `Result<T>` | Não |
-| `cast(variant, input)` | `T \| null` | Não |
-| `tryCast(variant, input)` | `Result<T>` | Não |
-| `validate(variant, value)` | `ValidationResult` | Não |
-| `isValid(variant, value)` | `boolean` | Não |
-| `format(variant, value, options?)` | `string` | Não |
-| `getVariants()` | `string[]` | Não |
-| `hasVariant(name)` | `boolean` | Não |
-| `toSpec()` | `RoleSpec` | Não |
-
-### RoleMorphic Methods
-
-| Método | Retorno | Throws |
-|--------|---------|--------|
-| `register(id, spec)` | `void` | Sim (duplicado) |
-| `convert(from, to, value)` | `T` | Sim |
-| `tryConvert(from, to, value)` | `Result<T>` | Não |
-| `hasRole(id)` | `boolean` | Não |
-| `hasVariant(fullId)` | `boolean` | Não |
-| `listRoles()` | `string[]` | Não |
-| `listVariants(roleId)` | `string[]` | Não |
+```typescript
+import { areaRole } from '@attrx/role-morphic';
+
+areaRole.convert('hectare', 'acre', 1);
+areaRole.cast('hectare', '100 ha');
+areaRole.validate('hectare', 100);
+areaRole.format('hectare', 2.5);
+areaRole.getVariants();               // ['square_meter', 'hectare', ...]
+areaRole.hasVariant('hectare');       // true
+areaRole.toSpec();                    // RoleSpec para RoleMorphic
+```
 
 ## Roles Disponíveis
 
-### SimpleRoles (Numéricas)
+### SimpleRoles (Numéricas - 4 pilares)
 
 | Role | Base | Variantes | Exemplo |
 |------|------|-----------|---------|
@@ -115,36 +158,32 @@ Cada role exporta uma instância singleton (ex: `areaRole`, `lengthRole`):
 | **Power** | watt | 11 | kw, hp, btu/h |
 | **Pressure** | pascal | 12 | bar, psi, atm |
 | **Frequency** | hertz | 9 | khz, mhz, rpm |
-| **Angle** | radian | 7 | degree, turn, grad |
+| **Angle** | degree | 7 | radian, turn, grad |
 | **Digital** | byte | 12 | kb, mb, gb, gib |
 
-### ComplexRoles (Heterogêneas)
+### ComplexRoles (Heterogêneas - 4 pilares)
 
 | Role | Base | Variantes |
 |------|------|-----------|
 | **Color** | rgb_object | hex, rgb_string, hsl_object, hsl_string |
 | **Date** | timestamp | iso, epoch |
 
+### MetadataRoles (3 pilares - sem convert)
+
+| Role | Pilares | Moedas |
+|------|---------|--------|
+| **Currency** | validate, cast, format | BRL, USD, EUR, GBP, JPY, +15 |
+
 ## Exemplos por Role
 
 ### Area
 
 ```typescript
-import { areaRole } from '@attrx/role-morphic';
+import { areaRole, convertArea, formatArea } from '@attrx/role-morphic';
 
 areaRole.convert('hectare', 'acre', 1);           // 2.47105
-areaRole.convert('square_meter', 'hectare', 10000); // 1
-areaRole.format('hectare', 2.5, { verbose: true }); // "2.5 hectares"
-```
-
-### Length
-
-```typescript
-import { lengthRole } from '@attrx/role-morphic';
-
-lengthRole.convert('mile', 'kilometer', 1);       // 1.609344
-lengthRole.convert('inch', 'centimeter', 1);      // 2.54
-lengthRole.cast('meter', '100 m');                // 100
+convertArea('square_meter', 'hectare', 10000);    // 1
+formatArea('hectare', 2.5, { verbose: true });    // "2.5 hectares"
 ```
 
 ### Temperature
@@ -160,42 +199,55 @@ temperatureRole.format('celsius', 25);                 // "25 °C"
 ### Color
 
 ```typescript
-import { colorRole } from '@attrx/role-morphic';
+import { colorRole, convertColor, hexToRgb } from '@attrx/role-morphic';
 
 // Hex → RGB
-colorRole.convert('hex', 'rgb_object', '#ff0000');
-// { r: 255, g: 0, b: 0, a: 1 }
-
-// RGB → HSL
-colorRole.convert('rgb_object', 'hsl_object', { r: 255, g: 0, b: 0, a: 1 });
-// { h: 0, s: 100, l: 50, a: 1 }
-
-// Format options
-colorRole.format('hex', '#ff0000', { uppercase: true });  // "#FF0000"
-colorRole.format('rgb_string', { r: 255, g: 0, b: 0, a: 1 }, { compact: true });
+convertColor('hex', 'rgb_object', '#ff0000');
+// { r: 255, g: 0, b: 0 }
+
+// Convenience functions
+hexToRgb('#ff0000');      // { r: 255, g: 0, b: 0 }
+hexToHsl('#ff0000');      // { h: 0, s: 100, l: 50 }
+isValidColor('#ff0000');  // true
+isValidColor('red');      // true (named colors)
 ```
 
 ### Date
 
 ```typescript
-import { dateRole } from '@attrx/role-morphic';
+import { dateRole, convertDate, formatDate } from '@attrx/role-morphic';
 
 // ISO → Timestamp
-dateRole.convert('iso', 'timestamp', '2024-12-05T00:00:00.000Z');
+convertDate('iso', 'timestamp', '2024-12-05T00:00:00.000Z');
 // 1733356800000
 
-// Timestamp → ISO
-dateRole.convert('timestamp', 'iso', 1733356800000);
-// "2024-12-05T00:00:00.000Z"
-
-// Format options
-dateRole.format('iso', '2024-12-05T10:30:00.000Z', {
+// Format with locale
+formatDate('iso', '2024-12-05T10:30:00.000Z', {
   dateStyle: 'long',
-  timeStyle: 'short',
   locale: 'pt-BR',
 });
 ```
 
+### Currency
+
+```typescript
+import { currencyRole, castCurrency, formatCurrency } from '@attrx/role-morphic';
+
+// Cast (parseia string → número)
+castCurrency('R$ 1.500,50');     // 1500.50
+castCurrency('$1,000.00');       // 1000
+castCurrency('€ 99,99');         // 99.99
+
+// Format (número → string com moeda)
+formatCurrency(1500.50, { currency: 'BRL' }); // "R$1.500,50"
+formatCurrency(1000, { currency: 'USD' });    // "$1,000.00"
+
+// Validate
+currencyRole.validate(100.50);                // { valid: true }
+currencyRole.validate(-50);                   // { valid: false } (por padrão)
+currencyRole.validate(-50, { allowNegative: true }); // { valid: true }
+```
+
 ## FormatOptions
 
 ### Base (todas as roles)
@@ -231,11 +283,25 @@ type DateFormatOptions = BaseFormatOptions & {
 };
 ```
 
+### Currency
+
+```typescript
+type CurrencyFormatOptions = {
+  currency: CurrencyCode; // 'BRL', 'USD', 'EUR', etc.
+  locale?: string;
+  decimals?: number;
+  verbose?: boolean;      // "1.500,50 Brazilian reais"
+  hideSymbol?: boolean;
+  showPositiveSign?: boolean;
+};
+```
+
 ## Arquitetura
 
 - **Hub-and-Spoke**: Toda conversão passa pela variante base (2N vs N² funções)
 - **SimpleRole**: Para roles numéricas - usa `factors` para conversão linear
 - **ComplexRole**: Para roles heterogêneas - cada variante implementa `IVariant`
+- **MetadataRole**: Para roles onde o "tipo" é metadata (ex: currency code)
 
 Ver [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) para detalhes.
 
@@ -246,21 +312,21 @@ Ver [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) para detalhes.
 ```typescript
 import { SimpleRole, SimpleUnitConfig } from '@attrx/role-morphic';
 
-const CURRENCY_UNITS: Record<string, SimpleUnitConfig> = {
-  brl: { factor: 1, symbol: 'R$' },
-  usd: { factor: 0.20, symbol: '$' },  // 1 BRL = 0.20 USD
-  eur: { factor: 0.18, symbol: '€' },
+const DISTANCE_UNITS: Record<string, SimpleUnitConfig> = {
+  meter: { factor: 1, symbol: 'm' },
+  lightyear: { factor: 9.461e15, symbol: 'ly' },
+  parsec: { factor: 3.086e16, symbol: 'pc' },
 };
 
-class CurrencyRole extends SimpleRole {
-  readonly name = 'currency';
-  readonly base = 'brl';
-  readonly units = CURRENCY_UNITS;
-  readonly aliases = { real: 'brl', dollar: 'usd', euro: 'eur' };
+class AstronomicalRole extends SimpleRole {
+  readonly name = 'astronomical';
+  readonly base = 'meter';
+  readonly units = DISTANCE_UNITS;
+  readonly aliases = { ly: 'lightyear' };
 }
 
-const currencyRole = new CurrencyRole();
-currencyRole.convert('brl', 'usd', 100);  // 20
+const astroRole = new AstronomicalRole();
+astroRole.convert('lightyear', 'parsec', 1);  // 0.3066
 ```
 
 ### Via RoleSpec
@@ -268,24 +334,25 @@ currencyRole.convert('brl', 'usd', 100);  // 20
 ```typescript
 import { RoleMorphic, RoleSpec } from '@attrx/role-morphic';
 
-const currencySpec: RoleSpec<number> = {
-  base: 'cents',
+const percentSpec: RoleSpec<number> = {
+  base: 'decimal',
   variants: {
-    cents: {
+    decimal: {
       type: 'number',
       toBase: (v) => v,
       fromBase: (v) => v,
     },
-    dollars: {
+    percent: {
       type: 'number',
-      toBase: (d) => Math.round(d * 100),
-      fromBase: (c) => c / 100,
+      toBase: (p) => p / 100,
+      fromBase: (d) => d * 100,
     },
   },
 };
 
 const morph = new RoleMorphic();
-morph.register('currency', currencySpec);
+morph.register('percent', percentSpec);
+morph.convert('percent:percent', 'percent:decimal', 50);  // 0.5
 ```
 
 ## Testes
@@ -294,7 +361,7 @@ morph.register('currency', currencySpec);
 pnpm test
 ```
 
-**Status:** 15 roles, 1324 testes
+**Status:** 16 roles, 1407 testes
 
 ## Licença