reactive-route 0.0.1-alpha.29 → 0.0.1-alpha.30

package/vitepress/guide/router-configuration.md

@@ -1,185 +0,0 @@
-# Router Configuration
-
-The router is the central piece that manages the state of the router and provides methods for navigation. It's created using the `createRouter` function.
-
-## Creating a Router Store
-
-```typescript [router.ts]
-import { createRouter } from 'reactive-route';
-import { adapters } from 'reactive-route/adapters/{reactive-system}';
-
-const routes = createRoutes({ 
-  // ...your config 
-});
-
-//  If you prefer Context and SSR
-export function getRouter() {
-  return createRouter({ routes, adapters });
-}
-
-//  If you prefer singletons
-export const router = createRouter({ routes, adapters })
-```
-
-The `createRouter` function accepts an object with the following properties:
-
-| Property          | Type                              | Description                                                |
-|-------------------|-----------------------------------|------------------------------------------------------------|
-| `routes`          | `ReturnType<typeof createRoutes>` | The routes configuration                                   |
-| `adapters`        | `TypeAdapters`                    | Adapters for the state management system                   |
-| `lifecycleParams` | `Array<any>`                      | Built-in DI for `beforeEnter` and `beforeLeave` (optional) |
-
-You may pass your own adapters if they satisfy the model
-
-```typescript
-type TypeAdapters = {
-  batch: (cb: () => void) => void;
-  autorun: (cb: () => void) => any;
-  replaceObject: <TObj extends Record<string, any>>(obj: TObj, newObj: TObj) => void;
-  makeObservable: <TObj extends Record<string, any>>(obj: TObj) => TObj;
-  observer?: (comp: any) => any;
-};
-```
-
-## Router API
-
-The router store provides several methods for navigation and state management:
-
-| Property            | Type                                            | Description                  |
-|---------------------|-------------------------------------------------|------------------------------|
-| `currentRoute`      | `TypeCurrentRoute<typeof routes['routeKey']>`   | The current route data       |
-| `routesHistory`     | `Array<string>`                                 | The history of visited paths |
-| `isRedirecting`     | `boolean`                                       | The indicator of redirecting |
-| `redirect`          | `(config: TypeRedirectToParams): Promise<void>` | The navigation function      |
-| `restoreFromURL`    | `(params: { pathname: string }): Promise<void>` | To restore from url          |
-| `restoreFromServer` | `(obj: TypeRouter): Promise<void>`              | To restore from object       |
-| `routes`            | `ReturnType<typeof createRoutes>`               | Routes configuration         |
-| `lifecycleParams`   | `Array<any>`                                    | Custom lifecycle parameters  |
-
-### redirect
-
-Navigates to a specified route:
-
-```typescript
-await router.redirect({
-  route: 'about',
-  // with dynamic parameters
-  params: { id: '123' },
-  // with query parameters
-  query: { q: 's' },
-  // if you want to replace history state instead of pushing
-  replace: true,
-});
-```
-
-This function is fully TypeScript-typed, and TypeScript hints will be shown for autocomplete.
-
-```typescript
-const routes = createRoutes({
-  static: {
-    path: '/static',
-    loader: () => import('./pages/static'),
-  },
-  dynamic: {
-    path: '/page/:foo',
-    params: {
-      foo: (value: string) => value.length > 0,
-    },
-    query: {
-      q: (value: string) => value.length > 0,
-    },
-    loader: () => import('./pages/dynamic'),
-  },
-  
-  // other routes
-});
-
-// Good
-redirect({ route: 'static' })
-redirect({ route: 'dynamic', params: { foo: 'bar' } })
-redirect({ route: 'dynamic', params: { foo: 'bar' }, query: { q: 's' } })
-
-// TS errors
-redirect({ });
-redirect({ route: 'nonExisting' });
-redirect({ route: 'static', params: {} });
-redirect({ route: 'dynamic' });
-redirect({ route: 'dynamic', params: {} });
-redirect({ route: 'dynamic', params: { a: 'b' } });
-redirect({ route: 'dynamic', params: { foo: 'bar' }, query: { some: 'value' } });
-```
-
-### restoreFromURL
-
-Initializes the basic route from the current URL:
-
-```typescript
-// Client-side
-await router.restoreFromURL({
-  pathname: location.pathname + location.search,
-});
-
-// Server-side
-await router.restoreFromURL({
-  // use your framework's way to get the full path + search
-  pathname: req.originalUrl,
-});
-```
-
-### restoreFromServer
-
-Initializes the basic route from an object, for example SSR-prepared data:
-
-```typescript
-await router.restoreFromServer({ routesHistory, currentRoute });
-```
-
-### currentRoute
-
-```typescript
-import { TypeCurrentRoute } from 'reactive-route';
-
-const currentRoute = router.currentRoute 
-  as TypeCurrentRoute<typeof router.routes.dynamic>;
-```
-
-The current route object has the following properties:
-
-| Property   | Type                                                  | Description                                                       |
-|------------|-------------------------------------------------------|-------------------------------------------------------------------|
-| `name`     | `string (keyof typeof routes)`                        | The name of the route                                             |
-| `path`     | `string (typeof routes[keyof typeof routes]['path'])` | The path of the route                                             |
-| `params`   | `Record<string, string>`                              | The parameters of the route                                       |
-| `query`    | `Record<string, string>`                              | The query parameters of the route                                 |
-| `props`    | `Record<string, any>`                                 | The props for the component                                       |
-| `pageId` | `string`                                              | The name of the page, if exported from the page loader (optional) |
-
-Note that TS-typing is static and `currentRoute` is not necessarily this one. When redirecting is finished,
-it will become a new route instance, so if you use `autorun` to track current params, check `currentRoute.name` first.
-
-## isRedirecting
-
-If you need to show loaders on redirects, you may use this parameter. For global loader:
-
-```tsx
-const GlobalHeader = () => {
-  const { router } = useContext(StoreContext);
-  
-  return router.isRedirecting ? <Loader /> : null;
-}
-```
-
-Or for a local one:
-
-```tsx
-const GlobalHeader = () => {
-  const { router } = useContext(StoreContext);
-  
-  return <Button isLoading={router.isRedirecting} />;
-}
-```
-
-## routesHistory
-
-This array includes all the visited paths and may be used for logging or to check from which route
-the user came to the current page.

