@qezor/structkit 1.0.0 → 1.0.2

package/lib/deep.js

@@ -0,0 +1,435 @@
+"use strict"
+
+const {
+  isObjectLike,
+  isPlainObject,
+  tokenizePath,
+  getValueByPath,
+  cloneDeep,
+  stringifyPathTokens,
+  getValueByTokens,
+  setValueByTokens,
+  deleteByTokens,
+} = require("./shared.js")
+const { isEqual } = require("./compare.js")
+const { normalizeCount } = require("./range.js")
+const { insertValue } = require("./insert.js")
+
+function isTraversable(value) {
+  return Array.isArray(value) || isPlainObject(value)
+}
+
+function getNodeType(value) {
+  if (value === null) return "null"
+  if (Array.isArray(value)) return "array"
+  if (value instanceof Date) return "date"
+  if (value instanceof RegExp) return "regexp"
+  if (value instanceof Map) return "map"
+  if (value instanceof Set) return "set"
+  return typeof value === "object" ? "object" : typeof value
+}
+
+function toPositiveLimit(value, fallback) {
+  if (value == null) return fallback
+  const next = normalizeCount(value, fallback)
+  return next === 0 ? 0 : next
+}
+
+function normalizeDeepOptions(options = {}) {
+  return {
+    fromPath: options.fromPath ?? options.scope ?? [],
+    minDepth: normalizeCount(options.minDepth, 0),
+    maxDepth: options.maxDepth == null ? Number.POSITIVE_INFINITY : normalizeCount(options.maxDepth, 0),
+    includeRoot: options.includeRoot !== false,
+    includeContainers: options.includeContainers !== false,
+    includeLeaves: options.includeLeaves !== false,
+    order: options.order === "bfs" ? "bfs" : "dfs",
+    greedy: options.greedy ?? false,
+    limit: options.limit == null ? Number.POSITIVE_INFINITY : toPositiveLimit(options.limit, Number.POSITIVE_INFINITY),
+    maxNodes: options.maxNodes == null ? 100000 : toPositiveLimit(options.maxNodes, 100000),
+  }
+}
+
+function createDeepMatcher(predicate) {
+  if (typeof predicate === "function") return predicate
+
+  if (typeof predicate === "string") {
+    const expected = predicate
+    return (entry) => entry.path === expected || entry.key === expected
+  }
+
+  if (predicate && typeof predicate === "object" && !Array.isArray(predicate)) {
+    const query = predicate
+    return (entry) => {
+      if (query.path != null && entry.path !== String(query.path)) return false
+      if (query.key != null && entry.key !== String(query.key)) return false
+      if (query.type != null && entry.type !== String(query.type)) return false
+      if (query.depth != null && entry.depth !== Number(query.depth)) return false
+      if (query.pathDepth != null && entry.pathDepth !== Number(query.pathDepth)) return false
+      if (query.absoluteDepth != null && entry.absoluteDepth !== Number(query.absoluteDepth)) return false
+      if (query.minDepth != null && entry.depth < Number(query.minDepth)) return false
+      if (query.maxDepth != null && entry.depth > Number(query.maxDepth)) return false
+      if (query.minPathDepth != null && entry.pathDepth < Number(query.minPathDepth)) return false
+      if (query.maxPathDepth != null && entry.pathDepth > Number(query.maxPathDepth)) return false
+      if (Object.prototype.hasOwnProperty.call(query, "value") && !isEqual(entry.value, query.value)) return false
+
+      if (query.includes != null) {
+        const needle = String(query.includes).toLowerCase()
+        const keyHit = typeof entry.key === "string" && entry.key.toLowerCase().includes(needle)
+        const pathHit = entry.path.toLowerCase().includes(needle)
+        const valueHit = typeof entry.value === "string" && entry.value.toLowerCase().includes(needle)
+        if (!keyHit && !pathHit && !valueHit) return false
+      }
+
+      return true
+    }
+  }
+
+  if (predicate === undefined) return () => true
+  return (entry) => Object.is(entry.value, predicate)
+}
+
+function createEntry(frame) {
+  const value = frame.value
+  const isContainer = isTraversable(value)
+
+  return {
+    value,
+    parent: frame.parent,
+    key: frame.key == null ? null : String(frame.key),
+    tokens: frame.tokens.slice(),
+    path: stringifyPathTokens(frame.tokens),
+    depth: frame.depth,
+    pathDepth: frame.pathDepth,
+    absoluteDepth: frame.absoluteDepth,
+    type: getNodeType(value),
+    isContainer,
+    isLeaf: !isContainer,
+  }
+}
+
+function pushChildFrames(stack, frame, options, enqueue) {
+  const parentValue = frame.value
+  const isArrayParent = Array.isArray(parentValue)
+
+  const pushChild = (key, childValue) => {
+    const childIsContainer = isTraversable(childValue)
+    const childDepth = childIsContainer ? frame.depth + 1 : frame.depth
+    if (childDepth > options.maxDepth) return
+
+    enqueue({
+      value: childValue,
+      parent: parentValue,
+      key,
+      tokens: frame.tokens.concat(key),
+      depth: childDepth,
+      pathDepth: frame.pathDepth + 1,
+      absoluteDepth: frame.absoluteDepth + 1,
+      parentIsArray: isArrayParent,
+    })
+  }
+
+  if (Array.isArray(parentValue)) {
+    stack(parentValue.length, (index) => pushChild(index, parentValue[index]))
+    return
+  }
+
+  const keys = Object.keys(parentValue)
+  stack(keys.length, (index) => {
+    const key = keys[index]
+    pushChild(key, parentValue[key])
+  })
+}
+
+function* iterateDepthFirst(root, options) {
+  const scopeTokens = tokenizePath(options.fromPath)
+  const scopeValue = scopeTokens.length ? getValueByPath(root, scopeTokens) : root
+
+  if (scopeTokens.length && scopeValue === undefined) return
+
+  const initialParent = scopeTokens.length ? getValueByPath(root, scopeTokens.slice(0, -1)) : undefined
+  const initialKey = scopeTokens.length ? scopeTokens[scopeTokens.length - 1] : null
+  const stack = [{
+    value: scopeValue,
+    parent: initialParent,
+    key: initialKey,
+    tokens: scopeTokens,
+    depth: 0,
+    pathDepth: 0,
+    absoluteDepth: scopeTokens.length,
+  }]
+
+  let visited = 0
+  let yielded = 0
+
+  while (stack.length) {
+    const frame = stack.pop()
+    visited += 1
+
+    if (visited > options.maxNodes) {
+      const error = new Error(`deep traversal exceeded maxNodes=${options.maxNodes}`)
+      error.code = "EMAXNODES"
+      throw error
+    }
+
+    const entry = createEntry(frame)
+    const shouldYield = (frame.depth > 0 || options.includeRoot)
+      && frame.depth >= options.minDepth
+      && ((entry.isContainer && options.includeContainers) || (entry.isLeaf && options.includeLeaves))
+
+    if (shouldYield) {
+      yield entry
+      yielded += 1
+      if (yielded >= options.limit) return
+    }
+
+    if (!entry.isContainer) continue
+
+    pushChildFrames(
+      (length, iteratee) => {
+        for (let index = length - 1; index >= 0; index -= 1) {
+          iteratee(index)
+        }
+      },
+      frame,
+      options,
+      (nextFrame) => stack.push(nextFrame)
+    )
+  }
+}
+
+function* iterateBreadthFirst(root, options) {
+  const scopeTokens = tokenizePath(options.fromPath)
+  const scopeValue = scopeTokens.length ? getValueByPath(root, scopeTokens) : root
+
+  if (scopeTokens.length && scopeValue === undefined) return
+
+  const queue = [{
+    value: scopeValue,
+    parent: scopeTokens.length ? getValueByPath(root, scopeTokens.slice(0, -1)) : undefined,
+    key: scopeTokens.length ? scopeTokens[scopeTokens.length - 1] : null,
+    tokens: scopeTokens,
+    depth: 0,
+    pathDepth: 0,
+    absoluteDepth: scopeTokens.length,
+  }]
+
+  let cursor = 0
+  let visited = 0
+  let yielded = 0
+
+  while (cursor < queue.length) {
+    const frame = queue[cursor]
+    cursor += 1
+    visited += 1
+
+    if (visited > options.maxNodes) {
+      const error = new Error(`deep traversal exceeded maxNodes=${options.maxNodes}`)
+      error.code = "EMAXNODES"
+      throw error
+    }
+
+    const entry = createEntry(frame)
+    const shouldYield = (frame.depth > 0 || options.includeRoot)
+      && frame.depth >= options.minDepth
+      && ((entry.isContainer && options.includeContainers) || (entry.isLeaf && options.includeLeaves))
+
+    if (shouldYield) {
+      yield entry
+      yielded += 1
+      if (yielded >= options.limit) return
+    }
+
+    if (!entry.isContainer) continue
+
+    pushChildFrames(
+      (length, iteratee) => {
+        for (let index = 0; index < length; index += 1) {
+          iteratee(index)
+        }
+      },
+      frame,
+      options,
+      (nextFrame) => queue.push(nextFrame)
+    )
+  }
+}
+
+function iterateDeep(value, options = {}) {
+  const normalized = normalizeDeepOptions(options)
+  return normalized.order === "bfs"
+    ? iterateBreadthFirst(value, normalized)
+    : iterateDepthFirst(value, normalized)
+}
+
+function isBetterGreedyMatch(current, next, mode) {
+  if (!current) return true
+
+  if (mode === true || mode === "last") return true
+
+  if (mode === "deepest") {
+    if (next.depth !== current.depth) return next.depth > current.depth
+    if (next.pathDepth !== current.pathDepth) return next.pathDepth > current.pathDepth
+    return next.path >= current.path
+  }
+
+  if (mode === "path" || mode === "deepest-path") {
+    if (next.pathDepth !== current.pathDepth) return next.pathDepth > current.pathDepth
+    if (next.depth !== current.depth) return next.depth > current.depth
+    return next.path >= current.path
+  }
+
+  return false
+}
+
+function findDeep(value, predicate, options = {}) {
+  const normalized = normalizeDeepOptions(options)
+  const match = createDeepMatcher(predicate)
+  let selected
+
+  for (const entry of iterateDeep(value, options)) {
+    if (!match(entry)) continue
+    if (!normalized.greedy) return entry
+    if (isBetterGreedyMatch(selected, entry, normalized.greedy)) {
+      selected = entry
+    }
+  }
+
+  return selected
+}
+
+function filterDeep(value, predicate, options = {}) {
+  const match = createDeepMatcher(predicate)
+  const output = []
+  for (const entry of iterateDeep(value, options)) {
+    if (!match(entry)) continue
+    output.push(entry)
+  }
+  return output
+}
+
+function findPaths(value, predicate, options = {}) {
+  const output = []
+  for (const entry of filterDeep(value, predicate, options)) {
+    output.push(entry.path)
+  }
+  return output
+}
+
+function compareTokenPathsDescending(left, right) {
+  if (left.tokens.length !== right.tokens.length) {
+    return right.tokens.length - left.tokens.length
+  }
+
+  const length = Math.max(left.tokens.length, right.tokens.length)
+  for (let index = 0; index < length; index += 1) {
+    const leftToken = left.tokens[index]
+    const rightToken = right.tokens[index]
+    if (leftToken === rightToken) continue
+
+    if (typeof leftToken === "number" && typeof rightToken === "number") {
+      return rightToken - leftToken
+    }
+
+    return String(rightToken).localeCompare(String(leftToken))
+  }
+
+  return 0
+}
+
+function mapDeep(value, predicate, updater, options = {}) {
+  if (typeof updater !== "function") {
+    throw new TypeError("mapDeep requires an updater function")
+  }
+
+  let output = cloneDeep(value)
+  const match = createDeepMatcher(predicate)
+  const matches = []
+
+  for (const entry of iterateDeep(output, options)) {
+    if (!match(entry)) continue
+    matches.push({
+      tokens: entry.tokens.slice(),
+      path: entry.path,
+      depth: entry.depth,
+      absoluteDepth: entry.absoluteDepth,
+      type: entry.type,
+      key: entry.key,
+    })
+  }
+
+  matches.sort(compareTokenPathsDescending)
+
+  for (const matchEntry of matches) {
+    const current = getValueByTokens(output, matchEntry.tokens)
+    const next = updater(current, {
+      ...matchEntry,
+      value: current,
+    })
+    output = setValueByTokens(output, matchEntry.tokens, next)
+  }
+
+  return output
+}
+
+function removeDeep(value, predicate, options = {}) {
+  let output = cloneDeep(value)
+  const matches = filterDeep(output, predicate, options)
+    .map((entry) => ({
+      tokens: entry.tokens.slice(),
+      path: entry.path,
+    }))
+
+  matches.sort(compareTokenPathsDescending)
+
+  for (const match of matches) {
+    output = deleteByTokens(output, match.tokens)
+  }
+
+  return output
+}
+
+function insertDeep(value, predicate, insertion, options = {}) {
+  let output = cloneDeep(value)
+  const match = createDeepMatcher(predicate)
+  const matches = []
+
+  for (const entry of iterateDeep(output, options)) {
+    if (!match(entry)) continue
+    matches.push({
+      tokens: entry.tokens.slice(),
+      path: entry.path,
+      depth: entry.depth,
+      pathDepth: entry.pathDepth,
+      absoluteDepth: entry.absoluteDepth,
+      type: entry.type,
+      key: entry.key,
+    })
+  }
+
+  matches.sort(compareTokenPathsDescending)
+
+  for (const matchEntry of matches) {
+    const current = getValueByTokens(output, matchEntry.tokens)
+    const resolvedInsertion = typeof insertion === "function"
+      ? insertion(current, {
+          ...matchEntry,
+          value: current,
+        })
+      : insertion
+    const next = insertValue(current, resolvedInsertion, options)
+    output = setValueByTokens(output, matchEntry.tokens, next)
+  }
+
+  return output
+}
+
+module.exports = {
+  iterateDeep,
+  findDeep,
+  filterDeep,
+  findPaths,
+  mapDeep,
+  removeDeep,
+  insertDeep,
+}

