bit-badger/BitBadger.Documents
1
0
Fork 0
Code Issues Pull Requests Projects Releases 11 Activity

11 Releases 11 Tags

RSS Feed
  • v4.1 43fed5789a

    Version 4.1 Stable

    danieljsummers released this 2025-04-19 20:05:15 +00:00 | 0 commits to main since this release

    FEATURE - The new Json module/static class allows documents to be retrieved as JSON. The functions/methods are the same as the Find module/static class, and return a string. There are also functions that begin with Write (C#) / write (F#) which write the JSON to a PipeWriter as it arrives. For JSON API servers, this allows documents to be retrieved and streamed to the output without having to create domain objects or an in-memory string of all of them.

    DOCUMENTATION - The documentation for this site is now built with docfx ("Documentation Framework"), a project which can extract the API docs (delivered in 4.0.1) and create nice, browsable web pages. It also supports hand-written documentation, and creates a set of files which can be dropped anywhere and served as-is. For this project, these are now served at https://relationaldocs.bitbadger.solutions/dotnet/. The parent level of that website also now has a lot of information on the concepts behind document storage, impartial evaluations of their pros and cons, and more.

    POSSIBLE BREAKING CHANGE - Custom.Single used to run whatever query it was given and return the first result. However, this meant that large queries could be retrieved, deserialized, collected into a list - and then be immediately discarded. This function now adds LIMIT 1 to the end of the query before it is executed, returning only the rows necessary to satisfy the request. This was a mostly-internal API, though if you have queries where you have specifically added this clause, you can remove it.

    Downloads
  • v4.0.1 5580284910

    Version 4.0.1 Stable

    danieljsummers released this 2024-12-30 22:05:49 +00:00 | 1 commits to main since this release

    In this release, full XML documentation is generated and packaged along with the code. IDEs should provide more help with classes, functions, and parameters than they have in previous releases.

    (NOTE: v4 contained some breaking changes; see its release notes for more information.)

    Downloads
  • 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
  • v4-rc5 740767661c

    Version 4 (RC 5) Pre-Release

    danieljsummers released this 2024-09-18 13:39:05 +00:00 | 3 commits to main since this release

    This is an API bug-fix for rc4, which allows any IEnumerable<T> (C#) / seq<'T> (F#) to be provided to Field.In and Field.InArray transparently. That was the intent of these functions, but their rc4 definitions required existing sequences to have each item cast to object/obj; this should no longer be required.

    Downloads
  • v4-rc4 168bf0cd14

    Version 4 (RC 4) Pre-Release

    danieljsummers released this 2024-09-17 02:41:38 +00:00 | 4 commits to main since this release

    Changes from rc3 include:

    • In and InArray comparisons for Fields allow for retrieving documents where certain items match a given set of values
    • 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#.
    • Field constructor functions are now spelled out (ex. EQ is now Equal). The shorter versions exist as aliases.

    Version 4 is thought to be feature-complete with this release. Barring any unexpected bugs, a non-RC release should be forthcoming by the end of October 2024.

    Downloads
  • v4-rc3 3bc662c984

    Version 4 (RC 3) Pre-Release

    danieljsummers released this 2024-09-17 02:31:12 +00:00 | 5 commits to main since this release

    This is a bug-fix for rc2 which preserves extra qualifiers after ASC or DESC in an ordered field definition. This allows for specifying case insensitive searches, NULLS FIRST or NULLS LAST, etc.

    This was released August 22nd, but was not tagged at the time

    Downloads
  • v4-rc2 b019548a4e

    Version 4 (RC 2) Pre-Release

    danieljsummers released this 2024-08-23 00:24:26 +00:00 | 6 commits to main since this release

    This release has one change from rc1:

    • 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.

    If upgrading from v3, be sure to check out the rc1 list for the changes in this release.

    Downloads
  • v4-rc1 2c24e2e912

    Version 4 (RC 1) Pre-Release

    danieljsummers released this 2024-08-19 23:39:14 +00:00 | 8 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 is a work-in-progress at the time of this release, but will be fully fleshed out before v4 is released for good. The remainder of the documentation at that site has been updated for version 4, including configuring automatic IDs and ordering query results.

    From the v4 pull request, a slightly-organized list of features and breaking changes:

    • 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.
    • 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.
    • FEATURE / 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.
    • FEATURE: 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); adding " DESC" to the field name will sort it descending (Z-A, high to low) instead of ascending (A-Z, low to high).
    • FEATURE: 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 (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.
    • FEATURE: 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.
    • FEATURE: 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
  • v3.1 a0da5f83b1

    Version 3.1 Stable

    danieljsummers released this 2024-06-06 01:58:08 +00:00 | 10 commits to main since this release

    This release brings a new BT operator and corresponding Field.BT function/method to create those criteria. This change mandated that whereByField be moved out of the common library, as PostgreSQL needs different syntax to use BETWEEN against numeric values once the item is plucked from the JSON document. This mandated that whereById be moved as well, which then cascaded to most of the Query module queries. If your program uses these functions, and it cannot find them, open or using the implementation-specific module. (#4)

    This release also drops support for .NET 7, which went end-of-life on May 14, 2024. (#3)

    Finally, all dependencies for these libraries were brought current.

    Downloads
  • v3 fc045d021c

    Version 3 Stable

    danieljsummers released this 2024-04-21 03:05:06 +00:00 | 14 commits to main since this release

    This is the official release of version 3 - no more RCs! The API has been stable, and these libraries have been implemented in several projects successfully.

    NOTE: This replaces BitBadger.Npgsql.Documents and BitBadger.Npgsql.FSharp.Documents. The namespace for PostgreSQL is BitBadger.Documents.Postgres, and both C# and F# syntax is contained in that namespace. A migration guide is available at the prior project site.

    Downloads