Masterly.NonEmptyList 3.0.1

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Masterly.NonEmptyList --version 3.0.1
                    


                    

                
NuGet\Install-Package Masterly.NonEmptyList -Version 3.0.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Masterly.NonEmptyList" Version="3.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Masterly.NonEmptyList" Version="3.0.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Masterly.NonEmptyList" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Masterly.NonEmptyList --version 3.0.1
                    


                    

                
#r "nuget: Masterly.NonEmptyList, 3.0.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Masterly.NonEmptyList@3.0.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Masterly.NonEmptyList&version=3.0.1
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Masterly.NonEmptyList&version=3.0.1
                    


                            Install as a Cake Tool

Masterly.NonEmptyList

Proof-carrying collections for .NET. NonEmptyList<T> is a list the type system guarantees has at least one element, so Head, Last, Max, Average and Reduce can never fail for lack of data.

Give a Star on Github! ⭐

If you like or are using this project please give it a star. Thanks!

Highlights

  • Unbreakable guarantee: the list wraps its storage, so no interface cast can empty it.
  • Collection expressions and list patterns: NonEmptyList<int> xs = [1, 2, 3];, xs is [var head, .. var rest], xs[1..].
  • Type-preserving LINQ: Select, OrderBy/ThenBy, GroupBy, Distinct, Union, Concat, Chunk, Max, Min keep the non-empty type. Query syntax supported.
  • Generic math: Sum, Product, Average, Median, Mode, MinMax with no empty-sequence exception path, for built-in and user-defined numeric types.
  • Constraint algebra: ConstrainedList<T, AtLeast<Two>>, Distinct, Sorted, AtMost, Exactly, And, Or. Second() and Third() compile only when the type proves them.
  • Sibling types: NonEmptySet<T>, NonEmptyDictionary<TKey, TValue>, NonEmptyString, NonEmptySpan<T>, ImmutableNonEmptyList<T>, lazy NonEmptyEnumerable<T>.
  • Modeling types: NonEmptyZipper<T>, History<T>, EventStream<TEvent>, NonEmptyTree<T>.
  • Validation<T, TError>: error-accumulating validation whose error list is non-empty by construction.
  • Async batching: BatchNonEmpty(size, maxWait), ReadAllBatchesAsync for channels, ToNonEmptyAsync with the head in memory and the rest streaming.
  • Query-string binding: ISpanParsable<T> plus a TypeConverter, so ASP.NET Core binds NonEmptyList<T>, NonEmptySet<T> and NonEmptyString directly and rejects empty input with a 400.
  • Bundled analyzer and source generator: NEL001 to NEL005 with code fixes, a v3 migration fix, and [NonEmptyCollection] for domain collections.
  • Integration packages: EF Core, ASP.NET Core (OpenAPI, problem details), Configuration, Newtonsoft.Json, MessagePack, Dapper, Testing (CsCheck, AutoFixture, laws).

Installation

dotnet add package Masterly.NonEmptyList

Usage

using Masterly.NonEmptyList;

NonEmptyList<int> numbers = [3, 1, 2];

int first = numbers.Head;              // never throws
int max = numbers.Max();               // int, not int?
double average = numbers.Average();    // never divides by zero

NonEmptyList<string> sorted =
    from n in numbers
    orderby n
    select n.ToString();               // still a NonEmptyList

ConstrainedList<Waypoint, AtLeast<Two>> route = ConstrainedList<Waypoint, AtLeast<Two>>.From(points);
Waypoint second = route.Second();      // safe only because AtLeast<Two> is in the type

Validation<User, ValidationError> user = Validation.Combine(
    ValidateName(input.Name),
    ValidateEmail(input.Email),
    (name, email) => new User(name, email));   // all errors reported together

app.MapGet("/products", (NonEmptyList<int> ids) => repo.GetByIds(ids));   // ?ids=1,2,3

[NonEmptyCollection(typeof(OrderLine), Distinct = true, MaxCount = 500)]
public sealed partial class OrderLines;                                      // generated domain collection

Migrating from 2.x

NonEmptyList<T> no longer derives from List<T> (a bundled code fix offers .ToList() for CS1503, CS0029, CS0266 and CS1662; explicit casts need a manual change); Prepend returns a new list (use AddFirst to mutate); Remove returns bool; .NET 6 is no longer targeted. EF Core users should call .UseNonEmptyList() on their options.

License

MIT

Free Software, Hell Yeah!

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

  • net10.0

    • No dependencies.

  • net8.0

    • No dependencies.

  • net9.0

    • No dependencies.

