(#36) OfflineDbContext with operations queue. (#63)

- Adds an OfflineDbContext
- Adds an OperationsQueue
- When SaveChanges() is called, OperationsQueue is updated.
- Optional bypass of the operations queue.
- Full test coverage.

Author: adrianhall

src/CommunityToolkit.Datasync.Client/CommunityToolkit.Datasync.Client.csproj

@@ -5,11 +5,12 @@
 
   <ItemGroup>
     <InternalsVisibleTo Include="CommunityToolkit.Datasync.Client.Test" />
-    <InternalsVisibleTo Include="DynamicProxyGenAssembly2"/>
+    <InternalsVisibleTo Include="DynamicProxyGenAssembly2" />
   </ItemGroup>
 
   <ItemGroup>
     <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.7" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="8.0.7" />
     <PackageReference Include="Microsoft.Extensions.Http" Version="8.0.0" />
     <PackageReference Include="Microsoft.Azure.Core.Spatial" Version="1.1.0" />
   </ItemGroup>

src/CommunityToolkit.Datasync.Client/Exceptions/DatasyncException.cs

@@ -26,4 +26,32 @@ public DatasyncException(string? message) : base(message)
     public DatasyncException(string? message, Exception? innerException) : base(message, innerException)
     {
     }
+
+    /// <summary>
+    /// A helper method to throw the <see cref="DatasyncException"/> if the value is null.
+    /// </summary>
+    /// <param name="value">The value to check.</param>
+    /// <param name="message">The message for this exception.</param>
+    /// <exception cref="DatasyncException">Thrown if <paramref name="value"/> is null.</exception>
+    internal static void ThrowIfNull(object? value, string? message)
+    {
+        if (value is null)
+        {
+            throw new DatasyncException(message);
+        }
+    }
+
+    /// <summary>
+    /// A helper method to throw the <see cref="DatasyncException"/> if the value is null or empty.
+    /// </summary>
+    /// <param name="value">The value to check.</param>
+    /// <param name="message">The message for this exception.</param>
+    /// <exception cref="DatasyncException">Thrown if <paramref name="value"/> is null or empty.</exception>
+    internal static void ThrowIfNullOrEmpty(string? value, string? message)
+    {
+        if (string.IsNullOrEmpty(value))
+        {
+            throw new DatasyncException(message);
+        }
+    }
 }

src/CommunityToolkit.Datasync.Client/Offline/DatasyncOperation.cs

@@ -0,0 +1,81 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Microsoft.EntityFrameworkCore.Metadata.Internal;
+
+namespace CommunityToolkit.Datasync.Client.Offline;
+
+/// <summary>
+/// The kind of operation represented by a <see cref="DatasyncOperation"/> entity.
+/// </summary>
+public enum OperationKind
+{
+    /// <summary>The operation represents an addition to the entity set.</summary>
+    Add,
+    /// <summary>The operation represents a deletion from the entity set.</summary>
+    Delete,
+    /// <summary>The operation represents a replacement of the entity within the entity set.</summary>
+    Replace
+}
+
+/// <summary>
+/// The current state of the pending operation.
+/// </summary>
+public enum OperationState
+{
+    /// <summary>The operation has not been completed yet.</summary>
+    Pending,
+    /// <summary>The operation has been completed successfully.</summary>
+    Completed,
+    /// <summary>The operation failed.</summary>
+    Failed
+}
+
+/// <summary>
+/// An entity representing a pending operation against an entity set.
+/// </summary>
+public class DatasyncOperation
+{
+    /// <summary>
+    /// A unique ID for the operation.
+    /// </summary>
+    public required string Id { get; set; }
+
+    /// <summary>
+    /// The kind of operation that this entity represents.
+    /// </summary>
+    public required OperationKind Kind { get; set; }
+
+    /// <summary>
+    /// The current state of the operation.
+    /// </summary>
+    public required OperationState State { get; set; }
+
+    /// <summary>
+    /// The fully qualified name of the entity type.
+    /// </summary>
+    public required string EntityType { get; set; }
+
+    /// <summary>
+    /// The globally unique ID of the entity.
+    /// </summary>
+    public required string ItemId { get; set; }
+
+    /// <summary>
+    /// The JSON-encoded representation of the Item.
+    /// </summary>
+    public required string Item { get; set; }
+
+    /// <summary>
+    /// The sequence number for the operation.  This is incremented for each
+    /// new operation to a different entity.
+    /// </summary>
+    public required long Sequence { get; set; }
+
+    /// <summary>
+    /// The version number for the operation.  This is incremented as multiple
+    /// changes to the same entity are performed in between pushes.
+    /// </summary>
+    public required int Version { get; set; }
+}

src/CommunityToolkit.Datasync.Client/Offline/DatasyncQueueException.cs

@@ -0,0 +1,33 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace CommunityToolkit.Datasync.Client.Offline;
+
+/// <summary>
+/// An error occurred when updating the Datasync Operations Queue.
+/// </summary>
+public class DatasyncQueueException : DatasyncException
+{
+    /// <summary>
+    /// Creates a new <see cref="DatasyncQueueException"/> based on the original and updated operations.
+    /// </summary>
+    /// <param name="originalOperation"></param>
+    /// <param name="updatedOperation"></param>
+    public DatasyncQueueException(DatasyncOperation originalOperation, DatasyncOperation updatedOperation)
+        : base("The operation could not be updated due to an invalid state change.")
+    {
+        OriginalOperation = originalOperation;
+        UpdatedOperation = updatedOperation;
+    }
+
+    /// <summary>
+    /// The original operation definition.
+    /// </summary>
+    public DatasyncOperation OriginalOperation { get; }
+
+    /// <summary>
+    /// The updated operation definition.
+    /// </summary>
+    public DatasyncOperation UpdatedOperation { get; }
+}

src/CommunityToolkit.Datasync.Client/Offline/DoNotSynchronizeAttribute.cs

@@ -0,0 +1,20 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace CommunityToolkit.Datasync.Client.Offline;
+
+/// <summary>
+/// An attribute for signifying that the DbSet should not be synchronized with
+/// a remote datasync service.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property)]
+public class DoNotSynchronizeAttribute : Attribute
+{
+    /// <summary>
+    /// Creates a new <see cref="DoNotSynchronizeAttribute"/> instance.
+    /// </summary>
+    public DoNotSynchronizeAttribute()
+    {
+    }
+}