@squiz/dx-common-lib 1.21.1-alpha.9 → 1.22.0

package/src/json-order/order.spec.ts

@@ -0,0 +1,251 @@
+import order from './order';
+import { PropertyMap } from './models';
+
+describe('order()', () => {
+  const expectObject = <T extends object>(obj: T, map: PropertyMap | null, res: string) =>
+    expect(JSON.stringify(order(obj, map, '.'))).toBe(res);
+
+  it('returns nothing for a blank JSON string', () => expectObject({}, {}, '{}'));
+
+  it('throws error if separator is an empty string', () => {
+    expect(() => order({}, {}, '')).toThrowError('Separator should not be an empty string.');
+  });
+
+  it('throws error if separator is a slash', () => {
+    expect(() => order({}, {}, '\\')).toThrowError('Separator cannot be "\\".');
+  });
+
+  it('ignores properties not found in source', () => expectObject({}, { $: ['a'] }, '{}'));
+
+  it('returns regular json string if map is undefined', () =>
+    expectObject({ a: '1', b: '2' }, null, '{"a":"1","b":"2"}'));
+
+  it('ignores properties not found in map', () => expectObject({ a: '1', b: '2' }, { $: ['b'] }, '{"b":"2"}'));
+
+  it('returns first level object properties in order', () =>
+    expectObject({ a: 2, b: 1 }, { $: ['b', 'a'] }, '{"b":1,"a":2}'));
+
+  it('returns first level array value in order', () =>
+    expectObject({ a: ['2', 1, true] }, { $: ['a'] }, '{"a":["2",1,true]}'));
+
+  it('returns nested [array] > [object] properties in expected order', () =>
+    expectObject({ a: [1, { c: '3', d: '2' }] }, { $: ['a'], '$.a.1': ['d', 'c'] }, '{"a":[1,{"d":"2","c":"3"}]}'));
+
+  it('ignores nested [array] > [object] properties partially not found in map', () =>
+    expectObject({ a: [1, { b: 2, c: 3 }, 4] }, { $: ['a'], '$.a.1': ['c'] }, '{"a":[1,{"c":3},4]}'));
+
+  it('ignores nested [array] > [object] properties not found in map', () =>
+    expectObject({ a: [1, { b: 2, c: 3 }, 4] }, { $: ['a'] }, '{"a":[1,{},4]}'));
+
+  it('handles multi-character prefix', () => {
+    expect(
+      order(
+        {
+          a: {
+            b: {
+              c: 3,
+              d: 4,
+            },
+            e: {
+              f: 4,
+              g: 5,
+            },
+            h: 6,
+          },
+          i: 7,
+        },
+        {
+          ab: ['i', 'a'],
+          'ab.a': ['e', 'h', 'b'],
+          'ab.a.e': ['g', 'f'],
+          'ab.a.b': ['d', 'c'],
+        },
+        '.',
+      ),
+    ).toEqual({ i: 7, a: { e: { g: 5, f: 4 }, h: 6, b: { d: 4, c: 3 } } });
+  });
+
+  it('handles multi-character separator', () => {
+    expect(
+      order(
+        {
+          a: {
+            b: {
+              c: 3,
+              d: 4,
+            },
+            e: {
+              f: 4,
+              g: 5,
+            },
+            h: 6,
+          },
+          i: 7,
+        },
+        {
+          $: ['i', 'a'],
+          '$~|a': ['e', 'h', 'b'],
+          '$~|a~|e': ['g', 'f'],
+          '$~|a~|b': ['d', 'c'],
+        },
+        '~|',
+      ),
+    ).toEqual({ i: 7, a: { e: { g: 5, f: 4 }, h: 6, b: { d: 4, c: 3 } } });
+  });
+
+  it('returns nested [object] > [object] properties in expected order', () =>
+    expectObject(
+      {
+        a: {
+          b: {
+            c: 3,
+            d: 4,
+          },
+          e: {
+            f: 4,
+            g: 5,
+          },
+          h: 6,
+        },
+        i: 7,
+      },
+      {
+        $: ['i', 'a'],
+        '$.a': ['e', 'h', 'b'],
+        '$.a.e': ['g', 'f'],
+        '$.a.b': ['d', 'c'],
+      },
+      '{"i":7,"a":{"e":{"g":5,"f":4},"h":6,"b":{"d":4,"c":3}}}',
+    ));
+
+  it('returns nested [object] > [array] > [object] > [array] > [object] properties in expected order', () =>
+    expectObject(
+      {
+        a: {
+          b: [
+            8,
+            {
+              c: 9,
+              d: [
+                {
+                  e: 12,
+                  f: {
+                    g: true,
+                    h: 'h',
+                  },
+                },
+                10,
+              ],
+            },
+            11,
+          ],
+        },
+        i: 7,
+      },
+      {
+        $: ['i', 'a'],
+        '$.a': ['b'],
+        '$.a.b.1': ['d', 'c'],
+        '$.a.b.1.d.0': ['f', 'e'],
+        '$.a.b.1.d.0.f': ['h', 'g'],
+      },
+      '{"i":7,"a":{"b":[8,{"d":[{"f":{"h":"h","g":true},"e":12},10],"c":9},11]}}',
+    ));
+
+  it('handles keys with no name', () => {
+    expectObject(
+      {
+        '': {
+          b: 'str',
+          a: 'str',
+          c: 'str',
+        },
+      },
+      {
+        $: [''],
+        '$.': ['c', 'b', 'a'],
+      },
+      '{"":{"c":"str","b":"str","a":"str"}}',
+    );
+  });
+
+  it('handles escape sequences in the object', () => {
+    expectObject(
+      {
+        '.a': {
+          b: { t: 'str' },
+          c: { u: 'str' },
+          a: { s: 'str' },
+        },
+        '\\': {
+          a: { v: 'str' },
+        },
+        '\\.': {
+          a: { w: 'str' },
+          b: { x: 'str' },
+        },
+        '.': {
+          b: { y: 'str' },
+          a: { z: 'str' },
+        },
+      },
+      {
+        $: ['.', '\\.', '\\', '.a'],
+        '$.\\.': ['a', 'b'],
+        '$.\\..a': ['z'],
+        '$.\\..b': ['y'],
+        '$.\\\\\\.': ['b', 'a'],
+        '$.\\\\\\..b': ['x'],
+        '$.\\\\\\..a': ['w'],
+        '$.\\\\': ['a'],
+        '$.\\\\.a': ['v'],
+        '$.\\.a': ['c', 'b', 'a'],
+        '$.\\.a.c': ['u'],
+        '$.\\.a.b': ['t'],
+        '$.\\.a.a': ['s'],
+      },
+      '{".":{"a":{"z":"str"},"b":{"y":"str"}},' +
+        '"\\\\.":{"b":{"x":"str"},"a":{"w":"str"}},' +
+        '"\\\\":{"a":{"v":"str"}},' +
+        '".a":{"c":{"u":"str"},"b":{"t":"str"},"a":{"s":"str"}}}',
+    );
+  });
+
+  it('handles escape sequences in child properties of the object', () => {
+    expectObject(
+      {
+        property: {
+          '..': { '.': 4, '..': 3 },
+          '.': { '..': 0, '...': 2, '.': 1 },
+          '...': { '.': 5 },
+        },
+      },
+      {
+        $: ['property'],
+        '$.property': ['.', '..', '...'],
+        '$.property.\\.': ['..', '.', '...'],
+        '$.property.\\.\\.': ['..', '.'],
+        '$.property.\\.\\.\\.': ['.'],
+      },
+      '{"property":{".":{"..":0,".":1,"...":2},"..":{"..":3,".":4},"...":{".":5}}}',
+    );
+  });
+
+  it('numeric key order defined in map is lost', () => {
+    // Numeric keys aren't ordered per map but instead appear first in ascending order.
+    // See: https://tc39.es/ecma262/#sec-ordinaryownpropertykeys
+    expectObject(
+      {
+        4: 'str',
+        a: 'str',
+        3: 'str',
+        b: 'str',
+        2: 'str',
+      },
+      {
+        $: ['a', '4', 'b', '3', '2'],
+      },
+      '{"2":"str","3":"str","4":"str","a":"str","b":"str"}',
+    );
+  });
+});

