@xlsft/grammy-reactive 0.7.34

package/dist/utils/isIntrinsicElement.d.ts

@@ -0,0 +1,23 @@
+import { type IntrinsicElements } from "~/types/jsx.types";
+/**
+ * Checks whether a string is a valid intrinsic JSX element name.
+ *
+ * This utility acts as a runtime type guard for intrinsic JSX tags
+ * supported by the renderer.
+ *
+ * When the check succeeds, TypeScript narrows `name` to
+ * `keyof IntrinsicElements`, making it safe to use in intrinsic
+ * element factories, render dispatchers, and JSX runtime pipelines.
+ *
+ * @param {string} name - The element name to validate.
+ * @returns {name is keyof IntrinsicElements}
+ * `true` if the name is a supported intrinsic element.
+ *
+ * @example
+ * if (isIntrinsicElement(tag)) {
+ *     // tag is narrowed to keyof IntrinsicElements
+ *     createIntrinsicElement({ tag, props });
+ * }
+ */
+export declare function isIntrinsicElement(name: string): name is keyof IntrinsicElements;
+//# sourceMappingURL=isIntrinsicElement.d.ts.map

package/dist/utils/isIntrinsicElement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isIntrinsicElement.d.ts","sourceRoot":"","sources":["../../src/utils/isIntrinsicElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,MAAM,iBAAiB,CAEhF"}

package/dist/utils/isIntrinsicElement.js

@@ -0,0 +1,25 @@
+import { intrinsicElements } from "~/types/jsx.types";
+/**
+ * Checks whether a string is a valid intrinsic JSX element name.
+ *
+ * This utility acts as a runtime type guard for intrinsic JSX tags
+ * supported by the renderer.
+ *
+ * When the check succeeds, TypeScript narrows `name` to
+ * `keyof IntrinsicElements`, making it safe to use in intrinsic
+ * element factories, render dispatchers, and JSX runtime pipelines.
+ *
+ * @param {string} name - The element name to validate.
+ * @returns {name is keyof IntrinsicElements}
+ * `true` if the name is a supported intrinsic element.
+ *
+ * @example
+ * if (isIntrinsicElement(tag)) {
+ *     // tag is narrowed to keyof IntrinsicElements
+ *     createIntrinsicElement({ tag, props });
+ * }
+ */
+export function isIntrinsicElement(name) {
+    return name in intrinsicElements;
+}
+//# sourceMappingURL=isIntrinsicElement.js.map

package/dist/utils/isIntrinsicElement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isIntrinsicElement.js","sourceRoot":"","sources":["../../src/utils/isIntrinsicElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA0B,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC3C,OAAO,IAAI,IAAI,iBAAiB,CAAC;AACrC,CAAC"}

package/dist/utils/isMessageNotFount.d.ts

@@ -0,0 +1,2 @@
+export declare function isMessageNotFound(error: unknown): boolean;
+//# sourceMappingURL=isMessageNotFount.d.ts.map

package/dist/utils/isMessageNotFount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isMessageNotFount.d.ts","sourceRoot":"","sources":["../../src/utils/isMessageNotFount.ts"],"names":[],"mappings":"AAEA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQzD"}

package/dist/utils/isUnixTime.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Checks whether a numeric value is a valid Unix timestamp.
+ *
+ * Supports both:
+ * - Unix time in **seconds**
+ * - Unix time in **milliseconds**
+ *
+ * Millisecond timestamps are automatically normalized to seconds
+ * before range validation.
+ *
+ * @remarks
+ * The accepted range is:
+ * - minimum: Unix epoch (`0`)
+ * - maximum: year `3000-01-01T00:00:00Z`
+ *
+ * @param {number} time - The timestamp value to validate.
+ * @returns {boolean} `true` if the value is a finite valid Unix timestamp.
+ *
+ * @example
+ * isUnixTime(1712745600); // true
+ *
+ * @example
+ * isUnixTime(1712745600000); // true
+ *
+ * @example
+ * isUnixTime(NaN); // false
+ *
+ * @example
+ * isUnixTime(-1); // false
+ */
+export declare function isUnixTime(time: number): boolean;
+//# sourceMappingURL=isUnixTime.d.ts.map

package/dist/utils/isUnixTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isUnixTime.d.ts","sourceRoot":"","sources":["../../src/utils/isUnixTime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKhD"}

package/dist/utils/isUnixTime.js

