@mirta/store 0.3.5 → 0.4.0

package/dist/index.mjs

@@ -1,57 +1,525 @@
 import '@mirta/polyfills';
+import { hasOwn, deepMerge } from '@mirta/basics/object';
 
-if ((process.env.NODE_ENV === 'test')) {
+/**
+ * Имя текущего пакета в формате, используемом в npm-реестре.
+ *
+ * Используется для логирования, формирования сообщений об ошибках,
+ * а также в диагностических и пользовательских интерфейсах,
+ * чтобы явно указывать источник операций.
+ *
+ * Централизованное определение позволяет избежать жёсткой привязки
+ * к строковому значению в разных частях кода и упрощает поддержку
+ * при возможном переименовании пакета.
+ *
+ * @example
+ * ```ts
+ * console.log(`[${THIS_PACKAGE_NAME}] Запуск сборки...`);
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+const THIS_PACKAGE_NAME = '@mirta/store';
+
+/**
+ * Специализированный класс для обработки ошибок, связанных с работой хранилища Store.
+ *
+ * Предоставляет структурированные и типизированные ошибки с использованием кодов, что упрощает
+ * программную обработку исключений в инструментах, работающих с пакетами.
+ *
+ * @example
+ * ```ts
+ * throw StoreError.get('alreadyDefined', 'mystore')
+ * ```
+ * @since 0.4.0
+ *
+ **/
+class StoreError extends Error {
+    /**
+     * Код ошибки для программной идентификации.
+     *
+     * Позволяет точно определить причину ошибки в обработчиках `try/catch`.
+     *
+     **/
+    code;
+    /**
+     * Приватный конструктор, используемый только внутри
+     * класса для создания экземпляров ошибки.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для идентификации.
+     * @param scope - Пространство имён или модуль, в котором возникла ошибка.
+     *                По умолчанию — {@link THIS_PACKAGE_NAME}.
+     *
+     **/
+    constructor(message, code, scope) {
+        super(`[${scope ?? THIS_PACKAGE_NAME}] ${message}`);
+        this.name = 'StoreError';
+        this.code = code;
+        // Захватываем стек вызовов, исключая фабричный метод `get`,
+        // чтобы улучшить читаемость трассировки.
+        //
+        if ('captureStackTrace' in Error)
+            Error.captureStackTrace(this, scope
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                ? StoreError.getScoped
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                : StoreError.get);
+    }
+    /** Карта кодов ошибок с соответствующими сообщениями. */
+    static codeMappings = {
+        /**
+         * Ошибка, возникающая при попытке повторно определить хранилище.
+         *
+         * @param typeName - Идентификатор типа хранилища.
+         *
+         **/
+        alreadyDefined: (typeName) => `Store type "${typeName}" already defined`,
+        /**
+         * Ошибка, возникающая при попытке повторно определить хранилище,
+         * заданное другим модулем.
+         *
+         * @param typeName - Идентификатор типа хранилища.
+         * @param otherModule - Модуль, в котором тип уже определён.
+         *
+         **/
+        alreadyDefinedOutside: (typeName, otherModule) => `Store type "${typeName}" already defined in "${otherModule}"`,
+        /**
+         * Ошибка, возникающая при попытке присвоить значение неизменяемому полю.
+         * @param propertyName - Название свойства, которому нельзя присваивать значение.
+         *
+         */
+        readonlyProperty: (propertyName) => `Cannot assign to readonly property "${propertyName}"`,
+        /**
+         * Ошибка, возникающая при попытке обращения к несуществующему свойству хранилища.
+         * @param propertyName Имя отсутствующего свойства, вызвавшего ошибку.
+         *
+         **/
+        unknownProperty: (propertyName) => `Unknown property "${propertyName}"`,
+    };
+    /**
+     * Фабричный метод для создания экземпляра ошибки по её коду.
+     *
+     * Автоматически подставляет сообщение из `codeMappings` и формирует ошибку с заданными параметрами.
+     *
+     * @template T - Ограниченный ключами `codeMappings` тип, гарантирующий корректность кода.
+     * @param code - Код ошибки (например, `'alreadyDefined'`).
+     * @param args - Аргументы, соответствующие параметрам функции сообщения из `codeMappings`.
+     * @returns Новый экземпляр {@link StoreError} с шаблонным сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = StoreError.get('alreadyDefined')
+     * ```
+     */
+    static get(code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new StoreError(message, code);
+    }
+    /**
+     * Фабричный метод, аналогичный `get`, но с возможностью указать
+     * пользовательское пространство имён (scope).
+     *
+     * Полезно при использовании в других модулях, где нужно указать
+     * иной контекст ошибки.
+     *
+     * @template TKey - Тип кода ошибки, аналогично `get`.
+     *
+     * @param scope - Пространство имён ошибки (например, `'@mirta/store'`).
+     * @param code - Код ошибки.
+     * @param args - Аргументы для формирования сообщения.
+     *
+     * @returns Новый экземпляр {@link StoreError} с пользовательским
+     *          префиксом и шаблонным сообщением.
+     *
+     * @example
+     *
+     * ```ts
+     * const error = StoreError.getScoped('@mirta/bot-remote', 'alreadyDefined')
+     * ```
+     **/
+    static getScoped(scope, code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new StoreError(message, code, scope);
+    }
+}
+
+/**
+ * Уникальный идентификатор текущей сессии выполнения скрипта.
+ *
+ * Сбрасывается при каждом перезапуске скрипта. Используется для отслеживания,
+ * был ли вызван `defineStore` с определённым именем в рамках одной сессии.
+ *
+ **/
+let sessionId;
+/**
+ * Возвращает уникальный идентификатор сессии.
+ *
+ * При первом вызове генерирует случайную строку на основе `Math.random()`.
+ * Во всех последующих вызовах возвращает уже сгенерированный идентификатор.
+ *
+ * Это позволяет:
+ * - Разрешить повторное определение хранилищ после перезапуска скрипта
+ * - Запретить повторное определение в рамках одной сессии
+ *
+ * @returns Уникальный строковый идентификатор сессии.
+ *
+ * @since 0.4.0
+ *
+ **/
+function getSessionId() {
+    return sessionId ??= Math.random().toString(36).slice(2);
+}
+
+/**
+ * Пытается определить путь к файлу, вызвавшему `defineStore`, через анализ стека вызовов.
+ *
+ * Проходит по строкам стека, ищет вызов `defineStore`, а затем в следующей строке
+ * извлекает путь к файлу, откуда был совершён вызов.
+ *
+ * @returns Путь к файлу, вызвавшему `defineStore`, или `undefined`, если определить не удалось.
+ *
+ * @since 0.4.0
+ *
+ **/
+function tryGetCallerPath() {
+    const errorStack = new Error().stack;
+    if (!errorStack)
+        return;
+    const stackLines = errorStack.split('\n');
+    let foundDefineStore = false;
+    for (const line of stackLines) {
+        // Ищем первую строку, содержащую "defineStore".
+        if (!foundDefineStore && line.includes('defineStore')) {
+            foundDefineStore = true;
+            continue;
+        }
+        // После нахождения defineStore берём следующую строку с вызовом.
+        if (foundDefineStore) {
+            // Извлекаем путь к файлу: ищем шаблон " /путь/к/файлу:строка"
+            //
+            const fileMatch = /\s([^\s]+?):\d+/.exec(line);
+            if (fileMatch)
+                return fileMatch[1];
+        }
+    }
+}
+/**
+ * Получает реестр определений хранилищ из `module.static`.
+ *
+ * Реестр сохраняется между перезапусками скриптов, что позволяет отслеживать
+ * уже определённые типы хранилищ.
+ *
+ * @returns Реестр определений типа {@link DefinitionsRegistry}.
+ *
+ * @since 0.4.0
+ *
+ **/
+function getDefinitionsRegistry() {
+    return (module.static.definitions ??= {});
+}
+/**
+ * Обеспечивает уникальность определения типа хранилища.
+ *
+ * Проверяет, что:
+ * 1. Тип хранилища не определён в другом модуле.
+ * 2. В текущей сессии и файле для этого типа ещё не вызывался `defineStore`.
+ *
+ * Если проверки не проходят — выбрасывается соответствующая ошибка.
+ *
+ * @param typeId - Уникальный идентификатор типа хранилища.
+ * @throws {StoreError} Тип уже определён в другом модуле (`alreadyDefinedOutside`).
+ * @throws {StoreError} Тип уже определён в текущей сессии (`alreadyDefined`).
+ *
+ * @since 0.4.0
+ *
+ **/
+function enforceDefinitionIsUnique(typeId) {
+    const currentCallerPath = tryGetCallerPath();
+    if (!currentCallerPath)
+        return;
+    const registry = getDefinitionsRegistry();
+    // Если указанный тип хранилища ещё не зарегистрирован,
+    // вносим его в реестр.
+    //
+    if (!(typeId in registry))
+        registry[typeId] = {
+            callerPath: currentCallerPath,
+            sessions: {},
+        };
+    const entry = registry[typeId];
+    // Проверка 1: тип не определён в другом модуле.
+    if (currentCallerPath !== entry.callerPath)
+        throw StoreError.get('alreadyDefinedOutside', typeId, entry.callerPath);
+    const sessionId = getSessionId();
+    // Проверка 2: тип не зарегистрирован в текущей сессии.
+    if (entry.sessions[__filename] === sessionId)
+        throw StoreError.get('alreadyDefined', typeId);
+    // Регистрируем вызов в текущей сессии.
+    entry.sessions[__filename] = sessionId;
+}
+/**
+ * Сбрасывает внутреннее состояние реестра определений.
+ *
+ * Используется исключительно в тестах для обеспечения изоляции.
+ *
+ * @internal
+ *
+ * @since 0.4.0
+ *
+ **/
+function __resetInternalState$1() {
+    if (!(process.env.NODE_ENV === 'test'))
+        return;
     module.static = {
-        state: {},
+        definitions: {},
     };
 }
-const stores = {};
-const staticState = (module.static.state ??= {});
+// Инициализация внутреннего состояния при запуске
+// в режиме тестирования.
+//
+if ((process.env.NODE_ENV === 'test'))
+    __resetInternalState$1();
+
 const { assign } = Object;
-function createStore(id, options) {
-    const { state } = options;
-    const initialState = staticState[id];
-    const localState = (initialState ?? (staticState[id] = state ? state() : {}));
-    function $patch(payload) {
-        if (typeof payload === 'function') {
-            payload(staticState[id]);
+/**
+ * Кэш созданных экземпляров хранилищ.
+ *
+ * Обеспечивает повторное использование одного и того же экземпляра хранилища
+ * при многократных вызовах `useStore()`. Ключ — идентификатор хранилища (`storeId`),
+ * значение — сам экземпляр хранилища.
+ *
+ * @internal
+ *
+ **/
+let stores = {};
+// Первичная инициализация для тестов.
+if ((process.env.NODE_ENV === 'test'))
+    __resetInternalState();
+/**
+ * Получает или создаёт статическое состояние хранилища в `module.static`.
+ *
+ * Обеспечивает сохранение состояния между перезапусками скриптов
+ * и межскриптовое взаимодействие через общий контекст `module.static`.
+ *
+ * @param storeId - Уникальный идентификатор хранилища.
+ * @param createState - Функция, возвращающая начальное состояние хранилища.
+ * @returns Актуальное состояние хранилища — либо существующее, либо новое.
+ *
+ * @since 0.4.0
+ *
+ * @internal
+ *
+ **/
+function getStaticState(storeId, createState) {
+    const states = (module.static.states ??= {});
+    return states[storeId] ??= createState();
+}
+/**
+ * Создаёт экземпляр хранилища с заданными параметрами.
+ *
+ * Формирует реактивный объект на основе `Proxy`, объединяющий состояние, геттеры и действия.
+ * Обеспечивает корректную работу `this` внутри `actions` и геттеров.
+ *
+ * @param storeId - Уникальный идентификатор экземпляра хранилища.
+ * @param options - Параметры хранилища: `state`, `getters`, `actions`.
+ * @returns Прокси-объект хранилища с полной функциональностью.
+ *
+ * @template TState - Тип дерева состояния.
+ * @template TGetters - Тип дерева геттеров.
+ * @template TActions - Тип дерева действий.
+ *
+ * @internal
+ *
+ **/
+function createStore(storeId, options) {
+    // Функция для создания начального состояния
+    const createState = () => options.state ? options.state() : {};
+    // 1. Получение или создание общего состояния в module.static
+    const staticState = getStaticState(storeId, createState);
+    // 2. Инициализация геттеров как функций, возвращающих вычисленное значение
+    const getters = {};
+    if (options.getters) {
+        for (const key in options.getters) {
+            if (!hasOwn(options.getters, key))
+                continue;
+            const getter = options.getters[key];
+            // Поддержка геттеров вида (state) => value и () => value
+            getters[key] = typeof getter === 'function' && getter.length > 0
+                ? () => getter.call(null, staticState)
+                : () => getter.call(proxy);
+        }
+    }
+    // Метод для частичного обновления состояния
+    const $patch = (mutator) => {
+        if (typeof mutator === 'function') {
+            mutator(staticState);
         }
         else {
-            assign(staticState[id], payload);
+            const merged = deepMerge(staticState, mutator);
+            for (const key in merged)
+                staticState[key] = merged[key];
         }
-        assign(store, staticState[id]);
-    }
-    const $reset = function $reset() {
-        const { state } = options;
-        const newState = state ? state() : {};
-        this.$patch((state) => {
-            assign(state, newState);
-        });
     };
-    const partialStore = {
-        $id: id,
+    // Метод для сброса состояния до начального
+    const $reset = () => {
+        const newState = createState();
+        $patch(state => assign(state, newState));
+    };
+    // Создание контекста `this` для действий
+    // Обеспечивает доступ к $state, $patch, геттерам и текущему состоянию
+    const actionThis = new Proxy({
+        $state: staticState,
+        $id: storeId,
         $patch,
         $reset,
+        ...getters,
+    }, {
+        get(target, key) {
+            // Состояние
+            if (key in staticState)
+                return staticState[key];
+            // Геттеры
+            if (key in getters)
+                return getters[key]();
+            if (key in actions)
+                return actions[key];
+            // Служебные свойства
+            if (key in target)
+                return target[key];
+            throw StoreError.get('unknownProperty', key);
+        },
+        set(target, key, value) {
+            if (key in target)
+                throw StoreError.get('readonlyProperty', key);
+            if (!(key in staticState))
+                throw StoreError.get('unknownProperty', key);
+            staticState[key] = value;
+            return true;
+        },
+    });
+    // Привязка действий к контексту `actionThis`
+    const actions = {};
+    if (options.actions) {
+        for (const key in options.actions) {
+            if (!hasOwn(options.actions, key))
+                continue;
+            actions[key] = options.actions[key].bind(actionThis);
+        }
+    }
+    // Реестр служебных свойств и методов хранилища
+    const internals = {
+        $state: () => staticState,
+        $id: () => storeId,
+        $patch: () => $patch,
+        $reset: () => $reset,
     };
-    const store = assign(localState, partialStore
-    // {
-    //   get $state() {
-    //     return staticState[id] as TState
-    //   },
-    //   set $state(state) {
-    //     $patch($state => assign($state, state))
-    //   }
-    // }
-    );
-    return store;
-}
-function defineStore(id, options) {
-    function useStore() {
-        const store = (id in stores ? stores[id] : stores[id] = createStore(id, options));
-        return store;
+    // Финальный прокси-объект хранилища
+    const proxy = new Proxy(staticState, {
+        get(target, key) {
+            // Состояние
+            if (key in target)
+                return target[key];
+            // Геттеры
+            if (key in getters)
+                return getters[key]();
+            // Действия
+            if (key in actions)
+                return actions[key];
+            // Служебные свойства
+            if (key in internals)
+                return internals[key]();
+            throw StoreError.get('unknownProperty', key);
+        },
+        set(target, key, value) {
+            if (key in internals || key in getters || key in actions)
+                throw StoreError.get('readonlyProperty', key);
+            if (!(key in target))
+                throw StoreError.get('unknownProperty', key);
+            target[key] = value;
+            return true;
+        },
+        has(target, key) {
+            return (key in internals
+                || key in getters
+                || key in actions
+                || key in target);
+        },
+    });
+    return proxy;
+}
+/**
+ * Определяет новое хранилище с заданным именем и параметрами.
+ *
+ * Является основной точкой входа для создания хранилищ.
+ * Возвращает функцию `useStore()`, используемую для получения экземпляра хранилища.
+ *
+ * @param type - Уникальный тип хранилища.
+ * @param options - Конфигурация хранилища: `state`, `getters`, `actions`.
+ * @returns Функция `useStore`, создающая или возвращающая экземпляр хранилища.
+ *
+ * @template TState - Тип состояния хранилища.
+ * @template TGetters - Тип вычисляемых свойств.
+ * @template TActions - Тип методов мутации состояния.
+ *
+ * @throws {StoreError} Если хранилище с таким именем уже определено.
+ *
+ * @example
+ * ```ts
+ * const useCounter = defineStore('counter', {
+ *   state: () => ({ count: 0 }),
+ *   getters: { double: (state) => state.count * 2 },
+ *   actions: { increment() { this.count++ } }
+ * })
+ *
+ * const store = useCounter()
+ * ```
+ * @since 0.0.2
+ *
+ **/
+function defineStore(typeId, options) {
+    enforceDefinitionIsUnique(typeId);
+    /**
+     * Возвращает экземпляр хранилища.
+     *
+     * При первом вызове создаёт хранилище, при последующих — возвращает из кэша.
+     * Поддерживает создание именованных экземпляров через параметр `scope`.
+     *
+     * @param scope - Опциональный ключ для создания именованного экземпляра.
+     *                Если указан, создаётся хранилище с идентификатором `typeId/scope`.
+     *                Если не указан — возвращается общий экземпляр хранилища `typeId`.
+     *
+     * @returns Экземпляр хранилища требуемого типа.
+     *
+     * @since 0.0.2
+     *
+     **/
+    function useStore(scope) {
+        const storeId = scope ? `${typeId}/${scope}` : typeId;
+        return (stores[storeId] ??= createStore(storeId, options));
     }
-    useStore.$id = id;
+    useStore.$typeId = typeId;
     return useStore;
 }
+/**
+ * Сбрасывает внутреннее состояние (для тестов).
+ *
+ * @since 0.4.0
+ *
+ * @internal
+ *
+ **/
+function __resetInternalState() {
+    if (!(process.env.NODE_ENV === 'test'))
+        return;
+    module.static = {
+        states: {},
+    };
+    stores = {};
+    __resetInternalState$1();
+}
 
-export { defineStore };
+export { StoreError, defineStore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mirta/store",
   "description": "Type-safe store for wb-rules",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "license": "Unlicense",
   "keywords": [
     "mirta",
@@ -14,6 +14,7 @@
     "LICENSE",
     "README.md"
   ],
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
       "import": {
@@ -22,6 +23,10 @@
       }
     }
   },
+  "imports": {
+    "#src": "./src/index.js",
+    "#src/*": "./src/*.js"
+  },
   "homepage": "https://github.com/wb-mirta/core/tree/latest/packages/mirta-store#readme",
   "repository": {
     "type": "git",
@@ -36,10 +41,14 @@
     "url": "https://boosty.to/wihome/donate"
   },
   "dependencies": {
-    "@mirta/polyfills": "0.3.5"
+    "@mirta/polyfills": "0.4.0",
+    "@mirta/basics": "0.4.0"
+  },
+  "peerDependencies": {
+    "@mirta/basics": "0.4.0",
+    "@mirta/polyfills": "0.4.0"
   },
   "scripts": {
-    "clean": "rimraf dist",
-    "build:mono": "pnpm clean && rollup -c node:@mirta/rollup/config --config-package"
+    "build:mono": "rollup -c node:@mirta/rollup/config-package"
   }
 }