@maxvue/max-use

@maxvue/max-use

A biblioteca de utilitários definitiva para Vue 3
VueUse + Lodash + Helpers customizados — com suporte total a reatividade.

✨ Por que MaxUse?

A MaxUse combina o melhor dos dois mundos em uma única dependência, adicionando um ecossistema completo de helpers voltados para o mercado brasileiro e projetos Laravel + Vue.

📦 Instalação

npm install @maxvue/max-use @vueuse/core @vueuse/integrations vue

Módulo Routes (Ziggy/Laravel): Se utilizar @maxvue/max-use/routes, instale também:

npm install ziggy-js vue-router

🚀 Como Usar

1. Importação Individual (Recomendado)

import { isString, isWeekend, capitalize, deepMerge } from '@maxvue/max-use'

const text = 'hello'
if (isString(text)) {
  console.log(capitalize(text)) // Hello
}

2. O Objeto Centralizado (_)

Para manter a conveniência do padrão Lodash, a MaxUse exporta o objeto _. Ele agrupa todos os helpers próprios, as funções do VueUse e do Lodash, priorizando a MaxUse em caso de conflitos.

import { _ } from '@maxvue/max-use'

// Helpers nativos da MaxUse
const id = _.intervalRandom(1, 10)
const merged = _.deepMerge({ a: 1 }, { b: 2 })

// Composables do VueUse integrados
const { x, y } = _.useMouse()

// Funções do Lodash
const debounced = _.debounce(fn, 300)

3. Importação por Submódulos

Para otimizar o bundle, importe diretamente das categorias:

import { isTouchDevice, getColorFromVar } from '@maxvue/max-use/browser'
import { addTime, isWeekend, isPast }       from '@maxvue/max-use/dates'
import { first, uniqueBy, groupBy }         from '@maxvue/max-use/iterables'
import { average, median }                  from '@maxvue/max-use/math'
import { deepMerge, renameKeys }            from '@maxvue/max-use/objects'
import { truncate, readingTime, slugify }    from '@maxvue/max-use/strings'
import { isBlank, hasContent, isNumber }     from '@maxvue/max-use/types'
import { isCpf, isEmail, cepIsValid }       from '@maxvue/max-use/validations'
import { formatCurrency, formatBytes }       from '@maxvue/max-use/format'
import { wireSize }                          from '@maxvue/max-use/electrical'
import { useRefCached, useTimeAgo }          from '@maxvue/max-use/composables'
import { apiGetRoute, goToRoute }            from '@maxvue/max-use/routes'

4. Acesso ao VueUse completo

import { vueUse } from '@maxvue/max-use'

// Todos os exports do @vueuse/core, sem filtros
const { useMouse, useStorage, useClipboard } = vueUse

⚡ Reatividade como Princípio

Diferente de bibliotecas utilitárias comuns, toda função da MaxUse entende a reatividade do Vue. Você pode passar valores puros, Refs, Computeds ou funções getter — internamente, toValue() é utilizado para resolver o valor.

import { ref, computed } from 'vue'
import { isPast, isWeekend, capitalize } from '@maxvue/max-use'

// ✅ Funciona com Refs
const date = ref(new Date('2020-01-01'))
const isExpired = computed(() => isPast(date))

// ✅ Funciona com Getters
const weekend = computed(() => isWeekend(() => new Date()))

// ✅ Funciona com valores primitivos
capitalize('hello') // 'Hello'

Convenção de tipo: Todos os parâmetros utilizam MaybeRefOrGetter<T> — o tipo nativo do Vue que aceita T | Ref<T> | (() => T).

📖 Referência Completa da API

🌐 Browser

Funções para detecção de ambiente e interação com o navegador.

import { isTouchDevice, getColorFromVar } from '@maxvue/max-use/browser'

if (isTouchDevice()) {
  console.log('Dispositivo touch detectado')
}

// Aceita tanto '--cor' quanto 'var(--cor)'
const cor = getColorFromVar('--primary-color') // '#41b883'

