@creejs/commons-lang 1.0.1

package/lib/type-utils.js

@@ -0,0 +1,290 @@
+'use strict'
+
+/**
+ * @module TypeUtils
+ * @description Utility functions for type checking and validation.
+ */
+
+/**
+   * Checks if the given value is an array.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is an array, false otherwise.
+   */
+function isArray (value) {
+  return Array.isArray(value)
+}
+
+/**
+   * Checks if the given value is a boolean.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a boolean, false otherwise.
+   */
+function isBoolean (value) {
+  return typeof value === 'boolean'
+}
+
+/**
+   * Checks if the given value is a Buffer.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a Buffer, false otherwise.
+   */
+function isBuffer (value) {
+  return value != null && Buffer.isBuffer(value)
+}
+
+/**
+   * Checks if the given value is a Date.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a Date, false otherwise.
+   */
+function isDate (value) {
+  return value != null && value instanceof Date
+}
+
+/**
+   * Checks if the given value is an instance of Error.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is an Error, false otherwise.
+   */
+function isError (value) {
+  return value != null && value instanceof Error
+}
+
+/**
+   * Checks if the given value is a function.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a function, false otherwise.
+   */
+function isFunction (value) {
+  return typeof value === 'function'
+}
+
+/**
+   * Checks if a value is a class instance (non-null and not a plain object).
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a class instance, false otherwise.
+   */
+function isInstance (value) {
+  return value != null && typeof value === 'object' && !TypeUtils.isPlainObject(value)
+}
+
+/**
+   * Checks if a value is isIterable
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is isIterable, false otherwise.
+   */
+function isIterable (value) {
+  return value != null && typeof value[Symbol.iterator] === 'function'
+}
+
+/**
+   * Checks if a value is Map
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is Map, otherwise false.
+   */
+function isMap (value) {
+  return value != null && typeof value === 'object' && value.constructor === Map
+}
+
+/**
+   * Checks if a value is WeakMap
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is WeakMap, otherwise false.
+   */
+function isWeakMap (value) {
+  return value != null && typeof value === 'object' && value.constructor === WeakMap
+}
+
+/**
+   * Checks if a value is null or undefined.
+   * 1. value == null
+   * 2. return true, if value is null or undefined
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is null or undefined, otherwise false.
+   */
+function isNil (value) {
+  return value == null
+}
+
+/**
+   * Checks if a value is null or undefined.
+   * 1. same with isNil()
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is null or undefined, otherwise false.
+   */
+function isNullOrUndefined (value) {
+  return value == null
+}
+
+/**
+ * check that a value is a positive number.
+ * @param {number} value - The value to check.
+ * @returns {boolean}
+ */
+function isPositive (value) {
+  if (!isNumber(value)) {
+    return false
+  }
+  return value > 0
+}
+
+/**
+ * check that a value is a Negative number.
+ * @param {number} value - The value to check.
+ */
+function isNegative (value) {
+  if (!isNumber(value)) {
+    return false
+  }
+  return value < 0
+}
+
+/**
+   * Checks if the given value is exactly null.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is null, false otherwise.
+   */
+function isNull (value) {
+  return value === null
+}
+
+/**
+   * Checks if a value is exactly undefined.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is undefined, false otherwise.
+   */
+function isUndefined (value) {
+  return value === undefined
+}
+
+/**
+   * Checks if a value is a number.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a number, false otherwise.
+   */
+function isNumber (value) {
+  return value != null && typeof value === 'number'
+}
+
+/**
+   * Checks if a value is an object (and not null).
+   * @param {*} value - The value to check
+   * @returns {boolean} True if the value is an object (not null), false otherwise
+   */
+function isObject (value) {
+  return value != null && typeof value === 'object'
+}
+
+/**
+   * Checks if a value is a plain object (created by the Object constructor).
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a plain object, false otherwise.
+   */
+function isPlainObject (value) {
+  return value !== null && typeof value === 'object' && (value.constructor === Object || value.constructor === undefined)
+}
+
+/**
+   * check if value is primitive: string, number, boolean
+   * 1. null/undefined returns false
+   * @param {*} value
+   * @returns {boolean}
+   */
+function isPrimitive (value) {
+  return value !== null && (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+}
+
+/**
+   * Checks if a value is a Promise.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a Promise, false otherwise.
+   */
+function isPromise (value) {
+  return value != null && typeof value.then === 'function'
+}
+
+/**
+   * Checks if a RegExp
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is RegExp, otherwise false.
+   */
+function isRegExp (value) {
+  return value != null && typeof value === 'object' && value.constructor === RegExp
+}
+
+/**
+   * Checks if a Set
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is Set, otherwise false.
+   */
+function isSet (value) {
+  return value != null && typeof value === 'object' && value.constructor === Set
+}
+
+/**
+   * Checks if a WeakSet
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is WeakSet, otherwise false.
+   */
+function isWeakSet (value) {
+  return value != null && typeof value === 'object' && value.constructor === WeakSet
+}
+
+/**
+   * Check if the value is a string
+   * @param {*} value
+   * @return {boolean}
+   */
+function isStream (value) {
+  return value != null && typeof value.pipe === 'function'
+}
+
+/**
+   * Check if the value is a string
+   * @param {*} value
+   * @return {boolean}
+   */
+function isString (value) {
+  return value != null && typeof value === 'string'
+}
+
+/**
+   * Checks if the given value is a Symbol.
+   * @param {*} value - The value to check.
+   * @returns {boolean} True if the value is a Symbol, false otherwise.
+   */
+function isSymbol (value) {
+  return value != null && typeof value === 'symbol'
+}
+
+const TypeUtils = {
+  isArray,
+  isBoolean,
+  isBuffer,
+  isFunction,
+  isInstance,
+  isIterable,
+  isDate,
+  isError,
+  isMap,
+  isWeakMap,
+  isNumber,
+  isPositive,
+  isNegative,
+  isNil,
+  isNullOrUndefined,
+  isNull,
+  isUndefined,
+  isPlainObject,
+  isObject,
+  isPromise,
+  isRegExp,
+  isSet,
+  isWeakSet,
+  isStream,
+  isString,
+  isSymbol,
+  isPrimitive
+}
+
+module.exports = TypeUtils

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@creejs/commons-lang",
+  "version": "1.0.1",
+  "private": false,
+  "description": "Commons Utils About Language",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib/",
+    "types/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frameworkee/commons.git"
+  },
+  "scripts": {
+    "dts": "tsc",
+    "generate-docs": "jsdoc -c ./jsdoc.json"
+  },
+  "author": "rodney.vin@gmail.com",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "better-docs": "^2.7.3",
+    "jsdoc": "^4.0.4"
+  },
+  "dependencies": {}
+}

