⚡ refactor encoder to iterative stack-based approach

lib/src/models/decode_options.dart

@@ -17,7 +17,8 @@ import 'package:qs_dart/src/utils.dart';
 /// - **Dot notation**: set [allowDots] to treat `a.b=c` like `{a: {b: "c"}}`.
 ///   If you *explicitly* request dot decoding in keys via [decodeDotInKeys],
 ///   [allowDots] is implied and will be treated as `true` unless you explicitly
-///   set `allowDots: false` — which is an invalid combination and will throw at construction time.
+///   set `allowDots: false` — which is an invalid combination and will throw
+///   when validated/used.
 /// - **Charset handling**: [charset] selects UTF‑8 or Latin‑1 decoding. When
 ///   [charsetSentinel] is `true`, a leading `utf8=✓` token (in either UTF‑8 or
 ///   Latin‑1 form) can override [charset] as a compatibility escape hatch.
@@ -73,25 +74,13 @@ final class DecodeOptions with EquatableMixin {
   })  : allowDots = allowDots ?? (decodeDotInKeys ?? false),
         decodeDotInKeys = decodeDotInKeys ?? false,
         _decoder = decoder,
-        _legacyDecoder = legacyDecoder,
-        assert(
-          charset == utf8 || charset == latin1,
-          'Invalid charset',
-        ),
-        assert(
-          !(decodeDotInKeys ?? false) || allowDots != false,
-          'decodeDotInKeys requires allowDots to be true',
-        ),
-        assert(
-          parameterLimit > 0,
-          'Parameter limit must be positive',
-        );
+        _legacyDecoder = legacyDecoder;
 
   /// When `true`, decode dot notation in keys: `a.b=c` → `{a: {b: "c"}}`.
   ///
   /// If you set [decodeDotInKeys] to `true` and do not pass [allowDots], this
   /// flag defaults to `true`. Passing `allowDots: false` while
-  /// `decodeDotInKeys` is `true` is invalid and will throw at construction.
+  /// `decodeDotInKeys` is `true` is invalid and will throw when validated/used.
   final bool allowDots;
 
   /// When `true`, allow empty list values to be produced from inputs like
@@ -140,7 +129,7 @@ final class DecodeOptions with EquatableMixin {
   ///
   /// This explicitly opts into dot‑notation handling and **implies** [allowDots].
   /// Passing `decodeDotInKeys: true` while forcing `allowDots: false` is an
-  /// invalid combination and will throw *at construction time*.
+  /// invalid combination and will throw when validated/used.
   ///
   /// Note: inside bracket segments (e.g., `a[%2E]`), percent‑decoding naturally
   /// yields `"."`. Whether a `.` causes additional splitting is a parser concern
@@ -215,6 +204,8 @@ final class DecodeOptions with EquatableMixin {
     Encoding? charset,
     DecodeKind kind = DecodeKind.value,
   }) {
+    // Validate here to cover direct decodeKey/decodeValue usage; cached via Expando.
+    validate();
     if (_decoder != null) {
       return _decoder!(value, charset: charset, kind: kind);
     }
@@ -273,6 +264,7 @@ final class DecodeOptions with EquatableMixin {
     bool? parseLists,
     bool? strictNullHandling,
     bool? strictDepth,
+    bool? throwOnLimitExceeded,
     Decoder? decoder,
     LegacyDecoder? legacyDecoder,
   }) =>
@@ -294,10 +286,32 @@ final class DecodeOptions with EquatableMixin {
         parseLists: parseLists ?? this.parseLists,
         strictNullHandling: strictNullHandling ?? this.strictNullHandling,
         strictDepth: strictDepth ?? this.strictDepth,
+        throwOnLimitExceeded: throwOnLimitExceeded ?? this.throwOnLimitExceeded,
         decoder: decoder ?? _decoder,
         legacyDecoder: legacyDecoder ?? _legacyDecoder,
       );
 
