npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@dexcode/helpers

v3.1.0

Published

Helpers compartilhados entre os frontends DexCode: proxy de autenticação, PageProtected e dados do usuário do token para Next.js, cliente HTTP, utilitários de JWT, validação e máscara de CPF e CNPJ, máscaras de telefone e CEP e formatação de datas.

Readme

@dexcode/helpers

Helpers compartilhados entre os frontends DexCode.

npm install @dexcode/helpers

createProxy

Protege as rotas de um app Next.js 16+: libera rotas públicas, exige token, confere a expiração e verifica se o usuário tem acesso ao sistema.

// src/proxy.ts
import { createProxy } from "@dexcode/helpers";

export const proxy = createProxy({
  typeSystemAuth: "keycloak",
  system: "dexcode-system",
  tokenCookieName: "access_token",
  loginUrl: "/login",
  publicRoutes: ["/", "/auth/*", "/produtos/*"],
});

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)"],
};

Com typeSystemAuth: "personalizado", informe sua própria regra em hasSystemAccess: (payload, system) => boolean.

Renovar a sessão (refresh token)

Com refresh, o token vencido (ou a menos de marginSeconds, padrão 30) é renovado com o refresh token do Keycloak em vez de mandar para o login. Os tokens novos vão nos cookies e já valem na própria requisição (páginas, Server Functions e gateway). O usuário só volta para o loginUrl quando a sessão do Keycloak acaba.

export const proxy = createProxy({
  // ...
  refresh: {
    keycloakUrl: "https://sso.dexcodesystem.com",
    realm: "dexcode",
    clientId: "dexcode-system", // o client que emitiu o refresh token
    refreshTokenCookieName: "refresh_token",
    cookieDomain: ".dexcodesystem.com", // o mesmo de quem gravou o login; vazio em localhost
  },
});

O token é apenas decodificado; a assinatura não é validada. Valide o token de verdade no backend.

PageProtected

Server Component que só mostra a página se o usuário tiver um dos perfis. Se não tiver, redireciona no servidor para unauthorizedUrl (padrão /nao-autorizado). Sem token, ou com token expirado, redireciona para loginUrl (padrão /login). Usa next/headers, então só funciona no servidor.

// src/app/usuarios/page.tsx (Server Component)
import { PageProtected } from "@dexcode/helpers";
import { PerfilEnum } from "@/enums/PerfilEnum";

export default function UsuariosPage() {
  return (
    <PageProtected system="dexcode-system" perfil={[PerfilEnum.Master]}>
      {/* conteúdo da página */}
    </PageProtected>
  );
}
  • type="keycloak" (padrão): lê os perfis de resource_access[system].roles do token. system é obrigatório. Sem perfil, entra qualquer usuário com acesso ao sistema.
  • type="custom": informe a regra em hasAccess: (payload, perfil) => boolean | Promise<boolean>.
  • Outras props: tokenCookieName (padrão "access_token") e clockSkewSeconds (padrão 0).

O token é apenas decodificado; a assinatura não é validada. Valide o token e o perfil de verdade no backend.

getUsuarioTokenKeycloak

Dados do usuário logado, lidos do token do Keycloak no cookie. Só no servidor (Server Components, Route Handlers, Server Actions). Retorna null sem token ou com token malformado.

import { getUsuarioTokenKeycloak } from "@dexcode/helpers";

const usuario = await getUsuarioTokenKeycloak({ tokenCookieName: "access_token" });
// {
//   id: "7f3c1a52-...",              // sub
//   email: "[email protected]",
//   nome: "Ana",                      // given_name
//   sobrenome: "Souza",               // family_name
//   avatarUrl: null,                  // picture
//   perfis: { "dexcode-system": ["Master"] } // resource_access
// }
  • tokenCookieName: nome do cookie do token (padrão "access_token").
  • Com Cache Components, quem chama precisa ficar dentro de um <Suspense>, porque lê cookies da requisição.

O token é apenas decodificado; a assinatura e a expiração não são validadas. Use os dados para mostrar na tela e deixe a proteção com o createProxy, o PageProtected e o backend.

HttpClient e Gateway

