# Pacote `@nodusjs/std/spark`

O pacote `spark` é uma coleção de pequenas funções puras e reutilizáveis, projetadas para a **transformação de dados**. Ele é um pilar fundamental do ecossistema `@nodusjs/std`, atuando como a "cola" que permite manipular os dados que fluem entre os componentes e seus eventos.

## Responsabilidade: Transformação de Dados em Fluxo

A principal responsabilidade do `spark` é fornecer um conjunto de ferramentas para construir "pipelines" de dados. Cada *spark* é uma função simples que recebe um valor, o transforma de alguma forma e o repassa para a próxima etapa.

Isso permite que você componha lógicas complexas a partir de blocos de construção simples, mantendo seu código limpo e declarativo. Os sparks são usados principalmente como **filtros** em três contextos principais:

1.  **No atributo `on` (mixin `Echo`)**: Para transformar dados de eventos antes que cheguem a um componente.
2.  **No decorator `@attributeChanged`**: Para converter o valor de um atributo (que é sempre string) para um tipo mais útil (booleano, número, etc.).
3.  **No decorator `@event`**: Para processar o objeto de evento antes que ele chegue ao método manipulador.

## Como Usar os Sparks

### Exemplo 1: Como Filtro no Atributo `on` (Echo)

Este é o caso de uso mais poderoso. Você pode encadear sparks usando o caractere `|` para criar um pipeline de transformação de dados diretamente no seu HTML.

```html
<div on="*/user-status-changed:setter/message|prop=detail.name|add=' está online!'"></div>
```

**Fluxo de dados:**

1.  O evento é disparado. Seu objeto `detail` é o dado inicial.
2.  `prop=detail.name`: O spark `prop` extrai a propriedade `name`, resultando na string `"Ana"`.
3.  `add=' está online!'`: O spark `add` concatena a string, resultando em `"Ana está online!"`.
4.  O `setter` `message` do `<div>` é chamado com o resultado final.

### Exemplo 2: Como Filtro no Decorator `@attributeChanged`

Use sparks para converter o valor de um atributo antes que ele chegue ao seu setter.

```javascript
import { attributeChanged } from '@nodusjs/std/directive';
import { inc, truthy } from '@nodusjs/std/spark';

class MyComponent extends HTMLElement {
  // O valor do atributo 'data-count' (string) será convertido para
  // número e depois incrementado antes de chegar ao setter.
  @attributeChanged('data-count', Number, inc)
  set count(newValue) {
    // newValue será um número, não uma string.
  }

  // O valor do atributo 'visible' será convertido para booleano.
  @attributeChanged('visible', truthy)
  set visible(isVible) {
    // isVisible será true ou false.
  }
}
```

### Exemplo 3: Como Filtro no Decorator `@event`

Use sparks para extrair e transformar informações do objeto de evento.

```javascript
import event from '@nodusjs/std/event';
import { prop } from '@nodusjs/std/spark';

class MyComponent extends HTMLElement {
  // Extrai o valor do input (evt.target.value) e o passa como
  // argumento para o método handleInput.
  @event.input('input', prop('target.value'))
  handleInput(inputValue) {
    // inputValue é a string do input, não o objeto de evento completo.
    console.log(inputValue);
  }
}
```

## Sparks Disponíveis

Aqui está uma lista dos sparks prontos para uso:

  - `add(x, y)`: Soma `y` a `x`.
  - `always(token, value)`: Retorna sempre `value`, ignorando o valor anterior.
  - `dec(x)`: Decrementa um número.
  - `different(x, y)`: Compara se `x` é diferente de `y`.
  - `equals(x, y)`: Compara se `x` é igual a `y`.
  - `gt(x, y)`: Verifica se `x` é maior que `y`.
  - `gte(x, y)`: Verifica se `x` é maior ou igual a `y`.
  - `inc(x)`: Incrementa um número.
  - `len(x)`: Retorna o comprimento (tamanho) de um objeto ou string.
  - `lt(x, y)`: Verifica se `x` é menor que `y`.
  - `lte(x, y)`: Verifica se `x` é menor ou igual a `y`.
  - `not(x)`: Nega um valor booleano.
  - `prop(target, path)`: Acessa uma propriedade aninhada em um objeto.
  - `subtract(x, y)`: Subtrai `y` de `x`.
  - `truthy(value)`: Converte um valor para um booleano (útil para atributos HTML).