DEV Community: Andrew Morgan

Building a collaborative iOS Minesweeper game with Realm

Andrew Morgan — Mon, 14 Mar 2022 16:32:56 +0000

Introduction

I wanted to build an app that we could use at events to demonstrate Realm Sync. It needed to be fun to interact with, and so a multiplayer game made sense. Tic-tac-toe is too simple to get excited about. I'm not a game developer and so Call Of Duty wasn't an option. Then I remembered Microsoft's Minesweeper.

Minesweeper was a Windows fixture from 1990 until Windows 8 relegated it to the app store in 2012. It was a single-player game, but it struck me as something that could be a lot of fun to play with others. Some family beta-testing of my first version while waiting for a ferry proved that it did get people to interact with each other (even if most interactions involved shouting, "Which of you muppets clicked on that mine?!").

You can download the back end and iOS apps from the Realm-Sweeper repo, and get it up and running in a few minutes if you want to play with it.

This article steps you through some of the key aspects of setting up the backend Realm app, as well as the iOS code. Hopefully, you'll see how simple it is and try building something for yourself. If anyone's looking for ideas, then Sokoban could be interesting.

Prerequisites

Realm-Cocoa 10.20.1+
iOS 15+

The Minesweeper game

The gameplay for Minesweeper is very simple.

You're presented with a grid of gray tiles. You tap on a tile to expose what's beneath. If you expose a mine, game over. If there isn't a mine, then you'll be rewarded with a hint as to how many mines are adjacent to that tile. If you deduce (or guess) that a tile is covering a mine, then you can plant a flag to record that.

You win the game when you correctly flag every mine and expose what's behind every non-mined tile.

What Realm-Sweeper adds

Minesweeper wasn't designed for touchscreen devices; you had to use a physical mouse. Realm-Sweeper brings the game into the 21st century by adding touch controls. Tap a tile to reveal what's beneath; tap and hold to plant a flag.

Minesweeper was a single-player game. All people who sign into Realm-Sweeper with the same user ID get to collaborate on the same game in real time.

You also get to configure the size of the grid and how many mines you'd like to hide.

The data model

I decided to go for a simple data model that would put Realm sync to the test.

Each game is a single document/object that contains meta data (score, number of rows/columns, etc.) together with the grid of tiles (the board):

This means that even a modestly sized grid (20x20 tiles) results in a Game document/object with more than 2,000 attributes.

Every time you tap on a tile, the Game object has to be synced with all other players. Those players are also tapping on tiles, and those changes have to be synced too. If you tap on a tile which isn't adjacent to any mines, then the app will recursively ripple through exposing similar, connected tiles. That's a lot of near-simultaneous changes being made to the same object from different devices—a great test of Realm's automatic conflict resolution!

The backend Realm app

If you don't want to set this up yourself, simply follow the instructions from the repo to import the app.

If you opt to build the backend app yourself, there are only two things to configure once you create the empty Realm app:

Enable email/password authentication. I kept it simple by opting to auto-confirm new users and sticking with the default password-reset function (which does nothing).
Enable partitioned Realm sync. Set the partition key to partition and enable developer mode (so that the schema will be created automatically when the iOS app syncs for the first time).

The partition field will be set to the username—allowing anyone who connects as that user to sync all of their games.

You can also add sync rules to ensure that a user can only sync their own games (in case someone hacks the mobile app). I always prefer using Realm functions for permissions. You can add this for both the read and write rules:

{
  "%%true": {
    "%function": {
      "arguments": [
        "%%partition"
      ],
      "name": "canAccessPartition"
    }
  }
}

The canAccessPartition function is:

exports = function(partition) {
  const user = context.user.data.email;
  return partition === user;
};

The iOS app

I'd suggest starting by downloading, configuring, and running the app—just follow the instructions from the repo. That way, you can get a feel for how it works.

This isn't intended to be a full tutorial covering every line of code in the app. Instead, I'll point out some key components.

As always with Realm and MongoDB, it all starts with the data…

Model

There's a single top-level Realm Object—Game:

class Game: Object, ObjectKeyIdentifiable {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var numRows = 0
    @Persisted var numCols = 0
    @Persisted var score = 0
    @Persisted var startTime: Date? = Date()
    @Persisted var latestMoveTime: Date?
    @Persisted var secondsTakenToComplete: Int?
    @Persisted var board: Board?
    @Persisted var gameStatus = GameStatus.notStarted
    @Persisted var winningTimeInSeconds: Int?
    …
}

Most of the fields are pretty obvious. The most interesting is board, which contains the grid of tiles:

class Board: EmbeddedObject, ObjectKeyIdentifiable {
    @Persisted var rows = List<Row>()
    @Persisted var startingNumberOfMines = 0
    ... 
}

row is a list of Cells:

class Row: EmbeddedObject, ObjectKeyIdentifiable {
    @Persisted var cells = List<Cell>()
    ...
}

class Cell: EmbeddedObject, ObjectKeyIdentifiable {
    @Persisted var isMine = false
    @Persisted var numMineNeigbours = 0
    @Persisted var isExposed = false
    @Persisted var isFlagged = false
    @Persisted var hasExploded = false
    ...
}

The model is also where the ~~business~~ game logic is implemented. This means that the views can focus on the UI. For example, Game includes a computed variable to check whether the game has been solved:

var hasWon: Bool {
    guard let board = board else { return false }
    if board.remainingMines != 0 { return false }

    var result = true

    board.rows.forEach() { row in
        row.cells.forEach() { cell in
            if !cell.isExposed && !cell.isFlagged {
                result = false
                return
            }
        }
        if !result { return }
    }
    return result
}

Views

As with any SwiftUI app, the UI is built up of a hierarchy of many views.

Here's a quick summary of the views that make up Real-Sweeper:

ContentView is the top-level view. When the app first runs, it will show the LoginView. Once the user has logged in, it shows GameListView instead. It's here that we set the Realm Sync partition (to be the username of the user that's just logged in):

if username == "" {
    LoginView(username: $username)
} else {
    GameListView()
        .environment(\.realmConfiguration, realmApp.currentUser!.configuration(partitionValue: username))
        .navigationBarItems(leading: realmApp.currentUser != nil ? LogoutButton(username: $username) : nil)
}

ContentView also includes the LogoutButton view.

LoginView allows the user to provide a username and password:

Those credentials are then used to register or log into the backend Realm app:

func userAction() {
    Task {
        do {
            if newUser {
                try await realmApp.emailPasswordAuth.registerUser(
                    email: email, password: password)
            }
            let _ = try await realmApp.login(
                    credentials: .emailPassword(email: email, password: password))
            username = email
        } catch {
            errorMessage = error.localizedDescription
        }
    }
}

GameListView reads the list of this user's existing games.

@ObservedResults(Game.self, 
    sortDescriptor: SortDescriptor(keyPath: "startTime", ascending: false)) var games

It displays each of the games within a GameSummaryView. If you tap one of the games, then you jump to a GameView for that game:

