open-index/open-npm huggingface dataset:
npm package: @koph-npm/browser-backbutton
Description: > Gerencie ações personalizadas ao pressionar o botão "voltar" do navegador.
Latest version: 0.0.2

# @koph-npm/browser-backbutton

> Gerencie ações personalizadas ao pressionar o botão "voltar" do navegador.

Este módulo fornece uma API simples e poderosa para interceptar e controlar o comportamento do botão de "voltar" no navegador. Ideal para SPAs, modais, formulários ou fluxos com navegação controlada.

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-backbutton
```

---

## 🚀 Uso básico

### 1. Registrar ação personalizada ao voltar

```ts
import { BackButton } from '@koph-npm/browser-backbutton';

BackButton.onNextAction(() => {
  console.log('Fechando modal...');
  fecharModal();
});
```

> Isso adiciona um estado ao `history` e executa a função registrada se o usuário clicar em "voltar".

---

### 2. Cancelar a próxima ação (sem executá-la)

```ts
BackButton.cancelNextAction(true); // cancela e impede que a função seja executada
```

---

### 3. Limpar todas as ações registradas

```ts
await BackButton.clear(); // desfaz todos os estados e executa os callbacks (se aplicável)
```

---

## 🧠 API

### `BackButton.onNextAction(callback: () => void): Promise<void>`

Registra uma nova ação para ser executada ao voltar no histórico.

### `BackButton.cancelNextAction(cancel?: boolean): Promise<void>`

Cancela a próxima ação registrada. Se `cancel = true`, o callback não será executado.

### `BackButton.clear(): Promise<void>`

Remove todas as ações registradas e reverte o histórico.

---

## ⚠️ Observações

- Este módulo só funciona em **ambientes de navegador**.
- Evite múltiplas instâncias do módulo na mesma aplicação.
- Use com cuidado em apps que já manipulam `window.history`.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/browser-cache
Description: > Cache flexível para navegadores com suporte a localStorage, sessionStorage e armazenamento em memória.
Latest version: 0.0.2

# @koph-npm/browser-cache

> Cache flexível para navegadores com suporte a localStorage, sessionStorage e armazenamento em memória.

`CacheJS` é uma biblioteca que permite armazenar dados temporariamente no navegador com opções de expiração, prefixo customizável, modo seguro e gerenciamento global.

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-cache
```

---

## 🚀 Uso básico

```ts
import { CacheJS } from '@koph-npm/browser-cache';

// Criar uma instância de cache com timeout de 10 minutos usando localStorage
const cache = new CacheJS("user-cache", 10 * 60000, "local");

// Armazenar um valor
cache.set("username", "JohnDoe");

// Recuperar o valor
console.log(cache.get("username")); // "JohnDoe"

// Remover o item
cache.remove("username");

// Desativar o cache globalmente
CacheJS.disable();

// Limpar todos os caches
CacheJS.clearAll();
```

---

## 🧠 API

### Instância

- `new CacheJS(id, timeout, storageType)`
    - `id`: identificador do conjunto de chaves
    - `timeout`: tempo em milissegundos para expiração (padrão: 5 minutos)
    - `storageType`: "local" | "session" | "memory"

#### Métodos

- `cache.get(id, defaultValue?, persistent?)`
- `cache.set(id, value, timeout?)`
- `cache.remove(id)`
- `cache.clear()`
- `cache.key(id)`

### Estáticos

- `CacheJS.setPrefix(value: string)`
- `CacheJS.clearAll()`
- `CacheJS.disable(flag = true)`
- `CacheJS.version(value: string)`

---

## ⚠️ Observações

- `memoryStorage` é volátil e não persiste após reload.
- `CacheJS.disable()` bloqueia todas as operações de leitura/escrita.
- Use `version()` para invalidar cache entre versões da aplicação.

---

## 📄 Licença

MIT

---

## 👤 Autor

Fabio Nogueira <fabio.bacabal@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/browser-device
Description: > Identificador exclusivo e persistente do dispositivo (navegador), com redundância em múltiplos armazenamentos.
Latest version: 0.0.2

# @koph-npm/browser-device

> Identificador exclusivo e persistente do dispositivo (navegador), com redundância em múltiplos armazenamentos.

Este módulo gera um ID único para o navegador do usuário e o armazena de forma redundante em `localStorage`, `IndexedDB` e cookies. Isso garante persistência entre sessões e mesmo após atualizações da página.

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-device
```

---

## 🚀 Uso básico

```ts
import { Device } from '@koph-npm/browser-device';