package/src/json-order/order.ts

@@ -0,0 +1,95 @@
+import clonedeep from 'lodash.clonedeep';
+import { escapeKey, splitKey } from './key';
+import { PropertyMap } from './models';
+
+interface GetResult {
+  exists: boolean;
+  value: object;
+}
+
+const getProperty = (obj: object, key: string, separator: string): GetResult => {
+  let exists = true;
+
+  const value = splitKey(key, separator)
+    .slice(1)
+    .reduce((o: Record<string, any>, x: string) => {
+      exists = o && x in o;
+
+      if (!exists) {
+        return undefined;
+      }
+
+      return o[x];
+    }, obj);
+
+  return { exists, value };
+};
+
+const setProperty = (obj: object, key: string, value: object, separator: string) => {
+  splitKey(key, separator)
+    .slice(1)
+    .reduce((o: Record<string, any>, x: string, idx: number, src: Array<string>): object => {
+      if (idx === src.length - 1) {
+        const valueToSet = Array.isArray(value) ? clonedeep(value).map((p) => (typeof p === 'object' ? {} : p)) : value;
+        o[x] = valueToSet;
+      }
+
+      return o[x];
+    }, obj);
+};
+
+const copyProperty = (sourceObject: object, resultObject: object, propertyPath: string, separator: string) => {
+  const result = getProperty(sourceObject, propertyPath, separator);
+  if (result.exists) {
+    setProperty(resultObject, propertyPath, result.value, separator);
+  }
+};
+
+/**
+ * Duplicate a JS object but containing a particular property order
+ *
+ * @param sourceObject an object with the properties in any order
+ * @param map the `PropertyMap` generated by the `parse` method
+ * @param separator a non-empty `string` that controls what the key separator is in the generated map. Defaults to `~`.
+ * @returns the source object ordered as per the map
+ */
+const order = <T extends object>(sourceObject: T, map: PropertyMap | null, separator = '~'): T => {
+  if (separator.length < 1) {
+    throw new Error('Separator should not be an empty string.');
+  } else if (separator === '\\') {
+    throw new Error('Separator cannot be "\\".');
+  }
+
+  if (!map) {
+    return sourceObject;
+  }
+
+  const mapKeys = Object.keys(map);
+  const prefixLength = (mapKeys[0] && mapKeys[0].length) || 0;
+
+  const resultObject = {};
+  mapKeys.forEach((mk) => {
+    const childKeys = map[mk];
+
+    // Remove prefix
+    const parentKey = mk.substr(prefixLength);
+
+    const parent = getProperty(sourceObject, parentKey, separator);
+
+    if (parent.exists) {
+      // Set a default value for the property
+      const defaultValue = Array.isArray(parent.value) ? parent.value : {};
+
+      setProperty(resultObject, parentKey, defaultValue, separator);
+
+      // Fetch value from source and set on output
+      childKeys.forEach((key) =>
+        copyProperty(sourceObject, resultObject, `${parentKey}${separator}${escapeKey(key, separator)}`, separator),
+      );
+    }
+  });
+
+  return resultObject as T;
+};
+
+export default order;

