@viettv/universal-utils

Thư viện tiện ích toàn diện cho các thao tác với file, HTTP requests, xử lý dữ liệu và nhiều hơn nữa.

Cài đặt

npm install @viettv/universal-utils

Sử dụng

Cách 1: Import toàn bộ thư viện

const utils = require('@viettv/universal-utils');

// Sử dụng các hàm
const files = await utils.getChildFileOrFolder('./mydir');
const data = await utils.readJsonFile('./data.json');
utils.notify('Success!').success();

Cách 2: Import riêng các Helper modules

// Array Helper
const arrayHelper = require('@viettv/universal-utils/array');
const unique = arrayHelper.unique([1, 2, 2, 3, 4, 4, 5]);
const chunks = arrayHelper.chunk([1, 2, 3, 4, 5, 6, 7], 3);

// Number Helper
const numberHelper = require('@viettv/universal-utils/number');
const sum = numberHelper.sum([1, 2, 3, 4, 5]);
const formatted = numberHelper.formatCurrency(1234.56);

// String Helper
const stringHelper = require('@viettv/universal-utils/string');
const slug = stringHelper.slugify('Hello World');
const camelCase = stringHelper.toCamelCase('hello world');

// Object Helper
const objectHelper = require('@viettv/universal-utils/object');
const merged = objectHelper.merge({ a: 1 }, { b: 2 });
const value = objectHelper.get(obj, 'nested.path', 'default');

API Documentation

File Operations

getChildFileOrFolder(directoryPath)

Lấy danh sách tất cả files và folders trong một thư mục.

const files = await utils.getChildFileOrFolder('./mydir');
// Trả về: ['file1.txt', 'file2.js', 'folder1', ...]

getLatestVersion(directoryPath, fileName, separator)

Tìm phiên bản mới nhất của một file có đánh số phiên bản.

const result = await utils.getLatestVersion('./uploads', 'document.pdf', '_v');
// Trả về: { filename: 'document_v5.pdf', version: 5, recommendedNextName: 'document_v6.pdf', nextVersion: 6 }

readExcelFile(filePath, sheetIndex)

Đọc và parse file Excel thành JSON.

const data = await utils.readExcelFile('./data.xlsx', 0);
// Trả về: [{ col1: 'value1', col2: 'value2' }, ...]

readJsonFile(filePath)

Đọc file JSON bất đồng bộ.

const config = await utils.readJsonFile('./config.json');

writeToExcelFile(data, filePath, sheetName)

Ghi dữ liệu ra file Excel.

const data = [
    { name: 'John', age: 30 },
    { name: 'Jane', age: 25 }
];
utils.writeToExcelFile(data, './output.xlsx', 'Users');

writeToJsonFile(data, filePath, prettify)

Ghi dữ liệu ra file JSON.

await utils.writeToJsonFile({ key: 'value' }, './data.json', true);

writeToTextFile(data, filePath)

Ghi text ra file.

await utils.writeToTextFile('Hello World', './output.txt');

HTTP Operations

httpGet(urlString, options)

Thực hiện HTTP GET request.

const response = await utils.httpGet('https://api.example.com/data');
// Trả về: string response data

httpPost(url, postData, options)

Thực hiện HTTP POST request.

const result = await utils.httpPost('https://api.example.com/users', {
    name: 'John',
    email: '[email protected]'
});
// Trả về: { statusCode: 200, headers: {...}, data: {...} }

String Operations

getPositionOfSubString(string, subStr, index)

Tìm vị trí của substring tại lần xuất hiện thứ N.

const pos = utils.getPositionOfSubString('hello world hello', 'hello', 2);
// Trả về: 12

insertChar(originalString, charToInsert, position)

Chèn ký tự vào string tại vị trí chỉ định.

const result = utils.insertChar('Hello World', '!', 5);
// Trả về: 'Hello! World'

removeVietnameseTones(str)

Loại bỏ dấu tiếng Việt khỏi text.

const result = utils.removeVietnameseTones('Xin chào Việt Nam');
// Trả về: 'Xin chao Viet Nam'

Array Operations (Main Export)

Các hàm array cơ bản cũng có sẵn trong main export:

const utils = require('@viettv/universal-utils');

