diff --git a/Fauna/Client/IConnection.cs b/Fauna/Client/IConnection.cs index 8e2e0a9e..49a0babd 100644 --- a/Fauna/Client/IConnection.cs +++ b/Fauna/Client/IConnection.cs @@ -1,7 +1,17 @@ namespace Fauna; +/// +/// Represents an interface for connections to a Fauna database. +/// public interface IConnection { + /// + /// Asynchronously sends a POST request to the specified path with the provided body and headers. + /// + /// The path of the resource to send the request to. + /// The stream containing the request body. + /// A dictionary of headers to be included in the request. + /// A Task representing the asynchronous operation, which upon completion contains the response from the server as . Task DoPostAsync( string path, Stream body, diff --git a/Fauna/Client/QueryOptions.cs b/Fauna/Client/QueryOptions.cs index 38a780d8..62585a79 100644 --- a/Fauna/Client/QueryOptions.cs +++ b/Fauna/Client/QueryOptions.cs @@ -1,13 +1,42 @@ namespace Fauna; +/// +/// Represents the options for customizing Fauna queries. +/// public class QueryOptions { + /// + /// Gets or sets a value indicating whether the query runs as strictly serialized, affecting read-only transactions. + /// public bool? Linearized { get; set; } = null; + + /// + /// Gets or sets a value indicating whether type checking of the query is enabled or disabled before evaluation. + /// public bool? TypeCheck { get; set; } = null; + + /// + /// Gets or sets the query timeout. It defines how long the client waits for a query to complete. + /// public TimeSpan? QueryTimeout { get; set; } = null; + + /// + /// Gets or sets a string-encoded set of caller-defined tags for identifying the request in logs and response bodies. + /// Format is a list of key:value pairs, each key and value limited to [a-zA-Z0-9_]. + /// public Dictionary? QueryTags { get; set; } = null; + + /// + /// Gets or sets the trace parent identifier for distributed tracing systems. + /// public string? TraceParent { get; set; } = null; + /// + /// Combines default query options with overrides from the client configuration. + /// + /// The default query options. + /// The query options provided for a specific query, overriding the defaults. + /// A object representing the final combined set of query options. internal static QueryOptions? GetFinalQueryOptions(QueryOptions? defaultQueryOptions, QueryOptions? queryOptionOverrides) { diff --git a/Fauna/Constants/Endpoints.cs b/Fauna/Constants/Endpoints.cs index 83b196e5..38caefd4 100644 --- a/Fauna/Constants/Endpoints.cs +++ b/Fauna/Constants/Endpoints.cs @@ -1,7 +1,17 @@ namespace Fauna.Constants; +/// +/// Represents the endpoints used for accessing Fauna. +/// public readonly struct Endpoints { + /// + /// The default URI for Fauna, used for production. + /// public static readonly Uri Default = new("https://db.fauna.com"); + + /// + /// The local development URI for Fauna, used for testing or local development. + /// public static readonly Uri Local = new("http://localhost:8443"); } diff --git a/Fauna/Constants/Headers.cs b/Fauna/Constants/Headers.cs index e931d7e2..1e2007d3 100644 --- a/Fauna/Constants/Headers.cs +++ b/Fauna/Constants/Headers.cs @@ -1,16 +1,63 @@ namespace Fauna.Constants; +/// +/// Contains constant values for HTTP header names used in Fauna API requests. +/// internal readonly struct Headers { + /// + /// Header for the authorization token in API requests. + /// public const string Authorization = "Authorization"; + + /// + /// Header indicating the minimum snapshot time for the query execution based on the highest transaction timestamp observed by the client. + /// public const string LastTxnTs = "X-Last-Txn-Ts"; + + /// + /// Header to enforce strictly serialized execution of the query, affecting read-only transactions. + /// public const string Linearized = "X-Linearized"; + + /// + /// Header indicating the maximum number of retries for a transaction due to contention failure before returning an error. + /// public const string MaxContentionRetries = "X-Max-Contention-Retries"; + + /// + /// Header specifying the query timeout in milliseconds. + /// public const string QueryTimeoutMs = "X-Query-Timeout-Ms"; + + /// + /// Header to enable or disable type checking of the query before evaluation. + /// public const string TypeCheck = "X-Typecheck"; + + /// + /// Header for passing custom, string-encoded tags for request identification in logs and responses. + /// public const string QueryTags = "X-Query-Tags"; + + /// + /// Header for the trace parent identifier in distributed tracing systems. + /// public const string TraceParent = "Traceparent"; + + /// + /// Header indicating the driver used for the API request. + /// public const string Driver = "X-Driver"; + + /// + /// Header for specifying the environment of the driver used in the API request. + /// public const string DriverEnv = "X-Driver-Env"; + + /// + /// Header for specifying the encoded format for query arguments and response data. + /// Options are 'simple' and 'tagged'. 'Simple' is the default format. + /// public const string Format = "X-Format"; } diff --git a/Fauna/Constants/ResponseFields.cs b/Fauna/Constants/ResponseFields.cs index f4e346e0..3327a5c5 100644 --- a/Fauna/Constants/ResponseFields.cs +++ b/Fauna/Constants/ResponseFields.cs @@ -1,30 +1,119 @@ namespace Fauna.Constants; +/// +/// Contains constant values for the response field names returned by Fauna API queries. +/// internal readonly struct ResponseFields { - // Top-level fields + #region Top-level fields + + /// + /// Field name for the main data content of the response. + /// public const string DataFieldName = "data"; + + /// + /// Field name for the transaction timestamp of the last transaction seen by the request. + /// public const string LastSeenTxnFieldName = "txn_ts"; + + /// + /// Field name for static type information in the response. + /// public const string StaticTypeFieldName = "static_type"; + + /// + /// Field name for statistical information about the query execution. + /// public const string StatsFieldName = "stats"; + + /// + /// Field name for the schema version of the database at the time of query execution. + /// public const string SchemaVersionFieldName = "schema_version"; + + /// + /// Field name for the summary information about the query execution. + /// public const string SummaryFieldName = "summary"; + + /// + /// Field name for query tags associated with the request, used in logging and monitoring. + /// public const string QueryTagsFieldName = "query_tags"; + + /// + /// Field name for error information if the query fails. + /// public const string ErrorFieldName = "error"; - // "stats" block + #endregion + + #region "stats" block + + /// + /// Field name for the number of compute operations consumed by the query. + /// public const string Stats_ComputeOpsFieldName = "compute_ops"; + + /// + /// Field name for the number of read operations consumed by the query. + /// public const string Stats_ReadOps = "read_ops"; + + /// + /// Field name for the number of write operations consumed by the query. + /// public const string Stats_WriteOps = "write_ops"; + + /// + /// Field name for the query processing time in milliseconds. + /// public const string Stats_QueryTimeMs = "query_time_ms"; + + /// + /// Field name for the write contention retry count. + /// public const string Stats_ContentionRetries = "contention_retries"; + + /// + /// Field name for the amount of data read from storage, in bytes. + /// public const string Stats_StorageBytesRead = "storage_bytes_read"; + + /// + /// Field name for the amount of data written to storage, in bytes. + /// public const string Stats_StorageBytesWrite = "storage_bytes_write"; + + /// + /// Field name for the types of operations that were limited or approaching rate limits. + /// public const string Stats_RateLimitsHit = "rate_limits_hit"; - // "error" block + #endregion + + #region "error" block + + /// + /// Field name for the error code when a query fails. + /// public const string Error_CodeFieldName = "code"; + + /// + /// Field name for the detailed message describing the cause of the error. + /// public const string Error_MessageFieldName = "message"; + + /// + /// Field name for constraint failures that occurred during the query. + /// public const string Error_ConstraintFailuresFieldName = "constraint_failures"; + + /// + /// Field name for information about an abort operation within a transaction. + /// public const string Error_AbortFieldName = "abort"; + + #endregion } diff --git a/Fauna/Exceptions/AuthenticationException.cs b/Fauna/Exceptions/AuthenticationException.cs index bfe2e50e..c9fa368a 100644 --- a/Fauna/Exceptions/AuthenticationException.cs +++ b/Fauna/Exceptions/AuthenticationException.cs @@ -1,5 +1,9 @@ namespace Fauna.Exceptions; +/// +/// Represents an exception thrown when there is an authentication error in Fauna. +/// Corresponds to the 'unauthorized' error code in Fauna. +/// public class AuthenticationException : ServiceException { public AuthenticationException(QueryFailure queryFailure, string message) diff --git a/Fauna/Exceptions/AuthorizationException.cs b/Fauna/Exceptions/AuthorizationException.cs index f4a1521c..4a869d22 100644 --- a/Fauna/Exceptions/AuthorizationException.cs +++ b/Fauna/Exceptions/AuthorizationException.cs @@ -1,5 +1,9 @@ namespace Fauna.Exceptions; +/// +/// Represents an exception thrown when there is an authorization error in Fauna. +/// Corresponds to the 'forbidden' error code in Fauna. +/// public class AuthorizationException : ServiceException { public AuthorizationException(QueryFailure queryFailure, string message) diff --git a/Fauna/Exceptions/QueryCheckException.cs b/Fauna/Exceptions/QueryCheckException.cs index f36da0ad..22ee3cb7 100644 --- a/Fauna/Exceptions/QueryCheckException.cs +++ b/Fauna/Exceptions/QueryCheckException.cs @@ -1,5 +1,8 @@ namespace Fauna.Exceptions; +/// +/// Represents exceptions thrown when the query has syntax errors. +/// public class QueryCheckException : ServiceException { public QueryCheckException(QueryFailure queryFailure, string message) diff --git a/Fauna/Exceptions/QueryTimeoutException.cs b/Fauna/Exceptions/QueryTimeoutException.cs index 5727cc6d..d122c0f6 100644 --- a/Fauna/Exceptions/QueryTimeoutException.cs +++ b/Fauna/Exceptions/QueryTimeoutException.cs @@ -1,5 +1,8 @@ namespace Fauna.Exceptions; +/// +/// Represents exceptions thrown when the query execution time exceeds the specified or default timeout period. +/// public class QueryTimeoutException : ServiceException { public QueryTimeoutException(QueryFailure queryFailure, string message) diff --git a/Fauna/Exceptions/WriteConstraintException.cs b/Fauna/Exceptions/WriteConstraintException.cs index c32e5d89..2807722a 100644 --- a/Fauna/Exceptions/WriteConstraintException.cs +++ b/Fauna/Exceptions/WriteConstraintException.cs @@ -1,5 +1,8 @@ namespace Fauna.Exceptions; +/// +/// Represents exceptions thrown due to constraint violations on write operations. +/// public class WriteConstraintException : QueryRuntimeException { public WriteConstraintException(QueryFailure queryFailure, string message) diff --git a/Fauna/Query/QueryExpr.cs b/Fauna/Query/QueryExpr.cs index 66103148..0838f996 100644 --- a/Fauna/Query/QueryExpr.cs +++ b/Fauna/Query/QueryExpr.cs @@ -31,8 +31,16 @@ public QueryExpr(params IQueryFragment[] fragments) /// public ReadOnlyCollection Unwrap { get; } + /// + /// Gets the readonly collection of query fragments. + /// public ReadOnlyCollection Fragments => Unwrap; + /// + /// Serializes the query expression. + /// + /// The serialization context. + /// The writer to serialize the query expression to. public override void Serialize(SerializationContext ctx, Utf8FaunaWriter writer) { writer.WriteStartObject(); @@ -46,8 +54,18 @@ public override void Serialize(SerializationContext ctx, Utf8FaunaWriter writer) writer.WriteEndObject(); } + /// + /// Determines whether the specified QueryExpr is equal to the current QueryExpr. + /// + /// The QueryExpr to compare with the current QueryExpr. + /// true if the specified QueryExpr is equal to the current QueryExpr; otherwise, false. public override bool Equals(Query? o) => IsEqual(o as QueryExpr); + /// + /// Determines whether the specified object is equal to the current QueryExpr. + /// + /// The object to compare with the current QueryExpr. + /// true if the specified object is equal to the current QueryExpr; otherwise, false. public override bool Equals(object? o) { if (ReferenceEquals(this, o)) @@ -58,8 +76,16 @@ public override bool Equals(object? o) return o is QueryExpr expr && IsEqual(expr); } + /// + /// The default hash function. + /// + /// A hash code for the current QueryExpr. public override int GetHashCode() => Fragments.GetHashCode(); + /// + /// Returns a string that represents the current QueryExpr. + /// + /// A string that represents the current QueryExpr. public override string ToString() => $"QueryExpr({string.Join(",", Fragments)})"; private bool IsEqual(QueryExpr? o) @@ -77,6 +103,12 @@ private bool IsEqual(QueryExpr? o) return Fragments.SequenceEqual(o.Fragments); } + /// + /// Determines whether two specified instances of QueryExpr are equal. + /// + /// The first QueryExpr to compare. + /// The second QueryExpr to compare. + /// true if left and right are equal; otherwise, false. public static bool operator ==(QueryExpr left, QueryExpr right) { if (ReferenceEquals(left, right)) @@ -92,6 +124,12 @@ private bool IsEqual(QueryExpr? o) return left.Equals(right); } + /// + /// Determines whether two specified instances of QueryExpr are not equal. + /// + /// The first QueryExpr to compare. + /// The second QueryExpr to compare. + /// true if left and right are not equal; otherwise, false. public static bool operator !=(QueryExpr left, QueryExpr right) { return !(left == right); diff --git a/Fauna/Query/QueryLiteral.cs b/Fauna/Query/QueryLiteral.cs index 0e03f256..8c7a8e05 100644 --- a/Fauna/Query/QueryLiteral.cs +++ b/Fauna/Query/QueryLiteral.cs @@ -27,16 +27,30 @@ public QueryLiteral(string v) /// public string Unwrap { get; } + /// + /// Returns a string that represents the current QueryLiteral. + /// + /// A string that represents the current QueryLiteral. public override string ToString() { return $"QueryLiteral({Unwrap})"; } + /// + /// Serializes the query literal. + /// + /// The serialization context. + /// The writer to serialize the query literal to. public void Serialize(SerializationContext ctx, Utf8FaunaWriter writer) { writer.WriteStringValue(Unwrap); } + /// + /// Determines whether the specified object is equal to the current QueryLiteral. + /// + /// The object to compare with the current QueryLiteral. + /// true if the specified object is equal to the current QueryLiteral; otherwise, false. public override bool Equals(object? other) { var otherQuery = other as IQueryFragment; @@ -59,16 +73,32 @@ public override bool Equals(object? other) return false; } + /// + /// The default hash function. + /// + /// A hash code for the current QueryLiteral. public override int GetHashCode() { return Unwrap.GetHashCode(); } + /// + /// Determines whether two specified instances of QueryLiteral are equal. + /// + /// The first QueryLiteral to compare. + /// The second QueryLiteral to compare. + /// true if left and right are equal; otherwise, false. public static bool operator ==(QueryLiteral left, QueryLiteral right) { return Equals(left, right); } + /// + /// Determines whether two specified instances of QueryLiteral are not equal. + /// + /// The first QueryLiteral to compare. + /// The second QueryLiteral to compare. + /// true if left and right are not equal; otherwise, false. public static bool operator !=(QueryLiteral left, QueryLiteral right) { return !Equals(left, right); diff --git a/Fauna/Query/QueryVal.cs b/Fauna/Query/QueryVal.cs index 7bbb3715..f18c087c 100644 --- a/Fauna/Query/QueryVal.cs +++ b/Fauna/Query/QueryVal.cs @@ -22,6 +22,11 @@ public QueryVal(T v) /// public T Unwrap { get; } + /// + /// Serializes the query value. + /// + /// The serialization context. + /// The writer to serialize the query value to. public override void Serialize(SerializationContext ctx, Utf8FaunaWriter writer) { writer.WriteStartObject(); @@ -30,8 +35,18 @@ public override void Serialize(SerializationContext ctx, Utf8FaunaWriter writer) writer.WriteEndObject(); } + /// + /// Determines whether the specified QueryVal is equal to the current QueryVal. + /// + /// The QueryVal to compare with the current QueryVal. + /// true if the specified QueryVal is equal to the current QueryVal; otherwise, false. public override bool Equals(Query? o) => IsEqual(o as QueryVal); + /// + /// Determines whether the specified object is equal to the current QueryVal. + /// + /// The object to compare with the current QueryVal. + /// true if the specified object is equal to the current QueryVal; otherwise, false. public override bool Equals(object? o) { if (ReferenceEquals(this, o)) @@ -52,10 +67,24 @@ public override bool Equals(object? o) return IsEqual(o as QueryVal); } + /// + /// The default hash function. + /// + /// A hash code for the current QueryVal. public override int GetHashCode() => Unwrap != null ? EqualityComparer.Default.GetHashCode(Unwrap) : 0; + /// + /// Returns a string that represents the current QueryVal. + /// + /// A string that represents the current QueryVal. public override string ToString() => $"QueryVal({Unwrap})"; + /// + /// Determines whether two specified instances of QueryVal are equal. + /// + /// The first QueryVal to compare. + /// The second QueryVal to compare. + /// true if left and right are equal; otherwise, false. public static bool operator ==(QueryVal left, QueryVal right) { if (ReferenceEquals(left, right)) @@ -71,6 +100,12 @@ public override bool Equals(object? o) return left.Equals(right); } + /// + /// Determines whether two specified instances of QueryVal are not equal. + /// + /// The first QueryVal to compare. + /// The second QueryVal to compare. + /// true if left and right are not equal; otherwise, false. public static bool operator !=(QueryVal left, QueryVal right) { return !(left == right); diff --git a/Fauna/Response/ErrorInfo.cs b/Fauna/Response/ErrorInfo.cs index 3195385f..07b49efd 100644 --- a/Fauna/Response/ErrorInfo.cs +++ b/Fauna/Response/ErrorInfo.cs @@ -3,17 +3,32 @@ namespace Fauna; +/// +/// Contains detailed information about an error in a query response. +/// public readonly struct ErrorInfo { + /// + /// The error code when a query fails. + /// [JsonPropertyName(Error_CodeFieldName)] public string Code { get; init; } + /// + /// The detailed message describing the cause of the error. + /// [JsonPropertyName(Error_MessageFieldName)] public string Message { get; init; } + /// + /// The constraint failures that occurred during the query. + /// [JsonPropertyName(Error_ConstraintFailuresFieldName)] public object ConstraintFailures { get; init; } + /// + /// The information about an abort operation within a transaction. + /// [JsonPropertyName(Error_AbortFieldName)] public object Abort { get; init; } } diff --git a/Fauna/Response/QueryInfo.cs b/Fauna/Response/QueryInfo.cs index 4bb04fc5..6926376b 100644 --- a/Fauna/Response/QueryInfo.cs +++ b/Fauna/Response/QueryInfo.cs @@ -3,16 +3,42 @@ namespace Fauna; +/// +/// Provides basic information about a query response, including transaction and schema details. +/// public class QueryInfo { protected JsonElement _responseBody; + /// + /// Gets the last transaction seen by this query. + /// public long LastSeenTxn { get; init; } + + /// + /// Gets the schema version. + /// public long SchemaVersion { get; init; } + + /// + /// Gets a summary of the query execution. + /// public string Summary { get; init; } + + /// + /// Gets a dictionary of query tags, providing additional context about the query. + /// public Dictionary? QueryTags { get; init; } + + /// + /// Gets the statistics related to the query execution. + /// public QueryStats Stats { get; init; } + /// + /// Initializes a new instance of the QueryInfo class, parsing the provided raw response text to extract common query information. + /// + /// The raw JSON response text from the Fauna. internal QueryInfo(string rawResponseText) { _responseBody = JsonSerializer.Deserialize(rawResponseText); diff --git a/Fauna/Response/QueryResponse.cs b/Fauna/Response/QueryResponse.cs index c02b2204..d94bfa70 100644 --- a/Fauna/Response/QueryResponse.cs +++ b/Fauna/Response/QueryResponse.cs @@ -4,10 +4,20 @@ namespace Fauna; +/// +/// Represents the response from a query executed. +/// public abstract class QueryResponse : QueryInfo { internal QueryResponse(string rawResponseText) : base(rawResponseText) { } + /// + /// Asynchronously parses the HTTP response message to create a QueryResponse instance. + /// + /// The expected data type of the query response. + /// Serialization context for handling response data. + /// The HTTP response message received from the Fauna database. + /// A Task that resolves to a QueryResponse instance. public static async Task GetFromHttpResponseAsync(SerializationContext ctx, HttpResponseMessage message) { QueryResponse queryResponse; @@ -27,11 +37,27 @@ public static async Task GetFromHttpResponseAsync(Serializatio } } +/// +/// Represents a successful query response. +/// +/// The type of data expected in the query result. public class QuerySuccess : QueryResponse { + /// + /// Gets the deserialized data from the query response. + /// public T Data { get; init; } + + /// + /// Gets the static type information from the query response, if available. + /// public string? StaticType { get; init; } + /// + /// Initializes a new instance of the class, deserializing the query response into the specified type. + /// + /// The serialization context used for deserializing the response data. + /// The raw JSON response text from the Fauna database. public QuerySuccess(SerializationContext ctx, string rawResponseText) : base(rawResponseText) { var dataText = _responseBody.GetProperty(DataFieldName).GetRawText(); @@ -46,10 +72,20 @@ public QuerySuccess(SerializationContext ctx, string rawResponseText) : base(raw } } +/// +/// Represents a failed query response. +/// public class QueryFailure : QueryResponse { + /// + /// Gets the error information associated with the failed query. + /// public ErrorInfo ErrorInfo { get; init; } + /// + /// Initializes a new instance of the class, parsing the provided raw response text to extract error information. + /// + /// The raw JSON response text from the Fauna that contains the error information. public QueryFailure(string rawResponseText) : base(rawResponseText) { var errorBlock = _responseBody.GetProperty(ErrorFieldName); diff --git a/Fauna/Response/QueryStats.cs b/Fauna/Response/QueryStats.cs index 9deed31e..f9bb56c7 100644 --- a/Fauna/Response/QueryStats.cs +++ b/Fauna/Response/QueryStats.cs @@ -3,32 +3,64 @@ namespace Fauna; +/// +/// Contains statistics related to the execution of a query in the Fauna database. +/// public readonly struct QueryStats { + /// + /// The number of compute operations consumed by the query. + /// [JsonPropertyName(Stats_ComputeOpsFieldName)] public int ComputeOps { get; init; } + /// + /// The number of read operations consumed by the query. + /// [JsonPropertyName(Stats_ReadOps)] public int ReadOps { get; init; } + + /// + /// The number of write operations consumed by the query. + /// [JsonPropertyName(Stats_WriteOps)] public int WriteOps { get; init; } + /// + /// The query processing time in milliseconds. + /// [JsonPropertyName(Stats_QueryTimeMs)] public int QueryTimeMs { get; init; } + /// + /// The write contention retry count. + /// [JsonPropertyName(Stats_ContentionRetries)] public int ContentionRetries { get; init; } + /// + /// The amount of data read from storage, in bytes. + /// [JsonPropertyName(Stats_StorageBytesRead)] public int StorageBytesRead { get; init; } + /// + /// The amount of data written to storage, in bytes. + /// [JsonPropertyName(Stats_StorageBytesWrite)] public int StorageBytesWrite { get; init; } + /// + /// The types of operations that were limited or approaching rate limits. + /// [JsonPropertyName(Stats_RateLimitsHit)] public List RateLimitsHit { get; init; } + /// + /// Returns a string representation of the query statistics. + /// + /// A string detailing the query execution statistics. public override readonly string ToString() { return $"compute: {ComputeOps}, read: {ReadOps}, write: {WriteOps}, " + diff --git a/Fauna/Serialization/Attributes/FaunaObjectAttribute.cs b/Fauna/Serialization/Attributes/FaunaObjectAttribute.cs index 03a5f4f0..0649e785 100644 --- a/Fauna/Serialization/Attributes/FaunaObjectAttribute.cs +++ b/Fauna/Serialization/Attributes/FaunaObjectAttribute.cs @@ -1,5 +1,8 @@ namespace Fauna.Serialization.Attributes; +/// +/// Attribute used to indicate that a class represents a Fauna object. +/// [AttributeUsage(AttributeTargets.Class)] public class FaunaObjectAttribute : Attribute { diff --git a/Fauna/Serialization/Attributes/FieldAttribute.cs b/Fauna/Serialization/Attributes/FieldAttribute.cs index 8383816a..f8b591c2 100644 --- a/Fauna/Serialization/Attributes/FieldAttribute.cs +++ b/Fauna/Serialization/Attributes/FieldAttribute.cs @@ -2,11 +2,25 @@ namespace Fauna.Serialization.Attributes; +/// +/// Attribute used to specify properties of a field in a Fauna object. +/// [AttributeUsage(AttributeTargets.Property)] public class FieldAttribute : Attribute { + /// + /// Gets or sets the property information associated with this field. + /// public PropertyInfo? Info { get; set; } + + /// + /// Gets or sets the name of the field. + /// public string Name { get; set; } + + /// + /// Gets or sets the type of the field. + /// public FaunaType? Type { get; set; } diff --git a/Fauna/Serialization/FaunaType.cs b/Fauna/Serialization/FaunaType.cs index 1597ac7f..07e98a4c 100644 --- a/Fauna/Serialization/FaunaType.cs +++ b/Fauna/Serialization/FaunaType.cs @@ -1,5 +1,8 @@ namespace Fauna.Serialization; +/// +/// Enumerates the different types of data that can be stored in Fauna. +/// public enum FaunaType { Int, diff --git a/Fauna/Serialization/SerializationContext.cs b/Fauna/Serialization/SerializationContext.cs index 44f5b468..e4be004d 100644 --- a/Fauna/Serialization/SerializationContext.cs +++ b/Fauna/Serialization/SerializationContext.cs @@ -3,10 +3,18 @@ namespace Fauna.Serialization; +/// +/// Represents the context for serialization and deserialization operations within Fauna. +/// public class SerializationContext { private readonly Dictionary> _registry = new(); + /// + /// Retrieves the mapping of property names to their corresponding for a given .NET type. + /// + /// The type for which the field map is requested. + /// A dictionary where keys are property names and values are the corresponding instances. public Dictionary GetFieldMap(Type t) { if (_registry.TryGetValue(t, out var fieldMap)) diff --git a/Fauna/Serialization/SerializationException.cs b/Fauna/Serialization/SerializationException.cs index 08e233b9..968ccef5 100644 --- a/Fauna/Serialization/SerializationException.cs +++ b/Fauna/Serialization/SerializationException.cs @@ -1,7 +1,8 @@ -using System.Transactions; - namespace Fauna.Serialization; +/// +/// Represents error that occur during serialization and deserialization of Fauna data. +/// public class SerializationException : Exception { public SerializationException(string? message) : base(message) diff --git a/Fauna/Serialization/Serializer.Deserialize.cs b/Fauna/Serialization/Serializer.Deserialize.cs index 13d525a0..cbb344c4 100644 --- a/Fauna/Serialization/Serializer.Deserialize.cs +++ b/Fauna/Serialization/Serializer.Deserialize.cs @@ -3,8 +3,18 @@ namespace Fauna.Serialization; +/// +/// Represents methods for serializing and deserializing objects to and from Fauna format. +/// public static partial class Serializer { + /// + /// Deserializes data into a specified .NET type. + /// + /// The type of the object to deserialize to. + /// The serialization context. + /// The UTF8 reader. + /// The deserialized object. public static T Deserialize(SerializationContext context, ref Utf8FaunaReader reader) { return (T)Deserialize(context, ref reader, typeof(T))!; diff --git a/Fauna/Serialization/Serializer.Serialize.cs b/Fauna/Serialization/Serializer.Serialize.cs index aef26f04..09844860 100644 --- a/Fauna/Serialization/Serializer.Serialize.cs +++ b/Fauna/Serialization/Serializer.Serialize.cs @@ -1,8 +1,10 @@ -using System.Globalization; using Module = Fauna.Types.Module; namespace Fauna.Serialization; +/// +/// Represents methods for serializing and deserializing objects to and from Fauna format. +/// public static partial class Serializer { @@ -11,6 +13,14 @@ public static partial class Serializer "@int", "@long", "@double", "@date", "@time", "@mod", "@ref", "@doc", "@set", "@object" }; + /// + /// Serializes an object to a Fauna compatible format. + /// + /// The context for serialization. + /// The writer to serialize the object to. + /// The object to serialize. + /// Optional type hint for the object. + /// Thrown when serialization fails. public static void Serialize(SerializationContext context, Utf8FaunaWriter writer, object? obj, FaunaType? typeHint = null) { if (typeHint != null) diff --git a/Fauna/Serialization/TokenType.cs b/Fauna/Serialization/TokenType.cs index 0e2e5787..e7f4c50c 100644 --- a/Fauna/Serialization/TokenType.cs +++ b/Fauna/Serialization/TokenType.cs @@ -1,6 +1,8 @@ namespace Fauna.Serialization; - +/// +/// Enumerates the types of tokens used in Fauna serialization. +/// public enum TokenType { diff --git a/Fauna/Serialization/Utf8FaunaReader.cs b/Fauna/Serialization/Utf8FaunaReader.cs index 39e5e57f..e5c1ddbc 100644 --- a/Fauna/Serialization/Utf8FaunaReader.cs +++ b/Fauna/Serialization/Utf8FaunaReader.cs @@ -6,6 +6,9 @@ namespace Fauna.Serialization; +/// +/// Represents a reader that provides fast, non-cached, forward-only access to serialized data. +/// public ref struct Utf8FaunaReader { private Utf8JsonReader _json; @@ -22,6 +25,10 @@ public ref struct Utf8FaunaReader }; private string? _taggedTokenValue = null; + + /// + /// Gets the type of the current token. + /// public TokenType CurrentTokenType { get; private set; } private enum TokenTypeInternal @@ -30,12 +37,20 @@ private enum TokenTypeInternal StartEscapedObject, } + /// + /// Initializes a new Utf8FaunaReader to read from a ReadOnlySequence of bytes. + /// + /// The sequence of bytes to read from. public Utf8FaunaReader(ReadOnlySequence bytes) { _json = new Utf8JsonReader(bytes); CurrentTokenType = TokenType.None; } + /// + /// Initializes a new Utf8FaunaReader to read from a string. + /// + /// The string to read from. public Utf8FaunaReader(string str) { var bytes = Encoding.UTF8.GetBytes(str); @@ -44,6 +59,9 @@ public Utf8FaunaReader(string str) CurrentTokenType = TokenType.None; } + /// + /// Skips the value of the current token. + /// public void Skip() { switch (CurrentTokenType) @@ -67,6 +85,10 @@ private void SkipInternal() } } + /// + /// Reads the next token from the source. + /// + /// true if the token was read successfully; otherwise, false. public bool Read() { _taggedTokenValue = null; @@ -129,6 +151,11 @@ public bool Read() return true; } + /// + /// Gets the value of the current token. + /// + /// The value of the current token, or null if no value is associated with the token. + /// Thrown when an error occurs during token value retrieval. public object? GetValue() { return CurrentTokenType switch @@ -145,7 +172,10 @@ public bool Read() }; } - + /// + /// Retrieves a string value from the current token. + /// + /// A string representation of the current token's value. public string? GetString() { if (CurrentTokenType != TokenType.String && CurrentTokenType != TokenType.FieldName) @@ -163,6 +193,10 @@ public bool Read() } } + /// + /// Retrieves a boolean value from the current JSON token. + /// + /// A boolean representation of the current token's value. public bool GetBoolean() { try @@ -175,6 +209,10 @@ public bool GetBoolean() } } + /// + /// Retrieves a DateTime value from the current token. + /// + /// A DateTime representation of the current token's value. public DateTime GetDate() { ValidateTaggedType(TokenType.Date); @@ -189,6 +227,10 @@ public DateTime GetDate() } } + /// + /// Retrieves a double value from the current token. + /// + /// A double representation of the current token's value. public double GetDouble() { ValidateTaggedType(TokenType.Double); @@ -203,6 +245,10 @@ public double GetDouble() } } + /// + /// Retrieves a decimal value from the current token. + /// + /// A decimal representation of the current token's value. public decimal GetDoubleAsDecimal() { ValidateTaggedType(TokenType.Double); @@ -217,6 +263,10 @@ public decimal GetDoubleAsDecimal() } } + /// + /// Retrieves an integer value from the current token. + /// + /// An integer representation of the current token's value. public int GetInt() { ValidateTaggedType(TokenType.Int); @@ -231,6 +281,10 @@ public int GetInt() } } + /// + /// Retrieves a long value from the current token. + /// + /// A long representation of the current token's value. public long GetLong() { ValidateTaggedType(TokenType.Long); @@ -245,7 +299,10 @@ public long GetLong() } } - + /// + /// Retrieves a Module object from the current token. + /// + /// A Module representation of the current token's value. public Module GetModule() { ValidateTaggedType(TokenType.Module); @@ -253,6 +310,10 @@ public Module GetModule() return new Module(_taggedTokenValue!); } + /// + /// Retrieves a DateTime value from the current token. + /// + /// A DateTime representation of the current token's value. public DateTime GetTime() { ValidateTaggedType(TokenType.Time); @@ -267,36 +328,71 @@ public DateTime GetTime() } } + /// + /// Tries to retrieve a string value from the current token. + /// + /// When this method returns, contains the string value, if the conversion succeeded, or null if the conversion failed. + /// true if the token's value could be converted to a string; otherwise, false. public string TryGetString(out string value) { throw new NotImplementedException(); } + /// + /// Tries to retrieve a boolean value from the current token. + /// + /// When this method returns, contains the boolean value, if the conversion succeeded, or false if the conversion failed. + /// true if the token's value could be converted to a boolean; otherwise, false. public bool TryGetBoolean(out bool value) { throw new NotImplementedException(); } + /// + /// Tries to retrieve a DateTime value from the current token. + /// + /// When this method returns, contains the DateTime value, if the conversion succeeded, or the default DateTime value if the conversion failed. + /// true if the token's value could be converted to a DateTime; otherwise, false. public DateTime TryGetDateTime(out DateTime value) { throw new NotImplementedException(); } + /// + /// Tries to retrieve a double value from the current token. + /// + /// When this method returns, contains the double value, if the conversion succeeded, or 0.0 if the conversion failed. + /// true if the token's value could be converted to a double; otherwise, false. public double TryGetDouble(out double value) { throw new NotImplementedException(); } + /// + /// Tries to retrieve an integer value from the current token. + /// + /// When this method returns, contains the integer value, if the conversion succeeded, or 0 if the conversion failed. + /// true if the token's value could be converted to an integer; otherwise, false. public int TryGetInt(out int value) { throw new NotImplementedException(); } + /// + /// Tries to retrieve a long value from the current token. + /// + /// When this method returns, contains the long value, if the conversion succeeded, or 0 if the conversion failed. + /// true if the token's value could be converted to a long; otherwise, false. public long TryGetLong(out long value) { throw new NotImplementedException(); } + /// + /// Tries to retrieve a Module object from the current token. + /// + /// When this method returns, contains the Module object, if the conversion succeeded, or null if the conversion failed. + /// true if the token's value could be converted to a Module; otherwise, false. public Module TryGetModule(out Module value) { throw new NotImplementedException(); diff --git a/Fauna/Serialization/Utf8FaunaWriter.cs b/Fauna/Serialization/Utf8FaunaWriter.cs index d6f85f60..65fba443 100644 --- a/Fauna/Serialization/Utf8FaunaWriter.cs +++ b/Fauna/Serialization/Utf8FaunaWriter.cs @@ -5,49 +5,82 @@ namespace Fauna.Serialization; +/// +/// Provides functionality for writing data in a streaming manner to a buffer or a stream. +/// public sealed class Utf8FaunaWriter : IAsyncDisposable, IDisposable { private readonly Utf8JsonWriter _writer; + + /// + /// Initializes a new instance of the Utf8FaunaWriter class with a specified buffer writer. + /// + /// The buffer writer to write to. public Utf8FaunaWriter(IBufferWriter bufferWriter) { _writer = new Utf8JsonWriter(bufferWriter); } + /// + /// Initializes a new instance of the Utf8FaunaWriter class with a specified stream. + /// + /// The stream to write to. public Utf8FaunaWriter(Stream stream) { _writer = new Utf8JsonWriter(stream); } + /// + /// Flushes the written data to the underlying buffer or stream. + /// public void Flush() { _writer.Flush(); } + /// + /// Asynchronously flushes the written data to the underlying buffer or stream. + /// public async ValueTask FlushAsync() { await _writer.FlushAsync(); } + /// + /// Disposes the underlying writer. + /// public void Dispose() { _writer.Dispose(); } + /// + /// Asynchronously disposes the underlying writer. + /// public async ValueTask DisposeAsync() { await _writer.DisposeAsync(); } + /// + /// Writes the beginning of an object. + /// public void WriteStartObject() { _writer.WriteStartObject(); } + /// + /// Writes the end of an object. + /// public void WriteEndObject() { _writer.WriteEndObject(); } + /// + /// Writes the beginning of a specially tagged object. + /// public void WriteStartEscapedObject() { _writer.WriteStartObject(); @@ -55,22 +88,34 @@ public void WriteStartEscapedObject() _writer.WriteStartObject(); } + /// + /// Writes the end of a specially tagged object. + /// public void WriteEndEscapedObject() { _writer.WriteEndObject(); _writer.WriteEndObject(); } + /// + /// Writes the beginning of an array. + /// public void WriteStartArray() { _writer.WriteStartArray(); } + /// + /// Writes the end of an array. + /// public void WriteEndArray() { _writer.WriteEndArray(); } + /// + /// Writes the beginning of a reference object. + /// public void WriteStartRef() { _writer.WriteStartObject(); @@ -78,54 +123,97 @@ public void WriteStartRef() _writer.WriteStartObject(); } + /// + /// Writes the end of a reference object. + /// public void WriteEndRef() { _writer.WriteEndObject(); _writer.WriteEndObject(); } + /// + /// Writes a double value with a specific field name. + /// + /// The name of the field. + /// The decimal value to write. public void WriteDouble(string fieldName, decimal value) { WriteFieldName(fieldName); WriteDoubleValue(value); } + /// + /// Writes a double value with a specific field name. + /// + /// The name of the field. + /// The double value to write. public void WriteDouble(string fieldName, double value) { WriteFieldName(fieldName); WriteDoubleValue(value); } + /// + /// Writes an integer value with a specific field name. + /// + /// The name of the field. + /// The integer value to write. public void WriteInt(string fieldName, int value) { WriteFieldName(fieldName); WriteIntValue(value); } + /// + /// Writes a long integer value with a specific field name. + /// + /// The name of the field. + /// The long integer value to write. public void WriteLong(string fieldName, long value) { WriteFieldName(fieldName); WriteLongValue(value); } + /// + /// Writes a string value with a specific field name. + /// + /// The name of the field. + /// The string value to write. public void WriteString(string fieldName, string value) { WriteFieldName(fieldName); WriteStringValue(value); } + /// + /// Writes a date value with a specific field name. + /// + /// The name of the field. + /// The DateTime value to write. public void WriteDate(string fieldName, DateTime value) { WriteFieldName(fieldName); WriteDateValue(value); } + /// + /// Writes a time value with a specific field name. + /// + /// The name of the field. + /// The DateTime value to write. public void WriteTime(string fieldName, DateTime value) { WriteFieldName(fieldName); WriteTimeValue(value); } + /// + /// Writes a boolean value with a specific field name. + /// + /// The name of the field. + /// The boolean value to write. public void WriteBoolean(string fieldName, bool value) { WriteFieldName(fieldName); @@ -133,23 +221,41 @@ public void WriteBoolean(string fieldName, bool value) } + /// + /// Writes a null value with a specific field name. + /// + /// The name of the field. public void WriteNull(string fieldName) { WriteFieldName(fieldName); WriteNullValue(); } + /// + /// Writes a module value with a specific field name. + /// + /// The name of the field. + /// The module value to write. public void WriteModule(string fieldName, Module value) { WriteFieldName(fieldName); WriteModuleValue(value); } + /// + /// Writes a field name for the next value. + /// + /// The name of the field. public void WriteFieldName(string value) { _writer.WritePropertyName(value); } + /// + /// Writes a tagged value in an object. + /// + /// The tag to use for the value. + /// The value associated with the tag. public void WriteTaggedValue(string tag, string value) { WriteStartObject(); @@ -157,72 +263,122 @@ public void WriteTaggedValue(string tag, string value) WriteEndObject(); } + /// + /// Writes a double value as a tagged element. + /// + /// The double value to write. public void WriteDoubleValue(decimal value) { WriteTaggedValue("@double", value.ToString(CultureInfo.InvariantCulture)); } + /// + /// Writes a double value as a tagged element. + /// + /// The double value to write. public void WriteDoubleValue(double value) { WriteTaggedValue("@double", value.ToString(CultureInfo.InvariantCulture)); } + /// + /// Writes an integer value as a tagged element. + /// + /// The integer value to write. public void WriteIntValue(int value) { WriteTaggedValue("@int", value.ToString()); } + /// + /// Writes a long integer value as a tagged element. + /// + /// The long integer value to write. public void WriteLongValue(long value) { WriteTaggedValue("@long", value.ToString()); } + /// + /// Writes a string value as a tagged element. + /// + /// The string value to write. public void WriteStringValue(string value) { _writer.WriteStringValue(value); } - + /// + /// Writes a date value as a tagged element. + /// + /// The date value to write. public void WriteDateValue(DateTime value) { var str = value.ToString("yyyy-MM-dd"); WriteTaggedValue("@date", str); } + /// + /// Writes a date value as a tagged element. + /// + /// The date value to write. public void WriteDateValue(DateOnly value) { var str = value.ToString("yyyy-MM-dd"); WriteTaggedValue("@date", str); } + /// + /// Writes a date value as a tagged element. + /// + /// The date value to write. public void WriteDateValue(DateTimeOffset value) { var str = value.ToString("yyyy-MM-dd"); WriteTaggedValue("@date", str); } + /// + /// Writes a date value as a tagged element. + /// + /// The date value to write. public void WriteTimeValue(DateTime value) { var str = value.ToUniversalTime().ToString("o", CultureInfo.InvariantCulture); WriteTaggedValue("@time", str); } + /// + /// Writes a date value as a tagged element. + /// + /// The date value to write. public void WriteTimeValue(DateTimeOffset value) { var str = value.ToUniversalTime().ToString("o", CultureInfo.InvariantCulture); WriteTaggedValue("@time", str); } + /// + /// Writes a boolean value to the stream. + /// + /// The boolean value to write. public void WriteBooleanValue(bool value) { _writer.WriteBooleanValue(value); } + /// + /// Writes a null value to the stream. + /// public void WriteNullValue() { _writer.WriteNullValue(); } + /// + /// Writes a module value as a tagged element. + /// + /// The module value to write. public void WriteModuleValue(Module value) { WriteTaggedValue("@mod", value.Name); diff --git a/Fauna/Types/BaseDocument.cs b/Fauna/Types/BaseDocument.cs index 1a6c8b1e..9d971461 100644 --- a/Fauna/Types/BaseDocument.cs +++ b/Fauna/Types/BaseDocument.cs @@ -2,6 +2,9 @@ namespace Fauna.Types; +/// +/// Represents the base structure of a document. +/// public class BaseDocument : IReadOnlyDictionary { private readonly Dictionary _data; @@ -16,6 +19,11 @@ public class BaseDocument : IReadOnlyDictionary /// public Module Collection { get; } + /// + /// Initializes a new instance of the class with specified collection and timestamp. + /// + /// The collection to which the document belongs. + /// The timestamp of the document. public BaseDocument(Module coll, DateTime ts) { Ts = ts; @@ -23,6 +31,12 @@ public BaseDocument(Module coll, DateTime ts) _data = new Dictionary(); } + /// + /// Initializes a new instance of the class with specified collection, timestamp, and initial data. + /// + /// The collection to which the document belongs. + /// The timestamp of the document. + /// Initial data for the document in key-value pairs. public BaseDocument(Module coll, DateTime ts, Dictionary data) { Ts = ts; @@ -44,6 +58,10 @@ IEnumerator IEnumerable.GetEnumerator() return GetEnumerator(); } + /// + /// Gets the count of key-value pairs contained in the document. + /// + /// The number of key-value pairs. public int Count => _data.Count; @@ -70,6 +88,11 @@ public bool TryGetValue(string key, out object? value) return _data.TryGetValue(key, out value); } + /// + /// Gets the value associated with the specified key in the document. + /// + /// The key of the value to get. + /// The value associated with the specified key. public object? this[string key] => _data[key]; /// Gets a collection containing the keys of the data in the document. diff --git a/Fauna/Types/Module.cs b/Fauna/Types/Module.cs index 2a1a134c..89e17913 100644 --- a/Fauna/Types/Module.cs +++ b/Fauna/Types/Module.cs @@ -1,14 +1,30 @@ namespace Fauna.Types; +/// +/// Represents a module, a singleton object grouping related functionalities. +/// Modules are serialized as @mod values in tagged formats, organizing and encapsulating specific functionalities. +/// public sealed class Module : IEquatable { + /// + /// Gets the name of the module. The name is used to identify and reference the module. + /// public string Name { get; } + /// + /// Initializes a new instance of the Module class with the specified name. + /// + /// The name of the module. public Module(string name) { Name = name; } + /// + /// Determines whether the specified Module is equal to the current Module. + /// + /// The Module to compare with the current Module. + /// true if the specified Module is equal to the current Module; otherwise, false. public bool Equals(Module? other) { if (ReferenceEquals(null, other)) return false; @@ -16,6 +32,11 @@ public bool Equals(Module? other) return Name == other.Name; } + /// + /// Determines whether the specified object is equal to the current Module. + /// + /// The object to compare with the current Module. + /// true if the specified object is equal to the current Module; otherwise, false. public override bool Equals(object? obj) { if (ReferenceEquals(null, obj)) return false; @@ -24,6 +45,10 @@ public override bool Equals(object? obj) return Equals((Module)obj); } + /// + /// The default hash function. + /// + /// A hash code for the current Module. public override int GetHashCode() { return Name.GetHashCode(); diff --git a/Fauna/Types/NullDocumentRef.cs b/Fauna/Types/NullDocumentRef.cs index 1d533179..3bcef325 100644 --- a/Fauna/Types/NullDocumentRef.cs +++ b/Fauna/Types/NullDocumentRef.cs @@ -1,5 +1,8 @@ namespace Fauna.Types; +/// +/// Represents a null reference to a document, including a reason for its null state. +/// public class NullDocumentRef : DocumentRef { /// diff --git a/Fauna/Types/NullNamedDocumentRef.cs b/Fauna/Types/NullNamedDocumentRef.cs index 846b76e2..41ba7d41 100644 --- a/Fauna/Types/NullNamedDocumentRef.cs +++ b/Fauna/Types/NullNamedDocumentRef.cs @@ -1,5 +1,9 @@ namespace Fauna.Types; +/// +/// Represents a reference to a named document that is null, including a reason for its null state. +/// This class extends NamedDocumentRef to provide additional context for null references in the database. +/// public class NullNamedDocumentRef : NamedDocumentRef { ///