Create Dart Implementation by Fried-man · Pull Request #431 · cucumber/messages

Fried-man · 2026-05-22T02:21:01Z

🤔 What's changed?

Adds an initial Dart implementation for Cucumber Messages

⚡️ What's your motivation?

There is currently no officially maintained Dart implementation of Cucumber Messages. I'd like to use a Dart implementation to build out Gherkin dart support.

🏷️ What kind of change is this?

📖 Documentation (improvements without changing code)
⚡ New feature (non-breaking change which adds new behaviour)

♻️ Anything particular you want feedback on?

If the API surface needs updates to better conform with the other language implementations.

📋 Checklist:

I agree to respect and uphold the Cucumber Community Code of Conduct
I've changed the behaviour of the code
- I have added/updated tests to cover my changes.
My change requires a change to the documentation.
- I have updated the documentation accordingly.
Users should know about my change
- I have added an entry to the "Unreleased" section of the CHANGELOG, linking to this pull request.

This text was originally generated from a template, then edited by hand. You can modify the template here.

…mprove time conversion functions to truncate sub-microsecond precision. Add tests for error scenarios and precision handling.

…n JSON object structure and stream processing behavior.

mpkorstanje

Heya, thanks for the PR!

I've given this a quick look for big problems. I didn't spot any, but I'll have to give it a more detailed look later.

Some general remarks:

I assume you're aware of cucumber/gherkin#30 and cucumber/gherkin#29.
We currently don't publish the Gherkin parser. I assume that is something you'd like to see happen in the future. That can be arranged though but might take some work.
I see that you've chosen to set default values for all required fields. Perhaps copied from the JavaScript implementation. We are trying to get rid of those for JavaScript (#285). It would make sense not copy that mistake into Dart. Ideally the constructor would throw an exception when trying to create message with missing required fields.
The generated messages sit in the same folder as the support code. This makes reviewing code quite annoying. And this may cause issues in the future if introduce a message that clashes with the support code. Can we separate these?

A few more detailed remarks below.

mpkorstanje · 2026-05-22T07:51:21Z

+      // ignore_for_file: cast_nullable_to_non_nullable, public_member_api_docs
+      // ignore_for_file: sort_constructors_first
+      // ignore_for_file: unnecessary_null_in_if_null_operators
+    HEADER


For consistency, please move this to the template. That's where it is expected.

Moved to where this is expected

mpkorstanje · 2026-05-22T07:59:38Z

+    def class_name(ref)
+      base = File.basename(ref, '.schema.json')
+      return 'DurationMessage' if base == 'Duration'
+      return 'ExceptionMessage' if base == 'Exception'


If this is necessary, this could do with a comment to explain why these names are different. Though I assume Dart has some name spacing to prevent collisions in the first place, if so then using the message names would be preferable. People very familiar with messages, but not so familiar with Dart will occasionally have to make small changes to implementations that use Dart. This would likely trip them up.

It collides with some foundational dart classes. I refactored to use the normal names & refactored code that depends on it with explicit references to the file the class was from. Ex:

import 'package:cucumber_messages/src/messages.dart' as messages; /// Converts a Dart [Duration] to a Cucumber [messages.Duration]. /// /// The [duration] value is exported as whole seconds plus nanoseconds. messages.Duration durationToDurationMessage(Duration duration) { final micros = duration.inMicroseconds; final seconds = micros ~/ Duration.microsecondsPerSecond; final nanos = micros.remainder(Duration.microsecondsPerSecond) * 1000; return messages.Duration(seconds: seconds, nanos: nanos); }

mpkorstanje · 2026-05-22T08:05:52Z

