angd-dev/data-raft
1
0
Fork 0
Code Pull Requests Releases Activity

DataRaft swift package

Browse Source
This commit is contained in:
Oleksii Zghurskyi
2025-05-18 17:47:22 +03:00
parent d64c6b2ef2
commit 1b2cdaf23e
23 changed files with 1862 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
Sources/DataRaft/Structures/BitPackVersion.swift Normal file
View File

@@ -0,0 +1,158 @@
import Foundation
/// A semantic version packed into a 32-bit unsigned integer.
///
/// This type stores a `major.minor.patch` version using bit fields inside a single `UInt32`:
///
/// - 12 bits for `major` in the 0...4095 range
/// - 12 bits for `minor`in the 0...4095 range
/// - 8 bits for `patch` in the 0...255 range
///
/// ## Topics
///
/// ### Errors
///
/// - ``Error``
/// - ``ParseError``
///
/// ### Creating a Version
///
/// - ``init(rawValue:)``
/// - ``init(major:minor:patch:)``
/// - ``init(version:)``
/// - ``init(stringLiteral:)``
///
/// ### Instance Properties
///
/// - ``rawValue``
/// - ``major``
/// - ``minor``
/// - ``patch``
/// - ``description``
public struct BitPackVersion: VersionRepresentable, RawRepresentable, CustomStringConvertible {
/// An error related to invalid version components.
public enum Error: Swift.Error {
/// An error for a major component that exceeds the allowed range.
case majorOverflow(UInt32)
/// An error for a minor component that exceeds the allowed range.
case minorOverflow(UInt32)
/// An error for a patch component that exceeds the allowed range.
case patchOverflow(UInt32)
/// A message describing the reason for the error.
public var localizedDescription: String {
switch self {
case .majorOverflow(let value):
"Major version overflow: \(value). Allowed range: 0...4095."
case .minorOverflow(let value):
"Minor version overflow: \(value). Allowed range: 0...4095."
case .patchOverflow(let value):
"Patch version overflow: \(value). Allowed range: 0...255."
}
}
}
// MARK: - Properties
/// The packed 32-bit value that encodes the version.
public let rawValue: UInt32
/// The major component of the version.
public var major: UInt32 { (rawValue >> 20) & 0xFFF }
/// The minor component of the version.
public var minor: UInt32 { (rawValue >> 8) & 0xFFF }
/// The patch component of the version.
public var patch: UInt32 { rawValue & 0xFF }
/// A string representation in the form `"major.minor.patch"`.
public var description: String {
"\(major).\(minor).\(patch)"
}
// MARK: - Inits
/// Creates a version from a packed 32-bit unsigned integer.
///
/// - Parameter rawValue: A bit-packed version value.
public init(rawValue: UInt32) {
self.rawValue = rawValue
}
/// Creates a version from individual components.
///
/// - Parameters:
/// - major: The major component in the 0...4095 range.
/// - minor: The minor component in the 0...4095 range.
/// - patch: The patch component in the 0...255 range. Defaults to `0`.
///
/// - Throws: ``Error/majorOverflow(_:)`` if `major` is out of range.
/// - Throws: ``Error/minorOverflow(_:)`` if `minor` is out of range.
/// - Throws: ``Error/patchOverflow(_:)`` if `patch` is out of range.
public init(major: UInt32, minor: UInt32, patch: UInt32 = 0) throws {
guard major < (1 << 12) else { throw Error.majorOverflow(major) }
guard minor < (1 << 12) else { throw Error.minorOverflow(minor) }
guard patch < (1 << 8) else { throw Error.patchOverflow(patch) }
self.init(rawValue: (major << 20) | (minor << 8) | patch)
}
// MARK: - Comparable
/// Compares two versions by their packed 32-bit values.
public static func < (lhs: Self, rhs: Self) -> Bool {
lhs.rawValue < rhs.rawValue
}
}
// MARK: - ExpressibleByStringLiteral
@available(iOS 16.0, *)
@available(macOS 13.0, *)
extension BitPackVersion: ExpressibleByStringLiteral {
/// An error related to parsing a version string.
public enum ParseError: Swift.Error {
/// A string that doesn't match the expected version format.
case invalidFormat(String)
/// A message describing the format issue.
public var localizedDescription: String {
switch self {
case .invalidFormat(let str):
"Invalid version format: \(str). Expected something like '1.2' or '1.2.3'."
}
}
}
/// Creates a version by parsing a string like `"1.2"` or `"1.2.3"`.
///
/// - Parameter version: A version string in the form `x.y` or `x.y.z`.
///
/// - Throws: ``ParseError/invalidFormat(_:)`` if the string format is invalid.
/// - Throws: `Error` if any component is out of range.
public init(version: String) throws {
let regex = /^(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?$/
guard version.wholeMatch(of: regex) != nil else {
throw ParseError.invalidFormat(version)
}
let parts = version.split(separator: ".")
.compactMap { UInt32($0) }
try self.init(
major: parts[0],
minor: parts[1],
patch: parts.count == 3 ? parts[2] : 0
)
}
/// Creates a version from a string literal like `"1.2"` or `"1.2.3"`.
///
/// - Warning: Crashes if the string format is invalid.
/// Use ``init(version:)`` for safe parsing.
public init(stringLiteral value: String) {
try! self.init(version: value)
}
}

75
Sources/DataRaft/Structures/Migration.swift Normal file
View File

@@ -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)
}
}