Skip to content

Rewrite package from the ground up#5

Merged
mark-dropbear merged 9 commits intomainfrom
rewrite
Feb 27, 2026
Merged

Rewrite package from the ground up#5
mark-dropbear merged 9 commits intomainfrom
rewrite

Conversation

@mark-dropbear
Copy link
Contributor

No description provided.

inline lints directly in analysis_options.yaml

Signed-off-by: mark <mark@dropbear.dev>
Signed-off-by: mark <mark@dropbear.dev>
Signed-off-by: mark <mark@dropbear.dev>
@gemini-code-assist
Copy link
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a significant overhaul of the iri package, fundamentally changing its internal architecture to be a wrapper around Dart's built-in Uri class. This rewrite aims to provide a more robust and compliant implementation of Internationalized Resource Identifiers (IRIs) by streamlining Unicode handling, Punycode conversions, and offering a more intuitive API for developers.

Highlights

  • Complete Package Rewrite: The iri package has been completely rewritten to wrap Dart's native Uri class, enhancing RFC 3987 compliance and leveraging existing platform capabilities.
  • Unicode-Aware API: Introduced Unicode-aware component accessors (host, path, query, fragment, userInfo) and automatic Punycode conversion for hostnames in toUri().
  • Enhanced Constructors and Static Methods: Added support for standard constructors like Iri(), Iri.http(), Iri.https(), Iri.file(), and static methods Iri.parse() and Iri.tryParse() for flexible IRI creation.
  • Immutability and Equality: The Iri class is now immutable, marked with @immutable, and includes proper equality support for consistent behavior.
  • Normalization Improvements: Automatic application of NFKC (Normalization Form KC) to all inputs and support for international domain separators during parsing and conversion.
