@smounters/kit 2.24.0 → 2.26.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.25.0 - 2026-09-11
+
+### Added
+- `kit/text` — подстановка `{{ path.to.value }}` с экранированием ПО ЗНАЧЕНИЮ под получателя
+  (`html`, `url`, `markdownv2`), экранирование для SQL `LIKE` (поиск по «100%» не должен находить
+  всё подряд) и наивный разбор ФИО. Подпуть был в плане пакета с самого начала и закрывает третью
+  переписанную копию этих же функций.
+  Словаря предметной области здесь нет: канал отправки в режим экранирования переводит потребитель.
+
 ## 2.24.0 - 2026-09-11
 
 ### Added

package/README.md

@@ -19,6 +19,7 @@ npm i @smounters/kit @smounters/core
 | `kit/config` | zod-препроцессоры для разбора env | `zod` |
 | `kit/money` | decimal-арифметика, масштабы, округление, проверка сбалансированности проводки | — |
 | `kit/rpc` | `ProtoValidateInterceptor` — правила `buf.validate` из контракта, enforced транспортом | `@smounters/core`, `@connectrpc/connect`, `@bufbuild/*` |
+| `kit/text` | подстановка `{{ }}` с экранированием под получателя, экранирование для SQL `LIKE`, разбор ФИО | — |
 | `kit/util` | `ulid`, `redactSecrets` | — |
 
 ## Что здесь НЕ лежит и почему

package/dist/text/index.d.ts

@@ -0,0 +1,32 @@
+/** Where the rendered value is about to land. Picking the wrong one is an injection, not a typo. */
+export type EscapeMode = "none" | "url" | "html" | "markdownv2" | "plain";
+/**
+ * Escape a value for a SQL `LIKE` pattern: a user searching for "100%" must not match everything.
+ *
+ * The backslash goes first — escaping it after `%`/`_` would double-escape the escapes. Postgres needs
+ * no `ESCAPE` clause with this, since backslash is the default.
+ */
+export declare function escapeLike(value: string): string;
+export declare function escapeHtml(str: string): string;
+/** Telegram MarkdownV2 reserves this whole set; one unescaped character fails the whole send. */
+export declare function escapeMarkdownV2(str: string): string;
+export declare function escapeValue(str: string, mode: EscapeMode): string;
+/** Read `a.b.c` out of a plain object, returning undefined instead of throwing on a missing branch. */
+export declare function resolvePath(context: Record<string, unknown>, path: string): unknown;
+/**
+ * Substitute `{{ path.to.value }}` placeholders, escaping each substituted value for the target.
+ *
+ * Escaping is per-VALUE, never over the finished string: the template itself is authored by us and may
+ * legitimately contain markup, while the values come from data and may contain anything. A missing key
+ * renders as an empty string rather than leaving the placeholder visible to a customer.
+ */
+export declare function renderTemplate(template: string, context: Record<string, unknown>, escape?: boolean | EscapeMode): string;
+/**
+ * Split a full name into first + rest. Deliberately naive: one word is a first name, everything after
+ * the first space is the last name. Anything smarter guesses wrong on the half of the world that writes
+ * the family name first.
+ */
+export declare function splitPersonName(full: string | undefined): {
+    firstName?: string;
+    lastName?: string;
+};

package/dist/text/index.js

@@ -0,0 +1,73 @@
+// Text mechanics that every service rewrites: placeholder substitution with the right escaping for the
+// channel it is going out on, escaping for a SQL LIKE pattern, splitting a person's full name.
+//
+// No product vocabulary lives here — no channel enum, no header names, no field names. The caller says
+// which escape mode it needs; the mapping from its own channel enum to a mode is the caller's policy.
+/**
+ * Escape a value for a SQL `LIKE` pattern: a user searching for "100%" must not match everything.
+ *
+ * The backslash goes first — escaping it after `%`/`_` would double-escape the escapes. Postgres needs
+ * no `ESCAPE` clause with this, since backslash is the default.
+ */
+export function escapeLike(value) {
+    return value.replace(/\\/g, "\\\\").replace(/[%_]/g, "\\$&");
+}
+export function escapeHtml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/** Telegram MarkdownV2 reserves this whole set; one unescaped character fails the whole send. */
+export function escapeMarkdownV2(str) {
+    return str.replace(/[\\_*[\]()~`>#+\-=|{}.!]/g, (m) => `\\${m}`);
+}
+export function escapeValue(str, mode) {
+    switch (mode) {
+        case "url":
+            return encodeURIComponent(str);
+        case "html":
+            return escapeHtml(str);
+        case "markdownv2":
+            return escapeMarkdownV2(str);
+        default:
+            return str;
+    }
+}
+/** Read `a.b.c` out of a plain object, returning undefined instead of throwing on a missing branch. */
+export function resolvePath(context, path) {
+    let cur = context;
+    for (const key of path.split(".")) {
+        if (cur == null || typeof cur !== "object")
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+/**
+ * Substitute `{{ path.to.value }}` placeholders, escaping each substituted value for the target.
+ *
+ * Escaping is per-VALUE, never over the finished string: the template itself is authored by us and may
+ * legitimately contain markup, while the values come from data and may contain anything. A missing key
+ * renders as an empty string rather than leaving the placeholder visible to a customer.
+ */
+export function renderTemplate(template, context, escape = false) {
+    const mode = escape === true ? "url" : escape === false ? "none" : escape;
+    return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_match, path) => {
+        const value = resolvePath(context, path);
+        return escapeValue(value == null ? "" : String(value), mode);
+    });
+}
+/**
+ * Split a full name into first + rest. Deliberately naive: one word is a first name, everything after
+ * the first space is the last name. Anything smarter guesses wrong on the half of the world that writes
+ * the family name first.
+ */
+export function splitPersonName(full) {
+    const words = (full ?? "").trim().split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return {};
+    return { firstName: words[0], lastName: words.slice(1).join(" ") || undefined };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smounters/kit",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "description": "Batteries for Imperium services: structured logging, Redis module with a distributed lock, SSRF-safe fetch, decimal money, request context, env schemas",
   "keywords": [
     "imperium",
@@ -45,6 +45,10 @@
     "./util": {
       "types": "./dist/util/index.d.ts",
       "import": "./dist/util/index.js"
+    },
+    "./text": {
+      "types": "./dist/text/index.d.ts",
+      "import": "./dist/text/index.js"
     }
   },
   "files": [