@attrx/role-morphic 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1190 @@
+/**
+ * RoleMorphic Types
+ *
+ * Sistema de tipos para conversão polimórfica de valores.
+ * Um valor pode assumir múltiplas formas (variantes) mantendo sua identidade semântica.
+ *
+ * Os 4 Pilares:
+ * - Cast: Normaliza input sujo para o tipo esperado
+ * - Validate: Verifica regras semânticas do valor
+ * - Convert: Transforma entre variantes (via base)
+ * - Format: Apresenta o valor como string legível
+ */
+/**
+ * Função que converte um valor para o formato base da role
+ */
+type ToBaseFn<TValue = unknown, TBase = unknown> = (value: TValue) => TBase;
+/**
+ * Função que converte do formato base para uma variante específica
+ */
+type FromBaseFn<TBase = unknown, TValue = unknown> = (base: TBase) => TValue;
+/**
+ * Função que tenta normalizar um input desconhecido para o tipo esperado
+ * Retorna null se não conseguir fazer o cast
+ */
+type CastFn<TValue = unknown> = (input: unknown) => TValue | null;
+/**
+ * Resultado de uma operação de cast
+ */
+type CastResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Regras de validação para uma variante
+ */
+type ValidationRule = {
+    /** Valor mínimo permitido (para números) */
+    min?: number;
+    /** Valor máximo permitido (para números) */
+    max?: number;
+    /** Deve ser inteiro (para números) */
+    integer?: boolean;
+    /** Pattern regex (para strings) */
+    pattern?: RegExp;
+    /** Função de validação customizada - retorna mensagem de erro ou null se válido */
+    custom?: (value: unknown) => string | null;
+};
+/**
+ * Resultado de uma validação
+ */
+type ValidationResult = {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Opções base de formatação (compartilhadas por todas as roles)
+ */
+type BaseFormatOptions = {
+    /** Número de casas decimais */
+    decimals?: number;
+    /** Locale para formatação (ex: 'pt-BR', 'en-US') */
+    locale?: string;
+    /** Tipo de notação */
+    notation?: "standard" | "scientific" | "compact";
+    /** Usar nome completo ao invés de símbolo */
+    verbose?: boolean;
+};
+/**
+ * Opções de formatação genéricas
+ * @deprecated Use BaseFormatOptions ou tipos específicos (ColorFormatOptions, DateFormatOptions)
+ */
+type FormatOptions = BaseFormatOptions;
+/**
+ * Função de formatação customizada
+ */
+type FormatFn<TValue = unknown> = (value: TValue, options?: BaseFormatOptions) => string;
+/**
+ * Especificação de formatação para uma variante
+ */
+type FormatSpec<TValue = unknown> = {
+    /** Símbolo da unidade (ex: "m²", "ha", "°C") */
+    symbol: string;
+    /** Nome singular (ex: "meter", "hectare") */
+    singular?: string;
+    /** Nome plural (ex: "meters", "hectares") */
+    plural?: string;
+    /** Formatador customizado (override do padrão) */
+    formatter?: FormatFn<TValue>;
+};
+/**
+ * Definição de uma variante dentro de uma role
+ *
+ * Cada variante implementa os 4 pilares:
+ * - Convert: toBase/fromBase (obrigatório)
+ * - Cast: cast (opcional, usa default por type)
+ * - Validate: validate (opcional)
+ * - Format: format (opcional)
+ */
+type VariantSpec<TValue = unknown, TBase = unknown> = {
+    /** Tipo primitivo do valor nesta variante */
+    type: "string" | "number" | "boolean" | "object" | "array";
+    /** Converte o valor desta variante para o formato base */
+    toBase: ToBaseFn<TValue, TBase>;
+    /** Converte do formato base para esta variante */
+    fromBase: FromBaseFn<TBase, TValue>;
+    /** Tenta normalizar um input desconhecido para o tipo esperado */
+    cast?: CastFn<TValue>;
+    /** Regras de validação semântica */
+    validate?: ValidationRule;
+    /** Especificação de formatação */
+    format?: FormatSpec<TValue>;
+};
+/**
+ * Definição completa de uma Role
+ *
+ * Uma Role representa um conceito semântico (cor, área, data) que pode
+ * ser expresso em múltiplas variantes (hex, rgb, hsl para cor).
+ */
+type RoleSpec<TBase = unknown> = {
+    /** Nome da variante que serve como pivot para todas as conversões */
+    base: string;
+    /** Mapa de variantes disponíveis para esta role */
+    variants: Record<string, VariantSpec<unknown, TBase>>;
+};
+/**
+ * Identificador de variante parseado
+ *
+ * "color:rgb:object" => { role: "color", variant: "rgb:object" }
+ */
+type ParsedVariantId = {
+    role: string;
+    variant: string;
+};
+/**
+ * Resultado de uma conversão que pode falhar
+ */
+type ConversionResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resultado de validação de reversibilidade
+ */
+type ReversibilityResult = {
+    reversible: boolean;
+    original: unknown;
+    converted: unknown;
+    reconverted: unknown;
+};
+/**
+ * Função que transforma um valor de uma role para outra
+ */
+type MorpherFn<TFrom = unknown, TTo = unknown> = (value: TFrom) => TTo;
+/**
+ * Chave de um morpher: "fromRole:fromVariant->toRole:toVariant"
+ */
+type MorpherKey = `${string}->${string}`;
+/**
+ * Definição de um morpher
+ */
+type MorpherSpec<TFrom = unknown, TTo = unknown> = {
+    from: string;
+    to: string;
+    transform: MorpherFn<TFrom, TTo>;
+};
+
+/**
+ * RoleMorphic
+ *
+ * Motor de conversão polimórfica de valores.
+ * Permite que um valor assuma múltiplas formas (variantes) mantendo sua identidade semântica.
+ *
+ * Arquitetura Hub-and-Spoke:
+ * - Cada role tem uma variante BASE que serve como pivot
+ * - Toda conversão passa pela base: origem -> base -> destino
+ * - Isso reduz a complexidade de N² para 2N conversões
+ */
+
+declare class RoleMorphic {
+    /** Registry de roles */
+    private roles;
+    /** Registry de morphers (transformações cross-role) */
+    private morphers;
+    /**
+     * Registra uma nova role
+     */
+    register<TBase = unknown>(roleId: string, spec: RoleSpec<TBase>): this;
+    /**
+     * Remove uma role registrada
+     */
+    unregister(roleId: string): boolean;
+    /**
+     * Verifica se uma role está registrada
+     */
+    hasRole(roleId: string): boolean;
+    /**
+     * Obtém a spec de uma role
+     */
+    getRole(roleId: string): RoleSpec | undefined;
+    /**
+     * Lista todas as roles registradas
+     */
+    listRoles(): string[];
+    /**
+     * Parseia um identificador de variante
+     *
+     * "color:rgb:object" => { role: "color", variant: "rgb:object" }
+     * "area:m2" => { role: "area", variant: "m2" }
+     */
+    parseVariantId(fullId: string): ParsedVariantId;
+    /**
+     * Verifica se uma variante existe
+     */
+    hasVariant(fullId: string): boolean;
+    /**
+     * Obtém a spec de uma variante
+     */
+    getVariant(fullId: string): VariantSpec | undefined;
+    /**
+     * Lista todas as variantes de uma role
+     */
+    listVariants(roleId: string): string[];
+    /**
+     * Lista variantes para as quais uma variante pode converter
+     */
+    getConvertibleVariants(fullId: string): string[];
+    /**
+     * Converte um valor de uma variante para outra (mesma role)
+     *
+     * @param from - Identificador da variante de origem (ex: "color:hex")
+     * @param to - Identificador da variante de destino (ex: "color:rgb:object")
+     * @param value - Valor a converter
+     * @returns Valor convertido
+     * @throws Error se a conversão não for possível
+     */
+    convert<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): TTo;
+    /**
+     * Tenta converter, retornando Result ao invés de throw
+     */
+    tryConvert<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): ConversionResult<TTo>;
+    /**
+     * Verifica se uma conversão é reversível (sem perda de dados)
+     */
+    isReversible<T = unknown>(from: string, to: string, value: T): boolean;
+    /**
+     * Retorna detalhes sobre a reversibilidade de uma conversão
+     */
+    checkReversibility<T = unknown>(from: string, to: string, value: T): ReversibilityResult;
+    /**
+     * Converte apenas se a conversão for reversível
+     *
+     * @throws Error se a conversão causar perda de dados
+     */
+    convertSafe<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): TTo;
+    /**
+     * Registra um morpher para transformação entre roles diferentes
+     */
+    registerMorpher<TFrom = unknown, TTo = unknown>(spec: MorpherSpec<TFrom, TTo>): this;
+    /**
+     * Remove um morpher
+     */
+    unregisterMorpher(from: string, to: string): boolean;
+    /**
+     * Verifica se existe um morpher para a transformação
+     */
+    hasMorpher(from: string, to: string): boolean;
+    /**
+     * Lista morphers disponíveis a partir de uma variante
+     */
+    getMorphersFrom(from: string): string[];
+    /**
+     * Transforma um valor de uma role para outra usando um morpher registrado
+     */
+    morph<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): TTo;
+    /**
+     * Tenta transformar, retornando Result ao invés de throw
+     */
+    tryMorph<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): ConversionResult<TTo>;
+    /**
+     * Converte ou transforma automaticamente
+     *
+     * - Se mesma role: usa convert()
+     * - Se roles diferentes: usa morph()
+     */
+    auto<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): TTo;
+    /**
+     * Converte um valor para a variante base da sua role
+     */
+    toBase<T = unknown, TBase = unknown>(fullId: string, value: T): TBase;
+    /**
+     * Converte um valor da base para uma variante específica
+     */
+    fromBase<TBase = unknown, T = unknown>(fullId: string, baseValue: TBase): T;
+}
+
+/**
+ * IRole - Interface principal que todas as Roles devem implementar
+ *
+ * Define o contrato dos 4 pilares: Convert, Cast, Validate, Format
+ *
+ * @example
+ * class AreaRole implements IRole { ... }
+ * class ColorRole implements IRole { ... }
+ */
+
+/**
+ * Resultado de operação que pode falhar
+ */
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Interface que TODA Role deve implementar.
+ *
+ * Uma Role representa um conceito semântico (área, cor, data) que pode
+ * ser expresso em múltiplas variantes (m², hectare, acre).
+ *
+ * Os 4 pilares:
+ * - **Convert**: Transforma entre variantes (via base)
+ * - **Cast**: Normaliza input sujo para o tipo esperado
+ * - **Validate**: Verifica regras semânticas
+ * - **Format**: Apresenta como string legível
+ */
+interface IRole<TBase = unknown> {
+    /** Nome único da role (ex: "area", "color", "temperature") */
+    readonly name: string;
+    /** Nome da variante base/pivot (ex: "square_meter", "rgb_object") */
+    readonly base: string;
+    /** Retorna lista de todas as variantes disponíveis */
+    getVariants(): string[];
+    /** Verifica se uma variante existe */
+    hasVariant(variant: string): boolean;
+    /**
+     * Converte valor entre variantes da mesma role.
+     * Usa arquitetura hub-and-spoke: from → base → to
+     *
+     * @throws Error se variante não existir
+     *
+     * @example
+     * areaRole.convert('hectare', 'acre', 1) // 2.47105
+     */
+    convert<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): TTo;
+    /**
+     * Versão safe do convert que retorna Result ao invés de throw
+     *
+     * @example
+     * const result = areaRole.tryConvert('hectare', 'acre', 1);
+     * if (result.ok) console.log(result.value);
+     */
+    tryConvert<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): Result<TTo>;
+    /**
+     * Converte qualquer variante para a base
+     *
+     * @example
+     * areaRole.toBase('hectare', 1) // 10000 (m²)
+     */
+    toBase<T = unknown>(variant: string, value: T): TBase;
+    /**
+     * Converte da base para qualquer variante
+     *
+     * @example
+     * areaRole.fromBase('hectare', 10000) // 1
+     */
+    fromBase<T = unknown>(variant: string, baseValue: TBase): T;
+    /**
+     * Tenta normalizar um input desconhecido para o tipo esperado pela variante.
+     * Retorna null se não conseguir fazer o cast.
+     *
+     * @example
+     * areaRole.cast('hectare', "100 ha")     // 100
+     * areaRole.cast('hectare', "100")        // 100
+     * areaRole.cast('hectare', 100)          // 100
+     * areaRole.cast('hectare', "invalid")    // null
+     */
+    cast<T = unknown>(variant: string, input: unknown): T | null;
+    /**
+     * Versão safe do cast que retorna Result
+     *
+     * @example
+     * const result = areaRole.tryCast('hectare', "100 ha");
+     * if (result.ok) console.log(result.value);
+     */
+    tryCast<T = unknown>(variant: string, input: unknown): Result<T>;
+    /**
+     * Valida se um valor atende às regras semânticas da variante.
+     * Retorna objeto com valid: boolean e errors: string[]
+     *
+     * @example
+     * areaRole.validate('hectare', 100)  // { valid: true, errors: [] }
+     * areaRole.validate('hectare', -5)   // { valid: false, errors: ['Area cannot be negative'] }
+     */
+    validate(variant: string, value: unknown): ValidationResult;
+    /**
+     * Versão simplificada que retorna apenas boolean
+     *
+     * @example
+     * areaRole.isValid('hectare', 100) // true
+     * areaRole.isValid('hectare', -5)  // false
+     */
+    isValid(variant: string, value: unknown): boolean;
+    /**
+     * Formata valor para apresentação humana.
+     *
+     * @example
+     * areaRole.format('hectare', 2.5)                        // "2.5 ha"
+     * areaRole.format('hectare', 2.5, { verbose: true })     // "2.5 hectares"
+     * areaRole.format('hectare', 1000, { locale: 'pt-BR' })  // "1.000 ha"
+     */
+    format(variant: string, value: unknown, options?: BaseFormatOptions): string;
+    /**
+     * Gera RoleSpec para registro no RoleMorphic (backward compatible).
+     * Permite usar a nova arquitetura de classes com a API existente.
+     *
+     * @example
+     * const morph = new RoleMorphic();
+     * morph.register('area', areaRole.toSpec());
+     */
+    toSpec(): RoleSpec<TBase>;
+}
+
+/**
+ * IVariant - Interface para variantes de ComplexRole
+ *
+ * Cada variante complexa (hex, rgb:object, hsl:string) implementa esta interface.
+ * Usada quando variantes têm tipos/estruturas diferentes.
+ *
+ * @example
+ * class HexVariant implements IVariant<string, RGBA> { ... }
+ * class RgbObjectVariant implements IVariant<RGBA, RGBA> { ... }
+ */
+
+/**
+ * Interface para uma variante de ComplexRole.
+ *
+ * @typeParam TValue - Tipo do valor nesta variante (ex: string para hex, RGBA para rgb:object)
+ * @typeParam TBase - Tipo da base da role (ex: RGBA para color)
+ *
+ * @example
+ * // Variante hex de Color
+ * class HexVariant implements IVariant<string, RGBA> {
+ *   name = 'hex';
+ *   type = 'string';
+ *
+ *   toBase(hex: string): RGBA { ... }
+ *   fromBase(rgba: RGBA): string { ... }
+ *   cast(input: unknown): string | null { ... }
+ *   validate(hex: string): ValidationResult { ... }
+ *   format(hex: string, opts?): string { ... }
+ * }
+ */
+interface IVariant<TValue = unknown, TBase = unknown> {
+    /** Nome da variante (ex: "hex", "rgb:object", "hsl:string") */
+    readonly name: string;
+    /** Tipo primitivo do valor (ex: "string", "object") */
+    readonly type: "string" | "number" | "boolean" | "object" | "array";
+    /**
+     * Converte valor desta variante para o formato base da role.
+     *
+     * @example
+     * hexVariant.toBase('#ff0000') // { r: 255, g: 0, b: 0, a: 1 }
+     */
+    toBase(value: TValue): TBase;
+    /**
+     * Converte do formato base para esta variante.
+     *
+     * @example
+     * hexVariant.fromBase({ r: 255, g: 0, b: 0, a: 1 }) // '#ff0000ff'
+     */
+    fromBase(base: TBase): TValue;
+    /**
+     * Tenta normalizar um input desconhecido para o tipo desta variante.
+     * Retorna null se não conseguir.
+     *
+     * @example
+     * hexVariant.cast('ff0000')        // '#ff0000'
+     * hexVariant.cast('red')           // '#ff0000'
+     * hexVariant.cast('rgb(255,0,0)')  // '#ff0000'
+     * hexVariant.cast(123)             // null
+     */
+    cast(input: unknown): TValue | null;
+    /**
+     * Versão safe que retorna Result
+     */
+    tryCast(input: unknown): Result<TValue>;
+    /**
+     * Valida se um valor atende às regras desta variante.
+     *
+     * @example
+     * hexVariant.validate('#ff0000')   // { valid: true, errors: [] }
+     * hexVariant.validate('#gg0000')   // { valid: false, errors: ['Invalid hex character'] }
+     */
+    validate(value: TValue): ValidationResult;
+    /**
+     * Versão simplificada que retorna boolean
+     */
+    isValid(value: TValue): boolean;
+    /**
+     * Formata valor para apresentação humana.
+     *
+     * @example
+     * hexVariant.format('#ff0000')                      // '#ff0000'
+     * hexVariant.format('#ff0000', { uppercase: true }) // '#FF0000'
+     */
+    format(value: TValue, options?: BaseFormatOptions): string;
+}
+
+/**
+ * SimpleRole - Classe base abstrata para roles numéricas
+ *
+ * Para roles onde TODAS as variantes são do mesmo tipo (geralmente number).
+ * Implementa os 4 pilares com lógica compartilhada via fatores de conversão.
+ *
+ * Roles que estendem: Area, Length, Mass, Volume, Speed, Pressure, Energy, etc.
+ *
+ * @example
+ * class AreaRole extends SimpleRole<number> {
+ *   readonly name = 'area';
+ *   readonly base = 'square_meter';
+ *   readonly factors = { square_meter: 1, hectare: 10000, acre: 4046.86 };
+ *   readonly symbols = { square_meter: 'm²', hectare: 'ha', acre: 'ac' };
+ * }
+ */
+
+/**
+ * Configuração de uma unidade em SimpleRole
+ */
+interface SimpleUnitConfig {
+    /** Fator de conversão para a base (ou função para temperatura) */
+    factor?: number;
+    /** Fórmula de conversão para base (para temperatura) */
+    toBase?: (value: number) => number;
+    /** Fórmula de conversão da base (para temperatura) */
+    fromBase?: (value: number) => number;
+    /** Símbolo da unidade (ex: "m²", "ha") */
+    symbol: string;
+    /** Nome singular (ex: "hectare") */
+    singular?: string;
+    /** Nome plural (ex: "hectares") */
+    plural?: string;
+    /** Se true, não adiciona espaço antes do símbolo (ex: 45° ao invés de 45 °) */
+    noSpace?: boolean;
+}
+/**
+ * Configuração de validação para SimpleRole
+ */
+interface SimpleValidationConfig {
+    /** Valor mínimo permitido */
+    min?: number;
+    /** Valor máximo permitido */
+    max?: number;
+    /** Deve ser inteiro */
+    integer?: boolean;
+    /** Mensagem de erro customizada para min */
+    minError?: string;
+    /** Mensagem de erro customizada para max */
+    maxError?: string;
+}
+/**
+ * Alias para reconhecimento no cast
+ */
+type UnitAliases = Record<string, string>;
+/**
+ * Classe base abstrata para roles numéricas simples.
+ *
+ * Subclasses devem definir:
+ * - name: Nome da role
+ * - base: Variante base
+ * - units: Configuração de cada unidade
+ * - aliases: (opcional) Aliases para cast
+ * - validation: (opcional) Regras de validação
+ */
+declare abstract class SimpleRole implements IRole<number> {
+    /** Nome único da role */
+    abstract readonly name: string;
+    /** Nome da variante base */
+    abstract readonly base: string;
+    /** Configuração de cada unidade */
+    abstract readonly units: Record<string, SimpleUnitConfig>;
+    /** Aliases para reconhecimento no cast (ex: "ha" → "hectare") */
+    readonly aliases: UnitAliases;
+    /** Regras de validação */
+    readonly validation: SimpleValidationConfig;
+    getVariants(): string[];
+    hasVariant(variant: string): boolean;
+    convert<TFrom = number, TTo = number>(from: string, to: string, value: TFrom): TTo;
+    tryConvert<TFrom = number, TTo = number>(from: string, to: string, value: TFrom): Result<TTo>;
+    toBase<T = number>(variant: string, value: T): number;
+    fromBase<T = number>(variant: string, baseValue: number): T;
+    cast<T = number>(variant: string, input: unknown): T | null;
+    tryCast<T = number>(variant: string, input: unknown): Result<T>;
+    /**
+     * Parseia string para número, detectando unidade se presente.
+     * Subclasses podem sobrescrever para lógica customizada.
+     */
+    protected parseString(input: string, targetVariant: string): number | null;
+    /**
+     * Parseia string numérica considerando formatos brasileiro e americano
+     */
+    protected parseNumber(numStr: string): number | null;
+    /**
+     * Detecta unidade a partir de string (símbolo ou alias)
+     */
+    protected detectUnit(unitStr: string): string | null;
+    validate(variant: string, value: unknown): ValidationResult;
+    isValid(variant: string, value: unknown): boolean;
+    format(variant: string, value: unknown, options?: BaseFormatOptions): string;
+    toSpec(): RoleSpec<number>;
+}
+
+/**
+ * ComplexRole - Classe base abstrata para roles com variantes heterogêneas
+ *
+ * Para roles onde cada variante tem tipo/estrutura diferente.
+ * Cada variante é implementada como sua própria classe (IVariant).
+ *
+ * Roles que estendem: Color, Date, etc.
+ *
+ * @example
+ * class ColorRole extends ComplexRole<RGBA> {
+ *   readonly name = 'color';
+ *   readonly base = 'rgb_object';
+ *
+ *   protected createVariants() {
+ *     return {
+ *       'hex': new HexVariant(),
+ *       'rgb_object': new RgbObjectVariant(),
+ *       'rgb_string': new RgbStringVariant(),
+ *       'hsl_object': new HslObjectVariant(),
+ *     };
+ *   }
+ * }
+ */
+
+/**
+ * Classe base abstrata para roles com variantes heterogêneas.
+ *
+ * Subclasses devem definir:
+ * - name: Nome da role
+ * - base: Variante base
+ * - createVariants(): Factory que retorna mapa de variantes
+ *
+ * @typeParam TBase - Tipo do valor na variante base
+ */
+declare abstract class ComplexRole<TBase = unknown> implements IRole<TBase> {
+    /** Nome único da role */
+    abstract readonly name: string;
+    /** Nome da variante base */
+    abstract readonly base: string;
+    /** Cache das variantes */
+    private _variants;
+    /**
+     * Factory method para criar variantes.
+     * Subclasses devem implementar.
+     */
+    protected abstract createVariants(): Record<string, IVariant<unknown, TBase>>;
+    /**
+     * Retorna mapa de variantes (lazy initialization)
+     */
+    protected get variants(): Map<string, IVariant<unknown, TBase>>;
+    /**
+     * Retorna uma variante específica
+     */
+    protected getVariant(name: string): IVariant<unknown, TBase>;
+    getVariants(): string[];
+    hasVariant(variant: string): boolean;
+    convert<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): TTo;
+    tryConvert<TFrom = unknown, TTo = unknown>(from: string, to: string, value: TFrom): Result<TTo>;
+    toBase<T = unknown>(variant: string, value: T): TBase;
+    fromBase<T = unknown>(variant: string, baseValue: TBase): T;
+    cast<T = unknown>(variant: string, input: unknown): T | null;
+    tryCast<T = unknown>(variant: string, input: unknown): Result<T>;
+    validate(variant: string, value: unknown): ValidationResult;
+    isValid(variant: string, value: unknown): boolean;
+    format(variant: string, value: unknown, options?: BaseFormatOptions): string;
+    toSpec(): RoleSpec<TBase>;
+}
+
+/**
+ * Area Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de área.
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - International Yard and Pound Agreement (1959)
+ * - SI Brochure, 9th Edition (2019)
+ */
+
+type AreaUnit = "square_kilometer" | "hectare" | "are" | "square_meter" | "square_decimeter" | "square_centimeter" | "square_millimeter" | "square_mile" | "acre" | "square_yard" | "square_foot" | "square_inch";
+
+declare class AreaRole extends SimpleRole {
+    readonly name = "area";
+    readonly base = "square_meter";
+    readonly units: Record<AreaUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da AreaRole */
+declare const areaRole: AreaRole;
+
+/**
+ * Length Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de comprimento.
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - International Yard and Pound Agreement (1959)
+ * - SI Brochure, 9th Edition (2019)
+ */
+
+type LengthUnit = "kilometer" | "hectometer" | "decameter" | "meter" | "decimeter" | "centimeter" | "millimeter" | "micrometer" | "nanometer" | "inch" | "foot" | "yard" | "mile" | "nautical_mile" | "fathom" | "furlong" | "league";
+
+declare class LengthRole extends SimpleRole {
+    readonly name = "length";
+    readonly base = "meter";
+    readonly units: Record<LengthUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+}
+/** Instância singleton da LengthRole */
+declare const lengthRole: LengthRole;
+
+/**
+ * Mass Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de massa.
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - International Yard and Pound Agreement (1959)
+ * - SI Brochure, 9th Edition (2019)
+ *
+ * Nota: Massa ≠ Peso
+ * - Massa: quantidade de matéria (invariante)
+ * - Peso: força gravitacional (varia com localização)
+ */
+
+type MassUnit = "metric_ton" | "kilogram" | "hectogram" | "decagram" | "gram" | "decigram" | "centigram" | "milligram" | "microgram" | "long_ton" | "short_ton" | "stone" | "pound" | "ounce" | "dram" | "grain" | "troy_pound" | "troy_ounce" | "pennyweight";
+
+declare class MassRole extends SimpleRole {
+    readonly name = "mass";
+    readonly base = "kilogram";
+    readonly units: Record<MassUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da MassRole */
+declare const massRole: MassRole;
+
+/**
+ * Temperature Role - Constants
+ *
+ * Fórmulas de conversão, símbolos e aliases para unidades de temperatura.
+ *
+ * IMPORTANTE: Temperatura usa FÓRMULAS, não fatores multiplicativos.
+ * Isso porque as escalas têm offsets diferentes (0°C ≠ 0°F ≠ 0K).
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - SI Brochure, 9th Edition (2019)
+ */
+
+type TemperatureUnit = "celsius" | "fahrenheit" | "kelvin" | "rankine";
+
+declare class TemperatureRole extends SimpleRole {
+    readonly name = "temperature";
+    readonly base = "celsius";
+    readonly units: Record<TemperatureUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+    /**
+     * Override validate para considerar o zero absoluto na escala correta
+     */
+    validate(variant: string, value: unknown): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Retorna o zero absoluto na escala especificada
+     */
+    private getAbsoluteZero;
+}
+/** Instância singleton da TemperatureRole */
+declare const temperatureRole: TemperatureRole;
+
+/**
+ * Angle Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de ângulo.
+ *
+ * Base: degree (grau) - mais comum em aplicações práticas.
+ * Nota: Embora radiano seja a unidade SI, grau é mais intuitivo para a maioria dos casos.
+ *
+ * Fontes:
+ * - SI Brochure, 9th Edition (2019)
+ * - NIST SP 811 (2008)
+ */
+
+type AngleUnit = "turn" | "degree" | "arcminute" | "arcsecond" | "milliarcsecond" | "radian" | "milliradian" | "gradian";
+
+declare class AngleRole extends SimpleRole {
+    readonly name = "angle";
+    readonly base = "degree";
+    readonly units: Record<AngleUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+}
+/** Instância singleton da AngleRole */
+declare const angleRole: AngleRole;
+
+/**
+ * Energy Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de energia.
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - SI Brochure, 9th Edition (2019)
+ * - CODATA 2018 (electronvolt)
+ */
+
+type EnergyUnit = "gigajoule" | "megajoule" | "kilojoule" | "joule" | "millijoule" | "calorie" | "kilocalorie" | "watt_hour" | "kilowatt_hour" | "megawatt_hour" | "gigawatt_hour" | "btu" | "therm" | "electronvolt" | "kiloelectronvolt" | "megaelectronvolt" | "erg" | "foot_pound";
+
+declare class EnergyRole extends SimpleRole {
+    readonly name = "energy";
+    readonly base = "joule";
+    readonly units: Record<EnergyUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da EnergyRole */
+declare const energyRole: EnergyRole;
+
+/**
+ * Power Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de potência.
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - SI Brochure, 9th Edition (2019)
+ */
+
+type PowerUnit = "gigawatt" | "megawatt" | "kilowatt" | "watt" | "milliwatt" | "microwatt" | "horsepower_mechanical" | "horsepower_metric" | "horsepower_electric" | "horsepower_boiler" | "btu_per_hour" | "btu_per_second" | "ton_of_refrigeration" | "foot_pound_per_second" | "calorie_per_second" | "kilocalorie_per_hour";
+
+declare class PowerRole extends SimpleRole {
+    readonly name = "power";
+    readonly base = "watt";
+    readonly units: Record<PowerUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da PowerRole */
+declare const powerRole: PowerRole;
+
+/**
+ * Speed Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de velocidade.
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - SI Brochure, 9th Edition (2019)
+ * - International Yard and Pound Agreement (1959)
+ */
+
+type SpeedUnit = "meter_per_second" | "kilometer_per_hour" | "mile_per_hour" | "foot_per_second" | "knot" | "mach" | "speed_of_light";
+
+declare class SpeedRole extends SimpleRole {
+    readonly name = "speed";
+    readonly base = "meter_per_second";
+    readonly units: Record<SpeedUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+}
+/** Instância singleton da SpeedRole */
+declare const speedRole: SpeedRole;
+
+/**
+ * Date Role - Types
+ *
+ * Tipos para representação de datas nas diferentes variantes.
+ */
+/**
+ * Tipo base para Date: timestamp em milissegundos (como JavaScript Date.getTime())
+ *
+ * @example
+ * const ts: DateTimestamp = 1733425800000; // 2024-12-05T19:30:00.000Z
+ */
+type DateTimestamp = number;
+/**
+ * Variante ISO 8601
+ *
+ * @example
+ * "2024-12-05T19:30:00.000Z"
+ * "2024-12-05T19:30:00.000-03:00"
+ * "2024-12-05"
+ */
+type DateIso = string;
+/**
+ * Variante Epoch (segundos desde 1970-01-01T00:00:00Z)
+ *
+ * @example
+ * 1733425800 // 2024-12-05T19:30:00Z
+ */
+type DateEpoch = number;
+type DateVariant = "iso" | "timestamp" | "epoch";
+
+interface DateFormatOptions extends BaseFormatOptions {
+    /** Estilo de data: "full", "long", "medium", "short" */
+    dateStyle?: "full" | "long" | "medium" | "short";
+    /** Estilo de hora: "full", "long", "medium", "short" */
+    timeStyle?: "full" | "long" | "medium" | "short";
+    /** Timezone (ex: "America/Sao_Paulo", "UTC") */
+    timeZone?: string;
+    /** Se true, mostra apenas data (sem hora) */
+    dateOnly?: boolean;
+    /** Se true, mostra apenas hora (sem data) */
+    timeOnly?: boolean;
+}
+
+/**
+ * DateRole - Role para conversão e manipulação de datas
+ *
+ * ComplexRole com 3 variantes:
+ * - iso: string ISO 8601 ("2024-12-05T19:30:00.000Z")
+ * - timestamp: number em milissegundos (1733425800000)
+ * - epoch: number em segundos (1733425800)
+ *
+ * @example
+ * const date = new DateRole();
+ * date.convert('iso', 'epoch', '2024-12-05T19:30:00.000Z')  // 1733425800
+ * date.convert('epoch', 'iso', 1733425800)                  // '2024-12-05T19:30:00.000Z'
+ * date.cast('iso', '2024-12-05')                            // '2024-12-05T00:00:00.000Z'
+ * date.format('iso', '2024-12-05T19:30:00.000Z', { dateStyle: 'full', locale: 'pt-BR' })
+ */
+
+declare class DateRole extends ComplexRole<DateTimestamp> {
+    readonly name = "date";
+    readonly base = "timestamp";
+    protected createVariants(): Record<string, IVariant<unknown, DateTimestamp>>;
+    /**
+     * Override format to accept DateFormatOptions
+     */
+    format(variant: string, value: unknown, options?: DateFormatOptions): string;
+}
+/** Instância singleton da DateRole */
+declare const dateRole: DateRole;
+
+/**
+ * Volume Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de volume.
+ *
+ * Fontes:
+ * - NIST SP 811 (2008)
+ * - NIST Handbook 44 (2024)
+ * - SI Brochure, 9th Edition (2019)
+ *
+ * Notas:
+ * - Base: liter (L) - unidade aceita para uso com o SI
+ * - 1 L = 1 dm³ = 0.001 m³
+ * - Galão US vs UK: ~20% diferença (UK é maior)
+ */
+
+type VolumeUnit = "cubic_meter" | "cubic_decimeter" | "cubic_centimeter" | "cubic_millimeter" | "hectoliter" | "decaliter" | "liter" | "deciliter" | "centiliter" | "milliliter" | "microliter" | "gallon_us" | "quart_us" | "pint_us" | "cup_us" | "fluid_ounce_us" | "tablespoon_us" | "teaspoon_us" | "gallon_uk" | "quart_uk" | "pint_uk" | "fluid_ounce_uk" | "barrel_oil" | "cubic_inch" | "cubic_foot" | "cubic_yard";
+
+declare class VolumeRole extends SimpleRole {
+    readonly name = "volume";
+    readonly base = "liter";
+    readonly units: Record<VolumeUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da VolumeRole */
+declare const volumeRole: VolumeRole;
+
+/**
+ * Time Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de tempo/duração.
+ *
+ * Fontes:
+ * - SI Brochure, 9th Edition (2019)
+ * - Gregorian calendar (365.2425 dias/ano)
+ */
+
+type TimeUnit = "nanosecond" | "microsecond" | "millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year" | "decade" | "century" | "millennium";
+
+declare class TimeRole extends SimpleRole {
+    readonly name = "time";
+    readonly base = "second";
+    readonly units: Record<TimeUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da TimeRole */
+declare const timeRole: TimeRole;
+
+/**
+ * Digital Storage Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de armazenamento digital.
+ *
+ * Fontes:
+ * - IEC 60027-2 (prefixos binários)
+ * - SI Brochure, 9th Edition (2019)
+ *
+ * IMPORTANTE: Esta biblioteca suporta AMBOS os sistemas:
+ * - SI (decimal): kB, MB, GB, TB (base 1000)
+ * - IEC (binário): KiB, MiB, GiB, TiB (base 1024)
+ */
+
+type DigitalUnit = "bit" | "byte" | "kibibyte" | "mebibyte" | "gibibyte" | "tebibyte" | "pebibyte" | "exbibyte" | "kilobyte" | "megabyte" | "gigabyte" | "terabyte" | "petabyte" | "exabyte";
+
+declare class DigitalRole extends SimpleRole {
+    readonly name = "digital";
+    readonly base = "byte";
+    readonly units: Record<DigitalUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da DigitalRole */
+declare const digitalRole: DigitalRole;
+
+/**
+ * Frequency Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de frequência.
+ *
+ * Fontes:
+ * - SI Brochure, 9th Edition (2019)
+ * - NIST SP 811
+ */
+
+type FrequencyUnit = "terahertz" | "gigahertz" | "megahertz" | "kilohertz" | "hertz" | "millihertz" | "microhertz" | "rpm" | "bpm" | "radians_per_second" | "cycles_per_minute";
+
+declare class FrequencyRole extends SimpleRole {
+    readonly name = "frequency";
+    readonly base = "hertz";
+    readonly units: Record<FrequencyUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da FrequencyRole */
+declare const frequencyRole: FrequencyRole;
+
+/**
+ * Pressure Role - Constants
+ *
+ * Fatores de conversão, símbolos e aliases para unidades de pressão.
+ *
+ * Fontes:
+ * - SI Brochure, 9th Edition (2019)
+ * - NIST SP 811
+ * - 10th CGPM (1954) - definição da atmosfera padrão
+ */
+
+type PressureUnit = "megapascal" | "kilopascal" | "hectopascal" | "pascal" | "bar" | "millibar" | "atmosphere" | "torr" | "mmhg" | "inhg" | "psi" | "ksi" | "cmh2o" | "inh2o";
+
+declare class PressureRole extends SimpleRole {
+    readonly name = "pressure";
+    readonly base = "pascal";
+    readonly units: Record<PressureUnit, SimpleUnitConfig>;
+    readonly aliases: UnitAliases;
+    readonly validation: SimpleValidationConfig;
+}
+/** Instância singleton da PressureRole */
+declare const pressureRole: PressureRole;
+
+/**
+ * Color Role - Types
+ *
+ * Tipos para representação de cores nas diferentes variantes.
+ */
+/**
+ * Tipo base para Color: objeto RGBA com valores 0-255 e alpha 0-1
+ *
+ * @example
+ * const red: RGBA = { r: 255, g: 0, b: 0, a: 1 };
+ * const semiTransparent: RGBA = { r: 0, g: 0, b: 255, a: 0.5 };
+ */
+interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Variante Hex
+ *
+ * @example
+ * "#ff0000"     // RGB (6 chars)
+ * "#ff0000ff"   // RGBA (8 chars)
+ * "#f00"        // RGB shorthand (3 chars)
+ * "#f00f"       // RGBA shorthand (4 chars)
+ */
+type ColorHex = string;
+/**
+ * Variante RGB Object
+ *
+ * @example
+ * { r: 255, g: 0, b: 0 }
+ * { r: 255, g: 0, b: 0, a: 0.5 }
+ */
+interface ColorRgbObject {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+/**
+ * Variante RGB String
+ *
+ * @example
+ * "rgb(255, 0, 0)"
+ * "rgba(255, 0, 0, 0.5)"
+ */
+type ColorRgbString = string;
+/**
+ * Variante HSL Object
+ *
+ * @example
+ * { h: 0, s: 100, l: 50 }        // Red
+ * { h: 0, s: 100, l: 50, a: 0.5 } // Semi-transparent red
+ */
+interface ColorHslObject {
+    h: number;
+    s: number;
+    l: number;
+    a?: number;
+}
+/**
+ * Variante HSL String
+ *
+ * @example
+ * "hsl(0, 100%, 50%)"
+ * "hsla(0, 100%, 50%, 0.5)"
+ */
+type ColorHslString = string;
+type ColorVariant = "hex" | "rgb_object" | "rgb_string" | "hsl_object" | "hsl_string";
+
+interface ColorFormatOptions extends BaseFormatOptions {
+    /** Se true, usa letras maiúsculas para hex */
+    uppercase?: boolean;
+    /** Se true, inclui alpha mesmo quando é 1 */
+    includeAlpha?: boolean;
+    /** Se true, usa formato compacto (shorthand hex, sem espaços em rgb) */
+    compact?: boolean;
+}
+
+/**
+ * ColorRole - Role para conversão e manipulação de cores
+ *
+ * ComplexRole com 5 variantes:
+ * - hex: string hexadecimal ("#ff0000", "#ff0000ff")
+ * - rgb_object: objeto { r, g, b, a? }
+ * - rgb_string: string "rgb(255, 0, 0)" ou "rgba(255, 0, 0, 0.5)"
+ * - hsl_object: objeto { h, s, l, a? }
+ * - hsl_string: string "hsl(0, 100%, 50%)" ou "hsla(0, 100%, 50%, 0.5)"
+ *
+ * @example
+ * const color = new ColorRole();
+ * color.convert('hex', 'rgb_object', '#ff0000')  // { r: 255, g: 0, b: 0 }
+ * color.convert('rgb_object', 'hsl_string', { r: 255, g: 0, b: 0 })  // "hsl(0, 100%, 50%)"
+ * color.cast('hex', 'red')                        // '#ff0000'
+ * color.format('hex', '#ff0000', { uppercase: true })  // '#FF0000'
+ */
+
+declare class ColorRole extends ComplexRole<RGBA> {
+    readonly name = "color";
+    readonly base = "rgb_object";
+    protected createVariants(): Record<string, IVariant<unknown, RGBA>>;
+    /**
+     * Override format to accept ColorFormatOptions
+     */
+    format(variant: string, value: unknown, options?: ColorFormatOptions): string;
+}
+/** Instância singleton da ColorRole */
+declare const colorRole: ColorRole;
+
+export { AngleRole, type AngleUnit, AreaRole, type AreaUnit, type BaseFormatOptions, type CastFn, type CastResult, type ColorHex, type ColorHslObject, type ColorHslString, type ColorRgbObject, type ColorRgbString, ColorRole, type ColorVariant, type ConversionResult, type DateEpoch, type DateIso, DateRole, type DateTimestamp, type DateVariant, DigitalRole, type DigitalUnit, EnergyRole, type EnergyUnit, type FormatFn, type FormatOptions, type FormatSpec, FrequencyRole, type FrequencyUnit, type FromBaseFn, LengthRole, type LengthUnit, MassRole, type MassUnit, type MorpherFn, type MorpherKey, type MorpherSpec, type ParsedVariantId, PowerRole, type PowerUnit, PressureRole, type PressureUnit, type RGBA, type ReversibilityResult, RoleMorphic, type RoleSpec, SpeedRole, type SpeedUnit, TemperatureRole, type TemperatureUnit, TimeRole, type TimeUnit, type ToBaseFn, type ValidationResult, type ValidationRule, type VariantSpec, VolumeRole, type VolumeUnit, angleRole, areaRole, colorRole, dateRole, digitalRole, energyRole, frequencyRole, lengthRole, massRole, powerRole, pressureRole, speedRole, temperatureRole, timeRole, volumeRole };