package/types/exec-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+   * Executes a task silently, suppressing any errors or rejections.
+   * @param {Function} task - The function to execute.
+   * @returns {Promise<*>|*} The return value of the task, or a Promise if the task is asynchronous.
+   */
+export function quiet(task: Function): Promise<any> | any;
+/**
+   * Executes a task quietly, capturing any errors and passing them to the errorKeeper.
+   * 1. Handles both synchronous and asynchronous (Promise) tasks.
+   * @param {Function} task - The function to execute.
+   * @param {Error[]} errorKeeper - The array to store any caught errors.
+   * @returns {Promise<*>|*} The return value of the task, or a Promise if the task is asynchronous.
+   */
+export function quietKeepError(task: Function, errorKeeper: Error[]): Promise<any> | any;

package/types/index.d.ts

@@ -0,0 +1,7 @@
+import LangUtils = require("./lang-utils");
+import StringUtils = require("./string-utils");
+import TypeUtils = require("./type-utils");
+import TypeAssert = require("./type-assert");
+import ExecUtils = require("./exec-utils");
+import PromiseUtils = require("./promise-utils");
+export { LangUtils, StringUtils, TypeUtils, TypeAssert, ExecUtils, PromiseUtils, LangUtils as Lang, StringUtils as String, TypeUtils as Type, ExecUtils as Exec };