@@ -0,0 +1,38 @@
+/**
+ * Checks whether a numeric value is a valid Unix timestamp.
+ *
+ * Supports both:
+ * - Unix time in **seconds**
+ * - Unix time in **milliseconds**
+ *
+ * Millisecond timestamps are automatically normalized to seconds
+ * before range validation.
+ *
+ * @remarks
+ * The accepted range is:
+ * - minimum: Unix epoch (`0`)
+ * - maximum: year `3000-01-01T00:00:00Z`
+ *
+ * @param {number} time - The timestamp value to validate.
+ * @returns {boolean} `true` if the value is a finite valid Unix timestamp.
+ *
+ * @example
+ * isUnixTime(1712745600); // true
+ *
+ * @example
+ * isUnixTime(1712745600000); // true
+ *
+ * @example
+ * isUnixTime(NaN); // false
+ *
+ * @example
+ * isUnixTime(-1); // false
+ */
+export function isUnixTime(time) {
+    if (typeof time !== "number" || !Number.isFinite(time))
+        return false;
+    const min = 0, max = 32503680000;
+    const t = time > 1e12 ? Math.floor(time / 1000) : time;
+    return t >= min && t <= max;
+}
+//# sourceMappingURL=isUnixTime.js.map

package/dist/utils/isUnixTime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isUnixTime.js","sourceRoot":"","sources":["../../src/utils/isUnixTime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACnC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,WAAW,CAAC;IACjC,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,CAAC;AAChC,CAAC"}

package/dist/utils/sanitizeHtmlString.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Escapes unsafe characters in a string for safe HTML rendering.
+ *
+ * This utility replaces the core HTML-sensitive characters:
+ * - `&` → `&`
+ * - `<` → `&lt;`
+ * - `>` → `&gt;`
+ *
+ * It is primarily used during the final message serialization phase
+ * to ensure that plain text content cannot break Telegram HTML markup.
+ *
+ * @param {string} unsafe - The raw string to sanitize.
+ * @returns {string} The escaped HTML-safe string.
+ *
+ * @example
+ * sanitizeHtmlString("<b>Hello</b>");
+ * // "&lt;b&gt;Hello&lt;/b&gt;"
+ *
+ * @example
+ * sanitizeHtmlString("Tom & Jerry");
+ * // "Tom &amp; Jerry"
+ */
+export declare function sanitizeHtmlString(unsafe: string): string;
+//# sourceMappingURL=sanitizeHtmlString.d.ts.map

package/dist/utils/sanitizeHtmlString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeHtmlString.d.ts","sourceRoot":"","sources":["../../src/utils/sanitizeHtmlString.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzD"}

package/dist/utils/sanitizeHtmlString.js

@@ -0,0 +1,29 @@
+/**
+ * Escapes unsafe characters in a string for safe HTML rendering.
+ *
+ * This utility replaces the core HTML-sensitive characters:
+ * - `&` → `&`
+ * - `<` → `&lt;`
+ * - `>` → `&gt;`
+ *
+ * It is primarily used during the final message serialization phase
+ * to ensure that plain text content cannot break Telegram HTML markup.
+ *
+ * @param {string} unsafe - The raw string to sanitize.
+ * @returns {string} The escaped HTML-safe string.
+ *
+ * @example
+ * sanitizeHtmlString("<b>Hello</b>");
+ * // "&lt;b&gt;Hello&lt;/b&gt;"
+ *
+ * @example
+ * sanitizeHtmlString("Tom & Jerry");
+ * // "Tom &amp; Jerry"
+ */
+export function sanitizeHtmlString(unsafe) {
+    return unsafe
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+//# sourceMappingURL=sanitizeHtmlString.js.map

package/dist/utils/sanitizeHtmlString.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeHtmlString.js","sourceRoot":"","sources":["../../src/utils/sanitizeHtmlString.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC7C,OAAO,MAAM;SACR,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC"}

package/dist/utils/withComponentScope.d.ts

@@ -0,0 +1,2 @@
+export declare function withComponentScope<T>(callback: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=withComponentScope.d.ts.map

package/dist/utils/withComponentScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withComponentScope.d.ts","sourceRoot":"","sources":["../../src/utils/withComponentScope.ts"],"names":[],"mappings":"AAEA,wBAAsB,kBAAkB,CAAC,CAAC,EACtC,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAyBZ"}

package/dist/utils/withRuntime.d.ts

@@ -0,0 +1,4 @@
+import type { HookRuntime } from "~/types/hooks.types";
+import type { ReactiveContext } from "~/types/plugin.types";
+export declare function withRuntime<C extends ReactiveContext>(runtime: HookRuntime, callback: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=withRuntime.d.ts.map

package/dist/utils/withRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withRuntime.d.ts","sourceRoot":"","sources":["../../src/utils/withRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,wBAAgB,WAAW,CAAC,CAAC,SAAS,eAAe,EACjD,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,iBAkBhC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+    "type": "module",
+    "name": "@xlsft/grammy-reactive",
+    "description": "React-like stateful library for grammY",
+    "license": "MIT",
+    "version": "0.7.34",
+    "engines": {
+        "node": ">=14.17.0"
+    },
+    "author": "xlsft",
+    "homepage": "https://cv.xlsft.ru/en/projects/grammy-reactive",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/xlsft/grammy-reactive.git"
+    },
+    "bugs": {
+        "url": "https://github.com/xlsft/grammy-reactive/issues"
+    },
+    "module": "true",
+    "main": "./dist/lib/index.js",
+    "types": "./dist/lib/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/lib/index.d.ts",
+            "import": "./dist/lib/index.js"
+        },
+        "./jsx": {
+            "types": "./dist/jsx/index.d.ts",
+            "import": "./dist/jsx/index.js"
+        },
+        "./jsx/jsx-runtime": {
+            "types": "./dist/jsx/jsx-runtime.d.ts",
+            "import": "./dist/jsx/jsx-runtime.js"
+        },
+        "./jsx/jsx-dev-runtime": {
+            "types": "./dist/jsx/jsx-dev-runtime.d.ts",
+            "import": "./dist/jsx/jsx-dev-runtime.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "dev": "bun run --watch examples/main.tsx",
+        "build": "tsc -p tsconfig.build.json",
+        "publish": "npm publish --access public"
+    },
+    "devDependencies": {
+        "@types/node": "^25.6.0",
+        "typescript": "^5"
+    },
+    "peerDependencies": {
+        "grammy": ">=1.0.0 <2"
+    },
+    "keywords": [
+        "declarative",
+        "library",
+        "jsx",
+        "grammy",
+        "bot"
+    ]
+}