NavigationLink(destination: GameView(game: game)) {
    GameSummaryView(game: game)
}

Tap the settings button and you're sent to SettingsView.

Tap the "New Game" button and a new Game object is created and then stored in Realm by appending it to the games live query:

private func createGame() {
    numMines = min(numMines, numRows * numColumns)
    game = Game(rows: numRows, cols: numColumns, mines: numMines)
    if let game = game {
        $games.append(game)
    }
    startGame  = true
}

SettingsView lets the user choose the number of tiles and mines to use:

If the user uses multiple devices to play the game (e.g., an iPhone and an iPad), then they may want different-sized boards (taking advantage of the extra screen space on the iPad). Because of that, the view uses the device's UserDefaults to locally persist the settings rather than storing them in a synced realm:

@AppStorage("numRows") var numRows = 10
@AppStorage("numColumns") var numColumns = 10
@AppStorage("numMines") var numMines = 15

GameSummaryView displays a summary of one of the user's current or past games.

GameView shows the latest stats for the current game at the top of the screen:

It uses the LEDCounter and StatusButton views for the summary.

Below the summary, it displays the BoardView for the game.

LEDCounter displays the provided number as three digits using a retro LED font:

StatusButton uses a ZStack to display the symbol for the game's status on top of a tile image:

The view uses SwiftUI's GeometryReader function to discover how much space is available so that it can select an appropriate font size for the symbol:

GeometryReader { geo in
    Text(status)
        .font(.system(size: geo.size.height * 0.7))
}

BoardView displays the game's grid of tiles:

Each of the tiles is represented by a CellView view.

When a tile is tapped, this view exposes its contents:

.onTapGesture() {
    expose(row: row, col: col)
}

On a tap-and-hold, a flag is dropped:

.onLongPressGesture(minimumDuration: 0.1) {
    flag(row: row, col: col)
}

When my family tested the first version of the app, they were frustrated that they couldn't tell whether they'd held long enough for the flag to be dropped. This was an easy mistake to make as their finger was hiding the tile at the time—an example of where testing with a mouse and simulator wasn't a substitute for using real devices. It was especially frustrating as getting it wrong meant that you revealed a mine and immediately lost the game. Fortunately, this is easy to fix using iOS's haptic feedback:

func hapticFeedback(_ isSuccess: Bool) {
    let generator = UINotificationFeedbackGenerator()
    generator.notificationOccurred(isSuccess ? .success : .error)
}

You now feel a buzz when the flag has been dropped.

CellView displays an individual tile:

What's displayed depends on the contents of the Cell and the state of the game. It uses four further views to display different types of tile: FlagView, MineCountView, MineView, and TileView.

FlagView

MineCountView

MineView

TileView

Conclusion

Realm-Sweeper gives a real feel for how quickly Realm is able to synchronize data over the internet.

I intentionally avoided optimizing how I updated the game data in Realm. When you see a single click exposing dozens of tiles, each cell change is an update to the Game object that needs to be synced.

Note that both instances of the game are running in iPhone simulators on an overworked Macbook in England. The Realm backend app is running in the US—that's a 12,000 km/7,500 mile round trip for each sync.

I took this approach as I wanted to demonstrate the performance of Realm synchronization. If an app like this became super-popular with millions of users, then it would put a lot of extra strain on the backend Realm app.

An obvious optimization would be to condense all of the tile changes from a single tap into a single write to the Realm object. If you're interested in trying that out, just fork the repo and make the changes. If you do implement the optimization, then please create a pull request. (I'd probably add it as an option within the settings so that the "slow" mode is still an option.)

Got questions? Ask them in our Community forum.

Using Realm Flexible Sync in Your App – an iOS Tutorial

Andrew Morgan — Fri, 25 Feb 2022 12:44:10 +0000

Introduction

We recently announced the release of the Realm Flexible Sync preview—an opportunity for developers to take it for a spin and give us feedback. That article provided an overview of the benefits of flexible sync and how it works. TL;DR: You typically don't want to sync the entire backend database to every device—whether for capacity or security concerns. Realm Flexible Sync lets the developer provide queries to control exactly what the mobile app asks to sync, together with backend rules to ensure users can only access the data that they're entitled to.

This post builds on that introduction by showing how to add flexible sync to the RChat mobile app. I'll show how to configure the Realm backend app, and then what code needs adding to the mobile app.

Everything you see in this tutorial can be found in the flex-sync branch of the RChat repo.

Prerequisites

Xcode 13.2+
iOS 15+
Realm-Swift 10.22.0+
MongoDB 5.0+

The RChat App

RChat is a messaging app. Users can add other users to a chat room and then share messages, images, and location with each other.

All of the user and chat message data is shared between instances of the app via Realm Sync.

There's a common Realm backend app. There are frontend apps for iOS and Android. This post focuses on the backend and the iOS app.

Configuring the Realm Backend App

The backend app contains a lot of functionality that isn't connected to the sync functionality, and so I won't cover that here. If you're interested, then check out the original RChat series.

As a starting point, you can install the app. I'll then explain the parts connected to Realm Sync.

Import the Backend Realm App

If you don't already have one, create a MongoDB Atlas Cluster, keeping the default name of Cluster0. The Atlas cluster must be running MongoDB 5.0 or later.
Install the Realm CLI and create an API key pair.
Download the repo and install the Realm app:

git clone https://github.com/ClusterDB/RChat.git
git checkout flex-sync
cd RChat/RChat-Realm/RChat
realm-cli login --api-key <your new public key> --private-api-key <your new private key>
realm-cli import # Then answer prompts, naming the app RChat

From the Atlas UI, click on the Realm logo and you will see the RChat app. Open it and copy the App Id. You'll need to use this before building the iOS app.

How Flexible Sync is Enabled in the Back End

Schema

The schema represents how the data will be stored in MongoDB Atlas *and- what the Swift (and Kotlin) model classes must contain.

Each collection/class requires a schema. If you enable Realm's "Developer Mode" option, then Realm will automatically define the schema based on your Swift or Kotlin model classes. In this case, your imported Realm App includes the schemas, and so developer mode isn't needed. You can view the schemas by browsing to the "Schema" section in the Realm UI:

You can find more details about the schema/model in Building a Mobile Chat App Using Realm – Data Architecture, but note that for flexible sync (as opposed to the original partition-based sync), the partition field has been removed.

We're interested in the schema for three collections/model-classes:

User:

