feat(stringtopath): add util to convert string to a property path array

src/isSymbol.ts

@@ -9,7 +9,7 @@ import { getTag } from './getTag';
  * @returns {boolean} Returns `true` if `value` is a symbol, else `false`.
  * @example
  *
- * isSymbol(Symbol.iterator)
+ * isSymbol(Symbol())
  * // => true
  *
  * isSymbol('abc')

src/stringToPath.test.ts

@@ -0,0 +1,17 @@
+import { stringToPath } from './stringToPath';
+
+describe('stringToPath', () => {
+  it("should match anything that isn't a dot or bracket", () => {
+    expect(stringToPath('hi')).toEqual(['hi']);
+    expect(stringToPath('attribute?')).toEqual(['attribute?']);
+  });
+  it('should match property names within brackets', () => {
+    expect(stringToPath('first[second].third')).toEqual([
+      'first',
+      'second',
+      'third'
+    ]);
+    expect(stringToPath('first[].third')).toEqual(['first', '', 'third']);
+    expect(stringToPath("first['second\x02]")).toEqual(['first', 'second']);
+  });
+});

src/stringToPath.ts

@@ -0,0 +1,54 @@
+import { memoizeCapped } from './memoizeCapped';
+
+const charCodeOfDot = '.'.charCodeAt(0);
+const reEscapeChar = /\\(\\)?/g;
+const rePropName = RegExp(
+  // Match anything that isn't a dot or bracket.
+  '[^.[\\]]+' +
+    '|' +
+    // Or match property names within brackets.
+    '\\[(?:' +
+    // Match a non-string expression.
+    '([^"\'][^[]*)' +
+    '|' +
+    // Or match strings (supports escaping characters).
+    '(["\'])((?:(?!\\x02)[^\\\\]|\\\\.)*?)\\x02' +
+    ')\\]' +
+    '|' +
+    // Or match "" as the space between consecutive dots or empty brackets.
+    '(?=(?:\\.|\\[\\])(?:\\.|\\[\\]|$))',
+  'g'
+);
+
+/**
+ * Converts `string` to a property path array.
+ *
+ * @private
+ * @param {string} string The string to convert.
+ * @returns {Array} Returns the property path array.
+ */
+export const stringToPath = memoizeCapped((string: string) => {
+  const result = [];
+  if (string.charCodeAt(0) === charCodeOfDot) {
+    result.push('');
+  }
+  string.replace(
+    rePropName,
+    (
+      match: string,
+      expression: string,
+      quote: string,
+      subString: string
+    ): string => {
+      let key = match;
+      if (quote) {
+        key = subString.replace(reEscapeChar, '$1');
+      } else if (expression) {
+        key = expression.trim();
+      }
+      result.push(key);
+      return '';
+    }
+  );
+  return result;
+});

src/toKey.ts

@@ -9,6 +9,13 @@ const INFINITY = 1 / 0;
  * @private
  * @param {*} value The value to inspect.
  * @returns {string|symbol} Returns the key.
+ * @example
+ *
+ * toKey(Symbol.iterator)
+ * // => true
+ *
+ * toKey('abc')
+ * // => false
  */
 export function toKey(value: any): string | symbol {
   if (typeof value === 'string' || isSymbol(value)) {