@arkyn/shared 3.0.1-beta.9 → 3.0.1-beta.91

package/README.md

@@ -1,119 +1,504 @@
-The `@arkyn/shared` package provides reusable utilities such as formatting functions, generators, services, and validations. It is designed to be used across different parts of a project, offering common and practical solutions to streamline development.
+# @arkyn/shared
 
----
+A comprehensive collection of reusable utilities for consistent data handling across your applications. Provides formatting functions, validation tools, generators, and services to streamline common development tasks.
+
+[![npm version](https://img.shields.io/npm/v/@arkyn/shared.svg)](https://www.npmjs.com/package/@arkyn/shared)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+## ✨ Features
 
-## Installation
+- 📅 **Date Utilities** - Flexible date manipulation and timezone support
+- 🏦 **Financial Tools** - Currency formatting and installment calculations
+- 🔒 **Brazilian Validators** - CPF, CNPJ, CEP, RG, and phone number validation
+- 🎨 **String Utilities** - Formatting, masking, and text manipulation
+- 🔧 **Generators** - ID generation, slugs, colors, and more
+- 🛡️ **Data Security** - Sensitive data masking and sanitization
+- 🌐 **Internationalization** - Multi-locale support for formatting
 
-Install the package using npm:
+## 📦 Installation
 
 ```bash
 npm install @arkyn/shared
 ```
 
----
+## 🚀 Quick Start
+
+```typescript
+import {
+  formatToCpf,
+  validateCpf,
+  formatToCurrency,
+  generateId,
+} from "@arkyn/shared";
 
-## Features
+// Format and validate CPF
+const cpf = formatToCpf("12345678901"); // "123.456.789-01"
+const isValid = validateCpf(cpf); // true
 
-### Formatting
+// Format currency
+const price = formatToCurrency(1299.99); // "R$ 1.299,99"
 
-- **`formatDate(date: dateString[], inputFormat: "brazilianDate" | "isoDate" | "timestamp", outputFormat: string, timezone?: number): string`**  
-  Formats a date into a readable string.
+// Generate unique ID
+const id = generateId(); // "uuid-v4-string"
+```
 
-- **`formatJsonObject(obj: object): string`**  
-  Converts a JSON object into a formatted string.
+## 📋 API Reference
 
-- **`formatJsonString(json: string): object`**  
-  Converts a JSON string into an object.
+### 📅 Date Formatting
 
-- **`formatToCep(value: string): string`**  
-  Formats a string into the CEP format (`XXXXX-XXX`).
+#### formatDate(date, inputFormat, outputFormat, timezone?)
 
-- **`formatToCnpj(value: string): string`**  
-  Formats a string into the CNPJ format (`XX.XXX.XXX/XXXX-XX`).
+Formats dates with timezone support.
 
-- **`formatToCpf(value: string): string`**  
-  Formats a string into the CPF format (`XXX.XXX.XXX-XX`).
+```typescript
+import { formatDate } from "@arkyn/shared";
 
-- **`formatToCpfCnpj(value: string): string`**  
-  Formats a string into either CPF or CNPJ format, depending on its length.
+// Format ISO date to Brazilian format
+const formatted = formatDate("2023-12-25", "isoDate", "DD/MM/YYYY");
+// Result: "25/12/2023"
 
-- **`formatToCurrency(value: number): string`**  
-  Converts a number into a currency format.
+// With timezone
+const withTz = formatDate(
+  "2023-12-25T10:00:00Z",
+  "isoDate",
+  "DD/MM/YYYY HH:mm",
+  -3
+);
+// Result: "25/12/2023 07:00"
+```
 
-  - **`formatToDate(date: dateString[], inputFormat: "brazilianDate" | "isoDate" | "timestamp", timezone?: number): Date`**  
-    Formats a date into a Date class.
+#### formatToDate(date, inputFormat, timezone?)
 
-- **`formatToEllipsis(value: string, maxLength: number): string`**  
-  Truncates a string and appends an ellipsis if it exceeds the maximum length.
+Converts strings to Date objects.
 
-- **`formatToHiddenDigits(value: string): string`**  
-  Masks part of a string by replacing it with asterisks.
+```typescript
+import { formatToDate } from "@arkyn/shared";
 
-- **`formatToPhone(value: string): string`**  
-  Formats a string into a phone number format.
+const date = formatToDate("25/12/2023", "brazilianDate");
+// Result: Date object
+```
 
----
+### 🏦 Financial Formatting
+
+#### formatToCurrency(value: number): string
+
+Formats numbers to Brazilian currency format.
+
+```typescript
+import { formatToCurrency } from "@arkyn/shared";
+
+formatToCurrency(1299.99); // "R$ 1.299,99"
+formatToCurrency(0.5); // "R$ 0,50"
+```
+
+#### calculateCardInstallment(total: number, installments: number): number[]
+
+Calculates installment values for credit card payments.
+
+```typescript
+import { calculateCardInstallment } from "@arkyn/shared";
+
+const installments = calculateCardInstallment(1000, 10);
+// Result: [100, 100, 100, 100, 100, 100, 100, 100, 100, 100]
+```
+
+### 🇧🇷 Brazilian Document Formatting
 
-### Generators
+#### formatToCpf(value: string): string
+
+Formats strings to CPF format.
+
+```typescript
+import { formatToCpf } from "@arkyn/shared";
+
+formatToCpf("12345678901"); // "123.456.789-01"
+```
+
+#### formatToCnpj(value: string): string
+
+Formats strings to CNPJ format.
+
+```typescript
+import { formatToCnpj } from "@arkyn/shared";
+
+formatToCnpj("12345678000195"); // "12.345.678/0001-95"
+```
+
+#### formatToCpfCnpj(value: string): string
+
+Auto-detects and formats CPF or CNPJ.
+
+```typescript
+import { formatToCpfCnpj } from "@arkyn/shared";
+
+formatToCpfCnpj("12345678901"); // "123.456.789-01" (CPF)
+formatToCpfCnpj("12345678000195"); // "12.345.678/0001-95" (CNPJ)
+```
+
+#### formatToCep(value: string): string
+
+Formats strings to CEP format.
+
+```typescript
+import { formatToCep } from "@arkyn/shared";
+
+formatToCep("01234567"); // "01234-567"
+```
 
-- **`generateColorByString(value: string): string`**  
-  Generates a hexadecimal color based on a string.
+#### formatToPhone(value: string): string
 
-- **`generateId(): string`**  
-  Generates a unique identifier.
+Formats phone numbers.
 
-- **`generateSlug(value: string): string`**  
-  Converts a string into a URL-friendly slug.
+```typescript
+import { formatToPhone } from "@arkyn/shared";
+
+formatToPhone("11987654321"); // "(11) 98765-4321"
+```
 
 ---
 
-### Services
+### 🎨 String Utilities
+
+#### formatToEllipsis(value: string, maxLength: number): string
+
+Truncates strings with ellipsis.
+
+```typescript
+import { formatToEllipsis } from "@arkyn/shared";
+
+formatToEllipsis("This is a very long text", 10); // "This is a..."
+```
+
+#### formatToHiddenDigits(value: string): string
+
+Masks sensitive information.
+
+```typescript
+import { formatToHiddenDigits } from "@arkyn/shared";
+
+formatToHiddenDigits("123456789"); // "12***6789"
+```
+
+#### formatToCapitalizeFirstWordLetter(value: string): string
+
+Capitalizes the first letter of each word.
+
+```typescript
+import { formatToCapitalizeFirstWordLetter } from "@arkyn/shared";
+
+formatToCapitalizeFirstWordLetter("hello world"); // "Hello World"
+```
+
+#### stripHtmlTags(value: string): string
+
+Removes HTML tags from strings.
 
-- **`calculateCardInstallment(total: number, installments: number): number[]`**  
-  Calculates the installment values for a given total.
+```typescript
+import { stripHtmlTags } from "@arkyn/shared";
 
-- **`ensureQuotes(rawValue: string): string`**  
-  Ensures that a given rawValue string is enclosed in quotes.
+stripHtmlTags("<p>Hello <strong>World</strong></p>"); // "Hello World"
+```
+
+### 📄 JSON Utilities
+
+#### formatJsonObject(obj: object): string
+
+Converts objects to formatted JSON strings.
+
+```typescript
+import { formatJsonObject } from "@arkyn/shared";
 
-- **`maskSensitiveData(data: string): string`**  
-  Masks sensitive data in a string.
+const obj = { name: "John", age: 30 };
+formatJsonObject(obj); // Pretty-printed JSON string
+```
+
+#### formatJsonString(json: string): object
 
-- **`removeNonNumeric(value: string): string`**  
-  Removes all non-numeric characters from a string.
+Parses JSON strings safely.
 
-- **`truncateLargeFields(obj: object, maxLength: number): object`**  
-  Truncates large fields in an object to a specified maximum length.
+```typescript
+import { formatJsonString } from "@arkyn/shared";
+
+const parsed = formatJsonString('{"name":"John"}');
+// Result: { name: "John" }
+```
 
 ---
 
-### Validations
+### 🔧 Generators
+
+#### generateId(): string
+
+Generates unique identifiers using UUID v4.
+
+```typescript
+import { generateId } from "@arkyn/shared";
+
+const id = generateId(); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+```
+
+#### generateSlug(value: string): string
+
+Creates URL-friendly slugs.
+
+```typescript
+import { generateSlug } from "@arkyn/shared";
+
+generateSlug("Hello World! How are you?"); // "hello-world-how-are-you"
+```
+
+#### generateColorByString(value: string): string
+
+Generates consistent colors from strings.
+
+```typescript
+import { generateColorByString } from "@arkyn/shared";
+
+generateColorByString("John Doe"); // "#3498db" (always same color for same input)
+```
+
+### 🛡️ Data Security & Sanitization
+
+#### maskSensitiveData(data: string): string
+
+Masks sensitive information in logs and outputs.
+
+```typescript
+import { maskSensitiveData } from "@arkyn/shared";
+
+maskSensitiveData("user@email.com"); // "us***@email.com"
+```
+
+#### removeNonNumeric(value: string): string
+
+Removes all non-numeric characters.
+
+```typescript
+import { removeNonNumeric } from "@arkyn/shared";
+
+removeNonNumeric("(11) 98765-4321"); // "11987654321"
+```
+
+#### removeCurrencySymbols(value: string): string
 
-- **`validateCep(value: string): boolean`**  
-  Validates whether a string is a valid CEP.
+Removes currency symbols and formatting.
 
-- **`validateCnpj(value: string): boolean`**  
-  Validates whether a string is a valid CNPJ.
+```typescript
+import { removeCurrencySymbols } from "@arkyn/shared";
 
-- **`validateCpf(value: string): boolean`**  
-  Validates whether a string is a valid CPF.
+removeCurrencySymbols("R$ 1.299,99"); // "1299.99"
+```
 
-- **`validateDate(value: string): boolean`**  
-  Validates whether a string is a valid date.
+#### ensureQuotes(rawValue: string): string
 
-- **`validatePhone(value: string): boolean`**  
-  Validates whether a string is a valid phone number.
+Ensures strings are properly quoted.
 
-- **`validateRg(value: string): boolean`**  
-  Validates whether a string is a valid ID (RG).
+```typescript
+import { ensureQuotes } from "@arkyn/shared";
+
+ensureQuotes("hello"); // '"hello"'
+ensureQuotes('"hello"'); // '"hello"' (no double quotes)
+```
+
+#### truncateLargeFields(obj: object, maxLength: number): object
+
+Truncates large text fields in objects.
+
+```typescript
+import { truncateLargeFields } from "@arkyn/shared";
+
+const data = { description: "Very long text..." };
+truncateLargeFields(data, 10); // { description: 'Very long...' }
+```
 
 ---
 
-## Contribution
+### ✅ Validation Functions
+
+#### validateCpf(value: string): boolean
+
+Validates Brazilian CPF numbers.
+
+```typescript
+import { validateCpf } from "@arkyn/shared";
+
+validateCpf("123.456.789-01"); // true/false
+validateCpf("12345678901"); // true/false (accepts without formatting)
+```
 
-Contributions are welcome! Feel free to open issues or submit pull requests to improve the project.
+#### validateCnpj(value: string): boolean
+
+Validates Brazilian CNPJ numbers.
+
+```typescript
+import { validateCnpj } from "@arkyn/shared";
+
+validateCnpj("12.345.678/0001-95"); // true/false
+```
+
+#### validateCep(value: string): boolean
+
+Validates Brazilian postal codes.
+
+```typescript
+import { validateCep } from "@arkyn/shared";
+
+validateCep("01234-567"); // true/false
+validateCep("01234567"); // true/false (accepts without formatting)
+```
+
+#### validatePhone(value: string): boolean
+
+Validates Brazilian phone numbers.
+
+```typescript
+import { validatePhone } from "@arkyn/shared";
+
+validatePhone("(11) 98765-4321"); // true/false
+validatePhone("11987654321"); // true/false
+```
+
+#### validateRg(value: string): boolean
+
+Validates Brazilian RG (ID) numbers.
+
+```typescript
+import { validateRg } from "@arkyn/shared";
+
+validateRg("12.345.678-9"); // true/false
+```
+
+#### validateDate(value: string): boolean
+
+Validates date strings.
+
+```typescript
+import { validateDate } from "@arkyn/shared";
+
+validateDate("25/12/2023"); // true/false
+validateDate("2023-12-25"); // true/false
+```
+
+#### validatePassword(value: string): boolean
+
+Validates password strength.
+
+```typescript
+import { validatePassword } from "@arkyn/shared";
+
+validatePassword("MyPassword123!"); // true/false
+```
+
+## 🔧 Advanced Usage
+
+### Complete Form Validation
+
+```typescript
+import {
+  validateCpf,
+  validatePhone,
+  validateCep,
+  formatToCpf,
+  formatToPhone,
+  formatToCep,
+} from "@arkyn/shared";
+
+function validateUserForm(data) {
+  const errors = {};
+
+  // Validate and format CPF
+  if (!validateCpf(data.cpf)) {
+    errors.cpf = "Invalid CPF";
+  } else {
+    data.cpf = formatToCpf(data.cpf);
+  }
+
+  // Validate and format phone
+  if (!validatePhone(data.phone)) {
+    errors.phone = "Invalid phone number";
+  } else {
+    data.phone = formatToPhone(data.phone);
+  }
+
+  // Validate and format CEP
+  if (!validateCep(data.cep)) {
+    errors.cep = "Invalid postal code";
+  } else {
+    data.cep = formatToCep(data.cep);
+  }
+
+  return { isValid: Object.keys(errors).length === 0, errors, data };
+}
+```
+
+### Data Processing Pipeline
+
+```typescript
+import {
+  removeNonNumeric,
+  formatToCurrency,
+  calculateCardInstallment,
+  generateId,
+} from "@arkyn/shared";
+
+function processOrder(orderData) {
+  // Clean price input
+  const numericPrice = removeNonNumeric(orderData.price);
+  const price = parseFloat(numericPrice) / 100; // Convert cents to reais
+
+  // Format for display
+  const formattedPrice = formatToCurrency(price);
+
+  // Calculate installments
+  const installments = calculateCardInstallment(price, 12);
+
+  // Generate order ID
+  const orderId = generateId();
+
+  return {
+    id: orderId,
+    price: formattedPrice,
+    installmentOptions: installments.map((value, index) => ({
+      number: index + 1,
+      value: formatToCurrency(value),
+    })),
+  };
+}
+```
+
+## 🧪 Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build the package
+bun run build
+
+# Run tests
+bun run test
+
+# Type check
+bun run typecheck
+```
 
 ---
 
-## License
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to help improve the package.
+
+## 📄 License
+
+This project is licensed under the Apache 2.0 License - see the [LICENSE](./LICENSE.txt) file for details.
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/Lucas-Eduardo-Goncalves/arkyn)
+- [NPM Package](https://www.npmjs.com/package/@arkyn/shared)
+- [Full Documentation](https://github.com/Lucas-Eduardo-Goncalves/arkyn#readme)
+
+---
 
-This project is licensed under the Apache 2.0 License. See the `LICENSE` file for more details.
+Made with ❤️ by the Arkyn team