@radio-garden/ditojs-utils 2.85.0-0.5067ad799

package/src/dataPath/getEntriesAtDataPath.js

@@ -0,0 +1,67 @@
+import { parseDataPath } from './parseDataPath.js'
+import { normalizeDataPath } from './normalizeDataPath.js'
+
+const NOT_FOUND = Symbol('NOT_FOUND')
+
+export function getEntriesAtDataPath(
+  obj,
+  path,
+  handleError = () => {
+    throw new Error(`Invalid path: ${path}`)
+  }
+) {
+  const parsedPath = parseDataPath(path)
+
+  const prefixEntries = (obj, index, getEntries) => {
+    const prefix = normalizeDataPath(parsedPath.slice(0, index))
+    return Object.entries(obj).reduce(
+      (map, [key, value]) => {
+        const pathKey = prefix ? `${prefix}/${key}` : key
+        for (const [path, val] of Object.entries(getEntries(value))) {
+          if (val !== NOT_FOUND) {
+            map[`${pathKey}/${path}`] = val
+          }
+        }
+        return map
+      },
+      {}
+    )
+  }
+
+  let index = 0
+  for (const part of parsedPath) {
+    if (obj && typeof obj === 'object') {
+      if (part in obj) {
+        obj = obj[part]
+        index++
+        continue
+      } else if (part === '*') {
+        // Support wildcards on arrays and objects
+        const pathNested = parsedPath.slice(index + 1)
+        return prefixEntries(
+          obj,
+          index,
+          value => getEntriesAtDataPath(value, pathNested, handleError)
+        )
+      } else if (part === '**') {
+        // Support wildcards on arrays and objects
+        const pathNested = parsedPath.slice(index + 1)
+        const pathSelf = parsedPath.slice(index)
+        return prefixEntries(
+          obj,
+          index,
+          value => ({
+            ...getEntriesAtDataPath(value, pathNested, () => NOT_FOUND),
+            ...getEntriesAtDataPath(value, pathSelf, () => NOT_FOUND)
+          })
+        )
+      }
+    }
+    const res = handleError?.(obj, part, index)
+    // Do not add `undefined` results to the resulting entries object.
+    return res !== undefined
+      ? { [normalizeDataPath(parsedPath)]: res }
+      : {}
+  }
+  return { [normalizeDataPath(parsedPath)]: obj }
+}

package/src/dataPath/getEntriesAtDataPath.test.js

