@yaebal/filters 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @yaebal/filters
+
+composable, type-narrowing update filters for `composer.filter(...)`. a filter is a type guard that may also attach data to the context; combine them with `and` / `or` / `not`.
+
+## install
+
+```sh
+pnpm add @yaebal/filters
+```
+
+## usage
+
+```ts
+import { and, command, isPrivate, mediaType, or, regex } from "@yaebal/filters";
+
+// command filter: exposes ctx.command and ctx.args
+bot.filter(command("buy"), (ctx) => ctx.reply(`args: ${ctx.args.join(", ")}`));
+
+// regex filter: exposes ctx.match
+bot.filter(regex(/^\d+$/), (ctx) => ctx.reply(`number: ${ctx.match[0]}`));
+
+// combinators
+bot.filter(and(isPrivate, command("secret")), (ctx) => ctx.reply("shhh"));
+
+bot.filter(
+  or(mediaType("photo"), mediaType("video")),
+  (ctx) => ctx.reply("got media"),
+);
+```
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,56 @@
+import type { Context, Filter } from "@yaebal/core";
+/** message has non-empty text. */
+export declare const text: Filter<Context, {
+    text: string;
+}>;
+/** text matches `re`; exposes `ctx.match` (RegExpMatchArray). */
+export declare function regex(re: RegExp): Filter<Context, {
+    match: RegExpMatchArray;
+}>;
+/** a `/command` (optionally a specific name); exposes `ctx.command` and `ctx.args`. */
+export declare function command(name?: string): Filter<Context, {
+    command: string;
+    args: string[];
+}>;
+/** chat is one of the given types (`private`, `group`, `supergroup`, `channel`). */
+export declare function chatType(...types: string[]): Filter<Context>;
+export declare const isPrivate: Filter<Context>;
+export declare const isGroup: Filter<Context>;
+/** update is from one of the given user ids. */
+export declare function fromUser(...ids: number[]): Filter<Context>;
+/** update is in one of the given chat ids. */
+export declare function chatId(...ids: number[]): Filter<Context>;
+/** message carries one of the given media kinds (`photo`, `video`, …). */
+export declare function mediaType(...kinds: string[]): Filter<Context>;
+/** message carries any media. */
+export declare const media: Filter<Context>;
+/** message contains an entity of the given type (`url`, `mention`, `hashtag`, …). */
+export declare function hasEntity(type: string): Filter<Context>;
+/** matches when every filter matches; the additions intersect. */
+export declare function and<A extends object, B extends object>(a: Filter<Context, A>, b: Filter<Context, B>): Filter<Context, A & B>;
+export declare function and<A extends object, B extends object, D extends object>(a: Filter<Context, A>, b: Filter<Context, B>, c: Filter<Context, D>): Filter<Context, A & B & D>;
+export declare function and(...filters: Filter<Context, object>[]): Filter<Context>;
+/** matches when any filter matches. no additions (the matched branch is unknown). */
+export declare function or(...filters: Filter<Context, object>[]): Filter<Context>;
+/** matches when the filter does NOT match. no additions. */
+export declare function not(filter: Filter<Context, object>): Filter<Context>;
+/** everything under one namespace, mtcute-style: `filters.command(...)`, `filters.and(...)`. */
+export declare const filters: {
+    text: Filter<Context, {
+        text: string;
+    }>;
+    regex: typeof regex;
+    command: typeof command;
+    chatType: typeof chatType;
+    isPrivate: Filter<Context, Record<never, never>>;
+    isGroup: Filter<Context, Record<never, never>>;
+    fromUser: typeof fromUser;
+    chatId: typeof chatId;
+    mediaType: typeof mediaType;
+    media: Filter<Context, Record<never, never>>;
+    hasEntity: typeof hasEntity;
+    and: typeof and;
+    or: typeof or;
+    not: typeof not;
+};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAiBpD,kCAAkC;AAClC,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAElD,CAAC;AAEF,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAQ9E;AAED,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAa3F;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAE5D;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,OAAO,CAAuB,CAAC;AAC9D,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,OAAO,CAAmC,CAAC;AAExE,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAE1D;AAED,8CAA8C;AAC9C,wBAAgB,MAAM,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAExD;AAaD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAK7D;AAED,iCAAiC;AACjC,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,OAAO,CAGhC,CAAC;AAEH,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAKvD;AAED,kEAAkE;AAClE,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EACrD,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,EACrB,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,GACnB,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1B,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EACvE,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,EACrB,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,EACrB,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,GACnB,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAE9B,wBAAgB,GAAG,CAAC,GAAG,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;AAW5E,qFAAqF;AACrF,wBAAgB,EAAE,CAAC,GAAG,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAEzE;AAED,4DAA4D;AAC5D,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAQpE;AA0BD,gGAAgG;AAChG,eAAO,MAAM,OAAO;;cAlJuB,MAAM;;;;;;;;;;;;;;;CAiKhD,CAAC"}

