@buzola/router 0.0.21 → 0.0.23

package/dist/define/lazy-route.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentType } from 'react';
+type RouteModuleComponent = ComponentType<Record<string, never>>;
+export interface LazyRoute {
+    /** Renders the loaded component, synchronously once the module has loaded. */
+    component: RouteModuleComponent;
+    /** Starts loading the module. Calls share one request; a failed one is retried by the next call. */
+    preload: () => Promise<RouteModuleComponent>;
+}
+/**
+ * A route component loaded on demand, like `React.lazy`, but sharing its request with `preload`.
+ *
+ * `React.lazy` starts its own `import()` the first time it renders, even when the module is already
+ * loaded, and the browser resolves that a task later. React then commits the Suspense fallback and
+ * holds the page back ~300 ms before revealing it. Once loaded, this component renders without suspending.
+ */
+export declare function lazyRoute(load: () => Promise<{
+    default: RouteModuleComponent;
+}>): LazyRoute;
+export {};
+//# sourceMappingURL=lazy-route.d.ts.map

package/dist/define/lazy-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-route.d.ts","sourceRoot":"","sources":["../../src/define/lazy-route.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAyC,MAAM,OAAO,CAAA;AAEjF,KAAK,oBAAoB,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;AAEhE,MAAM,WAAW,SAAS;IACzB,8EAA8E;IAC9E,SAAS,EAAE,oBAAoB,CAAA;IAC/B,oGAAoG;IACpG,OAAO,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAC5C;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC,GAAG,SAAS,CA4B3F"}

package/dist/define/lazy-route.js

@@ -0,0 +1,31 @@
+import { createElement, use } from 'react';
+/**
+ * A route component loaded on demand, like `React.lazy`, but sharing its request with `preload`.
+ *
+ * `React.lazy` starts its own `import()` the first time it renders, even when the module is already
+ * loaded, and the browser resolves that a task later. React then commits the Suspense fallback and
+ * holds the page back ~300 ms before revealing it. Once loaded, this component renders without suspending.
+ */
+export function lazyRoute(load) {
+    let loaded = null;
+    let request = null;
+    let failed = false;
+    const start = () => {
+        failed = false;
+        request = load().then(module => {
+            loaded = module.default;
+            return module.default;
+        }, (error) => {
+            failed = true;
+            throw error;
+        });
+        return request;
+    };
+    const preload = () => (request === null || failed ? start() : request);
+    function LazyRouteComponent() {
+        // A failed request stays failed for rendering, as with `React.lazy`; only `preload` asks again.
+        return createElement(loaded ?? use(request ?? start()));
+    }
+    return { component: LazyRouteComponent, preload };
+}
+//# sourceMappingURL=lazy-route.js.map