@@ -0,0 +1,204 @@
+import { getEntriesAtDataPath } from './getEntriesAtDataPath.js'
+
+describe('getEntriesAtDataPath()', () => {
+  const data = {
+    object: {
+      array: [
+        null,
+        {
+          prop: 'expected'
+        }
+      ]
+    }
+  }
+
+  it('should return data at a given path in property access notation', () => {
+    expect(getEntriesAtDataPath(data, 'object.array[1].prop')).toStrictEqual({
+      'object/array/1/prop': 'expected'
+    })
+  })
+
+  it('should return data at a given JSON pointer path', () => {
+    expect(getEntriesAtDataPath(data, '/object/array/1/prop')).toStrictEqual({
+      'object/array/1/prop': 'expected'
+    })
+  })
+
+  it(`should return data at a given 'relative' JSON pointer path`, () => {
+    expect(getEntriesAtDataPath(data, 'object/array/1/prop')).toStrictEqual({
+      'object/array/1/prop': 'expected'
+    })
+  })
+
+  it('should throw an error with faulty paths', () => {
+    expect(() => getEntriesAtDataPath(data, 'object/unknown/prop'))
+      .toThrow('Invalid path: object/unknown/prop')
+  })
+
+  it('should throw an error with nullish objects', () => {
+    expect(() => getEntriesAtDataPath(null, 'object'))
+      .toThrow('Invalid path: object')
+  })
+
+  it('should support custom error handler', () => {
+    const handleError = (object, part, index) => `Error: ${part}, ${index}`
+    expect(getEntriesAtDataPath(data, 'object/unknown/prop', handleError))
+      .toStrictEqual({ 'object/unknown/prop': 'Error: unknown, 1' })
+  })
+
+  it('should handle non-existing paths with custom `handleError()`', () => {
+    const handleError = () => undefined
+    expect(getEntriesAtDataPath(data, 'object/unknown/prop', handleError))
+      .toStrictEqual({})
+  })
+
+  it('should return shallow wildcard matches', () => {
+    const data = {
+      object1: {
+        array: [
+          {
+            name: 'one',
+            array: [
+              { name: 'one.one' },
+              { name: 'one.two' }
+            ]
+          },
+          {
+            name: 'two',
+            array: [
+              { name: 'two.one' },
+              { name: 'two.two' }
+            ]
+          }
+        ]
+      },
+      object2: {
+        object: {
+          one: {
+            name: 'one',
+            object: {
+              one: { name: 'one.one' },
+              two: { name: 'one.two' }
+            }
+          },
+          two: {
+            name: 'two',
+            object: {
+              one: { name: 'two.one' },
+              two: { name: 'two.two' }
+            }
+          }
+        }
+      },
+      object3: {
+        array: [
+          {
+            one: { name: 'one.one' },
+            two: { name: 'one.two' }
+          },
+          {
+            one: { name: 'two.one' },
+            two: { name: 'two.two' }
+          }
+        ]
+      }
+    }
+
+    expect(getEntriesAtDataPath(data, 'object1/array/*/name'))
+      .toStrictEqual({
+        'object1/array/0/name': 'one',
+        'object1/array/1/name': 'two'
+      })
+    expect(getEntriesAtDataPath(data, 'object1.array[*].name'))
+      .toStrictEqual({
+        'object1/array/0/name': 'one',
+        'object1/array/1/name': 'two'
+      })
+    expect(getEntriesAtDataPath(data, 'object1/array/*/array/*/name'))
+      .toStrictEqual({
+        'object1/array/0/array/0/name': 'one.one',
+        'object1/array/0/array/1/name': 'one.two',
+        'object1/array/1/array/0/name': 'two.one',
+        'object1/array/1/array/1/name': 'two.two'
+      })
+    expect(getEntriesAtDataPath(data, 'object2/object/*/name'))
+      .toStrictEqual({
+        'object2/object/one/name': 'one',
+        'object2/object/two/name': 'two'
+      })
+    expect(getEntriesAtDataPath(data, 'object2/object/*/object/*/name'))
+      .toStrictEqual({
+        'object2/object/one/object/one/name': 'one.one',
+        'object2/object/one/object/two/name': 'one.two',
+        'object2/object/two/object/one/name': 'two.one',
+        'object2/object/two/object/two/name': 'two.two'
+      })
+    expect(getEntriesAtDataPath(data, 'object3/array/*/*/name'))
+      .toStrictEqual({
+        'object3/array/0/one/name': 'one.one',
+        'object3/array/0/two/name': 'one.two',
+        'object3/array/1/one/name': 'two.one',
+        'object3/array/1/two/name': 'two.two'
+      })
+  })
+
+  it('should return deep wildcard matches', () => {
+    const data = {
+      object: {
+        array: [
+          { name: 'one' },
+          { name: 'two' },
+          {
+            object: {
+              one: { name: 'three' },
+              two: { name: 'four' }
+            },
+            array: [
+              { name: 'five' },
+              { name: 'six' },
+              {
+                object: {
+                  one: { name: 'seven' },
+                  two: { name: 'eight' }
+                }
+              }
+            ]
+          }
+        ]
+      }
+    }
+
+    const expected = {
+      'object/array/0/name': 'one',
+      'object/array/1/name': 'two',
+      'object/array/2/object/one/name': 'three',
+      'object/array/2/object/two/name': 'four',
+      'object/array/2/array/0/name': 'five',
+      'object/array/2/array/1/name': 'six',
+      'object/array/2/array/2/object/one/name': 'seven',
+      'object/array/2/array/2/object/two/name': 'eight'
+    }
+
+    let result = getEntriesAtDataPath(data, '**/name')
+    expect(result).toEqual(expected)
+    expect(Object.values(result)).toEqual(Object.values(expected))
+
+    result = getEntriesAtDataPath(data, 'object/**/name')
+    expect(result).toEqual(expected)
+    expect(Object.values(result)).toEqual(Object.values(expected))
+
+    expect(getEntriesAtDataPath(data, 'object/**/array/**/name')).toEqual({
+      'object/array/2/array/0/name': 'five',
+      'object/array/2/array/1/name': 'six',
+      'object/array/2/array/2/object/one/name': 'seven',
+      'object/array/2/array/2/object/two/name': 'eight'
+    })
+
+    expect(getEntriesAtDataPath(data, 'object/**/object/**/name')).toEqual({
+      'object/array/2/object/one/name': 'three',
+      'object/array/2/object/two/name': 'four',
+      'object/array/2/array/2/object/one/name': 'seven',
+      'object/array/2/array/2/object/two/name': 'eight'
+    })
+  })
+})

