DataSnapshotDecoder.swift

/* DataSnapshotDecoder.swift

 Copyright 2018 MindSea Development Inc.

 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

import FirebaseDatabase
import Foundation

/**
 Decodes Firebase Realtime Database snapshots into `Swift.Decodable` values.

 Example:
 ````
 struct CoolData: Decodable {
     let hasBindle: Bool
     let interestingItemCount: Int
 }

 Database.database().reference(withPath: "/cools").observe(.value, with: { snapshot in
     do {
         let cools = try DataSnapshotDecoder().decode([CoolData].self, from: snapshot)
         print("decoded cools! \(cools)")
     } catch {
         print("couldn't decode snapshot: \(error)")
     }
 }
 ````

 ## Special keys

 `DataSnapshotDecoder` has two special keys:

 - `.key` maps to the Firebase Realtime Database object's key.
 - `.priority` maps to the Firebase Realtime Database object's priority.

 The annoying part is we can't rely on the Swift compiler's autogenerated `CodingKey` if we want the key and/or priority to be decoded; you'll have to specify your own `CodingKey`.

 Example:
 ````
 struct CoolKeyedData: Decodable {
     let coconutCount: Int
     let key: String

     private enum CodingKeys: String, CodingKey {
         case coconutCount
         case key = ".key"
     }
 }

 // later, assuming you're in some observe block…
 let coolKeyed = try DataSnapshotDecoder().decode(CoolKeyedData.self, from: snapshot)
 print("key is \(coolKeyed.key)") // prints something useful
 ````

 Note that Firebase Realtime Database keys are not allowed to contain a period `.`, so you can't set a value in your database that gets shadowed by these special keys.
 */
public final class DataSnapshotDecoder {

    // JSONDecoder has this weird interface with a pointless initializer that I don't really understand, so let's blindly copy it!
    public init() {}

    public func decode<T: Decodable>(_ type: T.Type, from snapshot: DataSnapshot) throws -> T {
        return try T.init(from: _DataSnapshotDecoder(snapshot))
    }

    /**
     These are the special keys we support to decode a Firebase Realtime Database object's key and priority.

     [Firebase docs](https://firebase.google.com/docs/database/web/structure-data) say: "If you create your own keys, they… cannot contain ., $, #, [, ], /, or ASCII control characters 0-31 or 127." So there's no chance that we accidentally shadow a value set by the database user so long as we pick one of those characters to include in the key.
     */
    public enum SpecialKey: String, CodingKey {
        case key = ".key"
        case priority = ".priority"
    }
}

/**
 The actual workhorse of the `DataSnapshotDecoder`.

 There's a fairly straightforward mapping from `DataSnapshot` to the various decoding containers and their methods:

 - `DataSnapshot.exists()` maps to `decodeNil()`
 - `DataSnapshot.childSnapshot(forPath:)` (usually followed by a `DataSnapshot.value`) maps to `KeyedDecodingContainer`.
 - `DataSnapshot.children` maps to `UnkeyedDecodingContainer`.
 - `DataSnapshot.value` maps to `SingleValueDecodingContainer`.

 There's a lot of copied code here and a healthy amount of boilerplate, but it starts to make sense after you dive in. Useful references include:

 - `Decodable` and its related protocols have documenting comments (command-right click any of them).
 - Mike Ash's writeups on [`Swift.Codable`](https://www.mikeash.com/pyblog/friday-qa-2017-07-14-swiftcodable.html) and [A Binary Decoder for Swift](https://www.mikeash.com/pyblog/friday-qa-2017-07-28-a-binary-coder-for-swift.html) (the binary decoder writeup includes sample code).
 - [`JSONDecoder`'s implementation](https://github.com/apple/swift/blob/master/stdlib/public/SDK/Foundation/JSONEncoder.swift). Note that, as of writing (2017-12-19), `JSONDecoder` uses a different approach than we use here. Only one instance of `_JSONDecoder` gets created, and it maintains a context stack to keep track of where it is in the JSON object. We create new instnces of `_DataSnapshotDecoder` as needed.
 */
