Skip to main content

Unflat by pstlnce

NuGet / site data​

Nuget GitHub last commit GitHub Repo stars

Details​

Info​

info

Name: Unflat

AOT ORM Сode generator for fast parsing DataReader into complex classes/structs with zero allocations

Author: pstlnce

NuGet: https://www.nuget.org/packages/Unflat/

You can find more details at https://github.com/pstlnce/unflat

Source: https://github.com/pstlnce/unflat

Author​

note

pstlnce Alt text

Original Readme​

note

Unflat

Unflat

Unflat is an AOT ORM Сode generator for fast parsing DataReader into complex classes/structs with zero allocations

How To Use​

Generating Parser​

Unflat generates parsers for classes or structs that have the UnflatMarkerAttribute applied to them. Target types can contain any number of nested complex fields or properties, with no depth limit. Circular references are resolved using default values.

[UnflatMarker(Case = MatchCase.IgnoreCase)]
public sealed class TestClass
{
   ...
}

Custom Converters​

Unflat supports custom converters by applying the UnflatParserAttribute to a method that should be called during parsing. Unflat searches for converters by matching the property types with the return types of marked methods, and selects the method that is closest in namespace to the target type. For example, if there are two converters—one in Namespace1 and the other in Namespace1.Namespace2:

  • If the target type is in Namespace1.Namespace2.Namespace3, the second converter will be chosen.
  • If the target is in Namespace1.Namespace4, the first converter will be chosen.
  • If the target is in Namespace5, the one marked with IsDefault = true will be selected.

There are several options to control how converters are called and matched:

  • CallFormat: Specifies how the converter should be invoked. It is used as the format string for string.Format(...), where 0 is replaced with reader.GetValue(<column_index>) and 1 with <column_index>.
  • IsDefault: Indicates that this converter is the default and should be used when no closer match is found by namespace.
  • NamespaceScope: Tells Unflat to treat the converter as if it resides in the specified namespace, regardless of its actual location.
[UnflatParser(CallFormat = "Example.ExampleClass.Parse({0}, {1}, reader)", IsDefault = false, NamespaceScope = "Example2")]
public static int Parse(object v, int index, IDataReader reader)
{
    return Convert.ToInt32(v);
}

Per Property/Field converter​

For different parsing behavior on specific properties or fields, use the SettableParserAttribute. It takes a single argument—the format string for string.Format(...), where 0 is replaced with reader.GetValue(<column_index>) and 1 with <column_index>.

[SettableParser("Convert.ToString({0})")]
public string Description \{ get; set; }

SplitOn, Column Prefix​

Unflat does not currently support split_on like Dapper.

Instead, you can use the UnflatPrefixAttribute to differentiate properties or fields of complex types that share the same names as properties or fields of primitive types.

If all names are unique (or if a field source is explicitly specified to resolve naming conflicts), no additional configuration is needed—nested complex types will be automatically assigned to their corresponding properties, unlike in Dapper.

public sealed class Example
{
    [UnflatPrefix("nested_class_")]
    public required NestedClassExample NestedClass \{ get; set; }

    [UnflatPrefix("nested_class_2_")]
    public required NestedClassExample NestedClass \{ get; set; }
}

Per Property/Field Field Source​

Unflat allows you to specify a field source using the UnflatSourceAttribute. It can be a concrete column name, a column ordinal, or multiple column names.

[UnflatSource("column_1")]
public required strign Field1 \{ get; set; }

[UnflatSource(1)]
public required strign Field2 \{ get; set; }

[UnflatSource(["column_1", "column_2", "column_3"])]
public required strign Field3 \{ get; set; }

