⚡ simplify key parsing and enhance numeric entity interpretation

Author: techouse

lib/src/extensions/decode.dart

@@ -1,13 +1,8 @@
 part of '../qs.dart';
 
-extension _$Decode on QS {
-  static String _interpretNumericEntities(String str) => str.replaceAllMapped(
-        RegExp(r'&#(\d+);'),
-        (Match match) => String.fromCharCode(
-          int.parse(match.group(1)!),
-        ),
-      );
+final RegExp _dotToBracket = RegExp(r'\.([^.\[]+)');
 
+extension _$Decode on QS {
   static dynamic _parseListValue(
     dynamic val,
     DecodeOptions options,
@@ -117,7 +112,7 @@ extension _$Decode on QS {
           !Utils.isEmpty(val) &&
           options.interpretNumericEntities &&
           charset == latin1) {
-        val = _interpretNumericEntities(
+        val = Utils.interpretNumericEntities(
           val is Iterable
               ? val.map((e) => e.toString()).join(',')
               : val.toString(),
@@ -213,60 +208,91 @@ extension _$Decode on QS {
   static dynamic _parseKeys(
     String? givenKey,
     dynamic val,
-    DecodeOptions options,
-    bool valuesParsed,
-  ) {
-    if (givenKey?.isEmpty ?? true) {
-      return;
-    }
+    DecodeOptions options, [
+    bool valuesParsed = false,
+  ]) {
+    if (givenKey == null || givenKey.isEmpty) return null;
 
-    // Transform dot notation to bracket notation
-    String key = options.allowDots
-        ? givenKey!.replaceAllMapped(
-            RegExp(r'\.([^.[]+)'),
-            (Match match) => '[${match[1]}]',
-          )
-        : givenKey!;
-
-    // The regex chunks
-    final RegExp brackets = RecursiveRegex(
-      startDelimiter: '[',
-      endDelimiter: ']',
+    final segments = _splitKeyIntoSegments(
+      originalKey: givenKey,
+      allowDots: options.allowDots,
+      maxDepth: options.depth,
+      strictDepth: options.strictDepth,
     );
 
-    // Get the parent
-    Match? segment = options.depth > 0 ? brackets.firstMatch(key) : null;
-    final String parent = segment != null ? key.slice(0, segment.start) : key;
+    return _parseObject(segments, val, options, valuesParsed);
+  }
 
-    // Stash the parent if it exists
-    final List<String> keys = [];
-    if (parent.isNotEmpty) {
-      keys.add(parent);
+  static List<String> _splitKeyIntoSegments({
+    required String originalKey,
+    required bool allowDots,
+    required int maxDepth,
+    required bool strictDepth,
+  }) {
+    final key = allowDots
+        ? originalKey.replaceAllMapped(_dotToBracket, (m) => '[${m[1]}]')
+        : originalKey;
+
+    // Depth=0: do not split and do not throw (qs semantics)
+    if (maxDepth <= 0) {
+      return <String>[key];
     }
 
-    // Loop through children appending to the array until we hit depth
-    int i = 0;
-    while (options.depth > 0 &&
-        (segment = brackets.firstMatch(key)) != null &&
-        i < options.depth) {
-      i += 1;
-      if (segment != null) {
-        keys.add(segment.group(0)!);
-        // Update the key to start searching from the next position
-        key = key.slice(segment.end);
+    final segments = <String>[];
+
+    // Parent (everything before first '['), may be empty
+    final first = key.indexOf('[');
+    final parent = first >= 0 ? key.substring(0, first) : key;
+    if (parent.isNotEmpty) segments.add(parent);
+
+    final n = key.length;
+    var open = first;
+    var depth = 0;
+
+    while (open >= 0 && depth < maxDepth) {
+      // Balance nested brackets inside this group: "[ ... possibly [] ... ]"
+      var level = 1;
+      var i = open + 1;
+      var close = -1;
+
+      while (i < n) {
+        final ch = key.codeUnitAt(i);
+        if (ch == 0x5B) {
+          // '['
+          level++;
+        } else if (ch == 0x5D) {
+          // ']'
+          level--;
+          if (level == 0) {
+            close = i;
+            break;
+          }
+        }
+        i++;
+      }
+
+      if (close < 0) {
+        // Unterminated group, stop collecting groups
+        break;
       }
+
+      segments.add(key.substring(open, close + 1)); // includes enclosing [ ]
+      depth++;
+
+      // find next group, starting after this one
+      open = key.indexOf('[', close + 1);
     }
 
-    // If there's a remainder, check strictDepth option for throw, else just add whatever is left
-    if (segment != null) {
-      if (options.strictDepth) {
+    if (open >= 0) {
+      // We still have remainder starting with '['
+      if (strictDepth) {
         throw RangeError(
-          'Input depth exceeded depth option of ${options.depth} and strictDepth is true',
-        );
+            'Input depth exceeded $maxDepth and strictDepth is true');
       }
-      keys.add('[${key.slice(segment.start)}]');
+      // Stash the remainder as a single segment (qs behavior)
+      segments.add('[${key.substring(open)}]');
     }
 
-    return _parseObject(keys, val, options, valuesParsed);
+    return segments;
   }
 }

lib/src/qs.dart

@@ -11,11 +11,9 @@ import 'package:qs_dart/src/models/decode_options.dart';
 import 'package:qs_dart/src/models/encode_options.dart';
 import 'package:qs_dart/src/models/undefined.dart';
 import 'package:qs_dart/src/utils.dart';
-import 'package:recursive_regex/recursive_regex.dart';
 import 'package:weak_map/weak_map.dart';
 
 part 'extensions/decode.dart';
-
 part 'extensions/encode.dart';
 
 /// A query string decoder (parser) and encoder (stringifier) class.
@@ -52,16 +50,14 @@ final class QS {
     // Iterate over the keys and setup the new object
     if (tempObj?.isNotEmpty ?? false) {
       for (final MapEntry<String, dynamic> entry in tempObj!.entries) {
-        obj = Utils.merge(
-          obj,
-          _$Decode._parseKeys(
-            entry.key,
-            entry.value,
-            options,
-            input is String,
-          ),
-          options,
-        );
+        final parsed = _$Decode._parseKeys(
+            entry.key, entry.value, options, input is String);
+
+        if (obj.isEmpty && parsed is Map<String, dynamic>) {
+          obj = parsed; // direct assignment – no merge needed
+        } else {
+          obj = Utils.merge(obj, parsed, options) as Map<String, dynamic>;
+        }
       }
     }
 

lib/src/utils.dart

@@ -495,4 +495,51 @@ final class Utils {
       (val is String && val.isEmpty) ||
       (val is Iterable && val.isEmpty) ||
       (val is Map && val.isEmpty);
+
+  static String interpretNumericEntities(String s) {
+    if (s.length < 4) return s;
+    final sb = StringBuffer();
+    var i = 0;
+    while (i < s.length) {
+      final ch = s.codeUnitAt(i);
+      if (ch == 0x26 /* & */ &&
+          i + 2 < s.length &&
+          s.codeUnitAt(i + 1) == 0x23 /* # */) {
+        var j = i + 2;
+        if (j < s.length) {
+          int code = 0;
+          final start = j;
+          while (j < s.length) {
+            final cu = s.codeUnitAt(j);
+            if (cu < 0x30 || cu > 0x39) break; // 0..9
+            code = code * 10 + (cu - 0x30);
+            j++;
+          }
+          if (j < s.length && s.codeUnitAt(j) == 0x3B /* ; */ && j > start) {
+            if (code <= 0xFFFF) {
+              sb.writeCharCode(code);
+            } else if (code <= 0x10FFFF) {
+              final v = code - 0x10000;
+              sb.writeCharCode(0xD800 | (v >> 10)); // high surrogate
+              sb.writeCharCode(0xDC00 | (v & 0x3FF)); // low surrogate
+            } else {
+              // out of range: keep literal '&' and continue
+              sb.writeCharCode(0x26);
+              i++;
+              continue;
+            }
+            i = j + 1;
+            continue;
+          }
+        }
+        // not a well-formed entity: keep literal '&'
+        sb.writeCharCode(0x26);
+        i++;
+      } else {
+        sb.writeCharCode(ch);
+        i++;
+      }
+    }
+    return sb.toString();
+  }
 }

test/unit/utils_test.dart

@@ -1027,5 +1027,61 @@ void main() {
         equals('%26%2355357%3B%26%2356489%3B'),
       );
     });
+
+    group('interpretNumericEntities', () {
+      test('returns input unchanged when there are no entities', () {
+        expect(Utils.interpretNumericEntities('hello world'), 'hello world');
+        expect(Utils.interpretNumericEntities('100% sure'), '100% sure');
+      });
+
+      test('decodes a single decimal entity', () {
+        expect(Utils.interpretNumericEntities('A = A'), 'A = A');
+        expect(Utils.interpretNumericEntities('012'), '012');
+      });
+
+      test('decodes multiple entities in a sentence', () {
+        const input = 'Hello World!';
+        const expected = 'Hello World!';
+        expect(Utils.interpretNumericEntities(input), expected);
+      });
+
+      test('surrogate pair as two decimal entities (emoji)', () {
+        // U+1F4A9 (💩) is represented as two decimal entities:
+        // 55357 (0xD83D) and 56489 (0xDCA9)
+        expect(Utils.interpretNumericEntities('��'), '💩');
+      });
+
+      test('entities can appear at string boundaries', () {
+        expect(Utils.interpretNumericEntities('ABC'), 'ABC');
+        expect(Utils.interpretNumericEntities('ABC!'), 'ABC!');
+        expect(Utils.interpretNumericEntities('A'), 'A');
+      });
+
+      test('mixes literals and entities', () {
+        // '=' is 61
+        expect(Utils.interpretNumericEntities('x=y'), 'x=y');
+        expect(Utils.interpretNumericEntities('x==y'), 'x==y');
+      });
+
+      test('malformed patterns remain unchanged', () {
+        // No digits
+        expect(Utils.interpretNumericEntities('&#;'), '&#;');
+        // Missing semicolon
+        expect(Utils.interpretNumericEntities('&#12'), '&#12');
+        // Hex form not supported by this decoder
+        expect(Utils.interpretNumericEntities('A'), 'A');
+        // Space inside
+        expect(Utils.interpretNumericEntities('&# 12;'), '&# 12;');
+        // Negative / non-digit after '#'
+        expect(Utils.interpretNumericEntities('&#-12;'), '&#-12;');
+        // Mixed garbage
+        expect(Utils.interpretNumericEntities('&#+;'), '&#+;');
+      });
+
+      test('out-of-range code points remain unchanged', () {
+        // Max valid is 0x10FFFF (1114111). One above should be left as literal.
+        expect(Utils.interpretNumericEntities('�'), '�');
+      });
+    });
   });
 }