private class _DataSnapshotDecoder: Decoder {
    let codingPath: [CodingKey]
    private let snapshot: DataSnapshot

    var userInfo: [CodingUserInfoKey: Any] { return [:] }

    init(_ snapshot: DataSnapshot, codingPath: [CodingKey] = []) {
        self.codingPath = codingPath
        self.snapshot = snapshot
    }

    func container<Key: CodingKey>(keyedBy type: Key.Type) throws -> KeyedDecodingContainer<Key> {
        guard snapshot.exists() else {
            throw DecodingError.valueNotFound(KeyedDecodingContainer<Key>.self, DecodingError.Context(codingPath: codingPath, debugDescription: "Cannot get keyed decoding container, found nil instead"))
        }

        let container = KeyedContainer<Key>(snapshot, codingPath: codingPath)
        return KeyedDecodingContainer(container)
    }

    private struct KeyedContainer<Key: CodingKey>: KeyedDecodingContainerProtocol {
        let codingPath: [CodingKey]
        let snapshot: DataSnapshot
        private let stringKeys: [String]

        var allKeys: [Key] {
            return stringKeys.flatMap { Key(stringValue: $0) }
        }

        init(_ snapshot: DataSnapshot, codingPath: [CodingKey]) {
            self.snapshot = snapshot
            self.codingPath = codingPath

            let randoKeys = snapshot
                .children
                .map { ($0 as! DataSnapshot).key }

            var specialKeys = [DataSnapshotDecoder.SpecialKey.key]
            if snapshot.hasPriority {
                specialKeys.append(.priority)
            }
            stringKeys = randoKeys + specialKeys.map { $0.stringValue }
        }

        func contains(_ key: Key) -> Bool {
            return stringKeys.contains(key.stringValue)
        }

        func decodeNil(forKey key: Key) throws -> Bool {
            if case .priority? = DataSnapshotDecoder.SpecialKey(stringValue: key.stringValue) {
                return !snapshot.hasPriority
            }

            guard snapshot.hasChild(key.stringValue) else {
                throw DecodingError.keyNotFound(key, DecodingError.Context(codingPath: codingPath, debugDescription: "No value associated with key \(key) (\"\(key.stringValue)\")"))
            }

            return !snapshot.childSnapshot(forPath: key.stringValue).exists()
        }

        private func decodePrimitive<T>(_ type: T.Type, forKey key: Key) throws -> T {
            guard snapshot.hasChild(key.stringValue) else {
                throw DecodingError.keyNotFound(key, DecodingError.Context(codingPath: codingPath, debugDescription: "No value associated with key \(key) (\"\(key.stringValue)\")"))
            }

            let child = snapshot.childSnapshot(forPath: key.stringValue)
            guard child.exists(), let anyValue = child.value else {
                throw DecodingError.valueNotFound(type, DecodingError.Context(codingPath: codingPath + [key], debugDescription: "Expected \(type) but found nil instead"))
            }

            guard let value = anyValue as? T else {
                throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: codingPath + [key], debugDescription: "Expected \(type) but found \(Swift.type(of: anyValue))"))
            }