package/lib/index.js

@@ -0,0 +1,139 @@
+/**
+ * @yaebal/filters — composable, type-narrowing update filters (the mtcute idea),
+ * for the core `composer.filter(...)` method. a filter is a type guard that may
+ * also attach data to the context (e.g. `regex` exposes `ctx.match`); combine
+ * them with `and` / `or` / `not`.
+ *
+ *   bot.filter(and(isPrivate, command("buy")), (ctx) => ctx.args);
+ *   bot.filter(regex(/^\d+$/), (ctx) => ctx.match[0]);
+ *   bot.filter(or(mediaType("photo"), mediaType("video")), handler);
+ */
+const make = (test) => ({ test: test });
+/** message has non-empty text. */
+export const text = make((ctx) => typeof ctx.text === "string" && ctx.text.length > 0);
+/** text matches `re`; exposes `ctx.match` (RegExpMatchArray). */
+export function regex(re) {
+    return make((ctx) => {
+        const m = ctx.text?.match(re);
+        if (!m)
+            return false;
+        Object.assign(ctx, { match: m });
+        return true;
+    });
+}
+/** a `/command` (optionally a specific name); exposes `ctx.command` and `ctx.args`. */
+export function command(name) {
+    return make((ctx) => {
+        const value = ctx.text;
+        if (!value || !value.startsWith("/"))
+            return false;
+        const parts = value.slice(1).split(/\s+/);
+        const head = parts[0]?.split("@")[0] ?? "";
+        if (name !== undefined && head !== name)
+            return false;
+        Object.assign(ctx, { command: head, args: parts.slice(1) });
+        return true;
+    });
+}
+/** chat is one of the given types (`private`, `group`, `supergroup`, `channel`). */
+export function chatType(...types) {
+    return make((ctx) => types.includes(ctx.chat?.type ?? ""));
+}
+export const isPrivate = chatType("private");
+export const isGroup = chatType("group", "supergroup");
+/** update is from one of the given user ids. */
+export function fromUser(...ids) {
+    return make((ctx) => ctx.from?.id !== undefined && ids.includes(ctx.from.id));
+}
+/** update is in one of the given chat ids. */
+export function chatId(...ids) {
+    return make((ctx) => ctx.chat?.id !== undefined && ids.includes(ctx.chat.id));
+}
+const MEDIA_KINDS = [
+    "photo",
+    "video",
+    "document",
+    "audio",
+    "voice",
+    "sticker",
+    "animation",
+    "video_note",
+];
+/** message carries one of the given media kinds (`photo`, `video`, …). */
+export function mediaType(...kinds) {
+    return make((ctx) => {
+        const msg = ctx.message;
+        return !!msg && kinds.some((k) => msg[k] != null);
+    });
+}
+/** message carries any media. */
+export const media = make((ctx) => {
+    const msg = ctx.message;
+    return !!msg && MEDIA_KINDS.some((k) => msg[k] != null);
+});
+/** message contains an entity of the given type (`url`, `mention`, `hashtag`, …). */
+export function hasEntity(type) {
+    return make((ctx) => {
+        const entities = ctx.message?.entities;
+        return Array.isArray(entities) && entities.some((e) => e.type === type);
+    });
+}
+export function and(...filters) {
+    return make((ctx) => {
+        const before = ownKeys(ctx);
+        if (filters.every((f) => f.test(ctx)))
+            return true;
+        rollback(ctx, before); // a later filter failed → undo earlier filters' attachments
+        return false;
+    });
+}
+/** matches when any filter matches. no additions (the matched branch is unknown). */
+export function or(...filters) {
+    return make((ctx) => filters.some((f) => attempt(f, ctx)));
+}
+/** matches when the filter does NOT match. no additions. */
+export function not(filter) {
+    return make((ctx) => {
+        const before = ownKeys(ctx);
+        const matched = filter.test(ctx);
+        rollback(ctx, before); // the inner filter's attachments are never wanted by `not`
+        return !matched;
+    });
+}
+// data-attaching filters (regex/command/custom) call Object.assign before returning.
+// when a combinator ends up rejecting, undo any fields the sub-filters attached so they
+// don't leak onto the context for downstream middleware.
+const ownKeys = (ctx) => new Set(Object.keys(ctx));
+function rollback(ctx, before) {
+    const bag = ctx;
+    for (const key of Object.keys(bag)) {
+        if (!before.has(key)) {
+            delete bag[key];
+        }
+    }
+}
+function attempt(filter, ctx) {
+    const before = ownKeys(ctx);
+    if (filter.test(ctx))
+        return true;
+    rollback(ctx, before);
+    return false;
+}
+/** everything under one namespace, mtcute-style: `filters.command(...)`, `filters.and(...)`. */
+export const filters = {
+    text,
+    regex,
+    command,
+    chatType,
+    isPrivate,
+    isGroup,
+    fromUser,
+    chatId,
+    mediaType,
+    media,
+    hasEntity,
+    and,
+    or,
+    not,
+};
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { and, command, fromUser, isPrivate, not, or, regex, text } from "./index.js";
+const noop = async () => { };
+const entry = (c) => c.toMiddleware();
+const api = {};
+const msgCtx = (body, chatType = "private", fromId = 1) => new Context({
+    api,
+    update: {
+        update_id: 1,
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: 1, type: chatType },
+            from: { id: fromId, is_bot: false, first_name: "u" },
+            text: body,
+        },
+    },
+    updateType: "message",
+});
+const cbCtx = () => new Context({
+    api,
+    update: {
+        update_id: 2,
+        callback_query: { id: "q", from: { id: 1, is_bot: false, first_name: "u" }, data: "x" },
+    },
+    updateType: "callback_query",
+});
+test("filter(text) runs only on non-empty text", async () => {
+    const seen = [];
+    const mw = entry(new Composer().filter(text, (ctx) => seen.push(ctx.text)));
+    await mw(msgCtx("hi"), noop);
+    await mw(cbCtx(), noop); // no text
+    assert.deepEqual(seen, ["hi"]);
+});
+test("regex matches and exposes ctx.match", async () => {
+    let captured = "";
+    const mw = entry(new Composer().filter(regex(/^buy (\d+)/), (ctx) => {
+        captured = ctx.match[1] ?? "";
+    }));
+    await mw(msgCtx("buy 42"), noop);
+    assert.equal(captured, "42");
+});
+test("command matches a name and exposes ctx.command / ctx.args", async () => {
+    let cmd = "";
+    let args = [];
+    const mw = entry(new Composer().filter(command("add"), (ctx) => {
+        cmd = ctx.command;
+        args = ctx.args;
+    }));
+    await mw(msgCtx("/add a b"), noop);
+    assert.equal(cmd, "add");
+    assert.deepEqual(args, ["a", "b"]);
+});
+test("and requires all; or requires any; not inverts", async () => {
+    let andHits = 0;
+    const andMw = entry(new Composer().filter(and(isPrivate, command("buy")), () => {
+        andHits++;
+    }));
+    await andMw(msgCtx("/buy", "private"), noop); // ✓ private + command
+    await andMw(msgCtx("/buy", "group"), noop); // ✗ not private
+    assert.equal(andHits, 1);
+    let orHits = 0;
+    const orMw = entry(new Composer().filter(or(command("a"), command("b")), () => {
+        orHits++;
+    }));
+    await orMw(msgCtx("/a"), noop);
+    await orMw(msgCtx("/b"), noop);
+    await orMw(msgCtx("/c"), noop);
+    assert.equal(orHits, 2);
+    let notHits = 0;
+    const notMw = entry(new Composer().filter(not(fromUser(99)), () => {
+        notHits++;
+    }));
+    await notMw(msgCtx("hi", "private", 5), noop); // from 5 → allowed
+    await notMw(msgCtx("hi", "private", 99), noop); // from 99 → blocked
+    assert.equal(notHits, 1);
+});
+test("not() and failed and() do not leak attached data downstream", async () => {
+    const seen = [];
+    const probe = (ctx) => {
+        seen.push(ctx.command);
+    };
+    // not(command("a")) on "/a": command matches+attaches, not rejects → branch skipped,
+    // but ctx.command must NOT leak to the downstream use()
+    const notMw = entry(new Composer().filter(not(command("a")), () => { }).use(probe));
+    await notMw(msgCtx("/a"), noop);
+    // and(command("a"), fromUser(999)) on "/a" from user 1: command attaches, fromUser fails →
+    // the whole and rejects and must roll back command/args
+    const andMw = entry(new Composer().filter(and(command("a"), fromUser(999)), () => { }).use(probe));
+    await andMw(msgCtx("/a", "private", 1), noop);
+    assert.deepEqual(seen, [undefined, undefined]); // no leak in either case
+});
+test("scoped derive runs only for the listed update types", async () => {
+    const tags = [];
+    const mw = entry(new Composer()
+        .derive("message", () => ({ tag: 7 }))
+        .use((ctx) => {
+        tags.push(ctx.tag);
+    }));
+    await mw(msgCtx("hi"), noop); // message → derived
+    await mw(cbCtx(), noop); // callback_query → skipped
+    assert.deepEqual(tags, [7, undefined]);
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/filters",
+  "version": "0.0.1",
+  "description": "yaebal filters — composable, type-narrowing update filters (and/or/not) for ctx.filter().",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "filter",
+    "filters"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/filters"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import { and, command, fromUser, isPrivate, not, or, regex, text } from "./index.js";
+
+const noop = async () => {};
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+const api = {} as never;
+
+const msgCtx = (body: string, chatType = "private", fromId = 1) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: 1, type: chatType },
+				from: { id: fromId, is_bot: false, first_name: "u" },
+				text: body,
+			},
+		} as never,
+		updateType: "message",
+	});
+
+const cbCtx = () =>
+	new Context({
+		api,
+		update: {
+			update_id: 2,
+			callback_query: { id: "q", from: { id: 1, is_bot: false, first_name: "u" }, data: "x" },
+		} as never,
+		updateType: "callback_query",
+	});
+
+test("filter(text) runs only on non-empty text", async () => {
+	const seen: string[] = [];
+
+	const mw = entry(new Composer<Context>().filter(text, (ctx) => seen.push(ctx.text)));
+	await mw(msgCtx("hi"), noop);
+	await mw(cbCtx(), noop); // no text
+
+	assert.deepEqual(seen, ["hi"]);
+});
+
+test("regex matches and exposes ctx.match", async () => {
+	let captured = "";
+
+	const mw = entry(
+		new Composer<Context>().filter(regex(/^buy (\d+)/), (ctx) => {
+			captured = ctx.match[1] ?? "";
+		}),
+	);
+	await mw(msgCtx("buy 42"), noop);
+
+	assert.equal(captured, "42");
+});
+
+test("command matches a name and exposes ctx.command / ctx.args", async () => {
+	let cmd = "";
+	let args: string[] = [];
+
+	const mw = entry(
+		new Composer<Context>().filter(command("add"), (ctx) => {
+			cmd = ctx.command;
+			args = ctx.args;
+		}),
+	);
+	await mw(msgCtx("/add a b"), noop);
+
+	assert.equal(cmd, "add");
+	assert.deepEqual(args, ["a", "b"]);
+});
+
+test("and requires all; or requires any; not inverts", async () => {
+	let andHits = 0;
+
+	const andMw = entry(
+		new Composer<Context>().filter(and(isPrivate, command("buy")), () => {
+			andHits++;
+		}),
+	);
+	await andMw(msgCtx("/buy", "private"), noop); // ✓ private + command
+	await andMw(msgCtx("/buy", "group"), noop); // ✗ not private
+
+	assert.equal(andHits, 1);
+
+	let orHits = 0;
+
+	const orMw = entry(
+		new Composer<Context>().filter(or(command("a"), command("b")), () => {
+			orHits++;
+		}),
+	);
+	await orMw(msgCtx("/a"), noop);
+	await orMw(msgCtx("/b"), noop);
+	await orMw(msgCtx("/c"), noop);
+
+	assert.equal(orHits, 2);
+
+	let notHits = 0;
+
+	const notMw = entry(
+		new Composer<Context>().filter(not(fromUser(99)), () => {
+			notHits++;
+		}),
+	);
+	await notMw(msgCtx("hi", "private", 5), noop); // from 5 → allowed
+	await notMw(msgCtx("hi", "private", 99), noop); // from 99 → blocked
+
+	assert.equal(notHits, 1);
+});
+
+test("not() and failed and() do not leak attached data downstream", async () => {
+	const seen: (string | undefined)[] = [];
+	const probe = (ctx: Context) => {
+		seen.push((ctx as Context & { command?: string }).command);
+	};
+
+	// not(command("a")) on "/a": command matches+attaches, not rejects → branch skipped,
+	// but ctx.command must NOT leak to the downstream use()
+	const notMw = entry(new Composer<Context>().filter(not(command("a")), () => {}).use(probe));
+	await notMw(msgCtx("/a"), noop);
+
+	// and(command("a"), fromUser(999)) on "/a" from user 1: command attaches, fromUser fails →
+	// the whole and rejects and must roll back command/args
+	const andMw = entry(
+		new Composer<Context>().filter(and(command("a"), fromUser(999)), () => {}).use(probe),
+	);
+	await andMw(msgCtx("/a", "private", 1), noop);
+
+	assert.deepEqual(seen, [undefined, undefined]); // no leak in either case
+});
+
+test("scoped derive runs only for the listed update types", async () => {
+	const tags: (number | undefined)[] = [];
+
+	const mw = entry(
+		new Composer<Context>()
+			.derive("message", () => ({ tag: 7 }))
+			.use((ctx) => {
+				tags.push((ctx as Context & { tag?: number }).tag);
+			}),
+	);
+	await mw(msgCtx("hi"), noop); // message → derived
+	await mw(cbCtx(), noop); // callback_query → skipped
+	
+	assert.deepEqual(tags, [7, undefined]);
+});