NuGet packages (7)

Showing the top 5 NuGet packages that depend on Masterly.NonEmptyList:

Package Downloads
Masterly.NonEmptyList.EntityFrameworkCore

Entity Framework Core integration for Masterly.NonEmptyList. Provides value converters, comparers, relationship configuration, and query extensions to seamlessly store and retrieve NonEmptyList and ImmutableNonEmptyList collections in your database.
Masterly.NonEmptyList.AspNetCore

ASP.NET Core integration for Masterly.NonEmptyList: OpenAPI schema transformer that emits minItems/minLength/uniqueItems for every non-empty type, Validation-to-HTTP result helpers that turn accumulated errors into RFC 7807 validation problem details, and ModelState helpers for MVC.
Masterly.NonEmptyList.Configuration

Microsoft.Extensions.Configuration and Options integration for Masterly.NonEmptyList. Binds NonEmptyList, NonEmptySet, NonEmptyDictionary, ConstrainedList and NonEmptyString properties from configuration (arrays or comma-separated values) and fails at startup, naming the key, when a required collection is empty or missing.
Masterly.NonEmptyList.Dapper

Dapper type handlers for Masterly.NonEmptyList. Stores NonEmptyList, ImmutableNonEmptyList, NonEmptySet, ConstrainedList and NonEmptyDictionary columns as JSON text and NonEmptyString as text, rejecting empty values when reading.
Masterly.NonEmptyList.Testing

Test support for Masterly.NonEmptyList: CsCheck generators for every non-empty type, an AutoFixture customization, and the published law suite (functor, monad, fold and structural laws) so property-based tests can verify your own code and extensions.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.1 234 11/2/2026
3.0.0 220 11/2/2026
2.0.0 241 1/1/2026
1.2.2 157 1/1/2026
1.2.1 262 9/15/2024
1.2.0 218 9/15/2024
1.1.0 216 9/15/2024
1.0.0 220 9/13/2024

v3.0.1:
- New package icon: a pair of brackets around a single element

v3.0.0:
- BREAKING: NonEmptyList<T> no longer inherits List<T>. It wraps its storage, so the non-empty guarantee now holds through IList<T>, ICollection<T> and IList as well
- BREAKING: Prepend(item) now returns a new list (LINQ semantics); use AddFirst(item) to insert in place
- BREAKING: Remove(item) returns bool like List<T>; AsReadOnly returns ReadOnlyCollection<T>
- BREAKING: Dropped .NET 6 target; now targets .NET 8, 9 and 10
- Collection expressions: NonEmptyList<int> xs = [1, 2, 3]; (also ImmutableNonEmptyList, ConstrainedList, NonEmptySet)
- List patterns and range slicing: xs is [var head, .. var rest], xs[1..]
- Type-preserving LINQ: Select, SelectMany, OrderBy/ThenBy, GroupBy, Distinct, Union, Concat, Chunk, Min, Max stay non-empty; query syntax supported
- Generic math: Sum, Product, Average, Median, Mode, MinMax with no empty-sequence exception path
- ISpanParsable / TypeConverter: bind NonEmptyList<T> and NonEmptyString directly from query strings, route values and configuration
- Validation<T, TError>: error-accumulating validation whose error list is non-empty by construction
- Constraint algebra: ConstrainedList<T, AtLeast<Two>>, Distinct, Sorted, AtMost, Exactly, And, Or; Second()/Third() only when the type proves them
- New types: NonEmptySet, NonEmptyDictionary, NonEmptyString, NonEmptySpan, NonEmptyZipper, History, EventStream, NonEmptyTree, NonEmptyEnumerable (lazy, infinite)
- Async batching: BatchNonEmpty (size and time based), ReadAllBatchesAsync for channels, ToNonEmptyAsync / NonEmptyAsyncEnumerable
- Bundled Roslyn analyzers (NEL001-NEL005) with code fixes, and the [NonEmptyCollection] source generator for domain collections
- Protected invariant hooks (EnsureMutable, ValidateItem, ValidateRange, ValidateReplacement, ValidateCount) for derived types
- New factories: NonEmptyList.Of, Create, Range, Iterate, Unfold; FromSpan; params ReadOnlySpan constructors; IEnumerable constructors
- New operators: Scan, Tails, Inits, Append, Flatten, Unzip, Interleave, Cycle, ConvertAll
- [NotNullWhen(true)] on TryFrom; DebuggerDisplay and debugger type proxy; O(n) MinBy/MaxBy