            return value
        }

        func decode(_ type: Bool.Type, forKey key: Key) throws -> Bool {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: Int.Type, forKey key: Key) throws -> Int {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: Int8.Type, forKey key: Key) throws -> Int8 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: Int16.Type, forKey key: Key) throws -> Int16 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: Int32.Type, forKey key: Key) throws -> Int32 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: Int64.Type, forKey key: Key) throws -> Int64 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: UInt.Type, forKey key: Key) throws -> UInt {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: UInt8.Type, forKey key: Key) throws -> UInt8 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: UInt16.Type, forKey key: Key) throws -> UInt16 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: UInt32.Type, forKey key: Key) throws -> UInt32 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: UInt64.Type, forKey key: Key) throws -> UInt64 {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: Float.Type, forKey key: Key) throws -> Float {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: Double.Type, forKey key: Key) throws -> Double {
            return try decodePrimitive(type, forKey: key)
        }

        func decode(_ type: String.Type, forKey key: Key) throws -> String {
            if let specialKey = DataSnapshotDecoder.SpecialKey(stringValue: key.stringValue) {
                switch specialKey {
                case .key:
                    return snapshot.key

                case .priority:
                    guard snapshot.hasPriority else {
                        throw DecodingError.valueNotFound(String.self, DecodingError.Context(codingPath: codingPath + [key], debugDescription: "No value associated with key \(key) (\"\(key.stringValue)\")"))
                    }

                    return snapshot.priority as! String
                }
            }

            return try decodePrimitive(type, forKey: key)
        }

        func decode<T: Decodable>(_ type: T.Type, forKey key: Key) throws -> T {
            if DataSnapshotDecoder.SpecialKey(stringValue: key.stringValue) != nil {
                let decoder = _DataSnapshotDecoder(snapshot, codingPath: codingPath + [key])
                return try T.init(from: decoder)
            }

            guard snapshot.hasChild(key.stringValue) else {
                throw DecodingError.keyNotFound(key, DecodingError.Context(codingPath: codingPath, debugDescription: "No value associated with key \(key) (\"\(key.stringValue)\")"))
            }

            let child = snapshot.childSnapshot(forPath: key.stringValue)
            guard child.exists() else {
                throw DecodingError.valueNotFound(type, DecodingError.Context(codingPath: codingPath + [key], debugDescription: "Expected \(type) but found nil instead"))
            }

            let decoder = _DataSnapshotDecoder(child, codingPath: codingPath + [key])
            return try T.init(from: decoder)
        }

        func nestedContainer<NestedKey: CodingKey>(keyedBy type: NestedKey.Type, forKey key: Key) throws -> KeyedDecodingContainer<NestedKey> {
            guard snapshot.hasChild(key.stringValue) else {
                throw DecodingError.keyNotFound(key, DecodingError.Context(codingPath: codingPath, debugDescription: "Cannot get \(KeyedDecodingContainer<NestedKey>.self); no value associated with key \(key) (\"\(key.stringValue)\")"))
            }

            let child = snapshot.childSnapshot(forPath: key.stringValue)
            guard child.exists() else {
                throw DecodingError.valueNotFound(type, DecodingError.Context(codingPath: codingPath + [key], debugDescription: "Cannot get \(KeyedDecodingContainer<NestedKey>.self); no value found for key \(key) (\"\(key.stringValue)\")"))
            }

            let container = KeyedContainer<NestedKey>(child, codingPath: codingPath + [key])
            return KeyedDecodingContainer(container)
        }

        func nestedUnkeyedContainer(forKey key: Key) throws -> UnkeyedDecodingContainer {
            let child = snapshot.childSnapshot(forPath: key.stringValue)
            guard child.exists() else {
                throw DecodingError.keyNotFound(key, DecodingError.Context(codingPath: codingPath, debugDescription: "Cannot get \(UnkeyedDecodingContainer.self); no value associated with key \(key) (\"\(key.stringValue)\")"))
            }

            return UnkeyedContainer(child, codingPath: codingPath + [key])
        }

        func superDecoder() throws -> Decoder {
            return _DataSnapshotDecoder(snapshot, codingPath: codingPath)
        }

        func superDecoder(forKey key: Key) throws -> Decoder {
            let child = snapshot.childSnapshot(forPath: key.stringValue)
            return _DataSnapshotDecoder(child, codingPath: codingPath + [key])
        }
    }

    func unkeyedContainer() throws -> UnkeyedDecodingContainer {
        guard snapshot.exists() else {
            throw DecodingError.valueNotFound(UnkeyedDecodingContainer.self, DecodingError.Context(codingPath: codingPath, debugDescription: "Cannot get unkeyed decoding container, found nil instead"))
        }

        return UnkeyedContainer(snapshot, codingPath: codingPath)
    }

    private struct IndexKey: CodingKey {
        private let index: Int

        init?(intValue: Int) {
            index = intValue
        }

        init?(stringValue: String) {
            return nil
        }

        init(index: Int) {
            self.index = index
        }

        var intValue: Int? { return index }
        var stringValue: String { return "\(index)" }
    }

    private struct UnkeyedContainer: UnkeyedDecodingContainer {
        let codingPath: [CodingKey]
        private let snapshot: DataSnapshot
        private var iterator: NSEnumerator.Iterator
        private var currentItem: DataSnapshot?

        var count: Int? { return Int(snapshot.childrenCount) }
        var isAtEnd: Bool { return currentItem == nil }

        private(set) var currentIndex: Int

        init(_ snapshot: DataSnapshot, codingPath: [CodingKey]) {
            self.snapshot = snapshot
            self.codingPath = codingPath
            iterator = snapshot.children.makeIterator()
            currentItem = iterator.next() as! DataSnapshot?
            currentIndex = 0
        }

        private mutating func advanceToNextItem() {
            currentItem = iterator.next() as! DataSnapshot?
            if currentItem != nil {
                currentIndex += 1
            }
        }

        private func ensureCurrentItem() throws -> DataSnapshot {
            guard let currentItem = currentItem else {
                throw DecodingError.valueNotFound(Any.self, DecodingError.Context(codingPath: codingPath + [IndexKey(index: currentIndex)], debugDescription: "End of unkeyed container"))
            }

            return currentItem
        }

        mutating func decodeNil() throws -> Bool {
            let isNil = !snapshot.exists()
            if isNil {
                advanceToNextItem()
            }
            return isNil
        }

        private mutating func decodePrimitive<T>(_ type: T.Type) throws -> T {
            guard let currentItem = currentItem else {
                throw DecodingError.valueNotFound(Any.self, DecodingError.Context(codingPath: codingPath + [IndexKey(index: currentIndex)], debugDescription: "End of unkeyed container"))
            }

            guard let anyValue = currentItem.value else {
                throw DecodingError.valueNotFound(type, DecodingError.Context(codingPath: codingPath + [IndexKey(index: currentIndex)], debugDescription: "Expected item of type \(type) but got nil instead"))
            }

            guard let value = anyValue as? T else {
                throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: codingPath + [IndexKey(index: currentIndex)], debugDescription: "Expected item of type \(type) but got \(Swift.type(of: anyValue)) instead"))
            }

            advanceToNextItem()

            return value
        }

        mutating func decode(_ type: Bool.Type) throws -> Bool {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: Int.Type) throws -> Int {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: Int8.Type) throws -> Int8 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: Int16.Type) throws -> Int16 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: Int32.Type) throws -> Int32 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: Int64.Type) throws -> Int64 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: UInt.Type) throws -> UInt {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: UInt8.Type) throws -> UInt8 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: UInt16.Type) throws -> UInt16 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: UInt32.Type) throws -> UInt32 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: UInt64.Type) throws -> UInt64 {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: Float.Type) throws -> Float {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: Double.Type) throws -> Double {
            return try decodePrimitive(type)
        }

        mutating func decode(_ type: String.Type) throws -> String {
            return try decodePrimitive(type)
        }

        mutating func decode<T: Decodable>(_ type: T.Type) throws -> T {
            let decoder = try _DataSnapshotDecoder(ensureCurrentItem(), codingPath: codingPath + [IndexKey(index: currentIndex)])
            let value = try type.init(from: decoder)

            advanceToNextItem()

            return value
        }

        mutating func nestedContainer<NestedKey: CodingKey>(keyedBy type: NestedKey.Type) throws -> KeyedDecodingContainer<NestedKey> {
            let container = try KeyedContainer<NestedKey>(ensureCurrentItem(), codingPath: codingPath + [IndexKey(index: currentIndex)])

            advanceToNextItem()

            return KeyedDecodingContainer(container)
        }

        mutating func nestedUnkeyedContainer() throws -> UnkeyedDecodingContainer {
            let container = try UnkeyedContainer(ensureCurrentItem(), codingPath: codingPath + [IndexKey(index: currentIndex)])

            advanceToNextItem()

            return container
        }

        mutating func superDecoder() throws -> Decoder {
            let decoder = try _DataSnapshotDecoder(ensureCurrentItem(), codingPath: codingPath + [IndexKey(index: currentIndex)])

            advanceToNextItem()

            return decoder
        }
    }

    func singleValueContainer() throws -> SingleValueDecodingContainer {
        return self
    }
}

