arkyn
ChangelogGuides
docs / shared / introduction

Introduction to @arkyn/shared

@arkyn/shared is a comprehensive utility library designed to provide a collection of well-tested, reusable functions for common development tasks. Built with TypeScript and optimized for modern JavaScript environments, it offers a modular approach to handling data formatting, generation, parsing, validation, and general-purpose utilities.

Why @arkyn/shared?

When building modern applications, developers often find themselves writing the same utility functions repeatedly across different projects. @arkyn/shared solves this problem by providing a curated set of tools that handle common tasks with a consistent, well-documented API.
Key benefits:
  • Type-safe: Written in TypeScript with full type definitions for excellent IDE support and compile-time safety
  • Modular: Import only what you need—each function is independently exportable to keep your bundle size minimal
  • Well-documented: Every function includes comprehensive documentation with usage examples
  • Battle-tested: Functions are designed to handle edge cases and provide meaningful error messages
  • Lightweight: No runtime dependencies are declared in package.json, keeping the install footprint small
  • Framework agnostic: Works in any JavaScript/TypeScript runtime—no framework-specific APIs required

Installation

Important: libphonenumber-js (>=1.13.7) is the package's declared peer dependency, required by formatToPhone for parsing and validating phone numbers. See formatToPhone for details.
Additionally, some formatting utilities—such as formatToCurrency and findCountryMask—internally import from @arkyn/templates at runtime, even though it is not currently declared as a dependency or peer dependency in package.json.

bash

bun add @arkyn/shared

Module Overview

The library is organized into five main categories, each serving a specific purpose:

Formats

Functions for transforming and formatting data into standardized string representations. Includes formatters for dates, currencies (22+ international currencies), Brazilian documents (CPF, CNPJ, CEP), phone numbers, and text manipulation utilities.

ts

import { formatDate } from "@arkyn/shared/formatDate";
import { formatToCurrency } from "@arkyn/shared/formatToCurrency";
import { formatToCpf } from "@arkyn/shared/formatToCpf";


formatDate(["25/12/2025"], "brazilianDate", "YYYY-MM-DD");
// → "2025-12-25"


formatToCurrency(1234.56, "BRL");
// → "R$ 1.234,56"


formatToCpf("12345678909");
// → "123.456.789-09"

Generators

Utilities for creating unique identifiers, slugs, and other generated content. Perfect for database IDs, URL-friendly strings, and dynamic content generation.

ts

import { generateId } from "@arkyn/shared/generateId";
import { generateSlug } from "@arkyn/shared/generateSlug";
import { generateColorByString } from "@arkyn/shared/generateColorByString";


generateId("text", "v7");
// → "018e4c5a-1b2c-7d3e-8f4a-5b6c7d8e9f0a"


generateSlug("Hello, World! This is a Test.");
// → "hello-world-this-is-a-test"


generateColorByString("user@email.com");
// → "#d4b9fa" (consistent color for the same input)

Parsers

Functions for extracting, transforming, and sanitizing data. Includes tools for handling sensitive information, parsing dates, and processing large data fields.

ts

import { parseSensitiveData } from "@arkyn/shared/parseSensitiveData";
import { parseToDate } from "@arkyn/shared/parseToDate";


parseSensitiveData('{"password":"secret123"}', ["password"]);
// → '{"password":"****"}'

Services

Service classes that encapsulate complex validation and business logic. These provide reusable, stateful utilities for common operations like date validation with leap year support.

ts

import { ValidateDateService } from "@arkyn/shared/validateDateService";


const validator = new ValidateDateService();
validator.validateDateParts(2024, 2, 29); // Validates leap year date

Utilities

General-purpose helper functions for common tasks such as HTML processing, financial calculations, string manipulation, and data cleaning.

ts

import { stripHtmlTags } from "@arkyn/shared/stripHtmlTags";
import { calculateCardInstallment } from "@arkyn/shared/calculateCardInstallment";
import { isHtml } from "@arkyn/shared/isHtml";


stripHtmlTags("<p>Hello <strong>World</strong></p>");
// → "Hello World"


calculateCardInstallment({ cashPrice: 1000, numberInstallments: 12 });
// → { totalPrice: 1241.04, installmentPrice: 103.42 }

Design Philosophy

@arkyn/shared follows these core principles:
  1. Predictable behavior: Functions behave consistently and throw meaningful errors when inputs are invalid
  2. Immutability: Functions never mutate input data—they always return new values
  3. Explicit over implicit: Required parameters are clearly documented, with sensible defaults for optional ones
  4. Internationalization ready: Built-in support for Brazilian formats (CPF, CNPJ, CEP, phone) and 22+ international currencies

Getting Started

Explore the documentation sections to learn about each function in detail:
  • Formats, Data formatting utilities
  • Generators, ID and content generation
  • Parsers, Data parsing and transformation
  • Services, Validation and business logic services
  • Utilities, General-purpose helper functions
On this page
    arkyn