@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/core/template/expr.js

@@ -0,0 +1,108 @@
+// src/core/template/expr.ts
+const PATH_RE = /\.(?![A-Za-z0-9_])|[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)*/y;
+const NAME_RE = /[A-Za-z][A-Za-z0-9_]*/y;
+const NUMBER_RE = /-?\d+(?:\.\d+)?(?![A-Za-z0-9_.])/y;
+const BARE_RE = /[A-Za-z0-9_.+-]+/y;
+function sticky(re, src, at) {
+	re.lastIndex = at;
+	const m = re.exec(src);
+	return m ? m[0] : null;
+}
+/** Parses a path (`a.b.c` or `.`). */
+function parsePath(src) {
+	const s = src.trim();
+	const m = sticky(PATH_RE, s, 0);
+	if (m === null || m.length !== s.length) return null;
+	return m === "." ? [] : m.split(".");
+}
+function parseExpr(src) {
+	let i = 0;
+	const ws = () => {
+		while (i < src.length && /\s/.test(src[i] ?? "")) i++;
+	};
+	ws();
+	const p = sticky(PATH_RE, src, i);
+	if (p === null) return {
+		offset: i,
+		message: "expected a variable name"
+	};
+	const path = p === "." ? [] : p.split(".");
+	i += p.length;
+	const filters = [];
+	const filterOffsets = [];
+	ws();
+	while (i < src.length) {
+		if (src[i] !== "|") return {
+			offset: i,
+			message: `unexpected "${src[i]}"; use | to add a filter`
+		};
+		i++;
+		ws();
+		const name = sticky(NAME_RE, src, i);
+		if (name === null) return {
+			offset: i,
+			message: "expected a filter name after |"
+		};
+		filterOffsets.push(i);
+		i += name.length;
+		ws();
+		const args = [];
+		if (src[i] === ":") {
+			i++;
+			for (;;) {
+				ws();
+				const arg = parseArg(src, i);
+				if ("message" in arg) return arg;
+				args.push(arg.value);
+				i = arg.end;
+				ws();
+				if (src[i] !== ",") break;
+				i++;
+			}
+		}
+		filters.push({
+			name,
+			args
+		});
+	}
+	return {
+		path,
+		filters,
+		filterOffsets
+	};
+}
+function parseArg(src, i) {
+	const q = src[i];
+	if (q === "\"" || q === "'") {
+		let out = "";
+		let j = i + 1;
+		while (j < src.length && src[j] !== q) {
+			if (src[j] === "\\" && j + 1 < src.length) j++;
+			out += src[j];
+			j++;
+		}
+		if (j >= src.length) return {
+			offset: i,
+			message: "unterminated string"
+		};
+		return {
+			value: out,
+			end: j + 1
+		};
+	}
+	const num = sticky(NUMBER_RE, src, i);
+	if (num !== null) return {
+		value: Number(num),
+		end: i + num.length
+	};
+	const bare = sticky(BARE_RE, src, i);
+	if (bare !== null) return {
+		value: bare === "true" ? true : bare === "false" ? false : bare,
+		end: i + bare.length
+	};
+	return {
+		offset: i,
+		message: "expected a filter argument"
+	};
+}
+export { parseExpr, parsePath };

package/dist/core/template/filters.d.ts

@@ -0,0 +1,20 @@
+import { FilterArg } from "./ast.js";
+import { FormatContext } from "./format.js";
+/** Formatting context a filter receives (locale, IANA zone, currency…). */
+export type FilterContext = FormatContext;
+/** A filter: raw value + literal args → raw value. The result is stringified and escaped by the renderer. */
+export type FilterFn = (value: unknown, args: readonly FilterArg[], ctx: FilterContext) => unknown;
+/** A filter with its allowed argument count. */
+export interface FilterDef {
+  /** Maps the value; must not return markup. */
+  apply: FilterFn;
+  /** Allowed argument count (checked by `validateTemplate`). Defaults: 0…∞. */
+  minArgs?: number;
+  maxArgs?: number;
+}
+/** Host filters, by name. A plain function accepts any number of arguments. */
+export type FilterRegistry = Readonly<Record<string, FilterDef | FilterFn>>;
+/** Identity helper that types a {@link FilterDef} for `options.filters`. */
+export declare function defineFilter(def: FilterDef): FilterDef;
+/** Built-in template filters (`money`, `number`, `date`, `truncate`, `yesno`…), by name. Host filters with the same name win. */
+export declare const BUILTIN_FILTERS: Readonly<Record<string, FilterDef>>;

package/dist/core/template/filters.js