package/src/dataPath/getValueAtDataPath.js

@@ -0,0 +1,45 @@
+import { isArray, asArray } from '../base/index.js'
+import { parseDataPath } from './parseDataPath.js'
+
+const NOT_FOUND = Symbol('NOT_FOUND')
+
+export function getValueAtDataPath(
+  obj,
+  path,
+  handleError = () => {
+    throw new Error(`Invalid path: ${path}`)
+  }
+) {
+  const parsedPath = parseDataPath(path)
+  let index = 0
+  for (const part of parsedPath) {
+    if (obj && typeof obj === 'object') {
+      if (part in obj) {
+        obj = obj[part]
+        index++
+        continue
+      } else if (part === '*') {
+        // Support wildcards on arrays and objects
+        const pathNested = parsedPath.slice(index + 1)
+        const values = isArray(obj) ? obj : Object.values(obj)
+        return values
+          .map(value => getValueAtDataPath(value, pathNested, handleError))
+          .flat(1)
+      } else if (part === '**') {
+        // Support deep wildcards on arrays and objects
+        const pathNested = parsedPath.slice(index + 1)
+        const pathSelf = parsedPath.slice(index)
+        const values = isArray(obj) ? obj : Object.values(obj)
+        return values
+          .map(value => [
+            ...asArray(getValueAtDataPath(value, pathNested, () => NOT_FOUND)),
+            ...asArray(getValueAtDataPath(value, pathSelf, () => NOT_FOUND))
+          ])
+          .flat(1)
+          .filter(value => value !== NOT_FOUND)
+      }
+    }
+    return handleError?.(obj, part, index)
+  }
+  return obj
+}

package/src/dataPath/getValueAtDataPath.test.js

