Isar 개념 7 - Watchers

아래 내용은 첨부된 이미지를 토대로 Isar의 Watchers 기능에 대해 최대한 빠짐없이 정리한 것입니다.
Dart 언어 초급자 분들도 이해하기 쉬우시도록 용어를 풀어서 설명하고, 코드 예시와 상세한 주석을 포함했습니다.

---

1. Watchers 개요

“Isar allows you to subscribe to changes in the database. You can ‘watch’ for changes in a specific object, an entire collection, or a query.”

Isar의 Watcher는 데이터베이스(DB)에 변화가 생길 때 이를 실시간으로 감지하고, 특정 동작(예: UI 갱신, 콘솔 출력, 이벤트 처리 등)을 수행할 수 있도록 도와주는 기능입니다.

• 특정 객체(Object) 변경 감지: 어떤 객체가 추가/수정/삭제될 때 알림 받기
• 컬렉션(Collection) 전체 변경 감지: 해당 컬렉션에 새로운 객체가 추가되거나, 기존 객체가 업데이트 또는 삭제될 때 알림 받기
• 쿼리(Query) 결과 변경 감지: 특정 쿼리(예: name == '홍길동'인 User 목록) 결과가 바뀔 때 알림 받기

Watcher는 트랜잭션이 성공적으로 커밋된 후, 실제로 해당 대상이 변경되었을 때 알림을 발생시킵니다.

---

2. Watching Objects (특정 객체 감시)

“If you want to be notified when a specific object is created, updated or deleted, you should watch an object.”

2.1 기본 사용법

아래 예시에서는 User라는 모델과, 그 모델의 id를 사용하여 특정 유저 객체의 변화를 감시합니다.

// 특정 유저 객체(ID=3)를 감시하는 스트림
Stream<User?> userChange = isar.users.watchObject(3);

// 변화가 생길 때마다 알림을 받음
userChange.listen((model) {
  // model == null 이라면 해당 User가 삭제되었음을 의미
  if (model == null) {
    print("User changed: null (deleted)");
  } else {
    print("User changed: ${model.name}");
  }
});

/// 실제 데이터 조작 예시
final user = User()
  ..id = 3
  ..name = "David";

// 1) 유저 추가 -> "User changed: David" 가 출력됨
await isar.writeTxn(() => isar.users.put(user));

// 2) 유저 업데이트 -> "User changed: Mark" 가 출력됨
user.name = "Mark";
await isar.writeTxn(() => isar.users.put(user));

// 3) 유저 삭제 -> "User changed: null" 이 출력됨
await isar.writeTxn(() => isar.users.delete(user.id));

설명

1. watchObject(3)
   • id=3번 User 객체를 대상으로 변경 사항을 감시합니다.
   • 해당 객체가 없어도 괜찮습니다. 존재하지 않던 객체가 추가될 때, 알림이 발생합니다.
2. User? (nullable)
   • 객체가 삭제되면 model이 null로 들어옵니다.
3. 트랜잭션
   • Isar에서 데이터를 추가/수정/삭제하려면 항상 writeTxn 블록 안에서 수행해야 하며, Watcher도 트랜잭션이 커밋된 후 알림을 받습니다.

2.2 fireImmediately 파라미터

“There is an additional parameter fireImmediately. If you set it to true, Isar will immediately add the object’s current value to the stream.”

• watchObject(id, fireImmediately: true) 처럼 사용하면, Watcher를 등록하자마자 해당 객체의 현재 상태를 즉시 한 번 내보내줍니다.
• 기본값은 false이며, 이 경우는 변경이 일어날 때만 알림을 받습니다.

---

3. Lazy Watching (값이 아닌 변경 사실만 수신)

“Maybe you don’t need to receive the new value but only be notified about the change. That saves Isar from having to fetch the object.”

Lazy Watching은 객체 변경 시, 새 객체 정보가 아니라 “변경이 일어났다”라는 사실만 알림을 받는 방법입니다.
이 기능을 사용하면 DB가 실제로 객체를 다시 로드하거나, 스트림으로 전달할 필요가 없기 때문에 성능상 이점이 있을 수 있습니다.

// '값' 대신 '변경 이벤트'만 전달됨
Stream<void> userChange = isar.users.watchObjectLazy(3);

userChange.listen((_) {
  print("User with id=3 changed!");
});

// 이후 동일하게 트랜잭션에서 put, delete 등을 하면
// "User with id=3 changed!" 가 로그로 출력 (model 정보 없음)

• _ (매개변수)로 아무런 데이터가 들어오지 않으며, 단지 “어떤 변경이 발생했다”는 이벤트만 받습니다.
• 객체의 새로운 상태를 확인하려면, 별도로 isar.users.get(3) 등을 호출해야 합니다.

---

4. Watching Collections (컬렉션 전체 감시)

“Instead of watching a single object, you can watch an entire collection and get notified when any object is added, updated or deleted.”

컬렉션 전체를 감시하면, 해당 컬렉션 내 어떤 객체가 추가, 수정, 삭제되어도 알림을 받을 수 있습니다.