package/src/json-order/parse.spec.ts

@@ -0,0 +1,302 @@
+import { PropertyMap } from './models';
+import parse from './parse';
+
+describe('parse ', () => {
+  const expectMap = (input: string, map: PropertyMap) => expect(parse(input, '$', '.').map).toEqual(map);
+
+  it('returns nothing for a blank JSON string', () => expectMap('{}', {}));
+
+  it('throws error if prefix is an empty string', () => {
+    expect(() => parse('', '', '.')).toThrowError('Prefix should not be an empty string.');
+  });
+
+  it('throws error if separator is an empty string', () => {
+    expect(() => parse('', '$', '')).toThrowError('Separator should not be an empty string.');
+  });
+
+  it('throws error if separator is a slash', () => {
+    expect(() => parse('', '$', '\\')).toThrowError('Separator cannot be "\\".');
+  });
+
+  it('handles top level values for of primitive types', () => {
+    const input = `
+    {
+      "b": "str",
+      "c": 3,
+      "a": true
+    }`;
+
+    const map = {
+      $: ['b', 'c', 'a'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles top level values of type [object]', () => {
+    const input = `
+    {
+      "a": {
+        "az": "str",
+        "ay": "str"
+      }
+    }`;
+
+    const map = {
+      $: ['a'],
+      '$.a': ['az', 'ay'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles top level values of a blank [object]', () => {
+    const input = `
+    {
+      "a": { }
+    }`;
+
+    const map = {
+      $: ['a'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles multi-character prefix', () => {
+    const input = `
+    {
+      "a": {
+        "a2": {
+          "b": "str"
+        },
+        "a1": {
+          "d": 2,
+          "c": false
+        }
+      }
+    }`;
+
+    const map = {
+      ab: ['a'],
+      'ab.a': ['a2', 'a1'],
+      'ab.a.a2': ['b'],
+      'ab.a.a1': ['d', 'c'],
+    };
+
+    expect(parse(input, 'ab', '.').map).toEqual(map);
+  });
+
+  it('handles multi-character separator', () => {
+    const input = `
+    {
+      "a": {
+        "a2": {
+          "b": "str"
+        },
+        "a1": {
+          "d": 2,
+          "c": false
+        }
+      }
+    }`;
+
+    const map = {
+      $: ['a'],
+      '$~|a': ['a2', 'a1'],
+      '$~|a~|a2': ['b'],
+      '$~|a~|a1': ['d', 'c'],
+    };
+
+    expect(parse(input, '$', '~|').map).toEqual(map);
+  });
+
+  it('handles nesting [object] > [object]', () => {
+    const input = `
+    {
+      "a": {
+        "a2": {
+          "b": "str"
+        },
+        "a1": {
+          "d": 2,
+          "c": false
+        }
+      }
+    }`;
+
+    const map = {
+      $: ['a'],
+      '$.a': ['a2', 'a1'],
+      '$.a.a2': ['b'],
+      '$.a.a1': ['d', 'c'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('should not return mappings for primitive elements of an [array]', () => {
+    const input = `
+    {
+      "a": [1, "2", "three"]
+    }`;
+
+    const map = {
+      $: ['a'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles nesting [array] > [array]', () => {
+    const input = `
+    {
+      "a": [1, "two", [ 3, "four", true]]
+    }`;
+
+    const map = {
+      $: ['a'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles nesting [array] > [object]', () => {
+    const input = `
+    {
+      "a": [1, "two", {
+        "b": "str"
+      }]
+    }`;
+
+    const map = {
+      $: ['a'],
+      '$.a.2': ['b'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles nesting [array] > [array] > [object]', () => {
+    const input = `
+    {
+      "c": [1, "two", [3, {
+        "b": "str"
+      }, 4], {
+        "a": "str"
+      }]
+    }`;
+
+    const map = {
+      $: ['c'],
+      '$.c.2.1': ['b'],
+      '$.c.3': ['a'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles nesting [array] > [array] > [object] > [array] > [object]', () => {
+    const input = `
+    {
+      "d": [
+        1, "two", [
+          3, {
+            "c": "str",
+            "b": [4, {
+              "a": "str"
+            }]
+          }
+        ]
+      ]
+    }`;
+
+    const map = {
+      $: ['d'],
+      '$.d.2.1': ['c', 'b'],
+      '$.d.2.1.b.1': ['a'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles keys with no name', () => {
+    const input = `
+    {
+      "": {
+        "c": "str",
+        "b": "str",
+        "a": "str"
+      }
+    }`;
+
+    const map = {
+      $: [''],
+      '$.': ['c', 'b', 'a'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('escapes slashes as well as the separator when it exists in the object keys', () => {
+    // slashes in the encoded JSON are double escapes, so "\\\\" is actually equivalent to "\".
+    const input = `
+    {
+      ".": {
+        "a": {"z": "str"},
+        "b": {"y": "str"}
+      },
+      "\\\\.": {
+        "b": {"x": "str"},
+        "a": {"w": "str"}
+      },
+      "\\\\": {
+        "a": {"v": "str"}
+      },
+      ".a": {
+        "c": {"u": "str"},
+        "b": {"t": "str"},
+        "a": {"s": "str"}
+      }
+    }`;
+
+    // all below slashes are escaped so "\\" is actually equivalent to "\".
+    const map = {
+      $: ['.', '\\.', '\\', '.a'],
+      '$.\\.': ['a', 'b'],
+      '$.\\..a': ['z'],
+      '$.\\..b': ['y'],
+      '$.\\\\\\.': ['b', 'a'],
+      '$.\\\\\\..b': ['x'],
+      '$.\\\\\\..a': ['w'],
+      '$.\\\\': ['a'],
+      '$.\\\\.a': ['v'],
+      '$.\\.a': ['c', 'b', 'a'],
+      '$.\\.a.c': ['u'],
+      '$.\\.a.b': ['t'],
+      '$.\\.a.a': ['s'],
+    };
+
+    expectMap(input, map);
+  });
+
+  it('handles keys with different types of values', () => {
+    const input = `
+    {
+      "a": "a",
+      "b": 2,
+      "c": 2.3,
+      "d": true,
+      "e": false,
+      "f": null,
+      "g": {},
+      "h": []
+    }`;
+
+    const map = {
+      $: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'],
+    };
+
+    expectMap(input, map);
+  });
+});

package/src/json-order/parse.ts

@@ -0,0 +1,59 @@
+import { escapeKey } from './key';
+import { OrderedParseResult, PropertyMap } from './models';
+
+const traverseObject = <T extends Record<string, any>>(
+  obj: T,
+  map: PropertyMap,
+  parentKey: string,
+  separator: string,
+) => {
+  const childKeys = Object.keys(obj);
+
+  if (childKeys.length === 0) {
+    return;
+  }
+
+  // Ignore storing keys for arrays
+  if (!Array.isArray(obj)) {
+    map[`${parentKey}`] = childKeys;
+  }
+
+  childKeys.forEach((childKey) => {
+    const value = obj[childKey];
+
+    if (value !== null && typeof value === 'object') {
+      traverseObject(value, map, `${parentKey}${separator}${escapeKey(childKey, separator)}`, separator);
+    }
+  });
+};
+
+/**
+ * Parse a JSON string and generate a map
+ *
+ * @param jsonString a json string
+ * @param prefix a non-empty `string` that controls what the key prefix value is in the generated map. Defaults to `$`.
+ * @param separator a non-empty `string` that controls what the key separator is in the generated map. Defaults to `~`.
+ * @returns an object containing the parsed `object: T` and the `map: PropertyMap`
+ */
+const parse = <T extends object>(jsonString: string, prefix = '$', separator = '~'): OrderedParseResult<T> => {
+  if (prefix.length < 1) {
+    throw new Error('Prefix should not be an empty string.');
+  }
+
+  if (separator.length < 1) {
+    throw new Error('Separator should not be an empty string.');
+  } else if (separator === '\\') {
+    throw new Error('Separator cannot be "\\".');
+  }
+
+  const obj: T = JSON.parse(jsonString);
+
+  const map = {};
+  traverseObject(obj, map, escapeKey(prefix, separator), separator);
+  return {
+    object: obj,
+    map,
+  };
+};
+
+export default parse;