Future PowerSync .NET SDK Package Architecture

[LucDeCaf]

Future PowerSync .NET SDK Package Architecture

Overview

The current architecture of the PowerSync .NET SDK revolves around a core PowerSync.Common package which implements the main SDK behaviours and additionally bundles desktop libraries to be able to run the PowerSync SQLite extension. The library also includes interfaces which can be implemented by other packages to allow customizing the PowerSync SDK's behavior and also to allow for running the PowerSync SQLite extension on non-desktop platforms. Currently, the only official package which does this is PowerSync.Maui, which extends PowerSync.Common to include mobile builds of the PowerSync SQLite extension and behavior for loading them.

This document is on how the future architecture of the PowerSync .NET SDKs, including what will happen to the existing PowerSync.Common and PowerSync.Maui packages. This document focuses primarily on changes happening in version 1.0.0 of the PowerSync .NET SDKs.

Problem and Current Architecture

As stated above, the current architecture focuses on PowerSync.Common. The PowerSync.Common package includes SDK behaviour and loading and bundling for desktop builds of the PowerSync SQLite extension. The PowerSync.Maui package provides loading and bundling for mobile builds for the PowerSync SQLite extension.

Note: PowerSync.Maui is somewhat incorrectly named; it depends on zero MAUI libraries and can work for non-MAUI apps that target mobile via other frameworks, e.g. Uno Platform (demo).

This works, and for targets with unique/esoteric runtimes (e.g. mobile, Unity, web via Blazor), it's nice to have a Common-style package which we can depend on for behavior. However, the problem with how we currently do things is that Common is not just a behavior package; it bundles its own native libraries for desktop and has some platform-dependent code which needs to be overridden or worked around on non-desktop runtimes.

While unneeded runtimes can often be stripped from release builds using clever conditional MSBuild / .csproj properties, it is still something which needs to be worked around when designing support for a new platform and often leads to users needing to install two packages instead of one (e.g. needing to install both PowerSync.Maui and PowerSync.Common in MAUI apps).

Proposed Solutions

Solution 1: Consolidate more into PowerSync.Common

This approach goes all in on one SDK which can do almost everything.
Include mobile libraries in PowerSync.Common and only override for very specific platforms. This approach is what I implemented in this PR and would make things simpler for the most common PowerSync use cases (cross-platform mobile apps, desktop apps).

Pros: easy to develop for maintainers and consumers, simpler flow for most common use case (cross-platform mobile app).
Cons: doesn't help much with supporting other platforms; could lead to package/bundle bloat if not managed carefully.

Solution 2: Split more into separate packages, provide wrappers

This approach delegates as little native behavior as possible to the core SDK.
Introduce a new package called PowerSync.Core which includes purely cross-platform behaviour and no native code. Implement a number of provider packages which provide behavior for loading native libraries on different platforms. Finally, provide wrapper packages that bundle PowerSync.Core with a specific set of providers for common use cases.

Pros: Flexible structure, separation of native and cross-platform concerns, one package for most use cases, extensible.
Cons: Much more complex package structure; not sure how feasible this is in DotNet. Needs further testing.

Conclusion

I prefer Solution 2 in concept, but I'm not sure if it's actually feasible to make the SDK so flexible while keeping the happy-path DX that Solution 1 offers. I'd like feedback on the solutions proposed above and am open to other solutions which could help solve the problems outlined above. Thank you for reading this spiel :)

[Chriztiaan]

I agree that we should restructure this the packages. To some extent having everything in Common would be nice from an end user perspective, however I am worried that we might have platform specific code in the future (looks at Blazor menacingly) - but it's hard to say without investigating. I am leaning towards something close to solution 2 if it is feasible.

[simolus3]

IMO, we should default to a single package unless there's an unavoidable platform-inherited reason not to.

Looking at our other SDKs:

1. The PowerSync Dart SDK is a single Dart package with support for all Dart platforms (Flutter/non-Flutter and native+web). It offers multiple exports, most of which work across all platforms and some of them are platform-specific. There is no reason to split that SDK, so we don't.
2. The Kotlin SDK is split: :common contains a cross-platform code but no individual SQLite driver or HTTP client dependency. :core depends on :common plus a default client and SQLite library for the current platform. This split is mainly motivated by the fact that we want to allow users to decide between plain SQLite and SQLite3 Multiple Ciphers. In Dart we can use user-defines to control that, in Kotlin those need to make this separate packages, it's unavoidable.
3. The JavaScript SDKs are split: While we could technically have a single PowerSync package with multiple module exports for platforms, we have different dependencies for different targets (the React Native SDK shouldn't depend on comlink for example). There is no way to express those platform-specific dependencies in a package.json, so we have multiple packages.

I don't have enough experience with DotNet to make an informed comment on these proposals. If it is possible to offer a single package that works everywhere (#87 seems to suggest it is?), I think we should do that.