@creejs/commons-lang 1.0.1

package/README.md

@@ -0,0 +1,2 @@
+# commons-lang
+Commons Utils About Language

package/index.js

@@ -0,0 +1,2 @@
+'use strict'
+module.exports = require('./lib')

package/lib/exec-utils.js

@@ -0,0 +1,58 @@
+'use strict'
+/**
+ * @module ExecUtils
+ * @description Utils about how to execute task functions.
+ */
+
+// @ts-ignore
+const { assertFunction, assertArray } = require('./type-assert')
+const { isPromise } = require('./type-utils')
+
+/**
+   * 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.
+   */
+function quiet (task) {
+  assertFunction(task)
+  try {
+    const rtnVal = task()
+    if (isPromise(rtnVal)) {
+      return rtnVal.catch(() => {
+        // do nothing
+      })
+    }
+    return rtnVal
+  } catch (e) {
+    // do nothing
+  }
+}
+
+/**
+   * 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.
+   */
+function quietKeepError (task, errorKeeper) {
+  assertFunction(task)
+  assertArray(errorKeeper)
+  try {
+    const rtnVal = task()
+    if (isPromise(rtnVal)) {
+      // @ts-ignore
+      return rtnVal.catch(e => errorKeeper.push(e))
+    }
+    return rtnVal
+  } catch (e) {
+    // @ts-ignore
+    errorKeeper.push(e)
+  }
+}
+const ExecUtils = {
+  quiet,
+  quietKeepError
+}
+
+module.exports = ExecUtils

package/lib/index.js

@@ -0,0 +1,26 @@
+'use strict'
+
+/**
+ * @module Lang
+ * @description Core language utilities for type checking, string manipulation, and common operations.
+ */
+
+const LangUtils = require('./lang-utils')
+const StringUtils = require('./string-utils')
+const TypeUtils = require('./type-utils')
+const TypeAssert = require('./type-assert')
+const ExecUtils = require('./exec-utils')
+const PromiseUtils = require('./promise-utils')
+
+module.exports = {
+  LangUtils,
+  StringUtils,
+  TypeUtils,
+  TypeAssert,
+  ExecUtils,
+  PromiseUtils,
+  Lang: LangUtils,
+  String: StringUtils,
+  Type: TypeUtils,
+  Exec: ExecUtils
+}

package/lib/lang-utils.js

@@ -0,0 +1,110 @@
+'use strict'
+
+/**
+ * @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.
+ */
+function constructorName (value) {
+  return value?.constructor?.name
+}
+
+/**
+ * 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
+ */
+function defaults (target, ...sources) {
+  if (target == null) {
+    throw new TypeError('"target" must not be null or undefined')
+  }
+  for (const source of sources) {
+    if (source == null) {
+      continue
+    }
+    for (const key in source) {
+      if (target[key] === undefined) {
+        target[key] = source[key]
+      }
+    }
+  }
+  return target
+}
+
+/**
+ * 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
+ */
+function extend (target, ...sources) {
+  if (target == null) {
+    throw new TypeError('"target" must not be null or undefined')
+  }
+  for (const source of sources) {
+    if (source == null) {
+      continue
+    }
+    for (const key in source) {
+      target[key] = source[key]
+    }
+  }
+  return target
+}
+
+/**
+ * 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
+ */
+function equals (value1, value2) {
+  if (value1 === value2) {
+    return true
+  }
+  if (typeof value1?.equals === 'function') {
+    return value1.equals(value2)
+  }
+  if (typeof value2?.equals === 'function') {
+    return value2.equals(value1)
+  }
+  return false
+}
+
+/**
+ * Check if the current environment is a browser
+ * @returns {boolean}
+ */
+function isBrowser () {
+  return typeof window !== 'undefined' && typeof document !== 'undefined'
+}
+
+/**
+ * Check if the current environment is a nodejs
+ * @returns {boolean}
+ */
+function isNode () {
+  return !isBrowser()
+}
+
+const LangUtils = {
+  constructorName,
+  defaults,
+  extend,
+  extends: extend,
+  equals,
+  isBrowser,
+  isNode
+}
+
+module.exports = LangUtils

package/lib/promise-utils.js

