@scbt-ecom/ui 0.127.1 → 0.128.0

package/dist/types/lib/shared/utils/variableHolder/variableContextHolder.d.ts

@@ -8,15 +8,57 @@ export interface Variable<Key = string, Value = string> {
 }
 export type VariableEntry<Key = string, Value = string> = [Key, Value];
 export interface IVariableContextHolder<Key, Value> {
+    /**
+     * список переменных, находящихся в имплементации
+     */
     variables: Variable<Key, Value>[];
+    /**
+     * метод для добавления переменной
+     * @param variable
+     */
     append: (variable: Variable<Key, Value>) => void;
+    /**
+     * метод для удаления переменной
+     * @param key
+     */
     remove: (key: Key) => void;
+    /**
+     * метод для проверки наличия переменной по ключу
+     * @param key
+     */
     has: (key: Key) => boolean;
+    /**
+     * метод для замены всех переменных
+     * @param variables
+     */
     replace: (variables: Variable<Key, Value>[]) => void;
+    /**
+     * метод для очистки переменных
+     */
     clear: () => void;
+    /**
+     * метод для обновления переменной, по её идентификатору
+     * @param id
+     * @param variable
+     */
     update: (id: string, variable: Variable<Key, Value>) => void;
+    /**
+     * получение вхождений переменных по ключам
+     * @param keys
+     * @returns {VariableEntry<Key, Value>[]} entries `Array<[Key, Value]>`
+     */
     entriesOf: (...keys: Key[]) => VariableEntry<Key, Value>[];
+    /**
+     * метод для подписки на изменения переменных
+     * @param listener
+     * @returns функция для отписки
+     */
     observe: (listener: (variables: Variable<Key, Value>[]) => void) => () => void;
+    /**
+     * получение переменной по ключу
+     * @param key
+     * @returns `Variable<Key, Value>` если переменная присутствует, `undefined` если переменной не существует
+     */
     get: (key: Key) => Variable<Key, Value> | undefined;
 }
 export interface VariableStore {
@@ -25,7 +67,90 @@ export interface VariableStore {
     clearItems: (...keys: string[]) => void;
 }
 /**
- * Класс для управления переменными
+ * Класс для управления переменными.
+ * Присутствует возможность использования в среде исполнения NodeJS, при этом будет использоваться in-memory хранилище переменных, что может потреблять дополнительную память приложения
+ *
+ * @example Базовое использование
+ * ```ts
+ * // используем статичный метод класса для получения инстанса
+ * const holder = VariableContextHolder.getInstance('VARIABLE_STORE')
+ *
+ * // эмулируем создание переменной
+ * const variable: Variable = {
+ *   _id: Math.random().toString(36).substring(2),
+ *   // ключ должен быть обёрнут в шаблон переменной
+ *   // чтобы это сделать, используем статичный метод
+ *   key: VariableContextHolder.wrap('variable_key'),
+ *   value: 'variable_value',
+ *   createdAt: new Date().toISOString(),
+ *   updatedAt: new Date().toISOString(),
+ *   description: ''
+ * }
+ *
+ * holder.append(variable)
+ *
+ * holder.variables.forEach((v) => {
+ *   // рендерим переменные как в соответствии с требованиями
+ * })
+ * ```
+ *
+ * @example Использование с react
+ * ```tsx
+ * const Component = () => {
+ *   // создадим ref с экземпляром класса (это нужно чтобы не изменять ссылку при ре-рендере)
+ *   const holder = useRef(VariableContextHolder.getInstance('VARIABLE_STORE'))
+ *   // подключаем и подписываемся на мутацию переменных
+ *   const variables = useSyncExternalStore(holder.current.observe, () => holder.current.variables)
+ *
+ *   return (
+ *     <div>
+ *       {variables.map((variable) => (
+ *         // рендерим переменные как в соответствии с требованиями
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Синхронизация с сервером
+ * ```ts
+ * const holder = VariableContextHolder.getInstance('VARIABLE_STORE')
+ *
+ * // загружаем переменные с сервера
+ * fetch('https://backend.url/variables')
+ *   .then((response) => response.json())
+ *   .then((data) => holder.replace(data))
+ * ```
+ *
+ * @example Обход строки для замены переменных на их значения
+ * ```ts
+ * const holder = VariableContextHolder.getInstance('VARIABLE_STORE')
+ *
+ * const transformVariable = (value: string): string => {
+ *   let str = value
+ *   // находим все переменные в строке
+ *   let matches = VariableContextHolder.match(str)
+ *   // получаем вхождения по найденным переменным
+ *   let variables = holder.entriesOf(...(matches ?? []))
+ *
+ *   // выполняем замену переменных до тех пор, пока в строке содержатся переменные
+ *   while (!TypeGuards.isArrayEmpty(variables)) {
+ *     variables.forEach(([key, value]) => {
+ *       // заменяем каждую переменную на её значение
+ *       str = str.replace(key, value)
+ *     })
+ *     // пробуем снова получить переменные в строке,
+ *     // так как переменная может содержать другую переменную
+ *     matches = VariableContextHolder.match(str)
+ *     variables = holder.entriesOf(...(matches ?? []))
+ *   }
+ *
+ *   return str
+ * }
+ *
+ * const stringWithVariables = 'Процентная ставка \${percent}% годовых до \${months} месяцев'
+ * const processedString = transformVariable(stringWithVariables)
+ * ```
  */
 export declare class VariableContextHolder<Key extends string = string, Value = string> implements IVariableContextHolder<Key, Value> {
     private _store;
@@ -37,9 +162,27 @@ export declare class VariableContextHolder<Key extends string = string, Value =
     private static _VARIABLE_PATTERN;
     private static _instance;
     private constructor();
+    /**
+     * метод для извлечения ключа переменной из шаблона
+     * @param variable
+     */
     static unwrap(variable: string): string;
+    /**
+     * метод для оборачивания ключа переменной в шаблон
+     * @param variable
+     */
     static wrap(variable: string): string;
+    /**
+     * метод для поиска переменных в строке
+     * @param pattern
+     * @returns `string[]` если переменные присутствуют в строке, иначе `null`
+     */
     static match(pattern: string): string[] | null;
+    /**
+     * метод для получения синглтон экземпляра класса по ключу хранилища
+     * @param store
+     * @returns экземпляр подключенный к in-memory хранилищу если код выполняется в NodeJS, `localStorage` если в браузере
+     */
     static getInstance(store: string): VariableContextHolder;
     get variables(): Variable<Key, Value>[];
     private collect;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scbt-ecom/ui",
-  "version": "0.127.1",
+  "version": "0.128.0",
   "type": "module",
   "exports": {
     ".": {