@questwork/q-utilities 0.1.22 → 0.1.29

package/.github/workflows/publish.yml

@@ -4,12 +4,13 @@ on:
     tags:
       - 'v*'
   workflow_dispatch:
+
 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: write
+      id-token: write  # OIDC
     # environment: production
     steps:
       - uses: actions/checkout@v4
@@ -39,8 +40,21 @@ jobs:
             pnpm run build
           fi
 
+      # - name: Publish to npm
+      #   # if: steps.version-check.outputs.should_publish == 'true'
+      #   run: pnpm publish --no-git-checks --access public
+      #   env:
+      #     NODE_AUTH_TOKEN: ${{ secrets.QW_NPM_TOKEN }}
+          
+      - name: Update npm
+        run: |
+          NPM_VERSION=$(npm -v)
+          echo "Current npm version: $NPM_VERSION"
+          if ! npx semver -r ">=11.5.1" "$NPM_VERSION"; then
+            echo "npm version $NPM_VERSION is too old. Installing latest npm..."
+            npm install -g npm@latest
+            echo "Updated npm version: $(npm -v)"
+          fi
+
       - name: Publish to npm
-        # if: steps.version-check.outputs.should_publish == 'true'
-        run: pnpm publish --no-git-checks --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.QW_NPM_TOKEN }}
+        run: npm publish --no-git-checks --access public

package/dist/index.min.cjs

@@ -522,7 +522,147 @@ class AwsStsS3Client {
 
 
 
+;// ./lib/helpers/objectHelper/objectHelper.js
+const objectHelper = {
+  get(obj, path) {
+    const parts = path.split('.')
+    return parts.reduce((acc, part) => {
+      if (part.endsWith('[]')) {
+        // 处理数组遍历
+        const key = part.slice(0, -2) // 去掉 '[]' 得到属性名
+        if (Array.isArray(acc[key])) {
+          return acc[key] // 返回整个数组
+        }
+        return [] // 如果不是数组，返回空数组
+      }
+      if (part.includes('[') && part.includes(']')) {
+        // 处理数组索引
+        const arrayMatch = part.match(/(\w+)\[(\d+)\]/)
+        if (arrayMatch) {
+          const key = arrayMatch[1]
+          const index = arrayMatch[2]
+          return acc && acc[key] && acc[key][index]
+        }
+      } else if (acc && Array.isArray(acc)) {
+        // 如果当前值是数组，提取每个对象的指定属性
+        return acc.map((item) => item[part])
+      } else {
+        // 处理普通属性
+        return acc && acc[part]
+      }
+    }, obj)
+  },
+  isPlainObject,
+  merge,
+  set(obj, path, value) {
+    const parts = path.split('.')
+    let current = obj
+
+    // 处理所有中间部分
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i]
+      let key, index
+
+      // 检查是否是数组索引格式，如key[0]
+      const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/)
+      if (arrayMatch) {
+        key = arrayMatch[1]
+        index = Number.parseInt(arrayMatch[2], 10)
+        // 确保当前层级的数组存在
+        if (!current[key] || !Array.isArray(current[key])) {
+          current[key] = []
+        }
+        // 扩展数组到足够大
+        while (current[key].length <= index) {
+          current[key].push(undefined)
+        }
+        // 如果当前位置未定义或为null，初始化为对象
+        if (current[key][index] == null) {
+          current[key][index] = {}
+        }
+        current = current[key][index]
+      } else {
+        // 处理普通属性
+        if (!current[part]) {
+          current[part] = {}
+        }
+        current = current[part]
+      }
+    }
+
+    // 处理最后一部分
+    const lastPart = parts[parts.length - 1]
+    const arrayMatch = lastPart.match(/^(\w+)\[(\d+)\]$/)
+    if (arrayMatch) {
+      const key = arrayMatch[1]
+      const index = Number.parseInt(arrayMatch[2], 10)
+      // 确保数组存在
+      if (!current[key] || !Array.isArray(current[key])) {
+        current[key] = []
+      }
+      // 扩展数组到所需索引
+      while (current[key].length <= index) {
+        current[key].push(undefined)
+      }
+      current[key][index] = value
+    } else {
+      current[lastPart] = value
+    }
+  }
+}
+
+function isPlainObject(value) {
+  return (
+    value !== null
+    && typeof value === 'object'
+    && !Array.isArray(value) &&
+    !(value instanceof Date) &&
+    !(value instanceof RegExp) &&
+    // Optional: exclude other built-in objects
+    Object.prototype.toString.call(value) === '[object Object]'
+  )
+}
+
+function merge(target, ...sources) {
+  if (!sources.length)
+    return target
+
+  const source = sources.shift() // 取出第一个源对象
+
+  if (_isObject(target) && _isObject(source)) {
+    for (const key in source) {
+      if (_isObject(source[key])) {
+        if (!target[key]) {
+          // 如果目标对象没有该属性，创建一个空对象
+          target[key] = {}
+        }
+        // 递归合并
+        merge(target[key], source[key])
+      } else {
+        // 直接覆盖
+        target[key] = source[key]
+      }
+    }
+  }
+
+  // 继续合并剩余的源对象
+  return merge(target, ...sources)
+}
+
+function _isObject(obj) {
+  return obj && typeof obj === 'object' && !Array.isArray(obj)
+}
+
+
+
+;// ./lib/helpers/objectHelper/index.js
+
+
+
+
 ;// ./lib/models/keyValueObject/keyValueObject.js