const merged = await utils.mergeAndGetDistinctValues([1, 2, 3], [3, 4, 5]);
const unique = await utils.getUniqueItems(users, 'id');
const grouped = utils.groupBy(items, 'category');
const grouped2D = utils.groupBy2DArray(items, 'category');

Array Helper Module

Module chuyên dụng với nhiều hàm tiện ích cho arrays:

const arrayHelper = require('@viettv/universal-utils/array');

unique(arr)

Lấy các giá trị unique từ array đơn giản.

const numbers = [1, 2, 2, 3, 4, 4, 5];
const result = arrayHelper.unique(numbers);
// Trả về: [1, 2, 3, 4, 5]

flatten(arr, depth)

Làm phẳng array đa chiều.

const nested = [1, [2, [3, [4]], 5]];
const flat = arrayHelper.flatten(nested);
// Trả về: [1, 2, 3, 4, 5]

chunk(arr, size)

Chia array thành các mảng con có kích thước cố định.

const items = [1, 2, 3, 4, 5, 6, 7];
const chunks = arrayHelper.chunk(items, 3);
// Trả về: [[1, 2, 3], [4, 5, 6], [7]]

groupBy(arr, key)

Nhóm các items trong array theo một thuộc tính.

const items = [
    { category: 'fruit', name: 'apple' },
    { category: 'fruit', name: 'banana' },
    { category: 'vegetable', name: 'carrot' }
];
const grouped = arrayHelper.groupBy(items, 'category');
// Trả về: {
//   fruit: [{ category: 'fruit', name: 'apple' }, { category: 'fruit', name: 'banana' }],
//   vegetable: [{ category: 'vegetable', name: 'carrot' }]
// }

groupBy2DArray(arr, key)

Nhóm items và trả về dạng mảng 2D.

const grouped = arrayHelper.groupBy2DArray(items, 'category');
// Trả về: [
//   [{ category: 'fruit', name: 'apple' }, { category: 'fruit', name: 'banana' }],
//   [{ category: 'vegetable', name: 'carrot' }]
// ]

shuffle(arr)

Xáo trộn array ngẫu nhiên.

const items = [1, 2, 3, 4, 5];
const shuffled = arrayHelper.shuffle(items);
// Trả về: [3, 1, 5, 2, 4] (thứ tự ngẫu nhiên)

sample(arr, count)

Lấy ngẫu nhiên item(s) từ array.

const items = [1, 2, 3, 4, 5];
const one = arrayHelper.sample(items);      // 3 (1 item ngẫu nhiên)
const three = arrayHelper.sample(items, 3); // [2, 5, 1] (3 items ngẫu nhiên)

difference(arr1, arr2)

Tìm các phần tử có trong arr1 nhưng không có trong arr2.

const diff = arrayHelper.difference([1, 2, 3, 4], [3, 4, 5, 6]);
// Trả về: [1, 2]

intersection(arr1, arr2)

Tìm các phần tử có trong cả hai arrays.

const common = arrayHelper.intersection([1, 2, 3, 4], [3, 4, 5, 6]);
// Trả về: [3, 4]

partition(arr, predicate)

Phân chia array thành hai arrays dựa trên điều kiện.

const numbers = [1, 2, 3, 4, 5, 6];
const [evens, odds] = arrayHelper.partition(numbers, n => n % 2 === 0);
// evens: [2, 4, 6]
// odds: [1, 3, 5]

countBy(arr)

Đếm số lần xuất hiện của mỗi item.

const items = ['apple', 'banana', 'apple', 'orange', 'banana', 'apple'];
const counts = arrayHelper.countBy(items);
// Trả về: { apple: 3, banana: 2, orange: 1 }

sortBy(arr, key, ascending)

Sắp xếp array của objects theo một thuộc tính.

const users = [
    { name: 'John', age: 30 },
    { name: 'Jane', age: 25 },
    { name: 'Bob', age: 35 }
];
const sorted = arrayHelper.sortBy(users, 'age');
// Trả về: [{ name: 'Jane', age: 25 }, { name: 'John', age: 30 }, { name: 'Bob', age: 35 }]

includesAny(arr, values)

Kiểm tra xem array có chứa bất kỳ giá trị nào không.

const items = [1, 2, 3, 4, 5];
const hasAny = arrayHelper.includesAny(items, [6, 7, 3]);
// Trả về: true (vì 3 có trong items)

