@winglet/common-utils

Overview

@winglet/common-utils is a package that provides various utility functions useful in JavaScript/TypeScript projects.

This library offers commonly used functionalities in various areas including caching, array processing, object manipulation, Promise handling, and type checking.

Installation

# Using npm
npm install @winglet/common-utils

# Using yarn
yarn add @winglet/common-utils

Key Features

Constants

• Time-related constants (time.ts)
• Type tag constants (typeTag.ts)
• Unit conversion constants (unit.ts)

Error Handling

• BaseError: Base error class
• AbortError: Error for operation abortion
• InvalidTypeError: Error for invalid types
• TimeoutError: Error for timeouts

Utility Libraries (Libs)

• weakMapCacheFactory: Factory for WeakMap-based cache
• mapCacheFactory: Factory for Map-based cache
• counter: Utility for creating incrementing counters
• getKeys: Utility for getting object keys
• getTypeTag: Function to get the internal type tag of a JavaScript value
• hasOwnProperty: Function to check if an object has a specific property
• random: Utilities for random number generation

Utility Functions (Utils)

Array

• at: Function to return an element at a specified index in an array
• chunk: Function to split an array into chunks of specified size
• difference: Function to return elements in the first array that are not in other arrays
• differenceBy: Function to compute the difference between arrays based on results processed by an iterator function
• differenceWith: Function to compute the difference between arrays using a comparator function
• forEach: Function to execute a given function for each element in an array
• forEachDual: Function to iterate through two arrays simultaneously
• forEachReverse: Function to execute a function for each element in an array in reverse order
• groupBy: Function to group array elements by the result of an iterator function
• intersection: Function to return elements that exist in all arrays
• intersectionBy: Function to compute the intersection of arrays based on results processed by an iterator function
• intersectionWith: Function to compute the intersection of arrays using a comparator function
• map: Function to apply a function to each element in an array and create a new array with the results
• unique: Function to remove duplicate elements from an array
• uniqueBy: Function to return unique elements based on results processed by an iterator function
• uniqueWith: Function to return unique elements using a comparator function

Console

• printError: Function to print error objects to the console in a formatted way

Convert

• convertMsFromDuration: Function to convert a duration string (e.g., '1h30m') to milliseconds

DataLoader

• DataLoader: Utility class for efficiently loading data by processing requests in batches and caching

Filter

• isArray: Function to check if a value is an array
• isArrayBuffer: Function to check if a value is an ArrayBuffer
• isArrayIndex: Function to check if a value is a valid array index
• isArrayLike: Function to check if a value is array-like
• isBlob: Function to check if a value is a Blob object
• isBoolean: Function to check if a value is a Boolean
• isBuffer: Function to check if a value is a Buffer
• isCloneable: Function to check if a value can be cloned
• isDataView: Function to check if a value is a DataView
• isDate: Function to check if a value is a Date object
• isEmptyArray: Function to check if an array is empty
• isEmptyObject: Function to check if an object is empty
• isEmptyPlainObject: Function to check if a plain object is empty
• isError: Function to check if a value is an Error object
• isFile: Function to check if a value is a File object
• isFunction: Function to check if a value is a function
• isInteger: Function to check if a value is an integer
• isMap: Function to check if a value is a Map object
• isNil: Function to check if a value is null or undefined
• isNotNil: Function to check if a value is not null or undefined
• isNull: Function to check if a value is null
• isNumber: Function to check if a value is a number
• isObject: Function to check if a value is an object
• isPlainObject: Function to check if a value is a plain object
• isPrimitiveObject: Function to check if a value is a primitive wrapper object
• isPrimitiveType: Function to check if a value is a JavaScript primitive type
• isPromise: Function to check if a value is a Promise
• isRegex: Function to check if a value is a RegExp object
• isSet: Function to check if a value is a Set object
• isSharedArrayBuffer: Function to check if a value is a SharedArrayBuffer
• isString: Function to check if a value is a string
• isSymbol: Function to check if a value is a Symbol
• isTruthy: Function to check if a value is truthy
• isTypedArray: Function to check if a value is a TypedArray
• isUndefined: Function to check if a value is undefined
• isValidRegexPattern: Function to check if a string is a valid regex pattern
• isWeakMap: Function to check if a value is a WeakMap object
• isWeakSet: Function to check if a value is a WeakSet object

