Skip to content

Serializable Metadata#2

Merged
feO2x merged 15 commits intomainfrom
1-serializable-metadata
Jan 7, 2026
Merged

Serializable Metadata#2
feO2x merged 15 commits intomainfrom
1-serializable-metadata

Conversation

@feO2x
Copy link
Copy Markdown
Owner

@feO2x feO2x commented Jan 7, 2026

What was implemented in this PR:

  • MetadataValue uses Kind + MetadataPayload union, rejects NaN/Infinity, stores decimals as invariant strings, and provides typed getters plus implicit conversions.
  • MetadataObject/MetadataArray act as thin value types over sealed backing data with sorted entries and optional dictionary lookup once size > 8, matching the “view + lazy index” design.
  • MetadataObjectBuilder/MetadataArrayBuilder rent from ArrayPool, seal into owned arrays, invalidate after Build(), and support span-friendly APIs via overloads (the plan’s “public span-based builder” request was satisfied).
  • Result and Error now expose metadata, with WithMetadata/MergeMetadata helpers and merge semantics (objects merge recursively, arrays/scalars replace).
  • JSON/gRPC considerations are prepared (though actual converters/proto schema are future work), and tests/benchmarks were added broadly per plan.
  • Benchmarks for metadata
  • GitHub actions for building and testing

Deviations / still-open items:

  • Span overloads: builders expose Add taking string but not public ReadOnlySpan overloads yet; extending them would fully meet the DX ask.
  • Depth/size guardrails & Json converters: plan called for concrete guardrails and Utf8JsonReader/Writer converters, but those aren’t implemented yet (no converter classes).
  • Custom protobuf schema: implementation still uses Struct/Value; the plan documents pros/cons but no proto files were added (expected future decision).

@feO2x feO2x requested a review from Copilot January 7, 2026 13:47
@feO2x feO2x self-assigned this Jan 7, 2026
@feO2x feO2x linked an issue Jan 7, 2026 that may be closed by this pull request
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR implements a comprehensive serializable metadata system for the Light.Results library. The implementation adds strongly-typed, JSON-compatible metadata support to Result and Error types, with efficient value types, pooled builders, and recursive merge capabilities.

Key Changes:

  • Core metadata types (MetadataValue, MetadataObject, MetadataArray) using discriminated unions and value semantics
  • ArrayPool-based builders for efficient construction with automatic cleanup
  • Metadata integration into Result and Error with merge operations and strategies
  • Comprehensive test suite and performance benchmarks comparing against Dictionary<string, object?>

Reviewed changes

Copilot reviewed 67 out of 76 changed files in this pull request and generated 11 comments.

Show a summary per file
File Description
src/Light.Results/Metadata/MetadataValue.cs Discriminated union value type supporting null, bool, int64, double, string, array, and object with NaN/Infinity rejection
src/Light.Results/Metadata/MetadataPayload.cs Explicit-layout union struct for memory-efficient storage of primitives and references
src/Light.Results/Metadata/MetadataObject.cs Immutable dictionary-like struct with sorted keys and lazy indexing for objects >8 entries
src/Light.Results/Metadata/MetadataArray.cs Immutable array wrapper providing span access and efficient iteration
src/Light.Results/Metadata/MetadataObjectBuilder.cs Pooled builder with binary search insertion maintaining sorted order
src/Light.Results/Metadata/MetadataArrayBuilder.cs Pooled builder for array construction with span-based APIs
src/Light.Results/Metadata/MetadataObjectExtensions.cs Merge operations with recursive object merging and configurable strategies
src/Light.Results/Result.cs Adds metadata field, WithMetadata/MergeMetadata methods, metadata propagation in Map/Bind
src/Light.Results/Error.cs Replaces Meta dictionary with MetadataObject, adds WithMetadata helpers
src/Light.Results/Errors.cs Extracted from Result.cs to separate file
src/Light.Results/Unit.cs Void-like value type for non-generic Result
tests/* Comprehensive test coverage for all metadata types, builders, and integrations
benchmarks/* Performance benchmarks comparing against Dictionary with generated results
.github/workflows/build-and-test.yml CI/CD workflow for building, testing, and code coverage
global.json Specifies .NET SDK 10.0.101

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread tests/Light.Results.Tests/Metadata/MetadataArrayAdditionalTests.cs
Comment thread tests/Light.Results.Tests/Metadata/MetadataObjectAdditionalTests.cs
Comment thread tests/Light.Results.Tests/Metadata/MetadataArrayAdditionalTests.cs
Comment thread tests/Light.Results.Tests/Metadata/MetadataObjectAdditionalTests.cs
Comment thread src/Light.Results/Result.cs Outdated
Comment thread benchmarks/Benchmarks/MetadataArrayBenchmarks.cs Outdated
Comment thread benchmarks/Benchmarks/MetadataIterationBenchmarks.cs
Comment thread benchmarks/Benchmarks/MetadataIterationBenchmarks.cs
Comment thread benchmarks/Benchmarks/MetadataIterationBenchmarks.cs
Comment thread benchmarks/Benchmarks/MetadataIterationBenchmarks.cs
@feO2x feO2x merged commit ddba9d3 into main Jan 7, 2026
1 check passed
@feO2x feO2x deleted the 1-serializable-metadata branch January 7, 2026 14:08
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.

Serializable Metadata

2 participants