@yaebal/pagination

pnpm add @yaebal/pagination

const users = pagination({
  id: "users",
  pageSize: 10,
  source: {
    // the plugin asks for one page — paginate in the database
    fetch: ({ offset, limit }) => db.user.findMany({ skip: offset, take: limit }),
    count: () => db.user.count(), // optional — makes "page N/M" exact
  },
  line: (u, i) => `${i + 1}. ${u.name}`,
});

const feed = pagination({
  id: "feed",
  source: {
    // no count: the plugin fetches limit + 1 rows — the extra row only
    // answers "is there a next page", it is never rendered
    fetch: ({ offset, limit }) => db.events(offset, limit),
  },
  line: (e) => e.title,
});
// the header shows "page N" until the reader hits the end — then the
// real total is known and it upgrades to "page N/M"

const shop = pagination({
  id: "shop",
  pageSize: 4,
  columns: 2,                                    // item buttons per row
  source: () => products,
  line: (p) => `${p.name} — $${p.price}`,       // optional alongside item
  item: (p) => ({ label: p.name, id: p.id }),    // each item is a button
  onSelect: (ctx, sel) => {
    // sel.id keeps its type: numbers stay numbers, strings stay strings
    // sel.page lets a detail card link back to the exact page
    return showCard(ctx, sel.id, sel.page);
  },
});

const links = pagination({
  id: "docs",
  source: () => articles,
  // a raw InlineKeyboardButton passes through verbatim — url, web_app,
  // or your own callback_data instead of the built-in select
  item: (a) => ({ text: a.title, url: a.href }),
});

import { field } from "@yaebal/callback-data";

const byGenre = pagination({
  id: "genre",
  payload: { genre: field.enum(["fantasy", "sci-fi", "poetry"]) },
  source: {
    fetch: ({ offset, limit, payload }) => db.books(payload.genre, offset, limit),
    count: (ctx, payload) => db.countBooks(payload.genre),
  },
  header: (info) => `${info.payload.genre} — page ${info.page + 1}/${info.pages}`,
  line: (b) => b.title,
});

// the payload rides the buttons, not server state — it survives restarts
bot.command("fantasy", (ctx) =>
  byGenre.send(ctx, { payload: { genre: "fantasy" } }));

const mine = pagination({
  id: "mine",
  payload: { owner: Number },
  source: { fetch: ({ offset, limit, payload }) => myRows(payload.owner, offset, limit) },
  line: (r) => r.title,
  // the decoded payload is passed to filter — ownership rides the buttons
  filter: (ctx, payload) => ctx.from?.id === payload.owner,
  denied: "not your list",
});

bot.command("mine", (ctx) =>
  mine.send(ctx, { payload: { owner: ctx.from!.id } }));

import { bold, format, italic } from "@yaebal/core";

const library = pagination({
  id: "lib",
  source: () => books,
  header: (info) => format`${bold("library")} — ${info.count} books`,
  line: (b) => format`${bold(b.title)} — ${italic(b.author)}`,
  empty: "no books yet",
  labels: { prev: "‹", next: "›" },   // and first/last for ⏮ ⏭
  counter: true,                      // "N/M" button — doubles as refresh
  firstLast: true,                    // ⏮ ⏭ jump buttons
  keyboard: (kb) => kb.row().text("✖ close", "lib:close"),
});

// view(): render without sending — text, entities, markup, items, page info
const v = await users.view(ctx, { page: 2 });
await ctx.sendPhoto(cover, { caption: v.text, reply_markup: v.markup });

// edit(): re-render in place — the current callback message by default,
// or an explicit target
await users.edit(ctx, { page: 0 });
await users.edit(ctx, { page: 0, chatId, messageId });

// button(): a jump-to-page button for any keyboard. pressing it edits
// that message into the list — menus morph into lists in place
new InlineKeyboard()
  .add(byGenre.button("fantasy", { payload: { genre: "fantasy" } }))
  .add(byGenre.button("sci-fi", { payload: { genre: "sci-fi" } }));

import { apiError, createTestEnv } from "@yaebal/test";

const env = createTestEnv(new Composer().install(list.plugin()));
const user = env.createUser();

await user.sendCommand("list");
const bubble = env.lastBotMessage({ withReplyMarkup: true })!;

await user.on(bubble).clickByText("▶");
assert.match(env.lastApiCall("editMessageText")?.params?.text, /page 2/);

// the failure model is testable too
env.onApi("editMessageText", apiError(400, "Bad Request: message is not modified"), { times: 1 });
await user.on(bubble).clickByText("▶"); // swallowed — never reaches onError