📅 Dates

Manipulação, verificação e cálculo de diferenças entre datas.

Verificações

Manipulação

import { addTime } from '@maxvue/max-use/dates'

addTime('2025-01-01', 30, 'days')    // Date: 31 de janeiro
addTime(new Date(), -2, 'hours')     // 2 horas atrás
addTime(date_ref, 1, 'year')         // Aceita Refs!

Unidades suportadas: 'days', 'months', 'years', 'hours', 'minutes', 'seconds' (singular também funciona).

Diferenças entre datas

Tempo decorrido

🔢 Iterables

Manipulação de arrays, coleções e objetos iteráveis.

import { groupBy, uniqueBy, orderBy, first } from '@maxvue/max-use/iterables'

const users = [
  { id: 1, name: 'Ana', role: 'admin' },
  { id: 2, name: 'João', role: 'user' },
  { id: 3, name: 'Maria', role: 'admin' }
]

groupBy(users, 'role')       // { admin: [...], user: [...] }
uniqueBy(users, 'role')      // [{ id: 1, ... }, { id: 2, ... }]
orderBy(users, ['name'])     // Ordenado por nome
first(users)                 // { id: 1, name: 'Ana', ... }

🧮 Math

Cálculos estatísticos e arredondamento.

import { average, median } from '@maxvue/max-use/math'

average([10, 20, 30])           // 20
median([1, 2, 3, 100])          // 2.5 (ignora outlier)

📦 Objects

Manipulação profunda de objetos.

Alias: cloneDeep é um alias para deepClone.

import { deepMerge, get, pick, diff } from '@maxvue/max-use/objects'

// Merge de configs
const config = deepMerge(defaults, userConfig)

// Acesso seguro a dados aninhados
const city = get(user, 'address.city', 'Desconhecida')

// Selecionar campos
const summary = pick(user, ['id', 'name', 'email'])

// Comparar objetos
const changes = diff(oldData, newData)

Objeto agrupador Obj

import { Obj } from '@maxvue/max-use/objects'

Obj.deepClone(data)
Obj.get(obj, 'a.b')
Obj.set(obj, 'a.b', 42)
Obj.isEqual(a, b)
Obj.diff(a, b)

✏️ Strings

Transformação, análise, geração e filtragem de texto.

Manipulações

Conversão de Case

Filtros

Conversores

Geração

import { Random, ulid, truncate, slugify, initials } from '@maxvue/max-use/strings'

Random(10, 'upper number')  // 'A8K3M2P1X9'
Random('ulid')              // '01hy4z3f0g...' (ULID)
ulid()                      // '01hy4z3f0g...'

truncate('Texto muito longo para exibir aqui', 20) // 'Texto muito longo pa...'
slugify('Olá Mundo! É aqui.') // 'ola-mundo-e-aqui'
initials('João Victor Silva') // 'JS'

Objetos agrupadores

import { Str, StrFilter, StrCase } from '@maxvue/max-use/strings'

Str.truncate(text, 50)
Str.ulid()
StrFilter.onlyNumbers('abc123')     // '123'
StrCase.camelCase('hello_world')    // 'helloWorld'

🔍 Types

Verificação de tipos e estados de valores.

import { isBlank, hasContent, isNumber } from '@maxvue/max-use/types'

isBlank('')           // true
isBlank(null)         // true
isBlank(0)            // true  (0 é considerado blank por padrão)
isBlank(0, true)      // false (ifZero = true: 0 tem conteúdo)
hasContent([1, 2, 3]) // true
isNumber('42')        // true
isNumber('abc')       // false

Aliases: blank → isBlank, isNumeric / numeric → isNumber, isIterable → canIterate.

✅ Validations

Validação de dados comuns, com foco em documentos brasileiros.

import { isCpf, isEmail, cepIsValid } from '@maxvue/max-use/validations'

isCpf('123.456.789-09')    // true ou false (validação real)
isEmail('user@email.com')  // true
cepIsValid('01001-000')    // true

