npm package: @luriquepro/common-node-utils
Description: Biblioteca de funções utilitárias para projetos Node/TypeScript
Latest version: 1.0.1

# @luriquepro/common-node-utils

Biblioteca de funções utilitárias para projetos Node/TypeScript, organizada com Clean Architecture e Clean Code.

## Instalação

### npm (registry público)

```bash
npm install @luriquepro/common-node-utils
```

### Nexus ou registry privado

```bash
npm install @luriquepro/common-node-utils --registry=https://seu-nexus.com/repository/npm-hosted/
```

Ou no `.npmrc` do projeto:

```
registry=https://seu-nexus.com/repository/npm-hosted/
```

---

## Uso

### PaginateHelper

```ts
import { PaginateHelper } from '@luriquepro/common-node-utils';

const items = [1, 2, 3, 4, 5, 6, 7];
PaginateHelper.paginate(items, 2, 2); // [3, 4]
PaginateHelper.clamp(15, 0, 10);      // 10
```

### FormatterHelper

```ts
import { FormatterHelper } from '@luriquepro/common-node-utils';

FormatterHelper.ParseBoolean('true');           // true
FormatterHelper.ParseNumber('42,5');            // 42.5
FormatterHelper.ParseToBRL(1234.56);           // "R$ 1.234,56"
FormatterHelper.FormatMessage('Olá {{ name }}', { name: 'Luiz' });
FormatterHelper.TransformToSnakeCase({ fooBar: 1 });
FormatterHelper.GetUnixTime(new Date());
FormatterHelper.FormatChatId('11987654321');     // "5511987654321@c.us"
```

### ValidateHelper

```ts
import { ValidateHelper, DOCUMENT_TYPE_ENUM } from '@luriquepro/common-node-utils';

ValidateHelper.IsValidCpf('123.456.789-09');
ValidateHelper.IsValidCnpj('11.222.333/0001-81');
ValidateHelper.IsValidEmail('user@example.com');
ValidateHelper.IsValidPhone('11987654321');
ValidateHelper.IsValidRg('12.345.678-9');
ValidateHelper.GetDocumentTypeByNumber('12345678901'); // DOCUMENT_TYPE_ENUM.CPF
```

### CleanHelper

```ts
import { CleanHelper } from '@luriquepro/common-node-utils';

CleanHelper.CleanNumber('R$ 1.234,56');      // "123456"
CleanHelper.CleanString('  foo   bar  ');    // "foo bar"
CleanHelper.CleanDocument('123.456.789-09');  // "12345678909"
CleanHelper.CleanCep('12345-678');           // "12345678"
CleanHelper.CleanPhone('(11) 98765-4321');   // "11987654321"
CleanHelper.CleanAlpha('abc123!');           // "abc"
CleanHelper.CleanAlphaNumeric('a1 b2-c3');   // "a1b2c3"
```

### IdHelper

```ts
import { IdHelper } from '@luriquepro/common-node-utils';

IdHelper.GenerateSecureId(12);                    // string aleatória segura
IdHelper.RandomAlphaNumString(6);                 // ex: "A3B9K2"
await IdHelper.GenerateUniqueId(async (id) => false); // ID único (callback verifica existência)
```

### AsyncHelper

```ts
import { AsyncHelper } from '@luriquepro/common-node-utils';

await AsyncHelper.Sleep(1000); // aguarda 1 segundo
```

### AuthHelper

```ts
import { AuthHelper } from '@luriquepro/common-node-utils';

AuthHelper.RolesCanAccess(['ADMIN', 'EDITOR'], userRoles);  // role ADMIN libera tudo
AuthHelper.CheckPermissions(requiredPerms, userPerms, true); // anyPermission
```

### Helpers específicos para MongoDB

Use o subpath `@luriquepro/common-node-utils/mongo`:

```ts
import { MongoAggregateHelper } from '@luriquepro/common-node-utils/mongo';

MongoAggregateHelper.SearchStep(options);
MongoAggregateHelper.SortStep(options);
MongoAggregateHelper.PaginationSkipStep(options);
MongoAggregateHelper.BuildResponse(result);
```

### Tipos (CommonNodeUtils)

```ts
import type { CommonNodeUtils } from '@luriquepro/common-node-utils';

const sort: CommonNodeUtils.Sort = { createdAt: -1 };
const opts: CommonNodeUtils.IQueryOptions = { pagination: { pageNumber: 1, quantityPerPage: 10 }, sort: {} };
```

### Importar funções individuais

```ts
import { parseBoolean, isValidCpf, cleanNumber, sleep } from '@luriquepro/common-node-utils';
```

---

## Estrutura

| Helper | Descrição |
|--------|-----------|
| **PaginateHelper** | Paginação, clamp, query options, infinite scroll |
| **SortHelper** | Ordenação (ex.: por data) |
| **FormatterHelper** | Parse (boolean, number, BRL), format message, snake_case, unix time, chat id |
| **ValidateHelper** | CPF, CNPJ, e-mail, telefone, RG, tipo de documento |
| **CleanHelper** | Limpar número, string, documento, CEP, telefone, alpha |
| **IdHelper** | IDs seguros, únicos, string alfanumérica aleatória |
| **AsyncHelper** | Sleep (Promise) |
| **AuthHelper** | Roles e permissões |
| **MongoAggregateHelper** | Pipelines MongoDB (subpath `/mongo`) |

---

## Publicar o pacote

### No npm público (registry.npmjs.org)

Pacote com escopo (`@luriquepro/...`) precisa de `--access=public` na primeira publicação:

```bash
npm login
npm version patch   # 1.0.0 → 1.0.1 (ou minor/major)
npm publish --access=public
```

### No Nexus (registry privado)

1. Defina o registry na hora de publicar:

```bash
npm login --registry=https://seu-nexus.com/repository/npm-hosted/
npm version patch
npm publish --registry=https://seu-nexus.com/repository/npm-hosted/
```

2. Ou use `publishConfig` no `package.json` (só para esse pacote):

```json
"publishConfig": {
  "registry": "https://seu-nexus.com/repository/npm-hosted/"
}
```

Depois: `npm login --registry=...` e `npm publish`.

---

## Versionamento

O projeto segue [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH).

## Desenvolvimento

```bash
npm install
npm run build
```

## Licença

MIT