@creejs/commons-lang 1.0.1

package/lib/string-utils.js

@@ -0,0 +1,428 @@
+'use strict'
+
+/**
+ * @module StringUtils
+ * @description Utility functions for string manipulation, validation, and transformation.
+ */
+
+// 3rd
+
+// internal
+
+// owned
+const { assertString, assertNumber } = require('./type-assert')
+
+/**
+  * 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
+}
+const StringUtils = {
+  isEmpty,
+  assertNotEmpty,
+  isBlank,
+  assertNotBlank,
+  capitalize,
+  decapitalize,
+  splitWithFixedLength,
+  split,
+  findMarkerPositions,
+  findMarkerPositionsRegex,
+  substringBefore,
+  substringBeforeLast,
+  substringAfter,
+  substringAfterLast,
+  substringBetween,
+  substringBetweenGreedy,
+  substringsBetween
+}
+
+module.exports = StringUtils

package/lib/type-assert.js

@@ -0,0 +1,253 @@
+'use strict'
+/**
+ * @module TypeAssert
+ * @description Type assertion utility functions for validating data types and throwing errors for invalid types.
+ */
+
+// 3rd
+
+// internal
+
+// owned
+const { isString, isNumber, isBoolean, isObject, isPlainObject, isPromise, isSymbol, isFunction, isInstance, isNil, isNull, isUndefined, isPositive, isNegative } = require('./type-utils')
+
+/**
+   * 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(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)}`)
+  }
+}
+const TypeAssert = {
+  assertNumber,
+  assertPositive,
+  assertNegative,
+  assertBoolean,
+  assertObject,
+  assertPlainObject,
+  assertSymbol,
+  assertFunction,
+  assertInstance,
+  assertPromise,
+  assertNil,
+  assertNotNil,
+  assertNull,
+  assertNotNull,
+  assertUndefined,
+  assertString,
+  assertArray,
+  assertStringOrSymbol
+}
+
+module.exports = TypeAssert