{
  "bsonType": "object",
  "properties": {
    "_id": {
      "bsonType": "string"
    },
    "conversations": {
      "bsonType": "array",
      "items": {
        "bsonType": "object",
        "properties": {
          "displayName": {
            "bsonType": "string"
          },
          "id": {
            "bsonType": "string"
          },
          "members": {
            "bsonType": "array",
            "items": {
              "bsonType": "object",
              "properties": {
                "membershipStatus": {
                  "bsonType": "string"
                },
                "userName": {
                  "bsonType": "string"
                }
              },
              "required": [
                "membershipStatus",
                "userName"
              ],
              "title": "Member"
            }
          },
          "unreadCount": {
            "bsonType": "long"
          }
        },
        "required": [
          "unreadCount",
          "id",
          "displayName"
        ],
        "title": "Conversation"
      }
    },
    "lastSeenAt": {
      "bsonType": "date"
    },
    "presence": {
      "bsonType": "string"
    },
    "userName": {
      "bsonType": "string"
    },
    "userPreferences": {
      "bsonType": "object",
      "properties": {
        "avatarImage": {
          "bsonType": "object",
          "properties": {
            "_id": {
              "bsonType": "string"
            },
            "date": {
              "bsonType": "date"
            },
            "picture": {
              "bsonType": "binData"
            },
            "thumbNail": {
              "bsonType": "binData"
            }
          },
          "required": [
            "_id",
            "date"
          ],
          "title": "Photo"
        },
        "displayName": {
          "bsonType": "string"
        }
      },
      "required": [],
      "title": "UserPreferences"
    }
  },
  "required": [
    "_id",
    "userName",
    "presence"
  ],
  "title": "User"
}

User documents/objects represent users of the app.

Chatster:

{
  "bsonType": "object",
  "properties": {
    "_id": {
      "bsonType": "string"
    },
    "avatarImage": {
      "bsonType": "object",
      "properties": {
        "_id": {
          "bsonType": "string"
        },
        "date": {
          "bsonType": "date"
        },
        "picture": {
          "bsonType": "binData"
        },
        "thumbNail": {
          "bsonType": "binData"
        }
      },
      "required": [
        "_id",
        "date"
      ],
      "title": "Photo"
    },
    "displayName": {
      "bsonType": "string"
    },
    "lastSeenAt": {
      "bsonType": "date"
    },
    "presence": {
      "bsonType": "string"
    },
    "userName": {
      "bsonType": "string"
    }
  },
  "required": [
    "_id",
    "presence",
    "userName"
  ],
  "title": "Chatster"
}

Chatster documents/objects represent a read-only subset of instances of User documents. Chatster is needed because there's a subset of User data that we want to make accessible to all users. E.g., I want everyone to be able to see my username, presence status, and avatar image, but I don't want them to see which chat rooms I'm a member of.

Realm Sync lets you control which users can sync which documents, but it doesn't let you sync just a subset of a document's fields. That's why Chatster is needed. I'm looking forward to when Realm Sync permissions allow me to control access on a per-field (rather than per-document/class) basis. At that point, I can remove Chatster from the app.

ChatMessage:

{
  "bsonType": "object",
  "properties": {
    "_id": {
      "bsonType": "string"
    },
    "author": {
      "bsonType": "string"
    },
    "authorID": {
      "bsonType": "string"
    },
    "conversationID": {
      "bsonType": "string"
    },
    "image": {
      "bsonType": "object",
      "properties": {
        "_id": {
          "bsonType": "string"
        },
        "date": {
          "bsonType": "date"
        },
        "picture": {
          "bsonType": "binData"
        },
        "thumbNail": {
          "bsonType": "binData"
        }
      },
      "required": [
        "_id",
        "date"
      ],
      "title": "Photo"
    },
    "location": {
      "bsonType": "array",
      "items": {
        "bsonType": "double"
      }
    },
    "text": {
      "bsonType": "string"
    },
    "timestamp": {
      "bsonType": "date"
    }
  },
  "required": [
    "_id",
    "authorID",
    "conversationID",
    "text",
    "timestamp"
  ],
  "title": "ChatMessage"
}

There's a ChatMessage document object for every message sent to any chat room.

Flexible Sync Configuration

You can view and edit the sync configuration by browsing to the "Sync" section of the Realm UI:

For this deployment, I've selected the Atlas cluster to use. That cluster must be running MongoDB 5.0 or later. At the time of writing, MongoDB 5.0 isn't available for shared clusters (including free-tier M0 instances)—that's expected to change very soon, possibly by the time that you're reading this.

You must specify which fields the mobile app can use in its sync filter queries. Without this, you can't refer to those fields in your sync queries or permissions. You are currently limited to 10 fields.

Scrolling down, you can see the sync permissions:

The UI has flattened the permissions JSON document; here's a version that's easier to read:

{
   "rules": {
       "User": [
           {
               "name": "anyone",
               "applyWhen": {},
               "read": {
                   "_id": "%%user.id"
               },
               "write": {
                   "_id": "%%user.id"
               }
           }
       ],
       "Chatster": [
           {
               "name": "anyone",
               "applyWhen": {},
               "read": true,
               "write": false
           }
       ],
       "ChatMessage": [
           {
               "name": "anyone",
               "applyWhen": {},
               "read": true,
               "write": {
                   "authorID": "%%user.id"
               }
           }
       ]
   },
   "defaultRoles": [
       {
           "name": "all",
           "applyWhen": {},
           "read": {},
           "write": {}
       }
   ]
}

The rules component contains a sub-document for each of our collections. Each of those sub-documents contain an array of roles. Each role contains:

The name of the role, this should be something that helps other developers understand the purpose of the role (e.g., "admin," "owner," "guest").
applyWhen, which defines whether the requesting user matches the role or not. Each of our collections have a single role, and so applyWhen is set to {}, which always evaluates to true.
A read rule—how to decide whether this user can view a given document. This is where our three collections impose different rules:
- A user can read and write to their own User object. No one else can read or write to it.
- Anyone can read any Chatster document, but no one can write to them. Note that these documents are maintained by database triggers to keep them consistent with their associated User document.
- The author of a ChatMessage is allowed to write to it. Anyone can read any ChatMessage. Ideally, we'd restrict it to just members of the chat room, but permissions don't currently support arrays—this is another feature that I'm keen to see added.

Adding Realm Flexible Sync to the iOS App

As with the back end, the iOS app is too big to cover in its entirety in this post. I'll explain how to build and run the app and then go through the components relevant to Realm Flexible Sync.

Configure, Build, and Run the RChat iOS App

You've already downloaded the repo containing the iOS app, but you need to change directory before opening and running the app:

cd ../../RChat-iOS
pod install
open RChat.xcodeproj

Update RChatApp.swift with your Realm App Id (you copied that from the Realm UI when configuring your backend Realm app). In Xcode, select your device or simulator before building and running the app (⌘R). Select a second device or simulator and run the app a second time (⌘R).

On each device, provide a username and password and select the "Register new user" checkbox:

Once registered and logged in on both devices, you can create a new chat room, invite your second user, and start sharing messages and photos. To share location, you first need to enable it in the app's settings.

Key Pieces of the iOS App Code

The Model

You've seen the schemas that were defined for the "User," "Chatster," and "ChatMessage" collections in the back end Realm app. Each of those collections has an associated Realm Object class in the iOS app. Sub-documents map to embedded objects that conform to RealmEmbeddedObject:

Let's take a close look at each of these classes:

User Class

class User: Object, ObjectKeyIdentifiable {
   @Persisted(primaryKey: true) var _id = UUID().uuidString
   @Persisted var userName = ""
   @Persisted var userPreferences: UserPreferences?
   @Persisted var lastSeenAt: Date?
   @Persisted var conversations = List<Conversation>()
   @Persisted var presence = "On-Line"
}