package/vitepress/guide/routes-configuration.md

@@ -1,191 +0,0 @@
-# Routes Configuration
-
-The router configuration is the heart of Reactive Route. It defines all the routes in your application, their paths, parameters, and behavior.
-
-Use the `createRoutes` function to create a router configuration:
-
-```typescript
-import { createRoutes } from 'reactive-route';
-
-const routes = createRoutes({
-  // Your route definitions go here.
-
-  // These routes are required
-  notFound: {
-    path: '/not-found',
-    loader: () => import('./pages/error'),
-  },
-  internalError: {
-    path: '/internal-error',
-    loader: () => import('./pages/error'),
-  },
-});
-```
-
-## Route Definition
-
-Each route is defined as a key-value pair in the configuration object. The key is the route name, and the value is an object with the route configuration.
-
-| Property      | Type                                             | Description                                                                                           |
-|---------------|--------------------------------------------------|-------------------------------------------------------------------------------------------------------|
-| `path`        | `string`                                         | The URL path for the route. Can include dynamic segments prefixed with `:`                            |
-| `loader`      | `() => Promise<{ default, pageId, ...rest }>`    | A function that returns a Promise resolving to the component (it should be in the **default** export) |
-| `props`       | `Record<string, any>`                            | Static props to pass to the component (optional)                                                      |
-| `params`      | `Record<string, (value: string) => boolean>`     | Validation functions for path parameters (required if route type is Dynamic)                          |
-| `query`       | `Record<string, (value: string) => boolean>`     | Validation functions for query parameters (optional)                                                  |
-| `pageId`      | `string`                                         | An optimization for nested routes to avoid page's rerender (optional)                                 |
-| `beforeEnter` | `(config: TypeLifecycleConfig) => Promise<void>` | Hook called before entering the route (optional)                                                      |
-| `beforeLeave` | `(config: TypeLifecycleConfig) => Promise<void>` | Hook called before leaving the route (optional)                                                       |
-
-## Route Types
-
-### Static Routes
-
-Static routes have fixed paths without parameters:
-
-```typescript
-home: {
-  path: '/',
-  loader: () => import('./pages/Home'),
-}
-```
-
-### Dynamic Routes
-
-Dynamic routes have parameters in their paths, indicated by a colon prefix:
-
-```typescript
-user: {
-  path: '/user/:id',
-  params: {
-    id: (value) => /^\d+$/.test(value), // Validation function
-  },
-  loader: () => import('./pages/User'),
-}
-```
-
-A validation function is required, and if it's not satisfied, the user will be redirected to the "notFound" route.
-If the page is rendered, you can be sure that all the params are validated and present in `router.currentRoute`.
-
-### Routes with Query Parameters
-
-Both Static Routes and Dynamic Routes may have query parameters:
-
-```typescript
-search: {
-  path: '/search',
-  query: {
-    text: (value) => value.length > 0,
-  },
-  loader: () => import('./pages/Search'),
-}
-```
-
-A validation function is required, and if it's not satisfied, the parameter will be inaccessible from the
-store. This means that all query parameters are optional and may be `undefined` in `router.currentRoute`.
-
-## Navigation Guards
-
-Navigation guards allow you to control the navigation flow in your application. Both `beforeEnter` and `beforeLeave` are async functions.
-
-The `beforeEnter` hook is called before entering a route. It can be used to redirect to another route, 
-perform authentication checks, and load data.
-
-The `beforeLeave` hook is called before leaving a route. It can be used to prevent navigation or 
-show a confirmation dialog.
-
-```typescript
-dashboard: {
-  path: '/dashboard', 
-  loader: () => import('./pages/protected'),
-  async beforeEnter(config) {
-    await api.loadUser();
-
-    if (!isAuthenticated()) {
-      return config.redirect({ route: 'login', query: { return: 'dashboard' } });
-    }
-
-    await api.loadDashboard();
-  },
-  async beforeLeave(config) {
-    const hasUnsavedChanges = await api.checkSavedForm();
-
-    if (hasUnsavedChanges) {
-      const confirmed = window.confirm(
-        `You have unsaved changes. Are you sure you want to leave?`
-      );
-
-      if (!confirmed) return config.preventRedirect();
-    }
-
-    if (config.nextRoute.name === 'user') {
-      return config.preventRedirect();
-    }
-  },
-}
-```
-
-Always remember to use `return` with `config.redirect` and `config.preventRedirect` to ensure proper flow control.
-
-Uncaught errors in `beforeEnter` or `beforeLeave` will lead to the rendering of the "internalError" route,
-so it's important to handle errors properly using `try-catch` blocks or `Promise.catch()` methods.
-
-Note that `beforeEnter` is called on dynamic parameter changes, but not called on query changes.
-This behavior may become configurable in future versions.
-
-### Accessing Route Information
-
-The `config` is an object with parameters as follows:
-
-```typescript
-type TypeLifecycleConfig = {
-  nextUrl: string;
-  nextRoute: any;
-  nextPathname: string;
-  nextQuery?: any;
-  nextSearch?: string;
-
-  currentUrl?: string;
-  currentQuery?: any;
-  currentRoute?: any;
-  currentSearch?: string;
-  currentPathname?: string;
-
-  redirect: (params: any) => void;
-  preventRedirect: () => void;
-};
-```
-
-Be careful with `config.redirect` function. It accepts the same route data as `router.redirect`,
-but is not typed. So, if you refactor your routes, TS errors will not be shown here which may lead to
-incorrect redirects.
-
-### Accessing Custom Parameters in Lifecycle Hooks
-
-Both `beforeEnter` and `beforeLeave` support passing custom parameters. These parameters are passed through
-`createRouter({ lifecycleParams })` as will be described in the next section of the documentation.
-
-```typescript
-const routes = createRoutes({
-  dashboard: {
-    path: '/dashboard',
-    loader: () => import('./pages/protected'),
-    async beforeEnter(config, userStore: UserStore, uiStore: UIStore) {
-      if (!userStore.isAuthenticated()) {
-        return config.redirect({ route: 'login' });
-      }
-    },
-    async beforeLeave(config, userStore, uiStore) {
-      console.log(userStore, uiStore);
-    },
-  },
-
-  // Other routes
-});
-
-createRouter({ routes, lifecycleParams: [new UserStore(), new UIStore()] })
-```
-
-This approach may not be necessary for CSR-only projects with singletons, as you can simply import `userStore`
-and `uiStore` directly. However, for SSR projects, it's a powerful helper because you can't use singletons
-in that context, and each store needs to be created for every request.