Faz as chamadas para as APIs saírem do servidor Next.js: o browser chama /api/gateway/{service}/... no próprio app e o Gateway repassa para a API. Resolve APIs que não aceitam chamadas do browser (CORS) e mantém a URL delas fora do JavaScript do cliente.

1. URLs das APIs no .env (sem NEXT_PUBLIC_):

VIACEP_SERVICE_URL=https://viacep.com.br

2. Cadastro dos serviços:

// src/config/gateway.ts
import { Gateway } from "@dexcode/helpers";

const services = {
  viacep: process.env.VIACEP_SERVICE_URL,
};

export const gateway = new Gateway({ services });

// Autocomplete do "service" no HttpClient
declare module "@dexcode/helpers" {
  interface GatewayRegistry {
    services: typeof services;
  }
}

3. Rota do gateway (a pasta precisa se chamar [service], no singular):

// src/app/api/gateway/[service]/[...path]/route.ts
import { gateway } from "@/config/gateway";

const handler = gateway.handler;

export { handler as GET, handler as POST, handler as PUT, handler as PATCH, handler as DELETE };

4. Uso:

import { HttpClient } from "@dexcode/helpers";

const http = new HttpClient({ service: "viacep" });
const endereco = await http.get<Endereco>({ url: "/ws/01001000/json" });
await http.post({ url: "/clientes", data: { nome: "Ana" } });
  • Respostas que não são 2xx lançam HttpClientError (status, body).
  • O Gateway responde 404 para serviço não cadastrado e 502 quando a API não responde.
  • serverSide: false faz o browser chamar a API direto em baseUrl (só funciona se a API aceitar CORS).
  • O mesmo HttpClient funciona no servidor e no navegador (veja abaixo).

Documentação completa no site da biblioteca, em HttpClient e Gateway.

Token e servidor

  • O token do usuário logado vai sozinho: o Gateway (navegador) e o HttpClient no servidor leem o cookie do token e enviam para a API como Authorization: Bearer .... O cookie é o da variável TOKEN_COOKIE_NAME ou, sem ela, access_token; outro nome vai em tokenCookieName. O route.ts do gateway fica só com export { handler as GET, ... }.
  • Outro token só quando precisar: token na requisição (http.get({ url, token })) ou Authorization em config.headers têm prioridade sobre o cookie.
  • throwOnError: false no HttpClient: erros (e API fora do ar, 503) voltam como DefaultResponse com validationResult.isValid false, o statusCode e as mensagens da API, em vez de lançar HttpClientError.
  • Um HttpClient para os dois lados. O pacote entrega uma versão para cada lado pela condição react-server do package.json, com o mesmo import:
    • no servidor (Server Components, Server Functions e route handlers): chama a API direto em baseUrl (variável sem NEXT_PUBLIC_), envia o token do usuário logado e repassa o IP e o navegador dele (forwardClientHeaders);
    • no navegador: passa pelo gateway; o baseUrl fica vazio e não faz falta.
  • Assim o mesmo service serve para a page.tsx e para os hooks. Em Client Components, chame a API em eventos ou useEffect, nunca no corpo do componente (no SSR a versão do navegador não chega no gateway).
import { HttpClient } from "@dexcode/helpers";

const http = new HttpClient({
  service: "dexcodeservice",
  baseUrl: process.env.DEXCODE_SERVICE_API_URL,
  throwOnError: false,
});

const resposta = await http.get<DefaultResponse<Sistema[]>>({ url: "/api/Sistema/Usuario" });
if (!resposta.validationResult.isValid) { /* resposta.statusCode: 401, 403, 500... */ }

Utilitários

  • decodeJwt(token): payload do JWT ou null se malformado
  • isTokenExpired(payload, clockSkewSeconds?): se passou do exp
  • hasKeycloakSystemAccess(payload, system): se o sistema está em resource_access
  • getKeycloakSystemRoles(payload, system): perfis do usuário no sistema (resource_access[system].roles) ou null se ele não tem acesso
  • isPublicRoute(pathname, routes): se o caminho bate com alguma rota (aceita *)

CPF

import { isValidCpf, maskCpf } from "@dexcode/helpers";

isValidCpf("529.982.247-25"); // true (aceita com ou sem máscara)
isValidCpf(undefined);        // false, nunca lança erro
maskCpf("12345678909");       // "123.456.789-09"