+  /// Validates option invariants (used by [QS.decode] and direct decoder calls).
+  void validate() {
+    if (_validated[this] == true) return;
+
+    final Encoding currentCharset = charset;
+    if (currentCharset != utf8 && currentCharset != latin1) {
+      throw ArgumentError.value(currentCharset, 'charset', 'Invalid charset');
+    }
+
+    if (decodeDotInKeys && !allowDots) {
+      throw ArgumentError('decodeDotInKeys requires allowDots to be true');
+    }
+
+    final num limit = parameterLimit;
+    if (limit.isNaN || (limit.isFinite && limit <= 0)) {
+      throw ArgumentError('Parameter limit must be a positive number.');
+    }
+
+    _validated[this] = true;
+  }
+
   @override
   String toString() => 'DecodeOptions(\n'
       '  allowDots: $allowDots,\n'
@@ -315,6 +329,7 @@ final class DecodeOptions with EquatableMixin {
       '  parameterLimit: $parameterLimit,\n'
       '  parseLists: $parseLists,\n'
       '  strictDepth: $strictDepth,\n'
+      '  throwOnLimitExceeded: $throwOnLimitExceeded,\n'
       '  strictNullHandling: $strictNullHandling\n'
       ')';
 
@@ -340,4 +355,7 @@ final class DecodeOptions with EquatableMixin {
         _decoder,
         _legacyDecoder,
       ];
+
+  static final Expando<bool> _validated =
+      Expando<bool>('qsDecodeOptionsValidated');
 }

lib/src/models/encode_frame.dart

@@ -0,0 +1,122 @@
+part of '../qs.dart';
+
+/// Internal encoder stack frame used by the iterative `_encode` traversal.
+///
+/// Stores the current object, derived key paths, and accumulated child results
+/// so the encoder can walk deep graphs without recursion while preserving
+/// Node `qs` ordering and cycle detection behavior.
+final class _EncodeFrame {
+  _EncodeFrame({
+    required this.object,
+    required this.undefined,
+    required this.sideChannel,
+    required this.prefix,
+    required this.generateArrayPrefix,
+    required this.commaRoundTrip,
+    required this.commaCompactNulls,
+    required this.allowEmptyLists,
+    required this.strictNullHandling,
+    required this.skipNulls,
+    required this.encodeDotInKeys,
+    required this.encoder,
+    required this.serializeDate,
+    required this.sort,
+    required this.filter,
+    required this.allowDots,
+    required this.format,
+    required this.formatter,
+    required this.encodeValuesOnly,
+    required this.charset,
+    required this.onResult,
+  });
+
+  /// Current value being encoded at this stack level.
+  dynamic object;
+
+  /// Whether the value is "missing" rather than explicitly present (qs semantics).
+  final bool undefined;
+
+  /// Weak side-channel for cycle detection across the traversal path.
+  final WeakMap sideChannel;
+
+  /// Fully-qualified key path prefix for this frame.
+  final String prefix;
+
+  /// List key generator (indices/brackets/repeat/comma).
+  final ListFormatGenerator generateArrayPrefix;
+
+  /// Emit a round-trip marker for comma lists with a single element.
+  final bool commaRoundTrip;
+
+  /// Drop nulls before joining comma lists.
+  final bool commaCompactNulls;
+
+  /// Whether empty lists should emit `key[]`.
+  final bool allowEmptyLists;
+
+  /// Emit bare keys for explicit nulls (no `=`).
+  final bool strictNullHandling;
+
+  /// Skip keys whose values are null.
+  final bool skipNulls;
+
+  /// Encode literal dots in keys as `%2E`.
+  final bool encodeDotInKeys;
+
+  /// Optional value encoder (and key encoder when `encodeValuesOnly` is false).
+  final Encoder? encoder;
+
+  /// Optional serializer for DateTime values.
+  final DateSerializer? serializeDate;
+
+  /// Optional key sorter for deterministic ordering.
+  final Sorter? sort;
+
+  /// Filter hook or whitelist for keys at this level.
+  final dynamic filter;
+
+  /// Whether to use dot notation between segments.
+  final bool allowDots;
+
+  /// Output formatting mode.
+  final Format format;
+
+  /// Formatter applied to already-encoded tokens.
+  final Formatter formatter;
+
+  /// Encode values only (leave keys unencoded).
+  final bool encodeValuesOnly;
+
+  /// Declared charset (used by encoder/formatter hooks).
+  final Encoding charset;
+
+  /// Callback invoked with this frame's encoded fragments.
+  final void Function(List<String> result) onResult;
+
+  /// Whether this frame has been initialized (keys computed, prefix adjusted).
+  bool prepared = false;
+
+  /// Whether this frame registered a cycle-tracking entry.
+  bool tracked = false;
+
+  /// The object used for cycle tracking (after filter/date transforms).
+  Object? trackedObject;
+
+  /// Keys/indices to iterate at this level.
+  List<dynamic> objKeys = const [];
+
+  /// Current index into [objKeys].
+  int index = 0;
+
+  /// Cached list form for iterable values (to avoid re-iteration).
+  List<dynamic>? seqList;
+
+  /// Effective comma list length after filtering nulls.
+  int? commaEffectiveLength;
+
+  /// Prefix after dot-encoding and comma round-trip adjustment.
+  String? adjustedPrefix;
+
+  /// Accumulated encoded fragments from child frames.
+  List<String> values = [];
+}