@@ -0,0 +1,127 @@
+import { formatDateTime, formatMoney, formatNumber, formatPercent, intlLocale, isDateStyle, toEpoch, toNumber } from "./format.js";
+// src/core/template/filters.ts
+/** Identity helper that types a {@link FilterDef} for `options.filters`. */
+function defineFilter(def) {
+	return def;
+}
+let segmenter;
+function graphemes(s) {
+	segmenter ??= new Intl.Segmenter(void 0, { granularity: "grapheme" });
+	return Array.from(segmenter.segment(s), (x) => x.segment);
+}
+const str = (v) => v === null || v === void 0 ? "" : String(v);
+const intArg = (a) => typeof a === "number" && Number.isInteger(a) && a >= 0 && a <= 20 ? a : void 0;
+const YES_NO = {
+	en: ["Yes", "No"],
+	mr: ["होय", "नाही"]
+};
+function dateFilter(defaults) {
+	return {
+		maxArgs: 1,
+		apply: (v, args, ctx) => {
+			const t = toEpoch(v);
+			if (t === null) return "";
+			const style = args[0];
+			const date = isDateStyle(style) ? style : "medium";
+			const time = isDateStyle(style) ? style : "short";
+			return formatDateTime(t, ctx, {
+				...defaults.date ? { dateStyle: date } : {},
+				...defaults.time ? { timeStyle: time } : {}
+			});
+		}
+	};
+}
+/** Built-in template filters (`money`, `number`, `date`, `truncate`, `yesno`…), by name. Host filters with the same name win. */
+const BUILTIN_FILTERS = {
+	/** Minor units → currency (`money` or `money:"USD"`). */
+	money: {
+		maxArgs: 1,
+		apply: (v, args, ctx) => {
+			const n = toNumber(v);
+			const code = typeof args[0] === "string" ? args[0].toUpperCase() : void 0;
+			return n === null ? "" : formatMoney(n, ctx, code);
+		}
+	},
+	/** `number` (≤ 2 decimals) or `number:0` (fixed decimals). */
+	number: {
+		maxArgs: 1,
+		apply: (v, args, ctx) => {
+			const n = toNumber(v);
+			return n === null ? "" : formatNumber(n, ctx, intArg(args[0]));
+		}
+	},
+	/** Ratio → percent (`0.456 | percent` → 45.6%). */
+	percent: {
+		maxArgs: 1,
+		apply: (v, args, ctx) => {
+			const n = toNumber(v);
+			return n === null ? "" : formatPercent(n, ctx, intArg(args[0]));
+		}
+	},
+	/** Epoch ms → date in the context zone (`date`, `date:"long"`). */
+	date: dateFilter({ date: true }),
+	time: dateFilter({ time: true }),
+	datetime: dateFilter({
+		date: true,
+		time: true
+	}),
+	upper: {
+		maxArgs: 0,
+		apply: (v, _a, ctx) => str(v).toLocaleUpperCase(intlLocale(ctx).split("-u-")[0])
+	},
+	lower: {
+		maxArgs: 0,
+		apply: (v, _a, ctx) => str(v).toLocaleLowerCase(intlLocale(ctx).split("-u-")[0])
+	},
+	/** At most n user-visible characters (grapheme clusters, so Devanagari and emoji stay whole), then `…`. */
+	truncate: {
+		minArgs: 1,
+		maxArgs: 2,
+		apply: (v, args) => {
+			const n = typeof args[0] === "number" && args[0] >= 1 ? Math.floor(args[0]) : 0;
+			const tail = typeof args[1] === "string" ? args[1] : "…";
+			const g = graphemes(str(v));
+			return n > 0 && g.length > n ? g.slice(0, n).join("").trimEnd() + tail : g.join("");
+		}
+	},
+	default: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: (v, args) => v === null || v === void 0 || v === "" || Array.isArray(v) && v.length === 0 ? args[0] ?? "" : v
+	},
+	join: {
+		maxArgs: 1,
+		apply: (v, args) => Array.isArray(v) ? v.map(str).join(typeof args[0] === "string" ? args[0] : ", ") : v
+	},
+	count: {
+		maxArgs: 0,
+		apply: (v) => Array.isArray(v) ? v.length : v && typeof v === "object" ? Object.keys(v).length : typeof v === "string" ? graphemes(v).length : 0
+	},
+	/** Boolean → Yes/No (localized), or `yesno:"Open","Closed"`. */
+	yesno: {
+		maxArgs: 2,
+		apply: (v, args, ctx) => {
+			const [yes, no] = YES_NO[ctx.locale.split("-")[0] ?? ""] ?? YES_NO.en ?? ["Yes", "No"];
+			return v ? str(args[0] ?? yes) : str(args[1] ?? no);
+		}
+	},
+	/** Percent-encodes a value for use inside a URL (`href="https://x/{{key | url}}"`). */
+	url: {
+		maxArgs: 0,
+		apply: (v) => encodeURIComponent(str(v))
+	},
+	/** Epoch ms → Unix seconds (for `<tg-time unix="…">`). */
+	unix: {
+		maxArgs: 0,
+		apply: (v) => {
+			const t = toEpoch(v);
+			return t === null ? "" : Math.floor(t / 1e3);
+		}
+	}
+};
+function resolveFilter(name, registry) {
+	const f = (registry && Object.hasOwn(registry, name) ? registry[name] : void 0) ?? (Object.hasOwn(BUILTIN_FILTERS, name) ? BUILTIN_FILTERS[name] : void 0);
+	if (f === void 0) return void 0;
+	return typeof f === "function" ? { apply: f } : f;
+}
+export { BUILTIN_FILTERS, defineFilter, resolveFilter };