Planned Features / Limitations​

  • Parameterless constructor requirement: Unflat currently only works if the target type has a parameterless constructor. I plan to add support for constructor argument matching (similar to Dapper) and the ability to call methods where parameters correspond to fields in the reader.
  • Method argument support: The ability to pass arguments to parsing methods, including injecting custom code into generated parsing logic.
  • Code templating: Support for templated code generation—such as automatically generating method extensions—to reduce boilerplate. For example, generating helper methods that use Dapper to fetch data and parse it with Unflat.
  • Alternative error handling: Currently, errors result in exceptions. Future support may include returning a Result<TTarget> type (if the user chooses), which could provide detailed error information—such as missing columns for required fields, invalid casts, etc.
  • Generic converters: Support for generic converter types (e.g., Converter<T>), which are not currently supported.
  • Multi-column converters: Converters that require values from multiple columns. (I haven’t yet determined how to design the API for this without conflicting with class or struct field declarations.)
  • "Split On" support: Potential future support for a split_on-like feature, if there is a clear need.
  • Tuple parsing: Currently, Unflat cannot parse tuples. This limitation may be addressed in a future update.

Perfomane​

Raw test against Dapper​

Parsing an in-memory DataTable using a DataTableReader into a model with 18 properties.

[UnflatMarker]
public class TestClass
{
    public string String1 \{ get; set; }
    public string String2 \{ get; set; }
    public string String3 \{ get; set; }
    public string Int \{ get; set; }
    public string Int2 \{ get; set; }
    public int IntNullable \{ get; set; }

    public string String1_1 \{ get; set; }
    public string String2_1 \{ get; set; }
    public string String3_1 \{ get; set; }
    public string Int_1 \{ get; set; }
    public string Int2_1 \{ get; set; }
    public int IntNullable_1 \{ get; set; }

    public string String1_2 \{ get; set; }
    public string String2_2 \{ get; set; }
    public string String3_2 \{ get; set; }
    public string Int_2 \{ get; set; }
    public string Int2_2 \{ get; set; }
    public int IntNullable_2 \{ get; set; }
}
BenchmarkDotNet v0.14.0, Windows 11 (10.0.26100.4652)
11th Gen Intel Core i5-1135G7 2.40GHz, 1 CPU, 8 logical and 4 physical cores
.NET SDK 10.0.100-preview.5.25277.114
  [Host]     : .NET 9.0.0 (9.0.24.52809), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
  DefaultJob : .NET 9.0.0 (9.0.24.52809), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
MethodcountMeanErrorStdDevMedianGen0Gen1Gen2Allocated
Unflat10022.68 us0.259 us0.242 us22.61 us7.2021--29.49 KB
Dapper10027.61 us0.549 us0.933 us27.44 us7.9956--32.69 KB
Unflat1000260.84 us5.161 us5.069 us258.15 us68.847718.5547-282.63 KB
Dapper1000297.94 us4.265 us4.380 us296.87 us76.17198.7891-313.95 KB
Unflat100005,680.10 us113.556 us308.937 us5,555.69 us546.8750343.750093.75002913.38 KB
Dapper100007,420.81 us146.523 us271.590 us7,444.71 us609.3750375.0000109.37503226 KB
Unflat5000033,989.82 us352.901 us330.104 us33,963.35 us2600.00001600.0000466.666714306.6 KB
Dapper5000041,203.97 us815.625 us1,551.811 us41,597.04 us2833.33331666.6667416.666715869.31 KB

What's the purpose?​

Unflat allows you to debug the parsing process and see exactly which converters or parsers are used—at compile time. In contrast, debugging the parsing logic in Dapper is difficult and often requires tools like WinDbg. With Dapper, you must manually verify whether a type parser is registered, and since only one parser can be registered per type, you may end up writing general-purpose converters that perform unnecessary checks, hurting performance.

Additionally, Unflat does not allocate any memory beyond what is required to create the target object—which is unavoidable, as object creation is the core purpose of any ORM.

What About Other Libraries?​

I couldn't find any source generators that address the most frustrating aspects of Dapper — specifically, the inability to debug the parsing process and the need to manually register type parsers.

Some similar libraries only support flat types, while others lack support for custom type parsers altogether.

About​

note

DataReader to Object Model

How to use​

Example (source csproj, source files)​

This is the CSharp Project that references Unflat

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Unflat" Version="0.0.1" OutputItemType="Analyzer" ReferenceOutputAssembly="false"  />
  </ItemGroup>


  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
	<PropertyGroup>
		<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
		<CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GX</CompilerGeneratedFilesOutputPath>
	</PropertyGroup>

