utilzify

JavaScript va TypeScript loyihalari uchun yengil, modulli yordamchi funksiyalar kutubxonasi.

utilzify — frontend va backend ishlanmalarda eng ko'p uchraydigan vazifalarni soddalashtirish uchun mo'ljallangan utilitlar to'plami. Sana formatlash, raqam parselash, Excel/CSV bilan ishlash, Google Sheets'dan ma'lumot o'qish, HTTP header generatsiyasi, xato xabarlarini chiqarib olish va boshqa ko'plab vazifalar uchun tayyor yechimlar.

Mundarija

• O'rnatish
• Xususiyatlar
• Tezkor boshlash
• API hujjati
  • Sana bilan ishlash
  • Raqam va matnni formatlash
  • Asinxron yordamchilar
  • Vaqt birliklari
  • Object va jadval bilan ishlash
  • Excel bilan ishlash
  • Column / Row parser
  • Google Sheets mapper
  • Axios handler'lari
  • HTTP header generator
  • Xato xabarlarini ajratish
  • DOM va fayl saqlash
  • Atrof-muhit (environment)
  • Boshqa utilitlar
• TypeScript qo'llab-quvvatlash
• Litsenziya

O'rnatish

# yarn
yarn add utilzify

# npm
npm install utilzify

# pnpm
pnpm add utilzify

Talablar: Node.js >= 20. Kutubxona ESM, CJS va UMD formatlarida tarqatiladi.

Xususiyatlar

