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.

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.

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.

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.

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.

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:

Predictable behavior: Functions behave consistently and throw meaningful errors when inputs are invalid
Immutability: Functions never mutate input data—they always return new values
Explicit over implicit: Required parameters are clearly documented, with sensible defaults for optional ones
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

Using with AI coding assistants

@arkyn/shared ships its own AGENTS.md file inside the published package (available at node_modules/@arkyn/shared/AGENTS.md after install), a reference written specifically for AI coding assistants like Claude Code, Cursor, or Copilot. It documents every formatter, generator, parser, and service's exact signature and behavior, so your assistant doesn't need to read the source to use the library correctly.

Run @arkyn/cli once in your project to link it in: