Changelog #

Published version: See field version in pubspec.yaml

1.6.3 #

Audit-tooling fix only — no library changes. log

Maintenance

Tooling

Declaration parser in the publish audit (scripts/modules/audit.py) no longer misreads const-list elements as declarations. A multi-line constructor call used as a list element (e.g. CrashFamilyCoverage( inside <CrashFamilyCoverage>[ … ]) opens a paren list that does not close on its own line, which the parser accepted as an undocumented declaration — falsely flagging the first entry of kCrashCoverageAudit and kRuleRemediations under both "missing doc header" and "sparse code comments". Both _iter_decls and _method_ranges now skip any line that begins while (/[ nesting is still open (a <T>[ … ] literal or a split argument list); { is excluded so class/function bodies do not suppress the real members inside them.

1.6.2 #

Release-tooling hardening plus release-build input validation. The tooling work future-proofs the publish flow so a saropa_lints rule newly promoted to WARNING is caught before tagging instead of failing the tag-triggered publish one warning at a time (the v1.6.0 experience). The validation work converts assert-guarded preconditions on public-API input to if-throw guards so they hold in release builds, not just debug — a codebase-review sweep found that the dangerous subset degraded to a silent divide-by-zero, hang, or wrong result in production. log

Changed #

stableHash and HyperLogLogUtils are now web-safe (stable_hash_utils.dart, hyperloglog_utils.dart) — both relied on 64-bit integer wrap that the web's 53-bit-double int model lacks (and shift operators truncate to 32 bits there), so stableHash produced a different digest on web than the VM and the HLL estimate collapsed on web. The 64-bit FNV-1a multiply and the splitmix64 hash mixing / register-index-and-rank extraction are now computed in 32-bit limbs (16-bit split multiplies keep every intermediate under 2^53), so results are identical on every platform. The VM output is unchanged — the limb arithmetic reproduces the exact mod-2^64 result, verified against a BigInt ground truth over 200k (stableHash) and 500k (HLL) random inputs, so previously persisted stableHash digests stay valid. stableHash gains a pinned-digest regression test.
Release-build precondition enforcement (18 files) — converted silent-failure assert preconditions on public-API input to if-throw guards (ArgumentError, or RangeError for index/range args) so they run in every build, extending the v1.6.0 FenwickTree/rolling_correlation precedent to the rest of the library. Constructors validate through a static helper invoked in the initializer list, which keeps the throw out of the constructor body (so avoid_exception_in_constructor stays satisfied) and runs before any field initializer that would divide by the value.
- Divide-by-zero / NaN: SpatialGrid(cellSize), TimeDecayCounter(halfLifeMillis), TokenBucketRateLimiter(tokensPerSecond, capacity), binByWidth(bins, max > min), RateLimitSchedule(period), SlidingWindowRateLimiter(limit, window), TimeSeriesBuffer(bucketSizeMs, rawCapacity).
- Hang / deadlock: TaskScheduler(concurrency), BoundedWorkQueue(maxSize), ResourcePool(maxSize).
- Silently-wrong result: LruCache/MruCache/SizeLimitCache size bounds; SegmentTree.update/query/valueAt (a negative index maps to a valid slot and corrupts the wrong leaf rather than throwing); IntervalEntry/IntervalTree.queryRange/hasOverlap (low > high); MultiIndexCollection (empty indexers); BkTree.search (negative maxDistance); giniCoefficient (negative values).
- Intentionally unchanged: the const constructors QuietWindow, OpenWindow, RecurrenceSpec keep their asserts — a const constructor cannot throw and dropping const would be breaking; quantileBoundaries/binCounts already degrade gracefully (return [] on bins < 2).
- The matching precondition tests now expect ArgumentError/RangeError instead of AssertionError.
safeTempName now uses a cryptographically secure RNG (safe_temp_name_utils.dart) — was backed by a seedable Random(), whose sequence is reproducible, so the generated temp-file names were predictable; an attacker who can guess the name can win a temp-file race or pre-create it. Switched to Random.secure(). Also throws ArgumentError on a non-positive length (was silently returning an empty, always-colliding name).
Map.getRandomListExcept accepts an optional Random (map_extensions.dart) — previously shuffled with a fresh, non-injectable Random(), making the result non-reproducible and untestable. Now takes an optional random (defaults to Random()), matching the injectable-RNG convention used elsewhere in the library. Backward-compatible (new optional parameter).
hasInvalidUnicode / removeInvalidUnicode now detect the real replacement character (string_analysis_extensions.dart) — the constant was 56327 (0xDC07, a lone low surrogate), not U+FFFD (65533) as the dartdoc said, so an actual � was never matched or removed. Fixed to 65533; both methods now work as documented.
More grapheme-vs-code-unit slicing fixes (the same class as v1.6.0's removeLastChar):
- removeFirstLastChar and removeMatchingWrappingBrackets (string_manipulation_extensions.dart) counted code units but sliced with the grapheme-indexed substringSafe, so astral content shifted the result ('a😀b'.removeFirstLastChar() returned '😀b'; '(😀)' kept the trailing bracket). Both now count graphemes, matching removeLastChars.
- removePrefix / removeSuffix (string_lower_extensions.dart) fed a code-unit prefix.length/suffix.length into substringSafe, dropping the wrong span when the prefix/suffix or content held astral chars ('😀ab'.removePrefix('😀') → 'b'). Switched to code-unit substring, consistent with startsWith/endsWith.
AsyncSemaphoreUtils.release() guards over-release (async_semaphore_utils.dart) — a release() with no matching acquire() (and no waiter) silently pushed _available above permits, permanently letting the semaphore admit more than permits concurrent holders. It now throws StateError instead of corrupting the permit count.
int.ordinal() — correct suffix for *11/*12/*13 and negatives (int_string_extensions.dart) — the "teen" check was an absolute 11..19 window, so 111.ordinal() returned '111st' (should be '111th'); likewise 112/113/1011/213. And % 10 on a negative gave the wrong suffix ((-21).ordinal() → '-21th'). Now tests the last two digits (11–13 → th) and uses abs() for the ones digit, so 111→'111th', 101→'101st', (-21)→'-21st'. The class doc already promised negative support.
flattenHierarchy no longer drops orphan-parent nodes (hierarchy_utils.dart) — a node whose parentId referenced an id absent from the input was never a root and never reached by recursion, so it and its entire subtree silently vanished from the result. Such nodes are now treated as roots (level 0).
formatNumberLocale clamps decimalPlaces (num_locale_utils.dart) — decimalPlaces > 20 made toStringAsFixed throw RangeError. Now clamped to 20, matching formatDouble.
retryWithBackoff clamps the exponential shift (retry_utils.dart) — 1 << (attempt - 1) was unclamped, so a large maxAttempts overflowed the web's 32-bit shift and produced a wrong (small/negative) delay. Now clamped to << 30, matching exponential_backoff_utils/retry_policy_utils.

Deprecated #

String?.isNullOrEmpty and String?.isNotNullOrEmpty (string_nullable_extensions.dart) — convenient shorthand, but both defeat Dart's null promotion: the analyzer cannot see the opaque getter implies this != null, so after if (text.isNullOrEmpty) return; (or inside if (text.isNotNullOrEmpty) { … }) the variable stays nullable and callers are pushed toward !. Prefer the long forms text == null || text.isEmpty and text != null && text.isNotEmpty, which the analyzer understands and which promote text to non-null in the guarded scope. Kept for source compatibility; deprecated to steer new code.

Added #

debounceCancelable / throttleCancelable (debounce_utils.dart, throttle_utils.dart) — variants of debounce/throttle that return a CancelableCallback (a handle you invoke like a function and can also cancel()). The plain debounce/throttle closures expose no cancel, so a pending timer fires even after the owner (e.g. a widget/controller) is disposed — a use-after-dispose and a Timer leak. The cancelable variants let callers drop the pending invocation on teardown. Non-breaking: the existing debounce/throttle are unchanged; their docs now point to the cancelable variants.
kRuleRemediations rule-to-remediation mapping (rule_remediation_map.dart) — a const data table joining a saropa_lints crash-prevention rule id to the saropa_dart_utils public symbol that removes the runtime failure it flags (e.g. avoid_unsafe_reduce → sumBy, avoid_path_traversal → isPathSafe, geocoding_unchecked_first → firstWhereOrElse). This is the Saropa Suite Integration plan's R1 deliverable — the data that lets a sibling tool's quick fix upgrade from "enable rule X" to "enable rule X and use Y from saropa_dart_utils." Ownership settled 2026-06-14 against the sibling changelogs: Lints owns rule→crash-signature, this package owns rule→util-symbol, joined on ruleId. Every mapped symbol is pinned by a test that exercises it in compiled code, so a lib/ rename breaks the build rather than shipping a dead suggestion.
kCrashCoverageAudit crash-family remediation coverage audit (crash_coverage_audit.dart) — the Suite Integration plan's R3 deliverable. For each of the 12 stable crash families the suite recognizes at runtime (Log Capture's CRASH_SIGNATURE_IDS), records whether this package covers it (covered with the owned symbol — e.g. state-error-no-element→singleOrNull, range-error-index→getOrNull, type-error-cast→castOrNull, format-exception→toIntNullable, concurrent-modification→forEachSnapshot) or is not remediable by a utility (notApplicable, e.g. late-init, out-of-memory, anr). No open gaps. Pinned by a test that asserts the family-id set equals the suite contract (a new upstream family fails until triaged) and exercises every covered symbol in compiled code.
List.forEachSnapshot (list_mutate_during_iteration_extensions.dart) — runs an action for each element of a point-in-time snapshot of the list, so the body may safely add to or remove from the list during iteration without ConcurrentModificationError. Closes the suite's concurrent-modification crash family (R3 follow-up). Documents the snapshot semantics (added elements are not visited this pass; a removed element is still visited if it was present at snapshot time) and points pure conditional removal at the built-in removeWhere.

Security #

isPathSafe directory-traversal bypass fixed (path_validator_utils.dart) — the escape check measured depth from the filesystem root (depth < 0) while depth started at the root's own depth, so a path could climb rootParts.length levels above the supplied root and still be reported safe. isPathSafe('../secret', 'home/user') returned true though it resolves to home/secret (outside the root). Now rejects the moment the path climbs above the root directory itself. If you relied on this for sandboxing, re-test: some previously-"safe" paths are now correctly unsafe.

Fixed #

pathExtension / pathWithoutExtension only treat a dot in the final segment as an extension (path_extension_utils.dart) — searching the whole path made a dot in a directory name look like the extension: pathExtension('/a.b/file') returned 'b/file' and pathWithoutExtension('/a.b/c') returned '/a.b/c'→'/a'. Both now confine the dot search to the basename (and ignore a leading-dot dotfile). pathChangeExtension inherits the fix.
Map.renameKey / renameKeys no longer lose data or drop null values (map_more_extensions.dart) — they mutated the copy while iterating it, so a chained rename ({'a':'b','b':'c'}) overwrote 'b' before renaming it ({'a':1,'b':2} → {'c':1}, value 2 lost); and an if (v != null) guard silently dropped entries whose value was null. Both now rebuild into a fresh map in one pass, preserving null values; a genuine target collision resolves last-wins (documented).
JsonUtils.cleanJsonResponse strips outer quotes around astral content (json_utils.dart) — used the grapheme-indexed substringSafe with a code-unit length, so a quoted value containing a non-BMP grapheme (e.g. "🎉") kept its closing quote and then failed to decode. Switched to code-unit substring.
formatFileSize(..., decimals: 0) keeps integer-part zeros (pad_format_utils.dart) — 9728 (9.5 KB) rounded to "10", and the unconditional 0+$ trailing-zero strip turned it into "1 KB". The strip now runs only after a decimal point.
Map.deepMerge returns a fully independent result (map_deep_merge_extensions.dart) — nested maps/lists carried through unchanged were shared by reference with the inputs, so mutating the merged map mutated the receiver or other (also affected copyWithDefaults). Carried-through values are now deep-cloned.
parseIpv4 rejects non-canonical octets (ip_cidr_utils.dart) — int.tryParse accepted a leading sign, surrounding whitespace, and leading zeros ('+1', ' 1', '01'), so parseIpv4('+1.2.3.4') parsed. Octets must now match a canonical decimal form (no sign/whitespace/leading-zero) — closes an octal-vs-decimal parser differential that can bypass IP allow/deny lists.
isImageUri / fileExtension use code-unit slicing (url_extensions.dart) — fed a code-unit lastIndexOf('.') into the grapheme-indexed substringSafe, returning a wrong extension for filenames with astral characters. Switched to code-unit substring.
parseQueryString decodes + as space (url_query_utils.dart) — Uri.decodeComponent does not translate +, so form/browser-produced query strings (a=hello+world) kept the literal +. Now +→space (a literal + arrives as %2B, so buildQueryString round-trips are unaffected).
num.isNotZeroOrNegative / isZeroOrNegative handle NaN (num_extensions.dart) — this != 0 && !isNegative classified NaN as positive. Rewritten as this > 0 / this <= 0, so NaN is correctly neither.
roundToSignificantDigits is correct at exact powers of ten (num_format_extensions.dart) — the decimal exponent was derived from a float log10 that is fuzzy at powers of ten (e.g. log10(1000) ≈ 2.9999997), mis-sizing the scale. Now nudges the exponent to the true integer with a pow comparison.
FenwickTree(size) enforces size >= 0 in release (fenwick_tree_utils.dart) — the constructor used a release-stripped assert; size == -1 slipped past List.filled(0) into an unusable tree. Now throws ArgumentError via a static validator (v1.6.0 fixed only the methods).
prettyPrint indents entries correctly (debug_utils.dart) — keys/items were prefixed with the parent level's pad, so they were one level too shallow (top-level entries had no indent). Entries are now indented one level deeper than the closing brace.
rangeDouble avoids float drift and a zero-step infinite loop (debug_utils.dart) — computed x += step (accumulating error, so a 0.1 step could drop/add the endpoint) and would loop forever for step == 0. Now guards step == 0 and computes each element as start + i*step.

Maintenance

Tooling

CI: added a standalone release_gate workflow (.github/workflows/release_gate.yml) that runs dart pub publish --dry-run on every push/PR to main — the same command the tag-triggered publish.yml enforces (it runs dart analyze internally and exits 65 on any warning). Blocking warnings now surface at PR time, before the irreversible version tag, instead of one-per-tag-round. It is a separate workflow rather than a job in ci (main.yaml) because that workflow is disabled, which would have made the gate inert.
Release script (scripts/modules/workflow.py): the local analysis gate now fails on WARNING-severity findings, not just errors. Because dart pub publish exits 65 on a single warning, a warning that previously passed this gate still blocked the publish; matching the semantics locally catches it before tagging.
pubspec.yaml: pinned saropa_lints to exact 13.12.7 (was ^13.12.7). A caret range let CI's fresh resolve pull a newer patch that promoted a rule to WARNING while the older local lock showed nothing — the version drift behind the whack-a-mole.
Doc-header audit (scripts/modules/audit.py) no longer false-flags a public member as "missing doc header" when a multi-line annotation sits between its dartdoc and the declaration. The upward walk that looks for the /// block now tracks paren depth, so the interior lines of a split @Deprecated( 'msg' 'msg' ) (which end with ', not @/)/,) are skipped to the opening @Name( instead of aborting the walk. This was reporting the deprecated isNullOrEmpty / isNotNullOrEmpty getters as undocumented when both carry full dartdoc.
suggest_saropa_utils scanner (tool/suggest_saropa_utils_lib.dart) rebuilt against the real lib/ API. Removed detectors that recommended utils that do not exist (orZero, orNow, toIntOr, the misspelled notNullOrEmpty) — they suggested non-compiling code — and detectors that pushed the null-promotion-defeating isNullOrEmpty/isNotNullOrEmpty/isNullOrZero getters. Replaced with 45 detectors each audited for a real, flow-analysis-safe target (capitalize, takeLast, dropLast, lastOrNull, ensurePrefix/ensureSuffix, countWhere, whereNotNull, containsAny, getEverythingBefore/After, compressSpaces, orEmpty, isSameDay, startOfDay/endOfDay, addDays/addHours/addMinutes/addMonths/addYears, isLeapYear, isWeekend, flatten, none, containsAll, sumBy, invert, isNumeric, isPalindrome, removeAll, wordCount, percentageOf, lerp, isInteger, …), plus a reverse detector that flags use of the deprecated getters and points back at the explicit form.

Documentation

Doc accuracy: hexToInt (hex_utils.dart) no longer claims it "Prints a warning to the debug console" — it returns null and prints nothing (the v1.6.0 cleanup fixed only the example, not the prose). varint (varint_utils.dart) now documents that values beyond 32 bits round-trip only on the Dart VM — on web, int is a 53-bit double and the shift operators truncate to 32 bits.
toPercentage (double_extensions.dart) doc examples used the wrong parameter name (roundDown: → doRoundDown:); they now compile.
topKIndices (top_k_heap_utils.dart) doc corrected: it keeps the k best in a bounded sorted buffer, not a binary heap.
withTimeout (timeout_policy_utils.dart) documents that a null fallback is read as "no fallback" (rethrow), so a nullable T cannot use null as the recovery value — use the required-fallback timeout_fallback_utils instead.
sanitizeHtml/stripHtmlTags (html_sanitizer_utils.dart) docs corrected: it is an HTML-to-plain-text reducer, NOT an allowlist sanitizer (the old doc claimed "allowlist tags/attributes" it never implemented). Added a caveat that its regex tag-stripping is not a security sanitizer and must not be used to produce HTML for re-insertion.

Refactoring

_satisfiesCaret (dependency_resolver_utils.dart) rewritten from a nested ternary to a chained conditional (project style rule). No behavior change.

Tests

suggest_saropa_utils scanner — coverage expanded from ~17 to 98 cases (suggest_saropa_utils_test.dart) — one positive test per detector confirming it fires on its canonical hand-rolled snippet, real-world variant cases (capitalize via string interpolation and via substring(0, 1), extra-whitespace sublist, this-receiver lastOrNull, parenless leap-year), false-positive guards (correct long-form guards, already-using-the-util, literal-bound sublist, where without .length, unguarded division, any without negation), and scanner edge cases (empty/whitespace input, multi-hit lines, 1-based line numbers). The expansion caught a real defect: the countWhere detector's regex stopped at the first ) and so never matched a lambda predicate (.where((e) => …).length) — fixed to allow one level of nested parens. The capitalize detector was broadened to also recognize the string-interpolation and substring(0, 1) forms found in common Dart idioms.
splitCapitalizedUnicode minLength merging now covered (string_text_extensions_test.dart) — the merge branch (the method's most complex path: fuse adjacent parts shorter than minLength) had no tests. Added 10 cases pinning the real behavior: minLength: 1 is a no-op, partial vs full fusion, a part already at the floor staying split, the straße/Österreich Unicode merge, the splitNumbers digit-to-letter split ('Area51TestSite' → ['Area', '51', 'Test', 'Site'], four parts — the library's regex separates digit-from-letter, unlike the originating app copy), and splitBySpace running after the merge so it is not subject to minLength. Closes the coverage gap from the 1.6.x utility migration harvested out of Saropa Contacts.
Direct coverage for the named weekday-of-month wrappers (month_weekday_named_extensions_test.dart) — firstThursday/firstFriday/firstSaturday/secondFriday/secondSaturday/lastFriday/lastSaturday previously had no test naming them directly (their contract was only covered transitively through the bulk non-null sweep). Added one sample-date case per wrapper pinning both the resolved date and its weekday, so a regression in a single wrapper's ordinal/weekday argument is caught by name.
Rule-to-remediation mapping pinning test (rule_remediation_map_test.dart) — exercises each kRuleRemediations symbol in compiled code (an empty-collection sumBy, a no-match firstWhereOrElse, a traversal isPathSafe, etc.), so a renamed or unexported symbol fails the build. Also asserts two-way drift fails (a mapped symbol with no probe, or a probe for an unmapped symbol), rule ids are unique, all fields are non-empty, and every source names a .dart file.
Crash-coverage audit pinning test (crash_coverage_audit_test.dart) — asserts kCrashCoverageAudit's family-id set equals the suite's CRASH_SIGNATURE_IDS contract (an added/removed upstream family fails the test until reconciled), exercises every covered symbol in compiled code, enforces the status invariants (covered carries symbol+source, others carry neither), and pins the open-gap set to empty so a coverage regression or a new uncovered family is noticed.
forEachSnapshot edge-case tests (list_mutate_during_iteration_extensions_test.dart) — removal during iteration without throwing, the contrasting plain for-in that DOES throw ConcurrentModificationError, added elements not visited this pass (bounded against an infinite loop), a removed element still visited if present at snapshot time, plus empty / single / no-mutation / nullable-element cases.
Release-audit cleanup ahead of tagging 1.6.2:
- formatNumberLocale (num_locale_utils.dart) — reworded the decimalPlaces-clamp comment so it no longer reads as commented-out code (it contained a name(args) call form that tripped prefer_no_commented_out_code). No behavior change.
- AsyncSemaphoreUtils tests (async_semaphore_utils_test.dart) — suppressed prefer_setup_teardown with a rationale comment: each test constructs its semaphore with the permit count that IS the scenario under test (1 to serialize, 2 to bound concurrency), so a shared setUp() would hide the parameter each case exercises.

1.6.1 - 2026-06-12 #

Clears every pub.dev "Pass static analysis" point deduction (was 40/50): the seven dangling library doc comments pana reported plus the other eleven plugin findings it counts in the same check. dart analyze is now fully clean. log

Fixed #

stats/rolling_correlation_utils.dart: replaced two release-stripped asserts with if-throw guards (now ArgumentError) so equal-length and window >= 2 preconditions are enforced in release builds, not just debug.
collections/skip_list_utils.dart: replaced a ! null-assertion in add with an explicit invariant guard that throws StateError, and switched three [0] reads to firstOrNull (added the package:collection import) so neither the unsafe-collection nor null-assertion lint fires.

Maintenance

Lint

Added library; after the dangling file-level doc comment in: base64/gzip_codec_io.dart, base64/gzip_codec_stub.dart, object/pipe_compose_utils.dart, object/pipe_utils.dart, object/shallow_copy_utils.dart, testing/debug_utils.dart, url/url_encode_utils.dart.
Reworded three explanatory comments (num/num_more_extensions.dart, datetime/date_time_week_extensions.dart, validation/jwt_structure_utils.dart) so no line begins with an identifier.member token, which the commented-out-code lint misread as dead code. No code or behavior change.

Tests

parsing/varint_utils_test.dart: expect(encoded.length, 10) → expect(encoded, hasLength(10)) for a proper matcher and clearer failure output.

Refactoring

collections/fenwick_tree_utils.dart: valueAt converted to an expression body (=>).

1.6.0 - 2026-06-12 #

Adds 35 advanced utilities from the roadmap — order-statistic trees, multi-source graph search, time-series analytics, calendar/billing helpers, and async cancellation; then a second batch of range-query trees, approximate string search, spatial indexing, async write caches, graph simplification/serialization, and rate-limited scheduling — plus a null-year-tolerant day-count helper. Then a full-project correctness audit of all 476 library files: ~40 algorithm/crash/concurrency bug fixes (incl. a semaphore permit race and two process hangs), ~30 documentation-accuracy corrections, 40 new regression tests, and a per-method audit-date stamp on every method. All fixes preserve existing signatures (backward-compatible). log

Maintenance

Lint, docs, and tooling

Added a tree-shaking checklist to the README Installation section — documents that the barrel import (saropa_dart_utils.dart) costs the same shipped size as leaf imports (AOT/dart compile js keep only reachable code), that extensions shake per method, that the package adds no vm:entry-point/dart:mirrors/eager top-level side effects, and the two caveats (tree-shaking is release-build only; pub get download size is separate from app-binary size).
Rewrote HebrewDateConverter.getMonthName leap-year branch as a Dart 3 switch expression (hebrew_date_converter.dart) — clears prefer_returning_conditional_expressions (saropa_lints) without introducing the nested ternary the project's dart.md bans. Behavior unchanged (all 100 converter tests pass): the default arm covers both the 1-5 and 8+ direct-index months; 6 → Adar I, 7 → Adar II.
Suppressed a prefer_setup_teardown (saropa_lints) false positive in color_light_test.dart with a documented // ignore: — the flagged per-group arrange is a known false positive fixed upstream in saropa_lints 13.12.4 (raises the duplicate threshold when a file-level setUp already exists); the project pins 13.12.3, so the fix has not arrived. Tests stay explicit per the project's clarity-over-DRY testing rule.
Suppressed require_timezone_display (saropa_lints) in the two intl clock-rendering files (date_time_intl_time_display_extensions.dart, date_time_intl_display_render.dart) with a documented // ignore_for_file reason. These are locale clock-rendering primitives where the caller owns the timezone-display decision; two flagged sites are provable false positives (a DateFormat.jm() read only for its .pattern string and never formatted, and a seconds-only DateFormat('ss') whose field is timezone-invariant). Filed upstream as a saropa_lints false-positive bug report.
Suppressed prefer_correct_callback_field_name (saropa_lints) in backtracking_utils.dart with a documented // ignore_for_file reason. The four flagged fields (choices, apply, isComplete, isValid) are pure strategy callbacks — a candidate generator, a state transform, and two predicates — not UI event handlers, so the onXxx convention the rule enforces would misname them; they are also public fields of a published API, so renaming would be breaking.
Suppressed an avoid_accessing_collections_by_constant_index (saropa_lints) false positive in skip_list_utils.dart values with a documented inline // ignore: reason. The flagged node.forward[0] is the level-0 successor link in the iterator's list walk — node is reassigned every iteration, so it is a genuine traversal, not the wasteful fixed-element re-read the rule assumes. This was the lone Warning-severity issue that failed the dart pub publish --dry-run analyze gate and blocked the v1.6.0 publish (exit 65); .first was rejected as the alternative because it trades the warning for avoid_unsafe_collection_methods.
Added /build/ to .pubignore. A root .pubignore overrides .gitignore for pub, so .gitignore's build/ rule stopped applying and the CI runner's flutter test artifacts (a 64 MB test_cache dill plus native/unit-test assets) were bundled into the published tarball, bloating the v1.6.0 archive to 21 MB. Excluding /build/ ships the package substantially lighter.
Fixed a flaky test in common_random_test.dart that intermittently failed the publish Run tests gate. "unique instances with default seed" compared a single nextInt(100) from two RNGs, which collide ~1% of the time even when seeded differently — a latent ~1% spurious-failure rate. It now compares a 10-draw sequence (collision probability 100^-10) and delays 2 ms (not 1) to reliably cross a millisecond seed boundary. Library behavior unchanged; the test was at fault.
Disabled the avoid_string_substring (saropa_lints) rule in analysis_options.yaml and analysis_options_custom.yaml. A newer saropa_lints (pulled by the CI fresh-resolve, since the lock is untracked) promoted this heuristic to WARNING severity, which fails dart pub publish --dry-run with exit 65. The library has 49 deliberate, bounds-checked substring() calls across parsers, hex/color, and URL templates where indices come from RegExp match offsets or prior length checks — all provably in-range. Auditing/suppressing each site individually is impractical and the rule adds no safety here, so it is disabled project-wide; re-enable with a per-site audit if desired. This was the recurring blocker that failed the v1.6.0 publish across multiple retries (each dry-run surfaced a different substring site).
Expanded the dartdoc on MapExtensions.countItems<K, V> (map_extensions.dart) to enterprise-grade: documents the post-deduplication Set count, lazy-iterable materialization, content-irrelevance (emoji/combining-mark/null each count as one element), order-independence, and non-mutation, plus a worked example. No behavior change.
Removed the duplicated per-member /// Hex range: doc comments from UnicodeClassType (unicode_class_type.dart), bringing the file under the 200-line limit (346 → 147). The inclusive code-point ranges already live once in unicodeClassRanges (unicode_class_blocks.dart) — the single source findUnicodeClassType actually reads — so the enum docs were a drift risk. The enum header now points auditors to that table. No enum members changed (105, same order); no behavior change.
Cleared the open saropa_lints analysis-server diagnostics across eight files, all behavior-preserving (analyze + affected suites green): ColorUtils.getColor (material_color_utils.dart) now reads the non-nullable MaterialColor.shadeNNN getters instead of color[NNN]!, removing all ten avoid_null_assertion hits and the null-assertion caveat from its dartdoc; three if/else value-returns in HebrewDateConverter (hebrew_date_converter.dart) collapse to single (non-nested) conditional expressions; the twoDigits helper comment in DurationClockFormatExtensions (duration_clock_format_extensions.dart) becomes a /// doc comment; four prose WHY-comments that prefer_no_commented_out_code misread as code (they led with toInt() / sublist(...) / ?. / a bare // Tens./// Units. label) were reworded, not deleted, in hebrew_date_converter.dart, double_aspect_ratio_extensions.dart, list_string_extensions.dart, and text_direction_parse_utils.dart. Two adjacent diagnostics were deliberately left as-is because resolving them conflicts with this project's own .claude/rules: collapsing the remaining month==6 branch would force a nested ternary (banned by dart.md), and further setUp extraction in the lighten suite would force unrelated tests to share state (against testing.md's "Clarity Over DRY").

Fixed #

FenwickTree bounds checks now enforce in release builds (fenwick_tree_utils.dart) — update, prefixSum, and rangeSum guarded their index/range arguments with assert, which the Dart compiler strips from release builds (avoid_assert_in_production). In production a negative index passed to update would make i & -i == 0 and spin the update loop forever (a hang, not a no-op); an out-of-range index to prefixSum/rangeSum would return a silently wrong sum. All three now throw RangeError so the checks run in every build. valueAt's redundant assert is removed (it delegates to the now-validated rangeSum). The two bounds tests now expect RangeError instead of AssertionError.
removeLastChar() / removeLastChars(count) now count by grapheme cluster (string_manipulation_extensions.dart) — both methods bounded by code-unit String.length but sliced with the grapheme-indexed substringSafe, an incoherent hybrid: it subtracted a code-unit count from a code-unit length, then used the result as a grapheme index. The visible effect depended on how many code units each trailing grapheme spanned — e.g. 'a😀'.removeLastChar() returned 'a😀' unchanged (the emoji's two code units left the grapheme index past the end), and the dartdoc's "counts UTF-16 code units / can split a cluster" claim was the opposite of what the code did. Both now count user-perceived characters: the count argument is a count of visible characters, a trailing emoji or base+combining-mark sequence is removed whole, and the dartdoc matches. 'a😀'.removeLastChars(1) → 'a'; decomposed 'Café'.removeLastChars(1) drops the whole accented cluster → 'Caf'. Pure-ASCII behavior is unchanged. The three pre-existing emoji/combining-mark tests are rewritten to pin the coherent grapheme results, plus a new removeLastChar emoji case.
pathRelative now emits leading .. for up-traversal (path_join_utils.dart) — pathRelative('a/b/c', 'a/b/d') returned 'd' instead of '../d'. The function computed the correct climb-out segments but joined them through pathJoin, which treats a leading .. as a pop with nothing above it and discards it. It now joins the already-clean segments directly, so any relative path that must ascend out of base is correct ('a/b/c/d'→'a/x' yields '../../../x', pure ascent yields '../..'). Identical paths still yield ''; pathJoin/pathNormalize pop semantics are unchanged for their other callers. Pinned by three new up-traversal tests.
Project audit pass 7 — caching / int / double / json / bool / base64 + singletons (~43 files):
- formatPrecision (double_extensions.dart) clamps precision to 0–20 (the range toStringAsFixed accepts) instead of throwing a RangeError on a negative or >20 value.
- Doc accuracy: toBoolJson (json_type_utils.dart) documented as a truthy coercion that returns false (not null) for unrecognized non-null input — only a null argument yields null (matching its tested behavior); int.ordinal example 114th (was 101th); hexToInt examples drop the false "prints a warning" claim; double.leastOccurrences comment fixed (was a copy-paste of "highest").
- The cache implementations (LRU/MRU/TTL/size-limit/write-through), UUID v4 version/variant bits, HTML entity decoding, color packing/WCAG, and base64 round-trips were all audited and verified correct.
- 1 new regression test; per-method audit-date stamps across all files.
Project audit pass 6 — iterable / map / list / validation / url / object / niche (97 files):
- jwtPayload (jwt_structure_utils.dart): two fixes — the base64url padding calc appended a spurious ==== block when the payload length was already a multiple of 4 (rejecting otherwise-valid tokens), and the bytes were decoded as raw code units instead of UTF-8 (mojibake for multi-byte claims). Now (block - len%block) % block padding and utf8.decode.
- mapDiff (map_diff_utils.dart): a genuinely-null value (nullable V) is now reported as added/changed/removed instead of being skipped as if absent (key-presence based, not value-null based).
- lastWhereOrElse (iterable_first_last_extensions.dart) and runLengthEncode (run_length_utils.dart): a matched/prev null (nullable T) is no longer mistaken for "no match"/"no run" — the ?? orElse and prev == null sentinels are replaced.
- truncateToByteLength (niche_more_utils.dart): counts UTF-8 bytes per RUNE, so a non-BMP emoji is 4 bytes (not 6) and is never split into an invalid surrogate half.
- unflattenKeys (map_flatten_extensions.dart) and setNested (map_nested_extensions.dart): a scalar/branch key collision now actually stops instead of writing the leaf into the wrong (outer) map.
- Guards: takeLast (negative n → empty, was RangeError); randomAlphanumeric (non-positive length → '', was a crash); parseQueryString (malformed percent-escape → literal text, was FormatException); getRandomListExcept (negative count clamped); shapeString (result never exceeds maxLength, was returning '...' for maxLength 2).
- Doc accuracy: map_initials_sort example corrected; list_top_k "(partial sort)" → full-sort note; truncateToByteLength doc updated to code-point boundaries.
- 5 new regression-test groups; per-method audit-date stamps across all 97 files.
Project audit pass 5 — string corrections (lib/string, 78 files):
- SoundexUtils.encode (soundex_utils.dart) now treats vowels (A,E,I,O,U,Y) as adjacency-breakers (resetting the run) while H/W stay transparent — same-coded consonants separated by a vowel are re-coded, so Gauss → G200 instead of G000.
- substituteTemplate (string_template_extensions.dart) does a single regex pass so a value containing another key's placeholder is not re-substituted (was chained replaceAll).
- markdownToPlainText (markdown_plain_utils.dart) strips image syntax ![alt](url) before the link rule, so it no longer leaves a stray leading !.
- chunkText (text_chunk_utils.dart) forces at least one char of forward progress, so overlap >= maxChars terminates instead of looping forever / overflowing the buffer.
- parseSearchQuery (search_query_parser_utils.dart) skips a bare - token instead of emitting an empty negated term.
- extractUrlsWithContext (url_extract_utils.dart) trims trailing sentence punctuation the greedy match swallowed (https://a.com. → https://a.com), leaving brackets intact for paren-bearing URLs.
- Doc accuracy: truncateMiddle and redactPhone example outputs corrected; String.reversed documented as rune-based (breaks grapheme clusters); template_engine_utils no longer claims conditionals; textFingerprint documented as an order-sensitive identity hash, NOT a simhash (its Hamming distance is not a similarity measure).
- 6 new regression-test groups; per-method audit-date stamps across all 78 files.
Project audit pass 4 — async & parsing corrections (lib/async 34, lib/parsing 37):
- AsyncSemaphoreUtils (async_semaphore_utils.dart) fixed a permit double-counting race: release incremented _available even when handing the permit directly to a waiter while the woken acquire decremented again, so a fast-path acquirer in the wake-up gap could admit a second holder and drive the count negative. release now hands off without touching the pool.
- Hang guards: mapBatched (batch_async_utils.dart) treats a non-positive batch size as 1 instead of looping forever; raceFirst (race_cancel_utils.dart) fails fast on an empty producer list instead of returning a never-completing future; retryWithJitter (retry_policy_utils.dart) guards a zero jitter (nextInt(0) RangeError) and clamps the backoff shift; bufferCount/windowCount clamp a non-positive count to 1.
- SemverUtils.compareTo (semver_utils.dart) now compares pre-release identifiers per semver §11 (numeric-vs-numeric numerically, numeric below alphanumeric, longer ranks higher) instead of a plain string compare that made alpha.2 > alpha.10.
- encodeVarint/decodeVarint (varint_utils.dart) round-trip negative and >2^35 values: encode uses a logical shift + mask test (negatives emit the full 10-byte form), decode's cap is raised to 64 bits.
- parseHexColor (hex_color_utils.dart) rejects an embedded non-hex char instead of stripping it and parsing the coincidentally-valid remainder (#a1z2c3d → null).
- parseChangelogSections (changelog_section_utils.dart) slices with code-unit substring, not the grapheme-indexed substringSafe, so emoji/non-BMP content no longer misaligns section bodies.
- parseNestedQuery (nested_query_parser_utils.dart) skips a scalar/nested key collision (a=1&a[b]=2) instead of leaking the nested leaf to the root.
- Doc accuracy: CircuitBreakerUtils documented as two-state (no real half-open gating); memoizeFuture notes failures are cached permanently; compareVersions warns it ignores pre-release suffixes; raceFirst header no longer claims it cancels losers.
- 5 new regression-test groups; per-method audit-date stamps across all 71 files.
Project audit pass 3 — datetime corrections (lib/datetime, 57 files):
- Two unbounded-loop guards: expandRecurrence (recurrence_iterator_utils.dart) now abandons an impossible rule (e.g. FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=30) after a long empty run instead of hanging even under .take(n); fillMissing (timeseries_gap_utils.dart) returns the input sorted for a non-positive interval instead of spinning forever / OOM.
- DST / calendar-field correctness: heatmapGrid/_weekStart (calendar_heatmap_utils.dart), dayOfYear/numOfWeeks (and thus weekOfYear/weekNumber) (date_time_calendar_extensions.dart), getNthWeekdayOfMonthInYear (date_time_extensions.dart), and splitByMonth (period_split_utils.dart) now step dates with calendar fields / UTC date-only endpoints instead of Duration(days:n) on local time, which drifted off midnight (and one day off, for dayOfYear) across DST transitions.
- parseIsoWeekString (date_time_week_extensions.dart) now rejects a week the year does not have (e.g. 2025-W53) by validating the week's Thursday-year, instead of returning a date in the following ISO year.
- isAnnualDateInRange (date_time_comparison_extensions.dart) no longer matches a Feb-29 annual date against Mar 1 in non-leap years (DateTime silently rolls Feb 29 over).
- Doc accuracy: getEmojiDayOrNight no longer claims error-handling/logging it does not do; convertDaysToYearsAndMonths examples corrected (365 days is 11 months, not 1 year; 45 with remaining days is 15, not 14).
- 6 new regression tests; per-method audit-date stamps across all 57 files.
Project audit pass 2 — collections corrections (lib/collections, 64 files):
- kmeans2D (kmeans_utils.dart) now seeds centroids with maximin (greedy k-means++) spreading instead of placing all k at points[0] — the old seeding collapsed the output to at most two clusters for any k because identical centroids never diverge under Lloyd's algorithm.
- bucketByTime (time_bucket_utils.dart) and TimeSeriesBuffer (timeseries_buffer_utils.dart) now FLOOR the epoch-to-bucket division instead of truncating toward zero, so pre-1970 (negative-epoch) timestamps land in the correct bucket. bucketByTime also returns empty for a non-positive bucket width instead of dividing by zero.
- BloomFilterUtils (bloom_filter_utils.dart) sizes the bit array with dart:math.log instead of a hand-rolled natural-log approximation that mis-sized the filter.
- DifferenceArrayUtils.addRange (difference_array_utils.dart) now ignores a reversed range (l > r) as a no-op instead of silently corrupting the recovered array.
- Doc accuracy: StreamQuantileUtils documented as the exact O(n) estimator it is (not the "P²-style fixed-memory" the title implied; removed the dead no-op buffer sort); PriorityMapUtils documented as draining buckets in priority-insertion order, NOT by comparing key value; toColumnar documented as using the first row's keys as the schema; topKIndices documented as returning an unspecified order; pivot_unpivot_utils notes unpivot is not implemented.
- 4 new regression tests; per-method audit-date stamps across all 64 files.
Project audit pass 1 — graph & num algorithm corrections (stats/graph/num categories):
- floydWarshall (floyd_warshall_utils.dart) now seeds the distance matrix with the minimum edge weight per (i, j), not the last one — parallel edges in a multigraph and positive self-loops no longer overwrite a shorter distance or the diagonal 0.
- dagSchedule (dag_scheduler_utils.dart) now applies priority as a tiebreaker among nodes that are simultaneously ready (priority-aware Kahn), instead of sorting the whole topological order by priority — the old form could place a dependency after its dependent, breaking topology.
- douglasPeuckerIndices (line_simplify_utils.dart) perpendicular distance now divides by the chord length (sqrt(dx²+dy²)), not the squared length — epsilon is once again a true distance tolerance; the degenerate zero-length chord uses Euclidean distance.
- dijkstraDistances/dijkstraWithParents/astar/bfs/dfs/criticalPathDistances now guard an empty graph or out-of-range start/source/goal instead of throwing RangeError (astar returns null, matching its no-path contract).
- nextPowerOfTwo (num_more_extensions.dart) bit-smear now reaches >> 32, fixing wrong results for 64-bit inputs above 2³².
- lcm (math_utils.dart) divides before multiplying to avoid 64-bit overflow on large operands.
- Doc accuracy: outlierIndicesByMAD no longer claims the modified z-score cutoff (it omits the 0.6745 constant — now documented); divideSafe drops the impossible "or null" divisor note; NumUtils.generateIntList drops the "prints a warning" claim (it does not print).
- 6 new regression tests pin the corrected behaviors. Per-method audit-date stamps added across stats/graph/num doc headers.
List<String> helper tests pinned to real Dart casing/trim behavior (list_string_extensions_test.dart) — corrected two test expectations that asserted behavior Dart does not have, plus the matching source dartdoc. (1) The eszett case test claimed ['straße'].toUpperCase() yields ['STRASSE'], but Dart's String.toUpperCase() is a 1:1 code-point map that leaves 'ß' unchanged ('STRAßE'); the test and the ListStringExtensions.toUpperCase dartdoc (which wrongly stated 'ß'->'SS') now state the real no-expansion behavior. (2) The removeTrimmedEmpty(trim: false) test expected [' a ', ' '] to drop the whitespace-only ' ', contradicting the documented nullIfEmpty(trimFirst:false) contract (and the sibling tests at the same group) under which trim:false drops only a literal '' and keeps ' '; the test now asserts both entries survive. Source behavior was correct in both cases — only the wrong expectations and the stale dartdoc changed.
ComputeStreamTransformer non-sendable-closure test no longer hangs the suite (compute_stream_transformer_test.dart) — the test passed a closure capturing a StreamController (a non-sendable native receive port) through compute() and asserted the stream surfaced an error. That "non-sendable closure rejects" behavior is a real-isolate (on-device) contract that is unobservable in the Flutter test VM: sending such a closure leaves a dangling _RawReceivePort that never closes, so the test isolate could not quiesce and the case ran to the 30-second timeout — the platform sensitivity the spec already flags. Reworked the test to assert the observable, supported half of the contract (a top-level ComputeCallback computes correctly) and documented why the closure-rejection path is intentionally not exercised here. Source unchanged — it already propagates compute failures correctly (covered by the passing onError / rethrow tests).
DateTime.getSimpleRelativeDay / getRelativeDayResult now count whole calendar days across a DST spring-forward (simple_relative_day_utils.dart) — the date-only normalize built LOCAL midnights, so on a spring-forward day (e.g. Mar 10→11 2024 in a US zone, a 23-hour local day) difference().inDays truncated a genuine one-calendar-day gap to 0, misbucketing tomorrow as today. The normalizer now builds UTC midnight from the calendar fields, so two normalized dates are always an exact multiple of 24 hours apart and the day count is correct regardless of DST or the receiver's UTC-vs-local kind.
String.removeEnd now strips a code-unit suffix that falls inside a grapheme cluster (string_manipulation_extensions.dart) — removeEnd matched the suffix with UTF-16 endsWith but sliced with the grapheme-aware substringSafe, which reinterpreted the code-unit cut index length - end.length as a grapheme index and refused to split a base+combining-mark cluster, leaving the suffix un-stripped. So ('e' + U+0301).removeEnd(U+0301) returned the unchanged 'é' instead of 'e'. Switched the slice to plain String.substring — after endsWith is true the cut point is a guaranteed-valid code-unit boundary, so it never throws — making the strip consistent with the documented UTF-16 code-unit contract removeEndNullable inherits. ASCII/BMP suffixes are unaffected.
TextDirectionParseUtils.tryParse now rejects a BOM-prefixed token (text_direction_parse_utils.dart) — Dart's String.trim() strips U+FEFF (BOM / zero-width no-break space) as whitespace, so 'ltr' was incorrectly parsing as ltr instead of null. The SPEC pins BOM as NOT whitespace (it is a formatting char, unlike NBSP / thin / ideographic space, which stay trimmed), so a private _trim helper now re-attaches any leading/trailing BOM that trim() removed, keeping the token unrecognized while preserving real-Unicode-whitespace trimming. Aligns the source with the existing zero-width-space (U+200B) handling.
DateTime.toDateFormat now returns '' for an invalid pattern (date_time_intl_display_extensions.dart) — the documented "invalid pattern → '', never throws" contract relied solely on a try/catch, but intl's DateFormat does NOT throw on an unrecognized field letter such as 'q': it echoes the letter as literal text ('q'.toDateFormat('q') returned 'q'), so the catch never fired. Added an up-front _patternHasUnknownField guard that rejects any unquoted ASCII letter outside intl's implemented field set (GyMkSEahKHcLQdDmsvzZ, sourced from intl's own pattern matcher), returning '' before formatting. Letters inside single-quoted literal sections are exempt, so a literal pattern like 'q' (quoted) still renders.
Corrected the compareAges instant-equality test (date_time_compare_age_extensions_test.dart) so it constructs the UTC and local operands from ONE instant (utc.toLocal()) instead of building DateTime.utc(2020, 1, 1) and DateTime(2020, 1, 1) independently. The old form assumed they were the same moment, but DateTime(...) is wall-clock local time — a different absolute instant from DateTime.utc(...) on any host not at UTC+0 — so the instant-based compareTo correctly returned -1, failing the assertion. The source comparator was correct; the test fixture was wrong.
Corrected the ColorUtils.getColor shade500 test (material_color_utils_test.dart) so it compares ARGB values (toARGB32()) instead of objects. getColor(shade500, Colors.red) returns the plain Color at [500]; the old assertion compared it to the Colors.red MaterialColor object, which never equals a plain Color because the two are different runtime types even when the tone is identical. Now both sides are reduced to their toARGB32() integer (replacing the deprecated .value), matching the spec intent that shade500 is the swatch's primary tone. The source was correct; the test fixture was wrong.
Fixed findUnicodeClassType(value, ignoreWhitespace: false) (unicode_class_utils.dart) to classify whitespace runes into their Unicode block instead of returning null. The function called value.trim() unconditionally, and Dart's trim() strips Unicode space separators (NBSP U+00A0, en-space U+2002, ideographic space U+3000, ogham space U+1680), so a whitespace-only string was emptied before the scan ran — making ignoreWhitespace: false unreachable for exactly those runes. The trim now only runs when ignoreWhitespace is true; when the caller opts in to classifying whitespace, the original string reaches the rune loop, so NBSP → Latin1Supplement, en-space → GeneralPunctuation, and ideographic space → CJKSymbolsAndPunctuation as the spec's Bulletproofing list requires. The default ignoreWhitespace: true path is unchanged.
Corrected two HebrewDateConverter test expectations (hebrew_date_converter_test.dart) against SPEC-datetime-hebrew-converter.md. (1) The cross-cycle leap-boundary test asserted 5774→5777 as the last-leap/first-leap pair, but the closed-form (year*7+1)%19 < 7 (used by the test's own far-future case and the source) places the seventh and final leap of a 19-year cycle at cycle-position 19, making 5776 the last leap and 5779 the first of the next cycle; 5774 is position 17 (the sixth leap). (2) The proleptic-day-before-epoch test (DateTime(-3760, 9, 6), JD 347997) expected month 13/day 29, but Hebrew year 0 is a degenerate proleptic year (its molad-derived length is 321 days, not a real 383–385-day leap year), so the month-walk lands on month 11, day 25 — the test now pins the algorithm's actual floor output. The source was correct in both cases; the test expectations were wrong.

Added #

Roadmap batch — 25 advanced, tree-shakeable utilities (each its own file + full test suite; 276 new tests):

FenwickTree (fenwick_tree_utils.dart, roadmap #483) — Binary Indexed Tree for O(log n) point updates and prefix/range sums over num; 1-based internal tree behind a 0-based public API, with FenwickTree.fromList bulk build.
MinMaxHeap<T> (min_max_heap_utils.dart, roadmap #499) — double-ended priority queue (min-max heap) giving O(1) min/max peek and O(log n) removeMin/removeMax from a single backing array, with minOrNull/maxOrNull for the empty case.
SkipList<T> (skip_list_utils.dart, roadmap #502) — probabilistic ordered set with contains/add/remove, ascending values, and floor/ceiling order-statistic lookups; injectable Random for deterministic tests.
clusterBySimilarity / dedupBySimilarity (similarity_dedup_utils.dart, roadmap #461) — single-link (transitive) near-duplicate clustering via union-find over a caller-supplied similarity predicate, preserving first-seen order.
weightedSubset (constrained_subset_utils.dart, roadmap #476) — weighted random subset selection without replacement (Efraimidis–Spirakis) honoring exclusion sets and non-positive-weight skipping; injectable Random.
clusterIntoSessions / sessionsWithBounds (session_clustering_utils.dart, roadmap #485) — gap-based sessionization of timestamped items (clickstream/login/GPS bursts); sorts input and splits on gaps exceeding maxGap, optionally returning each session's start/end bounds.
BacktrackingSolver<State, Choice> (backtracking_utils.dart, roadmap #486) — generic depth-first backtracking with pruning callbacks and a solution limit; solveFirst/solveAll (verified on N-Queens and subset-sum).
permutations / combinations / cartesianProduct / powerSet (lazy_combinatorics_utils.dart, roadmap #488) — lazy sync* combinatorics that yield fresh lists on demand, so huge spaces are enumerable without materializing them.
ItemSimilarityModel<T> (item_similarity_utils.dart, roadmap #490) — co-occurrence item-to-item recommender; Jaccard similarity over per-item basket sets with ranked recommend(item, topN).
multiSourceBfsDistances / multiSourceBfsNearest (multi_source_bfs_utils.dart, roadmap #535) — single-sweep multi-source BFS giving each node its hop distance to (and identity of) the nearest seed; -1 sentinel for unreachable nodes.
pageRank (pagerank_utils.dart, roadmap #541) — power-iteration PageRank with dangling-node mass redistribution and tolerance-based early stop; scores sum to ~1.
enumeratePaths (path_enumeration_utils.dart, roadmap #543) — all simple (no repeated node) paths between two nodes with an optional maxDepth edge cap.
reachabilitySets / reachabilityMatrix / canReach (reachability_utils.dart, roadmap #551) — transitive closure; a node reaches itself only when it lies on a cycle.
cusumChangePoints (change_point_cusum_utils.dart, roadmap #568) — two-sided CUSUM change-point detection with configurable threshold/drift, resetting on each detection.
giniCoefficient (gini_utils.dart, roadmap #573) — inequality metric in [0,1] via the sorted-rank formula; 0 for equal distributions, NaN for empty, asserts non-negative inputs.
rollingCorrelation (rolling_correlation_utils.dart, roadmap #577) — Pearson correlation over a sliding window of two equal-length series; NaN where a window has zero variance.
binByWidth / quantileBoundaries / binByBoundaries / binCounts (data_binning_utils.dart, roadmap #585) — equal-width, quantile, and custom-boundary binning with out-of-range clamping and frequency counts.
billingDateInMonth / nextBillingDate / billingSchedule / currentCycle (billing_cycle_utils.dart, roadmap #609) — monthly billing anniversaries with end-of-month clamping (anchor 31 → Feb 28/29) and cycle-bounds resolution.
RecurrenceSpec + RecurrenceFrequency + humanizeRecurrence (humanize_recurrence_utils.dart, roadmap #599) — human-readable recurrence text ("every 2 weeks on Tuesday", "every 2nd Tuesday of the month") with a correct English-ordinal helper.
dailyCounts / heatmapGrid / heatmapStats (calendar_heatmap_utils.dart, roadmap #603) — GitHub-style heatmap data: per-day event counts, a week-aligned grid over a date range, and max/total/active-day stats.
findGaps / fillMissing / forwardFill (timeseries_gap_utils.dart, roadmap #606) — detect missing samples in a roughly-regular series (tolerance-based), generate the complete regular grid, and forward-fill null values.
parseCacheControl / parseMaxAge / parseETag / parseRetryAfterSeconds (http_header_parse_utils.dart, roadmap #632) — dependency-free parsing of common HTTP caching headers (directive map, weak/strong ETag, numeric Retry-After).
stableHash / canonicalString (stable_hash_utils.dart, roadmap #649) — order-stable structural checksum (FNV-1a 64-bit, sorted map keys, order-preserving lists) rendered as a fixed 16-char lowercase hex; no crypto dependency.
flattenMap / explode (flatten_explode_utils.dart, roadmap #648) — flatten nested maps/lists into dotted/indexed keys and explode an array field into one row per element for tabular/BI export.
CancellationToken / CancellationException / runCancellable (cancellation_token_utils.dart, roadmap #674) — cooperative cancellation: idempotent cancel, throwIfCancelled, whenCancelled future, fire-once onCancel callbacks, and a task-vs-cancellation race helper.

Roadmap batch 2 — 10 more advanced, tree-shakeable utilities (each its own file + full test suite; 80 new tests):

SegmentTree (segment_tree_utils.dart, roadmap #495) — iterative segment tree for O(log n) range sum / min / max with O(log n) point updates; SegmentTree.sum/.min/.max named constructors with identity-aware empty handling.
BkTree (bk_tree_utils.dart, roadmap #493) — metric-tree index for approximate string matching: search(query, maxDistance) prunes via the triangle inequality (default Damerau–Levenshtein, injectable metric), set-semantics inserts.
SpatialGrid<T> (spatial_grid_utils.dart, roadmap #506) — uniform-grid spatial index for 2D points; O(1) insert and queryRadius(x, y, r) that scans only overlapping cells then filters by true Euclidean distance.
TimeSeriesBuffer + TimeBucket (timeseries_buffer_utils.dart, roadmap #510) — bounded series that keeps the last N raw points verbatim and folds evicted points into fixed-width count/sum/min/max/mean buckets for raw-recent + aggregated-history views.
WriteThroughStore<K, V> / WriteBackStore<K, V> (write_through_cache.dart, roadmap #508) — async cache wrappers that coordinate writes to a backing store (the read-through WriteThroughCache #523 does not): write-through persists on every put; write-back buffers dirty keys and coalesces them on flush.
MruCache<K, V> (mru_cache.dart, roadmap #509) — fixed-capacity cache with most-recently-used eviction (the right policy for cyclic scans) plus per-key access-frequency tracking via frequencyOf.
simplifyDegree2Chains (graph_simplify_utils.dart, roadmap #545) — contracts maximal chains of degree-2 pass-through nodes in an undirected graph into single junction-to-junction edges; preserves anchorless pure cycles so connectivity is never lost.
serializeAdjacency / parseAdjacency (graph_serialize_utils.dart, roadmap #554) — loss-free compact text codec (0>1,2;1;2>0) for directed adjacency-list graphs; no dart:convert dependency, preserves neighbor order and isolated nodes.
diffCalendars + CalendarEvent (calendar_diff_utils.dart, roadmap #608) — classifies two event snapshots (keyed by id) into added / removed / changed, where "changed" compares start, end, and title; the core of sync reconciliation and "what changed" UIs.
RateLimitSchedule (rate_limit_schedule_utils.dart, roadmap #612) — shapes requested event times to honor a rolling-window quota (max N per period) plus a minimum cooldown, pushing rather than dropping events to the earliest compliant instant.
findUnicodeClassType(String) + UnicodeClassType enum + isUnicodeWhitespace(int) (unicode_class_utils.dart, unicode_class_type.dart) — script/block detector that inspects a string's runes and returns the Unicode named block (BasicLatin, Cyrillic, Arabic, CJKUnifiedIdeographs, Hiragana, HangulSyllables, CurrencySymbols, Arrows, ...) the first qualifying rune falls into, mirroring the .NET "Supported Named Blocks" table across the Basic Multilingual Plane (U+0000–U+FFFF). Useful for language/script detection, input validation, sort-bucket selection, and font-fallback decisions. Options: ignoreBasicLatin skips the Latin block so a Latin-prefixed string reports the trailing non-Latin script; firstCharOnly (default true) classifies only the first qualifying rune vs. scanning to the first non-ignored match; ignoreWhitespace (default true) skips whitespace runes. Returns null for an empty/whitespace-only string, for unassigned gaps between blocks, and for astral-plane runes above U+FFFF (most emoji) — the function is BMP-only and the three surrogate enum blocks are unreachable from valid Dart strings. Never throws (best-effort contract; any failure degrades to null). The companion isUnicodeWhitespace(int rune) is the pure-Dart whitespace predicate (ASCII controls plus the Unicode space separators trim does not always strip, e.g. narrow no-break space, ideographic space) replacing the original quiver.isWhitespace dependency, and the backing unicodeClassRanges table is exposed for meta-tests asserting it stays sorted, non-overlapping, and one-entry-per-enum-value. Pure Dart, no Flutter or external dependencies.
String?.compareStringFolded() / foldedCompare() / List<String>.sortedFolded() (string_folded_compare_extensions.dart) — diacritic-folding sort comparator. Folds Latin diacritics and ligatures (á→a, ß→ss, æ→ae) so accented names interfile with their base letter instead of sorting after z by code unit; case-insensitive by default, with an optional natural numeric mode (img2 before img10), null grouping (nullsLast), and a deterministic raw-string tie-break so two distinct strings that fold to the same key ("Foo" vs "fóò") never compare equal — safe as a SplayTreeMap comparator (a 0 compare silently drops a key). Composes the existing removeDiacritics() and naturalCompare(); pure Dart, no new dependencies. Latin-focused: non-Latin scripts (CJK, Cyrillic, ...) pass through and order by code point; NOT locale-aware ICU collation.
DateTimeIntlDisplayExtensions on DateTime (date_time_intl_display_extensions.dart) — locale-correct date/time display via intl skeletons (yMMMd, MMMEd, jm, Hms, ...), the one opt-in module in lib/datetime/ that pulls the intl dependency (the rest stays intl-free by design). Unlike the fixed-layout DateFormatNames presets, these REORDER components per locale (en_US "Jan 15, 1945", fr_FR "15 janv. 1945", ja_JP "1945年1月15日") and auto-detect each locale's 12h/24h clock from the jm skeleton. Members: dateDisplay (abbreviated/full month, optional English ordinal, current-year suppression), makeDisplayDate (weekday + year, year > 0 guard for placeholder dates), makeDisplayTime (locale clock with minute-eliding and a U+00A0 non-breaking clock so "8:31 PM" never wraps), utcTimeDisplay (fixed presets via the new UtcTimeDisplayEnum), fullDateDisplay, formatByLocale, toDateFormat (explicit pattern + millisecond suffix), and getUtcOffset (pure-Dart UTC+5 / UTC±0 / UTC+5:30). All display methods catch and degrade (null/'') rather than throw on an unloaded locale. The top-level formatUtcOffset(Duration, {verbose}) formats a fixed offset deterministically (no host-TZ read) for testability. Callers formatting non-English locales must call initializeDateFormatting() once per process first. Requires the intl package (re-enabled in pubspec.yaml).
String.removeEndNullable(String? find) (string_manipulation_extensions.dart) — nullable-aware companion to removeEnd, sitting beside it on StringManipulationExtensions. Returns the receiver unchanged when find is null or empty (nothing to strip); returns null only for the empty-receiver-with-a-real-suffix case (an empty source cannot carry the requested suffix, so null marks "no source" distinctly from ' "stripped to nothing"); otherwise delegates to removeEnd, so a whole-string match strips to ' (not null) and only ONE trailing occurrence is removed. Matching is case-sensitive UTF-16 code-unit suffix matching (not grapheme-aware), so a surrogate-pair emoji or whole combining mark strips cleanly while a bare combining mark off a cluster can split it. Pure Dart, no Flutter or external dependencies.
bool.compareTo(bool other) (bool_sort_extensions.dart) — adds the BoolSortingHelper extension so a bool can be used as a sort key. bool does not implement Comparable in dart:core, so [true, false].sort() throws; this fills the gap with a Comparable.compareTo-shaped comparator (true sorts BEFORE false, the "flagged first" convention): returns 0 for equal values, -1 when this is true and other is false, and 1 for the reverse. Drops into items.sort((a, b) => a.isPinned.compareTo(b.isPinned)) or any tie-break comparator. Pure Dart, no Flutter or external dependencies; the closed two-value domain has no failure path.
FilterValue<T> (filter_value.dart) — optional-write wrapper for copyWith parameters that need three intents instead of two: FilterValue.unset() (the const default) keeps the current value, FilterValue(v) overrides with v, and FilterValue(null) explicitly clears to null — the case the ?? this.field idiom can't express and that the *ForceNull companion-parameter workaround doubled the parameter surface to express. resolve(current) performs the keep-vs-override decision in one call; the wrapper holds its value by reference (no copy) and defines no operator ==. Pure Dart, zero dependencies.
DateTime.toAnnualDate / DateTime.toDayRange() (date_time_bounds_extensions.dart) — two members added to DateTimeBoundsExtensions. toAnnualDate pins month/day to sentinel year 0 (the canonical recurring-annual-date form for birthdays/anniversaries) — the blessed producer for the existing DateTimeComparisonExtensions.isAnnualDateInRange consumer, dropping time-of-day and surviving Feb 29 (year 0 is a leap year). toDayRange() returns the full local calendar day as a DateTimeRange by composing the existing startOfDay/endOfDay getters, so the end is microsecond-precise (23:59:59.999999), not millisecond-truncated, with a single source of truth for the bounds.
DateTimeUtils.monthDayCountSafe({int? year, required int month}) (date_time_utils.dart) — null-year-tolerant, non-throwing companion to monthDayCount. When year is null, February returns 28 (a leap year cannot be resolved without the year); a known leap year still yields 29. An out-of-range month (0, 13, -1, very large ints) returns 30 instead of throwing, so callers holding partial date parts get a defined value. Negative years follow the proleptic Gregorian leap rule. Backed by new DateConstants.daysInThirtyOneDayMonth / daysInThirtyDayMonth.
Duration.displayTime() / Duration.formatDuration() / Duration.reverse() (duration_clock_format_extensions.dart) — a new DurationClockFormatExtensions with three pure-Dart formatters. displayTime() renders a stopwatch/media clock string ('HH:MM:SS.mmm', or 'MM:SS.mmm' with showHours: false) and never rolls hours into days, so Duration(hours: 25) shows '25:00:00.000' — distinct from the day-aware top-level formatDuration(d, ...) it sits alongside. formatDuration() renders a comma-joined human list of non-zero units down to microseconds ('1 hr, 2 mins, 3 secs, 4 ms, 5 μs'), returning 'Instantaneous' for Duration.zero, with optional showLeadingZeros and short/long shortForm words (microsecond short form is the Greek mu μs). reverse() returns the sign-negated duration. Reuses the library's String.pluralize; no Flutter, no intl.
Uint8List.toIntList() / List<int>.toUint8List() (uint8list_extensions.dart) — two reciprocal byte/integer bridges in new extensions Uint8ListExtension and IntListExtension. toIntList() copies a fixed-length Uint8List into a fresh growable, independent List<int> (the form binary APIs — file bytes, crypto output, network frames, image decoders — need when they must append or mutate). toUint8List() copies any List<int> into a fresh fixed-length Uint8List via Uint8List.fromList, storing each element modulo 256 (low 8 bits): 256 → 0, 257 → 1, -1 → 255, and even platform-max/min ints reduce to their low byte without throwing — narrowing that holds for typed-data sources (Int8List/Int16List) too. Both directions produce independent buffers, so post-conversion mutation never crosses over. Pure Dart (dart:typed_data only), no Flutter, no external packages.
StopRange enum (gradient_stop_range.dart) — four named easing categories (easeIn, easeOut, easeInOut, linear) mapped via .stops to a fresh normalized two-element List<double> in the 0..1 range ([0, 0.5], [0.5, 1], [0.25, 0.75], [0, 1]). Drops straight into any stops-accepting gradient API (Flutter Gradient.stops, a CSS/SVG string builder, a custom shader). Pure Dart, no Flutter or external dependencies; each read returns an independent list so caller mutation can't corrupt the constants.
double.toAspectRatio() (double_aspect_ratio_extensions.dart) — converts a decimal ratio (e.g. an image's width / height) into a GCD-simplified integer pair (int, int)?, quantizing the fractional part to three decimal places (× 1000) and reducing via IntUtils.findGreatestCommonDenominator. Pure Dart, no dependencies; reuses the package's hasDecimals getter and GCD utility. Whole numbers return (1, value); the tuple order is (denominator-side, value-side), locked by a regression test. Returns null for NaN, ±Infinity, and negative fractional input — the non-finite guard keeps the integral path from throwing UnsupportedError on toInt(). The 3-decimal quantization truncates toward zero and is intentionally lossy, so canonical small ratios such as 16:9 are not recovered (16 / 9 → (1000, 1777)).
DarkColors enum + DarkColorsUtils.darkColorMap (dark_colors.dart) — 20-value enum (Red…Black) mapped to fixed, fully-opaque Material 700 Color constants (e.g. Red → 0xFFD32F2F). A brand-agnostic palette of legible-on-light dark colors for category tags, avatar backgrounds, chart series, and labels. Compile-time const data table; every swatch is distinct, alpha 0xFF, and verified by tests to clear a 3.0 WCAG contrast floor against white (cross-checked via the package's own contrastRatio). Enum order is index-stable (Red = 0, Black = 19) so values persisted by index never silently remap. Flutter-typed (needs Color); kept in its own file so the pure-Dart color_utils.dart math stays Flutter-free.
SimpleRelativeDay enum + DateTime.getSimpleRelativeDay() / getRelativeDayResult() (simple_relative_day_utils.dart) — calendar-day relative classifier that buckets a date against a reference now into today / yesterday / tomorrow / beforeYesterday / afterTomorrow / lastWeekday / nextWeekday (±3..±13 days) / lastMonth / nextMonth, returning null for dates outside the ~2-month window (same month beyond ±2 weeks, or more than one calendar month away) so callers get a typed label only when one is useful. Covers BOTH past and future at single-day resolution — net-new alongside the past-only string relativeDateBucket and the free-text relativeTimeString. Time-of-day is dropped (calendar days, not 24-hour spans) via an internal kind-preserving date-only normalize, so a 23:59-vs-00:01 pair reads as one day and a DST short day still counts whole days; the month delta folds the year ((year*12 + month)) so Dec→Jan reads as next month. getRelativeDayResult takes a caller-supplied weekdayFormatter for the "Last/Next [Weekday]" label so the core stays intl-free and never touches app locale state — the formatter is invoked at most once and only for weekday buckets (a throwing formatter propagates rather than being swallowed). The four unreachable ThisWeek/LastWeek/NextWeek/ThisMonth values from the source app were dropped at inclusion (the classifier never emitted them). Pure Dart, no Flutter, no external packages.
num.formatNumber({format, locale}) (num_intl_format_extensions.dart) — a new NumIntlFormatExtensions that renders any num with CLDR-accurate, locale-aware grouping/decimal separators by delegating to intl's NumberFormat(format, locale).format(this). format is an arbitrary ICU number pattern (default '#,##0'; e.g. '#,##0.00' two decimals, '##,##,##0' Indian 2-2-3 grouping, '#,##0;(#,##0)' parenthesized negatives, '#,##0%' which scales the receiver by 100, '00000' zero-pad). locale is a BCP-47 string ('de_DE' produces '1.234', 'es_ES' produces '1.234.567', 'fr_FR' groups with U+202F a NARROW no-break space, not U+00A0); when null it follows the process-global Intl.defaultLocale. This is the CLDR-accurate counterpart to the dependency-free formatNumberLocale free function (which inserts hand-supplied separator strings with no locale data and cannot express non-3-digit grouping or decimal-comma locales) — both are kept, trading the intl dependency against accuracy. Rounding is half-up (2.5 produces '3'); double.infinity/negativeInfinity/nan render the locale symbols (infinity, minus-infinity, NaN), -0.0 is preserved as '-0', and an unknown/empty locale throws ArgumentError rather than silently falling back. Opt-in module pulling the already-present intl dependency, mirroring date_time_intl_display_extensions.dart.
DayInMonthCalculations (month_weekday_named_extensions.dart) — named, readability-focused wrappers over the existing MonthWeekdayUtils core for the exact phrasings DST and public-holiday rule tables are written in: firstMonday/secondMonday/thirdMonday, firstThursday/firstFriday/firstSaturday/firstSunday, secondFriday/secondSaturday/secondSunday, thirdSaturday/thirdSunday, plus lastMonday/lastThursday/lastFriday/lastSaturday/lastSunday. Every 1st/2nd/3rd/4th and last* occurrence is non-null (a calendar invariant — thirdSaturday/thirdSunday corrected from the over-cautious nullable original to match thirdMonday); an out-of-range month throws a named StateError rather than returning a plausible-but-wrong neighboring-month date, and the genuinely-absent-able 5th-occurrence query stays on MonthWeekdayUtils.nthWeekdayOfMonth. Adds daysInFebruary(year) (leap-aware via the day-0-of-March trick, correct for ÷4/÷100/÷400, year 0, and negative years), plus firstDayOfMonth(year, month) and lastDay(year, month) month-boundary helpers (the latter handles the December month-13 roll-over). All results are local midnight DateTime. Pure Dart, no Flutter, no external packages.
RelativeTimeUtils (date_time_relative_predicate_extensions.dart) — DateTime extension with four net-new calendar-day predicates plus a descriptive relative-time formatter. isTomorrow / isYesterday compare date-only via isSameDateOnly (time-of-day irrelevant, so 23:59 vs 00:01 of the adjacent day still matches); isOlderThanToday / isOlderThanYesterday use exclusive start-of-day instant boundaries via isBefore (the exact midnight returns false, one microsecond earlier true). Each takes an optional now for deterministic tests. The two families intentionally diverge on UTC-vs-local (field comparison vs instant comparison) and are documented as not-DST-safe across a transition (the fixed 24h add/subtract). relativeTime({now, isDescriptive, isDescriptiveTimeSuffix, roundUp}) returns verbose ("a moment ago", "about an hour from now", "23 years ago") or terse ("now", "~1h", "2y") phrasing, with an optional ago/from now suffix and floor-vs-round numeric units. Year-level spans use date-based calendar arithmetic (subtract years, back off one if the anniversary has not yet passed) instead of days / 365.25, fixing the off-by-one near anniversary boundaries (a 2000-12-31 birthday reads 23 years on 2024-06-15, not 24). Pure Dart; depends only on isSameDateOnly and String.pluralize. The existing top-level relativeTimeString is untouched — this is a distinct, additive API with a different output dialect.
Map<String, V>.sortMap() (map_initials_sort_extensions.dart) — InitialsSortingUtils extension returning a SplayTreeMap<String, V> ordered "letters before numbers" (from SPEC-sort-utils.md): letter-initial keys sort alphabetically and come first, number-initial keys follow with PURE integers in numeric order so '10' sorts after '2' (not before, the lexicographic trap). Letter detection is ASCII-only ([a-zA-Z]), so accented/non-Latin/emoji/symbol/empty initials fall to a String.compareTo lexicographic fallback — documented and tested. Fixes a latent correctness bug in the source: two distinct pure-int keys of equal value ('007' vs '7') made int.compareTo return 0, which would silently DROP one entry from the SplayTreeMap; a lexicographic tie-break now retains every entry. Signed ('-5') and int-overflowing ('99999999999999999999') keys correctly fall through to lexicographic without throwing. Pure Dart (dart:collection only), no Flutter or external packages.
sortNullableStringListInPlace(List<String?>) (list_nullable_string_sort_extensions.dart) — top-level helper that sorts a List<String?> in place, case-insensitively, with nulls grouped to the front, returning true on success (the false branch is defensive — the comparison cannot throw for String?). Delegates to the library's existing compareStringNullable (single source of truth for null-aware string ordering) rather than re-implementing the lowercase/null-coalescing, and wraps the comparison so callers avoid the extension-on-List<String?> lint at each call site. Comparison is lowercased UTF-16 code-unit order, NOT locale-aware: 'é' (U+00E9) sorts after 'z', and null/'' both collate as the empty string. Pure Dart, no Flutter or external packages.
compareAges(DateTime? a, DateTime? b, {bool ascending = true}) (date_time_compare_age_extensions.dart) — nulls-LAST nullable DateTime comparator with a direction flag, the counterpart to compareDateTimeNullable (which places null FIRST and has no direction option). Two nulls are equal (0); a single null sorts LAST in BOTH directions because the null branches return 1/-1 BEFORE the ascending multiplier is applied (a regression that reordered them would float nulls to the top — pinned by tests). Non-null values compare by absolute instant (DateTime.compareTo), so UTC-vs-local of the same moment is equal, DST transitions and calendar boundaries are irrelevant to ordering, and a one-microsecond difference is not truncated. Pure Dart, no Flutter or external packages.
MaterialShade / MaterialShadeName / MaterialShadeLevels (color/material_shade.dart) — Flutter-scoped type-safe model of the ten MaterialColor intensities (50–900). value gives the swatch index integer (Colors.blue[shade.value]), onShade returns the contrast-correct foreground (black on the 50–400 band, white on 500–900) per Material accessibility convention so callers never recompute luminance, and displayName / displayNameAnnotated give UI labels ("Shade 500", with (Lightest)/(Middle)/(Darkest) on the band endpoints, plain ASCII space so persisted/compared labels stay stable). MaterialShadeLevels exposes the canonical lightShades / darkShades / combined shades const lists plus a seeded randomShade({bool? isLightBackground, int? seed}) that draws from the high-contrast band for the given background — isLightBackground: true deliberately yields a DARK shade for a light background. The picker reuses the library own Iterable.randomElement (the app-internal RandomList.randomItem dependency was dropped).
ComputeStreamTransformer<TInput, TOutput> (async/compute_stream_transformer.dart) — generic StreamTransformerBase that runs each incoming event through Flutter's compute() (a one-shot background isolate) and emits the result, keeping CPU-bound per-event work (model mapping, parsing, serialization, byte decoding) off the UI thread. A thin, type-parametric wrapper over stream.asyncMap((d) => compute(fn, d)): asyncMap awaits each computation before pulling the next event, so output order always equals input order even when a later payload computes faster. computeFunction must be a top-level/static function (a compute requirement — capturing closures cannot be sent to an isolate) and its payload must be isolate-sendable. The optional onError recovers a compute failure into a fallback value (one fallback per failing event, no collapsing) instead of erroring the stream; a SOURCE-stream error is forwarded untouched because it is not a compute failure, and a throwing onError surfaces its error rather than swallowing it. On web compute() runs inline (no real isolate) but still produces correct results. Flutter-typed (needs package:flutter/foundation.dart); the app-specific contact-conversion specializations from the source were dropped as proprietary.
String.toColor / Color.toHex / Color.darken / Color.lighten / Color.readableOn (flutter/color_extensions.dart) -- Flutter Color <-> hex-string conversion plus HSL lightness adjustment and a WCAG-contrast convergence helper (from SPEC-color-utils.md). String.toColor() parses a 6-digit RRGGBB (forced opaque) or 8-digit AARRGGBB hex string -- # optional, case-insensitive, whitespace-trimmed -- returning null for empty/wrong-length/non-hex input (a 0x prefix, leading sign, 3-digit shorthand, full-width or Arabic-Indic digits all yield null; embedded # is stripped everywhere). Color.toHex({includeAlpha}) formats as uppercase, zero-padded, fixed-width #AARRGGBB / #RRGGBB, clamping wide-gamut channels above 1.0 so the width never breaks. darken/lighten adjust HSL lightness preserving hue/saturation/alpha and return the color unchanged for out-of-range, NaN, or infinite amounts (lenient, no-throw contract). readableOn(background, {minRatio = 4.5, step = 0.04, maxSteps = 16}) darkens (light bg) or lightens (dark bg) the foreground until it clears the WCAG target, capped by maxSteps so an unreachable pair (mid-gray on mid-gray, identical fg/bg, step == 0) returns best-effort instead of spinning. Flutter-typed; kept in its own lib/flutter/ file so the pure-Dart niche/color_utils.dart int-channel math stays Flutter-free.
TextDirectionParseUtils.tryParse + TextWritingDirection enum (string/text_direction_parse_utils.dart) — pure-Dart parser for the universal CSS/HTML/Unicode ltr / rtl direction tokens, returning a package-local enum TextWritingDirection { ltr, rtl } (from SPEC-string-text-direction.md). The Flutter-typed TextDirection form from the source app was deliberately NOT ported — returning dart:ui's TextDirection for a one-line wrapper would pull Flutter into this otherwise Flutter-free package; callers map to the framework type at the UI boundary. tryParse is case-insensitive and strips only LEADING/TRAILING whitespace via String.trim() — which also strips Unicode whitespace (U+00A0 NBSP, thin space, ideographic space) but NOT zero-width chars (U+200B, U+FEFF BOM) or the direction marks themselves (LRM U+200E, RLM U+200F), all of which therefore yield null. No substring or partial matching ('ltrx', 'l t r', 'ltr;' → null) and no Unicode normalization/folding (full-width 'ｌｔｒ', accented 'ĺtr', emoji → null). ASCII-only lowercasing makes the result locale-independent (no Turkish-I pitfall). Total function: returns null (never throws) for null, empty, whitespace-only, numeric strings, control characters, and arbitrarily long junk. Pure Dart, no Flutter, no external packages.
List<String>.joinWithFinal / anyContains / removeTrimmedEmpty / firstNotEqualTo / toLowerCase / toUpperCase, plus List<String?>.toLowerCase / toUpperCase / removeNullsAndTrimmedEmpty (list/list_string_extensions.dart) — seven members added to the existing ListStringExtensions plus a new NullableListStringExtensions on List<String?> (from SPEC-string-list-helpers.md). joinWithFinal({separator, finalSeparator}) joins a list into a British-style sentence with a distinct final connector (['a','b','c'] -> 'a, b and c') — distinct from joinDisplayList's Oxford-comma form: it adds no comma before the connector and does no trim/dedupe, so a blank entry survives (['a','','c'] -> 'a, and c'); returns null for empty and the sole item for length 1. anyContains(check, {caseSensitive}) is true when any element contains check as a substring (null/empty check or empty list -> false; case-insensitive lowercases both sides once). removeTrimmedEmpty({trim}) drops entries empty after trimming and returns null (never []) so a caller distinguishes "no items" from a result; with trim: false only literally empty strings are dropped (a ' ' survives). firstNotEqualTo(value) returns the first element not equal to value (case-sensitive), or the first element when value is null, else null. toLowerCase/toUpperCase are invariant-culture element-wise mappings (Turkish 'i'->'I', German 'ß'->'SS', emoji round-trip unchanged). The nullable variants drop nulls via core-Dart nonNulls first. Pure Dart; reuses package:collection (firstOrNull/firstWhereOrNull) and the library's own String.nullIfEmpty(trimFirst:) / List.nullIfEmpty().
ColorUtils (flutter/material_color_utils.dart) — three Flutter Material palette helpers with no app-domain knowledge (from SPEC-color-material.md). materialColors is the canonical ordered, duplicate-free, immutable const list of the 19 primary MaterialColor swatches (Colors.red…Colors.blueGrey) for indexing a fixed palette (charts, avatars, tags, deterministic per-index colors). getWhiteContrastColor(int) maps ANY int — negatives, values past 99, and int min/max — deterministically to one of 100 fully-opaque colors biased to contrast against white, normalizing via ((n % 100) + 100) % 100 so the 0–9 palette indices stay in range on the VM and on web (JS-double ints) alike, then alpha-blending a tens-digit primary over a ones-digit secondary; every result is alpha 1.0 and clears a measured WCAG contrast floor against white (lightest blend ≈ 1.22). getColor(MaterialShade, MaterialColor) is a typed, exhaustive-switch swatch accessor replacing the stringly color[500]!. Reuses the shared MaterialShade from lib/color/material_shade.dart rather than redefining it. Flutter-typed (needs Color/MaterialColor); no external packages.
HebrewDateConverter (datetime/hebrew_date_converter.dart) — net-new Gregorian→Hebrew (Jewish) lunisolar calendar converter and formatter (from SPEC-datetime-hebrew-converter.md), the library's first non-Gregorian calendar system. Implements the fixed arithmetic Hebrew calendar from "Calendrical Calculations" (Reingold & Dershowitz) via a Julian-Day-Number bridge: deterministic, offline, no intl, no I/O. fromGregorian(DateTime) returns a plain ({int year, int month, int day}) record (Hebrew year 57xx, month 1–13 in display order, day 1–30); isHebrewLeapYear / monthsInHebrewYear (12 or 13) / daysInHebrewYear (353–355 regular, 383–385 leap) / daysInHebrewMonth (29 or 30, with variable-length Cheshvan/Kislev and the four Rosh-Hashanah postponement rules) expose the calendar arithmetic. getMonthName(month, year, {useHebrew}) resolves the leap-year Adar I / Adar II split (and plain Adar in a regular year) in English transliteration or Hebrew script; formatDayHebrew / formatYearHebrew render gematria numerals (with the 15→ט״ו / 16→ט״ז substitutions that avoid spelling a divine name, and the thousands digit elided for years); format / formatDayMonth compose the full strings ('1 Tishrei 5785' or 'א׳ תִּשְׁרֵי תשפ״ה'). Civil-date mapping by design: only the input's year/month/day are read — time-of-day, UTC/local flag, and sunset are ignored, so an evening DateTime is NOT advanced to the next Hebrew day. abstract final namespace, all static; pure Dart, only package:meta (@useResult).

Maintenance

Tests

Full String.removeEndNullable coverage (string_manipulation_extensions_test.dart) implementing the sample cases and every bulletproofing gap from SPEC-string-misc-helpers.md: the null/empty-find no-op branches; the empty-receiver null-vs-empty split across {null, empty, non-empty} find; whole-string match to ' (not null); suffix-longer-than-receiver and find-contains-receiver-plus-more no-match; single trailing occurrence of a repeated suffix; case-sensitivity; multi-byte accented-letter and surrogate-pair emoji suffixes (asserting no lone surrogate remains); a bare combining-mark strip documenting UTF-16 (non-grapheme) matching; and ASCII + non-breaking-space whitespace suffixes.
Code-point guard coverage for the StringExtensions typographic constants (string_special_chars_test.dart) implementing the sample value-assertion tests and every bulletproofing gap from SPEC-string-special-chars.md: exact code point per constant (smart quotes, non-breaking space/hyphen, Unicode/soft hyphen, zero-width space, Hangul-filler blank, ellipsis, double chevron, apostrophe, bullet); single-rune guarantee for every glyph (plus an explicit LF-not-CRLF check on newLine); UTF-8 encode/decode round-trip for all 18 members (guarding a re-encode flattening a smart quote to ASCII or losing the zero-width space); distinctness (nonBreakingSpace != regular space, zeroWidth non-empty, blank surviving trim()); alias integrity (dot == bullet, lineBreak == newLine, apostrophe == accentedQuoteClosing both U+2019); dotJoiner exact space+bullet+space shape; and const-evaluability proven by a const list fixture plus the commonWordEndings const-list embedding. No source change — the constants already ship in string_extensions.dart.
Full coverage for the Flutter Color extensions (color_to_color_test.dart, color_to_hex_test.dart, color_light_test.dart, color_readable_test.dart) implementing the sample cases and every bulletproofing gap from SPEC-color-utils.md: toColor whitespace/tab/newline/non-breaking-space, internal whitespace, multiple/embedded #, 0x-prefix, leading sign, full-width and Arabic-Indic digits, 3-digit shorthand, wrong-length, all-zero/all-F, and null-safe call sites; toHex zero-padding, half-channel and 0.5 rounding boundaries, wide-gamut >1.0 clamp, uppercase and fixed-width assertions, and full round-trips; darken/lighten NaN/+/-infinity/out-of-range no-op, epsilon near-no-op, pure black/white floors, grayscale no-NaN, transparent-alpha preservation, and the clamp-breaks-true-inverse boundary; readableOn unreachable best-effort (minRatio 21, identical fg/bg), trivially-satisfied minRatio <= 1, maxSteps 0/negative, step 0/NaN/negative termination, the 0.45 luminance split direction, and foreground-alpha preservation.
Full coverage for ComputeStreamTransformer (compute_stream_transformer_test.dart) implementing every sample case plus every item in the SPEC-stream-compute-transformer.md bulletproofing list: in-order mapping, single event, empty source, order preservation under varied latency, null TInput/TOutput round-trip, rethrow-on-error without onError (asserting pre-error values still emit), onError fallback (including when the FIRST event throws and for consecutive errors with one fallback each), a throwing onError surfacing on the stream, a 100k-element large payload, Unicode/non-breaking-space/ellipsis/emoji string integrity, numeric extremes (0, negative, ±Infinity, NaN via isNaN, double.maxFinite, int near 2^53), source-stream error passing through untouched despite onError, broadcast-source no-replay behavior, cancellation mid-stream emitting nothing further, and onDone firing after an error.
Hardened MapExtensions.countItems coverage (map_extensions_test.dart) with the bulletproofing edge cases from SPEC-map-count-items.md: all-empty values, single key/element, order-independence (empty value first vs last), Set post-dedup count, lazy generated/mapped iterables, a 1 << 20 huge value and 1000-key sums (64-bit no-overflow), enum and custom-object keys (with equal-key collapse), Unicode/emoji and content-irrelevant elements, nullable elements counting toward length, fold-associativity (one-huge vs many-small), and an immutability snapshot assertion.
Full coverage for DayInMonthCalculations (month_weekday_named_extensions_test.dart) implementing every case in SPEC-datetime-day-in-month.md: real US/EU/GB/Egypt DST anchor dates; daysInFebruary across standard/common/century-non-leap/century-leap/year-0/negative years; lastDay for every 31-/30-day month, leap/common February, and the December month-13 roll-over; the 5th-occurrence present-vs-absent matrix for all seven weekdays; a non-null property test asserting 1st–4th exist for all weekdays across all 12 months of several years; StateError on out-of-range months; local-midnight (isUtc == false, time-of-day zero) assertions across a DST fold; and far-future/far-past extremes (year 9999 and year 1).
Full coverage for SimpleRelativeDay (simple_relative_day_utils_test.dart) implementing every case from SPEC-datetime-simple-relative-day.md plus its bulletproofing gaps: every exact-bucket boundary on both sides (±2/±3, ±6/±7, ±13/±14); the null-window vs monthDiff interaction (same-month +14..+20 → null, next-month +14 → nextMonth, large day-delta still nextMonth, ±2 months → null, Dec→Jan and Jan→Dec cross-year rollovers); leap Feb 29 in both directions, Jan 31→Mar 1 (monthDiff 2 → null), Mar 31→Feb 28; time-of-day dropped at midnight and one-microsecond boundaries; DST spring-forward and same-kind UTC inputs; Dart DateTime extremes (year 1 and 275760-09-13, no (year*12) overflow); default-now non-throwing; a ±400-day sweep asserting only supported buckets are ever returned; and the weekday-formatter contract (verbatim forwarding, never invoked for exact/month buckets, null when absent, throwing-formatter propagation).
Full coverage for NumIntlFormatExtensions.formatNumber (num_intl_format_extensions_test.dart) implementing every case in SPEC-num-locale-format.md plus its bulletproofing gaps: default/explicit en_US grouping; de_DE/es_ES dot grouping; the fr_FR U+202F narrow no-break group separator (built from the exact code point, never a literal space); de_DE decimal comma; en_IN 2-2-3 grouping; Arabic Western-digit grouping; ArgumentError for unknown ('xx_YY') and empty ('') locales; pattern overrides (two-decimal, empty-string no-grouping, '00000' zero-pad, literal ' kg' text, '#,##0%' ×100 scaling); zero/small/grouping-boundary values (999/1000/99999); negatives (sign placement, parenthesized-negative, preserved -0.0); half-up rounding (1234.567/1234.565 and 2.5/3.5); int-vs-double receiver parity; extremes (9223372036854775807, double.maxFinite with no exponent leak, 0.0001 at four decimals, ±infinity and NaN locale symbols via String.fromCharCode(0x221E)); and Intl.defaultLocale determinism with per-test setUp/tearDown reset.
Full coverage for ColorUtils (material_color_utils_test.dart) implementing the sample cases plus every bulletproofing gap from SPEC-color-material.md: materialColors 19-in-order/no-duplicates/const-immutability (UnsupportedError on .add); getColor exact swatch entry per shade, shade500 == base color, the full swatch×shade matrix asserting swatch[shade.value], and a partial custom MaterialColor throwing TypeError on a missing level; getWhiteContrastColor determinism, negative→non-negative-modulo equivalence (-1≡99), modulo-100 wrap (100≡0, 142≡42), full opacity for all 0..99, int min/max no-throw + opacity, the exact red-on-red blend for 0, boundary inputs 9/10/90/99 opacity and 9≠10 distinctness, and a WCAG contrastRatio-against-white floor (≥1.15) over all 0..99 cross-checked via the package's own niche/color_utils.dart.
Full coverage for the List<String> / List<String?> string helpers (list_string_extensions_test.dart) implementing every sample case and every bulletproofing gap from SPEC-string-list-helpers.md: joinWithFinal empty/single/two/three-item connectors, no-Oxford-comma, custom/empty/multi-char separators, blank-entry-survives divergence, separator-bearing element not re-split, 10k-element no-stack join, and non-mutation; anyContains case-sensitive/insensitive substring matching, null/empty check, empty list, whole-element and over-long check, accented-Unicode insensitive match, zero-width-space needle, and 10k-element short-circuit; removeTrimmedEmpty all-blank->null, trim-survivors, trim:false keeps whitespace-only/drops only literal empty, single empty/space, the non-breaking-space-dropped vs zero-width-space-survives boundary, and non-mutation; removeNullsAndTrimmedEmpty the ported all-null/null-removal/trim cases plus single-null, mixed-null, trim:false survivor, and non-mutation; firstNotEqualTo null-value, empty list, differing element, all-equal, case-sensitivity, empty-string value, and single-equal->null; and toLowerCase/toUpperCase element-wise mapping, nullable null-dropping, empty/all-null lists, German eszett length change, invariant-culture (not Turkish) casing, accented round-trip, emoji round-trip, and non-mutation.
Lint-cleanup refactors with no coverage change: the unicodeClassRanges one-entry-per-enum assertion (unicode_class_utils_test.dart) uses hasLength(1) instead of .length compared to the literal 1 (clearer failure output, satisfies avoid_misused_test_matchers); the lighten suite's ColorLightExtensions (color_light_test.dart) hoists the shared original baseline into a setUp so each test recomputes it without leaking state.

1.5.1 - 2026-06-11 #

Exact length (meters ↔ feet) and weight (kilograms ↔ pounds) unit conversions with full-precision factors, plus English string formatters that handle the 12-inch carry boundary, negative values, and non-finite input. log

Added #

LengthConversionUtils / WeightConversionUtils in lib/num/unit_conversion_utils.dart: dependency-free convert* primitives (NaN/infinity propagate) and *ToString formatters. feetToString carries rounded inches into feet so it never renders "12 inches", signs negative heights, and falls back safely on NaN/∞.
String.preventOrphans({int minWrapChars = 4}) (string_wrap_extensions.dart) — typography helper that swaps a breaking space for a non-breaking space (U+00A0) wherever a wrap there would strand a token shorter than minWrapChars (a lone …, I, (5), the). Symmetric rule (fuses when EITHER adjacent token is short, anywhere in the line), idempotent, pure-Dart with no dependencies. Splits on a single ASCII space only; code-unit length, not grapheme width.

Maintenance

Documentation

Added inline WHY comments inside LruLfuCacheUtils._evict (lru_lfu_cache_utils.dart) for the scan, tie-break, and empty-map guard — resolves the publish-audit sparse-comments flag.

Tests

Filled the migrated-util coverage gaps harvested from Saropa Contacts (TEST-COVERAGE-migrated-utils-from-contacts.md): added a weekOfYear group (previously untested — only weekNumber/numOfWeeks were covered) including the documented week-0 boundary; precomposed- and decomposed-accent cases for String.removeLastChars (the decomposed case documents that it actually trims by grapheme cluster via substringSafe, not by code unit); four/five-element Oxford-comma cases for List<String>.joinDisplayList; and debounceAfterFirst late-consumer regression + upstream-cancel-on-consumer-cancel cases for StreamDebounceExtensions. MonthUtils/WeekdayUtils were already fully covered, and the harvested nullable-element joinDisplayList cases do not apply (the extension is on List<String>).

1.5.0 #

Ten advanced algorithm utilities from the roadmap-to-700 batch — quote-aware text folding, language detection, TF-IDF keyphrases, line-based redline diffs, Gale–Shapley stable matching, hierarchical clustering, HyperLogLog distinct counts, Pareto frontiers, time-decayed counters, and an LRU/LFU hybrid cache — each its own tree-shakeable file so apps pull in only what they use. log

Added #

foldText / unfoldText / FoldOptions (text_fold_utils.dart) — quote-aware hard-wrap and unwrap for email-reply text: foldText wraps each line to FoldOptions.width while repeating the leading quote prefix (> , > > ) on every continuation; unfoldText merges soft-wrapped continuations back into one logical line per quote level. Words longer than the available width are emitted whole (never split — no infinite loop), blank lines are paragraph boundaries, and quote-depth changes are join boundaries. Roadmap #412.
detectLanguage / LanguageGuess (language_detect_utils.dart) — best-effort dominant-language detection over a short string using character-trigram out-of-place rank distance against six compact built-in profiles (en/es/fr/de/it/pt). Returns the closest match with a 0..1 confidence, or null when the text is too short (fewer than 3 trigrams) to decide. Heuristic, no data files, Unicode-safe. Roadmap #428.
extractKeyphrases / Keyphrase / KeyphraseOptions (keyphrase_utils.dart) — TF-IDF keyphrase extraction over a single document against a corpus, returning the top-K ranked phrases (optional bigrams). Smoothed IDF guards the single-doc div-by-zero case; built-in English stopword filtering; deterministic tie-breaking. (termFrequencies is also defined here but hidden from the barrel — the established text_similarity_utils export keeps that name; import the file directly to use this one.) Roadmap #432.
redlineDiff / RedlineEntry / RedlineOp (redline_utils.dart) — line-based track-changes diff: an LCS alignment classifies each line as unchanged / added / removed / changed (adjacent remove+add runs paired into changed), each entry carrying its old and new line numbers. Immutable result, built for diff UIs. Roadmap #433.
stableMatching / StableMatchingPrefs (stable_matching_utils.dart) — proposer-optimal Gale–Shapley stable matching from two-sided strict preference lists. Handles unequal set sizes and incomplete lists (unranked parties stay unmatched), and throws ArgumentError on malformed input. Roadmap #448.
hierarchicalCluster / cutClustersByCount / cutClustersByDistance / ClusterLinkage (hierarchical_cluster_utils.dart) — agglomerative hierarchical clustering on numeric vectors with single / complete / average linkage (Lance–Williams updates), producing a dendrogram you can cut at K clusters or a distance threshold. Default Euclidean distance, pluggable via VectorDistance. Small-N intent (naive O(n³)). Roadmap #450.
HyperLogLogUtils (hyperloglog_utils.dart) — HyperLogLog-lite approximate distinct count: configurable precision (2^p registers), register-of-leading-zeros over a SplitMix64-mixed hash, harmonic-mean estimator with linear-counting small-range correction, and a pure register-wise merge. Roadmap #454.
paretoFrontier / ParetoOptions / ParetoDirection (pareto_frontier_utils.dart) — Pareto frontier (dominance filtering) over 2–3 objectives with per-dimension minimize/maximize directions; returns the non-dominated set in original order, retaining duplicates and all-equal points. Roadmap #463.
TimeDecayCounter (time_decay_counter_utils.dart) — exponential time-decayed counter with O(1) memory via lazy decay (stored value + last-updated millis), a configurable half-life, and explicit injected timestamps (no wall-clock reads, fully deterministic). Defends against out-of-order timestamps. Roadmap #479.
LruLfuCacheUtils (lru_lfu_cache_utils.dart) — bounded cache with hybrid eviction: lowest frequency first, least-recently-used as the tie-breaker. get/put/remove/length, with documented behavior for capacity 0/1 and key updates. Roadmap #480.

1.4.1 #

Small ergonomic utilities pulled from the Saropa Contacts adoption review — trailing-character trim, an integer-string predicate, and a natural-language Oxford-comma list join — so the app can delete its hand-rolled local copies. log

Added #

String.removeLastChars(int count) (string_manipulation_extensions.dart) — drop the last N characters, bounds-safe: a zero/negative count is a no-op and a count at or above length returns '' rather than throwing — so consumers stop hand-rolling the substring(0, length - n) guard (Saropa Contacts carried exactly this in string_utils_local.dart). Generalizes the existing single-character removeLastChar. Counts UTF-16 code units like String.length, not graphemes (documented). ENH-001.
String.isNumber (string_number_extensions.dart) — a getter that is true when the string parses as an integer via int.tryParse, so consumers stop writing int.tryParse(s) != null inline. Stricter than the existing isNumeric() (which parses as double): a decimal ('4.2') or scientific-notation ('1e3') value is false here but true for isNumeric(). Inherits int.tryParse's rules — accepts a leading sign and 0x/0X hex prefix, trims surrounding whitespace, and returns false for a magnitude that overflows the native 64-bit int. ENH-002.
List<String>.joinDisplayList(...) (list_string_extensions.dart) — join strings into the natural-language form ('Alice', 'Alice and Bob', 'Alice, Bob, and Carol') instead of join()'s bare a, b, c. Trims each entry and drops blank/whitespace-only ones, de-duplicates by default (isUnique, via the existing toUnique), and returns null — not '' — for an effectively-empty input so callers can distinguish "no items". The three joiners (joiner / doubleJoiner / lastJoiner, the last defaulting to the Oxford comma ', and ') are named params for locale/style control. Reuses toUnique + takeSafe. ENH-003.
Iterable<T>.randomElement({int? seed}) (iterable_extensions.dart) — the existing no-arg randomElement() gains an optional seed, so the pick can be made deterministic (same seed + same iterable → same element) for reproducible demo data and stable widget tests. Routes through the library's own CommonRandom RNG, replacing the bare dart:math Random(). Default (no seed) behavior is unchanged — still a fresh pick each run. Picks by elementAt, so the iterable is not materialized to a list. ENH-004.
String?.compareStringNullable(...) (string_compare_extensions.dart) — a null-tolerant string comparator, the counterpart to the existing compareDateTimeNullable for DateTime?. Sorting a List<String?> (or objects by a nullable string field) no longer needs a hand-rolled (a ?? '').compareTo(b ?? ''). Mirrors the DateTime convention — null sorts before non-null by default — with a caseSensitive flag (default case-insensitive) and a nullsLast flag to push nulls to the end. Comparison is String.compareTo (UTF-16 code unit, not locale collation; documented). New file, exported from the barrel. ENH-005.
StreamDebounceExtensions<T> on Stream<T> — debounce / debounceDistinct / debounceAfterFirst (stream_debounce_utils.dart) — the existing top-level debounceStream function gains a chainable extension form so reactive pipelines read as stream.debounce(d).map(...). Plus two variants a database-watch UI needs: debounceDistinct(d, {equals}) debounces and suppresses unchanged values, and debounceAfterFirst(d) emits the first value instantly then debounces the tail — the correct shape for a .watch() stream (Drift, Isar fireImmediately: true) where the initial render must be instant but bulk writes should coalesce. debounceStream is unchanged (back-compat); its deferred-listen single-subscription controller — which guarantees a late subscriber still receives the first emission (a fixed perpetual-spinner bug) — is now shared by all variants and has a dedicated regression test. ENH-006.
MonthWeekdayUtils.nthWeekdayOfMonth / lastWeekdayOfMonth (month_weekday_utils.dart) — static (year, month)-keyed weekday-occurrence helpers, the no-seed counterpart to the existing DateTime.getNthWeekdayOfMonthInYear instance extension. Calendar-construction code (DST rules, holiday tables) computes occurrences for an arbitrary year/month with no seed DateTime to hang the instance call on; these take the year/month explicitly. nthWeekdayOfMonth(year, month, n, weekday) returns the nth weekday or null when it does not exist (a 5th Friday in a 4-Friday month), guarding out-of-range n/month/weekday so an invalid argument can't compute a neighboring month; lastWeekdayOfMonth(year, month, weekday) ("last Sunday of October") has no prior equivalent — the extension only counts from the start. Reuses the instance algorithm for the nth case. New file, exported from the barrel. ENH-007.
parseCsv + CsvParseResult / CsvRowError (csv_parse_utils.dart) — an error-accumulating multi-line CSV parser layered over the existing single-line parseCsvLine, for user-facing imports that must report every bad row rather than abort on the first. Splits on \n (strips trailing \r, skips blank lines), and sends a row to result.errors (with 1-based line number, raw line, and reason) instead of result.rows on an unterminated quote (odd " count) or a column-count mismatch — the expected width coming from expectedColumns or, when hasHeader is true, the header row. ENH-008 (part 1).
retryWithPolicy gains retryIf (retry_policy_utils.dart) — a bool Function(Object error)? retryIf predicate so only transient failures are retried; returning false rethrows immediately without consuming the remaining attempts, the delay, or firing onRetry (which already existed). retryWithJitter is intentionally untouched. ENH-008 (part 2).
partialRatio / tokenSortRatio / tokenSetRatio (fuzzy_search_utils.dart) — fuzzywuzzy-style standalone string-similarity scores in [0, 1], so a consumer doing single-best-match selection with its own threshold can compute these directly and drop the external fuzzywuzzy dependency. (The per-result score on fuzzySearch was already public — this adds the missing ratio variants.) partialRatio slides a window for the best substring alignment ('New York' vs 'New York City' → 1.0); tokenSortRatio sorts tokens first for order-insensitivity; tokenSetRatio compares the shared token core against each side's remainder (forgiving of extra words). All case-insensitive, reusing LevenshteinUtils.ratio. ENH-008 (part 3).

Maintenance

Tests

CsvRowError direct-construction coverage (csv_parse_utils_test.dart) — adds a CsvRowError test group asserting all three fields (lineNumber, line, message) and toString(). The prior parseCsv tests only read lineNumber/message off returned errors, leaving the line field and toString() unexercised; this closes that gap.

Tooling

Publish audit: credit value-class constructors by field reads (audit.py) — the "untested public methods" check matched the constructor's name token in test/, so a result/data class only ever built inside library code and returned (e.g. CsvRowError, produced by parseCsv) was flagged untested even when every field was asserted off the returned instance. The check now credits a constructor as covered when all its declared final instance fields are referenced in tests, and still flags the real gap when a field is never read. Internal tooling only — not shipped to package consumers.

1.4.0 #

Eleven more utilities from the Roadmap-to-700 set — INI/.env config parsing, RFC 5545 recurrence (parse + expand), a holiday-aware business-day calendar and SLA clock, ISO 8601 interval parsing, an interval-overlap tree, a dependency resolver, a priority task scheduler, a token-bucket rate limiter, and a resource pool — plus the capabilities catalog rebuilt from the Dart AST so every public symbol is listed. log

Added #

parseIni / parseEnv (ini_parser_utils.dart) — read the two near-universal flat-config formats with no dependency. parseIni returns section → key → value (pre-header entries under the '' global section, declared-empty sections preserved); parseEnv returns a flat key → value map for dotenv files and strips the export prefix. The first = is the separator (so url=http://host:80 keeps its colon), #/; full-line comments and blanks are skipped, surrounding quotes are stripped (double-quoted values expand \n \t \r \\ \", single-quoted are literal), and # stays literal in values (no inline-comment stripping) so passwords/URLs/hex colors survive. A non-comment, non-section line lacking = throws FormatException — strict so config typos surface. Roadmap #626.
parseRrule + RecurrenceRule / RecurFrequency / RecurWeekday (rrule_parse_utils.dart) — parse a practical subset of the RFC 5545 recurrence rule used by iCalendar / Google Calendar exports (FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR;COUNT=10) into an immutable, value-equal RecurrenceRule. Supports FREQ (DAILY/WEEKLY/MONTHLY/YEARLY), INTERVAL, COUNT, UNTIL (yyyyMMdd[THHmmss][Z], UTC vs floating), BYDAY, BYMONTHDAY (1..31 / -1..-31), BYMONTH, and WKST; an optional RRULE: prefix is tolerated. Part order is irrelevant and duplicates take the last value. Unsupported parts (e.g. BYSETPOS, BYHOUR) throw FormatException rather than being silently dropped, so the subset boundary is explicit. RecurWeekday carries its DateTime.weekday number for the companion iterator. Roadmap #591.
expandRecurrence (recurrence_iterator_utils.dart) — the companion to parseRrule: lazily generate the concrete occurrences of a RecurrenceRule from a start instant, in ascending order. A sync* generator, so an unbounded rule is safe — bound it with the rule's count/until, the limit argument, or .take(n). Walks one FREQ×INTERVAL period at a time and expands the BY rules within it: WEEKLY BYDAY positioned relative to WKST, MONTHLY/YEARLY BYMONTHDAY (negative = from month-end) with non-existent days (e.g. day-31 in a 30-day month, Feb-29 off leap years) dropped, BYMONTH filtering. The start supplies each occurrence's time-of-day and UTC-ness and acts as DTSTART (earlier candidates skipped); date math uses calendar fields, not Duration, so it never drifts across DST. Roadmap #592.
BusinessCalendar (business_calendar_utils.dart) — a holiday-aware, weekend-configurable working-day calendar, extending the weekend-only free functions in date_time_business_days_utils.dart. Construct with a holiday list (matched by calendar day, time/zone ignored) and an optional custom weekend set ({DateTime.friday, DateTime.saturday} for regions that rest Fri/Sat); reuse it for isBusinessDay / isWeekend / isHoliday, nextBusinessDay / previousBusinessDay, addBusinessDays (skips weekends + holidays, negative goes backward), businessDaysBetween (count, [start, end)), and businessDaysIn (the list). Immutable after construction; calendar-field date stepping avoids DST drift. Roadmap #593.
TaskScheduler (task_scheduler_utils.dart) — runs async tasks under a fixed concurrency cap, dispatching the highest-priority waiter whenever a slot frees (FIFO among equal priorities). The piece the FIFO AsyncSemaphoreUtils can't offer: a semaphore admits waiters in arrival order, whereas this reorders the backlog by importance so an urgent task jumps ahead of queued background work (without preempting jobs already running). schedule(task, {priority}) returns a future for the task's result; a failed task never stalls the scheduler (the slot is always released). Exposes running / pending for monitoring; a sub-1 concurrency is rejected. Roadmap #655.
TokenBucketRateLimiter (rate_limiter_utils.dart) — smooths bursts to a sustainable average rate: tokens refill continuously at tokensPerSecond up to a capacity (the burst ceiling, starts full), and work spends them. tryAcquire([tokens]) is the non-blocking allow/deny primitive (no partial spend); timeUntilAvailable([tokens]) reports the wait until a denied request would succeed, so the caller chooses to drop, queue, or delay; availableTokens() exposes the current fractional count. Time is read through an injectable now closure (defaults to DateTime.now), so refill is fully deterministic under test with no Timer or wall-clock coupling; a backward clock step accrues nothing. Requesting more than capacity (or fewer than 1) throws ArgumentError. Roadmap #670.
ResourcePool<T> (resource_pool_utils.dart) — a bounded, reusing pool for expensive-to-create resources (DB connections, HTTP clients, isolates). Grows lazily up to maxSize, reuses idle resources, and when all are busy makes further borrowers wait FIFO until a release. use(action) is the leak-proof entry point (acquire → run → release, even on throw); lower-level acquire / release are also exposed, plus idleCount / inUseCount / waitingCount. A failed create rolls back the slot so a transient factory error doesn't permanently shrink the pool. close() disposes idle resources via the optional onDispose, fails waiting borrowers with StateError, and blocks new acquisitions; resources still checked out at close are the caller's to dispose. Roadmap #666.
parseIsoInterval (iso_interval_parse_utils.dart) — parse an ISO 8601 time interval into a DateTimeRange, supporting all three forms: start/end, start/duration, and duration/end (separated by /). Timestamps use Dart's native ISO parsing; the duration half is an ISO 8601 duration (P[nY][nM][nW][nD][T[nH][nM][nS]], weeks folded into days, fractional time components allowed) applied with calendar arithmetic so years/months add as calendar units (Jan 31 + P1M normalizes correctly) and time-of-day + UTC-ness are preserved. A missing separator, a malformed half, two durations, or an inverted (start after end) interval throws FormatException. Roadmap #646.
IntervalTree<T> + IntervalEntry<T> (interval_tree_utils.dart) — an overlap (stabbing) query index over inclusive [low, high] intervals: queryPoint(x) returns every interval containing a point, queryRange(lo, hi) every interval overlapping a range, and hasOverlap(lo, hi) short-circuits on the first hit — all O(log n + k) instead of an O(n) scan. Built once from a fixed set, balanced by median split and augmented with each subtree's max-high so branches prune. Distinct from IntervalSchedulingUtils (max non-overlapping subset) and weightedIntervals (DP optimizer): this is the lookup for calendar conflicts, IP-range matching, gap detection. Results come back in ascending low order. Roadmap #494.
resolveDependencies + PackageManifest / DependencyResolution (dependency_resolver_utils.dart) — resolve a set of root requirements against a universe of available package versions (each with its own dependency constraints), picking one concrete version per package and returning a topological install order (dependencies first). Constraint matching supports */any, caret (^1.2.0, including 0.x minor-lock semantics), the comparison operators >= <= > < == =, bare exact versions, and space-separated compound constraints (AND). Reuses compareVersions for ordering and topologicalSort for the install order + cycle detection; throws DependencyResolutionException on an unknown package, an unsatisfiable constraint set, or a cycle. Greedy highest-version over a fixpoint worklist (terminating, no backtracking — documented as simple-lock-file scope, not a SAT solver). Roadmap #540.
SlaCalculator + BusinessHours / OpenWindow (sla_calculator_utils.dart) — compute SLA deadlines and elapsed working time against a weekly open-hours schedule, optionally skipping holidays via a BusinessCalendar (#593). BusinessHours holds open windows per weekday (OpenWindow(startMinute, endMinute), half-open) with a uniform factory for the common "9-to-5 on weekdays" case. addWorkingTime(start, amount) returns the instant N working hours later (rolling across close boundaries, weekends, and holidays; clamps a before-open start to open); workingTimeBetween(start, end) sums open-hour time in a span; isOpen(at) tests a single instant. Calendar-field stepping avoids DST drift; a fully-closed schedule throws StateError rather than looping. Roadmap #595.
QuietHours + QuietWindow (quiet_hours_utils.dart) — "do not disturb" time-of-day blackout windows for deferring notifications. QuietWindow(startMinute, endMinute) is a daily minute-of-day window that may wrap past midnight (start > end, e.g. 1320→420 = 22:00–07:00). isQuiet(at) tests membership; quietUntil(at) returns the instant quiet ends when at is muted (else null), chaining back-to-back/overlapping windows into one contiguous stretch — so a held notification can be scheduled for exactly when quiet lifts. A daily factory covers the single-window case. Simpler than BusinessHours (a per-weekday OPEN schedule); quiet windows apply every day. Roadmap #613.
BoundedWorkQueue<T> (bounded_work_queue_utils.dart) — a fixed-capacity async producer/consumer channel with backpressure: push(item) returns a future that stays pending while the buffer is full (throttling a fast producer to the consumer's pace) and pull() waits while empty. Hand-off is FIFO and direct (a waiting consumer receives a pushed item without it touching the buffer). Non-blocking tryPush (false when full) / tryPull (null when empty) variants, plus length / isFull / pendingProducers / pendingConsumers. close() blocks new pushes, fails blocked producers/consumers, and lets consumers drain already-buffered items before erroring. Complements TaskScheduler (which is for fire-and-forget concurrency, not flow control). Roadmap #654.
SlidingWindowRateLimiter (sliding_window_rate_limiter_utils.dart) — enforces "no more than limit events in any trailing window" exactly, by keeping recent event timestamps and counting those still inside the window. The precise counterpart to the token bucket (#670): the bucket smooths to an average rate with O(1) memory and allows bursts to its capacity, this gives an exact rolling-window count with O(limit) memory and no over-limit burst. tryAcquire() records-and-allows or denies; currentCount() and timeUntilAvailable() (when the oldest event ages out) round it out. Time is read through an injectable now closure for deterministic tests; the window's lower bound is exclusive (an event exactly window old has expired). Roadmap #685.
ReadWriteLock (read_write_lock_utils.dart) — an async reader/writer lock: many read(action) scopes run concurrently OR one write(action) runs exclusively, never both — the right primitive for a read-heavy cache where AsyncMutexUtils would needlessly serialize reads. Writer-preference by default (a waiting writer blocks newly-arriving readers, so a stream of reads can't starve a write); writerPreferred: false switches to reader-preference for max read throughput. Both scopes release on throw and expose activeReaders / isWriteLocked / waitingReaders / waitingWriters. Roadmap #653.
MultiIndexCollection<T> (multi_index_collection_utils.dart) — an in-memory table maintaining several secondary hash indexes at once, so the same items can be looked up by different keys in O(1) instead of scanning (a user list queried by id, by email, AND by city). Construct with named key extractors; add/addAll/remove keep every index in sync (empty buckets pruned). getBy(index, key) returns the matching list (non-unique by default), getOneBy the first match (unique-index convenience), containsKey tests presence; all / length / indexNames expose the contents. Distinct from buildInvertedIndex (text search) and the row/column transposers. Roadmap #505.
evaluateExpression / evaluateBool (expression_evaluator_utils.dart) — evaluate a string expression over a supplied variable map with NO host access (no function calls, no property access, no eval), so untrusted formula input (a rule, computed column, feature-flag condition) runs without executing arbitrary code. Supports numbers, 'string'/"string" literals, true/false, named variables, arithmetic (+ - * / %, unary -), comparison (== != < <= > >=), boolean (&& || !), and parentheses, with correct precedence. Lexing reuses the tokenize pipeline (#434). Any syntax error, unknown variable, or type mismatch throws FormatException; evaluateBool is the convenience that requires a boolean result. Roadmap #634.
filterRows / compileFilter + RowPredicate (sql_filter_utils.dart) — filter a list of Map<String, Object?> rows with a SQL WHERE-style clause (age > 18 AND city LIKE 'New%') instead of a hand-written closure. compileFilter parses the clause once into a reusable RowPredicate; filterRows applies it. Grammar: AND/OR/NOT/parentheses, comparisons = <> != < <= > >=, LIKE (% any run, _ one char, case-sensitive), IN (…), IS [NOT] NULL, and literals (number, 'string', true, false, null); keywords are case-insensitive. Ordering across incomparable types yields no match (SQL's unknown→false). Record-oriented and SQL-flavored, distinct from the scalar evaluateExpression (#634); both reuse the tokenize lexer. Roadmap #633.
expandUriTemplate (url_template_utils.dart) — expand RFC 6570 URI templates against a variable map, the way an API client builds a request URL from /users/{id}{?fields*}. Covers Levels 1–3 plus the prefix ({var:3}) and explode ({list*}) modifiers: simple {var} and multiple {a,b}, reserved {+var} / fragment {#var} (keep reserved chars), and the . / ; ? & operators with their separators and name= formatting for the named ones. Values may be string/number/bool/List; an undefined variable contributes nothing; percent-encoding is UTF-8 and RFC 3986-correct. Complements UriPattern (#630, which matches paths) — this builds them. Roadmap #629.
LogLineParser (log_line_parser_utils.dart) — parse log lines against a format template with {field} placeholders, extracting each field into a Map<String, String>. Literal text between placeholders (spaces, brackets, quotes) delimits the fields, so the common access-log shapes parse without a bespoke regex. Presets LogLineParser.apacheCommon() / apacheCombined() / nginxCombined() cover the standard formats; a custom format is just a template string, and a field can carry an explicit regex ({status:\d+}) when the default lazy match would over-match. parse(line) returns the field map or null on a non-match; fields lists the names in order. Roadmap #631.

Maintenance

Changed

Renamed the two private _Node helper classes to _IntervalNode (interval_tree_utils.dart) and _TrieNode (trie_utils.dart) to clear the publish audit's duplicate-class-name flag (file-private, no public API change).
Inline WHY-comments added to the parser/iterator internals flagged by the publish audit (no behavior change). The recursive-descent levels of the expression evaluator (_equality/_comparison/_additive/_multiplicative/_primary/_resolveIdentifier) and SQL filter (_comparison/_value/_keywordLiteral/_applyOrder), the RRULE part dispatcher (apply), the recurrence candidate generators (_candidatesFor/_dailyCandidates), the interval-tree overlap prune (_anyOverlap), the quiet-hours latest-end scan (_latestEndCovering), the URI-template expander (_expandExpression), and the INI escape decoder (_escapeChar) now carry block-level comments explaining precedence climbing, the augmented-tree pruning rules, BY-filter gating, and the type-coercion/error-path decisions a cold reader couldn't infer from the identifiers alone.
CAPABILITIES.md rebuilt from the Dart AST so it lists EVERY public symbol + a release/date header (docs/tooling only, no API change). Replaced the doc-comment-gated regex generator with tool/gen_capabilities.dart, which parses each file with package:analyzer and enumerates every public declaration — documented or not. This closes two gaps in the old output: undocumented public symbols were silently dropped (a container type like DateConstants never appeared, and getters such as CircuitBreakerUtils.isClosed were missing), and field initializers were mislabeled (final Duration x = Duration(...) showed up as a Duration constructor; function-typed fields as a Function constructor). Result: 1834 symbols across 383 files, up from 1528/371, with correct kinds. The title now carries **Release X.Y.Z** · Generated yyyy-mm-dd (version read from pubspec.yaml), so each snapshot is identifiable. Added analyzer as a direct dev_dependency (already resolved transitively at ^11.0.0, no new download) so the tool script can import it. publish.py step 4 now runs the Dart generator (dart run tool/gen_capabilities.dart).

Fixed

Quieted IDE-only stylistic-lint false positives in async/parsing utilities (no API or behavior change). The analysis-server view of saropa_lints surfaces opt-in stylistic-tier rules that flutter analyze (recommended tier) does not enforce — several of which misfire on correct code: prefer_reusing_assigned_local on a recursive-descent parser's token-consuming _and()/_equality()/_not() calls (reusing the local would skip a parse), avoid_string_concatenation_loop on numeric _asNum(...) + _asNum(...), and prefer_correct_callback_field_name / prefer_correct_handler_name on an injected now clock, an indexers map, a start thunk, and the isClosed state getter. Added targeted // ignore: saropa_lints/<rule> -- reason suppressions (the plain form is not honored for these rules) plus two trailing commas, and filed upstream false-positive reports for the two rules whose logic is still wrong in source (prefer_reusing_assigned_local, prefer_correct_handler_name). Affected: bounded_work_queue_utils.dart, rate_limiter_utils.dart, read_write_lock_utils.dart, sliding_window_rate_limiter_utils.dart, task_scheduler_utils.dart, multi_index_collection_utils.dart, expression_evaluator_utils.dart, sql_filter_utils.dart, log_line_parser_utils.dart, url_template_utils.dart, business_calendar_utils.dart, sla_calculator_utils.dart.
CAPABILITIES.md descriptions no longer truncate at inline periods (docs/tooling only). firstSentence in tool/gen_capabilities.dart cut at the first . , so any description with an inline period lost everything after it (Target false positive rate (e.g. dropped the 0.01 for 1% example; Splits … (split on . dropped ! ?). It now ends the sentence only on a period that sits outside backticks and balanced parentheses, is followed by a space/end, and is not an abbreviation (e.g., i.e., vs.) or single-letter dot, so the example survives intact.
CAPABILITIES.md no longer leaks internal roadmap #NNN markers (docs/tooling only). Internal backlog references in dartdoc (Async barrier: wait for N events — roadmap #676.) were emitted verbatim to the customer-facing catalog. firstSentence now strips them after the sentence cut, with no dangling period (164 leaked references → 0).
CAPABILITIES.md no longer promotes a member's dartdoc to the file purpose (docs/tooling only). When a file had no library-level doc, filePurpose used the first member's /// (e.g. a field doc on html/html_entity_data.dart) as the whole file's purpose. It now suppresses a leading block whose offset matches the first declaration's doc comment, so only a genuine library/floating note is used. Regression tests: test/tool/gen_capabilities_test.dart.

1.3.0 #

Ten new utilities from the Roadmap-to-700 set: a forgiving JSON-to-model reader, a CSV writer, a path-template matcher, stream zip/combine operators, multi-key grouping, a swappable cache interface with a write-through loader, date-format presets, ICU plural/select message lite, timing wrappers, and a JSON pretty-printer. log

Added #

JsonModelReader (json_model_mapper_utils.dart) — reads typed fields (requireString/requireInt/requireBool/requireDouble/requireList/optionalString/child) from decoded JSON, accumulating a ValidationErrors list instead of throwing on the first bad field. Distinguishes missing (code: 'missing') from wrong-type (code: 'type'), widens int→double, and reports nested failures with dotted paths (address.city) on a shared collection. Roadmap #637.
writeCsvLine / writeCsv (csv_writer_utils.dart) — the inverse of parseCsvLine: encode rows to CSV with RFC 4180 auto-quoting (a field is quoted only when it contains the delimiter, a quote, CR, or LF; embedded quotes are doubled). Configurable delimiter (TSV via \t), eol (CRLF default), and forceQuote. Round-trips with parseCsvLine. Roadmap #622.
UriPattern (uri_pattern_utils.dart) — compile a path template (/users/{id}/posts/{slug}) and match() concrete paths to extract named segment params, or null on no match. Supports a typed {id:int} constraint (matches only integer segments) and ignores leading/trailing slashes. Segment-based, no regex. Roadmap #630.
zipStreams / combineLatestStreams (stream_combine_utils.dart) — zipStreams pairs two streams by index (lock-step, drops the unpaired tail); combineLatestStreams emits the combination of the latest values whenever either source emits, once both have produced a value. Both forward errors, complete when their sources do, and cancel sources on cancel. combineLatest subscribes lazily on listen. Roadmap #661.
groupByKeys / aggregateByKeys / MultiKey (multi_key_group_utils.dart) — group an iterable by several key selectors at once into value-equal MultiKey buckets (a raw List can't be a map key), then optionally reduce each bucket with an aggregator (count/sum/avg per (country, year)). Preserves first-seen order. Roadmap #477.
Cache<K, V> interface + WriteThroughCache (cache_interface.dart) — a common get/set/clear contract now implemented by LruCache, TtlCache, and SizeLimitCache, so call sites can depend on "a cache" and swap the eviction policy freely. WriteThroughCache wraps any Cache with an async loader: a miss loads once and stores (read-through), concurrent misses for the same key share one in-flight load (thundering-herd guard), and a failed load is not cached so the next call retries. Roadmap #523.
formatDateShort / formatDateMedium / formatDateLong + DateFormatNames (date_format_preset_utils.dart) — dashboard date presets without the intl dependency: short is ISO 2026-06-10 (locale-independent, sorts lexically), medium is Jun 10, 2026, long is Wednesday, June 10, 2026. Month/weekday names are injected via DateFormatNames (English default) so the presets render in any language while the layout stays fixed. Roadmap #615.
icuPlural / icuSelect (icu_message_utils.dart) — ICU MessageFormat lite: icuPlural(count, {zero, one, other}) picks a plural form (English cardinal rules) and substitutes # with the count; icuSelect(value, cases, {other}) picks a gendered/category form. No parser, no intl. Unlike String.pluralize (appends an s), these choose among caller-supplied, locale-routable forms. Roadmap #414.
observeAsync / observeSync (observability_utils.dart) — wrap an operation to measure its wall-clock duration and report the outcome through optional onSuccess(elapsed, result) / onError(elapsed, error, stackTrace) hooks (logging, metrics, tracing), returning the result unchanged or rethrowing the original error. Transparent: timing only, never swallows a failure. Roadmap #680.
prettyPrintJson (json_pretty_print_utils.dart) — render decoded JSON as an indented string with a configurable indent width (0 for compact single-line) and optional recursive sortKeys (via canonicalizeJson) for stable, diff-friendly output. Roadmap #436.
tokenize + TokenRule / Token (tokenizer_pipeline_utils.dart) — a reusable lexer core: walk input taking the first ordered TokenRule that matches as a prefix, emitting Token(type, value, start) or skipping (shouldSkip rules like whitespace/comments). Rule order resolves ambiguity deterministically; an unmatched position throws FormatException with the offset; zero-width matches are rejected so the cursor always advances. Roadmap #434.
diffSequences / diffWords / diffSentences + SeqDiffOp / SeqDiffKind (text_diff_structured_utils.dart) — LCS-based structured diff returning an ordered equal/insert/delete edit script (not a rendered string) so a UI can color or animate changes. diffWords/diffSentences reuse the existing tokenizeWords/tokenizeSentences splitters; the generic diffSequences<T> engine works on any list. Roadmap #415.
empiricalCdf / cdfAt / cumulativeHistogram + CdfPoint (cdf_utils.dart) — the cumulative view of numeric samples: empiricalCdf returns one CdfPoint(value, p) per distinct value (p = fraction ≤ value), cdfAt evaluates the CDF at a point, and cumulativeHistogram is the running total of the existing histogramFixed. Complements the bin-counting histogram utils. Roadmap #574.
validateJsonSchema + FieldSchema / JsonType (json_schema_utils.dart) — declare a JSON object as a field → FieldSchema map and validate it in one pass, collecting a ValidationErrors list: required presence (missing), type match (type), and allowed-set/enum membership (enum). A non-map input yields a single object-level type error. Companion to JsonModelReader. Roadmap #636.
groupedStats + NumericStats (grouped_stats_utils.dart) — group an iterable by a key and compute the common numeric bundle (count, sum, min, max, mean) per group in a single pass, no custom reducer. Every returned group has count ≥ 1 (no divide-by-zero in mean). The "totals and averages per category" report in one call. Roadmap #571.

Maintenance

Changed

Lint cleanup across lib/ (no API or behavior change). Resolved 68 of the live saropa_lints violations a full insanity-tier scan surfaced: added explicit type arguments to 46 empty collection literals (<int>[], <Map<String, Object?>>[], etc.) so they match the codebase's double-explicit convention; reused an already-assigned local in deepMerge instead of re-reading MapEntry.value; and extended the existing documented // ignore directives on the diagnostic debugPrint sites in JsonUtils, Base64Utils, and async_more_utils to also cover the sibling avoid_debug_print / avoid_stack_trace_in_production rules. Reworded two prose design-notes so they no longer trip prefer_no_commented_out_code, and suppressed the Flutter-app-lifecycle rules (avoid_work_in_paused_state, require_workmanager_for_background) on HeartbeatUtils with a reason, since they do not apply to a pure-Dart timer primitive. The remaining prefer_list_first hits are string-index false positives (String has no .first) and were left unchanged.
Publish-audit accuracy + coverage (no API or behavior change). Rebuilt the scripts/modules/audit.py declaration matcher and test-discovery so the publish audit stops reporting false positives: doc-header findings 94→0, recursion findings 29→0 (the check was removed — every hit was legitimate recursion), and per-method "0 tests" false positives eliminated via a global tested-identifier scan (methods tested in combined files like duration_format_parse_test.dart are now credited). Wrote tests for the 29 genuinely-untested public methods (new *_untested_test.dart / feature test files under test/). Added explanatory WHY-comments to 61 of 92 under-commented function bodies across lib/ (algorithm intent: k-way merge, A*, Dijkstra, Floyd–Warshall, knapsack, LIS, Rabin-Karp, kmeans, trial-division primes, LCS, bin-packing, inverted index, and more); 31 remain as tracked documentation debt.
Closed the remaining 31 under-commented bodies + fixed the last audit warning (no API or behavior change). Added WHY-comments to the final 31 function bodies the audit still flagged (prefixFrequencyTable, maxWeightIntervals, rank, addBusinessDays, _buildDurationParts, roundMinutes, lowestCommonAncestor, diff, takeEveryNth/skipEveryNth, allEqual, renameKeys, upsert, getNested, abbreviateName, decodeVarint, linearRegression, simpleMovingAverage, outlierIndicesByMAD, stratifiedSampleIndices, didYouMean, stripSubstring, wrapAtChars, allIndicesOf, textFingerprint, cosineSimilarity, tokenizeSentences, pathRelative, validateOneOfRequired, parseIpv4, jwtPayload) — documenting the invariants and failure modes the names alone can't carry (window-sort precondition, MAD-zero divide guard, varint overflow bail-out, base64url padding restore, and so on), with the big-O prose phrased to avoid prefer_no_commented_out_code false positives. Corrected the lone live analyzer warning by prefixing the WriteThroughCache suppression with the plugin namespace (// ignore: saropa_lints/require_cache_expiration) so it is actually honored — expiration is delegated to the wrapped Cache. dart analyze is now clean across lib/.

1.2.0 - 2026-06-10 #

A handful of everyday helpers: skip nulls while mapping, a readable none() check, sum or average by a selector, middle-eliding for long strings and paths, and float comparison that shrugs off rounding error. The published download is slimmer, too. log

Added #

Iterable.none(predicate) (iterable_none_extensions.dart) — the boolean complement of any; returns true when no element matches (and true for an empty iterable, matching every). Reads as intent and removes the easy-to-misplace !any(...).
Iterable.mapNotNull(selector) / Iterable<T?>.whereNotNull() (iterable_map_not_null_extensions.dart) — map-and-drop-nulls in a single lazy pass, recovering the non-nullable result type without a separate whereType/cast.
Iterable.sumBy(selector) / Iterable.averageBy(selector) (iterable_sum_by_extensions.dart) — numeric sum/mean over a selector, so reductions work on any element type. sumBy returns 0 for empty; averageBy returns null for empty (no silent NaN).
String.truncateMiddle(maxLength, {ellipsis}) (string_truncate_middle_extensions.dart) — elides the middle while keeping both ends visible (paths, hashes, IDs). Grapheme-cluster safe, so emoji are never split; degrades to a leading cut when the budget is too small.
double.isCloseTo(other, {relativeTolerance, absoluteTolerance}) (double_close_to_extensions.dart) — tolerance-based float comparison ((0.1 + 0.2).isCloseTo(0.3) is true). Combines an absolute floor (meaningful near zero) with a relative tolerance (scales to large magnitudes); NaN is never close, same-sign infinities are.
nthSmallest / nthLargest (quickselect_utils.dart) — k-th order statistic via quickselect (median-of-three pivot), O(n) average without a full sort; returns null for an out-of-range k and never mutates the input.
Iterable.stableSortBy / stableSort (iterable_stable_sort_extensions.dart) — stable sort that preserves the input order of equal elements, unlike Dart's List.sort (which is not guaranteed stable) — needed for correct multi-pass sorting.
longestCommonSubsequence / longestCommonSubsequenceLength (lcs_sequence_utils.dart) — LCS of two lists (order-preserving, gaps allowed), distinct from the existing contiguous LCS-substring; the length variant uses O(min) space.
deepFreeze (deep_freeze_utils.dart) — recursively unmodifiable copy of a map/list/set tree; any mutation at any depth throws UnsupportedError. A copy, so later edits to the original do not show through.
getByJsonPath (json_path_utils.dart) — read a value from decoded JSON by a simple $.a.b[0] path; returns null for any missing/out-of-range segment. Deliberately not full JSONPath (no wildcards/filters/recursive descent).
CronSchedule.tryParse + nextRunAfter (cron_utils.dart) — parse a 5-field cron expression (*, lists, ranges, steps) and compute the next run after a given time, with Vixie-cron OR semantics for the two day fields; returns null for malformed expressions and for impossible schedules (no match within four years).
parseAcceptLanguage (accept_language_utils.dart) — parse an Accept-Language header into LanguageRanges ordered by quality (stable on ties); drops q=0, skips malformed entries.
parseRangeHeader (range_header_utils.dart) — parse an HTTP Range header (bytes= unit) into ByteRanges, supporting explicit, open-ended, suffix, and multi-range forms; null on unsupported unit or any malformed range.
canonicalizeUrl (url_canonicalize_utils.dart) — canonical URL form for dedupe/cache keys: lower-cased scheme/host, default port dropped, query parameters (and repeated values) sorted, optional fragment removal.
debounceStream (stream_debounce_utils.dart) — re-emits stream values only after a quiet gap (latest-wins per burst); flushes the trailing pending value on close and forwards errors immediately.
CAPABILITIES.md — a complete per-symbol index of every public utility (1,391 symbols across 352 files), grouped by category with one-line descriptions and per-file import paths, for teams evaluating or adopting the library. Covers every documented public member — methods, getters, functions, constructors, fields, enum values, setters, typedefs, classes, and extensions (verified: zero undocumented public members repo-wide). Generated by tool/gen_capabilities.py from the documented public API; linked from the README's "What's Included" section.

Fixed #

First 1.2.0 publish attempt was rejected by pub.dev validation (exit 65), so the tag/release existed but pub.dev served nothing. Two artifacts — .favorites.json (VS Code Favorites extension state) and coverage/lcov.info (generated by flutter test --coverage) — were tracked in git while also matching .gitignore rules. dart pub publish --dry-run emits a warning for "checked-in files ignored by a .gitignore" and exits 65, which the publish workflow treats as a hard failure (the .pubignore tarball trim does not clear this warning — it is about git tracking state, not package contents). Both files are now untracked (kept on disk); the dry run passes and 1.2.0 reached pub.dev. No lib/ changes.
16 implemented utilities were unreachable via the barrel import. Extensions and helpers that only had direct file imports — cartesian, diff, firstWhereOrElse, flattenDeep, groupByTransform, mapIndexed, minBy/maxBy, consecutivePairs (and the rest of iterable_more), allPairs, sortByThenBy, splitAt, symmetricDifference, shuffleWithSeed, topK, race/allSettled/retryTimes, and GestureUtils — are now exported from package:saropa_dart_utils/saropa_dart_utils.dart, honoring the README's "one import" promise. A new test/barrel_exports_test.dart imports only the barrel and exercises each, so the reachability (and absence of any method-name ambiguity) is regression-guarded. The internal html_entity_data.dart data table stays unexported by design.

Maintenance

Changed

Publish audit (scripts/modules/audit.py) rebuilt for accuracy — ~600 noisy findings reduced to ~220 genuine ones. The audit's findings were dominated by artifacts of its regex declaration matcher and test-file mapping, not real defects. Changes:
- Declaration matcher replaced with a balanced-delimiter parser. The old regex both MISSED real generic functions (Future<T> raceFirst<T>(... Function() ...) never matched, so it was invisible to every check) and mis-captured type names from generic bounds / constructor calls / string literals (nWayMerge<T extends Comparable<…>>( was reported as Comparable; = Completer<T>() as Completer; 'TrieUtils()' inside a string as TrieUtils). The parser finds the real name (the identifier before the parameter (, after an optional balanced <…>), strips string literals, and rejects names in expression/call/list-element position by the preceding character and the post-) tail.
- Test discovery made global. The per-parameter check mapped each lib file to a single <name>_test.dart, but this repo groups several lib files under one combined test (e.g. duration_format_utils.dart → duration_format_parse_test.dart), so well-tested methods reported 0 tests. It now counts references across all of test/. Also fixed a break that credited only the first member per test block, zeroing the rest.
- Per-parameter check redefined to "untested public methods (with parameters)". Per-parameter-variation coverage is unmeasurable by name matching, so the old "N+1 test blocks" floor was an arbitrary proxy; the measurable, meaningful signal is whether a method is referenced by ANY test.
- Non-public declarations skipped for doc/test/param checks (private members, ClassName._() constructors, members of private types like class _Node); nested local closures excluded via a containment filter; @override members excluded from the doc check (they inherit docs); the doc-walk now skips multi-line signature continuations.
- "Possible recursion" check removed — every hit was legitimate recursion (tries, graph traversal, deep transforms) and a regex cannot do base-case analysis; the genuine empty-catch smell is kept.
- Inline-comment density no longer counts plain final/var declarations (policy: "well-named identifiers cover WHAT; comment WHY on branches/loops").
- Net on this repo: missing-doc-headers 94→1 (the 1 is a local closure under a multi-line signature), recursion 29→0, untested-public-methods now 29 (all verified genuinely untested), sparse-comments 190 (genuine inline-comment debt). The remaining findings are real, not noise.
publish.py now regenerates CAPABILITIES.md automatically during release (step 4, after the remote-sync check and before formatting), so the per-symbol index can never ship stale — the release commit stages it via git add -A. Non-fatal if the generator errors.
ROADMAP_TO_400.md reached 400/400 and was archived to plans/history/2026.06/2026.06.10/. All originally-outstanding items are implemented; ROADMAP_TO_700.md remains the active forward roadmap.
README now carries a quality-standard banner stating the bar every utility meets — world-class lint-clean code, detailed dartdoc on every public member, and comprehensive unit-test coverage.
Hardened today's new utilities to that bar. Documented the LanguageRange and ByteRange constructors, resolved trailing-comma lints in deep_freeze_utils.dart, and reworded two comments that tripped the commented-out-code heuristic. All 15 new files pass dart analyze (including saropa_lints and public_member_api_docs) with zero issues.
Trimmed the published pub.dev tarball via .pubignore. Repo-internal directories that no consumer needs — test/, plans/ (130 files), tool/, bugs/, reports/, scripts/, and the coverage/ artifact — are now excluded from the package. lib/, example/, assets/, and the standard README/CHANGELOG/LICENSE/pubspec files remain. Takes effect on the next release; does not alter the already-published 1.1.6.
Every release in CHANGELOG.md and CHANGELOG_HISTORY.md now carries a plain-language opening line followed immediately by a [log] link to that version's tagged changelog (https://github.com/saropa/saropa_dart_utils/blob/vX.Y.Z/CHANGELOG.md; [Unreleased] points at main). The maintenance-note template URL was corrected from the saropa-log-capture repo to saropa_dart_utils.
publish.py (v2.8) now enforces the release-intro/log-link convention before publishing. A new pre-check requires the release section to open with a plain-language intro line and pins its [log] link to the proposed version's tag (rewriting the [Unreleased] template's main reference to vX.Y.Z automatically). A missing intro prompts retry / ignore / abort, defaulting to retry so the operator can add it in an editor and re-check without restarting the run. New version_changelog helpers has_release_intro and update_log_link carry the logic.

1.1.6 #

A republish fix: 1.1.5's exact content reaches pub.dev now that a missing test dependency is declared. No library changes. log

Fixed #

Release fix: dart pub publish failed validation (exit 65), so 1.1.5 never reached pub.dev. test/async/debounce_utils_test.dart and test/async/heartbeat_utils_test.dart import package:fake_async/fake_async.dart, but fake_async was only available transitively (via flutter_test) and was not declared in pubspec.yaml. pub.dev rejects publishing a package whose sources import an undeclared library. Added fake_async: ^1.3.3 to dev_dependencies (matching the version flutter_test resolves). No lib/ changes — this republishes the 1.1.5 content under 1.1.6.

Older versions: Entries for 1.1.5 and earlier live in CHANGELOG_HISTORY.md.

                                    ....
                             -+shdmNMMMMNmdhs+-
                          -odMMMNyo/-..``.++:+o+/-
                       /dMMMMMM/               `````
                      dMMMMMMMMNdhhhdddmmmNmmddhs+-
                      /MMMMMMMMMMMMMMMMMMMMMMMMMMMMMNh/
                    . :sdmNNNNMMMMMNNNMMMMMMMMMMMMMMMMm+
                    o     ..~~~::~+==+~:/+sdNMMMMMMMMMMMo
                    m                        .+NMMMMMMMMMN
                    m+                         :MMMMMMMMMm
                    /N:                        :MMMMMMMMM/
                     oNs.                    +NMMMMMMMMo
                      :dNy/.              ./smMMMMMMMMm:
                       /dMNmhyso+++oosydNNMMMMMMMMMd/
                          .odMMMMMMMMMMMMMMMMMMMMdo-
                             -+shdNNMMMMNNdhs+-
                                     ``

Made by Saropa. All rights reserved.

Learn more at https://saropa.com, or mailto://dev.tools@saropa.com

saropa_dart_utils 1.6.3
saropa_dart_utils: ^1.6.3 copied to clipboard

Metadata

Changelog #

1.6.3 #

1.6.2 #

Changed #

Deprecated #

Added #

Security #

Fixed #

1.6.1 - 2026-06-12 #

Fixed #

1.6.0 - 2026-06-12 #

Fixed #

Added #

1.5.1 - 2026-06-11 #

Added #

1.5.0 #

Added #

1.4.1 #

Added #

1.4.0 #

Added #

1.3.0 #

Added #

1.2.0 - 2026-06-10 #

Added #

Fixed #

1.1.6 #

Fixed #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

saropa_dart_utils 1.6.3 saropa_dart_utils: ^1.6.3 copied to clipboard

Metadata

Changelog #

1.6.3 #

1.6.2 #

Changed #

Deprecated #

Added #

Security #

Fixed #

1.6.1 - 2026-06-12 #

Fixed #

1.6.0 - 2026-06-12 #

Fixed #

Added #

1.5.1 - 2026-06-11 #

Added #

1.5.0 #

Added #

1.4.1 #

Added #

1.4.0 #

Added #

1.3.0 #

Added #

1.2.0 - 2026-06-10 #

Added #

Fixed #

1.1.6 #

Fixed #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

saropa_dart_utils 1.6.3
saropa_dart_utils: ^1.6.3 copied to clipboard