extension _DataSnapshotDecoder: SingleValueDecodingContainer {
    func decodeNil() -> Bool {
        return !snapshot.exists()
    }

    private var specialLastPathComponent: DataSnapshotDecoder.SpecialKey? {
        return codingPath.last.flatMap { DataSnapshotDecoder.SpecialKey(stringValue: $0.stringValue) }
    }

    private func decodePrimitive<T>(_ type: T.Type) throws -> T {
        switch specialLastPathComponent {
        case .key?:
            guard T.self is String.Type else {
                throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: codingPath, debugDescription: "Expected \(type) but got \(String.self) instead"))
            }

            return snapshot.key as! T

        case .priority?:
            guard let anyPriority = snapshot.priority else {
                throw DecodingError.valueNotFound(type, DecodingError.Context(codingPath: codingPath, debugDescription: "Expected \(type) but got nil instead"))
            }

            guard let priority = anyPriority as? T else {
                throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: codingPath, debugDescription: "Expected \(type) but got \(Swift.type(of: anyPriority)) instead"))
            }

            return priority

        case nil:
            guard let anyValue = snapshot.value else {
                throw DecodingError.valueNotFound(type, DecodingError.Context(codingPath: codingPath, debugDescription: "Expected \(type) but got nil instead"))
            }

            guard let value = anyValue as? T else {
                throw DecodingError.typeMismatch(type, DecodingError.Context(codingPath: codingPath, debugDescription: "Expected \(type) but got \(Swift.type(of: anyValue)) instead"))
            }

            return value
        }
    }

    func decode(_ type: Bool.Type) throws -> Bool {
        return try decodePrimitive(type)
    }

    func decode(_ type: Int.Type) throws -> Int {
        return try decodePrimitive(type)
    }

    func decode(_ type: Int8.Type) throws -> Int8 {
        return try decodePrimitive(type)
    }

    func decode(_ type: Int16.Type) throws -> Int16 {
        return try decodePrimitive(type)
    }

    func decode(_ type: Int32.Type) throws -> Int32 {
        return try decodePrimitive(type)
    }

    func decode(_ type: Int64.Type) throws -> Int64 {
        return try decodePrimitive(type)
    }

    func decode(_ type: UInt.Type) throws -> UInt {
        return try decodePrimitive(type)
    }

    func decode(_ type: UInt8.Type) throws -> UInt8 {
        return try decodePrimitive(type)
    }

    func decode(_ type: UInt16.Type) throws -> UInt16 {
        return try decodePrimitive(type)
    }

    func decode(_ type: UInt32.Type) throws -> UInt32 {
        return try decodePrimitive(type)
    }

    func decode(_ type: UInt64.Type) throws -> UInt64 {
        return try decodePrimitive(type)
    }

    func decode(_ type: Float.Type) throws -> Float {
        return try decodePrimitive(type)
    }

    func decode(_ type: Double.Type) throws -> Double {
        return try decodePrimitive(type)
    }

    func decode(_ type: String.Type) throws -> String {
        return try decodePrimitive(type)
    }

    func decode<T>(_ type: T.Type) throws -> T where T : Decodable {
        return try type.init(from: self)
    }
}


private extension DataSnapshot {

    /**
     Whether this object has a priority.

     This is slightly annoying to determine because `priority` is optional but in the field we tend to see it set to `NSNull.null`.
     */
    var hasPriority: Bool {

        // Documented to be a `String` if it's set, so we can simplify this check and avoid force unwrapping errors above.
        return priority is String
    }
}