package/dist/core/template/format.d.ts

@@ -0,0 +1,17 @@
+/** Digit shapes: Latin (`0–9`) or Devanagari (`०–९`). */
+export type Numerals = "latn" | "deva";
+/** Locale-aware formatting context (money in minor units, dates in an IANA zone). */
+export interface FormatContext {
+  /** Plugin locale (`en`, `mr`, `pt-BR`). */
+  locale: string;
+  /** IANA zone for dates. */
+  tz: string;
+  /** ISO 4217 code for `money` (default `INR`). */
+  currency?: string | undefined;
+  /** Digits in the currency's minor unit (default 2: paise, cents). */
+  minorDigits?: number | undefined;
+  /** Digit shapes (default `latn`; `deva` gives Devanagari digits ०–९). */
+  numerals?: Numerals | undefined;
+  /** Explicit Intl locale (`en-IN`), overriding the derived one. */
+  intlLocale?: string | undefined;
+}

package/dist/core/template/format.js

@@ -0,0 +1,88 @@
+// src/core/template/format.ts
+const cache = /* @__PURE__ */ new Map();
+/**
+* The Intl locale for a context: `intlLocale`, else `locale` (+ `-IN` when the locale has no region and the
+* currency is INR or the zone is Asia/Kolkata, so `en` groups ₹1,23,456.00), plus the numbering system.
+*/
+function intlLocale(ctx) {
+	const key = `${ctx.intlLocale ?? ""}|${ctx.locale}|${ctx.tz}|${ctx.currency ?? ""}|${ctx.numerals ?? ""}`;
+	const hit = cache.get(key);
+	if (hit) return hit;
+	let base = ctx.intlLocale ?? ctx.locale;
+	if (!ctx.intlLocale && !base.includes("-") && (ctx.currency === "INR" || ctx.tz === "Asia/Kolkata")) base = `${base}-IN`;
+	let out = `${base}-u-nu-${ctx.numerals ?? "latn"}`;
+	try {
+		out = Intl.getCanonicalLocales(out)[0] ?? "en";
+	} catch {
+		out = "en";
+	}
+	cache.set(key, out);
+	return out;
+}
+/** Epoch ms from a number, a numeric string or an ISO string; null when not a date. */
+function toEpoch(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.getTime();
+	if (typeof value === "string" && value.trim()) {
+		const n = /^-?\d+$/.test(value.trim()) ? Number(value) : Date.parse(value);
+		return Number.isFinite(n) ? n : null;
+	}
+	return null;
+}
+function toNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "string" && value.trim() !== "") {
+		const n = Number(value);
+		return Number.isFinite(n) ? n : null;
+	}
+	return null;
+}
+/** Minor units → currency text (`12345600` paise → `₹1,23,456.00` in en-IN). */
+function formatMoney(minor, ctx, currency) {
+	const digits = ctx.minorDigits ?? 2;
+	const code = currency ?? ctx.currency ?? "INR";
+	return new Intl.NumberFormat(intlLocale({
+		...ctx,
+		currency: code
+	}), {
+		style: "currency",
+		currency: code,
+		minimumFractionDigits: digits,
+		maximumFractionDigits: digits
+	}).format(minor / 10 ** digits);
+}
+function formatNumber(n, ctx, digits) {
+	const opts = digits === void 0 ? { maximumFractionDigits: 2 } : {
+		minimumFractionDigits: digits,
+		maximumFractionDigits: digits
+	};
+	return new Intl.NumberFormat(intlLocale(ctx), opts).format(n);
+}
+/** A ratio as percent (`0.456` → `45.6%`). */
+function formatPercent(ratio, ctx, digits) {
+	const opts = digits === void 0 ? { maximumFractionDigits: 1 } : {
+		minimumFractionDigits: digits,
+		maximumFractionDigits: digits
+	};
+	return new Intl.NumberFormat(intlLocale(ctx), {
+		style: "percent",
+		...opts
+	}).format(ratio);
+}
+const DATE_STYLES = [
+	"short",
+	"medium",
+	"long",
+	"full"
+];
+function isDateStyle(v) {
+	return typeof v === "string" && DATE_STYLES.includes(v);
+}
+function formatDateTime(epoch, ctx, parts) {
+	return new Intl.DateTimeFormat(intlLocale(ctx), {
+		...parts,
+		timeZone: ctx.tz
+	}).format(epoch);
+}
+export { DATE_STYLES, formatDateTime, formatMoney, formatNumber, formatPercent, intlLocale, isDateStyle, toEpoch, toNumber };