package/vitepress/guide/solid.md

@@ -1,68 +0,0 @@
-# Solid.js Integration
-
-## Solid.js native reactivity
-
-The relevant imports are as follows
-
-```typescript
-import { Router } from 'reactive-route/solid';
-import { adapters } from 'reactive-route/adapters/solid';
-```
-
-No extra packages or configuration needed.
-
-## Mobx
-
-The relevant imports are as follows
-
-```typescript
-import { Router } from 'reactive-route/solid';
-import { adapters } from 'reactive-route/adapters/mobx-solid';
-```
-
-You should ensure that package `mobx` is installed.
-
-Actually Solid.js has no native integration with MobX. So if you use MobX with Solid.js you probably
-use something like this:
-
-```typescript
-import { Reaction } from 'mobx';
-import { enableExternalSource } from 'solid-js';
-
-let id = 0;
-
-enableExternalSource((fn, trigger) => {
-  const reaction = new Reaction(`mobx@${++id}`, trigger);
-
-  return {
-    track: (x) => {
-      let next;
-      reaction.track(() => (next = fn(x)));
-      return next;
-    },
-    dispose: () => reaction.dispose(),
-  };
-});
-```
-
-... or has better alternatives. Anyway, something like this should be included in your entry file.
-
-## Observable
-
-The relevant imports are as follows
-
-```typescript
-import { Router } from 'reactive-route/solid';
-import { adapters } from 'reactive-route/adapters/kr-observable-solid';
-```
-
-You should ensure that package `kr-observable` is installed.
-
-Be sure to enable integration in your entry file
-
-```typescript
-import { enableObservable } from 'kr-observable/solidjs';
-
-enableObservable();
-```
-