async function init() {
  const id = await Device.id();
  console.log("ID único do dispositivo:", id);
}

init();
```

> Exemplo de saída: `'f7c93089-4a7e-4a9c-8c52-1b2b4b1f00a1'`

---

## ⚙️ API

### `Device.id(): Promise<string>`

Retorna o ID persistente do dispositivo. Gera um novo se necessário e salva em todos os meios disponíveis.

---

## ⚠️ Observações

- Utiliza `crypto.randomUUID()` se disponível; caso contrário, gera UUID manualmente.
- Ideal para rastrear dispositivos em SPAs e apps offline.
- Funciona apenas em ambientes de navegador.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/browser-jwt
Description: > Utilitários para manipulação de JWTs no navegador, com suporte a validação de expiração e geração simplificada.
Latest version: 0.0.2

# @koph-npm/browser-jwt

> Utilitários para manipulação de JWTs no navegador, com suporte a validação de expiração e geração simplificada.

Este pacote oferece funções para decodificar, verificar validade e gerar JSON Web Tokens (JWT) diretamente no navegador, sem dependências externas.

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-jwt
```

---

## 🚀 Uso básico

```ts
import { jwt } from '@koph-npm/browser-jwt';

const token = jwt.encode({ user: 'john' });

const decoded = jwt.decode(token);
console.log(decoded.payload.user); // "john"
```

---

## 🧠 API

### `jwt.decodeOnly(token: string): TDecoded | null`
Decodifica o JWT (header + payload), sem verificar validade. Retorna `null` se malformado.

### `jwt.decode(token: string, timeSkew = 15): TDecoded`
Decodifica e valida o token (verifica expiração). Lança `JsonWebTokenError` ou `TokenExpiredError` se inválido.

### `jwt.encode(data: object, lifeSpan = 5): string`
Gera um JWT simples (sem assinatura) com tempo de vida definido em minutos.

### `jwt.verify(decoded: TDecoded, timeSkew = 15): TDecoded`
Verifica validade de um token decodificado (baseado na propriedade `exp`).

### `jwt.isExpired(exp: number, timeSkew = 15): boolean`
Retorna `true` se o token estiver expirado.

---

## ⚠️ Observações

- Este JWT é não assinado (alg: "none") e deve ser usado apenas em ambientes controlados (ex.: testes).
- A verificação de expiração suporta tolerância configurável (`timeSkew`).
- Em ambiente de desenvolvimento (`NODE_ENV=development`), é possível forçar a expiração com `localStorage.setItem('jwtExpired', '1')`.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/browser-loader
Description: > Carregador dinâmico de arquivos JavaScript e CSS com cache, timeout e controle de status.
Latest version: 0.0.2

# # @koph-npm/browser-loader

> Carregador dinâmico de arquivos JavaScript e CSS com cache, timeout e controle de status.

Este utilitário permite carregar scripts JS e folhas de estilo CSS dinamicamente no navegador com suporte a:

- Cache de carregamento (evita carregamentos repetidos)
- Timeout configurável para falhas
- Suporte a multiplos arquivos
- Uso com `async` ou `defer` no carregamento de scripts

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-loader
```

---

## 🚀 Uso básico

### Carregar um script JS
```ts
import { Loader } from '@koph-npm/browser-loader';

Loader.js("/scripts/utils.js").then(() => {
  console.log("JS carregado com sucesso!");
}).catch(console.error);
```

### Carregar um CSS
```ts
Loader.css("/styles/theme.css").then(() => {
  console.log("CSS aplicado!");
}).catch(console.error);
```

### Múltiplos arquivos
```ts
await Loader.js(["/lib/a.js", "/lib/b.js"]);
await Loader.css(["/css/reset.css", "/css/main.css"]);
```

---

## 🧠 API

### `Loader.js(path: string | string[], async = true, timeoutMs = 10000): Promise<boolean | boolean[]>`
Carrega um ou mais arquivos JS. Usa `async` por padrão. Retorna `true` ou um array de `true` se bem-sucedido.

### `Loader.css(path: string | string[], async = true, timeoutMs = 10000): Promise<boolean | boolean[]>`
Carrega um ou mais arquivos CSS. Retorna `true` ou um array de `true` se bem-sucedido.

---

## ⚠️ Observações

- Recursos são carregados apenas uma vez por URL.
- Rejeita com erro em caso de falha ou timeout.
- Não depende de nenhuma biblioteca externa.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/browser-locker
Description: > Mutex simples entre abas do navegador usando `localStorage` + `StorageEvent`.
Latest version: 0.0.2

# @koph-npm/browser-locker

> Mutex simples entre abas do navegador usando `localStorage` + `StorageEvent`.

Este utilitário permite coordenar o acesso a recursos compartilhados entre diferentes abas abertas de uma mesma aplicação. Ideal para evitar execuções concorrentes de operações como *refresh token*, *jobs programados*, etc.

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-locker
```