• Yengil bundle — sanalar uchun dayjs (~2kb gzip)
• Tree-shakeable — sideEffects: false, faqat ishlatilgan funksiyalar build'ga tushadi
• TypeScript — barcha funksiyalar uchun to'liq typelar va nested key inferensiyasi
• Universal — Node.js va brauzer muhitlarida ishlaydi (muhitga bog'liq funksiyalar avtomatik tekshiriladi)
• Excel/CSV — exceljs asosida o'qish/yozish
• Robust xato ajratish — har qanday API javobidan xato matnini topib oladi

Tezkor boshlash

import { getFormattedDate, formatCurrencyPrice, debounce, Excel } from "utilzify";

// Sana formatlash
getFormattedDate(new Date(), "DD/MM/YYYY"); // "15/05/2026"

// Pulni formatlash
formatCurrencyPrice(1250000, "UZS"); // "UZS 1,250,000.00"

// Debounce
const onSearch = debounce((q: string) => fetch(`/api?q=${q}`), 300);

// Excel o'qish (frontend)
const excel = new Excel();
const rows = await excel.readFromArrayBuffer(blob, 1);

API hujjati

Sana bilan ishlash

Ichkarida dayjs ishlatiladi, customParseFormat plugini avtomatik kengaytirilgan — moment formatidagi tokenlar (DD/MM/YYYY, HH:mm:ss va h.k.) ishlayveradi.

getFormattedDate(date?, format?)

Date, number yoki string qiymatni formatlangan satrga aylantiradi.

getFormattedDate();                                   // "15/05/2026 14:30:00" (default: DD/MM/YYYY HH:mm:ss)
getFormattedDate(Date.now(), "YYYY-MM-DD");           // "2026-05-15"
getFormattedDate("2026-05-15T10:00:00Z", "HH:mm");    // "15:00"
getFormattedDate("noto'g'ri sana");                   // ""  (yaroqsiz bo'lsa bo'sh satr)

getValidDate(dateStr, parseFormat)

Formatga ko'ra satrdan Date obyektini parselaydi.

getValidDate("15/05/2026", "DD/MM/YYYY"); // Date obyekti

formatDateLocaleString(date, locales?, timeZone?)

Intl orqali mahalliy formatlash. Default: en-GB locale, Asia/Tashkent vaqt zonasi.

formatDateLocaleString(Date.now());                              // "15/05/2026, 14:30:00"
formatDateLocaleString(Date.now(), "uz-UZ", "Asia/Tashkent");    // "15.05.2026, 14:30:00"

Raqam va matnni formatlash

formatCurrencyPrice(price, currency, locales?)

Pul qiymatini valyuta bilan birga formatlaydi.

formatCurrencyPrice(1250000, "UZS");           // "UZS 1,250,000.00"
formatCurrencyPrice(99.99, "USD", "en-US");    // "$99.99"
formatCurrencyPrice(1500, "EUR", "de-DE");     // "1.500,00 €"

formatStringToFloat(str, defaultValue?)

Har xil formatdagi raqamli matnlarni number ga aylantiradi. Hind (1,23,456.78), Yevropa (1.234,56) va oddiy (1234.56) formatlarni tushunadi.

formatStringToFloat("1,234.56");      // 1234.56
formatStringToFloat("1.234,56");      // 1234.56
formatStringToFloat("1,23,456.78");   // 123456.78
formatStringToFloat("noto'g'ri", 0);  // 0

parseSeparatedNumber(str)

Verguldan tozalab Number ga aylantiradi.

parseSeparatedNumber("1,234,567"); // 1234567

isIndianFormat(str) / parseIndianFormat(str) / parseEuropeanFormat(str)

Spetsifik format aniqlovchilari va parserlar (formatStringToFloat ichida ishlatiladi).

stripHtmlTags(html)

HTML teglarni olib tashlaydi.

stripHtmlTags("<p>Salom <b>dunyo</b></p>"); // "Salom dunyo"

Asinxron yordamchilar

delay(ms)

Berilgan vaqtga kutadi.

await delay(1000); // 1 soniya

delayRun(ms, callback?)

Berilgan vaqtdan keyin callback'ni ishga tushiradi va natijasini qaytaradi.

const result = await delayRun(500, async () => fetchData());

debounce(func, delay?, immediate?)

Funksiyani debounce qiladi (default: 300ms).

const onChange = debounce((value: string) => {
  console.log("Foydalanuvchi yozishni to'xtatdi:", value);
}, 500);

measureExecutionTime(fn, label?, format)

Funksiya bajarilish vaqtini o'lchaydi va konsolga chiqaradi.

const data = await measureExecutionTime(
  () => fetchLargeDataset(),
  "fetchLargeDataset",
  "s",
);
// [fetchLargeDataset] Boshladi: 15/05/2026 14:30:00
// [fetchLargeDataset] Tugadi: 15/05/2026 14:30:03
// [fetchLargeDataset] Davomiyligi: 3.20 soniya

Vaqt birliklari

toMilliseconds(time)

Turli vaqt birliklarini millisekundga aylantiradi.

toMilliseconds({ minutes: 5, seconds: 30 }); // 330000
toMilliseconds({ hours: 1, days: 2 });       // 176400000
toMilliseconds({ years: 1 });                // 31557600000

Qabul qiluvchi kalitlar: milliseconds, seconds, minutes, hours, days, weeks, months (30.44 kun), years (365.25 kun).

formatDuration(ms, format)

Davomiylikni odamga tushunarli ko'rinishga keltiradi.

formatDuration(125000, "human"); // "2 daqiqa 5 soniya"
formatDuration(125000, "s");     // "125.00 soniya"
formatDuration(125000, "min");   // "2.08 daqiqa"
formatDuration(125000, "ms");    // "125000 millisoniya"

Object va jadval bilan ishlash

getNestedValue(obj, key)

Nested kalit bo'yicha qiymatni xavfsiz olish.

getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
getNestedValue({ a: null }, "a.b.c");             // null

TypeScript bilan ishlatilganda NestedKeyOf<T> orqali kalit avtomatik to'liq tip xavfsiz bo'ladi.

buildTableRows(data, columns, withHeader?, extraMapper?)

Obyekt massivini jadval (any[][]) ko'rinishiga aylantiradi. Excel/CSV eksporti va react-table kabi kutubxonalar uchun ideal.

type User = { id: number; name: string; email: string; createdAt: string };

const users: User[] = [...];

const rows = buildTableRows(users, {
  id: "ID",                                         // sodda header
  name: { header: "Ismi" },                         // obyekt formati
  email: [
    "Email manzili",
    (val, row) => `<${val}>`,                       // tuple: [header, mapper]
  ],
  createdAt: (val) => getFormattedDate(val),        // faqat mapper
}, true);

// Natija:
// [
//   ["ID", "Ismi", "Email manzili", "createdAt"],
//   [1, "Ali", "<[email protected]>", "15/05/2026 14:30:00"],
//   ...
// ]

Column tip variantlari:

| Format | Misol | Tushuntirish | |---|---|---| | string | "Header nomi" | Faqat header matni | | MapperFn | (val, row, key) => ... | Faqat mapper, header avtomatik | | [string, MapperFn] | ["Header", mapper] | Header va mapper | | Object | { header, mapper, emptyVal, staticVal } | To'liq nazorat | | false | — | Bu ustun skip qilinadi |

Performance: Funksiya 25k+ qatorlik massivlar bilan ham tez ishlaydi — column metadata bir marta compile qilinib hot loopda qayta ishlatiladi.

objectToArray(data, keys, headers?, emptyVal?)

Tezkor variant: faqat ko'rsatilgan kalitlardan jadval tuzadi (mapper yo'q).

