@xbibzlibrary/telebibz 0.1.2 → 0.1.4

package/dist-cjs/src/queue/queue.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Scheduler = exports.TaskQueue = void 0;
+exports.parseCronExpression = parseCronExpression;
+exports.nextCronOccurrence = nextCronOccurrence;
+function sleep(delayMs) { return new Promise((resolve) => setTimeout(resolve, delayMs)); }
 class TaskQueue {
     worker;
     options;
@@ -10,77 +13,200 @@ class TaskQueue {
     active = 0;
     sequence = 0;
     draining = false;
+    closed = false;
     constructor(worker, options = {}) {
         this.worker = worker;
         this.options = options;
+        if ((options.concurrency ?? 1) < 1 || !Number.isInteger(options.concurrency ?? 1))
+            throw new RangeError("concurrency must be a positive integer");
+        if ((options.retries ?? 0) < 0 || !Number.isInteger(options.retries ?? 0))
+            throw new RangeError("retries must be a non-negative integer");
+    }
+    add(data, options = {}) {
+        if (this.closed)
+            throw new Error("TaskQueue is closed");
+        const id = options.id ?? `job_${Date.now()}_${this.sequence++}`;
+        if (this.jobs.has(id))
+            throw new Error(`Job already exists: ${id}`);
+        if (options.delayMs !== undefined && options.delayMs < 0)
+            throw new RangeError("delayMs must be non-negative");
+        const job = { id, data, attempts: 0, priority: options.priority ?? 0, runAt: Date.now() + (options.delayMs ?? 0), status: "queued" };
+        this.jobs.set(id, job);
+        this.pending.push(job);
+        this.pending.sort((a, b) => b.priority - a.priority || a.runAt - b.runAt);
+        void this.drain();
+        return { ...job };
     }
-    add(data, options = {}) { const id = options.id ?? `job_${Date.now()}_${this.sequence++}`; if (this.jobs.has(id))
-        throw new Error(`Job already exists: ${id}`); const job = { id, data, attempts: 0, priority: options.priority ?? 0, runAt: Date.now() + (options.delayMs ?? 0), status: "queued" }; this.jobs.set(id, job); this.pending.push(job); this.pending.sort((a, b) => b.priority - a.priority || a.runAt - b.runAt); void this.drain(); return { ...job }; }
     get(id) { const job = this.jobs.get(id); return job ? { ...job } : undefined; }
     cancel(id) { const job = this.jobs.get(id); if (!job || ["completed", "failed", "cancelled"].includes(job.status))
         return false; job.status = "cancelled"; this.controllers.get(id)?.abort(); return true; }
-    async onIdle() { while (this.pending.length || this.active)
-        await new Promise((resolve) => setTimeout(resolve, 10)); }
-    async close() { this.draining = false; for (const id of this.controllers.keys())
-        this.cancel(id); }
-    async drain() { if (this.draining)
-        return; this.draining = true; try {
-        while (this.pending.length && this.active < (this.options.concurrency ?? 1)) {
-            const index = this.pending.findIndex((job) => job.runAt <= Date.now() && job.status === "queued");
-            if (index < 0) {
-                const wait = Math.max(1, Math.min(...this.pending.map((job) => job.runAt - Date.now())));
-                await new Promise((resolve) => setTimeout(resolve, wait));
-                continue;
+    async onIdle() { while (this.pending.some((job) => job.status === "queued") || this.active)
+        await sleep(10); }
+    async close() { this.closed = true; this.draining = false; for (const id of this.controllers.keys())
+        this.cancel(id); for (const job of this.pending)
+        if (job.status === "queued")
+            job.status = "cancelled"; this.pending.length = 0; }
+    async drain() {
+        if (this.draining || this.closed)
+            return;
+        this.draining = true;
+        try {
+            while (!this.closed && this.pending.some((job) => job.status === "queued") && this.active < (this.options.concurrency ?? 1)) {
+                const index = this.pending.findIndex((job) => job.runAt <= Date.now() && job.status === "queued");
+                if (index < 0) {
+                    const next = Math.min(...this.pending.filter((job) => job.status === "queued").map((job) => job.runAt));
+                    await sleep(Math.max(1, next - Date.now()));
+                    continue;
+                }
+                const [job] = this.pending.splice(index, 1);
+                if (!job)
+                    continue;
+                this.active += 1;
+                void this.run(job).finally(() => { this.active -= 1; void this.drain(); });
             }
-            const [job] = this.pending.splice(index, 1);
-            if (!job)
-                continue;
-            this.active += 1;
-            void this.run(job).finally(() => { this.active -= 1; void this.drain(); });
+        }
+        finally {
+            this.draining = false;
         }
     }
-    finally {
-        this.draining = false;
-    } }
-    async run(job) { const maxAttempts = this.options.retries ?? 0; const controller = new AbortController(); this.controllers.set(job.id, controller); try {
-        while (job.attempts <= maxAttempts && job.status !== "cancelled") {
-            job.status = "running";
-            job.attempts += 1;
-            try {
-                await this.worker(job, controller.signal);
-                job.status = "completed";
-                return;
-            }
-            catch (error) {
-                job.error = error;
-                if (job.attempts > maxAttempts) {
-                    job.status = "failed";
+    async run(job) {
+        const maxAttempts = this.options.retries ?? 0;
+        const controller = new AbortController();
+        this.controllers.set(job.id, controller);
+        try {
+            while (job.attempts <= maxAttempts && job.status !== "cancelled") {
+                job.status = "running";
+                job.attempts += 1;
+                try {
+                    await this.worker(job, controller.signal);
+                    job.status = "completed";
                     return;
                 }
-                const delay = Math.min(this.options.maxBackoffMs ?? 30_000, (this.options.backoffMs ?? 250) * 2 ** (job.attempts - 1));
-                await new Promise((resolve) => setTimeout(resolve, delay));
+                catch (error) {
+                    job.error = error;
+                    const wasCancelled = job.status === "cancelled";
+                    if (job.attempts > maxAttempts || wasCancelled) {
+                        job.status = wasCancelled ? "cancelled" : "failed";
+                        await this.options.onError?.(error, { ...job });
+                        return;
+                    }
+                    const delay = Math.min(this.options.maxBackoffMs ?? 30_000, (this.options.backoffMs ?? 250) * 2 ** (job.attempts - 1));
+                    await sleep(delay);
+                }
             }
         }
+        finally {
+            this.controllers.delete(job.id);
+        }
     }
-    finally {
-        this.controllers.delete(job.id);
-    } }
 }
 exports.TaskQueue = TaskQueue;
+function parseCronField(token, min, max, normalize) {
+    if (!token)
+        throw new Error("Cron fields cannot be empty");
+    const values = new Set();
+    for (const part of token.split(",")) {
+        const [rangePart, stepPart] = part.split("/");
+        const step = stepPart === undefined ? 1 : Number(stepPart);
+        if (!Number.isInteger(step) || step < 1)
+            throw new Error(`Invalid cron step: ${part}`);
+        const bounds = rangePart === "*" ? [min, max] : rangePart?.split("-").map(Number);
+        if (!bounds || bounds.length < 1 || bounds.some((value) => !Number.isInteger(value)))
+            throw new Error(`Invalid cron range: ${part}`);
+        const start = bounds[0];
+        const end = (bounds[1] ?? start);
+        if (start < min || end > max || start > end)
+            throw new Error(`Cron value out of range: ${part}`);
+        for (let value = start; value <= end; value += step)
+            values.add(normalize ? normalize(value) : value);
+    }
+    return { min, max, values };
+}
+function parseCronExpression(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5)
+        throw new Error("Cron expression must contain exactly five fields: minute hour day-of-month month day-of-week");
+    return {
+        minute: parseCronField(fields[0], 0, 59),
+        hour: parseCronField(fields[1], 0, 23),
+        dayOfMonth: parseCronField(fields[2], 1, 31),
+        month: parseCronField(fields[3], 1, 12),
+        dayOfWeek: parseCronField(fields[4], 0, 7, (value) => value === 7 ? 0 : value),
+    };
+}
+function nextCronOccurrence(expression, from = new Date()) {
+    const cron = typeof expression === "string" ? parseCronExpression(expression) : expression;
+    const candidate = new Date(from);
+    candidate.setSeconds(0, 0);
+    candidate.setMinutes(candidate.getMinutes() + 1);
+    const maxMinutes = 366 * 24 * 60 * 5;
+    for (let index = 0; index < maxMinutes; index += 1) {
+        const dayOfMonthMatches = cron.dayOfMonth.values.has(candidate.getDate());
+        const dayOfWeekMatches = cron.dayOfWeek.values.has(candidate.getDay());
+        const dayMatches = cron.dayOfMonth.values.size === cron.dayOfMonth.max - cron.dayOfMonth.min + 1
+            || cron.dayOfWeek.values.size === cron.dayOfWeek.max - cron.dayOfWeek.min + 1
+            ? dayOfMonthMatches && dayOfWeekMatches
+            : dayOfMonthMatches || dayOfWeekMatches;
+        if (cron.month.values.has(candidate.getMonth() + 1) && cron.hour.values.has(candidate.getHours()) && cron.minute.values.has(candidate.getMinutes()) && dayMatches)
+            return new Date(candidate);
+        candidate.setMinutes(candidate.getMinutes() + 1);
+    }
+    throw new Error(`Cron expression has no occurrence within five years: ${typeof expression === "string" ? expression : "[parsed]"}`);
+}
 class Scheduler {
+    options;
     timers = new Map();
-    every(id, intervalMs, task) { if (intervalMs <= 0)
-        throw new RangeError("intervalMs must be positive"); this.cancel(id); const timer = setInterval(() => { void task(); }, intervalMs); this.timers.set(id, timer); return { id, cancel: () => this.cancel(id) }; }
-    after(id, delayMs, task) { this.cancel(id); const timer = setTimeout(() => { this.timers.delete(id); void task(); }, delayMs); this.timers.set(id, timer); return { id, cancel: () => this.cancel(id) }; }
-    cron(id, expression, task) { const interval = parseSimpleCronInterval(expression); return this.every(id, interval, task); }
-    cancel(id) { const timer = this.timers.get(id); if (!timer)
-        return false; clearTimeout(timer); clearInterval(timer); this.timers.delete(id); return true; }
+    nextRuns = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    every(id, intervalMs, task) {
+        if (!Number.isFinite(intervalMs) || intervalMs <= 0)
+            throw new RangeError("intervalMs must be positive");
+        this.cancel(id);
+        const timer = setInterval(() => { void this.run(id, task); }, intervalMs);
+        this.timers.set(id, timer);
+        return { id, cancel: () => this.cancel(id) };
+    }
+    after(id, delayMs, task) {
+        if (!Number.isFinite(delayMs) || delayMs < 0)
+            throw new RangeError("delayMs must be non-negative");
+        this.cancel(id);
+        const timer = setTimeout(() => { this.timers.delete(id); void this.run(id, task); }, delayMs);
+        this.timers.set(id, timer);
+        return { id, cancel: () => this.cancel(id) };
+    }
+    cron(id, expression, task) {
+        const parsed = parseCronExpression(expression);
+        this.cancel(id);
+        const scheduleNext = () => {
+            const nextRunAt = nextCronOccurrence(parsed);
+            this.nextRuns.set(id, nextRunAt);
+            const timer = setTimeout(() => {
+                this.timers.delete(id);
+                void this.run(id, task).finally(() => { if (this.nextRuns.has(id))
+                    scheduleNext(); });
+            }, Math.max(1, nextRunAt.getTime() - Date.now()));
+            this.timers.set(id, timer);
+        };
+        scheduleNext();
+        const scheduler = this;
+        return { id, cancel: () => scheduler.cancel(id), get nextRunAt() { return scheduler.nextRuns.get(id); } };
+    }
+    getNextRun(id) { const value = this.nextRuns.get(id); return value ? new Date(value) : undefined; }
+    cancel(id) { const timer = this.timers.get(id); if (!timer) {
+        this.nextRuns.delete(id);
+        return false;
+    } clearTimeout(timer); clearInterval(timer); this.timers.delete(id); this.nextRuns.delete(id); return true; }
     clear() { for (const id of [...this.timers.keys()])
         this.cancel(id); }
+    async run(id, task) {
+        try {
+            await task();
+        }
+        catch (error) {
+            await this.options.onError?.(error, id);
+        }
+    }
 }
 exports.Scheduler = Scheduler;
-function parseSimpleCronInterval(expression) { const minute = expression.trim().split(/\s+/)[0]; if (minute?.startsWith("*/")) {
-    const value = Number(minute.slice(2));
-    if (Number.isInteger(value) && value > 0)
-        return value * 60_000;
-} throw new Error("Only interval cron expressions such as */5 are supported by the built-in scheduler; use an adapter for full cron syntax."); }

package/dist-cjs/src/router/router.js

@@ -2,25 +2,83 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Router = void 0;
 const compose_js_1 = require("../middleware/compose.js");
+function testRegExp(expression, value) {
+    expression.lastIndex = 0;
+    return expression.test(value);
+}
 class Router {
     routes = [];
     sequence = 0;
-    use(...middleware) { this.routes.push({ priority: -1_000_000 + this.sequence++, matcher: () => true, middleware }); return this; }
-    route(matcher, ...middleware) { this.routes.push({ priority: this.sequence++, matcher, middleware }); return this; }
-    command(name, ...middleware) { return this.route(async (ctx) => { const text = ctx.message?.text; if (!text?.startsWith("/"))
-        return false; const command = text.slice(1).split(/[\s@]/, 1)[0] ?? ""; return typeof name === "string" ? command === name.replace(/^\//, "") : name.test(command); }, ...middleware); }
-    text(value, ...middleware) { return this.route((ctx) => ctx.message?.text === value, ...middleware); }
-    regex(expression, ...middleware) { return this.route((ctx) => expression.test(ctx.message?.text ?? ""), ...middleware); }
-    callback(pattern, ...middleware) { return this.route((ctx) => { const data = ctx.callbackQuery?.data ?? ""; return typeof pattern === "string" ? pattern.endsWith("*") ? data.startsWith(pattern.slice(0, -1)) : data === pattern : pattern.test(data); }, ...middleware); }
-    chat(chatId, ...middleware) { return this.route((ctx) => { const id = ctx.message?.chat?.id; return id === chatId || String(id) === String(chatId); }, ...middleware); }
-    predicate(matcher, ...middleware) { return this.route(matcher, ...middleware); }
-    nest(child) { return this.route(() => true, async (ctx, next) => { await child.handle(ctx, next); }); }
-    async handle(ctx, terminal) { const ordered = [...this.routes].sort((left, right) => left.priority - right.priority); let matched = false; for (const route of ordered) {
-        if (!(await route.matcher(ctx)))
-            continue;
-        matched = true;
-        await (0, compose_js_1.compose)(route.middleware)(ctx);
-    } if (!matched)
-        await terminal?.(); }
+    matchMode;
+    constructor(options = {}) {
+        this.matchMode = options.matchMode ?? "first";
+    }
+    use(...middleware) {
+        if (middleware.length === 0)
+            return this;
+        this.routes.push({ priority: -1_000_000 + this.sequence++, matcher: () => true, middleware });
+        return this;
+    }
+    route(matcher, ...middleware) {
+        if (middleware.length === 0)
+            throw new Error("A route requires at least one middleware handler.");
+        this.routes.push({ priority: this.sequence++, matcher, middleware });
+        return this;
+    }
+    command(name, ...middleware) {
+        return this.route(async (ctx) => {
+            const text = ctx.message?.text;
+            if (!text?.startsWith("/"))
+                return false;
+            const command = text.slice(1).split(/[\s@]/, 1)[0] ?? "";
+            return typeof name === "string"
+                ? command === name.replace(/^\//, "")
+                : testRegExp(name, command);
+        }, ...middleware);
+    }
+    text(value, ...middleware) {
+        return this.route((ctx) => ctx.message?.text === value, ...middleware);
+    }
+    regex(expression, ...middleware) {
+        return this.route((ctx) => testRegExp(expression, ctx.message?.text ?? ""), ...middleware);
+    }
+    callback(pattern, ...middleware) {
+        return this.route((ctx) => {
+            const data = ctx.callbackQuery?.data ?? "";
+            return typeof pattern === "string"
+                ? pattern.endsWith("*")
+                    ? data.startsWith(pattern.slice(0, -1))
+                    : data === pattern
+                : testRegExp(pattern, data);
+        }, ...middleware);
+    }
+    chat(chatId, ...middleware) {
+        return this.route((ctx) => {
+            const id = ctx.message?.chat?.id;
+            return id !== undefined && (id === chatId || String(id) === String(chatId));
+        }, ...middleware);
+    }
+    predicate(matcher, ...middleware) {
+        return this.route(matcher, ...middleware);
+    }
+    nest(child) {
+        return this.route(() => true, async (ctx, next) => {
+            await child.handle(ctx, next);
+        });
+    }
+    async handle(ctx, terminal) {
+        const ordered = [...this.routes].sort((left, right) => left.priority - right.priority);
+        let matched = false;
+        for (const route of ordered) {
+            if (!(await route.matcher(ctx)))
+                continue;
+            matched = true;
+            await (0, compose_js_1.compose)(route.middleware)(ctx);
+            if (this.matchMode === "first")
+                break;
+        }
+        if (!matched)
+            await terminal?.();
+    }
 }
 exports.Router = Router;

package/dist-cjs/src/state/conversation.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Wizard = exports.ConversationManager = exports.ConversationFlow = void 0;
+const storage_js_1 = require("../storage/storage.js");
 class ConversationFlow {
     ctx;
     state;
@@ -19,19 +20,86 @@ class ConversationFlow {
 exports.ConversationFlow = ConversationFlow;
 class ConversationManager {
     active = new Map();
-    start(key, name, values = {}) { const state = { name, step: 0, values, status: "active", updatedAt: Date.now() }; this.active.set(key, state); return state; }
+    storage;
+    constructor(storage = new storage_js_1.MemoryStorage()) {
+        this.storage = storage;
+    }
+    start(key, name, values = {}) {
+        const state = { name, step: 0, values, status: "active", updatedAt: Date.now() };
+        this.active.set(key, state);
+        void this.storage.set(key, state);
+        return state;
+    }
     get(key) { return this.active.get(key); }
-    cancel(key) { const state = this.active.get(key); if (!state)
-        return false; state.status = "cancelled"; state.updatedAt = Date.now(); return true; }
-    clearExpired(maxAgeMs) { const threshold = Date.now() - maxAgeMs; let removed = 0; for (const [key, state] of this.active)
-        if (state.updatedAt < threshold) {
-            this.active.delete(key);
-            removed += 1;
-        } return removed; }
-    async run(ctx, key, name, steps) { const state = this.active.get(key) ?? this.start(key, name); const flow = new ConversationFlow(ctx, state); const step = steps[state.step]; if (!step) {
-        state.status = "completed";
+    async getAsync(key) {
+        const cached = this.active.get(key);
+        if (cached)
+            return cached;
+        const stored = await this.storage.get(key);
+        if (stored)
+            this.active.set(key, stored);
+        return stored;
+    }
+    cancel(key) {
+        const state = this.active.get(key);
+        if (!state)
+            return false;
+        state.status = "cancelled";
+        state.updatedAt = Date.now();
+        void this.storage.set(key, state);
+        return true;
+    }
+    async cancelAsync(key) {
+        const state = await this.getAsync(key);
+        if (!state)
+            return false;
+        state.status = "cancelled";
+        state.updatedAt = Date.now();
+        await this.storage.set(key, state);
+        return true;
+    }
+    clearExpired(maxAgeMs) {
+        if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0)
+            throw new RangeError("maxAgeMs must be non-negative");
+        const threshold = Date.now() - maxAgeMs;
+        let removed = 0;
+        for (const [key, state] of this.active)
+            if (state.updatedAt < threshold) {
+                this.active.delete(key);
+                void this.storage.delete(key);
+                removed += 1;
+            }
+        return removed;
+    }
+    async clearExpiredAsync(maxAgeMs) {
+        if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0)
+            throw new RangeError("maxAgeMs must be non-negative");
+        const threshold = Date.now() - maxAgeMs;
+        let removed = 0;
+        for await (const [key, state] of this.storage.entries()) {
+            if (state.updatedAt < threshold) {
+                await this.storage.delete(key);
+                this.active.delete(key);
+                removed += 1;
+            }
+        }
+        return removed;
+    }
+    async run(ctx, key, name, steps) {
+        const state = (await this.getAsync(key)) ?? this.start(key, name);
+        if (state.name !== name)
+            throw new Error(`Conversation ${key} belongs to ${state.name}, not ${name}`);
+        const flow = new ConversationFlow(ctx, state);
+        const step = steps[state.step];
+        if (!step)
+            state.status = "completed";
+        else
+            await step(flow);
+        state.updatedAt = Date.now();
+        await this.storage.set(key, state);
+        this.active.set(key, state);
         return state;
-    } await step(flow); return state; }
+    }
 }
 exports.ConversationManager = ConversationManager;
 class Wizard {

package/dist-cjs/src/state/menu.js

@@ -1,15 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Menu = void 0;
+exports.MenuController = exports.Menu = void 0;
 exports.paginate = paginate;
 exports.paginationButtons = paginationButtons;
 const index_js_1 = require("../keyboard/index.js");
-function paginate(items, page, pageSize) { if (!Number.isInteger(page) || page < 0)
-    throw new RangeError("page must be a non-negative integer"); if (!Number.isInteger(pageSize) || pageSize < 1)
-    throw new RangeError("pageSize must be a positive integer"); const pageCount = Math.max(1, Math.ceil(items.length / pageSize)); const safePage = Math.min(page, pageCount - 1); const start = safePage * pageSize; return { items: items.slice(start, start + pageSize), page: safePage, pageCount, hasPrevious: safePage > 0, hasNext: safePage < pageCount - 1 }; }
-function paginationButtons(page, prefix) { const buttons = []; if (page.hasPrevious)
-    buttons.push({ text: "Previous", callback_data: `${prefix}:page:${page.page - 1}` }); buttons.push({ text: `${page.page + 1}/${page.pageCount}`, callback_data: `${prefix}:noop` }); if (page.hasNext)
-    buttons.push({ text: "Next", callback_data: `${prefix}:page:${page.page + 1}` }); return buttons; }
+function paginate(items, page, pageSize) {
+    if (!Number.isInteger(page) || page < 0)
+        throw new RangeError("page must be a non-negative integer");
+    if (!Number.isInteger(pageSize) || pageSize < 1)
+        throw new RangeError("pageSize must be a positive integer");
+    const pageCount = Math.max(1, Math.ceil(items.length / pageSize));
+    const safePage = Math.min(page, pageCount - 1);
+    const start = safePage * pageSize;
+    return { items: items.slice(start, start + pageSize), page: safePage, pageCount, hasPrevious: safePage > 0, hasNext: safePage < pageCount - 1 };
+}
+function paginationButtons(page, prefix, labels = {}) {
+    const buttons = [];
+    if (page.hasPrevious)
+        buttons.push({ text: labels.previous ?? "Previous", callback_data: `${prefix}:page:${page.page - 1}` });
+    buttons.push({ text: `${page.page + 1}/${page.pageCount}`, callback_data: `${prefix}:noop` });
+    if (page.hasNext)
+        buttons.push({ text: labels.next ?? "Next", callback_data: `${prefix}:page:${page.page + 1}` });
+    return buttons;
+}
 class Menu {
     id;
     itemsList = [];
@@ -17,17 +30,104 @@ class Menu {
     constructor(id) {
         this.id = id;
     }
-    item(item) { this.itemsList.push(item); return this; }
-    breadcrumb(label) { this.parents.push(label); return this; }
-    async build() { const keyboard = new index_js_1.InlineKeyboard(); for (const item of this.itemsList) {
-        const visible = typeof item.visible === "function" ? await item.visible() : item.visible ?? true;
-        if (!visible)
-            continue;
-        if (item.url)
-            keyboard.url(item.label, item.url);
-        else
-            keyboard.text(item.label, item.callbackData ?? `${this.id}:${item.id}`);
-    } return keyboard; }
+    item(item) {
+        if (!item.id || !item.label)
+            throw new Error("Menu item id and label are required.");
+        if (item.url !== undefined && item.callbackData !== undefined)
+            throw new Error("A menu item cannot have both url and callbackData.");
+        this.itemsList.push(item);
+        return this;
+    }
+    breadcrumb(label) { if (label)
+        this.parents.push(label); return this; }
+    get items() { return this.itemsList; }
     get breadcrumbs() { return this.parents; }
+    async visibleItems(context = {}) {
+        const permissions = context.permissions ? new Set(context.permissions) : undefined;
+        const result = [];
+        for (const item of this.itemsList) {
+            const visible = typeof item.visible === "function" ? await item.visible(context, item) : item.visible ?? true;
+            if (!visible)
+                continue;
+            const allowed = typeof item.permission === "function"
+                ? await item.permission(context, item)
+                : item.permission === undefined
+                    ? true
+                    : permissions?.has(item.permission) ?? false;
+            if (allowed)
+                result.push(item);
+        }
+        return result;
+    }
+    async build(context = {}, options = {}) {
+        const columns = options.columns ?? 1;
+        if (!Number.isInteger(columns) || columns < 1)
+            throw new RangeError("columns must be a positive integer");
+        const keyboard = new index_js_1.InlineKeyboard();
+        if (options.includeBreadcrumbs && this.parents.length)
+            keyboard.text(this.parents.join(" / "), `${this.id}:breadcrumb`);
+        const buttons = (await this.visibleItems(context)).map((item) => item.url
+            ? { text: item.label, url: item.url }
+            : { text: item.label, callback_data: item.callbackData ?? `${this.id}:${item.id}` });
+        keyboard.grid(buttons, columns);
+        return keyboard;
+    }
 }
 exports.Menu = Menu;
+class MenuController {
+    currentPage = 0;
+    options;
+    constructor(options) {
+        if (!options.id || !options.id.trim())
+            throw new Error("MenuController id is required.");
+        if (!Number.isInteger(options.pageSize) || options.pageSize < 1)
+            throw new RangeError("pageSize must be a positive integer");
+        this.options = options;
+    }
+    get page() { return this.currentPage; }
+    async allItems() { return typeof this.options.items === "function" ? await this.options.items() : this.options.items; }
+    async render(context = this.options.context ?? {}) {
+        const items = await this.allItems();
+        const page = paginate(items, this.currentPage, this.options.pageSize);
+        this.currentPage = page.page;
+        const keyboard = new index_js_1.InlineKeyboard();
+        for (let index = 0; index < page.items.length; index += 1) {
+            const absoluteIndex = page.page * this.options.pageSize + index;
+            keyboard.text(this.options.label(page.items[index], absoluteIndex), `${this.options.id}:select:${absoluteIndex}`);
+        }
+        const navigation = paginationButtons(page, this.options.id, this.options.labels);
+        if (navigation.length)
+            keyboard.row(...navigation);
+        void context;
+        return keyboard.build();
+    }
+    async handle(data, context = this.options.context ?? {}) {
+        const prefix = `${this.options.id}:`;
+        if (!data.startsWith(prefix))
+            return undefined;
+        const action = data.slice(prefix.length);
+        if (action === "noop" || action === "breadcrumb")
+            return { type: "noop" };
+        if (action.startsWith("page:")) {
+            const page = Number(action.slice("page:".length));
+            if (!Number.isInteger(page) || page < 0)
+                return undefined;
+            this.currentPage = page;
+            const items = await this.allItems();
+            const pageData = paginate(items, this.currentPage, this.options.pageSize);
+            this.currentPage = pageData.page;
+            return { type: "page", page: pageData, keyboard: await this.render(context) };
+        }
+        if (action.startsWith("select:")) {
+            const index = Number(action.slice("select:".length));
+            const items = await this.allItems();
+            const item = items[index];
+            if (item === undefined || !Number.isInteger(index) || index < 0)
+                return undefined;
+            await this.options.callback?.(item, context);
+            return { type: "select", item, index };
+        }
+        return undefined;
+    }
+}
+exports.MenuController = MenuController;