pulse-agent
112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
# @pulse-libs/core — Biblioteca Universal Atomizada
|
|
|
|
> **React · Hooks · Utils · Validators** em um único pacote
|
|
> `npm install @pulse-libs/core`
|
|
|
|
---
|
|
|
|
## 📐 Estrutura real do projeto
|
|
|
|
```
|
|
@pulse-libs/core
|
|
├── src/
|
|
│ ├── types/ → Result / AsyncState / Paginated / SortConfig (zero deps)
|
|
│ ├── utils/ → date, str, num, cn, debounce, throttle, storage, arr, obj (zero deps)
|
|
│ ├── validators/ → Zod schemas: email, password, uuid, url, phone, CPF/CNPJ
|
|
│ ├── hooks/ → useToggle, useAsync, useDebounce, useLocalStorage, useMedia, useInterval, useOnClickOutside, useClipboard, useFetch
|
|
│ ├── components/ → Button, Input, Alert, Card (+Header/Title/Body), Spinner (React)
|
|
│ └── index.ts → barrel export principal
|
|
├── tests/ → vitest + jsdom — 57 testes, 100% passando
|
|
├── dist/ → ESM + CJS + DTS + sourcemaps (gerado por tsup v8)
|
|
├── Dockerfile → multi-stage Node 20 Alpine
|
|
├── __docs__/ → guias de deploy, docker, arquitetura
|
|
└── package.json → sub-exports por camada
|
|
```
|
|
|
|
## 📦 Imports por camada
|
|
|
|
```tsx
|
|
// ── Root barrel
|
|
import { Button, useAsync, date, cn } from '@pulse-libs/core';
|
|
|
|
// ── Sub-exports (tree-shakeable)
|
|
import { Button, Input, Alert } from '@pulse-libs/core/components';
|
|
import { useToggle, useDebounce } from '@pulse-libs/core/hooks';
|
|
import { cn, date, str, num, storage } from '@pulse-libs/core/utils';
|
|
import { emailSchema, safeParse } from '@pulse-libs/core/validators';
|
|
import type { Result, AsyncState } from '@pulse-libs/core/types';
|
|
```
|
|
|
|
## 🏗️ Filosofia atômica
|
|
|
|
Uma camada **nunca importa de uma camada de nível inferior**:
|
|
|
|
```
|
|
utils ← zero deps
|
|
types ← zero deps
|
|
validators ← usa utils, types, zod
|
|
hooks ← usa utils, types, react
|
|
components ← usa utils, validators
|
|
```
|
|
|
|
### Convenções de código
|
|
|
|
| Regra | Por quê |
|
|
|-------|---------|
|
|
| `className` sempre no topo dos props | Tailwind merge via `cn()` |
|
|
| `...rest` sempre por último | Não mata props nativas |
|
|
| Funções puras em `utils/` | Testáveis sem setup |
|
|
| Schema Zod é a **única** fonte de verdade | Sem validação duplicada |
|
|
| DTS arquivos declarados (`--dts`) | Imports no TS dos consumidores |
|
|
| `flat(2)` nunca `flat(Infinity)` | Quebra DTS generate |
|
|
|
|
## 🔄 Versionamento
|
|
|
|
| Fase | Tag | Significado |
|
|
|------|-----|-------------|
|
|
| alpha | `1.0.0-alpha.x` | API instável |
|
|
| beta | `1.0.0-beta.x` | feature-complete, API pode mudar |
|
|
| stable | `1.0.0` | API congelada, sem breaking em minor |
|
|
|
|
## 🚀 Comandos
|
|
|
|
```bash
|
|
npm run build # tsup ESM+CJS+DTS+sourcemaps
|
|
npm run build:esm # ESM only
|
|
npm run build:cjs # CJS only
|
|
npm test # vitest run (57 testes)
|
|
npm test:w # vitest watch mode
|
|
npm run coverage # relatorio de cobertura
|
|
npm run typecheck # tsc --noEmit
|
|
npm run lint # eslint (se configurado)
|
|
npm run dev # tsup --watch
|
|
npm run clean # rm -rf dist coverage .tsup
|
|
npm run release # bumpp + git push --follow-tags
|
|
```
|
|
|
|
## 🐳 Docker
|
|
|
|
```bash
|
|
# Build image
|
|
docker build -t pulse-libs/core:1.0.0-beta.1 .
|
|
|
|
# Ou com docker-compose
|
|
docker compose build
|
|
|
|
# Test local
|
|
docker compose run core npm test
|
|
```
|
|
|
|
## 📚 Documentação adicional
|
|
|
|
- [`__docs__/docker/build-guide.md`](__docs__/docker/build-guide.md) — Guia de build e publish Docker
|
|
- [`__docs__/docker/architecture.md`](__docs__/docker/architecture.md) — Arquitetura da biblioteca
|
|
|
|
## 🤝 Contribuir
|
|
|
|
- Issues com tag `[bug]`, `[feat]`, `[docs]`
|
|
- PRs devem Rodar `npm test` + `npm run typecheck` antes
|
|
- Cada camada nova precisa de pelo menos 1 teste unitário
|
|
- Breaking changes só em major version (`2.0.0`, `3.0.0`, …)
|
|
- Sem duplicação de lógica — extrair para utils antes de adicionar
|