class UserPreferences: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var displayName: String?
   @Persisted var avatarImage: Photo?
}

class Photo: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var _id = UUID().uuidString
   @Persisted var thumbNail: Data?
   @Persisted var picture: Data?
   @Persisted var date = Date()
}

class Conversation: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var id = UUID().uuidString
   @Persisted var displayName = ""
   @Persisted var unreadCount = 0
   @Persisted var members = List<Member>()
}

class Member: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var userName = ""
   @Persisted var membershipStatus = "User added, but invite pending"
}

Chatster Class

class Chatster: Object, ObjectKeyIdentifiable {
   @Persisted(primaryKey: true) var _id = UUID().uuidString // This will match the _id of the associated User
   @Persisted var userName = ""
   @Persisted var displayName: String?
   @Persisted var avatarImage: Photo?
   @Persisted var lastSeenAt: Date?
   @Persisted var presence = "Off-Line"
}

class Photo: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var _id = UUID().uuidString
   @Persisted var thumbNail: Data?
   @Persisted var picture: Data?
   @Persisted var date = Date()
}

ChatMessage Class

class ChatMessage: Object, ObjectKeyIdentifiable {
   @Persisted(primaryKey: true) var _id = UUID().uuidString
   @Persisted var conversationID = ""
   @Persisted var author: String? // username
   @Persisted var authorID: String
   @Persisted var text = ""
   @Persisted var image: Photo?
   @Persisted var location = List<Double>()
   @Persisted var timestamp = Date()
}

class Photo: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var _id = UUID().uuidString
   @Persisted var thumbNail: Data?
   @Persisted var picture: Data?
   @Persisted var date = Date()
}

Accessing Synced Realm Data

Any iOS app that wants to sync Realm data needs to create a Realm App instance, providing the Realm App ID so that the Realm SDK can connect to the backend Realm app:

let app = RealmSwift.App(id: "rchat-xxxxx") // TODO: Set the Realm application ID

When a SwiftUI view (in this case, LoggedInView) needs to access synced data, the parent view must flag that flexible sync will be used. It does this by passing the Realm configuration through the SwiftUI environment:

LoggedInView(userID: $userID)
   .environment(\.realmConfiguration,
               app.currentUser!.flexibleSyncConfiguration())

LoggedInView can then access two variables from the SwiftUI environment:

struct LoggedInView: View {
   ...
   @Environment(\.realm) var realm
   @ObservedResults(User.self) var users

The users variable is a live query containing all synced User objects in the Realm. But at this point, no User documents have been synced because we haven't subscribed to anything.

That's easy to fix. We create a new function (setSubscription) that's invoked when the view is opened:

struct LoggedInView: View {
   ...
   @Binding var userID: String?
   ...
   var body: some View {
       ZStack {
           ...
       }
       .onAppear(perform: setSubscription)
   }

   private func setSubscription() {
       let subscriptions = realm.subscriptions
       subscriptions.write {
           if let currentSubscription = subscriptions.first(named: "user_id") {
               print("Replacing subscription for user_id")
               currentSubscription.update(toType: User.self) { user in
                   user._id == userID!
               }
           } else {
               print("Appending subscription for user_id")
               subscriptions.append(QuerySubscription<User>(name: "user_id") { user in
                   user._id == userID!
               })
           }
       }
   }
}

Subscriptions are given a name to make them easier to work with. I named this one user_id.

The function checks whether there's already a subscription named user_id. If there is, then the function replaces it. If not, then it adds the new subscription. In either case, the subscription is defined by passing in a query that finds any User documents/objects where the _id field matches the current user's ID.

The subscription should sync exactly one User object to the realm, and so the code for the view's body can work with the first object in the results:

struct LoggedInView: View {
   ...
   @ObservedResults(User.self) var users
   @Binding var userID: String?
   ...
   var body: some View {
       ZStack {
           if let user = users.first {
               ...
               ConversationListView(user: user)
               ...
           }
       }
       .navigationBarTitle("Chats", displayMode: .inline)
       .onAppear(perform: setSubscription)
   }
}

Other views work with different model classes and sync queries. For example, when the user clicks on a chat room, a new view is opened that displays all of the ChatMessages for that conversation:

struct ChatRoomBubblesView: View {
   ...
   @ObservedResults(ChatMessage.self, sortDescriptor: SortDescriptor(keyPath: "timestamp", ascending: true)) var chats
   @Environment(\.realm) var realm
   ...
   var conversation: Conversation?
   ...
   var body: some View {
       VStack {
           ...
       }
       .onAppear { loadChatRoom() }
   }

   private func loadChatRoom() {
       ...
       setSubscription()
       ...
   }

   private func setSubscription() {
       let subscriptions = realm.subscriptions
       subscriptions.write {
           if let conversation = conversation {
               if let currentSubscription = subscriptions.first(named: "conversation") {
                   currentSubscription.update(toType: ChatMessage.self) { chatMessage in
                       chatMessage.conversationID == conversation.id
                   }
               } else {
                   subscriptions.append(QuerySubscription<ChatMessage>(name: "conversation") { chatMessage in
                       chatMessage.conversationID == conversation.id
                   })
               }
           }
       }
   }
}

In this case, the query syncs all ChatMessage objects where the conversationID matches the id of the Conversation object passed to the view.

The view's body can then iterate over all of the matching, synced objects:

struct ChatRoomBubblesView: View {
...
   @ObservedResults(ChatMessage.self,
       sortDescriptor: SortDescriptor(keyPath: "timestamp", ascending: true)) var chats
   ...
   var body: some View {
       ...
       ForEach(chats) { chatMessage in
           ChatBubbleView(chatMessage: chatMessage,
                           authorName: chatMessage.author != user.userName ? chatMessage.author : nil,
                           isPreview: isPreview)
       }
       ...
   }
}

As it stands, there's some annoying behavior. If you open conversation A, go back, and then open conversation B, you'll initially see all of the messages from conversation A. The reason is that it takes a short time for the updated subscription to replace the ChatMessage objects in the synced Realm. I solve that by explicitly removing the subscription (which purges the synced objects) when closing the view:

struct ChatRoomBubblesView: View {
   ...
   @Environment(\.realm) var realm
   ...
   var body: some View {
       VStack {
           ...
       }
       .onDisappear { closeChatRoom() }
   }

   private func closeChatRoom() {
       clearSubscription()
       ...
   }