objectToArray(users, ["id", "name", "email"], ["ID", "Ism", "Email"]);

objectItemToArray(row, keys, emptyVal?)

Bitta obyektni massivga aylantiradi.

getPrimitiveKeys(input)

Obyekt yoki massiv ichidagi barcha primitiv kalitlarni dot.notation ko'rinishida qaytaradi (dinamik tablica generatsiyasi uchun foydali).

getPrimitiveKeys([{ id: 1, user: { name: "Ali" } }]);
// ["id", "user.name"]

Excel bilan ishlash

Excel sinfi exceljs asosida ishlaydi va faqat frontend muhitda chaqiriladi (konstruktor o'zi muhitni tekshiradi).

import { Excel } from "utilzify";

const excel = new Excel();

// 1) Blob/ArrayBuffer dan o'qish
const rows = await excel.readFromArrayBuffer(blob, 1);

// 2) Disk yo'lidan o'qish (Node muhitida)
const rows2 = await excel.read("./data.xlsx", "Sheet1");

// 3) Obyekt massividan yozish va yuklatish
await excel.write(
  users,
  ["ID", "Ismi", "Email"],
  ["id", "name", "email"],
  "users",
  "Sheet1",
);
// → users_2026-05-15.xlsx yuklab olinadi

// 4) Massivlardan yozish
await excel.writeFromArray(
  [["1", "Ali", "[email protected]"]],
  ["ID", "Ismi", "Email"],
  "users",
);

Column / Row parser

Excel/Google Sheets dan kelgan qator massivlarini tip-xavfsiz ravishda parselash uchun.

Yordamchi funksiyalar

getColumnIndex("A");    // 0
getColumnIndex("Z");    // 25
getColumnIndex("AA");   // 26

getColumnName(0);       // "A"
getColumnName(26);      // "AA"

getValueByName(row, "C", null);  // C ustun qiymati

ColumnParser

Default qiymat va tip-xavfsiz ishlash bilan.

const row = ["Ali", "25", "TRUE", "1,250,000", "15/05/2026"];

ColumnParser.string(row, "A");                                 // "Ali"
ColumnParser.number(row, "B", 0);                              // 25
ColumnParser.boolean(row, "C", false);                         // true
ColumnParser.price(row, "D");                                  // 1250000
ColumnParser.date(row, "E", "DD/MM/YYYY");                     // Date obyekti
ColumnParser.formattedDate(row, "E", "DD/MM/YYYY", "YYYY-MM-DD"); // "2026-05-15"

ColumnMapper va IndexMapper

Eski API — ColumnMapper kalit nomi bo'yicha ("A", "B"), IndexMapper indeks bo'yicha (0, 1) ishlaydi.

ColumnMapper.getStr(row, "A", "default");
ColumnMapper.getNum(row, "B", 0);
ColumnMapper.getBool(row, "C", false);
ColumnMapper.getPrice(row, "D");
ColumnMapper.getDate(row, "E", "DD/MM/YYYY");
ColumnMapper.getDateFormatted(row, "E", "YYYY-MM-DD", "DD/MM/YYYY");

IndexMapper.getStr(row, 0);
IndexMapper.getNum(row, 1);
// ...

resolveHeaderColumn va resolveHeaderColumnMap

Sheet'ning birinchi qatoridagi headerlar bo'yicha ustun harflarini topish.

const headers = ["ID", "Ismi", "Email", "Sana"];

resolveHeaderColumn(headers, "Email");                  // "C"
resolveHeaderColumn(headers, "Telefon", "X");           // "X" (topilmasa)

resolveHeaderColumnMap(headers, {
  id: "ID",
  name: "Ismi",
  email: ["Email", "C"],   // [header, default]
});
// → { id: "A", name: "B", email: "C" }

Google Sheets mapper

Tipik Google Sheets ma'lumotlarini tip-xavfsiz ravishda obyektlarga aylantirish uchun yuqori darajali API.

createColMapper — ustun harfi bo'yicha

import { createColMapper, col } from "utilzify";

const mapRow = createColMapper({
  id: col.num("A"),
  name: col.str("B", ""),
  isActive: col.bool("C", false),
  price: col.price("D"),
  createdAt: col.date("E", "DD/MM/YYYY"),
  formattedDate: col.datefmt("E", "DD/MM/YYYY", "YYYY-MM-DD"),
  fullName: col.fn((row) => `${row[1]} ${row[2]}`),  // custom logika
});

const result = mapRow(["1", "Ali", "TRUE", "1,250,000", "15/05/2026"]);
// { id: 1, name: "Ali", isActive: true, price: 1250000, ... }

createHdrMapper — header nomi bo'yicha

Sheet ustunlari joyi o'zgarib turishi mumkin bo'lgan holatlar uchun.

import { createHdrMapper, hdr } from "utilzify";

const buildMapper = createHdrMapper({
  id: hdr.num("ID"),
  name: hdr.str("Ismi"),
  email: hdr.str(["Email", "C"]),  // default ustun "C"
});

const rows = await excel.read("./data.xlsx");
const [headers, ...dataRows] = rows;

const mapRow = buildMapper(headers);
const users = dataRows.map(mapRow);

Builderlar: col.str(), col.num(), col.bool(), col.price(), col.date(), col.datefmt(), col.fn(). Shu kabi hdr.*.

Axios handler'lari

axios interceptor'lari uchun tayyor handler'lar.

import axios from "axios";
import { axiosSuccessHandler, axiosErrorHandler } from "utilzify";

axios.interceptors.response.use(
  axiosSuccessHandler((data) => console.log("OK:", data)),
  axiosErrorHandler((err, message) => console.error("XATO:", message)),
);

// Endi har qanday so'rov natijasi:
// { ...response, type: "SUCCESS" }
// yoki rejected: { error, data, status, statusText, type: "ERROR" }

axiosErrorHandler ning ikkinchi parametri (reject) false qilinsa, xato o'rniga resolved promise qaytariladi.

HTTP header generator

Brauzer fingerprintingidan qochish yoki test qilish uchun real ko'rinishdagi headerlar.

import {
  generateUserAgents,
  generateRandomHeaders,
  generateAndAssignRandomHeaders,
  clearHeaders,
  headerRandomizer,
  randIp,
} from "utilzify";

generateUserAgents(5);
// ["Mozilla/5.0 (Windows NT 10.0; en) Chrome/12.3 Blink/4.7", ...]

generateRandomHeaders();
// { Accept: "...", "User-Agent": "...", Referer: "...", "X-Forwarded-For": "...", ... }

randIp(); // "15.234.12.87"

// Axios config'iga to'g'ridan-to'g'ri qo'shish
const config = generateAndAssignRandomHeaders({ url: "/api/data" });

clearHeaders(headers, ["x-custom-header"]); // Sezgir headerlarni olib tashlaydi

Eslatma: Brauzer muhitida User-Agent, Referer va shu kabilar avtomatik o'tkazib yuboriladi (brauzer ularni o'zi belgilaydi).