---

## 🚀 Uso básico

```ts
import { Locker } from '@koph-npm/browser-locker';

const tokenLocker = Locker("token-locked");

await tokenLocker.block(5000); // tenta adquirir o lock por 5s
try {
  // seção crítica - apenas uma aba entra aqui
  const data = await fetch("/api/refresh-token").then(r => r.json());
  localStorage.setItem("api_token", data.token);
} finally {
  tokenLocker.release();
}
```

---

## 🧠 API

### `Locker(key: string)`
Retorna um objeto com duas funções:

#### `await block(timeoutMs?: number): Promise<number>`
- Tenta adquirir o lock pela chave fornecida.
- Retorna:
    - `0` se conseguiu imediatamente
    - `1` se aguardou outra aba liberar
    - `2` se expirou o tempo de espera

#### `release(): void`
- Libera o lock imediatamente

---

## ⚠️ Observações

- Usa `localStorage` para persistir o lock entre abas.
- Remove locks expirados automaticamente.
- Não impede concorrência entre **abas diferentes de domínios distintos**.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/browser-storage
Description: > Armazenamento seguro e reativo com suporte a `localStorage` e `sessionStorage` + sincronização entre abas.
Latest version: 0.0.2

# @koph-npm/browser-storage

> Armazenamento seguro e reativo com suporte a `localStorage` e `sessionStorage` + sincronização entre abas.

Este pacote fornece uma interface unificada para acesso a armazenamento no navegador com:

- Prefixo codificado para isolamento de chave
- Opção de criptografia simples (base64 com prefixo aleatório)
- Suporte a `localStorage` e `sessionStorage`
- API `read`/`write` mais segura e flexível
- Proxy reativo via `createStore()` com sincronização automática entre abas

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-storage
```

---

## 🚀 Uso básico

### Classe `Storage`
```ts
import { Storage } from '@koph-npm/browser-storage';

const store = new Storage(true, false, "app");

store.write("user", { name: "Ana" });
console.log(store.read("user")); // { name: "Ana" }
```

### Proxy reativo com `createStore()`
```ts
import { createStore } from '@koph-npm/browser-storage';

const user = createStore("session", { name: "", token: "" });

user.name = "João"; // sincroniza em tempo real com sessionStorage e outras abas
console.log(user.token); // recupera token de forma segura
```

---

## 🧠 API

### `new Storage(encrypt = false, useSession = false, key = '')`
- `encrypt`: ativa ofuscação base64 com prefixo aleatório
- `useSession`: usa `sessionStorage` em vez de `localStorage`
- `key`: prefixo para as chaves

#### Métodos:
- `read(key: string): T | null`
- `write(key: string, value: any): void`
- `getItem(key: string): string | null`
- `setItem(key: string, value: string): void`
- `removeItem(key: string): void`
- `remove(key: string): void`

### `createStore<T>(name: string, obj: T): T`
- Cria um `Proxy` reativo sincronizado com `sessionStorage`

---

## ⚠️ Observações

- A criptografia é apenas uma ofuscação base64 com prefixo aleatório.
- Eventos `storage` mantêm valores sincronizados entre abas.
- Não é recomendada para dados altamente sensíveis.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/browser-token
Description: > Gerenciador de autenticação baseado em JWT com refresh automático e controle entre abas.
Latest version: 0.0.2

# @koph-npm/browser-token

> Gerenciador de autenticação baseado em JWT com refresh automático e controle entre abas.

Este pacote oferece uma solução completa para gerenciar tokens JWT em SPAs:

- Armazenamento de `accessToken` e `refreshToken`
- Decodificação e validação automática do JWT
- Refresh automático do token quando expira
- Controle de concorrência entre abas com `Locker`
- Callback `onChange` para reagir a mudanças de token
- Suporte a mocks para testes

---

## 📦 Instalação

```bash
npm install @koph-npm/browser-token
```

---

## 🚀 Uso básico

```ts
import { Token } from '@koph-npm/browser-token';

