# Fauna v10 .NET/C# client driver (current)

| Version: 1.0.1 | Repository: fauna/fauna-dotnet |
| --- | --- | --- | --- |

Fauna’s .NET/C# client driver lets you run FQL queries from .NET and C# applications.

This guide shows how to set up the driver and use it to run FQL queries.

## [](#supported-net-and-c-versions)Supported .NET and C# versions

*   .NET 8.0
    
*   C# ^10.0
    

## [](#installation)Installation

The driver is available on [NuGet](https://www.nuget.org/packages/fauna). To install it using the .NET CLI, run:

```csharp
dotnet add package Fauna
```

## [](#api-reference)API reference

API reference documentation for the driver is available at [https://fauna.github.io/fauna-dotnet/](https://fauna.github.io/fauna-dotnet/).

## [](#sample-app)Sample app

For a practical example, check out the [.NET sample app](https://github.com/fauna/dotnet-sample-app).

This sample app is an e-commerce application that uses the Fauna .NET/C# driver. The source code includes comments highlighting best practices for using the driver and composing FQL queries.

## [](#basic-usage)Basic usage

The following applications:

*   Initialize a client instance to connect to Fauna
    
*   Compose a basic FQL query using an `FQL` string template
    
*   Run the query using `QueryAsync()` or `PaginateAsync()`
    
*   Deserialize the results based on a provided type parameter
    

Use `QueryAsync()` to run a non-paginated query:

```csharp
using Fauna;
using Fauna.Exceptions;
using static Fauna.Query;

try
{
    // Initialize the client to connect to Fauna
    var config = new Configuration("FAUNA_SECRET")
    var client = new Client(config);

    // Compose a query
    var query = FQL($@"
        Product.byName('cups').first() {{
            name,
            description,
            price
        }}
    ");

    // Run the query
    // Optionally specify the expected result type as a type parameter.
    // If not provided, the value will be deserialized as object.
    var response = await client.QueryAsync<Dictionary<string, object?>>(query);

    Console.WriteLine(response.Data["name"]);
    Console.WriteLine(response.Data["description"]);
    Console.WriteLine(response.Data["price"]);
    Console.WriteLine("--------");
}
catch (FaunaException e)
{
    Console.WriteLine(e);
}
```

Queries that return a [Set](../../../reference/fql/types/#set) are automatically paginated. Use `PaginateAsync()` to iterate through paginated results:

```csharp
using Fauna;
using Fauna.Exceptions;
using static Fauna.Query;

try
{
    // Initialize the client to connect to Fauna
    var client = new Client("FAUNA_SECRET");

    // Compose a query
    var query = FQL($@"
      Product.sortedByPriceLowToHigh() {{
        name,
        description,
        price
      }}
    ");

    // Run the query
    // PaginateAsync returns an IAsyncEnumerable of pages
    var response = client.PaginateAsync<Dictionary<string, object?>>(query);

    await foreach (var page in response)
    {
        foreach (var product in page.Data)
        {
            Console.WriteLine(product["name"]);
            Console.WriteLine(product["description"]);
            Console.WriteLine(product["price"]);
            Console.WriteLine("--------");
        }
    }
}
catch (FaunaException e)
{
    Console.WriteLine(e);
}
```

## [](#connect-to-fauna)Connect to Fauna

Each Fauna query is an independently authenticated request to the [Query HTTP API endpoint](../../../reference/http/reference/core-api/#operation/query). You authenticate with Fauna with an [authentication secret](../../../learn/security/authentication/#secrets).

### [](#get-an-authentication-secret)Get an authentication secret

Fauna supports several [secret types](../../../learn/security/authentication/#secret-types). For testing, you can create a [key](../../../learn/security/keys/), which is a type of secret:

1.  Log in to the [Fauna Dashboard](https://dashboard.fauna.com/).
    
2.  On the **Explorer** page, create a database.
    
3.  In the database’s **Keys** tab, click **Create Key**.
    
4.  Choose a **Role** of **server**.
    
5.  Click **Save**.
    
6.  Copy the **Key Secret**. The secret is scoped to the database.
    

### [](#initialize-a-client)Initialize a client

To send query requests to a Fauna database, initialize a `Client` instance using an authentication secret scoped to the database:

```csharp
var client = new Client("FAUNA_SECRET");
```

`Client` requires a `secret` or `configuration` argument. For configuration options, see [Client configuration](#config).

### [](#connect-to-a-child-database)Connect to a child database

A [scoped key](../../../learn/security/keys/#scoped-keys) lets you use a parent database’s admin key to send query requests to its child databases.

For example, if you have an admin key for a parent database and want to connect to a child database named `childDB`, you can create a scoped key using the following format:

```
// Scoped key that impersonates an `admin` key for
// the `childDB` child database.
fn...:childDB:admin
```

You can then initialize a `Client` instance using the scoped key:

```csharp
var client = new Client("fn...:childDB:admin");
```

### [](#multiple-connections)Multiple connections

You can use a single client instance to run multiple asynchronous queries at once. The driver manages HTTP connections as needed. Your app doesn’t need to implement connection pools or other connection management strategies.

You can create multiple client instances to connect to Fauna using different credentials or client configurations.

## [](#run-fql-queries)Run FQL queries

Use `FQL` string templates to compose FQL queries. Run the queries using `QueryAsync()` or `PaginateAsync()`:

```csharp
// Unpaginated query
var query = FQL($@"Product.byName('cups').first()");
client.QueryAsync(query);

// Paginated query
// Adjust `pageSize()` size as needed
var paginatedQuery = FQL($@"Category.all().pageSize(2)");
client.PaginateAsync(paginatedQuery);
```

You can only compose FQL queries using string templates.

### [](#var)Variable interpolation

Use single braces `{}` to pass native variables to fql queries. Use `{{}}` to escape other single braces in the query.

```csharp
// Create a native var
var collectionName = "Product";

// Pass the var to an FQL query
var query = FQL($@"
    let collection = Collection({collectionName})
    collection.byName('cups').first() {{ price }}"
);

client.QueryAsync(query);
```

The driver encodes interpolated variables to an appropriate [FQL type](../../../reference/fql/types/) and uses the [wire protocol](../../../reference/http/reference/wire-protocol/) to pass the query to the Core HTTP API’s [Query endpoint](../../../reference/http/reference/core-api/#operation/query). This helps prevent injection attacks.

### [](#query-composition)Query composition

You can use variable interpolation to pass FQL string templates as query fragments to compose an FQL query:

```csharp
// Create a reusable query fragment.
var product = FQL($@"Product.byName(""pizza"").first()");

// Use the fragment in another FQL query.
var query = FQL($@"
    let product = {product}
    product {{
        name,
        price
    }}
");

client.QueryAsync(query);
```

### [](#poco-mapping)POCO mapping

With `Fauna.Mapping`, you can map a POCO class to a Fauna document or object shape:

```csharp
using Fauna.Mapping;

class Category
{
    // Property names are automatically converted to camelCase.
    [Id]
    public string? Id { get; set; }

    // Manually specify a name by providing a string.
    [Field("name")]
    public string? CatName { get; set; }
}

class Product
{
    [Id]
    public string? Id { get; set; }

    public string? Name { get; set; }

    public string? Description { get; set; }

    public int Price { get; set; }

    // Reference to document
    public Ref<Category> Category { get; set; }
}
```

*   `[Id]`: Should only be used once per class on a field named `Id` that represents the Fauna document ID. It’s not encoded unless the `isClientGenerated` flag is true.
    
*   `[Ts]`: Should only be used once per class on a field named `Ts` that represents the timestamp of a document. It’s not encoded.
    
*   `[Collection]`: Typically goes unmodeled. Should only be used once per class on a field named `Coll` that represents the collection field of a document. It will never be encoded.
    
*   `[Field]`: Can be associated with any field to override its name in Fauna.
    
*   `[Ignore]`: Can be used to ignore fields during encoding and decoding.
    

You can use POCO classes to deserialize query responses:

```csharp
var query = FQL($@"Product.sortedByPriceLowToHigh()");
var products = client.PaginateAsync<Product>(query).FlattenAsync();

await foreach (var p in products)
{
    Console.WriteLine($"{p.Name} {p.Description} {p.Price}");
}
```

You can also use POCO classes to write to your database:

```csharp
var product = new Product {
    Id = "12345",
    Name = "limes",
    Description = "Organic, 2 ct",
    Price = 95
};

client.QueryAsync(FQL($@"Product.create({product})"));
```

### [](#datacontext)`DataContext`

The `DataContext` class provides a schema-aware view of your database. Subclass it and configure your collections:

```csharp
class CustomerDb : DataContext
{
    public class CustomerCollection : Collection<Customer>
    {
        public Index<Customer> ByEmail(string email) => Index().Call(email);
        public Index<Customer> ByName(string name) => Index().Call(name);
    }

    public CustomerCollection Customer { get => GetCollection<CustomerCollection>(); }
}
```

`DataContext` provides `Client` querying, which automatically maps your collections to POCO equivalents, even when type hints are not provided.

```csharp
var db = client.DataContext<CustomerDb>

var result = db.QueryAsync(FQL($"Customer.all().first()"));
var customer = (Customer)result.Data!;

Console.WriteLine(customer.name);
```

### [](#document-references)Document references

The driver supports [document references](../../../learn/data-model/relationships/) using the `Ref<T>` type. There are several ways to work with document references using the driver:

1.  Fetch the reference without loading the referenced document:
    
    ```csharp
    // Gets a Product document.
    // The document's `category` field contains a
    // reference to a Category document. The
    // `category` field is not projected.
    var query = FQL($@"
      Product.byName('limes').first()
    ");
    
    var response = await client.QueryAsync<Product>(query);
    var product = response.Data;
    ```
    
2.  [Project](../../../reference/fql/projection/) the document reference to load the referenced document:
    
    ```csharp
    // Gets a Product document.
    // The `category` field is projected to load the
    // referenced document.
    var query = FQL($@"
      Product.byName('limes').first() {
        name,
        category {
          name
        }
      }
    ");
    
    var response = await client.QueryAsync<Dictionary<string, object?>>(query);
    var product = response.Data;
    
    Console.WriteLine(product["name"]);
    
    // Prints the category name.
    var category = (Dictionary<string, object?>)product["category"];
    Console.WriteLine(category["name"]);
    ```
    
3.  Use `LoadRefAsync()` to load the referenced document:
    
    ```csharp
    // Gets a Product document.
    var query = FQL($@"Product.byName('limes').first()");
    
    var response = await client.QueryAsync<Product>(query);
    var product = response.Data;
    
    // Loads the Category document referenced in
    // the Product document.
    var category = await client.LoadRefAsync(product.Category);
    // Prints the category name.
    Console.WriteLine(category.Name);
    ```
    
    If the reference is already loaded, it returns the cached value without making another query to Fauna:
    
    ```csharp
    // This won't run another query if the referenced
    // document is already loaded.
    var sameCategory = await client.LoadRefAsync(product.Category);
    ```
    

#### [](#null-documents)Null documents

A [null document](../../../reference/fql/types/#nulldoc) can be handled two ways:

1.  Let the driver throw an exception and do something with it:
    
    ```csharp
    try {
        await client.QueryAsync<SomeCollDoc>(FQL($"SomeColl.byId('123')"))
    } catch (NullDocumentException e) {
        Console.WriteLine(e.Id); // "123"
        Console.WriteLine(e.Collection.Name); // "SomeColl"
        Console.WriteLine(e.Cause); // "not found"
    }
    ```
    
2.  Wrap your expected type in a `Ref<>` or `NamedRef`. You can wrap `Dictionary<string,object>` and POCOs.
    
    ```csharp
    var q = FQL($"Collection.byName('Fake')");
    var r = (await client.QueryAsync<NamedRef<Dictionary<string,object>>>(q)).Data;
    if (r.Data.Exists) {
        Console.WriteLine(d.Id); // "Fake"
        Console.WriteLine(d.Collection.Name); // "Collection"
        var doc = r.Get(); // A dictionary with id, coll, ts, and any user-defined fields.
    } else {
        Console.WriteLine(d.Name); // "Fake"
        Console.WriteLine(d.Collection.Name); // "Collection"
        Console.WriteLine(d.Cause); // "not found"
        r.Get() // this throws a NullDocumentException
    }
    ```
    

### [](#pagination)Pagination

When you wish to paginate a [set](../../../reference/fql/types/#set), such as a collection or index, use `PaginateAsync()`.

Example of a query that returns a Set:

```csharp
var query = FQL($"Customer.all()");
await foreach (var page in client.PaginateAsync<Customer>(query))
{
    // handle each page
}

await foreach (var item in client.PaginateAsync<Customer>(query).FlattenAsync())
{
    // handle each item
}
```

Example of a query that returns an object with an embedded Set:

```csharp
class MyResult
{
    [Field("customers")]
    public Page<Customer>? Customers { get; set; }
}

var query = FQL($"{{customers: Customer.all()}}");
var result = await client.QueryAsync<MyResult>(query);

await foreach (var page in client.PaginateAsync(result.Data.Customers!))
{
    // handle each page
}

await foreach (var item in client.PaginateAsync(result.Data.Customers!).FlattenAsync())
{
    // handle each item
}
```

### [](#query-stats)Query stats

Successful query responses and `ServiceException` exceptions include [query stats](../../../reference/http/reference/query-stats/):

```csharp
try
{
    var client = new Client("FAUNA_SECRET");

    var query = FQL($@"'Hello world'");
    var response = await client.QueryAsync<string>(query);

    Console.WriteLine(response.Stats.ToString());
}
catch (FaunaException e)
{
  if (e is ServiceException serviceException)
  {
    Console.WriteLine(serviceException.Stats.ToString());
    Console.WriteLine(e);
  }
  else {
    Console.WriteLine(e);
  }
}
```

## [](#config)Client configuration

The `Client` instance comes with reasonable configuration defaults. We recommend using the defaults in most cases.

If needed, you can configure the client and override the defaults. This also lets you set default [Query options](#query-opts).

```csharp
var config = new Configuration("FAUNA_SECRET")
{
    // Configure the client
    Endpoint = new Uri("https://db.fauna.com"),
    RetryConfiguration = new RetryConfiguration(3, TimeSpan.FromSeconds(20)),

    // Set default query options
    DefaultQueryOptions = new QueryOptions
    {
        Linearized = false,
        QueryTags = new Dictionary<string, string>
        {
            { "tag", "value" }
        },
        QueryTimeout = TimeSpan.FromSeconds(60),
        TraceParent = "00-750efa5fb6a131eb2cf4db39f28366cb-000000000000000b-00",
        TypeCheck = false
    }
};

var client = new Client(config);
```

For supported properties, see [Fauna.Configuration](https://fauna.github.io/fauna-dotnet/latest/class_fauna_1_1_configuration.html) in the API reference.

### [](#environment-variables)Environment variables

By default, the client configuration’s `Secret` and `Endpoint` default to the respective `FAUNA_SECRET` and `FAUNA_ENDPOINT` environment variables.

For example, if you set the following environment variables:

```bash
export FAUNA_SECRET=FAUNA_SECRET
export FAUNA_ENDPOINT=https://db.fauna.com/
```

You can initialize the client with a default configuration:

```csharp
var client = new Client();
```

### [](#retries)Retries

By default, the client automatically retries query requests that return a `limit_exceeded` [error code](../../../reference/http/reference/errors/). Retries use an exponential backoff.

The client retries a query up to three times by default. The maximum wait time between retries defaults to 20 seconds.

To override these defaults, pass a `RetryConfiguration` instance to the [Client configuration](#config).

```csharp
var config = new Configuration("FAUNA_SECRET")
{
    RetryConfiguration = new RetryConfiguration(3, TimeSpan.FromSeconds(20))
};

var client = new Client(config);
```

For supported parameters, see [Fauna.Core.RetryConfiguration](https://fauna.github.io/fauna-dotnet/latest/class_fauna_1_1_core_1_1_retry_configuration.html) in the API reference.

## [](#query-opts)Query options

The [Client configuration](#config) sets default query options for the following methods:

*   `QueryAsync()`
    
*   `PaginateAsync()`
    

You can pass a `QueryOptions` argument to override these defaults:

```csharp
var queryOptions = new QueryOptions
{
    Linearized = false,
    QueryTags = new Dictionary<string, string>
    {
        { "tag", "value" }
    },
    QueryTimeout = TimeSpan.FromSeconds(60),
    TraceParent = "00-750efa5fb6a131eb2cf4db39f28366cb-000000000000000b-00",
    TypeCheck = true
};

var query = FQL($@"'Hello world'");
client.QueryAsync(query, queryOptions);
```

For supported properties, see [Fauna.Core.QueryOptions](https://fauna.github.io/fauna-dotnet/latest/class_fauna_1_1_core_1_1_query_options.html) in the API reference.

## [](#event-feeds)Event feeds

The driver supports [event feeds](../../../learn/cdc/#event-feeds). An event feed asynchronously polls an [event source](../../../learn/cdc/#create-an-event-source) for paginated events.

To use event feeds, you must have a Pro or Enterprise plan.

### [](#request-an-event-feed)Request an event feed

To get an event source, append [`set.eventSource()`](../../../reference/fql-api/set/eventsource/) or [`set.eventsOn()`](../../../reference/fql-api/set/eventson/) to a [supported Set](../../../learn/cdc/#sets).

To get paginated events, pass the event source to `EventFeedAsync()`:

```csharp
// Get an event source from a supported Set
EventSource eventSource = await client.QueryAsync<EventSource>(FQL($"Product.all().eventSource()"));

var feed = await client.EventFeedAsync<Product>(eventSource);
```

If changes occur between the creation of the event source and the event feed request, the feed replays and emits any related events.

You can also pass a query that produces an event source directly to `EventFeedAsync()`:

```csharp
var feed = await client.EventFeedAsync<Product>(FQL($"Product.all().eventSource()"));
```

If you pass an event source query to `EventFeedAsync()`, the driver creates the event source and requests the event feed at the same time.

In most cases, you’ll get events after a specific [event cursor](#cursor) or [start time](#start-time).

#### [](#start-time)Get events after a specific start time

When you first poll an event source using an event feed, you usually include a `startTs` (start timestamp) in the [`FeedOptions` object](#event-feed-opts) that’s passed to `EventFeedAsync()`. The request returns events that occurred after the specified timestamp (exclusive).

`startTs` is an integer representing a time in microseconds since the Unix epoch:

```csharp
// Calculate timestamp for 10 minutes ago in microseconds
long tenMinutesAgo = DateTimeOffset.UtcNow.AddMinutes(-10).ToUnixTimeMilliseconds() * 1000;
var feedOptions = new FeedOptions(startTs: tenMinutesAgo);

var feed = await client.EventFeedAsync<Product>(FQL($"Product.all().eventSource()", feedOptions));
```

`startTs` must be later than the creation time of the event source. The period between the request and the `startTs` can’t exceed the `history_days` setting for the source Set’s collection. If `history_days` is `0` or unset, the period is limited to 15 minutes.

#### [](#cursor)Get events after a specific event cursor

After the initial request, you usually get subsequent events using the [cursor](../../../learn/cdc/#cursor) for the last page or event.

To get events after a cursor (exclusive), include the `cursor` in the [`FeedOptions` object](#event-feed-opts) that’s passed to `EventFeedAsync()`:

```csharp
var feedOptions = new FeedOptions(cursor: "gsGabc456"); // Cursor for a previous page

var feed = await client.EventFeedAsync<Product>(FQL($"Product.all().eventSource()", feedOptions));
```

You can reuse cursors across event sources with identical queries in the same database.

### [](#loop)Iterate on an event feed

`EventFeedAsync()` returns a `FeedEnumerable` instance that acts as an `AsyncEnumerator`. Use `foreach()` to iterate through the pages of events:

```csharp
await foreach (var page in feed)
{
    foreach (var evt in page.Events)
    {
        Console.WriteLine($"Event Type: {evt.Type}");
        Product product = evt.Data;
        Console.WriteLine($"Product Name: {product.Name}");
    }
}
```

The `FeedEnumerable` will stop when there are no more events to poll.

Each page includes a top-level `cursor`. You can include the cursor in a [`FeedOptions` object](#event-feed-opts) passed to `EventFeedAsync()` to poll for events after the cursor.

### [](#error-handling)Error handling

Exceptions can be raised at two different places:

*   While fetching a page
    
*   While iterating a page’s events
    

This distinction allows for you to ignore errors originating from event processing. For example:

```csharp
try
{
    await foreach (var page in feed)
    {
        try
        {
            foreach (var evt in page.Events)
            {
                Console.WriteLine($"Event Type: {evt.Type}");
                Product product = evt.Data;
                Console.WriteLine($"Product Name: {product.Name}");
            }
        }
        // `EventException` is thrown for event processing errors.
        catch (EventException eventError)
        {
            Console.WriteLine($"Feed event error: {eventError}");
        }
    }
}
catch (Exception error)
{
    Console.WriteLine($"Non-retryable error: {error}");
}
```

Each page’s `cursor` contains the cursor for the page’s last successfully processed event. If you’re using a [loop to poll for changes](#loop), using the cursor will skip any events that caused errors.

### [](#event-feed-opts)Event feed options

The client configuration sets the default options for `EventFeedAsync()`. You can pass a [`FeedOptions`](https://fauna.github.io/fauna-dotnet/latest/class_fauna_1_1_core_1_1_feed_options.html) object to override these defaults:

```csharp
var feedOptions = new FeedOptions(
    startTs: 1710968002310000,
    pageSize: 10,
    cursor: "gsGabc456"
);

var feed = await client.EventFeedAsync<Product>(FQL($"Product.all().eventSource()"), feedOptions);
```

For supported properties, see [`FeedOptions`](https://fauna.github.io/fauna-dotnet/latest/class_fauna_1_1_core_1_1_feed_options.html) in the API reference.

## [](#event-streaming)Event streams

The driver supports [event streams](../../../learn/cdc/).

### [](#start-a-stream)Start a stream

To get an event source, append [`set.eventSource()`](../../../reference/fql-api/set/eventsource/) or [`set.eventsOn()`](../../../reference/fql-api/set/eventson/) to a [supported Set](../../../learn/cdc/#sets).

To stream the source’s events, pass the event source to `SubscribeStream()`:

```csharp
var query = fql($@"
  let set = Customer.all()

  {{
    initialPage: set.pageSize(10),
    eventSource: set.eventSource()
  }}
");

var response = await client.QueryAsync(query);
var eventSource = response["eventSource"].ToString();

await using var stream = client.SubscribeStream<Customer>(eventSource);
await foreach (var evt in stream)
{
    Console.WriteLine($"Received Event Type: {evt.Type}");
    if (evt.Data != null) // Status events won't have Data
    {
        Customer customer = evt.Data;
        Console.WriteLine($"Name: {customer.Name} - Email: {customer.Email}");
    }
}
```

You can also pass a query that produces an event source directly to `EventStreamAsync()`:

```csharp
var stream = await client.EventStreamAsync<Customer>(FQL($"Customer.all().eventSource()"));
await foreach (var evt in stream)
{
    Console.WriteLine($"Received Event Type: {evt.Type}");
    if (evt.Data != null)
    {
        Customer customer = evt.Data;
        Console.WriteLine($"Name: {customer.Name} - Email: {customer.Email}");
    }
}
```

### [](#stream-options)Stream options

The [Client configuration](#config) sets default options for the `SubscribeStream()` and `EventStreamAsync()` methods.

You can pass a [`StreamOptions`](https://fauna.github.io/fauna-dotnet/latest/class_fauna_1_1_stream_options.html) object to override these defaults:

```csharp
var options = new StreamOptions(
    token: "<EVENT_SOURCE>",
    cursor: "gsGghu789"
);

var stream = await client.EventStreamAsync<Customer>(
    query: FQL("Product.all().eventSource()"),
    streamOptions: options
);

await foreach (var evt in stream)
{
    Console.WriteLine($"Received Event Type: {evt.Type}");
    if (evt.Data != null)
    {
        Customer customer = evt.Data;
        Console.WriteLine($"Name: {customer.Name} - Email: {customer.Email}");
    }
}
```

## [](#debug-logging)Debug logging

To enable debug logging, set the `FAUNA_DEBUG` environment variable to an integer for the `Microsoft.Extensions.Logging.LogLevel`. For example:

*   `0`: `LogLevel.Trace` and higher (all messages)
    
*   `3`: `LogLevel.Warning` and higher
    

The driver logs HTTP request and response details, including headers. For security, the `Authorization` header is redacted in debug logs but is visible in trace logs.

For advanced logging, you can use a custom `ILogger` implementation, such as Serilog or NLog. Pass the implementation to the `Configuration` class when instantiating a `Client`.

### [](#basic-example-serilog)Basic example: Serilog

Install the packages:

```bash
dotnet add package Serilog
dotnet add package Serilog.Extensions.Logging
dotnet add package Serilog.Sinks.Console
dotnet add package Serilog.Sinks.File
```

Configure and use the logger:

```csharp
using Fauna;
using Microsoft.Extensions.Logging;
using Serilog;
using static Fauna.Query;

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Verbose()
    .WriteTo.Console()
    .WriteTo.File("log.txt",
        rollingInterval: RollingInterval.Day,
        rollOnFileSizeLimit: true)
    .CreateLogger();

var logFactory = new LoggerFactory().AddSerilog(Log.Logger);

var config = new Configuration("mysecret", logger: logFactory.CreateLogger("myapp"));

var client = new Client(config);

await client.QueryAsync(FQL($"1+1"));

// You should see LogLevel.Debug messages in both the Console and the "log{date}.txt" file
```

# .NET/C# driver source code


# Files

## File: Fauna/Core/Connection.cs
```csharp
using System.Collections.Concurrent;
using System.Net.Http.Headers;
using System.Runtime.CompilerServices;
using System.Text.Json;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;
using Fauna.Util;
using Microsoft.Extensions.Logging;
using Polly;
using Stream = System.IO.Stream;

namespace Fauna.Core;

/// <summary>
/// A class that handles HTTP requests and retries.
/// </summary>
internal class Connection : IConnection
{
    private readonly Configuration _cfg;
    private bool _disposed;

    public TimeSpan BufferedRequestTimeout { get; init; }

    /// <summary>
    /// Initializes a new instance of the Connection class.
    /// </summary>
    /// <param name="configuration">The <see cref="Configuration"/> to use.</param>
    public Connection(Configuration configuration)
    {
        _cfg = configuration;
        BufferedRequestTimeout = _cfg.DefaultQueryOptions.QueryTimeout.Add(_cfg.ClientBufferTimeout);
    }

    public async Task<HttpResponseMessage> DoPostAsync(
        string path,
        Stream body,
        Dictionary<string, string> headers,
        TimeSpan requestTimeout,
        CancellationToken cancel = default)
    {
        HttpResponseMessage response;

        using var timeboundCts = new CancellationTokenSource(requestTimeout);
        using var combinedCts = CancellationTokenSource.CreateLinkedTokenSource(timeboundCts.Token, cancel);

        var policyResult = await _cfg.RetryConfiguration.RetryPolicy
            .ExecuteAndCaptureAsync(() =>
                _cfg.HttpClient.SendAsync(CreateHttpRequest(path, body, headers), combinedCts.Token))
            .ConfigureAwait(false);
        response = policyResult.Outcome == OutcomeType.Successful
            ? policyResult.Result
            : policyResult.FinalHandledResult ?? throw policyResult.FinalException;

        Logger.Instance.LogDebug(
            "Fauna HTTP Response {status} from {uri}, headers: {headers}",
            response.StatusCode.ToString(),
            response.RequestMessage?.RequestUri?.ToString() ?? "UNKNOWN",
            JsonSerializer.Serialize(
                response.Headers.ToDictionary(kv => kv.Key, kv => kv.Value.ToList()))
        );

        Logger.Instance.LogTrace("Response body: {body}", await response.Content.ReadAsStringAsync(cancel));

        return response;
    }

    public async IAsyncEnumerable<Event<T>> OpenStream<T>(
        string path,
        Types.EventSource eventSource,
        Dictionary<string, string> headers,
        MappingContext ctx,
        [EnumeratorCancellation] CancellationToken cancellationToken = default) where T : notnull
    {
        cancellationToken.ThrowIfCancellationRequested();

        while (!cancellationToken.IsCancellationRequested)
        {
            using var bc = new BlockingCollection<Event<T>>(new ConcurrentQueue<Event<T>>());
            Task<PolicyResult<HttpResponseMessage>> streamTask =
                _cfg.RetryConfiguration.RetryPolicy.ExecuteAndCaptureAsync(async () =>
                {
                    var streamData = new MemoryStream();
                    eventSource.Serialize(streamData);

                    var response = await _cfg.HttpClient
                        .SendAsync(
                            CreateHttpRequest(path, streamData, headers),
                            HttpCompletionOption.ResponseHeadersRead,
                            cancellationToken)
                        .ConfigureAwait(false);

                    if (!response.IsSuccessStatusCode)
                    {
                        bc.CompleteAdding();
                        return response;
                    }

                    await using var streamAsync = await response.Content.ReadAsStreamAsync(cancellationToken);
                    using var streamReader = new StreamReader(streamAsync);

                    while (!streamReader.EndOfStream && !cancellationToken.IsCancellationRequested)
                    {
                        string? line = await streamReader.ReadLineAsync().WaitAsync(cancellationToken);
                        if (string.IsNullOrWhiteSpace(line))
                        {
                            continue;
                        }

                        var evt = Event<T>.From(line, ctx);
                        eventSource.Options.Cursor = evt.Cursor;

                        bc.Add(evt, cancellationToken);
                    }

                    return response;
                });

            foreach (var evt in bc.GetConsumingEnumerable(cancellationToken))
            {
                yield return evt;
            }

            await streamTask;
            bc.CompleteAdding();
            if (streamTask.Result.Result.IsSuccessStatusCode)
            {
                continue;
            }

            var httpResponse = streamTask.Result.Result;
            string body = await httpResponse.Content.ReadAsStringAsync(cancellationToken);

            throw ExceptionHandler.FromRawResponse(body, httpResponse);
        }
    }

    private HttpRequestMessage CreateHttpRequest(string path, Stream body, Dictionary<string, string> headers)
    {
        body.Position = 0;
        var request = new HttpRequestMessage
        {
            Content = new StreamContent(body),
            Method = HttpMethod.Post,
            RequestUri = new Uri(_cfg.Endpoint, path)
        };

        request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
        request.Headers.AcceptEncoding.Add(new StringWithQualityHeaderValue("gzip"));

        foreach (var header in headers)
        {
            request.Headers.Add(header.Key, header.Value);
        }

        Logger.Instance.LogDebug(
            "Fauna HTTP {method} Request to {uri} (timeout {timeout}ms), headers: {headers}",
            HttpMethod.Post.ToString(),
            request.RequestUri.ToString(),
            _cfg.HttpClient.Timeout.TotalMilliseconds,
            JsonSerializer.Serialize(
                request.Headers
                    .Select(header =>
                    {
                        // Redact Auth header in debug logs
                        if (header.Key.StartsWith("Authorization", StringComparison.InvariantCultureIgnoreCase))
                        {
                            return KeyValuePair.Create(header.Key, new[] { "hidden" }.AsEnumerable());
                        }

                        return header;
                    })
                    .ToDictionary(kv => kv.Key, kv => kv.Value.ToList()))
        );

        // Emit unredacted Auth header and response body in trace logs
        Logger.Instance.LogTrace("Unredacted Authorization header: {value}", request.Headers.Authorization?.ToString() ?? "null");
        Logger.Instance.LogTrace("Request body: {body}", request.Content.ReadAsStringAsync().Result);

        return request;
    }

    private void Dispose(bool disposing)
    {
        if (_disposed) return;

        if (disposing && _cfg.DisposeHttpClient)
        {
            _cfg.HttpClient.Dispose();
            GC.SuppressFinalize(this);
        }

        _disposed = true;
    }

    /// <summary>
    /// Disposes the resources used by the <see cref="Connection"/> class.
    /// </summary>
    public void Dispose()
    {
        Dispose(true);
    }

    // A finalizer: https://stackoverflow.com/questions/151051/when-should-i-use-gc-suppressfinalize
    ~Connection()
    {
        Dispose(false);
    }
}
```

## File: Fauna/Core/Endpoints.cs
```csharp
namespace Fauna.Core;

/// <summary>
/// Represents the endpoints used for accessing Fauna.
/// </summary>
public static class Endpoints
{
    /// <summary>
    /// The default URI for Fauna, used for production.
    /// </summary>
    public static Uri Default { get; } = new("https://db.fauna.com");

    /// <summary>
    /// Gets the configured endpoint URI, falling back to the default if not set.
    /// </summary>
    /// <returns>The URI for the Fauna endpoint.</returns>
    public static Uri GetFaunaEndpoint()
    {
        string? endpoint = Environment.GetEnvironmentVariable("FAUNA_ENDPOINT");
        if (string.IsNullOrWhiteSpace(endpoint))
        {
            return Default;
        }

        if (Uri.IsWellFormedUriString(endpoint, UriKind.Absolute))
        {
            return new Uri(endpoint);
        }

        throw new UriFormatException("Invalid FAUNA_ENDPOINT environment variable. Must be a valid URI.");
    }
}
```

## File: Fauna/Core/ErrorInfo.cs
```csharp
using System.Text.Json.Serialization;
using Fauna.Exceptions;
using static Fauna.Core.ResponseFields;

namespace Fauna.Core;

/// <summary>
/// Contains detailed information about an error in a query response.
/// </summary>
public readonly struct ErrorInfo
{
    /// <summary>
    /// The error code when a query fails.
    /// </summary>
    [JsonPropertyName(Error_CodeFieldName)]
    public string? Code { get; init; }

    /// <summary>
    /// The detailed message describing the cause of the error.
    /// </summary>
    [JsonPropertyName(Error_MessageFieldName)]
    public string? Message { get; init; }

    /// <summary>
    /// The constraint failures that occurred during the query.
    /// </summary>
    [JsonPropertyName(Error_ConstraintFailuresFieldName)]
    public ConstraintFailure[] ConstraintFailures { get; init; }

    /// <summary>
    /// The information about an abort operation within a transaction.
    /// </summary>
    [JsonPropertyName(Error_AbortFieldName)]
    public object? Abort { get; init; }
}
```

## File: Fauna/Core/FeedEnumerable.cs
```csharp
using Fauna.Types;

namespace Fauna.Core;


/// <summary>
/// Represents a Fauna event feed.
/// </summary>
/// <typeparam name="T">Type to map each of the Events to.</typeparam>
public class FeedEnumerable<T> where T : notnull
{
    private readonly BaseClient _client;
    private readonly EventSource _eventSource;
    private readonly CancellationToken _cancel;

    /// <summary>
    /// Current cursor for the Feed.
    /// </summary>
    public string? Cursor => CurrentPage?.Cursor;

    /// <summary>
    /// The latest page returned from the event feed enumerator.
    /// </summary>
    public FeedPage<T>? CurrentPage { get; private set; }

    internal FeedEnumerable(
        BaseClient client,
        EventSource eventSource,
        CancellationToken cancel = default)
    {
        _client = client;
        _eventSource = eventSource;
        _cancel = cancel;
    }

    /// <summary>
    /// Returns an enumerator that iterates through the Feed.
    /// </summary>
    /// <returns>Event Page Enumerator</returns>
    public async IAsyncEnumerator<FeedPage<T>> GetAsyncEnumerator()
    {
        await using var subscribeFeed = _client.SubscribeFeed<T>(
            _eventSource,
            _client.MappingCtx,
            _cancel);

        while (!_cancel.IsCancellationRequested && await subscribeFeed.MoveNextAsync())
        {
            CurrentPage = subscribeFeed.Current;
            yield return CurrentPage;
        }
    }
}
```

## File: Fauna/Core/FeedOptions.cs
```csharp
using Fauna.Types;

namespace Fauna.Core;

/// <summary>
/// Represents the options when subscribing to Fauna event feeds.
/// </summary>
public class FeedOptions : EventOptions
{
    /// <summary>
    /// Initializes a new instance of the <see cref="FeedOptions"/> class with the specified cursor and optional page size.
    /// </summary>
    /// <param name="cursor">The cursor for the feed. Used to resume the Feed.</param>
    /// <param name="pageSize">Optional page size for the feed. Sets the maximum number of events returned per page. Must
    /// be in the range 1 to 16000 (inclusive). Defaults to 16.</param>
    /// <seealso href="https://docs.fauna.com/fauna/current/reference/cdc/#get-events-after-a-specific-cursor"/>
    public FeedOptions(string cursor, int? pageSize = null)
    {
        Cursor = cursor;
        PageSize = pageSize;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="FeedOptions"/> class with the specified start timestamp and optional page size.
    /// </summary>
    /// <param name="startTs">The start timestamp for the feed. Used to resume the Feed.</param>
    /// <param name="pageSize">Optional page size for the feed. Sets the maximum number of events returned per page. Must
    /// be in the range 1 to 16000 (inclusive). Defaults to 16.</param>
    /// <seealso href="https://docs.fauna.com/fauna/current/reference/cdc/#get-events-after-a-specific-cursor"/>
    public FeedOptions(long startTs, int? pageSize = null)
    {
        StartTs = startTs;
        PageSize = pageSize;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="FeedOptions"/> class with the specified page size.
    /// </summary>
    /// <param name="pageSize">Maximum number of events returned per page. Must
    /// be in the range 1 to 16000 (inclusive). Defaults to 16.</param>
    public FeedOptions(int pageSize)
    {
        PageSize = pageSize;
    }
}
```

## File: Fauna/Core/FeedPage.cs
```csharp
using System.Text.Json;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;
using static Fauna.Core.ResponseFields;

namespace Fauna.Core;

/// <summary>
/// Represents the response from Fauna event feed requests.
/// </summary>
/// <typeparam name="T"></typeparam>
public class FeedPage<T> where T : notnull
{
    /// <summary>
    /// List of Events returned by the Feed
    /// </summary>
    public List<Event<T>> Events { get; private init; } = [];

    /// <summary>
    /// Cursor returned from the Feed
    /// </summary>
    public string Cursor { get; private init; } = null!;

    /// <summary>
    /// Indicates if there are more pages for pagination.
    /// </summary>
    public bool HasNext { get; private init; }

    /// <summary>
    /// Stats returned from the Feed.
    /// </summary>
    public QueryStats Stats { get; private init; }

    internal static FeedPage<T> From(string body, MappingContext ctx)
    {
        var json = JsonSerializer.Deserialize<JsonElement>(body);

        var err = GetError(json);
        if (err != null)
        {
            throw new FaunaException(err.Value);
        }

        return new FeedPage<T>
        {
            Cursor = GetCursor(json),
            Events = GetEvents(json, ctx),
            Stats = GetStats(json),
            HasNext = json.TryGetProperty(HasNextFieldName, out var elem) && elem.GetBoolean()
        };
    }

    private static List<Event<T>> GetEvents(JsonElement json, MappingContext ctx)
    {
        if (!json.TryGetProperty(EventsFieldName, out var elem))
        {
            return new List<Event<T>>();
        }

        var events = elem.EnumerateArray().Select(e => Event<T>.From(e, ctx)).ToList();
        return events;
    }

    private static QueryStats GetStats(JsonElement json)
    {
        return json.TryGetProperty(StatsFieldName, out var elem) ? elem.Deserialize<QueryStats>() : default;
    }

    private static string GetCursor(JsonElement json)
    {
        return json.TryGetProperty(CursorFieldName, out var elem) ? elem.GetString()! : null!;
    }

    private static ErrorInfo? GetError(JsonElement json)
    {
        return json.TryGetProperty(ErrorFieldName, out var elem) ? elem.Deserialize<ErrorInfo>() : null;
    }
}
```

## File: Fauna/Core/Headers.cs
```csharp
namespace Fauna.Core;

/// <summary>
/// Contains constant values for HTTP header names used in Fauna API requests.
/// </summary>
internal readonly struct Headers
{
    /// <summary>
    /// Header for the authorization token in API requests.
    /// </summary>
    public const string Authorization = "Authorization";

    /// <summary>
    /// Header indicating the minimum snapshot time for the query execution based on the highest transaction timestamp observed by the client.
    /// </summary>
    public const string LastTxnTs = "X-Last-Txn-Ts";

    /// <summary>
    /// Header to enforce strictly serialized execution of the query, affecting read-only transactions.
    /// </summary>
    public const string Linearized = "X-Linearized";

    /// <summary>
    /// Header indicating the maximum number of retries for a transaction due to contention failure before returning an error.
    /// </summary>
    public const string MaxContentionRetries = "X-Max-Contention-Retries";

    /// <summary>
    /// Header specifying the query timeout in milliseconds.
    /// </summary>
    public const string QueryTimeoutMs = "X-Query-Timeout-Ms";

    /// <summary>
    /// Header to enable or disable type checking of the query before evaluation.
    /// </summary>
    public const string TypeCheck = "X-Typecheck";

    /// <summary>
    /// Header for passing custom, string-encoded tags for request identification in logs and responses.
    /// </summary>
    public const string QueryTags = "X-Query-Tags";

    /// <summary>
    /// Header for the trace parent identifier in distributed tracing systems.
    /// </summary>
    public const string TraceParent = "Traceparent";

    /// <summary>
    /// Header indicating the driver used for the API request.
    /// </summary>
    public const string Driver = "X-Driver";

    /// <summary>
    /// Header for specifying the environment of the driver used in the API request.
    /// </summary>
    public const string DriverEnv = "X-Driver-Env";

    /// <summary>
    /// Header for specifying the encoded format for query arguments and response data.
    /// Options are 'simple' and 'tagged'. 'Simple' is the default format.
    /// </summary>
    public const string Format = "X-Format";
}
```

## File: Fauna/Core/IConnection.cs
```csharp
using Fauna.Mapping;
using Fauna.Types;
using Stream = System.IO.Stream;

namespace Fauna.Core;

/// <summary>
/// Represents an interface for making HTTP requests.
/// </summary>
internal interface IConnection : IDisposable
{
    /// <summary>
    /// Asynchronously sends a POST request to the specified path with the provided body and headers.
    /// </summary>
    /// <param name="path">The path of the resource to send the request to.</param>
    /// <param name="body">The stream containing the request body.</param>
    /// <param name="headers">A dictionary of headers to be included in the request.</param>
    /// <param name="requestTimeout">The HTTP request timeout</param>
    /// <param name="cancel">A cancellation token to use with the request.</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the response from the server as <see cref="HttpResponseMessage"/>.</returns>
    Task<HttpResponseMessage> DoPostAsync(
        string path,
        Stream body,
        Dictionary<string, string> headers,
        TimeSpan requestTimeout,
        CancellationToken cancel);

    /// <summary>
    /// Asynchronously sends a POST request to open Stream.
    /// </summary>
    /// <param name="path">The path of the resource to send the request to.</param>
    /// <param name="eventSource"></param>
    /// <param name="headers">The headers to include in the request.</param>
    /// <param name="ctx"></param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
    /// <returns>A task that represents the asynchronous operation, which opens the HTTP stream and returns the <see cref="HttpResponseMessage"/>.</returns>
    /// Implementation <seealso cref="Connection.OpenStream{T}"/>

    IAsyncEnumerable<Event<T>> OpenStream<T>(
        string path,
        Types.EventSource eventSource,
        Dictionary<string, string> headers,
        MappingContext ctx,
        CancellationToken cancellationToken = default) where T : notnull;
}
```

## File: Fauna/Core/QueryOptions.cs
```csharp
namespace Fauna.Core;

/// <summary>
/// Represents the options for customizing Fauna queries.
/// </summary>
public class QueryOptions
{
    /// <summary>
    /// Gets or sets a value indicating whether the query runs as strictly serialized, affecting read-only transactions.
    /// </summary>
    public bool? Linearized { get; set; } = null;

    /// <summary>
    /// Gets or sets a value indicating whether type checking of the query is enabled or disabled before evaluation.
    /// </summary>
    public bool? TypeCheck { get; set; } = null;

    /// <summary>
    /// Gets or sets the query timeout. It defines how long the client waits for a query to complete.
    /// Default value is 5 seconds.
    /// </summary>
    public TimeSpan QueryTimeout { get; set; } = TimeSpan.FromSeconds(5);

    /// <summary>
    /// Gets or sets a string-encoded set of caller-defined tags for identifying the request in logs and response bodies. 
    /// Each key and value should be limited to [a-zA-Z0-9_].
    /// </summary>
    public Dictionary<string, string>? QueryTags { get; set; } = null;

    /// <summary>
    /// Gets or sets the trace parent identifier for distributed tracing systems.
    /// </summary>
    public string? TraceParent { get; set; } = null;

    /// <summary>
    /// Merges two instances of <see cref="QueryOptions"/>.
    /// </summary>
    /// <param name="options">The default query options.</param>
    /// <param name="overrides">The query options provided for a specific query, overriding the defaults.</param>
    /// <returns>A <see cref="QueryOptions"/> object representing the final combined set of query options.</returns>
    internal static QueryOptions GetFinalQueryOptions(QueryOptions options, QueryOptions? overrides)
    {
        if (overrides == null)
        {
            return options;
        }

        var finalQueryOptions = new QueryOptions()
        {
            Linearized = options.Linearized,
            TypeCheck = options.TypeCheck,
            QueryTimeout = options.QueryTimeout,
            QueryTags = options.QueryTags,
            TraceParent = options.TraceParent,
        };

        var properties = typeof(QueryOptions).GetProperties();

        foreach (var prop in properties)
        {
            if (prop.Name.Equals(nameof(QueryTags)))
            {
                continue;
            }

            var propertyOverride = prop.GetValue(overrides);

            if (propertyOverride != null)
            {
                prop.SetValue(finalQueryOptions, propertyOverride);
            }
        }

        if (overrides.QueryTags != null)
        {
            if (finalQueryOptions.QueryTags == null)
            {
                finalQueryOptions.QueryTags = overrides.QueryTags;
            }
            else
            {
                foreach (var kv in overrides.QueryTags)
                {
                    if (finalQueryOptions.QueryTags.ContainsKey(kv.Key))
                    {
                        finalQueryOptions.QueryTags[kv.Key] = kv.Value;
                    }
                    else
                    {
                        finalQueryOptions.QueryTags.Add(kv.Key, kv.Value);
                    }
                }
            }
        }

        return finalQueryOptions;
    }
}
```

## File: Fauna/Core/QueryResponse.cs
```csharp
using System.Net;
using System.Text.Json;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Serialization;
using static Fauna.Core.ResponseFields;

namespace Fauna.Core;

/// <summary>
/// Represents the response from a query executed.
/// </summary>
public abstract class QueryResponse
{
    /// <summary>
    /// The raw JSON of the query response.
    /// </summary>
    public JsonElement RawJson { get; init; }

    /// <summary>
    /// Gets the last transaction seen by this query.
    /// </summary>
    public long LastSeenTxn { get; init; }

    /// <summary>
    /// Gets the schema version.
    /// </summary>
    public long SchemaVersion { get; init; }

    /// <summary>
    /// Gets a summary of the query execution.
    /// </summary>
    public string Summary { get; init; } = "";

    /// <summary>
    /// Gets a dictionary of query tags, providing additional context about the query.
    /// </summary>
    public Dictionary<string, string> QueryTags { get; init; } = new();

    /// <summary>
    /// Gets the statistics related to the query execution.
    /// </summary>
    public QueryStats Stats { get; init; }

    internal QueryResponse(JsonElement json)
    {
        RawJson = json;

        if (json.TryGetProperty(LastSeenTxnFieldName, out var elem))
        {
            if (elem.TryGetInt64(out var i)) LastSeenTxn = i;
        }

        if (json.TryGetProperty(SchemaVersionFieldName, out elem))
        {
            if (elem.TryGetInt64(out var i)) LastSeenTxn = i;
        }

        if (json.TryGetProperty(SummaryFieldName, out elem))
        {
            Summary = elem.GetString() ?? "";
        }


        if (json.TryGetProperty(QueryTagsFieldName, out elem))
        {
            var queryTagsString = elem.GetString();

            if (!string.IsNullOrEmpty(queryTagsString))
            {
                var tagPairs = queryTagsString.Split(',').Select(tag =>
                {
                    var tokens = tag.Split('=');
                    return KeyValuePair.Create(tokens[0], tokens[1]);
                });

                QueryTags = new Dictionary<string, string>(tagPairs);
            }
        }

        if (json.TryGetProperty(StatsFieldName, out elem))
        {
            Stats = elem.Deserialize<QueryStats>();
        }
    }

    /// <summary>
    /// Asynchronously parses the HTTP response message to create a QueryResponse instance.
    /// </summary>
    /// <typeparam name="T">The expected data type of the query response.</typeparam>
    /// <param name="ctx">Serialization context for handling response data.</param>
    /// <param name="serializer">A serializer for the success data type.</param>
    /// <param name="statusCode">The HTTP status code.</param>
    /// <param name="body">The response body.</param>
    /// <returns>A Task that resolves to a QueryResponse instance.</returns>
    public static QueryResponse? GetFromResponseBody<T>(
        MappingContext ctx,
        ISerializer<T> serializer,
        HttpStatusCode statusCode,
        string body)
    {
        try
        {
            var json = JsonSerializer.Deserialize<JsonElement>(body);

            if (statusCode is >= HttpStatusCode.OK and <= (HttpStatusCode)299)
            {
                return new QuerySuccess<T>(ctx, serializer, json);
            }

            return new QueryFailure(statusCode, json);
        }
        catch (JsonException)
        {
            return null;
        }
    }
}

/// <summary>
/// Represents a successful query response.
/// </summary>
/// <typeparam name="T">The type of data expected in the query result.</typeparam>
public sealed class QuerySuccess<T> : QueryResponse
{
    /// <summary>
    /// Gets the deserialized data from the query response.
    /// </summary>
    public T Data { get; init; }

    /// <summary>
    /// Gets the static type information from the query response, if available.
    /// </summary>
    public string? StaticType { get; init; }

    /// <summary>
    /// Initializes a new instance of the <see cref="QuerySuccess{T}"/> class, deserializing the query response into the specified type.
    /// </summary>
    /// <param name="ctx">The serialization context used for deserializing the response data.</param>
    /// <param name="serializer">A deserializer for the response data type.</param>
    /// <param name="json">The parsed JSON response body.</param>
    public QuerySuccess(
        MappingContext ctx,
        ISerializer<T> serializer,
        JsonElement json)
        : base(json)
    {
        var dataText = json.GetProperty(DataFieldName).GetRawText();
        var reader = new Utf8FaunaReader(dataText);
        reader.Read();
        Data = serializer.Deserialize(ctx, ref reader);

        if (json.TryGetProperty(StaticTypeFieldName, out var elem))
        {
            StaticType = elem.GetString();
        }
    }
}

/// <summary>
/// Represents a failed query response.
/// </summary>
public sealed class QueryFailure : QueryResponse
{
    /// <summary>
    /// The HTTP status code.
    /// </summary>
    public HttpStatusCode StatusCode { get; init; }
    /// <summary>
    /// The Fauna error code.
    /// </summary>
    public string ErrorCode { get; init; } = "";
    /// <summary>
    /// The query failure message.
    /// </summary>
    public string Message { get; init; } = "";
    /// <summary>
    /// The constraint failures, if any. Only present for the  constraint_failure error code.
    /// </summary>
    public ConstraintFailure[]? ConstraintFailures { get; init; }
    /// <summary>
    /// The abort object, if any. Only present for the abort error code.
    /// </summary>
    public object? Abort { get; init; }

    /// <summary>
    /// Initializes a new instance of the <see cref="QueryFailure"/> class, parsing the provided raw response text to extract error information.
    /// </summary>
    /// <param name="statusCode">The HTTP status code.</param>
    /// <param name="json">The JSON response body.</param>
    public QueryFailure(HttpStatusCode statusCode, JsonElement json) : base(json)
    {
        StatusCode = statusCode;
        if (!json.TryGetProperty(ErrorFieldName, out var elem)) return;

        var info = elem.Deserialize<ErrorInfo>();
        ErrorCode = info.Code ?? "";
        Message = info.Message ?? "";

        ConstraintFailures = info.ConstraintFailures;
        Abort = info.Abort;
    }
}
```

## File: Fauna/Core/QueryStats.cs
```csharp
using System.Text.Json.Serialization;
using static Fauna.Core.ResponseFields;

namespace Fauna.Core;

/// <summary>
/// Contains statistics related to the execution of a query in the Fauna database.
/// </summary>
public readonly struct QueryStats
{
    /// <summary>
    /// The number of compute operations consumed by the query.
    /// </summary>
    [JsonPropertyName(Stats_ComputeOpsFieldName)]
    public int ComputeOps { get; init; }

    /// <summary>
    /// The number of read operations consumed by the query.
    /// </summary>
    [JsonPropertyName(Stats_ReadOps)]
    public int ReadOps { get; init; }

    /// <summary>
    /// The number of write operations consumed by the query.
    /// </summary>
    [JsonPropertyName(Stats_WriteOps)]
    public int WriteOps { get; init; }

    /// <summary>
    /// The query processing time in milliseconds.
    /// </summary>
    [JsonPropertyName(Stats_QueryTimeMs)]
    public int QueryTimeMs { get; init; }

    /// <summary>
    /// The write contention retry count.
    /// </summary>
    [JsonPropertyName(Stats_ContentionRetries)]
    public int ContentionRetries { get; init; }

    /// <summary>
    /// The amount of data read from storage, in bytes.
    /// </summary>
    [JsonPropertyName(Stats_StorageBytesRead)]
    public int StorageBytesRead { get; init; }

    /// <summary>
    /// The amount of data written to storage, in bytes.
    /// </summary>
    [JsonPropertyName(Stats_StorageBytesWrite)]
    public int StorageBytesWrite { get; init; }

    /// <summary>
    /// The types of operations that were limited or approaching rate limits.
    /// </summary>
    [JsonPropertyName(Stats_RateLimitsHit)]
    public List<string> RateLimitsHit { get; init; }

    /// <summary>
    /// Processing time in milliseconds. Only returned on Events.
    /// </summary>
    [JsonPropertyName(Stats_ProcessingTimeMs)]
    public int? ProcessingTimeMs { get; init; }

    /// <summary>
    /// Returns a string representation of the query statistics.
    /// </summary>
    /// <returns>A string detailing the query execution statistics.</returns>
    public override string ToString()
    {
        return $"compute: {ComputeOps}, read: {ReadOps}, write: {WriteOps}, " +
               $"queryTime: {QueryTimeMs}, retries: {ContentionRetries}, " +
               $"storageRead: {StorageBytesRead}, storageWrite: {StorageBytesWrite}, " +
               $"{(ProcessingTimeMs.HasValue ? $"processingTime: {ProcessingTimeMs}, " : "")}" +
               $"limits: [{string.Join(',', RateLimitsHit)}]";
    }
}
```

## File: Fauna/Core/ResponseFields.cs
```csharp
namespace Fauna.Core;

/// <summary>
/// Contains constant values for the response field names returned by Fauna API queries.
/// </summary>
internal readonly struct ResponseFields
{
    #region Top-level fields

    /// <summary>
    /// Field name for the main data content of the response.
    /// </summary>
    public const string DataFieldName = "data";

    /// <summary>
    /// Field name for the transaction timestamp of the last transaction seen by the request.
    /// </summary>
    public const string LastSeenTxnFieldName = "txn_ts";

    /// <summary>
    /// Field name for the stream cursor of the response.
    /// </summary>
    public const string CursorFieldName = "cursor";

    /// <summary>
    /// Field name for static type information in the response.
    /// </summary>
    public const string StaticTypeFieldName = "static_type";

    /// <summary>
    /// Field name for statistical information about the query execution.
    /// </summary>
    public const string StatsFieldName = "stats";

    /// <summary>
    /// Field name for the schema version of the database at the time of query execution.
    /// </summary>
    public const string SchemaVersionFieldName = "schema_version";

    /// <summary>
    /// Field name for the summary information about the query execution.
    /// </summary>
    public const string SummaryFieldName = "summary";

    /// <summary>
    /// Field name for query tags associated with the request, used in logging and monitoring.
    /// </summary>
    public const string QueryTagsFieldName = "query_tags";

    /// <summary>
    /// Field name for error information if the query fails.
    /// </summary>
    public const string ErrorFieldName = "error";

    /// <summary>
    /// Field name for pagination information.
    /// </summary>
    public const string HasNextFieldName = "has_next";

    /// <summary>
    /// Field name for array of events.
    /// </summary>
    public const string EventsFieldName = "events";

    #endregion

    #region "stats" block

    /// <summary>
    /// Field name for the number of compute operations consumed by the query.
    /// </summary>
    public const string Stats_ComputeOpsFieldName = "compute_ops";

    /// <summary>
    /// Field name for the number of read operations consumed by the query.
    /// </summary>
    public const string Stats_ReadOps = "read_ops";

    /// <summary>
    /// Field name for the number of write operations consumed by the query.
    /// </summary>
    public const string Stats_WriteOps = "write_ops";

    /// <summary>
    /// Field name for the query processing time in milliseconds.
    /// </summary>
    public const string Stats_QueryTimeMs = "query_time_ms";

    /// <summary>
    /// Field name for the write contention retry count.
    /// </summary>
    public const string Stats_ContentionRetries = "contention_retries";

    /// <summary>
    /// Field name for the amount of data read from storage, in bytes.
    /// </summary>
    public const string Stats_StorageBytesRead = "storage_bytes_read";

    /// <summary>
    /// Field name for the amount of data written to storage, in bytes.
    /// </summary>
    public const string Stats_StorageBytesWrite = "storage_bytes_write";

    /// <summary>
    /// Field name for the types of operations that were limited or approaching rate limits.
    /// </summary>
    public const string Stats_RateLimitsHit = "rate_limits_hit";

    /// <summary>
    /// Field name for the processing time in milliseconds.
    /// </summary>
    public const string Stats_ProcessingTimeMs = "processing_time_ms";

    #endregion

    #region "error" block

    /// <summary>
    /// Field name for the error code when a query fails.
    /// </summary>
    public const string Error_CodeFieldName = "code";

    /// <summary>
    /// Field name for the detailed message describing the cause of the error.
    /// </summary>
    public const string Error_MessageFieldName = "message";

    /// <summary>
    /// Field name for constraint failures that occurred during the query.
    /// </summary>
    public const string Error_ConstraintFailuresFieldName = "constraint_failures";

    /// <summary>
    /// Field name for the message in constraint failures.
    /// </summary>
    public const string Error_ConstraintFailuresMessageFieldName = "message";

    /// <summary>
    /// Field name for the name in constraint failures.
    /// </summary>
    public const string Error_ConstraintFailuresNameFieldName = "name";

    /// <summary>
    /// Field name for the paths in constraint failures.
    /// </summary>
    public const string Error_ConstraintFailuresPathsFieldName = "paths";

    /// <summary>
    /// Field name for information about an abort operation within a transaction.
    /// </summary>
    public const string Error_AbortFieldName = "abort";

    #endregion
}
```

## File: Fauna/Core/RetryConfiguration.cs
```csharp
using System.Net;
using System.Net.Sockets;
using Polly;

namespace Fauna.Core;

/// <summary>
/// A class representing a retry configuration for queries.
/// </summary>
public class RetryConfiguration
{

    /// <summary>
    /// Gets the retry policy.
    /// </summary>
    public AsyncPolicy<HttpResponseMessage> RetryPolicy { get; set; }


    /// <summary>
    /// Creates a new <see cref="RetryConfiguration"/> instance.
    /// </summary>
    /// <param name="retryCount">Maximum times to retry a request.</param>
    /// <param name="maxBackoff">The maximum backoff to apply.</param>
    public RetryConfiguration(int retryCount, TimeSpan maxBackoff)
    {
        RetryPolicy = Policy
            .Handle<HttpRequestException>()
            .Or<SocketException>()
            .Or<IOException>()
            .Or<InvalidOperationException>()
            .OrResult<HttpResponseMessage>(r => r.StatusCode == HttpStatusCode.TooManyRequests)
            .WaitAndRetryAsync(retryCount, attempt =>
            {
                int calculated = (int)Math.Floor(Math.Pow(2, attempt));
                int backoff = calculated > maxBackoff.Seconds ? maxBackoff.Seconds : calculated;
                return TimeSpan.FromSeconds(backoff);
            });
    }
}
```

## File: Fauna/Core/StatsCollector.cs
```csharp
namespace Fauna.Core;


/// <summary>
/// A struct representing stats aggregated across queries.
/// </summary>
public readonly struct Stats
{
    /// <summary>
    /// The aggregate read ops.
    /// </summary>
    public long ReadOps { get; init; }
    /// <summary>
    /// The aggregate compute ops.
    /// </summary>
    public long ComputeOps { get; init; }
    /// <summary>
    /// The aggregate write ops.
    /// </summary>
    public long WriteOps { get; init; }
    /// <summary>
    /// The aggregate query time in milliseconds.
    /// </summary>
    public long QueryTimeMs { get; init; }
    /// <summary>
    /// The aggregate number of retries due to transaction contention.
    /// </summary>
    public int ContentionRetries { get; init; }
    /// <summary>
    /// The aggregate number of storage bytes read.
    /// </summary>
    public long StorageBytesRead { get; init; }
    /// <summary>
    /// The aggregate number of storage bytes written.
    /// </summary>
    public long StorageBytesWrite { get; init; }
    /// <summary>
    /// The aggregate number of queries summarized.
    /// </summary>
    public int QueryCount { get; init; }

    /// <summary>
    /// The aggregate count of rate limited queries due to read limits.
    /// </summary>
    public int RateLimitedReadQueryCount { get; init; }
    /// <summary>
    /// The aggregate count of rate limited queries due to compute limits.
    /// </summary>
    public int RateLimitedComputeQueryCount { get; init; }
    /// <summary>
    /// The aggregate count of rate limited queries due to write limits.
    /// </summary>
    public int RateLimitedWriteQueryCount { get; init; }
}

/// <summary>
/// An interface used by a client instance for aggregating stats across all queries.
/// </summary>
public interface IStatsCollector
{
    /// <summary>
    /// Add the <see cref="QueryStats"/> to the current counts.
    /// </summary>
    /// <param name="stats">QueryStats</param>
    public void Add(QueryStats stats);

    /// <summary>
    /// Return the collected <see cref="Stats"/>.
    /// </summary>
    public Stats Read();

    /// <summary>
    /// Return the collected <see cref="Stats"/> and Reset counts.
    /// </summary>
    public Stats ReadAndReset();
}

/// <summary>
/// The default implementation of <see cref="IStatsCollector"/>.
/// </summary>
public class StatsCollector : IStatsCollector
{
    private const string RateLimitReadOps = "read";
    private const string RateLimitComputeOps = "compute";
    private const string RateLimitWriteOps = "write";

    private long _readOps;
    private long _computeOps;
    private long _writeOps;
    private long _queryTimeMs;
    private int _contentionRetries;
    private long _storageBytesRead;
    private long _storageBytesWrite;
    private int _queryCount;
    private int _rateLimitedReadQueryCount;
    private int _rateLimitedComputeQueryCount;
    private int _rateLimitedWriteQueryCount;

    /// <inheritdoc />
    public void Add(QueryStats stats)
    {
        Interlocked.Exchange(ref _readOps, _readOps + stats.ReadOps);
        Interlocked.Exchange(ref _computeOps, _computeOps + stats.ComputeOps);
        Interlocked.Exchange(ref _writeOps, _writeOps + stats.WriteOps);
        Interlocked.Exchange(ref _queryTimeMs, _queryTimeMs + stats.QueryTimeMs);
        Interlocked.Exchange(ref _contentionRetries, _contentionRetries + stats.ContentionRetries);
        Interlocked.Exchange(ref _storageBytesRead, _storageBytesRead + stats.StorageBytesRead);
        Interlocked.Exchange(ref _storageBytesWrite, _storageBytesWrite + stats.StorageBytesWrite);

        stats.RateLimitsHit?.ForEach(limitHit =>
        {
            switch (limitHit)
            {
                case RateLimitReadOps:
                    Interlocked.Increment(ref _rateLimitedComputeQueryCount);
                    break;
                case RateLimitComputeOps:
                    Interlocked.Increment(ref _rateLimitedComputeQueryCount);
                    break;
                case RateLimitWriteOps:
                    Interlocked.Increment(ref _rateLimitedWriteQueryCount);
                    break;
            }
        });

        Interlocked.Increment(ref _queryCount);
    }

    /// <inheritdoc />
    public Stats Read()
    {
        return new Stats
        {
            ReadOps = _readOps,
            ComputeOps = _computeOps,
            WriteOps = _writeOps,
            QueryTimeMs = _queryTimeMs,
            ContentionRetries = _contentionRetries,
            StorageBytesRead = _storageBytesRead,
            StorageBytesWrite = _storageBytesWrite,
            QueryCount = _queryCount,
            RateLimitedReadQueryCount = _rateLimitedReadQueryCount,
            RateLimitedComputeQueryCount = _rateLimitedComputeQueryCount,
            RateLimitedWriteQueryCount = _rateLimitedWriteQueryCount
        };
    }

    /// <inheritdoc />
    public Stats ReadAndReset()
    {
        var beforeReset = new Stats
        {
            ReadOps = Interlocked.Exchange(ref _readOps, 0),
            ComputeOps = Interlocked.Exchange(ref _computeOps, 0),
            WriteOps = Interlocked.Exchange(ref _writeOps, 0),
            QueryTimeMs = Interlocked.Exchange(ref _queryTimeMs, 0),
            ContentionRetries = Interlocked.Exchange(ref _contentionRetries, 0),
            StorageBytesRead = Interlocked.Exchange(ref _storageBytesRead, 0),
            StorageBytesWrite = Interlocked.Exchange(ref _storageBytesWrite, 0),
            QueryCount = Interlocked.Exchange(ref _queryCount, 0),
            RateLimitedReadQueryCount = Interlocked.Exchange(ref _rateLimitedReadQueryCount, 0),
            RateLimitedComputeQueryCount = Interlocked.Exchange(ref _rateLimitedComputeQueryCount, 0),
            RateLimitedWriteQueryCount = Interlocked.Exchange(ref _rateLimitedWriteQueryCount, 0)
        };

        return beforeReset;
    }
}
```

## File: Fauna/Core/StreamEnumerable.cs
```csharp
using Fauna.Types;

namespace Fauna.Core;

/// <summary>
/// A class representing a Fauna event stream. Additional queries will be made during enumeration.
/// </summary>
/// <typeparam name="T">The return type of the stream.</typeparam>
public class StreamEnumerable<T> where T : notnull
{
    private readonly BaseClient _client;
    private readonly EventSource _eventSource;
    private readonly CancellationToken _cancel;

    /// <summary>
    /// The token for the event source.
    /// </summary>
    public string Token => _eventSource.Token;

    internal StreamEnumerable(
        BaseClient client,
        EventSource eventSource,
        CancellationToken cancel = default)
    {
        _client = client;
        _eventSource = eventSource;
        _cancel = cancel;
    }

    /// <summary>
    /// Gets an async enumerator for the stream.
    /// </summary>
    /// <returns>An async enumerator that yields <see cref="Event{T}"/>.</returns>
    public async IAsyncEnumerator<Event<T>> GetAsyncEnumerator()
    {
        await using var subscribeStream = _client.SubscribeStream<T>(
            _eventSource,
            _client.MappingCtx,
            _cancel);

        while (!_cancel.IsCancellationRequested && await subscribeStream.MoveNextAsync())
        {
            yield return subscribeStream.Current;
        }
    }
}
```

## File: Fauna/Core/StreamOptions.cs
```csharp
using Fauna.Types;

namespace Fauna;

/// <summary>
/// Represents the options when subscribing to Fauna event streams.
/// </summary>
public class StreamOptions : EventOptions
{
    /// <summary>
    /// Initializes a new instance of the <see cref="StreamOptions"/> class with the specified token and cursor.
    /// </summary>
    /// <param name="token">The token for a Fauna event source.</param>
    /// <param name="cursor">The cursor from the stream, must be used with the associated Token. Used to resume the stream.</param>
    /// See <a href="https://docs.fauna.com/fauna/current/reference/cdc/#restart">Restart an event stream</a>.
    public StreamOptions(string token, string cursor)
    {
        Token = token;
        Cursor = cursor;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="StreamOptions"/> class with the specified token and start timestamp.
    /// </summary>
    /// <param name="token">The token for a Fauna event source.</param>
    /// <param name="startTs">The start timestamp to use for the stream.</param>
    public StreamOptions(string token, long startTs)
    {
        Token = token;
        StartTs = startTs;
    }

    /// <summary>Token for a Fauna event source.</summary>
    /// See the <a
    /// href="https://docs.fauna.com/fauna/current/reference/cdc/#event-source">Create an event source</a>.
    public string? Token { get; }
}
```

## File: Fauna/Exceptions/AbortException.cs
```csharp
using Fauna.Core;
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception that occurs when the FQL `abort` function is called.
/// This exception captures the data provided during the abort operation.
/// </summary>
public class AbortException : ServiceException
{
    private readonly MappingContext _ctx;
    private readonly Dictionary<Type, object?> _cache = new();
    private readonly object? _abortRaw;


    /// <summary>
    /// Initializes a new instance of the <see cref="AbortException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/></param>
    /// <param name="ctx">A mapping context.</param>
    public AbortException(string message, QueryFailure failure, MappingContext ctx)
        : base(message, failure)
    {
        _ctx = ctx;
        _abortRaw = failure.Abort;
    }

    /// <summary>
    /// Retrieves the deserialized data associated with the abort operation as an object.
    /// </summary>
    /// <returns>The deserialized data as an object, or null if no data is available.</returns>
    public object? GetData() => GetData(Serializer.Dynamic);

    /// <summary>
    /// Retrieves the deserialized data associated with the abort operation as a specific type.
    /// </summary>
    /// <typeparam name="T">The type to which the data should be deserialized.</typeparam>
    /// <returns>The deserialized data as the specified type, or null if no data is available.</returns>
    public T? GetData<T>() where T : notnull => GetData(Serializer.Generate<T>(_ctx));

    /// <summary>
    /// Retrieves the deserialized data associated with the abort operation as a specific type.
    /// </summary>
    /// <typeparam name="T">The type to which the data should be deserialized.</typeparam>
    /// <param name="serializer">A serializer for the abort data.</param>
    /// <returns>The deserialized data as the specified type, or null if no data is available.</returns>
    public T? GetData<T>(ISerializer<T> serializer)
    {
        var typeKey = typeof(T);
        if (_cache.TryGetValue(typeKey, out var cachedData)) return (T?)cachedData;

        if (_abortRaw == null) return (T?)cachedData;

        var abortDataString = _abortRaw.ToString();
        if (string.IsNullOrEmpty(abortDataString)) return (T?)cachedData;

        // TODO(matt) pull from context
        var reader = new Utf8FaunaReader(abortDataString);
        reader.Read();

        var deserializedResult = serializer.Deserialize(_ctx, ref reader);
        _cache[typeKey] = deserializedResult;
        return deserializedResult;
    }
}
```

## File: Fauna/Exceptions/AuthenticationException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception thrown when there is an authorization error in Fauna.
/// Corresponds to the 'unauthorized' error code in Fauna.
/// </summary>
public class AuthenticationException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="AuthenticationException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public AuthenticationException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/AuthorizationException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception thrown when access to a resource is not allowed.
/// Corresponds to the 'forbidden' error code in Fauna.
/// </summary>
public class AuthorizationException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="AuthorizationException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/></param>
    public AuthorizationException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/BadGatewayException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception thrown for a bad gateway.
/// Corresponds to the 'bad_gateway' error code in Fauna.
/// </summary>
public class BadGatewayException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="BadGatewayException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/></param>
    public BadGatewayException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/ConstraintFailure.cs
```csharp
using System.Text.Json.Serialization;
using static Fauna.Core.ResponseFields;

namespace Fauna.Exceptions;

/// <summary>
/// A class representing a <a href="https://docs.fauna.com/fauna/current/reference/fsl/check/">constraint failure</a> from Fauna.
/// </summary>
public class ConstraintFailure
{
    /// <summary>
    /// Initializes a new <see cref="ConstraintFailure"/>.
    /// </summary>
    /// <param name="message">The message describing the constraint failure.</param>
    /// <param name="name">The name of the constraint failure.</param>
    /// <param name="paths">The paths for the constraint failure.</param>
    public ConstraintFailure(string message, string name, object[][]? paths)
    {
        Message = message;
        Name = name;
        Paths = paths;
    }

    /// <summary>
    /// The constraint failure message describing the specific check that failed.
    /// </summary>
    [JsonPropertyName(Error_ConstraintFailuresMessageFieldName)]
    public string Message { get; set; }

    /// <summary>
    /// The constraint failure name.
    /// </summary>
    [JsonPropertyName(Error_ConstraintFailuresNameFieldName)]
    public string Name { get; set; }

    /// <summary>
    /// The constraint failure paths.
    /// </summary>
    [JsonPropertyName(Error_ConstraintFailuresPathsFieldName)]
    public object[][]? Paths { get; set; }

}
```

## File: Fauna/Exceptions/ConstraintFailureException.cs
```csharp
using Fauna.Core;
using Fauna.Mapping;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception that occurs when constraints are violated in a query.
/// This exception captures the specific constraint failures for inspection.
/// </summary>
public class ConstraintFailureException : ServiceException
{
    /// <summary>
    /// The constraint failures related to the exception.
    /// </summary>
    public ConstraintFailure[]? ConstraintFailures { get; }

    /// <summary>
    /// Initializes a new instance of the <see cref="ConstraintFailureException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/></param>
    public ConstraintFailureException(string message, QueryFailure failure)
        : base(message, failure)
    {
        ConstraintFailures = failure.ConstraintFailures;
    }
}
```

## File: Fauna/Exceptions/ContendedTransactionException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception that occurs when a transaction is aborted due to concurrent modification.
/// This exception is considered retryable after a suitable delay.
/// </summary>
public class ContendedTransactionException : ServiceException, IRetryableException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="ContendedTransactionException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public ContendedTransactionException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/EventException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception related to Fauna event stream and event feed errors.
/// </summary>
public class EventException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="EventException"/> class.
    /// </summary>
    /// <param name="err">The <see cref="ErrorInfo"/> from which to extract a message.</param>
    public EventException(ErrorInfo err) : base(message: err.Message!) { }
}
```

## File: Fauna/Exceptions/ExceptionHandler.cs
```csharp
using System.Net;
using Fauna.Core;
using Fauna.Mapping;

namespace Fauna.Exceptions;

/// <summary>
/// A utility class for generating an appropriate <see cref="FaunaException"/> from a <see cref="QueryFailure"/>.
/// </summary>
public static class ExceptionHandler
{
    /// <summary>
    /// Creates an exception from a <see cref="QueryFailure"/>
    /// </summary>
    /// <param name="ctx">A <see cref="MappingContext"/> used for exceptions that require additional deserialization, such as <see cref="AbortException"/>.</param>
    /// <param name="f">The <see cref="QueryFailure"/>.</param>
    /// <returns></returns>
    public static Exception FromQueryFailure(MappingContext ctx, QueryFailure f)
    {
        var msg =
            $"{f.StatusCode} ({f.ErrorCode}): {f.Message}{(f.Summary is { Length: > 0 } ? "\n---\n" + f.Summary : "")}";

        return f.ErrorCode switch
        {
            "abort" => new AbortException(msg, f, ctx),
            "bad_gateway" => new BadGatewayException(msg, f),
            "contended_transaction" => new ContendedTransactionException(msg, f),
            "forbidden" => new AuthorizationException(msg, f),
            "internal_error" => new ServiceException(msg, f),
            "invalid_query" => new QueryCheckException(msg, f),
            "invalid_request" => new InvalidRequestException(msg, f),
            "limit_exceeded" => new ThrottlingException(msg, f),
            "time_out" => new QueryTimeoutException(msg, f),
            "gateway_timeout" => new NetworkException(msg, f.StatusCode, f.Message),
            "unauthorized" => new AuthenticationException(msg, f),
            "constraint_failure" => new ConstraintFailureException(msg, f),

            _ => new QueryRuntimeException(msg, f)
        };
    }


    /// <summary>
    /// Creates an exception from a body and an already consumed <see cref="HttpResponseMessage"/>
    /// </summary>
    /// <param name="body">The response body.</param>
    /// <param name="r">The <see cref="HttpResponseMessage"/> with consumed body.</param>
    /// <returns></returns>
    public static Exception FromRawResponse(string body, HttpResponseMessage r)
    {
        if (r.StatusCode is >= HttpStatusCode.OK and <= (HttpStatusCode)299)
        {
            // We should never get here, but if we do it's outside of the expected wire protocol.
            return new ProtocolException("Malformed response.", r.StatusCode, body);
        }

        return r.StatusCode switch
        {
            HttpStatusCode.TooManyRequests => new ThrottlingException(
                $"{r.StatusCode}: {r.ReasonPhrase ?? "Too many requests."}"),
            _ => new FaunaException($"{r.StatusCode}: {r.ReasonPhrase}")
        };
    }
}
```

## File: Fauna/Exceptions/FaunaException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents the base exception class for all exceptions specific to Fauna interactions.
/// </summary>
public class FaunaException : Exception
{
    /// <summary>
    /// Initializes a FaunaException with a message.
    /// </summary>
    /// <param name="message">The exception message.</param>
    public FaunaException(string message) : base(message) { }

    /// <summary>
    /// Initializes a FaunaException with a message and inner exception.
    /// </summary>
    /// <param name="message">The exception message.</param>
    /// <param name="innerException">The inner exception.</param>
    public FaunaException(string message, Exception innerException)
    : base(message, innerException) { }

    /// <summary>
    /// Initializes a FaunaException from an <see cref="ErrorInfo"/> instance.
    /// </summary>
    /// <param name="err">The <see cref="ErrorInfo"/> from which to extract a message.</param>
    public FaunaException(ErrorInfo err) : base(message: err.Message) { }
}
```

## File: Fauna/Exceptions/InvalidRequestException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents exceptions caused by invalid requests to Fauna.
/// </summary>
public class InvalidRequestException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="InvalidRequestException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public InvalidRequestException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/IRetryableException.cs
```csharp
namespace Fauna.Exceptions;

/// <summary>
/// Represents an interface for exceptions that are potentially recoverable through retrying the failed operation.
/// </summary>
public interface IRetryableException { }
```

## File: Fauna/Exceptions/NetworkException.cs
```csharp
using System.Net;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception that occurs when a request fails due to a network issue.
/// </summary>
public class NetworkException : FaunaException
{
    /// <summary>
    /// The response body that caused the <see cref="ProtocolException"/> to be thrown.
    /// </summary>
    public string ResponseBody { get; init; }

    /// <summary>
    /// The HTTP status code associated with the <see cref="ProtocolException"/>.
    /// </summary>
    public HttpStatusCode StatusCode { get; init; }

    /// <summary>
    /// Initializes a new instance of the <see cref="NetworkException"/> class.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="statusCode">The HTTP status code from the related HTTP request.</param>
    /// <param name="body">The HTTP response body that was out of protocol.</param>
    public NetworkException(string message, HttpStatusCode statusCode, string body)
        : base(message)
    {
        StatusCode = statusCode;
        ResponseBody = body;
    }
}
```

## File: Fauna/Exceptions/NullDocumentException.cs
```csharp
using Fauna.Types;

namespace Fauna.Exceptions;

/// <summary>
/// An exception representing a case when a document cannot be materialized because it does not exist.
/// </summary>
public class NullDocumentException : Exception
{
    /// <summary>
    /// The ID associated with the document. In the case of named documents, this will be null.
    /// </summary>
    public string? Id { get; }

    /// <summary>
    /// The name associated with the document. In the case of user documents, this will be null.
    /// </summary>
    public string? Name { get; }

    /// <summary>
    /// The collection to which the document belongs.
    /// </summary>
    public Module Collection { get; }

    /// <summary>
    /// The cause for the null document.
    /// </summary>
    public string Cause { get; }

    /// <summary>
    /// Initializes a new instance of the <see cref="NullDocumentException"/> class.
    /// </summary>
    /// <param name="id">The ID of the document. Should be null if it's a named document.</param>
    /// <param name="name">The name of the document. Should be null if it's a user docuemnt.</param>
    /// <param name="collection">The collection associated with the document.</param>
    /// <param name="cause">The cause of the null document.</param>
    public NullDocumentException(string? id, string? name, Module collection, string cause) : base($"Document {id ?? name} in collection {collection.Name} is null: {cause}")
    {
        Id = id;
        Name = name;
        Collection = collection;
        Cause = cause;
    }
}
```

## File: Fauna/Exceptions/ProtocolException.cs
```csharp
using System.Net;

namespace Fauna.Exceptions;

/// <summary>
/// Represents exceptions when a response does not match the wire protocol.
/// </summary>
public class ProtocolException : FaunaException
{
    /// <summary>
    /// The response body that caused the <see cref="ProtocolException"/> to be thrown.
    /// </summary>
    public string ResponseBody { get; init; }

    /// <summary>
    /// The HTTP status code associated with the <see cref="ProtocolException"/>.
    /// </summary>
    public HttpStatusCode StatusCode { get; init; }

    /// <summary>
    /// Initializes a new instance of the <see cref="ProtocolException"/> class.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="statusCode">The HTTP status code from the related HTTP request.</param>
    /// <param name="body">The HTTP response body that was out of protocol.</param>
    public ProtocolException(string message, HttpStatusCode statusCode, string body)
        : base(message)
    {
        StatusCode = statusCode;
        ResponseBody = body;
    }
}
```

## File: Fauna/Exceptions/QueryCheckException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents exceptions thrown when the query has syntax errors.
/// </summary>
public class QueryCheckException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="QueryCheckException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public QueryCheckException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/QueryRuntimeException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents exceptions thrown when the query fails at runtime.
/// </summary>
public class QueryRuntimeException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="QueryRuntimeException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public QueryRuntimeException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/QueryTimeoutException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents exceptions thrown when the query execution time exceeds the specified or default timeout period.
/// </summary>
public class QueryTimeoutException : TimeoutException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="QueryTimeoutException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public QueryTimeoutException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/SerializationException.cs
```csharp
namespace Fauna.Exceptions;

/// <summary>
/// Represents error that occur during serialization and deserialization of Fauna data.
/// </summary>
public class SerializationException : Exception
{
    /// <summary>
    /// Initializes a new instance of the <see cref="SerializationException"/> class with a specified error message.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    public SerializationException(string? message) : base(message)
    {
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="SerializationException"/> class with a specified error message and inner exception.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="innerException">The inner exception.</param>
    public SerializationException(string? message, Exception? innerException) : base(message, innerException)
    {
    }
}
```

## File: Fauna/Exceptions/ServiceException.cs
```csharp
using System.Net;
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception related to Fauna service errors, particularly for query failures.
/// </summary>
public class ServiceException : FaunaException
{

    /// <summary>
    /// The error code when a query fails.
    /// </summary>
    public string? ErrorCode { get; init; }

    /// <summary>
    /// The tags on the x-query-tags header, if it was provided.
    /// </summary>
    public IDictionary<string, string> QueryTags { get; init; }

    /// <summary>
    /// The schema version used by the query. This can be used by clients displaying
    /// schema to determine when they should refresh their schema. If the schema
    /// version that a client has stored differs from the one returned by the query,
    /// schema should be refreshed.
    /// </summary>
    public long? SchemaVersion { get; init; }

    /// <summary>
    /// The query stats for the request.
    /// </summary>
    public QueryStats Stats { get; init; }

    /// <summary>
    /// The HTTP status code.
    /// </summary>
    public HttpStatusCode? StatusCode { get; set; }

    /// <summary>
    /// A comprehensive, human readable summary of any errors, warnings and/or logs returned from the query.
    /// </summary>
    public string? Summary { get; init; }

    /// <summary>
    /// The transaction commit time in micros since epoch. Used by drivers to
    /// populate the x-last-txn-ts request header in order to get a consistent
    /// prefix RYOW guarantee.
    /// </summary>
    public long? TxnTs { get; init; }

    /// <summary>
    /// Initializes a new instance of the <see cref="ServiceException"/> class with a specified query failure details and error message.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    public ServiceException(string message)
        : base(message)
    {
        QueryTags = new Dictionary<string, string>();
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="ServiceException"/> class with a specified query failure details and error message.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/></param>
    public ServiceException(string message, QueryFailure failure)
        : base(message)
    {
        StatusCode = failure.StatusCode;
        ErrorCode = failure.ErrorCode;
        Summary = failure.Summary;
        Stats = failure.Stats;
        TxnTs = failure.LastSeenTxn;
        SchemaVersion = failure.SchemaVersion;
        QueryTags = failure.QueryTags;
    }

}
```

## File: Fauna/Exceptions/ThrottlingException.cs
```csharp
using System.Net;
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents an exception that indicates some capacity limit was exceeded and thus the request could not be served.
/// This exception is considered retryable after a suitable delay.
/// </summary>
public class ThrottlingException : ServiceException, IRetryableException
{

    /// <summary>
    /// Initializes a new instance of the <see cref="ThrottlingException"/> class with a specified error message.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    public ThrottlingException(string message) : base(message)
    {
        StatusCode = HttpStatusCode.TooManyRequests;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="ThrottlingException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public ThrottlingException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Exceptions/TimeoutException.cs
```csharp
using Fauna.Core;

namespace Fauna.Exceptions;

/// <summary>
/// Represents exceptions thrown when the query execution time exceeds the specified or default timeout period.
/// </summary>
public class TimeoutException : ServiceException
{
    /// <summary>
    /// Initializes a new instance of the <see cref="TimeoutException"/> class with a specified error message and query failure details.
    /// </summary>
    /// <param name="message">The error message that explains the reason for the exception.</param>
    /// <param name="failure">A <see cref="QueryFailure"/>.</param>
    public TimeoutException(string message, QueryFailure failure) : base(message, failure)
    {
    }
}
```

## File: Fauna/Linq/DataContext.cs
```csharp
using System.Collections.Immutable;
using System.Diagnostics.CodeAnalysis;
using System.Reflection;
using System.Runtime.CompilerServices;
using Fauna.Core;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Linq;

/// <summary>
/// An abstract class representing a DataContext. This is a special type of Fauna client that can be used to execute LINQ-style queries.
///
/// Users should implement this for each database they'd like to query with LINQ.
/// </summary>
public abstract class DataContext : BaseClient
{
    private bool _initialized = false;
    [AllowNull]
    private IReadOnlyDictionary<Type, ICollection> _collections = null!;
    [AllowNull]
    private Client _client = null!;
    [AllowNull]
    private MappingContext _ctx = null!;

    internal override MappingContext MappingCtx { get => _ctx; }
    internal Linq.LookupTable LookupTable { get => new Linq.LookupTable(_ctx); }

    internal void Init(Client client, Dictionary<Type, ICollection> collections, MappingContext ctx)
    {
        _client = client;
        _collections = collections.ToImmutableDictionary();
        _ctx = ctx;

        foreach (var col in collections.Values)
        {
            ((Linq.QuerySource)col).SetContext(this);
        }

        _initialized = true;
    }

    // IClient impl

    internal override Task<QuerySuccess<T>> QueryAsyncInternal<T>(
        Query query,
        Serialization.ISerializer<T> serializer,
        MappingContext ctx,
        QueryOptions? queryOptions,
        CancellationToken cancel)
    {
        CheckInitialization();
        return _client.QueryAsyncInternal(query, serializer, ctx, queryOptions, cancel);
    }

    internal override IAsyncEnumerator<Event<T>> SubscribeStreamInternal<T>(
        EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default)
    {
        CheckInitialization();
        return _client.SubscribeStreamInternal<T>(eventSource, ctx, cancel);
    }

    internal override IAsyncEnumerator<FeedPage<T>> SubscribeFeedInternal<T>(
        EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default)
    {
        CheckInitialization();
        return _client.SubscribeFeedInternal<T>(eventSource, ctx, cancel);
    }


    // Schema DSL

    /// <summary>
    /// An attribute representing a collection name.
    /// </summary>
    [AttributeUsage(AttributeTargets.Class)]
    public class NameAttribute : Attribute
    {
        internal readonly string Name;

        /// <summary>
        /// Initializes a <see cref="NameAttribute"/>.
        /// </summary>
        /// <param name="name">The collection name.</param>
        public NameAttribute(string name)
        {
            Name = name;
        }
    }

    /// <summary>
    /// An interface for a Fauna collection within a <see cref="DataContext"/>.
    /// </summary>
    public interface ICollection : Linq.IQuerySource
    {
        /// <summary>
        /// The collection name.
        /// </summary>
        public string Name { get; }
        /// <summary>
        /// The .NET type associated with documents in the collection.
        /// </summary>
        public Type DocType { get; }
    }

    /// <summary>
    /// An abstract collection. This should be implemented for each collection in the database.
    /// </summary>
    /// <typeparam name="Doc">The .NET type associated with documents in the collection.</typeparam>
    public abstract class Collection<Doc> : Linq.QuerySource<Doc>, ICollection
    {
        /// <inheritdoc />
        public string Name { get; }

        /// <inheritdoc />
        public Type DocType { get => typeof(Doc); }

        /// <summary>
        /// Initializes a new collection with a name set to the <see cref="NameAttribute"/>, or the name of
        /// .NET type associated with its documents.
        /// </summary>
        public Collection()
        {
            var nameAttr = this.GetType().GetCustomAttribute<NameAttribute>();
            Name = nameAttr?.Name ?? typeof(Doc).Name;
            SetQuery<Doc>(Linq.IntermediateQueryHelpers.CollectionAll(this));
        }

        // index call DSL

        /// <summary>
        /// Initializes an index associated with the collection. The name of the index can be assigned, or if
        /// declared inside a concrete <see cref="DataContext"/>, a canonical name will be assigned when a name
        /// is not provided.
        /// </summary>
        /// <param name="name">The name of the index.</param>
        /// <param name="auto">Used to generate a canonical name when name is null.</param>
        /// <returns></returns>
        /// <exception cref="ArgumentException"></exception>
        protected IndexCall Index(string? name = null, [CallerMemberName] string? auto = null)
        {
            if (name is null && auto is not null)
            {
                name = FieldName.Canonical(auto);
            }

            if (string.IsNullOrEmpty(name))
                throw new ArgumentException($"{nameof(name)} cannot be null or empty.");

            return new IndexCall(this, name, Ctx);
        }

        /// <summary>
        /// A class representing an index call.
        /// </summary>
        protected class IndexCall
        {
            private readonly ICollection _coll;
            private readonly string _name;
            private readonly DataContext _ctx;

            /// <summary>
            /// Initializes an index call.
            /// </summary>
            /// <param name="coll">The collection the index belongs to.</param>
            /// <param name="name">The name of the index.</param>
            /// <param name="ctx">The <see cref="DataContext"/></param>
            public IndexCall(ICollection coll, string name, DataContext ctx)
            {
                _coll = coll;
                _name = name;
                _ctx = ctx;
            }

            /// <summary>
            /// Invokes an index.
            /// </summary>
            /// <returns>An <see cref="Index{Doc}"/> query source.</returns>
            public Index<Doc> Call() => Call(new object[] { });

            /// <summary>
            /// Invokes an index.
            /// </summary>
            /// <param name="a1">An index argument.</param>
            /// <returns>An <see cref="Index{Doc}"/> query source.</returns>
            public Index<Doc> Call(object a1) => Call(new object[] { a1 });

            /// <summary>
            /// Invokes an index.
            /// </summary>
            /// <param name="a1">An index argument.</param>
            /// <param name="a2">An index argument.</param>
            /// <returns>An <see cref="Index{Doc}"/> query source.</returns>
            public Index<Doc> Call(object a1, object a2) => Call(new object[] { a1, a2 });

            /// <summary>
            /// Invokes an index.
            /// </summary>
            /// <param name="a1">An index argument.</param>
            /// <param name="a2">An index argument.</param>
            /// <param name="a3">An index argument.</param>
            /// <returns>An <see cref="Index{Doc}"/> query source.</returns>
            public Index<Doc> Call(object a1, object a2, object a3) => Call(new object[] { a1, a2, a3 });

            /// <summary>
            /// Invokes an index.
            /// </summary>
            /// <param name="args">An array of index arguments.</param>
            /// <returns>An <see cref="Index{Doc}"/> query source.</returns>
            public Index<Doc> Call(object[] args) => new Index<Doc>(_coll, _name, args, _ctx);

        }
    }

    /// <summary>
    /// An interface representing an index query source.
    /// </summary>
    public interface IIndex : Linq.IQuerySource
    {
        /// <summary>
        /// The collection the index belongs to.
        /// </summary>
        public ICollection Collection { get; }
        /// <summary>
        /// The name of the index.
        /// </summary>
        public string Name { get; }
        /// <summary>
        /// The return type of the index.
        /// </summary>
        public Type DocType { get; }
        /// <summary>
        /// An index argument array.
        /// </summary>
        public object[] Args { get; }
    }

    /// <summary>
    /// A class representing an index query source.
    /// </summary>
    /// <typeparam name="Doc"></typeparam>
    public class Index<Doc> : Linq.QuerySource<Doc>, IIndex
    {
        /// <inheritdoc />
        public ICollection Collection { get; }

        /// <inheritdoc />
        public string Name { get; }

        /// <inheritdoc />
        public Type DocType { get => typeof(Doc); }

        /// <inheritdoc />
        public object[] Args { get; }

        internal Index(ICollection coll, string name, object[] args, DataContext ctx)
        {
            Collection = coll;
            Name = name;
            Args = args;
            Ctx = ctx;
            SetQuery<Doc>(Linq.IntermediateQueryHelpers.CollectionIndex(this));
        }
    }

    // UDF / Function DSL

    /// <summary>
    /// An interface representing a function.
    /// </summary>
    public interface IFunction : Linq.IQuerySource
    {
        /// <summary>
        /// The name of the function.
        /// </summary>
        public string Name { get; }
        /// <summary>
        /// An array of arguments for the function.
        /// </summary>
        public object[] Args { get; }
    }

    /// <summary>
    /// A class representing a function call.
    /// </summary>
    /// <typeparam name="T">The return type of the function.</typeparam>
    protected class FunctionCall<T> where T : notnull
    {

        /// <summary>
        /// The name of the function.
        /// </summary>
        public string Name { get; }
        private readonly DataContext _ctx;

        /// <summary>
        /// Initializes a function call.
        /// </summary>
        /// <param name="name">The name of the function.</param>
        /// <param name="ctx">The <see cref="DataContext"/> that the function belongs to.</param>
        public FunctionCall(string name, DataContext ctx)
        {
            Name = name;
            _ctx = ctx;
        }

        /// <summary>
        /// Calls the function.
        /// </summary>
        /// <returns>The result of the function call.</returns>
        public T Call() => Call(Array.Empty<object>());

        /// <summary>
        /// Calls the function.
        /// </summary>
        /// <param name="a1">A function call argument.</param>
        /// <returns>The result of the function call.</returns>
        public T Call(object a1) => Call(new[] { a1 });

        /// <summary>
        /// Calls the function.
        /// </summary>
        /// <param name="a1">A function call argument.</param>
        /// <param name="a2">A function call argument.</param>
        /// <returns>The result of the function call.</returns>
        public T Call(object a1, object a2) => Call(new[] { a1, a2 });

        /// <summary>
        /// Calls the function.
        /// </summary>
        /// <param name="a1">A function call argument.</param>
        /// <param name="a2">A function call argument.</param>
        /// <param name="a3">A function call argument.</param>
        /// <returns>The result of the function call.</returns>
        public T Call(object a1, object a2, object a3) => Call(new[] { a1, a2, a3 });

        /// <summary>
        /// Calls the function.
        /// </summary>
        /// <param name="args">An array of function call arguments.</param>
        /// <returns>The result of the function call.</returns>
        public T Call(object[] args) => CallAsync(args).Result;

        /// <summary>
        /// Calls the function asynchronously.
        /// </summary>
        /// <returns>The result of the function call.</returns>
        public async Task<T> CallAsync() => await CallAsync(Array.Empty<object>());

        /// <summary>
        /// Calls the function asynchronously.
        /// </summary>
        /// <param name="a1">A function call argument.</param>
        /// <returns>The result of the function call.</returns>
        public async Task<T> CallAsync(object a1) => await CallAsync(new[] { a1 });

        /// <summary>
        /// Calls the function asynchronously.
        /// </summary>
        /// <param name="a1">A function call argument.</param>
        /// <param name="a2">A function call argument.</param>
        /// <returns>The result of the function call.</returns>
        public async Task<T> CallAsync(object a1, object a2) => await CallAsync(new[] { a1, a2 });

        /// <summary>
        /// Calls the function asynchronously.
        /// </summary>
        /// <param name="a1">A function call argument.</param>
        /// <param name="a2">A function call argument.</param>
        /// <param name="a3">A function call argument.</param>
        /// <returns>The result of the function call.</returns>
        public async Task<T> CallAsync(object a1, object a2, object a3) => await CallAsync(new[] { a1, a2, a3 });

        /// <summary>
        /// Calls the function asynchronously.
        /// </summary>
        /// <param name="args">An array of function call arguments.</param>
        /// <returns>The result of the function call.</returns>
        public async Task<T> CallAsync(object[] args)
        {
            var q = Linq.IntermediateQueryHelpers.Function(Name, args);
            return (await _ctx.QueryAsync<T>(q)).Data;
        }

    }

    /// <summary>
    /// A helper method to declare new function calls.
    /// </summary>
    /// <param name="name">The name of the function. If null, the caller name is used.</param>
    /// <param name="callerName">The caller name.</param>
    /// <typeparam name="T"></typeparam>
    /// <returns></returns>
    protected FunctionCall<T> Fn<T>(string name = "", [CallerMemberName] string callerName = "") where T : notnull
    {
        var fnName = name == "" ? callerName : name;
        return new FunctionCall<T>(fnName, this);
    }

    /// <summary>
    /// Gets a collection of type <typeparamref name="Col"/>.
    /// </summary>
    /// <typeparam name="Col">The type of the collection.</typeparam>
    /// <returns>The collection</returns>
    protected Col GetCollection<Col>() where Col : ICollection
    {
        CheckInitialization();
        return (Col)_collections[typeof(Col)];
    }

    private void CheckInitialization()
    {
        if (!_initialized)
        {
            throw new InvalidOperationException(
                "Uninitialized context. DataContext sub-classes must be instantiated using a client's .DataContext() method.");
        }

    }
}
```

## File: Fauna/Linq/DataContextBuilder.cs
```csharp
using System.Diagnostics;
using System.Reflection;
using Fauna.Mapping;
using Fauna.Util.Extensions;

namespace Fauna.Linq;

internal class DataContextBuilder<DB> where DB : DataContext
{
    public DB Build(Client client)
    {
        var dbType = typeof(DB);
        const BindingFlags flags = BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static;
        var colTypes = dbType.GetNestedTypes(flags).Where(IsColType).ToList();
        var colProps = dbType.GetProperties(flags).Where(IsColProp).ToList();

        foreach (var ty in colTypes)
        {
            ValidateColType(ty);
        }

        foreach (var p in colProps)
        {
            ValidateColProp(colTypes, p);
        }

        var colImpls = new Dictionary<Type, DataContext.ICollection>();
        foreach (var ty in colTypes)
        {
            colImpls[ty] = (DataContext.ICollection)Activator.CreateInstance(ty)!;
            var nameAttr = ty.GetCustomAttribute<DataContext.NameAttribute>();
            var colName = nameAttr?.Name ?? ty.Name;
        }

        var db = (DB)Activator.CreateInstance(dbType)!;
        db.Init(client, colImpls, new MappingContext(colImpls.Values));
        return db;
    }

    private static bool IsColType(Type ty) =>
        ty.GetInterfaces().Any(iface => iface == typeof(DataContext.ICollection));

    private static void ValidateColType(Type ty)
    {
        var isGeneric = ty.IsGenericType;
        var colDef = GetColBase(ty);

        var errors = new List<string>();

        if (isGeneric) errors.Add("Cannot be generic.");
        if (colDef is null) errors.Add("Must inherit Collection<>.");

        if (errors.Any())
        {
            throw new InvalidOperationException(
                $"Invalid collection type: {string.Join(" ", errors)}");
        }
    }

    private static bool IsColProp(PropertyInfo prop)
    {
        var getter = prop.GetGetMethod();

        if (getter is null) return false;
        if (getter.IsStatic) return false;

        var retType = getter.ReturnType;
        if (!IsColType(retType)) return false;

        return true;
    }

    private static void ValidateColProp(List<Type> colTypes, PropertyInfo prop)
    {
        var nullCtx = new NullabilityInfoContext();
        var nullInfo = nullCtx.Create(prop);
        var getter = prop.GetGetMethod()!;
        var retType = getter.ReturnType;

        var returnsValidColType = colTypes.Contains(retType);
        var isNullable = nullInfo.ReadState is NullabilityState.Nullable;

        var errors = new List<string>();

        if (!returnsValidColType) errors.Add("Must return a nested collection type.");
        if (isNullable) errors.Add("Cannot be nullable.");

        if (errors.Any())
        {
            throw new InvalidOperationException(
                $"Invalid collection property: {string.Join(" ", errors)}");
        }
    }

    // helpers

    private static Type? GetColBase(Type ty) => ty.GetGenInst(typeof(DataContext.Collection<>));

    private static Type GetDocType(Type ty)
    {
        var col = GetColBase(ty);
        Debug.Assert(col is not null);
        return col.GetGenericArguments()[0];
    }
}
```

## File: Fauna/Linq/Deserializers.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna.Linq;

internal class MappedDeserializer<I, O> : BaseSerializer<O>
{
    private ISerializer<I> _inner;
    private Func<I, O> _mapper;

    public MappedDeserializer(ISerializer<I> inner, Func<I, O> mapper)
    {
        _inner = inner;
        _mapper = mapper;
    }

    public override List<FaunaType> GetSupportedTypes() => _inner.GetSupportedTypes();

    public override O Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        _mapper(_inner.Deserialize(ctx, ref reader));

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        throw new NotImplementedException();
    }
}

internal class ProjectionDeserializer : BaseSerializer<object?[]>
{
    private ISerializer[] _fields;

    public ProjectionDeserializer(IEnumerable<ISerializer> fields)
    {
        _fields = fields.ToArray();
    }

    public override List<FaunaType> GetSupportedTypes() => _fields.SelectMany(x => x.GetSupportedTypes()).Distinct().ToList();

    public override object?[] Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        if (reader.CurrentTokenType != TokenType.StartArray)
            throw UnexpectedToken(reader.CurrentTokenType);

        var values = new object?[_fields.Length];

        for (var i = 0; i < _fields.Length; i++)
        {
            if (!reader.Read()) throw new SerializationException("Unexpected end of stream");
            if (reader.CurrentTokenType == TokenType.EndArray) throw UnexpectedToken(reader.CurrentTokenType);

            values[i] = _fields[i].Deserialize(ctx, ref reader);
        }

        if (!reader.Read()) throw new SerializationException("Unexpected end of stream");
        if (reader.CurrentTokenType != TokenType.EndArray) throw UnexpectedToken(reader.CurrentTokenType);

        return values;
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        throw new NotImplementedException();
    }

    private new static SerializationException UnexpectedToken(TokenType tokenType) =>
        new($"Unexpected token while deserializing LINQ element: {tokenType}");
}
```

## File: Fauna/Linq/IntermediateQueryHelpers.cs
```csharp
namespace Fauna.Linq;

internal static class IntermediateQueryHelpers
{
    public static QueryExpr Expr(string fql) => new(new List<IQueryFragment> { new QueryLiteral(fql) });

    public static QueryVal Const(object? v) => new(v);

    private static readonly Query _larr = Expr("[");
    private static readonly Query _rarr = Expr("]");
    public static Query Array(Query inner) => _larr.Concat(inner).Concat(_rarr);
    public static Query Array(IEnumerable<Query> inners) => Join(inners, _larr, ",", _rarr);

    private static readonly Query _lparen = Expr("(");
    private static readonly Query _rparen = Expr(")");
    public static Query Parens(Query inner) => _lparen.Concat(inner).Concat(_rparen);
    public static Query Parens(IEnumerable<Query> inners) => Join(inners, _lparen, ",", _rparen);

    private static readonly Query _lbrace = Expr("{");
    private static readonly Query _rbrace = Expr("}");
    public static Query Block(Query inner) => _lbrace.Concat(inner).Concat("}");
    public static Query Block(IEnumerable<Query> inners) => Join(inners, _lbrace, ";", _rbrace);
    public static Query Obj(Query inner) => _lbrace.Concat(inner).Concat("}");
    public static Query Obj(IEnumerable<Query> inners) => Join(inners, _lbrace, ",", _rbrace);

    public static Query Op(Query a, string op, Query b) =>
        a.Concat(Expr(op)).Concat(b);

    public static Query FieldAccess(Query callee, string f) =>
        callee.Concat($".{f}");

    public static Query FnCall(string m) =>
        Expr($"{m}()");

    public static Query FnCall(string m, Query arg) =>
        Expr($"{m}(").Concat(arg).Concat(_rparen);

    public static Query FnCall(string m, IEnumerable<Query> args) =>
        Join(args, Expr($"{m}("), ",", _rparen);

    public static Query MethodCall(Query callee, string m) =>
        callee.Concat($".{m}()");

    public static Query MethodCall(Query callee, string m, Query a1) =>
        callee.Concat($".{m}(").Concat(a1).Concat(_rparen);

    public static Query MethodCall(Query callee, string m, Query a1, Query a2) =>
        callee.Concat($".{m}(").Concat(a1).Concat(",").Concat(a2).Concat(_rparen);

    public static Query MethodCall(Query callee, string m, IEnumerable<Query> args) =>
        Join(args, callee.Concat($".{m}("), ",", _rparen);

    public static Query Join(IEnumerable<Query> ies, Query l, string sep, Query r)
    {
        Query ret = l;
        var init = true;
        foreach (var ie in ies)
        {
            if (init) init = false; else ret = ret.Concat(sep);
            ret = ret.Concat(ie);
        }
        ret = ret.Concat(r);
        return ret;
    }

    public static Query CollectionAll(DataContext.ICollection col) =>
        MethodCall(Expr(col.Name), "all");

    public static Query CollectionIndex(DataContext.IIndex idx) =>
        MethodCall(Expr(idx.Collection.Name), idx.Name, idx.Args.Select(Const));

    public static Query Function(string name, object[] args) =>
        FnCall(name, args.Select(Const));

    public static QueryExpr Concat(this Query q1, string str)
    {
        var frags = new List<IQueryFragment>();

        if (q1 is QueryExpr e1)
        {
            if (e1.Fragments.Last() is QueryLiteral l1)
            {
                frags.AddRange(e1.Fragments.SkipLast(1));
                frags.Add(new QueryLiteral(l1.Unwrap + str));
            }
            else
            {
                frags.AddRange(e1.Fragments);
                frags.Add(new QueryLiteral(str));
            }
        }
        else
        {
            frags.Add(q1);
            frags.Add(new QueryLiteral(str));
        }

        return new QueryExpr(frags);
    }

    public static QueryExpr Concat(this Query q1, Query q2)
    {
        var frags = new List<IQueryFragment>();

        if (q1 is QueryExpr e1)
        {
            if (q2 is QueryExpr e2)
            {
                if (e1.Fragments.Last() is QueryLiteral l1 &&
                    e2.Fragments.First() is QueryLiteral l2)
                {
                    frags.AddRange(e1.Fragments.SkipLast(1));
                    frags.Add(new QueryLiteral(l1.Unwrap + l2.Unwrap));
                    frags.AddRange(e2.Fragments.Skip(1));
                }
                else
                {
                    frags.AddRange(e1.Fragments);
                    frags.AddRange(e2.Fragments);
                }
            }
            else
            {
                frags.AddRange(e1.Fragments);
                frags.Add(q2);
            }
        }
        else
        {
            if (q2 is QueryExpr e2)
            {
                frags.Add(q1);
                frags.AddRange(e2.Fragments);
            }
            else
            {
                frags.Add(q1);
                frags.Add(q2);
            }
        }

        return new QueryExpr(frags);
    }
}
```

## File: Fauna/Linq/IQuerySource.cs
```csharp
using System.Linq.Expressions;
using Fauna.Core;
using Fauna.Types;

namespace Fauna.Linq;

/// <summary>
/// An interface for common static IQuerySource methods that are non-generic.
/// </summary>
public interface IQuerySource
{
    // TODO(matt) use an API-specific exception in-line with what other LINQ
    // libraries do.
    internal static Exception Fail(Expression? expr) =>
        Fail($"Unsupported {expr?.NodeType} expression: {expr}");

    internal static Exception Fail(string op, string msg) =>
        Fail($"Unsupported method call `{op}`: {msg}");

    internal static Exception Fail(string msg) => new NotSupportedException(msg);
}

/// <summary>
/// An interface defining the LINQ API for Fauna queries.
/// </summary>
/// <typeparam name="T">The type returned by the query.</typeparam>
public interface IQuerySource<T> : IQuerySource
{
    // Core execution

    /// <summary>
    /// Executes a paginating query asynchronously and returns an enumerable of pages.
    /// </summary>
    /// <param name="queryOptions">An instance of <see cref="QueryOptions"/>.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <returns>An IAsyncEnumerable of type <see cref="Page{T}"/>.</returns>
    public IAsyncEnumerable<Page<T>> PaginateAsync(QueryOptions? queryOptions = null, CancellationToken cancel = default);
    /// <summary>
    /// Executes a query asynchronously.
    /// </summary>
    /// <param name="cancel">A cancellation token.</param>
    /// <returns>An <see cref="IAsyncEnumerable{T}"/>.</returns>
    public IAsyncEnumerable<T> ToAsyncEnumerable(CancellationToken cancel = default);
    /// <summary>
    /// Executes a query.
    /// </summary>
    /// <returns>An <see cref="IEnumerable{T}"/>.</returns>
    public IEnumerable<T> ToEnumerable();

    // Composition methods

    /// <summary>
    /// Obtains a distinct set of results. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> Distinct();
    /// <summary>
    /// Applies default ordering to the query. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> Order();
    /// <summary>
    /// Orders according to the selector. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> OrderBy<K>(Expression<Func<T, K>> keySelector);
    /// <summary>
    /// Orders by descending. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> OrderDescending();
    /// <summary>
    /// Orders by descending according to the selector. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> OrderByDescending<K>(Expression<Func<T, K>> keySelector);
    /// <summary>
    /// Reverses the order of the results. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> Reverse();
    /// <summary>
    /// Applies a projection to the query. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<R> Select<R>(Expression<Func<T, R>> selector);
    // public IQuerySource<R> SelectMany<R>(Expression<Func<T, IQuerySource<R>>> selector);
    /// <summary>
    /// Skips the first N elements of the results. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> Skip(int count);
    // public IQuerySource<R> SelectMany<R>(Expression<Func<T, IQuerySource<R>>> selector);
    /// <summary>
    /// Takes the first N elements of the results. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> Take(int count);
    // public IQuerySource<R> SelectMany<R>(Expression<Func<T, IQuerySource<R>>> selector);
    /// <summary>
    /// Applies the predicate to the query. This is evaluated server-side.
    /// </summary>
    /// <returns>This <see cref="IQuerySource{T}"/> instance.</returns>
    public IQuerySource<T> Where(Expression<Func<T, bool>> predicate);

    // Terminal result methods

    // public R Aggregate<A, R>(A seed, Expression<Func<A, T, A>> accum, Func<A, R> selector);
    // public Task<R> AggregateAsync<A, R>(A seed, Expression<Func<A, T, A>> accum, Func<A, R> selector);

    // // not IQueryable
    // public R Fold<R>(R seed, Expression<Func<R, T, R>> accum);
    // public Task<R> FoldAsync<R>(R seed, Expression<Func<R, T, R>> accum);

    // public IQuerySource<R> SelectMany<R>(Expression<Func<T, IQuerySource<R>>> selector);

    /// <summary>
    /// Applies each predicate and executes the query. This is evaluated server-side.
    /// </summary>
    /// <returns>True if every predicate evaluates to true. Otherwise, false.</returns>
    public bool All(Expression<Func<T, bool>> predicate);

    /// <summary>
    /// Applies each predicate and executes the query asynchronously. This is evaluated server-side.
    /// </summary>
    /// <returns>True if every predicate evaluate to true, otherwise false.</returns>
    public Task<bool> AllAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Determines if the result is not empty. This is evaluated server-side.
    /// </summary>
    /// <returns>True if the result contains any elements, otherwise false.</returns>
    public bool Any();
    /// <summary>
    /// Determines if the result is not empty asynchronously. This is evaluated server-side.
    /// </summary>
    /// <returns>True if the result contains any elements, otherwise false.</returns>
    public Task<bool> AnyAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies each predicate and executes the query. This is evaluated server-side.
    /// </summary>
    /// <returns>True if any predicate evaluates to true, otherwise false.</returns>
    public bool Any(Expression<Func<T, bool>> predicate);


    /// <summary>
    /// Applies each predicate and executes the query asynchronously. This is evaluated server-side.
    /// </summary>
    /// <returns>True if any predicate evaluates to true, otherwise false.</returns>
    public Task<bool> AnyAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Applies a count of the elements and executes the query. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public int Count();
    /// <summary>
    /// Applies a count of the elements and executes the query asynchronously. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public Task<int> CountAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate, applies a count, and executes the query. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public int Count(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate, applies a count, and executes the query asynchronously. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public Task<int> CountAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Executes the query and obtains the first element in the result. This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result.</returns>
    public T First();
    /// <summary>
    /// Executes the query asynchronously and obtains the first element in the result. This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result.</returns>
    public Task<T> FirstAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate, executes the query, and obtains the first element in the result. This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result.</returns>
    public T First(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate, executes the query asynchronously, and obtains the first element in the result.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result.</returns>
    public Task<T> FirstAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Executes the query and obtains the first element in the result
    /// or the default value, if there is no result. This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result or the default value, if there is no result.</returns>
    public T? FirstOrDefault();
    /// <summary>
    /// Executes the query asynchronously and obtains the first element in the result
    /// or the default value, if there is no result. This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result.</returns>
    public Task<T?> FirstOrDefaultAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate, executes the query, and obtains the first element in the result or the
    /// default value, if there is no result. This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result.</returns>
    public T? FirstOrDefault(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate, executes the query asynchronously, and obtains the first element in the result or the
    /// default value, if there is no result. This is evaluated server-side.
    /// </summary>
    /// <returns>The first element in the result.</returns>
    public Task<T?> FirstOrDefaultAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);


    /// <summary>
    /// Executes the query and obtains the last element in the result. This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result.</returns>
    public T Last();
    /// <summary>
    /// Executes the query asynchronously and obtains the last element in the result. This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result.</returns>
    public Task<T> LastAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate, executes the query, and obtains the last element in the result.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result.</returns>
    public T Last(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate, executes the query asynchronously, and obtains the last element in the result.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result.</returns>
    public Task<T> LastAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Executes the query and obtains the last element in the result or the default value, if there is no result.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result or the default value, if there is no result.</returns>
    public T? LastOrDefault();
    /// <summary>
    /// Executes the query asynchronously and obtains the last element in the result or the default value,
    /// if there is no result. This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result or the default value, if there is no result.</returns>
    public Task<T?> LastOrDefaultAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate, executes the query and obtains the last element in the result
    /// or the default value, if there is no result. This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result or the default value, if there is no result.</returns>
    public T? LastOrDefault(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate, executes the query asynchronously and obtains the last element in the result
    /// or the default value, if there is no result. This is evaluated server-side.
    /// </summary>
    /// <returns>The last element in the result or the default value, if there is no result.</returns>
    public Task<T?> LastOrDefaultAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Applies a count of the elements and executes the query. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public long LongCount();
    /// <summary>
    /// Applies a count of the elements and executes the query asynchronously. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public Task<long> LongCountAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate, applies a count, and executes the query. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public long LongCount(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate, applies a count, and executes the query asynchronously. This is evaluated server-side.
    /// </summary>
    /// <returns>The number of elements in the result.</returns>
    public Task<long> LongCountAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);


    /// <summary>
    /// Executes a query and returns the maximum value in the result set. This is evaluated server-side.
    /// <p/>
    /// (a, b) => if (a >= b) a else b
    /// </summary>
    /// <returns>The maximum <typeparamref name="T"/>.</returns>
    public T Max();
    /// <summary>
    /// Executes a query asynchronously and returns the maximum value in the result set. This is evaluated server-side.
    /// <p/>
    /// (a, b) => if (a >= b) a else b
    /// </summary>
    /// <returns>The maximum <typeparamref name="T"/>.</returns>
    public Task<T> MaxAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies a selector, executes a query, and returns the maximum value in the result set. This is evaluated server-side.
    /// <p/>
    /// (a, b) => if (a >= b) a else b
    /// </summary>
    /// <returns>The maximum <typeparamref name="T"/>.</returns>
    public R Max<R>(Expression<Func<T, R>> selector);
    /// <summary>
    /// Applies a selector, executes a query asynchronously, and returns the maximum value in the result set.
    /// This is evaluated server-side.
    /// <p/>
    /// (a, b) =&gt; if (a &gt;= b) a else b
    /// </summary>
    /// <returns>The maximum <typeparamref name="T"/>.</returns>
    public Task<R> MaxAsync<R>(Expression<Func<T, R>> selector, CancellationToken cancel = default);

    // public T MaxBy<K>(Expression<Func<T, K>> selector);
    // public Task<K> MaxByAsync<K>(Expression<Func<T, K>> selector, CancellationToken cancel = default);

    /// <summary>
    /// Executes a query and returns the minimum value in the result set. This is evaluated server-side.
    /// <p/>
    /// (a, b) =&gt; if (a &lt;= b) a else b
    /// </summary>
    /// <returns>The minimum <typeparamref name="T"/>.</returns>
    public T Min();
    /// <summary>
    /// Executes a query asynchronously and returns the minimum value in the result set. This is evaluated server-side.
    /// <p/>
    /// (a, b) =&gt; if (a &lt;= b) a else b
    /// </summary>
    /// <returns>The minimum <typeparamref name="T"/>.</returns>
    public Task<T> MinAsync(CancellationToken cancel = default);

    // public T MinBy<K>(Expression<Func<T, K>> selector);
    // public Task<K> MinByAsync<K>(Expression<Func<T, K>> selector, CancellationToken cancel = default);

    /// <summary>
    /// Applies the selector, executes the query, and returns the minimum value in the result set.
    /// This is evaluated server-side.
    /// <p/>
    /// (a, b) =&gt; if (a &lt;= b) a else b
    /// </summary>
    /// <returns>The minimum <typeparamref name="T"/>.</returns>
    public R Min<R>(Expression<Func<T, R>> selector);
    /// <summary>
    /// Applies the selector, executes the query asynchronously, and returns the minimum value in the result set.
    /// This is evaluated server-side.
    /// <p/>
    /// (a, b) =&gt; if (a &lt;= b) a else b
    /// </summary>
    /// <returns>The minimum <typeparamref name="T"/>.</returns>
    public Task<R> MinAsync<R>(Expression<Func<T, R>> selector, CancellationToken cancel = default);

    /// <summary>
    /// Executes the query. If the result is a single element, returns it. Otherwise, throws an exception.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result.</returns>
    public T Single();
    /// <summary>
    /// Executes the query asynchronously. If the result is a single element, returns it. Otherwise, throws an exception.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result.</returns>
    public Task<T> SingleAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate and executes the query. If the result is a single element, returns it. Otherwise, throws an exception.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result.</returns>
    public T Single(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate and executes the query asynchronously. If the result is a single element, returns it. Otherwise, throws an exception.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result.</returns>
    public Task<T> SingleAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Executes the query. If the result is a single element, returns it. Otherwise, returns the default.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result or default.</returns>
    public T SingleOrDefault();
    /// <summary>
    /// Executes the query asynchronously. If the result is a single element, returns it. Otherwise, returns the default.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result or default.</returns>
    public Task<T> SingleOrDefaultAsync(CancellationToken cancel = default);

    /// <summary>
    /// Applies the predicate and executes the query. If the result is a single element, returns it. Otherwise, returns the default.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result or default.</returns>
    public T SingleOrDefault(Expression<Func<T, bool>> predicate);
    /// <summary>
    /// Applies the predicate and executes the query asynchronously. If the result is a single element, returns it. Otherwise, returns the default.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The query result or default.</returns>
    public Task<T> SingleOrDefaultAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default);

    /// <summary>
    /// Calculates the sum of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The sum of selected values.</returns>
    public int Sum(Expression<Func<T, int>> selector);
    /// <summary>
    /// Asynchronously calculates the sum of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The sum of selected values.</returns>
    public Task<int> SumAsync(Expression<Func<T, int>> selector, CancellationToken cancel = default);

    /// <summary>
    /// Calculates the sum of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The sum of selected values.</returns>
    public long Sum(Expression<Func<T, long>> selector);
    /// <summary>
    /// Asynchronously calculates the sum of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The sum of selected values.</returns>
    public Task<long> SumAsync(Expression<Func<T, long>> selector, CancellationToken cancel = default);

    // public float Sum(Expression<Func<T, float>> selector);
    // public Task<float> SumAsync(Expression<Func<T, float>> selector, CancellationToken cancel = default);

    /// <summary>
    /// Calculates the sum of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The sum of selected values.</returns>
    public double Sum(Expression<Func<T, double>> selector);
    /// <summary>
    /// Asynchronously calculates the sum of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The sum of selected values.</returns>
    public Task<double> SumAsync(Expression<Func<T, double>> selector, CancellationToken cancel = default);

    /// <summary>
    /// Calculates the mean average of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The mean average of selected values.</returns>
    public double Average(Expression<Func<T, double>> selector);
    /// <summary>
    /// Asynchronously calculates the mean average of values returned by a provided selector.
    /// This is evaluated server-side.
    /// </summary>
    /// <returns>The mean average of selected values.</returns>
    public Task<double> AverageAsync(Expression<Func<T, double>> selector, CancellationToken cancel = default);

    // Collection result methods

    /// <summary>
    /// Executes the query and converts the results to a <see cref="List{T}"/>.
    /// </summary>
    /// <returns>A <see cref="List{T}"/>.</returns>
    public List<T> ToList();
    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="List{T}"/>.
    /// </summary>
    /// <returns>A <see cref="List{T}"/>.</returns>
    public Task<List<T>> ToListAsync(CancellationToken cancel = default);

    /// <summary>
    /// Executes the query and converts the results to a <see cref="T:T[]"/>.
    /// </summary>
    /// <returns>A <see cref="T:T[]"/>.</returns>
    public T[] ToArray();
    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="T:T[]"/>.
    /// </summary>
    /// <returns>A <see cref="T:T[]"/>.</returns>
    public Task<T[]> ToArrayAsync(CancellationToken cancel = default);

    /// <summary>
    /// Executes the query and converts the results to a <see cref="HashSet{T}"/>.
    /// </summary>
    /// <returns>A <see cref="HashSet{T}"/>.</returns>
    public HashSet<T> ToHashSet();
    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="HashSet{T}"/>.
    /// </summary>
    /// <returns>A <see cref="HashSet{T}"/>.</returns>
    public Task<HashSet<T>> ToHashSetAsync(CancellationToken cancel = default);


    /// <summary>
    /// Executes the query and converts the results to a <see cref="HashSet{T}"/>.
    /// </summary>
    /// <param name="comparer">A comparer to use.</param>
    /// <returns>A <see cref="HashSet{T}"/>.</returns>
    public HashSet<T> ToHashSet(IEqualityComparer<T>? comparer);

    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="HashSet{T}"/>.
    /// </summary>
    /// <param name="comparer">A comparer to use.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <returns>A <see cref="HashSet{T}"/>.</returns>
    public Task<HashSet<T>> ToHashSetAsync(IEqualityComparer<T>? comparer, CancellationToken cancel = default);

    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as a <see cref="Dictionary{K,V}"/>.</returns>
    public Dictionary<K, V> ToDictionary<K, V>(Func<T, K> getKey, Func<T, V> getValue) where K : notnull;
    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="Dictionary{K,V}"/>.</returns>
    public Task<Dictionary<K, V>> ToDictionaryAsync<K, V>(Func<T, K> getKey, Func<T, V> getValue, CancellationToken cancel = default) where K : notnull;

    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <param name="comparer">A comparer used to compare keys.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as a <see cref="Dictionary{K,V}"/>.</returns>
    public Dictionary<K, V> ToDictionary<K, V>(Func<T, K> getKey, Func<T, V> getValue, IEqualityComparer<K>? comparer) where K : notnull;
    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <param name="comparer">A comparer used to compare keys.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="Dictionary{K,V}"/>.</returns>
    public Task<Dictionary<K, V>> ToDictionaryAsync<K, V>(Func<T, K> getKey, Func<T, V> getValue, IEqualityComparer<K>? comparer, CancellationToken cancel = default) where K : notnull;
}
```

## File: Fauna/Linq/LookupTable.cs
```csharp
using System.Linq.Expressions;
using System.Reflection;
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna.Linq;

// TODO(matt) reconcile/merge this behavior with MappingCtx
internal record struct LookupTable(MappingContext Ctx)
{
    public record class Result(string Name, ISerializer Serializer, Type Type);
    private static Result R(string name, ISerializer ser, Type ty) => new Result(name, ser, ty);

    public Result? FieldLookup(PropertyInfo prop, Expression callee)
    {
        if (Ctx.TryGetBaseType(callee.Type, out var info))
        {
            var field = info.Fields.FirstOrDefault(f => f.Property == prop);
            return field is null ? null : R(field.Name, field.Serializer, field.Type);
        }

        return Table(prop, callee);
    }

    public Result? MethodLookup(MethodInfo method, Expression callee) =>
        Table(method, callee);

    public bool HasField(PropertyInfo prop, Expression callee) =>
        FieldLookup(prop, callee) is not null;

    public bool HasMethod(MethodInfo method, Expression callee) =>
        MethodLookup(method, callee) is not null;


    // built-ins

    private Result? Table(MemberInfo member, Expression callee) =>
        callee.Type.Name switch
        {
            "string" => StringTable(member, callee),
            _ => null,
        };

    private Result? StringTable(MemberInfo member, Expression callee) =>
        member.Name switch
        {
            "Length" => R("length", Serializer.Generate<int>(Ctx), typeof(int)),
            "EndsWith" => R("endsWith", Serializer.Generate<bool>(Ctx), typeof(int)),
            "StartsWith" => R("startsWith", Serializer.Generate<bool>(Ctx), typeof(int)),
            _ => null,
        };
}
```

## File: Fauna/Linq/Pipeline.cs
```csharp
using System.Linq.Expressions;
using Fauna.Serialization;

namespace Fauna.Linq;

/// <summary>
/// The mode of the query pipeline.
/// </summary>
public enum PipelineMode
{
    /// <summary>
    /// When a "pure" query, no local processing is required except deserialization.
    /// </summary>
    Query,
    /// <summary>
    /// When elements have local projection.
    /// </summary>
    Project,
    /// <summary>
    /// When post-processing on the loaded set is required.
    /// </summary>
    SetLoad,
    /// <summary>
    /// When there is a final, non-enum result, no more transformations are allowed.
    /// </summary>
    Scalar,
}

internal readonly record struct Pipeline(
    PipelineMode Mode,
    Query Query,
    Type ElemType,
    bool ElemNullable,
    ISerializer? ElemSerializer,
    LambdaExpression? ProjectExpr)
{
    public IPipelineExecutor GetExec(DataContext ctx)
    {
        var ser = ElemSerializer ??
            (ElemNullable ?
             Serializer.GenerateNullable(ctx.MappingCtx, ElemType) :
             Serializer.Generate(ctx.MappingCtx, ElemType));

        var proj = ProjectExpr?.Compile();

        return IPipelineExecutor.Create(ctx, Query, ser, proj, Mode);
    }
}
```

## File: Fauna/Linq/PipelineExecutor.cs
```csharp
using System.Diagnostics;
using System.Reflection;
using System.Runtime.CompilerServices;
using Fauna.Core;
using Fauna.Serialization;
using Fauna.Types;
using Fauna.Util.Extensions;

namespace Fauna.Linq;

internal interface IPipelineExecutor
{
    private static readonly MethodInfo _createEnumExec =
        typeof(IPipelineExecutor).GetMethod(nameof(CreateEnumExec), BindingFlags.Public | BindingFlags.Static)!;

    private static readonly MethodInfo _createScalarExec =
        typeof(IPipelineExecutor).GetMethod(nameof(CreateScalarExec), BindingFlags.Public | BindingFlags.Static)!;

    Type ElemType { get; }
    Type ResType { get; }

    IAsyncEnumerable<Page<object?>> PagedResult(QueryOptions? queryOptions, CancellationToken cancel = default);
    Task<object?> Result(QueryOptions? queryOptions, CancellationToken cancel = default);

    IAsyncEnumerable<Page<T>> PagedResult<T>(QueryOptions? queryOptions, CancellationToken cancel = default);
    Task<T> Result<T>(QueryOptions? queryOptions, CancellationToken cancel = default);

    public static IPipelineExecutor Create(
        DataContext ctx,
        Query query,
        ISerializer ser,
        Delegate? proj,
        PipelineMode mode)
    {
        Debug.Assert(mode != PipelineMode.SetLoad);

        var innerTy = ser.GetType()
            .GetGenInst(typeof(ISerializer<>))!
            .GetGenericArguments()[0];

        var elemTy = proj is null ?
            innerTy :
            proj.GetType().GetGenInst(typeof(Func<,>))!
            .GetGenericArguments()[1];

        var method = mode switch
        {
            PipelineMode.Query or PipelineMode.Project => _createEnumExec,
            PipelineMode.Scalar => _createScalarExec,
            _ => throw new Exception("unreachable"),
        };

        var typeArgs = new Type[] { innerTy, elemTy };
        var args = new object?[] { ctx, query, ser, proj };
        var exec = method.MakeGenericMethod(typeArgs).Invoke(null, args);

        return (IPipelineExecutor)exec!;
    }

    public static EnumExecutor<E> CreateEnumExec<I, E>(
        DataContext ctx,
        Query query,
        ISerializer<I> ser,
        Func<I, E>? proj) =>
        new EnumExecutor<E>(ctx, query, new PageSerializer<E>(MapSer(ser, proj)));

    public static ScalarExecutor<E> CreateScalarExec<I, E>(
        DataContext ctx,
        Query query,
        ISerializer<I> ser,
        Func<I, E>? proj) =>
        new ScalarExecutor<E>(ctx, query, MapSer(ser, proj));

    private static ISerializer<E> MapSer<I, E>(ISerializer<I> inner, Func<I, E>? proj)
    {
        if (proj is not null)
        {
            return new MappedDeserializer<I, E>(inner, proj);
        }

        Debug.Assert(typeof(I) == typeof(E));
        return (ISerializer<E>)inner;
    }

    public readonly record struct EnumExecutor<E>(
        DataContext Ctx,
        Query Query,
        PageSerializer<E> Ser) : IPipelineExecutor
    {
        public Type ElemType { get => typeof(E); }
        public Type ResType { get => typeof(IEnumerable<E>); }

        public IAsyncEnumerable<Page<T>> PagedResult<T>(QueryOptions? queryOptions, CancellationToken cancel = default)
        {
            var pages = Ctx.PaginateAsyncInternal(Query, Ser, queryOptions, cancel);
            if (pages is IAsyncEnumerable<Page<T>> ret)
            {
                return ret;
            }

            Debug.Assert(typeof(T) == ElemType);
            throw new Exception("unreachable");
        }

        public async Task<T> Result<T>(QueryOptions? queryOptions, CancellationToken cancel = default)
        {
            var pages = PagedResult<E>(queryOptions, cancel);
            var elems = new List<E>();

            if (elems is T res)
            {
                await foreach (var page in pages)
                {
                    cancel.ThrowIfCancellationRequested();
                    elems.AddRange(page.Data);
                }

                return res;
            }

            Debug.Assert(typeof(T) == ResType, $"{typeof(T)} is not {ResType}");
            throw new Exception("unreachable");
        }

        public async IAsyncEnumerable<Page<object?>> PagedResult(QueryOptions? queryOptions, [EnumeratorCancellation] CancellationToken cancel = default)
        {
            await foreach (var page in PagedResult<E>(queryOptions, cancel))
            {
                var data = page.Data.Select(e => (object?)e).ToList();
                yield return new Page<object?>(data, page.After);
            }
        }

        public async Task<object?> Result(QueryOptions? queryOptions, CancellationToken cancel = default) =>
            await Result<IEnumerable<E>>(queryOptions, cancel);
    }


    public readonly record struct ScalarExecutor<E>(
        DataContext Ctx,
        Query Query,
        ISerializer<E> Ser) : IPipelineExecutor
    {
        public Type ElemType { get => typeof(E); }
        public Type ResType { get => typeof(E); }

        public async Task<T> Result<T>(QueryOptions? queryOptions, CancellationToken cancel = default)
        {
            var qres = await Ctx.QueryAsync(Query, Ser, queryOptions, cancel);
            if (qres.Data is T ret)
            {
                return ret;
            }

            if (qres.Data is null)
            {
                return default(T)!;
            }

            Debug.Assert(typeof(T) == ResType, $"{typeof(T)} is not {ResType}");
            throw new Exception("unreachable");
        }

        public async IAsyncEnumerable<Page<T>> PagedResult<T>(QueryOptions? queryOptions, [EnumeratorCancellation] CancellationToken cancel = default)
        {
            if (await Result<E>(queryOptions, cancel) is T ret)
            {
                yield return new Page<T>(new List<T> { ret }, null);
            }

            Debug.Assert(typeof(T) == ElemType);
            throw new Exception("unreachable");
        }

        public async Task<object?> Result(QueryOptions? queryOptions, CancellationToken cancel = default) =>
            await Result<E>(queryOptions, cancel);

        public async IAsyncEnumerable<Page<object?>> PagedResult(QueryOptions? queryOptions, [EnumeratorCancellation] CancellationToken cancel = default)
        {
            yield return new Page<object?>(new List<object?> { await Result(queryOptions, cancel) }, null);
        }
    }
}
```

## File: Fauna/Linq/ProjectionVisitors.cs
```csharp
using System.Diagnostics;
using System.Linq.Expressions;
using System.Reflection;
using Fauna.Mapping;

namespace Fauna.Linq;

internal class ProjectionAnalysisVisitor : ExpressionVisitor
{
    private readonly LookupTable _l;
    private readonly ParameterExpression _param;

    public HashSet<PropertyInfo> Accesses { get; } = new();
    public bool Escapes { get; private set; } = false;

    public ProjectionAnalysisVisitor(MappingContext ctx, ParameterExpression param)
    {
        _l = new LookupTable(ctx);
        _param = param;
    }

    protected override Expression VisitMember(MemberExpression node)
    {
        // FIXME handle chaining
        if (node.Expression == _param &&
            node.Member is PropertyInfo prop &&
            _l.HasField(prop, node.Expression))
        {
            Accesses.Add(prop);
            return node;
        }

        return base.VisitMember(node);
    }

    protected override Expression VisitMethodCall(MethodCallExpression node)
    {
        // FIXME(matt) handle these by checking arg FQL purity
        return base.VisitMethodCall(node);
    }

    protected override Expression VisitParameter(ParameterExpression node)
    {
        if (node == _param)
        {
            Escapes = true;
            return node;
        }

        return base.VisitParameter(node);
    }
}

internal class ProjectionRewriteVisitor : ExpressionVisitor
{
    private readonly ParameterExpression _param;
    private readonly PropertyInfo[] _props;
    private readonly Expression[] _fieldAccesses;

    public ProjectionRewriteVisitor(
        ParameterExpression doc,
        PropertyInfo[] props,
        ParameterExpression projected)
    {
        var accesses = new Expression[props.Length];

        for (var i = 0; i < props.Length; i++)
        {
            accesses[i] = Expression.Convert(
                Expression.ArrayIndex(projected, Expression.Constant(i)),
                props[i].PropertyType);
        }

        _param = doc;
        _props = props;
        _fieldAccesses = accesses;
    }

    protected override Expression VisitMember(MemberExpression node)
    {
        if (node.Expression == _param)
        {
            var prop = node.Member as PropertyInfo;
            var idx = -1;
            Debug.Assert(prop is not null);

            for (var i = 0; idx < 0 && i < _props.Length; i++)
            {
                if (_props[i] == prop)
                {
                    idx = i;
                }
            }

            Debug.Assert(idx >= 0);

            return _fieldAccesses[idx];
        }

        return base.VisitMember(node);
    }
}
```

## File: Fauna/Linq/QuerySource.cs
```csharp
using System.Diagnostics.CodeAnalysis;
using Fauna.Core;
using Fauna.Types;
using Fauna.Util.Extensions;

namespace Fauna.Linq;

/// <summary>
/// An abstract class representing a QuerySource for LINQ-style queries.
/// </summary>
public abstract class QuerySource : IQuerySource
{
    [AllowNull]
    internal DataContext Ctx { get; private protected set; }
    [AllowNull]
    internal Pipeline Pipeline { get; private protected set; }

    internal void SetContext(DataContext ctx)
    {
        Ctx = ctx;
    }

    internal void SetQuery<TElem>(Query query)
    {
        Pipeline = new Pipeline(PipelineMode.Query, query, typeof(TElem), false, null, null);
    }
}

public partial class QuerySource<T> : QuerySource, IQuerySource<T>
{
    internal QuerySource(DataContext ctx, Pipeline pl)
    {
        Ctx = ctx;
        Pipeline = pl;
    }

    // Collection/Index DSLs are allowed to set _expr and _ctx in their own
    // constructors, so they use this base one.
    internal QuerySource() { }

    /// <summary>
    /// Executes a query with pagination.
    /// </summary>
    /// <param name="queryOptions">Query options.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <returns>An async enumerable for page results.</returns>
    public IAsyncEnumerable<Page<T>> PaginateAsync(QueryOptions? queryOptions = null, CancellationToken cancel = default)
    {
        var pe = Pipeline.GetExec(Ctx);
        return pe.PagedResult<T>(queryOptions, cancel);
    }

    /// <summary>
    /// Executes a query asynchronously.
    /// </summary>
    /// <param name="cancel">A cancellation token.</param>
    /// <returns>A enumerable of results.</returns>
    public IAsyncEnumerable<T> ToAsyncEnumerable(CancellationToken cancel = default) =>
        PaginateAsync(cancel: cancel).FlattenAsync();

    /// <summary>
    /// Executes a query.
    /// </summary>
    /// <returns>A enumerable of results.</returns>
    public IEnumerable<T> ToEnumerable() => new QuerySourceEnumerable(this);
}
```

## File: Fauna/Linq/QuerySourceDsl.cs
```csharp
using System.Diagnostics;
using System.Linq.Expressions;
using System.Runtime.CompilerServices;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Serialization;
using Fauna.Util;
using QH = Fauna.Linq.IntermediateQueryHelpers;

namespace Fauna.Linq;

public partial class QuerySource<T>
{
    private Query Query { get => Pipeline.Query; }
    private MappingContext MappingCtx { get => Ctx.MappingCtx; }
    private LookupTable Lookup { get => Ctx.LookupTable; }

    // Composition methods

    /// <inheritdoc />
    public IQuerySource<T> Distinct()
    {
        RequireQueryMode();
        return Chain<T>(q: QH.MethodCall(Query, "distinct"));
    }

    /// <inheritdoc />
    public IQuerySource<T> Order()
    {
        RequireQueryMode();
        return Chain<T>(q: QH.MethodCall(Query, "order"));
    }

    /// <inheritdoc />
    public IQuerySource<T> OrderBy<K>(Expression<Func<T, K>> keySelector)
    {
        RequireQueryMode();
        return Chain<T>(q: QH.MethodCall(Query, "order", SubQuery(keySelector)));
    }

    /// <inheritdoc />
    public IQuerySource<T> OrderByDescending<K>(Expression<Func<T, K>> keySelector)
    {
        RequireQueryMode();
        return Chain<T>(q: QH.MethodCall(Query, "order", QH.FnCall("desc", SubQuery(keySelector))));
    }

    /// <inheritdoc />
    public IQuerySource<T> OrderDescending()
    {
        RequireQueryMode();
        return Chain<T>(q: QH.MethodCall(Query, "order", QH.Expr("desc(x => x)")));
    }

    /// <inheritdoc />
    public IQuerySource<T> Reverse() =>
        Chain<T>(q: QH.MethodCall(Query, "reverse"));

    /// <inheritdoc />
    public IQuerySource<R> Select<R>(Expression<Func<T, R>> selector)
    {
        var pl = SelectCall(Query, selector);
        return new QuerySource<R>(Ctx, pl);
    }

    /// <inheritdoc />
    public IQuerySource<T> Skip(int count) =>
         Chain<T>(q: QH.MethodCall(Query, "drop", QH.Const(count)));

    /// <inheritdoc />
    public IQuerySource<T> Take(int count) =>
         Chain<T>(q: QH.MethodCall(Query, "take", QH.Const(count)));

    /// <inheritdoc />
    public IQuerySource<T> Where(Expression<Func<T, bool>> predicate) =>
        Chain<T>(q: WhereCall(Query, predicate));

    // Terminal result methods

    /// <inheritdoc />
    public bool All(Expression<Func<T, bool>> predicate) => Execute<bool>(AllImpl(predicate));
    /// <inheritdoc />
    public Task<bool> AllAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<bool>(AllImpl(predicate), cancel);
    private Pipeline AllImpl(Expression<Func<T, bool>> predicate)
    {
        RequireQueryMode("All");
        return CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(Query, "every", SubQuery(predicate)),
            ety: typeof(bool));
    }

    /// <inheritdoc />
    public bool Any() => Execute<bool>(AnyImpl(null));
    /// <inheritdoc />
    public Task<bool> AnyAsync(CancellationToken cancel = default) =>
        ExecuteAsync<bool>(AnyImpl(null), cancel);
    /// <inheritdoc />
    public bool Any(Expression<Func<T, bool>> predicate) => Execute<bool>(AnyImpl(predicate));
    /// <inheritdoc />
    public Task<bool> AnyAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<bool>(AnyImpl(predicate), cancel);
    private Pipeline AnyImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(MaybeWhereCall(Query, predicate), "nonEmpty"),
            ety: typeof(bool));

    /// <inheritdoc />
    public int Count() => Execute<int>(CountImpl(null));
    /// <inheritdoc />
    public Task<int> CountAsync(CancellationToken cancel = default) =>
        ExecuteAsync<int>(CountImpl(null), cancel);
    /// <inheritdoc />
    public int Count(Expression<Func<T, bool>> predicate) => Execute<int>(CountImpl(predicate));
    /// <inheritdoc />
    public Task<int> CountAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<int>(CountImpl(predicate), cancel);
    private Pipeline CountImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(MaybeWhereCall(Query, predicate), "count"),
            ety: typeof(int));

    /// <inheritdoc />
    public T First() => Execute<T>(FirstImpl(null));
    /// <inheritdoc />
    public Task<T> FirstAsync(CancellationToken cancel = default) =>
        ExecuteAsync<T>(FirstImpl(null), cancel);
    /// <inheritdoc />
    public T First(Expression<Func<T, bool>> predicate) => Execute<T>(FirstImpl(predicate));
    /// <inheritdoc />
    public Task<T> FirstAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<T>(FirstImpl(predicate), cancel);
    private Pipeline FirstImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(AbortIfEmpty(MaybeWhereCall(Query, predicate)), "first"));

    /// <inheritdoc />
    public T? FirstOrDefault() => Execute<T?>(FirstOrDefaultImpl(null));
    /// <inheritdoc />
    public Task<T?> FirstOrDefaultAsync(CancellationToken cancel = default) =>
        ExecuteAsync<T?>(FirstOrDefaultImpl(null), cancel);
    /// <inheritdoc />
    public T? FirstOrDefault(Expression<Func<T, bool>> predicate) => Execute<T?>(FirstOrDefaultImpl(predicate));
    /// <inheritdoc />
    public Task<T?> FirstOrDefaultAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<T?>(FirstOrDefaultImpl(predicate), cancel);
    private Pipeline FirstOrDefaultImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(MaybeWhereCall(Query, predicate), "first"),
            ety: typeof(T),
            enull: true);

    /// <inheritdoc />
    public T Last() => Execute<T>(LastImpl(null));
    /// <inheritdoc />
    public Task<T> LastAsync(CancellationToken cancel = default) =>
        ExecuteAsync<T>(LastImpl(null), cancel);
    /// <inheritdoc />
    public T Last(Expression<Func<T, bool>> predicate) => Execute<T>(LastImpl(predicate));
    /// <inheritdoc />
    public Task<T> LastAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<T>(LastImpl(predicate), cancel);
    private Pipeline LastImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(AbortIfEmpty(MaybeWhereCall(Query, predicate)), "last"));

    /// <inheritdoc />
    public T? LastOrDefault() => Execute<T?>(LastOrDefaultImpl(null));
    /// <inheritdoc />
    public Task<T?> LastOrDefaultAsync(CancellationToken cancel = default) =>
        ExecuteAsync<T?>(LastOrDefaultImpl(null), cancel);
    /// <inheritdoc />
    public T? LastOrDefault(Expression<Func<T, bool>> predicate) => Execute<T?>(LastOrDefaultImpl(predicate));
    /// <inheritdoc />
    public Task<T?> LastOrDefaultAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<T?>(LastOrDefaultImpl(predicate), cancel);
    private Pipeline LastOrDefaultImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(MaybeWhereCall(Query, predicate), "last"),
            ety: typeof(T),
            enull: true);

    /// <inheritdoc />
    public long LongCount() => Execute<long>(LongCountImpl(null));
    /// <inheritdoc />
    public Task<long> LongCountAsync(CancellationToken cancel = default) =>
        ExecuteAsync<long>(LongCountImpl(null), cancel);
    /// <inheritdoc />
    public long LongCount(Expression<Func<T, bool>> predicate) => Execute<long>(LongCountImpl(predicate));
    /// <inheritdoc />
    public Task<long> LongCountAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<long>(LongCountImpl(predicate), cancel);
    private Pipeline LongCountImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(MaybeWhereCall(Query, predicate), "count"),
            ety: typeof(long));

    private static readonly Query _maxReducer = QH.Expr("(a, b) => if (a >= b) a else b");

    /// <inheritdoc />
    public T Max() => Execute<T>(MaxImpl<T>(null));
    /// <inheritdoc />
    public Task<T> MaxAsync(CancellationToken cancel = default) =>
        ExecuteAsync<T>(MaxImpl<T>(null), cancel);
    /// <inheritdoc />
    public R Max<R>(Expression<Func<T, R>> selector) => Execute<R>(MaxImpl(selector));
    /// <inheritdoc />
    public Task<R> MaxAsync<R>(Expression<Func<T, R>> selector, CancellationToken cancel = default) =>
        ExecuteAsync<R>(MaxImpl(selector), cancel);
    private Pipeline MaxImpl<R>(Expression<Func<T, R>>? selector, [CallerMemberName] string callerName = "")
    {
        RequireQueryMode(callerName);
        return CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(MaybeMap(AbortIfEmpty(Query), selector), "reduce", _maxReducer),
            ety: typeof(R));
    }

    private static readonly Query _minReducer = QH.Expr("(a, b) => if (a <= b) a else b");

    /// <inheritdoc />
    public T Min() => Execute<T>(MinImpl<T>(null));
    /// <inheritdoc />
    public Task<T> MinAsync(CancellationToken cancel = default) => ExecuteAsync<T>(MinImpl<T>(null), cancel);
    /// <inheritdoc />
    public R Min<R>(Expression<Func<T, R>> selector) => Execute<R>(MinImpl(selector));
    /// <inheritdoc />
    public Task<R> MinAsync<R>(Expression<Func<T, R>> selector, CancellationToken cancel = default) =>
        ExecuteAsync<R>(MinImpl(selector), cancel);
    private Pipeline MinImpl<R>(Expression<Func<T, R>>? selector, [CallerMemberName] string callerName = "")
    {
        RequireQueryMode(callerName);
        return CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(MaybeMap(AbortIfEmpty(Query), selector), "reduce", _minReducer),
            ety: typeof(R));
    }

    /// <inheritdoc />
    public double Average(Expression<Func<T, double>> selector) => Execute<double>(AverageImpl(selector));
    /// <inheritdoc />
    public Task<double> AverageAsync(Expression<Func<T, double>> selector, CancellationToken cancel = default) =>
        ExecuteAsync<double>(AverageImpl(selector), cancel);

    private Pipeline AverageImpl<R>(Expression<Func<T, R>> selector)
    {
        RequireQueryMode("Average");

        return CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.FnCall("Math.mean", QH.MethodCall(QH.MethodCall(AbortIfEmpty(Query), "map", SubQuery(selector)), "toArray")),
            ety: typeof(R));
    }

    /// <inheritdoc />
    public T Single() => Execute<T>(SingleImpl(null));
    /// <inheritdoc />
    public Task<T> SingleAsync(CancellationToken cancel = default) => ExecuteAsync<T>(SingleImpl(null), cancel);
    /// <inheritdoc />
    public T Single(Expression<Func<T, bool>> predicate) => Execute<T>(SingleImpl(predicate));
    /// <inheritdoc />
    public Task<T> SingleAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<T>(SingleImpl(predicate), cancel);
    private Pipeline SingleImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(AbortIfEmpty(Singularize(MaybeWhereCall(Query, predicate))), "first"));

    /// <inheritdoc />
    public T SingleOrDefault() => Execute<T>(SingleOrDefaultImpl(null));
    /// <inheritdoc />
    public Task<T> SingleOrDefaultAsync(CancellationToken cancel = default) => ExecuteAsync<T>(SingleOrDefaultImpl(null), cancel);
    /// <inheritdoc />
    public T SingleOrDefault(Expression<Func<T, bool>> predicate) => Execute<T>(SingleOrDefaultImpl(predicate));
    /// <inheritdoc />
    public Task<T> SingleOrDefaultAsync(Expression<Func<T, bool>> predicate, CancellationToken cancel = default) =>
        ExecuteAsync<T>(SingleOrDefaultImpl(predicate), cancel);
    private Pipeline SingleOrDefaultImpl(Expression<Func<T, bool>>? predicate) =>
        CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(Singularize(MaybeWhereCall(Query, predicate)), "first"),
            ety: typeof(T),
            enull: true);

    private static readonly Query _sumReducer = QH.Expr("(a, b) => a + b");

    /// <inheritdoc />
    public int Sum(Expression<Func<T, int>> selector) => Execute<int>(SumImpl<int>(selector));
    /// <inheritdoc />
    public Task<int> SumAsync(Expression<Func<T, int>> selector, CancellationToken cancel = default) =>
        ExecuteAsync<int>(SumImpl<int>(selector), cancel);
    /// <inheritdoc />
    public long Sum(Expression<Func<T, long>> selector) => Execute<long>(SumImpl<long>(selector));
    /// <inheritdoc />
    public Task<long> SumAsync(Expression<Func<T, long>> selector, CancellationToken cancel = default) =>
        ExecuteAsync<long>(SumImpl<long>(selector), cancel);
    /// <inheritdoc />
    public double Sum(Expression<Func<T, double>> selector) => Execute<double>(SumImpl<double>(selector));
    /// <inheritdoc />
    public Task<double> SumAsync(Expression<Func<T, double>> selector, CancellationToken cancel = default) =>
        ExecuteAsync<double>(SumImpl<double>(selector), cancel);
    private Pipeline SumImpl<R>(Expression<Func<T, R>> selector)
    {
        RequireQueryMode("Sum");
        var seed = (typeof(R) == typeof(int) || typeof(R) == typeof(long)) ?
            QH.Expr("0") :
            QH.Expr("0.0");
        var mapped = QH.MethodCall(Query, "map", SubQuery(selector));
        return CopyPipeline(
            mode: PipelineMode.Scalar,
            q: QH.MethodCall(mapped, "fold", seed, _sumReducer),
            ety: typeof(R));
    }

    // helpers

    private void RequireQueryMode([CallerMemberName] string callerName = "")
    {
        if (Pipeline.Mode != PipelineMode.Query)
        {
            throw IQuerySource.Fail(
                callerName,
                $"Query is not pure: Earlier `Select` could not be translated to pure FQL.");
        }
    }

    private R Execute<R>(Pipeline pl)
    {
        try
        {
            var res = ExecuteAsync<R>(pl);
            res.Wait();
            return res.Result;
        }
        catch (AggregateException ex)
        {
            throw TranslateException(ex.InnerExceptions.First());
        }
    }

    private async Task<R> ExecuteAsync<R>(Pipeline pl, CancellationToken cancel = default)
    {
        try
        {
            return await pl.GetExec(Ctx).Result<R>(queryOptions: null, cancel: cancel);
        }
        catch (AggregateException ex)
        {
            throw TranslateException(ex.InnerExceptions.First());
        }
    }

    private QuerySource<R> Chain<R>(
        PipelineMode? mode = null,
        Query? q = null,
        ISerializer? ser = null,
        Type? ety = null,
        bool enull = false,
        LambdaExpression? proj = null) =>
        new QuerySource<R>(Ctx, CopyPipeline(mode, q, ser, ety, enull, proj));

    private Pipeline CopyPipeline(
        PipelineMode? mode = null,
        Query? q = null,
        ISerializer? ser = null,
        Type? ety = null,
        bool enull = false,
        LambdaExpression? proj = null)
    {
        if (ser is not null) Debug.Assert(ety is not null);

        var mode0 = mode ?? Pipeline.Mode;
        var q0 = q ?? Pipeline.Query;

        // if ety is not null, reset ser and proj if not provided.
        var (ety0, enull0, ser0, proj0) = ety is not null ?
            (ety, enull, ser, proj) :
            (Pipeline.ElemType,
             Pipeline.ElemNullable,
             Pipeline.ElemSerializer,
             proj ?? Pipeline.ProjectExpr);

        return new Pipeline(mode0, q0, ety0, enull0, ser0, proj0);
    }

    // There is a bug in abort data deserialization if the abort
    // value is a string. Work around it by using an array.
    // FIXME(matt) remove workaround and use a string
    private Query AbortIfEmpty(Query setq) =>
        QH.Expr(@"({ let s = (").Concat(setq).Concat(@")
            if (s.isEmpty()) abort(['empty'])
            s
        })");

    private Query Singularize(Query setq) =>
        QH.Expr(@"({
          let s = (").Concat(setq).Concat(@")
          let s = if (s isa Set) s.toArray() else s
          if (s isa Array) {
            if (s.length > 1) abort(['not single'])
            s.take(1)
          } else {
            [s]
          }
        })");

    private Exception TranslateException(Exception ex) =>
        ex switch
        {
            AbortException aex =>
                aex.GetData<List<string>>()?.First() switch
                {
                    "empty" => new InvalidOperationException("Empty set"),
                    "not single" => new InvalidOperationException("Set contains more than one element"),
                    _ => aex,
                },
            _ => ex
        };

    private Query MaybeWhereCall(Query callee, Expression? predicate, [CallerMemberName] string callerName = "") =>
        predicate is null ? callee : WhereCall(callee, predicate, callerName);

    private Query MaybeMap(Query setq, Expression? selector) =>
        selector is null ? setq : QH.MethodCall(setq, "map", SubQuery(selector));

    private Query SubQuery(Expression expr) =>
        new SubQuerySwitch(Ctx.LookupTable).Apply(expr);

    private Query WhereCall(Query callee, Expression predicate, [CallerMemberName] string callerName = "")
    {
        RequireQueryMode(callerName);
        return QH.MethodCall(callee, "where", SubQuery(predicate));
    }

    private Pipeline SelectCall(Query callee, Expression proj, [CallerMemberName] string callerName = "")
    {
        var lambda = Expressions.UnwrapLambda(proj);
        Debug.Assert(lambda is not null, $"lambda is {proj.NodeType}");
        Debug.Assert(lambda.Parameters.Count() == 1);

        // there is already a projection wired up, so tack on to its mapping lambda
        if (Pipeline.Mode == PipelineMode.Project)
        {
            Debug.Assert(Pipeline.ProjectExpr is not null);
            var prev = Pipeline.ProjectExpr;
            var pbody = Expression.Invoke(lambda, new Expression[] { prev.Body });
            var plambda = Expression.Lambda(pbody, prev.Parameters);

            return CopyPipeline(proj: plambda);
        }

        Debug.Assert(Pipeline.Mode == PipelineMode.Query);

        var lparam = lambda.Parameters.First()!;
        var analysis = new ProjectionAnalysisVisitor(MappingCtx, lparam);
        analysis.Visit(lambda.Body);

        // select is a simple field access which we can translate directly to FQL.
        // TODO(matt) translate more cases to pure FQL
        if (lambda.Body is MemberExpression mexpr && mexpr.Expression == lparam)
        {
            Debug.Assert(!analysis.Escapes);
            var info = MappingCtx.GetInfo(lparam.Type);
            var access = analysis.Accesses.First();
            var field = Lookup.FieldLookup(access, lparam);
            Debug.Assert(field is not null);

            return CopyPipeline(
                q: QH.MethodCall(callee, "map", QH.Expr($".{field.Name}")),
                ser: field.Serializer,
                ety: field.Type);
        }

        if (analysis.Escapes)
        {
            return CopyPipeline(mode: PipelineMode.Project, proj: lambda);
        }
        else
        {
            var accesses = analysis.Accesses.OrderBy(f => f.Name).ToArray();
            var fields = accesses.Select(a => Lookup.FieldLookup(a, lparam)!);

            // projection query fragment
            var accs = fields.Select(f => QH.Expr($"x.{f.Name}"));
            var pquery = QH.Expr("x => ").Concat(QH.Array(accs));

            // projected field deserializer
            var deser = new ProjectionDeserializer(fields.Select(f => f.Serializer));
            var ety = typeof(object?[]);

            // build mapping lambda expression
            var pparam = Expression.Parameter(typeof(object?[]), "x");
            var rewriter = new ProjectionRewriteVisitor(lparam, accesses, pparam);
            var pbody = rewriter.Visit(lambda.Body);
            var plambda = Expression.Lambda(pbody, pparam);

            return CopyPipeline(
                q: QH.MethodCall(callee, "map", pquery),
                mode: PipelineMode.Project,
                ser: deser,
                ety: ety,
                proj: plambda);
        }
    }
}
```

## File: Fauna/Linq/QuerySourceExtensions.cs
```csharp
namespace Fauna.Linq;

internal static class QuerySourceExtensions
{
    public static Dictionary<K, V> ToDictionary<K, V>(this IQuerySource<ValueTuple<K, V>> src) where K : notnull =>
        src.ToDictionary(t => t.Item1, t => t.Item2);
    public static Task<Dictionary<K, V>> ToDictionaryAsync<K, V>(this IQuerySource<ValueTuple<K, V>> src, CancellationToken cancel = default) where K : notnull =>
        src.ToDictionaryAsync(t => t.Item1, t => t.Item2, cancel);

    public static Dictionary<K, V> ToDictionary<K, V>(this IQuerySource<ValueTuple<K, V>> src, IEqualityComparer<K>? comparer) where K : notnull =>
        src.ToDictionary(t => t.Item1, t => t.Item2, comparer);
    public static Task<Dictionary<K, V>> ToDictionaryAsync<K, V>(this IQuerySource<ValueTuple<K, V>> src, IEqualityComparer<K>? comparer, CancellationToken cancel = default) where K : notnull =>
        src.ToDictionaryAsync(t => t.Item1, t => t.Item2, comparer, cancel);

    public static int Sum(this IQuerySource<int> src) => src.Sum(x => x);
    public static Task<int> SumAsync(this IQuerySource<int> src, CancellationToken cancel = default) =>
        src.SumAsync(x => x, cancel);

    public static long Sum(this IQuerySource<long> src) => src.Sum(x => x);
    public static Task<long> SumAsync(this IQuerySource<long> src, CancellationToken cancel = default) =>
        src.SumAsync(x => x, cancel);

    public static double Sum(this IQuerySource<double> src) => src.Sum(x => x);
    public static Task<double> SumAsync(this IQuerySource<double> src, CancellationToken cancel = default) =>
        src.SumAsync(x => x, cancel);

    public static double Average(this IQuerySource<double> src) => src.Average(x => x);
    public static Task<double> AverageAsync(this IQuerySource<double> src, CancellationToken cancel = default) =>
        src.AverageAsync(x => x, cancel);
}
```

## File: Fauna/Linq/QuerySourceToCollections.cs
```csharp
using System.Collections;

namespace Fauna.Linq;

/// <summary>
/// Represents a Fauna query with a LINQ-style API.
/// </summary>
/// <typeparam name="T">The type returned by the query when evaluated.</typeparam>
public partial class QuerySource<T>
{
    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="List{T}"/>.
    /// </summary>
    /// <returns>The query result as a <see cref="List{T}"/>.</returns>
    public List<T> ToList() => ToEnumerable().ToList();

    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="List{T}"/>.
    /// </summary>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="List{T}"/>.</returns>
    public async Task<List<T>> ToListAsync(CancellationToken cancel = default)
    {
        var ret = new List<T>();
        await foreach (var e in ToAsyncEnumerable(cancel)) ret.Add(e);
        return ret;
    }

    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="T:T[]"/>.
    /// </summary>
    /// <returns>The query result as <see cref="T:T[]"/>.</returns>
    public T[] ToArray() => ToEnumerable().ToArray();

    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="T:T[]"/>.
    /// </summary>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="T:T[]"/>.</returns>
    public async Task<T[]> ToArrayAsync(CancellationToken cancel = default) =>
        (await ToListAsync(cancel)).ToArray();

    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="HashSet{T}"/>.
    /// </summary>
    /// <returns>The query result as a <see cref="HashSet{T}"/>.</returns>
    public HashSet<T> ToHashSet() => ToHashSet(null);

    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="HashSet{T}"/>.
    /// </summary>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="HashSet{T}"/>.</returns>
    public Task<HashSet<T>> ToHashSetAsync(CancellationToken cancel = default) =>
        ToHashSetAsync(null, cancel);

    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="HashSet{T}"/> using a comparer.
    /// </summary>
    /// <param name="comparer">The comparer to use.</param>
    /// <returns>The query result as a <see cref="HashSet{T}"/>.</returns>
    public HashSet<T> ToHashSet(IEqualityComparer<T>? comparer) => ToEnumerable().ToHashSet(comparer);

    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="HashSet{T}"/>.
    /// </summary>
    /// <param name="comparer">The comparer to use.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="HashSet{T}"/>.</returns>
    public async Task<HashSet<T>> ToHashSetAsync(IEqualityComparer<T>? comparer, CancellationToken cancel = default)
    {
        var ret = new HashSet<T>(comparer);
        await foreach (var e in ToAsyncEnumerable(cancel)) ret.Add(e);
        return ret;
    }

    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as a <see cref="Dictionary{K,V}"/>.</returns>
    public Dictionary<K, V> ToDictionary<K, V>(Func<T, K> getKey, Func<T, V> getValue) where K : notnull =>
        ToDictionary(getKey, getValue, null);

    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="Dictionary{K,V}"/>.</returns>
    public Task<Dictionary<K, V>> ToDictionaryAsync<K, V>(Func<T, K> getKey, Func<T, V> getValue, CancellationToken cancel = default) where K : notnull =>
        ToDictionaryAsync(getKey, getValue, null, cancel);

    /// <summary>
    /// Executes the query synchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <param name="comparer">A comparer used to compare keys.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as a <see cref="Dictionary{K,V}"/>.</returns>
    public Dictionary<K, V> ToDictionary<K, V>(Func<T, K> getKey, Func<T, V> getValue, IEqualityComparer<K>? comparer) where K : notnull =>
        ToEnumerable().ToDictionary(getKey, getValue, comparer);

    /// <summary>
    /// Executes the query asynchronously and converts the results to a <see cref="Dictionary{K,V}"/>.
    /// </summary>
    /// <param name="getKey">A function used to obtain a key.</param>
    /// <param name="getValue">A function used to obtain a value.</param>
    /// <param name="comparer">A comparer used to compare keys.</param>
    /// <param name="cancel">A cancellation token.</param>
    /// <typeparam name="K">The key type of the dictionary.</typeparam>
    /// <typeparam name="V">The value type of the dictionary.</typeparam>
    /// <returns>The query result as an awaitable <see cref="Task"/> of <see cref="Dictionary{K,V}"/>.</returns>
    public async Task<Dictionary<K, V>> ToDictionaryAsync<K, V>(Func<T, K> getKey, Func<T, V> getValue, IEqualityComparer<K>? comparer, CancellationToken cancel = default) where K : notnull
    {
        var ret = new Dictionary<K, V>(comparer);
        await foreach (var e in ToAsyncEnumerable(cancel)) ret[getKey(e)] = getValue(e);
        return ret;
    }

    /// <summary>
    /// A struct to treat a <see cref="QuerySource{T}"/> as enumerable.
    /// </summary>
    /// <param name="Source"></param>
    public record struct QuerySourceEnumerable(QuerySource<T> Source) : IEnumerable<T>
    {
        /// <summary>
        /// Gets an enumerator for the wrapped <see cref="QuerySource{T}"/>.
        /// </summary>
        /// <returns>An enumerator.</returns>
        public IEnumerator<T> GetEnumerator()
        {
            var pe = Source.PaginateAsync().GetAsyncEnumerator();
            try
            {
                var mv = pe.MoveNextAsync().AsTask();
                mv.Wait();
                while (mv.Result)
                {
                    var page = pe.Current;

                    foreach (var e in page.Data)
                    {
                        yield return e;
                    }

                    mv = pe.MoveNextAsync().AsTask();
                    mv.Wait();
                }
            }
            finally { pe.DisposeAsync(); }
        }

        IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
    }
}
```

## File: Fauna/Linq/SubQuerySwitch.cs
```csharp
using System.Linq.Expressions;
using System.Reflection;
using Fauna.Util;
using Fauna.Util.Extensions;
using QH = Fauna.Linq.IntermediateQueryHelpers;

namespace Fauna.Linq;

internal class SubQuerySwitch : DefaultExpressionSwitch<Query>
{
    private readonly LookupTable _lookup;

    public SubQuerySwitch(LookupTable lookup)
    {
        _lookup = lookup;
    }

    protected override Query ApplyDefault(Expression? expr) =>
        throw IQuerySource.Fail(expr);

    protected override Query ConstantExpr(ConstantExpression expr)
    {
        return expr.Value switch
        {
            DataContext.ICollection col => QH.CollectionAll(col),
            DataContext.IIndex idx => QH.CollectionIndex(idx),
            _ => QH.Const(expr.Value)
        };
    }

    protected override Query LambdaExpr(LambdaExpression expr)
    {
        var ps = expr.Parameters;
        var pinner = string.Join(", ", ps.Select(p => p.Name));
        var param = ps.Count() == 1 ? pinner : $"({pinner})";
        var arrow = QH.Expr($"{param} =>");

        return arrow.Concat(QH.Parens(Apply(expr.Body)));
    }

    protected override Query ParameterExpr(ParameterExpression expr) => QH.Expr(expr.Name!);

    protected override Query BinaryExpr(BinaryExpression expr)
    {
        var op = expr.NodeType switch
        {
            ExpressionType.Add => "+",
            ExpressionType.AddChecked => "+",
            ExpressionType.And => "&", // bitwise
            ExpressionType.AndAlso => "&&", // boolean
                                            // ExpressionType.ArrayIndex => ,
            ExpressionType.Coalesce => "??",
            ExpressionType.Divide => "/",
            ExpressionType.Equal => "==",
            ExpressionType.ExclusiveOr => "^",
            ExpressionType.GreaterThan => ">",
            ExpressionType.GreaterThanOrEqual => ">=",
            ExpressionType.LeftShift => "<<",
            ExpressionType.LessThan => "<",
            ExpressionType.LessThanOrEqual => "<=",
            ExpressionType.Modulo => "%",
            ExpressionType.Multiply => "*",
            ExpressionType.MultiplyChecked => "*",
            ExpressionType.NotEqual => "!=",
            ExpressionType.Or => "|", // bitwise
            ExpressionType.OrElse => "||", // boolean
            ExpressionType.Power => "**",
            ExpressionType.RightShift => ">>",
            ExpressionType.Subtract => "-",
            ExpressionType.SubtractChecked => "-",
            _ => throw IQuerySource.Fail(expr)
        };

        var lhs = Apply(expr.Left);
        var rhs = Apply(expr.Right);

        return QH.Parens(QH.Op(lhs, op, rhs));
    }

    protected override Query CallExpr(MethodCallExpression expr)
    {
        var (callee, args, ext) = Expressions.GetCalleeAndArgs(expr);
        var name = _lookup.MethodLookup(expr.Method, callee)?.Name;
        if (name is null) throw IQuerySource.Fail(expr);
        return QH.MethodCall(Apply(callee), name, ApplyAll(args));
    }

    protected override Query MemberAccessExpr(MemberExpression expr)
    {
        var callee = expr.Expression;
        if (callee is null)
        {
            var val = Expression.Lambda(expr).Compile().DynamicInvoke();
            return QH.Const(val);
        }
        else if (callee.Type.IsClosureType())
        {
            var val = Expression.Lambda(expr).Compile().DynamicInvoke();
            return QH.Const(val);
        }

        switch (Apply(callee))
        {
            case QueryVal v:
                var c = Expression.Constant(v.Unwrap);
                var access = Expression.PropertyOrField(c, expr.Member.Name);
                var val = Expression.Lambda(access).Compile().DynamicInvoke();
                return QH.Const(val);

            case var q:
                var name = expr.Member is PropertyInfo prop ?
                    _lookup.FieldLookup(prop, callee)?.Name :
                    null;

                if (name is null) throw IQuerySource.Fail(expr);
                return QH.FieldAccess(q, name);
        }
    }
}
```

## File: Fauna/Mapping/Attributes.cs
```csharp
namespace Fauna.Mapping;


/// <summary>
/// Attribute used to indicate that a class represents a Fauna document or struct.
/// </summary>
[AttributeUsage(AttributeTargets.Class)]
[Obsolete("Object attribute is no longer used and will not influence serialization.")]
public class ObjectAttribute : Attribute
{
}

/// <summary>
/// Attribute used to indicate that a field should be ignored during serialization and deserialization.
/// </summary>
[AttributeUsage(AttributeTargets.Property)]
public class IgnoreAttribute : Attribute
{
    /// <summary>
    /// Initializes an instance of an <see cref="IgnoreAttribute"/>.
    /// </summary>
    public IgnoreAttribute() { }

}

/// <summary>
/// An abstract type for attributing user-defined document classes.
/// </summary>
public abstract class BaseFieldAttribute : Attribute
{
    /// <summary>
    /// The name of the field.
    /// </summary>
    public readonly string? Name;
    /// <summary>
    /// The type of the field.
    /// </summary>
    public readonly FieldType Type;

    internal BaseFieldAttribute(string? name, FieldType type)
    {
        Name = name;
        Type = type;
    }
}

/// <summary>
/// Attribute used to specify fields on a Fauna document or struct.
/// </summary>
[AttributeUsage(AttributeTargets.Property)]
public class FieldAttribute : BaseFieldAttribute
{
    /// <summary>
    /// Initializes a <see cref="FieldAttribute"/> of type Field with no name override. The name is inferred.
    /// </summary>
    public FieldAttribute() : base(null, FieldType.Field) { }

    /// <summary>
    /// Initializes a <see cref="FieldAttribute"/> of type Field with a name.
    /// </summary>
    /// <param name="name">The name of the field as stored in Fauna.</param>
    public FieldAttribute(string name) : base(name, FieldType.Field) { }
}

/// <summary>
/// Attribute used to specify the id field on a Fauna document. The associated field will be ignored during
/// serialization unless isClientGenerated is set to true.
/// </summary>
[AttributeUsage(AttributeTargets.Property)]
public class IdAttribute : BaseFieldAttribute
{
    private const string FieldName = "id";

    /// <summary>
    /// Initializes a <see cref="IdAttribute"/>, indicating Fauna will generate the ID.
    /// </summary>
    public IdAttribute() : base(FieldName, FieldType.ServerGeneratedId) { }


    /// <summary>
    /// Initializes a <see cref="IdAttribute"/>.
    /// </summary>
    /// <param name="isClientGenerated">Whether the ID should be considered client-generated or not.</param>
    public IdAttribute(bool isClientGenerated)
        : base(FieldName, isClientGenerated ? FieldType.ClientGeneratedId : FieldType.ServerGeneratedId) { }
}

/// <summary>
/// Attribute used to specify the coll (Collection) field on a Fauna document. The associated field will be ignored
/// during serialization.
/// </summary>
[AttributeUsage(AttributeTargets.Property)]
public class CollectionAttribute : BaseFieldAttribute
{
    private const string FieldName = "coll";

    /// <summary>
    /// Initializes a <see cref="CollectionAttribute"/>. The Fauna field name will always be `coll` for this attribute.
    /// </summary>
    public CollectionAttribute() : base(FieldName, FieldType.Coll) { }

}

/// <summary>
/// Attribute used to specify the ts field on a Fauna document. The associated field will be ignored during
/// serialization.
/// </summary>
[AttributeUsage(AttributeTargets.Property)]
public class TsAttribute : BaseFieldAttribute
{
    private const string FieldName = "ts";

    /// <summary>
    /// Initializes a <see cref="TsAttribute"/>. The Fauna field name will always be `ts` for this attribute.
    /// </summary>
    public TsAttribute() : base(FieldName, FieldType.Ts) { }
}
```

## File: Fauna/Mapping/FieldInfo.cs
```csharp
using System.Reflection;
using Fauna.Serialization;

namespace Fauna.Mapping;

/// <summary>
/// A class that encapsulates the field mapping, serialization, and deserialization of a particular field in Fauna.
/// </summary>
public sealed class FieldInfo
{
    /// <summary>
    /// The name of the field.
    /// </summary>
    public string Name { get; }
    /// <summary>
    /// The property info of an associated class.
    /// </summary>
    public PropertyInfo Property { get; }

    /// <summary>
    /// The <see cref="FieldType"/> for the particular property.
    /// </summary>
    public FieldType FieldType { get; }

    /// <summary>
    /// The <see cref="Type"/> that the field should deserialize into.
    /// </summary>
    public Type Type { get; }
    /// <summary>
    /// Whether the field is nullable.
    /// </summary>
    public bool IsNullable { get; }

    private MappingContext _ctx;
    private ISerializer? _serializer;

    internal FieldInfo(MappingContext ctx, BaseFieldAttribute attr, PropertyInfo prop)
    {
        var nullCtx = new NullabilityInfoContext();
        var nullInfo = nullCtx.Create(prop);

        Name = attr.Name ?? FieldName.Canonical(prop.Name);
        FieldType = attr.Type;
        Property = prop;
        Type = prop.PropertyType;
        IsNullable = nullInfo.WriteState is NullabilityState.Nullable;
        _ctx = ctx;
    }

    internal ISerializer Serializer
    {
        get
        {
            lock (_ctx)
            {
                if (_serializer is null)
                {
                    _serializer = Serialization.Serializer.Generate(_ctx, Type);
                    if (IsNullable && (!_serializer.GetType().IsGenericType ||
                                       (_serializer.GetType().IsGenericType &&
                                        _serializer.GetType().GetGenericTypeDefinition() !=
                                        typeof(NullableStructSerializer<>))))
                    {
                        var serType = typeof(NullableSerializer<>).MakeGenericType(new[] { Type });
                        var ser = Activator.CreateInstance(serType, new[] { _serializer });
                        _serializer = (ISerializer)ser!;
                    }
                }

                return _serializer;
            }
        }
    }
}
```

## File: Fauna/Mapping/FieldName.cs
```csharp
namespace Fauna.Mapping;

/// <summary>
/// A class of utilities for field names.
/// </summary>
public static class FieldName
{
    /// <summary>
    /// The canonical representation of a field name in Faun. C# properties are capitalized whereas Fauna fields are not by convention.
    /// </summary>
    /// <param name="name">The field name.</param>
    /// <returns>The canonical name for the field in Fauna.</returns>
    public static string Canonical(string name) =>
        (string.IsNullOrEmpty(name) || char.IsLower(name[0])) ?
            name :
            string.Concat(name[0].ToString().ToLower(), name.AsSpan(1));
}
```

## File: Fauna/Mapping/FieldType.cs
```csharp
namespace Fauna.Mapping;

/// <summary>
/// An enum for the field type, used with concrete implementations of <see cref="BaseFieldAttribute"/>.
/// </summary>
public enum FieldType
{
    /// <summary>
    /// Indicates the document ID is client-generated.
    /// </summary>
    ClientGeneratedId,

    /// <summary>
    /// Indicates the document ID is Fauna-generated.
    /// </summary>
    ServerGeneratedId,

    /// <summary>
    /// Indicates the field is the coll (collection) field of the document.
    /// </summary>
    Coll,

    /// <summary>
    /// Indicates the field is the ts field of the document.
    /// </summary>
    Ts,

    /// <summary>
    /// Indicates the field contains user-defined data for the document.
    /// </summary>
    Field
}
```

## File: Fauna/Mapping/MappingContext.cs
```csharp
using System.Diagnostics.CodeAnalysis;
using Fauna.Linq;

namespace Fauna.Mapping;

/// <summary>
/// A class representing the mapping context to be used during serialization and deserialization.
/// </summary>
public sealed class MappingContext
{
    // FIXME(matt) possibly replace with more efficient cache impl
    private readonly Dictionary<Type, MappingInfo> _cache = new();
    private readonly Dictionary<string, MappingInfo> _collections = new();
    private readonly Dictionary<Type, MappingInfo> _baseTypes = new();

    /// <summary>
    /// Initializes an empty <see cref="MappingContext"/>.
    /// </summary>
    public MappingContext() { }

    /// <summary>
    /// Initializes a <see cref="MappingContext"/> with associated collections.
    /// </summary>
    /// <param name="collections">The collections to associate.</param>
    public MappingContext(IEnumerable<DataContext.ICollection> collections)
    {
        foreach (var col in collections)
        {
            var info = GetInfo(col.DocType, col.Name);
            _collections[col.Name] = info;
            _baseTypes[col.DocType] = info;
        }
    }

    /// <summary>
    /// Initializes a <see cref="MappingContext"/> with associated collections.
    /// </summary>
    /// <param name="collections">The collections to associate.</param>
    public MappingContext(Dictionary<string, Type> collections)
    {
        foreach ((string name, Type ty) in collections)
        {
            _collections[name] = GetInfo(ty, name);
        }
    }

    /// <summary>
    /// Gets the <see cref="MappingInfo"/> for a given collection name.
    /// </summary>
    /// <param name="col">The collection name to get.</param>
    /// <param name="ret">When this method returns, contains the <see cref="MappingInfo"/> associated with the collection if found; otherwise, <c>null</c>. This parameter is passed uninitialized.</param>
    /// <returns><c>true</c> if the <see cref="MappingContext"/> contains <see cref="MappingInfo"/> for the specified collection; otherwise, <c>false</c>.</returns>
    public bool TryGetCollection(string col, [NotNullWhen(true)] out MappingInfo? ret)
    {
        return _collections.TryGetValue(col, out ret);
    }

    /// <summary>
    /// Gets the <see cref="MappingInfo"/> for a given <see cref="Type"/>.
    /// </summary>
    /// <param name="ty">The type to get.</param>
    /// <param name="ret">When this method returns, contains the <see cref="MappingInfo"/> associated with the type if found; otherwise, <c>null</c>. This parameter is passed uninitialized.</param>
    /// <returns><c>true</c> if the <see cref="MappingContext"/> contains <see cref="MappingInfo"/> for the specified type; otherwise, <c>false</c>.</returns>
    public bool TryGetBaseType(Type ty, [NotNullWhen(true)] out MappingInfo? ret)
    {
        return _baseTypes.TryGetValue(ty, out ret);
    }

    /// <summary>
    /// Gets the <see cref="MappingInfo"/> for a given <see cref="Type"/>.
    /// </summary>
    /// <param name="ty">The type to get.</param>
    /// <param name="colName">The associated collection name, if any</param>
    /// <returns></returns>
    public MappingInfo GetInfo(Type ty, string? colName = null)
    {
        lock (this)
        {
            if (_cache.TryGetValue(ty, out var ret))
            {
                return ret;
            }
        }

        // MappingInfo caches itself during construction in order to make
        // itself available early for recursive lookup.
        return new MappingInfo(this, ty, colName);
    }

    internal void Add(Type ty, MappingInfo info)
    {
        lock (this)
        {
            _cache[ty] = info;
        }
    }
}
```

## File: Fauna/Mapping/MappingInfo.cs
```csharp
using System.Collections.Immutable;
using System.Reflection;
using Fauna.Serialization;
using Module = Fauna.Types.Module;

namespace Fauna.Mapping;

/// <summary>
/// A class that encapsulates the class mapping, serialization, and deserialization of a Fauna object, including documents.
/// </summary>
public sealed class MappingInfo
{
    /// <summary>
    /// The associated type.
    /// </summary>
    public Type Type { get; }
    /// <summary>
    /// A read-only list of <see cref="FieldInfo"/> representing the object.
    /// </summary>
    public IReadOnlyList<FieldInfo> Fields { get; }
    /// <summary>
    /// A read-only dictionary of <see cref="FieldInfo"/> representing the object.
    /// </summary>
    public IReadOnlyDictionary<string, FieldInfo> FieldsByName { get; }

    internal bool ShouldEscapeObject { get; }
    internal ISerializer ClassSerializer { get; }
    internal Module? Collection { get; }

    internal MappingInfo(MappingContext ctx, Type ty, string? colName = null)
    {
        ctx.Add(ty, this);
        Type = ty;
        Collection = colName != null ? new Module(colName) : null;

        var fields = new List<FieldInfo>();
        var byName = new Dictionary<string, FieldInfo>();

        foreach (var prop in ty.GetProperties())
        {
            if (prop.GetCustomAttribute<IgnoreAttribute>() != null) continue;

            var attr = prop.GetCustomAttribute<BaseFieldAttribute>() ?? new FieldAttribute();
            var info = new FieldInfo(ctx, attr, prop);

            if (byName.ContainsKey(info.Name))
                throw new ArgumentException($"Duplicate field name {info.Name} in {ty}");

            fields.Add(info);
            byName[info.Name] = info;
        }

        ShouldEscapeObject = Serializer.Tags.Overlaps(byName.Values.Select(i => i.Name));
        Fields = fields.ToImmutableList();
        FieldsByName = byName.ToImmutableDictionary();

        var serType = typeof(ClassSerializer<>).MakeGenericType(new[] { ty });
        ClassSerializer = (ISerializer)Activator.CreateInstance(serType, this)!;
    }
}
```

## File: Fauna/Properties/AssemblyInfo.cs
```csharp
using System.Runtime.CompilerServices;

#if DEBUG
[assembly: InternalsVisibleTo("Fauna.Test")]
#endif
```

## File: Fauna/Query/IQueryFragment.cs
```csharp
using System.Text;
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna;

/// <summary>
/// Represents the base interface for a query fragment used for FQL query construction.
/// </summary>
public interface IQueryFragment
{
    /// <summary>
    /// Serializes the query fragment into the provided stream.
    /// </summary>
    /// <param name="ctx">The context to be used during serialization.</param>
    /// <param name="writer">The writer to which the query fragment is serialized.</param>
    void Serialize(MappingContext ctx, Utf8FaunaWriter writer);
}

/// <summary>
/// Provides extension methods for the <see cref="IQueryFragment"/> interface to enhance its functionality,
/// allowing for more flexible serialization options.
/// </summary>
public static class QueryFragmentExtensions
{
    /// <summary>
    /// Serializes the query fragment to a string using UTF-8 encoding.
    /// </summary>
    /// <param name="fragment">The query fragment to serialize.</param>
    /// <param name="ctx">A <see cref="MappingContext"/> to influence serialization.</param>
    /// <returns>A string representation of the serialized query fragment.</returns>
    public static string Serialize(this IQueryFragment fragment, MappingContext ctx)
    {
        using var ms = new MemoryStream();
        using var fw = new Utf8FaunaWriter(ms);
        fragment.Serialize(ctx, fw);
        fw.Flush();
        return Encoding.UTF8.GetString(ms.ToArray());
    }
}
```

## File: Fauna/Query/Query.cs
```csharp
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna;

/// <summary>
/// Represents the abstract base class for constructing FQL queries.
/// </summary>

public abstract class Query : IEquatable<Query>, IQueryFragment
{
    /// <summary>
    /// Serializes the query into the provided stream.
    /// </summary>
    /// <param name="ctx">The context to be used during serialization.</param>
    /// <param name="writer">The writer to which the query is serialized.</param>
    public abstract void Serialize(MappingContext ctx, Utf8FaunaWriter writer);

    /// <summary>
    /// Returns a hash code for the current query.
    /// </summary>
    /// <returns>A hash code for the current query.</returns>
    public abstract override int GetHashCode();

    /// <summary>
    /// Determines whether the specified object is equal to the current query.
    /// </summary>
    /// <param name="otherObject">The object to compare with the current query.</param>
    /// <returns>true if the specified object is equal to the current query; otherwise, false.</returns>
    public abstract override bool Equals(object? otherObject);

    /// <summary>
    /// Determines whether the specified Query is equal to the current query.
    /// </summary>
    /// <param name="otherQuery">The Query to compare with the current query.</param>
    /// <returns>true if the specified Query is equal to the current query; otherwise, false.</returns>
    public abstract bool Equals(Query? otherQuery);

    /// <summary>
    /// Constructs an FQL query using the specified QueryStringHandler.
    /// </summary>
    /// <param name="handler">The QueryStringHandler that contains the query fragments.</param>
    /// <returns>A Query instance constructed from the handler.</returns>
    public static Query FQL(ref QueryStringHandler handler)
    {
        return handler.Result();
    }
}
```

## File: Fauna/Query/QueryArr.cs
```csharp
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna;

/// <summary>
/// Represents an array of FQL queries.
/// </summary>
internal sealed class QueryArr : Query, IQueryFragment
{
    /// <summary>
    /// Gets the value of the specified type represented in the query.
    /// </summary>
    public IEnumerable<Query> Unwrap { get; }

    /// <summary>
    /// Initializes a new instance of the QueryArr class with the specified value.
    /// </summary>
    /// <param name="v">The value of the specified type to be represented in the query.</param>
    public QueryArr(IEnumerable<Query> v)
    {
        Unwrap = v;
    }


    /// <summary>
    /// Serializes the query value.
    /// </summary>
    /// <param name="ctx">The serialization context.</param>
    /// <param name="writer">The writer to serialize the query value to.</param>
    public override void Serialize(MappingContext ctx, Utf8FaunaWriter writer)
    {
        writer.WriteStartObject();
        writer.WriteFieldName("array");
        writer.WriteStartArray();
        foreach (Query t in Unwrap)
        {
            var ser = Serializer.Generate(ctx, t.GetType());
            ser.Serialize(ctx, writer, t);
        }
        writer.WriteEndArray();
        writer.WriteEndObject();
    }

    /// <summary>
    /// Determines whether the specified QueryArr is equal to the current QueryArr.
    /// </summary>
    /// <param name="o">The QueryArr to compare with the current QueryArr.</param>
    /// <returns>true if the specified QueryArr is equal to the current QueryArr; otherwise, false.</returns>
    public override bool Equals(Query? o)
    {
        return o is QueryArr other && Unwrap.SequenceEqual(other.Unwrap);
    }

    /// <summary>
    /// Determines whether the specified object is equal to the current QueryArr.
    /// </summary>
    /// <param name="otherObject">The object to compare with the current QueryArr.</param>
    /// <returns>true if the specified object is equal to the current QueryArr; otherwise, false.</returns>
    public override bool Equals(object? otherObject)
    {
        return Equals(otherObject as QueryArr);
    }

    /// <summary>
    /// The default hash function.
    /// </summary>
    /// <returns>A hash code for the current QueryArr.</returns>
    public override int GetHashCode()
    {
        return Unwrap.GetHashCode();
    }

    /// <summary>
    /// Returns a string that represents the current QueryArr.
    /// </summary>
    /// <returns>A string that represents the current QueryArr.</returns>
    public override string ToString()
    {
        return $"QueryArr({string.Join(", ", Unwrap)})";
    }

}
```

## File: Fauna/Query/QueryExpr.cs
```csharp
using System.Collections.ObjectModel;
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna;

/// <summary>
/// Represents an FQL query expression. This class encapsulates a list of IQueryFragment instances, allowing for complex query constructions.
/// </summary>
public sealed class QueryExpr : Query, IQueryFragment
{
    /// <summary>
    /// Initializes a new instance of the QueryExpr class with a collection of query fragments.
    /// </summary>
    /// <param name="fragments">The collection of IQueryFragment instances.</param>
    public QueryExpr(IList<IQueryFragment> fragments)
    {
        Unwrap = new ReadOnlyCollection<IQueryFragment>(fragments);
    }

    /// <summary>
    /// Initializes a new instance of the QueryExpr class with one or more query fragments.
    /// </summary>
    /// <param name="fragments">The array of IQueryFragment instances.</param>
    public QueryExpr(params IQueryFragment[] fragments)
        : this(fragments.ToList())
    {
    }

    /// <summary>
    /// Gets the readonly collection of query fragments.
    /// </summary>
    public IReadOnlyCollection<IQueryFragment> Unwrap { get; }

    /// <summary>
    /// Gets the readonly collection of query fragments.
    /// </summary>
    public IReadOnlyCollection<IQueryFragment> Fragments => Unwrap;

    /// <summary>
    /// Serializes the query expression.
    /// </summary>
    /// <param name="ctx">The serialization context.</param>
    /// <param name="writer">The writer to serialize the query expression to.</param>
    public override void Serialize(MappingContext ctx, Utf8FaunaWriter writer)
    {
        writer.WriteStartObject();
        writer.WriteFieldName("fql");
        writer.WriteStartArray();
        foreach (var t in Unwrap)
        {
            t.Serialize(ctx, writer);
        }
        writer.WriteEndArray();
        writer.WriteEndObject();
    }

    /// <summary>
    /// Determines whether the specified QueryExpr is equal to the current QueryExpr.
    /// </summary>
    /// <param name="o">The QueryExpr to compare with the current QueryExpr.</param>
    /// <returns>true if the specified QueryExpr is equal to the current QueryExpr; otherwise, false.</returns>
    public override bool Equals(Query? o) => IsEqual(o as QueryExpr);

    /// <summary>
    /// Determines whether the specified object is equal to the current QueryExpr.
    /// </summary>
    /// <param name="o">The object to compare with the current QueryExpr.</param>
    /// <returns>true if the specified object is equal to the current QueryExpr; otherwise, false.</returns>
    public override bool Equals(object? o)
    {
        if (ReferenceEquals(this, o))
        {
            return true;
        }

        return o is QueryExpr expr && IsEqual(expr);
    }

    /// <summary>
    /// The default hash function.
    /// </summary>
    /// <returns>A hash code for the current QueryExpr.</returns>
    public override int GetHashCode() => Fragments.GetHashCode();

    /// <summary>
    /// Returns a string that represents the current QueryExpr.
    /// </summary>
    /// <returns>A string that represents the current QueryExpr.</returns>
    public override string ToString() => $"QueryExpr({string.Join(",", Fragments)})";

    private bool IsEqual(QueryExpr? o)
    {
        if (o is null)
        {
            return false;
        }

        if (Fragments == null || o.Fragments == null)
        {
            return Fragments == null && o.Fragments == null;
        }

        return Fragments.SequenceEqual(o.Fragments);
    }

    /// <summary>
    /// Determines whether two specified instances of QueryExpr are equal.
    /// </summary>
    /// <param name="left">The first QueryExpr to compare.</param>
    /// <param name="right">The second QueryExpr to compare.</param>
    /// <returns>true if left and right are equal; otherwise, false.</returns>
    public static bool operator ==(QueryExpr left, QueryExpr right)
    {
        if (ReferenceEquals(left, right))
        {
            return true;
        }

        if (left is null || right is null)
        {
            return false;
        }

        return left.Equals(right);
    }

    /// <summary>
    /// Determines whether two specified instances of QueryExpr are not equal.
    /// </summary>
    /// <param name="left">The first QueryExpr to compare.</param>
    /// <param name="right">The second QueryExpr to compare.</param>
    /// <returns>true if left and right are not equal; otherwise, false.</returns>
    public static bool operator !=(QueryExpr left, QueryExpr right)
    {
        return !(left == right);
    }
}
```

## File: Fauna/Query/QueryLiteral.cs
```csharp
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna;

/// <summary>
/// Represents a literal part of an FQL query. This class is used for embedding raw string values directly into the query structure.
/// </summary>
public sealed class QueryLiteral : IQueryFragment
{
    /// <summary>
    /// Initializes a new instance of the QueryLiteral class with the specified value.
    /// </summary>
    /// <param name="v">The string value to be represented as a query literal.</param>
    /// <exception cref="ArgumentNullException">Thrown when the value is null.</exception>
    public QueryLiteral(string v)
    {
        if (v == null)
        {
            throw new ArgumentNullException(nameof(v), "Value cannot be null.");
        }

        Unwrap = v;
    }

    /// <summary>
    /// Gets the string value of the query literal.
    /// </summary>
    public string Unwrap { get; }

    /// <summary>
    /// Returns a string that represents the current QueryLiteral.
    /// </summary>
    /// <returns>A string that represents the current QueryLiteral.</returns>
    public override string ToString()
    {
        return $"QueryLiteral({Unwrap})";
    }

    /// <summary>
    /// Serializes the query literal.
    /// </summary>
    /// <param name="ctx">The serialization context.</param>
    /// <param name="writer">The writer to serialize the query literal to.</param>
    public void Serialize(MappingContext ctx, Utf8FaunaWriter writer)
    {
        writer.WriteStringValue(Unwrap);
    }

    /// <summary>
    /// Determines whether the specified object is equal to the current QueryLiteral.
    /// </summary>
    /// <param name="other">The object to compare with the current QueryLiteral.</param>
    /// <returns>true if the specified object is equal to the current QueryLiteral; otherwise, false.</returns>
    public override bool Equals(object? other)
    {
        var otherQuery = other as IQueryFragment;

        if (otherQuery is null)
        {
            return false;
        }

        if (ReferenceEquals(this, otherQuery))
        {
            return true;
        }

        if (otherQuery is QueryLiteral otherLiteral)
        {
            return Unwrap == otherLiteral.Unwrap;
        }

        return false;
    }

    /// <summary>
    /// The default hash function.
    /// </summary>
    /// <returns>A hash code for the current QueryLiteral.</returns>
    public override int GetHashCode()
    {
        return Unwrap.GetHashCode();
    }

    /// <summary>
    /// Determines whether two specified instances of QueryLiteral are equal.
    /// </summary>
    /// <param name="left">The first QueryLiteral to compare.</param>
    /// <param name="right">The second QueryLiteral to compare.</param>
    /// <returns>true if left and right are equal; otherwise, false.</returns>
    public static bool operator ==(QueryLiteral left, QueryLiteral right)
    {
        return Equals(left, right);
    }

    /// <summary>
    /// Determines whether two specified instances of QueryLiteral are not equal.
    /// </summary>
    /// <param name="left">The first QueryLiteral to compare.</param>
    /// <param name="right">The second QueryLiteral to compare.</param>
    /// <returns>true if left and right are not equal; otherwise, false.</returns>
    public static bool operator !=(QueryLiteral left, QueryLiteral right)
    {
        return !Equals(left, right);
    }
}
```

## File: Fauna/Query/QueryObj.cs
```csharp
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna;

/// <summary>
/// Represents a dictionary of FQL queries.
/// </summary>
public sealed class QueryObj : Query, IQueryFragment
{
    /// <summary>
    /// Gets the value of the specified type represented in the query.
    /// </summary>
    public IDictionary<string, Query> Unwrap { get; }

    /// <summary>
    /// Initializes a new instance of the QueryObj class with the specified value.
    /// </summary>
    /// <param name="v">The value of the specified type to be represented in the query.</param>
    public QueryObj(IDictionary<string, Query> v)
    {
        Unwrap = v;
    }

    /// <summary>
    /// Serializes the query value.
    /// </summary>
    /// <param name="ctx">The serialization context.</param>
    /// <param name="writer">The writer to serialize the query value to.</param>
    public override void Serialize(MappingContext ctx, Utf8FaunaWriter writer)
    {
        var ser = Serializer.Generate(ctx, GetType());
        ser.Serialize(ctx, writer, this);
    }

    /// <summary>
    /// Determines whether the specified QueryObj is equal to the current QueryObj.
    /// </summary>
    /// <param name="o">The QueryObj to compare with the current QueryObj.</param>
    /// <returns>true if the specified QueryObj is equal to the current QueryObj; otherwise, false.</returns>
    public override bool Equals(Query? o) => IsEqual(o as QueryObj);

    /// <summary>
    /// Determines whether the specified object is equal to the current QueryObj.
    /// </summary>
    /// <param name="o">The object to compare with the current QueryObj.</param>
    /// <returns>true if the specified object is equal to the current QueryObj; otherwise, false.</returns>
    public override bool Equals(object? o)
    {
        return ReferenceEquals(this, o) || IsEqual(o as QueryObj);
    }

    /// <summary>
    /// The default hash function.
    /// </summary>
    /// <returns>A hash code for the current QueryObj.</returns>
    public override int GetHashCode()
    {
        int hash = 31;

        hash *= Unwrap.GetHashCode();

        return hash;
    }

    /// <summary>
    /// Returns a string that represents the current QueryObj.
    /// </summary>
    /// <returns>A string that represents the current QueryObj.</returns>
    public override string ToString() => $"QueryObj({Unwrap})";

    /// <summary>
    /// Determines whether two specified instances of QueryObj are equal.
    /// </summary>
    /// <param name="left">The first QueryObj to compare.</param>
    /// <param name="right">The second QueryObj to compare.</param>
    /// <returns>true if left and right are equal; otherwise, false.</returns>
    public static bool operator ==(QueryObj left, QueryObj right)
    {
        return ReferenceEquals(left, right) || left.Equals(right);
    }

    /// <summary>
    /// Determines whether two specified instances of QueryObj are not equal.
    /// </summary>
    /// <param name="left">The first QueryObj to compare.</param>
    /// <param name="right">The second QueryObj to compare.</param>
    /// <returns>true if left and right are not equal; otherwise, false.</returns>
    public static bool operator !=(QueryObj left, QueryObj right)
    {
        return !(left == right);
    }

    private bool IsEqual(QueryObj? o)
    {
        return o is not null && Unwrap.Equals(o.Unwrap);
    }
}
```

## File: Fauna/Query/QueryStringHandler.cs
```csharp
using System.Runtime.CompilerServices;

namespace Fauna;

/// <summary>
/// Provides a mechanism to build FQL query expressions using interpolated strings. This structure collects fragments and literals to construct complex query expressions.
/// </summary>
[InterpolatedStringHandler]
public ref struct QueryStringHandler
{
    private readonly List<IQueryFragment> _fragments;

    /// <summary>
    /// Initializes a new instance of the <see cref="QueryStringHandler"/> struct.
    /// </summary>
    /// <param name="literalLength">The estimated length of the literals in the interpolated string.</param>
    /// <param name="formattedCount">The number of format items in the interpolated string.</param>
    public QueryStringHandler(int literalLength, int formattedCount)
    {
        _fragments = new List<IQueryFragment>();
    }

    /// <summary>
    /// Appends a literal string to the query.
    /// </summary>
    /// <param name="value">The literal string to append.</param>
    public void AppendLiteral(string value)
    {
        _fragments.Add(new QueryLiteral(value));
    }

    /// <summary>
    /// Appends a formatted value to the query. The value is wrapped as a <see cref="QueryVal"/> or <see cref="QueryExpr"/> depending on its type.
    /// </summary>
    /// <param name="value">The value to append.</param>
    public void AppendFormatted(object? value)
    {
        if (value is IQueryFragment frag)
        {
            _fragments.Add(frag);
        }
        else
        {
            _fragments.Add(new QueryVal(value));
        }
    }

    /// <summary>
    /// Constructs and returns a <see cref="Query"/> instance representing the current state of the handler.
    /// </summary>
    /// <returns>A <see cref="Query"/> instance representing the constructed query fragments.</returns>
    public Query Result()
    {
        return new QueryExpr(_fragments);
    }
}
```

## File: Fauna/Query/QueryVal.cs
```csharp
using Fauna.Mapping;
using Fauna.Serialization;

namespace Fauna;

/// <summary>
/// Represents a generic value holder for FQL queries. This class allows embedding values of various types into the query, with support for primitives, POCOs, and other types.
/// </summary>
public sealed class QueryVal : Query, IQueryFragment
{
    /// <summary>
    /// Gets the value of the specified type represented in the query.
    /// </summary>
    public object? Unwrap { get; }

    /// <summary>
    /// Initializes a new instance of the QueryVal class with the specified value.
    /// </summary>
    /// <param name="v">The value of the specified type to be represented in the query.</param>
    public QueryVal(object? v)
    {

        Unwrap = v;
    }

    /// <summary>
    /// Serializes the query value.
    /// </summary>
    /// <param name="ctx">The serialization context.</param>
    /// <param name="writer">The writer to serialize the query value to.</param>
    public override void Serialize(MappingContext ctx, Utf8FaunaWriter writer)
    {
        writer.WriteStartObject();
        writer.WriteFieldName("value");
        var ser = Unwrap is not null ? Serializer.Generate(ctx, Unwrap.GetType()) : DynamicSerializer.Singleton;
        ser.Serialize(ctx, writer, Unwrap);
        writer.WriteEndObject();
    }

    /// <summary>
    /// Determines whether the specified QueryVal is equal to the current QueryVal.
    /// </summary>
    /// <param name="o">The QueryVal to compare with the current QueryVal.</param>
    /// <returns>true if the specified QueryVal is equal to the current QueryVal; otherwise, false.</returns>
    public override bool Equals(Query? o) => IsEqual(o as QueryVal);

    /// <summary>
    /// Determines whether the specified object is equal to the current QueryVal.
    /// </summary>
    /// <param name="o">The object to compare with the current QueryVal.</param>
    /// <returns>true if the specified object is equal to the current QueryVal; otherwise, false.</returns>
    public override bool Equals(object? o)
    {
        if (ReferenceEquals(this, o))
        {
            return true;
        }

        return IsEqual(o as QueryVal);
    }

    /// <summary>
    /// The default hash function.
    /// </summary>
    /// <returns>A hash code for the current QueryVal.</returns>
    public override int GetHashCode()
    {
        var hash = 31;

        if (Unwrap is not null)
        {
            hash *= Unwrap.GetHashCode();
        }

        return hash;
    }

    /// <summary>
    /// Returns a string that represents the current QueryVal.
    /// </summary>
    /// <returns>A string that represents the current QueryVal.</returns>
    public override string ToString() => $"QueryVal({Unwrap})";

    /// <summary>
    /// Determines whether two specified instances of QueryVal are equal.
    /// </summary>
    /// <param name="left">The first QueryVal to compare.</param>
    /// <param name="right">The second QueryVal to compare.</param>
    /// <returns>true if left and right are equal; otherwise, false.</returns>
    public static bool operator ==(QueryVal left, QueryVal right)
    {
        if (ReferenceEquals(left, right))
        {
            return true;
        }

        if (left is null || right is null)
        {
            return false;
        }

        return left.Equals(right);
    }

    /// <summary>
    /// Determines whether two specified instances of QueryVal are not equal.
    /// </summary>
    /// <param name="left">The first QueryVal to compare.</param>
    /// <param name="right">The second QueryVal to compare.</param>
    /// <returns>true if left and right are not equal; otherwise, false.</returns>
    public static bool operator !=(QueryVal left, QueryVal right)
    {
        return !(left == right);
    }

    private bool IsEqual(QueryVal? o)
    {
        if (o is null)
        {
            return false;
        }

        if (Unwrap is null)
        {
            return (o.Unwrap is null) ? true : false;
        }

        return Unwrap.Equals(o.Unwrap);
    }
}
```

## File: Fauna/Serialization/BaseRefSerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;


internal class RefSerializer<T> : BaseSerializer<Ref<T>> where T : notnull
{
    private readonly BaseRefSerializer<T> _baseRefSerializer;

    public RefSerializer(ISerializer docSerializer)
    {
        _baseRefSerializer = new BaseRefSerializer<T>(docSerializer);
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.Ref };

    public override Ref<T> Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        return (Ref<T>)_baseRefSerializer.Deserialize(ctx, ref reader);
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        _baseRefSerializer.Serialize(context, writer, o);
    }
}

internal class NamedRefSerializer<T> : BaseSerializer<NamedRef<T>> where T : notnull
{
    private readonly BaseRefSerializer<T> _baseRefSerializer;

    public NamedRefSerializer(ISerializer docSerializer)
    {
        _baseRefSerializer = new BaseRefSerializer<T>(docSerializer);
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.Ref };

    public override NamedRef<T> Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        return (NamedRef<T>)_baseRefSerializer.Deserialize(ctx, ref reader);
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        _baseRefSerializer.Serialize(context, writer, o);
    }
}

internal class BaseRefSerializer<T> : BaseSerializer<BaseRef<T>> where T : notnull
{
    private readonly ISerializer _docSerializer;

    public BaseRefSerializer(ISerializer docSerializer)
    {
        _docSerializer = docSerializer;
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.Ref };

    public override BaseRef<T> Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        return reader.CurrentTokenType switch
        {
            TokenType.StartRef => DeserializeRefInternal(new BaseRefBuilder<T>(), ctx, ref reader),
            TokenType.StartDocument => DeserializeDocument(new BaseRefBuilder<T>(), ctx, ref reader),
            _ => throw new SerializationException(
                $"Unexpected token while deserializing into Ref: {reader.CurrentTokenType}")
        };
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case Ref<T> r:
                writer.WriteStartRef();
                writer.WriteString("id", r.Id);
                writer.WriteModule("coll", r.Collection);
                writer.WriteEndRef();
                break;
            case NamedRef<T> r:
                writer.WriteStartRef();
                writer.WriteString("name", r.Name);
                writer.WriteModule("coll", r.Collection);
                writer.WriteEndRef();
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    private static BaseRef<T> DeserializeRefInternal(BaseRefBuilder<T> builder, MappingContext context, ref Utf8FaunaReader reader)
    {

        while (reader.Read() && reader.CurrentTokenType != TokenType.EndRef)
        {
            if (reader.CurrentTokenType != TokenType.FieldName)
                throw new SerializationException(
                    $"Unexpected token while deserializing into NamedRef: {reader.CurrentTokenType}");

            string fieldName = reader.GetString()!;
            reader.Read();
            switch (fieldName)
            {
                case "id":
                    builder.Id = reader.GetString();
                    break;
                case "name":
                    builder.Name = reader.GetString();
                    break;
                case "coll":
                    builder.Collection = reader.GetModule();
                    break;
                case "cause":
                    builder.Cause = reader.GetString();
                    break;
                case "exists":
                    builder.Exists = reader.GetBoolean();
                    break;
                default:
                    throw new SerializationException(
                        $"Unexpected field while deserializing into Ref: {fieldName}");
            }
        }

        return builder.Build();
    }

    public BaseRef<T> DeserializeDocument(BaseRefBuilder<T> builder, MappingContext context, ref Utf8FaunaReader reader)
    {

        while (reader.Read() && reader.CurrentTokenType != TokenType.EndDocument)
        {
            if (reader.CurrentTokenType != TokenType.FieldName)
                throw new SerializationException(
                    $"Unexpected token while deserializing into NamedRef: {reader.CurrentTokenType}");

            string fieldName = reader.GetString()!;
            reader.Read();
            switch (fieldName)
            {
                case "id":
                    builder.Id = reader.GetString();
                    break;
                case "name":
                    builder.Name = reader.GetString();
                    break;
                case "coll":
                    builder.Collection = reader.GetModule();

                    if (_docSerializer is not IPartialDocumentSerializer cs)
                    {
                        throw new SerializationException($"Serializer {_docSerializer.GetType().Name} must implement IPartialDocumentSerializer interface.");
                    }

                    // This assumes ordering on the wire. If name is not null and we're here, then it's a named document so name is a string.
                    builder.Doc = (T?)cs.DeserializeDocument(context, builder.Id, builder.Name, builder.Collection, ref reader);
                    break;
            }

            // After we deserialize into a doc, we end on the EndDocument a token and do not want to read again
            if (reader.CurrentTokenType == TokenType.EndDocument) break;
        }

        return builder.Build();
    }
}
```

## File: Fauna/Serialization/ClassSerializer.cs
```csharp
using System.Diagnostics;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;

internal class ClassSerializer<T> : BaseSerializer<T>, IPartialDocumentSerializer
{
    private const string IdField = "id";
    private const string NameField = "name";
    private const string CollField = "coll";
    private readonly MappingInfo _info;

    public ClassSerializer(MappingInfo info)
    {
        Debug.Assert(info.Type == typeof(T));
        _info = info;
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Document, FaunaType.Null, FaunaType.Object, FaunaType.Ref };

    public object DeserializeDocument(MappingContext context, string? id, string? name, Module? coll, ref Utf8FaunaReader reader)
    {
        object instance = CreateInstance();
        if (id is not null) TrySetId(instance, id);
        if (name is not null) TrySetName(instance, name);
        if (coll is not null) TrySetColl(instance, coll);
        SetFields(instance, context, ref reader, TokenType.EndDocument);
        return instance;
    }

    public override T Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        var endToken = reader.CurrentTokenType switch
        {
            TokenType.StartDocument => TokenType.EndDocument,
            TokenType.StartObject => TokenType.EndObject,
            TokenType.StartRef => TokenType.EndRef,
            var other => throw UnexpectedToken(other),
        };

        if (endToken == TokenType.EndRef)
        {
            string? id = null;
            string? name = null;
            Module? coll = null;
            string? cause = null;
            bool exists = true;

            while (reader.Read() && reader.CurrentTokenType != TokenType.EndRef)
            {
                if (reader.CurrentTokenType != TokenType.FieldName)
                    throw new SerializationException(
                        $"Unexpected token while deserializing into Ref: {reader.CurrentTokenType}");

                string fieldName = reader.GetString()!;
                reader.Read();
                switch (fieldName)
                {
                    case "id":
                        id = reader.GetString();
                        break;
                    case "name":
                        name = reader.GetString();
                        break;
                    case "coll":
                        coll = reader.GetModule();
                        break;
                    case "cause":
                        cause = reader.GetString();
                        break;
                    case "exists":
                        exists = reader.GetBoolean();
                        break;
                }
            }

            if ((id != null || name != null) && coll != null && exists)
            {
                throw new SerializationException("Cannot deserialize refs into classes.");
            }

            if (id != null)
            {
                throw new NullDocumentException(id, null, coll!, cause!);
            }

            throw new NullDocumentException(null, name, coll!, cause!);
        }

        object instance = CreateInstance();
        SetFields(instance, ctx, ref reader, endToken);
        return (T)instance;
    }

    public override void Serialize(MappingContext ctx, Utf8FaunaWriter writer, object? o)
    {
        SerializeInternal(ctx, writer, o);
    }

    private static void SerializeInternal(MappingContext ctx, Utf8FaunaWriter w, object? o)
    {
        if (o == null)
        {
            w.WriteNullValue();
            return;
        }

        var t = o.GetType();
        var info = ctx.GetInfo(t);
        bool shouldEscape = info.ShouldEscapeObject;

        if (shouldEscape) w.WriteStartEscapedObject(); else w.WriteStartObject();
        foreach (var field in info.Fields)
        {
            if (field.FieldType is FieldType.ServerGeneratedId or FieldType.Ts or FieldType.Coll)
            {
                continue;
            }

            object? v = field.Property.GetValue(o);
            if (field.FieldType is FieldType.ClientGeneratedId && v == null)
            {
                // The field is a client generated ID but set to null, so assume they're doing something
                // other than creating the object.
                continue;
            }

            w.WriteFieldName(field.Name);
            field.Serializer.Serialize(ctx, w, v);
        }
        if (shouldEscape) w.WriteEndEscapedObject(); else w.WriteEndObject();
    }

    private object CreateInstance() => Activator.CreateInstance(_info.Type)!;

    private void SetFields(object instance, MappingContext context, ref Utf8FaunaReader reader, TokenType endToken)
    {
        while (reader.Read() && reader.CurrentTokenType != endToken)
        {
            if (reader.CurrentTokenType != TokenType.FieldName)
                throw UnexpectedToken(reader.CurrentTokenType);

            string fieldName = reader.GetString()!;
            reader.Read();

            if (fieldName == IdField && reader.CurrentTokenType == TokenType.String)
            {
                TrySetId(instance, reader.GetString()!);
            }
            else if (fieldName == NameField && reader.CurrentTokenType == TokenType.String)
            {
                TrySetName(instance, reader.GetString()!);
            }
            else if (_info.FieldsByName.TryGetValue(fieldName, out var field))
            {
                field.Property.SetValue(instance, field.Serializer.Deserialize(context, ref reader));
            }
            else
            {
                reader.Skip();
            }
        }
    }

    private void TrySetId(object instance, string id)
    {
        if (!_info.FieldsByName.TryGetValue(IdField, out var field))
        {
            return;
        }

        if (field.Type == typeof(long))
        {
            field.Property.SetValue(instance, long.Parse(id));
        }
        else if (field.Type == typeof(string))
        {
            field.Property.SetValue(instance, id);
        }
        else
        {
            throw UnexpectedToken(TokenType.String);
        }
    }

    private void TrySetName(object instance, string name)
    {
        if (_info.FieldsByName.TryGetValue(NameField, out var field))
        {
            if (field.Type == typeof(string))
            {
                field.Property.SetValue(instance, name);
            }
            else
            {
                throw UnexpectedToken(TokenType.String);
            }
        }
    }

    private void TrySetColl(object instance, Module coll)
    {
        if (_info.FieldsByName.TryGetValue(CollField, out var field))
        {
            if (field.Type == typeof(Module))
            {
                field.Property.SetValue(instance, coll);
            }
            else
            {
                throw UnexpectedToken(TokenType.String);
            }
        }
    }

    private new SerializationException UnexpectedToken(TokenType tokenType) =>
        new($"Unexpected token while deserializing into class {_info.Type.Name}: {tokenType}");
}
```

## File: Fauna/Serialization/DictionarySerializer.cs
```csharp
using System.Text.Json;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;

internal class DictionarySerializer<T> : BaseSerializer<Dictionary<string, T>>, IPartialDocumentSerializer
{
    private readonly ISerializer<T> _elemSerializer;

    public DictionarySerializer(ISerializer<T> elemSerializer)
    {
        _elemSerializer = elemSerializer;
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.Object };

    public override Dictionary<string, T> Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        switch (reader.CurrentTokenType)
        {
            case TokenType.StartObject:
                return DeserializeInternal(new Dictionary<string, T>(), TokenType.EndObject, ctx, ref reader);
            case TokenType.StartDocument:
                return DeserializeInternal(new Dictionary<string, T>(), TokenType.EndDocument, ctx, ref reader);
            default:
                throw new SerializationException(
                    $"Unexpected token while deserializing into {typeof(Dictionary<string, T>)}: {reader.CurrentTokenType}");
        }
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case Dictionary<string, T> d:
                bool shouldEscape = Serializer.Tags.Overlaps(d.Keys);
                if (shouldEscape) writer.WriteStartEscapedObject();
                else writer.WriteStartObject();
                foreach (var (key, value) in d)
                {
                    writer.WriteFieldName(key);
                    _elemSerializer.Serialize(context, writer, value);
                }

                if (shouldEscape) writer.WriteEndEscapedObject();
                else writer.WriteEndObject();
                break;
            default:
                throw new NotImplementedException();
        }
    }

    public object DeserializeDocument(MappingContext context, string? id, string? name, Module? coll, ref Utf8FaunaReader reader)
    {
        var dict = new Dictionary<string, T>();
        if (typeof(T) == typeof(object))
        {
            if (id != null) dict.Add("id", (T)(object)id);
            if (name != null) dict.Add("name", (T)(object)name);
            if (coll != null) dict.Add("coll", (T)(object)coll);
        }

        return DeserializeInternal(dict, TokenType.EndDocument, context, ref reader);
    }

    private Dictionary<string, T> DeserializeInternal(
        Dictionary<string, T> dict,
        TokenType endToken,
        MappingContext context,
        ref Utf8FaunaReader reader)
    {

        while (reader.Read() && reader.CurrentTokenType != endToken)
        {
            if (reader.CurrentTokenType != TokenType.FieldName)
                throw new SerializationException(
                    $"Unexpected token while deserializing field of {typeof(Dictionary<string, T>)}: {reader.CurrentTokenType}");

            string fieldName = reader.GetString()!;
            reader.Read();
            dict.Add(fieldName, _elemSerializer.Deserialize(context, ref reader));
        }

        return dict;
    }
}
```

## File: Fauna/Serialization/DynamicSerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;

internal class DynamicSerializer : BaseSerializer<object?>
{
    public static DynamicSerializer Singleton { get; } = new();

    private readonly ListSerializer<object?> _list;
    private readonly PageSerializer<object?> _page;
    private readonly DictionarySerializer<object?> _dict;
    private readonly BaseRefSerializer<Dictionary<string, object>> _docref;


    private DynamicSerializer()
    {
        _list = new ListSerializer<object?>(this);
        _page = new PageSerializer<object?>(this);
        _dict = new DictionarySerializer<object?>(this);
        _docref = new BaseRefSerializer<Dictionary<string, object>>(_dict);
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> {
        FaunaType.Array,
        FaunaType.Boolean,
        FaunaType.Bytes,
        FaunaType.Date,
        FaunaType.Double,
        FaunaType.Document,
        FaunaType.Int,
        FaunaType.Long,
        FaunaType.Module,
        FaunaType.Null,
        FaunaType.Object,
        FaunaType.Ref,
        FaunaType.Set,
        FaunaType.Stream,
        FaunaType.String,
        FaunaType.Time
    };

    public override object? Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.StartObject => _dict.Deserialize(ctx, ref reader),
            TokenType.StartArray => _list.Deserialize(ctx, ref reader),
            TokenType.StartPage => _page.Deserialize(ctx, ref reader),
            TokenType.StartRef => _docref.Deserialize(ctx, ref reader),
            TokenType.StartDocument => DeserializeDocumentInternal(ctx, ref reader),
            TokenType.String => reader.GetString(),
            TokenType.Int => reader.GetInt(),
            TokenType.Long => reader.GetLong(),
            TokenType.Double => reader.GetDouble(),
            TokenType.Date => reader.GetDate(),
            TokenType.Time => reader.GetTime(),
            TokenType.True or TokenType.False => reader.GetBoolean(),
            TokenType.Module => reader.GetModule(),
            TokenType.Bytes => reader.GetBytes(),
            TokenType.Null => null,
            TokenType.EventSource => reader.GetEventSource(),
            _ => throw new SerializationException(
                $"Unexpected token while deserializing: {reader.CurrentTokenType}"),
        };

    private object DeserializeDocumentInternal(MappingContext context, ref Utf8FaunaReader reader)
    {
        var builder = new BaseRefBuilder<Dictionary<string, object>>();
        while (reader.Read() && reader.CurrentTokenType != TokenType.EndDocument)
        {
            if (reader.CurrentTokenType != TokenType.FieldName)
                throw new SerializationException(
                    $"Unexpected token while deserializing @doc: {reader.CurrentTokenType}");

            string fieldName = reader.GetString()!;

            reader.Read();

            switch (fieldName)
            {
                // Relies on ordering for doc fields.
                case "id":
                    builder.Id = reader.GetString();
                    break;
                case "name":
                    builder.Name = reader.GetString();
                    break;
                case "coll":
                    builder.Collection = reader.GetModule();

                    // if we encounter a mapped collection, jump to the class deserializer.
                    // NB this relies on the fact that docs on the wire always start with id and coll.
                    if (context.TryGetCollection(builder.Collection.Name, out var info) && info.ClassSerializer is IPartialDocumentSerializer ser)
                    {
                        return new BaseRefBuilder<object>
                        {
                            Id = builder.Id,
                            Name = builder.Name,
                            Collection = builder.Collection,
                            Doc = ser.DeserializeDocument(context, builder.Id, builder.Name, builder.Collection,
                                ref reader)
                        }.Build();
                    }

                    builder.Doc = (Dictionary<string, object>?)_dict.DeserializeDocument(context, builder.Id, builder.Name, builder.Collection, ref reader);
                    break;
            }

            // After we deserialize into a doc, we end on the EndDocument a token and do not want to read again
            if (reader.CurrentTokenType == TokenType.EndDocument) break;
        }

        return builder.Build();
    }

    /// <summary>
    /// Serializes an object to a Fauna compatible format.
    /// </summary>
    /// <param name="ctx">The context for serialization.</param>
    /// <param name="w">The writer to serialize the object to.</param>
    /// <param name="o">The object to serialize.</param>
    /// <exception cref="SerializationException">Thrown when serialization fails.</exception>
    public override void Serialize(MappingContext ctx, Utf8FaunaWriter w, object? o)
    {
        if (o == null)
        {
            w.WriteNullValue();
            return;
        }

        var ser = Serializer.Generate(ctx, o.GetType());
        ser.Serialize(ctx, w, o);
    }
}
```

## File: Fauna/Serialization/EventSourceSerializer.cs
```csharp
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;


internal class EventSourceSerializer : BaseSerializer<EventSource>
{
    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.Stream };

    public override EventSource Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.EventSource => reader.GetEventSource(),
            _ => throw UnexpectedToken(reader.CurrentTokenType)
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        throw new NotImplementedException();
    }
}
```

## File: Fauna/Serialization/FaunaType.cs
```csharp
namespace Fauna.Serialization;

/// <summary>
/// An enum representing possible <a href="https://docs.fauna.com/fauna/current/reference/fql/types/">Fauna types</a>.
/// </summary>
public enum FaunaType
{
    /// <summary>
    /// A Fauna integer.
    /// </summary>
    Int,

    /// <summary>
    /// A Fauna long.
    /// </summary>
    Long,

    /// <summary>
    /// A Fauna double.
    /// </summary>
    Double,

    /// <summary>
    /// A Fauna string.
    /// </summary>
    String,

    /// <summary>
    /// A Fauna date.
    /// </summary>
    Date,


    /// <summary>
    /// A Fauna time.
    /// </summary>
    Time,

    /// <summary>
    /// A Fauna boolean.
    /// </summary>
    Boolean,

    /// <summary>
    /// A Fauna object. This is different from a <see cref="Document"/>.
    /// </summary>
    Object,

    /// <summary>
    /// A Fauna document reference. This includes named documents.
    /// </summary>
    Ref,

    /// <summary>
    /// A Fauna document.
    /// </summary>
    Document,

    /// <summary>
    /// A Fauna array.
    /// </summary>
    Array,

    /// <summary>
    /// A Fauna byte array, stored as a base-64 encoded string.
    /// </summary>
    Bytes,

    /// <summary>
    /// A null value.
    /// </summary>
    Null,

    /// <summary>
    /// A Fauna event source.
    /// </summary>
    Stream,

    /// <summary>
    /// A Fauna module.
    /// </summary>
    Module,

    /// <summary>
    /// A Fauna set.
    /// </summary>
    Set
}
```

## File: Fauna/Serialization/IPartialDocumentSerializer.cs
```csharp
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;

internal interface IPartialDocumentSerializer : ISerializer
{
    public object DeserializeDocument(MappingContext context, string? id, string? name, Module? coll, ref Utf8FaunaReader reader);
}
```

## File: Fauna/Serialization/ISerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;

namespace Fauna.Serialization;

/// <summary>
/// A generic interface that defines serialize and deserialize behavior for a specific type, and declares the supported <see cref="FaunaType"/>.
/// </summary>
/// <typeparam name="T">The type <see cref="ISerializer{T}"/> applies to.</typeparam>
public interface ISerializer<out T> : ISerializer
{
    /// <summary>
    /// Consumes all or some of a <see cref="Utf8FaunaReader"/> and returns an instance of <typeparamref name="T"/>.
    /// </summary>
    /// <param name="ctx">A <see cref="MappingContext"/> used to influence deserialization.</param>
    /// <param name="reader">The <see cref="Utf8FaunaReader"/> to consume.</param>
    /// <returns>An instance representing part or all of the consumed <see cref="Utf8FaunaReader"/>.</returns>
    new T Deserialize(MappingContext ctx, ref Utf8FaunaReader reader);
}

/// <summary>
/// An interface that defines serialize and deserialize behavior for each supported <see cref="FaunaType"/>.
/// </summary>
public interface ISerializer
{
    /// <summary>
    /// Consumes all or some of a <see cref="Utf8FaunaReader"/> and returns an object or null.
    /// </summary>
    /// <param name="ctx">A <see cref="MappingContext"/> used to influence deserialization.</param>
    /// <param name="reader">The <see cref="Utf8FaunaReader"/> to consume.</param>
    /// <returns>An instance representing part or all of the consumed <see cref="Utf8FaunaReader"/>.</returns>
    object? Deserialize(MappingContext ctx, ref Utf8FaunaReader reader);

    /// <summary>
    /// Serializes the provided object into the <see cref="Utf8FaunaWriter"/>.
    /// </summary>
    /// <param name="ctx">>A <see cref="MappingContext"/> used to influence serialization.</param>
    /// <param name="writer">The <see cref="Utf8FaunaWriter"/> to write to.</param>
    /// <param name="o">The object to serialize.</param>
    void Serialize(MappingContext ctx, Utf8FaunaWriter writer, object? o);

    /// <summary>
    /// A list of types to which the <see cref="ISerializer"/> applies.
    /// </summary>
    /// <returns>A list of <see cref="FaunaType"/>s.</returns>
    List<FaunaType> GetSupportedTypes();
}

/// <summary>
/// An abstract class encapsulating common serialization and deserialization logic.
/// </summary>
/// <typeparam name="T">The type the BaseSerializer applies to.</typeparam>
public abstract class BaseSerializer<T> : ISerializer<T>
{
    /// <summary>
    /// Supported types for the serializer.
    /// </summary>
    /// <returns>A list of supported <see cref="FaunaType"/>s.</returns>
    public virtual List<FaunaType> GetSupportedTypes() => new List<FaunaType>();

    /// <summary>
    /// Gets the end token for a given start token.
    /// </summary>
    /// <param name="start">A start token.</param>
    /// <returns>The end token.</returns>
    /// <exception cref="ArgumentOutOfRangeException">Thrown when the start token does not have a related end token.</exception>
    protected static TokenType EndTokenFor(TokenType start)
    {
        return start switch
        {
            TokenType.StartObject => TokenType.EndObject,
            TokenType.StartArray => TokenType.EndArray,
            TokenType.StartPage => TokenType.EndPage,
            TokenType.StartRef => TokenType.EndRef,
            TokenType.StartDocument => TokenType.EndDocument,
            _ => throw new ArgumentOutOfRangeException(nameof(start), start, null)
        };
    }

    /// <summary>
    /// A helper to build an unsupported serialization type exception message.
    /// </summary>
    /// <param name="type">The unsupported type</param>
    /// <returns>An exception message to use.</returns>
    protected string UnsupportedSerializationTypeMessage(Type type) => $"Cannot serialize `{type}` with `{GetType()}`";

    /// <summary>
    /// A helper to build an unexpected type decoding exception message.
    /// </summary>
    /// <param name="faunaType">The unexpected fauna type.</param>
    /// <returns>An exception message to use.</returns>
    protected string UnexpectedTypeDecodingMessage(FaunaType faunaType) =>
        $"Unable to deserialize `{faunaType.GetType().Name}.{faunaType}` with `{GetType().Name}`. " +
        $"Supported types are [{string.Join(", ", GetSupportedTypes().Select(x => $"{x.GetType().Name}.{x}"))}]";

    object? ISerializer.Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        Deserialize(ctx, ref reader);

    /// <summary>
    /// Consumes or partially consumes the provided reader and deserializes into a result.
    /// </summary>
    /// <param name="ctx">A <see cref="MappingContext"/> to influence deserialization.</param>
    /// <param name="reader">A <see cref="Utf8FaunaReader"/> to consume or partially consume.</param>
    /// <returns></returns>
    public abstract T Deserialize(MappingContext ctx, ref Utf8FaunaReader reader);

    void ISerializer.Serialize(MappingContext context, Utf8FaunaWriter writer, object? o) =>
        Serialize(context, writer, o);

    /// <summary>
    /// Serializes the provided object onto the <see cref="Utf8FaunaWriter"/>
    /// </summary>
    /// <param name="context">A <see cref="MappingContext"/> to influence serialization.</param>
    /// <param name="writer">A <see cref="Utf8FaunaWriter"/> to write to.</param>
    /// <param name="o">The object to write.</param>
    public abstract void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o);

    /// <summary>
    /// Creates a serailization exception with an unexpected token exception message.
    /// </summary>
    /// <param name="token"></param>
    /// <returns></returns>
    protected static SerializationException UnexpectedToken(TokenType token) =>
        new($"Unexpected token while deserializing: {token}");
}
```

## File: Fauna/Serialization/ListSerializer.cs
```csharp
using System.Collections;
using Fauna.Exceptions;
using Fauna.Mapping;
using ArgumentException = System.ArgumentException;

namespace Fauna.Serialization;

internal class ListSerializer<T> : BaseSerializer<List<T>>
{
    private readonly ISerializer<T> _elemSerializer;

    public ListSerializer(ISerializer<T> elemSerializer)
    {
        _elemSerializer = elemSerializer;
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Array, FaunaType.Null };

    public override List<T> Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        if (reader.CurrentTokenType == TokenType.StartPage)
            throw new SerializationException(
            $"Unexpected token while deserializing into {typeof(List<T>)}: {reader.CurrentTokenType}");

        var wrapInList = reader.CurrentTokenType != TokenType.StartArray;

        var lst = new List<T>();

        if (wrapInList)
        {
            lst.Add(_elemSerializer.Deserialize(ctx, ref reader));
        }
        else
        {
            while (reader.Read() && reader.CurrentTokenType != TokenType.EndArray)
            {
                lst.Add(_elemSerializer.Deserialize(ctx, ref reader));
            }
        }

        return lst;
    }

    public override void Serialize(MappingContext ctx, Utf8FaunaWriter w, object? o)
    {
        if (o is null)
        {
            w.WriteNullValue();
            return;
        }

        if (o.GetType().IsGenericType &&
            o.GetType().GetGenericTypeDefinition() == typeof(List<>) ||
            o.GetType().GetGenericTypeDefinition() == typeof(IEnumerable))
        {
            w.WriteStartArray();
            foreach (object? elem in (IEnumerable)o)
            {
                _elemSerializer.Serialize(ctx, w, elem);
            }
            w.WriteEndArray();
            return;
        }

        throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
    }
}
```

## File: Fauna/Serialization/ModuleSerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;


internal class ModuleSerializer : BaseSerializer<Module>
{
    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Module, FaunaType.Null };

    public override Module Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Module => reader.GetModule(),
            _ => throw UnexpectedToken(reader.CurrentTokenType)
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case Module module:
                writer.WriteModuleValue(module);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }
}
```

## File: Fauna/Serialization/NullableSerializer.cs
```csharp
using Fauna.Mapping;

namespace Fauna.Serialization;

internal class NullableSerializer<T> : BaseSerializer<T?>
{
    private readonly ISerializer<T> _inner;

    public NullableSerializer(ISerializer<T> inner)
    {
        _inner = inner;
    }

    public override List<FaunaType> GetSupportedTypes() => _inner.GetSupportedTypes();

    public override T? Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        if (reader.CurrentTokenType == TokenType.Null)
        {
            return default(T);
        }

        return _inner.Deserialize(ctx, ref reader);
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        _inner.Serialize(context, writer, (T?)o);
    }
}
```

## File: Fauna/Serialization/NullableStructSerializer.cs
```csharp
using Fauna.Mapping;

namespace Fauna.Serialization;

internal class NullableStructSerializer<T> : BaseSerializer<T?> where T : struct
{
    private readonly ISerializer<T> _inner;

    public NullableStructSerializer(ISerializer<T> inner)
    {
        _inner = inner;
    }

    public override List<FaunaType> GetSupportedTypes() => _inner.GetSupportedTypes();

    public override T? Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        return reader.CurrentTokenType == TokenType.Null ? new T?() : _inner.Deserialize(ctx, ref reader);
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        _inner.Serialize(context, writer, (T?)o);
    }
}
```

## File: Fauna/Serialization/PageSerializer.cs
```csharp
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;

internal class PageSerializer<T> : BaseSerializer<Page<T>>
{
    private readonly ISerializer<List<T>> _dataSerializer;

    public PageSerializer(ISerializer<T> elemSerializer)
    {
        _dataSerializer = new ListSerializer<T>(elemSerializer);
    }

    public override List<FaunaType> GetSupportedTypes() => [FaunaType.Null, FaunaType.Set];

    public override Page<T> Deserialize(MappingContext ctx, ref Utf8FaunaReader reader)
    {
        bool wrapInPage = false;
        var endToken = TokenType.None;
        switch (reader.CurrentTokenType)
        {
            case TokenType.StartPage:
                endToken = TokenType.EndPage;
                break;
            case TokenType.StartObject:
                endToken = TokenType.EndObject;
                break;
            default:
                wrapInPage = true;
                break;
        }

        if (wrapInPage)
        {
            var data = _dataSerializer.Deserialize(ctx, ref reader);
            return new Page<T>(data, null);
        }

        reader.Read();
        return reader.CurrentTokenType == TokenType.String
            ? HandleUnmaterialized(ctx, ref reader, endToken)
            : HandleMaterialized(ctx, ref reader, endToken);
    }

    private Page<T> HandleUnmaterialized(MappingContext ctx, ref Utf8FaunaReader reader, TokenType endToken)
    {
        string after = reader.GetString()!;
        reader.Read();
        if (reader.CurrentTokenType != endToken)
        {
            throw UnexpectedToken(reader.CurrentTokenType);
        }

        return new Page<T>([], after);
    }

    private Page<T> HandleMaterialized(MappingContext ctx, ref Utf8FaunaReader reader, TokenType endToken)
    {
        List<T> data = [];
        string? after = null;

        do
        {
            string fieldName = reader.GetString()!;
            reader.Read();

            switch (fieldName)
            {
                case "data":
                    data = _dataSerializer.Deserialize(ctx, ref reader);
                    break;
                case "after":
                    after = reader.GetString()!;
                    break;
            }
        } while (reader.Read() && reader.CurrentTokenType != endToken);

        return new Page<T>(data, after);
    }

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        throw new NotImplementedException();
    }
}
```

## File: Fauna/Serialization/QueryArrSerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;

namespace Fauna.Serialization;

internal class QueryArrSerializer : BaseSerializer<QueryArr>
{
    public override QueryArr Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        throw new NotImplementedException();

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? obj)
    {
        switch (obj)
        {
            case null:
                writer.WriteNullValue();
                break;
            case QueryArr o:
                writer.WriteStartObject();
                writer.WriteFieldName("array");
                var ser = Serializer.Generate(context, o.Unwrap.GetType());
                ser.Serialize(context, writer, o.Unwrap);
                writer.WriteEndObject();
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(obj.GetType()));
        }
    }
}
```

## File: Fauna/Serialization/QueryExprSerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;


internal class QueryExprSerializer : BaseSerializer<QueryExpr>
{
    public override QueryExpr Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        throw new NotImplementedException();

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? obj)
    {
        switch (obj)
        {
            case null:
                writer.WriteNullValue();
                break;
            case QueryExpr o:
                writer.WriteStartObject();
                writer.WriteFieldName("fql");
                writer.WriteStartArray();
                foreach (var t in o.Unwrap)
                {
                    var ser = Serializer.Generate(context, t.GetType());
                    ser.Serialize(context, writer, t);
                }
                writer.WriteEndArray();
                writer.WriteEndObject();
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(obj.GetType()));
        }
    }
}
```

## File: Fauna/Serialization/QueryLiteralSerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;

namespace Fauna.Serialization;


internal class QueryLiteralSerializer : BaseSerializer<QueryLiteral>
{
    public override QueryLiteral Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        throw new NotImplementedException();

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? obj)
    {
        switch (obj)
        {
            case null:
                writer.WriteNullValue();
                break;
            case QueryLiteral o:
                writer.WriteStringValue(o.Unwrap);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(obj.GetType()));
        }
    }
}
```

## File: Fauna/Serialization/QueryObjSerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;

namespace Fauna.Serialization;


internal class QueryObjSerializer : BaseSerializer<QueryObj>
{
    public override QueryObj Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        throw new NotImplementedException();

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? obj)
    {
        switch (obj)
        {
            case null:
                writer.WriteNullValue();
                break;
            case QueryObj o:
                writer.WriteStartObject();
                writer.WriteFieldName("object");
                var ser = Serializer.Generate(context, o.Unwrap.GetType());
                ser.Serialize(context, writer, o.Unwrap);
                writer.WriteEndObject();
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(obj.GetType()));
        }
    }
}
```

## File: Fauna/Serialization/QuerySerializer.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;

namespace Fauna.Serialization;

internal class QuerySerializer : BaseSerializer<Query>
{
    public override Query Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        throw new NotImplementedException();

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? obj)
    {
        switch (obj)
        {
            case null:
                writer.WriteNullValue();
                break;
            case Query o:
                var ser = Serializer.Generate(context, o.GetType());
                ser.Serialize(context, writer, o);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(obj.GetType()));
        }
    }
}
```

## File: Fauna/Serialization/QueryValSerializer.cs
```csharp
using System.Diagnostics;
using Fauna.Exceptions;
using Fauna.Mapping;

namespace Fauna.Serialization;


internal class QueryValSerializer : BaseSerializer<QueryObj>
{
    public override QueryObj Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        throw new NotImplementedException();

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? obj)
    {
        switch (obj)
        {
            case null:
                writer.WriteNullValue();
                break;
            case QueryVal v:
                writer.WriteStartObject();
                writer.WriteFieldName("value");
                var ser = v.Unwrap is not null ? Serializer.Generate(context, v.Unwrap.GetType()) : DynamicSerializer.Singleton;
                ser.Serialize(context, writer, v.Unwrap);
                writer.WriteEndObject();
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(obj.GetType()));
        }
    }
}
```

## File: Fauna/Serialization/Serializer.cs
```csharp
using System.Runtime.CompilerServices;
using Fauna.Mapping;
using Fauna.Types;

namespace Fauna.Serialization;

/// <summary>
/// Represents methods for serializing objects to and from Fauna's value format.
/// </summary>
public static class Serializer
{
    /// <summary>
    /// The dynamic data serializer.
    /// </summary>
    public static ISerializer<object?> Dynamic => DynamicSerializer.Singleton;

    private static readonly Dictionary<Type, ISerializer> _reg = new();

    internal static readonly HashSet<string> Tags = new()
    {
        "@int", "@long", "@double", "@date", "@time", "@mod", "@stream", "@ref", "@doc", "@set", "@object", "@bytes"
    };

    private static readonly DynamicSerializer s_object = DynamicSerializer.Singleton;
    private static readonly StringSerializer s_string = new();
    private static readonly ByteSerializer s_byte = new();
    private static readonly BytesSerializer s_bytes = new();
    private static readonly SByteSerializer s_sbyte = new();
    private static readonly ShortSerializer s_short = new();
    private static readonly UShortSerializer s_ushort = new();
    private static readonly IntSerializer s_int = new();
    private static readonly UIntSerializer s_uint = new();
    private static readonly LongSerializer s_long = new();
    private static readonly FloatSerializer s_float = new();
    private static readonly DoubleSerializer s_double = new();
    private static readonly DateOnlySerializer s_dateOnly = new();
    private static readonly DateTimeSerializer s_dateTime = new();
    private static readonly DateTimeOffsetSerializer s_dateTimeOffset = new();
    private static readonly BooleanSerializer s_bool = new();
    private static readonly ModuleSerializer s_module = new();
    private static readonly EventSourceSerializer s_eventSource = new();
    private static readonly QuerySerializer s_query = new();
    private static readonly QueryExprSerializer s_queryExpr = new();
    private static readonly QueryLiteralSerializer s_queryLiteral = new();
    private static readonly QueryArrSerializer s_queryArr = new();
    private static readonly QueryObjSerializer s_queryObj = new();
    private static readonly QueryValSerializer s_queryVal = new();


    /// <summary>
    /// Generates a serializer for the specified non-nullable .NET type.
    /// </summary>
    /// <typeparam name="T">The type of the object to serialize.</typeparam>
    /// <param name="context">The serialization context.</param>
    /// <returns>An <see cref="ISerializer{T}"/>.</returns>
    public static ISerializer<T> Generate<T>(MappingContext context) where T : notnull
    {
        var targetType = typeof(T);
        var ser = (ISerializer<T>)Generate(context, targetType);
        return ser;
    }

    /// <summary>
    /// Generates a serializer for the specified non-nullable .NET type.
    /// </summary>
    /// <param name="context">The serialization context.</param>
    /// <param name="targetType">The type of the object to serialize.</param>
    /// <returns>An <see cref="ISerializer"/>.</returns>
    public static ISerializer Generate(MappingContext context, Type targetType)
    {
        if (_reg.TryGetValue(targetType, out var s)) return s;

        if (IsAnonymousType(targetType))
        {
            var info = context.GetInfo(targetType);
            return info.ClassSerializer;
        }

        if (targetType == typeof(object)) return s_object;
        if (targetType == typeof(string)) return s_string;
        if (targetType == typeof(byte)) return s_byte;
        if (targetType == typeof(byte[])) return s_bytes;
        if (targetType == typeof(sbyte)) return s_sbyte;
        if (targetType == typeof(short)) return s_short;
        if (targetType == typeof(ushort)) return s_ushort;
        if (targetType == typeof(int)) return s_int;
        if (targetType == typeof(uint)) return s_uint;
        if (targetType == typeof(long)) return s_long;
        if (targetType == typeof(float)) return s_float;
        if (targetType == typeof(double)) return s_double;
        if (targetType == typeof(DateOnly)) return s_dateOnly;
        if (targetType == typeof(DateTime)) return s_dateTime;
        if (targetType == typeof(DateTimeOffset)) return s_dateTimeOffset;
        if (targetType == typeof(bool)) return s_bool;
        if (targetType == typeof(Module)) return s_module;
        if (targetType == typeof(EventSource)) return s_eventSource;
        if (targetType == typeof(Query)) return s_query;
        if (targetType == typeof(QueryExpr)) return s_queryExpr;
        if (targetType == typeof(QueryLiteral)) return s_queryLiteral;
        if (targetType == typeof(QueryArr)) return s_queryArr;
        if (targetType == typeof(QueryObj)) return s_queryObj;
        if (targetType == typeof(QueryVal)) return s_queryVal;

        if (targetType.IsGenericType)
        {
            if (targetType.GetGenericTypeDefinition() == typeof(Nullable<>))
            {
                var args = targetType.GetGenericArguments();
                if (args.Length == 1)
                {
                    var inner = (ISerializer)Generate(context, args[0]);
                    var serType = typeof(NullableStructSerializer<>).MakeGenericType(new[] { args[0] });
                    object? ser = Activator.CreateInstance(serType, new[] { inner });

                    return (ISerializer)ser!;
                }

                throw new ArgumentException($"Unsupported nullable type. Generic arguments > 1: {args}");
            }


            if (targetType.GetGenericTypeDefinition() == typeof(Dictionary<,>))
            {
                var argTypes = targetType.GetGenericArguments();
                var keyType = argTypes[0];
                var valueType = argTypes[1];

                if (keyType != typeof(string))
                    throw new ArgumentException(
                        $"Unsupported Dictionary key type. Key must be of type string, but was a {keyType}");

                var valueSerializer = Generate(context, valueType);

                var serType = typeof(DictionarySerializer<>).MakeGenericType(new[] { valueType });
                object? ser = Activator.CreateInstance(serType, new[] { valueSerializer });

                return (ISerializer)ser!;
            }

            if (targetType.GetGenericTypeDefinition() == typeof(List<>) || targetType.GetGenericTypeDefinition() == typeof(IEnumerable<>))
            {
                var elemType = targetType.GetGenericArguments()[0];
                var elemSerializer = Generate(context, elemType);

                var serType = typeof(ListSerializer<>).MakeGenericType(new[] { elemType });
                object? ser = Activator.CreateInstance(serType, new[] { elemSerializer });

                return (ISerializer)ser!;
            }

            if (targetType.GetGenericTypeDefinition() == typeof(Page<>))
            {
                var elemType = targetType.GetGenericArguments()[0];
                var elemSerializer = Generate(context, elemType);

                var serType = typeof(PageSerializer<>).MakeGenericType(new[] { elemType });
                object? ser = Activator.CreateInstance(serType, new[] { elemSerializer });

                return (ISerializer)ser!;
            }

            if (targetType.GetGenericTypeDefinition() == typeof(BaseRef<>))
            {
                var docType = targetType.GetGenericArguments()[0];
                var docSerializer = Generate(context, docType);

                var serType = typeof(BaseRefSerializer<>).MakeGenericType(new[] { docType });
                object? ser = Activator.CreateInstance(serType, new[] { docSerializer });

                return (ISerializer)ser!;
            }

            if (targetType.GetGenericTypeDefinition() == typeof(Ref<>))
            {
                var docType = targetType.GetGenericArguments()[0];
                var docSerializer = Generate(context, docType);

                var serType = typeof(RefSerializer<>).MakeGenericType(new[] { docType });
                object? ser = Activator.CreateInstance(serType, new[] { docSerializer });

                return (ISerializer)ser!;
            }

            if (targetType.GetGenericTypeDefinition() == typeof(NamedRef<>))
            {
                var docType = targetType.GetGenericArguments()[0];
                var docSerializer = Generate(context, docType);

                var serType = typeof(NamedRefSerializer<>).MakeGenericType(new[] { docType });
                object? ser = Activator.CreateInstance(serType, new[] { docSerializer });

                return (ISerializer)ser!;
            }

            if (targetType.IsGenericType && targetType.Name.Contains("AnonymousType"))
            {
                return DynamicSerializer.Singleton;
            }
        }


        if (targetType.IsClass)
        {
            var info = context.GetInfo(targetType);
            return info.ClassSerializer;
        }

        throw new ArgumentException($"Unsupported deserialization target type {targetType}");
    }

    /// <summary>
    /// Generates a serializer which returns values of the specified .NET type, or the default if the underlying query value is null.
    /// </summary>
    /// <typeparam name="T">The type of the object to serialize.</typeparam>
    /// <param name="context">The serialization context.</param>
    /// <returns>An <see cref="ISerializer{T}"/>.</returns>
    public static ISerializer<T?> GenerateNullable<T>(MappingContext context)
    {
        var targetType = typeof(T);
        var ser = (ISerializer<T>)Generate(context, targetType);
        return new NullableSerializer<T>(ser);
    }

    /// <summary>
    /// Generates a serializer which returns values of the specified .NET type, or the default if the underlying query value is null.
    /// </summary>
    /// <param name="context">The serialization context.</param>
    /// <param name="targetType">The type of the object to serialize.</param>
    /// <returns>An <see cref="ISerializer"/>.</returns>
    public static ISerializer GenerateNullable(MappingContext context, Type targetType)
    {
        var inner = (ISerializer)Generate(context, targetType);
        var serType = typeof(NullableSerializer<>).MakeGenericType(new[] { targetType });
        var ser = Activator.CreateInstance(serType, new[] { inner });

        return (ISerializer)ser!;
    }

    /// <summary>
    /// Registers a serializer for a type. This serializer will take precedence over the default serializer for the that type.
    /// </summary>
    /// <param name="t">The type to associate with the serializer.</param>
    /// <param name="s">The serializer.</param>
    /// <exception cref="ArgumentException">Throws if a serializer is already registered for the type.</exception>
    public static void Register(Type t, ISerializer s)
    {
        if (!_reg.TryAdd(t, s)) throw new ArgumentException($"Serializer for type `{t}` already registered");
    }

    /// <summary>
    /// Registers a generic serializer. This serializer will take precedence over the default serializer for the that type.
    /// </summary>
    /// <param name="s">The generic serializer.</param>
    /// <exception cref="ArgumentException">Throws if a serializer is already registered for the type.</exception>
    public static void Register<T>(ISerializer<T> s)
    {
        var success = false;
        foreach (var i in s.GetType().GetInterfaces())
        {
            if (!i.IsGenericType || i.GetGenericTypeDefinition() != typeof(ISerializer<>)) continue;

            var t = i.GetGenericArguments()[0];
            success = _reg.TryAdd(t, s);
            if (!success) throw new ArgumentException($"Serializer for type `{t}` already registered");
            break;
        }

        if (!success) throw new ArgumentException($"Could not infer associated type for `{s.GetType()}`. Use Register(type, serializer).");
    }

    /// <summary>
    /// Deregisters a serializer for a type. If no serializer was registered, no-op.
    /// </summary>
    /// <param name="t">The associated type to deregister.</param>
    public static void Deregister(Type t)
    {
        if (_reg.ContainsKey(t)) _reg.Remove(t);
    }

    private static bool IsAnonymousType(this Type type)
    {
        bool hasCompilerGeneratedAttribute = type.GetCustomAttributes(typeof(CompilerGeneratedAttribute), false).Any();
        bool nameContainsAnonymousType = type?.FullName?.Contains("AnonymousType") ?? false;
        return hasCompilerGeneratedAttribute && nameContainsAnonymousType;
    }
}
```

## File: Fauna/Serialization/StructSerializers.cs
```csharp
using Fauna.Exceptions;
using Fauna.Mapping;

namespace Fauna.Serialization;


internal class StringSerializer : BaseSerializer<string?>
{
    public override string? Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Null => null,
            TokenType.String => reader.GetString(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case string s:
                writer.WriteStringValue(s);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.String };
}

internal class ByteSerializer : BaseSerializer<byte>
{
    public override byte Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int => reader.GetByte(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case byte i:
                writer.WriteIntValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Int, FaunaType.Null };
}

internal class BytesSerializer : BaseSerializer<byte[]>
{
    public override byte[] Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Bytes => reader.GetBytes(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case byte[] b:
                writer.WriteBytesValue(b);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Bytes, FaunaType.Null };
}

internal class SByteSerializer : BaseSerializer<sbyte>
{
    public override sbyte Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int => reader.GetUnsignedByte(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case sbyte i:
                writer.WriteIntValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Int, FaunaType.Null };
}


internal class ShortSerializer : BaseSerializer<short>
{
    public override short Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int => reader.GetShort(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case short i:
                writer.WriteIntValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Int, FaunaType.Null };
}

internal class UShortSerializer : BaseSerializer<ushort>
{
    public override ushort Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int => reader.GetUnsignedShort(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case ushort i:
                writer.WriteIntValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Int, FaunaType.Null };
}

internal class IntSerializer : BaseSerializer<int>
{
    public override int Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int => reader.GetInt(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case int i:
                writer.WriteIntValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Int, FaunaType.Null };
}

internal class UIntSerializer : BaseSerializer<uint>
{
    public override uint Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int or TokenType.Long => reader.GetUnsignedInt(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case uint i:
                writer.WriteLongValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Int, FaunaType.Long, FaunaType.Null };
}

internal class LongSerializer : BaseSerializer<long>
{
    public override long Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int or TokenType.Long => reader.GetLong(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case long i:
                writer.WriteLongValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Int, FaunaType.Long, FaunaType.Null };
}

internal class FloatSerializer : BaseSerializer<float>
{
    public override float Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int or TokenType.Long or TokenType.Double => reader.GetFloat(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case float i:
                writer.WriteDoubleValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }


    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Double, FaunaType.Int, FaunaType.Long, FaunaType.Null };
}

internal class DoubleSerializer : BaseSerializer<double>
{
    public override double Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Int or TokenType.Long or TokenType.Double => reader.GetDouble(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case double i:
                writer.WriteDoubleValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Double, FaunaType.Int, FaunaType.Long, FaunaType.Null };
}

internal class BooleanSerializer : BaseSerializer<bool>
{
    public override bool Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.True or TokenType.False => reader.GetBoolean(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case bool i:
                writer.WriteBooleanValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Boolean, FaunaType.Null };
}

internal class DateOnlySerializer : BaseSerializer<DateOnly>
{
    public override DateOnly Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Date => reader.GetDate(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case DateOnly i:
                writer.WriteDateValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Date, FaunaType.Null };
}

internal class DateTimeSerializer : BaseSerializer<DateTime>
{
    public override DateTime Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Time => reader.GetTime(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case DateTime i:
                writer.WriteTimeValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.Time };
}

internal class DateTimeOffsetSerializer : BaseSerializer<DateTimeOffset>
{
    public override DateTimeOffset Deserialize(MappingContext ctx, ref Utf8FaunaReader reader) =>
        reader.CurrentTokenType switch
        {
            TokenType.Time => reader.GetTime(),
            _ => throw new SerializationException(UnexpectedTypeDecodingMessage(reader.CurrentTokenType.GetFaunaType()))
        };

    public override void Serialize(MappingContext context, Utf8FaunaWriter writer, object? o)
    {
        switch (o)
        {
            case null:
                writer.WriteNullValue();
                break;
            case DateTimeOffset i:
                writer.WriteTimeValue(i);
                break;
            default:
                throw new SerializationException(UnsupportedSerializationTypeMessage(o.GetType()));
        }
    }

    public override List<FaunaType> GetSupportedTypes() => new List<FaunaType> { FaunaType.Null, FaunaType.Time };
}
```

## File: Fauna/Serialization/TokenType.cs
```csharp
namespace Fauna.Serialization;

/// <summary>
/// Enumerates the types of tokens used in Fauna serialization.
/// </summary>
public enum TokenType
{
    /// <summary>There is no value. This is the default token type if no data has been read by the <see cref="T:Fauna.Serialization.Utf8FaunaReader" />.</summary>
    None,

    /// <summary>The token type is the start of a Fauna object.</summary>
    StartObject,
    /// <summary>The token type is the end of a Fauna object.</summary>
    EndObject,

    /// <summary>The token type is the start of a Fauna array.</summary>
    StartArray,
    /// <summary>The token type is the end of a Fauna array.</summary>
    EndArray,

    /// <summary>The token type is the start of a Fauna set (a.k.a. page).</summary>
    StartPage,
    /// <summary>The token type is the end of a Fauna set (a.k.a. page).</summary>
    EndPage,

    /// <summary>The token type is the start of a Fauna ref.</summary>
    StartRef,
    /// <summary>The token type is the end of a Fauna ref.</summary>
    EndRef,

    /// <summary>The token type is the start of a Fauna document.</summary>
    StartDocument,
    /// <summary>The token type is the end of a Fauna document.</summary>
    EndDocument,

    /// <summary>The token type is a Fauna property name.</summary>
    FieldName,

    /// <summary>The token type is a Fauna string.</summary>
    String,
    /// <summary>The token type is a Fauna byte array.</summary>
    Bytes,

    /// <summary>The token type is a Fauna integer.</summary>
    Int,
    /// <summary>The token type is a Fauna long.</summary>
    Long,
    /// <summary>The token type is a Fauna double.</summary>
    Double,

    /// <summary>The token type is a Fauna date.</summary>
    Date,
    /// <summary>The token type is a Fauna time.</summary>
    Time,

    /// <summary>The token type is the Fauna literal true.</summary>
    True,
    /// <summary>The token type is the Fauna literal false.</summary>
    False,

    /// <summary>The token type is the Fauna literal null.</summary>
    Null,

    /// <summary>The token type is the Fauna module.</summary>
    Module,

    /// <summary>The token type is the Fauna event source token.</summary>
    EventSource,
}

/// <summary>
/// A set of extension methods that operate on <see cref="TokenType"/>.
/// </summary>
public static class TokenTypeExtensions
{
    /// <summary>
    /// Maps a <see cref="TokenType"/> to a <see cref="FaunaType"/>.
    /// </summary>
    /// <param name="tokenType">The token type to map to a Fauna type.</param>
    /// <returns>The related Fauna type.</returns>
    /// <exception cref="ArgumentException">Thrown when the provided token type does not map to a Fauna type.</exception>
    public static FaunaType GetFaunaType(this TokenType tokenType)
    {
        switch (tokenType)
        {
            case TokenType.StartObject:
            case TokenType.EndObject:
                return FaunaType.Object;

            case TokenType.StartArray:
            case TokenType.EndArray:
                return FaunaType.Array;

            case TokenType.StartPage:
            case TokenType.EndPage:
                return FaunaType.Set;

            case TokenType.StartRef:
            case TokenType.EndRef:
                return FaunaType.Ref;

            case TokenType.StartDocument:
            case TokenType.EndDocument:
                return FaunaType.Document;

            case TokenType.String:
                return FaunaType.String;
            case TokenType.Bytes:
                return FaunaType.Bytes;
            case TokenType.Int:
                return FaunaType.Int;
            case TokenType.Long:
                return FaunaType.Long;
            case TokenType.Double:
                return FaunaType.Double;
            case TokenType.Date:
                return FaunaType.Date;
            case TokenType.Time:
                return FaunaType.Time;
            case TokenType.True:
            case TokenType.False:
                return FaunaType.Boolean;
            case TokenType.Null:
                return FaunaType.Null;
            case TokenType.EventSource:
                return FaunaType.Stream;
            case TokenType.Module:
                return FaunaType.Module;
            default:
                throw new ArgumentException($"No associated FaunaType for TokenType: {tokenType}");
        }
    }
}
```

## File: Fauna/Serialization/Utf8FaunaReader.cs
```csharp
using System.Buffers;
using System.Globalization;
using System.Text;
using System.Text.Json;
using Fauna.Exceptions;
using Fauna.Types;

namespace Fauna.Serialization;

/// <summary>
/// Represents a reader that provides fast, non-cached, forward-only access to serialized data.
/// </summary>
public ref struct Utf8FaunaReader
{
    private Utf8JsonReader _json;
    private readonly Stack<object> _tokenStack = new();
    private TokenType? _bufferedTokenType = null;
    private object? _bufferedTokenValue = null;

    private readonly HashSet<TokenType> _closers = new()
    {
        TokenType.EndObject,
        TokenType.EndPage,
        TokenType.EndDocument,
        TokenType.EndRef,
        TokenType.EndArray
    };

    private string? _taggedTokenValue = null;

    /// <summary>
    /// Gets the type of the current token.
    /// </summary>
    public TokenType CurrentTokenType { get; private set; }

    private enum TokenTypeInternal
    {
        /// <summary>The token type is the start of an escaped Fauna object.</summary>
        StartEscapedObject,
        StartPageUnmaterialized,
    }

    /// <summary>
    /// Initializes a new Utf8FaunaReader to read from a ReadOnlySequence of bytes.
    /// </summary>
    /// <param name="bytes">The sequence of bytes to read from.</param>
    public Utf8FaunaReader(ReadOnlySequence<byte> bytes)
    {
        _json = new Utf8JsonReader(bytes);
        CurrentTokenType = TokenType.None;
    }

    /// <summary>
    /// Initializes a new Utf8FaunaReader to read from a string.
    /// </summary>
    /// <param name="str">The string to read from.</param>
    public Utf8FaunaReader(string str)
    {
        var bytes = Encoding.UTF8.GetBytes(str);
        var seq = new ReadOnlySequence<byte>(bytes);
        _json = new Utf8JsonReader(seq);
        CurrentTokenType = TokenType.None;
    }

    /// <summary>
    /// Skips the value of the current token.
    /// </summary>
    public void Skip()
    {
        switch (CurrentTokenType)
        {
            case TokenType.StartObject:
            case TokenType.StartArray:
            case TokenType.StartPage:
            case TokenType.StartRef:
            case TokenType.StartDocument:
                SkipInternal();
                break;
        }
    }

    private void SkipInternal()
    {
        var startCount = _tokenStack.Count;
        while (Read())
        {
            if (_tokenStack.Count < startCount) break;
        }
    }

    /// <summary>
    /// Reads the next token from the source.
    /// </summary>
    /// <returns>true if the token was read successfully; otherwise, false.</returns>
    public bool Read()
    {
        _taggedTokenValue = null;

        if (_bufferedTokenType != null)
        {
            CurrentTokenType = (TokenType)_bufferedTokenType;
            _bufferedTokenType = null;
            if (_closers.Contains(CurrentTokenType))
            {
                _tokenStack.Pop();
            }
            return true;
        }

        // At this point we're passed a buffered token type so this read should unset this no matter what
        _bufferedTokenValue = null;

        if (!Advance())
        {
            return false;
        }

        switch (_json.TokenType)
        {
            case JsonTokenType.PropertyName:
                CurrentTokenType = TokenType.FieldName;
                break;
            case JsonTokenType.None:
                break;
            case JsonTokenType.StartObject:
                HandleStartObject();
                break;
            case JsonTokenType.EndObject:
                HandleEndObject();
                break;
            case JsonTokenType.StartArray:
                _tokenStack.Push(TokenType.StartArray);
                CurrentTokenType = TokenType.StartArray;
                break;
            case JsonTokenType.EndArray:
                _tokenStack.Pop();
                CurrentTokenType = TokenType.EndArray;
                break;
            case JsonTokenType.String:
                CurrentTokenType = TokenType.String;
                break;
            case JsonTokenType.True:
                CurrentTokenType = TokenType.True;
                break;
            case JsonTokenType.False:
                CurrentTokenType = TokenType.False;
                break;
            case JsonTokenType.Null:
                CurrentTokenType = TokenType.Null;
                break;
            case JsonTokenType.Comment:
            case JsonTokenType.Number:
            default:
                throw new SerializationException($"Unhandled JSON token type {_json.TokenType}.");
        }

        return true;
    }

    /// <summary>
    /// Gets the value of the current token.
    /// </summary>
    /// <returns>The value of the current token, or null if no value is associated with the token.</returns>
    /// <exception cref="SerializationException">Thrown when an error occurs during token value retrieval.</exception>
    public object? GetValue()
    {
        return CurrentTokenType switch
        {
            TokenType.FieldName or TokenType.String => GetString(),
            TokenType.Int => GetInt(),
            TokenType.Long => GetLong(),
            TokenType.Double => GetDouble(),
            TokenType.Date => GetDate(),
            TokenType.Time => GetTime(),
            TokenType.True or TokenType.False => GetBoolean(),
            TokenType.Module => GetModule(),
            TokenType.Bytes => GetBytes(),
            _ => throw new SerializationException($"{CurrentTokenType} does not have an associated value")
        };
    }

    /// <summary>
    /// Retrieves a string value from the current token.
    /// </summary>
    /// <returns>A string representation of the current token's value.</returns>
    public string? GetString()
    {
        if (CurrentTokenType != TokenType.String && CurrentTokenType != TokenType.FieldName)
        {
            throw new InvalidOperationException($"Fauna token value isn't a {TokenType.String.ToString()} or a {TokenType.FieldName.ToString()}.");
        }

        try
        {
            if (_bufferedTokenValue != null) return (string)_bufferedTokenValue;
            return _json.GetString();
        }
        catch (Exception e)
        {
            throw new SerializationException("Failed to get string", e);
        }
    }

    /// <summary>
    /// Retrieves a boolean value from the current JSON token.
    /// </summary>
    /// <returns>A boolean representation of the current token's value.</returns>
    public bool GetBoolean()
    {
        try
        {
            return _json.GetBoolean();
        }
        catch (Exception e)
        {
            throw new SerializationException("Failed to get boolean", e);
        }
    }

    /// <summary>
    /// Retrieves a DateOnly value from the current token.
    /// </summary>
    /// <returns>A DateOnly representation of the current token's value.</returns>
    public DateOnly GetDate()
    {
        ValidateTaggedType(TokenType.Date);

        try
        {
            return DateOnly.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get date from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves a float value from the current token.
    /// </summary>
    /// <returns>A float representation of the current token's value.</returns>
    public float GetFloat()
    {
        ValidateTaggedTypes(TokenType.Int, TokenType.Long, TokenType.Double);

        try
        {
            return float.Parse(_taggedTokenValue!, CultureInfo.InvariantCulture);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get float from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves a double value from the current token.
    /// </summary>
    /// <returns>A double representation of the current token's value.</returns>
    public double GetDouble()
    {
        ValidateTaggedTypes(TokenType.Int, TokenType.Long, TokenType.Double);

        try
        {
            return double.Parse(_taggedTokenValue!, CultureInfo.InvariantCulture);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get double from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves a decimal value from the current token.
    /// </summary>
    /// <returns>A decimal representation of the current token's value.</returns>
    public decimal GetDoubleAsDecimal()
    {
        ValidateTaggedType(TokenType.Double);

        try
        {
            return decimal.Parse(_taggedTokenValue!, CultureInfo.InvariantCulture);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get decimal from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves an byte value from the current token.
    /// </summary>
    /// <returns>A byte representation of the current token's value.</returns>
    public byte GetByte()
    {
        ValidateTaggedTypes(TokenType.Int);

        try
        {
            return byte.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get byte from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves a byte array value from the current token.
    /// </summary>
    /// <returns>A byte array representation of the current token's value.</returns>
    public byte[] GetBytes()
    {
        ValidateTaggedTypes(TokenType.Bytes);

        try
        {
            return Convert.FromBase64String(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get byte array from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves an unsigned byte value from the current token.
    /// </summary>
    /// <returns>An unsigned byte representation of the current token's value.</returns>
    public sbyte GetUnsignedByte()
    {
        ValidateTaggedTypes(TokenType.Int);

        try
        {
            return sbyte.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get sbyte from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves an integer value from the current token.
    /// </summary>
    /// <returns>An integer representation of the current token's value.</returns>
    public int GetInt()
    {
        ValidateTaggedTypes(TokenType.Int, TokenType.Long);

        try
        {
            return int.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get int from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves an unsigned integer value from the current token.
    /// </summary>
    /// <returns>An unsigned integer representation of the current token's value.</returns>
    public uint GetUnsignedInt()
    {
        ValidateTaggedTypes(TokenType.Int, TokenType.Long);

        try
        {
            return uint.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get uint from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves an short value from the current token.
    /// </summary>
    /// <returns>An short representation of the current token's value.</returns>
    public short GetShort()
    {
        ValidateTaggedTypes(TokenType.Int, TokenType.Long);
        try
        {
            return short.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get short from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves an unsigned short value from the current token.
    /// </summary>
    /// <returns>An unsigned short representation of the current token's value.</returns>
    public ushort GetUnsignedShort()
    {
        ValidateTaggedTypes(TokenType.Int, TokenType.Long);
        try
        {
            return ushort.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get ushort from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves a long value from the current token.
    /// </summary>
    /// <returns>A long representation of the current token's value.</returns>
    public long GetLong()
    {
        ValidateTaggedTypes(TokenType.Int, TokenType.Long);

        try
        {
            return long.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get long from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Retrieves a Module object from the current token.
    /// </summary>
    /// <returns>A Module representation of the current token's value.</returns>
    public Module GetModule()
    {
        ValidateTaggedType(TokenType.Module);

        return new Module(_taggedTokenValue!);
    }

    /// <summary>
    /// Retrieves an EventSource token string from the current token.
    /// </summary>
    /// <returns>A EventSource of the current token's value.</returns>
    public EventSource GetEventSource()
    {
        ValidateTaggedType(TokenType.EventSource);

        return new EventSource(_taggedTokenValue!);
    }

    /// <summary>
    /// Retrieves a DateTime value from the current token.
    /// </summary>
    /// <returns>A DateTime representation of the current token's value.</returns>
    public DateTime GetTime()
    {
        ValidateTaggedType(TokenType.Time);

        try
        {
            return DateTime.Parse(_taggedTokenValue!);
        }
        catch (Exception e)
        {
            throw new SerializationException($"Failed to get time from {_taggedTokenValue}", e);
        }
    }

    /// <summary>
    /// Tries to retrieve a string value from the current token.
    /// </summary>
    /// <param name="value">When this method returns, contains the string value, if the conversion succeeded, or null if the conversion failed.</param>
    /// <returns>true if the token's value could be converted to a string; otherwise, false.</returns>
    public string TryGetString(out string value)
    {
        throw new NotImplementedException();
    }

    /// <summary>
    /// Tries to retrieve a boolean value from the current token.
    /// </summary>
    /// <param name="value">When this method returns, contains the boolean value, if the conversion succeeded, or false if the conversion failed.</param>
    /// <returns>true if the token's value could be converted to a boolean; otherwise, false.</returns>
    public bool TryGetBoolean(out bool value)
    {
        throw new NotImplementedException();
    }

    /// <summary>
    /// Tries to retrieve a DateTime value from the current token.
    /// </summary>
    /// <param name="value">When this method returns, contains the DateTime value, if the conversion succeeded, or the default DateTime value if the conversion failed.</param>
    /// <returns>true if the token's value could be converted to a DateTime; otherwise, false.</returns>
    public DateTime TryGetDateTime(out DateTime value)
    {
        throw new NotImplementedException();
    }

    /// <summary>
    /// Tries to retrieve a double value from the current token.
    /// </summary>
    /// <param name="value">When this method returns, contains the double value, if the conversion succeeded, or 0.0 if the conversion failed.</param>
    /// <returns>true if the token's value could be converted to a double; otherwise, false.</returns>
    public double TryGetDouble(out double value)
    {
        throw new NotImplementedException();
    }

    /// <summary>
    /// Tries to retrieve an integer value from the current token.
    /// </summary>
    /// <param name="value">When this method returns, contains the integer value, if the conversion succeeded, or 0 if the conversion failed.</param>
    /// <returns>true if the token's value could be converted to an integer; otherwise, false.</returns>
    public int TryGetInt(out int value)
    {
        throw new NotImplementedException();
    }

    /// <summary>
    /// Tries to retrieve a long value from the current token.
    /// </summary>
    /// <param name="value">When this method returns, contains the long value, if the conversion succeeded, or 0 if the conversion failed.</param>
    /// <returns>true if the token's value could be converted to a long; otherwise, false.</returns>
    public long TryGetLong(out long value)
    {
        throw new NotImplementedException();
    }

    /// <summary>
    /// Tries to retrieve a Module object from the current token.
    /// </summary>
    /// <param name="value">When this method returns, contains the Module object, if the conversion succeeded, or null if the conversion failed.</param>
    /// <returns>true if the token's value could be converted to a Module; otherwise, false.</returns>
    public Module TryGetModule(out Module value)
    {
        throw new NotImplementedException();
    }

    private void ValidateTaggedType(TokenType type)
    {
        if (CurrentTokenType != type || _taggedTokenValue == null || _taggedTokenValue.GetType() != typeof(string))
        {
            throw new InvalidOperationException($"CurrentTokenType is a {CurrentTokenType.ToString()}, not a {type.ToString()}.");
        }
    }

    private void ValidateTaggedTypes(params TokenType[] types)
    {
        if (!types.Contains(CurrentTokenType) || _taggedTokenValue == null || _taggedTokenValue.GetType() != typeof(string))
        {
            throw new InvalidOperationException($"CurrentTokenType is a {CurrentTokenType.ToString()}, not in {types}.");
        }
    }


    private void HandleStartObject()
    {
        AdvanceTrue();

        switch (_json.TokenType)
        {
            case JsonTokenType.PropertyName:
                switch (_json.GetString())
                {
                    case "@date":
                        HandleTaggedString(TokenType.Date);
                        break;
                    case "@doc":
                        AdvanceTrue();
                        CurrentTokenType = TokenType.StartDocument;
                        _tokenStack.Push(TokenType.StartDocument);
                        break;
                    case "@double":
                        HandleTaggedString(TokenType.Double);
                        break;
                    case "@int":
                        HandleTaggedString(TokenType.Int);
                        break;
                    case "@long":
                        HandleTaggedString(TokenType.Long);
                        break;
                    case "@mod":
                        HandleTaggedString(TokenType.Module);
                        break;
                    case "@stream":
                        HandleTaggedString(TokenType.EventSource);
                        break;
                    case "@object":
                        AdvanceTrue();
                        CurrentTokenType = TokenType.StartObject;
                        _tokenStack.Push(TokenTypeInternal.StartEscapedObject);
                        break;
                    case "@ref":
                        AdvanceTrue();
                        CurrentTokenType = TokenType.StartRef;
                        _tokenStack.Push(TokenType.StartRef);
                        break;
                    case "@set":
                        AdvanceTrue();
                        CurrentTokenType = TokenType.StartPage;
                        if (_json.TokenType == JsonTokenType.String)
                        {
                            _bufferedTokenValue = _json.GetString();
                            _bufferedTokenType = TokenType.String;
                            _tokenStack.Push(TokenTypeInternal.StartPageUnmaterialized);
                        }
                        else
                        {
                            _tokenStack.Push(TokenType.StartPage);
                        }
                        break;
                    case "@time":
                        HandleTaggedString(TokenType.Time);
                        break;
                    case "@bytes":
                        HandleTaggedString(TokenType.Bytes);
                        break;
                    default:
                        _bufferedTokenType = TokenType.FieldName;
                        _tokenStack.Push(TokenType.StartObject);
                        CurrentTokenType = TokenType.StartObject;
                        break;
                }
                break;
            case JsonTokenType.EndObject:
                _bufferedTokenType = TokenType.EndObject;
                _tokenStack.Push(TokenType.StartObject);
                CurrentTokenType = TokenType.StartObject;
                break;
            default:
                throw new SerializationException($"Unexpected token following StartObject: {_json.TokenType}");
        }
    }

    private void HandleEndObject()
    {
        var startToken = _tokenStack.Pop();
        switch (startToken)
        {
            case TokenType.StartDocument:
                CurrentTokenType = TokenType.EndDocument;
                AdvanceTrue();
                break;
            case TokenType.StartPage:
                CurrentTokenType = TokenType.EndPage;
                AdvanceTrue();
                break;
            case TokenTypeInternal.StartPageUnmaterialized:
                CurrentTokenType = TokenType.EndPage;
                break;
            case TokenType.StartRef:
                CurrentTokenType = TokenType.EndRef;
                AdvanceTrue();
                break;
            case TokenTypeInternal.StartEscapedObject:
                CurrentTokenType = TokenType.EndObject;
                AdvanceTrue();
                break;
            case TokenType.StartObject:
                CurrentTokenType = TokenType.EndObject;
                break;
            default:
                throw new SerializationException($"Unexpected token {startToken}. This might be a bug.");
        }
    }

    /// <summary>
    /// Method <c>HandleTaggedString</c> is used to advance through a JSON object that represents a tagged type with a
    /// a string value. For example:
    ///
    /// * Given { "@int": "123" }
    /// * Read JSON until JsonTokenType.PropertyName and you've determined it's an int
    /// * Call HandleTaggedString(TokenType.Int)
    /// * The underlying JSON reader is advanced until JsonTokenType.EndObject
    /// * Access the int via GetInt()
    ///
    /// </summary>
    private void HandleTaggedString(TokenType token)
    {
        AdvanceTrue();
        CurrentTokenType = token;
        _taggedTokenValue = _json.GetString();
        AdvanceTrue();
    }

    private bool Advance()
    {
        try
        {
            return _json.Read();
        }
        catch (Exception e)
        {
            throw new SerializationException("Failed to advance underlying JSON reader.", e);
        }
    }

    private void AdvanceTrue()
    {
        if (!Advance())
        {
            throw new SerializationException("Unexpected end of underlying JSON reader.");
        }
    }
}
```

## File: Fauna/Serialization/Utf8FaunaWriter.cs
```csharp
using System.Buffers;
using System.Globalization;
using System.Text.Json;
using Fauna.Types;
using Stream = System.IO.Stream;

namespace Fauna.Serialization;

/// <summary>
/// Provides functionality for writing data in a streaming manner to a buffer or a stream.
/// </summary>
public sealed class Utf8FaunaWriter : IAsyncDisposable, IDisposable
{
    private readonly Utf8JsonWriter _writer;

    /// <summary>
    /// Initializes a new instance of the Utf8FaunaWriter class with a specified buffer writer.
    /// </summary>
    /// <param name="bufferWriter">The buffer writer to write to.</param>
    public Utf8FaunaWriter(IBufferWriter<byte> bufferWriter)
    {
        _writer = new Utf8JsonWriter(bufferWriter);
    }

    /// <summary>
    /// Initializes a new instance of the Utf8FaunaWriter class with a specified stream.
    /// </summary>
    /// <param name="stream">The stream to write to.</param>
    public Utf8FaunaWriter(Stream stream)
    {
        _writer = new Utf8JsonWriter(stream);
    }

    /// <summary>
    /// Flushes the written data to the underlying buffer or stream.
    /// </summary>
    public void Flush()
    {
        _writer.Flush();
    }

    /// <summary>
    /// Asynchronously flushes the written data to the underlying buffer or stream.
    /// </summary>
    public async ValueTask FlushAsync()
    {
        await _writer.FlushAsync();
    }

    /// <summary>
    /// Disposes the underlying writer.
    /// </summary>
    public void Dispose()
    {
        _writer.Dispose();
    }

    /// <summary>
    /// Asynchronously disposes the underlying writer.
    /// </summary>
    public async ValueTask DisposeAsync()
    {
        await _writer.DisposeAsync();
    }

    /// <summary>
    /// Writes the beginning of an object.
    /// </summary>
    public void WriteStartObject()
    {
        _writer.WriteStartObject();
    }

    /// <summary>
    /// Writes the end of an object.
    /// </summary>
    public void WriteEndObject()
    {
        _writer.WriteEndObject();
    }

    /// <summary>
    /// Writes the beginning of a specially tagged object.
    /// </summary>
    public void WriteStartEscapedObject()
    {
        _writer.WriteStartObject();
        WriteFieldName("@object");
        _writer.WriteStartObject();
    }

    /// <summary>
    /// Writes the end of a specially tagged object.
    /// </summary>
    public void WriteEndEscapedObject()
    {
        _writer.WriteEndObject();
        _writer.WriteEndObject();
    }

    /// <summary>
    /// Writes the beginning of an array.
    /// </summary>
    public void WriteStartArray()
    {
        _writer.WriteStartArray();
    }

    /// <summary>
    /// Writes the end of an array.
    /// </summary>
    public void WriteEndArray()
    {
        _writer.WriteEndArray();
    }

    /// <summary>
    /// Writes the beginning of a reference object.
    /// </summary>
    public void WriteStartRef()
    {
        _writer.WriteStartObject();
        WriteFieldName("@ref");
        _writer.WriteStartObject();
    }

    /// <summary>
    /// Writes the end of a reference object.
    /// </summary>
    public void WriteEndRef()
    {
        _writer.WriteEndObject();
        _writer.WriteEndObject();
    }

    /// <summary>
    /// Writes a double value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The decimal value to write.</param>
    public void WriteDouble(string fieldName, decimal value)
    {
        WriteFieldName(fieldName);
        WriteDoubleValue(value);
    }

    /// <summary>
    /// Writes a double value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The double value to write.</param>
    public void WriteDouble(string fieldName, double value)
    {
        WriteFieldName(fieldName);
        WriteDoubleValue(value);
    }

    /// <summary>
    /// Writes an integer value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The integer value to write.</param>
    public void WriteInt(string fieldName, int value)
    {
        WriteFieldName(fieldName);
        WriteIntValue(value);
    }

    /// <summary>
    /// Writes a long integer value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The long integer value to write.</param>
    public void WriteLong(string fieldName, long value)
    {
        WriteFieldName(fieldName);
        WriteLongValue(value);
    }

    /// <summary>
    /// Writes a byte array value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The byte array value to write.</param>
    public void WriteBytes(string fieldName, byte[] value)
    {
        WriteFieldName(fieldName);
        WriteBytesValue(value);
    }

    /// <summary>
    /// Writes a string value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The string value to write.</param>
    public void WriteString(string fieldName, string value)
    {
        WriteFieldName(fieldName);
        WriteStringValue(value);
    }

    /// <summary>
    /// Writes a date value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The DateTime value to write.</param>
    public void WriteDate(string fieldName, DateTime value)
    {
        WriteFieldName(fieldName);
        WriteDateValue(value);
    }

    /// <summary>
    /// Writes a time value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The DateTime value to write.</param>
    public void WriteTime(string fieldName, DateTime value)
    {
        WriteFieldName(fieldName);
        WriteTimeValue(value);
    }

    /// <summary>
    /// Writes a boolean value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The boolean value to write.</param>
    public void WriteBoolean(string fieldName, bool value)
    {
        WriteFieldName(fieldName);
        WriteBooleanValue(value);

    }

    /// <summary>
    /// Writes a null value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    public void WriteNull(string fieldName)
    {
        WriteFieldName(fieldName);
        WriteNullValue();
    }

    /// <summary>
    /// Writes a module value with a specific field name.
    /// </summary>
    /// <param name="fieldName">The name of the field.</param>
    /// <param name="value">The module value to write.</param>
    public void WriteModule(string fieldName, Module value)
    {
        WriteFieldName(fieldName);
        WriteModuleValue(value);
    }

    /// <summary>
    /// Writes a field name for the next value.
    /// </summary>
    /// <param name="value">The name of the field.</param>
    public void WriteFieldName(string value)
    {
        _writer.WritePropertyName(value);
    }

    /// <summary>
    /// Writes a tagged value in an object.
    /// </summary>
    /// <param name="tag">The tag to use for the value.</param>
    /// <param name="value">The value associated with the tag.</param>
    public void WriteTaggedValue(string tag, string value)
    {
        WriteStartObject();
        WriteString(tag, value);
        WriteEndObject();
    }

    /// <summary>
    /// Writes a double value as a tagged element.
    /// </summary>
    /// <param name="value">The double value to write.</param>
    public void WriteDoubleValue(decimal value)
    {
        WriteTaggedValue("@double", value.ToString(CultureInfo.InvariantCulture));
    }

    /// <summary>
    /// Writes a double value as a tagged element.
    /// </summary>
    /// <param name="value">The double value to write.</param>
    public void WriteDoubleValue(double value)
    {
        WriteTaggedValue("@double", value.ToString(CultureInfo.InvariantCulture));
    }

    /// <summary>
    /// Writes an integer value as a tagged element.
    /// </summary>
    /// <param name="value">The integer value to write.</param>
    public void WriteIntValue(int value)
    {
        WriteTaggedValue("@int", value.ToString());
    }

    /// <summary>
    /// Writes a byte array value as a tagged element.
    /// </summary>
    /// <param name="value">The byte array value to write.</param>
    public void WriteBytesValue(byte[] value)
    {
        WriteTaggedValue("@bytes", Convert.ToBase64String(value));
    }

    /// <summary>
    /// Writes a long integer value as a tagged element.
    /// </summary>
    /// <param name="value">The long integer value to write.</param>
    public void WriteLongValue(long value)
    {
        WriteTaggedValue("@long", value.ToString());
    }

    /// <summary>
    /// Writes a string value as a tagged element.
    /// </summary>
    /// <param name="value">The string value to write.</param>
    public void WriteStringValue(string value)
    {
        _writer.WriteStringValue(value);
    }

    /// <summary>
    /// Writes a date value as a tagged element.
    /// </summary>
    /// <param name="value">The date value to write.</param>
    public void WriteDateValue(DateTime value)
    {
        var str = value.ToString("yyyy-MM-dd");
        WriteTaggedValue("@date", str);
    }

    /// <summary>
    /// Writes a date value as a tagged element.
    /// </summary>
    /// <param name="value">The date value to write.</param>
    public void WriteDateValue(DateOnly value)
    {
        var str = value.ToString("yyyy-MM-dd");
        WriteTaggedValue("@date", str);
    }

    /// <summary>
    /// Writes a date value as a tagged element.
    /// </summary>
    /// <param name="value">The date value to write.</param>
    public void WriteDateValue(DateTimeOffset value)
    {
        var str = value.ToString("yyyy-MM-dd");
        WriteTaggedValue("@date", str);
    }

    /// <summary>
    /// Writes a date value as a tagged element.
    /// </summary>
    /// <param name="value">The date value to write.</param>
    public void WriteTimeValue(DateTime value)
    {
        var str = value.ToUniversalTime().ToString("o", CultureInfo.InvariantCulture);
        WriteTaggedValue("@time", str);
    }

    /// <summary>
    /// Writes a date value as a tagged element.
    /// </summary>
    /// <param name="value">The date value to write.</param>
    public void WriteTimeValue(DateTimeOffset value)
    {
        var str = value.ToUniversalTime().ToString("o", CultureInfo.InvariantCulture);
        WriteTaggedValue("@time", str);
    }

    /// <summary>
    /// Writes a boolean value to the stream.
    /// </summary>
    /// <param name="value">The boolean value to write.</param>
    public void WriteBooleanValue(bool value)
    {
        _writer.WriteBooleanValue(value);
    }

    /// <summary>
    /// Writes a null value to the stream.
    /// </summary>
    public void WriteNullValue()
    {
        _writer.WriteNullValue();
    }

    /// <summary>
    /// Writes a module value as a tagged element.
    /// </summary>
    /// <param name="value">The module value to write.</param>
    public void WriteModuleValue(Module value)
    {
        WriteTaggedValue("@mod", value.Name);
    }
}
```

## File: Fauna/Types/BaseRef.cs
```csharp
using Fauna.Linq;

namespace Fauna.Types;

/// <summary>
/// An abstract class representing a reference that can wrap an instance of the referenced document.
/// </summary>
/// <typeparam name="T">The referenced document type.</typeparam>
public abstract class BaseRef<T>
{

    /// <summary>
    /// Gets the materialized document represented by the Ref. Is null unless IsLoaded is true
    /// and Exists is true.
    /// </summary>
    protected readonly T? Doc;

    /// <summary>
    /// Gets the cause when exists is false. Is null unless IsLoaded is true and Exists is false.
    /// </summary>
    public string? Cause { get; }

    /// <summary>
    /// Gets the collection to which the ref belongs.
    /// </summary>
    public Module Collection { get; }

    /// <summary>
    /// Gets a boolean indicating whether the doc exists. Is null unless IsLoaded is true.
    /// </summary>
    public bool? Exists { get; }

    /// <summary>
    /// Gets a boolean indicating whether the document represented by the ref has been loaded.
    /// </summary>
    public bool IsLoaded { get; }

    internal BaseRef(DataContext.ICollection col)
    {
        Collection = new Module(col.Name);
    }


    internal BaseRef(DataContext.ICollection col, T doc)
    {
        Collection = new Module(col.Name);
        Doc = doc;
        IsLoaded = true;
        Exists = true;
    }

    internal BaseRef(DataContext.ICollection col, string cause)
    {
        Collection = new Module(col.Name);
        Exists = false;
        Cause = cause;
        IsLoaded = true;
    }

    internal BaseRef(Module coll)
    {
        Collection = coll;
    }

    internal BaseRef(Module coll, T doc)
    {
        Collection = coll;
        Exists = true;
        Doc = doc;
        IsLoaded = true;
    }

    internal BaseRef(Module coll, string cause)
    {
        Collection = coll;
        Exists = false;
        Cause = cause;
        IsLoaded = true;
    }

    /// <summary>
    /// Gets the underlying document if it's loaded and exists.
    /// </summary>
    /// <returns>An instance of <typeparamref name="T"/>.</returns>
    public abstract T Get();
}

internal class UnloadedRefException : Exception
{
}
```

## File: Fauna/Types/BaseRefBuilder.cs
```csharp
namespace Fauna.Types;

internal class BaseRefBuilder<T>
{
    public string? Id { get; set; }
    public string? Name { get; set; }
    public Module? Collection { get; set; }
    public string? Cause { get; set; }
    public bool? Exists { get; set; }
    public T? Doc { get; set; }

    public BaseRef<T> Build()
    {
        if (Collection is null) throw new ArgumentNullException(nameof(Collection));

        if (Id is not null)
        {
            if (Exists != null && !Exists.Value) return new Ref<T>(Id, Collection, Cause ?? "");
            if (Doc != null) return new Ref<T>(Id, Collection, Doc);
            return new Ref<T>(Id, Collection);
        }

        if (Name is not null)
        {
            if (Exists != null && !Exists.Value) return new NamedRef<T>(Name, Collection, Cause ?? "");
            if (Doc != null) return new NamedRef<T>(Name, Collection, Doc);
            return new NamedRef<T>(Name, Collection);
        }

        throw new ArgumentException("Id and Name cannot both be null");
    }
}
```

## File: Fauna/Types/Event.cs
```csharp
using System.Text.Json;
using Fauna.Core;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Serialization;
using static Fauna.Core.ResponseFields;

namespace Fauna.Types;


/// <summary>
/// An enum representing Fauna event types.
/// </summary>
public enum EventType
{
    /// <summary>
    /// An add event. Emitted when a document is added to the tracked Set.
    /// </summary>
    Add,
    /// <summary>
    /// An update event. Emitted when a document is updated in the tracked Set.
    /// </summary>
    Update,
    /// <summary>
    /// A remove event. Emitted when a document is removed from the tracked Set.
    /// </summary>
    Remove,
    /// <summary>
    /// A status event. Typically used as an implementation detail for a driver. Indicates a status change on the stream. Not emitted for event feeds.
    /// </summary>
    Status
}

/// <summary>
/// A class representing an event from an event feed or event stream.
/// </summary>
/// <typeparam name="T"></typeparam>
public class Event<T> where T : notnull
{
    /// <summary>
    /// The type of the event.
    /// </summary>
    public EventType Type { get; private init; }
    /// <summary>
    /// The transaction time of the event.
    /// </summary>
    public long TxnTime { get; private init; }
    /// <summary>
    /// A cursor for the event. Used to resume an event feed or event stream after the event.
    /// </summary>
    public string Cursor { get; private init; } = null!;
    /// <summary>
    /// Document data for the event.
    /// </summary>
    public T? Data { get; private init; }
    /// <summary>
    /// Query stats related to the event.
    /// </summary>
    public QueryStats Stats { get; private init; }


    /// <summary>
    /// A helper method for converting a JSON element into an Event.
    /// </summary>
    /// <param name="json">JSON Element to convert.</param>
    /// <param name="ctx">A mapping context to influence deserialization.</param>
    /// <returns>An instance of <see cref="Event{T}"/>.</returns>
    /// <exception cref="EventException">Thrown when the event includes a Fauna error.</exception>
    internal static Event<T> From(JsonElement json, MappingContext ctx)
    {
        var err = GetError(json);
        if (err != null)
        {
            throw new EventException(err.Value);
        }

        var evt = new Event<T>
        {
            TxnTime = GetTxnTime(json),
            Cursor = GetCursor(json),
            Type = GetType(json),
            Stats = GetStats(json),
            Data = GetData(json, ctx),
        };

        return evt;
    }

    /// <summary>
    /// A helper method for converting a JSON string into an Event.
    /// </summary>
    /// <param name="body">The string of raw JSON.</param>
    /// <param name="ctx">A mapping context to influence deserialization.</param>
    /// <returns>An instance of <see cref="Event{T}"/>.</returns>
    /// <exception cref="FaunaException">Thrown when the event includes a Fauna error.</exception>
    internal static Event<T> From(string body, MappingContext ctx)
    {
        var json = JsonSerializer.Deserialize<JsonElement>(body);

        return From(json, ctx);
    }

    private static long GetTxnTime(JsonElement json)
    {
        if (!json.TryGetProperty(LastSeenTxnFieldName, out var elem))
        {
            return default;
        }

        return elem.TryGetInt64(out long i) ? i : default;
    }

    private static string GetCursor(JsonElement json)
    {
        if (!json.TryGetProperty(CursorFieldName, out var elem))
        {
            throw new InvalidDataException($"Missing required field: cursor - {json.ToString()}");
        }

        return elem.Deserialize<string>()!;
    }


    private static EventType GetType(JsonElement json)
    {
        if (!json.TryGetProperty("type", out var elem))
        {
            throw new InvalidDataException($"Missing required field: type - {json.ToString()}");
        }

        string? evtType = elem.Deserialize<string?>();
        EventType type = evtType switch
        {
            "add" => EventType.Add,
            "update" => EventType.Update,
            "remove" => EventType.Remove,
            "status" => EventType.Status,
            _ => throw new InvalidOperationException($"Unknown event type: {evtType}")
        };

        return type;
    }

    private static QueryStats GetStats(JsonElement json)
    {
        return json.TryGetProperty(StatsFieldName, out var elem) ? elem.Deserialize<QueryStats>() : default;
    }

    private static T? GetData(JsonElement json, MappingContext ctx)
    {
        if (!json.TryGetProperty(DataFieldName, out var elem))
        {
            return default;
        }

        var reader = new Utf8FaunaReader(elem.GetRawText());
        reader.Read();

        return Serializer.Generate<T>(ctx).Deserialize(ctx, ref reader);
    }

    private static ErrorInfo? GetError(JsonElement json)
    {
        return json.TryGetProperty(ErrorFieldName, out var elem) ? elem.Deserialize<ErrorInfo>() : null;
    }
}
```

## File: Fauna/Types/EventSource.cs
```csharp
using System.Text.Json;

namespace Fauna.Types;

/// <summary>
/// Represents a Fauna EventSource for initializing Streams and Feeds.
/// </summary>
public sealed class EventSource : IEquatable<EventSource>
{
    /// <summary>
    /// Gets the string value of the stream token.
    /// </summary>
    internal string Token { get; }

    internal EventOptions Options { get; set; }

    /// <summary>
    /// Initializes an <see cref="EventSource"/>.
    /// </summary>
    /// <param name="token">An event source.</param>
    public EventSource(string token)
    {
        Token = token;
        Options = new EventOptions();
    }

    /// <summary>
    /// Serializes the event source to the provided <see cref="Stream"/>.
    /// </summary>
    /// <param name="stream"></param>
    public void Serialize(Stream stream)
    {
        var writer = new Utf8JsonWriter(stream);
        writer.WriteStartObject();
        writer.WriteString("token", Token);
        if (Options.Cursor != null)
        {
            writer.WriteString("cursor", Options.Cursor);
        }
        else if (Options.StartTs != null)
        {
            writer.WriteNumber("start_ts", Options.StartTs.Value);
        }

        if (Options.PageSize is > 0)
        {
            writer.WriteNumber("page_size", Options.PageSize.Value);
        }

        writer.WriteEndObject();
        writer.Flush();
    }


    /// <summary>
    ///     Determines whether the specified Stream is equal to the current Stream.
    /// </summary>
    /// <param name="other">The Stream to compare with the current Stream.</param>
    /// <returns>true if the specified Stream is equal to the current Stream; otherwise, false.</returns>
    public bool Equals(EventSource? other)
    {
        if (ReferenceEquals(null, other)) return false;
        if (ReferenceEquals(this, other)) return true;
        return Token == other.Token;
    }

    /// <summary>
    ///     Determines whether the specified object is equal to the current Stream.
    /// </summary>
    /// <param name="obj">The object to compare with the current Stream.</param>
    /// <returns>true if the specified object is equal to the current Stream; otherwise, false.</returns>
    public override bool Equals(object? obj)
    {
        if (ReferenceEquals(null, obj)) return false;
        if (ReferenceEquals(this, obj)) return true;
        if (obj.GetType() != GetType()) return false;
        return Equals((EventSource)obj);
    }

    /// <summary>
    ///     The default hash function.
    /// </summary>
    /// <returns>A hash code for the current Stream.</returns>
    public override int GetHashCode()
    {
        return Token.GetHashCode();
    }
}

/// <summary>
/// Represents the options for a Fauna EventSource.
/// </summary>
public class EventOptions
{
    /// <summary>
    /// Cursor returned from Fauna
    /// </summary>
    /// <seealso href="https://docs.fauna.com/fauna/current/reference/cdc/#get-events-after-a-specific-cursor"/>
    public string? Cursor { get; internal set; }

    /// <summary>
    /// Start timestamp returned for the feed. Used to resume the Feed.
    /// </summary>
    public long? StartTs { get; protected init; }

    /// <summary>
    /// Limit page size for the Feed
    /// </summary>
    public int? PageSize { get; protected init; }
}
```

## File: Fauna/Types/Module.cs
```csharp
namespace Fauna.Types;

/// <summary>
/// Represents a module, a singleton object grouping related functionalities.
/// Modules are serialized as \@mod values in tagged formats, organizing and encapsulating specific functionalities.
/// </summary>
public sealed class Module : IEquatable<Module>
{
    /// <summary>
    /// Gets the name of the module. The name is used to identify and reference the module.
    /// </summary>
    public string Name { get; }

    /// <summary>
    /// Initializes a new instance of the Module class with the specified name.
    /// </summary>
    /// <param name="name">The name of the module.</param>
    public Module(string name)
    {
        Name = name;
    }

    /// <summary>
    /// Determines whether the specified Module is equal to the current Module.
    /// </summary>
    /// <param name="other">The Module to compare with the current Module.</param>
    /// <returns>true if the specified Module is equal to the current Module; otherwise, false.</returns>
    public bool Equals(Module? other)
    {
        if (ReferenceEquals(null, other)) return false;
        if (ReferenceEquals(this, other)) return true;
        return Name == other.Name;
    }

    /// <summary>
    /// Determines whether the specified object is equal to the current Module.
    /// </summary>
    /// <param name="obj">The object to compare with the current Module.</param>
    /// <returns>true if the specified object is equal to the current Module; otherwise, false.</returns>
    public override bool Equals(object? obj)
    {
        if (ReferenceEquals(null, obj)) return false;
        if (ReferenceEquals(this, obj)) return true;
        if (obj.GetType() != GetType()) return false;
        return Equals((Module)obj);
    }

    /// <summary>
    /// The default hash function.
    /// </summary>
    /// <returns>A hash code for the current Module.</returns>
    public override int GetHashCode()
    {
        return Name.GetHashCode();
    }
}
```

## File: Fauna/Types/NamedRef.cs
```csharp
using Fauna.Exceptions;
using Fauna.Linq;

namespace Fauna.Types;


/// <summary>
/// Represents a document ref that has a "name" instead of an "id". For example, a Role document reference is
/// represented as a NamedRef.
/// </summary>
public class NamedRef<T> : BaseRef<T>
{
    /// <summary>
    /// Gets the string value of the ref name.
    /// </summary>
    public string Name { get; }

    /// <summary>
    /// Initializes a new instance of an unloaded <see cref="NamedRef{T}"/> class.
    /// </summary>
    /// <param name="name">The name of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    public NamedRef(string name, DataContext.ICollection col) : base(col)
    {
        Name = name;
    }

    /// <summary>
    /// Initializes a new instance of a loaded <see cref="NamedRef{T}"/> class.
    /// </summary>
    /// <param name="name">The name of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="doc">The instance of <typeparamref name="T" /> referenced.</param>
    public NamedRef(string name, DataContext.ICollection col, T doc) : base(col, doc)
    {
        Name = name;
    }

    /// <summary>
    /// Initializes a new instance of a loaded and non-existent <see cref="NamedRef{T}"/> class.
    /// </summary>
    /// <param name="name">The name of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="cause">A string representing the cause for non-existence.</param>
    public NamedRef(string name, DataContext.ICollection col, string cause) : base(col, cause)
    {
        Name = name;
    }

    /// <summary>
    /// Initializes a new instance of an unloaded <see cref="NamedRef{T}"/> class.
    /// </summary>
    /// <param name="name">The name of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    public NamedRef(string name, Module col) : base(col)
    {
        Name = name;
    }

    /// <summary>
    /// Initializes a new instance of a loaded and non-existent <see cref="NamedRef{T}"/> class.
    /// </summary>
    /// <param name="name">The name of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="cause">A string representing the cause for non-existence.</param>
    public NamedRef(string name, Module col, string cause) : base(col, cause)
    {
        Name = name;
    }

    /// <summary>
    /// Initializes a new instance of a loaded <see cref="NamedRef{T}"/> class.
    /// </summary>
    /// <param name="name">The name of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="doc">The instance of <typeparamref name="T" /> referenced.</param>
    public NamedRef(string name, Module col, T doc) : base(col, doc)
    {
        Name = name;
    }

    /// <inheritdoc />
    /// <exception cref="UnloadedRefException">Thrown when IsLoaded is false.</exception>
    /// <exception cref="NullDocumentException">Thrown when Exists is false.</exception>
    public override T Get()
    {
        if (!IsLoaded) throw new UnloadedRefException();
        if (Exists.HasValue && !Exists.Value) throw new NullDocumentException(null, Name, Collection, Cause ?? "");
        return Doc!;
    }
}
```

## File: Fauna/Types/Page.cs
```csharp
namespace Fauna.Types;

/// <summary>
/// Represents a page in a dataset for pagination.
/// </summary>
/// <typeparam name="T">The type of data contained in the page.</typeparam>
/// <param name="Data">The <see cref="IReadOnlyList{T}"/> of data items on the page.</param>
/// <param name="After">The cursor for the next page, if available.</param>
/// <remarks>
/// Used for segmenting large datasets into pages with cursors to navigate between them.
/// </remarks>
public record Page<T>(IReadOnlyList<T> Data, string? After);
```

## File: Fauna/Types/Ref.cs
```csharp
using Fauna.Exceptions;
using Fauna.Linq;

namespace Fauna.Types;


/// <summary>
/// Represents a document ref.
/// </summary>
public class Ref<T> : BaseRef<T>
{
    /// <summary>
    /// Gets the string value of the ref ID.
    /// </summary>
    public string Id { get; }

    /// <summary>
    /// Initializes a new instance of an unloaded <see cref="Ref{T}"/> class.
    /// </summary>
    /// <param name="id">The ID of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    public Ref(string id, DataContext.ICollection col) : base(col)
    {
        Id = id;
    }

    /// <summary>
    /// Initializes a new instance of a loaded <see cref="Ref{T}"/> class.
    /// </summary>
    /// <param name="id">The ID of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="doc">The instance of <typeparamref name="T" /> referenced.</param>
    public Ref(string id, DataContext.ICollection col, T doc) : base(col, doc)
    {
        Id = id;
    }

    /// <summary>
    /// Initializes a new instance of a loaded and non-existent <see cref="Ref{T}"/> class.
    /// </summary>
    /// <param name="id">The ID of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="cause">A string representing the cause for non-existence.</param>
    public Ref(string id, DataContext.ICollection col, string cause) : base(col, cause)
    {
        Id = id;
    }

    /// <summary>
    /// Initializes a new instance of an unloaded <see cref="Ref{T}"/> class.
    /// </summary>
    /// <param name="id">The ID of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    public Ref(string id, Module col) : base(col)
    {
        Id = id;
    }

    /// <summary>
    /// Initializes a new instance of a loaded and non-existent <see cref="Ref{T}"/> class.
    /// </summary>
    /// <param name="id">The ID of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="cause">A string representing the cause for non-existence.</param>
    public Ref(string id, Module col, string cause) : base(col, cause)
    {
        Id = id;
    }

    /// <summary>
    /// Initializes a new instance of a loaded <see cref="Ref{T}"/> class.
    /// </summary>
    /// <param name="id">The ID of the document.</param>
    /// <param name="col">The collection to which the document belongs.</param>
    /// <param name="doc">The instance of <typeparamref name="T" /> referenced.</param>
    public Ref(string id, Module col, T doc) : base(col, doc)
    {
        Id = id;
    }


    /// <inheritdoc />
    /// <exception cref="UnloadedRefException">Thrown when IsLoaded is false.</exception>
    /// <exception cref="NullDocumentException">Thrown when Exists is false.</exception>
    public override T Get()
    {
        if (!IsLoaded) throw new UnloadedRefException();
        if (Exists.HasValue && !Exists.Value) throw new NullDocumentException(Id, null, Collection, Cause ?? "");
        return Doc!;
    }
}
```

## File: Fauna/Util/Extensions/PaginationExtensions.cs
```csharp
using Fauna.Types;

namespace Fauna.Util.Extensions;

/// <summary>
/// Provides extension methods for pagination.
/// </summary>
public static class PaginationExtensions
{
    /// <summary>
    /// Flattens all pages into a stream of items.
    /// </summary>
    /// <typeparam name="T">Data type.</typeparam>
    /// <param name="pages">Pages to flatten.</param>
    /// <returns>An <see cref="IAsyncEnumerable{T}"/> that enumerates each item across all pages.</returns>
    public static async IAsyncEnumerable<T> FlattenAsync<T>(this IAsyncEnumerable<Page<T>> pages)
    {
        await foreach (var page in pages)
        {
            foreach (var item in page.Data)
            {
                yield return item;
            }
        }
    }
}
```

## File: Fauna/Util/Extensions/TypeExtensions.cs
```csharp
using System.Reflection;
using System.Runtime.CompilerServices;

namespace Fauna.Util.Extensions;

internal static class TypeExtensions
{
    public static bool IsClosureType(this Type ty)
    {
        var compilerGen = ty.GetCustomAttribute<CompilerGeneratedAttribute>() != null;
        // check for the closure class name pattern. see
        // https://stackoverflow.com/questions/2508828/where-to-learn-about-vs-debugger-magic-names/2509524#2509524
        var dcName = ty.Name.StartsWith("<>c__DisplayClass");

        return compilerGen && dcName;
    }

    public static Type? GetGenInst(this Type ty, Type genTy)
    {
        if (!genTy.IsGenericTypeDefinition)
        {
            throw new ArgumentException($"{nameof(genTy)} is not a generic type definition.");
        }

        if (genTy.IsInterface)
        {
            foreach (var iface in ty.GetInterfaces())
            {
                if (iface.IsGenericType && iface.GetGenericTypeDefinition() == genTy)
                {
                    return iface;
                }
            }
        }
        else
        {
            Type? curr = ty;

            while (curr is not null)
            {
                if (curr.IsGenericType && curr.GetGenericTypeDefinition() == genTy)
                {
                    return curr;
                }

                curr = curr.BaseType;
            }
        }

        return null;
    }
}
```

## File: Fauna/Util/Expressions.cs
```csharp
using System.Linq.Expressions;

namespace Fauna.Util;

internal static class Expressions
{
    public static (Expression, Expression[], bool) GetCalleeAndArgs(MethodCallExpression expr) =>
         expr.Object switch
         {
             null => (expr.Arguments.First(), expr.Arguments.Skip(1).ToArray(), true),
             var c => (c, expr.Arguments.ToArray(), false),
         };

    public static LambdaExpression? UnwrapLambda(Expression expr) =>
    expr.NodeType switch
    {
        ExpressionType.Lambda => (LambdaExpression)expr,

        ExpressionType.Convert or
        ExpressionType.ConvertChecked or
        ExpressionType.Quote =>
            UnwrapLambda(((UnaryExpression)expr).Operand),
        _ => null,
    };
}
```

## File: Fauna/Util/ExpressionSwitch.cs
```csharp
using System.Linq.Expressions;

namespace Fauna.Util;

internal abstract class ExpressionSwitch<TResult>
{
    // if true, will transparently handle certain node types (Quote, Convert, etc.)
    protected virtual bool Simplified { get => true; }

    public IEnumerable<TResult> ApplyAll(IEnumerable<Expression> exprs) =>
        exprs.Select(e => Apply(e));

    // Apply this switch to an expression
    public TResult Apply(Expression? expr)
    {
        if (expr is null) return NullExpr();

        return expr.NodeType switch
        {
            ExpressionType.Add or
            ExpressionType.AddAssign or
            ExpressionType.AddAssignChecked or
            ExpressionType.AddChecked or
            ExpressionType.And or
            ExpressionType.AndAssign or
            ExpressionType.AndAlso or
            ExpressionType.ArrayIndex or
            ExpressionType.Assign or
            ExpressionType.Coalesce or
            ExpressionType.Divide or
            ExpressionType.DivideAssign or
            ExpressionType.Equal or
            ExpressionType.ExclusiveOr or
            ExpressionType.ExclusiveOrAssign or
            ExpressionType.GreaterThan or
            ExpressionType.GreaterThanOrEqual or
            ExpressionType.LeftShift or
            ExpressionType.LeftShiftAssign or
            ExpressionType.LessThan or
            ExpressionType.LessThanOrEqual or
            ExpressionType.Modulo or
            ExpressionType.ModuloAssign or
            ExpressionType.Multiply or
            ExpressionType.MultiplyAssign or
            ExpressionType.MultiplyAssignChecked or
            ExpressionType.MultiplyChecked or
            ExpressionType.NotEqual or
            ExpressionType.Or or
            ExpressionType.OrAssign or
            ExpressionType.OrElse or
            ExpressionType.Power or
            ExpressionType.PowerAssign or
            ExpressionType.RightShift or
            ExpressionType.RightShiftAssign or
            ExpressionType.Subtract or
            ExpressionType.SubtractAssign or
            ExpressionType.SubtractAssignChecked or
            ExpressionType.SubtractChecked =>
                BinaryExpr((BinaryExpression)expr),

            ExpressionType.Block =>
                BlockExpr((BlockExpression)expr),
            ExpressionType.Call =>
                CallExpr((MethodCallExpression)expr),
            ExpressionType.Conditional =>
                ConditionalExpr((ConditionalExpression)expr),
            ExpressionType.Constant =>
                ConstantExpr((ConstantExpression)expr),
            ExpressionType.DebugInfo =>
                DebugInfoExpr((DebugInfoExpression)expr),
            ExpressionType.Default =>
                DefaultExpr((DefaultExpression)expr),
            ExpressionType.Dynamic =>
                DynamicExpr((DynamicExpression)expr),
            ExpressionType.Goto =>
                GotoExpr((GotoExpression)expr),
            ExpressionType.Index =>
                IndexExpr((IndexExpression)expr),
            ExpressionType.Invoke =>
                InvokeExpr((InvocationExpression)expr),
            ExpressionType.Label =>
                LabelExpr((LabelExpression)expr),
            ExpressionType.Lambda =>
                LambdaExpr((LambdaExpression)expr),
            ExpressionType.Loop =>
                LoopExpr((LoopExpression)expr),
            ExpressionType.ListInit =>
                ListInitExpr((ListInitExpression)expr),
            ExpressionType.MemberAccess =>
                MemberAccessExpr((MemberExpression)expr),
            ExpressionType.MemberInit =>
                MemberInitExpr((MemberInitExpression)expr),
            ExpressionType.New =>
                NewExpr((NewExpression)expr),

            ExpressionType.NewArrayBounds or
            ExpressionType.NewArrayInit =>
                NewArrayExpr((NewArrayExpression)expr),

            ExpressionType.Parameter =>
                ParameterExpr((ParameterExpression)expr),
            ExpressionType.RuntimeVariables =>
                RuntimeVariablesExpr((RuntimeVariablesExpression)expr),
            ExpressionType.Switch =>
                SwitchExpr((SwitchExpression)expr),
            ExpressionType.Try =>
                TryExpr((TryExpression)expr),

            ExpressionType.TypeEqual or
            ExpressionType.TypeIs =>
                TypeBinaryExpr((TypeBinaryExpression)expr),

            ExpressionType.Convert or
            ExpressionType.ConvertChecked or
            ExpressionType.Quote
            when Simplified =>
                Apply(((UnaryExpression)expr).Operand),

            ExpressionType.ArrayLength or
            ExpressionType.Convert or
            ExpressionType.ConvertChecked or
            ExpressionType.Decrement or
            ExpressionType.Increment or
            ExpressionType.IsFalse or
            ExpressionType.IsTrue or
            ExpressionType.Negate or
            ExpressionType.NegateChecked or
            ExpressionType.Not or
            ExpressionType.OnesComplement or
            ExpressionType.PostDecrementAssign or
            ExpressionType.PostIncrementAssign or
            ExpressionType.PreDecrementAssign or
            ExpressionType.PreIncrementAssign or
            ExpressionType.Quote or
            ExpressionType.Throw or
            ExpressionType.TypeAs or
            ExpressionType.UnaryPlus or
            ExpressionType.Unbox =>
                UnaryExpr((UnaryExpression)expr),

            // not sure what to do with this one

            ExpressionType.Extension => UnknownExpr(expr)
        };
    }

    protected abstract TResult NullExpr();

    protected abstract TResult BinaryExpr(BinaryExpression expr);
    protected abstract TResult BlockExpr(BlockExpression expr);
    protected abstract TResult ConditionalExpr(ConditionalExpression expr);
    protected abstract TResult CallExpr(MethodCallExpression expr);
    protected abstract TResult ConstantExpr(ConstantExpression expr);
    protected abstract TResult DebugInfoExpr(DebugInfoExpression expr);
    protected abstract TResult DefaultExpr(DefaultExpression expr);
    protected abstract TResult DynamicExpr(DynamicExpression expr);
    protected abstract TResult GotoExpr(GotoExpression expr);
    protected abstract TResult IndexExpr(IndexExpression expr);
    protected abstract TResult InvokeExpr(InvocationExpression expr);
    protected abstract TResult LabelExpr(LabelExpression expr);
    protected abstract TResult LambdaExpr(LambdaExpression expr);
    protected abstract TResult ListInitExpr(ListInitExpression expr);
    protected abstract TResult LoopExpr(LoopExpression expr);
    protected abstract TResult MemberAccessExpr(MemberExpression expr);
    protected abstract TResult MemberInitExpr(MemberInitExpression expr);
    protected abstract TResult NewArrayExpr(NewArrayExpression expr);
    protected abstract TResult NewExpr(NewExpression expr);
    protected abstract TResult ParameterExpr(ParameterExpression expr);
    protected abstract TResult RuntimeVariablesExpr(RuntimeVariablesExpression expr);
    protected abstract TResult SwitchExpr(SwitchExpression expr);
    protected abstract TResult TryExpr(TryExpression expr);
    protected abstract TResult TypeBinaryExpr(TypeBinaryExpression expr);
    protected abstract TResult UnaryExpr(UnaryExpression expr);
    protected abstract TResult UnknownExpr(Expression expr);
}

internal class DefaultExpressionSwitch<TResult> : ExpressionSwitch<TResult>
{
    protected virtual TResult ApplyDefault(Expression? expr)
        => throw new NotSupportedException($"Unsupported expression: {expr}");

    protected override TResult NullExpr() => ApplyDefault(null);

    protected override TResult BinaryExpr(BinaryExpression expr) => ApplyDefault(expr);
    protected override TResult BlockExpr(BlockExpression expr) => ApplyDefault(expr);
    protected override TResult ConditionalExpr(ConditionalExpression expr) => ApplyDefault(expr);
    protected override TResult CallExpr(MethodCallExpression expr) => ApplyDefault(expr);
    protected override TResult ConstantExpr(ConstantExpression expr) => ApplyDefault(expr);
    protected override TResult DebugInfoExpr(DebugInfoExpression expr) => ApplyDefault(expr);
    protected override TResult DefaultExpr(DefaultExpression expr) => ApplyDefault(expr);
    protected override TResult DynamicExpr(DynamicExpression expr) => ApplyDefault(expr);
    protected override TResult GotoExpr(GotoExpression expr) => ApplyDefault(expr);
    protected override TResult IndexExpr(IndexExpression expr) => ApplyDefault(expr);
    protected override TResult InvokeExpr(InvocationExpression expr) => ApplyDefault(expr);
    protected override TResult LabelExpr(LabelExpression expr) => ApplyDefault(expr);
    protected override TResult LambdaExpr(LambdaExpression expr) => ApplyDefault(expr);
    protected override TResult ListInitExpr(ListInitExpression expr) => ApplyDefault(expr);
    protected override TResult LoopExpr(LoopExpression expr) => ApplyDefault(expr);
    protected override TResult MemberAccessExpr(MemberExpression expr) => ApplyDefault(expr);
    protected override TResult MemberInitExpr(MemberInitExpression expr) => ApplyDefault(expr);
    protected override TResult NewArrayExpr(NewArrayExpression expr) => ApplyDefault(expr);
    protected override TResult NewExpr(NewExpression expr) => ApplyDefault(expr);
    protected override TResult ParameterExpr(ParameterExpression expr) => ApplyDefault(expr);
    protected override TResult RuntimeVariablesExpr(RuntimeVariablesExpression expr) => ApplyDefault(expr);
    protected override TResult SwitchExpr(SwitchExpression expr) => ApplyDefault(expr);
    protected override TResult TryExpr(TryExpression expr) => ApplyDefault(expr);
    protected override TResult TypeBinaryExpr(TypeBinaryExpression expr) => ApplyDefault(expr);
    protected override TResult UnaryExpr(UnaryExpression expr) => ApplyDefault(expr);
    protected override TResult UnknownExpr(Expression expr) => ApplyDefault(expr);
}
```

## File: Fauna/Util/Logger.cs
```csharp
using Microsoft.Extensions.Logging;

namespace Fauna.Util;

/// <summary>
/// This class encapsulates an <see cref="ILogger"/> object for logging throughout
/// the Fauna .NET driver business logic.
/// </summary>
internal static class Logger
{
    private static ILogger? s_logger;

    /// <summary>
    /// The singleton <see cref="ILogger"/> instance to use for logging
    /// </summary>
    public static ILogger Instance
    {
        get
        {
            if (s_logger == null)
            {
                s_logger = InitializeDefaultLogger();
            }

            return s_logger;
        }
    }

    /// <summary>
    /// Optionally initialize the internal <see cref="ILogger"/> with a custom one
    /// </summary>
    /// <param name="logger">The <see cref="ILogger"/> instance to use for logging</param>
    public static void Initialize(ILogger logger)
    {
        s_logger = logger;
    }

    /// <summary>
    /// Initializes a default Console logger with single-line output, UTC timestamps, and
    /// minimum log-level based on the FAUNA_DEBUG environment variable; if the variable is
    /// not set, the default minimum log-level is <see cref="LogLevel.None"/>
    /// </summary>
    /// <returns>An instance of <see cref="ILogger"/> created with <see cref="ILoggerFactory"/></returns>
    /// <exception cref="ArgumentException">Throws if FAUNA_DEBUG is outside of acceptable values</exception>
    private static ILogger InitializeDefaultLogger()
    {
        var logLevel = Environment.GetEnvironmentVariable("FAUNA_DEBUG");
        var minLogLevel = LogLevel.None;

        if (!string.IsNullOrEmpty(logLevel) && int.TryParse(logLevel, out var level))
        {
            if (level < (int)LogLevel.Trace || level > (int)LogLevel.None)
            {
                throw new ArgumentException(
                    $"Invalid FAUNA_DEBUG value of {level}; must be between 0 and 6 inclusive. Set to 0 for highest verbosity, default is 6 (no logging).");
            }

            minLogLevel = (LogLevel)level;
        }

        using ILoggerFactory factory = LoggerFactory.Create(builder => builder
            .AddConsole(options => options.LogToStandardErrorThreshold = LogLevel.Trace)
            .AddSimpleConsole(options =>
            {
                options.IncludeScopes = true;
                options.SingleLine = true;
                options.TimestampFormat = "yyyy-MM-ddTHH:mm:ss.fffZ ";
                options.UseUtcTimestamp = true;
            })
            .SetMinimumLevel(minLogLevel));

        return factory.CreateLogger("fauna-dotnet");
    }
}
```

## File: Fauna/Client.cs
```csharp
using System.Globalization;
using Fauna.Core;
using Fauna.Exceptions;
using Fauna.Linq;
using Fauna.Mapping;
using Fauna.Serialization;
using Fauna.Types;
using Stream = System.IO.Stream;

namespace Fauna;

/// <summary>
/// Represents a client for interacting with a Fauna.
/// </summary>
public class Client : BaseClient, IDisposable
{
    private const string QueryUriPath = "/query/1";
    private const string StreamUriPath = "/stream/1";
    private const string FeedUriPath = "/feed/1";

    private readonly Configuration _config;
    private readonly IConnection _connection;

    private readonly MappingContext _defaultCtx = new();
    private readonly Dictionary<Type, DataContext> _dbCtxs = new();

    private bool _disposed;

    internal override MappingContext MappingCtx { get => _defaultCtx; }

    /// <summary>
    /// Provides collection and aggregation of query statistics. Can be set to null in the <see cref="Configuration"/>.
    /// </summary>
    public readonly IStatsCollector? StatsCollector;

    /// <summary>
    /// Gets the timestamp of the last transaction seen by this client.
    /// </summary>
    public long LastSeenTxn { get; private set; }

    /// <summary>
    /// Initializes a new instance of a Client with the default configuration.
    /// Assumes the environment variable FAUNA_SECRET is set.
    /// </summary>
    public Client() : this(new Configuration()) { }

    /// <summary>
    /// Initializes a new instance of a Client with a secret.
    /// </summary>
    /// <param name="secret">The secret key for authentication.</param>
    public Client(string secret) :
        this(new Configuration(secret))
    {
    }

    /// <summary>
    /// Initializes a new instance of the Client with a custom <see cref="Configuration"/>.
    /// </summary>
    /// <param name="config">The configuration settings for the client.</param>
    public Client(Configuration config)
    {
        config.Validate();
        _config = config;
        StatsCollector = config.StatsCollector;
        _connection = new Connection(config);
    }

    /// <summary>
    /// Create and return a new database context which uses the <see cref="Client"/> instance.
    /// </summary>
    /// <typeparam name="DB">The DataContext subtype to instantiate.</typeparam>
    /// <returns>An instance of <typeparamref name="DB"/>.</returns>
    public DB DataContext<DB>() where DB : DataContext
    {
        var dbCtxType = typeof(DB);
        DataContext? ctx;
        lock (_dbCtxs)
        {
            if (!_dbCtxs.TryGetValue(dbCtxType, out ctx))
            {
                var builder = new DataContextBuilder<DB>();
                ctx = builder.Build(this);
                _dbCtxs[dbCtxType] = ctx;
            }
        }

        return (DB)ctx;
    }

    /// <summary>
    /// Disposes the resources used by the <see cref="Client"/> class.
    /// </summary>
    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    /// <inheritdoc />
    /// <remarks>
    /// https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/finalizers
    /// https://stackoverflow.com/questions/151051/when-should-i-use-gc-suppressfinalize
    /// </remarks>
    ~Client()
    {
        Dispose(false);
    }

    internal override async Task<QuerySuccess<T>> QueryAsyncInternal<T>(
        Query query,
        ISerializer<T> serializer,
        MappingContext ctx,
        QueryOptions? queryOptions,
        CancellationToken cancel)
    {
        if (query == null)
        {
            throw new ArgumentNullException(nameof(query));
        }

        var finalOptions = QueryOptions.GetFinalQueryOptions(_config.DefaultQueryOptions, queryOptions);
        var headers = GetRequestHeaders(finalOptions);

        using var stream = new MemoryStream();
        Serialize(stream, query, ctx);

        using var httpResponse = await _connection.DoPostAsync(
            QueryUriPath,
            stream,
            headers,
            GetRequestTimeoutWithBuffer(finalOptions.QueryTimeout),
            cancel);
        var body = await httpResponse.Content.ReadAsStringAsync(cancel);
        var res = QueryResponse.GetFromResponseBody<T>(ctx, serializer, httpResponse.StatusCode, body);
        switch (res)
        {
            case QuerySuccess<T> success:
                LastSeenTxn = res.LastSeenTxn;
                StatsCollector?.Add(res.Stats);
                return success;
            case QueryFailure failure:
                StatsCollector?.Add(res.Stats);
                throw ExceptionHandler.FromQueryFailure(ctx, failure);
            default:
                throw ExceptionHandler.FromRawResponse(body, httpResponse);
        }
    }

    internal override async IAsyncEnumerator<Event<T>> SubscribeStreamInternal<T>(
        Types.EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default)
    {
        var finalOptions = QueryOptions.GetFinalQueryOptions(_config.DefaultQueryOptions, null);
        var headers = GetRequestHeaders(finalOptions);

        await foreach (var evt in _connection.OpenStream<T>(
                           StreamUriPath,
                           eventSource,
                           headers,
                           ctx,
                           cancel))
        {
            LastSeenTxn = evt.TxnTime;
            eventSource.Options.Cursor = evt.Cursor;

            StatsCollector?.Add(evt.Stats);
            yield return evt;
        }
    }
    internal override async IAsyncEnumerator<FeedPage<T>> SubscribeFeedInternal<T>(
        Types.EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default)
    {
        cancel.ThrowIfCancellationRequested();

        var finalOptions = _config.DefaultQueryOptions;
        var headers = GetRequestHeaders(finalOptions);

        while (!cancel.IsCancellationRequested)
        {
            var feedData = new MemoryStream();
            eventSource.Serialize(feedData);

            using var httpResponse = await _connection.DoPostAsync(
                FeedUriPath,
                feedData,
                headers,
                GetRequestTimeoutWithBuffer(finalOptions.QueryTimeout),
                cancel);
            string body = await httpResponse.Content.ReadAsStringAsync(cancel);

            var res = FeedPage<T>.From(body, ctx);
            eventSource.Options.Cursor = res.Cursor;

            StatsCollector?.Add(res.Stats);
            yield return res;
            if (!res.HasNext)
            {
                break;
            }
        }
    }

    private void Serialize(Stream stream, Query query, MappingContext ctx)
    {
        using var writer = new Utf8FaunaWriter(stream);
        writer.WriteStartObject();
        writer.WriteFieldName("query");
        query.Serialize(ctx, writer);
        writer.WriteEndObject();
        writer.Flush();
    }

    private Dictionary<string, string> GetRequestHeaders(QueryOptions queryOptions)
    {
        var headers = new Dictionary<string, string>
        {
            { Headers.Authorization, $"Bearer {_config.Secret}"},
            { Headers.Format, "tagged" },
            { Headers.Driver, "C#" }
        };

        if (LastSeenTxn > long.MinValue)
        {
            headers.Add(Headers.LastTxnTs, LastSeenTxn.ToString());
        }

        if (queryOptions.QueryTimeout != TimeSpan.Zero)
        {
            headers.Add(
                Headers.QueryTimeoutMs,
                queryOptions.QueryTimeout.TotalMilliseconds.ToString(CultureInfo.InvariantCulture));
        }

        if (queryOptions.QueryTags != null)
        {
            headers.Add(Headers.QueryTags, EncodeQueryTags(queryOptions.QueryTags));
        }

        if (!string.IsNullOrEmpty(queryOptions.TraceParent))
        {
            headers.Add(Headers.TraceParent, queryOptions.TraceParent);
        }

        if (queryOptions.Linearized != null)
        {
            headers.Add(Headers.Linearized, queryOptions.Linearized.ToString()!);
        }

        if (queryOptions.TypeCheck != null)
        {
            headers.Add(Headers.TypeCheck, queryOptions.TypeCheck.ToString()!);
        }

        return headers;
    }

    private TimeSpan GetRequestTimeoutWithBuffer(TimeSpan queryTimeout)
    {
        return queryTimeout.Add(_config.ClientBufferTimeout);
    }

    private static string EncodeQueryTags(Dictionary<string, string> tags)
    {
        return string.Join(",", tags.Select(entry => entry.Key + "=" + entry.Value));
    }

    private void Dispose(bool disposing)
    {
        if (_disposed) return;

        if (disposing)
        {
            _connection.Dispose();
            GC.SuppressFinalize(this);
        }
        _disposed = true;
    }
}
```

## File: Fauna/Configuration.cs
```csharp
using Fauna.Core;
using Fauna.Util;
using Microsoft.Extensions.Logging;

namespace Fauna;

/// <summary>
/// Configuration is a class used to configure a Fauna <see cref="Client"/>. It encapsulates various settings such as the <see cref="Endpoint"/>,
/// secret, query timeout, and others.
/// </summary>
public record class Configuration
{
    /// <summary>
    /// Whether the <see cref="Client"/> should dispose of the  <see cref="HttpClient"/> on Dispose.
    /// </summary>
    public bool DisposeHttpClient { get; } = true;

    /// <summary>
    /// Additional buffer to add to <see cref="QueryOptions.QueryTimeout"/> when setting the HTTP request
    /// timeout on the <see cref="HttpClient"/>; default is 5 seconds.
    /// </summary>
    public TimeSpan ClientBufferTimeout { get; init; } = TimeSpan.FromSeconds(5);

    /// <summary>
    /// The HTTP Client to use for requests.
    /// </summary>
    public HttpClient HttpClient { get; init; }

    /// <summary>
    /// The secret key used for authentication.
    /// </summary>
    public string Secret { get; init; } = Environment.GetEnvironmentVariable("FAUNA_SECRET") ?? string.Empty;

    /// <summary>
    /// The endpoint URL of the Fauna server.
    /// </summary>
    public Uri Endpoint { get; init; } = Endpoints.GetFaunaEndpoint();

    /// <summary>
    /// Default options for queries sent to Fauna.
    /// </summary>
    public QueryOptions DefaultQueryOptions { get; init; } = new();

    /// <summary>
    /// The retry configuration to apply to requests.
    /// </summary>
    public RetryConfiguration RetryConfiguration { get; init; } = new(3, TimeSpan.FromSeconds(20));


    /// <summary>
    /// StatsCollector for the client.
    /// </summary>
    public IStatsCollector? StatsCollector { get; init; } = new StatsCollector();

    /// <summary>
    /// Initializes a new instance of the <see cref="Configuration"/> record with the specified secret key.
    /// </summary>
    /// <param name="secret">The secret used for authentication. If null or empty, attempt to use the FAUNA_SECRET env var.</param>
    /// <param name="httpClient">The <see cref="HttpClient"/> to use. If null, a default HttpClient is used.</param>
    /// <param name="logger">A logger. If null, a default logger is used.</param>
    public Configuration(string secret = "", HttpClient? httpClient = null, ILogger? logger = null)
    {
        if (!string.IsNullOrEmpty(secret))
        {
            Secret = secret;
        }

        if (httpClient != null)
        {
            HttpClient = httpClient;
            DisposeHttpClient = false;
        }
        else
        {
            HttpClient = new HttpClient { Timeout = Timeout.InfiniteTimeSpan };
        }

        if (logger != null)
        {
            Logger.Initialize(logger);
        }
    }

    internal void Validate()
    {
        if (string.IsNullOrEmpty(Secret))
            throw new ArgumentNullException(
                nameof(Secret),
                "Need to set FAUNA_SECRET environment variable or pass a secret as a parameter when creating the Client."
            );
    }
}
```

## File: Fauna/Fauna.csproj
```
<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Version>1.0.1</Version>
    <PackageId>Fauna</PackageId>
    <Title>.NET Driver for Fauna</Title>
    <Authors>Fauna, Inc.</Authors>
    <Description>.NET Driver for Fauna.

      See https://fauna.com for more information.</Description>

    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="8.0.1" />
    <PackageReference Include="Polly" Version="8.3.0" />
  </ItemGroup>
  <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="dotnet format --severity warn --verbosity diagnostic" />
  </Target>
</Project>
```

## File: Fauna/IClient.cs
```csharp
using System.Runtime.CompilerServices;
using Fauna.Core;
using Fauna.Exceptions;
using Fauna.Mapping;
using Fauna.Serialization;
using Fauna.Types;
using static Fauna.Query;

namespace Fauna;

/// <summary>
/// Represents a client for interacting with a Fauna.
/// </summary>
public interface IClient
{
    /// <summary>
    /// Asynchronously executes a specified FQL query against the Fauna database and returns the typed result.
    /// </summary>
    /// <typeparam name="T">The type of the result expected from the query, corresponding to the structure of the FQL query's expected response.</typeparam>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the result of the query execution as <see cref="QuerySuccess{T}"/>.</returns>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public Task<QuerySuccess<T>> QueryAsync<T>(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
        where T : notnull;

    /// <summary>
    /// Asynchronously executes a specified FQL query against the Fauna database.
    /// </summary>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the result of the query execution.</returns>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public Task<QuerySuccess<object?>> QueryAsync(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously executes a specified FQL query against the Fauna database and returns the typed result.
    /// </summary>
    /// <typeparam name="T">The type of the result expected from the query, corresponding to the structure of the FQL query's expected response.</typeparam>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="serializer">A serializer for the success data type.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the result of the query execution as <see cref="QuerySuccess{T}"/>.</returns>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public Task<QuerySuccess<T>> QueryAsync<T>(
        Query query,
        ISerializer<T> serializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously executes a specified FQL query against the Fauna database and returns the typed result.
    /// </summary>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="serializer">A serializer for the success data type.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation toke to use.</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the result of the query execution.</returns>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public Task<QuerySuccess<object?>> QueryAsync(
        Query query,
        ISerializer serializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// </summary>
    /// <typeparam name="T">The type of the data expected in each page.</typeparam>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>An asynchronous enumerable of pages, each containing a list of items of type <typeparamref name="T"/>.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
        where T : notnull;

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// The provided page is the first page yielded.
    /// </summary>
    /// <typeparam name="T">The type of the data expected in each page.</typeparam>
    /// <param name="page">The initial page.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>An asynchronous enumerable of pages, each containing a list of items of type <typeparamref name="T"/>.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Page<T> page,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
        where T : notnull;

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// </summary>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>An asynchronous enumerable of pages, each containing a list of items.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// The provided page is the first page yielded.
    /// </summary>
    /// <param name="page">The initial page.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>An asynchronous enumerable of pages, each containing a list of items.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Page<object?> page,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// </summary>
    /// <typeparam name="T">The type of the data expected in each page.</typeparam>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="elemSerializer">A data serializer for the page element type.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>An asynchronous enumerable of pages, each containing a list of items of type <typeparamref name="T"/>.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Query query,
        ISerializer<T> elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// The provided page is the first page yielded.
    /// </summary>
    /// <typeparam name="T">The type of the data expected in each page.</typeparam>
    /// <param name="page">The initial page.</param>
    /// <param name="elemSerializer">A data serializer for the page element type.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>An asynchronous enumerable of pages, each containing a list of items of type <typeparamref name="T"/>.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Page<T> page,
        ISerializer<T> elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// </summary>
    /// <param name="query">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="elemSerializer">A data serializer for the page element type.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the result of the query execution.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Query query,
        ISerializer elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously iterates over pages of a Fauna query result, automatically fetching subsequent pages using the 'after' cursor.
    /// The provided page is the first page yielded.
    /// </summary>
    /// <param name="page">The FQL query object representing the query to be executed against the Fauna database.</param>
    /// <param name="elemSerializer">A data serializer for the page element type.</param>
    /// <param name="queryOptions">Optional parameters to customize the query execution, such as timeout settings and custom headers.</param>
    /// <param name="cancel">A cancellation token to use.</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the result of the query execution.</returns>
    /// <remarks>
    /// This method handles pagination by sending multiple requests to Fauna as needed, based on the presence of an 'after' cursor in the query results.
    /// </remarks>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Page<object?> page,
        ISerializer elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default);

    /// <summary>
    /// Asynchronously executes a specified FQL query against the Fauna database and returns the typed result.
    /// </summary>
    /// <typeparam name="T">The type of the result expected from the query, corresponding to the structure of the FQL query's expected response.</typeparam>
    /// <param name="reference">The reference to load.</param>
    /// <param name="cancel">A cancellation token to use</param>
    /// <returns>A Task representing the asynchronous operation, which upon completion contains the result of the query execution as <see cref="QuerySuccess{T}"/>.</returns>
    /// <exception cref="AuthenticationException">Thrown when authentication fails due to invalid credentials or other authentication issues.</exception>
    /// <exception cref="AuthorizationException">Thrown when the client lacks sufficient permissions to execute the query.</exception>
    /// <exception cref="QueryCheckException">Thrown when the query has syntax errors or is otherwise malformed.</exception>
    /// <exception cref="QueryRuntimeException">Thrown when runtime errors occur during query execution, such as invalid arguments or operational failures.</exception>
    /// <exception cref="AbortException">Thrown when the FQL `abort` function is called within the query, containing the data provided during the abort operation.</exception>
    /// <exception cref="InvalidRequestException">Thrown for improperly formatted requests or requests that Fauna cannot process.</exception>
    /// <exception cref="ContendedTransactionException">Thrown when a transaction is aborted due to concurrent modification or contention issues.</exception>
    /// <exception cref="ThrottlingException">Thrown when the query exceeds established rate limits for the Fauna service.</exception>
    /// <exception cref="QueryTimeoutException">Thrown when the query execution time exceeds the specified or default timeout period.</exception>
    /// <exception cref="ServiceException">Thrown in response to internal Fauna service errors, indicating issues on the server side.</exception>
    /// <exception cref="FaunaException">Thrown for unexpected or miscellaneous errors not covered by the other specific exception types.</exception>
    /// <exception cref="NullDocumentException">Thrown when the provided reference does not exist.</exception>
    public Task<T> LoadRefAsync<T>(
        BaseRef<T> reference,
        CancellationToken cancel = default)
        where T : notnull;
}

/// <summary>
/// The base class for Client and DataContext.
/// </summary>
public abstract class BaseClient : IClient
{
    internal BaseClient()
    {
    }

    internal abstract MappingContext MappingCtx { get; }

    internal abstract Task<QuerySuccess<T>> QueryAsyncInternal<T>(
        Query query,
        ISerializer<T> serializer,
        MappingContext ctx,
        QueryOptions? queryOptions,
        CancellationToken cancel
    );

    #region IClient

    /// <inheritdoc />
    public Task<QuerySuccess<T>> QueryAsync<T>(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
        where T : notnull =>
        QueryAsync<T>(query, Serializer.Generate<T>(MappingCtx), queryOptions, cancel);

    /// <inheritdoc />
    public Task<QuerySuccess<object?>> QueryAsync(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default) =>
        QueryAsync<object?>(query, Serializer.Dynamic, queryOptions, cancel);

    /// <inheritdoc />
    public Task<QuerySuccess<T>> QueryAsync<T>(
        Query query,
        ISerializer<T> serializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default) =>
        QueryAsyncInternal(query, serializer, MappingCtx, queryOptions, cancel);

    /// <inheritdoc />
    public Task<QuerySuccess<object?>> QueryAsync(
        Query query,
        ISerializer serializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default) =>
        QueryAsync<object?>(query, (ISerializer<object?>)serializer, queryOptions, cancel);

    /// <inheritdoc />
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
        where T : notnull =>
        PaginateAsync(query, Serializer.Generate<T>(MappingCtx), queryOptions, cancel);

    /// <inheritdoc />
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Page<T> page,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
        where T : notnull =>
        PaginateAsync(page, Serializer.Generate<T>(MappingCtx), queryOptions, cancel);

    /// <inheritdoc />
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Query query,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default) =>
        PaginateAsync(query, Serializer.Dynamic, queryOptions, cancel);

    /// <inheritdoc />
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Page<object?> page,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default) =>
        PaginateAsync(page, Serializer.Dynamic, queryOptions, cancel);

    /// <inheritdoc />
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Query query,
        ISerializer<T> elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
    {
        var serializer = new PageSerializer<T>(elemSerializer);
        return PaginateAsyncInternal(query, serializer, queryOptions, cancel);
    }

    /// <inheritdoc />
    public IAsyncEnumerable<Page<T>> PaginateAsync<T>(
        Page<T> page,
        ISerializer<T> elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
    {
        var serializer = new PageSerializer<T>(elemSerializer);
        return PaginateAsyncInternal(page, serializer, queryOptions, cancel);
    }

    /// <inheritdoc />
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Query query,
        ISerializer elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
    {
        var elemObjSer = (ISerializer<object?>)elemSerializer;
        var serializer = new PageSerializer<object?>(elemObjSer);
        return PaginateAsyncInternal(query, serializer, queryOptions, cancel);
    }

    /// <inheritdoc />
    public IAsyncEnumerable<Page<object?>> PaginateAsync(
        Page<object?> page,
        ISerializer elemSerializer,
        QueryOptions? queryOptions = null,
        CancellationToken cancel = default)
    {
        var elemObjSer = (ISerializer<object?>)elemSerializer;
        var serializer = new PageSerializer<object?>(elemObjSer);
        return PaginateAsyncInternal(page, serializer, queryOptions, cancel);
    }

    /// <inheritdoc />
    public async Task<T> LoadRefAsync<T>(
        BaseRef<T> reference,
        CancellationToken cancel = default) where T : notnull
    {
        if (reference.IsLoaded)
        {
            return reference.Get();
        }

        var q = FQL($"{reference}");
        var res = await QueryAsync(q, Serializer.Generate<BaseRef<T>>(MappingCtx), null, cancel);
        return res.Data.Get();
    }

    #endregion

    // Internally accessible for QuerySource use
    internal async IAsyncEnumerable<Page<T>> PaginateAsyncInternal<T>(
        Query query,
        PageSerializer<T> serializer,
        QueryOptions? queryOptions,
        [EnumeratorCancellation] CancellationToken cancel = default)
    {
        var p = await QueryAsyncInternal(query,
            serializer,
            MappingCtx,
            queryOptions,
            cancel);

        await foreach (var page in PaginateAsyncInternal(p.Data, serializer, queryOptions, cancel))
        {
            yield return page;
        }
    }

    private async IAsyncEnumerable<Page<T>> PaginateAsyncInternal<T>(
        Page<T> page,
        PageSerializer<T> serializer,
        QueryOptions? queryOptions,
        [EnumeratorCancellation] CancellationToken cancel = default)
    {
        yield return page;

        while (page.After is not null)
        {
            var q = new QueryExpr(new QueryLiteral($"Set.paginate('{page.After}')"));

            var response = await QueryAsyncInternal(q,
                serializer,
                MappingCtx,
                queryOptions,
                cancel);

            page = response.Data;
            yield return page;
        }
    }

    #region Streaming

    /// <summary>
    /// Opens the stream with Fauna and returns an enumerator for the stream events.
    /// </summary>
    /// <typeparam name="T">The type of event data that will be deserialized from the stream.</typeparam>
    /// <param name="eventSource">The event source to subscribe to.</param>
    /// <param name="ctx">The mapping context to use for deserializing stream events.</param>
    /// <param name="cancel">The cancellation token for the operation.</param>
    /// <returns>An async enumerator of stream events.</returns>
    /// Implementation <seealso cref="Client.SubscribeStreamInternal{T}(EventSource,MappingContext,CancellationToken)"/>
    internal abstract IAsyncEnumerator<Event<T>> SubscribeStreamInternal<T>(
        EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default) where T : notnull;

    /// <summary>
    /// Retrieves a Stream token from Fauna and returns a StreamEnumerable for the stream events.
    /// </summary>
    /// <typeparam name="T">Event Data will be deserialized to this type.</typeparam>
    /// <param name="query">The query to create the stream from Fauna.</param>
    /// <param name="queryOptions">The options for the query.</param>
    /// <param name="streamOptions">The options for the stream.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains a stream of events.</returns>
    public async Task<StreamEnumerable<T>> EventStreamAsync<T>(
        Query query,
        QueryOptions? queryOptions = null,
        StreamOptions? streamOptions = null,
        CancellationToken cancellationToken = default) where T : notnull
    {
        EventSource eventSource = streamOptions?.Token != null
            ? new EventSource(streamOptions.Token) { Options = streamOptions }
            : await GetEventSourceFromQueryAsync(query, queryOptions, cancellationToken);

        return new StreamEnumerable<T>(this, eventSource, cancellationToken);
    }

    /// <summary>
    /// Returns a StreamEnumerable for the stream events.
    /// </summary>
    /// <param name="eventSource"></param>
    /// <param name="cancellationToken"></param>
    /// <typeparam name="T">Which Type to map the Events to.</typeparam>
    /// <returns></returns>
    public async Task<StreamEnumerable<T>> EventStreamAsync<T>(
        EventSource eventSource,
        CancellationToken cancellationToken = default) where T : notnull
    {
        await Task.CompletedTask;

        return new StreamEnumerable<T>(this, eventSource, cancellationToken);
    }


    /// <summary>
    /// Opens the event feed with Fauna and returns an enumerator for the events.
    /// </summary>
    /// <typeparam name="T">The type of event data that will be deserialized from the stream.</typeparam>
    /// <param name="eventSource">The event source to subscribe to.</param>
    /// <param name="ctx">The mapping context to use for deserializing stream events.</param>
    /// <param name="cancel">The cancellation token for the operation.</param>
    /// <returns>An async enumerator of stream events.</returns>
    /// Implementation <seealso cref="Client.SubscribeFeedInternal{T}(EventSource,MappingContext,CancellationToken)"/>
    internal abstract IAsyncEnumerator<FeedPage<T>> SubscribeFeedInternal<T>(
        EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default) where T : notnull;

    /// <summary>
    /// Opens the event feed with Fauna and returns an enumerator for the events.
    /// </summary>
    /// <param name="eventSource"></param>
    /// <param name="feedOptions">The options for the feed.</param>
    /// <param name="cancellationToken">The cancellation token for the operation.</param>
    /// <typeparam name="T">Which Type to map the Events to.</typeparam>
    /// <returns></returns>
    public async Task<FeedEnumerable<T>> EventFeedAsync<T>(
        EventSource eventSource,
        FeedOptions? feedOptions = null,
        CancellationToken cancellationToken = default) where T : notnull
    {
        await Task.CompletedTask;

        if (feedOptions != null) eventSource.Options = feedOptions;

        return new FeedEnumerable<T>(this, eventSource, cancellationToken);
    }

    /// <summary>
    /// Opens the event feed with Fauna and returns an enumerator for the events.
    /// </summary>
    /// <param name="query">The query to create the stream from Fauna.</param>
    /// <param name="feedOptions">The options for the feed.</param>
    /// <param name="cancellationToken">The cancellation token for the operation.</param>
    /// <typeparam name="T">Which Type to map the Events to.</typeparam>
    /// <returns></returns>
    public async Task<FeedEnumerable<T>> EventFeedAsync<T>(
        Query query,
        FeedOptions? feedOptions = null,
        CancellationToken cancellationToken = default) where T : notnull
    {
        EventSource eventSource = await GetEventSourceFromQueryAsync(query, null, cancellationToken);
        if (feedOptions != null) eventSource.Options = feedOptions;

        return new FeedEnumerable<T>(this, eventSource, cancellationToken);
    }

    /// <summary>
    /// Retrieves an EventSource from Fauna Query
    /// </summary>
    /// <param name="query"></param>
    /// <param name="queryOptions"></param>
    /// <param name="cancellationToken"></param>
    /// <returns>EventSource returned from Query</returns>
    private async Task<EventSource> GetEventSourceFromQueryAsync(
        Query query,
        QueryOptions? queryOptions,
        CancellationToken cancellationToken)
    {
        try
        {
            var response = await QueryAsync<EventSource>(
                query,
                queryOptions,
                cancellationToken);
            return response.Data;
        }
        catch (SerializationException ex)
        {
            throw new InvalidOperationException("Query must return an EventSource.", ex);
        }
    }

    /// <summary>
    /// Opens the stream with Fauna and returns an enumerator for the stream events.
    /// </summary>
    /// <typeparam name="T">Event Data will be deserialized to this type.</typeparam>
    /// <param name="eventSource">The stream to subscribe to.</param>
    /// <param name="ctx">Mapping context for stream.</param>
    /// <param name="cancel">The cancellation token.</param>
    /// <returns>An async enumerator of stream events.</returns>
    public IAsyncEnumerator<Event<T>> SubscribeStream<T>(
        EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default) where T : notnull
    {
        return SubscribeStreamInternal<T>(eventSource, ctx, cancel);
    }

    /// <summary>
    /// Opens an event feed with Fauna and returns an enumerator for the events.
    /// </summary>
    /// <typeparam name="T">Event Data will be deserialized to this type.</typeparam>
    /// <param name="eventSource">The stream to subscribe to.</param>
    /// <param name="ctx">Mapping context for stream.</param>
    /// <param name="cancel">The cancellation token.</param>
    /// <returns>An async enumerator of stream events.</returns>
    public IAsyncEnumerator<FeedPage<T>> SubscribeFeed<T>(
        EventSource eventSource,
        MappingContext ctx,
        CancellationToken cancel = default) where T : notnull
    {
        return SubscribeFeedInternal<T>(eventSource, ctx, cancel);
    }

    #endregion
}
```