Changelog
  • CHANGELOG.md
    • Updated version to 0.2.0.
    • Added entry for complete package rewrite as a wrapper around native Uri class.
    • Noted automatic Punycode conversion for hostnames in toUri().
    • Highlighted Unicode-aware component accessors (host, path, query, fragment, userInfo).
    • Included support for standard constructors: Iri(), Iri.http(), Iri.https(), Iri.file().
    • Mentioned static methods Iri.parse() and Iri.tryParse().
    • Added immutable design with @immutable and equality support.
  • README.md
    • Updated package description to reflect the new Iri class and its wrapper implementation.
    • Revised feature list to detail standard compliance, Punycode support, Unicode-awareness, normalization (NFKC), IDNA separators, Mailto support, familiar API, and immutability.
    • Added a new section on RFC 3987 compliance and known limitations.
    • Updated getting started and usage examples to demonstrate the new Iri.parse() and component-based constructors.
  • analysis_options.yaml
    • Updated include directive from package:oath/strict.yaml to package:lints/recommended.yaml.
    • Added strict language analysis options for strict-casts, strict-inference, and strict-raw-types.
    • Expanded the list of linter rules significantly to enforce stricter code quality and style.
  • doc/api/__404error.html
    • Updated theme toggle button HTML structure and accessibility attributes.
    • Adjusted layout and styling for the 404 error page content.
    • Updated package version from 0.1.1 to 0.2.0 in the footer.
    • Modified library link from iri to iri/.
  • doc/api/index.html
    • Updated theme toggle button HTML structure and accessibility attributes.
    • Revised markdown content to reflect the new Iri class, features, and RFC compliance details.
    • Updated usage examples to use Iri.parse() and component-based constructors.
    • Changed class reference from IRI to Iri in the Libraries section.
    • Updated package version from 0.1.1 to 0.2.0 in the footer.
    • Modified library link from iri to iri/.
  • doc/api/index.json
    • Updated package description to include RFC 3987 URL.
    • Renamed class entries from iri.IRI to iri.Iri.
    • Updated constructor entries to reflect new Iri constructors (Iri.file, Iri.fromUri, Iri.http, Iri.https, Iri.new, Iri.parse).
    • Modified property descriptions for clarity (e.g., fragment, host, path, query, userInfo are now Unicode-aware).
    • Added new methods: replace, resolve, resolveIri, toUriString, tryParse.
  • doc/api/iri/Iri-class-sidebar.html
    • Added new file for Iri class sidebar documentation.
    • Listed new constructors: new, file, fromUri, http, https, parse.
    • Listed properties: fragment, hashCode, host, path, pathSegments, port, query, queryParameters, runtimeType, scheme, userInfo.
    • Listed methods: noSuchMethod, replace, resolve, resolveIri, toString, toUri, toUriString.
    • Listed operators: operator ==.
    • Listed static methods: tryParse.
  • doc/api/iri/Iri-class.html
    • Added new file for Iri class documentation.
    • Provided detailed description of the Iri class as a Unicode-aware wrapper around Uri.
    • Documented all new constructors, properties, methods, and operators of the Iri class.
  • doc/api/iri/Iri/Iri.file.html
    • Added new file for Iri.file constructor documentation.
  • doc/api/iri/Iri/Iri.fromUri.html
    • Added new file for Iri.fromUri constructor documentation.
  • doc/api/iri/Iri/Iri.html
    • Added new file for Iri.new constructor documentation.
  • doc/api/iri/Iri/Iri.http.html
    • Added new file for Iri.http constructor documentation.
  • doc/api/iri/Iri/Iri.https.html
    • Added new file for Iri.https constructor documentation.
  • doc/api/iri/Iri/Iri.parse.html
    • Added new file for Iri.parse factory constructor documentation.
  • doc/api/iri/Iri/fragment.html
    • Added new file for Iri.fragment property documentation.
  • doc/api/iri/Iri/hashCode.html
    • Added new file for Iri.hashCode property documentation.
  • doc/api/iri/Iri/host.html
    • Added new file for Iri.host property documentation.
  • doc/api/iri/Iri/operator_equals.html
    • Added new file for Iri.operator == method documentation.
  • doc/api/iri/Iri/path.html
    • Added new file for Iri.path property documentation.
  • doc/api/iri/Iri/pathSegments.html
    • Added new file for Iri.pathSegments property documentation.
  • doc/api/iri/Iri/port.html
    • Added new file for Iri.port property documentation.
  • doc/api/iri/Iri/query.html
    • Added new file for Iri.query property documentation.
  • doc/api/iri/Iri/queryParameters.html
    • Added new file for Iri.queryParameters property documentation.
  • doc/api/iri/Iri/replace.html
    • Added new file for Iri.replace method documentation.
  • doc/api/iri/Iri/resolve.html
    • Added new file for Iri.resolve method documentation.
  • doc/api/iri/Iri/resolveIri.html
    • Added new file for Iri.resolveIri method documentation.
  • doc/api/iri/Iri/scheme.html
    • Added new file for Iri.scheme property documentation.
  • doc/api/iri/Iri/toString.html
    • Added new file for Iri.toString method documentation.
  • doc/api/iri/Iri/toUri.html
    • Added new file for Iri.toUri method documentation.
  • doc/api/iri/Iri/toUriString.html
    • Added new file for Iri.toUriString method documentation.
  • doc/api/iri/Iri/tryParse.html
    • Added new file for Iri.tryParse static method documentation.
  • doc/api/iri/Iri/userInfo.html
    • Added new file for Iri.userInfo property documentation.
  • doc/api/iri/index.html
    • Updated theme toggle button HTML structure and accessibility attributes.
    • Revised markdown content to reflect the new Iri class, features, and RFC compliance details.
    • Updated usage examples to use Iri.parse() and component-based constructors.
    • Changed class reference from IRI to Iri in the Libraries section.
    • Modified library link from iri to iri/.
  • doc/api/iri/iri-library-sidebar.html
    • Updated class link from IRI-class.html to Iri-class.html.
  • doc/api/iri/iri-library.html
    • Updated canonical and refresh URLs to ../iri/.
  • doc/api/search.html
    • Updated theme toggle button HTML structure and accessibility attributes.
    • Modified library link from iri to iri/.
    • Updated package version from 0.1.1 to 0.2.0 in the footer.
  • doc/api/static-assets/styles.css
    • Updated CSS variables for light and dark themes, including new color scheme properties.
    • Refactored theme button styling for better accessibility and appearance.
    • Adjusted scroll-padding-top for sticky headers.
    • Updated styles for markdown alerts, search input, and sidebar components.
  • example/iri_example.dart
    • Added // ignore_for_file: avoid_print to allow print statements for demo purposes.
    • Replaced IRI class instantiation with Iri.parse().
    • Replaced stdout.writeln with print for output.
  • lib/iri.dart
    • Added /// @docImport 'src/iri_base.dart'; for documentation purposes.
    • Updated RFC 3987 reference to include the full URL.
    • Changed class name references from IRI to Iri in documentation comments.
    • Updated library export from src/internationalized_resource_identifier.dart to src/iri_base.dart.
  • lib/src/internationalized_resource_identifier.dart
    • Removed the entire file as part of the package rewrite.
  • lib/src/iri_base.dart
    • Added new file containing the rewritten Iri class implementation.
    • Implemented Iri as an immutable wrapper around Uri.
    • Included constructors: Iri(), Iri.http(), Iri.https(), Iri.file(), Iri.fromUri(), and an internal Iri._().
    • Provided factory Iri.parse() and static Iri.tryParse() methods.
    • Implemented Unicode-aware getters for scheme, host, path, query, fragment, userInfo, port, queryParameters, pathSegments.
    • Added methods for resolve(), resolveIri(), replace(), toUri(), toString(), and toUriString().
    • Overrode operator == and hashCode for proper equality checks.
  • pubspec.yaml
    • Updated package version from 0.1.1 to 0.2.0.
    • Removed collection dependency.
    • Updated punycoder dependency from ^0.2.0 to ^0.3.0.
    • Added unorm_dart dependency with version ^0.3.2.
    • Updated lints dev dependency from ^5.0.0 to ^6.1.0.
    • Removed oath dev dependency.
  • test/iri_test.dart
    • Rewrote test suite to align with the new Iri class API.
    • Grouped tests by Iri Core and Punycode mapping, Iri mailto: special handling, Iri constructors, Iri component accessors, Iri equality, Normalization and Unicode Representation, Iri Resolution, Iri.replace, and RFC Specicifc complaince.
    • Added comprehensive tests for Punycode conversion, Unicode handling, NFKC normalization, constructor functionality, component access, equality, and IRI resolution.
    • Included specific tests for RFC 3987 sections on mapping IRIs to URIs, converting URIs to IRIs, normalization and comparison, character limitations, and relative IRI references.