package/dist/core/template/index.d.ts

@@ -0,0 +1,20 @@
+import { Attr, AttrPart, CoreTemplateError, ElementNode, FilterArg, FilterCall, Node, Pos, SectionNode, TemplateAst, TemplateErrorCode, TextNode, VarNode } from "./ast.js";
+import { FormatContext, Numerals } from "./format.js";
+import { BUILTIN_FILTERS, FilterContext, FilterDef, FilterFn, FilterRegistry, defineFilter } from "./filters.js";
+import { ValidateOptions, validateTemplate } from "./validate.js";
+import { ParseResult, parseTemplate } from "./parse.js";
+import { RenderContext, RenderResult, renderTemplate } from "./render.js";
+import { Shape, ShapeVariable, shapeVariables, zodToShape } from "./shape.js";
+import { VariableRef, listVariables } from "./variables.js";
+/** Result of {@link compileTemplate}. */
+export type CompileResult = {
+  ok: true;
+  ast: TemplateAst;
+} | {
+  ok: false;
+  ast: TemplateAst;
+  errors: CoreTemplateError[];
+};
+/** Parse + validate in one step (syntax errors first; variable checks only when the syntax is valid). */
+export declare function compileTemplate(source: string, opts?: ValidateOptions): CompileResult;
+export { Attr, AttrPart, BUILTIN_FILTERS, CoreTemplateError, ElementNode, FilterArg, FilterCall, FilterContext, FilterDef, FilterFn, FilterRegistry, FormatContext, Node, Numerals, ParseResult, Pos, RenderContext, RenderResult, SectionNode, Shape, ShapeVariable, TemplateAst, TemplateErrorCode, TextNode, ValidateOptions, VarNode, VariableRef, defineFilter, listVariables, parseTemplate, renderTemplate, shapeVariables, validateTemplate, zodToShape };

package/dist/core/template/index.js

@@ -0,0 +1,29 @@
+import { pathText } from "./ast.js";
+import { ALLOWED_TAGS, SAFE_URL_RE, checkAttrs, isAllowedTag, literalValue, renderedAttrOk } from "./tags.js";
+import { parseTemplate } from "./parse.js";
+import { DATE_STYLES, formatDateTime, formatMoney, formatNumber, formatPercent, intlLocale, isDateStyle, toEpoch, toNumber } from "./format.js";
+import { BUILTIN_FILTERS, defineFilter, resolveFilter } from "./filters.js";
+import { shapeVariables, zodToShape } from "./shape.js";
+import { validateTemplate } from "./validate.js";
+import { isFalsy, renderTemplate } from "./render.js";
+import { listVariables } from "./variables.js";
+// src/core/template/index.ts
+/** Parse + validate in one step (syntax errors first; variable checks only when the syntax is valid). */
+function compileTemplate(source, opts = {}) {
+	const { ast, errors } = parseTemplate(source);
+	if (errors.length > 0) return {
+		ok: false,
+		ast,
+		errors
+	};
+	const issues = validateTemplate(ast, opts);
+	return issues.length > 0 ? {
+		ok: false,
+		ast,
+		errors: issues
+	} : {
+		ok: true,
+		ast
+	};
+}
+export { ALLOWED_TAGS, BUILTIN_FILTERS, DATE_STYLES, SAFE_URL_RE, checkAttrs, compileTemplate, defineFilter, formatDateTime, formatMoney, formatNumber, formatPercent, intlLocale, isAllowedTag, isDateStyle, isFalsy, listVariables, literalValue, parseTemplate, pathText, renderTemplate, renderedAttrOk, resolveFilter, shapeVariables, toEpoch, toNumber, validateTemplate, zodToShape };

package/dist/core/template/parse.d.ts

@@ -0,0 +1,8 @@
+import { CoreTemplateError, TemplateAst } from "./ast.js";
+/** Result of {@link parseTemplate}: the tree (best effort) plus syntax errors. */
+export interface ParseResult {
+  ast: TemplateAst;
+  errors: CoreTemplateError[];
+}
+/** Parses a template (`{{…}}` tags inside the allowed Telegram HTML) into an AST. Never throws; errors carry 1-based positions. */
+export declare function parseTemplate(src: string): ParseResult;