@@ -0,0 +1,140 @@
+import { getValueAtDataPath } from './getValueAtDataPath.js'
+
+describe('getValueAtDataPath()', () => {
+  const data = {
+    object: {
+      array: [
+        null,
+        {
+          prop: 'expected'
+        }
+      ]
+    }
+  }
+
+  it('should return the root data for empty paths', () => {
+    expect(getValueAtDataPath(data, '')).toBe(data)
+  })
+
+  it('should return data at a given path in property access notation', () => {
+    expect(getValueAtDataPath(data, 'object.array[1].prop')).toBe('expected')
+  })
+
+  it('should return data at a given JSON pointer path', () => {
+    expect(getValueAtDataPath(data, '/object/array/1/prop')).toBe('expected')
+  })
+
+  it(`should return data at a given 'relative' JSON pointer path`, () => {
+    expect(getValueAtDataPath(data, 'object/array/1/prop')).toBe('expected')
+  })
+
+  it('should throw an error with faulty paths', () => {
+    expect(() => getValueAtDataPath(data, 'object/unknown/prop'))
+      .toThrow('Invalid path: object/unknown/prop')
+  })
+
+  it('should throw an error with nullish objects', () => {
+    expect(() => getValueAtDataPath(null, 'object'))
+      .toThrow('Invalid path: object')
+  })
+
+  it('should support custom error handler', () => {
+    const handleError = (object, part, index) => `Error: ${part}, ${index}`
+    expect(getValueAtDataPath(data, 'object/unknown/prop', handleError))
+      .toBe('Error: unknown, 1')
+  })
+
+  it('should return shallow wildcard matches', () => {
+    const data = {
+      object1: {
+        array: [
+          { name: 'one' },
+          { name: 'two' }
+        ]
+      },
+      object2: {
+        object: {
+          one: { name: 'one' },
+          two: { name: 'two' }
+        }
+      }
+    }
+
+    expect(getValueAtDataPath(data, 'object1/array/*/name'))
+      .toEqual(['one', 'two'])
+    expect(getValueAtDataPath(data, 'object1.array[*].name'))
+      .toEqual(['one', 'two'])
+    expect(getValueAtDataPath(data, 'object2/object/*/name'))
+      .toEqual(['one', 'two'])
+    expect(getValueAtDataPath(data, 'object2.object[*].name'))
+      .toEqual(['one', 'two'])
+    expect(getValueAtDataPath(data, '*/*/*'))
+      .toEqual([
+        { name: 'one' },
+        { name: 'two' },
+        { name: 'one' },
+        { name: 'two' }
+      ])
+    expect(getValueAtDataPath(data, '*/*/*/name'))
+      .toEqual(['one', 'two', 'one', 'two'])
+
+    expect(getValueAtDataPath(data, '**/name'))
+      .toEqual(['one', 'two', 'one', 'two'])
+  })
+
+  it('should return deep wildcard matches', () => {
+    const data = {
+      object: {
+        object: {
+          array: [
+            { name: 'one' },
+            { name: 'two' },
+            {
+              object: {
+                one: { name: 'three' },
+                two: { name: 'four' }
+              },
+              array: [
+                { name: 'five' },
+                { name: 'six' },
+                {
+                  object: {
+                    one: { name: 'seven' },
+                    two: { name: 'eight' }
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      }
+    }
+
+    expect(getValueAtDataPath(data, 'object/**/name'))
+      .toEqual(['one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight'])
+
+    expect(getValueAtDataPath(data, 'object/**/object/one/name'))
+      .toEqual(['three', 'seven'])
+
+    expect(getValueAtDataPath(data, 'object/**/object/two/name'))
+      .toEqual(['four', 'eight'])
+
+    expect(getValueAtDataPath(data, 'object/**/array/0/name'))
+      .toEqual(['one', 'five'])
+
+    expect(getValueAtDataPath(data, 'object/**/array/1/name'))
+      .toEqual(['two', 'six'])
+
+    expect(getValueAtDataPath(data, 'object/**/object'))
+      .toEqual([
+        {
+          one: { name: 'three' },
+          two: { name: 'four' }
+        },
+        {
+          one: { name: 'seven' },
+          two: { name: 'eight' }
+        }
+      ])
+  })
+})

package/src/dataPath/index.js

@@ -0,0 +1,6 @@
+export * from './getEntriesAtDataPath.js'
+export * from './getValueAtDataPath.js'
+export * from './normalizeDataPath.js'
+export * from './parseDataPath.js'
+export * from './setDataPathEntries.js'
+export * from './setValueAtDataPath.js'

package/src/dataPath/normalizeDataPath.js

@@ -0,0 +1,27 @@
+import { parseDataPath } from './parseDataPath.js'
+
+export function normalizeDataPath(path) {
+  path = parseDataPath(path)
+  // Normalize relative tokens and concatenated absolute paths.
+  for (let i = 0; i < path.length; i++) {
+    const token = path[i]
+    if (token === '.' || token === '..' && i === 0) {
+      path.splice(i, 1)
+      i--
+    } else if (token === '..') {
+      path.splice(--i, 2)
+      i--
+    } else if (token === '') {
+      if (i === path.length - 1) {
+        // Remove trailing slash
+        path.splice(i, 1)
+      } else {
+        // The beginning of a concatenated absolute path:
+        // Start from scratch, see `parseDataPath.test.js`
+        path.splice(0, i + 1)
+        i = 0
+      }
+    }
+  }
+  return path.join('/')
+}

package/src/dataPath/normalizeDataPath.test.js

@@ -0,0 +1,36 @@
+import { normalizeDataPath } from './normalizeDataPath.js'
+
+describe('normalizeDataPath()', () => {
+  it('should normalize JSON pointers', () => {
+    expect(normalizeDataPath('/object/array/1/prop'))
+      .toStrictEqual('object/array/1/prop')
+  })
+
+  it('should normalize property access notation', () => {
+    const expected = 'object/array/1/prop'
+    expect(normalizeDataPath('.object.array[1].prop')).toStrictEqual(expected)
+    expect(normalizeDataPath('.object["array"][1].prop'))
+      .toStrictEqual(expected)
+    expect(normalizeDataPath(`['object']['array'][1]['prop']`))
+      .toStrictEqual(expected)
+  })
+
+  it('should normalize relative tokens', () => {
+    expect(normalizeDataPath('/object/property1/..'))
+      .toStrictEqual('object')
+    expect(normalizeDataPath('/object/property1/../'))
+      .toStrictEqual('object')
+    expect(normalizeDataPath('/object/property1/../value'))
+      .toStrictEqual('object/value')
+    expect(normalizeDataPath('/object/property1/../value/'))
+      .toStrictEqual('object/value')
+    expect(normalizeDataPath('/object/property1/../property2/../value'))
+      .toStrictEqual('object/value')
+    expect(normalizeDataPath('/object/property1/property2/../../value'))
+      .toStrictEqual('object/value')
+    expect(normalizeDataPath('/object/property1//object/value'))
+      .toStrictEqual('object/value')
+    expect(normalizeDataPath('/object1/object2/./object3/value'))
+      .toStrictEqual('object1/object2/object3/value')
+  })
+})

package/src/dataPath/parseDataPath.js

@@ -0,0 +1,16 @@
+import { isArray, isString } from '../base/index.js'
+
+export function parseDataPath(path) {
+  if (isArray(path)) {
+    return [...path] // Alway return new arrays (clones).
+  } else if (isString(path)) {
+    if (!path) return []
+    const str = path
+      // Convert from JavaScript property access notation to JSON pointers,
+      // while preserving '..' in paths:
+      .replace(/\.([^./]+)/g, '/$1')
+      // Expand array property access notation ([])
+      .replace(/\[['"]?([^'"\]]*)['"]?\]/g, '/$1')
+    return /^\//.test(str) ? str.slice(1).split('/') : str.split('/')
+  }
+}

package/src/dataPath/parseDataPath.test.js

@@ -0,0 +1,67 @@
+import { parseDataPath } from './parseDataPath.js'
+
+describe('parseDataPath()', () => {
+  it('should parse JSON pointers', () => {
+    expect(parseDataPath('/object/array/1/prop'))
+      .toStrictEqual(['object', 'array', '1', 'prop'])
+  })
+
+  it('should parse property access notation', () => {
+    const expected = ['object', 'array', '1', 'prop']
+    expect(parseDataPath('.object.array[1].prop')).toStrictEqual(expected)
+    expect(parseDataPath(`.object["array"][1].prop`)).toStrictEqual(expected)
+    expect(parseDataPath(`['object']['array'][1]['prop']`))
+      .toStrictEqual(expected)
+  })
+
+  it(`should parse 'relative' JSON pointers`, () => {
+    expect(parseDataPath('object/array/1/prop'))
+      .toStrictEqual(['object', 'array', '1', 'prop'])
+  })
+
+  it(`should parse 'relative' property access notation`, () => {
+    expect(parseDataPath('object.array[1].prop'))
+      .toStrictEqual(['object', 'array', '1', 'prop'])
+  })
+
+  it('should parse relative and absolute tokens', () => {
+    expect(parseDataPath('/object/property1/../property2/../value'))
+      .toStrictEqual(['object', 'property1', '..', 'property2', '..', 'value'])
+    expect(parseDataPath('../object/value'))
+      .toStrictEqual(['..', 'object', 'value'])
+    expect(parseDataPath('./object/value'))
+      .toStrictEqual(['.', 'object', 'value'])
+    // This happens when concatenating a data path with another absolute one, an
+    // empty space will be interpreted as "start from scratch" when normalizing.
+    expect(parseDataPath('//object/value'))
+      .toStrictEqual(['', 'object', 'value'])
+  })
+
+  it('should handle white-space in JSON pointers', () => {
+    expect(parseDataPath('/object/property name'))
+      .toStrictEqual(['object', 'property name'])
+  })
+
+  it('should handle white-space in property access notation', () => {
+    const expected = ['object', 'property name']
+    expect(parseDataPath(`.object["property name"]`)).toStrictEqual(expected)
+    expect(parseDataPath(`.object['property name']`)).toStrictEqual(expected)
+  })
+
+  it('should return a clone if argument is already an array', () => {
+    const array = ['object', 'array', '1']
+    const actual = parseDataPath(array)
+    expect(actual).toStrictEqual(array)
+    expect(actual).not.toBe(array)
+  })
+
+  it('should return undefined for values other than array / string', () => {
+    expect(parseDataPath({})).toBe(undefined)
+    expect(parseDataPath(false)).toBe(undefined)
+    expect(parseDataPath(10)).toBe(undefined)
+  })
+
+  it('should parse an empty string to an empty array', () => {
+    expect(parseDataPath('')).toStrictEqual([])
+  })
+})

package/src/dataPath/setDataPathEntries.js

@@ -0,0 +1,8 @@
+import { setValueAtDataPath } from './setValueAtDataPath.js'
+
+export function setDataPathEntries(obj, entries) {
+  for (const [path, value] of Object.entries(entries)) {
+    setValueAtDataPath(obj, path, value)
+  }
+  return obj
+}

package/src/dataPath/setDataPathEntries.test.js

@@ -0,0 +1,36 @@
+import { setDataPathEntries } from './setDataPathEntries.js'
+
+describe('setDataPathEntries()', () => {
+  const data = {
+    object: {
+      array: [
+        {}
+      ],
+      number: 10
+    }
+  }
+
+  const add = { prop: 'new' }
+
+  it('should add data at a path to a given object and array', () => {
+    expect(() =>
+      setDataPathEntries(data, {
+        'object.array[0].added': add,
+        'object.array[1]': add
+      })
+    )
+      .not.toThrow()
+    expect(data.object.array[0].added).toStrictEqual(add)
+    expect(data.object.array[1]).toStrictEqual(add)
+  })
+
+  it('should throw an error with faulty paths', () => {
+    expect(() => setDataPathEntries(data, { 'object/unknown/prop': add }))
+      .toThrow()
+  })
+
+  it('should throw an error with invalid target', () => {
+    expect(() => setDataPathEntries(data, { 'object/number/invalid': add }))
+      .toThrow('Invalid path: object/number/invalid')
+  })
+})

package/src/dataPath/setValueAtDataPath.js

@@ -0,0 +1,13 @@
+import { parseDataPath } from './parseDataPath.js'
+import { getValueAtDataPath } from './getValueAtDataPath.js'
+
+export function setValueAtDataPath(obj, path, value) {
+  const parts = parseDataPath(path)
+  const last = parts.pop()
+  const dest = getValueAtDataPath(obj, parts)
+  if (!(dest && typeof dest === 'object')) {
+    throw new Error(`Invalid path: ${path}`)
+  }
+  dest[last] = value
+  return obj
+}