   private func clearSubscription() {
       print("Leaving room, clearing subscription")
       let subscriptions = realm.subscriptions
       subscriptions.write {
           subscriptions.remove(named: "conversation")
       }
   }
}

I made a design decision that I'd use the same name ("conversation") for this view, regardless of which conversation/chat room it's working with. An alternative would be to create a unique subscription whenever a new chat room is opened (including the ID of the conversation in the name). I could then avoid removing the subscription when navigating away from a chat room. This second approach would come with two advantages:

The app should be more responsive when navigating between chat rooms (if you'd previously visited the chat room that you're opening).
You can switch between chat rooms even when the device isn't connected to the internet.

The disadvantages of this approach would be:

The app could end up with a lot of subscriptions (and there's a cost to them).
The app continues to store all of the messages from any chat room that you've ever visited from this device. That consumes extra device storage and network bandwidth as messages from all of those rooms continue to be synced to the app.

A third approach would be to stick with a single subscription (named "conversations") that matches every ChatMessage object. The view would then need to apply a filter on the resulting ChatMessage objects so it only displayed those for the open chat room. This has the same advantages as the second approach, but can consume even more storage as the device will contain messages from all chat rooms—including those that the user has never visited.

Note that a different user can log into the app from the same device. You don't want that user to be greeted with someone else's data. To avoid that, the app removes all subscriptions when a user logs out:

struct LogoutButton: View {
   ...
   @Environment(\.realm) var realm


   var body: some View {
       Button("Log Out") { isConfirming = true }
       .confirmationDialog("Are you that you want to logout",
                           isPresented: $isConfirming) {
           Button("Confirm Logout", role: .destructive, action: logout)
           Button("Cancel", role: .cancel) {}
       }
       .disabled(state.shouldIndicateActivity)
   }

   private func logout() {
       ...
       clearSubscriptions()
       ...
   }

   private func clearSubscriptions() {
       let subscriptions = realm.subscriptions
       subscriptions.write {
           subscriptions.removeAll()
       }
   }
}

Conclusion

In this article, you've seen how to include Realm Flexible Sync in your mobile app. I've shown the code for Swift, but the approach would be the same when building apps with Kotlin, Javascript, or .NET.

This is a preview release and we want your feedback.

Realm Flexible Sync will evolve to include more query and permission operators. Up next, we're looking to expose array operators (that would allow me to add tighter restrictions on who can ask to read which chat messages). We'll also enable querying on embedded documents.

Another feature I'd like to see is to limit which fields from a document get synced to a given user. This could allow the removal of the Chatster collection, as it's only there to provide a read-only view of a subset of User fields to other users.

Want to suggest an enhancement or up-vote an existing request? The most effective way is through our feedback portal.

Got questions? Ask them in our Community forum.

Realm-Swift Type Projections

Andrew Morgan — Wed, 26 Jan 2022 17:06:37 +0000

Introduction

Realm natively provides a broad set of data types, including Bool, Int, Float, Double, String, Date, ObjectID, List, Mutable Set, enum, Map, …

But, there are other data types that many of your iOS apps are likely to use. As an example, if you're using Core Graphics, then it's hard to get away without using types such as CGFloat, CGPoint, etc. When working with SwiftUI, you use the Color struct when working with colors.

A typical design pattern is to persist data using types natively supported by Realm, and then use a richer set of types in your app. When reading data, you add extra boilerplate code to convert them to your app's types. When persisting data, you add more boilerplate code to convert your data back into types supported by Realm.

That works fine and gives you complete control over the type conversions. The downside is that you can end up with dozens of places in your code where you need to make the conversion.

Type projections still give you total control over how to map a CGPoint into something that can be persisted in Realm. But, you write the conversion code just once and then forget about it. The Realm-Swift SDK will then ensure that types are converted back and forth as required in the rest of your app.

The Realm-Swift SDK enables this by adding two new protocols that you can use to extend any Swift type. You opt whether to implement CustomPersistable or the version that's allowed to fail (FailableCustomPersistable):

protocol CustomPersistable {
   associatedtype PersistedType
   init(persisted: PersistedType)
   var persistableValue: PersistedType { get }
}
protocol FailableCustomPersistable {
   associatedtype PersistedType
   init?(persisted: PersistedType)
   var persistableValue: PersistedType { get }
}

In this post, I'll show how the Realm-Drawing app uses type projections to interface between Realm and Core Graphics.

Prerequisites

iOS 15+
Xcode 13.2+
Realm-Swift 10.21.0+

The Realm-Drawing App

Realm-Drawing is a simple, collaborative drawing app. If two people log into the app using the same username, they can work on a drawing together. All strokes making up the drawing are persisted to Realm and then synced to all other instances of the app where the same username is logged in.

It's currently iOS-only, but it would also sync with any Android drawing app that is connected to the same Realm back end.

Using Type Projections in the App

The Realm-Drawing iOS app uses three types that aren't natively supported by Realm:

CGFloat
CGPoint
Color (SwiftUI)

In this section, you'll see how simple it is to use type projections to convert them into types that can be persisted to Realm and synced.

Realm Schema (The Model)

An individual drawing is represented by a single Drawing object:

class Drawing: Object, ObjectKeyIdentifiable {
   @Persisted(primaryKey: true) var _id: ObjectId
   @Persisted var name = UUID().uuidString
   @Persisted var lines = RealmSwift.List<Line>()
}

A Drawing contains a List of Line objects:

class Line: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var lineColor: Color
   @Persisted var lineWidth: CGFloat = 5.0
   @Persisted var linePoints = RealmSwift.List<CGPoint>()
}

It's the Line class that uses the non-Realm-native types.

Let's see how each type is handled.

CGFloat

I extend CGFloat to conform to Realm-Swift's CustomPersistable protocol. All I needed to provide was:

An initializer to convert what's persisted in Realm (a Double) into the CGFloat used by the model
A method to convert a CGFloat into a Double:

extension CGFloat: CustomPersistable {
   public typealias PersistedType = Double
   public init(persistedValue: Double) { self.init(persistedValue) }
   public var persistableValue: Double { Double(self) }
}

The view can then use lineWidth from the model object without worrying about how it's converted by the Realm SDK:

context.stroke(path, with: .color(line.lineColor),
   style: StrokeStyle(
       lineWidth: line.lineWidth,
       lineCap: .round, l
       ineJoin: .round
   )
)

CGPoint

CGPoint is a little trickier, as it can't just be cast into a Realm-native type. CGPoint contains the x and y coordinates for a point, and so, I create a Realm-friendly class (PersistablePoint) that stores just that—x and y values as Doubles:

public class PersistablePoint: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var x = 0.0
   @Persisted var y = 0.0

   convenience init(_ point: CGPoint) {
       self.init()
       self.x = point.x
       self.y = point.y
   }
}

I implement the CustomPersistable protocol for CGPoint by mapping between a CGPoint and the x and y coordinates within a PersistablePoint:

extension CGPoint: CustomPersistable {
   public typealias PersistedType = PersistablePoint   
   public init(persistedValue: PersistablePoint) { self.init(x: persistedValue.x, y: persistedValue.y) }
   public var persistableValue: PersistablePoint { PersistablePoint(self) }
}

SwiftUI.Color

Color is made up of the three RGB components plus the opacity. I use the PersistableColor class to persist a representation of Color:

public class PersistableColor: EmbeddedObject {
   @Persisted var red: Double = 0
   @Persisted var green: Double = 0
   @Persisted var blue: Double = 0
   @Persisted var opacity: Double = 0