Xato xabarlarini ajratish

Har qanday API javobidan eng mos xato matnini topib chiqaradi (50+ umumiy kalit yo'llari sinab ko'riladi).

extractErrorMessage(error, defaultMsg?, additionalKeys?)

import { extractErrorMessage } from "utilzify";

try {
  await api.request();
} catch (err) {
  const msg = extractErrorMessage(err, "Noma'lum xato");
  showToast(msg);
}

Quyidagi yo'llardan biri bo'yicha xato topiladi: response.data.error, response.data.message, error.message, cause.message, errors[*].message, va h.k. HTML teglar avtomatik tozalanadi.

extractErrorMessages(error, additionalKeys?)

Bir nechta xato xabarlarini massiv ko'rinishida qaytaradi (validatsiya xatolari uchun).

const messages = extractErrorMessages(validationError);
// ["Ism majburiy", "Email noto'g'ri formatda", ...]

DOM va fayl saqlash

Bu funksiyalar faqat brauzer muhitida ishlaydi. Node.js da chaqirilsa Error tashlanadi.

scrollToElement(selector)

scrollToElement("#section-2"); // smooth scroll

saveFile(blob, fileName)

Blob'ni foydalanuvchiga fayl ko'rinishida yuklatadi.

const blob = new Blob([data], { type: "application/pdf" });
saveFile(blob, "hisobot.pdf");

