Skip to content

Releases

1.0.0

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 18 Nov 07:51

First stable release of Hlibz.Paging: paging and sorting for list endpoints. The DTO says what clients may sort by, a client's sort string is checked against it, and one call sorts, counts and loads the page. Targets .NET 10 and 11.

Same code as 1.0.0-preview.6. No changes since that preview. The preview releases describe how the API got here.

Packages

Full changelog: v1.0.0-preview.6...v1.0.0

1.0.0-preview.6

1.0.0-preview.6 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 14 Nov 16:27

Sixth preview: built with runtime async on .NET 11.

Changes

  • Runtime async on .NET 11. The net11.0 build compiles its async methods with runtime async (runtime-async=on), the way the .NET 11 libraries themselves are compiled: no compiler state machine, cheaper suspension inside ASP.NET Core's own async chains, and clearer async stack traces. The net10.0 build is unchanged. It covers PaginateAsync.

No API changes.

Packages

Full changelog: v1.0.0-preview.5...v1.0.0-preview.6

1.0.0-preview.5

1.0.0-preview.5 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 14 Nov 08:05

Fifth preview: sortable DTOs are checked at build time and listed by a source generator, in-memory paging is faster, and the packages are AOT-compatible.

Breaking changes

  • A DTO without exactly one [Sortable(IsDefault = true)] property fails the build with HPAG001. Before, the check ran only at startup.
  • SortableDto.ValidateAll(assemblies) reads a generated list of each assembly's sortable DTOs instead of scanning its types. It throws for an assembly that references Hlibz.Paging but wasn't compiled with the generator. The generator ships in the Hlibz.Paging package and reaches projects that get Hlibz.Paging indirectly, so this happens only if something removes it.
  • Sorting a database query carries AOT warnings. OrderBy on an IQueryable and PaginateAsync are marked [RequiresDynamicCode]/[RequiresUnreferencedCode], as LINQ provider queries are. So is ValidateAll(IEnumerable<Type>).

Features

  • A new source generator and analyzer (Hlibz.Paging.Generators) ships inside Hlibz.Paging.
  • IsAotCompatible is on for Hlibz.Paging and Hlibz.Paging.EntityFrameworkCore. In-memory Paginate, SortableDto.For<TDto>() and sort parsing are trimming-safe.

Performance

  • In-memory Paginate sorts with plain delegates instead of going through AsQueryable(), which compiled the sort expression on every call. The order is unchanged.
  • Each type's properties are read once and looked up by name, instead of on every sort.
  • SortableDto builds the list of allowed sort keys only when it needs it for an error message, and SortingParams.Params no longer creates a new list each time it is read.

Packages

Full changelog: v1.0.0-preview.4...v1.0.0-preview.5

1.0.0-preview.4

1.0.0-preview.4 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 13 Nov 19:46

Fourth preview: stable pages and a null-safe in-memory sort.

Changes

  • Id breaks ties. OrderBy(SortingParams) now sorts by Id after the requested keys when the type has an Id property and no key already names it. Sorting only by a non-unique key (a name, a status) left the order of equal rows to the database, so consecutive pages could repeat some rows and skip others. Rows with equal keys now come back in Id order. Sorting with no keys still sorts by Id alone.

Fixes

  • In-memory paging handles null strings. Paginate over an in-memory query threw NullReferenceException when a string sort key was null. Nulls now sort first (ascending). Database queries are unchanged: they still sort by UPPER(column).

Packages

Full changelog: v1.0.0-preview.3...v1.0.0-preview.4

1.0.0-preview.3

1.0.0-preview.3 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 13 Nov 18:54

Third preview: a documentation fix found while adopting 1.0.0-preview.2.

Fixes

  • The XML <summary> of PagedData<T> and PagingMetadata no longer ends with a note about their properties being required. Summaries become OpenAPI descriptions (with Hlibz.OpenApi's AddXmlDocumentation(), say), so that developer note showed on every list endpoint's published docs. It's in <remarks> now.

No API changes.

Packages

Full changelog: v1.0.0-preview.2...v1.0.0-preview.3

1.0.0-preview.2

1.0.0-preview.2 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 13 Nov 17:15

Second preview, with fixes from adopting 1.0.0-preview.1 in a real API.

Changes

  • SortableDto.ValidateAll(assemblies) skips abstract types, so a base class can mark properties [Sortable] for the DTOs that inherit them without failing startup.
  • New SortableDto.ValidateAll(IEnumerable<Type>) checks just the DTOs you pass: SortableDto.ValidateAll([typeof(OrderDto), typeof(CustomerDto)]). Use it when some types have [Sortable] properties but are never sorted, such as a DTO that only inherits them.
  • Every PagedData<T> and PagingMetadata property is required, so an OpenAPI document (Microsoft.AspNetCore.OpenApi 10 and 11, checked) lists them all as required, with no schema transformer of your own. Both types also read back from JSON now.
    • The existing constructors still work, and are the way to build a page: they work out TotalPages and HasNextPage.
    • The new parameterless constructors are for serializers and object initializers.
    • TotalPages and HasNextPage are now set by the constructor, no longer computed when read.

Packages

Full changelog: v1.0.0-preview.1...v1.0.0-preview.2

1.0.0-preview.1

1.0.0-preview.1 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 13 Nov 15:06

First preview of Hlibz.Paging: paging and sorting for list endpoints. The DTO says what clients may sort by, a client's sort string is checked against it, and one call sorts, counts and loads the page. Targets .NET 10 and 11.

Features

  • Hlibz.Paging (no dependencies):
    • [Sortable] marks which DTO properties clients may sort by, and the default order.
    • SortableDto.For<TDto>().TryParse(sort, namingPolicy, ...) parses key[:asc|desc],..., with keys in any casing, accepting only sortable properties. Its error names what can be sorted by, in your API's casing.
    • SortableDto.ValidateAll(assemblies) fails startup on a DTO without exactly one default.
    • PagingParams: page from 1 (default 1), page size (default 100), and PagingParams.All. Out-of-range values fall back to the defaults.
    • PagedData<T> and PagingMetadata: TotalItems, CurrentPage, PerPage, TotalPages, HasNextPage.
    • OrderBy(SortingParams) on any IQueryable (strings case-insensitive), and Paginate for lists in memory.
  • Hlibz.Paging.EntityFrameworkCore: PaginateAsync sorts in the database, runs a COUNT, then loads the page. An empty result skips the second query, and PagingParams.All loads everything in one query. Works with EF Core 10.0.15 and later on .NET 10, and 11.0.0 and later on .NET 11.

The Orders.Api sample is a plain minimal API on EF Core with SQLite in memory, with a .http file for each request.

Packages