Latest 0.4.4
Homepage https://github.com/sadawi/ModelKit
License MIT
Platforms ios 9.0, requires ARC
Dependencies PromiseKit/CorePromise
Authors

This is a framework for working with model objects.

pod 'ModelKit'

Or, include only some components:

  • ‘ModelKit/Fields’
  • ‘ModelKit/Models’
  • ‘ModelKit/RemoteModelStore’ (Alamofire dependency)

Fields

Fields give you:

  • type-safe change observation
  • automatic timestamps
  • validations

Basic usage:

class Person {
  let age = Field<Int>()
}
person.age.value = 10

For multivalued fields, there is ArrayField, which wraps a field object describing the single-valued type.

let tags = ArrayField(Field<String>(), name: "Tags")

The inner field is responsible for validations, transformations, etc.. The ArrayField owns top-level attributes like name, key, etc. — but for convenience, it will copy them from the inner field at initialization.

The unary postfix operator * is provided to wrap a Field in an ArrayField. So you can also write the above declaration like this:

let tags = Field<String>(name: "Tags")*

Validations

Simple closure validations:

let age = Field<Int>().require { $0 > 0 }

Rules can be chained, too, implying an AND. Order is not important.

let age = Field<Int>().require { $0 > 0 }.require { $0 % 2 == 0 }

By default, nil values will be considered valid. To change that for a given rule, pass allowNil: false to require.

To validate a field value, call field.validate(), which returns a ValidationState enum:

public enum ValidationState:Equatable {
    case unknown
    case invalid([String])
    case valid
}

The associated value of the .invalid case is a list of error messages (e.g., ["must be greater than 0", "is required"]).

Timestamps

Fields will automatically have the following timestamps:

  • updatedAt: the last time any value was set
  • changedAt: the last time a new value was set (compared using ==)

Observers

This library includes the ValueObserver and ValueObservable protocols for generic, type-safe change observation. Fields implement both protocols.

A ValueObservable can have any number of registered ValueObserver objects. The --> operator is a shortcut for the addObserver method (<-- works the same, only with its arguments swapped). Observation events are triggered once when the observer is added, and after that whenever a field value is set.

Adding an observer

An observer can be added if it implements the ValueObserver protocol, which has a valueChanged(observable, value: value) method.

field --> observer

Or, a closure can be provided. In place of an observer object, an owner is used only to identify each closure.

field --> owner { value in
  print(value)
}

We can still register a closure even if no observer is given. This is effectively registering the closure with a null observer.

age --> { value in 
  print("Age was changed to (value)")
}

Binding a field to another field

Since Field itself implements both ValueObservable and ValueObserver, the --> operator can be used to create a link between two field values.

sourceField --> destinationField

This will set the value of destinationField to that of sourceField immediately, and again whenever sourceField‘s value changes.

The <--> operator is a shortcut for <-- followed by --> (and can only be used between two Fields).

field1 <--> field2

Since <-- is called first, both fields will initially have the value of field2.

Unregistering

Unregistering observers is done with the removeObserver method, or the -/-> operator. All observers can be removed with removeAllObservers().

Models

A Model object automatically converts to and from a dictionary representation of its Field properties.

person.dictionaryValue()
// --> ["name": "Bob", "tags": ["red", "blue", "green"]]

If your field’s value is a subclass of Model, you should use the ModelField subclass.

let companies = ModelField<Company>()*

ModelStore

This library provides a Promise-based interface for abstract data stores, specified in the ModelStore protocol, as well as several concrete implementations.

func create<T: Model>(model:T) -> Promise<T>
func update<T: Model>(model:T) -> Promise<T>
func delete<T: Model>(model:T) -> Promise<T>
func lookup<T: Model>(modelClass:T.Type, identifier:String) -> Promise<T>
func list<T: Model>(modelClass:T.Type) -> Promise<[T]>

MemoryModelStore

This stores models in memory. It adds a lookupImmediately method for synchronous identifier-based lookups.

RemoteModelStore

This is intended as a base class for your RESTful server interface. It includes a number of overridable hooks that you can customize for your particular needs, like:

  • defaultHeaders
  • handleError
  • constructResponse

A RESTRouter is responsible for generating paths for resource locations.

collectionPath(for: Person.self)
instancePath(for: person)

Nested routes are generated automatically if your model conforms to HasOwnerField, which requires it to specify an owning field. If a person’s owner field is its company field, for example, you might get "/companies/10/employees/45" for its instance path.

It also contains a ValueTransformerContext var that can be used to customize serialization. For example:

  • context.keyCase – specify the casing style of keys (.snake, .upperCamel, .lowerCamel)
  • context.explicitNull – decide whether keys for null values should be included
  • Specify custom transformers

Latest podspec

{
    "name": "ModelKit",
    "version": "0.4.4",
    "summary": "A collection of utilities for working with model objects",
    "homepage": "https://github.com/sadawi/ModelKit",
    "license": "MIT",
    "authors": {
        "Sam Williams": "[email protected]"
    },
    "source": {
        "git": "https://github.com/sadawi/ModelKit.git",
        "tag": "0.4.4"
    },
    "platforms": {
        "ios": "9.0"
    },
    "requires_arc": true,
    "dependencies": {
        "PromiseKit/CorePromise": [
            "~> 4.0.5"
        ]
    },
    "pushed_with_swift_version": "3.0",
    "subspecs": [
        {
            "name": "Fields",
            "source_files": "ModelKit/Fields/**/*",
            "dependencies": {
                "StringInflections": [
                    "~> 0.0.6"
                ]
            }
        },
        {
            "name": "Models",
            "source_files": [
                "ModelKit/Models/**/*",
                "ModelKit/ModelStore/**/*"
            ],
            "dependencies": {
                "ModelKit/Fields": []
            }
        },
        {
            "name": "RemoteModelStore",
            "source_files": "ModelKit/RemoteModelStore/**/*",
            "dependencies": {
                "ModelKit/Models": [],
                "Alamofire": [
                    "~> 4.2.0"
                ],
                "SwiftyJSON": [
                    "~> 3.1.3"
                ]
            }
        }
    ]
}

Pin It on Pinterest

Share This