package/lib/insert.js

@@ -0,0 +1,62 @@
+"use strict"
+
+const { insertText } = require("./string.js")
+const { insertAt } = require("./array.js")
+const { isPlainObject, cloneDeep } = require("./shared.js")
+
+function cloneInsertion(value) {
+  if (value == null) return value
+  if (typeof value !== "object") return value
+  return cloneDeep(value)
+}
+
+function getObjectInsertKey(options = {}) {
+  const key = options.key ?? options.property
+  if (key == null || key === "") return null
+  return String(key)
+}
+
+function createMissingSeed(options = {}) {
+  if (options.kind === "array") return []
+  if (options.kind === "string") return ""
+  if (options.kind === "object") return {}
+  if (getObjectInsertKey(options)) return {}
+  return undefined
+}
+
+function insertValue(current, insertion, options = {}) {
+  let target = current
+
+  if (target === undefined && options.createMissing === true) {
+    target = createMissingSeed(options)
+  }
+
+  if (Array.isArray(target)) {
+    return insertAt(target, options.at ?? options.index ?? target.length, cloneInsertion(insertion))
+  }
+
+  if (typeof target === "string") {
+    return insertText(target, insertion, options)
+  }
+
+  if (isPlainObject(target)) {
+    const key = getObjectInsertKey(options)
+    if (!key) {
+      if (options.merge === true && isPlainObject(insertion)) {
+        return { ...target, ...cloneDeep(insertion) }
+      }
+      throw new TypeError("object insertion requires options.key or options.property")
+    }
+
+    return {
+      ...target,
+      [key]: cloneInsertion(insertion),
+    }
+  }
+
+  throw new TypeError("insertValue only supports arrays, strings, and plain objects")
+}
+
+module.exports = {
+  insertValue,
+}

