@attrx/role-morphic 0.1.0 → 0.2.1

package/dist/types-mbeS1e-k.d.mts

@@ -0,0 +1,312 @@
+/**
+ * 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>;
+};
+
+/**
+ * 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";
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+export type { BaseFormatOptions as B, ConversionResult as C, DateTimestamp as D, FromBaseFn as F, MorpherSpec as M, ParsedVariantId as P, RoleSpec as R, TemperatureUnit as T, ValidationResult as V, VariantSpec as a, ReversibilityResult as b, DateFormatOptions as c, RGBA as d, ColorFormatOptions as e, ToBaseFn as f, MorpherFn as g, MorpherKey as h, FormatOptions as i, FormatSpec as j, FormatFn as k, ValidationRule as l, CastFn as m, CastResult as n, DateVariant as o, DateIso as p, DateEpoch as q, ColorVariant as r, ColorHex as s, ColorRgbObject as t, ColorRgbString as u, ColorHslObject as v, ColorHslString as w };

package/dist/types-mbeS1e-k.d.ts

@@ -0,0 +1,312 @@
+/**
+ * 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>;
+};
+
+/**
+ * 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";
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+export type { BaseFormatOptions as B, ConversionResult as C, DateTimestamp as D, FromBaseFn as F, MorpherSpec as M, ParsedVariantId as P, RoleSpec as R, TemperatureUnit as T, ValidationResult as V, VariantSpec as a, ReversibilityResult as b, DateFormatOptions as c, RGBA as d, ColorFormatOptions as e, ToBaseFn as f, MorpherFn as g, MorpherKey as h, FormatOptions as i, FormatSpec as j, FormatFn as k, ValidationRule as l, CastFn as m, CastResult as n, DateVariant as o, DateIso as p, DateEpoch as q, ColorVariant as r, ColorHex as s, ColorRgbObject as t, ColorRgbString as u, ColorHslObject as v, ColorHslString as w };