📣 Announcement - Road to v1

[aaronpowell]

Hey friends 👋 ,

It was around 18 months ago that I created this project, and it was originally designed to tackle some challenges I was having myself more than anything.

Since then, I've plugged away here and there, made a few tweaks to it, fixed some bugs, but it just trickled along.

After some recent activity around it, off the back of some conference talks I gave, I figured it was time to actively look at getting as major release out.

Today I've created PR #53, which is the work going in to making a v1 release, and here I want to mention some of the major changes, as there are breaking changes.

Changing the Cosmos SDK dependency

When I created the library I decided to use the v4 SDK, which was in preview, working on the assumption that it was coming along soon. Well, 18 months later and it's still in preview, with no indication as to when it's likely to be released (and hasn't had any updates in months).

This represented a fork in the road, either I stuck with the v4 SDK and hope it does come out one day, but miss all the improvements in v3, or roll back to using the v3 SDK.

I'm made the decision that v1 will roll back to the v3 SDK, and this does represent a breaking change.

The main change that happens between v3 and v4 (for the context of this library) is that v4 uses IAsyncEnumerable as a way to iterate over the result set, which with F# we map using AsyncSeq.

To try and reduce the impact on existing code, I've changed the internals to continue pushing out an AsyncSeq as results, by creating that myself, rather than relying on a type conversion.

Changes to batch requests

With #23, pagination support was added, and it was represented by Page<'T>, which was returned from the SDK. With the downgrade of the SDK it no longer natively uses Page<'T>, meaning that when doing execBatchAsync, the return type is different.

On the plus side, I actually figured out paging properly, so now you can pass in a page size to the batch request and it'll return you an AsyncSeq containing in batches of the required size, so I call it a win!

New features

There's three new features being added for v1, so it's not all breaking changes!

Client caching

42 has been open for ages and since we now use the v3 SDK I figured I should follow the advice and cache the CosmosClient. Caching is done by connection string (or host/access key) and will be reused for all operations that use that value.

I've also added a Cosmos.dispose method do dispose of the client. I'll also look to making the record that contains the connection info implement IDisposable, but I need to work out how to best make it access the cache.

Change feed processor support

One of the nifty features of Cosmos is change feed processors, but they feel C#-ish to work with, so I've created a F# wrapper around it:

        let onChange changes _ =
            printfn "Changes: %A" changes
            System.Threading.Tasks.Task.CompletedTask

        let processor =
            conn
            |> Cosmos.ChangeFeed.create<Family> "changeFeedSample" onChange
            |> Cosmos.ChangeFeed.withInstanceName "consoleHost"
            |> Cosmos.ChangeFeed.leaseContainer (conn |> Cosmos.container "leaseContainer")
            |> Cosmos.ChangeFeed.build

        printfn "Starting change feed"
        do! processor.StartAsync() |> Async.AwaitTask

        printfn "Change feed started. Press any key to exit"

        Console.Read() |> ignore

Raw SDK access

FSharp.CosmosDb doesn't do everything that the Cosmos SDK does, so for those scenarios, rather than having to create your own CosmosClient, it'd be nice to access the one that's in cache. Well, now you can, using the Cosmos.Raw module, you can get the client, database and container SDK objects.

Looking for help

So this is what it's looking like for v1. I don't have a hard and fast date on when v1 will ship, the main hurdle I have is testing. While I can test against my own apps, I'd really appreciate anyone who can test it in their app, does so. You can get the pre-release package from GitHub packages - https://github.com/aaronpowell/FSharp.CosmosDb/packages/530463 and install it via NuGet.

Thanks, and let's go for a major release!

[mabasic]

I can help you test this. Let's test and ship.

My app currently reads, writes and deletes items from a container.

Let me know how can I help.

[neptunao]

Any help needed to merge the PR?

[aaronpowell]

@neptunao Have a test of the pre-release build, let me know if there's any problems.

I need to get around to finalising it (been caught up with other things)