package/src/index.ts

@@ -0,0 +1,180 @@
+import type { Context, Filter } from "@yaebal/core";
+
+/**
+ * @yaebal/filters — composable, type-narrowing update filters (the mtcute idea),
+ * for the core `composer.filter(...)` method. a filter is a type guard that may
+ * also attach data to the context (e.g. `regex` exposes `ctx.match`); combine
+ * them with `and` / `or` / `not`.
+ *
+ *   bot.filter(and(isPrivate, command("buy")), (ctx) => ctx.args);
+ *   bot.filter(regex(/^\d+$/), (ctx) => ctx.match[0]);
+ *   bot.filter(or(mediaType("photo"), mediaType("video")), handler);
+ */
+
+const make = <Add extends object = Record<never, never>>(
+	test: (ctx: Context) => boolean,
+): Filter<Context, Add> => ({ test: test as (ctx: Context) => ctx is Context & Add });
+
+/** message has non-empty text. */
+export const text: Filter<Context, { text: string }> = make(
+	(ctx) => typeof ctx.text === "string" && ctx.text.length > 0,
+);
+
+/** text matches `re`; exposes `ctx.match` (RegExpMatchArray). */
+export function regex(re: RegExp): Filter<Context, { match: RegExpMatchArray }> {
+	return make((ctx) => {
+		const m = ctx.text?.match(re);
+		if (!m) return false;
+
+		Object.assign(ctx as object, { match: m });
+		return true;
+	});
+}
+
+/** a `/command` (optionally a specific name); exposes `ctx.command` and `ctx.args`. */
+export function command(name?: string): Filter<Context, { command: string; args: string[] }> {
+	return make((ctx) => {
+		const value = ctx.text;
+		if (!value || !value.startsWith("/")) return false;
+
+		const parts = value.slice(1).split(/\s+/);
+		const head = parts[0]?.split("@")[0] ?? "";
+
+		if (name !== undefined && head !== name) return false;
+		Object.assign(ctx as object, { command: head, args: parts.slice(1) });
+
+		return true;
+	});
+}
+
+/** chat is one of the given types (`private`, `group`, `supergroup`, `channel`). */
+export function chatType(...types: string[]): Filter<Context> {
+	return make((ctx) => types.includes(ctx.chat?.type ?? ""));
+}
+
+export const isPrivate: Filter<Context> = chatType("private");
+export const isGroup: Filter<Context> = chatType("group", "supergroup");
+
+/** update is from one of the given user ids. */
+export function fromUser(...ids: number[]): Filter<Context> {
+	return make((ctx) => ctx.from?.id !== undefined && ids.includes(ctx.from.id));
+}
+
+/** update is in one of the given chat ids. */
+export function chatId(...ids: number[]): Filter<Context> {
+	return make((ctx) => ctx.chat?.id !== undefined && ids.includes(ctx.chat.id));
+}
+
+const MEDIA_KINDS = [
+	"photo",
+	"video",
+	"document",
+	"audio",
+	"voice",
+	"sticker",
+	"animation",
+	"video_note",
+] as const;
+
+/** message carries one of the given media kinds (`photo`, `video`, …). */
+export function mediaType(...kinds: string[]): Filter<Context> {
+	return make((ctx) => {
+		const msg = ctx.message as Record<string, unknown> | undefined;
+		return !!msg && kinds.some((k) => msg[k] != null);
+	});
+}
+
+/** message carries any media. */
+export const media: Filter<Context> = make((ctx) => {
+	const msg = ctx.message as Record<string, unknown> | undefined;
+	return !!msg && MEDIA_KINDS.some((k) => msg[k] != null);
+});
+
+/** message contains an entity of the given type (`url`, `mention`, `hashtag`, …). */
+export function hasEntity(type: string): Filter<Context> {
+	return make((ctx) => {
+		const entities = (ctx.message as { entities?: { type: string }[] } | undefined)?.entities;
+		return Array.isArray(entities) && entities.some((e) => e.type === type);
+	});
+}
+
+/** matches when every filter matches; the additions intersect. */
+export function and<A extends object, B extends object>(
+	a: Filter<Context, A>,
+	b: Filter<Context, B>,
+): Filter<Context, A & B>;
+
+export function and<A extends object, B extends object, D extends object>(
+	a: Filter<Context, A>,
+	b: Filter<Context, B>,
+	c: Filter<Context, D>,
+): Filter<Context, A & B & D>;
+
+export function and(...filters: Filter<Context, object>[]): Filter<Context>;
+export function and(...filters: Filter<Context, object>[]): Filter<Context> {
+	return make((ctx) => {
+		const before = ownKeys(ctx);
+		if (filters.every((f) => f.test(ctx))) return true;
+
+		rollback(ctx, before); // a later filter failed → undo earlier filters' attachments
+		return false;
+	});
+}
+
+/** matches when any filter matches. no additions (the matched branch is unknown). */
+export function or(...filters: Filter<Context, object>[]): Filter<Context> {
+	return make((ctx) => filters.some((f) => attempt(f, ctx)));
+}
+
+/** matches when the filter does NOT match. no additions. */
+export function not(filter: Filter<Context, object>): Filter<Context> {
+	return make((ctx) => {
+		const before = ownKeys(ctx);
+		const matched = filter.test(ctx);
+
+		rollback(ctx, before); // the inner filter's attachments are never wanted by `not`
+		return !matched;
+	});
+}
+
+// data-attaching filters (regex/command/custom) call Object.assign before returning.
+// when a combinator ends up rejecting, undo any fields the sub-filters attached so they
+// don't leak onto the context for downstream middleware.
+const ownKeys = (ctx: Context): Set<string> => new Set(Object.keys(ctx));
+
+function rollback(ctx: Context, before: Set<string>): void {
+	const bag = ctx as unknown as Record<string, unknown>;
+
+	for (const key of Object.keys(bag)) {
+		if (!before.has(key)) {
+			delete bag[key];
+		}
+	}
+}
+
+function attempt(filter: Filter<Context, object>, ctx: Context): boolean {
+	const before = ownKeys(ctx);
+
+	if (filter.test(ctx)) return true;
+
+	rollback(ctx, before);
+	return false;
+}
+
+/** everything under one namespace, mtcute-style: `filters.command(...)`, `filters.and(...)`. */
+export const filters = {
+	text,
+	regex,
+	command,
+	chatType,
+	isPrivate,
+	isGroup,
+	fromUser,
+	chatId,
+	mediaType,
+	media,
+	hasEntity,
+	and,
+	or,
+	not,
+};