grammy-match-query 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2023 grammyjs
+
+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,105 @@
+# Match Query Plugin for grammY
+
+A [grammY](https://grammy.dev/) plugin that interprets
+[filter queries](https://grammy.dev/guide/filter-queries) at runtime, with
+support for any property combination — including queries that grammY's static
+type system would reject.
+
+## Features
+
+- **Full query syntax** — supports L1, L2, and L3 filter queries just like
+  grammY's built-in `bot.on()`.
+- **L1 shortcuts** — `""` and `msg` expand to `message` + `channel_post`;
+  `edit` expands to `edited_message` + `edited_channel_post`.
+- **L2 shortcuts** — `""` expands to `entities` + `caption_entities`; `media`
+  expands to `photo` + `video`; `file` expands to all file types.
+- **Unrestricted queries** — no static validation, so any property path works
+  at runtime (e.g. `:media_group_id`).
+- **Multiple queries** — pass an array of queries for OR logic.
+- **Compatible** — returns a predicate for `bot.filter()`.
+
+## Installation
+
+### Node.js
+
+```bash
+npm install github:PonomareVlad/grammy-match-query
+```
+
+### Deno
+
+```typescript
+import { matchQuery } from "https://raw.githubusercontent.com/PonomareVlad/grammy-match-query/main/src/mod.ts";
+```
+
+## Usage
+
+```typescript
+import { Bot } from "grammy";
+import { matchQuery } from "grammy-match-query";
+
+const bot = new Bot("<your-bot-token>");
+
+// Filter by an unsupported query — messages with media_group_id
+bot.filter(matchQuery(":media_group_id"), (ctx) => {
+    console.log("Media group received");
+});
+
+// Restrict to photo/video only (L3 checks L1 object for the property)
+bot.filter(matchQuery(":media:media_group_id"), (ctx) => {
+    console.log("Photo/video media group");
+});
+
+// Standard queries work too
+bot.filter(matchQuery("message:entities:url"), (ctx) => {
+    console.log("Message with URL entity");
+});
+
+// Multiple queries (OR logic)
+bot.filter(matchQuery([":photo", ":video"]), (ctx) => {
+    console.log("Photo or video");
+});
+
+// L1 shortcuts
+bot.filter(matchQuery("edit:text"), (ctx) => {
+    console.log("Edited text message or channel post");
+});
+
+// L2 shortcuts
+bot.filter(matchQuery("message:file"), (ctx) => {
+    console.log("Message with any file type");
+});
+
+bot.start();
+```
+
+## Query Syntax
+
+Queries use the same colon-separated format as grammY's
+[filter queries](https://grammy.dev/guide/filter-queries):
+
+| Query                   | Description                         |
+| ----------------------- | ----------------------------------- |
+| `message`               | Any message update                  |
+| `message:photo`         | Message with a photo                |
+| `message:entities:url`  | Message with a URL entity           |
+| `:photo`                | Photo in message or channel post    |
+| `msg:photo`             | Same as above                       |
+| `edit:text`             | Edited text message or channel post |
+| `message:media`         | Message with photo or video         |
+| `message:file`          | Message with any file type          |
+| `message::url`          | URL in entities or caption_entities |
+| `:media_group_id`       | Any message with media_group_id     |
+| `:media:media_group_id` | Photo/video with media_group_id     |
+
+## How It Works
+
+1. **Parse** — the query string is split by `:` into up to three levels.
+2. **Expand** — L1 and L2 shortcuts are expanded into all concrete paths.
+3. **Compile** — each path becomes a predicate checking property existence on
+   the update object. L3 checks both property names and `type` fields.
+4. **Compose** — multiple predicates are combined with OR logic.
+
+The key difference from grammY's built-in `matchFilter` is that this plugin
+does not validate queries against a static set of known keys, allowing any
+property path to be checked at runtime.

package/out/deps.node.d.ts

@@ -0,0 +1 @@
+export { Api, Composer, Context } from "grammy";

package/out/deps.node.js

@@ -0,0 +1 @@
+export { Api, Composer, Context } from "grammy";

package/out/mod.d.ts

@@ -0,0 +1,53 @@
+/**
+ * grammY Match Query Plugin
+ *
+ * Interprets filter queries like grammY does, but supports any possible
+ * combinations via runtime property checking — including queries that
+ * grammY's static type system would reject.
+ *
+ * @example
+ * ```ts
+ * import { matchQuery } from 'grammy-match-query'
+ * bot.filter(matchQuery(':media_group_id'), ctx => {
+ *   console.log('Media group')
+ * })
+ * ```
+ */
+import { Context } from "./deps.node.js";
+/**
+ * Create a runtime filter predicate from a grammY-style filter query string.
+ *
+ * Unlike grammY's built-in `matchFilter`, this function does not validate
+ * queries against a static set of known keys. Instead, it interprets the
+ * query at runtime, checking if the specified properties exist on the
+ * update object. This allows using any property path, including ones
+ * that grammY's type system would reject (e.g. `:media_group_id`).
+ *
+ * Supports:
+ * - L1, L2, and L3 queries (e.g. `message`, `message:photo`, `message:entities:url`)
+ * - L1 shortcuts: `""` and `msg` expand to `message` + `channel_post`;
+ *   `edit` expands to `edited_message` + `edited_channel_post`
+ * - L2 shortcuts: `""` expands to `entities` + `caption_entities`;
+ *   `media` expands to `photo` + `video`;
+ *   `file` expands to `photo`, `animation`, `audio`, `document`, `video`, `video_note`, `voice`, `sticker`
+ * - Multiple queries separated by logical OR (pass array or use multiple calls)
+ *
+ * @param query A filter query string or array of filter query strings
+ * @returns A predicate function compatible with `bot.filter()`
+ *
+ * @example
+ * ```ts
+ * import { matchQuery } from 'grammy-match-query'
+ *
+ * // Single query — any message/channel_post with media_group_id
+ * bot.filter(matchQuery(':media_group_id'), ctx => {
+ *   console.log('Media group')
+ * })
+ *
+ * // Multiple queries (OR logic)
+ * bot.filter(matchQuery([':photo', ':video']), ctx => {
+ *   console.log('Photo or video')
+ * })
+ * ```
+ */
+export declare function matchQuery(query: string | string[]): (ctx: Context) => boolean;

package/out/mod.js

@@ -0,0 +1,167 @@
+/**
+ * grammY Match Query Plugin
+ *
+ * Interprets filter queries like grammY does, but supports any possible
+ * combinations via runtime property checking — including queries that
+ * grammY's static type system would reject.
+ *
+ * @example
+ * ```ts
+ * import { matchQuery } from 'grammy-match-query'
+ * bot.filter(matchQuery(':media_group_id'), ctx => {
+ *   console.log('Media group')
+ * })
+ * ```
+ */
+// L1 shortcuts: map shortcut names to L1 update types
+const L1_SHORTCUTS = {
+    "": ["message", "channel_post"],
+    msg: ["message", "channel_post"],
+    edit: ["edited_message", "edited_channel_post"],
+};
+// L2 shortcuts: map shortcut names to L2 message properties
+const L2_SHORTCUTS = {
+    "": ["entities", "caption_entities"],
+    media: ["photo", "video"],
+    file: [
+        "photo",
+        "animation",
+        "audio",
+        "document",
+        "video",
+        "video_note",
+        "voice",
+        "sticker",
+    ],
+};
+/**
+ * Parse a filter query string into its component parts.
+ */
+function parse(query) {
+    return query.split(":");
+}
+/**
+ * Expand shortcuts in a parsed query to produce all concrete query paths.
+ */
+function expand(parts) {
+    const [l1, l2, l3] = parts;
+    // Do not expand if all parts are empty/undefined
+    if (!l1 && !l2 && !l3)
+        return [parts];
+    // Expand L1 shortcuts
+    let expanded;
+    if (l1 in L1_SHORTCUTS) {
+        const targets = L1_SHORTCUTS[l1];
+        expanded = targets.map((s) => [s, l2, l3]);
+    }
+    else {
+        expanded = [[l1, l2, l3]];
+    }
+    // Expand L2 shortcuts
+    expanded = expanded.flatMap((q) => {
+        const [ql1, ql2, ql3] = q;
+        if (ql2 !== undefined && ql2 in L2_SHORTCUTS) {
+            const targets = L2_SHORTCUTS[ql2];
+            return targets.map((s) => [ql1, s, ql3]);
+        }
+        return [q];
+    });
+    return expanded;
+}
+/**
+ * Test a value that may be an array or a single item.
+ */
+function testMaybeArray(t, pred) {
+    const p = (x) => x != null && pred(x);
+    return Array.isArray(t) ? t.some(p) : p(t);
+}
+/**
+ * Build a predicate function for a single expanded query path.
+ */
+function buildPredicate(parts) {
+    const [l1, l2, l3] = parts;
+    if (l1 === undefined || l1 === "") {
+        throw new Error("Empty filter query given");
+    }
+    return (update) => {
+        // Check L1: the update type property must exist
+        const l1Value = update[l1];
+        if (l1Value == null)
+            return false;
+        // L1-only query: just check existence
+        if (l2 === undefined)
+            return true;
+        // Check L2: the L2 property must exist on the L1 object
+        const l1Obj = l1Value;
+        const l2Value = l1Obj[l2];
+        if (l2Value == null)
+            return false;
+        // L2-only query: just check existence
+        if (l3 === undefined)
+            return true;
+        // Check L3: first check within the L2 value (may be array),
+        // then fall back to checking the L1 object for the L3 property.
+        // Standard queries like message:entities:url check type="url" on
+        // each entity object in the entities array. Runtime-only queries
+        // like :media:media_group_id expand media to photo/video at L2,
+        // but media_group_id exists on the message (L1), not inside the
+        // photo/video sub-object — the L1 fallback handles this case.
+        const l2Match = testMaybeArray(l2Value, (item) => (item[l3] !== undefined && item[l3] !== null) ||
+            item.type === l3);
+        if (l2Match)
+            return true;
+        // Fall back: check L3 property on the L1 object
+        const l3Value = l1Obj[l3];
+        return l3Value !== undefined && l3Value !== null;
+    };
+}
+/**
+ * Compile multiple query paths into a single predicate (OR logic).
+ */
+function compile(paths) {
+    const predicates = paths.map(buildPredicate);
+    return (update) => predicates.some((pred) => pred(update));
+}
+/**
+ * Create a runtime filter predicate from a grammY-style filter query string.
+ *
+ * Unlike grammY's built-in `matchFilter`, this function does not validate
+ * queries against a static set of known keys. Instead, it interprets the
+ * query at runtime, checking if the specified properties exist on the
+ * update object. This allows using any property path, including ones
+ * that grammY's type system would reject (e.g. `:media_group_id`).
+ *
+ * Supports:
+ * - L1, L2, and L3 queries (e.g. `message`, `message:photo`, `message:entities:url`)
+ * - L1 shortcuts: `""` and `msg` expand to `message` + `channel_post`;
+ *   `edit` expands to `edited_message` + `edited_channel_post`
+ * - L2 shortcuts: `""` expands to `entities` + `caption_entities`;
+ *   `media` expands to `photo` + `video`;
+ *   `file` expands to `photo`, `animation`, `audio`, `document`, `video`, `video_note`, `voice`, `sticker`
+ * - Multiple queries separated by logical OR (pass array or use multiple calls)
+ *
+ * @param query A filter query string or array of filter query strings
+ * @returns A predicate function compatible with `bot.filter()`
+ *
+ * @example
+ * ```ts
+ * import { matchQuery } from 'grammy-match-query'
+ *
+ * // Single query — any message/channel_post with media_group_id
+ * bot.filter(matchQuery(':media_group_id'), ctx => {
+ *   console.log('Media group')
+ * })
+ *
+ * // Multiple queries (OR logic)
+ * bot.filter(matchQuery([':photo', ':video']), ctx => {
+ *   console.log('Photo or video')
+ * })
+ * ```
+ */
+export function matchQuery(query) {
+    const queries = Array.isArray(query) ? query : [query];
+    const allPaths = queries.flatMap((q) => expand(parse(q)));
+    const predicate = compile(allPaths);
+    // deno-lint-ignore no-explicit-any
+    return (ctx) => predicate(ctx.update);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "grammy-match-query",
+    "version": "0.0.0",
+    "description": "Match Query Plugin for grammY",
+    "homepage": "https://github.com/PonomareVlad/grammy-match-query",
+    "main": "./out/mod.js",
+    "types": "./out/mod.d.ts",
+    "type": "module",
+    "scripts": {
+        "prepare": "npm run build",
+        "build": "deno2node tsconfig.json"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/PonomareVlad/grammy-match-query.git"
+    },
+    "exports": {
+        ".": {
+            "types": "./out/mod.d.ts",
+            "default": "./out/mod.js"
+        }
+    },
+    "files": [
+        "out/"
+    ],
+    "author": "PonomareVlad",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/PonomareVlad/grammy-match-query/issues"
+    },
+    "peerDependencies": {
+        "grammy": "^1.15.2"
+    },
+    "devDependencies": {
+        "deno2node": "^1.3.0"
+    },
+    "keywords": [
+        "grammY",
+        "Telegram bot framework",
+        "plugin",
+        "match query",
+        "filter query"
+    ]
+}