package/readme.md

@@ -0,0 +1,373 @@
+# @xlsft/grammy-reactive
+
+> React-like stateful library for **grammY** with JSX, hooks, lifecycle, effects, and component error boundaries.
+
+---
+
+# ✨ Features
+
+- ⚛️ JSX component system
+- 🪝 React-like hooks API
+- 🔁 Stateful rerendering
+- 🧠 Persistent component-local hook storage
+- 🧹 `useEffect` with cleanup support
+- 💥 Error boundaries for root + nested components
+- ⛔ Abortable rerenders via `AbortController`
+- 🧩 Async component support
+- 📦 Component path–scoped state isolation
+- 🤖 Deep access to `grammY` context via runtime hooks
+
+---
+
+# 🚀 Quick Start
+
+## Installation
+
+```bash
+# Bun
+bun add @xlsft/grammy-reactive
+
+# npm
+npm install @xlsft/grammy-reactive
+
+# pnpm
+pnpm add @xlsft/grammy-reactive
+
+# yarn
+yarn add @xlsft/grammy-reactive
+```
+
+Add JSX runtime to `tsconfig.json`
+
+```json
+{
+    "compilerOptions": {
+        "jsxImportSource": "@xlsft/grammy-reactive/jsx",
+        "jsx": "react-jsx",
+    },
+}
+
+```
+
+---
+
+## Basic Message Component
+
+```tsx
+import { Bot, Context } from "grammy";
+import { defineMessageHandler, useState, reactive, type ReactiveFlavor } from "@xlsft/grammy-reactive";
+
+const bot = new Bot<ReactiveFlavor<Context>>(process.env.TG_TOKEN!);
+bot.use(reactive());
+
+const startHandler = defineMessageHandler(async () => {
+    const [count, setCount] = useState(0);
+
+    return (
+        <>
+            <h>Counter</h>
+            <blockquote>
+                Value: <b>{count}</b>
+            </blockquote>
+            <button onClick={() => setCount(c => c + 1)}>
+                Increment
+            </button>
+        </>
+    );
+});
+
+bot.command("start", startHandler);
+```
+---
+# 📔 Full documentation 
+
+WIP
+
+---
+
+# 🧠 Core Mental Model
+
+Every message handler creates a **persistent message runtime instance**.
+
+This runtime stores:
+
+- current Telegram message state
+- hook values
+- effect queue
+- cleanup callbacks
+- component tree path
+- abort controller
+- grammY context
+
+Each rerender reuses the same runtime.
+
+---
+
+# 🪝 Hooks API
+
+The framework ships with a familiar React-like hooks layer:
+
+- `useState` → local reactive state
+- `useMemo` → memoized computed values
+- `useCallback` → stable callback references
+- `useReducer` → complex state transitions
+- `useEffect` → post-commit side effects + cleanup
+
+...etc
+
+### All hooks are:
+
+- component-path scoped
+- persistent across rerenders
+- safe inside async components
+- automatically restored by render order
+
+---
+
+
+# 🔘 Inline Buttons
+
+Inline buttons are a **first-class reactive UI primitive**.
+
+They behave like component event handlers and automatically participate in the lifecycle runtime.
+
+```tsx
+<button color="primary" onClick={() => setCount(c => c + 1)}>
+    Increment
+</button>
+```
+```tsx
+<button variant="copy" value="Copy this text!">
+    Copy what text?
+</button>
+```
+```tsx
+<button variant="url" url="https://google.com">
+    Go to google
+</button>
+```
+
+
+# 🧩 Stateful Component Example
+
+```tsx
+import {
+    defineMessageHandler,
+    useEffect,
+    useState,
+    useContext,
+} from "~/lib";
+
+export default defineMessageHandler(async () => {
+    const [seconds, setSeconds] = useState(0);
+    const ctx = useContext();
+
+    useEffect(() => {
+        const interval = setInterval(() => {
+            setSeconds(s => s + 1);
+        }, 1000);
+
+        return () => clearInterval(interval);
+    }, []);
+
+    return <b>Running for {seconds}s</b>;
+});
+```
+
+---
+
+# 🔄 Lifecycle Model
+
+The framework uses a **render → commit → effects** lifecycle.
+
+```mermaid
+flowchart TD
+    A[Handler / Event] --> B[Render JSX Tree]
+    B --> C[Commit to Telegram]
+    C --> D[Flush useEffect Queue]
+    D --> E[Wait for User Events]
+    E -->|setState| B
+    E -->|unmount| F[Run Cleanup]
+    F --> G[Delete Message]
+```
+
+---
+
+# 🧠 Hook Storage Architecture
+
+Hooks are stored by **component path key**.
+
+```mermaid
+flowchart LR
+    A[Runtime] --> B[hooks: Map]
+    B --> C[0]
+    B --> D[0.0]
+    B --> E[0.1]
+    C --> F[Parent hooks]
+    D --> G[Child A hooks]
+    E --> H[Child B hooks]
+```
+
+This guarantees:
+
+- sibling isolation
+- nested component stability
+- deterministic hook ordering
+- subtree-safe rerenders
+
+---
+
+# 🧬 State Management Principles
+
+## 1) Component Path Isolation
+Each component subtree owns its own hook array.
+
+This prevents collisions between:
+
+```tsx
+<A />
+<B />
+```
+
+Both may safely use:
+
+```tsx
+useState()
+```
+
+without shared state.
+
+---
+
+## 2) Functional Updates Preferred
+Always prefer:
+
+```tsx
+setCount(prev => prev + 1)
+```
+
+over:
+
+```tsx
+setCount(count + 1)
+```
+
+This avoids stale closures in async effects.
+
+---
+
+## 3) Effects Are Commit-Phase Only
+`useEffect` runs **after successful Telegram message update**.
+
+This guarantees UI consistency.
+
+---
+
+# 💥 Error Boundaries
+
+The framework automatically catches:
+
+- root handler exceptions
+- nested component exceptions
+- rerender errors
+- effect cleanup errors
+- event handler errors
+
+Fallback UI renders `InternalError` safely.
+
+```mermaid
+flowchart TD
+    A[Render Component] --> B{Throws?}
+    B -->|No| C[Continue Render]
+    B -->|Yes| D[Render InternalError]
+    D --> E[Commit Fallback UI]
+```
+
+---
+
+# ⛔ Abort + Rerender Semantics
+
+Every message runtime owns its own `AbortController`.
+
+Before rerender:
+
+1. previous controller is aborted
+2. new controller is created
+3. stale async updates are cancelled
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant R as Runtime
+    participant T as Telegram
+
+    U->>R: setState()
+    R->>R: abort previous controller
+    R->>R: render new tree
+    R->>T: editMessageText()
+    R->>R: flushEffects()
+```
+
+---
+
+# 📐 Best Practices
+
+## ✅ Prefer split effects
+
+```tsx
+useEffect(startInterval, []);
+useEffect(syncReaction, [seconds]);
+```
+
+instead of mixing unrelated side effects.
+
+---
+
+## ✅ Use reducer for flows
+Use `useReducer` for:
+
+- wizards
+- menus
+- calculators
+- async status machines
+- pagination
+
+---
+
+## ✅ Memoize callbacks for child props
+
+```tsx
+const onSave = useCallback(() => save(id), [id]);
+```
+
+---
+
+# 🏗️ Architecture Summary
+
+```mermaid
+flowchart TD
+    A[defineMessageHandler] --> B[createMessageState]
+    B --> C[withRuntime]
+    C --> D[createMessageRender]
+    D --> E[Telegram Commit]
+    E --> F[flushEffects]
+    F --> G[cleanupEffects on unmount]
+```
+
+---
+
+# ❤️ Philosophy
+
+The goal is simple:
+
+> Bring **React-like declarative stateful UI architecture** into Telegram bots without losing grammY power.
+
+This library treats a Telegram message as a **live reactive UI surface**.
+
+State, effects, rerenders, and cleanup behave like a real component runtime.
+
+---
+
+# 📄 License
+
+MIT