native-document 1.0.16 → 1.0.17-1.2

package/tests/unit/router/route-matching.test.js

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest';
+import { Route } from '../../../src/router/Route';
+
+const route = (path, options = {}) => new Route(path, () => {}, options);
+
+describe('Route matching', () => {
+
+    // -- exact path -----------------------------------------------------------
+
+    describe('exact path', () => {
+        it('matches an exact path', () => {
+            const r = route('/about');
+            expect(r.match('/about')).toEqual({});
+        });
+
+        it('does not match a different path', () => {
+            const r = route('/about');
+            expect(r.match('/contact')).toBe(false);
+        });
+
+        it('normalizes leading and trailing slashes', () => {
+            const r = route('about/');
+            expect(r.match('about')).toEqual({});
+        });
+
+        it('does not match a partial path', () => {
+            const r = route('/about');
+            expect(r.match('/about/us')).toBe(false);
+        });
+
+        it('matches root path /', () => {
+            const r = route('/');
+            expect(r.match('/')).toEqual({});
+        });
+    });
+
+    // -- :param extraction ----------------------------------------------------
+
+    describe('param extraction', () => {
+        it('extracts a single param', () => {
+            const r = route('/user/{id}');
+            expect(r.match('/user/42')).toEqual({ id: '42' });
+        });
+
+        it('extracts multiple params', () => {
+            const r = route('/user/{userId}/post/{postId}');
+            expect(r.match('/user/1/post/99')).toEqual({ userId: '1', postId: '99' });
+        });
+
+        it('does not match if param segment is missing', () => {
+            const r = route('/user/{id}');
+            expect(r.match('/user/')).toBe(false);
+        });
+
+        it('does not match if extra segments are present', () => {
+            const r = route('/user/{id}');
+            expect(r.match('/user/42/extra')).toBe(false);
+        });
+    });
+
+    // -- typed params ---------------------------------------------------------
+
+    describe('typed params', () => {
+        it('{id:id} matches numeric id', () => {
+            const r = route('/post/{id:id}');
+            expect(r.match('/post/123')).toEqual({ id: '123' });
+        });
+
+        it('{id:id} does not match non-numeric', () => {
+            const r = route('/post/{id:id}');
+            expect(r.match('/post/abc')).toBe(false);
+        });
+
+        it('{lang:lang} matches a two-letter language code', () => {
+            const r = route('/{lang:lang}/home');
+            expect(r.match('/fr/home')).toEqual({ lang: 'fr' });
+        });
+
+        it('{lang:lang} does not match three-letter code', () => {
+            const r = route('/{lang:lang}/home');
+            expect(r.match('/fra/home')).toBe(false);
+        });
+
+        it('{token:token} matches alphanumeric token', () => {
+            const r = route('/token/{value:token}');
+            expect(r.match('/token/abc123_-')).toEqual({ value: 'abc123_-' });
+        });
+
+        it('{n:number} matches integer', () => {
+            const r = route('/page/{n:number}');
+            expect(r.match('/page/5')).toEqual({ n: '5' });
+        });
+
+        it('{n:number} matches float', () => {
+            const r = route('/price/{n:number}');
+            expect(r.match('/price/3.14')).toEqual({ n: '3.14' });
+        });
+    });
+
+    // -- custom param validators ----------------------------------------------
+
+    describe('custom param validators (with)', () => {
+        it('accepts a custom regex pattern via options.with', () => {
+            const r = route('/status/{code}', {
+                with: { code: 'active|inactive|pending' },
+            });
+            expect(r.match('/status/active')).toEqual({ code: 'active' });
+            expect(r.match('/status/unknown')).toBe(false);
+        });
+    });
+
+    // -- url() ----------------------------------------------------------------
+
+    describe('url()', () => {
+        it('generates a URL from params', () => {
+            const r = route('/user/{id}');
+            expect(r.url({ params: { id: 42 } })).toBe('/user/42');
+        });
+
+        it('generates a URL with query string', () => {
+            const r = route('/search');
+            const url = r.url({ query: { q: 'hello', page: '1' } });
+            expect(url).toContain('/search?');
+            expect(url).toContain('q=hello');
+            expect(url).toContain('page=1');
+        });
+
+        it('throws if a required param is missing', () => {
+            const r = route('/user/{id}');
+            expect(() => r.url({ params: {} })).toThrow();
+        });
+
+        it('prepends basePath if provided', () => {
+            const r = route('/about');
+            expect(r.url({ basePath: '/app' })).toBe('/app/about');
+        });
+    });
+
+    // -- route metadata -------------------------------------------------------
+
+    describe('route metadata', () => {
+        it('name() returns the route name', () => {
+            const r = route('/about', { name: 'about' });
+            expect(r.name()).toBe('about');
+        });
+
+        it('name() returns null without a name', () => {
+            const r = route('/about');
+            expect(r.name()).toBeNull();
+        });
+
+        it('path() returns the normalized path', () => {
+            // trim() strips trailing slashes
+            const r = route('/about');
+            expect(r.path()).toBe('/about');
+        });
+
+        it('shouldRebuild() returns false by default', () => {
+            const r = route('/about');
+            expect(r.shouldRebuild()).toBe(false);
+        });
+
+        it('shouldRebuild() returns true when set', () => {
+            const r = route('/about', { shouldRebuild: true });
+            expect(r.shouldRebuild()).toBe(true);
+        });
+    });
+
+});