Aliases abundantes: Cada função possui múltiplos aliases para conveniência ergonômica (ex: cpfIsValid, isValidCpf, validCpf, hasValidCpf). Use o que for mais natural para seu projeto.

Objeto agrupador validate

import { validate } from '@maxvue/max-use/validations'

validate.isCpf('123.456.789-09')
validate.isEmail('user@email.com')
validate.phone('+5511999999999')
validate.cepIsValid('01001-000')

🎨 Format

Formatadores de exibição para o mercado brasileiro.

import { formatCurrency, formatBytes, formatPhone, maskSensitive } from '@maxvue/max-use/format'

formatCurrency(1234.5)                  // 'R$ 1.234,50'
formatBytes(1536000)                    // '1.46 MB'
formatPhone('11999887766')              // '(11) 99988-7766'
maskSensitive('user@email.com', 'email') // 'use***@ema***.com'
maskSensitive('4532015112830366', 'card') // '**** **** **** 0366'

Objeto agrupador format

import { format } from '@maxvue/max-use/format'

format.currency(1500)
format.bytes(2048)
format.cpf('12345678909')
format.phone('11999887766')
format.sensitive('dados', 'text')

⚡ Electrical

Funções de domínio para cálculos de engenharia elétrica.

import { electrical } from '@maxvue/max-use/electrical'

electrical.wireSize(/* parâmetros de cálculo */)

🔧 Composables

Composables reativos para uso em componentes Vue.

useRefCached / useStorage

Cria uma Ref automaticamente sincronizada com o localStorage, com suporte a sincronização entre abas via evento storage.

import { useRefCached } from '@maxvue/max-use'

// O valor persiste no localStorage com a chave 'theme'
const theme = useRefCached('theme', 'dark')

// A chave pode ser reativa!
const userId = ref(1)
const prefs = useRefCached(() => `prefs-${userId.value}`, { sidebar: true })

Aliases: useRefStorage, useCached, useSharedCache, useStorage

useDefaultReset / refAutoReset

Cria uma Ref com valor padrão que pode ser resetada a qualquer momento. Opcionalmente, reseta automaticamente após um timer.

import { useDefaultReset } from '@maxvue/max-use'

// Ref resetável manualmente
const form = useDefaultReset({ name: '', email: '' })
form.value.name = 'João'
form.reset() // { name: '', email: '' }

// Com auto-reset após 3 segundos
const notification = useDefaultReset('', 3000)
notification.value = 'Salvo com sucesso!'
// Após 3s → volta para ''

Mágica de IDs: Se initialData contiver id: 'ulid', um novo ULID é gerado a cada reset. Se contiver created_at: 'now', a data atual é inserida.

useTimeAgo

Exibe tempo relativo em Português do Brasil, com múltiplos formatos.

import { useTimeAgo } from '@maxvue/max-use'

const timeAgo = useTimeAgo('2025-01-01')        // Ref reativa: "5 meses"
const abbrev  = useTimeAgo(date, 'abbrev')       // "5 M"
const action  = useTimeAgo(deadline, 'action')   // "Atrasado: 3 dias"
const limit   = useTimeAgo(date, 'limitAbbrev')  // "Ontem" / "Amanhã"

useDateFormat

Formata datas com fallback seguro para valores inválidos.

import { useDateFormat } from '@maxvue/max-use'

const formatted = useDateFormat('2025-06-15', 'DD/MM/YYYY') // Ref: "15/06/2025"
const time = useDateFormat(date_ref, 'HH:mm')               // Ref reativa

useCachedApi

Cache reativo com sincronização automática de API (via rotas Ziggy).

import { useCachedApi } from '@maxvue/max-use'

// Carrega do localStorage imediatamente, depois atualiza da API
const users = useCachedApi<User[]>('api.users.index', {
  defaultValue: [],
  data_get: { active: true }
})

Aliases: useRefCachedApi, useSharedCacheApi, useInCacheApi

