PropertyKit

A protocol-centric, type and queue safe key-value workflow.

Programming language: Swift

License: MIT License

Tags: Database    

Latest version: v1.1

README

Light-weight, strict protocol-first styled PropertyKit helps you to easily and safely handle guaranteed values, keys or types on various situations of the large-scale Swift project on iOS, macOS and tvOS.

Installation

Detail Guide

CocoaPods

pod 'PropertyKit'

Carthage

github "metasmile/PropertyKit"

Swift Package Manager

.Package(url: "https://github.com/metasmile/PropertyKit.git")

Modules

• PropertyWatchable for NSKeyValueObservation
• PropertyDefaults for UserDefaults
• ~

PropertyDefaults

The simplest, but reliable way to manage UserDefaults. PropertyDefaults automatically binds value and type from Swift property to UserDefaults keys and values. It forces only protocol extension pattern that is focusing on syntax-driven value handling, so it helps to avoid unsafe String key use. Therefore, natually, Swift compiler will protect all of missing or duplicating states with its own.

PropertyDefaults is new hard fork of DefaultsKit by nmdias with entirely different approaches.

Features

• [x] Swift 4 Codable Support
• [x] Compile-time UserDefaults guaranteeing.
• [x] Key-Type-Value relationship safety, no String literal use.
• [x] Structural extension-protocol-driven, instead of an intension.
• [x] Permission control
• [ ] Automatic private scope - In File, Class or Struct, Function

Usage

An example to define automatic UserDefaults keys with basic Codable types:

extension Defaults: PropertyDefaults {
    public var autoStringProperty: String? {
        set{ set(newValue) } get{ return get() }
    }
    public var autoDateProperty: Date? {
        set{ set(newValue) } get{ return get() }
    }
}

var sharedDefaults = Defaults()
sharedDefaults.autoStringProperty = "the new value will persist in shared scope"
// sharedDefaults.autoStringProperty == Defaults.shared.autoStringProperty

Defaults.shared.autoStringProperty = "another new value will persist in shared scope"
// Defaults.shared.autoStringProperty == sharedDefaults.autoStringProperty

var localDefaults = Defaults(suiteName:"local")
localDefaults.autoStringProperty = "the new value will persist in local scope"
// localDefaults.autoStringProperty != Defaults.shared.autoStringProperty

Directly save/load as Codable type

public struct CustomValueType: Codable{
    var key:String = "value"
    var date:Date?
    var data:Data?
}
extension Defaults: PropertyDefaults {
    // non-optional - must define the default value with the keyword 'or'
    public var autoCustomNonOptionalProperty: CustomValueType {
        set{ set(newValue) } get{ return get(or: CustomValueType()) }
    }
    // optional with/without setter default value
    public var autoCustomOptionalProperty: CustomValueType? {
        set{ set(newValue) } get{ return get() }
    }
    public var autoCustomOptionalPropertySetterDefaultValue: CustomValueType? {
        set{ set(newValue, or: CustomValueType()) } get{ return get() }
    }
}

Strongly guaranteeing unique key with Swift compiler.

//CodeFile1_ofLargeProject.swift
protocol MyDefaultsKeysUsingInA : PropertyDefaults{
    var noThisIsMyKeyNotYours:Int?{ get }
}
extension Defaults : MyDefaultsKeysUsingInA{
    var noThisIsMyKeyNotYours:Int?{ set{ set(newValue) } get{ return get() } }
}

//CodeFile2_ofLargeProject.swift
protocol MyDefaultsKeysUsingInB : PropertyDefaults{
    var noThisIsMyKeyNotYours:Int?{ get }
}
extension Defaults : MyDefaultsKeysUsingInB{
    var noThisIsMyKeyNotYours:Int?{ set{ set(newValue) } get{ return get() } }
}

❗️Swift Compiler Error
~.swift:30:9: Invalid redeclaration of 'noThisIsMyKeyNotYours'
~.swift:21:9: 'noThisIsMyKeyNotYours' previously declared here

With this pattern, as you know, you also can control access permission with the protocol. It means you can use 'private' or 'file-private' defaults access.

// MyFile.swift
fileprivate protocol PrivateDefaultKeysInThisSwiftFile: PropertyDefaults{
    var filePrivateValue: String? {set get}
}

extension Defaults: PrivateDefaultKeysInThisSwiftFile {
    public var filePrivateValue: String? {
        set{ set(newValue) } get{ return get() }
    }
}

// Can access - 👌
Defaults.shared.filePrivateValue

// MyOtherFile.swift

// Not able to access - ❌
Defaults.shared.filePrivateValue

And, Yes, It's a hack way to crack our design intention.

var p1:Int{
    Defaults.shared.set(2)  
    return Defaults.shared.get(or:0)  
}
var p2: Int{
    return Defaults.shared.get(or:0)  
}

p1 // == 2
p2 // == 0
//It means that are function/property-scoped capsulated defaults values.

PropertyWatchable

A protocol extension based on NSKeyValueObservation. It simply enables to let a class object become a type-safe keypath observable object. And unique observer identifier will be assigned to all observers automatically. That prevents especially duplicated callback calls and so it can let you atomically manage a bunch of key-value flows between its joined queues.

Features

• [x] Making an observable object with only protocol use.
• [x] Swift property literal based keypath observation.
• [x] Strictful type-guaranteed callback parameter support.
• [x] Automatic unique identifier support.
• [x] File-scoped observer removing support.
• [ ] Queue-private atomic operation support.

Usage

The simplest example to use.

class WatchableObject:NSObject, PropertyWatchable{
    @objc dynamic
    var testingProperty:String?
}

let object = WatchableObject()
object.watch(\.testingProperty) {
    object.testingProperty == "some value"
    //Do Something.
}

object.testingProperty = "some value"

All options and strongly typed-parameters are same with NSKeyValueObservation.

// Default option is the default of NSKeyValueObservation (.new)
// (WatchableObject, NSKeyValueObservedChange<Value>)
object.watch(\.testingProperty, options: [.initial, .new, .old]) { (target, changes) in     
    target.testingProperty == "some value"
    //Dd Something.
}

let object = WatchableObject()
object.testingProperty = "initial value"
config.watch(\.testingProperty, options: [.initial]) { (o, _) in
    o.testingProperty == "initial value"
}

Automatic line by line identifier support.

object.watch(\.testingProperty) {
    // Listening as a unique observer 1
}

object.watch(\.testingProperty) {
    // Listening as a unique observer 2
}

object.watch(\.testingProperty, id:"myid", options:[.old]) {
    // Listening as an observer which has identifier "myid"
}

// total 3 separated each observers are listening each callbacks.

Remove observations with various options.

// Remove only an observer which has "myid" only
object.unwatch(\.testingProperty, forIds:["myid"])

// Remove all observers that are watching ".testingProperty"
object.unwatch(\.testingProperty)

//Automatically remove all observers in current file.
object.unwatchAllFilePrivate()

//Automatically remove entire observers in application-wide.
object.unwatchAll()