@wavelengthusaf/client-router 0.0.1 → 0.0.3

package/src/router/Router.ts

@@ -1,225 +0,0 @@
-import type {
-  CompiledRoute,
-  MatchedRoute,
-  RouteComponent,
-  RouteContext,
-  RouteDefinition,
-  RouteGuard,
-} from '../models/index.ts';
-import { compileRoute, matchRoute } from '../utils/index.ts';
-
-export interface RouterEnv {
-  window?: Window;
-  document?: Document;
-}
-
-export interface RouterOptions {
-  outlet?: HTMLElement;
-  hashMode?: boolean;
-  beforeEach?: RouteGuard;
-}
-
-export class Router {
-  readonly #compiledRoutes: CompiledRoute[];
-  readonly #hashMode: boolean;
-  readonly #outlet: HTMLElement | undefined;
-  readonly #beforeEach?: RouteGuard;
-  #currentComponent?: RouteComponent;
-  readonly #window?: Window;
-  readonly #document?: Document;
-
-  #isStarted: boolean = false;
-
-  constructor(
-    routeDefinitions: RouteDefinition[],
-    routerOptions: RouterOptions = {},
-    env: RouterEnv = {},
-  ) {
-    this.#compiledRoutes = routeDefinitions.map(compileRoute);
-    this.#hashMode = routerOptions.hashMode ?? false;
-
-    if (routerOptions.beforeEach !== undefined) {
-      this.#beforeEach = routerOptions.beforeEach;
-    }
-
-    if (env.window !== undefined) {
-      this.#window = env.window;
-    }
-
-    if (env.document !== undefined) {
-      this.#document = env.document;
-    }
-
-    this.#outlet = routerOptions.outlet ?? this.#document?.body ?? undefined;
-  }
-
-  public start(): void {
-    if (!this.#window?.addEventListener || !this.#document?.addEventListener) {
-      throw new Error('[Router] Invalid environment: missing DOM APIs');
-    }
-
-    if (this.#isStarted) return;
-
-    this.#bindEvents();
-    this.#resolve();
-
-    this.#isStarted = true;
-  }
-
-  public destroy(): void {
-    if (!this.#window || !this.#document) return;
-
-    this.#window.removeEventListener('popstate', this.#handlePopState);
-    this.#document.removeEventListener('click', this.#handleClick);
-
-    this.#currentComponent?.unmount?.();
-    this.#isStarted = false;
-  }
-
-  public navigate(path: string): void {
-    if (!this.#window) return;
-
-    if (this.#hashMode) {
-      this.#window.location.hash = path;
-    } else {
-      this.#window.history.pushState(null, '', path);
-    }
-
-    this.#resolve();
-  }
-
-  public replace(path: string): void {
-    if (!this.#window) return;
-
-    if (this.#hashMode) {
-      this.#window.location.replace('#' + path);
-    } else {
-      this.#window.history.replaceState(null, '', path);
-    }
-
-    this.#resolve();
-  }
-
-  public back(): void {
-    this.#window?.history.back();
-  }
-
-  #bindEvents(): void {
-    this.#window!.addEventListener('popstate', this.#handlePopState);
-    this.#document!.addEventListener('click', this.#handleClick);
-  }
-
-  #handlePopState = (): void => {
-    this.#resolve();
-  };
-
-  #handleClick = (event: MouseEvent): void => {
-    const target = event.target as Element | null;
-    const anchor = target?.closest?.('a') as HTMLAnchorElement | null;
-
-    if (!anchor) return;
-
-    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
-      return;
-
-    if (anchor.target === '_blank') return;
-
-    const href: string | null = anchor.getAttribute('href');
-
-    if (!href) return;
-
-    if (
-      href.startsWith('http') ||
-      href.startsWith('//') ||
-      href.startsWith('mailto:') ||
-      href.startsWith('tel:')
-    ) {
-      return;
-    }
-
-    event.preventDefault();
-    this.navigate(href);
-  };
-
-  #currentPath(): string {
-    if (!this.#window) return '/';
-
-    if (this.#hashMode) {
-      const hash: string = this.#window.location.hash.slice(1);
-      return hash || '/';
-    }
-
-    return this.#window.location.pathname || '/';
-  }
-
-  #currentQuery(): URLSearchParams {
-    if (!this.#window) return new URLSearchParams();
-
-    if (this.#hashMode) {
-      const hash = this.#window.location.hash;
-      const queryIndex = hash.indexOf('?');
-
-      if (queryIndex >= 0) {
-        return new URLSearchParams(hash.slice(queryIndex));
-      }
-
-      return new URLSearchParams();
-    }
-
-    return new URLSearchParams(this.#window.location.search);
-  }
-
-  #mount(routeComponent: RouteComponent, routeContext: RouteContext): void {
-    if (!this.#outlet) return;
-
-    this.#currentComponent?.unmount?.();
-
-    this.#outlet.replaceChildren();
-
-    routeComponent.mount(this.#outlet, routeContext);
-
-    this.#currentComponent = routeComponent;
-  }
-
-  #resolve(): void {
-    const pathname: string = this.#currentPath();
-    const query: URLSearchParams = this.#currentQuery();
-
-    const match: MatchedRoute | null = matchRoute(
-      this.#compiledRoutes,
-      pathname,
-    );
-
-    if (!match) {
-      console.warn(`[Router] No route matched: ${pathname}`);
-      return;
-    }
-
-    const context: RouteContext = {
-      path: pathname,
-      routeParams: match.routeParams,
-      query,
-    };
-
-    if (!this.#beforeEach) {
-      this.#mount(match.routeDefinition.routeComponent, context);
-      return;
-    }
-
-    let redirected: boolean = false;
-
-    const next = (redirect?: string): void => {
-      if (redirected) return;
-
-      redirected = true;
-
-      if (redirect && redirect !== context.path) {
-        this.navigate(redirect);
-      } else {
-        this.#mount(match.routeDefinition.routeComponent, context);
-      }
-    };
-
-    this.#beforeEach(context, next);
-  }
-}

package/src/router/__tests__/Router.test.ts

@@ -1,464 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from 'vitest';
-import { Router } from '../Router.ts';
-import { matchRoute } from '../../utils/index.ts';
-
-/* eslint-disable  @typescript-eslint/no-explicit-any */
-vi.mock('../../utils/index.ts', () => ({
-    compileRoute: vi.fn((route) => ({ ...route, compiled: true })),
-    matchRoute: vi.fn(),
-}));
-
-const mockedMatchRoute = vi.mocked(matchRoute);
-
-const createMockWindow = (overrides: any = {}) => {
-    const state = {
-        pathname: overrides.pathname ?? '/',
-        search: overrides.search ?? '',
-        hash: overrides.hash ?? '',
-    };
-
-    return {
-        location: {
-            get pathname() { return state.pathname; },
-            get search() { return state.search; },
-            get hash() { return state.hash; },
-            set hash(v: string) { state.hash = v; },
-            replace: vi.fn((path: string) => {
-                state.hash = path.startsWith('#') ? path.slice(1) : path;
-            }),
-        },
-        history: {
-            pushState: vi.fn((data: any, title: string, url: string) => {
-                state.pathname = url;
-            }),
-            replaceState: vi.fn((data: any, title: string, url: string) => {
-                state.pathname = url;
-            }),
-            back: vi.fn(),
-        },
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-    } as unknown as Window;
-};
-
-const createMockDocument = (overrides: any = {}) => {
-    return {
-        body: { replaceChildren: vi.fn(), appendChild: vi.fn() },
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-        ...overrides,
-    } as unknown as Document;
-};
-
-const createEnv = (url = 'http://localhost/') => {
-    const currentUrl = new URL(url);
-
-    return {
-        window: {
-            location: {
-                get pathname() { return currentUrl.pathname; },
-                get search() { return currentUrl.search; },
-                get hash() { return currentUrl.hash; },
-                set hash(v: string) { currentUrl.hash = v; },
-                replace: vi.fn((v: string) => { currentUrl.hash = v; }),
-            },
-            history: {
-                pushState: vi.fn((_, __, path) => {
-                    const next = new URL(path, currentUrl.origin);
-                    currentUrl.pathname = next.pathname;
-                    currentUrl.search = next.search;
-                }),
-                back: vi.fn(),
-            },
-            addEventListener: vi.fn(),
-            removeEventListener: vi.fn(),
-        } as unknown as Window,
-        document: createMockDocument()
-    };
-};
-
-describe('Router', () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-    });
-
-    describe('Initialization & Environment Checks', () => {
-        it('throws when DOM APIs are missing in start()', () => {
-            // @ts-expect-error (passing wrong parameters)
-            const router = new Router([], {}, { window: undefined, document: undefined });
-            expect(() => router.start()).toThrow('[Router] Invalid environment: missing DOM APIs');
-        });
-
-        it('throws when objects exist but lack addEventListener', () => {
-            const router = new Router([], {}, { window: {} as Window, document: createMockDocument() });
-            expect(() => router.start()).toThrow('[Router] Invalid environment: missing DOM APIs');
-        });
-
-        it('gracefully exits early if methods are called in an SSR environment', () => {
-            // @ts-expect-error (passing wrong parameters)
-            const router = new Router([], {}, { window: undefined, document: undefined });
-            expect(() => router.navigate('/home')).not.toThrow();
-            expect(() => router.replace('/home')).not.toThrow();
-            expect(() => router.back()).not.toThrow();
-            expect(() => router.destroy()).not.toThrow();
-        });
-
-        it('falls back to document.body if outlet is completely omitted', () => {
-            const mockDoc = createMockDocument();
-            const router = new Router([], {}, { window: createMockWindow(), document: mockDoc });
-
-            const mountSpy = vi.fn();
-            mockedMatchRoute.mockReturnValue({
-                // @ts-expect-error (passing wrong parameters)
-                routeDefinition: { routeComponent: { mount: mountSpy, unmount: vi.fn() } },
-                routeParams: {},
-            });
-
-            router.start();
-            expect(mockDoc.body.replaceChildren).toHaveBeenCalled();
-            expect(mountSpy).toHaveBeenCalledWith(mockDoc.body, expect.any(Object));
-        });
-    });
-
-    describe('Lifecycle: start & destroy', () => {
-        it('prevents multiple redundant starts', () => {
-            const win = createMockWindow();
-            const router = new Router([], {}, { window: win, document: createMockDocument() });
-
-            router.start();
-            router.start();
-
-            expect(win.addEventListener).toHaveBeenCalledTimes(1);
-        });
-
-        it('cleans up listeners and unmounts current component on destroy', () => {
-            const win = createMockWindow();
-            const doc = createMockDocument();
-            const unmountSpy = vi.fn();
-
-            mockedMatchRoute.mockReturnValue({
-                // @ts-expect-error (passing wrong parameters)
-                routeDefinition: { routeComponent: { mount: vi.fn(), unmount: unmountSpy } },
-                routeParams: {},
-            });
-
-            const router = new Router([], {}, { window: win, document: doc });
-            router.start();
-            router.destroy();
-
-            expect(win.removeEventListener).toHaveBeenCalledWith('popstate', expect.any(Function));
-            expect(doc.removeEventListener).toHaveBeenCalledWith('click', expect.any(Function));
-            expect(unmountSpy).toHaveBeenCalledTimes(1);
-        });
-
-        it('allows restart after destruction', () => {
-            const win = createMockWindow();
-            const router = new Router([], {}, { window: win, document: createMockDocument() });
-
-            router.start();
-            router.destroy();
-            router.start();
-
-            expect(win.addEventListener).toHaveBeenCalledTimes(2);
-        });
-
-        it('throws an error if window or document are missing during start', () => {
-            const router = new Router([], {}, {});
-
-            expect(() => {
-                router.start();
-            }).toThrow('[Router] Invalid environment: missing DOM APIs');
-
-            expect(mockedMatchRoute).not.toHaveBeenCalled();
-        });
-
-        it('handles destruction when component lacks an unmount method', () => {
-            const env = createEnv();
-            mockedMatchRoute.mockReturnValue({
-                routeDefinition: { routeComponent: { mount: vi.fn() } } as any,
-                routeParams: {},
-            });
-
-            const router = new Router([], {}, env);
-            router.start();
-            expect(() => router.destroy()).not.toThrow();
-        });
-
-        it('does not throw if the current component lacks an unmount method', () => {
-            const mountSpy1 = vi.fn();
-            const mountSpy2 = vi.fn();
-
-            mockedMatchRoute
-                .mockReturnValueOnce({
-                    // @ts-expect-error (passing wrong parameters)
-                    routeDefinition: { routeComponent: { mount: mountSpy1 } }, // unmount is missing
-                    routeParams: {},
-                })
-                .mockReturnValueOnce({
-                    // @ts-expect-error (passing wrong parameters)
-                    routeDefinition: { routeComponent: { mount: mountSpy2, unmount: vi.fn() } },
-                    routeParams: {},
-                });
-
-            const router = new Router([], {}, { window: createMockWindow(), document: createMockDocument() });
-
-            router.start();
-
-            expect(() => router.navigate('/next')).not.toThrow();
-            expect(mountSpy2).toHaveBeenCalled();
-        });
-    });
-
-    describe('Navigation Methods', () => {
-        describe.each([
-            { hashMode: true },
-            { hashMode: false },
-        ])('Mode: hashMode=$hashMode', ({ hashMode }) => {
-            it('navigates via pushState or hash assignment', () => {
-                const win = createMockWindow();
-                const router = new Router([], { hashMode }, { window: win, document: createMockDocument() });
-
-                router.navigate('/path');
-
-                if (hashMode) {
-                    expect(win.location.hash).toBe('/path');
-                } else {
-                    expect(win.history.pushState).toHaveBeenCalledWith(null, '', '/path');
-                }
-            });
-
-            it('replaces via replaceState or location replace', () => {
-                const win = createMockWindow();
-                const router = new Router([], { hashMode }, { window: win, document: createMockDocument() });
-
-                router.replace('/path');
-
-                if (hashMode) {
-                    expect(win.location.replace).toHaveBeenCalledWith('#/path');
-                } else {
-                    expect(win.history.replaceState).toHaveBeenCalledWith(null, '', '/path');
-                }
-            });
-        });
-
-        it('triggers history.back()', () => {
-            const win = createMockWindow();
-            const router = new Router([], {}, { window: win, document: createMockDocument() });
-            router.back();
-            expect(win.history.back).toHaveBeenCalled();
-        });
-    });
-
-    describe('Click Handling', () => {
-        const createClickEvent = (config: any) => ({
-            target: {
-                closest: vi.fn((selector) => {
-                    if (selector === 'a' && config.isAnchor !== false) {
-                        return {
-                            target: config.target || '',
-                            getAttribute: vi.fn().mockReturnValue(config.href),
-                        };
-                    }
-                    return null;
-                }),
-            },
-            preventDefault: vi.fn(),
-            metaKey: !!config.metaKey,
-            ctrlKey: !!config.ctrlKey,
-            shiftKey: !!config.shiftKey,
-            altKey: !!config.altKey,
-        } as unknown as MouseEvent);
-
-        it.each([
-            ['Ignored: Not an anchor', { isAnchor: false }, false],
-            ['Ignored: Modifier Meta', { href: '/foo', metaKey: true }, false],
-            ['Ignored: Modifier Ctrl', { href: '/foo', ctrlKey: true }, false],
-            ['Ignored: Modifier Shift', { href: '/foo', shiftKey: true }, false],
-            ['Ignored: Modifier Alt', { href: '/foo', altKey: true }, false],
-            ['Ignored: Target _blank', { href: '/foo', target: '_blank' }, false],
-            ['Ignored: No href', { href: null }, false],
-            // eslint-disable-next-line  sonarjs/no-clear-text-protocols
-            ['Ignored: External HTTP', { href: 'http://foo.com' }, false],
-            ['Ignored: External HTTPS', { href: 'https://foo.com' }, false],
-            ['Ignored: External Protocol-Relative', { href: '//foo.com' }, false],
-            ['Ignored: Mailto', { href: 'mailto:a@b.com' }, false],
-            ['Ignored: Tel', { href: 'tel:123' }, false],
-            ['Handled: Valid internal path', { href: '/internal' }, true],
-        ])('%s', (_, config, shouldNavigate) => {
-            const win = createMockWindow();
-            const doc = createMockDocument();
-            const router = new Router([], {}, { window: win, document: doc });
-
-            router.start();
-
-            const clickHandler = vi.mocked(doc.addEventListener).mock.calls.find(c => c[0] === 'click')?.[1] as EventListener;
-            const event = createClickEvent(config);
-
-            clickHandler(event);
-
-            if (shouldNavigate) {
-                expect(event.preventDefault).toHaveBeenCalled();
-                // @ts-expect-error (passing wrong parameters)
-                expect(win.history.pushState).toHaveBeenCalledWith(null, '', config.href);
-            } else {
-                expect(win.history.pushState).not.toHaveBeenCalled();
-            }
-        });
-    });
-
-    describe('Path & Query Parsing', () => {
-        it.each([
-            ['History Mode, empty fallback', false, '', '', '', '/', new URLSearchParams()],
-            ['History Mode, with search', false, '/foo', '?a=1', '', '/foo', new URLSearchParams('?a=1')],
-            ['Hash Mode, empty fallback', true, '/', '', '', '/', new URLSearchParams()],
-            ['Hash Mode, just pound', true, '/', '', '#', '/', new URLSearchParams()],
-            ['Hash Mode, no hash string', true, '/', '', '', '/', new URLSearchParams()],
-            ['Hash Mode, path with no query', true, '/', '', '#/dashboard', '/dashboard', new URLSearchParams()],
-            ['Hash Mode, path only', true, '/', '', '#/bar', '/bar', new URLSearchParams()],
-            ['Hash Mode, path & query', true, '/', '', '#/bar?c=2', '/bar?c=2', new URLSearchParams('?c=2')],
-        ])('%s', (_, hashMode, pathname, search, hash, expectedPath, expectedQuery) => {
-            const win = createMockWindow({ pathname, search, hash });
-            const router = new Router([], { hashMode }, { window: win, document: createMockDocument() });
-
-            mockedMatchRoute.mockReturnValue({
-                // @ts-expect-error (passing wrong parameters)
-                routeDefinition: { routeComponent: { mount: vi.fn(), unmount: vi.fn() } },
-                routeParams: {},
-            });
-
-            router.start();
-
-            // @ts-expect-error (passing wrong parameters)
-            const routeComponent = mockedMatchRoute.mock.results[0].value.routeDefinition.routeComponent;
-            expect(mockedMatchRoute).toHaveBeenCalledWith(expect.any(Array), expectedPath);
-            expect(routeComponent.mount).toHaveBeenCalledWith(
-                expect.any(Object),
-                expect.objectContaining({ path: expectedPath, query: expectedQuery })
-            );
-        });
-    });
-
-    describe('Resolution & Guards (beforeEach)', () => {
-        it('resolves on popstate', () => {
-            const win = createMockWindow();
-            const router = new Router([], {}, { window: win, document: createMockDocument() });
-            router.start();
-
-            const popStateHandler = vi.mocked(win.addEventListener).mock.calls.find(c => c[0] === 'popstate')?.[1] as EventListener;
-            mockedMatchRoute.mockClear();
-
-            popStateHandler(new Event('popstate'));
-            expect(mockedMatchRoute).toHaveBeenCalled();
-        });
-
-        it('logs a warning when no route matches', () => {
-            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-            mockedMatchRoute.mockReturnValue(null);
-
-            const router = new Router([], {}, { window: createMockWindow(), document: createMockDocument() });
-            router.start();
-
-            expect(warnSpy).toHaveBeenCalledWith('[Router] No route matched: /');
-            warnSpy.mockRestore();
-        });
-
-        it('allows direct mount when guard calls next() without arguments', () => {
-            const mountSpy = vi.fn();
-            mockedMatchRoute.mockReturnValue({
-                // @ts-expect-error (passing wrong parameters)
-                routeDefinition: { routeComponent: { mount: mountSpy, unmount: vi.fn() } },
-                routeParams: {},
-            });
-
-            const beforeEachGuard = vi.fn((ctx, next) => next());
-            const router = new Router([], { beforeEach: beforeEachGuard }, { window: createMockWindow(), document: createMockDocument() });
-
-            router.start();
-
-            expect(beforeEachGuard).toHaveBeenCalled();
-            expect(mountSpy).toHaveBeenCalled();
-        });
-
-        it('triggers a redirect when guard provides a new path', () => {
-            const win = createMockWindow();
-            mockedMatchRoute.mockReturnValue({
-                // @ts-expect-error (passing wrong parameters)
-                routeDefinition: { routeComponent: { mount: vi.fn(), unmount: vi.fn() } },
-                routeParams: {},
-            });
-
-            const beforeEachGuard = vi.fn((ctx, next) => next('/login'));
-            const router = new Router([], { beforeEach: beforeEachGuard }, { window: win, document: createMockDocument() });
-
-            router.start();
-            expect(win.history.pushState).toHaveBeenCalledWith(null, '', '/login');
-        });
-
-        it('skips redirect and mounts if redirected path matches current context path', () => {
-            const win = createMockWindow({ pathname: '/login' });
-            const mountSpy = vi.fn();
-            mockedMatchRoute.mockReturnValue({
-                // @ts-expect-error (passing wrong parameters)
-                routeDefinition: { routeComponent: { mount: mountSpy, unmount: vi.fn() } },
-                routeParams: {},
-            });
-
-            const beforeEachGuard = vi.fn((ctx, next) => next('/login'));
-            const router = new Router([], { beforeEach: beforeEachGuard }, { window: win, document: createMockDocument() });
-
-            router.start();
-            expect(win.history.pushState).not.toHaveBeenCalled();
-            expect(mountSpy).toHaveBeenCalled();
-        });
-
-        it('ignores subsequent next(path) calls to prevent redirect loops', () => {
-            const win = createMockWindow({ pathname: '/home' });
-            mockedMatchRoute.mockReturnValue({
-                // @ts-expect-error (passing wrong parameters)
-                routeDefinition: { routeComponent: { mount: vi.fn(), unmount: vi.fn() } },
-                routeParams: {},
-            });
-
-            const beforeEachGuard = vi.fn((ctx, next) => {
-                next('/login');
-                next('/dashboard'); // Secondary attempts should be ignored
-            });
-
-            const router = new Router([], { beforeEach: beforeEachGuard }, { window: win, document: createMockDocument() });
-            router.start();
-
-            expect(win.history.pushState).toHaveBeenCalledTimes(1);
-            expect(win.history.pushState).toHaveBeenCalledWith(null, '', '/login');
-        });
-    });
-
-    describe('Component ComponentMount Lifecycle', () => {
-        it('unmounts the previous component before mounting the new one', () => {
-            const unmountSpy1 = vi.fn();
-            const mountSpy1 = vi.fn();
-            const unmountSpy2 = vi.fn();
-            const mountSpy2 = vi.fn();
-
-            mockedMatchRoute
-                .mockReturnValueOnce({
-                    // @ts-expect-error (passing wrong parameters)
-                    routeDefinition: { routeComponent: { mount: mountSpy1, unmount: unmountSpy1 } },
-                    routeParams: {},
-                })
-                .mockReturnValueOnce({
-                    // @ts-expect-error (passing wrong parameters)
-                    routeDefinition: { routeComponent: { mount: mountSpy2, unmount: unmountSpy2 } },
-                    routeParams: {},
-                });
-
-            const router = new Router([], {}, { window: createMockWindow(), document: createMockDocument() });
-
-            router.start();
-            expect(mountSpy1).toHaveBeenCalled();
-
-            router.navigate('/next');
-            expect(unmountSpy1).toHaveBeenCalled();
-            expect(mountSpy2).toHaveBeenCalled();
-        });
-    });
-});