Watchers Inteligentes

import { watchIfValid, watchDebounceIfValid } from '@maxvue/max-use'

// Executa só quando selectedUser tiver conteúdo
watchIfValid(selectedUser, (user) => {
  loadUserDetails(user.id)
})

// Com debounce de 500ms
watchDebounceIfValid(searchQuery, (query) => {
  fetchResults(query)
}, { debounce: 500 })

Aliases: watchValid, watchIsValid, watchDebouncedValid, watchDebouncedIsValid

🛤️ Routes — Integração Ziggy/Laravel

Módulo opcional para projetos Laravel + Inertia/Vue que utilizam o Ziggy para rotas nomeadas.

Setup Obrigatório

// main.ts ou app.ts
import { setLibraryRouter } from '@maxvue/max-use/routes'
import router from './router'

setLibraryRouter(router) // Necessário para goToRoute funcionar

Funções de Rota

import { apiGetRoute, apiPostRoute, goToRoute, getRoute } from '@maxvue/max-use/routes'

// Buscar dados
const users = await apiGetRoute('api.users.index', { page: 1 })

// Enviar dados
await apiPostRoute('api.users.store', { name: 'João', email: 'j@e.com' })

// Navegar
goToRoute('projects.show', { id: 42 })

// Obter URL
const url = getRoute('api.users.index') // '/api/users'

🧩 Auto Import

A MaxUse oferece integração nativa com unplugin-auto-import. Com uma única chamada, todos os helpers e composables ficam disponíveis globalmente sem imports manuais.

// vite.config.ts
import AutoImport from 'unplugin-auto-import/vite'
import { maxUseAutoImport } from '@maxvue/max-use'

export default defineConfig({
  plugins: [
    AutoImport({
      imports: [
        maxUseAutoImport(),
      ]
    })
  ]
})

Com isso, todas as funções podem ser usadas diretamente nos componentes:

<script setup>
// Nenhum import necessário!
const formatted = formatCurrency(price)
const valid = isCpf(document)
const ago = useTimeAgo(createdAt)
</script>

A função maxUseAutoImport() gera automaticamente a lista completa de exports, mantendo tudo sempre sincronizado com as atualizações da biblioteca.

📋 Resumo dos Submódulos

🤝 Contribuindo

Padrão para novos helpers

1. Reatividade obrigatória: Use MaybeRefOrGetter<T> para todos os parâmetros de entrada.
2. Resolução de valor: Utilize toValue(arg) internamente — nunca unref().
3. Documentação: Adicione JSDoc completo em pt-BR para todas as funções.
4. Exports: Registre a função no index.ts da categoria correspondente.
5. Aliases: Crie aliases ergonômicos quando fizer sentido (verbo-substantivo e substantivo-verbo).

Estrutura de diretórios

src/
├── Composables/       # Composables reativos (use*)
├── Helpers/
│   ├── Browser/       # Detecção de ambiente
│   ├── Dates/         # Manipulação de datas
│   ├── Electrical/    # Cálculos elétricos
│   ├── Format/        # Formatadores de exibição
│   ├── Iterables/     # Arrays e coleções
│   ├── Math/          # Estatísticas e arredondamento
│   ├── Objects/       # Objetos e deep operations
│   ├── Strings/       # Texto e geração
│   ├── Types/         # Verificação de tipos
│   ├── Validations/   # Validação de dados
│   └── VueUse/        # Re-export do VueUse
├── Routes/            # Integração Ziggy/Laravel
└── index.ts           # Entry point principal

Template de função

import { toValue, type MaybeRefOrGetter } from 'vue'

/**
 * Descrição da função em pt-BR.
 *
 * @param param1 Descrição do parâmetro.
 * @returns Descrição do retorno.
 */
export function minhaFuncao(
  param1: MaybeRefOrGetter<string>
): string {
  const data = toValue(param1)
  // Implementação...
  return data
}

📄 Licença

MIT License © MaxVue