package/types/lang-utils.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module LangUtils
+ * @description Language utility functions
+ */
+/**
+   * Gets the constructor name of a value.
+   * @param {*} value - The value to check.
+   * @returns {string|undefined} The constructor name, or undefined if value has no constructor.
+   */
+export function constructorName(value: any): string | undefined;
+/**
+   * Assigns default values from source objects to target object for undefined properties.
+   * @param {Object<string, any>} target - The target object to assign defaults to
+   * @param {...Object<string, any>} sources - Source objects containing default values
+   * @returns {Object<string, any>} The modified target object with defaults applied
+   * @throws {TypeError} If target is null or undefined
+   */
+export function defaults(target: {
+    [x: string]: any;
+}, ...sources: {
+    [x: string]: any;
+}[]): {
+    [x: string]: any;
+};
+/**
+   * Extends a target object with properties from one or more source objects.
+   * @param {Object<string, any>} target - The target object to extend (must not be null/undefined)
+   * @param {...Object<string, any>} sources - One or more source objects to copy properties from
+   * @returns {Object<string, any>} The modified target object
+   * @throws {TypeError} If target is null or undefined
+   */
+export function extend(target: {
+    [x: string]: any;
+}, ...sources: {
+    [x: string]: any;
+}[]): {
+    [x: string]: any;
+};
+/**
+   * Compares two values for equality
+   * 1. First checks strict equality (===),
+   * 2. then checks if either value has an `equals` method and uses it.
+   * @param {*} value1 - First value to compare
+   * @param {*} value2 - Second value to compare
+   * @returns {boolean} True if values are equal, false otherwise
+   */
+export function equals(value1: any, value2: any): boolean;
+/**
+   * Check if the current environment is a browser
+   * @returns {boolean}
+   */
+export function isBrowser(): boolean;
+/**
+   * Check if the current environment is a nodejs
+   * @returns {boolean}
+   */
+export function isNode(): boolean;
+export { extend as extends };

package/types/lang.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Check if the current environment is a browser
+ * @returns {boolean}
+ */
+export function isBrowser(): boolean;

package/types/promise-utils.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Creates a "Deferred" Object with Timeout support
+ * 1. timeout=-1, it means no timeout check
+ * @param {number} [timeout=-1] - Timeout duration in milliseconds
+ * @returns {{promise: Promise<*>, reject: function, resolve: function}}
+ */
+export function defer(timeout?: number, timeoutMessage: any): {
+    promise: Promise<any>;
+    reject: Function;
+    resolve: Function;
+};
+/**
+   * Delays the resolution or rejection of a promise by a specified time.
+   * Ensures the promise settles after at least the given milliseconds.
+   * If the original promise settles before the delay, waits for remaining time.
+   *
+   * @param {Promise} promise - The input promise to delay
+   * @param {number} [ms=1000] - Minimum delay in milliseconds (default: 1)
+   * @returns {Promise} A new promise that settles after the delay period
+   */
+export function delay(promise: Promise<any>, ms?: number): Promise<any>;
+/**
+ * Creates a timeout wrapper around a promise that rejects if the promise doesn't resolve within the given time.
+ * @param {Promise<*>} promise - The promise to wrap with a timeout
+ * @param {number} [time=1] - Timeout duration in milliseconds
+ * @param {string} [message=`Promise Timeout: ${time}ms`] - Custom rejection message
+ * @returns {Promise<*>} A new promise that either resolves with the original promise's value, rejects with original promise's error or timeout error
+ * @throws {TypeError} If input is not a promise or timeout is not a number
+ */
+export function timeout(promise: Promise<any>, time?: number, message?: string): Promise<any>;
+/**
+ * Excutes All promises in parallel and returns an array of results.
+ *
+ * Why:
+ * 1. Promise.allSettled() returns
+ *    * { status: 'fulfilled', value: any } when promise fulfills
+ *    * { status: 'rejected', reason: any } when promise rejects
+ * 2. It's NOT convenient to use Promise.allSettled() to get the results of all promises.
+ *    * the data structure is not consistent when fullfilled or rejected
+ *    * have to check "string" type of status to know sucess or failure
+ * @param {Promise} promises
+ * @returns {Array<{ok: boolean, result: any}>}
+ */
+export function allSettled(promises: Promise<any>): Array<{
+    ok: boolean;
+    result: any;
+}>;
+/**
+   * Execute the task Function, and ensure it returns a Promise.
+   * @param {function} task
+   * @returns {Promise<*>}
+   */
+export function returnValuePromised(task: Function): Promise<any>;
+/**
+   * Fast-Fail mode to execute Tasks(functions) in series (one after another) and returns their results in order.
+   * 1. function are executed one by one
+   * 2. Fast Fail: if any tasks fail, the whole chain is rejected with the first error
+   * 3. if an element is not function, rejects the whole chain with Error(Not Function)
+   * @param {Function[]} promises
+   * @returns {Promise<Array>} Promise that resolves with an array of results in the same order as input tasks
+   */
+export function series(tasks: any): Promise<any[]>;
+/**
+   * AllSettled Mode to execute Tasks(functions) in series (one after another) and returns their results in order.
+   * 1. tasks are executed one by one
+   * 2. Each result is an object with `ok` (boolean) and `result` (resolved value or error).
+   * 3. if a task is not Function, rejects the whole chain with Error(Not Function)
+   * @param {Function[]} tasks
+   * @returns {Promise<Array<{ok: boolean, result: *}>>}
+   */
+export function seriesAllSettled(tasks: Function[]): Promise<Array<{
+    ok: boolean;
+    result: any;
+}>>;
+/**
+   * FastFail Mode to Execute tasks in parallel with a maximum concurrency limit
+   * 1. tasks are executed in parallel with a maximum concurrency limit
+   * 2. rejects whole chain with the first error, when first task fails
+   * @param {Function[]} tasks
+   * @param {number} [maxParallel=5]
+   * @returns {Promise<Array>} Array of resolved values from all promises
+   * @throws {TypeError} If input is not an array of function or maxParallel is not a number
+   */
+export function parallel(tasks: Function[], maxParallel?: number): Promise<any[]>;
+/**
+   * AllSettled Mode to execute tasks in parallel with a maximum concurrency limit
+   * 1. tasks are executed in parallel with a maximum concurrency limit
+   * 2. all tasks will be executed, even some of them failed.
+   * @param {Function[]} tasks
+   * @param {number} [maxParallel=5] - Maximum number of tasks to run in parallel
+   * @returns {Promise<Array>} Array of resolved values from all promises
+   * @throws {TypeError} If input is not an array of function or maxParallel is not a number
+   */
+export function parallelAllSettled(tasks: Function[], maxParallel?: number): Promise<any[]>;

