# @arctics/utils (beta)
[](https://github.com/tyrog07/@arctics/utils/blob/HEAD/LICENSE)
[](https://www.npmjs.com/package/@arctics/utils)
[](https://www.npmjs.com/package/@arctics/utils)
[](https://github.com/tyrog07/arctics-utils/actions/workflows/test.yml)
[](https://github.com/tyrog07/arctics-utils/actions/workflows/build.yml)
[](https://github.com/tyrog07/arctics-utils/actions/workflows/CI.yml)
[](https://packagephobia.now.sh/result?p=@arctics/utils)
[](https://bundlephobia.com/package/@arctics/utils@latest)
[](https://snyk.io/test/npm/@arctics/utils)
## Table of Contents
1. [Introduction](#introduction)
2. [Features](#features)
3. [Installation](#installation)
4. [Usage](#usage)
5. [API](#api)
6. [Locales List](#locales-list)
7. [Contributing](#contributing)
8. [License](#license)
## Introduction
A JavaScript/TypeScript package providing utilities around certain functionalities.
## Features
- **FileConvertor**: Convert files to and from base64 and hexadecimal formats.
- **Localization**: Handle locale-specific formatting for numbers, currencies, and dates.
## Installation
```bash
npm install @arctics/utils
```
or
```bash
yarn add @arctics/utils
```
## Usage
### FileConvertor
```typescript
import { FileConverter } from '@arctics/utils';
// Create an instance of FileConverter
const fileConverter = new FileConverter();
// Convert a file to base64
fileConverter.fileToBase64('path/to/file.txt').then((base64String) => {
console.log('Base64:', base64String);
});
// Convert a URL to base64
fileConverter
.fileToBase64('https://example.com/image.png')
.then((base64String) => {
console.log('Base64:', base64String);
});
// Convert a base64 string to a file
fileConverter.base64ToFile('base64String', 'path/to/output.txt').then(() => {
console.log('File written successfully');
});
// Convert a file to hexadecimal
fileConverter.fileToHex('path/to/file.txt').then((hexString) => {
console.log('Hexadecimal:', hexString);
});
// Convert a hexadecimal string to a file
fileConverter.hexToFile('hexString', 'path/to/output.txt').then(() => {
console.log('File written successfully');
});
```
### Localization
```typescript
import { Localization } from '@arctics/utils';
// Set the locale to French (France)
Localization.setLocale('fr-FR');
// Get the current locale
console.log(Localization.getLocale()); // Output: 'fr-FR'
// Format a number according to the current locale
console.log(Localization.formatNumber(1234567.89)); // Output: '1 234 567,89'
// Format a number as currency according to the current locale
console.log(Localization.formatCurrency(1234567.89, 'EUR')); // Output: '1 234 567,89 €'
// Format a date according to the current locale
console.log(Localization.formatDate(new Date())); // Output: '19 févr. 2025'
// Format a phone number according to the current locale
console.log(Localization.formatPhoneNumber('+33612345678')); // Output: '06 12 34 56 78' (example for France)
```
## API
### FileConvertor
#### Methods
- **fileToBase64(source: string | Buffer | ReadableStream): Promise**
Converts a file, URL, Buffer, or ReadableStream to a base64 string.
- `source`: The source to convert. Can be a file path (string), URL (string), Buffer, or ReadableStream.
- Returns: A Promise that resolves to the base64 string, or null if an error occurs.
- **base64ToFile(base64String: string, outputPath: string): Promise**
Writes a base64 string to a file.
- `base64String`: The base64 string to write.
- `outputPath`: The path to the output file.
- Returns: A Promise that resolves when the file is written successfully, or rejects if an error occurs.
- **fileToHex(filePath: string): Promise**
Converts a file to a hexadecimal string.
- `filePath`: The path to the file.
- Returns: A Promise that resolves to the hexadecimal string, or null if an error occurs.
- **hexToFile(hexString: string, outputPath: string): Promise**
Writes a hexadecimal string to a file.
- `hexString`: The hexadecimal string to write.
- `outputPath`: The path to the output file.
- Returns: A Promise that resolves when the file is written successfully, or rejects if an error occurs.
#### Private Methods
- **isURL(str: string): boolean**
Checks if a string is a valid URL.
- `str`: The string to check.
- Returns: True if the string is a URL, false otherwise.
- **convertFromFile(filePath: string): Promise**
Converts a file to a base64 string.
- `filePath`: The path to the file.
- Returns: A Promise that resolves to the base64 string, or null if an error occurs.
- **convertFromURL(url: string): Promise**
Converts a URL to a base64 string.
- `url`: The URL.
- Returns: A Promise that resolves to the base64 string, or null if an error occurs.
- **convertFromBuffer(buffer: Buffer): string**
Converts a Buffer to a base64 string.
- `buffer`: The Buffer.
- Returns: The base64 string.
- **convertFromStream(stream: ReadableStream): Promise**
Converts a ReadableStream to a base64 string.
- `stream`: The ReadableStream.
- Returns: A Promise that resolves to the base64 string, or null if an error occurs.
### Localization
#### Methods
- **setLocale(localeCode: string): void**
Sets the current locale to the provided locale code.
- localeCode: The locale code to set.
- **getLocale(): string**
Returns the current locale code.
- Returns: The current locale code.
- **formatNumber(number: number): string**
Formats a number according to the current locale.
- number: The number to format.
- Returns: The formatted number.
- **formatCurrency(number: number, currencyCode: string = 'USD'): string**
Formats a number as currency according to the current locale.
- number: The number to format.
- currencyCode: The currency code to use for formatting. Defaults to 'USD' if not provided.
- Returns: The formatted currency.
- **formatDate(date: Date | string, options?: Intl.DateTimeFormatOptions): string**
Formats a date according to the current locale.
- date: The date to format, either as a Date object or a string.
- options: Options for date formatting as per Intl.DateTimeFormatOptions.
- Returns: The formatted date.
- **formatPhoneNumber(phoneNumber: string): string**
Formats a phone number according to the specified region or the current locale.
- phoneNumber: The phone number to format.
- Returns: The formatted phone number, or the original number if formatting fails.
## Locales List
For a detailed list of supported locales, please refer to the [Locales List](SUPPORTED_LOCALES.md) file.
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
## License
This project is licensed under the [MIT License](https://github.com/tyrog07/arctics-utils/blob/HEAD/LICENSE).