package/dist/define/lazy-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-route.js","sourceRoot":"","sources":["../../src/define/lazy-route.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsB,aAAa,EAAqB,GAAG,EAAE,MAAM,OAAO,CAAA;AAWjF;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAsD;IAC/E,IAAI,MAAM,GAAgC,IAAI,CAAA;IAC9C,IAAI,OAAO,GAAyC,IAAI,CAAA;IACxD,IAAI,MAAM,GAAG,KAAK,CAAA;IAElB,MAAM,KAAK,GAAG,GAAkC,EAAE;QACjD,MAAM,GAAG,KAAK,CAAA;QACd,OAAO,GAAG,IAAI,EAAE,CAAC,IAAI,CACpB,MAAM,CAAC,EAAE;YACR,MAAM,GAAG,MAAM,CAAC,OAAO,CAAA;YACvB,OAAO,MAAM,CAAC,OAAO,CAAA;QACtB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YAClB,MAAM,GAAG,IAAI,CAAA;YACb,MAAM,KAAK,CAAA;QACZ,CAAC,CACD,CAAA;QACD,OAAO,OAAO,CAAA;IACf,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,GAAkC,EAAE,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;IAErG,SAAS,kBAAkB;QAC1B,gGAAgG;QAChG,OAAO,aAAa,CAAC,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAA;IACxD,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAA;AAClD,CAAC"}

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export type { BlockerFn, BuzolaNavigateEvent, BuzolaPageMap, BuzolaPersistentPar
 export { s } from './engine/schema.js';
 export { BuzolaRedirect, createPage, redirect } from './define/create-page.js';
 export type { CatchContext, PageDefinition, PageProps, RedirectFn } from './define/create-page.js';
+export { lazyRoute } from './define/lazy-route.js';
+export type { LazyRoute } from './define/lazy-route.js';
 export { BuzolaProvider, ErrorBoundary, Link, Outlet, RouteContext, RouterContext, useBlocker, useInvalidate, useNavigate, useNavigationState, useParams, useRoute, useRouter, useRouterState, useSearchParams, } from './react/index.js';
 export type { BlockerState, BuzolaProviderProps, LinkProps, OutletProps, RouteContextValue } from './react/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAEzE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxE,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAC9G,YAAY,EAAE,uBAAuB,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAG7G,YAAY,EACX,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,cAAc,GACd,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAC9E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAGlG,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAEzE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxE,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAC9G,YAAY,EAAE,uBAAuB,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAG7G,YAAY,EACX,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,cAAc,GACd,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAC9E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAClG,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAGvD,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -8,6 +8,7 @@ export { createBrowserNavigationAdapter, createMemoryNavigationAdapter } from '.
 export { s } from './engine/schema.js';
 // ─── Route definition ───────────────────────────────────────────────────────
 export { BuzolaRedirect, createPage, redirect } from './define/create-page.js';
+export { lazyRoute } from './define/lazy-route.js';
 // ─── React (re-export from subpath) ─────────────────────────────────────────
 export { BuzolaProvider, ErrorBoundary, Link, Outlet, RouteContext, RouterContext, useBlocker, useInvalidate, useNavigate, useNavigationState, useParams, useRoute, useRouter, useRouterState, useSearchParams, } from './react/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGnE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAyB9G,gFAAgF;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAEtC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAG9E,+EAA+E;AAC/E,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGnE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAyB9G,gFAAgF;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAEtC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAGlD,+EAA+E;AAC/E,OAAO,EACN,cAAc,EACd,aAAa,EACb,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,GACf,MAAM,kBAAkB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@buzola/router",
-	"version": "0.0.21",
+	"version": "0.0.23",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",

package/src/__tests__/lazy-route.test.tsx

@@ -0,0 +1,98 @@
+import './setup-dom.js'
+import { act, cleanup, render } from '@testing-library/react'
+import { afterEach, describe, expect, it, mock } from 'bun:test'
+import React from 'react'
+import { lazyRoute } from '../define/lazy-route.js'
+import { createMemoryNavigationAdapter } from '../engine/navigation-adapter.js'
+import { buildRouteTree } from '../engine/route-tree.js'
+import { Router } from '../engine/router.js'
+import { BuzolaProvider, Outlet } from '../react/index.js'
+
+afterEach(cleanup)
+
+function About() {
+	return <div>About</div>
+}
+
+/** Resolves a task later, the way a browser resolves `import()` even for a module it has already loaded. */
+function loadAfterATask(): Promise<{ default: typeof About }> {
+	return new Promise(resolve => setTimeout(() => resolve({ default: About }), 0))
+}
+
+/** Lets the load settle and React render what it unblocked. */
+async function settle(route: { preload: () => Promise<unknown> }) {
+	await act(async () => {
+		await route.preload().catch(() => {})
+		await new Promise(resolve => setTimeout(resolve, 0))
+	})
+}
+
+async function renderRoute(component: React.ComponentType<Record<string, never>>) {
+	const fallbacks: string[] = []
+	function Fallback() {
+		React.useLayoutEffect(() => {
+			fallbacks.push('shown')
+		}, [])
+		return null
+	}
+	const routes = buildRouteTree([{ path: '/', component, isIndex: true }])
+	const router = new Router({ routes, adapter: createMemoryNavigationAdapter({ initialURL: 'http://localhost/' }) })
+	// An awaited act: React parks a `use()` suspension made inside a synchronous one and never retries it.
+	const { container } = await act(async () =>
+		render(
+			<BuzolaProvider router={router}>
+				<Outlet fallback={<Fallback />} errorFallback={error => <div>Failed: {error.message}</div>} />
+			</BuzolaProvider>,
+		)
+	)
+	return { container, fallbacks }
+}
+
+describe('lazyRoute', () => {
+	it('renders a preloaded route in its first commit, without the fallback', async () => {
+		const route = lazyRoute(loadAfterATask)
+		await route.preload()
+
+		const { container, fallbacks } = await renderRoute(route.component)
+
+		expect(container.textContent).toBe('About')
+		expect(fallbacks).toEqual([])
+	})
+
+	it('suspends until a route that was not preloaded loads', async () => {
+		const route = lazyRoute(loadAfterATask)
+
+		const { container, fallbacks } = await renderRoute(route.component)
+		expect(fallbacks).toEqual(['shown'])
+
+		await settle(route)
+		expect(container.textContent).toBe('About')
+	})
+
+	it('shares one request between preload and render', async () => {
+		const load = mock(loadAfterATask)
+		const route = lazyRoute(load)
+
+		route.preload()
+		const { container } = await renderRoute(route.component)
+		await settle(route)
+
+		expect(container.textContent).toBe('About')
+		expect(load).toHaveBeenCalledTimes(1)
+	})
+
+	it('a failed load reaches the error boundary without asking again, and the next preload asks again', async () => {
+		const load = mock(() => Promise.reject(new Error('chunk missing')))
+		const route = lazyRoute(load)
+
+		const { container } = await renderRoute(route.component)
+		await act(() => new Promise(resolve => setTimeout(resolve, 0)))
+		expect(container.textContent).toBe('Failed: chunk missing')
+
+		expect(load).toHaveBeenCalledTimes(1)
+
+		load.mockImplementation(loadAfterATask)
+		expect(await route.preload()).toBe(About)
+		expect(load).toHaveBeenCalledTimes(2)
+	})
+})

package/src/define/lazy-route.tsx

@@ -0,0 +1,47 @@
+import { type ComponentType, createElement, type ReactElement, use } from 'react'
+
+type RouteModuleComponent = ComponentType<Record<string, never>>
+
+export interface LazyRoute {
+	/** Renders the loaded component, synchronously once the module has loaded. */
+	component: RouteModuleComponent
+	/** Starts loading the module. Calls share one request; a failed one is retried by the next call. */
+	preload: () => Promise<RouteModuleComponent>
+}
+
+/**
+ * A route component loaded on demand, like `React.lazy`, but sharing its request with `preload`.
+ *
+ * `React.lazy` starts its own `import()` the first time it renders, even when the module is already
+ * loaded, and the browser resolves that a task later. React then commits the Suspense fallback and
+ * holds the page back ~300 ms before revealing it. Once loaded, this component renders without suspending.
+ */
+export function lazyRoute(load: () => Promise<{ default: RouteModuleComponent }>): LazyRoute {
+	let loaded: RouteModuleComponent | null = null
+	let request: Promise<RouteModuleComponent> | null = null
+	let failed = false
+
+	const start = (): Promise<RouteModuleComponent> => {
+		failed = false
+		request = load().then(
+			module => {
+				loaded = module.default
+				return module.default
+			},
+			(error: unknown) => {
+				failed = true
+				throw error
+			},
+		)
+		return request
+	}
+
+	const preload = (): Promise<RouteModuleComponent> => (request === null || failed ? start() : request)
+
+	function LazyRouteComponent(): ReactElement {
+		// A failed request stays failed for rendering, as with `React.lazy`; only `preload` asks again.
+		return createElement(loaded ?? use(request ?? start()))
+	}
+
+	return { component: LazyRouteComponent, preload }
+}

package/src/index.ts

@@ -40,6 +40,8 @@ export { s } from './engine/schema.js'
 // ─── Route definition ───────────────────────────────────────────────────────
 export { BuzolaRedirect, createPage, redirect } from './define/create-page.js'
 export type { CatchContext, PageDefinition, PageProps, RedirectFn } from './define/create-page.js'
+export { lazyRoute } from './define/lazy-route.js'
+export type { LazyRoute } from './define/lazy-route.js'
 
 // ─── React (re-export from subpath) ─────────────────────────────────────────
 export {