From 49b353106922176b772236be5636731c54cea778 Mon Sep 17 00:00:00 2001 From: desjoerd Date: Tue, 7 Jan 2025 22:23:13 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20"Why"=20in=20the=20readme?= =?UTF-8?q?=20and=20update=20package=20tags?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 51 ++++++++++++++---------- src/OptionalValues/OptionalValues.csproj | 11 +++-- 2 files changed, 38 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 3030213..7a486b0 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ A .NET library that provides an `OptionalValue` type, representing a value th | Package | Version | | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | [OptionalValues](https://www.nuget.org/packages/OptionalValues) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.svg)](https://www.nuget.org/packages/OptionalValues) | -| [OptionalValues.FluentValidation](https://www.nuget.org/packages/OptionalValues.FluentValidation) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.FluentValidation.svg)](https://www.nuget.org/packages/OptionalValues.FluentValidation) | | [OptionalValues.Swashbuckle](https://www.nuget.org/packages/OptionalValues.Swashbuckle) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.Swashbuckle.svg)](https://www.nuget.org/packages/OptionalValues.Swashbuckle) | +| [OptionalValues.FluentValidation](https://www.nuget.org/packages/OptionalValues.FluentValidation) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.FluentValidation.svg)](https://www.nuget.org/packages/OptionalValues.FluentValidation) | ## Overview @@ -21,35 +21,45 @@ The `OptionalValue` struct is designed to represent a value that can be in on - **Specified with a non-null value**: The value has been specified and is `not null`. - **Specified with a `null` value**: The value has been specified and is `null`. -This differs from `Nullable`, which can only distinguish between the presence or absence of a value, and cannot differentiate between an unspecified value and a specified `null` value. +### Why +When working with Json it's currently difficult to know whether a property was omitted or explicitly `null`. This makes it hard to support older clients that don't send all properties in a request. By using `OptionalValue` you can distinguish between `null` and `Unspecified` values. ```csharp -public class Person -{ - public OptionalValue FirstName { get; set; } - public OptionalValue LastName { get; set; } - public OptionalValue Address { get; set; } -} +using System.Text.Json; +using OptionalValues; -var person = new Person +var jsonSerializerOptions = new JsonSerializerOptions() + .AddOptionalValueSupport(); + +var json = + """ + { + "FirstName": "John", + "LastName": null + } + """; + +var person1 = JsonSerializer.Deserialize(json, jsonSerializerOptions); + +// equals: +var person2 = new Person { FirstName = "John", LastName = null, + Address = OptionalValue.Unspecified // or default }; -person.FirstName.IsSpecified; // True -person.FirstName.SpecifiedValue; // "John" - -person.LastName.IsSpecified; // True -person.LastName.SpecifiedValue; // null +bool areEqual = person1 == person2; // True -person.Address.IsSpecified; // False -person.Address.SpecifiedValue; // Throws InvalidOperationException - -var jsonSerializerOptions = new JsonSerializerOptions() - .AddOptionalValueSupport(); -string json = JsonSerializer.Serialize(person, jsonSerializerOptions); +string serialized = JsonSerializer.Serialize(person2, jsonSerializerOptions); // Output: {"FirstName":"John","LastName":null} + +public record Person +{ + public OptionalValue FirstName { get; set; } + public OptionalValue LastName { get; set; } + public OptionalValue Address { get; set; } +} ``` ## Installation @@ -86,6 +96,7 @@ dotnet add package OptionalValues.Swashbuckle - [OptionalValues](#optionalvalues) - [Overview](#overview) + - [Why](#why) - [Installation](#installation) - [Features](#features) - [Table of Contents](#table-of-contents) diff --git a/src/OptionalValues/OptionalValues.csproj b/src/OptionalValues/OptionalValues.csproj index 05a40d1..74a2607 100644 --- a/src/OptionalValues/OptionalValues.csproj +++ b/src/OptionalValues/OptionalValues.csproj @@ -16,16 +16,19 @@ OptionalValues en-US - Optional values for C# to model omitted values (undefined in javascript) and it has a JsonConvertor to support omitted values in Json. + Optional values for C# to model omitted values (undefined in javascript) and it has + a JsonConvertor to support omitted values in Json. README.md icon.png - optional partial undefined jsonpatch jsonmergepatch + optional partial json undefined jsonpatch jsonmergepatch patch System.Text.Json Api + unspecified - + - +