Function

• debounce: Function to delay execution until a certain time has passed with no additional calls
• throttle: Function to limit the execution frequency to specified time intervals

Hash

• Murmur3: Class implementing the Murmur3 hash algorithm for generating hashes from strings or byte arrays

JSON

• JSONPath: An expression system for querying and manipulating specific values within JSON data.
• JSONPointer: An implementation of JSON Pointer as defined in RFC 6901, used to reference specific locations within a JSON document.
  • getValueByPointer: Retrieves a value from JSON data based on a JSON Pointer.
  • setValueByPointer: Sets a value in JSON data based on a JSON Pointer.
  • escapePointer: Escapes a JSON Pointer string.
  • unescapePointer: Unescapes a JSON Pointer string.

Object

• clone: Function to create a deep copy of an object
• equals: Function to compare the equality of two objects
• getJSONPointer: Function to get a value from an object using a JSON Pointer
• getObjectKeys: Function to return all keys of an object as an array
• getSymbols: Function to return all symbol properties of an object as an array
• hasUndefined: Function to check if an object has undefined values
• merge: Function to merge multiple objects
• removeUndefined: Function to remove properties with undefined values from an object
• serializeNative: Function to serialize basic JavaScript objects to JSON strings
• serializeObject: Function to serialize objects to JSON strings
• serializeWithFullSortedKeys: Function to serialize objects to JSON strings with sorted keys
• sortObjectKeys: Function to sort an object's keys alphabetically
• stableEquals: Function to compare the equality of two objects in a stable way
• stableSerialize: Function to serialize objects in a stable way
• transformKeys: Function to apply a transformation function to all keys of an object
• transformValues: Function to apply a transformation function to all values of an object

Promise

• delay: Function to return a Promise that resolves after waiting for a specified time
• timeout: Function to return a Promise that rejects with a timeout error after a specified time
• withTimeout: Function to add a timeout to a Promise, causing an error if it doesn't complete within the specified time
• waitAndExecute: Function to execute a function after waiting for a specified time
• waitAndReturn: Function to return a value after waiting for a specified time

Scheduler

• scheduleMacrotask: Function to schedule a task in the macrotask queue
• cancelMacrotask: Function to cancel a scheduled macrotask
• scheduleCancelableMacrotask: Function to schedule a cancelable macrotask
• scheduleMicrotask: Function to schedule a task in the microtask queue
• scheduleNextTick: Function to schedule a task for the next tick, similar to Node.js's process.nextTick

Usage Examples

Using Cache Utilities

import { mapCacheFactory, weakMapCacheFactory } from '@winglet/common-utils';

// Create a WeakMap-based cache
const objectCache = weakMapCacheFactory<string>();
const myObject = { id: 1 };
objectCache.set(myObject, 'cached value');
console.log(objectCache.get(myObject)); // 'cached value'

// Create a Map-based cache
const stringCache = mapCacheFactory<Map<string, number>>();
stringCache.set('key1', 100);
console.log(stringCache.get('key1')); // 100

Using Promise Utilities

import { delay, withTimeout } from '@winglet/common-utils';

// Using the delay function
async function delayExample() {
  console.log('Start');
  await delay(1000); // Wait for 1 second
  console.log('After 1 second');
}

// Adding a timeout to a Promise
async function fetchWithTimeout(url: string) {
  const fetchPromise = fetch(url);
  return withTimeout(fetchPromise, 5000); // Add a 5-second timeout
}

Using Array Utilities

import { array } from '@winglet/common-utils';

// Example code:
const chunks = array.chunk([1, 2, 3, 4, 5, 6], 2);
console.log(chunks); // [[1, 2], [3, 4], [5, 6]]

Development Setup

# Clone repository
dir=your-albatrion && git clone https://github.com/vincent-kk/albatrion.git "$dir" && cd "$dir"

# Install dependencies
nvm use && yarn install && yarn run:all build

# Development build
yarn commonUtils build

# Run tests
yarn commonUtils test

License

This project is licensed under the MIT License. See the **LICENSE file for details.

Contact

For inquiries or suggestions related to the project, please create an issue.