@creejs/commons-lang 2.0.0 → 2.0.2

package/dist/esm/index-dev.js

@@ -0,0 +1,1532 @@
+/**
+ * @module LangUtils
+ * @description Language utility functions
+ */
+
+var LangUtils = {
+  constructorName,
+  defaults,
+  extend,
+  extends: extend,
+  equals,
+  isBrowser,
+  isNode
+};
+
+/**
+ * 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()
+}
+
+/**
+ * @module TypeUtils
+ * @description Utility functions for type checking and validation.
+ */
+var TypeUtils = {
+  isArray,
+  isBoolean,
+  isBuffer,
+  isFunction,
+  isInstance,
+  isIterable,
+  isDate,
+  isError,
+  isMap,
+  isWeakMap,
+  isNumber,
+  isPositive,
+  isNegative,
+  isNil,
+  isNullOrUndefined,
+  isNull,
+  isUndefined,
+  isPlainObject: isPlainObject$1,
+  isObject,
+  isPromise,
+  isRegExp,
+  isSet,
+  isWeakSet,
+  isStream,
+  isString,
+  isSymbol,
+  isPrimitive
+};
+/**
+   * 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' && !isPlainObject$1(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$1 (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'
+}
+
+// 3rd
+// internal
+// owned
+/**
+ * @module TypeAssert
+ * @description Type assertion utility functions for validating data types and throwing errors for invalid types.
+ */
+var TypeAssert = {
+  assertNumber,
+  assertPositive,
+  assertNegative,
+  assertBoolean,
+  assertObject,
+  assertPlainObject,
+  assertSymbol,
+  assertFunction,
+  assertInstance,
+  assertPromise,
+  assertNil,
+  assertNotNil,
+  assertNull,
+  assertNotNull,
+  assertUndefined,
+  assertString,
+  assertArray,
+  assertStringOrSymbol
+};
+/**
+   * if value is not Array, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertArray (value, paramName) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${paramName ? paramName + '' : ' '}Not Array: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a string, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertString (value, paramName) {
+  if (!isString(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not String: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a Number, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertNumber (value, paramName) {
+  if (!isNumber(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Number: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+
+/**
+ * Asserts that a value is a positive number.
+ * @param {number} value - The value to check.
+ * @param {string} [paramName] - Optional name of the parameter for error message.
+ * @throws {Error} If the value is not a number or is less than or equal to zero.
+ */
+function assertPositive (value, paramName) {
+  if (!isPositive(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Positive: ${value}`)
+  }
+}
+
+/**
+ * Asserts that a value is a Negative number.
+ * @param {number} value - The value to check.
+ * @param {string} [paramName] - Optional name of the parameter for error message.
+ * @throws {Error} If the value is not a number or is less than or equal to zero.
+ */
+function assertNegative (value, paramName) {
+  if (!isNegative(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Negative: ${value}`)
+  }
+}
+
+/**
+   * if value is not a string, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertBoolean (value, paramName) {
+  if (!isBoolean(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Boolean: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a Object, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertObject (value, paramName) {
+  if (!isObject(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Object: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a PlainObject, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertPlainObject (value, paramName) {
+  if (!isPlainObject$1(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not PlainObject: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a Symbol, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check@param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertSymbol (value, paramName) {
+  if (!isSymbol(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Symbol: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a Function, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertFunction (value, paramName) {
+  if (!isFunction(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Function: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a Class instance, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertInstance (value, paramName) {
+  if (!isInstance(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Class Instance: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a string, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertPromise (value, paramName) {
+  if (!isPromise(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Promise: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+/**
+   * if value is not a Null or Undefined, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertNil (value, paramName) {
+  if (!isNil(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Neither Null nor Undefined: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+
+/**
+ * Asserts that the given value is not nil.
+ * @param {*} value - The value to check
+ * @param {string} [paramName] - The name of the parameter to check
+ * @throws {Error} Throws an error if the value is nil
+ */
+function assertNotNil (value, paramName) {
+  if (isNil(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Should Not Nil`)
+  }
+}
+
+/**
+   * if value is not a Null, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertNull (value, paramName) {
+  if (!isNull(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Null: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+
+/**
+ * Asserts that the given value is not null.
+ * @param {*} value - The value to check
+ * @param {string} [paramName] - The name of the parameter to check
+ * @throws {Error} Throws an error if the value is null
+ */
+function assertNotNull (value, paramName) {
+  if (isNull(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Should Not Null`)
+  }
+}
+/**
+   * if value is not a Undefined, throw error
+   * @param {*} value
+   * @param {string} [paramName] - The name of the parameter to check
+   * @returns {void}
+   * @throws {Error}
+   */
+function assertUndefined (value, paramName) {
+  if (!isUndefined(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not Undefined: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+
+/**
+ * Asserts that the given value is either a string or a symbol.
+ * @param {*} value - The value to check.
+ * @param {string} [paramName] - Optional parameter name for error message.
+ * @throws {Error} Throws an error if the value is not a string or symbol.
+ */
+function assertStringOrSymbol (value, paramName) {
+  if (!isString(value) && !isSymbol(value)) {
+    throw new Error(`${paramName ? '"' + paramName + '" ' : ' '}Not String or Symbol: type=${typeof value} value=${JSON.stringify(value)}`)
+  }
+}
+
+// 3rd
+// internal
+// owned
+
+/**
+ * @module StringUtils
+ * @description Utility functions for string manipulation, validation, and transformation.
+ */
+var StringUtils = {
+  isEmpty,
+  assertNotEmpty,
+  isBlank,
+  assertNotBlank,
+  capitalize,
+  decapitalize,
+  splitWithFixedLength,
+  split,
+  findMarkerPositions,
+  findMarkerPositionsRegex,
+  substringBefore,
+  substringBeforeLast,
+  substringAfter,
+  substringAfterLast,
+  substringBetween,
+  substringBetweenGreedy,
+  substringsBetween
+};
+
+/**
+  * 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.
+  */
+function isEmpty (str) {
+  if (str == null) {
+    return true
+  }
+  assertString(str);
+  return str.length === 0
+}
+
+/**
+ * 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.
+ */
+function assertNotEmpty (str) {
+  if (isEmpty(str)) {
+    throw new Error(`Empty String: ${str}`)
+  }
+}
+
+/**
+ * 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.
+ */
+function isBlank (str) {
+  if (str == null) {
+    return true
+  }
+  assertString(str);
+  return str.trim().length === 0
+}
+
+/**
+ * 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.
+ */
+function assertNotBlank (str) {
+  if (isBlank(str)) {
+    throw new Error(`Blank String: ${str}`)
+  }
+}
+
+/**
+ * Capitalizes the first character of a string.
+ * @param {string} str - The string to capitalize.
+ * @returns {string} The capitalized string or original if unchanged.
+ */
+function capitalize (str) {
+  assertString(str);
+  if (str.length === 0) {
+    return str
+  }
+  const char0 = str.charAt(0);
+  const upperChar = char0.toUpperCase();
+  return char0 === upperChar ? str : upperChar + str.slice(1)
+}
+
+/**
+ * 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.
+ */
+function decapitalize (str) {
+  assertString(str);
+  if (str.length === 0) {
+    return str
+  }
+  const char0 = str.charAt(0);
+  const lowerChar = char0.toLowerCase();
+  return char0 === lowerChar ? str : lowerChar + str.slice(1)
+}
+
+/**
+ * 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.
+ */
+function splitWithFixedLength (str, length, padding = ' ') {
+  assertString(str);
+  assertNumber(length);
+  assertString(padding);
+  if (str.length === 0) {
+    return []
+  }
+  if (length <= 0) {
+    throw new Error('length muse >=0')
+  }
+  if (str.length < length) {
+    return [str.padEnd(length, padding)]
+  }
+  const chunks = [];
+  for (let i = 0; i < str.length; i += length) {
+    const splitted = str.substring(i, i + length);
+    chunks.push(splitted.padEnd(length, padding));
+  }
+  return chunks
+}
+
+/**
+ * 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.
+ */
+function split (str, ...markers) {
+  assertString(str);
+  const strLength = str.length;
+  if (strLength === 0) {
+    return []
+  }
+  const workingMarkers = [...markers];
+  if (markers.length === 0) {
+    markers.push(',');
+  }
+  const markerPostionPairs = findMarkerPositionsRegex(str, ...workingMarkers);
+  if (markerPostionPairs.length === 0) {
+    return []
+  }
+  const chunks = [];
+  let chunk = '';
+  let startIndex = 0;
+  for (const { marker, index: endIndex } of markerPostionPairs) {
+    chunk = str.substring(startIndex, endIndex);
+    chunks.push(chunk);
+    startIndex = endIndex + marker.length;
+  }
+  // add rested into chunks
+  chunk = str.substring(startIndex);
+  chunks.push(chunk);
+  return chunks
+}
+
+/**
+ * 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.
+ */
+function findMarkerPositions (str, ...markers) {
+  assertString(str);
+  if (markers.length === 0) {
+    throw new Error('At least one marker must be provided')
+  }
+
+  const positions = [];
+  for (const marker of new Set(markers)) { // filter duplicated markers
+    if (isEmpty(marker)) { // 'abc'.indexOf('') === 0
+      continue
+    }
+    assertString(marker);
+    let index = str.indexOf(marker);
+    while (index !== -1) {
+      positions.push({ marker, index });
+      index = str.indexOf(marker, index + marker.length);
+    }
+  }
+  // Sort positions by index in ascending order
+  positions.sort((p1, p2) => p1.index - p2.index);
+  return positions
+}
+
+/**
+ * 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.
+ */
+function findMarkerPositionsRegex (str, ...markers) {
+  assertString(str);
+  if (markers.length === 0) {
+    throw new Error('At least one marker must be provided')
+  }
+
+  // filter duplicated, empty markers
+  // Escape special regex characters in markers
+  const escapedMarkers = [...new Set(markers.filter(v => v != null))].map(marker => {
+    assertString(marker);
+    return marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  });
+
+  // Create regex pattern with each marker as a separate capture group
+  // Format: (marker1)|(marker2)|(marker3)...
+  const pattern = new RegExp(escapedMarkers.map(m => `(${m})`).join('|'), 'g');
+
+  const positions = [];
+  let match = null;
+
+  // Find all matches
+  while ((match = pattern.exec(str)) !== null) {
+    // Determine which marker was matched by checking which capture group has a value
+    for (let i = 1; i < match.length; i++) {
+      if (match[i]) {
+        positions.push({
+          marker: markers[i - 1], // Use the original marker, not the escaped version
+          index: match.index
+        });
+        break // Only one group will match for each exec call
+      }
+    }
+
+    // Avoid infinite loops with zero-width matches
+    if (match[0].length === 0) {
+      pattern.lastIndex++;
+    }
+  }
+
+  return positions
+}
+
+/**
+ * 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.
+ */
+function substringBefore (str, marker) {
+  assertString(str);
+  assertString(marker);
+  if (str.length === 0 || marker.length === 0) {
+    return
+  }
+  const index = str.indexOf(marker);
+  if (index === -1) {
+    return undefined
+  }
+  return str.substring(0, index)
+}
+
+/**
+ * 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.
+ */
+function substringBeforeLast (str, marker) {
+  assertString(str);
+  assertString(marker);
+  if (str.length === 0 || marker.length === 0) {
+    return
+  }
+  const index = str.lastIndexOf(marker);
+  if (index === -1) {
+    return
+  }
+  return str.substring(0, index)
+}
+
+/**
+ * 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
+ */
+function substringAfter (str, marker) {
+  assertString(str);
+  assertString(marker);
+  if (str.length === 0 || marker.length === 0) {
+    return
+  }
+  const index = str.indexOf(marker);
+  if (index === -1) {
+    return
+  }
+  return str.substring(index + marker.length)
+}
+
+/**
+ * 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.
+ */
+function substringAfterLast (str, marker) {
+  assertString(str);
+  assertString(marker);
+  if (str.length === 0 || marker.length === 0) {
+    return
+  }
+  const index = str.lastIndexOf(marker);
+  if (index === -1) {
+    return
+  }
+  return str.substring(index + marker.length)
+}
+
+/**
+ * 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.
+ */
+function substringBetween (str, startMarker, endMarker) {
+  assertNotEmpty(str);
+  assertNotEmpty(startMarker);
+  assertNotEmpty(endMarker);
+  const startIndex = str.indexOf(startMarker);
+  if (startIndex === -1) {
+    return
+  }
+  const endIndex = str.indexOf(endMarker, startIndex + startMarker.length);
+  if (endIndex === -1) {
+    return
+  }
+  return str.substring(startIndex + startMarker.length, endIndex)
+}
+
+/**
+ * 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.
+ */
+function substringBetweenGreedy (str, startMarker, endMarker) {
+  assertNotEmpty(str);
+  assertNotEmpty(startMarker);
+  assertNotEmpty(endMarker);
+  const startIndex = str.indexOf(startMarker);
+  if (startIndex === -1) {
+    return
+  }
+  const endIndex = str.lastIndexOf(endMarker);
+  if (endIndex === -1 || endIndex <= startIndex) {
+    return
+  }
+  return str.substring(startIndex + startMarker.length, endIndex)
+}
+
+/**
+ * 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
+ */
+function substringsBetween (str, startMarker, endMarker) {
+  assertNotEmpty(str);
+  assertNotEmpty(startMarker);
+  assertNotEmpty(endMarker);
+  const substrings = [];
+  let start = 0;
+  while (true) {
+    const index = str.indexOf(startMarker, start);
+    if (index === -1) {
+      break
+    }
+    const endIndex = str.indexOf(endMarker, index + startMarker.length);
+    if (endIndex === -1) {
+      break
+    }
+    substrings.push(str.substring(index + startMarker.length, endIndex));
+    start = endIndex + endMarker.length;
+  }
+  return substrings
+}
+
+/**
+ * Executes a task silently, suppressing any errors or rejections.
+ * @param {Function} task - The export 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 export 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);
+  }
+}
+var ExecUtils = {
+  quiet,
+  quietKeepError
+};
+
+// @ts-nocheck
+
+/**
+ * @module PromiseUtils
+ * @description Promise utility functions for enhanced promise handling, including timeout, delay, parallel execution, and series execution.
+ */
+var PromiseUtils = {
+  defer,
+  delay,
+  timeout,
+  allSettled,
+  returnValuePromised,
+  series,
+  seriesAllSettled,
+  parallel,
+  parallelAllSettled
+};
+
+/**
+ * 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 = 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 = 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. export 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 export 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 => 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 => 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 => 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 export 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 allSettled(tasks.map(task => 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 allSettled(tasksToRun.map(task => returnValuePromised(task)));
+      rtnVal.push(...resultsForBatch);
+      tasksToRun.length = 0;
+    }
+  }
+  // Run all rested
+  if (tasksToRun.length > 0 && tasksToRun.length < maxParallel) {
+    const resultsForBatch = await allSettled(tasksToRun.map(task => returnValuePromised(task)));
+    rtnVal.push(...resultsForBatch);
+  }
+  return rtnVal
+}
+
+// owned
+
+const { isPlainObject } = TypeUtils;
+
+/**
+ * @module ClassProxyUtils
+ */
+var ClassProxyUtils = {
+  proxy: proxy$1,
+  newProxyInstance
+};
+
+/**
+ * Creates a Proxy Class for given class.
+ * @template {object} T
+ * @param {Function} cls - The class to proxycls - The class to proxy
+ * @param {ProxyHandler<T>} [propertyHandler = {}] - Proxy Property Handler
+ * @param {boolean} [sealed=true] - Whether to seal the instance
+ * @returns {Function} A proxied classA proxied instance of the class
+ */
+function proxy$1 (cls, propertyHandler, sealed = true) {
+  if (typeof cls !== 'function') {
+    throw new TypeError(`Not Class: type=${typeof cls}, value=${JSON.stringify(cls)}`)
+  }
+  if (propertyHandler != null) {
+    if (!isPlainObject(propertyHandler)) {
+      throw new TypeError(`Not PropertyHandler: type=${typeof propertyHandler}, value=${JSON.stringify(propertyHandler)}`)
+    }
+    const { get, set } = propertyHandler;
+    if (get != null && typeof get !== 'function') {
+      throw new TypeError(`Not PropertyHandler.get: type=${typeof get}, value=${JSON.stringify(get)}`)
+    }
+    if (set != null && typeof set !== 'function') {
+      throw new TypeError(`Not PropertyHandler.set: type=${typeof set}, value=${JSON.stringify(set)}`)
+    }
+  }
+  const construcHandler = {
+    /**
+     * Creates a proxied instance of a class, optionally sealing it.
+     * @param {Function} constructor - The class constructor to instantiate.
+     * @param {any[]} args - Arguments to pass to the constructor.
+     * @param {Function} [newTarget] - The constructor that was originally called by `new`.
+     * @returns {Proxy} A proxied instance of the constructed class.
+     */
+    construct (constructor, args, newTarget) {
+      const clsInstance = Reflect.construct(constructor, args);
+      return new Proxy(sealed ? Object.preventExtensions(clsInstance) : clsInstance, propertyHandler ?? {})
+    }
+  };
+  return new Proxy(cls, construcHandler)
+}
+
+/**
+ * Creates a proxied instance of a class with custom property handling.
+ * @template {object} T
+ * @param {Function} cls - The class to proxy
+ * @param {any[]} args - Arguments to pass to the constructor
+ * @param {ProxyHandler<T>} propertyHandler - Handler for property access/mutation
+ * @param {boolean} [sealed=true] - Whether the proxy should be sealed
+ * @returns {T} Proxied class instance
+ */
+function newProxyInstance (cls, args, propertyHandler, sealed = true) {
+  const proxyCls = proxy$1(cls, propertyHandler, sealed);
+  return Reflect.construct(proxyCls, args ?? [])
+}
+
+/**
+ * @module InstanceProxyUtils
+ */
+
+/**
+ * Creates a proxy wrapper around an object instance with optional property handler.
+ * @template {object} T
+ * @param {T} instance - The target object to proxy
+ * @param {ProxyHandler<T>} [propertyHandler] - Optional proxy handler for property access
+ * @param {boolean} [sealed=true] - Whether to prevent extensions on the target object
+ * @returns {T} The proxied object instance
+ * @throws {TypeError} If instance is not an object
+ */
+function proxy (instance, propertyHandler, sealed = true) {
+  if (isNil(instance) || !isObject(instance) || isArray(instance)) {
+    throw new TypeError(`Not Object: type=${typeof instance}, value=${JSON.stringify(instance)}`)
+  }
+  return new Proxy(sealed ? Object.preventExtensions(instance) : instance, propertyHandler ?? {})
+}
+
+var InstanceProxyUtils = {
+  proxy
+};
+
+/**
+ * @module Lang
+ * @description Core language utilities for type checking, string manipulation, and common operations.
+ */
+
+
+var index = {
+  LangUtils,
+  StringUtils,
+  TypeUtils,
+  TypeAssert,
+  ExecUtils,
+  PromiseUtils,
+  Lang: LangUtils,
+  Type: TypeUtils,
+  Exec: ExecUtils,
+  ClassProxyUtils,
+  InstanceProxyUtils
+};
+
+export { ClassProxyUtils, ExecUtils as Exec, ExecUtils, InstanceProxyUtils, LangUtils as Lang, LangUtils, PromiseUtils, StringUtils, TypeUtils as Type, TypeAssert, TypeUtils, index as default };
+//# sourceMappingURL=index-dev.js.map