convertBase64ToFile(base64, fileName, fileType)

Base64 satrni faylga aylantirib yuklatadi.

convertBase64ToFile(base64String, "rasm", "PNG");
convertBase64ToFile(pdfBase64, "shartnoma", "PDF");

Qo'llab-quvvatlanadigan turlar: PDF, PNG, JPEG, EXCEL, WORD, TEXT.

Atrof-muhit (environment)

import { isBrowser, isNode, checkEnvironment } from "utilzify";

if (isBrowser()) {
  // brauzer kodi
}

if (isNode()) {
  // Node.js kodi
}

// Noto'g'ri muhitda chaqirilsa xato tashlaydi:
checkEnvironment("frontend");
checkEnvironment("backend");

Boshqa utilitlar

getRandomInt(min, max)

getRandomInt(1, 100); // 1 va 100 oraligida tasodifiy butun son

generateIdempotencyKey()

UUID v4 generatsiyasi (API'larda takroriy so'rovlarni oldini olish uchun).

generateIdempotencyKey(); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"

convertDigitalSize(input, output, value)

Raqamli o'lchov birliklarini aylantirish: bit, byte, kb, mb, gb, tb.

convertDigitalSize("mb", "gb", 1500);     // 1.46
convertDigitalSize("byte", "kb", 2048);   // 2

calculateDiscountedPrice(originalPrice, discountPercentage)

Chegirma narxini hisoblash.

calculateDiscountedPrice(100000, 15); // 85000

formatJsonForTelegram(data)

Telegram bot uchun JSON xabarini <pre> blokda formatlash (HTML parse mode).

formatJsonForTelegram({ status: "ok", id: 42 });
// "<pre>{\n  \"status\": \"ok\",\n  \"id\": 42\n}</pre>"

FileType va fileConfigs

Fayl turlari va ularning MIME-type/extension xaritalari.

import { FileType, fileConfigs } from "utilzify";

fileConfigs[FileType.PDF];   // { mimeType: "application/pdf", extension: "pdf" }
fileConfigs[FileType.EXCEL]; // { mimeType: "...spreadsheetml.sheet", extension: "xlsx" }

TypeScript qo'llab-quvvatlash

Kutubxona TypeScript bilan yozilgan va barcha publik API uchun tiplar mavjud. Eng qiziq tiplar:

import type {
  NestedKeyOf,           // T obyektining "a.b.c" ko'rinishidagi barcha kalitlari
  MapperFn,              // buildTableRows uchun mapper signature
  SortedArrayColumn,     // buildTableRows kolumn definitsiyasi
  ColSchema, HdrSchema,  // createColMapper / createHdrMapper sxemalari
  InferColSchema,        // sxemadan natija tipini inferensiya qilish
  TimeInput,             // toMilliseconds parametri
  FormatDurationTime,    // "ms" | "s" | "min" | "human"
  UnitType,              // "bit" | "byte" | "kb" | "mb" | "gb" | "tb"
  FileConfig,
  EcosystemApp,          // pm2 ecosystem.config tipi
  EcosystemConfig,
} from "utilzify";

NestedKeyOf orqali nested kalitlar avtomatik to'liq tip-xavfsiz bo'ladi:

type User = { id: number; profile: { name: string; age: number } };

getNestedValue<User, "profile.name">(user, "profile.name"); // string | null

Litsenziya

ISC © svkhrobbeck