Stream<void> userChanged = isar.users.watchLazy();
// Lazy 방식: 객체 목록이 아니라 단순 '변경 이벤트'만 전달

userChanged.listen((_) {
  print("A user changed");
});

// 새로운 User 추가
final user = User()..name = "David";
await isar.writeTxn(() => isar.users.put(user));
// 결과: "A user changed" 가 출력됨

• watchLazy()를 사용했으므로, 알림에서는 구체적인 User 정보가 아닌 “변경 발생”이라는 사실만 전달됩니다.
• 만약 변경된 객체 목록 등을 가져오려면, 알림을 받는 시점에 isar.users.get(id) 또는 isar.users.where()... 등으로 직접 조회하면 됩니다.

---

5. Watching Queries (특정 쿼리 결과 감시)

“It is even possible to watch entire queries. Isar does its best to only notify you when the query results actually change.”

5.1 기본 쿼리 감시

아래 예시는 isar.users.filter()로 모든 User를 조회하는 쿼리를 감시하고, 쿼리 결과가 바뀌면 새로운 전체 목록을 스트림으로 전달받습니다.

// 모든 User를 조회하는 쿼리
Query<User> userQuery = isar.users.filter();

// initially: true -> Watcher 등록 직후, 현재 쿼리 결과도 즉시 스트림에 전달
Stream<List<User>> usersChangedStream = userQuery.watch(initially: true);

usersChangedStream.listen((users) {
  // 변경된 전체 User 목록이 리스트로 전달됨
  print("User list changed! Current users: $users");
});

// 데이터 추가 예시
await isar.writeTxn(() => isar.users.put(User()..name = "Albert"));
// 출력: "User list changed! Current users: [User(name: Albert)]"

await isar.writeTxn(() => isar.users.put(User()..name = "Bob"));
// 출력: "User list changed! Current users: [User(name: Albert), User(name: Bob)]"

• initially: true: Watcher를 등록하자마자 현재 쿼리 결과를 한 번 내보냅니다.
• 쿼리 결과(예: User 목록)에 변화가 생길 때마다, 새로운 전체 목록이 스트림으로 전달됩니다.

5.2 Lazy Query Watching

“Just like watchObjectLazy, you can watchLazy() to get notified when the query results change but not fetch the results.”

Query<User> userQuery = isar.users.filter();
Stream<void> usersChangedLazy = userQuery.watchLazy(initially: false);

usersChangedLazy.listen((_) {
  print("The user query results changed! (Lazy)");
});

// 이후 트랜잭션에서 User 추가/삭제 시
// "The user query results changed! (Lazy)"가 출력
// 단, 실제 사용자 목록을 자동으로 주지는 않음

• 쿼리 결과가 변경되면 “변경됨” 이벤트만 수신합니다.
• 새로운 리스트는 자동으로 주어지지 않으므로, 필요하다면 userQuery.findAll() 등을 호출해서 직접 데이터를 가져와야 합니다.

---

6. 주의사항 및 요약

1. Watcher 알림 시점
   • 트랜잭션이 커밋된 후, 실제 데이터 변경이 이루어지고 나서 알림이 옵니다.
2. fireImmediately
   • true로 설정 시, Watcher 등록 직후 기존 상태도 한 번 전달받을 수 있습니다.
3. Lazy Watching
   • 변경 사실만 전달하며, 객체나 쿼리의 새로운 결과는 직접 가져와야 합니다.
   • 불필요한 DB I/O를 줄일 수 있으므로 성능 이점이 있을 수 있습니다.
4. 쿼리 Watcher
   • 쿼리 결과가 바뀌는 경우에만 알림을 보내므로, 컬렉션 전체 Watcher보다 더 적은 알림이 발생할 수 있습니다.
   • 단, 링크(Link) 변경 등으로 인해 간접적으로 쿼리 결과가 바뀌는 경우에는 어떻게 동작하는지(해당 쿼리 조건에 따라) 주의 깊게 확인해야 합니다.
5. Offset/Limit/Distinct
   • 쿼리에 offset, limit, distinct 등이 설정되어 있어도, Isar는 가능한 한 실제 결과에 변화가 있을 때만 알림을 발생시키려고 노력합니다.
   • 그래도 정확한 변경 감시가 필요하다면 watchLazy() 대신 컬렉션 Watcher를 쓰는 방법도 고려합니다.

---

결론

• Watchers는 DB 변경을 자동으로 감지하고, 이를 스트림 형태로 전달해주는 강력한 기능입니다.
• 객체, 컬렉션, 쿼리 등 원하는 단위로 감시 가능하며, Lazy 방식을 통해 성능을 최적화할 수도 있습니다.
• Dart 초급자 분들은 watchObject와 watchObjectLazy를 먼저 익혀 보신 뒤, 전체 컬렉션 감시나 쿼리 감시로 확장해보시면 좋습니다.

이상으로 Isar의 Watchers를 활용하는 방법을 살펴보았습니다.
추가 궁금한 점이 있으시면 언제든 질문해 주세요!