includesAll(arr, values)

Kiểm tra xem array có chứa tất cả các giá trị không.

const items = [1, 2, 3, 4, 5];
const hasAll = arrayHelper.includesAll(items, [2, 3, 4]);
// Trả về: true (tất cả values đều có trong items)

remove(arr, ...values)

Loại bỏ các items khỏi array theo giá trị.

const items = [1, 2, 3, 4, 5, 3];
const filtered = arrayHelper.remove(items, 3, 5);
// Trả về: [1, 2, 4]

take(arr, n) và takeLast(arr, n)

Lấy n items đầu hoặc cuối từ array.

const items = [1, 2, 3, 4, 5];
const first3 = arrayHelper.take(items, 3);     // [1, 2, 3]
const last3 = arrayHelper.takeLast(items, 3);  // [3, 4, 5]

zip(...arrays)

Gộp nhiều arrays lại với nhau.

const names = ['John', 'Jane', 'Bob'];
const ages = [30, 25, 35];
const zipped = arrayHelper.zip(names, ages);
// Trả về: [['John', 30], ['Jane', 25], ['Bob', 35]]

range(start, end, step)

Tạo array các số trong một khoảng.

const range1 = arrayHelper.range(1, 5);     // [1, 2, 3, 4]
const range2 = arrayHelper.range(0, 10, 2); // [0, 2, 4, 6, 8]

areArraysEqual(arr1, arr2)

Kiểm tra xem hai arrays có bằng nhau không (so sánh có thứ tự). Đây là phương thức tốt nhất về hiệu suất.

arrayHelper.areArraysEqual([1, 2, 3], [1, 2, 3]); // true
arrayHelper.areArraysEqual([1, 2, 3], [3, 2, 1]); // false (thứ tự khác)
arrayHelper.areArraysEqual([1, 2], [1, 2, 3]);    // false (độ dài khác)

areArraysEqualUnordered(arr1, arr2)

Kiểm tra xem hai arrays có chứa cùng các phần tử không, bất kể thứ tự.

arrayHelper.areArraysEqualUnordered([1, 2, 3], [3, 2, 1]); // true (cùng phần tử)
arrayHelper.areArraysEqualUnordered([1, 2, 3], [1, 2, 4]); // false (phần tử khác)
arrayHelper.areArraysEqualUnordered([1, 2], [1, 2, 3]);    // false (độ dài khác)

mergeAndGetDistinctValues(arr1, arr2, assumeUnique)

Gộp hai arrays và lấy các giá trị không trùng lặp.

const result = await arrayHelper.mergeAndGetDistinctValues([1, 2, 3], [3, 4, 5]);
// Trả về: [1, 2, 3, 4, 5]

getUniqueItems(arr, keyField)

Loại bỏ duplicates từ array dựa trên một thuộc tính.

const users = [
    { id: 1, name: 'John' },
    { id: 2, name: 'Jane' },
    { id: 1, name: 'John' }
];
const unique = await arrayHelper.getUniqueItems(users, 'id');
// Trả về: [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]

getUniqueBy(arr, keys, separator)

Loại bỏ duplicates dựa trên một hoặc nhiều thuộc tính (composite keys). Hỗ trợ cả single key và multiple keys.

// Single key
const users = [
    { email: '[email protected]', name: 'John' },
    { email: '[email protected]', name: 'Jane' },
    { email: '[email protected]', name: 'John Smith' }  // duplicate email
];
const uniqueByEmail = arrayHelper.getUniqueBy(users, 'email');
// Trả về: [
//   { email: '[email protected]', name: 'John' },
//   { email: '[email protected]', name: 'Jane' }
// ]

// Multiple keys (composite key)
const tickets = [
    { class: 'first', fare: 'a' },
    { class: 'first', fare: 'a' },   // duplicate
    { class: 'first', fare: 'b' },
    { class: 'second', fare: 'a' },
    { class: 'first', fare: 'a' }    // duplicate
];
const uniqueTickets = arrayHelper.getUniqueBy(tickets, ['class', 'fare']);
// Trả về: [
//   { class: 'first', fare: 'a' },
//   { class: 'first', fare: 'b' },
//   { class: 'second', fare: 'a' }
// ]

Number Helper Module

Module chuyên dụng với nhiều hàm tiện ích cho numbers:

