페이지네이션

Misskey는 커서 기반 페이지네이션을 사용합니다. 목록을 반환하는 API는 페이지네이션 파라미터를 직접 받아 List<T>를 반환합니다. 래퍼 타입은 존재하지 않습니다. 호출자가 파라미터를 전달하고 반환된 목록의 길이를 확인하여 추가 페이지 존재 여부를 판단합니다.

페이지네이션 파라미터

파라미터	타입	설명
`sinceId`	String	이 ID보다 새로운 결과를 반환
`untilId`	String	이 ID보다 오래된 결과를 반환
`sinceDate`	int	이 Unix 타임스탬프(ms)보다 새로운 결과를 반환
`untilDate`	int	이 Unix 타임스탬프(ms)보다 오래된 결과를 반환
`limit`	int	반환할 최대 항목 수 (일반적으로 1–100)
`offset`	int	지정한 수만큼 건너뜀 (오프셋 기반 API 전용)

모든 API가 모든 파라미터를 지원하는 것은 아닙니다. 각 엔드포인트의 API 레퍼런스를 참조하세요.

커서 기반 페이지네이션 (ID 기준)

오래된 페이지를 불러오려면 untilId를, 새로운 페이지를 불러오려면 sinceId를 사용합니다.

오래된 페이지 불러오기

// 첫 번째 페이지 — 가장 최근 알림
List<MisskeyNotification> page = await client.notifications.list(limit: 20);

// 다음 페이지 — 이전 페이지 마지막 항목보다 오래된 것
while (page.isNotEmpty) {
  final oldestId = page.last.id;
  final next = await client.notifications.list(
    limit: 20,
    untilId: oldestId,
  );
  if (next.isEmpty) break;
  page = next;
}

새로운 페이지 불러오기

// 마지막으로 가져온 최신 ID를 기억해 둠
String? latestId;

Future<List<MisskeyNote>> pollNewNotes() async {
  final notes = await client.notes.timelineHome(
    limit: 20,
    sinceId: latestId,
  );
  if (notes.isNotEmpty) {
    latestId = notes.first.id;
  }
  return notes;
}

타임스탬프 기반 페이지네이션

ID 대신 시간 기준으로 페이지를 나눠야 할 때는 sinceDate와 untilDate를 사용합니다.

final now = DateTime.now().millisecondsSinceEpoch;
final oneDayAgo = now - const Duration(days: 1).inMilliseconds;

final notes = await client.notes.timelineLocal(
  limit: 30,
  sinceDate: oneDayAgo,
  untilDate: now,
);

오프셋 기반 페이지네이션

일부 API는 커서 파라미터 대신 offset을 지원합니다. 커서 탐색을 사용할 수 없는 경우에 활용합니다.

const pageSize = 50;
var offset = 0;

while (true) {
  final users = await client.users.list(
    limit: pageSize,
    offset: offset,
  );
  // users 처리...
  if (users.length < pageSize) break; // 마지막 페이지
  offset += users.length;
}

마지막 페이지 감지

hasNext 플래그는 없습니다. 반환된 항목 수가 limit보다 적으면 마지막 페이지입니다.

const limit = 20;
final page = await client.blocking.list(limit: limit);
final isLastPage = page.length < limit;

모든 페이지 순회

Future<List<MisskeyNote>> fetchAllFavorites() async {
  const limit = 100;
  final all = <MisskeyNote>[];
  String? untilId;

  while (true) {
    final page = await client.account.favorites(
      limit: limit,
      untilId: untilId,
    );
    all.addAll(page);
    if (page.length < limit) break;
    untilId = page.last.id;
  }

  return all;
}

자동 페이지네이션 헬퍼

일부 API는 위의 untilId 반복 처리를 대신 수행하고 지연 Stream을 반환하는 헬퍼를 제공합니다. 현재 드라이브 목록 헬퍼가 이에 해당합니다.

client.drive.files.listAll() — 한 폴더의 파일
client.drive.folders.listAll() — 한 상위 폴더의 폴더
client.drive.streamAll() — 모든 폴더의 파일

await for (final file in client.drive.files.listAll(pageSize: 100)) {
  print(file.name);
}

스트림을 listen할 때만 요청이 시작되며 구독을 취소하면 이후 요청이 중단됩니다. 결과는 항상 ID 최신순입니다. 일찍 끝내려면 maxItems를 사용하세요. 자세한 내용은 드라이브 헬퍼를 참조하세요.