   convenience init(color: Color) {
       self.init()
       if let components = color.cgColor?.components {
           if components.count >= 3 {
               red = components[0]
               green = components[1]
               blue = components[2]
           }
           if components.count >= 4 {
               opacity = components[3]
           }
       }
   }
}

The extension to implement CustomPersistable for Color provides methods to initialize Color from a PersistableColor, and to generate a PersistableColor from itself:

extension Color: CustomPersistable {
   public typealias PersistedType = PersistableColor

   public init(persistedValue: PersistableColor) { self.init(
       .sRGB,
       red: persistedValue.red,
       green: persistedValue.green,
       blue: persistedValue.blue,
       opacity: persistedValue.opacity) }

   public var persistableValue: PersistableColor {
       PersistableColor(color: self)
   }
}

The view can then use selectedColor from the model object without worrying about how it's converted by the Realm SDK:

context.stroke(
   path,
   with: .color(line.lineColor),
   style: StrokeStyle(lineWidth:
   line.lineWidth,
   lineCap: .round,
   lineJoin: .round)
)

Conclusion

Type projections provide a simple, elegant way to convert any type to types that can be persisted and synced by Realm.

It's your responsibility to define how the mapping is implemented. After that, the Realm SDK takes care of everything else.

Please provide feedback and ask any questions in the Realm Community Forum.

Introducing Flexible Sync (Preview) - The Next Iteration of Realm Sync

Andrew Morgan — Wed, 26 Jan 2022 10:48:11 +0000

We are excited to announce the public preview of our next version of Realm Sync: Flexible Sync. This new method of syncing puts the power into the hands of the developer. Now, developers can get more granular control over the data synced to user applications with intuitive language-native queries and hierarchical permissions.

Introduction

Prior to launching the general availability of Realm Sync in February 2021, the Realm team spent countless hours with developers learning how they build best-in-class mobile applications. A common theme emerged—building real-time, offline-first mobile apps require an overwhelming amount of complex, non-differentiating work.

Our first version of Realm Sync addressed this pain by abstracting away offline-first, real-time syncing functionality using declarative APIs. It expedited the time-to-market for many developers and worked well for apps where data is static and compartmentalized, or where permissions rarely need to change. But for dynamic apps and complex use cases, developers still had to spend time creating workarounds instead of developing new features. With that in mind, we built the next iteration of Realm Sync: Flexible Sync. Flexible Sync is designed to help developers:

Get to market faster: Use intuitive, language-native queries to define the data synced to user applications instead of proprietary concepts.
Optimize real-time collaboration between users: Utilize object-level conflict-resolution logic.
Simplify permissions: Apply role-based logic to applications with an expressive permissions system that groups users into roles on a pe-class or collection basis.

Language-Native Querying

Flexible Sync’s query-based sync logic is distinctly different from how Realm Sync operates today. The new structure is designed to more closely mirror how developers are used to building sync today—typically using GET requests with query parameters.

One of the primary benefits of Flexible Sync is that it eliminates all the time developers spend determining what query parameters to pass to an endpoint. Instead, the Realm APIs directly integrate with the native querying system on the developer’s choice of platform—for example, a predicate-based query language for iOS, a Fluent query for Android, a string-based query for Javascript, and a LINQ query for .NET.

Under the hood, the Realm Sync thread sends the query to MongoDB Realm (Realm’s cloud offering). MongoDB Realm translates the query to MongoDB’s query language and executes the query against MongoDB Atlas. Atlas then returns the resulting documents. Those documents are then translated into Realm objects, sent down to the Realm client, and stored on disk. The Realm Sync thread keeps a queue of any changes made locally to synced objects—even when offline. As soon as connectivity is reestablished, any changes made to the server-side or client-side are synced down using built-in granular conflict resolution logic. All of this occurs behind the scenes while the developer is interacting with the data. This is the part we’ve heard our users describe as “magic.”

Flexible Sync also enables much more dynamic queries, based on user inputs. Picture a home listing app that allows users to search available properties in a certain area. As users define inputs—only show houses in Dallas, TX that cost less than $300k and have at least three bedrooms—the query parameters can be combined with logical ANDs and ORs to produce increasingly complex queries, and narrow down the search result even further. All query results are combined into a single realm file on the client’s device, which significantly simplifies code required on the client-side and ensures changes to data are synced efficiently and in real time.

Swift

// Set your Schema
class Listing: Object {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var location: String
    @Persisted var price: Int
    @Persisted var bedrooms: Int
}

// Configure your App and login
let app = App(id: "XXXX")
let user = try! await app.login(credentials:
            .emailPassword(email: "email", password: "password"))

// Set the new Flexible Sync Config and open the Realm
let config = user.flexibleSyncConfiguration()
let realm = try! await Realm(configuration: config, downloadBeforeOpen: .always)

// Create a Query and Add it to your Subscriptions
let subscriptions = realm.subscriptions

try! await subscriptions.write {
    subscriptions.append(QuerySubscription<Listing>(name: "home-search") {
        $0.location == "dallas" && $0.price < 300000 && $0.bedrooms >= 3
    })
}

// Now query the local realm and get your home listings - output is 100 listings
// in the results
print(realm.objects(Listing.self).count)

// Remove the subscription - the data is removed from the local device but stays
// on the server
try! await subscriptions.write {
    subscriptions.remove(named: "home-search")
}

// Output is 0 - listings have been removed locally
print(realm.objects(Listing.self).count)

Kotlin

// Set your Schema
open class Listing: ObjectRealm() {
  @PrimaryKey
  @RealmField("_id")
  var id: ObjectId
  var location: String = ""
  var price: Int = 0
  var bedrooms: Int = 0
}

// Configure your App and login
val app = App("<YOUR_APP_ID_HERE>")
val user = app.login(Credentials.emailPassword("email", "password"))

// Set the new Flexible Sync Config and open the Realm
let config = SyncConfiguration.defaultConfig(user)
let realm = Realm.getInstance(config)

// Create a Query and Add it to your Subscriptions
val subscriptions = realm.subscriptions
subscriptions.update { mutableSubscriptions ->
   val sub = Subscription.create(
      "home-search", 
      realm.where<Listing>()
         .equalTo("location", "dallas")
         .lessThan("price", 300_000)
         .greaterThanOrEqual("bedrooms", 3)
   )
   mutableSubscriptions.add(subscription)
}

// Wait for server to accept the new subscription and download data
subscriptions.waitForSynchronization()
realm.refresh()

// Now query the local realm and get your home listings - output is 100 listings 
// in the results
val homes = realm.where<Listing>().count()

// Remove the subscription - the data is removed from the local device but stays 
// on the server
subscriptions.update { mutableSubscriptions ->
   mutableSubscriptions.remove("home-search")
}
subscriptions.waitForSynchronization()
realm.refresh()

// Output is 0 - listings have been removed locally
val homes = realm.where<Listing>().count()

.NET