const numberHelper = require('@viettv/universal-utils/number');

Các hàm chính:

• sum(arr) - Tổng các số trong array
• average(arr) - Trung bình cộng
• min(arr), max(arr), median(arr) - Tìm giá trị min, max, median
• formatThousands(num, separator) - Format số với dấu phân cách nghìn
• formatCurrency(num, currency, decimals) - Format tiền tệ
• formatPercent(num, decimals, asDecimal) - Format phần trăm
• formatCompact(num, decimals) - Format gọn (1.2K, 1.5M, ...)
• round(num, decimals), roundUp(num, decimals), roundDown(num, decimals) - Làm tròn
• randomInt(min, max), randomFloat(min, max, decimals) - Số ngẫu nhiên
• percentChange(oldValue, newValue) - Tính % thay đổi
• isEven(num), isOdd(num), isPrime(num) - Kiểm tra số
• gcd(a, b), lcm(a, b) - Ước chung lớn nhất, bội chung nhỏ nhất

Xem file number.js để biết đầy đủ các functions và examples.

String Helper Module

Module chuyên dụng với nhiều hàm tiện ích cho strings:

const stringHelper = require('@viettv/universal-utils/string');

Các hàm chính:

• toCamelCase(str), toPascalCase(str), toSnakeCase(str), toKebabCase(str), toTitleCase(str) - Chuyển đổi case
• capitalize(str) - Viết hoa chữ cái đầu
• reverse(str) - Đảo ngược chuỗi
• truncate(str, length, suffix) - Cắt ngắn chuỗi
• pad(str, length, char, direction) - Padding chuỗi
• slugify(str) - Tạo slug URL-friendly
• isEmpty(str), isAlpha(str), isNumeric(str), isAlphanumeric(str) - Kiểm tra chuỗi
• isEmail(str), isUrl(str) - Kiểm tra email, URL
• countOccurrences(str, substr) - Đếm số lần xuất hiện
• extractNumbers(str), extractEmails(str), extractUrls(str) - Trích xuất dữ liệu
• removeVietnameseTones(str) - Loại bỏ dấu tiếng Việt
• mask(str, visibleChars, maskChar) - Che giấu chuỗi

Xem file string.js để biết đầy đủ các functions và examples.

Object Helper Module

Module chuyên dụng với nhiều hàm tiện ích cho objects:

const objectHelper = require('@viettv/universal-utils/object');

Các hàm chính:

• deepClone(obj) - Sao chép sâu object
• isEmpty(obj) - Kiểm tra object rỗng
• keys(obj), values(obj), entries(obj), size(obj) - Lấy thông tin object
• pick(obj, keys), omit(obj, keys) - Chọn hoặc loại bỏ keys
• merge(...objects) - Gộp nhiều objects
• flatten(obj, separator), unflatten(obj, separator) - Làm phẳng/mở rộng object
• invert(obj) - Đảo ngược keys và values
• isObject(value), hasKey(obj, key), hasKeys(obj, keys) - Kiểm tra object
• isEqual(obj1, obj2) - So sánh sâu hai objects
• mapValues(obj, fn), mapKeys(obj, fn), filter(obj, predicate) - Transform object
• get(obj, path, defaultValue), set(obj, path, value), has(obj, path) - Truy cập nested properties
• compact(obj, deep) - Loại bỏ null/undefined values

Xem file object.js để biết đầy đủ các functions và examples.

Console Operations

notify(content)

Tạo console notifications với màu sắc.

utils.notify('Operation completed').success();  // Màu xanh lá
utils.notify('Warning message').warning();      // Màu vàng
utils.notify('Error occurred').error();         // Màu đỏ
utils.notify('Information').info();             // Màu xanh dương
utils.notify('Regular log').log();              // Màu mặc định

Timer Operations

sleep(time)

Tạm dừng thực thi trong khoảng thời gian chỉ định.

await utils.sleep(1000); // Dừng 1 giây
console.log('1 giây sau...');

timeout(ms)

Tạo timeout promise.

try {
    await Promise.race([
        longRunningOperation(),
        utils.timeout(5000)
    ]);
} catch (error) {
    console.log('Operation timed out');
}

withTimeout(promise, ms)

Chạy promise với timeout.