package/lib/object.js

@@ -4,11 +4,13 @@ const {
   isObjectLike,
   isPlainObject,
   tokenizePath,
+  stringifyPathTokens,
   getValueByPath,
   createIteratee,
   cloneShallow,
   cloneDeep,
 } = require("./shared.js")
+const { insertValue } = require("./insert.js")
 
 function get(value, path, defaultValue) {
   const resolved = getValueByPath(value, path)
@@ -52,6 +54,46 @@ function set(target, path, nextValue) {
   return target
 }
 
+function update(target, path, updater, options = {}) {
+  if (typeof updater !== "function") {
+    throw new TypeError("update requires an updater function")
+  }
+
+  const tokens = tokenizePath(path)
+  if (!tokens.length) {
+    return updater(target, {
+      value: target,
+      path: "",
+      tokens: [],
+    })
+  }
+
+  if (!isObjectLike(target) && !Array.isArray(target)) return target
+
+  const current = getValueByPath(target, tokens)
+  const next = updater(
+    current === undefined && Object.prototype.hasOwnProperty.call(options, "defaultValue")
+      ? options.defaultValue
+      : current,
+    {
+      value: current,
+      path: stringifyPathTokens(tokens),
+      tokens: tokens.slice(),
+    }
+  )
+
+  return set(target, tokens, next)
+}
+
+function insertAtPath(target, path, insertion, options = {}) {
+  const tokens = tokenizePath(path)
+  const current = tokens.length ? getValueByPath(target, tokens) : target
+  const next = insertValue(current, insertion, options)
+
+  if (!tokens.length) return next
+  return set(target, tokens, next)
+}
+
 function unset(target, path) {
   if (!isObjectLike(target) && !Array.isArray(target)) return false
 
@@ -190,6 +232,8 @@ module.exports = {
   get,
   has,
   set,
+  update,
+  insertAtPath,
   unset,
   pick,
   omit,

package/lib/range.js

@@ -0,0 +1,55 @@
+"use strict"
+
+function toFiniteInteger(value, fallback) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.trunc(number)
+}
+
+function clampIndex(length, value, fallback) {
+  const size = Math.max(0, toFiniteInteger(length, 0))
+  let index = toFiniteInteger(value, fallback)
+  if (index == null) index = fallback
+  if (index < 0) index = size + index
+  if (index < 0) return 0
+  if (index > size) return size
+  return index
+}
+
+function normalizeRange(length, options = {}) {
+  const size = Math.max(0, toFiniteInteger(length, 0))
+  const start = clampIndex(size, options.from ?? options.start, 0)
+
+  let end
+  if (options.count != null) {
+    const count = Math.max(0, toFiniteInteger(options.count, 0))
+    end = Math.min(size, start + count)
+  } else {
+    end = clampIndex(size, options.to ?? options.end, size)
+  }
+
+  if (end < start) end = start
+
+  return {
+    start,
+    end,
+    length: end - start,
+  }
+}
+
+function normalizeInsertIndex(length, value, fallback) {
+  const size = Math.max(0, toFiniteInteger(length, 0))
+  return clampIndex(size, value, fallback == null ? size : fallback)
+}
+
+function normalizeCount(value, fallback = 0) {
+  return Math.max(0, toFiniteInteger(value, fallback))
+}
+
+module.exports = {
+  toFiniteInteger,
+  clampIndex,
+  normalizeRange,
+  normalizeInsertIndex,
+  normalizeCount,
+}

package/lib/shared.js

@@ -103,6 +103,10 @@ function tokenizePath(path) {
 
 function getValueByPath(value, path) {
   const tokens = tokenizePath(path)
+  return getValueByTokens(value, tokens)
+}
+
+function getValueByTokens(value, tokens) {
   let current = value
 
   for (let index = 0; index < tokens.length; index += 1) {
@@ -119,6 +123,24 @@ function createIteratee(iteratee) {
   return (value) => getValueByPath(value, iteratee)
 }
 
+function stringifyPathTokens(tokens) {
+  if (!Array.isArray(tokens) || !tokens.length) return ""
+
+  let output = ""
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]
+    if (typeof token === "number") {
+      output += `[${token}]`
+    } else if (!output) {
+      output = token
+    } else {
+      output += `.${token}`
+    }
+  }
+
+  return output
+}
+
 function cloneShallow(value) {
   if (Array.isArray(value)) return value.slice()
   if (isPlainObject(value)) return { ...value }
@@ -237,13 +259,55 @@ function cloneDeep(value) {
   return root
 }
 
+function setValueByTokens(target, tokens, nextValue) {
+  if (!Array.isArray(tokens) || !tokens.length) return nextValue
+  if (!isObjectLike(target) && !Array.isArray(target)) return target
+
+  let current = target
+
+  for (let index = 0; index < tokens.length - 1; index += 1) {
+    if (current == null) return target
+    current = current[tokens[index]]
+  }
+
+  if (current == null) return target
+  current[tokens[tokens.length - 1]] = nextValue
+  return target
+}
+
+function deleteByTokens(target, tokens) {
+  if (!Array.isArray(tokens) || !tokens.length) return undefined
+  if (!isObjectLike(target) && !Array.isArray(target)) return target
+
+  let current = target
+  for (let index = 0; index < tokens.length - 1; index += 1) {
+    if (current == null) return target
+    current = current[tokens[index]]
+  }
+
+  if (current == null) return target
+
+  const last = tokens[tokens.length - 1]
+  if (Array.isArray(current) && typeof last === "number") {
+    current.splice(last, 1)
+  } else {
+    delete current[last]
+  }
+
+  return target
+}
+
 module.exports = {
   isObjectLike,
   isPlainObject,
   isTypedArray,
   tokenizePath,
+  stringifyPathTokens,
   getValueByPath,
+  getValueByTokens,
   createIteratee,
   cloneShallow,
   cloneDeep,
+  setValueByTokens,
+  deleteByTokens,
 }