DataRaft swift package

Sources/DataRaft/Structures/Migration.swift

@@ -0,0 +1,75 @@
+import Foundation
+import DataLiteCore
+
+/// Represents a database migration step associated with a specific version.
+///
+/// Each `Migration` contains a reference to a migration script file (usually a `.sql` file) and the
+/// version to which this script corresponds. The script is expected to be bundled with the application.
+///
+/// You can initialize a migration directly with a URL to the script, or load it from a resource
+/// embedded in a bundle.
+public struct Migration<Version: VersionRepresentable>: Hashable, Sendable {
+    // MARK: - Properties
+    
+    /// The version associated with this migration step.
+    public let version: Version
+    
+    /// The URL pointing to the migration script (e.g., an SQL file).
+    public let scriptURL: URL
+    
+    /// The SQL script associated with this migration.
+    ///
+    /// This computed property reads the contents of the file at `scriptURL` and returns it as a
+    /// `SQLScript` instance. Use this to access and execute the migration's SQL commands.
+    ///
+    /// - Throws: An error if the script file cannot be read or is invalid.
+    public var script: SQLScript {
+        get throws {
+            try SQLScript(contentsOf: scriptURL)
+        }
+    }
+    
+    // MARK: - Inits
+    
+    /// Creates a migration with a specified version and script URL.
+    ///
+    /// - Parameters:
+    ///   - version: The version this migration corresponds to.
+    ///   - scriptURL: The file URL to the migration script.
+    public init(version: Version, scriptURL: URL) {
+        self.version = version
+        self.scriptURL = scriptURL
+    }
+    
+    /// Creates a migration by locating a script resource in the specified bundle.
+    ///
+    /// This initializer attempts to locate a script file in the provided bundle using the specified
+    /// resource `name` and optional `extension`. The `name` parameter may include or omit the file extension.
+    ///
+    /// - If `name` includes an extension (e.g., `"001_init.sql"`), pass `extension` as `nil` or an empty string.
+    /// - If `name` omits the extension (e.g., `"001_init"`), specify the extension separately
+    ///   (e.g., `"sql"`), or leave it `nil` if the file has no extension.
+    ///
+    /// - Important: Passing a name that already includes the extension while also specifying a non-`nil`
+    ///   `extension` may result in failure to locate the file.
+    ///
+    /// - Parameters:
+    ///   - version: The version this migration corresponds to.
+    ///   - name: The resource name of the script file. May include or omit the file extension.
+    ///   - extension: The file extension, if separated from the name. Defaults to `nil`.
+    ///   - bundle: The bundle in which to search for the resource. Defaults to `.main`.
+    ///
+    /// - Returns: A `Migration` if the resource file is found; otherwise, `nil`.
+    public init?(
+        version: Version,
+        byResource name: String,
+        extension: String? = nil,
+        in bundle: Bundle = .main
+    ) {
+        guard let url = bundle.url(
+            forResource: name,
+            withExtension: `extension`
+        ) else { return nil }
+        self.init(version: version, scriptURL: url)
+    }
+}