try {
    const result = await utils.withTimeout(fetchData(), 5000);
} catch (error) {
    console.log('Operation timed out after 5 seconds');
}

Utility Functions

isEmpty(value)

Kiểm tra xem giá trị có rỗng không.

utils.isEmpty(null);        // true
utils.isEmpty('');          // true
utils.isEmpty([]);          // true
utils.isEmpty({});          // true
utils.isEmpty('hello');     // false

deepClone(obj)

Sao chép sâu một object.

const original = { a: 1, b: { c: 2 } };
const cloned = utils.deepClone(original);
cloned.b.c = 3;
console.log(original.b.c); // 2 (không bị thay đổi)

generateUUID()

Tạo UUID v4 đơn giản.

const id = utils.generateUUID();
// Trả về: 'a3f5b2c1-4d5e-4f6a-8b9c-0d1e2f3a4b5c'

Legacy Aliases

Để tương thích ngược, các alias sau vẫn được hỗ trợ:

// HTTP Operations
utils.httpGetBuiltIn(...);  // Giống httpGet
utils.createPostRequest(...); // Giống httpPost

// Array Operations
utils.mergeAndGetDistinctValuesFrom2Arrays(...); // Giống mergeAndGetDistinctValues
utils.uniq_fast(...);  // Giống getUniqueItems

Ví dụ sử dụng thực tế

Ví dụ 1: Xử lý dữ liệu từ Excel

const utils = require('@viettv/universal-utils');
const arrayHelper = require('@viettv/universal-utils/array');

async function processExcelData() {
    // Đọc dữ liệu từ Excel
    const data = await utils.readExcelFile('./users.xlsx');
    
    // Loại bỏ duplicates dựa trên email
    const uniqueUsers = await arrayHelper.getUniqueItems(data, 'email');
    
    // Nhóm theo department
    const byDepartment = arrayHelper.groupBy(uniqueUsers, 'department');
    
    // Sắp xếp theo tuổi
    const sorted = arrayHelper.sortBy(uniqueUsers, 'age');
    
    // Ghi kết quả ra file mới
    await utils.writeToExcelFile(sorted, './processed_users.xlsx');
    
    utils.notify('Xử lý hoàn tất!').success();
}

Ví dụ 2: Làm việc với API và xử lý arrays

const utils = require('@viettv/universal-utils');
const arrayHelper = require('@viettv/universal-utils/array');

async function fetchAndProcessData() {
    try {
        // Fetch data từ API với timeout
        const response = await utils.withTimeout(
            utils.httpGet('https://api.example.com/products'),
            5000
        );
        
        const products = JSON.parse(response);
        
        // Phân loại products
        const [inStock, outOfStock] = arrayHelper.partition(
            products, 
            p => p.stock > 0
        );
        
        // Nhóm theo category
        const byCategory = arrayHelper.groupBy(inStock, 'category');
        
        // Lấy 10 sản phẩm ngẫu nhiên
        const featured = arrayHelper.sample(inStock, 10);
        
        // Lưu kết quả
        await utils.writeToJsonFile({
            inStock: inStock.length,
            outOfStock: outOfStock.length,
            categories: Object.keys(byCategory),
            featured
        }, './products-summary.json');
        
        utils.notify('Data processed successfully').success();
    } catch (error) {
        utils.notify(`Error: ${error.message}`).error();
    }
}

Ví dụ 3: Xử lý files với versioning

const utils = require('@viettv/universal-utils');

async function saveWithVersion() {
    // Lấy version mới nhất
    const versionInfo = await utils.getLatestVersion(
        './backups',
        'database.json',
        '_v'
    );
    
    console.log(`Current version: ${versionInfo.version}`);
    console.log(`Next version: ${versionInfo.nextVersion}`);
    
    // Đọc dữ liệu hiện tại
    const data = await utils.readJsonFile('./database.json');
    
    // Lưu với version mới
    await utils.writeToJsonFile(
        data,
        `./backups/${versionInfo.recommendedNextName}`
    );
    
    utils.notify(`Saved as ${versionInfo.recommendedNextName}`).success();
}

Requirements

• Node.js >= 12.0.0

Dependencies

• xlsx - Để xử lý files Excel

License

MIT

Author

Your Name [email protected]

Repository

https://github.com/1zuna/npm-utilities

Issues

https://github.com/1zuna/npm-utilities/issues