lib/src/models/encode_options.dart

@@ -1,4 +1,4 @@
-import 'dart:convert' show Encoding, utf8, latin1;
+import 'dart:convert' show Encoding, utf8;
 
 import 'package:equatable/equatable.dart';
 import 'package:qs_dart/src/enums/format.dart';
@@ -55,15 +55,7 @@ final class EncodeOptions with EquatableMixin {
             (indices == false ? ListFormat.repeat : null) ??
             ListFormat.indices,
         _serializeDate = serializeDate,
-        _encoder = encoder,
-        assert(
-          charset == utf8 || charset == latin1,
-          'Invalid charset',
-        ),
-        assert(
-          filter == null || filter is Function || filter is Iterable,
-          'Invalid filter',
-        );
+        _encoder = encoder;
 
   /// Set to `true` to add a question mark `?` prefix to the encoded output.
   final bool addQueryPrefix;

lib/src/qs.dart

@@ -17,6 +17,7 @@ export 'package:qs_dart/src/enums/decode_kind.dart';
 
 part 'extensions/decode.dart';
 part 'extensions/encode.dart';
+part 'models/encode_frame.dart';
 
 /// # QS (Dart)
 ///
@@ -45,6 +46,7 @@ final class QS {
   static Map<String, dynamic> decode(dynamic input, [DecodeOptions? options]) {
     options ??= const DecodeOptions();
     // Default to the library's safe, Node-`qs` compatible settings.
+    options.validate();
 
     // Fail fast on unsupported input shapes to avoid ambiguous behavior.
     if (!(input is String? || input is Map<String, dynamic>?)) {
@@ -102,6 +104,7 @@ final class QS {
   static String encode(Object? object, [EncodeOptions? options]) {
     options ??= const EncodeOptions();
     // Use default encoding settings unless overridden by the caller.
+    _validateEncodeOptions(options);
 
     // Normalize supported inputs into a mutable map we can traverse.
     Map<String, dynamic> obj = switch (object) {
@@ -210,3 +213,15 @@ final class QS {
     return out.toString();
   }
 }
+
+void _validateEncodeOptions(EncodeOptions options) {
+  final Encoding charset = options.charset;
+  if (charset != utf8 && charset != latin1) {
+    throw ArgumentError.value(charset, 'charset', 'Invalid charset');
+  }
+
+  final dynamic filter = options.filter;
+  if (filter != null && filter is! Function && filter is! Iterable) {
+    throw ArgumentError.value(filter, 'filter', 'Invalid filter');
+  }
+}