{"_id":"@astral/mobx-router","_rev":"58-ac25a926ad9b23b08ec88dfae38874ea","name":"@astral/mobx-router","dist-tags":{"rc":"1.12.0-rc.0","latest":"1.13.2"},"versions":{"0.1.0":{"name":"@astral/mobx-router","version":"0.1.0","author":{"name":"Astral.Soft"},"license":"MIT","_id":"@astral/mobx-router@0.1.0","maintainers":[{"name":"and_tem","email":"ipad_nw@icloud.com"},{"name":"astral_frontend","email":"frontendastral@gmail.com"}],"dist":{"shasum":"82bbf7aebeac1e52f7b06509109d8a77520c9f63","tarball":"https://registry.npmjs.org/@astral/mobx-router/-/mobx-router-0.1.0.tgz","fileCount":170,"integrity":"sha512-MW8Y3/+JW73nV2zUVshlZoK0NN+vQXdfRzChZq6hlIrzRnoIpdPhZ7WaSzl7fN9MHJUxixjqvSSke+PpQfgl0g==","signatures":[{"sig":"MEQCICKmxzhpiH9U7LukO62eX/lbw5h95dF1xOujuojXkrN9AiBvaeI29FOmJsANaTRfrzUG/sxIZplRvLGmE62/UnCRjA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":209328},"main":"./node/index.js","types":"./index.d.ts","module":"./index.js","browser":"./index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js","module":"./index.js","default":"./index.js","require":"./node/index.js"},"./_mocks":{"types":"./_mocks/index.d.ts","import":"./_mocks/index.js","module":"./_mocks/index.js","default":"./_mocks/index.js","require":"./node/_mocks/index.js"}},"gitHead":"d5ce5acd156078ea49d5fba213bfddcf79e77c45","_npmUser":{"name":"astral_frontend","email":"frontendastral@gmail.com"},"repository":{"url":"https://git.astralnalog.ru/frontend.shared/mobx-query","type":"git"},"_npmVersion":"11.3.0","description":"Абстрактный реактивный router service, позволяющий использовать один интерфейс взаимодействия для разных роутеров: - react-router v5 - react-router v6 и v7 - nextjs router","directories":{},"sideEffects":false,"_nodeVersion":"22.12.0","dependencies":{"remeda":"^2.30.0","@astral/validations":"^4.25.0"},"_hasShrinkwrap":false,"peerDependencies":{"mobx":"6.x.x"},"_npmOperationalInternal":{"tmp":"tmp/mobx-router_0.1.0_1756712076277_0.04010960477633452","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@astral/mobx-router","version":"0.2.0","author":{"name":"Astral.Soft"},"license":"MIT","_id":"@astral/mobx-router@0.2.0","maintainers":[{"name":"and_tem","email":"ipad_nw@icloud.com"},{"name":"astral_frontend","email":"frontendastral@gmail.com"}],"dist":{"shasum":"4681deef793c2ef157ca0ab52f04bde9cadfdbf0","tarball":"https://registry.npmjs.org/@astral/mobx-router/-/mobx-router-0.2.0.tgz","fileCount":170,"integrity":"sha512-jTu3R6bvdYtZ1KfjE+LFTj0wGgDT/LSH9u64EH1Z39U1GajbpUW5dFAqDlxskFvXsiAvWH3mREQTOt9eqlM4mw==","signatures":[{"sig":"MEYCIQDh+uS3LOSgD0x2eBiAxYiIipSCOQG3rw255DCEYOaJrQIhAOBvB9M/+M28r3ANGDOX5Gx/hdm0BhMe/8lrtQfbJSh7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":215229},"main":"./node/index.js","types":"./index.d.ts","module":"./index.js","browser":"./index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js","module":"./index.js","default":"./index.js","require":"./node/index.js"},"./_mocks":{"types":"./_mocks/index.d.ts","import":"./_mocks/index.js","module":"./_mocks/index.js","default":"./_mocks/index.js","require":"./node/_mocks/index.js"}},"gitHead":"7f77b9caf5e401a119fd78888ad02d3f2c832047","_npmUser":{"name":"astral_frontend","email":"frontendastral@gmail.com"},"repository":{"url":"https://git.astralnalog.ru/frontend.shared/mobx-query","type":"git"},"_npmVersion":"11.3.0","description":"Абстрактный реактивный router service, позволяющий использовать один интерфейс взаимодействия для разных роутеров: - react-router v5 - react-router v6 и v7 - nextjs router","directories":{},"sideEffects":false,"_nodeVersion":"22.12.0","dependencies":{"remeda":"^2.30.0","@astral/validations":"^4.25.0"},"_hasShrinkwrap":false,"peerDependencies":{"mobx":"6.x.x"},"_npmOperationalInternal":{"tmp":"tmp/mobx-router_0.2.0_1756990004199_0.917187630803453","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@astral/mobx-router","version":"1.0.0","author":{"name":"Astral.Soft"},"license":"MIT","_id":"@astral/mobx-router@1.0.0","maintainers":[{"name":"and_tem","email":"ipad_nw@icloud.com"},{"name":"astral_frontend","email":"frontendastral@gmail.com"}],"dist":{"shasum":"ffa1d9d7cb9183b6aed297e6c07bc300b465d18d","tarball":"https://registry.npmjs.org/@astral/mobx-router/-/mobx-router-1.0.0.tgz","fileCount":182,"integrity":"sha512-L/y//daNqtu9G2IRLpmAuSZ5lvOGOTy49fwnqhgPoREJxbL77llHKsDCdDWblGiS6ffB+I0ANWd0e3dNgVBcsQ==","signatures":[{"sig":"MEYCIQCeXx0vlVyZVaZ/Wxr3Ma9g+7OHCfsjAfS3qJXhD9bDmQIhAIUpSK6+IZP5+aziZq+/lPJePm98Jg7gwFGrbXv4cTua","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":238986},"main":"./node/index.js","types":"./index.d.ts","module":"./index.js","browser":"./index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js","module":"./index.js","default":"./index.js","require":"./node/index.js"},"./_mocks":{"types":"./_mocks/index.d.ts","import":"./_mocks/index.js","module":"./_mocks/index.js","default":"./_mocks/index.js","require":"./node/_mocks/index.js"}},"gitHead":"af9c1aa502e6955d6781155c32a8949c1b40100a","_npmUser":{"name":"astral_frontend","email":"frontendastral@gmail.com"},"repository":{"url":"https://git.astralnalog.ru/frontend.shared/mobx-query","type":"git"},"_npmVersion":"10.9.3","description":"Абстрактный реактивный router service, позволяющий использовать один интерфейс взаимодействия для разных роутеров: - react-router v5 - react-router v6 и v7 - nextjs router","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","dependencies":{"remeda":"^2.31.0","@astral/validations":"^4.25.0"},"_hasShrinkwrap":false,"peerDependencies":{"mobx":"6.x.x"},"_npmOperationalInternal":{"tmp":"tmp/mobx-router_1.0.0_1757424520560_0.4749354112903268","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@astral/mobx-router","version":"1.0.2","author":{"name":"Astral.Soft"},"license":"MIT","_id":"@astral/mobx-router@1.0.2","maintainers":[{"name":"and_tem","email":"ipad_nw@icloud.com"},{"name":"astral_frontend","email":"frontendastral@gmail.com"}],"dist":{"shasum":"02ecb9f0166d4f2a3673adbae6c73f9ae8aad080","tarball":"https://registry.npmjs.org/@astral/mobx-router/-/mobx-router-1.0.2.tgz","fileCount":182,"integrity":"sha512-bzwl+6IE48ICwu3nIWV85QVK8AkqpSwzaqlx0R7Dr9MflNd8/Ddn85ThBkSuF44bP5GFTSrpN/KeqY71/Bearg==","signatures":[{"sig":"MEUCIQCcyw4oPltF31WVnt1MgWaU6lfaic+j5bJrGrQRJb16QwIgcHqMW7mCUlQ4Iecd3t+R+rnwF6Zqw74rgcoJm4ser7Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":239671},"main":"./node/index.js","types":"./index.d.ts","module":"./index.js","browser":"./index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js","module":"./index.js","default":"./index.js","require":"./node/index.js"},"./_mocks":{"types":"./_mocks/index.d.ts","import":"./_mocks/index.js","module":"./_mocks/index.js","default":"./_mocks/index.js","require":"./node/_mocks/index.js"}},"gitHead":"ae90e2bbd0914f8d3e635c00301d5e0e43625d8b","_npmUser":{"name":"astral_frontend","email":"frontendastral@gmail.com"},"repository":{"url":"https://git.astralnalog.ru/frontend.shared/mobx-router","type":"git"},"_npmVersion":"10.9.3","description":"Абстрактный реактивный router service, позволяющий использовать один интерфейс взаимодействия для разных роутеров: - react-router v5 - react-router v6 и v7 - nextjs router","directories":{},"sideEffects":false,"_nodeVersion":"22.19.0","dependencies":{"remeda":"^2.31.0","@astral/validations":"^4.25.0"},"_hasShrinkwrap":false,"peerDependencies":{"mobx":"6.x.x"},"_npmOperationalInternal":{"tmp":"tmp/mobx-router_1.0.2_1757485017808_0.8920949854215499","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@astral/mobx-router","version":"1.0.3","author":{"name":"Astral.Soft"},"license":"MIT","_id":"@astral/mobx-router@1.0.3","maintainers":[{"name":"and_tem","email":"and.tem.dev@gmail.com"},{"name":"astral_frontend","email":"frontendastral@gmail.com"}],"dist":{"shasum":"888aa2202552ea74020389984c7362cb5bf4fd9d","tarball":"https://registry.npmjs.org/@astral/mobx-router/-/mobx-router-1.0.3.tgz","fileCount":182,"integrity":"sha512-FhcSL/TvIBmFuSR6A0gaqCc4spGZBg2CFK2+6rzMz4YXIshRGY6k96Vu3hJF8Php5Z174oVDHDVLAxSSk7IVPg==","signatures":[{"sig":"MEUCIFf29zEGh7xgmtd/lwMSKM7+vUJ0F29e7orxSXC9tN5MAiEA6PqyMC0A1mHxAeeWKu3dBLa4nZ8Iw0juNehcYW1rx4A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":265162},"main":"./node/index.js","types":"./index.d.ts","module":"./index.js","browser":"./index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js","module":"./index.js","default":"./index.js","require":"./node/index.js"},"./_mocks":{"types":"./_mocks/index.d.ts","import":"./_mocks/index.js","module":"./_mocks/index.js","default":"./_mocks/index.js","require":"./node/_mocks/index.js"}},"gitHead":"7cf5bb35813b02b917cf2b7187d4dbd535d32f80","_npmUser":{"name":"astral_frontend","email":"frontendastral@gmail.com"},"repository":{"url":"https://git.astralnalog.ru/frontend.shared/mobx-router","type":"git"},"_npmVersion":"10.9.3","description":"
\n\n# @astral/mobx-router\n\nАбстрактный реактивный router service, позволяющий использовать один интерфейс взаимодействия для разных роутеров:\n- react-router v6 и v7\n- nextjs router\n\n## Краткий обзор\n\n
\n\n## Содержание\n\n- [Getting Started](#getting-started)\n - [React Router v6/v7](#react-router-v6v7)\n - [Next.js (Pages Router)](#nextjs-pages-router)\n - [Использование](#использование)\n- [Определение routes](#определение-routes)\n - [Навигация (`navigate`)](#навигация-navigate)\n - [Генерация ссылок](#генерация-ссылок)\n- [Базовый путь приложения (baseName)](#базовый-путь-приложения-basename)\n \n- [RouteParams](#routeparams)\n- [Навигация](#навигация)\n - [Типобезопасная навигация](#типобезопасная-навигация)\n - [Метод `navigate`](#метод-navigate)\n - [Асинхронный переход `navigateAsync`](#асинхронный-переход-navigateasync)\n - [Возврат по истории назад (back)](#возврат-по-истории-назад-back)\n - [Перезагрузка страницы (reload)](#перезагрузка-страницы-reload)\n - [State при навигации](#state-при-навигации)\n- [Работа с SearchParams](#работа-с-searchparams)\n - [Типобезопасные изолированные searchParams](#типобезопасные-изолированные-searchparams)\n - [Values](#values)\n - [Валидация](#валидация)\n - [Валидация дат](#валидация-дат)\n \n - [Установка значений (set, setAll)](#установка-значений-set-setall)\n - [Удаление параметров (delete)](#удаление-параметров-delete)\n - [Сброс значений (reset)](#сброс-значений-reset)\n \n - [Создание нескольких searchParamsStore](#создание-нескольких-searchparamsstore)\n \n - [initialValues](#initialvalues)\n \n - [defaultValues](#defaultvalues)\n - [Особенности работы с nextjs](#особенности-работы-с-nextjs)\n - [Не типизированные searchParams, приведенные к js структурам](#не-типизированные-searchparams-приведенные-к-js-структурам)\n - [Парсинг и сериализация searchParams](#парсинг-и-сериализация-searchparams)\n - [Кастомный парсинг и сериализация searchParams](#кастомный-парсинг-и-сериализация-searchparams)\n - [Сохранение Search параметров при навигации](#сохранение-search-параметров-при-навигации)\n- [Блокировка маршрутов (blocker)](#блокировка-маршрутов-blocker)\n - [Состояние блокировки](#состояние-блокировки)\n - [Управления блокировкой](#управления-блокировкой)\n - [Работа с несколькими блокерами](#работа-с-несколькими-блокерами)\n - [Управление жизненным циклом (destroy)](#управление-жизненным-циклом-destroy)\n- [MatchPath - Сопоставление маршрутов](#matchpath---сопоставление-маршрутов)\n - [API](#api)\n - [Базовый пример](#базовый-пример)\n - [Полное сопоставление](#полное-сопоставление)\n - [Практические примеры](#практические-примеры)\n- [Location](#location)\n - [API](#api-1)\n - [pathname](#pathname)\n- [SubscribeRoute](#подписка-на-события-маршрутизации)\n- [Debug](#debug)\n- [Тестирование](#тестирование)\n\n## Getting Started\n\n### React Router v6/v7\n\n#### Установка\n\n```bash\nnpm install @astral/mobx-router @astral/mobx-router-react mobx react-router\n```\n\n#### Подготовка\n\n- Для работы с react-router v6/v7 **необходимо использовать [`DataRouter`](https://reactrouter.com/start/data/installation)**. Ниже описан пример настройки\n\n- Все импорты должны быть из `react-router`, а не из `react-router-dom`\n\n```typescript\n// ✅\nimport { createBrowserRouter, useLocation } from 'react-router';\n\n// ❌\nimport { createBrowserRouter, useLocation } from 'react-router-dom';\n```\n\n#### Настройка\n\n**Важно**: Для работы с react-router v6/v7 необходимо использовать [`DataRouter`](https://reactrouter.com/start/data/installation).\n\n```shared/services/Router```\n```typescript\nimport { MobxRouter } from '@astral/mobx-router';\nimport { ReactRouterProvider } from '@astral/mobx-router-react';\n\nexport const reactRouterProvider = new ReactRouterProvider();\n\nconst routesConfig = {\n home: MobxRouter.defineRoute({\n pattern: '/home',\n }),\n \n user: MobxRouter.defineRoute({\n pattern: '/user/:id',\n generatePath: (params: { id: string }) => `/user/${params.id}`,\n }),\n \n profile: MobxRouter.defineRoute({\n pattern: '/profile/:userId?',\n generatePath: ({ userId }: { userId?: string }) => userId ? `/profile/${userId}` : '/profile' ,\n }),\n};\n\nexport const router = new MobxRouter(reactRouterProvider, routesConfig);\n\n// Необходим для инжектирования в MobX store, чтобы в типах были routes приложения\nexport type Router = typeof router;\n```\n\n```application/routes.tsx```\n```typescript\nimport { lazy, Suspense } from 'react';\nimport { ProviderAdapter } from '@astral/mobx-router-react';\nimport { createBrowserRouter, Outlet } from 'react-router';\n\nimport { MainLayout } from '#modules/layout';\nimport { ContentState, reactRouterProvider, router } from '#shared';\n\nconst IndexPage = lazy(() => import('./pages/index'));\n\nconst HomePage = lazy(() => import('./pages/home'));\n\nconst UserPage = lazy(() => import('./pages/user'));\n\nconst ProfilePage = lazy(() => import('./pages/profile'));\n\nexport const browserRouter = createBrowserRouter([\n {\n element: (\n <>\n \n \n loading...}\n >\n \n \n \n \n ),\n children: [\n {\n path: '/',\n element: ,\n },\n {\n path: router.routes.home.pattern,\n element: ,\n },\n {\n path: router.routes.user.pattern,\n element: ,\n },\n {\n path: router.routes.profile.pattern,\n element: ,\n },\n ],\n },\n]);\n```\n\n```application/app```\n```typescript\nimport { ProviderAdapter } from '@astral/mobx-router-react';\nimport { RouterProvider as ReactRouterProvider } from 'react-router/dom';\n\nimport { browserRouter } from './routes';\n\nconst App = () => {\n return (\n \n );\n};\n```\n\n### Next.js (Pages Router)\n\n**Поддерживает только pages routing**\n\n#### Установка\n\n```bash\nnpm install @astral/mobx-router @astral/mobx-router-nextjs-pages mobx\n```\n\n#### Настройка\n\n```shared/services/Router```\n```typescript\nimport { MobxRouter } from '@astral/mobx-router';\nimport { NextjsPagesRouterProvider } from '@astral/mobx-router-nextjs-pages';\n\nconst provider = new NextjsPagesRouterProvider();\n\nconst routesConfig = {\n home: MobxRouter.defineRoute({\n pattern: '/home',\n }),\n \n user: MobxRouter.defineRoute({\n pattern: '/user/[id]',\n generatePath: (params: { id: string }) => `/user/${params.id}` ,\n }),\n \n profile: MobxRouter.defineRoute({\n pattern: '/profile/[[userId]]',\n generatePath: ({ userId }: { userId?: string }) => userId ? `/profile/${userId}` : '/profile' ,\n }),\n};\n\nexport const router = new MobxRouter(provider, routesConfig);\n\n// Необходим для инжектирования в MobX store, чтобы в типах были routes приложения\nexport type Router = typeof router;\n```\n\n```pages/_app.tsx```\n```typescript\nimport { ProviderAdapter } from '@astral/mobx-router-nextjs-pages';\nimport type { AppProps } from 'next/app';\n\nimport { provider } from '#shared/services/Router';\n\nfunction MyApp({ Component, pageProps }: AppProps) {\n return (\n <>\n \n \n \n );\n}\n\nexport default MyApp;\n```\n\n### Использование\n\nПосле настройки вы можете использовать роутер для навигации:\n```typescript\n// Простой переход\nrouter.navigate('/dashboard');\n\n// Переход с заменой истории\nrouter.navigate('/login', { replace: true });\n```\n\nИли подписываться на изменения роутера в mobx:\n```typescript\nimport { makeAutoObservable } from 'mobx';\nimport type { Router } from '#shared';\n\nclass Store {\n constructor(private readonly _router: Router) {\n makeAutoObservable(this);\n }\n\n get isAdminPage() {\n return this._router.location.pathname.startsWith('/admin');\n }\n}\n```\n\n## Определение routes\n\nПосле создания роутера необходимо определить маршруты приложения:\n- Для статических маршрутов достаточно указать только `pattern`. Он будет использоваться как pathname для переходов\n- Для динамических маршрутов с использованием routeParams необходимо определять `generatePath`. Если `generatePath` не будет принимать параметров, возникнет исключение\n\n```typescript\nimport { MobxRouter } from '@astral/mobx-router';\n\n// Определяем конфигурацию routes\nconst routesConfig = {\n // Для статичных путей без параметров достаточно указать pattern\n home: MobxRouter.defineRoute({\n pattern: '/home', // pathname будет '/home'\n }),\n \n // Для путей с параметрами рекомендуется указывать generatePath\n user: MobxRouter.defineRoute({\n pattern: '/user/:id',\n generatePath: (params: { id: string }) => `/user/${params.id}` ,\n }),\n \n profile: MobxRouter.defineRoute({\n pattern: '/profile/:userId?',\n generatePath: ({ userId }: { userId?: string }) => userId ? `/profile/${userId}` : '/profile' ,\n }),\n};\n\n// Создаем роутер с конфигурацией\nexport const router = new MobxRouter(provider, routesConfig);\n```\n\n### Навигация (`navigate`)\n\nИнтерфейс `navigate` аналогичен интерфейсу корневого [`navigate`](#метод-navigate).\n\nПосле определения routes вы можете использовать их для типобезопасной навигации:\n\n```typescript\n// Простая навигация без параметров\nrouter.routes.home.navigate();\n\n// Навигация с обязательными параметрами\nrouter.routes.user.navigate({ params: { id: '123' } });\n\n// Навигация с опциональными параметрами\nrouter.routes.profile.navigate(); // без параметров\nrouter.routes.profile.navigate({ params: { userId } }); // с параметрами\n```\n\n\n### RouteParams\n\nКаждый маршрут также предоставляет доступ к своим параметрам через свойство `routeParams`:\n\n```typescript\ntype Params = { id: string };\n\nconst routesConfig = {\n user: Router.defineRoute({\n pattern: '/user/:id',\n generatePath: (params: Params) => `/user/${params.id}`,\n }),\n};\n\n// Получение параметров конкретного маршрута\nrouter.routes.user.routeParams; // { id: '123' }\n```\n\nВ примере выше `router.routes.user.routeParams` будет соответствовать типу:\n```typescript\n{ id: string } | undefined\n```\n\n`undefined`, если маршрут не активен.\n\n### Проверка активности route (isActive)\n\nКаждый route предоставляет свойство `isActive`, которое позволяет определить, является ли данный route активным в текущий момент. Это свойство является MobX observable и автоматически обновляется при изменении URL.\n\n#### Синтаксис\n\n```typescript\nrouter.routes.routeName.isActive: boolean\n```\n\n#### Пример\n\n```typescript\nimport { MobxRouter } from '@astral/mobx-router';\n\nconst routesConfig = {\n user: MobxRouter.defineRoute({\n pattern: '/user/:id',\n generatePath: ({ id }: { id: string }) => `/user/${params.id}`,\n }),\n};\n\nexport const router = new MobxRouter(provider, routesConfig);\n...\n```\n\n```typescript\nimport { makeAutoObservable } from 'mobx';\n\nclass SidebarStore {\n constructor(private readonly _router: Router) {\n makeAutoObservable(this);\n }\n\n get isUserRouteActive() {\n return this._router.routes.user.isActive;\n }\n}\n```\n\n### Генерация ссылок (`generateHref`)\n\nДля создания ссылок на route используйте метод `generateHref`:\n\n```typescript\nconst profileLink = router.routes.profile.generateHref({\n userId: '456',\n}); // /profile/456\n\n// Использование в компонентах\nМой профиль\n```\n\n#### Генерация ссылки с searchParams\n\n```typescript\nconst userLink = router.routes.user.generateHref(\n { id: '123' },\n { searchParams: { page: 1 } },\n); // /user/123?page=1\n\n// Использование в компонентах\nМой профиль;\n```\n\n## Базовый путь приложения (baseName)\n\nДля настройки базового пути приложения используйте опцию `baseName` при создании MobxRouter.\n\n⚠️ В Next.js Router этот параметр **не поддерживается**\n\n```typescript\nconst browserRouter = createBrowserRouter(routes, {\n basename: '/app',\n});\n\nconst router = new MobxRouter(reactRouterProvider, routesConfig, {\n // Должен совпадать с basename, переданным в React Router\n baseName: '/app',\n});\n```\n\n## RouteParams\n\nРоутер предоставляет доступ к параметрам текущего активного маршрута через свойство `routeParams`:\n\n```typescript\nconst routesConfig = {\n user: Router.defineRoute({\n pattern: '/user/:id',\n generatePath: (params: { id: string }) => `/user/${params.id}`,\n }),\n};\n\nconst router = new Router(provider, routesConfig);\n\n// Получение параметров текущего активного маршрута\nconsole.log(router.routeParams); // { id: '123' }\n```\n\n## Навигация\n\n### Метод `navigate`\n\nОсновной метод для навигации между страницами приложения.\n\n#### Синтаксис\n\n```typescript\nrouter.navigate(to: string | Location, options?: NavigateOptions)\n```\n\n#### Параметры\n\n- `to` (string | Location) - путь для перехода (строка или объект)\n- `options` (NavigateOptions, опционально) - дополнительные параметры навигации\n\n#### Тип NavigateOptions\n\n```typescript\ntype NavigateOptions = {\n /**\n * Позволяет сделать переход без сохранения в history\n */\n replace?: boolean;\n /**\n * @sse https://developer.mozilla.org/en-US/docs/Web/API/History/scrollRestoration\n */\n scrollRestoration?: 'auto' | 'manual';\n /**\n * SearchParams в виде plain object для перехода\n */\n searchParams?: SearchParams;\n /**\n * Дополнительные данные, которые будут переданы в `location.state`\n * при навигации (поддерживается только в react-router).\n *\n * ⚠️ В Next.js Router этот параметр **не поддерживается**\n */\n state?: unknown;\n};\n```\n\n#### Примеры использования\n\n```typescript\n// Простой переход на страницу (строка)\nrouter.navigate('/main');\n\n// Переход с заменой текущей записи в истории браузера\nrouter.navigate('/main', { replace: true });\n\n// Переход с отключением автоматической прокрутки\nrouter.navigate('/main', { scrollRestoration: 'manual' });\n\n// Комбинирование параметров\nrouter.navigate('/main', { \n replace: true, \n scrollRestoration: 'manual' \n});\n```\n\n#### Переход с установкой searchParams\n\n```typescript\nrouter.navigate({\n pathname: '/user/123',\n // ?page=1&filters=[1,2]\n searchParams: { page: 1, filters: [1, 2] }\n});\n```\n\n#### Передача search строки\n\nSearch можно передавать как `?`, так и без:\n```typescript\n// Переход с search параметрами (с ?)\nrouter.navigate({\n pathname: '/search',\n search: '?query=test&page=1'\n});\n\n// Переход с search параметрами (без ?)\nrouter.navigate({\n pathname: '/search',\n search: 'query=test&page=1'\n});\n```\n\n#### Особенности реализации\n\n- `navigate` не синхронный:\n\n```typescript\nrouter.location.pathname; // /main\nrouter.navigate('/user');\nrouter.location.pathname; // /user\n```\n\n#### Асинхронный переход `navigateAsync`\n\nАсинхронный метод для перехода между страницами приложения, который позволяет дождаться завершения навигации.\n\nЗавершение навигации - успешный рендеринг нового маршрута.\n\n```typescript\n// Переход на страницу и ожидание завершения\nawait router.navigateAsync('/main');\n\n// Переход с заменой текущей записи в истории\nawait router.navigateAsync('/main', { replace: true });\n\n// Переход с отключением автоматической прокрутки\nawait router.navigateAsync('/main', { scrollRestoration: 'manual' });\n\n// Переход с передачей searchParams\nawait router.navigateAsync({\n pathname: '/user/123',\n searchParams: { page: 1, filters: [1, 2] }\n});\n```\n\n#### Возврат по истории назад (`back`)\n\nМетод позволяющий вернутся на предыдущий URL в истории\n\n```typescript\nrouter.navigate('/user'); // /main -> /user\n\nrouter.back(); // возврат на /main\n```\n\n#### Перезагрузка страницы (`reload`)\n\nМетод перезагружает текущую страницу\n\n```typescript\nrouter.reload();\n```\n\n#### `state` при навигации\n\nО работе `state` можно ознакомиться [здесь](https://developer.mozilla.org/en-US/docs/Web/API/History/state)\n\n##### Особенности реализации\n\n- **NextRouter**: параметр `state` не поддерживается\n\n##### Тип NavigationState\n\n```typescript\ntype NavigationState = {\n /**\n * Информация о предыдущем location, с которого был совершен переход\n */\n referer: {\n /**\n * Путь предыдущего location\n */\n pathname: string;\n /**\n * search предыдущего location\n */\n search?: string;\n };\n} & Record;\n```\n\n##### Пример использования\n\n```typescript\n// Навигация с передачей state и сохранением referer\nrouter.routes.user.navigate({\n params: { id: '123' },\n state: { filter: 'value' },\n});\n\nrouter.location \n// { \n// pathname: '/user/123', \n// search: '', \n// state: { referer: { pathname: currentLocation.pathname, search: currentLocation.search }, filter: 'value' },\n// }\n```\n\n## Работа с SearchParams\n\nРоутер предоставляет несколько способов работы с search параметрами URL.\n\n### Типобезопасные изолированные searchParams\n\n#### Базовая концепция\n\n- **Типобезопасность**: `router.createSearchParamsStore` гарантирует, что `values` содержит именно те типы данных, которые были переданы в generic и заданы через валидацию.\n- **Изолированность**: `router.createSearchParamsStore` работает только с теми параметрами, которые были переданы в generic и заданы через валидацию, никак не влияя при этом на другие searchParams.\n\n#### Пример использования\n\n```typescript\nimport { makeAutoObservable } from 'mobx';\nimport * as v from '@astral/validations';\nimport type {Router} from '#shared';\n\ntype SearchParams = {\n id: string;\n page?: number;\n filters?: string[];\n};\n\nclass UIStore {\n private readonly searchStore;\n\n public constructor(private readonly _router: Router) {\n makeAutoObservable(this, {}, {autoBind: true});\n \n this.searchStore = this._router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n page: v.optional(v.number()),\n filters: v.optional(v.array(v.arrayItem(v.string()))),\n },\n });\n }\n\n public get userId() {\n // Values === undefined, если валидация не прошла\n return this.searchStore.values?.id;\n }\n\n public get currentPage() {\n return this.searchStore.values?.page || 1;\n }\n\n public get activeFilters() {\n return this.searchStore.values?.filters || [];\n }\n\n public setUserId(id: string) {\n this.searchStore.set('id', id);\n }\n\n public setFilters = (filters: string[]) => {\n this.searchStore.set('filters', filters);\n }\n\n public deleteFilters = () => {\n this.searchStore.delete('filters');\n }\n}\n```\n\n#### Values\n\n`store.values` является observable.\n\n#### Валидация\n\nВалидация происходит:\n- При инициализации `SearchParamsStore`\n- При обращении к `values` или `validationErrors`\n- При изменении `searchParams` в рамках текущего store или в глобальном `router.searchParams`\n\n`store.values` содержат:\n- `undefined` если валидация завершилась ошибкой\n- значения после парсинга если валидация завершилась без ошибок\n\n`validationSchema` принимает [схему объекта для @astral/validations](https://www.npmjs.com/package/@astral/validations#basic-usage).\n\n\n\n##### Тип SearchParamsValidationSchema\n\n```typescript\n// Schema - схема объекта из @astral/validations\ntype SearchParamsValidationSchema = Schema;\n```\n\nЕсли схему нужно вынести из вызова `createSearchParamsStore` в отдельную переменную, константу или поле класса,\nто для ее типизации используется `SearchParamsValidationSchema`:\n\n```typescript\nimport * as v from '@astral/validations';\nimport type { SearchParamsValidationSchema } from '@astral/mobx-router';\n\ntype SearchParams = {\n id: string;\n page?: number;\n};\n\nconst searchParamsSchema: SearchParamsValidationSchema = {\n id: v.string(),\n page: v.optional(v.number()),\n};\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: searchParamsSchema,\n});\n```\n\nВ схеме должны быть описаны **все** параметры, включая опциональные: для `page?: number` в схеме\nвсе равно требуется ключ `page` со значением `v.optional(...)`.\n\n\n\n##### Валидация при инициализации `SearchParamsStore`\n\nЕсли валидация при инициализации `SearchParamsStore` завершилась ошибкой, то `values` будут содержать `undefined`, **при этом `router.searchParams` не изменится** если не заданы [`defaultValues`](#defaultvalues).\n\n##### Валидация при обращении к `values`\n\nВалидация при обращении к values никак не меняет `router.searchParams`.\n\n##### Валидация дат\n\nДля валидации дат необходимо использовать метод [transform](https://www.npmjs.com/package/@astral/validations#transform)\n\n```typescript\nimport * as v from '@astral/validations';\n\ntype SearchParams = {\n date: string;\n};\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n date: v.string(v.transform((value) => new Date(value))),\n },\n })\n\n// values === undefined, если валидация не прошла\nsearchStore.values?.date;\n```\n\n##### Обработка ошибок валидации\n\nЕсли валидация завершилась ошибкой, то `values` будут содержать `undefined`, а `validationErrors` объект с информацией об ошибке:\n\n```ts\nimport * as v from '@astral/validations';\n\ntype SearchParams = {\n id: string;\n};\n\n// В url search отсутствует id\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n },\n });\n\nsearchStore.values; // undefined\nsearchStore.validationErrors; // { id: { message: 'Не является строкой', code: 'astral-validations-string' } }\n\nif (searchStore.validationErrors?.id.code === v.STRING_TYPE_ERROR_INFO.code) { \n console.log('Передан не корректный id. Попробуйте...');\n}\n```\n\n---\n\n#### Установка значений (`set`, `setAll`)\n\nSearchParamsStore предоставляет несколько методов для изменения параметров.\n\nПо умолчанию все изменения не сохраняются в истории браузера (используется `replace: true`).\n\n##### `set`\n\nУстанавливает значение для конкретного параметра, сохраняя остальные параметры без изменений.\n\n```typescript\n// Установка обязательного параметра\nsearchStore.set('id', '123');\n\n// Установка массива\nsearchStore.set('filters', ['active', 'verified']);\n\n// Сохранение в истории браузера\nsearchStore.set('page', 3, { replace: false });\n```\n\n##### `setAll`\n\nУстанавливает все параметры сразу, позволяя полностью перезаписать текущие значения или модифицировать их на основе предыдущих.\n\n```typescript\n// Полная замена всех параметров\nsearchStore.setAll({ id: '456', page: 1 });\n\n// Модификация на основе предыдущих значений\n// prev может быть undefined\nsearchStore.setAll((prev) => ({\n ...prev,\n page: (prev?.page || 0) + 1,\n}));\n\n// Сохранение в истории браузера\nsearchStore.setAll({ id: '789' }, { replace: false });\n```\n\n**Важно**: `setAll` изменяет только те параметры, которые указаны в validationSchema.\n\n```typescript\nrouter.setSearchParams({ id: '1', page: 1, test: 'test' });\n\nsearchStore.setAll({ id: '2', page: 2, isShowModal: true });\n\nrouter.searchParams // { id: '2', page: 2, isShowModal: true }\n```\n\n#### Удаление параметров (`delete`)\n\n`delete` Удаляет конкретный параметр.\n\nПо-умолчанию удаление параметра не сохраняется в истории браузера (используется `replace: true`).\n\n**TypeScript не позволит удалить обязательные параметры** - только опциональные.\n\n```typescript\ntype SearchParams = {\n id: string; // Обязательный - нельзя удалить\n page?: number; // Опциональный - можно удалить\n filters?: string[]; // Опциональный - можно удалить\n};\n\n// ✅ Можно удалить опциональные параметры\nsearchStore.delete('page');\nsearchStore.delete('filters');\n\n// ❌ TypeScript ошибка - нельзя удалить обязательный параметр\n// searchStore.delete('id'); // Error: Argument of type '\"id\"' is not assignable to parameter of type '\"page\" | \"filters\"'\n\n// Сохранение в истории браузера\nsearchStore.delete('page', { replace: false });\n```\n\n#### Сброс значений (`reset`)\n\n`reset` удаляет все параметры, которые указаны в generic и validationSchema.\n\nПо-умолчанию сброс не сохраняется в истории браузера (используется `replace: true`).\n\n```typescript\nrouter.setSearchParams({ id: '1', page: 1, test: 'test' });\n\nsearchStore.reset();\n\nrouter.searchParams // { test: 'test' }\n\n// Сброс с сохранением в истории браузера\nsearchStore.reset({ replace: false });\n```\n\n##### Частичный сброс значений\n\n`include` и `exclude` позволяют сбросить только определенные параметры.\n\n```typescript\nsearchStore.setAll({ id: '1', page: 1 });\n\n// Сброс только id\nsearchStore.reset({ include: ['id'] }); // { page: 1 }\n```\n\n```typescript\nsearchStore.setAll({ id: '1', page: 1 });\n\n// Сброс всех параметров, кроме id\nsearchStore.reset({ exclude: ['id'] }); // { id: '1' }\n```\n\n#### Создание нескольких `searchParamsStore`\n\nВ приложении можно создавать несколько `searchParamsStore` с разными validationSchema.\nТак как `searchParamsStore` изолированы, то они не будут влиять друг на друга.\n\n\n```typescript\nconst tableFiltersStore = router.createSearchParamsStore<{\n page: number;\n filters: string[];\n}>({\n validationSchema: {\n page: v.optional(v.number()),\n filters: v.optional(v.array(v.arrayItem(v.string()))),\n },\n});\n\n// Если в searchParams есть modalOrgId, то открывается модалка\nconst detailsModalSearchParamsStore = router.createSearchParamsStore<{\n modalOrgId: string;\n}>({\n validationSchema: {\n modalOrgId: v.optional(v.string(v.guid())),\n },\n});\n\n// Никак не повлияет на modalOrgId\ntableFiltersStore.setAll({ page: 1, filters: ['active', 'verified'] });\n\ndetailsModalSearchParamsStore.set('modalOrgId', '123');\n\n// Никак не повлияет на modalOrgId\ntableFiltersStore.reset();\n```\n\n#### defaultValues\n\n`defaultValues` применяются только при инициализации `SearchParamsStore` или сбросе значений.\n\nПодробнее ниже:\n\n##### При инициализации `SearchParamsStore` searchParams пустые\n\n```typescript\nrouter.setSearchParams({});\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.optional(v.string()),\n },\n defaultValues: {\n id: 'default-user',\n },\n});\n\nsearchStore.values; // { id: 'default-user' }\nrouter.searchParams; // { id: 'default-user' }\n```\n\n##### При инициализации `SearchParamsStore` searchParams частично пустые\n\n```typescript\nrouter.setSearchParams({ page: 2 });\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n page: v.optional(v.number()),\n },\n defaultValues: {\n id: 'default-user',\n page: 1,\n },\n});\n\n// Сохранился исходный page, а для id установлено defaultValues\nsearchStore.values; // { id: 'default-user', page: 2 }\nrouter.searchParams; // { id: 'default-user', page: 2 }\n```\n\n##### При инициализации `SearchParamsStore` валидация не прошла\n\n```typescript\nrouter.setSearchParams({ id: 1 });\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n },\n defaultValues: {\n id: 'default-user',\n },\n});\n\nsearchStore.values; // { id: 'default-user' }\nrouter.searchParams; // { id: 'default-user' }\n```\n\n##### После вызова `reset()`\n\n```typescript\nrouter.setSearchParams({ id: '1' });\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n },\n defaultValues: {\n id: 'default-user',\n },\n});\n\nsearchStore.reset();\n\nrouter.searchParams // { test: 'test' }\n```\n\n##### При инициализации `SearchParamsStore` валидация прошла, но не все optional параметры находились в исходном searchParams\n\n```typescript\nrouter.setSearchParams({ id: '1' });\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n page: v.optional(v.number()),\n },\n defaultValues: {\n id: 'default-user',\n page: 1,\n },\n});\n\nsearchStore.values; // { id: '1', page: 1 }\nrouter.searchParams // { id: '1', page: 1 }\n```\n\n##### defaultValues как функция. Динамическая установка defaultValues \n\n`defaultValues` может быть функцией `(values: ParsedSearchParams) => TSearchParams`.\n\n```typescript\ntype SearchParams = {\n dateFrom?: string;\n dateTo?: string;\n};\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n dateFrom: v.optional(v.string(v.transform((value) => new Date(value)))),\n dateTo: v.optional(v.string(v.transform((value) => new Date(value)))),\n },\n defaultValues: (values) => {\n // Содержит сырые и не провалидированные values\n // Если в searchParams уже есть хотя бы одна дата — не подставляем defaultValues\n if (values?.fromDate || values?.toDate) {\n return values;\n }\n \n return {\n dateFrom: this.defaultDateRange.start,\n dateTo: this.defaultDateRange.end,\n };\n },\n});\n```\n\n#### initialValues\n\n`initialValues` - делают hard set значений в values и глобальные searchParams.\n\n```typescript\ntype SearchParams = {\n id: string;\n};\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n },\n initialValues: {\n id: '1',\n },\n});\n\nsearchStore.values; // { id: '1' }\nrouter.searchParams; // { id: '1' }\n```\n\nАналогичный пример:\n```typescript\ntype SearchParams = {\n id: string;\n};\n\nconst searchStore = router.createSearchParamsStore({\n validationSchema: {\n id: v.string(),\n },\n});\n\nsearchStore.setAll({ id: '1' });\n\nsearchStore.values; // { id: '1' }\nrouter.searchParams; // { id: '1' }\n```\n\n---\n\n### Особенности работы с nextjs\n\n#### SearchParams недоступны на сервере без `getServerSideProps`\n\nПри обращении к `router.searchParams` на сервере nextjs `searchParams` будут `{}`.\n\nДля того чтобы значение на сервере было актуальным, необходимо для конкретной страницы определить `getServerSideProps`:\n```tsx\nexport default () => {...}\n\n// Достаточно просто определить функцию\nexport async function getServerSideProps() {\n\treturn {\n\t\tprops: {},\n\t};\n}\n```\n\n#### При частичной интеграции mobx-router в `nextRouter.query` строки записываются с кавычками\n\nЕсли вы одновременно используете `nextRouter.query` и `mobxRouter.setSearchParams`, то при вызове `mobxRouter.setSearchParams` в `nextRouter.query` будут находится строки в кавычках:\n```js\n{\n id: '\"123\"'\n}\n```\n\nДля решения данной проблемы необходимо реализовывать кастомный парсер searchParams. [Инструкции](#кастомный-парсинг-и-сериализация-searchparams)\n\n---\n\n### Не типизированные searchParams, приведенные к js структурам\n\n**Рекомендуется использовать [типобезопасные searchParams из `router.createSearchParamsStore`](#типобезопасные-изолированные-searchparams)**.\n\n`router.searchParams` содержит не типизированные searchParams, приведенные к js структурам.\n\n`router.searchParams` в качестве значений может содержать:\n```ts\ntype ParsedSearchParamsValue =\n | string\n | boolean\n | number\n | null\n | undefined\n | ParsedSearchParamsValue[]\n | Record;\n```\n\n`router.searchParams` является observable.\n\n**Пример использования**:\n```typescript\nimport { makeAutoObservable } from 'mobx';\n\nclass Store {\n constructor(private readonly _router: Router) {\n makeAutoObservable(this);\n }\n\n get currentPage() {\n return this._router.searchParams.page || 1;\n }\n}\n```\n\n#### Установка searchParams\n\nМетод `setSearchParams` позволяет изменять search параметры с сохранением текущего пути:\n\n```typescript\nrouter.setSearchParams({ page: 1, type: 'request' });\n\n// Изменение с доступом к предыдущим параметрам\ntype PrevParams = { page: number };\n\nrouter.setSearchParams((prev) => ({ page: ++(prev as PrevParams).page }));\n\n// Установка с заменой записи в истории (по умолчанию replace: true)\nrouter.setSearchParams({ page: 1 }, { replace: false });\n```\n\n#### Сброс searchParams\n\nДля сброса достаточно пробросить пустой объект:\n```typescript\nrouter.setSearchParams({});\n```\n\n### Парсинг и сериализация searchParams\n\nПарсинг и сериализация параметров **по-дефолту** осуществляется через `JSON.parse` и `JSON.stringify`.\n\n#### Сериализация \n\n- Строки сериализуются с кавычками: `{ param: 'test' }` → `?param=\"test\"`\n- Числа и булевы значения преобразуются напрямую: `{ num: 123, bool: true }` → `?num=123&bool=true`\n- Массивы и объекты сериализуются в JSON: `{ arr: [1,2,3] }` → `?arr=[1,2,3]`\n- Значения `undefined`, `null`, `NaN`, пустые строки, пустые массивы, пустые объекты пропускаются и не добавляются в URL\n\n#### Парсинг\n\n- Строки в кавычках парсятся как строки: `?param=\"test\"` → `{ param: 'test' }`\n- Числа и булевы значения автоматически приводятся к соответствующим типам: `?num=123` → `{ num: 123 }`\n- Массивы парсятся как json: `?arr=[1,2,3]` → `{ arr: [1,2,3] }`\n- Объекты парсятся как json: `?obj={\"a\":2}` → `{ obj: { a: 2 } }`\n- Строка `\"undefined\"` преобразуется в `undefined`\n- Строка `\"null\"` преобразуется в `null`\n- При ошибке парсинга значение остается строкой: `?arr=[1,2-3]` → `{ arr: '[1,2,3]' }`, `?param=str` → `{ param: 'str' }`\n- Повторяющиеся параметры собираются в массив: `?arr=1&arr=2` → `{ arr: [1,2] }`\n\n#### Кастомный парсинг и сериализация searchParams\n\nМожет потребоваться изменить поведение дефолтного парсера.\nДля этого необходимо реализовать class имплементирующий интерфейс `ISearchParamsParser`:\n```ts\ntype CustomParsedSearchParams = Record;\n\n// import { ISearchParamsParser } from '@astral/mobx-router';\ninterface ISearchParamsParser {\n parse(rawSearchParams: URLSearchParams): CustomParsedSearchParams;\n serialize(searchParams: CustomParsedSearchParams): URLSearchParams;\n}\n```\n\nИ передать его при создании `router`:\n```ts\nnew Router(\n provider,\n routesConfig,\n { searchParamsParser: customParser }\n);\n```\n\nПосле этого searchParams и setSearchParams будут работать с типом `CustomParsedSearchParams`.\n```ts\nrouter.searchParams; // Record\nrouter.setSearchParams; // (searchParams: Record) => void \n```\n\n`SearchParamsStore` также начнет использовать тип, заданный в парсере, и не позволит передать в generic неправильный тип:\n```ts\nrouter.createSearchParamsStore<{ id: number }>(); // Будет ошибка потому что тип должен соответствовать Record\n```\n\n### Сохранение Search параметров при навигации\n\nРоутер предоставляет возможность сохранять существующие search параметры при переходах между маршрутами. \nФункция полезна в сценариях, где нужно сохранить состояние фильтров, сортировок или других параметров\nпри навигации между разными страницами приложения.\n\nДля сохранения параметров, необходимо передать параметр preserveOnNavigate=true и [установить](#установка-значений-set-setall)\nзначения. После редиректа, все параметры, входящие в validationSchema и установленные в URL, будут сохранены \n\n```typescript\ntype SearchParams = {\n id: string;\n redirectUrl: string;\n};\n\nconst searchStore = router.createSearchParamsStore({\n preserveOnNavigate: true,\n validationSchema: {\n id: v.string(),\n redirectUrl: v.string(),\n },\n});\n\nstore.setAll({\n id: '1',\n redirectUrl: '2',\n});\n\nrouter.navigate('/');\n\nrouter.searchParams; // { id: '1', redirectUrl: '2' }\n```\n\nЕсли нужно сохранять только определенные параметры - необходимо передать их ключи массивом в preserveOnNavigate: \n\n```typescript\ntype SearchParams = {\n id: string;\n redirectUrl: string;\n};\n\nconst searchStore = router.createSearchParamsStore({\n preserveOnNavigate: ['redirectUrl'],\n validationSchema: {\n id: v.string(),\n redirectUrl: v.string(),\n },\n});\n\nstore.setAll({\n id: '1',\n redirectUrl: '2',\n});\n\nrouter.navigate('/');\n\nrouter.searchParams; // { redirectUrl: '2' }\n```\n#### Сброс сохраненного параметра\n\nПосле сброса сохраненного параметра, он более не будет сохраняться при переходах.\n\n#### Сохранение при перезагрузке страницы\n\nЧтобы при перезагрузке страницы preserveOnNavigate параметры продолжали сохраняться при навигации, SearchParamsStore,\nинициализирующий их сохранение должен создаваться глобально.\n\n#### Особенности реализации\n\nМеханизм сохранения search параметров основан на blocker, необходимо учитывать особенности его реализации\n\n### Debug\n\nЕсли возникают проблемы установки значений - включите [debug режим](#debug).\n\n### Особенности реализации\n\n#### SearchParams устанавливаются синхронно\n\nМетоды `setSearchParams`, `setAll`, `set` устанавливают значения синхронно.\n\n```typescript\nrouter.searchParams; // {}\nrouter.setSearchParams({ test: 1 });\nrouter.searchParams; // { test: 1 }\n```\n\nВ отличии от `navigate`:\n```typescript\nrouter.location.pathname; // /main\nrouter.navigate('/user');\nrouter.location.pathname; // /user\n```\n\n## Location\n\n### Свойство `location`\n\nРоутер предоставляет реактивное свойство `location`, которое автоматически обновляется при изменении URL в браузере.\n\n```typescript\ntype Location = {\n pathname: string; // Текущий путь (например, '/dashboard')\n search?: string; // Query параметры (например, '?id=123')\n hash?: string; // Hash фрагмент (например, '#section')\n};\n```\n\n### Типобезопасная навигация\n\nДля типобезопасной навигации используйте предопределенные routes.\n\nСм. раздел [Использование routes](#использование-routes) для подробной информации о навигации по routes.\n\n## Блокировка маршрутов (blocker)\n\n#### Базовая концепция\n\n`router.createBlocker(shouldBlock)` создаёт блокер. **Не забудьте его активировать**.\n\n`shouldBlock(nextLocation)` — функция, которая возвращает true, если переход нужно остановить и false если его нужно продолжить.\n\nКогда переход заблокирован, `blocker.isBlocked === true`.\n\nДля управления блокировкой используются методы: `activate`, `proceed`, `reset`, `destroy`\n\n#### Пример использования\n\n```typescript\nimport { makeAutoObservable } from 'mobx';\nimport type { Router } from '#shared';\n\nclass UIStore {\n private readonly blocker;\n \n public isDirty: boolean = false;\n \n public showModal: boolean = false;\n\n public constructor(private readonly _router: Router) {\n makeAutoObservable(this, {}, {autoBind: true});\n\n /**\n * Создаём блокер, который будет перехватывать навигацию.\n * Функция обратного вызова вызывается перед каждым переходом.\n * Если возвращается true — переход блокируется.\n */\n this.blocker = this._router.createBlocker((nextLocation) => {\n const isBlocked = this.isDirty;\n\n if(isBlocked) {\n this.openModal();\n }\n\n return isBlocked;\n });\n }\n \n public mount = () => {\n this.blocker.activate();\n };\n\n public unmount = () => {\n this.blocker.destroy();\n };\n\n private openModal = () => {\n this.showModal = true;\n };\n \n public confirm = () => {\n // Продолжаем переход на заблокированный маршрут\n this.blocker.proceed();\n };\n \n public cancel = () => {\n // Снимаем блокировку и остаемся на текущей странице\n this.blocker.reset();\n };\n}\n\nconst Component = observer(() => {\n const [store] = useState(createUIStore);\n\n useEffect(() => {\n store.mount();\n\n return () => {\n store.unmount();\n };\n }, []);\n});\n```\n\n### Особенности реализации\n\n**React Router v6 и v7**: Блокеры, созданные через `createBlocker`, не будут работать одновременно с хуком `useBlocker`.\nЕсли вы используете `useBlocker`, необходимо полностью полагаться на него для управления блокировкой переходов, или использовать подход через метод `createBlocker`\n\n**Next.js**: Для блокировки навигации используется выброс исключения `throw new Error` при попытке перехода на заблокированный маршрут.\nЭто позволяет остановить переход до того, как **NextRouter** выполнит смену URL.\n\n### Активация блокера\n\nКаждый блокер должен быть активирован перед началом работы.\n\n```typescript\nblocker.activate();\n```\n\n#### Использование в компоненте\n\nПри использовании блокера в компоненте, его необходимо активировать и деактивировать в useEffect:\n\n```tsx\nuseEffect(() => {\n blocker.activate();\n\n return () => {\n blocker.destroy();\n };\n}, []);\n```\n\n**Если этого не сделать, то в Strict Mode будут проблемы в работе блокера**\n\n#### Глобальный store\n\nПри использовании блокера вне компонента его можно активировать сразу в конструкторе класса:\n```typescript\nclass GlobalStore {\n constructor(private readonly _router: Router) {\n this.blocker = this._router.createBlocker((nextLocation) => {\n return nextLocation.pathname === '/main';\n });\n\n this.blocker.activate();\n }\n}\n```\n\n\n### Состояние блокировки\n\nblocker.isBlocked является observable\n\n```typescript\nconst blocker = router.createBlocker((nextLocation) => {\n return nextLocation.pathname === '/main'\n})\n\nrouter.navigate('/main')\n\nblocker.isBlocked // true\n```\n\n### Управления блокировкой\n\n```typescript\n// Активировать блокировку\nblocker.activate()\n\n// Продолжить переход на заблокированный маршрут.\nblocker.proceed() \n\n// Отменить переход и остаться на текущей странице.\nblocker.reset()\n\n// Удалить блокер\nblocker.destroy()\n```\n\n### Работа с несколькими блокерами\n\nМожно создавать несколько блокеров одновременно. Навигация будет заблокирована, если хотя бы один из активных блокеров запретит переход на другую страницу.\nКаждый блокер имеет свое независимое состояние `isBlocked`\n\n```typescript\nconst blockMain = router.createBlocker((next) => next.pathname === '/main');\nblockMain.activate();\n\nconst blockUsers = router.createBlocker((next) => next.pathname === '/users');\nblockUsers.activate();\n\nrouter.navigate('/users'); // переход заблокирован\nrouter.navigate('/settings'); // переход разрешён\n```\n\n### Управление жизненным циклом (destroy)\n\nКаждый блокер подписывается на события изменения маршрута. Необходимо удалять его, если он больше не используется.\n\nЕсли не вызывать `destroy`, блокер продолжит слушать изменения маршрутов, что может привести к непредсказуемому поведению в навигации.\n\n```typescript\nconst blocker = router.createBlocker((nextLocation) => nextLocation.pathname === '/main');\n\nblocker.activate();\n\nblocker.destroy(); // снимает все подписки и очищает внутренние ссылки\n```\n\n## MatchPath - Сопоставление маршрутов\n\nФункция `matchPath` позволяет получить детальную информацию о текущем маршруте и извлечь параметры из URL. Это мощный инструмент для анализа URL и получения метаданных о совпадении паттерна маршрута с текущим путем.\n\n### API\n\n#### Синтаксис\n\n```typescript\nrouter.matchPath(pattern: MatchPathPattern | string, path: string): MatchPathInfo | null\n```\n\n#### Параметры\n\n- `pattern` - Паттерн маршрута (строка или объект `MatchPathPattern`)\n - При передаче строки используется точное сопоставление (`isExact: true` по умолчанию)\n - При передаче объекта `MatchPathPattern` можно указать `isExact: false` для частичного сопоставления\n- `path` - URL pathname для сопоставления\n\n#### Возвращаемое значение\n\n```typescript\ntype MatchPathInfo = {\n // Динамические параметры из URL.\n // Если опциональный параметр не задан, его значение равно undefined\n params: Record;\n pathname: string; // Полный совпадающий путь\n pathnameBase: string; // Базовый путь для дочерних маршрутов\n pattern: string; // Исходный паттерн маршрута\n};\n```\n\n### Базовый пример\n\nСамый простой способ использования - сопоставление строкового паттерна с URL:\n\n```typescript\n// Сопоставление простого маршрута\nconst match = router.matchPath('/user/:id', '/user/123');\n// {\n// params: { id: '123' },\n// pathname: '/user/123',\n// pattern: '/user/:id',\n// pathnameBase: '/user/123'\n// }\n\n// Сопоставление с несколькими параметрами\nconst postMatch = router.matchPath('/posts/:category/:id', '/posts/tech/456');\n// {\n// params: { category: 'tech', id: '456' },\n// pathname: '/posts/tech/456',\n// pattern: '/posts/:category/:id',\n// pathnameBase: '/posts/tech/456'\n// }\n\n// Когда сопоставления нет - возвращается null\nconst noMatch = router.matchPath('/user/:id', '/posts/123');\n// null\n```\n\n### Опциональные параметры\n\nСинтаксис паттерна задает провайдер: `:id?` у react-router и `[[id]]` у next.js.\nПуть сопоставляется и с опциональным параметром, и без него; если параметр не задан,\nего значение в `params` равно `undefined`:\n\n```typescript\n// react-router\nrouter.matchPath('/posts/:id?', '/posts/123'); // params: { id: '123' }\nrouter.matchPath('/posts/:id?', '/posts'); // params: { id: undefined }\n\n// next.js\nrouter.matchPath('/posts/[[id]]', '/posts/123'); // params: { id: '123' }\nrouter.matchPath('/posts/[[id]]', '/posts'); // params: { id: undefined }\n```\n\nОпциональный параметр может стоять и в середине паттерна — остальные параметры\nизвлекаются независимо от того, задан он в пути или нет:\n\n```typescript\nconst pattern = '/letters/[[folder]]/[guid]/answer';\n\nrouter.matchPath(pattern, '/letters/f1/abc/answer'); // params: { folder: 'f1', guid: 'abc' }\nrouter.matchPath(pattern, '/letters/abc/answer'); // params: { folder: undefined, guid: 'abc' }\n```\n\nЕсли опциональных параметров несколько, а в пути задано меньше значений, значения\nдостаются первым по порядку:\n\n```typescript\nrouter.matchPath('/letters/[[first]]/[[second]]', '/letters/abc');\n// params: { first: 'abc', second: undefined }\n```\n\nПо URL невозможно определить, какой именно из опциональных параметров не задан, поэтому\nдля сценария «задан только второй» нужен разделяющий статический сегмент или отдельный route.\n\n### Полное сопоставление `isExact`\n\nПо умолчанию `isExact` равен `true`, что означает точное сопоставление пути.\n\nДля более точного контроля над сопоставлением используйте объект `MatchPathPattern`:\n\n```typescript\n// Точное сопоставление (значение по умолчанию)\nconst exactMatch = router.matchPath(\n { path: '/user/:id' }, \n '/user/123'\n);\n// {\n// params: { id: '123' },\n// pathname: '/user/123',\n// pattern: '/user/:id',\n// pathnameBase: '/user/123'\n// }\n\n// Частичное сопоставление (isExact: false)\nconst partialMatch = router.matchPath(\n { path: '/user', isExact: false }, \n '/user/123/settings'\n);\n// {\n// params: {},\n// pathname: '/user/123/settings',\n// pattern: '/user',\n// pathnameBase: '/user'\n// }\n```\n\n### Сопоставление с wildcard\n\n```typescript\n// Сопоставит любые пути, начинающиеся с '/posts/'\nconst wildcardMatch = router.matchPath(\n { path: '/posts/*' }, \n '/posts/tech/123/comments'\n);\n// {\n// params: {},\n// pathname: '/posts/tech/123/comments',\n// pattern: '/posts/*',\n// pathnameBase: '/posts'\n// }\n```\n\n## Location\n\n`router.location` - это MobX observable.\n\n### API\n\n```typescript\ntype Location = {\n pathname: string; // Текущий путь (например, '/dashboard')\n search?: string; // Query параметры (например, '?id=123&tab=settings')\n hash?: string; // Hash фрагмент (например, '#section')\n state?: NavigationState; \n};\n```\n\n### pathname\n\nОсновное свойство `pathname` содержит текущий путь URL без query параметров и hash фрагмента.\n\n#### Примеры использования\n\n```typescript\n// Получение текущего пути\nconst currentPath = router.location.pathname;\nconsole.log(currentPath); // '/user/123'\n```\n\n#### Реактивное использование с MobX\n\n```typescript\nimport { makeAutoObservable } from 'mobx';\n\nclass NavigationStore {\n constructor(private readonly _router: Router) {\n makeAutoObservable(this);\n }\n\n // Computed свойства на основе pathname\n get isAdminPage() {\n return this._router.location.pathname.startsWith('/admin');\n }\n}\n```\n\n## Подписка на события маршрутизации\n\nМетоды `subscribeRouteChangeStart` и `subscribeRouteChangeEnd` позволяют подписываться на начало и окончание навигации.\n\n#### Особенности реализации\n\n- Начало навигации (subscribeRouteChangeStart) — вызывается сразу после инициирования перехода на новый маршрут, до фактической активации/рендера компонентов.\n- Окончание навигации (subscribeRouteChangeEnd) — вызывается после успешного завершения перехода и рендера нового маршрута.\n\n### API\n\n#### Синтаксис\n\n```typescript\nconst disposeStart = router.subscribeRouteChangeStart(handler: (location: Location) => void): () => void;\nconst disposeEnd = router.subscribeRouteChangeEnd(handler: (location: Location) => void): () => void;\n```\n\n#### Параметры\n\n- `handler` - функция-обработчик, которая будет вызвана с объектом [Location](#location) или строкой `url`:\n - для `subscribeRouteChangeStart` — при начале навигации\n - для `subscribeRouteChangeEnd` — после завершения навигации\n\n#### Возвращаемое значение\n\nФункция `subscribeRouteChangeStart` и `subscribeRouteChangeEnd` возвращает функцию `dispose`, которая отписывает обработчик от событий.\n\n#### Примеры использования\n\n```typescript\n// Подписка на начало перехода:\nconst disposeStart = router.subscribeRouteChangeStart((location) => {\n console.log('Начинается переход на:', location.pathname);\n});\n\n// Отписка от события перехода:\ndisposeStart();\n\n// Подписка на окончание перехода:\nconst disposeEnd = router.subscribeRouteChangeEnd((location) => {\n console.log('Переход завершён:', location.pathname);\n});\n\n// Отписка от события перехода:\ndisposeEnd();\n```\n\n## Debug\n\nВ debug режиме router будет логировать внутренние операции.\n\n```typescript\nconst router = new MobxRouter(\n provider,\n routesConfig,\n { logLevel: 'debug' },\n);\n```\n\n## Тестирование\n\n\n\nДля мока роутера используйте `createRouterMockFactory`.\n\n`RouterMock` полностью эмулирует поведение реального роутера в памяти, сохраняя реактивность и особенности поведения (например, асинхронный `navigate`).\n\n`RouterMock` создается на основе реального роутера, что позволяет переиспользовать его конфигурацию и маршруты.\n\n### Фабрика `createRouterMock` (задается один раз)\n\n```shared/services/Router/Router.ts```\n```typescript\nimport { MobxRouter } from '@astral/mobx-router';\n\nconst routesConfig = {\n home: MobxRouter.defineRoute({\n pattern: '/home',\n }),\n};\n\nexport const router = new MobxRouter(reactRouterProvider, routesConfig);\n```\n\n```shared/tests/RouterMock/RouterMock.ts```\n```typescript\nimport { createRouterMockFactory } from '@astral/mobx-router';\n\nimport { router } from '#shared/services/Router';\n\nexport const createRouterMock = createRouterMockFactory(router);\n```\n\n### Использование `routerMock`\n\n#### Для каждого теста свой routerMock instance\n\n```ts\nconst setup = () => {\n const routerMock = createRouterMock();\n\n const sut = new Store(routerMock);\n};\n```\n\n#### Проверка состояния location, searchParams, routeParams\n\n```ts\nexpect(routerMock.location.pathname).toBe('/main');\n\nexpect(routerMock.searchParams).toBeEqual({ page: 1 });\n```\n\n#### Initial path, searchParams, routeParams\n\n```ts\ncreateRouterMock({\n initialLocation: { pathname: '/main/:userId' },\n searchParams: { page: 1 }\n});\n```\n\n#### Ожидание завершения navigate\n\n```ts\nawait routerMock.waitNavigation();\n```\n\n#### Изменение location\n\n```ts\nawait routerMock.navigateAsync('/main/123')\n```\n\n#### Изменение searchParams\n\n```ts\nrouter.setSearchParams({ page: 1 });\n```\n\n#### SearchParamsStore\n\n`SearchParamsStore` получает состояние из `router.searchParams`: установка значений через `router.setSearchParams` установит `values` и в `SearchParamsStore`.\n","readmeFilename":"README.md"}
![](\"https://storage.yandexcloud.net/astral-frontend/mobx-router-logo.png\"){kind=logo}
![](\"https://storage.yandexcloud.net/astral-frontend/mobx-router-record.png\")
\n \n