Improve Documentation

Author: Andrea Scuderi

Sources/BreezeDynamoDBService/BreezeCodable.swift

@@ -18,8 +18,17 @@ import FoundationEssentials
 import Foundation
 #endif
 
+/// CodableSendable is a protocol that combines Sendable and Codable.
 public protocol CodableSendable: Sendable, Codable { }
 
+/// BreezeCodable is a protocol that extends CodableSendable to include properties
+/// for a key, creation date, and update date.
+/// It is designed to be used with Breeze services that require these common fields
+/// for items stored in a database, such as DynamoDB.
+/// - Parameters:
+///   - key: A unique identifier for the item.
+///   - createdAt: An optional string representing the creation date of the item.
+///   - updatedAt: An optional string representing the last update date of the item.
 public protocol BreezeCodable: CodableSendable {
     var key: String { get set }
     var createdAt: String? { get set }

Sources/BreezeDynamoDBService/BreezeDynamoDBConfig.swift

@@ -14,7 +14,16 @@
 
 import SotoCore
 
+/// BreezeDynamoDBConfig is a configuration structure for Breeze DynamoDB service.
+/// It contains the necessary parameters to connect to a DynamoDB instance, including the region, table name, key name, and an optional endpoint.
 public struct BreezeDynamoDBConfig: Sendable {
+    
+    /// Initializes a new instance of BreezeDynamoDBConfig.
+    /// - Parameters:
+    ///   - region: The AWS region where the DynamoDB table is located.
+    ///   - tableName: The name of the DynamoDB table.
+    ///   - keyName: The name of the primary key in the DynamoDB table.
+    ///   - endpoint: An optional endpoint URL for the DynamoDB service. If not provided, the default AWS endpoint will be used.
     public init(
         region: Region,
         tableName: String,
@@ -27,8 +36,15 @@ public struct BreezeDynamoDBConfig: Sendable {
         self.endpoint = endpoint
     }
 
+    /// The AWS region where the DynamoDB table is located.
     public let region: Region
+    
+    /// The name of the DynamoDB table.
     public let tableName: String
+    
+    /// The name of the primary key in the DynamoDB table.
     public let keyName: String
+    
+    /// An optional endpoint URL for the DynamoDB service.
     public let endpoint: String?
 }

Sources/BreezeDynamoDBService/BreezeDynamoDBManager.swift

@@ -16,16 +16,32 @@ import struct Foundation.Date
 import NIO
 import SotoDynamoDB
 
+/// BreezeDynamoDBManager is a manager for handling DynamoDB operations in Breeze.
+/// It provides methods to create, read, update, delete, and list items in a DynamoDB table.
+/// It conforms to the BreezeDynamoDBManaging protocol, which defines the necessary operations for Breeze's DynamoDB integration.
+/// - Note: This manager requires a DynamoDB instance, a table name, and a key name to operate.
+/// It uses the SotoDynamoDB library to interact with AWS DynamoDB services.
 public struct BreezeDynamoDBManager: BreezeDynamoDBManaging {
+    
+    /// ServiceError defines the possible errors that can occur when interacting with the BreezeDynamoDBManager.
     enum ServiceError: Error {
+        /// Indicates that the requested item was not found in the DynamoDB table.
         case notFound
+        /// Indicates that the operation failed due to missing parameters, such as a required key.
         case missingParameters
     }
-
-    let db: DynamoDB
+    
+    /// The name of the primary key in the DynamoDB table.
     public let keyName: String
+    
+    let db: DynamoDB
     let tableName: String
 
+    /// Initializes a new instance of BreezeDynamoDBManager.
+    /// - Parameters:
+    ///   - db: The DynamoDB instance to use for operations.
+    ///   - tableName: The name of the DynamoDB table to manage.
+    ///   - keyName: The name of the primary key in the DynamoDB table.
     public init(db: DynamoDB, tableName: String, keyName: String) {
         self.db = db
         self.tableName = tableName
@@ -34,6 +50,10 @@ public struct BreezeDynamoDBManager: BreezeDynamoDBManaging {
 }
 
 public extension BreezeDynamoDBManager {
+    
+    /// Creates a new item in the DynamoDB table.
+    /// - Parameter item: The item to create, conforming to the BreezeCodable protocol.
+    /// - Returns: The created item, with its `createdAt` and `updatedAt` timestamps set.
     func createItem<T: BreezeCodable>(item: T) async throws -> T {
         var item = item
         let date = Date()
@@ -49,6 +69,9 @@ public extension BreezeDynamoDBManager {
         return try await readItem(key: item.key)
     }
 
+    /// Reads an item from the DynamoDB table by its key.
+    /// - Parameter key: The key of the item to read.
+    /// - Returns: The item with the specified key, conforming to the BreezeCodable protocol.
     func readItem<T: BreezeCodable>(key: String) async throws -> T {
         let input = DynamoDB.GetItemInput(
             key: [keyName: DynamoDB.AttributeValue.s(key)],
@@ -65,6 +88,11 @@ public extension BreezeDynamoDBManager {
         let oldUpdatedAt: String
     }
 
+    /// Updates an existing item in the DynamoDB table.
+    /// - Parameter item: The item to update, conforming to the BreezeCodable protocol.
+    /// - Returns: The updated item, with its `updatedAt` timestamp set to the current date.
+    /// - Throws: An error if the item cannot be updated, such as if the item does not exist or the condition fails.
+    /// - Important: The update operation checks that the `updatedAt` and `createdAt` timestamps match the existing values to prevent concurrent modifications.
     func updateItem<T: BreezeCodable>(item: T) async throws -> T {
         var item = item
         let oldUpdatedAt = item.updatedAt ?? ""
@@ -82,6 +110,10 @@ public extension BreezeDynamoDBManager {
         return try await readItem(key: item.key)
     }
 
+    /// Deletes an item from the DynamoDB table.
+    /// - Parameter item: The item to delete, conforming to the BreezeCodable protocol.
+    /// - Throws: An error if the item cannot be deleted, such as if the item does not exist or the condition fails.
+    /// - Important: The `updatedAt` and `createdAt` timestamps must be set on the item to ensure safe deletion. This method checks that the `updatedAt` and `createdAt` timestamps match the existing values to prevent concurrent modifications.
     func deleteItem<T: BreezeCodable>(item: T) async throws {
         guard let updatedAt = item.updatedAt,
               let createdAt = item.createdAt else {
@@ -101,6 +133,13 @@ public extension BreezeDynamoDBManager {
         return
     }
 
+    /// Lists items in the DynamoDB table with optional pagination.
+    /// - Parameters:
+    /// - key: An optional key to start the listing from, useful for pagination.
+    /// - limit: An optional limit on the number of items to return.
+    /// - Returns: A `ListResponse` containing the items and the last evaluated key for pagination.
+    /// - Throws: An error if the listing operation fails.
+    /// - Important: The `key` parameter is used to continue listing from a specific point, and the `limit` parameter controls how many items are returned in one call.
     func listItems<T: BreezeCodable>(key: String?, limit: Int?) async throws -> ListResponse<T> {
         var exclusiveStartKey: [String: DynamoDB.AttributeValue]?
         if let key {

Sources/BreezeDynamoDBService/BreezeDynamoDBManaging.swift

@@ -14,12 +14,60 @@
 
 import SotoDynamoDB
 
+/// BreezeDynamoDBManaging is a protocol that defines the methods for managing DynamoDB items.
 public protocol BreezeDynamoDBManaging: Sendable {
+    /// The keyName is the name of the primary key in the DynamoDB table.
     var keyName: String { get }
+    /// Initializes the BreezeDynamoDBManaging with the provided DynamoDB client, table name, and key name.
+    /// - Parameters:
+    ///   - db: The DynamoDB client to use for database operations.
+    ///   - tableName: The name of the DynamoDB table.
+    ///   - keyName: The name of the primary key in the DynamoDB table.
     init(db: DynamoDB, tableName: String, keyName: String)
+    
+    /// Creates a new item in the DynamoDB table.
+    /// - Parameter item: The item to create, conforming to BreezeCodable.
+    /// - Returns: The created item.
+    /// - Note:
+    ///   - The item must conform to BreezeCodable.
     func createItem<Item: BreezeCodable>(item: Item) async throws -> Item
+    
+    /// Reads an item from the DynamoDB table.
+    /// - Parameter key: The key of the item to read.
+    /// - Returns: The item read from the table, conforming to BreezeCodable.
+    /// - Throws: An error if the item could not be read.
+    /// - Note:
+    ///   - The key should match the primary key defined in the DynamoDB table.
+    ///   - The item must conform to BreezeCodable.
     func readItem<Item: BreezeCodable>(key: String) async throws -> Item
+    
+    /// Updates an existing item in the DynamoDB table.
+    /// - Parameter item: The item to update, conforming to BreezeCodable.
+    /// - Returns: The updated item.
+    /// - Throws: An error if the item could not be updated.
+    /// - Note:
+    ///   - The item must have the same primary key as an existing item in the table.
+    ///   - The item must conform to BreezeCodable.
     func updateItem<Item: BreezeCodable>(item: Item) async throws -> Item
+    
+    /// Deletes an item from the DynamoDB table.
+    /// - Parameter item: The item to delete, conforming to BreezeCodable.
+    /// - Throws: An error if the item could not be deleted.
+    /// - Returns: Void if the item was successfully deleted.
+    /// - Note:
+    ///   - The item must conform to BreezeCodable.
+    ///   - The item must have the same primary key as an existing item in the table.
     func deleteItem<Item: BreezeCodable>(item: Item) async throws
+    
+    /// Lists items in the DynamoDB table.
+    /// - Parameters:
+    ///   - key: An optional key to filter the items.
+    ///   - limit: An optional limit on the number of items to return.
+    /// - Returns: A ListResponse containing the items and an optional last evaluated key.
+    /// - Throws: An error if the items could not be listed.
+    /// - Note:
+    ///  - The items must conform to BreezeCodable.
+    ///  - The key is used to filter the items based on the primary key defined in the DynamoDB table.
+    ///  - The limit is used to control the number of items returned in the response.
     func listItems<Item: BreezeCodable>(key: String?, limit: Int?) async throws -> ListResponse<Item>
 }

Sources/BreezeDynamoDBService/BreezeDynamoDBService.swift

@@ -17,6 +17,9 @@ import AsyncHTTPClient
 import ServiceLifecycle
 import Logging
 
+/// BreezeDynamoDBServing
+/// A protocol that defines the interface for a Breeze DynamoDB service.
+/// It provides methods to access the database manager and to gracefully shutdown the service.
 public protocol BreezeDynamoDBServing: Actor {
     func dbManager() async -> BreezeDynamoDBManaging
     func gracefulShutdown() throws
@@ -26,9 +29,17 @@ public actor BreezeDynamoDBService: BreezeDynamoDBServing {
 
     private let dbManager: BreezeDynamoDBManaging
     private let logger: Logger
-    private var awsClient: AWSClient
+    private let awsClient: AWSClient
     private let httpClient: HTTPClient
+    private var isShutdown = false
 
+    /// Initializes the BreezeDynamoDBService with the provided configuration.
+    /// - Parameters:
+    ///   - config: The configuration for the DynamoDB service.
+    ///   - httpConfig: The configuration for the HTTP client.
+    ///   - logger: The logger to use for logging messages.
+    ///   - DBManagingType: The type of the BreezeDynamoDBManaging to use. Defaults to BreezeDynamoDBManager.
+    ///   This initializer sets up the AWS client, HTTP client, and the database manager.
     public init(
         config: BreezeDynamoDBConfig,
         httpConfig: BreezeHTTPClientConfig,
@@ -64,18 +75,27 @@ public actor BreezeDynamoDBService: BreezeDynamoDBServing {
         logger.info("DBManager is ready.")
     }
 
+    /// Returns the BreezeDynamoDBManaging instance.
     public func dbManager() async -> BreezeDynamoDBManaging {
         logger.info("Starting DynamoDBService...")
         return self.dbManager
     }
 
+    /// Gracefully shutdown the service and its components.
+    /// - Throws: An error if the shutdown process fails.
+    /// This method ensures that the AWS client and HTTP client are properly shutdown before marking the service as shutdown.
+    /// It also logs the shutdown process.
+    /// This method is idempotent;
+    /// - Important: This method must be called at leat once to ensure that resources are released properly. If the method is not called, it will lead to a crash.
     public func gracefulShutdown() throws {
+        guard !isShutdown else { return }
         logger.info("Stopping DynamoDBService...")
         try awsClient.syncShutdown()
         logger.info("DynamoDBService is stopped.")
         logger.info("Stopping HTTPClient...")
         try httpClient.syncShutdown()
         logger.info("HTTPClient is stopped.")
+        isShutdown = true
     }
 }
 

Sources/BreezeDynamoDBService/BreezeHTTPClientConfig.swift

@@ -15,16 +15,26 @@
 import Logging
 import NIOCore
 
+/// BreezeClientServiceError defines the errors that can occur in the Breeze Client Service.
 public enum BreezeClientServiceError: Error {
     case invalidHttpClient
 }
 
+/// BreezeHTTPClientConfig is a configuration structure for the Breeze HTTP client.
 public struct BreezeHTTPClientConfig: Sendable {
+    
+    /// Initializes a new instance of BreezeHTTPClientConfig.
+    /// - Parameters:
+    ///   - timeout: The timeout duration for HTTP requests.
+    ///   - logger: The logger to use for logging messages.
     public init(timeout: TimeAmount, logger: Logger) {
         self.timeout = timeout
         self.logger = logger
     }
 
+    /// The timeout duration for HTTP requests.
     public let timeout: TimeAmount
+    
+    /// The logger to use for logging messages.
     public let logger: Logger
 }

Sources/BreezeDynamoDBService/Foundation+Extension.swift

@@ -16,6 +16,8 @@ import class Foundation.DateFormatter
 import struct Foundation.Date
 import struct Foundation.TimeZone
 
+/// This file contains extensions for DateFormatter, Date, and String to handle ISO 8601 date formatting and parsing.
+/// These extensions provide a convenient way to convert between `Date` objects and their ISO 8601 string representations.
 extension DateFormatter {
     static var iso8061: DateFormatter {
         let formatter = DateFormatter()
@@ -26,13 +28,15 @@ extension DateFormatter {
 }
 
 extension Date {
+    /// Returns a string representation of the date in ISO 8601 format.
     var iso8601: String {
         let formatter = DateFormatter.iso8061
         return formatter.string(from: self)
     }
 }
 
 extension String {
+    /// Attempts to parse the string as an ISO 8601 date.
     var iso8601: Date? {
         let formatter = DateFormatter.iso8061
         return formatter.date(from: self)

Sources/BreezeDynamoDBService/ListResponse.swift

@@ -18,11 +18,25 @@ import FoundationEssentials
 import Foundation
 #endif
 
+/// Model representing a paginated list response from a DynamoDB operation.
+/// This struct contains an array of items and an optional last evaluated key for pagination.
+/// This struct conforms to `CodableSendable`, allowing it to be encoded and decoded for network transmission or storage.
 public struct ListResponse<Item: CodableSendable>: CodableSendable {
+    
+    /// Initializes a new instance of `ListResponse`.
+    /// - Parameters:
+    ///   - items: An array of items returned from the DynamoDB operation.
+    ///   - lastEvaluatedKey: An optional string representing the last evaluated key for pagination. If nil, it indicates that there are no more items to fetch.
+    ///
+    /// This initializer is used to create a paginated response for DynamoDB operations.
     public init(items: [Item], lastEvaluatedKey: String? = nil) {
         self.items = items
         self.lastEvaluatedKey = lastEvaluatedKey
     }
+    
+    /// The items returned from the DynamoDB operation.
     public let items: [Item]
+    
+    /// An optional string representing the last evaluated key for pagination.
     public let lastEvaluatedKey: String?
 }

Sources/BreezeLambdaAPI/APIGatewayV2Response+Extensions.swift

@@ -19,15 +19,15 @@ import class Foundation.JSONEncoder
 extension APIGatewayV2Response {
     private static let encoder = JSONEncoder()
 
-    /// defaultHeaders
     /// Override the headers in APIGatewayV2Response
     static let defaultHeaders = [ "Content-Type": "application/json" ]
 
+    /// A  model representing the body of an error response
     struct BodyError: Codable {
         let error: String
     }
 
-    /// init
+    /// Initializer for APIGatewayV2Response with a BodyError
     /// - Parameters:
     ///   - error: Error
     ///   - statusCode: HTTP Status Code
@@ -36,7 +36,7 @@ extension APIGatewayV2Response {
         self.init(with: bodyError, statusCode: statusCode)
     }
 
-    /// init
+    /// Initializer for APIGatewayV2Response with an Encodable object
     /// - Parameters:
     ///   - object: Encodable Object
     ///   - statusCode: HTTP Status Code