docs: improve documentation (#1)

.github/workflows/ci.yml

@@ -51,6 +51,7 @@ jobs:
 
       - name: Report results
         uses: bibipkins/[email protected]
+        continue-on-error: true
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           comment-title: "Unit Test Results"

.gitignore

@@ -876,4 +876,7 @@ Temporary Items
 
 # End of https://www.toptal.com/developers/gitignore/api/dotnetcore,rider,intellij,jetbrains,macos,visualstudiocode,visualstudio,csharp
 
-.vscode
+.vscode
+**/.vitepress/cache
+.vitepress/cache
+dist

README.md

@@ -5,6 +5,8 @@ An alternative [libSQL](https://github.com/tursodatabase/libsql) .NET client, su
 > [!WARNING]
 > This is not an official libSQL client
 
+[![Continuous Integration](https://github.com/hermogenes/libsql-http-client-dotnet/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/hermogenes/libsql-http-client-dotnet/actions/workflows/ci.yml) [![NuGet](https://img.shields.io/nuget/dt/LibSql.Http.Client.svg)](https://www.nuget.org/stats/packages/LibSql.Http.Client?groupby=Version) [![NuGet](https://img.shields.io/nuget/vpre/LibSql.Http.Client.svg)](https://www.nuget.org/packages/LibSql.Http.Client/)
+
 ## About
 
 This client is a .NET implementation of HRANA protocol, intented to communicate with libSQL server.
@@ -15,6 +17,14 @@ This lib is inspired by [libsql-stateless-easy](https://github.com/DaBigBlob/lib
 
 - .NET 8 (6 and 7 are supported as well)
 
+## Installation
+
+Install [Nuget](https://www.nuget.org/packages/LibSql.Http.Client/) package:
+
+```sh
+dotnet add package LibSql.Http.Client
+```
+
 ## Usage
 
 The instance of the client expect an instance of HttpClient.

docs/.vitepress/config.mts

@@ -0,0 +1,73 @@
+import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  cleanUrls: true,
+  title: "LibSql.Http.Client",
+  description: "A .NET HTTP client for libSQL",
+  head: [["link", { rel: "icon", href: "/favicon.ico" }]],
+  themeConfig: {
+    logo: "/logo.png",
+    nav: [
+      { text: "Home", link: "/" },
+      { text: "Guide", link: "/guide/getting-started" },
+    ],
+
+    sidebar: [
+      {
+        text: "Introduction",
+        collapsed: false,
+        items: [
+          { text: "Why?", link: "/guide/why" },
+          { text: "Getting started", link: "/guide/getting-started" },
+          {
+            text: "Guidelines",
+            link: "/guide/guidelines",
+          },
+          {
+            text: "JSON Serializer Context",
+            link: "/guide/concepts/json-serializer-context",
+          },
+          {
+            text: "Transactions",
+            link: "/guide/concepts/transactions",
+          },
+          {
+            text: "Demo Console App",
+            link: "/guide/demo-console-app",
+          },
+        ],
+      },
+      {
+        text: "Querying",
+        collapsed: false,
+        link: "/guide/query",
+        items: [
+          {
+            text: "Executing statements",
+            link: "/guide/query/execute",
+          },
+          { text: "Using args", link: "/guide/query/args" },
+          { text: "Scalar Values", link: "/guide/query/scalar-values" },
+          { text: "Single Row", link: "/guide/query/single-row" },
+          { text: "Multiple Rows", link: "/guide/query/multiple-rows" },
+          { text: "Multiple Results", link: "/guide/query/multiple-results" },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      {
+        icon: "github",
+        link: "https://github.com/hermogenes/libsql-http-client-dotnet",
+      },
+      {
+        icon: {
+          svg: `<img class="nuget-logo" src="/nuget.svg" alt="Nuget logo icon" />`,
+        },
+        ariaLabel: "NuGet link",
+        link: "https://www.nuget.org/packages/LibSql.Http.Client",
+      },
+    ],
+  },
+});

docs/.vitepress/theme/custom.css

@@ -0,0 +1,48 @@
+:root {
+  --vp-c-brand-1: #0f4f62;
+  --vp-c-brand-2: #4ff8d2;
+  --vp-c-brand-3: #4ff8d2;
+  --vp-button-brand-text: #121b22;
+  --vp-button-alt-border: #4ff8d2;
+  --nuget-logo-filter: brightness(0);
+  --nuget-logo-opacity: 0.65;
+  --nuget-logo-hover-opacity: 1;
+}
+
+.dark {
+  --vp-c-brand-1: #4ff8d2;
+  --vp-c-brand-2: #0f4f62;
+  --vp-c-bg: #121b22;
+  --nuget-logo-filter: brightness(0) invert(1);
+  --nuget-logo-opacity: 0.5;
+  --nuget-logo-hover-opacity: 0.8;
+}
+
+.nuget-logo {
+  width: 20px;
+  filter: var(--nuget-logo-filter);
+  opacity: var(--nuget-logo-opacity);
+}
+
+a:hover .nuget-logo {
+  opacity: var(--nuget-logo-hover-opacity);
+}
+
+.VPSidebarItem.level-0.debug .items,
+.VPSidebarItem.level-1 .items,
+.VPSidebarItem.level-2 .items,
+.VPSidebarItem.level-3 .items,
+.VPSidebarItem.level-4 .items,
+.VPSidebarItem.level-5 .items {
+  border-left: 1px solid var(--vp-c-divider);
+  padding-left: 16px;
+}
+
+.VPSidebarItem.level-0.is-active.debug > .item > .indicator,
+.VPSidebarItem.level-1.is-active.debug > .item > .indicator,
+.VPSidebarItem.level-2.is-active > .item > .indicator,
+.VPSidebarItem.level-3.is-active > .item > .indicator,
+.VPSidebarItem.level-4.is-active > .item > .indicator,
+.VPSidebarItem.level-5.is-active > .item > .indicator {
+  background-color: var(--vp-c-brand-1);
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme";
+import "./custom.css";
+
+export default DefaultTheme;

docs/guide/concepts/json-serializer-context.md

@@ -0,0 +1,9 @@
+# JSON Serializer Context
+
+One of the goals of this library is to be fully trimmable and Native AOT compatible. This means that we don't use reflection or emit code at runtime. This is a big challenge when working with JSON serialization, because most libraries use reflection to discover the properties of a type.
+
+In order to achieve this goal, all the methods which require JSON deserialization requires a JsonTypeInfo object as parameter.
+
+This object can be easily generated using System.Text.Json source generation.
+
+If you are not familiar with this concept, you can read more about it in the [official documentation](https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/source-generation?pivots=dotnet-8-0).

docs/guide/concepts/transactions.md

@@ -0,0 +1,3 @@
+# Transactions
+
+TODO

docs/guide/demo-console-app.md

@@ -0,0 +1,3 @@
+# Demo Console App
+
+TODO

docs/guide/getting-started.md

@@ -0,0 +1,43 @@
+# Getting started
+
+## Installation
+
+### Prerequisites
+
+- .NET 6.0 or higher
+
+### Install the package
+
+```sh
+dotnet add package LibSql.Http.Client
+```
+
+## Create a client
+
+```csharp
+var handler = new SocketsHttpHandler
+{
+    PooledConnectionLifetime = TimeSpan.FromMinutes(15) // Recreate every 15 minutes
+};
+
+var sharedClient = new HttpClient(handler)
+{
+    BaseAddress = new Uri("https://db.host.com/"),
+    DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_AUTH_TOKEN" )}
+};
+
+var libSqlClient = new LibSqlHttpClient(sharedClient);
+```
+
+## Executing statements
+
+```csharp
+libSqlClient.ExecuteAsync(("INSERT INTO table (column) VALUES (?)", ["Hello, World!"]));
+```
+
+## What's next?
+
+- Check the [guidelines](./guidelines.md) for the client instantiation
+- Learn how to [execute statements](./query/index.md)
+- Configure your project to query results and [type serialization](./concepts/json-serializer-context.md)
+- Learn about [transactions](./concepts/transactions.md) using the lib

docs/guide/guidelines.md

@@ -0,0 +1,9 @@
+# Client Guidelines and best practices
+
+This library uses the HttpClient and follows the same recommended usage patterns.
+You can check the [official HTTP client guidelines](https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/http/httpclient-guidelines) for more information.
+
+## Lifetime management
+
+The HttpClient class is intended to be instantiated once and reused throughout the life of an application.
+Same applies to the LibSqlHttpClient class, which is a wrapper around the HttpClient.

docs/guide/query/args.md

@@ -0,0 +1,3 @@
+# Using args
+
+TODO

docs/guide/query/execute.md

@@ -0,0 +1,3 @@
+# Executing statements
+
+TODO

docs/guide/query/index.md

@@ -0,0 +1,3 @@
+# Querying the database
+
+TODO

docs/guide/query/multiple-results.md

@@ -0,0 +1,3 @@
+# Multiple Results
+
+TODO

docs/guide/query/multiple-rows.md

@@ -0,0 +1,3 @@
+# Multiple Rows
+
+TODO

docs/guide/query/scalar-values.md

@@ -0,0 +1,3 @@
+# Scalar Values
+
+TODO

docs/guide/query/single-row.md

@@ -0,0 +1,3 @@
+# Single row
+
+TODO

docs/guide/why.md

@@ -0,0 +1 @@
+# Why does this library exist?

docs/index.md

@@ -0,0 +1,30 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "LibSql.Http.Client"
+  text: "A .NET HTTP client for libSQL"
+  # tagline: My great project tagline
+  actions:
+    - theme: brand
+      text: Get started
+      link: /guide/getting-started
+    - theme: alt
+      text: GitHub
+      link: https://github.com/hermogenes/libsql-http-client-dotnet
+    - theme: alt
+      text: NuGet
+      link: https://www.nuget.org/packages/LibSql.Http.Client
+
+features:
+  - title: NativeAOT compatible
+    details: Native AOT apps have faster startup time and smaller memory footprints. These apps can run on machines that don't have the .NET runtime installed.
+    icon: 🚀
+  - title: Minimum memory usage
+    details: The requests and response are handled using System.Text.Json low-level APIs, which are more efficient than standard JSON serialization and deserialization.
+    icon: 📉
+  - title: Nice developer experience
+    details: Clean and simple API, allowing you to execute SQL statements with ease.
+    icon: 😃
+---

src/LibSql.Http.Client/LibSqlHttpClient.cs

@@ -35,7 +35,7 @@ public sealed class LibSqlHttpClient : ILibSqlHttpClient
     ///             PooledConnectionLifetime = TimeSpan.FromMinutes(15) // Recreate every 15 minutes
     ///         };
     ///         var sharedClient = new HttpClient(handler);
-    ///         var libSqlClient = new LibSqlHttpClient(sharedClient, "https://db.host.com", "YOUR_AUTH_TOKEN");
+    ///         var libSqlClient = new LibSqlHttpClient(sharedClient, new Uri("https://db.host.com"), "YOUR_AUTH_TOKEN");
     ///     </code>
     ///     or
     ///     <code>