// Formatando enquanto o usuário digita
<Input
  value={cpf}
  onChange={(e) => setCpf(maskCpf(e.target.value))}
  maxLength={14}
  inputMode="numeric"
  errorMessage={cpf.length === 14 && !isValidCpf(cpf) ? "CPF inválido." : undefined}
/>
  • isValidCpf(value): valida pelos dígitos verificadores. Vazio, null, undefined, tamanho errado ou todos os dígitos iguais retornam false.
  • maskCpf(value): formata como 000.000.000-00, parcial enquanto digita. Remove o que não é número e limita a 11 dígitos.

CNPJ

import { isValidCnpj, maskCnpj } from "@dexcode/helpers";

isValidCnpj("11.222.333/0001-81"); // true (aceita com ou sem máscara)
isValidCnpj("12.ABC.345/01DE-35"); // true (CNPJ alfanumérico)
isValidCnpj(undefined);            // false, nunca lança erro
maskCnpj("12abc34501de35");        // "12.ABC.345/01DE-35"

<Input
  value={cnpj}
  onChange={(e) => setCnpj(maskCnpj(e.target.value))}
  maxLength={18}
  errorMessage={cnpj.length === 18 && !isValidCnpj(cnpj) ? "CNPJ inválido." : undefined}
/>
  • isValidCnpj(value): valida pelos dígitos verificadores. Já aceita o CNPJ alfanumérico (letras nas 12 primeiras posições, emitido desde julho de 2026), em maiúsculas ou minúsculas. Vazio, null, undefined, tamanho errado ou todos os caracteres iguais retornam false.
  • maskCnpj(value): formata como 00.000.000/0000-00, parcial enquanto digita. Mantém dígitos e letras (em maiúsculas) e limita a 14 caracteres.

Por causa das letras, não use inputMode="numeric" no campo de CNPJ nem guarde o CNPJ como número.

Telefone e CEP

import { maskCep, maskPhone } from "@dexcode/helpers";

maskPhone("7933036727");        // "(79) 3303-6727" (fixo)
maskPhone("79981160008");       // "(79) 98116-0008" (celular)
maskPhone("+55 79 98116-0008"); // "(79) 98116-0008" (tira o +55)
maskCep("49000000");            // "49000-000"

<Input value={telefone} onChange={(e) => setTelefone(maskPhone(e.target.value))} maxLength={15} inputMode="tel" />
<Input value={cep} onChange={(e) => setCep(maskCep(e.target.value))} maxLength={9} inputMode="numeric" />
  • maskPhone(value): formata como (00) 0000-0000 (fixo, 10 dígitos) ou (00) 00000-0000 (celular, 11 dígitos), parcial enquanto digita. Remove o que não for número, tira o 55 do começo quando vier com código do país e limita a 11 dígitos.
  • maskCep(value): formata como 00000-000, parcial enquanto digita, e limita a 8 dígitos.

Para salvar sem máscara, use valor.replace(/\D/g, "").

Datas

import { formatDate, formatDateTime } from "@dexcode/helpers";

formatDate("2026-10-17");                                 // "17/10/2026"
formatDate("2026-10-18T01:30:00Z");                       // "17/10/2026" (22:30 em Brasília)
formatDateTime("2026-10-17 14:30:00");                    // "17/10/2026 14:30"
formatDateTime("2026-10-17T17:30:00Z");                   // "17/10/2026 14:30"
formatDateTime("2026-10-17T14:30:05", { seconds: true }); // "17/10/2026 14:30:05"
formatDate(null);                                         // ""
  • Aceitam texto ISO (2026-10-17, com T ou espaço, milissegundos, Z ou -03:00), 17/10/2026, Date e timestamp em ms.
  • Sem fuso ("2026-10-17", "2026-10-17 14:30"): mostra como veio, sem conversão. Evita o erro comum de "2026-10-17" virar o dia 16.
  • Com fuso, Date e timestamp: converte para o horário de Brasília (America/Sao_Paulo). O resultado é o mesmo no servidor e no navegador.
  • Vazio ou inválido (null, "abc", 31/02, 25:00) retorna "", sem lançar erro.