+part of 'messages.dart';
+
+class DurationMessage {
+  final int seconds;


What is the range on integer values in dart?

From first-party docs:

The default implementation of int is 64-bit two's complement integers with operations that wrap to that range on overflow.

Note: When compiling to JavaScript, integers are restricted to values that can be represented exactly by double-precision floating point values. The available integer values include all integers between -2^53 and 2^53, and some integers with larger magnitude. That includes some integers larger than 2^63. The behavior of the operators and methods in the int class therefore sometimes differs between the Dart VM and Dart code compiled to JavaScript. For example, the bitwise operators truncate their operands to 32-bit integers when compiled to JavaScript.

So basically:

Platform Underlying Representation Minimum Value Maximum Value

Native 64-bit signed integer (-2^{63}) (2^{63} - 1)

Web 64-bit float (JS) (-2^{53} + 1) (precise) (2^{53} - 1) (precise)

mpkorstanje · 2026-05-22T08:17:17Z

+}
+
+/// Returns an [IdGenerator] that produces random RFC 4122 version 4 UUIDs.
+IdGenerator uuidV4IdGenerator() {


I don't think it is a good idea to implement and maintain our own UUIDv4 generator. I also don't think it is a good idea to add a dependency on library that does this.

Ideally the IdGenerator is an interface that users of this library implement. For example by delegating to an existing UUIDv4 generator implementation that they pull in as a dependency.

Agree, updated to only be an interface.

mpkorstanje · 2026-05-22T08:28:28Z

+Envelope parseEnvelopeJson(
+  String json, {
+  int? lineNumber,
+  bool includeLineInErrors = true,


Please default this to false. While not likely, it avoids accidental information disclosure type issues as well as logging of untrusted data.

Updated default to false

mpkorstanje · 2026-05-22T08:31:12Z

Please don't duplicate the CHANGELOG in the root of the project. This one will be overlooked if we make changes.

Makes sense, removed

Actually, re-added but had it point to the root changelog. pub.dev (official dart package distributor) has a scoring system for packages and having a changelog is one of the criteria. While it is not required, it can make the package not appear well-maintained & there is a GUI for the changelog on the site for potential adopters to reference.

If you would like, I can remove it again but felt like having it serve to only reference the root changelog was a fine solution to prevent the issue of having to maintain multiple versions.

Also, looks like they require I include the current version number in the changelog or else there will be an error when validating publishing. I included that validation for publishing dry run in the CI to ensure it stays publishable but can understand it be annoying to have to bump the changelog value whenever the package version changes.

mpkorstanje · 2026-05-22T08:47:37Z

+      matrix:
+        os:
+          - ubuntu-latest
+        dart: ["3.5.0", stable]


Please pin these to exact versions. This keeps CI stable.

Pinned to exact versions

mpkorstanje · 2026-05-22T08:52:23Z

+
+.generate-messages: $(schemas) ../codegen/codegen.rb ../codegen/templates/dart.dart.erb
+	ruby ../codegen/codegen.rb Generator::Dart dart.dart.erb > Generated.dart.tmp
+	ruby -e "input = File.readlines('Generated.dart.tmp', chomp: true); current = nil; lines = []; flush = lambda { next unless current; File.write(File.join('lib/src', current), lines.join(\"\\n\") + \"\\n\"); lines = [] }; input.each do |line| if line.end_with?('.g.dart') && !line.include?(' '); flush.call; current = line; else; lines << line; end; end; flush.call"


I assume this splits the generated file?

If so, please use the csplit solution used by other implementations.

messages/java/Makefile

Lines 21 to 25 in 521cb9d

csplit --quiet --prefix=Generated --suffix-format=%02d.java.tmp --elide-empty-files Generated.java.tmp /^[A-Za-z.]*[.]java/ {*}

rm Generated.java.tmp

rm -rf src/generated/java/io/cucumber/messages/types

mkdir --parents src/generated/java/io/cucumber/messages/types

for file in Generated**; do tail -n +2 $$file > src/generated/java/io/cucumber/messages/types/$$(head -n 1 $$file | tr -d '\r\n'); rm $$file; done

Updated to run using cpslit solution

and yeah it does split the generated files

mpkorstanje · 2026-05-22T09:05:37Z

+        with:
+          persist-credentials: false
+
+      - uses: dart-lang/setup-dart@c7a31f6a04bb9bf94f538fc551f7ef9e40223317 # v1.7.1


Where did you get these hashes from? Have you used an LLM?

I also don't see any actions ran in https://github.com/Fried-man/messages/actions. Please this yourself before submitting.

Yeah I used an LLM and it hallucinated. Updated to a real hash.

I tried to run it manually from the actions tab on my fork but didn't see an option to. Realized this morning that I could just open a PR on my fork and run the CI there. Here is a passing run from that.

Fried-man · 2026-05-22T12:12:41Z

+        with:
+          persist-credentials: false
+
+      - uses: dart-lang/setup-dart@c7a31f6a04bb9bf94f538fc551f7ef9e40223317 # v1.7.1


mpkorstanje · 2026-05-22T09:00:23Z

+
+require: ## Check requirements for generation and checks
+	@ruby --version >/dev/null 2>&1 || (echo "ERROR: ruby is required."; exit 1)
+	@dart --version >/dev/null 2>&1 || (echo "ERROR: dart is required."; exit 1)


Dart should not be required to generate the code. I suspect that will go away once the bench mark tests are removed.

Removed dart requirement. I was mainly using it to run dart format on the generated code. Not important to format generated code.

…es and updating code formatting for consistency. Adjust analysis options to exclude generated files and improve code generation process in Makefile.

…e error handling in NDJSON parsing.

…n generated files to prevent formatting issues.

…ency.

…tors and implementing schema validation with SchemaViolationException. Update CHANGELOG to document these changes.

Fried-man · 2026-05-22T11:57:52Z

Heya, thanks for the PR!

I've given this a quick look for big problems. I didn't spot any, but I'll have to give it a more detailed look later.

Some general remarks:

I assume you're aware of dart: Acceptance tests are not implemented gherkin#30 and dart: Parser is nog generated using Berp gherkin#29.

We currently don't publish the Gherkin parser. I assume that is something you'd like to see happen in the future. That can be arranged though but might take some work.

I see that you've chosen to set default values for all required fields. Perhaps copied from the JavaScript implementation. We are trying to get rid of those for JavaScript (Proposal to remove JavaScript classes and just generate interfaces #285). It would make sense not copy that mistake into Dart. Ideally the constructor would throw an exception when trying to create message with missing required fields.

The generated messages sit in the same folder as the support code. This makes reviewing code quite annoying. And this may cause issues in the future if introduce a message that clashes with the support code. Can we separate these?

Hey! Thanks for the review

I did see that. Planning on solving those.
I would like the gherkin parser to be published. Totally understand it may take some work & for the short-term I can have code that depends on it point to the repo itself rather than pub.dev
I was concerned that was going to be considered un-wanted behavior but thought it was fine since JS had it (Missed Proposal to remove JavaScript classes and just generate interfaces #285 ). I have updated it to require these values.
Sure, I moved the generated files (*.g.dart) to dart\lib\src\generated.

…ent for generated files

…rsion entry.

Fried-man · 2026-05-22T12:59:11Z

Alright, I think I'm done lol. Latest dart run passing on my fork can be found here.

mpkorstanje

Great! I don't have time for another review pass today.

But I was reading https://pubrelease.onepub.dev/creating-a-release and I see that the pub_release command is rather involved and makes a lot of assumptions about the work flow.

Because we're releasing 10+ different languages we don't exactly have a standard process.

But it looks like this:

Prepare the release by updating the version numbers and making other changes on a dev-machine.
Tag these changes in Git.
Push the changes and tags to GitHub.
GitHub will trigger on the tags and start the release process for each action independently.

Can you tell me if the pub_release command is the only way to "publish your project to pub.dev"? We might have some experimenting to do to that get that work.

Fried-man · 2026-05-22T22:43:11Z

Can you tell me if the pub_release command is the only way to "publish your project to pub.dev"? We might have some experimenting to do to that get that work.

I believe the official publish path is dart pub publish. I don't believe it automatically creates tags or bumps the version.

Fried-man added 17 commits May 21, 2026 20:14

Add initial implementation

4c3fe1f

Merge branch 'main' into feature/dart_implementation

aec0f0a

chore(dart): update Dart SDK version constraints and dependencies

f243847

Update to stricter linter & fix violations

98144b0

Organize test suite to follow dart conventions & improve coverage

2bdc994

Add changelog

1eefbe4

Add example

123b2c3

Setup for pubdev

2dbd2b4

Remove redundant property

09e5f21

Update Dart SDK version constraint to use caret syntax

1eea1f6

Enhance NDJSON parsing with error handling and line number context; i…

5bcd7ac

…mprove time conversion functions to truncate sub-microsecond precision. Add tests for error scenarios and precision handling.

Enhance NDJSON message stream functions with detailed documentation o…

2fd8be1

…n JSON object structure and stream processing behavior.

Add NDJSON benchmark and update documentation for performance testing

419ac8d

Ignore benchmark for publishing

b7089d6

Fix rounding error

3820104

Clean API surface

3bcd671

Update changelog

99a98ca

Fried-man changed the title ~~Feature/dart implementation~~ Create Dart Implementation May 22, 2026

mpkorstanje requested changes May 22, 2026

View reviewed changes

github-advanced-security AI found potential problems May 22, 2026

View reviewed changes

mpkorstanje reviewed May 22, 2026

View reviewed changes

Fried-man added 9 commits May 22, 2026 06:42

Migrate header to expected location

7085e93

Add comma

ae0d7e6

Fix trailing commas in template for linter

897d4e7

Remove changelog

faf2a39

Refactor generated Dart files by removing unnecessary ignore directiv…

d4ab291

…es and updating code formatting for consistency. Adjust analysis options to exclude generated files and improve code generation process in Makefile.

Remove benchmark from CI & makefile

cc2f24f

Fix makefile regression

b342afb

Update CHANGELOG and README to reflect new features and improvements.

0b40cda

Refactor tests to utilize the new ID generation methods and streamlin…

b5b8257

…e error handling in NDJSON parsing.

Fried-man added 6 commits May 22, 2026 07:27

Convert ID generator to only interface

f242af5

Update Dart SDK version to 3.7.0 and add 'dart format off' comments i…

ca5cc0e

…n generated files to prevent formatting issues.

Dart formatter

57e4d7f

Refactor Dart message classes to improve structure and naming consist…

3209b0a

…ency.

Enhance Dart message classes by enforcing required fields in construc…

12c9277

…tors and implementing schema validation with SchemaViolationException. Update CHANGELOG to document these changes.

Move generated files to dedicated directory

f42f0ee

Fried-man force-pushed the feature/dart_implementation branch from aedef0e to f42f0ee Compare May 22, 2026 12:09

Fried-man added 8 commits May 22, 2026 08:11

Fix hash & bump to working sdk version for linter

d91e5a1

Make changelog not manually maintanable

e280acd

Update Dart SDK version requirement to >=3.9.0 <4.0.0 in README.md

079be79

Add missing requirements

b64f706

Add documentation on name collisions with dart:core in README.md

1b73135

Decrease SDK version to minimum valuable version (null-safety support)

8c91fc2

Change dart sdk minimum to lowest reuired for dart formatter disablem…

e5030b1

…ent for generated files

Update CHANGELOG to clarify release notes location and add initial ve…

badfe14

…rsion entry.

mpkorstanje reviewed May 22, 2026

View reviewed changes

mpkorstanje self-requested a review May 27, 2026 17:47

Platform	Underlying Representation	Minimum Value	Maximum Value
Native	64-bit signed integer	(-2^{63})	(2^{63} - 1)
Web	64-bit float (JS)	(-2^{53} + 1) (precise)	(2^{53} - 1) (precise)

	csplit --quiet --prefix=Generated --suffix-format=%02d.java.tmp --elide-empty-files Generated.java.tmp /^[A-Za-z.][.]java/ {}
	rm Generated.java.tmp
	rm -rf src/generated/java/io/cucumber/messages/types
	mkdir --parents src/generated/java/io/cucumber/messages/types
	for file in Generated**; do tail -n +2 $$file > src/generated/java/io/cucumber/messages/types/$$(head -n 1 $$file \| tr -d '\r\n'); rm $$file; done

Uh oh!

Conversation

Fried-man commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤔 What's changed?

⚡️ What's your motivation?

🏷️ What kind of change is this?

♻️ Anything particular you want feedback on?

📋 Checklist:

Uh oh!

mpkorstanje left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fried-man May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fried-man May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fried-man May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mpkorstanje May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fried-man commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fried-man commented May 22, 2026

Uh oh!

mpkorstanje left a comment

Choose a reason for hiding this comment

Uh oh!

Fried-man commented May 22, 2026 •

edited

Loading

mpkorstanje left a comment •

edited

Loading

Fried-man May 22, 2026 •

edited

Loading

Fried-man May 22, 2026 •

edited

Loading

Fried-man May 22, 2026 •

edited

Loading

mpkorstanje May 22, 2026 •

edited

Loading

Fried-man commented May 22, 2026 •

edited

Loading

Fried-man commented May 22, 2026 •

edited

Loading