Deta-Swift is the unofficial Deta SDK for Swift.

⚠️ This package is still under active development and things might and will change. Do not use this package as-is in a production app. ⚠️

Installation

To use Deta-Swift in your project, add the following line to your Package.swift file:

.package(url: "https://github.com/pkrll/deta-swift.git", from: "1.0.0")

Add the dependency to the targets that will use Deta-Swift:

let package = Package(
    // ...
    dependencies: [
        .package(url: "https://github.com/pkrll/deta-swift.git", from: "1.0.0")
        // Other dependencies...
    ],
    targets: [
        .target(
            name: "<SomeApp>",
            dependencies: [
                .product(name: "Deta", package: "deta-swift")
                // Other dependencies...
            ]
        ),
        // Other targets...
    ]
)

Usage

To start using Deta, you need to first retrieve your project key. Initialize the Deta object with your project key, and the name of your Deta base:

import Deta

let deta = Deta(projectKey: "YourProjectKey", base: "SampleDB")

The Deta SDK for Swift supports all of Deta's HTTP API endpoints currently available.

⚠️ Warning ⚠️

Remember that your project key is a secret. Anyone with the key can access and modify your database. This SDK is not meant to be used client side, as it requires the API key to be sent over HTTPs and therefore visible for everyone. Do not commit this key to a public repository.

Put Item

The put method allows for adding multiple items to the Deta base in a single request. Your models must conform to the DetaModel protocol.

struct SomeModel: DetaModel {
    let key: String?
    let title: String
}

let items = [
    SomeModel(key: "1", title: "First item"),
    SomeModel(key: "2", title: "Second item")
]

let response = try await deta.put(items: items)
// response.processed contains all items that were successfully added.
// response.failed contains any item that failed due to internal processing.

For more information, please see the documentation for Put Item on Deta Docs.

Get Item

The get method retrieves a single item from the Deta base. This method requires a specific model type specified when retrieving. The return value must conform to your model, otherwise an error is returned.

If the item does not exist, an error will be returned.

struct SomeModel: DetaModel {
    let key: String?
    let title: String
}

let model = try await deta.get(model: SomeModel.self, key: "1")

For more information, please see the documentation for Get Item on Deta Docs.

Delete Item

The delete method deletes an item from the Deta base. Regardless of whether the item exists or not, a successful response will be returned.

try await deta.delete(key: "1")

For more information, please see the documentation for Delete Item on Deta Docs.

Insert Item

The insert method inserts a single item into the Deta Base. If an item with the same key already exists, an error will be returned.

struct SomeModel: Fetchable {
    let key: String?
    let title: String
}

let itemToInsert = SomeModel(key: "1", title: "First item")
let insertedItem = try await deta.insert(itemToInsert)

For more information, please see the documentation for Insert Item on Deta Docs.

Fetch Item

The fetch method retrieves items that matches some predicate. The predicate is a collection of Query objects. For more information on queries, please consult the Deta docs.

Deta-Swift has support for the following operators:

Equals:

Query(_: String, equals: AnyEncodable)

Less Than

Query(_: String, isLessThan: AnyEncodable)
Query(_: String, isLessThanOrEqualsTo: AnyEncodable)

Greater than

Query(_: String, isGreaterThan: AnyEncodable)
Query(_: String, isGreaterThanOrEqualsTo: AnyEncodable)

Prefix

Query(_: String, hasPrefix: AnyEncodable)

Range

Query(_: String, isBetween: ClosedRange<Int>)
Query(_: String, isBetween: ClosedRange<Double>)

Contains

Query(_: String, contains: AnyEncodable)
Query(_: String, doesNotContain: AnyEncodable)

Query objects can be grouped using GroupedQueries:

GroupedQueries {
    Query("someField", contains: "Some value")
    Query("someOtherField", isGreaterThan: 13)
}

Grouping queries are equivalent to OR, while multiple groups of queries will be ANDed.

struct SomeModel: Fetchable {
    let key: String?
    let title: String
    let year: Int
}

// Fetch items that satisfies the following:
// - Title contains "some value" AND year equals to 1988, OR:
// - Year ranges between 2000 and 2010
let response1 = try await deta.fetch(model: SomeModel.self) {
    GroupedQueries {
        Query("title", contains: "Some value")
        Query("year", equals: "1988")
    }
    
    GroupedQueries {
        Query("year", isBetween: 2000...2010)
    }
}

// Fetch items that satisfies the following:
// - Title contains "some value" AND
// - Year is less than 1960
let response2 = try await deta.fetch(model: SomeModel.self) {
    Query("title", contains: "Some value")
    Query("year", isLessThan: 1960)
}

For more information, please see the documentation for Query Item on Deta Docs.