WIP on READMEs and packaging

src/Common/BitBadger.Documents.Common.fsproj

@@ -1,7 +1,14 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
+  <PropertyGroup>
+    <PackageReleaseNotes>Initial release (RC 1)</PackageReleaseNotes>
+    <PackageTags>JSON Document SQL</PackageTags>
+  </PropertyGroup>
+
   <ItemGroup>
     <Compile Include="Library.fs" />
+    <None Include="README.md" Pack="true" PackagePath="\" />
+    <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
   <ItemGroup>

src/Common/README.md

@@ -0,0 +1,17 @@
+# BitBadger.Documents.Common
+
+This package provides common definitions and functionality for `BitBadger.Documents` implementations. These libraries provide a document storage view over relational databases, while also providing convenience functions for relational usage as well. This enables a hybrid approach to data storage, allowing the user to use documents where they make sense, while streamlining traditional ADO.NET functionality where relational data is required.
+- `BitBadger.Documents.Postgres` ([NuGet](https://www.nuget.org/packages/BitBadger.Documents.Postgres/)) provides a PostgreSQL implementation.
+- `BitBadger.Documents.Sqlite` ([NuGet](https://www.nuget.org/packages/BitBadger.Documents.Sqlite/)) provides a SQLite implementation
+
+## Features
+
+- Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
+- Addresses documents via ID and via comparison on any field (for PostgreSQL, also via equality on any property by using JSON containment, or via condition on any property using JSON Path queries)
+- Accesses documents as your domain models (<abbr title="Plain Old CLR Objects">POCO</abbr>s)
+- Uses `Task`-based async for all data access functions
+- Uses building blocks for more complex queries
+
+## Getting Started
+
+Install the library of your choice and follow its README; also, the [project site](https://bitbadger.solutions/open-source/relational-documents/) has complete documentation.

src/Directory.Build.props

@@ -7,17 +7,15 @@
     <FileVersion>3.0.0.0</FileVersion>
     <VersionPrefix>3.0.0</VersionPrefix>
     <VersionSuffix>rc-1</VersionSuffix>
-    <PackageReleaseNotes>Initial release with F# support</PackageReleaseNotes>
     <Authors>danieljsummers</Authors>
     <Company>Bit Badger Solutions</Company>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageIcon>icon.png</PackageIcon>
-    <PackageProjectUrl>https://bitbadger.solutions/open-source/sqlite-documents/</PackageProjectUrl>
+    <PackageProjectUrl>https://bitbadger.solutions/open-source/relational-documents/</PackageProjectUrl>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
-    <RepositoryUrl>https://github.com/bit-badger/BitBadger.Sqlite.Documents</RepositoryUrl>
+    <RepositoryUrl>https://github.com/bit-badger/BitBadger.Documents</RepositoryUrl>
     <RepositoryType>Git</RepositoryType>
     <Copyright>MIT License</Copyright>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
-    <PackageTags>SQLite JSON document</PackageTags>
   </PropertyGroup>
 </Project>

src/Postgres/BitBadger.Documents.Postgres.fsproj

@@ -1,8 +1,15 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
+  <PropertyGroup>
+    <PackageReleaseNotes>Initial release; migrated from BitBadger.Npgsql.Documents, with field and extension additions (RC 1)</PackageReleaseNotes>
+    <PackageTags>JSON Document PostgreSQL Npgsql</PackageTags>
+  </PropertyGroup>
+
   <ItemGroup>
     <Compile Include="Library.fs" />
     <Compile Include="Extensions.fs" />
+    <None Include="README.md" Pack="true" PackagePath="\" />
+    <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
   <ItemGroup>

src/Postgres/README.md

@@ -0,0 +1,101 @@
+# BitBadger.Documents.Postgres
+
+This package provides a lightweight document library backed by [PostgreSQL](https://www.postgresql.org). It also provides streamlined functions for traditional ADO.NET functionality where relational data is required. Both C# and F# have first-class implementations.
+
+## Features
+
+- Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
+- Address documents via ID, via comparison on any field, via equality on any property (using JSON containment, on a likely indexed field), or via condition on any property (using JSON Path queries)
+- Access documents as your domain models (<abbr title="Plain Old CLR Objects">POCO</abbr>s)
+- Use `Task`-based async for all data access functions
+- Use building blocks for more complex queries
+
+## Getting Started
+
+Once the package is installed, the library needs a data source. Construct an `NpgsqlDataSource` instance, and provide it to the library:
+
+```csharp
+// C#
+using BitBadger.Documents.Postgres;
+
+//...
+// Do not use "using" here; the library will handle disposing this instance
+var data = new NpgsqlDataSourceBuilder("connection-string").Build();
+Postgres.Configuration.UseDataSource(data);
+```
+
+```fsharp
+// F#
+open BitBadger.Documents.Postgres
+
+// ...
+// Do not use "use" here; the library will handle disposing this instance
+let dataSource = // same as above ....
+
+Configuration.useDataSource dataSource
+// ...
+```
+
+By default, the library uses a `System.Text.Json`-based serializer configured to use the `FSharp.SystemTextJson` converter. To provide a different serializer (different options, more converters, etc.), construct it to implement `IDocumentSerializer` and provide it via `Configuration.useSerializer`. If custom serialization makes the serialized Id field not be `Id`, that will also need to be configured.
+
+## Using
+
+Retrieve all customers:
+
+```csharp
+// C#; parameter is table name
+// Find.All type signature is Func<string, Task<List<TDoc>>>
+var customers = await Find.All("customer");
+```
+
+```fsharp
+// F#
+// Find.all type signature is string -> Task<'TDoc list>
+let! customers = Find.all<Customer> "customer"
+```
+
+Select a customer by ID:
+
+```csharp
+// C#; parameters are table name and ID
+// Find.ById type signature is Func<string, TKey, Task<TDoc?>>
+var customer = await Find.ById<string, Customer>("customer", "123");
+```
+```fsharp
+// F#
+// Find.byId type signature is string -> 'TKey -> Task<'TDoc option>
+let! customer = Find.byId<string, Customer> "customer" "123"
+```
+_(keys are treated as strings in the database)_
+
+Count customers in Atlanta (using JSON containment):
+
+```csharp
+// C#; parameters are table name and object for containment query
+// Count.ByContains type signature is Func<string, TCriteria, int>
+var customerCount = await Count.ByContains("customer", new { City = "Atlanta" });
+```
+
+```fsharp
+// F#
+// Count.byContains type signature is string -> 'TCriteria -> Task<int>
+let! customerCount = Count.byContains "customer" {| City = "Atlanta" |}
+```
+
+Delete customers in Chicago: _(no offense, Second City; just an example...)_
+
+```csharp
+// C#; parameters are table name and JSON Path expression
+// Delete.ByJsonPath type signature is Func<string, string, Task>
+await Delete.ByJsonPath("customer", "$.City ? (@ == \"Chicago\")");
+```
+
+```fsharp
+// F#
+// Delete.byJsonPath type signature is string -> string -> Task<unit>
+do! Delete.byJsonPath "customer" """$.City ? (@ == "Chicago")"""
+```
+
+## More Information
+
+The [project site](https://bitbadger.solutions/open-source/relational-documents/) has full details on how to use this library.

src/Sqlite/BitBadger.Documents.Sqlite.fsproj

@@ -1,12 +1,18 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
+  <PropertyGroup>
+    <PackageReleaseNotes>Initial release; SQLite document implementation similar to BitBadger.Npgsql.Documents (RC 1)</PackageReleaseNotes>
+    <PackageTags>JSON Document SQLite</PackageTags>
+  </PropertyGroup>
+
   <ItemGroup>
     <Compile Include="Library.fs" />
     <Compile Include="Extensions.fs" />
+    <None Include="README.md" Pack="true" PackagePath="\" />
+    <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="FSharp.SystemTextJson" Version="1.2.42" />
     <PackageReference Include="Microsoft.Data.Sqlite" Version="8.0.0" />
   </ItemGroup>
 

src/Sqlite/README.md

@@ -0,0 +1,101 @@
+# BitBadger.Documents.Sqlite
+
+This package provides a lightweight document library backed by [SQLite](https://www.sqlite.org). It also provides streamlined functions for traditional ADO.NET functionality where relational data is required. Both C# and F# have first-class implementations.
+
+## Features
+
+- Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
+- Address documents via ID or via comparison on any field
+- Access documents as your domain models (<abbr title="Plain Old CLR Objects">POCO</abbr>s)
+- Use `Task`-based async for all data access functions
+- Use building blocks for more complex queries
+
+## Getting Started
+
+Once the package is installed, the library needs a connection string. Once it has been obtained / constructed, provide it to the library:
+
+```csharp
+// C#
+using BitBadger.Documents.Sqlite;
+
+//...
+Sqlite.Configuration.UseConnectionString("connection-string");
+
+// A new, open connection to the database can be obtained via
+// Sqlite.Configuration.DbConn()
+```
+
+```fsharp
+// F#
+open BitBadger.Documents.Sqlite
+
+// ...
+Configuration.useConnectionString "connection-string"
+
+// A new, open connection to the database can be obtained via
+// Configuration.dbConn ()
+```
+
+By default, the library uses a `System.Text.Json`-based serializer configured to use the `FSharp.SystemTextJson` converter. To provide a different serializer (different options, more converters, etc.), construct it to implement `IDocumentSerializer` and provide it via `Configuration.useSerializer`. If custom serialization makes the serialized Id field not be `Id`, that will also need to be configured.
+
+## Using
+
+Retrieve all customers:
+
+```csharp
+// C#; parameter is table name
+// Find.All type signature is Func<string, Task<List<TDoc>>>
+var customers = await Find.All("customer");
+```
+
+```fsharp
+// F#
+// Find.all type signature is string -> Task<'TDoc list>
+let! customers = Find.all<Customer> "customer"
+```
+
+Select a customer by ID:
+
+```csharp
+// C#; parameters are table name and ID
+// Find.ById type signature is Func<string, TKey, Task<TDoc?>>
+var customer = await Find.ById<string, Customer>("customer", "123");
+```
+```fsharp
+// F#
+// Find.byId type signature is string -> 'TKey -> Task<'TDoc option>
+let! customer = Find.byId<string, Customer> "customer" "123"
+```
+_(keys are treated as strings in the database)_
+
+Count customers in Atlanta:
+
+```csharp
+// C#; parameters are table name, field, operator, and value
+// Count.ByField type signature is Func<string, string, Op, object, Task<long>>
+var customerCount = await Count.ByField("customer", "City", Op.EQ, "Atlanta");
+```
+
+```fsharp
+// F#
+// Count.byField type signature is string -> string -> Op -> obj -> Task<int64>
+let! customerCount = Count.byField "customer" "City" EQ "Atlanta"
+```
+
+Delete customers in Chicago: _(no offense, Second City; just an example...)_
+
+```csharp
+// C#; parameters are same as above, except return is void
+// Delete.ByField type signature is Func<string, string, Op, object, Task>
+await Delete.ByField("customer", "City", Op.EQ, "Chicago");
+```
+
+```fsharp
+// F#
+// Delete.byField type signature is string -> string -> Op -> obj -> Task<unit>
+do! Delete.byField "customer" "City" EQ "Chicago"
+```
+
+## More Information
+
+The [project site](https://bitbadger.solutions/open-source/relational-documents/) has full details on how to use this library.