Token.configure({
  refresh: async (refreshToken) => {
    const res = await fetch("/api/auth/refresh", {
      method: "POST",
      headers: { Authorization: `Bearer ${refreshToken}` }
    });
    const data = await res.json();
    return {
      accessToken: data.access_token,
      refreshToken: data.refresh_token
    };
  },
  onChange: (decoded) => {
    console.log("Novo token decodificado:", decoded);
  },
  timeSkew: 30
});

if (Token.isLoggedIn()) {
  const token = await Token.read();
  fetch("/api/dados", {
    headers: { Authorization: `Bearer ${token}` }
  });
}
```

---

## 🧠 API

### `Token.configure(config: TConfig)`
Inicializa o gerenciador com funções de `refresh`, `onChange`, etc.

### `Token.write(accessToken, refreshToken)`
Armazena os tokens manualmente.

### `Token.read(): Promise<string | null>`
Retorna o `accessToken` atual, atualizando-o se estiver expirado.

### `Token.refresh(): Promise<TSetToken>`
Força a atualização do token usando o `refreshToken`.

### `Token.clear()`
Remove os tokens armazenados.

### `Token.isLoggedIn(): boolean`
Verifica se o token atual é válido.

### `Token.isConfigured(): boolean`
Verifica se o gerenciador foi inicializado.

---

## ⚠️ Observações

- Usa `@koph-npm/browser-jwt` para decodificar/verificar tokens
- Usa `@koph-npm/browser-locker` para evitar refresh concorrente entre abas
- Requer configuração inicial obrigatória com `refresh()`

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/debounce
Description: > Função utilitária para debouncing de eventos e chamadas repetidas.
Latest version: 0.0.2

# @koph-npm/debounce

> Função utilitária para debouncing de eventos e chamadas repetidas.

Este pacote fornece uma implementação leve de `debounce`, que adia a execução de uma função até que um intervalo de tempo tenha passado desde sua última invocação. Último evento sempre prevalece.

---

## 📦 Instalação

```bash
npm install @koph-npm/debounce
```

---

## 🚀 Uso básico

```ts
import { debounce } from '@koph-npm/debounce';

function logMessage(msg: string) {
  console.log("Mensagem:", msg);
}

const debouncedLog = debounce(logMessage, 500);

debouncedLog("Olá");
debouncedLog("Mundo");
debouncedLog("Debounce");

// Apenas "Debounce" será impresso após 500ms sem novas chamadas
```

---

## 🧠 API

### `debounce(func: Function, delay: number = 10): Function`

- `func`: Função original a ser controlada
- `delay`: Tempo de espera em milissegundos
- Retorna uma nova função com comportamento debounced

---

## 🔄 Casos de uso

- Inputs de busca/autocomplete
- Scroll e resize intensivos
- Redução de chamadas de API

---

## ⚠️ Observações

- A função debounced **não retorna valor**.
- Se `delay = 0`, retorna a função original sem alterações.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)
npm package: @koph-npm/promise-once
Description: > Garante que uma promise nomeada seja executada apenas uma vez por chave, mesmo com chamadas concorrentes.
Latest version: 0.0.2

# @koph-npm/promise-once

> Garante que uma promise nomeada seja executada apenas uma vez por chave, mesmo com chamadas concorrentes.

Este utilitário é ideal para cenários onde você deseja evitar chamadas simultâneas duplicadas de uma mesma promise, como requisições para um endpoint ou inicialização de recursos.

---

## 📦 Instalação

```bash
npm install @koph-npm/promise-once
```

---

## 🚀 Uso básico

```ts
import { promiseOnce } from '@koph-npm/promise-once';

async function fetchConfig() {
  return await promiseOnce("config", async () => {
    const res = await fetch("/api/config");
    return await res.json();
  });
}

// Mesmo com chamadas simultâneas, a função será executada uma vez
const [a, b] = await Promise.all([fetchConfig(), fetchConfig()]);
```

---

## 🧠 API

### `promiseOnce<T>(key: string, callback: () => Promise<T>): Promise<T>`

- `key`: Identificador exclusivo da promise
- `callback`: Função que retorna uma promise
- Retorna: Promise resolvida ou rejeitada da execução original

---

## ⚠️ Observações

- A promise é removida do cache após ser resolvida ou rejeitada (`finally`).
- Erros síncronos durante a chamada do `callback()` são tratados corretamente.
- Adequado para uso com `async`/`await`, loaders e caches temporários.

---

## 📄 Licença

MIT

---

## 👤 Autor

Koph <kophmail@gmail.com>

---

## 🔗 Repositório

[https://github.com/koph-git/ts-lib](https://github.com/koph-git/ts-lib)