</Project>

Generated Files​

Those are taken from $(BaseIntermediateOutputPath)\GX

using System;

namespace Unflat
{
    [AttributeUsage(AttributeTargets.Class)]
    internal sealed class UnflatMarkerAttribute : Attribute
    {
        public string? ClassName \{ get; set; }
        public MatchCase Case \{ get; set; \} = MatchCase.All;
    }

    [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = false)]
    internal sealed class SettableParserAttribute : Attribute
    {
        /// <summary>
        /// <list type="bullet">
        /// <item> {0} - reader[i] </item>
        /// <item> {1} - i </item>
        /// <item> i - related column index </item>
        /// <item> reader - reader... </item>
        /// </list>
        /// </summary>
        /// <param name="callFormat"> an argument for string.Format(callFormat, "reader[i]", i) </param>
        public SettableParserAttribute(string callFormat) {}
    }

    [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = false)]
    internal sealed class UnflatPrefixAttribute : Attribute
    {
        public UnflatPrefixAttribute(string prefix) \{ }
    }

    [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
    internal sealed class UnflatSourceAttribute : Attribute
    {
        public UnflatSourceAttribute(params string[] fields) {}
        public UnflatSourceAttribute(int fieldOrder) {}
    }

    [Flags]
    public enum MatchCase : int
    {
        None                 = 0,
        IgnoreCase           = 1,
        MatchOriginal        = 1 << 1,
        SnakeCase            = 1 << 2,
        CamalCase            = 1 << 3,
        PascalCase           = 1 << 4,
        ApplyOnOverritenName = 1 << 5,
        All = IgnoreCase | MatchOriginal | SnakeCase | CamalCase | PascalCase | ApplyOnOverritenName
    }

    [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
    internal sealed class UnflatParserAttribute : Attribute
    {
        /// <summary>
        /// <list type="bullet">
        /// <item> {0} - reader[i] </item>
        /// <item> {1} - i </item>
        /// <item> i - related column index </item>
        /// <item> reader - reader... </item>
        /// </list>
        /// </summary>
        /// <param name="callFormat"> an argument for string.Format(callFormat, "reader[i]", i) </param>
        public string CallFormat \{ get; set; }

        /// <summary>
        /// If true than this would be a fallback way
        /// for parsing reader's column value to returning type
        /// if not found parsers in closest namespaces
        /// </summary>
        public bool IsDefault \{ get; set; }

        /// <summary>
        /// If set this value will replace the namespace that contains this parser.
        /// Parser searcher will look to closest parser available to the model.
        /// Parser in Test namespace, the target in Test.Test1 => matched.
        /// Parser in Test.Test1.Test2, the target in Test.Test1 => not matched.
        /// Parser in Test.Test1, the target in Test.Test2 => not matched, etc...
        /// </summary>
        public string NamespaceScope \{ get; set; }
    }

    [Serializable]
    internal sealed class NotEnoughFieldsForRequiredException : Exception
    {
        public NotEnoughFieldsForRequiredException(int expected, int actual)
            : base($"Required field/properties count: {expected}, actual reader's fields count: {actual}")
        {
            Expected = expected;
            Actual = actual;
        }
        
        public int Expected \{ get; init; }
        public int Actual \{ get; init; }
    }

    [Serializable]
    public class MissingRequiredFieldOrPropertyException : System.Exception
    {
        public MissingRequiredFieldOrPropertyException(string[] propertiesOrFields)
            : base("There is no matched data for required properties or fields")
        {
            PropertiesOrFields = propertiesOrFields;
        }

        public string[] PropertiesOrFields \{ get; init; }
    }
}

Useful​

Download Example (.NET C#)​

tip

Download Example project Unflat

Share Unflat​

https://ignatandrei.github.io/RSCG_Examples/v2/docs/Unflat

Category "Database" has the following generators:​

1 Breezy

2 Dapper.AOT

3 EntityLengths.Generator

4 Finch.Generators

5 Gedaq

6 TableStorage

7 Unflat

See category​

Database