https://github.com/heliomarpm/helpers
A utility for NodeJS App with many useful features
https://github.com/heliomarpm/helpers
cache cache-storage electron-app helpers library memory memory-storage node-js utility-library utils
Last synced: about 1 year ago
JSON representation
A utility for NodeJS App with many useful features
- Host: GitHub
- URL: https://github.com/heliomarpm/helpers
- Owner: heliomarpm
- License: mit
- Created: 2023-04-22T20:12:44.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-24T18:17:07.000Z (about 1 year ago)
- Last Synced: 2025-03-24T19:24:55.711Z (about 1 year ago)
- Topics: cache, cache-storage, electron-app, helpers, library, memory, memory-storage, node-js, utility-library, utils
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@heliomarpm/helpers
- Size: 403 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Helpers Library
[![DeepScan grade][url-deepscan-badge]][url-deepscan]
[![CodeFactor][url-codefactor-badge]][url-codefactor]
![CodeQL][url-codeql] [![NPM version][url-npm-badge]][url-npm]
[![Downloads][url-downloads-badge]][url-downloads]
## 🎯 About
`@heliomarpm/helpers` is a comprehensive collection of TypeScript utility functions for formatting, type checking, conversion, and general utilities. This library provides a set of helper functions to make common programming tasks easier and more maintainable.
## 🚀 Features
- Type checking utilities (is.ts)
- String and data formatting helpers (format.ts)
- Type conversion functions (to.ts)
- General utility functions (utils.ts)
- Fully typed with TypeScript
- Zero dependencies
- Tree-shakeable exports
- CommonJS and ES Module support
## 📁 Project structure:
```
src/
├── helpers/
│ ├── format.ts # Formatting utilities
│ ├── is.ts # Type checking functions
│ ├── to.ts # Type conversion helpers
│ └── utils.ts # General utilities
└── index.ts # Main entry point
```
## 📦 Installation
You can install the library using `npm` or `yarn`:
```bash
npm i @heliomarpm/helpers
# or
yarn add @heliomarpm/helpers
```
## 🔧 Basic Usage
To use the library in a TypeScript or modern JavaScript project, you can import it directly:
```typescript
import { Is, To, Format, Utils } from '@heliomarpm/helpers';
// Type checking
Is.CPF('111.222.333-00'); // false
Is.CNPJ('11.222.333/0001-00'); // false
// Conversion
To.boolean('1'); // true
To.boolean('false'); // false
To.boolean('invalid'); // false
// Formatting
Format.date('2025-03-02', 'dddd, dd mmmm yyyy', 'en-US'); // "Sunday, 02 March 2025"
Format.ptBr.valorPorExtenso(100_000); // "cem mil"
// General utilities
Utils.getNestedValue({ user: { name: { first: 'John' } }}, "user.name.first"); // "John"
const target = {user: {name: {first: 'John',last: 'Doe'} } };
Utils.setNestedValue(target, "user.name.first", "Jane");
Utils.setNestedValue(target, 'user.name.first', 'Jane');
Utils.setNestedValue(target, 'children[0].name', 'John');
Utils.setNestedValue(target, 'animals[0]', 'dog');
Utils.setNestedValue(target, 'animals[1]', 'cat');
// output will be target:
{
user: { name: { first: 'Jane', last: 'Doe' } },
children: [{ name: 'John' }],
animals: ['dog', 'cat']
}
```
## Main functionalities
### Usage
```typescript
import { Format, Is, To, Utils } from '@heliomarpm/helpers';
```
### Format Helpers
#### Brazilian Formats (ptBr)
```typescript
Format.ptBr.cnpj('12345678901234'); // Formatar CNPJ '12.345.678/9012-34'
Format.ptBr.cnpj('1234567890123400', 'CNPJ não pode ser formatado'); // 'CNPJ não pode ser formatado'
Format.ptBr.cpf('12345678901'); // '123.456.789-01'
Format.ptBr.cpf('1234567890100', 'CPF não pode ser formatado'); // 'CPF não pode ser formatado'
Format.ptBr.cep('12345678'); // '12345-678'
Format.ptBr.cep('1234567800', 'CEP não pode ser formatado'); // 'CEP não pode ser formatado'
Format.ptBr.telefone('11999999999'); // '11 99999-9999'
Format.ptBr.telefone('1199999999900', 'Telefone não pode ser formatado'); // 'Telefone não pode ser formatado'
Format.ptBr.valorPorExtenso(1234); // 'mil duzentos e trinta e quatro'
```
#### Date Formatting
```typescript
Format.date(new Date(), 'dd/mm/yyyy HH:MM:ss'); // '31/12/2023 23:59:59'
Format.date('2025-03-02', 'dddd, dd mmmm yyyy', 'en-US'); // "Sunday, 02
```
###### Supported formats are:
```js
/**
* @param {string} format - The desired format for the output string.
* - 'a': 'am' or 'pm' in lowercase
* - 'A': 'AM' or 'PM' in uppercase
* - 'hh': two-digit hours in 12h format (01-12)
* - 'h': hours in 12h format (1-12)
* - 'HH': two-digit hours in 24h format (00-23)
* - 'H': hours in 24h format (0-23)
* - 'MM': two-digit minutes (00-59)
* - 'ss': two-digit seconds (00-59)
* - 'SSS': three-digit milliseconds (000-999)
* - 'yyyy': four-digit year (2024)
* - 'yy': two-digit year (24)
* - 'mmmm': full month name (January, February, ...)
* - 'mmm': full month name abbreviated month (Jan, Feb, ...)
* - 'mm': two-digit month (01-12)
* - 'dddd': full weekday name (Sun, Mon, ...)
* - 'ddd': abbreviated weekday name (Sun, Mon, ...)
* - 'dd': two-digit day (01-31)
*/
```
#### Number Formatting
```typescript
// Format currency
Format.currency(1234.56, { locale: 'en', currency: 'USD' }); // '$1,234.56'
// Formating number (1.234,56)
Format.number(1234.56); // '1.234,56'
// Abreviate number (1.23K, 1.23M, etc.)
Format.abbreviateNumber(1234567); // '1.23M'
// Remove non-numeric characters from a string.
Format.onlyNumbers('abc123'); // '123'
// Pads a number with leading zeros to match the number of digits in a given maximum value
Format.padZerosByRef(5, 100); // '005'
#### String Formatting
// Capitalizes the first letter of a string
Format.titleCase('john doe'); // 'John Doe'
Format.titleCase('MARIA DA SILVA'); // 'Maria da Silva'
// Mask a part of a string with a single character
Format.maskIt('1234567890', 3, 6, '*'); // '123****890'
```
### Is Helpers (Validation)
```typescript
Is.cpf('123.456.789-01'); // Validates CPF
Is.cnpj('12.345.678/9012-34'); // Validates CNPJ
Is.numeric('123'); // true
Is.equals(obj1, obj2); // Deep comparison
Is.date('2023-12-31'); // Validates date
Is.nullOrEmpty(value); // Checks for null/empty
Is.object({}); // Validates object type
Is.email('user@example.com'); // Validates email
// OS and Architecture checks
Is.windowsOS
Is.linuxOS
Is.macOS
Is.arch_x86
Is.arch_x64
Is.arch_Arm
Is.arch_Arm64
```
### To Helpers (Conversion)
```typescript
To.dictionary(jsonObject); // Converts to Record
To.boolean('true'); // Converts to boolean
To.dateParts(new Date()); // Extracts date components
To.number('123'); // Converts to number
```
### Utils Helpers
```typescript
Utils.gerarCPF(); // Generates valid CPF
Utils.gerarCNPJ(); // Generates valid CNPJ
Utils.sortByProps(['name', '-age']); // Sort function for arrays
Utils.orderBy(array, 'key', 'asc'); // Sort array by key
Utils.getNestedValue(obj, 'user.name'); // Get nested object value
Utils.setNestedValue(obj, 'user.name', value); // Set nested object value
Utils.ifNull(value, defaultValue); // Null coalescing
Utils.ifNullOrEmpty(value, value2, defaultValue); // Returns the first non-null, non-undefined, and non-empty value from the given arguments.
Utils.generateGuid(); // Generate GUID (e.g. '00000000-0000-0000-0000-000000000000')
Utils.months({locale: 'pt-BR', month: 'long'}); // Get month names array (e.g. ['Janeiro', 'Fevereiro', ...])
Utils.weekdays({locale: 'pt-BR', weekday: 'long'}); // Get weekday names array (e.g. ['Domingo', 'Segunda-feira', ...])
// Crypto utilities
Utils.crypto.generateKey(); // Generate encryption key
Utils.crypto.encrypt(text, key); // Encrypt text
Utils.crypto.decrypt(encryptedText, key); // Decrypt text
```
## Dependencies
This library has no dependencies
## 🤝 Contributing
Please make sure to read the [Contributing Guide](docs/CONTRIBUTING.md) before making a pull request.
Thank you to all the people who already contributed to project!
###### Made with [contrib.rocks](https://contrib.rocks).
That said, there's a bunch of ways you can contribute to this project, like by:
- :beetle: Reporting a bug
- :page_facing_up: Improving this documentation
- :rotating_light: Sharing this project and recommending it to your friends
- :dollar: Supporting this project on GitHub Sponsors or Ko-fi
- :star2: Giving a star on this repository
## 📢 Support the Project
If you appreciate that, please consider donating to the Developer.
## 📝 License
[MIT © Heliomar P. Marques](LICENSE) 🔝
----
[url-npm]: https://www.npmjs.com/package/@heliomarpm/helpers
[url-npm-badge]: https://img.shields.io/npm/v/@heliomarpm/helpers.svg
[url-downloads]: http://badge.fury.io/js/@heliomarpm/helpers.svg
[url-downloads-badge]: https://img.shields.io/npm/dm/@heliomarpm/helpers.svg
[url-deepscan]: https://deepscan.io/dashboard#view=project&tid=19612&pid=28935&bid=933374
[url-deepscan-badge]: https://deepscan.io/api/teams/19612/projects/28935/branches/933374/badge/grade.svg
[url-codefactor]: https://www.codefactor.io/repository/github/heliomarpm/helpers
[url-codefactor-badge]: https://www.codefactor.io/repository/github/heliomarpm/helpers/badge
[url-codeql]: https://github.com/heliomarpm/helpers/actions/workflows/codeql.yml/badge.svg
[url-publish]: https://github.com/heliomarpm/helpers/actions/workflows/publish.yml/badge.svg