@@ -0,0 +1,317 @@
+// @ts-nocheck
+'use strict'
+
+/**
+ * @module PromiseUtils
+ * @description Promise utility functions for enhanced promise handling, including timeout, delay, parallel execution, and series execution.
+ */
+
+const { assertNumber, assertPromise, assertArray, assertFunction } = require('./type-assert')
+const { isPromise, isNumber } = require('./type-utils')
+/**
+ * Creates a "Deferred" Object with Timeout support
+ * 1. timeout=-1, it means no timeout check
+ * @param {number} [timeout=-1] - Timeout duration in milliseconds
+ * @param {string} [timeoutMessage]
+ * @returns {{promise: Promise<*>, reject: function, resolve: function}}
+ */
+function defer (timeout = -1, timeoutMessage) {
+  assertNumber(timeout)
+  const rtnVal = {}
+
+  let timerHandler
+  if (timeout >= 0) {
+    rtnVal.timerHandler = timerHandler = setTimeout(() => {
+      clearTimeout(timerHandler) // must clear it
+      rtnVal.timerCleared = true // easy to check in test case
+      rtnVal.reject(new Error(timeoutMessage ?? `Promise Timeout: ${timeout}ms`))
+    }, timeout)
+    rtnVal.timerHandler = timerHandler
+  }
+
+  rtnVal.promise = new Promise((resolve, reject) => {
+    rtnVal.resolve = (...args) => {
+      if (timerHandler != null) {
+        clearTimeout(timerHandler) // must clear it
+        rtnVal.timerCleared = true // easy to check in test case
+      }
+      rtnVal.resolved = true
+      resolve(...args)
+    }
+
+    rtnVal.reject = (err) => {
+      if (timerHandler != null) {
+        clearTimeout(timerHandler) // must clear it
+        rtnVal.timerCleared = true // easy to check in test case
+      }
+      rtnVal.rejected = true
+      reject(err)
+    }
+  })
+  rtnVal.promise.cancel = () => {
+    if (timerHandler != null) {
+      clearTimeout(timerHandler) // must clear it
+      rtnVal.timerCleared = true // easy to check in test case
+    }
+    rtnVal.rejected = true // easy to check in test case
+    rtnVal.canceled = rtnVal.promise.canceled = true // easy to check in test case
+    rtnVal.reject(new Error('Cancelled'))
+  }
+  return rtnVal
+}
+
+/**
+ * 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
+ */
+function timeout (promise, time, message) {
+  assertPromise(promise)
+
+  time = time ?? 1
+  assertNumber(time)
+
+  const deferred = PromiseUtils.defer(time, message)
+  const startTs = Date.now()
+  promise.then((...args) => { // original promise settled, but timeout
+    const elapsed = Date.now() - startTs
+    if (elapsed <= time) {
+      deferred.resolve(...args)
+    } else {
+      deferred.reject(new Error(message ?? `Promise Timeout: ${time}ms`))
+    }
+  }).catch((err) => {
+    // prevent double reject
+    !deferred.resolved && !deferred.rejected && deferred.reject(err)
+  })
+  return deferred.promise
+}
+
+/**
+ * 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}>}
+ */
+async function allSettled (promises) {
+  assertArray(promises)
+  const results = await Promise.allSettled(promises)
+  const rtnVal = []
+  for (const result of results) {
+    if (result.status === 'fulfilled') {
+      rtnVal.push({ ok: true, result: result.value })
+    }
+    if (result.status === 'rejected') {
+      rtnVal.push({ ok: false, result: result.reason })
+    }
+  }
+  return rtnVal
+}
+
+/**
+   * Execute the task Function, and ensure it returns a Promise.
+   * @param {function} task
+   * @returns {Promise<*>}
+   */
+function returnValuePromised (task) {
+  try {
+    const taskRtnVal = task()
+    if (isPromise(taskRtnVal)) {
+      return taskRtnVal
+    }
+    return Promise.resolve(taskRtnVal)
+  } catch (e) {
+    return Promise.reject(e)
+  }
+}
+
+/**
+   * Delays a promise by a specified time.
+   * 1. delay(), wait 1ms
+   * 2. delay(1000), wait 1000ms
+   * 3. delay(promise), after promise settled, wait 1000ms
+   * 4. delay(promise, 2000), after promise settled, wait 2000ms
+   *
+   * @param {Promise<*>|number|undefined} [promise] - The input promise to delay
+   * @param {number|undefined} [ms] - Minimum delay in milliseconds (default: 1)
+   * @returns {Promise} A new promise that settles after the delay period
+   */
+function delay (promise, ms) {
+  if (isNumber(promise)) {
+    ms = promise
+    promise = Promise.resolve()
+  } else if (promise == null && ms == null) {
+    ms = 1
+    promise = Promise.resolve()
+  }
+  promise != null && assertPromise(promise)
+  ms = ms ?? 1000
+  assertNumber(ms)
+  const deferred = PromiseUtils.defer()
+  const startTs = Date.now()
+  promise
+    .then((...args) => {
+      const escaped = Date.now() - startTs
+      if (escaped < ms) {
+        setTimeout(() => deferred.resolve(...args), ms - escaped)
+      } else {
+        deferred.resolve(...args)
+      }
+    })
+    .catch((err) => {
+      const escaped = Date.now() - startTs
+      if (escaped < ms) {
+        setTimeout(() => deferred.reject(err), ms - escaped)
+      } else {
+        deferred.reject(err)
+      }
+    })
+  return deferred.promise
+}
+
+/**
+   * 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
+   */
+async function series (tasks) {
+  assertArray(tasks)
+  const results = []
+  for (const task of tasks) {
+    assertFunction(task)
+    results.push(await task())
+  }
+  return results
+}
+
+/**
+   * 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: *}>>}
+   */
+async function seriesAllSettled (tasks) {
+  assertArray(tasks)
+  const results = []
+  for (const task of tasks) {
+    assertFunction(task)
+    try {
+      results.push({ ok: true, result: await task() })
+    } catch (err) {
+      results.push({ ok: false, result: err })
+    }
+  }
+  return results
+}
+
+/**
+   * 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
+   */
+async function parallel (tasks, maxParallel = 5) {
+  assertArray(tasks)
+  assertNumber(maxParallel)
+  if (maxParallel <= 0) {
+    throw new Error(`Invalid maxParallel: ${maxParallel}, should > 0`)
+  }
+  tasks.forEach((task) => assertFunction(task))
+  const rtnVal = []
+  // once for all, run all tasks
+  if (tasks.length <= maxParallel) {
+    const resultsForBatch = await Promise.all(tasks.map(task => PromiseUtils.returnValuePromised(task)))
+    rtnVal.push(...resultsForBatch)
+    return rtnVal
+  }
+  // run group by MaxParallel
+  const tasksToRun = []
+  for (const task of tasks) {
+    assertFunction(task)
+    tasksToRun.push(task)
+    if (tasksToRun.length >= maxParallel) {
+      const resultsForBatch = await Promise.all(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
+      rtnVal.push(...resultsForBatch)
+      tasksToRun.length = 0
+    }
+  }
+  // Run all rested
+  if (tasksToRun.length > 0 && tasksToRun.length < maxParallel) {
+    const resultsForBatch = await Promise.all(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
+    rtnVal.push(...resultsForBatch)
+  }
+  return rtnVal
+}
+
+/**
+   * 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
+   */
+async function parallelAllSettled (tasks, maxParallel = 5) {
+  assertArray(tasks)
+  assertNumber(maxParallel)
+  if (maxParallel <= 0) {
+    throw new Error(`Invalid maxParallel: ${maxParallel}, should > 0`)
+  }
+  tasks.forEach((task) => assertFunction(task))
+  const rtnVal = []
+  // once for all, run all promises
+  if (tasks.length <= maxParallel) {
+    const resultsForBatch = await PromiseUtils.allSettled(tasks.map(task => PromiseUtils.returnValuePromised(task)))
+    rtnVal.push(...resultsForBatch)
+    return rtnVal
+  }
+  // run group by MaxParallel
+  const tasksToRun = []
+  for (const task of tasks) {
+    assertFunction(task)
+    tasksToRun.push(task)
+    if (tasksToRun.length >= maxParallel) {
+      const resultsForBatch = await PromiseUtils.allSettled(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
+      rtnVal.push(...resultsForBatch)
+      tasksToRun.length = 0
+    }
+  }
+  // Run all rested
+  if (tasksToRun.length > 0 && tasksToRun.length < maxParallel) {
+    const resultsForBatch = await PromiseUtils.allSettled(tasksToRun.map(task => PromiseUtils.returnValuePromised(task)))
+    rtnVal.push(...resultsForBatch)
+  }
+  return rtnVal
+}
+const PromiseUtils = {
+  defer,
+  delay,
+  timeout,
+  allSettled,
+  returnValuePromised,
+  series,
+  seriesAllSettled,
+  parallel,
+  parallelAllSettled
+}
+
+module.exports = PromiseUtils