package/tests/unit/router/router-guards.test.js

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Route } from '../../../src/router/Route';
+import Router from '../../../src/router/Router';
+
+vi.mock('../../../src/core/utils/debug-manager', () => ({
+    default: { log: vi.fn(), warn: vi.fn(), error: vi.fn(), disable: vi.fn() },
+}));
+
+// Test helpers
+const component = () => document.createElement('div');
+
+const makeRouter = (callback) => {
+    const router = new Router({ mode: 'memory' });
+    callback(router);
+    return router;
+};
+
+describe('Router guards (middlewares)', () => {
+
+    // -- middleware execution -------------------------------------------------
+
+    describe('middleware execution', () => {
+        it('middleware is called on route change', () => {
+            const guard = vi.fn((_req, next) => next());
+            const router = makeRouter((r) => {
+                r.add('/home', component, { middlewares: [guard] });
+            });
+            const resolved = router.resolve('/home');
+            router.handleRouteChange(resolved.route, resolved.params, resolved.query, '/home');
+            expect(guard).toHaveBeenCalledOnce();
+        });
+
+        it('middleware receives the request object', () => {
+            let capturedRequest = null;
+            const guard = vi.fn((req, next) => {
+                capturedRequest = req;
+                next();
+            });
+            const router = makeRouter((r) => {
+                r.add('/about', component, { middlewares: [guard] });
+            });
+            const resolved = router.resolve('/about');
+            router.handleRouteChange(resolved.route, {}, {}, '/about');
+            expect(capturedRequest).toMatchObject({ path: '/about' });
+        });
+
+        it('multiple middlewares are called in order', () => {
+            const order = [];
+            const g1 = (_req, next) => { order.push(1); next(); };
+            const g2 = (_req, next) => { order.push(2); next(); };
+            const g3 = (_req, next) => { order.push(3); next(); };
+
+            const router = makeRouter((r) => {
+                r.add('/page', component, { middlewares: [g1, g2, g3] });
+            });
+            const resolved = router.resolve('/page');
+            router.handleRouteChange(resolved.route, {}, {}, '/page');
+            expect(order).toEqual([1, 2, 3]);
+        });
+
+        it('not calling next() stops the chain', () => {
+            const g1 = vi.fn((_req, _next) => {}); // does not call next
+            const g2 = vi.fn((_req, next) => next());
+
+            const router = makeRouter((r) => {
+                r.add('/blocked', component, { middlewares: [g1, g2] });
+            });
+            const resolved = router.resolve('/blocked');
+            router.handleRouteChange(resolved.route, {}, {}, '/blocked');
+            expect(g1).toHaveBeenCalledOnce();
+            expect(g2).not.toHaveBeenCalled();
+        });
+    });
+
+    // -- group middlewares ----------------------------------------------------
+
+    describe('group middlewares', () => {
+        it('group middleware is applied to all routes in the group', () => {
+            const authGuard = vi.fn((_req, next) => next());
+
+            const router = makeRouter((r) => {
+                r.group('/admin', { middlewares: [authGuard] }, () => {
+                    r.add('/dashboard', component);
+                    r.add('/settings', component);
+                });
+            });
+
+            const r1 = router.resolve('/admin/dashboard');
+            router.handleRouteChange(r1.route, {}, {}, '/admin/dashboard');
+
+            const r2 = router.resolve('/admin/settings');
+            router.handleRouteChange(r2.route, {}, {}, '/admin/settings');
+
+            expect(authGuard).toHaveBeenCalledTimes(2);
+        });
+
+        it('group middleware runs before route-level middleware', () => {
+            const order = [];
+            const groupGuard = (_req, next) => { order.push('group'); next(); };
+            const routeGuard = (_req, next) => { order.push('route'); next(); };
+
+            const router = makeRouter((r) => {
+                r.group('/admin', { middlewares: [groupGuard] }, () => {
+                    r.add('/users', component, { middlewares: [routeGuard] });
+                });
+            });
+
+            const resolved = router.resolve('/admin/users');
+            router.handleRouteChange(resolved.route, {}, {}, '/admin/users');
+            expect(order).toEqual(['group', 'route']);
+        });
+    });
+
+    // -- subscribe() ----------------------------------------------------------
+
+    describe('subscribe()', () => {
+        it('listener is called after all middlewares', () => {
+            const listener = vi.fn();
+            const guard = (_req, next) => next();
+
+            const router = makeRouter((r) => {
+                r.add('/home', component, { middlewares: [guard] });
+            });
+            router.subscribe(listener);
+
+            const resolved = router.resolve('/home');
+            router.handleRouteChange(resolved.route, {}, {}, '/home');
+            expect(listener).toHaveBeenCalledOnce();
+        });
+
+        it('unsubscribe stops the listener from being called', () => {
+            const listener = vi.fn();
+            const router = makeRouter((r) => r.add('/home', component));
+            const unsub = router.subscribe(listener);
+            unsub();
+
+            const resolved = router.resolve('/home');
+            router.handleRouteChange(resolved.route, {}, {}, '/home');
+            expect(listener).not.toHaveBeenCalled();
+        });
+
+        it('subscribe throws if argument is not a function', () => {
+            const router = makeRouter((r) => r.add('/home', component));
+            expect(() => router.subscribe('not-a-fn')).toThrow();
+        });
+    });
+
+    // -- resolve() ------------------------------------------------------------
+
+    describe('resolve()', () => {
+        it('resolves a path to a route', () => {
+            const router = makeRouter((r) => r.add('/about', component));
+            const resolved = router.resolve('/about');
+            expect(resolved.route).toBeDefined();
+            expect(resolved.params).toEqual({});
+        });
+
+        it('resolves a named route', () => {
+            const router = makeRouter((r) => {
+                r.add('/about', component, { name: 'about' });
+            });
+            const resolved = router.resolve({ name: 'about' });
+            expect(resolved.route.name()).toBe('about');
+        });
+
+        it('throws for an unknown path', () => {
+            const router = makeRouter((r) => r.add('/home', component));
+            expect(() => router.resolve('/unknown')).toThrow();
+        });
+
+        it('parses query string', () => {
+            const router = makeRouter((r) => r.add('/search', component));
+            const resolved = router.resolve('/search?q=hello&page=2');
+            expect(resolved.query).toMatchObject({ q: 'hello', page: '2' });
+        });
+    });
+
+    // -- currentState() -------------------------------------------------------
+
+    describe('currentState()', () => {
+        it('reflects the current route after handleRouteChange', () => {
+            const router = makeRouter((r) => r.add('/home', component));
+            const resolved = router.resolve('/home');
+            router.handleRouteChange(resolved.route, {}, {}, '/home');
+            expect(router.currentState().path).toBe('/home');
+        });
+    });
+
+});