Activity
  • The iri package underwent a complete rewrite, transitioning from a custom parsing implementation to a wrapper around Dart's native Uri class.
  • The package version was bumped to 0.2.0, indicating a major release with breaking changes due to the rewrite.
  • API documentation was regenerated and updated to reflect the new Iri class, its constructors, methods, and properties.
  • Development dependencies were updated, including a new lints package and the addition of unorm_dart for Unicode normalization.
  • The test suite was entirely rewritten to validate the new Iri class functionality and ensure compliance with RFC 3987 specifications.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a complete rewrite of the package, transitioning from a custom parser to a more maintainable implementation that wraps Dart's native Uri class. This is a significant architectural improvement. The update also includes stricter linting rules, comprehensive documentation, and an expanded test suite. My review identified one critical issue in the new Iri class implementation regarding the toUriString() method, which I've detailed in a specific comment.

Signed-off-by: mark <mark@dropbear.dev>
@mark-dropbear
Copy link
Contributor Author

/gemini review

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This is an impressive and substantial rewrite of the package. The new implementation, which wraps the native Uri class, is a significant improvement in terms of simplicity, maintainability, and readability over the previous custom parser. The API is now more familiar to Dart developers, and the addition of comprehensive tests and clear documentation (including limitations) is commendable. I've identified a minor bug in the normalization of query parameters when they contain iterable values, and I've provided suggestions for a fix.

Ensures that  values within  are correctly
normalized using NFKC. Previously, only  values were normalized,
leading to potential issues with international characters in multi-valued
query parameters.

This change applies to  constructors (, , )
and the  method.

A new test case has been added to verify this behavior.

Signed-off-by: mark <mark@dropbear.dev>
@mark-dropbear
Copy link
Contributor Author

/gemini review

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request is a complete rewrite of the package, moving from a custom IRI parser to a wrapper around Dart's native Uri class. This is a significant improvement in terms of simplicity, robustness, and maintainability. The new API is clean and mirrors the Uri API, making it familiar to Dart developers. The use of unorm_dart for Unicode normalization is a great choice.

I've added a couple of suggestions for minor improvements, mainly around code duplication and a potential performance optimization by caching the result of toUri(). Overall, this is an excellent refactoring.

Extracts duplicated query parameter normalization logic into a private static method `_normalizeQueryParameters` to improve code maintainability and readability.

Adds a new `queryParametersAll` getter to the `Iri` class, providing a way to access all query parameters, including those with multiple values per key.

Enhances the test suite with comprehensive test cases for various `queryParameters` scenarios, including `Iterable<String>` values and international characters, across different constructors (`Iri`, `Iri.http`, `Iri.https`) and the `replace` method. These tests now utilize the new `queryParametersAll` getter for robust verification.

Signed-off-by: mark <mark@dropbear.dev>
Optimizes the `toUri()` method by introducing a `late final _convertedUri` field to cache its result. This prevents redundant computations, especially when `toUri()` is called multiple times by `hashCode`, `operator==`, or `toUriString()` for the same immutable `Iri` instance.

The original logic of `toUri()` has been moved to a new private method, `_computeUri()`, which is called only once upon first access to the cached field. This improves performance, particularly when `Iri` objects are used in collections.

Signed-off-by: mark <mark@dropbear.dev>
Signed-off-by: mark <mark@dropbear.dev>
@mark-dropbear
Copy link
Contributor Author

/gemini review

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request is a complete rewrite of the iri package, moving from a custom parser to a wrapper around Dart's native Uri class. This is a significant improvement in terms of simplicity, maintainability, and leveraging the battle-tested Uri implementation. The new API is clean and mirrors the Uri API, which is great for usability. The addition of stricter linting rules and comprehensive tests, including skipped tests for known limitations, is commendable. I've found a few minor issues in documentation comments and a more significant issue with how query parameters are handled, which I've detailed in my review comments. Overall, this is an excellent update.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: mark-dropbear <76698672+mark-dropbear@users.noreply.github.com>
@mark-dropbear mark-dropbear merged commit 32556d8 into main Feb 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant