11 Releases 11 Tags

RSS Feed

• v4 147a72b476

  Version 4 Stable

  danieljsummers released this 2024-12-18 04:01:51 +00:00 | 2 commits to main since this release

  Version 4 is an evolution of this library to support better types (including treating numbers as numbers), generate IDs for documents, and support both queries on multiple fields and order of results without having to resort to custom SQL. This did bring some breaking changes, but there is also a Compat namespace that can be used to soften some of those to deprecation warnings, allowing you to upgrade without breaking the build. The migration guide details these changes, and the documentation there has been updated for version 4, including configuring automatic IDs and ordering query results.

  Library Changes

  • The library can now generate IDs for documents. It can generate a "max-plus-1" for numeric IDs, GUID strings, or random hexadecimal strings of a configurable length.
  • BREAKING CHANGE: All *byField/*ByField functions are now *byFields/*ByFields, and take a FieldMatch case before the list of fields. The Compat namespace in both libraries will assist in this transition. In support of this change, the Field parameter name is optional; the library will generate parameter names for it if they are not specified.

  v3 example:

  var result = Find.ByField("customer", Field.EQ("name", "john"));
  

  v4 equivalent:

  var result = Find.ByFields("customer", FieldMatch.Any, [Field.Equal("name", "john")]);
  

  • BREAKING CHANGE: PostgreSQL document fields will now be cast to numeric if the parameter value passed to the query is numeric. This drove the Query breaking changes, as the fields need to have their intended value for the library to generate the appropriate SQL. Additionally, if code assumes the library can be given something like 8 and transform it to "8", this is no longer the case.
  • All Find queries (except byId/ById) now have a version with the Ordered suffix. These take a list of fields by which the query should be ordered. A new Field method called Named can assist with creating these fields.
    • Prefixing the field name with n: will cast the field to numeric in PostgreSQL (and will be ignored by SQLite).
    • Prefixing fields by i: (lowercase "I" for "insensitive") in a list of ordering fields will force the sorting to be done in a case-insensitive manner. By default, PostgreSQL may sort this way already (but does not on Macintosh hosts), but SQLite will sort capital letters ahead of lowercase letters.
    • Adding " DESC" to the field name will sort it descending (Z-A, high to low) instead of ascending (A-Z, low to high). Additionally, other ordering directives, such as NULLS LAST, can appear after the field name (ex. Field.Named("i:last_name DESC NULLS FIRST") will do a case-insensitive sort descending, with nulls ahead of any present values).
  • In the F# v3 library, lists of parameters were expected to be F#'s List type, and the C# version took either List<T> or IEnumerable<T>. In this version, these all expect seq/IEnumerable<T>. F#'s List satisfies the seq constraints, so this should not be a breaking change.
  • In and InArray comparisons for Fields allow for retrieving documents where certain items match a given set of values.
  • Field constructor functions are now spelled out (ex. EQ is now Equal). The shorter versions exist as aliases, but these aliases are planned for deprecation in version 4.1.

  Query Building Features

  For those who like to go deeper and make their own queries, some of these internal APIs changed significantly.

  • BREAKING CHANGE: The Op type was replaced with the Comparison type; this was an internal API, but the type was public. Comparison is based on an F# discriminated union, which improves the type safety of field comparisons, but can be verbose to work with from C#.
  • BREAKING CHANGE: The Query namespaces have had some significant work, particularly from the full-query perspective. Most have been broken up into the base query and modifiers by* that will combine the base query with the WHERE clause needed to satisfy the criteria.
  • BREAKING CHANGE (PostgreSQL only): fieldNameParam/Parameters.FieldName are now plural. The function still only generates one parameter, but the name is now the same between PostgreSQL and SQLite. The goal of this library is to abstract the differences away as much as practical, and this furthers that end. There are functions with these names in the Compat namespace.
  • Fields now may have qualifiers; this allows tables to be aliased when joining multiple tables (as all have the same data column). F# users can use with to specify this at creation, and both F# and C# can use the WithQualifier method to create a field with the qualifier specified. Parameter names for fields may be specified in a similar way, substituting ParameterName for Qualifier.

  Downloads

  • Source Code (ZIP)
  • Source Code (TAR.GZ)
  • 4.0.0-tests.txt
    3.6 KiB