+
+
 class keyValueObject_KeyValueObject {
   constructor(options = {}) {
     options = options || {}
@@ -598,6 +738,19 @@ class keyValueObject_KeyValueObject {
   static getValueByKey(arr = [], key) {
     return this.foundValueByKey(arr, key)
   }
+  static getMetadataValueByKeyAsArray(arr = [], key) {
+    const _value = this.getValueByKey(arr, key)
+    if (!_value) {
+      return []
+    }
+    if (objectHelper.isPlainObject(_value)) {
+      return Object.keys(_value).reduce((acc, key) => {
+        acc.push({ key, value: _value[key] })
+        return acc
+      }, [])
+    }
+    return _value
+  }
   static getValueByKeyFromArray(arr = [], key) {
     if (arr.length === 0) {
       return null
@@ -1506,6 +1659,7 @@ class ActionRecord {
 
 
 const notUpdateAllowedProps = [
+  '_ActionRecord',
   'created',
   // 'statusType'
 ]
@@ -2722,6 +2876,10 @@ class TenantAwareEntity extends TrackedEntity {
   }
 
   // instance methods
+  insertOrUpdateMetadata(key, value) {
+    this.metadata = Metadata.insertOrUpdateRecord(this.metadata, key, value)
+    return this
+  }
   getMetadata() {
     return this.metadata
   }
@@ -2732,6 +2890,21 @@ class TenantAwareEntity extends TrackedEntity {
     const found = this.getMetadataByKey(key)
     return found ? found.value : null
   }
+  getMetadataValueByKeys(keys, kv) {
+    if (!Array.isArray(keys)) {
+      return null
+    }
+    kv = kv || this.metadata
+    if (keys.length === 0) {
+      return kv
+    }
+    const key = keys.shift()
+    const _val = Metadata.getMetadataValueByKeyAsArray(kv, key)
+    return this.getMetadataValueByKeys(keys, _val)
+  }
+  getMetadataValueByKeyAsArray(key) {
+    return Metadata.getMetadataValueByKeyAsArray(this.metadata, key)
+  }
   getRemarks() {
     return this.remarks
   }
@@ -3197,7 +3370,7 @@ function detectControlCharacters(input, options = {}) {
 
   return {
     hasControlChars: matches.length > 0,
-    matches: matches,
+    matches,
     totalFound: matches.length,
     inputPreview: input.length > 50 ? input.substring(0, 50) + '...' : input,
     inputLength: input.length,
@@ -3423,131 +3596,6 @@ function extractEmails(dirtyArray) {
 ;// ./lib/helpers/extractEmails/index.js
 
 
-;// ./lib/helpers/objectHelper/objectHelper.js
-const objectHelper = {
-  get(obj, path) {
-    const parts = path.split('.')
-    return parts.reduce((acc, part) => {
-      if (part.endsWith('[]')) {
-        // 处理数组遍历
-        const key = part.slice(0, -2) // 去掉 '[]' 得到属性名
-        if (Array.isArray(acc[key])) {
-          return acc[key] // 返回整个数组
-        }
-        return [] // 如果不是数组，返回空数组
-      }
-      if (part.includes('[') && part.includes(']')) {
-        // 处理数组索引
-        const arrayMatch = part.match(/(\w+)\[(\d+)\]/)
-        if (arrayMatch) {
-          const key = arrayMatch[1]
-          const index = arrayMatch[2]
-          return acc && acc[key] && acc[key][index]
-        }
-      } else if (acc && Array.isArray(acc)) {
-        // 如果当前值是数组，提取每个对象的指定属性
-        return acc.map((item) => item[part])
-      } else {
-        // 处理普通属性
-        return acc && acc[part]
-      }
-    }, obj)
-  },
-  merge,
-  set(obj, path, value) {
-    const parts = path.split('.')
-    let current = obj
-
-    // 处理所有中间部分
-    for (let i = 0; i < parts.length - 1; i++) {
-      const part = parts[i]
-      let key, index
-
-      // 检查是否是数组索引格式，如key[0]
-      const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/)
-      if (arrayMatch) {
-        key = arrayMatch[1]
-        index = Number.parseInt(arrayMatch[2], 10)
-        // 确保当前层级的数组存在
-        if (!current[key] || !Array.isArray(current[key])) {
-          current[key] = []
-        }
-        // 扩展数组到足够大
-        while (current[key].length <= index) {
-          current[key].push(undefined)
-        }
-        // 如果当前位置未定义或为null，初始化为对象
-        if (current[key][index] == null) {
-          current[key][index] = {}
-        }
-        current = current[key][index]
-      } else {
-        // 处理普通属性
-        if (!current[part]) {
-          current[part] = {}
-        }
-        current = current[part]
-      }
-    }
-
-    // 处理最后一部分
-    const lastPart = parts[parts.length - 1]
-    const arrayMatch = lastPart.match(/^(\w+)\[(\d+)\]$/)
-    if (arrayMatch) {
-      const key = arrayMatch[1]
-      const index = Number.parseInt(arrayMatch[2], 10)
-      // 确保数组存在
-      if (!current[key] || !Array.isArray(current[key])) {
-        current[key] = []
-      }
-      // 扩展数组到所需索引
-      while (current[key].length <= index) {
-        current[key].push(undefined)
-      }
-      current[key][index] = value
-    } else {
-      current[lastPart] = value
-    }
-  }
-}
-
-function merge(target, ...sources) {
-  if (!sources.length)
-    return target
-
-  const source = sources.shift() // 取出第一个源对象
-
-  if (_isObject(target) && _isObject(source)) {
-    for (const key in source) {
-      if (_isObject(source[key])) {
-        if (!target[key]) {
-          // 如果目标对象没有该属性，创建一个空对象
-          target[key] = {}
-        }
-        // 递归合并
-        merge(target[key], source[key])
-      } else {
-        // 直接覆盖
-        target[key] = source[key]
-      }
-    }
-  }
-
-  // 继续合并剩余的源对象
-  return merge(target, ...sources)
-}
-
-function _isObject(obj) {
-  return obj && typeof obj === 'object' && !Array.isArray(obj)
-}
-
-
-
-;// ./lib/helpers/objectHelper/index.js
-
-
-
-
 ;// ./lib/helpers/pReduce/pReduce.js
 async function pReduce(iterable, reducer, initialValue) {
   return new Promise((resolve, reject) => {

package/dist/q-utilities.esm.js

@@ -447,7 +447,147 @@ class AwsStsS3Client {
 
 
 
+;// ./lib/helpers/objectHelper/objectHelper.js
+const objectHelper = {
+  get(obj, path) {
+    const parts = path.split('.')
+    return parts.reduce((acc, part) => {
+      if (part.endsWith('[]')) {
+        // 处理数组遍历
+        const key = part.slice(0, -2) // 去掉 '[]' 得到属性名
+        if (Array.isArray(acc[key])) {
+          return acc[key] // 返回整个数组
+        }
+        return [] // 如果不是数组，返回空数组
+      }
+      if (part.includes('[') && part.includes(']')) {
+        // 处理数组索引
+        const arrayMatch = part.match(/(\w+)\[(\d+)\]/)
+        if (arrayMatch) {
+          const key = arrayMatch[1]
+          const index = arrayMatch[2]
+          return acc && acc[key] && acc[key][index]
+        }
+      } else if (acc && Array.isArray(acc)) {
+        // 如果当前值是数组，提取每个对象的指定属性
+        return acc.map((item) => item[part])
+      } else {
+        // 处理普通属性
+        return acc && acc[part]
+      }
+    }, obj)
+  },
+  isPlainObject,
+  merge,
+  set(obj, path, value) {
+    const parts = path.split('.')
+    let current = obj
+
+    // 处理所有中间部分
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i]
+      let key, index
+
+      // 检查是否是数组索引格式，如key[0]
+      const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/)
+      if (arrayMatch) {
+        key = arrayMatch[1]
+        index = Number.parseInt(arrayMatch[2], 10)
+        // 确保当前层级的数组存在
+        if (!current[key] || !Array.isArray(current[key])) {
+          current[key] = []
+        }
+        // 扩展数组到足够大
+        while (current[key].length <= index) {
+          current[key].push(undefined)
+        }
+        // 如果当前位置未定义或为null，初始化为对象
+        if (current[key][index] == null) {
+          current[key][index] = {}
+        }
+        current = current[key][index]
+      } else {
+        // 处理普通属性
+        if (!current[part]) {
+          current[part] = {}
+        }
+        current = current[part]
+      }
+    }
+
+    // 处理最后一部分
+    const lastPart = parts[parts.length - 1]
+    const arrayMatch = lastPart.match(/^(\w+)\[(\d+)\]$/)
+    if (arrayMatch) {
+      const key = arrayMatch[1]
+      const index = Number.parseInt(arrayMatch[2], 10)
+      // 确保数组存在
+      if (!current[key] || !Array.isArray(current[key])) {
+        current[key] = []
+      }
+      // 扩展数组到所需索引
+      while (current[key].length <= index) {
+        current[key].push(undefined)
+      }
+      current[key][index] = value
+    } else {
+      current[lastPart] = value
+    }
+  }
+}
+
+function isPlainObject(value) {
+  return (
+    value !== null
+    && typeof value === 'object'
+    && !Array.isArray(value) &&
+    !(value instanceof Date) &&
+    !(value instanceof RegExp) &&
+    // Optional: exclude other built-in objects
+    Object.prototype.toString.call(value) === '[object Object]'
+  )
+}
+
+function merge(target, ...sources) {
+  if (!sources.length)
+    return target
+
+  const source = sources.shift() // 取出第一个源对象
+
+  if (_isObject(target) && _isObject(source)) {
+    for (const key in source) {
+      if (_isObject(source[key])) {
+        if (!target[key]) {
+          // 如果目标对象没有该属性，创建一个空对象
+          target[key] = {}
+        }
+        // 递归合并
+        merge(target[key], source[key])
+      } else {
+        // 直接覆盖
+        target[key] = source[key]
+      }
+    }
+  }
+
+  // 继续合并剩余的源对象
+  return merge(target, ...sources)
+}
+
+function _isObject(obj) {
+  return obj && typeof obj === 'object' && !Array.isArray(obj)
+}
+
+
+
+;// ./lib/helpers/objectHelper/index.js
+
+
+
+
 ;// ./lib/models/keyValueObject/keyValueObject.js
+
+
 class keyValueObject_KeyValueObject {
   constructor(options = {}) {
     options = options || {}
@@ -523,6 +663,19 @@ class keyValueObject_KeyValueObject {
   static getValueByKey(arr = [], key) {
     return this.foundValueByKey(arr, key)
   }
+  static getMetadataValueByKeyAsArray(arr = [], key) {
+    const _value = this.getValueByKey(arr, key)
+    if (!_value) {
+      return []
+    }
+    if (objectHelper.isPlainObject(_value)) {
+      return Object.keys(_value).reduce((acc, key) => {
+        acc.push({ key, value: _value[key] })
+        return acc
+      }, [])
+    }
+    return _value
+  }
   static getValueByKeyFromArray(arr = [], key) {
     if (arr.length === 0) {
       return null
@@ -1431,6 +1584,7 @@ class ActionRecord {
 
 
 const notUpdateAllowedProps = [
+  '_ActionRecord',
   'created',
   // 'statusType'
 ]
@@ -2647,6 +2801,10 @@ class TenantAwareEntity extends TrackedEntity {
   }
 
   // instance methods
+  insertOrUpdateMetadata(key, value) {
+    this.metadata = Metadata.insertOrUpdateRecord(this.metadata, key, value)
+    return this
+  }
   getMetadata() {
     return this.metadata
   }
@@ -2657,6 +2815,21 @@ class TenantAwareEntity extends TrackedEntity {
     const found = this.getMetadataByKey(key)
     return found ? found.value : null
   }
+  getMetadataValueByKeys(keys, kv) {
+    if (!Array.isArray(keys)) {
+      return null
+    }
+    kv = kv || this.metadata
+    if (keys.length === 0) {
+      return kv
+    }
+    const key = keys.shift()
+    const _val = Metadata.getMetadataValueByKeyAsArray(kv, key)
+    return this.getMetadataValueByKeys(keys, _val)
+  }
+  getMetadataValueByKeyAsArray(key) {
+    return Metadata.getMetadataValueByKeyAsArray(this.metadata, key)
+  }
   getRemarks() {
     return this.remarks
   }
@@ -3122,7 +3295,7 @@ function detectControlCharacters(input, options = {}) {
 
   return {
     hasControlChars: matches.length > 0,
-    matches: matches,
+    matches,
     totalFound: matches.length,
     inputPreview: input.length > 50 ? input.substring(0, 50) + '...' : input,
     inputLength: input.length,
@@ -3348,131 +3521,6 @@ function extractEmails(dirtyArray) {
 ;// ./lib/helpers/extractEmails/index.js
 
 
-;// ./lib/helpers/objectHelper/objectHelper.js
-const objectHelper = {
-  get(obj, path) {
-    const parts = path.split('.')
-    return parts.reduce((acc, part) => {
-      if (part.endsWith('[]')) {
-        // 处理数组遍历
-        const key = part.slice(0, -2) // 去掉 '[]' 得到属性名
-        if (Array.isArray(acc[key])) {
-          return acc[key] // 返回整个数组
-        }
-        return [] // 如果不是数组，返回空数组
-      }
-      if (part.includes('[') && part.includes(']')) {
-        // 处理数组索引
-        const arrayMatch = part.match(/(\w+)\[(\d+)\]/)
-        if (arrayMatch) {
-          const key = arrayMatch[1]
-          const index = arrayMatch[2]
-          return acc && acc[key] && acc[key][index]
-        }
-      } else if (acc && Array.isArray(acc)) {
-        // 如果当前值是数组，提取每个对象的指定属性
-        return acc.map((item) => item[part])
-      } else {
-        // 处理普通属性
-        return acc && acc[part]
-      }
-    }, obj)
-  },
-  merge,
-  set(obj, path, value) {
-    const parts = path.split('.')
-    let current = obj
-
-    // 处理所有中间部分
-    for (let i = 0; i < parts.length - 1; i++) {
-      const part = parts[i]
-      let key, index
-
-      // 检查是否是数组索引格式，如key[0]
-      const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/)
-      if (arrayMatch) {
-        key = arrayMatch[1]
-        index = Number.parseInt(arrayMatch[2], 10)
-        // 确保当前层级的数组存在
-        if (!current[key] || !Array.isArray(current[key])) {
-          current[key] = []
-        }
-        // 扩展数组到足够大
-        while (current[key].length <= index) {
-          current[key].push(undefined)
-        }
-        // 如果当前位置未定义或为null，初始化为对象
-        if (current[key][index] == null) {
-          current[key][index] = {}
-        }
-        current = current[key][index]
-      } else {
-        // 处理普通属性
-        if (!current[part]) {
-          current[part] = {}
-        }
-        current = current[part]
-      }
-    }
-
-    // 处理最后一部分
-    const lastPart = parts[parts.length - 1]
-    const arrayMatch = lastPart.match(/^(\w+)\[(\d+)\]$/)
-    if (arrayMatch) {
-      const key = arrayMatch[1]
-      const index = Number.parseInt(arrayMatch[2], 10)
-      // 确保数组存在
-      if (!current[key] || !Array.isArray(current[key])) {
-        current[key] = []
-      }
-      // 扩展数组到所需索引
-      while (current[key].length <= index) {
-        current[key].push(undefined)
-      }
-      current[key][index] = value
-    } else {
-      current[lastPart] = value
-    }
-  }
-}
-
-function merge(target, ...sources) {
-  if (!sources.length)
-    return target
-
-  const source = sources.shift() // 取出第一个源对象
-
-  if (_isObject(target) && _isObject(source)) {
-    for (const key in source) {
-      if (_isObject(source[key])) {
-        if (!target[key]) {
-          // 如果目标对象没有该属性，创建一个空对象
-          target[key] = {}
-        }
-        // 递归合并
-        merge(target[key], source[key])
-      } else {
-        // 直接覆盖
-        target[key] = source[key]
-      }
-    }
-  }
-
-  // 继续合并剩余的源对象
-  return merge(target, ...sources)
-}
-
-function _isObject(obj) {
-  return obj && typeof obj === 'object' && !Array.isArray(obj)
-}
-
-
-
-;// ./lib/helpers/objectHelper/index.js
-
-
-
-
 ;// ./lib/helpers/pReduce/pReduce.js
 async function pReduce(iterable, reducer, initialValue) {
   return new Promise((resolve, reject) => {

package/dist/q-utilities.min.js

@@ -553,7 +553,147 @@ class AwsStsS3Client {
 
 
 
+;// ./lib/helpers/objectHelper/objectHelper.js
+const objectHelper = {
+  get(obj, path) {
+    const parts = path.split('.')
+    return parts.reduce((acc, part) => {
+      if (part.endsWith('[]')) {
+        // 处理数组遍历
+        const key = part.slice(0, -2) // 去掉 '[]' 得到属性名
+        if (Array.isArray(acc[key])) {
+          return acc[key] // 返回整个数组
+        }
+        return [] // 如果不是数组，返回空数组
+      }
+      if (part.includes('[') && part.includes(']')) {
+        // 处理数组索引
+        const arrayMatch = part.match(/(\w+)\[(\d+)\]/)
+        if (arrayMatch) {
+          const key = arrayMatch[1]
+          const index = arrayMatch[2]
+          return acc && acc[key] && acc[key][index]
+        }
+      } else if (acc && Array.isArray(acc)) {
+        // 如果当前值是数组，提取每个对象的指定属性
+        return acc.map((item) => item[part])
+      } else {
+        // 处理普通属性
+        return acc && acc[part]
+      }
+    }, obj)
+  },
+  isPlainObject,
+  merge,
+  set(obj, path, value) {
+    const parts = path.split('.')
+    let current = obj
+
+    // 处理所有中间部分
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i]
+      let key, index
+
+      // 检查是否是数组索引格式，如key[0]
+      const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/)
+      if (arrayMatch) {
+        key = arrayMatch[1]
+        index = Number.parseInt(arrayMatch[2], 10)
+        // 确保当前层级的数组存在
+        if (!current[key] || !Array.isArray(current[key])) {
+          current[key] = []
+        }
+        // 扩展数组到足够大
+        while (current[key].length <= index) {
+          current[key].push(undefined)
+        }
+        // 如果当前位置未定义或为null，初始化为对象
+        if (current[key][index] == null) {
+          current[key][index] = {}
+        }
+        current = current[key][index]
+      } else {
+        // 处理普通属性
+        if (!current[part]) {
+          current[part] = {}
+        }
+        current = current[part]
+      }
+    }
+
+    // 处理最后一部分
+    const lastPart = parts[parts.length - 1]
+    const arrayMatch = lastPart.match(/^(\w+)\[(\d+)\]$/)
+    if (arrayMatch) {
+      const key = arrayMatch[1]
+      const index = Number.parseInt(arrayMatch[2], 10)
+      // 确保数组存在
+      if (!current[key] || !Array.isArray(current[key])) {
+        current[key] = []
+      }
+      // 扩展数组到所需索引
+      while (current[key].length <= index) {
+        current[key].push(undefined)
+      }
+      current[key][index] = value
+    } else {
+      current[lastPart] = value
+    }
+  }
+}
+
+function isPlainObject(value) {
+  return (
+    value !== null
+    && typeof value === 'object'
+    && !Array.isArray(value) &&
+    !(value instanceof Date) &&
+    !(value instanceof RegExp) &&
+    // Optional: exclude other built-in objects
+    Object.prototype.toString.call(value) === '[object Object]'
+  )
+}
+
+function merge(target, ...sources) {
+  if (!sources.length)
+    return target
+
+  const source = sources.shift() // 取出第一个源对象
+
+  if (_isObject(target) && _isObject(source)) {
+    for (const key in source) {
+      if (_isObject(source[key])) {
+        if (!target[key]) {
+          // 如果目标对象没有该属性，创建一个空对象
+          target[key] = {}
+        }
+        // 递归合并
+        merge(target[key], source[key])
+      } else {
+        // 直接覆盖
+        target[key] = source[key]
+      }
+    }
+  }
+
+  // 继续合并剩余的源对象
+  return merge(target, ...sources)
+}
+
+function _isObject(obj) {
+  return obj && typeof obj === 'object' && !Array.isArray(obj)
+}
+
+
+
+;// ./lib/helpers/objectHelper/index.js
+
+
+
+
 ;// ./lib/models/keyValueObject/keyValueObject.js
+
+
 class keyValueObject_KeyValueObject {
   constructor(options = {}) {
     options = options || {}
@@ -629,6 +769,19 @@ class keyValueObject_KeyValueObject {
   static getValueByKey(arr = [], key) {
     return this.foundValueByKey(arr, key)
   }
+  static getMetadataValueByKeyAsArray(arr = [], key) {
+    const _value = this.getValueByKey(arr, key)
+    if (!_value) {
+      return []
+    }
+    if (objectHelper.isPlainObject(_value)) {
+      return Object.keys(_value).reduce((acc, key) => {
+        acc.push({ key, value: _value[key] })
+        return acc
+      }, [])
+    }
+    return _value
+  }
   static getValueByKeyFromArray(arr = [], key) {
     if (arr.length === 0) {
       return null
@@ -1537,6 +1690,7 @@ class ActionRecord {
 
 
 const notUpdateAllowedProps = [
+  '_ActionRecord',
   'created',
   // 'statusType'
 ]
@@ -2753,6 +2907,10 @@ class TenantAwareEntity extends TrackedEntity {
   }
 
   // instance methods
+  insertOrUpdateMetadata(key, value) {
+    this.metadata = Metadata.insertOrUpdateRecord(this.metadata, key, value)
+    return this
+  }
   getMetadata() {
     return this.metadata
   }
@@ -2763,6 +2921,21 @@ class TenantAwareEntity extends TrackedEntity {
     const found = this.getMetadataByKey(key)
     return found ? found.value : null
   }
+  getMetadataValueByKeys(keys, kv) {
+    if (!Array.isArray(keys)) {
+      return null
+    }
+    kv = kv || this.metadata
+    if (keys.length === 0) {
+      return kv
+    }
+    const key = keys.shift()
+    const _val = Metadata.getMetadataValueByKeyAsArray(kv, key)
+    return this.getMetadataValueByKeys(keys, _val)
+  }
+  getMetadataValueByKeyAsArray(key) {
+    return Metadata.getMetadataValueByKeyAsArray(this.metadata, key)
+  }
   getRemarks() {
     return this.remarks
   }
@@ -3228,7 +3401,7 @@ function detectControlCharacters(input, options = {}) {
 
   return {
     hasControlChars: matches.length > 0,
-    matches: matches,
+    matches,
     totalFound: matches.length,
     inputPreview: input.length > 50 ? input.substring(0, 50) + '...' : input,
     inputLength: input.length,
@@ -3454,131 +3627,6 @@ function extractEmails(dirtyArray) {
 ;// ./lib/helpers/extractEmails/index.js
 
 
-;// ./lib/helpers/objectHelper/objectHelper.js
-const objectHelper = {
-  get(obj, path) {
-    const parts = path.split('.')
-    return parts.reduce((acc, part) => {
-      if (part.endsWith('[]')) {
-        // 处理数组遍历
-        const key = part.slice(0, -2) // 去掉 '[]' 得到属性名
-        if (Array.isArray(acc[key])) {
-          return acc[key] // 返回整个数组
-        }
-        return [] // 如果不是数组，返回空数组
-      }
-      if (part.includes('[') && part.includes(']')) {
-        // 处理数组索引
-        const arrayMatch = part.match(/(\w+)\[(\d+)\]/)
-        if (arrayMatch) {
-          const key = arrayMatch[1]
-          const index = arrayMatch[2]
-          return acc && acc[key] && acc[key][index]
-        }
-      } else if (acc && Array.isArray(acc)) {
-        // 如果当前值是数组，提取每个对象的指定属性
-        return acc.map((item) => item[part])
-      } else {
-        // 处理普通属性
-        return acc && acc[part]
-      }
-    }, obj)
-  },
-  merge,
-  set(obj, path, value) {
-    const parts = path.split('.')
-    let current = obj
-
-    // 处理所有中间部分
-    for (let i = 0; i < parts.length - 1; i++) {
-      const part = parts[i]
-      let key, index
-
-      // 检查是否是数组索引格式，如key[0]
-      const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/)
-      if (arrayMatch) {
-        key = arrayMatch[1]
-        index = Number.parseInt(arrayMatch[2], 10)
-        // 确保当前层级的数组存在
-        if (!current[key] || !Array.isArray(current[key])) {
-          current[key] = []
-        }
-        // 扩展数组到足够大
-        while (current[key].length <= index) {
-          current[key].push(undefined)
-        }
-        // 如果当前位置未定义或为null，初始化为对象
-        if (current[key][index] == null) {
-          current[key][index] = {}
-        }
-        current = current[key][index]
-      } else {
-        // 处理普通属性
-        if (!current[part]) {
-          current[part] = {}
-        }
-        current = current[part]
-      }
-    }
-
-    // 处理最后一部分
-    const lastPart = parts[parts.length - 1]
-    const arrayMatch = lastPart.match(/^(\w+)\[(\d+)\]$/)
-    if (arrayMatch) {
-      const key = arrayMatch[1]
-      const index = Number.parseInt(arrayMatch[2], 10)
-      // 确保数组存在
-      if (!current[key] || !Array.isArray(current[key])) {
-        current[key] = []
-      }
-      // 扩展数组到所需索引
-      while (current[key].length <= index) {
-        current[key].push(undefined)
-      }
-      current[key][index] = value
-    } else {
-      current[lastPart] = value
-    }
-  }
-}
-
-function merge(target, ...sources) {
-  if (!sources.length)
-    return target
-
-  const source = sources.shift() // 取出第一个源对象
-
-  if (_isObject(target) && _isObject(source)) {
-    for (const key in source) {
-      if (_isObject(source[key])) {
-        if (!target[key]) {
-          // 如果目标对象没有该属性，创建一个空对象
-          target[key] = {}
-        }
-        // 递归合并
-        merge(target[key], source[key])
-      } else {
-        // 直接覆盖
-        target[key] = source[key]
-      }
-    }
-  }
-
-  // 继续合并剩余的源对象
-  return merge(target, ...sources)
-}
-
-function _isObject(obj) {
-  return obj && typeof obj === 'object' && !Array.isArray(obj)
-}
-
-
-
-;// ./lib/helpers/objectHelper/index.js
-
-
-
-
 ;// ./lib/helpers/pReduce/pReduce.js
 async function pReduce(iterable, reducer, initialValue) {
   return new Promise((resolve, reject) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@questwork/q-utilities",
-  "version": "0.1.22",
+  "version": "0.1.29",
   "description": "Questwork QUtilities",
   "author": {
     "name": "Questwork Consulting Limited",
@@ -8,6 +8,13 @@
     "url": "https://questwork.com/"
   },
   "license": "MIT",
+  "scripts": {
+    "build": "cross-env NODE_ENV=production minimize=false gulp",
+    "build:wp": "cross-env NODE_ENV=production minimize=false gulp wp",
+    "lint": "eslint .",
+    "test:helpers": "NODE_ENV=test mocha --exit 'lib/helpers/test.setup.js' 'lib/helpers/**/*.spec.js'",
+    "test:models": "NODE_ENV=test mocha --exit 'lib/test.setup.js' 'lib/**/*.spec.js'"
+  },
   "type": "module",
   "exports": {
     ".": {
@@ -43,12 +50,5 @@
   },
   "engines": {
     "node": ">=10.0.0"
-  },
-  "scripts": {
-    "build": "cross-env NODE_ENV=production minimize=false gulp",
-    "build:wp": "cross-env NODE_ENV=production minimize=false gulp wp",
-    "lint": "eslint .",
-    "test:helpers": "NODE_ENV=test mocha --exit 'lib/helpers/test.setup.js' 'lib/helpers/**/*.spec.js'",
-    "test:models": "NODE_ENV=test mocha --exit 'lib/test.setup.js' 'lib/**/*.spec.js'"
   }
-}
+}