package/tests/unit/utils/cache.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi } from 'vitest';
+import { once, singleton, memoize } from '../../../src/core/utils/cache';
+
+describe('Cache utilities', () => {
+
+    // -- singleton() ----------------------------------------------------------
+
+    describe('singleton() — once(fn)', () => {
+        it('calls the function on first access', () => {
+            const fn = vi.fn(() => ({ value: 42 }));
+            const get = singleton(fn);
+            get();
+            expect(fn).toHaveBeenCalledOnce();
+        });
+
+        it('returns the same result on subsequent calls', () => {
+            const fn = vi.fn(() => ({ value: 42 }));
+            const get = singleton(fn);
+            const r1 = get();
+            const r2 = get();
+            expect(r1).toBe(r2);
+            expect(fn).toHaveBeenCalledOnce();
+        });
+
+        it('passes arguments to the function on first call', () => {
+            const fn = vi.fn((x) => x * 2);
+            const get = singleton(fn);
+            expect(get(5)).toBe(10);
+            expect(get(99)).toBe(10); // cached result from first call
+        });
+    });
+
+    // -- once() — autoOnce proxy ---------------------------------------------
+
+    describe('once() — autoOnce(fn)', () => {
+        it('calls the factory on first property access', () => {
+            const factory = vi.fn(() => ({ name: 'store', count: 0 }));
+            const proxy = once(factory);
+            const _ = proxy.name;
+            expect(factory).toHaveBeenCalledOnce();
+        });
+
+        it('does not call the factory again on subsequent access', () => {
+            const factory = vi.fn(() => ({ name: 'store' }));
+            const proxy = once(factory);
+            const _a = proxy.name;
+            const _b = proxy.name;
+            expect(factory).toHaveBeenCalledOnce();
+        });
+
+        it('returns the correct property value', () => {
+            const proxy = once(() => ({ x: 10, y: 20 }));
+            expect(proxy.x).toBe(10);
+            expect(proxy.y).toBe(20);
+        });
+
+        it('returns undefined for unknown properties', () => {
+            const proxy = once(() => ({ x: 1 }));
+            expect(proxy.unknown).toBeUndefined();
+        });
+    });
+
+    // -- memoize() — autoMemoize proxy ----------------------------------------
+
+    describe('memoize() — autoMemoize(fn)', () => {
+        // autoMemoize behaviour:
+        // - fn.length === 0 -> calls fn(key), caches and returns the value
+        // - fn.length  >  0 -> returns a memoized (...args) => fn(...args, key)
+
+        it('fn.length === 0 — returns the value directly', () => {
+            // fn ignores key, autoMemoize calls fn(key) and caches the result
+            let callCount = 0;
+            const fn = function() { callCount++; return 'fixed'; };
+            const proxy = memoize(fn);
+            expect(proxy.any).toBe('fixed');
+            expect(callCount).toBe(1);
+        });
+
+        it('fn.length === 0 — caches per key', () => {
+            const calls = [];
+            const fn = function() { return calls.push(fn) && `r${calls.length}`; };
+            const proxy = memoize(fn);
+            const r1 = proxy.home;
+            const r2 = proxy.home;
+            expect(r1).toBe(r2);
+            expect(calls.length).toBe(1);
+        });
+
+        it('fn.length === 0 — independent keys call fn separately', () => {
+            const calls = [];
+            const fn = function() { calls.push(1); return `r${calls.length}`; };
+            const proxy = memoize(fn);
+            const r1 = proxy.home;
+            const r2 = proxy.search;
+            expect(r1).not.toBe(r2);
+            expect(calls.length).toBe(2);
+        });
+
+        it('fn.length > 0 — returns a function per key', () => {
+            // fn(value, key): value is passed by caller, key is appended by autoMemoize
+            const fn = function(value, key) { return `${key}:${value}`; };
+            const proxy = memoize(fn);
+            expect(typeof proxy.fr).toBe('function');
+            expect(proxy.fr('hello')).toBe('fr:hello');
+        });
+
+        it('fn.length > 0 — caches the function per key', () => {
+            let callCount = 0;
+            // fn must have length > 0 — declare at least one param
+            const fn = function(_value, _key) { callCount++; };
+            const proxy = memoize(fn);
+            proxy.fr('hello');
+            // second access to proxy.fr returns the cached wrapper, fn not called again
+            const cached = proxy.fr;
+            expect(typeof cached).toBe('function');
+            expect(callCount).toBe(1);
+        });
+    });
+
+});