package/vitepress/guide/ssr.md

@@ -1,70 +0,0 @@
-# Server-Side Rendering
-
-For server-side rendering, you need to initialize the router store on both the server and the client.
-Use `renderToString` and `hydrate` from you framework, as well as `escapeAllStrings` and `unescapeAllStrings` -
-for example, from `lodash`. These utilities are not included in `reactive-route`.
-
-### Server
-
-```tsx [server.tsx]
-import { getRouter } from './router';
-import { StoreContext } from './StoreContext';
-import { RedirectError } from 'reactive-route';
-
-express()
-  .get('*', async (req, res) => {
-    const template = fs.readFileSync(templatePath, 'utf-8');
-
-    const router = getRouter();
-
-    try {
-      await router.restoreFromURL({ pathname: req.originalUrl });
-    } catch (error: any) {
-      // The redirects on server-side are made manually, because
-      // we can't manipulate the browser's url and history
-      if (error instanceof RedirectError) {
-        // error.message is a full new path here
-        return res.redirect(error.message);
-      }
-
-      console.error(error);
-
-      return res.status(500).send('Unexpected error');
-    }
-
-    const htmlMarkup = renderToString(
-      <StoreContext.Provider value={{ router }}>
-        <App />
-      </StoreContext.Provider>
-    );
-    
-    // A very simple method of serialization, but sufficient for react-route
-    const storeJS = JSON.parse(JSON.stringify({ router }));
-    const initialData = JSON.stringify(escapeAllStrings(storeJS));
-
-    res.send(
-      template
-        .replace(`<!-- HTML -->`, htmlMarkup)
-        .replace('<!-- INITIAL_DATA -->', initialData)
-    );
-  })
-```
-
-### Client
-
-```tsx [client.tsx]
-import { getRouter } from './router';
-import { StoreContext } from './StoreContext';
-
-const router = getRouter();
-const initialData = unescapeAllStrings(window.INITIAL_DATA);
-
-await router.restoreFromServer(initialData.router);
-
-hydrate(
-  document.getElementById('app'),
-  <StoreContext.Provider value={{ router }}>
-    <App />
-  </StoreContext.Provider>
-);
-```

package/vitepress/index.md

@@ -1,29 +0,0 @@
----
-layout: home
-
-hero:
-  name: "Reactive Route"
-  text: "Framework-agnostic reactive routing"
-  tagline: A lightweight, flexible, and reactive router for React, Preact and Solid.js
-  actions:
-    - theme: brand
-      text: Get Started
-      link: /guide/
-    - theme: alt
-      text: View on GitHub
-      link: https://github.com/dkazakov8/reactive-route
-
-features:
-  - title: Framework Agnostic
-    details: Core routing logic is framework-agnostic, with adapters for React, Preact and Solid.js
-  - title: State Management Integration
-    details: Seamlessly integrates with MobX, Observable, and Solid.js reactivity systems
-  - title: Type Safety
-    details: Built with TypeScript for type safety and better developer experience
-  - title: Config-based
-    details: Define your routes in a simple, declarative configuration object
-  - title: Navigation Guards
-    details: Powerful async beforeEnter and beforeLeave route lifecycle with DI
-  - title: SSR Support
-    details: Full support for server-side rendering in any supported framework
----

package/vitest.vue.config.mjs

@@ -1,23 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    projects: ['packages/vue/vitest.config.mjs' /*, 'packages/vue/vitest.ssr.config.mjs'*/],
-    coverage: {
-      clean: false,
-      enabled: true,
-      provider: 'istanbul',
-      reporter: ['text', ['cobertura', { file: 'core.xml' }]],
-      reportsDirectory: './.nyc_output',
-      include: ['packages/*'],
-      exclude: ['packages/*/test/*', 'packages/shared'],
-    },
-    onConsoleLog(log) {
-      if (log.includes('a is not defined') /*|| log.includes('warn')*/) {
-        return false;
-      }
-
-      return true;
-    },
-  },
-});