pulse-libs/projetos/@pulse-libs/core

@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

// ── 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

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

# 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 — Guia de build e publish Docker
• __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