Skip to content

feat(dart): add external-type serialization - #3886

Merged
chaokunyang merged 8 commits into
apache:mainfrom
chaokunyang:agent/dart-external-type-serialization
Jul 27, 2026
Merged

feat(dart): add external-type serialization#3886
chaokunyang merged 8 commits into
apache:mainfrom
chaokunyang:agent/dart-external-type-serialization

Conversation

@chaokunyang

@chaokunyang chaokunyang commented Jul 26, 2026

Copy link
Copy Markdown
Collaborator

Why?

Dart classes owned by dependencies cannot carry Fory annotations. Applications
need generated serializers for those types without copying values into local
models or adding a second registration, carrier, root, or polymorphic path.

What does this PR do?

  • Adds ForyStruct.target and constructor selection so an abstract final
    local schema declaration generates a direct serializer for a closed external
    class.
  • Uses the existing generated struct model, target-keyed schema/module
    registration, field descriptors, carrier codecs, root APIs, reference
    resolver, compatible reads, and polymorphic registration.
  • Generates direct target getters, generative constructor calls, and setters;
    validates the external contract at generation time, including generic type
    rendering, re-exported nullable aliases, and constructor-cycle constraints.
  • Covers roots, fields, nested list/set/map fields, named and numeric
    registration, polymorphism, references, compatible mode, generic targets,
    Java-to-Dart xlang exchange, and JavaScript compilation.
  • Documents the current external-type serialization and manual serializer
    APIs without migration or removed-API material.

Related issues

N/A

AI Contribution Checklist

AI Usage Disclosure

Does this PR introduce any user-facing change?

  • Does this PR introduce any public API change?
  • Does this PR introduce any binary protocol compatibility change?

The public Dart annotation API adds optional target and constructor
arguments to ForyStruct. The wire format is unchanged.

Verification

  • cd dart/packages/fory && dart run build_runner build && dart analyze && dart test
    • generation: 98 outputs, no tracked changes
    • analysis: clean
    • tests: 232/232 passed
  • cd dart/packages/fory-test && dart run build_runner build && dart analyze && dart test
    • generation: 3 outputs, no tracked changes
    • analysis: clean
    • tests: 18/18 passed
  • cd dart && dart analyze && dart test
    • analysis: clean
    • tests: 1/1 passed
  • cd dart/packages/external-type-test-models && dart analyze
    • analysis: clean
  • dart compile js for
    dart/packages/fory-test/tool/external_type_js_smoke.dart, followed by Node
    execution
    • compiled successfully and exited successfully
  • FORY_DART_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 --no-transfer-progress test -Dtest=org.apache.fory.xlang.DartXlangTest
    • 101/101 passed with no failures, errors, or skips

Benchmark

Fresh apache/main ordinary benchmarks were run in adjacent baseline/current
pairs. Every retained median met the less-than-1% slowdown gate, and the
generated ordinary benchmark source was byte-identical.

Equivalent ordinary/external generated paths were measured in AOT mode with
split debugging data:

Path Retained delta
Root serialize +0.02%
Root deserialize +0.04%
Direct field serialize +0.53%
Direct field deserialize -0.82%
List field serialize +1.47%
List field deserialize -0.02%
Map field serialize +0.09%
Map field deserialize +0.90%

Negative values are slowdowns; every slowdown is below 1%. Serialized bytes
and normalized generated serializer bodies matched. The fixed-iteration VM
allocation check reported identical per-class object counts for all eight
serialize/deserialize lanes at 1,000 iterations.

@chaokunyang
chaokunyang marked this pull request as ready for review July 26, 2026 23:55
@chaokunyang
chaokunyang merged commit 1d4cf00 into apache:main Jul 27, 2026
63 checks 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.

2 participants