package/types/string-utils.d.ts

@@ -0,0 +1,152 @@
+/**
+  * Checks if a string is null, undefined, or length is 0.
+  * @param {string} str
+  * @returns {boolean}
+  * @throws {Error} If `str` is not null or undefined, and not a string.
+  */
+export function isEmpty(str: string): boolean;
+/**
+ * Asserts that the given string is not empty.
+ * @param {string} str - The string to check.
+ * @throws {Error} Throws an error if the string is empty.
+ */
+export function assertNotEmpty(str: string): void;
+/**
+ * Checks if a string is null, undefined, or consists only of whitespace.
+ * @param {string} str - The string to check.
+ * @returns {boolean} True if the string is blank, false otherwise.
+ * @throws {Error} If `str` is not null or undefined, and not a string.
+ */
+export function isBlank(str: string): boolean;
+/**
+ * Asserts that the given string is not blank.
+ * @param {string} str - The string to check.
+ * @throws {Error} Throws an error if the string is blank.
+ */
+export function assertNotBlank(str: string): void;
+/**
+ * Capitalizes the first character of a string.
+ * @param {string} str - The string to capitalize.
+ * @returns {string} The capitalized string or original if unchanged.
+ */
+export function capitalize(str: string): string;
+/**
+ * Converts the first character of a string to lowercase.
+ * If the string is null or empty, returns it unchanged.
+ * @param {string} str - The input string to decapitalize.
+ * @returns {string} The decapitalized string or original if unchanged.
+ */
+export function decapitalize(str: string): string;
+/**
+ * Splits a string into chunks of fixed length, padding the last chunk if needed.
+ * 1. if str is empty, returns an empty array "[]"
+ * 2. if length is less than string length, returns an array with the string padded with "padding" as the only element
+ * 3. the last chunk is padded with "padding" if needed
+ * @param {string} str - The string to split.
+ * @param {number} length - The desired length of each chunk.
+ * @param {string} [padding=' '] - The padding character for the last chunk.
+ * @returns {string[]} An array of string chunks with fixed length.
+ * @throws {Error} If `str` is not a string or `length` is not a number.
+ */
+export function splitWithFixedLength(str: string, length: number, padding?: string): string[];
+/**
+ * Splits a string into chunks using the specified markers.
+ * 1. If no markers are provided, defaults to comma (',').
+ * 2. null/undefined values are ignored
+ * 3. empty array "[]" returned, if string does not include any markers
+ * @param {string} str - The string to split.
+ * @param {...string} markers - The markers to split the string by.
+ * @returns {Array<string>} An array of string chunks.
+ * @throws {Error} If the input is not a string.
+ */
+export function split(str: string, ...markers: string[]): Array<string>;
+/**
+ * Finds all positions of markers in a string.
+ * 1. use loop to iterate over markers
+ * 2. use sting.indexOf to find position of each marker
+ * @param {string} str - The input string to search in.
+ * @param {...string} markers - The markers to search for.
+ * @returns {Array<{marker: string, index: number}>} Array of objects containing marker and its index.
+ * @throws {Error} If `str` is not a string or no markers are provided.
+ */
+export function findMarkerPositions(str: string, ...markers: string[]): Array<{
+    marker: string;
+    index: number;
+}>;
+/**
+ * Finds all positions of markers in a string.
+ * 1. Finds all positions of markers in a string using regular expressions.
+ * 2. Each marker is included as a separate capture group in a single regex.
+ * @param {string} str - The input string to search in.
+ * @param {...string} markers - The markers to search for.
+ * @returns {Array<{marker: string, index: number}>} Array of objects containing marker and its index.
+ * @throws {Error} If `str` is not a string or no markers are provided.
+ */
+export function findMarkerPositionsRegex(str: string, ...markers: string[]): Array<{
+    marker: string;
+    index: number;
+}>;
+/**
+ * Returns the substring before the first occurrence of a marker.
+ * @param {string} str - The input string to search in.
+ * @param {string} marker - The string to search for.
+ * @returns {string | undefined} The substring before the marker, or undefined if marker not found.
+ * @throws {Error} If either input is not a string.
+ */
+export function substringBefore(str: string, marker: string): string | undefined;
+/**
+ * Returns the substring before the last occurrence of a marker.
+ * @param {string} str
+ * @param {string} marker
+ * @returns {string | undefined}The substring before the last marker, or undefined if marker not found.
+ * @throws {Error} If either input is not a string.
+ */
+export function substringBeforeLast(str: string, marker: string): string | undefined;
+/**
+ * Returns the substring after the first occurrence of the specified marker.
+ * If the marker is not found, returns an empty string.
+ *
+ * @param {string} str - The string to search in
+ * @param {string} marker - The string to search for
+ * @returns {string | undefined} The substring after the marker, or undefined if not found
+ */
+export function substringAfter(str: string, marker: string): string | undefined;
+/**
+ * Returns the substring after the last occurrence of a marker in a string.
+ * @param {string} str - The input string to search in.
+ * @param {string} marker - The marker to search for.
+ * @returns {string|undefined} The substring after the last marker, or undefined if marker not found.
+ */
+export function substringAfterLast(str: string, marker: string): string | undefined;
+/**
+ * Extracts the substring between the specified start and end markers in a string.
+ * 1. NOT Greedy, substring between the FIRST startMarker and FIRST endMarker
+ * 2. undefined returned, if Not Found neither startMarker nor endMarker
+ * @param {string} str - The input string to search within
+ * @param {string} startMarker - The starting marker string
+ * @param {string} endMarker - The ending marker string
+ * @returns {string|undefined} The substring between markers, or undefined if markers not found
+ * @throws {Error} If any input is not a string.
+ */
+export function substringBetween(str: string, startMarker: string, endMarker: string): string | undefined;
+/**
+ * Extracts the substring between the first occurrence of `startMarker` and the last occurrence of `endMarker` in `str`.
+ * 1. Greedy, substring between the FIRST startMarker and LAST endMarker
+ * 2. undefined returned, if Not Found neither startMarker nor endMarker
+ * @param {string} str - The input string to search.
+ * @param {string} startMarker - The starting marker.
+ * @param {string} endMarker - The ending marker.
+ * @returns {string|undefined} The substring between markers, or `undefined` if markers are not found.
+ * @throws {Error} If any input is not a string.
+ */
+export function substringBetweenGreedy(str: string, startMarker: string, endMarker: string): string | undefined;
+/**
+ * Extracts all substrings between specified start and end markers in a string.
+ * 1. NOT Greedy
+ * @param {string} str - The input string to search within
+ * @param {string} startMarker - The substring marking the start of extraction
+ * @param {string} endMarker - The substring marking the end of extraction
+ * @returns {string[]} Array of all found substrings between markers, empty array "[]" returned if not found
+ * @throws {Error} If any input is not a string
+ */
+export function substringsBetween(str: string, startMarker: string, endMarker: string): string[];