// Set your Schema
class Listing: RealmObject
{
    [PrimaryKey, MapTo("_id")]
    public ObjectId Id { get; set; }
    public string Location { get; set; }
    public int Price { get; set; }
    public int Bedrooms { get; set; }
}

// Configure your App and login
var app = App.Create(YOUR_APP_ID_HERE);
var user = await app.LogInAsync(Credentials.EmailPassword("email", "password"));

// Set the new Flexible Sync Config and open the Realm
var config = new FlexibleSyncConfiguration(user);
var realm = await Realm.GetInstanceAsync(config);

// Create a Query and Add it to your Subscriptions
var dallasQuery = realm.All<Listing>().Where(l => l.Location == "dallas" && l.Price < 300_000 && l.Bedrooms >= 3);
realm.Subscriptions.Update(() =>
{
    realm.Subscriptions.Add(dallasQuery);
});

await realm.Subscriptions.WaitForSynchronizationAsync();

// Now query the local realm and get your home listings - output is 100 listings
// in the results
var numberOfListings = realm.All<Listing>().Count();

// Remove the subscription - the data is removed from the local device but stays
// on the server

realm.Subscriptions.Update(() =>
{
    realm.Subscriptions.Remove(dallasQuery);
});

await realm.Subscriptions.WaitForSynchronizationAsync();

// Output is 0 - listings have been removed locally
numberOfListings = realm.All<Listing>().Count();

JavaScript

import Realm from "realm";

// Set your Schema
const ListingSchema = {
  name: "Listing",
  primaryKey: "_id",
  properties: {
    _id: "objectId",
    location: "string",
    price: "int",
    bedrooms: "int",
  },
};

// Configure your App and login
const app = new Realm.App({ id: YOUR_APP_ID_HERE });
const credentials = Realm.Credentials.emailPassword("email", "password");
const user = await app.logIn(credentials);

// Set the new Flexible Sync Config and open the Realm
const realm = await Realm.open({
  schema: [ListingSchema],
  sync: { user, flexible: true },
});

// Create a Query and Add it to your Subscriptions
await realm.subscriptions.update((mutableSubscriptions) => {
  mutableSubscriptions.add(
    realm
      .objects(ListingSchema.name)
      .filtered("location = 'dallas' && price < 300000 && bedrooms = 3", {
        name: "home-search",
      })
  );
});

// Now query the local realm and get your home listings - output is 100 listings
// in the results
let homes = realm.objects(ListingSchema.name).length;

// Remove the subscription - the data is removed from the local device but stays
// on the server
await realm.subscriptions.update((mutableSubscriptions) => {
  mutableSubscriptions.removeByName("home-search");
});

// Output is 0 - listings have been removed locally
homes = realm.objects(ListingSchema.name).length;

Optimizing for Real-Time Collaboration

Flexible Sync also enhances query performance and optimizes for real-time user collaboration by treating a single object or document as the smallest entity for synchronization. Flexible Sync allows for Sync Realms to more efficiently share data and for conflict resolution to incorporate changes faster and with less data transfer.

For example, you and a fellow employee are analyzing the remaining tasks for a week. Your coworker wants to see all of the time-intensive tasks remaining (workunits > 5), and you want to see all the tasks you have left for the week (owner == ianward). Your queries will overlap where workunits > 5 and owner == ianward. If your coworker notices one of your tasks is marked incorrectly as 7 workunits and changes the value to 6, you will see the change reflected on your device in real time. Under the hood, the merge algorithm will only sync the changed document instead of the entire set of query results increasing query performance.

Permissions

Whether it’s a company’s internal application or an app on the App Store, permissions are required in almost every application. That’s why we are excited by how seamless Flexible Sync makes applying a document-level permission model when syncing data—meaning synced documents can be limited based on a user’s role.

Consider how a sales organization uses a CRM application. An individual sales representative should only be able to access her own sales pipeline while her manager needs to be able to see the entire region’s sales pipeline. In Flexible Sync, a user’s role will be combined with the client-side query to determine the appropriate result set. For example, when the sales representative above wants to view her deals, she would send a query where opportunities.owner == "EmmaLullo" but when her manager wants to see all the opportunities for their entire team, they would query with opportunities.team == "West”. If a user sends a much more expansive query, such as querying for all opportunities, then the permissions system would only allow data to be synced for which the user had explicit access.

