@arctics/utils (beta)

Table of Contents

1. Introduction
2. Features
3. Installation
4. Usage
5. API
6. Locales List
7. Contributing
8. 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

npm install @arctics/utils

or

yarn add @arctics/utils

Usage

FileConvertor

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

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<string | null>

  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<void>

  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<string | null>

  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<void>

  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<string | null>

  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<string | null>

  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<Uint8Array>): Promise<string | null>

  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 file.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.