{
  "Opportunities": {
    "roles": [
        {
                name: "manager", 
                applyWhen: { "%%user.custom_data.isSalesManager": true},
                read: {"team": "%%user.custom_data.teamManager"}
                write: {"team": "%%user.custom_data.teamManager"}
            },
        {
                name: "salesperson",
                applyWhen: {},
                read: {"owner": "%%user.id"}
                write: {"owner": "%%user.id"}
        }
    ]
  },
{
  "Bookings": {
    "roles": [
        {
                name: "accounting", 
                applyWhen: { "%%user.custom_data.isAccounting": true},
                read: true,
                write: true
            },
        {
                name: "sales",
                applyWhen: {},
                read: {"%%user.custom_data.isSales": true},
                write: false
        }
    ]
  }

Looking Ahead

Ultimately, our goal with Flexible Sync is to deliver a sync service that can fit any use case or schema design pattern imaginable without custom code or workarounds. And while we are excited that Flexible Sync is now in preview, we’re nowhere near done.

The Realm Sync team is planning to bring you more query operators and permissions integrations over the course of 2022. Up next we are looking to expose array operators and enable querying on embedded documents, but really, we look to you, our users, to help us drive the roadmap. Submit your ideas and feature requests to our feedback portal and ask questions in our Community forum. Happy building!

Goodbye NSPredicate, hello Realm Swift Query API

Andrew Morgan — Fri, 17 Dec 2021 19:26:02 +0000

Introduction

I'm not a fan of writing code using pseudo-English text strings. It's a major context switch when you've been writing "native" code. Compilers don't detect errors in the strings, whether syntax errors or mismatched types, leaving you to learn of your mistakes when your app crashes.

I spent more than seven years working at MySQL and Oracle, and still wasn't comfortable writing anything but the simplest of SQL queries. I left to join MongoDB because I knew that the object/document model was the way that developers should work with their data. I also knew that idiomatic queries for each programming language were the way to go.

That's why I was really excited when MongoDB acquired Realm—a leading mobile object database. You work with Realm objects in your native language (in this case, Swift) to manipulate your data.

However, there was one area that felt odd in Realm's Swift SDK. You had to use NSPredicate when searching for Realm objects that match your criteria. NSPredicates are strings with variable substitution. 🤦‍♂️

NSPredicates are used when searching for data in Apple's Core Data database, and so it was a reasonable design decision. It meant that iOS developers could reuse the skills they'd developed while working with Core Data.

But, I hate writing code as strings.

The good news is that the Realm SDK for Swift has added the option to use type-safe queries through the Realm Swift Query API. 🥳.

You now have the option whether to filter using NSPredicates:

let predicate = NSPredicate(format: "isSoft == %@", NSNumber(value: wantSoft)
let decisions = unfilteredDecisions.filter(predicate)

or with the new Realm Swift Query API:

let decisions = unfilteredDecisions.where { $0.isSoft == wantSoft }

In this article, I'm going to show you some examples of how to use the Realm Swift Query API. I'll also show you an example where wrangling with NSPredicate strings has frustrated me.

Prerequisites

Realm-Cocoa 10.19.0+

Using The Realm Swift Query API

I have a number of existing Realm iOS apps using NSPredicates. When I learnt of the new query API, the first thing I wanted to do was try to replace some of "legacy" queries. I'll start by describing that experience, and then show what other type-safe queries are possible.

Replacing an NSPredicate

I'll start with the example I gave in the introduction (and how the NSPredicate version had previously frustrated me).

I have an app to train you on what decisions to make in Black Jack (based on the cards you've been dealt and the card that the dealer is showing). There are three different decision matrices based on the cards you've been dealt:

Whether you have the option to split your hand (you've been dealt two cards with the same value)
Your hand is "soft" (you've been dealt an ace, which can take the value of either one or eleven)
Any other hand

All of the decision-data for the app is held in Decisions objects:

class Decisions: Object, ObjectKeyIdentifiable {
   @Persisted var decisions = List<DecisionList>()
   @Persisted var isSoft = false
   @Persisted var isSplit = false
   ...
}

SoftDecisionView needs to find the Decisions object where isSoft is set to true. That requires a simple NSPredicate:

struct SoftDecisionView: View {
   @ObservedResults(Decisions.self, filter: NSPredicate(format: "isSoft == YES")) var decisions
   ...
}

But, what if I'd mistyped the attribute name? There's no Xcode auto-complete to help when writing code within a string, and this code builds with no errors or warnings:

struct SoftDecisionView: View {
   @ObservedResults(Decisions.self, filter: NSPredicate(format: "issoft == YES")) var decisions
   ...
}

When I run the code, it works initially. But, when I'm dealt a soft hand, I get this runtime crash:

Terminating app due to uncaught exception 'Invalid property name', reason: 'Property 'issoft' not found in object of type 'Decisions''

Rather than having a dedicated view for each of the three types of hand, I want to experiment with having a single view to handle all three.

SwiftUI doesn't allow me to use variables (or even named constants) as part of the filter criteria for @ObservedResults. This is because the struct hasn't been initialized until after the @ObservedResults is defined. To live within SwitfUIs constraints, the filtering is moved into the view's body:

struct SoftDecisionView: View {
   @ObservedResults(Decisions.self) var unfilteredDecisions
   let isSoft = true

   var body: some View {
       let predicate = NSPredicate(format: "isSoft == %@", isSoft)
       let decisions = unfilteredDecisions.filter(predicate)
   ...
}

Again, this builds, but the app crashes as soon as I'm dealt a soft hand. This time, the error is much more cryptic:

Thread 1: EXC_BAD_ACCESS (code=1, address=0x1)

It turns out that, you need to convert the boolean value to an NSNumber before substituting it into the NSPredicate string:

struct SoftDecisionView: View {
   @ObservedResults(Decisions.self) var unfilteredDecisions


   let isSoft = true


   var body: some View {
       let predicate = NSPredicate(format: "isSoft == %@", NSNumber(value: isSoft))
       let decisions = unfilteredDecisions.filter(predicate)
   ...
}

Who knew? OK, StackOverflow did, but it took me quite a while to find the solution.

Hopefully, this gives you a feeling for why I don't like writing strings in place of code.

This is the same code using the new (type-safe) Realm Swift Query API:

struct SoftDecisionView: View {
   @ObservedResults(Decisions.self) var unfilteredDecisions
   let isSoft = true

   var body: some View {
       let decisions = unfilteredDecisions.where { $0.isSoft == isSoft }
   ...
}

The code's simpler, and (even better) Xcode won't let me use the wrong field name or type—giving me this error before I even try running the code:

Experimenting With Other Sample Queries

In my RCurrency app, I was able to replace this NSPredicate-based code:

struct CurrencyRowContainerView: View {
   @ObservedResults(Rate.self) var rates
   let baseSymbol: String
   let symbol: String

   var rate: Rate? {
       NSPredicate(format: "query.from = %@ AND query.to = %@", baseSymbol, symbol)).first
   }
   ...
}

With this:

struct CurrencyRowContainerView: View {
   @ObservedResults(Rate.self) var rates
   let baseSymbol: String
   let symbol: String

   var rate: Rate? {
       rates.where { $0.query.from == baseSymbol && $0.query.to == symbol }.first
   }
   ...
}

Again, I find this more Swift-like, and bugs will get caught as I type/build rather than when the app crashes.

I'll use this simple Task Object to show a few more example queries:

class Task: Object, ObjectKeyIdentifiable {
   @Persisted var name = ""
   @Persisted var isComplete = false
   @Persisted var assignee: String?
   @Persisted var priority = 0
   @Persisted var progressMinutes = 0
}

All in-progress tasks assigned to name:

let myStartedTasks = realm.objects(Task.self).where {
   ($0.progressMinutes > 0) && ($0.assignee == name)
}

All tasks where the priority is higher than minPriority:

let highPriorityTasks = realm.objects(Task.self).where {
   $0.priority >= minPriority
}

All tasks that have a priority that's an integer between -1 and minPriority:

let lowPriorityTasks = realm.objects(Task.self).where {
   $0.priority.contains(-1...minPriority)
}

All tasks where the assignee name string includes namePart:

let tasksForName = realm.objects(Task.self).where {
   $0.assignee.contains(namePart)
}

Filtering on Sub-Objects

You may need to filter your Realm objects on values within their sub-objects. Those sub-object may be EmbeddedObjects or part of a List.

I'll use the Project class to illustrate filtering on the attributes of sub-documents:

class Project: Object, ObjectKeyIdentifiable {
   @Persisted var name = ""
   @Persisted var tasks: List<Task>
}

All projects that include a task that's in-progress, and is assigned to a given user:

let myActiveProjects = realm.objects(Project.self).where {
   ($0.tasks.progressMinutes >= 1) && ($0.tasks.assignee == name)
}

Including the Query When Creating the Original Results (SwiftUI)

At the time of writing, this feature wasn't released, but it can be tested using this PR.

You can include the where modifier directly in your @ObservedResults call. That avoids the need to refine your results inside your view's body:

@ObservedResults(Decisions.self, where: { $0.isSoft == true }) var decisions

Unfortunately, SwiftUI rules still mean that you can't use variables or named constants in your where block for @ObservedResults.

Conclusion

Realm type-safe queries provide a simple, idiomatic way to filter results in Swift. If you have a bug in your query, it should be caught by Xcode rather than at run-time.

You can find more information in the docs. If you want to see hundreds of examples, and how they map to equivalent NSPredicate queries, then take a look at the test cases.

For those that prefer working with NSPredicates, you can continue to do so. In fact the Realm Swift Query API runs on top of the NSPredicate functionality, so they're not going anywhere soon.

Please provide feedback and ask any questions in the Realm Community Forum.